@sia-ui/cli 0.2.1 → 0.3.0

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

@@ -2,4 +2,11 @@ import { useState, type ReactNode, type TextareaHTMLAttributes } from "react";
 import { Textarea } from "../Textarea";
 import { cn } from "@sia-ui/utils";
 export interface MarkdownEditorProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "defaultValue" | "onChange"> { value?: string; defaultValue?: string; onValueChange?: (value: string) => void; preview?: (value: string) => ReactNode; }
+/**
+ * Une saisie Markdown, avec son aperçu.
+ *
+ * Le rendu n'est pas fourni : `preview` reçoit le texte et rend ce qu'il
+ * veut. Embarquer un moteur Markdown imposerait le nôtre à un projet qui a
+ * déjà le sien — et ferait grossir le paquet pour tous les autres.
+ */
 export function MarkdownEditor({ value, defaultValue = "", onValueChange, preview, className, ...props }: MarkdownEditorProps) { const [internal, setInternal] = useState(defaultValue); const [mode, setMode] = useState<"write" | "preview">("write"); const current = value ?? internal; const update = (next: string) => { if (value === undefined) setInternal(next); onValueChange?.(next); }; return <div className={cn("sia-markdown-editor", className)}><div className="sia-editor-toolbar"><button type="button" aria-pressed={mode === "write"} onClick={() => setMode("write")}>Écrire</button><button type="button" aria-pressed={mode === "preview"} onClick={() => setMode("preview")}>Aperçu</button></div>{mode === "write" ? <Textarea {...props} value={current} onChange={(event) => update(event.target.value)} /> : <div className="sia-editor-preview">{preview ? preview(current) : <pre>{current}</pre>}</div>}</div>; }

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

@@ -1,3 +1,10 @@
 import { Calendar, type CalendarProps } from "../Calendar";
 import { cn } from "@sia-ui/utils";
+/**
+ * Le même calendrier, en plus petit.
+ *
+ * Une variante de taille et non un composant à part : deux calendriers
+ * séparés auraient divergé sur la sélection de plage, les jours désactivés
+ * ou le premier jour de la semaine.
+ */
 export function MiniCalendar({ className, ...props }: CalendarProps) { return <Calendar {...props} className={cn("sia-calendar--mini", className)} />; }

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

@@ -17,6 +17,14 @@ export interface ModalProps {
   className?: string;
 }
 
