@synertech/ui 0.40.0 → 0.41.0

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

@@ -156,6 +156,10 @@ import { cn } from "@synertech/ui";
 - `ScatterChart` - Corrélation entre deux variables numériques (3 séries max)
 - `StatCard` / `StatCardGroup` - Valeur unique avec variation et sparkline
 - `Sparkline` - Courbe sans axe, pour une cellule ou une carte
+- `Heatmap` - Une grandeur sur une grille (jour × heure, cohortes, matrice)
+- `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
 
 ### Feedback & Overlays
 
@@ -586,6 +590,26 @@ const data = [
   showValues
 />
 
+// Barres divergentes : l'écart à une référence
+<BarChart
+  data={gaps}
+  x={{ key: "region" }}
+  series={[{ key: "gap" }]}
+  orientation="horizontal"
+  diverging                    // true | un nombre (le centre) | une clé de série
+  y={{ label: "Écart à la cible (%)" }}
+/>
+
+// Échelle d'accord : la série nommée est à cheval sur le centre
+<BarChart
+  data={survey}
+  x={{ key: "question" }}
+  series={[{ key: "awful" }, { key: "bad" }, { key: "ok" }, { key: "good" }, { key: "great" }]}
+  orientation="horizontal"
+  stack="stacked"
+  diverging="ok"
+/>
+
 // Camembert ou anneau
 <PieChart
   data={sources}
@@ -606,6 +630,46 @@ const data = [
 />
 ```
 
+```tsx
+// Carte de chaleur — une ligne de données par case
+<Heatmap
+  data={load}                  // [{ day, hour, sessions }, ...]
+  x={{ key: "hour", label: "Heure" }}
+  y={{ key: "day", label: "Jour" }}
+  value="sessions"
+  scale="sequential"           // "sequential" | "diverging" (+ center)
+  steps={undefined}            // la rampe reste continue tant qu'on ne la découpe pas
+  legendLabel="Sessions"       // la légende d'échelle est affichée par défaut
+  showValues
+  tableView="toggle"           // la grille pivotée : une ligne par catégorie de rangée
+/>
+
+// Graphique à puce — réalisé, objectif, plages
+<BulletChart
+  data={[{ measure: "Revenu", value: 38400, target: 42000, bands: [20000, 34000, 50000] }]}
+  x={{ key: "measure" }}
+  value="value"
+  target="target"
+  ranges="bands"               // bornes croissantes, peintes en gris derrière la barre
+  normalize="row"              // "row" (par défaut) | "shared" → ramène l'axe des valeurs
+/>
+
+// 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 }) => (
+    <LineChart
+      data={data}
+      series={[{ key: "revenue" }]}
+      x={{ key: "month" }}
+      y={{ domain }}           // ← toujours le passer, c'est tout l'intérêt
+      plotLabel={label}
+      height={130}
+      legend={false}
+    />
+  )}
+</ChartFacets>
+```
+
 **Ce que les composants refusent de faire, et pourquoi :**
 
 - **Pas de second axe Y.** Deux mesures d'échelles différentes inventent une
@@ -617,6 +681,16 @@ const data = [
   Un nuage de points s'arrête à 3 séries.
 - **`PieChart` n'est pas fait pour comparer des valeurs proches** — l'œil compare
   mal des angles. Deux parts, c'est une `StatCard`.
+- **La palette catégorielle ne peint pas une grandeur.** Les huit créneaux
+  répondent à « lequel » ; une rampe répond à « combien ». Dès qu'une couleur
+  encode une grandeur, la légende d'échelle est obligatoire.
+- **Une `Heatmap` ne se découpe pas au-delà de 7 classes de couleur** — les cases
+  voisines cessent d'être distinguables. Sans `steps`, la rampe reste continue.
+- **Les panneaux d'un `ChartFacets` partagent leur domaine.** Des échelles libres
+  ont l'air comparables et ne le sont pas : passez toujours le `domain` reçu.
+- **La rampe divergente dit un sens, pas un jugement.** « Au-dessus » n'est pas
+  « bon » : un délai qui glisse est au-dessus. Le jugement appartient aux
+  couleurs de statut, toujours accompagnées d'un libellé.
 
 ### Cartes KPI
 
@@ -653,9 +727,18 @@ tout le kit sur une charte :
   --color-chart-1: #0f766e;
   --color-chart-2: #b45309;
   /* ... jusqu'à 8 */
+
+  /* Les trois rampes de grandeur, si le kit en affiche */
+  --color-chart-seq-1: #e0f2f1; /* ... jusqu'à 6, du clair au foncé */
+  --color-chart-ord-1: #4db6ac; /* ... jusqu'à 5, paliers ordonnés */
+  --color-chart-div-1: #00695c; /* ... jusqu'à 7, milieu neutre au 4 */
 }
 ```
 
+Redéfinissez-les aussi sous `:root.dark` / `[data-theme="dark"]` : les rampes
+sombres du kit ne sont pas les claires éclaircies, elles courent en sens inverse
+(sur fond sombre, « plus » doit s'éloigner du fond).
+
 ### Card (Composable)
 
 ```tsx