@sia-ui/cli 0.2.1 → 0.3.0

package/dist/registry/package/components/Avatar/index.tsx

@@ -1,23 +1,344 @@
-import { useState, type ImgHTMLAttributes } from "react";
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useState,
+  type HTMLAttributes,
+  type ImgHTMLAttributes,
+  type ReactNode,
+} from "react";
 import { cn } from "@sia-ui/utils";
 import "./styles.css";
 
-export interface AvatarProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "children"> {
-  name: string;
-  size?: "sm" | "md" | "lg";
-  fallback?: string;
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type AvatarShape = "circle" | "rounded" | "square";
+export type AvatarVariant = "soft" | "solid" | "outline";
+
+/**
+ * La présence d'une personne.
+ *
+ * Quatre états et pas davantage : au-delà, la pastille devient un code que
+ * personne ne retient, et il faut une légende pour la lire.
+ */
+export type AvatarStatus = "online" | "offline" | "busy" | "away";
+
+const LIBELLES_STATUT: Record<AvatarStatus, string> = {
+  online: "en ligne",
+  offline: "hors ligne",
+  busy: "occupé",
+  away: "absent",
+};
+
+/**
+ * Les teintes dérivées du nom.
+ *
+ * Deux personnes aux mêmes initiales doivent se distinguer : dans une liste
+ * de participants, six pastilles identiques ne valent pas mieux qu'aucune.
+ * La couleur est donc déterministe — la même personne garde la sienne d'un
+ * écran à l'autre, d'une session à l'autre.
+ */
+const TEINTES = [
+  "primary",
+  "info",
+  "success",
+  "warning",
+  "danger",
+  "secondary",
+] as const;
+
+export type AvatarTint = (typeof TEINTES)[number];
+
+/**
+ * Une empreinte stable, calculée sur le nom.
+ *
+ * Volontairement minuscule : cette fonction tourne pour chaque avatar d'une
+ * liste qui peut en compter des centaines. Un hachage cryptographique y
+ * coûterait mille fois plus pour un résultat visuellement identique.
+ */
+function empreinte(texte: string): number {
+  let h = 0;
+  for (let i = 0; i < texte.length; i += 1) {
+    h = (h * 31 + texte.charCodeAt(i)) | 0;
+  }
+  return Math.abs(h);
+}
+
+export function tintForName(name: string): AvatarTint {
+  return TEINTES[empreinte(name) % TEINTES.length]!;
+}
+
+/**
+ * Les initiales d'un nom.
+ *
+ * Première et dernière partie plutôt que les deux premières : « Jean-Baptiste
+ * Kouassi Mbella » se lit « JM », pas « JK ». Les particules sont écartées,
+ * sinon « Marie de la Tour » donnerait « MD ».
+ */
+const PARTICULES = new Set([
+  "de", "du", "des", "la", "le", "les", "van", "von", "da", "di", "el", "al",
+]);
+
+export function initialsOf(name: string, count = 2): string {
+  const parts = name
+    .trim()
+    .split(/[\s'-]+/)
+    .filter((p) => p.length > 0 && !PARTICULES.has(p.toLowerCase()));
+
+  if (parts.length === 0) return "";
+  if (parts.length === 1 || count === 1) {
+    return (parts[0]!.slice(0, count) || "").toUpperCase();
+  }
+
+  return (
+    (parts[0]![0] ?? "") + (parts[parts.length - 1]![0] ?? "")
+  ).toUpperCase();
 }
 
-function getInitials(name: string) {
-  return name.trim().split(/\s+/).slice(0, 2).map((part) => part[0]?.toUpperCase() ?? "").join("");
+interface AvatarGroupContextValue {
+  size: AvatarSize;
+  shape: AvatarShape;
+  variant: AvatarVariant;
 }
 
-export function Avatar({ name, size = "md", fallback, className, src, alt, onError, ...props }: AvatarProps) {
-  const [failed, setFailed] = useState(false);
+const AvatarGroupContext = createContext<AvatarGroupContextValue | null>(null);
+
+export interface AvatarProps
+  extends Omit<ImgHTMLAttributes<HTMLImageElement>, "children" | "width" | "height"> {
+  /** Le nom de la personne : il sert au repli, à la couleur et à l'annonce. */
+  name: string;
+
+  size?: AvatarSize;
+  shape?: AvatarShape;
+  variant?: AvatarVariant;
+
+  /** Force la teinte au lieu de la dériver du nom. */
+  tint?: AvatarTint;
+
+  /** Remplace les initiales — une icône, un emoji, deux lettres à soi. */
+  fallback?: ReactNode;
+
+  /** Nombre d'initiales quand le repli est automatique. */
+  initials?: 1 | 2;
+
+  status?: AvatarStatus;
+  /** Le libellé du statut, pour les lecteurs d'écran. */
+  statusLabel?: string;
+
+  /** Un liseré qui détache l'avatar de son fond. */
+  ring?: boolean;
+
+  /** Rend l'avatar actionnable — un menu de compte, par exemple. */
+  onPress?: () => void;
+}
+
+/**
+ * Le portrait d'une personne, ou ce qui le remplace.
+ *
+ * Une image met du temps à arriver, échoue parfois, et manque souvent. Les
+ * trois cas sont traités sans que la mise en page bouge : l'espace est réservé
+ * d'emblée, le repli est peint dessous, et l'image se fond par-dessus quand
+ * elle arrive.
+ */
+export function Avatar({
+  name,
+  size,
+  shape,
+  variant,
+  tint,
+  fallback,
+  initials = 2,
+  status,
+  statusLabel,
+  ring = false,
+  onPress,
+  className,
+  src,
+  alt,
+  onError,
+  onLoad,
+  style,
+  ...props
+}: AvatarProps) {
+  const groupe = useContext(AvatarGroupContext);
+  const [etatImage, setEtatImage] = useState<"attente" | "prete" | "echouee">(
+    src ? "attente" : "echouee",
+  );
+
+  const resolvedSize = size ?? groupe?.size ?? "md";
+  const resolvedShape = shape ?? groupe?.shape ?? "circle";
+  const resolvedVariant = variant ?? groupe?.variant ?? "soft";
+
+  // Le nom ne change pas à chaque rendu, le hachage non plus : dans une liste
+  // de cent participants, c'est cent calculs évités par frappe au clavier.
+  const teinte = useMemo(() => tint ?? tintForName(name), [name, tint]);
+  const lettres = useMemo(
+    () => (fallback === undefined ? initialsOf(name, initials) : null),
+    [fallback, initials, name],
+  );
+
+  const classe = cn(
+    "sia-avatar",
+    `sia-avatar--${resolvedSize}`,
+    `sia-avatar--${resolvedShape}`,
+    `sia-avatar--${resolvedVariant}`,
+    `sia-avatar--tint-${teinte}`,
+    ring && "sia-avatar--ring",
+    etatImage === "attente" && "sia-avatar--loading",
+    onPress && "sia-avatar--pressable",
+    className,
+  );
+
+  const contenu = (
+    <>
+      {/* Le repli est toujours peint, sous l'image. C'est lui qui tient la
+          place pendant le chargement, et qui reste si l'image échoue —
+          aucune bascule, donc aucun saut. */}
+      <span className="sia-avatar__fallback" aria-hidden="true">
+        {fallback ?? lettres}
+      </span>
+
+      {src && etatImage !== "echouee" && (
+        <img
+          {...props}
+          className="sia-avatar__image"
+          src={src}
+          alt={alt ?? ""}
+          loading="lazy"
+          decoding="async"
+          onLoad={(event) => {
+            setEtatImage("prete");
+            onLoad?.(event);
+          }}
+          onError={(event) => {
+            setEtatImage("echouee");
+            onError?.(event);
+          }}
+        />
+      )}
+
+      {status && (
+        <span
+          className={cn("sia-avatar__status", `sia-avatar__status--${status}`)}
+          aria-hidden="true"
+        />
+      )}
+
+      {/* Le nom n'est jamais dans l'image : un `alt` vide et un texte masqué
+          annoncent la personne une seule fois, statut compris. */}
+      <span className="sia-visually-hidden">
+        {name}
+        {status ? ` — ${statusLabel ?? LIBELLES_STATUT[status]}` : ""}
+      </span>
+    </>
+  );
+
+  if (onPress) {
+    return (
+      <button
+        type="button"
+        className={classe}
+        title={name}
+        onClick={onPress}
+        {...(style ? { style } : {})}
+      >
+        {contenu}
+      </button>
+    );
+  }
+
   return (
-    <span className={cn("sia-avatar", `sia-avatar--${size}`, className)} title={name}>
-      {src && !failed ? <img src={src} alt={alt ?? name} onError={(event) => { setFailed(true); onError?.(event); }} {...props} /> : <span aria-hidden="true">{fallback ?? getInitials(name)}</span>}
-      {!src || failed ? <span className="sia-visually-hidden">{name}</span> : null}
+    <span className={classe} title={name} {...(style ? { style } : {})}>
+      {contenu}
     </span>
   );
 }
+
+export interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+
+  /**
+   * Au-delà, les suivants sont résumés par un compteur.
+   *
+   * Sans limite, une réunion de quarante personnes déborde de sa ligne et
+   * n'apprend plus rien : au-delà de cinq visages, on ne lit plus des gens,
+   * on lit une foule.
+   */
+  max?: number;
+
+  size?: AvatarSize;
+  shape?: AvatarShape;
+  variant?: AvatarVariant;
+
+  /** Le chevauchement, de 0 (côte à côte) à 1 (fortement empilés). */
+  overlap?: number;
+
+  /** Écarte les avatars au survol, pour les distinguer. */
+  spreadOnHover?: boolean;
+
+  /** Ce qu'affiche le compteur. Par défaut `+N`. */
+  renderOverflow?: (count: number) => ReactNode;
+}
+
+/**
+ * Plusieurs personnes, sur une ligne.
+ *
+ * Les avatars se chevauchent — c'est ce qui dit « un groupe » plutôt qu'« une
+ * liste ». Chacun porte un liseré de la couleur du fond, sans quoi la pile
+ * devient une bouillie dès que deux teintes se ressemblent.
+ */
+export function AvatarGroup({
+  children,
+  max,
+  size = "md",
+  shape = "circle",
+  variant = "soft",
+  overlap = 0.25,
+  spreadOnHover = false,
+  renderOverflow,
+  className,
+  style,
+  ...props
+}: AvatarGroupProps) {
+  const tous = Array.isArray(children) ? children : [children];
+  const visibles = max === undefined ? tous : tous.slice(0, max);
+  const reste = tous.length - visibles.length;
+
+  const contexte = useMemo(
+    () => ({ size, shape, variant }),
+    [shape, size, variant],
+  );
+
+  return (
+    <AvatarGroupContext.Provider value={contexte}>
+      <div
+        className={cn(
+          "sia-avatar-group",
+          `sia-avatar-group--${size}`,
+          spreadOnHover && "sia-avatar-group--spread",
+          className,
+        )}
+        style={{
+          ...style,
+          "--sia-avatar-overlap": String(Math.min(Math.max(overlap, 0), 1)),
+        } as Record<string, string>}
+        {...props}
+      >
+        {visibles}
+        {reste > 0 && (
+          <span
+            className={cn(
+              "sia-avatar",
+              `sia-avatar--${size}`,
+              `sia-avatar--${shape}`,
+              "sia-avatar--overflow",
+            )}
+          >
+            <span className="sia-avatar__fallback">
+              {renderOverflow ? renderOverflow(reste) : `+${reste}`}
+            </span>
+          </span>
+        )}
+      </div>
+    </AvatarGroupContext.Provider>
+  );
+}

package/dist/registry/package/components/Avatar/styles.css

@@ -1,5 +1,236 @@
-.sia-avatar { display:inline-grid; place-items:center; overflow:hidden; border-radius:50%; color:var(--sia-primary-foreground); background:var(--sia-primary); font-weight:750; line-height:1; }
-.sia-avatar img { width:100%; height:100%; object-fit:cover; }
-.sia-avatar--sm { width:2rem; height:2rem; font-size:.72rem; }
-.sia-avatar--md { width:2.75rem; height:2.75rem; font-size:.85rem; }
-.sia-avatar--lg { width:4rem; height:4rem; font-size:1.1rem; }
+/**
+ * L'avatar.
+ *
+ * Tout repose sur une teinte, `--sia-avatar-tint`, posée par une classe et
+ * consommée par les trois variantes. Changer de variante ne redéfinit donc
+ * jamais la couleur : c'est ce qui permet à une teinte dérivée du nom de
+ * survivre à `soft`, `solid` et `outline` sans triplement des règles.
+ */
+
+.sia-avatar {
+  --sia-avatar-tint: var(--sia-primary);
+  --sia-avatar-size: 2.5rem;
+  --sia-avatar-radius: 50%;
+
+  position: relative;
+  display: inline-grid;
+  place-items: center;
+  flex: none;
+  width: var(--sia-avatar-size);
+  height: var(--sia-avatar-size);
+  border: 0;
+  border-radius: var(--sia-avatar-radius);
+  padding: 0;
+  overflow: hidden;
+  font-family: inherit;
+  font-weight: 600;
+  /* Les initiales ne doivent jamais être sélectionnées par un double-clic
+     destiné à ouvrir une fiche. */
+  user-select: none;
+  line-height: 1;
+}
+
+/* ── Le repli ───────────────────────────────────────────────────────────── */
+
+.sia-avatar__fallback {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 100%;
+  /* La même courbure que le parent. Sans elle, l'ombre interne de la
+     variante `outline` dessine un cadre carré que le masque circulaire
+     rogne : il n'en restait que deux fragments verticaux. */
+  border-radius: inherit;
+  /* Une lettre ne se centre pas d'elle-même : la casse haute laisse un vide
+     sous la ligne de base, et l'initiale paraît trop haute. */
+  padding-top: .04em;
+  font-size: calc(var(--sia-avatar-size) * .38);
+  letter-spacing: .01em;
+}
+
+/* ── L'image ────────────────────────────────────────────────────────────── */
+
+.sia-avatar__image {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  /* Elle arrive par-dessus le repli, qui tenait la place : rien ne saute,
+     rien ne clignote. */
+  opacity: 0;
+  animation: sia-avatar-image var(--sia-duration-base) var(--sia-easing-standard) forwards;
+}
+@keyframes sia-avatar-image {
+  from { opacity: 0; transform: scale(1.04); }
+  to { opacity: 1; transform: none; }
+}
+
+/* Pendant l'attente, un souffle très léger sur le repli — assez pour dire
+   « ça arrive », pas assez pour attirer l'œil dans une liste de cinquante. */
+.sia-avatar--loading .sia-avatar__fallback {
+  animation: sia-avatar-attente 1.6s ease-in-out infinite;
+}
+@keyframes sia-avatar-attente {
+  50% { opacity: .55; }
+}
+
+/* ── Les variantes ──────────────────────────────────────────────────────── */
+
+/* `soft` : la teinte à faible saturation, posée en dégradé très court. C'est
+   ce qui donne la matière sans crier — un aplat pur paraît plat, un dégradé
+   marqué paraît daté. */
+.sia-avatar--soft .sia-avatar__fallback {
+  background: linear-gradient(
+    145deg,
+    color-mix(in srgb, var(--sia-avatar-tint) 20%, var(--sia-background)),
+    color-mix(in srgb, var(--sia-avatar-tint) 11%, var(--sia-background))
+  );
+  color: color-mix(in srgb, var(--sia-avatar-tint) 82%, var(--sia-foreground));
+}
+
+.sia-avatar--solid .sia-avatar__fallback {
+  background: linear-gradient(
+    145deg,
+    color-mix(in srgb, var(--sia-avatar-tint) 88%, white),
+    var(--sia-avatar-tint)
+  );
+  color: var(--sia-primary-foreground, #fff);
+}
+
+.sia-avatar--outline .sia-avatar__fallback {
+  box-shadow: inset 0 0 0 1.5px color-mix(in srgb, var(--sia-avatar-tint) 45%, transparent);
+  background: var(--sia-background);
+  color: color-mix(in srgb, var(--sia-avatar-tint) 85%, var(--sia-foreground));
+}
+
+/* Le liseré qui détache du fond — indispensable dans une pile. */
+.sia-avatar--ring {
+  box-shadow:
+    0 0 0 2px var(--sia-background),
+    0 0 0 3px color-mix(in srgb, var(--sia-avatar-tint) 30%, transparent);
+}
+
+/* ── Les teintes ────────────────────────────────────────────────────────── */
+
+.sia-avatar--tint-primary { --sia-avatar-tint: var(--sia-primary); }
+.sia-avatar--tint-secondary { --sia-avatar-tint: var(--sia-secondary); }
+.sia-avatar--tint-info { --sia-avatar-tint: var(--sia-info); }
+.sia-avatar--tint-success { --sia-avatar-tint: var(--sia-success); }
+.sia-avatar--tint-warning { --sia-avatar-tint: var(--sia-warning); }
+.sia-avatar--tint-danger { --sia-avatar-tint: var(--sia-danger); }
+
+/* ── Les formes ─────────────────────────────────────────────────────────── */
+
+.sia-avatar--circle { --sia-avatar-radius: 50%; }
+/* Un rayon proportionnel à la taille : un carré arrondi de 2 rem et un de
+   5 rem n'ont pas la même courbure apparente à rayon fixe. */
+.sia-avatar--rounded { --sia-avatar-radius: calc(var(--sia-avatar-size) * .28); }
+.sia-avatar--square { --sia-avatar-radius: calc(var(--sia-avatar-size) * .08); }
+
+/* ── Les tailles ────────────────────────────────────────────────────────── */
+
+.sia-avatar--xs { --sia-avatar-size: 1.5rem; }
+.sia-avatar--sm { --sia-avatar-size: 2rem; }
+.sia-avatar--md { --sia-avatar-size: 2.5rem; }
+.sia-avatar--lg { --sia-avatar-size: 3.25rem; }
+.sia-avatar--xl { --sia-avatar-size: 4.5rem; }
+
+/* ── Le statut ──────────────────────────────────────────────────────────── */
+
+.sia-avatar__status {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  width: calc(var(--sia-avatar-size) * .26);
+  height: calc(var(--sia-avatar-size) * .26);
+  /* Un minimum absolu : sous six pixels, la pastille n'est plus lisible,
+     quelle que soit la taille de l'avatar. */
+  min-width: .4rem;
+  min-height: .4rem;
+  border-radius: 50%;
+  box-shadow: 0 0 0 2px var(--sia-background);
+}
+
+/* Décalée vers l'intérieur sur un cercle : posée au coin d'une boîte carrée,
+   elle sortirait du disque. */
+.sia-avatar--circle .sia-avatar__status {
+  right: calc(var(--sia-avatar-size) * .03);
+  bottom: calc(var(--sia-avatar-size) * .03);
+}
+
+.sia-avatar__status--online { background: var(--sia-success); }
+.sia-avatar__status--busy { background: var(--sia-danger); }
+.sia-avatar__status--away { background: var(--sia-warning); }
+.sia-avatar__status--offline {
+  background: var(--sia-background);
+  box-shadow: 0 0 0 2px var(--sia-background), inset 0 0 0 2px var(--sia-muted);
+}
+
+/* ── Actionnable ────────────────────────────────────────────────────────── */
+
+.sia-avatar--pressable {
+  cursor: pointer;
+  transition:
+    transform var(--sia-duration-fast) var(--sia-easing-standard),
+    box-shadow var(--sia-duration-fast) var(--sia-easing-standard);
+}
+.sia-avatar--pressable:hover { transform: translateY(-1px); }
+.sia-avatar--pressable:active { transform: translateY(0) scale(.96); }
+.sia-avatar--pressable:focus-visible {
+  outline: 2px solid var(--sia-primary);
+  outline-offset: 2px;
+}
+
+/* ── Le groupe ──────────────────────────────────────────────────────────── */
+
+.sia-avatar-group {
+  --sia-avatar-overlap: .25;
+  display: inline-flex;
+  align-items: center;
+  /* Une marge négative dont l'amplitude suit la taille : un chevauchement
+     fixe disparaît sur les grands avatars et les écrase sur les petits. */
+  padding-left: calc(var(--sia-avatar-size, 2.5rem) * var(--sia-avatar-overlap));
+}
+
+.sia-avatar-group > .sia-avatar {
+  margin-left: calc(var(--sia-avatar-size) * var(--sia-avatar-overlap) * -1);
+  /* Le liseré de la couleur du fond : sans lui, deux teintes voisines se
+     fondent l'une dans l'autre et la pile devient une tache. Son épaisseur
+     suit la taille — deux pixels disparaissent sur un avatar de 4,5 rem. */
+  box-shadow: 0 0 0 calc(var(--sia-avatar-size) * .055) var(--sia-background);
+  transition: transform var(--sia-duration-base) var(--sia-easing-spring);
+}
+
+/* Chaque avatar recouvre le précédent — l'ordre de peinture naturel, sans
+   `z-index`.
+   
+   L'inverse semblait plus logique, et c'est un piège : en mettant le premier
+   devant, chaque suivant est masqué **à gauche**, c'est-à-dire précisément là
+   où commence la lecture. « AK » devenait « K ». Recouvert à droite, chacun
+   garde au moins sa première initiale, et le compteur final reste entier. */
+
+/* Au survol, la pile s'ouvre pour qu'on puisse viser quelqu'un. */
+.sia-avatar-group--spread:hover > .sia-avatar {
+  margin-left: calc(var(--sia-avatar-size) * var(--sia-avatar-overlap) * -.25);
+}
+.sia-avatar-group--spread > .sia-avatar {
+  transition:
+    margin-left var(--sia-duration-base) var(--sia-easing-spring),
+    transform var(--sia-duration-base) var(--sia-easing-spring);
+}
+.sia-avatar-group > .sia-avatar:hover { transform: translateY(-2px); z-index: 10; }
+
+.sia-avatar--overflow .sia-avatar__fallback {
+  background: var(--sia-surface);
+  color: var(--sia-muted);
+  font-size: calc(var(--sia-avatar-size) * .32);
+  font-variant-numeric: tabular-nums;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .sia-avatar__image,
+  .sia-avatar--loading .sia-avatar__fallback { animation: none; opacity: 1; }
+  .sia-avatar--pressable:hover,
+  .sia-avatar-group > .sia-avatar:hover { transform: none; }
+}

package/dist/registry/package/components/Badge/index.tsx

@@ -15,6 +15,13 @@ export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
   spinnerProps?: Omit<SpinnerProps, "label">;
 }
 
+/**
+ * Une étiquette d'état, courte et dense.
+ *
+ * Elle porte un ton, jamais une action : un badge cliquable se confond avec
+ * un bouton petit, et l'on découvre qu'il ne l'était pas en cliquant. Ce
+ * qui agit est un bouton.
+ */
 export function Badge({
   tone: toneProp,
   variant: variantProp,

package/dist/registry/package/components/Button/index.tsx

@@ -26,6 +26,13 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   rightIcon?: ReactNode;
 }
 
+/**
+ * L'action, sous toutes ses formes.
+ *
+ * Le chargement y est un état et non un remplacement : le bouton garde sa
+ * taille et son libellé pendant l'appel. Un bouton qui devient un rond
+ * tournant fait bouger la mise en page, et le clic suivant tombe à côté.
+ */
 export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
   (
     {

package/dist/registry/package/components/Calendar/index.tsx

@@ -59,6 +59,17 @@ function weekNumber(value: string) {
   return Math.ceil((((target.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
 }
 
+/**
+ * Un mois de dates, sélectionnables une à une ou par plage.
+ *
+ * Trois panneaux — jours, mois, années — plutôt qu'un défilement infini :
+ * choisir une date de naissance demande de remonter trente ans, et trente
+ * ans de défilement ne sont pas une navigation.
+ *
+ * Les dates circulent en chaînes `AAAA-MM-JJ`, jamais en objets `Date` : un
+ * `Date` porte une heure et un fuseau dont une date de facture n'a que
+ * faire, et qui la décalent d'un jour une fois sur deux.
+ */
 export function Calendar({
   value,
   defaultValue,

package/dist/registry/package/components/Card/index.tsx

@@ -2,6 +2,14 @@ import { type HTMLAttributes } from "react";
 import { cn } from "@sia-ui/utils";
 import "./styles.css";
 
+/**
+ * Une surface qui regroupe ce qui va ensemble.
+ *
+ * Quatre parties séparées — `Card`, `CardHeader`, `CardBody`, `CardFooter` —
+ * plutôt que des props `title` et `footer` : dès qu'un en-tête doit porter
+ * deux boutons et une pastille, une prop ne suffit plus, et l'on se retrouve
+ * à passer du JSX à travers une chaîne.
+ */
 export function Card({ className, ...props }: HTMLAttributes<HTMLDivElement>) { return <div className={cn("sia-card", className)} {...props} />; }
 export function CardHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) { return <div className={cn("sia-card__header", className)} {...props} />; }
 export function CardBody({ className, ...props }: HTMLAttributes<HTMLDivElement>) { return <div className={cn("sia-card__body", className)} {...props} />; }

package/dist/registry/package/components/Checkbox/index.tsx

@@ -38,6 +38,14 @@ export interface CheckboxGroupProps {
   children: ReactNode;
 }
 
+/**
+ * Une case, ou un groupe de cases.
+ *
+ * `CheckboxGroup` gère la liste des valeurs cochées; la case seule gère la
+ * sienne. L'état indéterminé est une troisième valeur, pas un entre-deux
+ * visuel : il dit « certains enfants sont cochés », ce qu'aucun booléen ne
+ * sait exprimer.
+ */
 export function CheckboxGroup({
   value,
   defaultValue = [],

package/dist/registry/package/components/ColorPicker/index.tsx

@@ -2,5 +2,12 @@ import { forwardRef, useState, type InputHTMLAttributes } from "react";
 import { cn } from "@sia-ui/utils";
 import "./styles.css";
 export interface ColorPickerProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "onChange"> { onValueChange?: (value: string) => void; showValue?: boolean; }
+/**
+ * Le choix d'une couleur.
+ *
+ * La valeur hexadécimale est affichée à côté du nuancier : deux bleus
+ * voisins ne se distinguent pas à l'œil sur un écran mal calibré, alors que
+ * leurs codes, si.
+ */
 export const ColorPicker = forwardRef<HTMLInputElement, ColorPickerProps>(({ className, onValueChange, showValue = true, value, defaultValue = "#2563eb", ...props }, ref) => { const [internal, setInternal] = useState(String(defaultValue)); const current = value === undefined ? internal : String(value); return <span className={cn("sia-color-picker", className)}><input {...props} ref={ref} type="color" value={current} onChange={(event) => { if (value === undefined) setInternal(event.target.value); onValueChange?.(event.target.value); }} />{showValue && <code>{current}</code>}</span>; });
 ColorPicker.displayName = "ColorPicker";