@synertech/ui 0.39.1 → 0.40.1

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

@@ -147,6 +147,16 @@ import { cn } from "@synertech/ui";
 | `Label` | Étiquette de formulaire | Oui |
 | `Banner` | Bannière notification/hero/promotion | Non |
 
+### Charts
+
+- `LineChart` - Évolution dans le temps (multi-séries, steppée, prévision en pointillés)
+- `AreaChart` - Idem avec remplissage : simple, empilée, empilée 100 %
+- `BarChart` - Comparaison entre catégories : verticale/horizontale, groupée, empilée, 100 %
+- `PieChart` - Proportions sur peu de catégories (camembert ou anneau)
+- `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
+
 ### Feedback & Overlays
 
 | Composant | Description | Server-compatible |
@@ -524,6 +534,128 @@ import { ImageUploader } from "@synertech/ui";
 />
 ```
 
+### Charts
+
+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";
+
+const data = [
+  { month: "Jan", revenue: 18400, cost: 12200 },
+  { month: "Fév", revenue: 21100, cost: 13050 },
+];
+
+<LineChart
+  data={data}
+  x={{ key: "month", label: "Mois" }}   // scale: "category" | "linear" | "time"
+  series={[
+    { key: "revenue", label: "Revenu" },
+    { key: "cost", label: "Coût" },
+  ]}
+  title="Revenu et coût"
+  description="Six derniers mois"
+  height={260}                 // la largeur suit toujours le conteneur
+  curve="monotone"             // "linear" | "monotone" | "step" | "stepAfter"
+  forecastFrom="Juin"          // la suite passe en pointillés
+  forecastLabel="prévision"
+  emphasis="revenue"           // une série en couleur, les autres en gris
+  referenceLines={[{ value: 30000, label: "Objectif" }]}
+  tableView="toggle"           // le jumeau accessible du graphique
+  onPointClick={(point) => console.log(point.value)}
+/>
+```
+
+**Props communes** : `data`, `series`, `x`, `y`, `height`, `size`, `grid`,
+`legend`, `tooltip`, `tableView`, `emphasis`, `title`, `description`, `loading`,
+`emptyState`, `locale`, `className`.
+
+```tsx
+// Aire : simple, empilée, ou 100 %
+<AreaChart data={data} x={{ key: "month" }} series={series} stack="percent" />
+
+// Barres : les deux orientations, groupées ou empilées
+<BarChart
+  data={data}
+  x={{ key: "region" }}
+  series={series}
+  orientation="horizontal"     // dès que les noms de catégories sont longs
+  stack="none"                 // "none" (groupé) | "stacked" | "percent"
+  sort="desc"                  // le tableau de données suit le même ordre
+  showValues
+/>
+
+// Camembert ou anneau
+<PieChart
+  data={sources}
+  x={{ key: "source" }}
+  value="visits"
+  variant="donut"
+  maxSlices={6}                // la queue est repliée dans « Autres »
+  centerLabel={{ value: "48,1 K", label: "Visites" }}
+/>
+
+// Nuage de points — 3 séries maximum
+<ScatterChart
+  data={campaigns}
+  x={{ key: "budget", scale: "linear", label: "Budget" }}
+  series={[{ key: "conversions" }]}
+  bubble={{ key: "clients", range: [4, 18] }}
+  trendLine
+/>
+```
+
+**Ce que les composants refusent de faire, et pourquoi :**
+
+- **Pas de second axe Y.** Deux mesures d'échelles différentes inventent une
+  corrélation absente des données. Deux graphiques, ou une indexation base 100.
+- **`LineChart` ne s'ancre pas à zéro ; `AreaChart` et `BarChart` si.** Une ligne
+  se lit à sa pente, une barre à la longueur de sa marque. `y={{ includeZero: true }}`
+  quand le niveau absolu compte.
+- **Au-delà de 8 séries**, la 9ᵉ passe en gris : replier la queue ou facetter.
+  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`.
+
+### Cartes KPI
+
+```tsx
+import { StatCard, StatCardGroup, Sparkline } from "@synertech/ui";
+
+<StatCardGroup columns={4}>
+  <StatCard
+    label="Revenu mensuel"
+    value={38400}                      // exact sous 10 000, compact au-dessus
+    delta={{ value: 0.124, period: "vs mois dernier" }}
+    trend={last12Months}               // dessine une Sparkline
+  />
+  <StatCard
+    label="Coût serveur"
+    value={4200}
+    delta={{ value: -0.18, goodWhen: "down" }}  // une baisse = bonne nouvelle
+  />
+</StatCardGroup>
+
+<Sparkline data={values} area emphasizeLast domain={[0, 100]} />
+```
+
+`StatCard` et `Sparkline` n'utilisent aucun hook : ils fonctionnent en composant
+serveur, sans `"use client"`.
+
+### Rhabiller la palette
+
+Les huit couleurs de séries sont des variables CSS. Un bloc suffit à aligner
+tout le kit sur une charte :
+
+```css
+:root {
+  --color-chart-1: #0f766e;
+  --color-chart-2: #b45309;
+  /* ... jusqu'à 8 */
+}
+```
+
 ### Card (Composable)
 
 ```tsx
@@ -1581,7 +1713,7 @@ Un dialogue vraiment specifique se construit avec le hook exporte
 ## Documentation interactive
 
 La documentation Storybook avec tous les composants et leurs variantes est disponible a :
-**https://ui.synertechweb.com/**
+**https://ui.synertechweb.com/storybook/**
 
 Chaque composant a une page interactive avec :
 - Props table auto-generee

package/README.md

@@ -2,7 +2,7 @@
 
 A TypeScript/React UI component library using Tailwind CSS classes. Published on the public npm registry.
 
-📖 **[View Storybook](https://ui.synertechweb.com/)** — Interactive component documentation
+📖 **[View Storybook](https://ui.synertechweb.com/storybook/)** — Interactive component documentation
 
 ## Installation
 
@@ -245,7 +245,7 @@ Then open [http://localhost:6006](http://localhost:6006).
 
 Storybook is automatically deployed to GitLab Pages on every push to `main`:
 
-👉 **https://ui.synertechweb.com/**
+👉 **https://ui.synertechweb.com/storybook/**
 
 ## Releasing