+/**
+ * Une boîte qui interrompt.
+ *
+ * Elle enferme le focus et bloque le défilement de la page : sans cela, la
+ * tabulation continue derrière le voile, et l'on remplit un formulaire
+ * qu'on ne voit pas. L'échappement la referme toujours — c'est la sortie
+ * que tout le monde essaie en premier.
+ */
 export function Modal({
   open,
   onOpenChange,

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

@@ -1,5 +1,12 @@
 import { forwardRef, type InputHTMLAttributes } from "react";
 import { cn } from "@sia-ui/utils";
 export interface MonthPickerProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "onChange"> { onValueChange?: (value: string) => void; invalid?: boolean; }
+/**
+ * Un mois, sans le jour.
+ *
+ * C'est le grain d'un exercice comptable ou d'un rapport mensuel : demander
+ * un jour obligerait à en choisir un arbitrairement, et le premier du mois
+ * finirait par être pris pour une vraie date.
+ */
 export const MonthPicker = forwardRef<HTMLInputElement, MonthPickerProps>(({ onValueChange, invalid, className, ...props }, ref) => <input {...props} ref={ref} type="month" className={cn("sia-month-picker", invalid && "sia-picker--invalid", className)} aria-invalid={invalid || undefined} onChange={(event) => onValueChange?.(event.target.value)} />);
 MonthPicker.displayName = "MonthPicker";

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

@@ -20,6 +20,13 @@ export interface MultiSelectProps {
   "aria-invalid"?: boolean;
   "aria-required"?: boolean;
 }
+/**
+ * Plusieurs choix dans une liste.
+ *
+ * Les valeurs retenues s'affichent dans le champ, retirables une à une :
+ * un compte seul — « 3 sélectionnés » — oblige à rouvrir la liste pour
+ * savoir lesquels.
+ */
 export function MultiSelect({
   id,
   options,

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

@@ -2,4 +2,11 @@ import { useRef, useState, type ClipboardEvent, type KeyboardEvent } from "react
 import { cn } from "@sia-ui/utils";
 import "./styles.css";
 export interface OtpInputProps { id?: string; value?: string; defaultValue?: string; onValueChange?: (value: string) => void; length?: number; inputMode?: "numeric" | "text"; mask?: boolean; disabled?: boolean; className?: string; "aria-describedby"?: string; "aria-labelledby"?: string; "aria-invalid"?: boolean; "aria-required"?: boolean; }
+/**
+ * Un code à usage unique, chiffre par chiffre.
+ *
+ * Le collage d'un code entier remplit toutes les cases d'un coup : c'est
+ * ainsi qu'on le récupère d'un SMS, et le forcer à être retapé serait une
+ * punition pour rien.
+ */
 export function OtpInput({ id, value, defaultValue = "", onValueChange, length = 6, inputMode = "numeric", mask, disabled, className, ...ariaProps }: OtpInputProps) { const [internal, setInternal] = useState(defaultValue); const refs = useRef<Array<HTMLInputElement | null>>([]); const current = (value ?? internal).padEnd(length, " ").slice(0, length).split(""); const update = (chars: string[]) => { const next = chars.join("").trimEnd(); if (value === undefined) setInternal(next); onValueChange?.(next); }; const accept = (text: string) => inputMode === "numeric" ? text.replace(/\D/g, "") : text; const paste = (event: ClipboardEvent<HTMLDivElement>) => { event.preventDefault(); const next = accept(event.clipboardData.getData("text")).slice(0, length).padEnd(length, " ").split(""); update(next); refs.current[Math.min(next.join("").trimEnd().length, length - 1)]?.focus(); }; return <div id={id} className={cn("sia-otp-input", className)} onPaste={paste} {...ariaProps}>{current.map((char, index) => <input key={index} ref={(node) => { refs.current[index] = node; }} value={char.trim()} type={mask ? "password" : "text"} inputMode={inputMode} maxLength={1} disabled={disabled} aria-label={`Caractère ${index + 1}`} onChange={(event) => { const next = [...current]; next[index] = accept(event.target.value).slice(-1) || " "; update(next); if (next[index]?.trim()) refs.current[index + 1]?.focus(); }} onKeyDown={(event: KeyboardEvent<HTMLInputElement>) => { if (event.key === "Backspace" && !current[index]?.trim()) refs.current[index - 1]?.focus(); if (event.key === "ArrowLeft") refs.current[index - 1]?.focus(); if (event.key === "ArrowRight") refs.current[index + 1]?.focus(); }} />)}</div>; }

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

@@ -10,13 +10,19 @@ import {
 } from "react";
 import { createPortal } from "react-dom";
 import { cn } from "@sia-ui/utils";
+import { computeFloatingPosition } from "@sia-ui/headless";
+import type { Placement } from "@sia-ui/headless";
 import "./styles.css";
 
-export type OverlayPlacement =
-  | "bottom-start"
-  | "bottom-end"
-  | "top-start"
-  | "top-end";
+/**
+ * Les douze placements du moteur de géométrie.
+ *
+ * Ce composant n'en exposait que quatre — haut et bas — parce qu'il calculait
+ * lui-même sa position, en vertical seulement. Le calcul vit dans
+ * `@sia-ui/headless`, sait basculer et recadrer dans les deux axes, et sert
+ * déjà le natif : le refaire ici privait tous les flottants des côtés.
+ */
+export type OverlayPlacement = Placement;
 
 export interface OverlayProps {
   open: boolean;
@@ -34,6 +40,16 @@ export interface OverlayProps {
 
 type Position = CSSProperties & { visibility: "hidden" | "visible" };
 
+/**
+ * Ce qui flotte à côté d'un élément.
+ *
+ * Le socle des menus, des listes déroulantes et des infobulles. Il place le
+ * panneau parmi douze positions, le retourne quand le bord de la fenêtre
+ * approche, et le ramène dans la vue plutôt que de le laisser déborder.
+ *
+ * Le calcul vit dans `@sia-ui/headless` : il ne dépend d'aucun rendu, et
+ * sert donc aussi à ce qui n'est pas le DOM.
+ */
 export function Overlay({
   open,
   anchorRef,
@@ -61,32 +77,26 @@ export function Overlay({
 
     const anchorRect = anchor.getBoundingClientRect();
     const overlayRect = overlay.getBoundingClientRect();
+
+    // `Select` veut un panneau au moins aussi large que son champ : la largeur
+    // entre donc dans le calcul, sinon le placement serait fait sur une taille
+    // que le panneau n'aura pas.
     const width = matchAnchorWidth
       ? Math.max(anchorRect.width, overlayRect.width)
       : overlayRect.width;
-    const spaceBelow = window.innerHeight - anchorRect.bottom - viewportPadding;
-    const spaceAbove = anchorRect.top - viewportPadding;
-    const requestedTop = placement.startsWith("top");
-    const useTop = requestedTop
-      ? spaceAbove >= overlayRect.height || spaceAbove > spaceBelow
-      : spaceBelow < overlayRect.height && spaceAbove > spaceBelow;
-    const rawTop = useTop
-      ? anchorRect.top - overlayRect.height - offset
-      : anchorRect.bottom + offset;
-    const alignEnd = placement.endsWith("end");
-    const rawLeft = alignEnd
-      ? anchorRect.right - width
-      : anchorRect.left;
-    const maxLeft = Math.max(viewportPadding, window.innerWidth - width - viewportPadding);
-    const maxTop = Math.max(
-      viewportPadding,
-      window.innerHeight - overlayRect.height - viewportPadding,
+
+    const { top, left } = computeFloatingPosition(
+      anchorRect,
+      { width, height: overlayRect.height },
+      { width: window.innerWidth, height: window.innerHeight },
+      placement,
+      { offset, padding: viewportPadding },
     );
 
     setStyle({
       position: "fixed",
-      top: Math.min(Math.max(rawTop, viewportPadding), maxTop),
-      left: Math.min(Math.max(rawLeft, viewportPadding), maxLeft),
+      top,
+      left,
       minWidth: matchAnchorWidth ? anchorRect.width : undefined,
       maxWidth: `calc(100vw - ${viewportPadding * 2}px)`,
       visibility: "visible",

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

@@ -10,6 +10,13 @@ export interface PageHeaderProps {
   className?: string;
 }
 
+/**
+ * Le titre d'un écran, et ses actions.
+ *
+ * Un seul `<h1>` par page, rendu ici : la hiérarchie des titres est ce qui
+ * permet de parcourir un écran au lecteur d'écran, et deux `<h1>` la
+ * cassent sans que rien ne se voie.
+ */
 export function PageHeader({ title, description, eyebrow, actions, className }: PageHeaderProps) {
   return (
     <header className={cn("sia-page-header", className)}>

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

@@ -1,3 +1,9 @@
 import { type ReactNode } from "react";
 export interface PermissionGateProps { permissions: string[]; require: string | string[]; mode?: "all" | "any"; fallback?: ReactNode; children: ReactNode; }
+/**
+ * Ce qui n'apparaît qu'avec le droit correspondant.
+ *
+ * > Ceci masque une portion d'écran; **ça ne protège pas une API**. Le
+ * > serveur reste seul juge, et doit refuser la même chose.
+ */
 export function PermissionGate({ permissions, require, mode = "all", fallback = null, children }: PermissionGateProps) { const expected = Array.isArray(require) ? require : [require]; const allowed = mode === "all" ? expected.every((item) => permissions.includes(item)) : expected.some((item) => permissions.includes(item)); return <>{allowed ? children : fallback}</>; }

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

@@ -5,6 +5,13 @@ import { Overlay, type OverlayPlacement } from "../Overlay";
 import "./styles.css";
 
 export interface PopoverProps { content: ReactNode; title?: ReactNode; children: ReactElement<{ onClick?: () => void; "aria-expanded"?: boolean }>; open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void; placement?: OverlayPlacement; trigger?: "click" | "hover"; variant?: "solid" | "outline"; tone?: ComponentTone; disabled?: boolean; className?: string; }
+/**
+ * Un panneau attaché à un élément, avec du contenu qu'on peut viser.
+ *
+ * À la différence d'une infobulle, il reste ouvert : on y met un lien, un
+ * bouton, un petit formulaire. Une infobulle qui contient un bouton est une
+ * infobulle cassée — elle disparaît dès qu'on va vers lui.
+ */
 export function Popover({ content, title, children, open: openProp, defaultOpen = false, onOpenChange, placement = "bottom-start", trigger = "click", variant = "outline", tone = "neutral", disabled = false, className }: PopoverProps) {
   const anchorRef = useRef<HTMLElement>(null); const [internalOpen, setInternalOpen] = useState(defaultOpen); const open = openProp ?? internalOpen; const setOpen = (next: boolean) => { if (disabled) return; if (openProp === undefined) setInternalOpen(next); onOpenChange?.(next); };
   const child = isValidElement(children) ? cloneElement(children, { ref: anchorRef, "aria-expanded": open, ...(trigger === "click" ? { onClick: () => { children.props.onClick?.(); setOpen(!open); } } : {}) } as never) : children;

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

@@ -3,4 +3,11 @@ import { cn } from "@sia-ui/utils";
 import "./styles.css";
 
 export interface QRCodeProps { value: string; size?: number; label?: string; render?: (value: string, size: number) => ReactNode; className?: string; }
+/**
+ * Un code à scanner.
+ *
+ * Le rendu est délégué à `render` : embarquer un encodeur ajouterait une
+ * dépendance à tous ceux qui ne s'en servent pas, alors que les projets qui
+ * en ont besoin ont déjà le leur.
+ */
 export function QRCode({ value, size = 160, label = "Code QR", render, className }: QRCodeProps) { return <figure className={cn("sia-qr-code", className)} aria-label={label} style={{ width: size }}><div className="sia-qr-code__frame" style={{ width: size, height: size }}>{render ? render(value, size) : <div className="sia-qr-code__adapter"><strong>QR</strong><span>Encodeur requis</span></div>}</div><figcaption>{value}</figcaption></figure>; }

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

@@ -10,6 +10,13 @@ const RadioGroupContext = createContext<RadioContextValue | null>(null);
 export interface RadioGroupProps {
   id?: string; name?: string; label?: ReactNode; value?: RadioValue; defaultValue?: RadioValue; onValueChange?: (value: RadioValue) => void; orientation?: "horizontal" | "vertical"; disabled?: boolean; size?: "sm" | "md" | "lg"; tone?: ComponentTone; className?: string; "aria-describedby"?: string; "aria-labelledby"?: string; "aria-invalid"?: boolean; "aria-required"?: boolean; children: ReactNode;
 }
+/**
+ * Un choix parmi plusieurs, tous visibles.
+ *
+ * Au-delà de cinq ou six options, une liste déroulante lit mieux : des
+ * boutons radio en montrent la totalité, ce qui est leur intérêt tant qu'on
+ * peut encore les embrasser du regard.
+ */
 export function RadioGroup({ id, name, label, value, defaultValue, onValueChange, orientation = "vertical", disabled, size = "md", tone = "primary", className, children, ...ariaProps }: RadioGroupProps) {
   const generatedName = useId(); const [internal, setInternal] = useState(defaultValue); const current = value ?? internal;
   const setValue = (next: RadioValue) => { if (value === undefined) setInternal(next); onValueChange?.(next); };

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

@@ -19,6 +19,12 @@ export interface RatingProps {
   "aria-invalid"?: boolean;
   "aria-required"?: boolean;
 }
+/**
+ * Une note, en étoiles.
+ *
+ * `allowClear` rend la note réversible : sans lui, cliquer une étoile par
+ * erreur est définitif, puisqu'aucune étoile ne vaut « aucune note ».
+ */
 export function Rating({
   id,
   value,

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

@@ -4,4 +4,11 @@ import type { SelectOption } from "../Select";
 import "./styles.css";
 export interface ReferenceOption extends SelectOption { description?: ReactNode; }
 export interface ReferenceSelectProps extends Omit<AutocompleteProps, "options"> { options: ReferenceOption[]; }
+/**
+ * Un choix parmi des objets métier, pas parmi des mots.
+ *
+ * Chaque option porte une description : deux clients peuvent s'appeler
+ * « Entreprise Alpha », et seule la ligne en dessous — la ville, le numéro
+ * de compte — dit lequel on vise.
+ */
 export function ReferenceSelect({ options, ...props }: ReferenceSelectProps) { return <Autocomplete {...props} options={options.map((option) => ({ ...option, label: <span className="sia-reference-select__option"><strong>{option.label}</strong>{option.description && <small>{option.description}</small>}</span> }))} />; }

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

@@ -9,6 +9,12 @@ export interface RelativeTimeProps extends Omit<HTMLAttributes<HTMLTimeElement>,
   refreshInterval?: number;
 }
 
+/**
+ * Une date, dite par rapport à maintenant.
+ *
+ * Elle se rafraîchit d'elle-même : « il y a une minute » affiché une heure
+ * plus tard est faux, et rien ne le signale à qui lit l'écran resté ouvert.
+ */
 export function RelativeTime({ value, locale = "fr-FR", prefix, refreshInterval = 60_000, className, title, ...props }: RelativeTimeProps) {
   const [, refresh] = useState(0);
   useEffect(() => {

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

@@ -3,4 +3,11 @@ import { cn } from "@sia-ui/utils";
 import "./styles.css";
 
 export interface ResizablePanelProps { first: ReactNode; second: ReactNode; defaultSize?: number; minSize?: number; maxSize?: number; direction?: "horizontal" | "vertical"; className?: string; }
+/**
+ * Deux zones, et une poignée entre elles.
+ *
+ * Les bornes `minSize` et `maxSize` empêchent de réduire un panneau à
+ * rien : une zone à zéro pour cent disparaît avec sa poignée, et on ne peut
+ * plus la rouvrir.
+ */
 export function ResizablePanel({ first, second, defaultSize = 50, minSize = 20, maxSize = 80, direction = "horizontal", className }: ResizablePanelProps) { const [size, setSize] = useState(defaultSize); const start = (event: PointerEvent<HTMLDivElement>) => { const container = event.currentTarget.parentElement; if (!container) return; event.currentTarget.setPointerCapture(event.pointerId); const move = (moveEvent: globalThis.PointerEvent) => { const rect = container.getBoundingClientRect(); const next = direction === "horizontal" ? ((moveEvent.clientX - rect.left) / rect.width) * 100 : ((moveEvent.clientY - rect.top) / rect.height) * 100; setSize(Math.min(maxSize, Math.max(minSize, next))); }; const stop = () => { window.removeEventListener("pointermove", move); window.removeEventListener("pointerup", stop); }; window.addEventListener("pointermove", move); window.addEventListener("pointerup", stop); }; const firstStyle = { flexBasis: `${size}%` }; return <div className={cn("sia-resizable-panel", `sia-resizable-panel--${direction}`, className)}><section style={firstStyle}>{first}</section><div className="sia-resizable-panel__handle" role="separator" aria-orientation={direction} aria-valuenow={Math.round(size)} tabIndex={0} onPointerDown={start} onKeyDown={(event) => { const delta = event.key === "ArrowLeft" || event.key === "ArrowUp" ? -5 : event.key === "ArrowRight" || event.key === "ArrowDown" ? 5 : 0; if (delta) { event.preventDefault(); setSize((current) => Math.min(maxSize, Math.max(minSize, current + delta))); } }} /><section>{second}</section></div>; }