@synertech/ui 0.43.0 → 0.44.0

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

@@ -168,6 +168,9 @@ import { cn } from "@synertech/ui";
 - `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
 
@@ -552,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 },
@@ -758,6 +764,75 @@ const data = [
   <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 }) => (
@@ -822,6 +897,33 @@ const data = [
 - **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