@zevra/ui 0.4.0 → 0.5.0

package/README.md

@@ -50,6 +50,66 @@ unique à 768px reprend les valeurs mobiles du relevé.
 Chaque valeur vient des maquettes de la passation. Là où deux planches se
 contredisaient, l'arbitrage est écrit dans [DECISIONS.md](DECISIONS.md).
 
+### Les composants React
+
+```bash
+pnpm add @zevra/ui react
+```
+
+```tsx
+import '@zevra/ui/tokens.css'
+import '@zevra/ui/base.css'
+import '@zevra/ui/forms.css'
+
+import { Button, Field, Input } from '@zevra/ui/react'
+
+<Field label="ADRESSE E-MAIL" htmlFor="mail" help="Votre adresse professionnelle.">
+  <Input id="mail" type="email" />
+</Field>
+<Button>Envoyer</Button>
+```
+
+Ce ne sont **pas** des composants qui embarquent leur style : chacun n'est
+qu'une façade typée et documentée au-dessus des classes `zv-`. Le CSS reste
+la source de vérité, il s'importe à part, et un test
+(`tests/react.test.js`) vérifie que toute classe qu'un composant peut émettre
+existe bien dans un module CSS — c'est ce qui empêche les deux de diverger.
+
+**Rendu serveur.** Un seul module est marqué `"use client"` : `overlays`
+(tiroir, modale, notification), les seuls qui aient besoin du navigateur.
+Tout le reste se rend au serveur — dans un composant serveur Next comme dans
+une île Astro à zéro JavaScript. Les composants qui prennent un gestionnaire
+d'événement (`Switch`, `Seg`, `Tabs`…) restent sans état : c'est un composant
+client à toi qui détient l'état et les rend.
+
+**Astro.** `@astrojs/react` rend ces composants en HTML statique à la
+compilation, sans JavaScript envoyé, tant qu'aucune directive `client:*` n'est
+posée. Un `<Button>` dans une `.astro` ne coûte donc rien de plus qu'un
+`<button class="zv-btn">` — avec les props typées et la documentation en
+prime. ⚠️ En revanche, un composant `.astro` ne peut pas être passé en enfant
+d'un composant React : ce sens-là ne fonctionne pas.
+
+**Les props sont en français**, comme le CSS et les commentaires. Celles qui
+portent une décision de charte sont documentées à l'endroit où on les lit, et
+les avertissements ⚠️ signalent ce qui casse le système si on le contourne —
+pas de simples préférences.
+
+**`className` est accepté partout**, mais c'est une sortie de secours, pas un
+usage courant : une classe locale qui repeint un composant du système est une
+divergence qui n'a pas dit son nom.
+
+### Le catalogue
+
+```tsx
+import { CATALOGUE } from '@zevra/ui/react/catalogue'
+```
+
+Chaque composant y a un exemple rendu, le code qui le produit, et le résumé de
+ce qu'il fait — et surtout de quand ne pas l'employer. C'est ce que rend la
+page « Design system » de l'admin, et c'est aussi le banc d'essai du test de
+dérive : un composant sans exemple n'est ni documenté ni couvert, et le test
+le refuse.
+
 ## Deux couches
 
 Le paquet en porte deux, et elles ne servent pas au même usage.
@@ -167,7 +227,10 @@ Tiroir et modale s'ouvrent par un état porté sur le conteneur. Deux écritures
 panneau resterait ouvert. C'est précisément pour cela que la variante en
 classe existe.
 
-Fermer sur Échap relève du gabarit : le CSS ne sait pas le faire.
+Fermer sur Échap relève du gabarit : le CSS ne sait pas le faire. En React,
+`Drawer` et `Modal` (`@zevra/ui/react`) le font déjà, avec le piège de focus,
+la restitution du focus au bouton d'ouverture et le verrou de défilement —
+et le hook `useOverlay` est exporté pour un enrobage maison.
 
 ## Les règles qui ne se négocient pas
 

package/dist/actions.d.ts

