@synertech/ui 0.40.1 → 0.42.0

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

@@ -156,6 +156,16 @@ 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
+- `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
 
 ### Feedback & Overlays
 
@@ -586,6 +596,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}
@@ -604,6 +634,118 @@ const data = [
   bubble={{ key: "clients", range: [4, 18] }}
   trendLine
 />
+
+// Histogramme — `bins` lit x.key comme une mesure, la range et la compte
+<BarChart
+  data={sessions}                // [{ duration: 42 }, { duration: 118 }, ...]
+  x={{ key: "duration", label: "Durée (s)" }}
+  series={[{ key: "sessions", label: "Sessions" }]}  // nomme le COMPTE
+  bins={12}                      // ou true (auto), ou [0, 15, 30, 60, 120]
+/>
+
+// Barres + ligne — une série typée, un seul axe
+<BarChart
+  data={monthly}
+  x={{ key: "month" }}
+  series={[
+    { key: "commandes", label: "Commandes" },
+    { key: "retours", label: "Retours", type: "line" },
+  ]}
+  curve="monotone"
+/>
+```
+
+```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
+/>
+
+// Cascade — chaque pas flotte entre le cumul avant et après lui
+<WaterfallChart
+  data={budget}                  // [{ poste, montant, jalon? }, ...]
+  x={{ key: "poste" }}
+  value="montant"
+  total="jalon"                  // ligne de contrôle dessinée depuis zéro
+  start={0}                      // cumul d'ouverture
+/>
+
+// Tunnel — étapes ORDONNÉES, donc rampe ordinale (jamais les créneaux)
+<FunnelChart
+  data={stages}                  // [{ etape, utilisateurs }, ...]
+  x={{ key: "etape" }}
+  value="utilisateurs"
+  align="center"                 // "center" (silhouette) | "left" (comparaison)
+  showConversion                 // le ratio d'un pas au suivant : le constat
+/>
+
+// Haltère — avant → après, ou une plage. L'écart EST la marque
+<DumbbellChart
+  data={satisfaction}
+  x={{ key: "service" }}
+  series={[{ key: "avant", label: "2025" }, { key: "apres", label: "2026" }]}
+  sort="gap"                     // les plus gros mouvements en tête
+/>
+
+// Boîte à moustaches — `values` (observations) ou `quantiles` (résumé)
+<BoxPlot
+  data={teams}                   // [{ equipe, durees: [12, 14, ...] }, ...]
+  x={{ key: "equipe" }}
+  values="durees"                // moustaches de Tukey + aberrations calculées
+  showMean                       // le losange : l'écart moyenne/médiane = la queue
+/>
+
+// Chandeliers — couleurs de statut + corps creux/plein, jamais la teinte seule
+<CandlestickChart
+  data={sessions}
+  x={{ key: "jour" }}
+  open="ouverture" high="haut" low="bas" close="cloture"
+/>
+
+// Planning — dates, dépendances, jalons. Ce n'est pas un `Calendar`
+<GanttChart
+  data={project}
+  x={{ key: "tache" }}
+  start="debut" end="fin"
+  id="id" dependencies="depend"  // les flèches : ce qui bloque quoi
+  progress="avancement"          // 0 à 1
+  milestone="jalon"
+  group="lot"                    // un créneau de palette par lot
+  today="2026-04-14"
+/>
+
+// 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 :**
@@ -617,6 +759,33 @@ 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é.
+- **Un `BarChart` combiné garde un seul axe.** Une série `type: "line"` partage
+  l'échelle des barres. Deux axes laissent deux mesures étrangères se croiser
+  là où le cadrage les place, ce qui se lit comme une corrélation inventée.
+- **Un histogramme ne se trie pas.** `sort`, `stack` et `diverging` sont ignorés
+  avec `bins` : les seaux ont un ordre, et le réordonner détruit la forme.
+- **Un tunnel encode une longueur, pas une surface.** Le trapèze classique
+  demande de comparer deux surfaces, ce que l'œil ne sait pas faire.
+- **Un `BoxPlot` nourri d'un résumé ne dessine aucune valeur aberrante.** Les
+  bornes de Tukey ont besoin des observations ; le composant préfère ne rien
+  affirmer plutôt qu'inventer.
+- **`DumbbellChart` et `BoxPlot` ne s'ancrent pas à zéro.** Ils se lisent à un
+  écart et à un étalement, pas à la longueur d'une marque depuis une base.
+- **`CandlestickChart` porte le sens deux fois** : couleur de statut ET corps
+  creux (hausse) contre plein (baisse). Vert contre rouge est la pire paire
+  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.
 
 ### Cartes KPI
 
@@ -653,9 +822,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