@synertech/ui 0.42.0 → 0.44.0

package/.claude/skills/use-synertech-ui/SKILL.md

@@ -160,12 +160,17 @@ import { cn } from "@synertech/ui";
 - `BulletChart` - Réalisé, objectif et plages qualitatives sur une seule ligne
 - `ChartFacets` - Petits multiples : un même graphique répété, à échelle partagée
 - `ChartScaleLegend` - La légende d'une rampe de couleur
+- `ChartFilterBar` - Les filtres en une rangée au-dessus des graphiques qu'ils cadrent
+- `ChartPeriodPicker` - La fenêtre d'un tableau de bord : préréglages nommés + calendrier
 - `WaterfallChart` - Comment on passe de A à B : chaque contribution, positive ou négative
 - `FunnelChart` - Des étapes ordonnées et leur déperdition (rampe ordinale)
 - `DumbbellChart` - Avant → après par élément, ou une plage min–max
 - `BoxPlot` - Médiane, quartiles, moustaches et valeurs aberrantes
 - `CandlestickChart` - Ouverture, haut, bas, clôture (couleurs de statut)
 - `GanttChart` - Des tâches dans le temps, avec dépendances et jalons
+- `ChartSyncProvider` - Plusieurs panneaux qui se lisent comme un seul objet :
+  survol partagé et fenêtre brossée en commun
+- `ChartExportButton` - Le tableau du graphique en CSV ou JSON
 
 ### Feedback & Overlays
 
