# Graphiques et KPI

Deux composants résument les enregistrements au lieu de les énumérer. Tous deux se lient via [`dataSource`](/fr/docs/pages-data-binding) puis agrègent ce qu'elle renvoie — les enregistrements bruts ne sont jamais rendus.

## `chart`

| Propriété         | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| `dataSource`      | Liaison de table.                                                                    |
| `chartType`       | `bar`, `line`, `area`, `pie`, `donut` ou `scatter`.                                  |
| `chartAggregate`  | Comment les enregistrements sont résumés (voir ci-dessous).                          |
| `series`          | Une ou plusieurs séries tracées.                                                     |
| `xAxis` / `yAxis` | Configuration des axes.                                                              |
| `legend`          | `{ position, visible }`. `position` vaut `top`, `bottom`, `left`, `right` ou `none`. |
| `tooltip`         | `{ format }` — un modèle acceptant `{label}` et `{value}`.                           |
| `emptyMessage`    | Affiché quand l'agrégat ne produit rien.                                             |

Le type de graphique est la **propriété** `chartType`, pas le `type` du composant — un composant graphique est toujours `type: chart`.

| Propriété de `series[]` | Description                                                          |
| ----------------------- | -------------------------------------------------------------------- |
| `field`                 | Champ tracé par cette série.                                         |
| `label`                 | Nom de la série affiché dans la légende et l'infobulle.              |
| `color`                 | Jeton de couleur du thème ou valeur brute.                           |
| `stack`                 | Nom du groupe d'empilement. Les séries partageant un nom s'empilent. |
| `fillOpacity`           | Opacité de remplissage de 0 à 1, pour les aires et les barres.       |

| Propriété d'axe | Description                                    |
| --------------- | ---------------------------------------------- |
| `field`         | Champ associé à l'axe.                         |
| `label`         | Titre de l'axe.                                |
| `scale`         | `linear` ou `logarithmic`.                     |
| `format`        | `date`, `currency`, `number` ou `percent`.     |
| `gridLines`     | Trace les lignes de grille le long de cet axe. |

### `chartAggregate`

| Propriété  | Description                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------ |
| `function` | `count`, `sum`, `avg`, `min` ou `max`.                                                           |
| `groupBy`  | **Obligatoire.** Champ de regroupement des enregistrements — les catégories du graphique.        |
| `field`    | Champ sur lequel opère la fonction. À omettre pour `count`.                                      |
| `interval` | Taille des tranches lors d'un regroupement par date : `day`, `week`, `month`, `quarter`, `year`. |

```yaml
- type: chart
  chartType: bar
  dataSource: { table: orders }
  chartAggregate: { function: sum, field: total, groupBy: created_at, interval: month }
  xAxis: { field: created_at, label: Month, format: date }
  yAxis: { field: total, label: Revenue, format: currency, gridLines: true }
  series: [{ field: total, label: Revenue, color: primary }]
  legend: { position: bottom, visible: true }
```

## `kpi`

Une mesure de synthèse unique — une carte de statistique — avec comparaison et sparkline optionnelles.

| Propriété      | Description                                                                                |
| -------------- | ------------------------------------------------------------------------------------------ |
| `dataSource`   | Liaison de table.                                                                          |
| `label`        | Le nom de la mesure.                                                                       |
| `icon`         | Icône rendue à côté de la valeur.                                                          |
| `kpiAggregate` | `{ function, field }`. `function` est obligatoire ; omettre `field` pour `count`.          |
| `kpiFormat`    | `{ type, options }`. `type` vaut `number`, `currency`, `percentage`, `compact` ou `bytes`. |
| `trend`        | Comparaison avec une période antérieure (voir ci-dessous).                                 |
| `sparkline`    | Courbe de tendance miniature (voir ci-dessous).                                            |
| `thresholds`   | Entrées `{ value, color }` qui recolorent la carte au franchissement d'une valeur.         |

### `trend`

Les trois propriétés `comparisonPeriod`, `direction` et `changePercent` sont obligatoires dès que `trend` est présent.

| Propriété          | Description                                                                          |
| ------------------ | ------------------------------------------------------------------------------------ |
| `comparisonPeriod` | `previousDay`, `previousWeek`, `previousMonth`, `previousQuarter` ou `previousYear`. |
| `direction`        | `up`, `down` ou `flat`.                                                              |
| `changePercent`    | La variation, sous forme de nombre.                                                  |
| `color`            | `green`, `red`, `yellow` ou `gray`.                                                  |

:::callout
**`direction` et `color` sont indépendants à dessein.** Un chiffre d'affaires en hausse est vert ; une attrition en hausse est rouge. Sovrium ne devinera pas lesquelles de vos mesures s'améliorent en montant : indiquez la couleur que vous voulez dire.
:::

### `sparkline`

Les quatre propriétés sont obligatoires dès que `sparkline` est présent.

| Propriété  | Description                                   |
| ---------- | --------------------------------------------- |
| `field`    | Champ tracé le long de la courbe.             |
| `groupBy`  | Champ selon lequel les points sont regroupés. |
| `interval` | `day`, `week` ou `month`.                     |
| `days`     | Nombre de jours couverts par la courbe.       |

```yaml
- type: kpi
  label: Revenue this month
  icon: banknote
  dataSource: { table: orders }
  kpiAggregate: { function: sum, field: total }
  kpiFormat: { type: currency, options: { currency: EUR } }
  trend: { comparisonPeriod: previousMonth, direction: up, changePercent: 12.4, color: green }
  sparkline: { field: total, groupBy: created_at, interval: day, days: 30 }
```

## Pages connexes

- [Tables et listes](/fr/docs/data-components) — `data-table`, `list`, `data-form`.
- [Tableaux, calendriers et chronologies](/fr/docs/data-components-boards) — les autres vues d'enregistrements.
- [Liaison de données](/fr/docs/pages-data-binding) — `dataSource` et filtrage.
- [Analytique](/fr/docs/analytics) — les mesures de trafic intégrées.
- [Aperçu du thème et couleurs](/fr/docs/theme) — les jetons de couleur référencés par les séries.