@@ -0,0 +1,41 @@
+import type { AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
+/** Variantes de bouton. Une seule pleine par écran — c'est la règle de charte. */
+export type BoutonVariante = 'plein' | 'fantome' | 'encre';
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
+    variante?: BoutonVariante;
+    /** Hauteur réduite, pour une barre de navigation. */
+    compact?: boolean;
+    /** Pleine largeur — l'appel à l'action d'un écran mobile. */
+    bloc?: boolean;
+    /** Échappatoire assumée. À employer pour un ajustement de position, jamais
+     *  pour redéfinir une couleur ou une taille : c'est par là que les apps
+     *  recommencent à écrire leur propre charte. */
+    className?: string;
+    children?: ReactNode;
+}
+export declare function Button({ variante, compact, bloc, className, type, ...reste }: ButtonProps): import("react").JSX.Element;
+export interface ButtonLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'className'> {
+    variante?: BoutonVariante;
+    compact?: boolean;
+    bloc?: boolean;
+    className?: string;
+}
+/** Le même bouton, mais qui navigue. Un <a> et un <button> ne s'échangent pas :
+ *  l'un ouvre dans un onglet, se copie et s'indexe, l'autre non. */
+export declare function ButtonLink({ variante, compact, bloc, className, ...reste }: ButtonLinkProps): import("react").JSX.Element;
+export interface ButtonRowProps extends Omit<HTMLAttributes<HTMLDivElement>, 'className'> {
+    /** Empile les boutons et les étire — la disposition mobile. */
+    empile?: boolean;
+    className?: string;
+}
+export declare function ButtonRow({ empile, className, ...reste }: ButtonRowProps): import("react").JSX.Element;
+export interface LinkArrowProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'className'> {
+    /** Sur la bande manifeste, où le lien passe en blanc. */
+    surSombre?: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+/** Lien fléché. La flèche est fournie : elle fait partie du composant, pas du
+ *  contenu — la recopier à la main a produit trois tracés différents. */
+export declare function LinkArrow({ surSombre, className, children, ...reste }: LinkArrowProps): import("react").JSX.Element;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../react/actions.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACV,MAAM,OAAO,CAAA;AAGd,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAA;AAQ1D,MAAM,WAAW,WACf,SAAQ,IAAI,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC;IAClE,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;oDAEgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED,wBAAgB,MAAM,CAAC,EACrB,QAAkB,EAClB,OAAO,EACP,IAAI,EACJ,SAAS,EACT,IAAe,EACf,GAAG,KAAK,EACT,EAAE,WAAW,+BAab;AAED,MAAM,WAAW,eACf,SAAQ,IAAI,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC;IAClE,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;oEACoE;AACpE,wBAAgB,UAAU,CAAC,EACzB,QAAkB,EAClB,OAAO,EACP,IAAI,EACJ,SAAS,EACT,GAAG,KAAK,EACT,EAAE,eAAe,+BAYjB;AAED,MAAM,WAAW,cACf,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC;IACzD,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,+BAOxE;AAED,MAAM,WAAW,cACf,SAAQ,IAAI,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC;IAClE,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED;yEACyE;AACzE,wBAAgB,SAAS,CAAC,EACxB,SAAS,EACT,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,cAAc,+BAiBhB"}

package/dist/actions.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from './cx.js';
+const VARIANTE_BOUTON = {
+    plein: 'zv-btn',
+    fantome: 'zv-btn--ghost',
+    encre: 'zv-btn--ink',
+};
+export function Button({ variante = 'plein', compact, bloc, className, type = 'button', ...reste }) {
+    return (_jsx("button", { type: type, className: cx(VARIANTE_BOUTON[variante], compact && 'zv-btn--sm', bloc && 'zv-btn--block', className), ...reste }));
+}
+/** Le même bouton, mais qui navigue. Un <a> et un <button> ne s'échangent pas :
+ *  l'un ouvre dans un onglet, se copie et s'indexe, l'autre non. */
+export function ButtonLink({ variante = 'plein', compact, bloc, className, ...reste }) {
+    return (_jsx("a", { className: cx(VARIANTE_BOUTON[variante], compact && 'zv-btn--sm', bloc && 'zv-btn--block', className), ...reste }));
+}
+export function ButtonRow({ empile, className, ...reste }) {
+    return (_jsx("div", { className: cx('zv-btn-row', empile && 'zv-btn-row--stack', className), ...reste }));
+}
+/** Lien fléché. La flèche est fournie : elle fait partie du composant, pas du
+ *  contenu — la recopier à la main a produit trois tracés différents. */
+export function LinkArrow({ surSombre, className, children, ...reste }) {
+    return (_jsxs("a", { className: cx('zv-link-arrow', surSombre && 'zv-link-arrow--on-dark', className), ...reste, children: [children, _jsxs("svg", { viewBox: "0 0 24 24", "aria-hidden": "true", children: [_jsx("path", { d: "M5 12h14" }), _jsx("path", { d: "M13 6l6 6-6 6" })] })] }));
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../react/actions.tsx"],"names":[],"mappings":";AAYA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAK5B,MAAM,eAAe,GAAmC;IACtD,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,eAAe;IACxB,KAAK,EAAE,aAAa;CACrB,CAAA;AAgBD,MAAM,UAAU,MAAM,CAAC,EACrB,QAAQ,GAAG,OAAO,EAClB,OAAO,EACP,IAAI,EACJ,SAAS,EACT,IAAI,GAAG,QAAQ,EACf,GAAG,KAAK,EACI;IACZ,OAAO,CACL,iBACE,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,EAAE,CACX,eAAe,CAAC,QAAQ,CAAC,EACzB,OAAO,IAAI,YAAY,EACvB,IAAI,IAAI,eAAe,EACvB,SAAS,CACV,KACG,KAAK,GACT,CACH,CAAA;AACH,CAAC;AAUD;oEACoE;AACpE,MAAM,UAAU,UAAU,CAAC,EACzB,QAAQ,GAAG,OAAO,EAClB,OAAO,EACP,IAAI,EACJ,SAAS,EACT,GAAG,KAAK,EACQ;IAChB,OAAO,CACL,YACE,SAAS,EAAE,EAAE,CACX,eAAe,CAAC,QAAQ,CAAC,EACzB,OAAO,IAAI,YAAY,EACvB,IAAI,IAAI,eAAe,EACvB,SAAS,CACV,KACG,KAAK,GACT,CACH,CAAA;AACH,CAAC;AASD,MAAM,UAAU,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,EAAkB;IACvE,OAAO,CACL,cACE,SAAS,EAAE,EAAE,CAAC,YAAY,EAAE,MAAM,IAAI,mBAAmB,EAAE,SAAS,CAAC,KACjE,KAAK,GACT,CACH,CAAA;AACH,CAAC;AAUD;yEACyE;AACzE,MAAM,UAAU,SAAS,CAAC,EACxB,SAAS,EACT,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACO;IACf,OAAO,CACL,aACE,SAAS,EAAE,EAAE,CACX,eAAe,EACf,SAAS,IAAI,wBAAwB,EACrC,SAAS,CACV,KACG,KAAK,aAER,QAAQ,EACT,eAAK,OAAO,EAAC,WAAW,iBAAa,MAAM,aACzC,eAAM,CAAC,EAAC,UAAU,GAAG,EACrB,eAAM,CAAC,EAAC,eAAe,GAAG,IACtB,IACJ,CACL,CAAA;AACH,CAAC"}

package/dist/catalogue.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from 'react';
+export interface Exemple {
+    /** Identifiant stable — sert d'ancre dans la page de consultation. */
+    id: string;
+    nom: string;
+    /** Ce que le composant fait, et surtout quand NE PAS l'employer. */
+    resume: string;
+    /** Le code qui produit `rendu`, à copier tel quel. */
+    code: string;
+    rendu: ReactNode;
+    /** Rendu sur la bande manifeste plutôt que sur papier. */
+    surSombre?: boolean;
+}
+export interface GroupeCatalogue {
+    id: string;
+    nom: string;
+    resume: string;
+    /** `applicatif` : interfaces internes. `vitrine` : pages publiques.
+     *  `commun` : les deux. */
+    couche: 'commun' | 'applicatif' | 'vitrine';
+    /** Le module CSS à charger pour ce groupe. */
+    css: string;
+    exemples: Exemple[];
+}
+export declare const CATALOGUE: GroupeCatalogue[];
+/** Tous les exemples à plat — pratique pour une recherche ou un test. */
+export declare const EXEMPLES: (Exemple & {
+    groupe: string;
+})[];
+//# sourceMappingURL=catalogue.d.ts.map

package/dist/catalogue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue.d.ts","sourceRoot":"","sources":["../react/catalogue.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAoChD,MAAM,WAAW,OAAO;IACtB,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;IACX,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAA;IACd,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,SAAS,CAAA;IAChB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd;+BAC2B;IAC3B,MAAM,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAA;IAC3C,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,OAAO,EAAE,CAAA;CACpB;AA0JD,eAAO,MAAM,SAAS,EAAE,eAAe,EA63CtC,CAAA;AAMD,yEAAyE;AACzE,eAAO,MAAM,QAAQ,EAAE,CAAC,OAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EAEpD,CAAA"}