@@ -550,7 +555,10 @@ Tous les graphiques partagent la même forme de données : un tableau de lignes
 et des séries qui pointent un champ, exactement comme `DataGrid`.
 
 ```tsx
-import { LineChart, AreaChart, BarChart, PieChart, ScatterChart } from "@synertech/ui";
+import {
+  LineChart, AreaChart, BarChart, PieChart, ScatterChart,
+  ChartSyncProvider, ChartExportButton, brushToPeriod,
+} from "@synertech/ui";
 
 const data = [
   { month: "Jan", revenue: 18400, cost: 12200 },
@@ -732,6 +740,99 @@ const data = [
   today="2026-04-14"
 />
 
+// Annotations — ce qui s'est passé, dessiné là où ça s'est passé
+// (`referenceLines` = un seuil sur l'axe des valeurs ; les annotations = un
+//  moment sur l'axe des catégories. Lisible sur LineChart, AreaChart, BarChart)
+<LineChart
+  data={monthly}
+  series={[{ key: "revenue" }]}
+  x={{ key: "month" }}
+  annotations={[
+    { type: "band", from: "Fév", to: "Mar", label: "Campagne" },
+    { type: "line", x: "Mai", label: "Refonte du tunnel" },
+    { type: "point", x: "Août", y: 39900, label: "Record" },
+  ]}
+/>
+
+// Trames — le canal de secours quand la teinte échoue (CVD sévère, impression
+// en niveaux de gris, forced-colors). Jamais par défaut : c'est de l'a11y
+<BarChart data={channels} series={channelSeries} x={{ key: "quarter" }} stack="stacked" patterns />
+
+// La rangée de filtres — une seule, au-dessus de TOUS les graphiques
+<ChartFilterBar actions={<Button size="sm">Exporter</Button>}>
+  <ChartPeriodPicker size="sm" value={period} onChange={setPeriod} />
+  <Select size="sm" options={regions} value={region} onValueChange={setRegion} />
+</ChartFilterBar>
+
+// L'état d'erreur — distinct de l'état vide, sur TOUS les graphiques du kit
+// (« il n'y a rien » et « on n'a pas réussi à charger » sont deux affirmations
+//  différentes ; seule la seconde appelle une reprise)
+<LineChart
+  data={rows}
+  series={series}
+  x={{ key: "month" }}
+  loading={query.isFetching}
+  error={query.isError}
+  onRetry={() => query.refetch()}
+/>
+
+// L'export — le tableau exact du graphique, dans la fente `actions`
+<LineChart
+  data={rows}
+  series={series}
+  x={{ key: "month", label: "Mois" }}
+  actions={
+    <ChartExportButton
+      data={rows}
+      series={series}
+      xKey="month"
+      xLabel="Mois"
+      filename="revenus"
+      size="sm"
+    />
+  }
+/>
+
+// La trappe d'évasion — dessiner DANS le tracé, avec les échelles du graphique
+// (Line, Area, Bar, Scatter. Une fonction dessine par-dessus les marques ;
+//  `{ under, over }` atteint aussi le dessous. Coordonnées relatives à la zone
+//  de dessin, et sans clip : la marge est à la charge de l'appelant)
+<LineChart
+  data={rows}
+  series={series}
+  x={{ key: "month" }}
+  y={{ domain: [100, 230] }}          // ← réserver la place de l'annotation
+  overlay={({ xAt, yAt, dimensions }) => (
+    <rect
+      x={0}
+      y={yAt(200)}
+      width={dimensions.innerWidth}
+      height={Math.abs(yAt(160) - yAt(200))}
+      className="fill-green-500"
+      opacity={0.1}
+    />
+  )}
+/>
+
+// La volumétrie — allège le TRACÉ, jamais les données
+// (LTTB sur Line/Area, échantillon régulier sur Scatter. Le tableau, l'infobulle
+//  et la droite de tendance continuent de lire chaque ligne)
+<LineChart data={fiftyThousandRows} series={series} x={{ key: "t", scale: "linear" }} maxPoints={400} />
+
+// Le tableau de bord synchronisé — un pointeur, une infobulle ; une plage, toutes
+// les cartes. `brushToPeriod` rend la fenêtre au `ChartPeriodPicker`
+<ChartSyncProvider brush={null} onBrushChange={(range) => {
+  const next = range && brushToPeriod(range);
+  if (next) setPeriod(next);
+}}>
+  <ChartFilterBar>
+    <ChartPeriodPicker size="sm" value={period} onChange={setPeriod} />
+  </ChartFilterBar>
+
+  <LineChart data={rows} series={series} x={xAxis} brush />
+  <BarChart data={rows} series={series} x={{ key: "day" }} />
+</ChartSyncProvider>
+
 // Petits multiples — le domaine est calculé sur l'ensemble et imposé à chaque panneau
 <ChartFacets data={rows} by="region" values={["revenue"]} columns={3}>
   {({ data, domain, label }) => (
@@ -786,6 +887,43 @@ const data = [
   sous déficience de vision des couleurs.
 - **`GanttChart` n'est pas un `Calendar`.** Le calendrier sélectionne une date
   et la renvoie ; le planning se lit. Une ligne sans largeur est un jalon.
+- **Les filtres vivent dans UNE rangée, au-dessus des graphiques.** Jamais dans
+  une carte, jamais par graphique : deux panneaux filtrés séparément répondent à
+  deux questions et rien à l'écran ne le dit.
+- **Les trames ne sont jamais activées par défaut.** C'est une option
+  d'accessibilité, pas une décoration — et elles ne peignent que des identités :
+  une rampe (Heatmap, `diverging`, tunnel) encode une grandeur, ce qu'aucune
+  trame ne sait dire.
+- **Les annotations se lisent sur l'axe des catégories.** Un `BarChart`
+  horizontal les ignore, avec un avertissement : un moment placé sur une liste
+  de noms n'en est plus un.
+- **`error` n'est jamais `empty`.** Un panneau qui affiche « Aucune donnée »
+  après une requête échouée affirme quelque chose de faux, et ne propose aucune
+  sortie. `loading` l'emporte sur les deux : une reprise remplace le message par
+  le voyant.
+- **Rien n'est décimé tout seul.** Un graphique qui dessinerait en douce une
+  autre forme que celle qu'on lui a remise serait pire qu'un graphique lent :
+  au-delà de 2 000 points il avertit, et `maxPoints` est à vous. Il n'allège
+  que le tracé — le tableau garde chaque ligne.
+- **`BarChart` n'a pas de `maxPoints`.** Décimer des barres, c'est supprimer des
+  catégories : `bins` est la réponse là-bas.
+- **`ScatterChart` échantillonne régulièrement, pas en LTTB.** Un nuage se lit à
+  sa densité ; garder les plus grands triangles en découperait l'enveloppe et
+  jetterait précisément ce qu'on regarde.
+- **`overlay` n'est pas `children`.** Les graphiques restent des objets fermés ;
+  la trappe remet la géométrie résolue et rien d'autre. C'est elle qui rend
+  défendable chaque refus de cette liste — « prenez un `BarChart` groupé » ne
+  tient que si l'application peut dessiner ce qu'elle n'obtiendra jamais du kit.
+- **Un `ScatterChart` ne se brosse pas.** Ses deux axes sont des mesures, et une
+  fenêtre sur l'une d'elles n'est pas le geste qu'un nuage appelle.
+- **Une plage se pose aussi au clavier.** Maj + flèches l'étend, Échap la retire :
+  un filtre qui ne s'atteint qu'à la souris est inaccessible à la moitié des
+  lecteurs.
+- **Une fenêtre qui a déjà recadré le tableau de bord n'a plus à être teintée.**
+  Les panneaux SONT la fenêtre ; la bande lave alors chaque tracé de bord à bord
+  et n'énonce rien. Repassez `brush={null}` après l'avoir appliquée.
+- **L'export écrit les mesures brutes.** Ce qui ouvre le fichier va calculer
+  dessus, et `1 234,5 $` est une chaîne. Seule la catégorie est formatée.
 
 ### Cartes KPI