@zevra/ui 0.4.0 → 0.5.0

package/react/overlays.tsx

@@ -0,0 +1,237 @@
+'use client'
+
+// Enrobages — voile, tiroir, modale, notification flottante.
+//
+// SEUL fichier du paquet marqué « use client », avec un hook. Tout ce qui vit
+// ici vole le regard à la page : il faut une touche Échap, un piège de focus
+// et un verrou de défilement, et rien de cela ne s'écrit en CSS.
+//
+// ⚠️ Ne PAS écrire `data-open={ouvert}` en React : cela rend `data-open="false"`,
+// que le sélecteur d'attribut du CSS considère comme PRÉSENT — le panneau
+// resterait ouvert. Ces composants emploient la classe `--open`, prévue pour ça.
+
+import { useCallback, useEffect, useRef } from 'react'
+import type { HTMLAttributes, ReactNode, RefObject } from 'react'
+import { cx } from './cx.js'
+
+type Div = Omit<HTMLAttributes<HTMLDivElement>, 'className'>
+
+const FOCUSABLES =
+  'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])'
+
+export interface UseOverlayOptions {
+  ouvert: boolean
+  onClose: () => void
+  /** Le nœud à piéger. Sans lui, pas de piège — mais Échap fonctionne quand
+   *  même. */
+  panneau?: RefObject<HTMLElement | null>
+  /** Verrouille le défilement du document. Vrai pour une modale, vrai pour un
+   *  tiroir mobile ; faux pour ce qui ne recouvre pas la page. */
+  verrouille?: boolean
+}
+
+/** Échap, piège de focus, restitution du focus, verrou de défilement.
+ *  Exporté : une app qui dessine son propre enrobage doit pouvoir reprendre
+ *  ce comportement sans recopier trente lignes qui se trompent une fois sur
+ *  deux. */
+export function useOverlay({ ouvert, onClose, panneau, verrouille = true }: UseOverlayOptions) {
+  // Le nœud qui avait le focus AVANT l'ouverture : c'est à lui qu'il revient
+  // à la fermeture. Sans cela, le focus repart au début du document et un
+  // utilisateur au clavier perd sa place dans la page.
+  const origine = useRef<HTMLElement | null>(null)
+
+  useEffect(() => {
+    if (!ouvert) return
+    const cible = panneau?.current
+    // ⚠️ Le document du PANNEAU, pas `document` : un enrobage peut vivre dans
+    // un autre document que celui du script (planche de composants rendue dans
+    // un iframe, fenêtre détachée). Écouter `document` y poserait la touche
+    // Échap sur la page hôte — elle fermerait la modale d'à côté et pas
+    // celle-ci. Sans panneau, on retombe sur le document courant.
+    const docu = cible?.ownerDocument ?? document
+    origine.current = docu.activeElement as HTMLElement | null
+
+    // ⚠️ La valeur PRÉCÉDENTE est restaurée, pas remise à '' : une page qui
+    // gérait déjà son propre défilement serait cassée par un reset aveugle.
+    const overflowPrecedent = verrouille ? docu.body.style.overflow : null
+    if (verrouille) docu.body.style.overflow = 'hidden'
+
+    const premier = cible?.querySelector<HTMLElement>(FOCUSABLES)
+    premier?.focus()
+
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        e.stopPropagation()
+        onClose()
+        return
+      }
+      if (e.key !== 'Tab' || !cible) return
+      const noeuds = Array.from(cible.querySelectorAll<HTMLElement>(FOCUSABLES)).filter(
+        (n) => n.offsetParent !== null || n === docu.activeElement,
+      )
+      if (noeuds.length === 0) return
+      const debut = noeuds[0]!
+      const fin = noeuds[noeuds.length - 1]!
+      // Le cycle est refermé à la main : sans cela, Tab sort du panneau et
+      // l'utilisateur se retrouve à parcourir la page cachée derrière le voile.
+      if (e.shiftKey && docu.activeElement === debut) {
+        e.preventDefault()
+        fin.focus()
+      } else if (!e.shiftKey && docu.activeElement === fin) {
+        e.preventDefault()
+        debut.focus()
+      }
+    }
+
+    docu.addEventListener('keydown', onKey)
+    return () => {
+      docu.removeEventListener('keydown', onKey)
+      if (overflowPrecedent !== null) docu.body.style.overflow = overflowPrecedent
+      origine.current?.focus?.()
+    }
+  }, [ouvert, onClose, panneau, verrouille])
+}
+
+/* ─── Voile ────────────────────────────────────────────────────────── */
+
+/** Toujours l'encre de charte diluée, jamais un noir pur : la page est
+ *  bleutée, un gris neutre y ferait un trou sale. */
+export function Scrim({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-scrim', className)} aria-hidden="true" {...reste} />
+}
+
+/* ─── Tiroir ───────────────────────────────────────────────────────── */
+
+export interface DrawerProps extends Omit<Div, 'title'> {
+  ouvert: boolean
+  onClose: () => void
+  /** Nom du dialogue — ce que le lecteur d'écran annonce à l'ouverture. */
+  label?: string
+  /** Croix de fermeture posée en absolu par-dessus la tête du panneau. */
+  fermeture?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+/** ⚠️ Le tiroir n'existe QUE sous le point de rupture : au-dessus, la
+ *  navigation est une colonne et il n'y a rien à ouvrir. Le CSS s'en charge —
+ *  ne pas conditionner le rendu sur la largeur en JavaScript, le serveur ne
+ *  la connaît pas. */
+export function Drawer({
+  ouvert,
+  onClose,
+  label = 'Navigation',
+  fermeture,
+  className,
+  children,
+  ...reste
+}: DrawerProps) {
+  const panneau = useRef<HTMLDivElement>(null)
+  useOverlay({ ouvert, onClose, panneau })
+  const fermer = useCallback(() => onClose(), [onClose])
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={label}
+      aria-hidden={!ouvert}
+      className={cx('zv-drawer', ouvert && 'zv-drawer--open', className)}
+      {...reste}
+    >
+      <div className="zv-scrim" onClick={fermer} aria-hidden="true" />
+      <div className="zv-drawer__panel" ref={panneau}>
+        {fermeture && <div className="zv-drawer__close">{fermeture}</div>}
+        {children}
+      </div>
+    </div>
+  )
+}
+
+/* ─── Modale ───────────────────────────────────────────────────────── */
+
+export interface ModalProps extends Omit<Div, 'title'> {
+  ouvert: boolean
+  onClose: () => void
+  titre?: ReactNode
+  /** Actions de tête, à droite du titre (la croix, en général). */
+  actions?: ReactNode
+  /** Pied d'actions. Il reste visible quand le corps défile — c'est tout
+   *  l'intérêt du plafond de hauteur. */
+  pied?: ReactNode
+  /** Modale destructive : le filet HAUT porte l'avertissement, pas un fond
+   *  rouge — une surface d'alerte pleine rendrait le texte pénible à lire. */
+  danger?: boolean
+  className?: string
+  children?: ReactNode
+}
+
+export function Modal({
+  ouvert,
+  onClose,
+  titre,
+  actions,
+  pied,
+  danger,
+  className,
+  children,
+  ...reste
+}: ModalProps) {
+  const panneau = useRef<HTMLDivElement>(null)
+  useOverlay({ ouvert, onClose, panneau })
+  const fermer = useCallback(() => onClose(), [onClose])
+
+  // Une modale fermée n'est pas rendue du tout : contrairement au tiroir, elle
+  // n'a pas d'animation d'entrée à préserver, et son contenu (un formulaire,
+  // le plus souvent) ne doit pas rester dans le DOM à l'état fantôme.
+  if (!ouvert) return null
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={typeof titre === 'string' ? titre : undefined}
+      className={cx('zv-modal', 'zv-modal--open', danger && 'zv-modal--danger', className)}
+      {...reste}
+    >
+      <div className="zv-scrim" onClick={fermer} aria-hidden="true" />
+      <div className="zv-modal__panel" ref={panneau}>
+        {(titre || actions) && (
+          <div className="zv-modal__head">
+            {titre && <h2 className="zv-modal__title">{titre}</h2>}
+            {actions}
+          </div>
+        )}
+        <div className="zv-modal__body">{children}</div>
+        {pied && <div className="zv-modal__foot">{pied}</div>}
+      </div>
+    </div>
+  )
+}
+
+/* ─── Notification flottante ───────────────────────────────────────── */
+
+/** Le conteneur ne capte RIEN : seules les notifications le font, sans quoi
+ *  une colonne invisible bloquerait les clics dans tout le coin de l'écran. */
+export function Toasts({ className, ...reste }: Div & { className?: string }) {
+  return (
+    <div
+      className={cx('zv-toasts', className)}
+      role="region"
+      aria-live="polite"
+      {...reste}
+    />
+  )
+}
+
+export interface ToastProps extends Div {
+  ton?: 'ok' | 'err'
+  className?: string
+}
+
+/** ⚠️ Ne remplace PAS `Alert` : une erreur de formulaire se dit à côté du
+ *  champ, jamais dans un coin qui disparaît. Réserver ce composant à ce qui
+ *  est vrai APRÈS COUP — « copié », « enregistré », « envoyé ». */
+export function Toast({ ton, className, ...reste }: ToastProps) {
+  return <div className={cx('zv-toast', ton && `zv-toast--${ton}`, className)} {...reste} />
+}

package/react/surfaces.tsx

@@ -0,0 +1,161 @@
+// Surfaces — halos, sols quadrillés, voiles de fondu, bandeau manifeste,
+// glyphes. C'est ce qui distingue une page Zevra d'une page blanche bien
+// composée.
+//
+// ⚠️ TOUT est DÉCORATIF : posé en absolu derrière le contenu, sans capter le
+// pointeur, et masqué aux lecteurs d'écran. Ces composants posent
+// `aria-hidden` eux-mêmes — ne pas y mettre de texte à lire.
+//
+// ⚠️ Tous supposent un parent `position: relative; overflow: hidden`. Sans le
+// second, un halo de 1400px de large fait déborder la page.
+
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cx } from './cx.js'
+
+type Div = Omit<HTMLAttributes<HTMLDivElement>, 'className'>
+
+/* ─── Halo ambiant ─────────────────────────────────────────────────── */
+
+/** Le violet et le cyan du spectre, très dilués. Ce n'est PAS un emploi du
+ *  spectre en aplat : c'est une lumière — elle ne compte pas dans les trois
+ *  emplois autorisés. */
+export function Halo({
+  place,
+  className,
+  ...reste
+}: Div & { place: 'hero' | 'cta' | 'core'; className?: string }) {
+  return (
+    <div
+      aria-hidden="true"
+      className={cx('zv-halo', `zv-halo--${place}`, className)}
+      {...reste}
+    />
+  )
+}
+
+/* ─── Sol quadrillé ────────────────────────────────────────────────── */
+
+export function GridFloor({
+  carte,
+  className,
+  ...reste
+}: Div & { carte?: boolean; className?: string }) {
+  return (
+    <div
+      aria-hidden="true"
+      className={cx('zv-grid-floor', carte && 'zv-grid-floor--card', className)}
+      {...reste}
+    />
+  )
+}
+
+/* ─── Voile de fondu ───────────────────────────────────────────────── */
+
+/** Éteint le bas d'une scène pour que le texte qui la suit reste lisible.
+ *  `blanc` quand la page est blanche sous la scène. */
+export function Fade({
+  blanc,
+  className,
+  ...reste
+}: Div & { blanc?: boolean; className?: string }) {
+  return (
+    <div
+      aria-hidden="true"
+      className={cx('zv-fade', blanc && 'zv-fade--white', className)}
+      {...reste}
+    />
+  )
+}
+
+/* ─── Bandeau manifeste ────────────────────────────────────────────── */
+
+export interface BandProps extends Div {
+  /** Glyphe en filigrane, très dilué, dans un coin. */
+  filigrane?: ReactNode
+  /** Lueur d'accent derrière le contenu. */
+  lueur?: boolean
+  className?: string
+  children?: ReactNode
+}
+
+/** LA surface sombre du système. ⚠️ Les surfaces sombres se font avec elle et
+ *  `--accent-on-dark`, JAMAIS en inversant les neutres : les contrastes ont
+ *  été réglés dans ce sens-là et pas dans l'autre. */
+export function Band({ filigrane, lueur, className, children, ...reste }: BandProps) {
+  return (
+    <section className={cx('zv-band', className)} {...reste}>
+      {lueur && <div className="zv-band__glow" aria-hidden="true" />}
+      {filigrane && (
+        <div className="zv-band__watermark" aria-hidden="true">
+          {filigrane}
+        </div>
+      )}
+      <div className="zv-band__content">{children}</div>
+    </section>
+  )
+}
+
+/** Panneau sombre plus petit qu'une bande : une carte, un encart. */
+export function PanelNavy({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-panel-navy', className)} {...reste} />
+}
+
+/** Repeint un texte pour une surface sombre. `Band` le fait déjà pour son
+ *  contenu courant — cette classe sert aux cas isolés. */
+export function TextOnDark({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-text-on-dark', className)} {...reste} />
+}
+
+/* ─── Glyphes ──────────────────────────────────────────────────────── */
+
+export interface GlyphProps extends Div {
+  /** `deep` accentue l'ombre portée, `watermark` dilue le glyphe jusqu'au
+   *  filigrane. */
+  variante?: 'deep' | 'watermark'
+  className?: string
+  children?: ReactNode
+}
+
+/** Enveloppe d'un logo de produit posé comme motif. Le glyphe lui-même est
+ *  une image du paquet (`@zevra/ui/logos/…`), pas un tracé du CSS. */
+export function Glyph({ variante, className, children, ...reste }: GlyphProps) {
+  return (
+    <div
+      aria-hidden="true"
+      className={cx('zv-glyph', variante && `zv-glyph--${variante}`, className)}
+      {...reste}
+    >
+      {children}
+    </div>
+  )
+}
+
+/* ─── Mouvement ────────────────────────────────────────────────────── */
+
+export type Animation =
+  | 'rise'
+  | 'pop'
+  | 'filet'
+  | 'glyph-in'
+  | 'converge'
+  | 'breathe'
+  | 'drift'
+  | 'dot-active'
+  | 'progress'
+
+/** Les neuf animations du paquet, nommées. ⚠️ Elles sont pilotées AU
+ *  DÉFILEMENT et réservées à la vitrine : le chrome applicatif n'anime rien.
+ *  `prefers-reduced-motion` les coupe toutes, globalement, depuis base.css.
+ *
+ *  `option` échelonne les entrées d'une même rangée (`pop`, rangs 2 à 6) ou
+ *  donne le coin d'arrivée (`converge` : tr, bl, br — le défaut vient du
+ *  haut-gauche). Passée à une autre animation, elle est ignorée. */
+export function anim(
+  nom: Animation,
+  option?: 2 | 3 | 4 | 5 | 6 | 'tr' | 'bl' | 'br',
+): string {
+  if (nom === 'pop' && typeof option === 'number') return `zv-anim-pop zv-anim-pop--${option}`
+  if (nom === 'converge' && typeof option === 'string')
+    return `zv-anim-converge zv-anim-converge--${option}`
+  return `zv-anim-${nom}`
+}

package/react/typography.tsx

@@ -0,0 +1,220 @@
+// Typographie — titres, corps, kickers, labels mono, filets.
+//
+// La HIÉRARCHIE VISUELLE et le NIVEAU SÉMANTIQUE sont deux choses : une page
+// n'a qu'un <h1>, mais elle peut avoir plusieurs blocs à la taille du h1.
+// D'où `as` sur les titres — la taille est un choix de mise en page, la
+// balise un choix de structure. Les confondre casse le plan du document pour
+// un lecteur d'écran sans que rien ne se voie à l'écran.
+
+import type { ElementType, HTMLAttributes, ReactNode } from 'react'
+import { cx } from './cx.js'
+
+type Div = Omit<HTMLAttributes<HTMLElement>, 'className'>
+type Span = Omit<HTMLAttributes<HTMLSpanElement>, 'className'>
+
+/* ─── Titres ───────────────────────────────────────────────────────── */
+
+export type TitreTaille = 'h1' | 'h2' | 'h2-sm' | 'h2-cta' | 'h3' | 'carte'
+
+const CLASSE_TITRE: Record<TitreTaille, string> = {
+  h1: 'zv-h1',
+  h2: 'zv-h2',
+  'h2-sm': 'zv-h2 zv-h2--sm',
+  'h2-cta': 'zv-h2 zv-h2--cta',
+  h3: 'zv-h3',
+  carte: 'zv-card-title',
+}
+
+export interface HeadingProps extends Div {
+  taille?: TitreTaille
+  /** Balise réellement rendue. Par défaut, celle qui correspond à la taille. */
+  as?: ElementType
+  className?: string
+  children?: ReactNode
+}
+
+const BALISE_PAR_DEFAUT: Record<TitreTaille, ElementType> = {
+  h1: 'h1',
+  h2: 'h2',
+  'h2-sm': 'h2',
+  'h2-cta': 'h2',
+  h3: 'h3',
+  carte: 'h3',
+}
+
+export function Heading({ taille = 'h2', as, className, ...reste }: HeadingProps) {
+  const Balise = as ?? BALISE_PAR_DEFAUT[taille]
+  return <Balise className={cx(CLASSE_TITRE[taille], className)} {...reste} />
+}
+
+export const H1 = (p: Omit<HeadingProps, 'taille'>) => <Heading taille="h1" {...p} />
+export const H2 = (p: Omit<HeadingProps, 'taille'>) => <Heading taille="h2" {...p} />
+export const H3 = (p: Omit<HeadingProps, 'taille'>) => <Heading taille="h3" {...p} />
+export const CardTitle = (p: Omit<HeadingProps, 'taille'>) => (
+  <Heading taille="carte" {...p} />
+)
+
+/** Chiffre ou mot posé pour sa PRÉSENCE, hors de la hiérarchie des titres —
+ *  d'où le `<div>` : un chiffre géant annoncé comme titre de section pollue
+ *  le plan du document. */
+export function Display({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-display', className)} {...reste} />
+}
+
+/* ─── Corps ────────────────────────────────────────────────────────── */
+
+export interface BodyProps extends Div {
+  taille?: 'normal' | 'lg' | 'dense'
+  as?: ElementType
+  className?: string
+  children?: ReactNode
+}
+
+export function Body({ taille = 'normal', as, className, ...reste }: BodyProps) {
+  const Balise = as ?? 'p'
+  return (
+    <Balise
+      className={cx(
+        'zv-body',
+        taille === 'lg' && 'zv-body--lg',
+        taille === 'dense' && 'zv-body--dense',
+        className,
+      )}
+      {...reste}
+    />
+  )
+}
+
+/** Chapô : le paragraphe qui suit immédiatement un titre de section. */
+export function Lead({
+  as,
+  className,
+  ...reste
+}: Div & { as?: ElementType; className?: string }) {
+  const Balise = as ?? 'p'
+  return <Balise className={cx('zv-lead', className)} {...reste} />
+}
+
+/** Mention légale, précision de bas de bloc. */
+export function Note({
+  as,
+  className,
+  ...reste
+}: Div & { as?: ElementType; className?: string }) {
+  const Balise = as ?? 'p'
+  return <Balise className={cx('zv-note', className)} {...reste} />
+}
+
+/** Signature de marque, sous un logo. */
+export function Tagline({ className, ...reste }: Span & { className?: string }) {
+  return <span className={cx('zv-tagline', className)} {...reste} />
+}
+
+/** Mise en valeur dans le fil du texte. Le pendant `surSombre` existe parce
+ *  que l'indigo d'accent devient illisible sur la bande manifeste. */
+export function Em({
+  surSombre,
+  className,
+  ...reste
+}: Span & { surSombre?: boolean; className?: string }) {
+  return (
+    <em className={cx('zv-em', surSombre && 'zv-em--on-dark', className)} {...reste} />
+  )
+}
+
+export function Link({
+  className,
+  ...reste
+}: Omit<HTMLAttributes<HTMLAnchorElement>, 'className'> & {
+  className?: string
+  href?: string
+}) {
+  return <a className={cx('zv-link', className)} {...reste} />
+}
+
+/* ─── Kicker et filet de signature ─────────────────────────────────── */
+
+export interface KickerProps extends Div {
+  /** `center` centre le bloc, `stack` empile le filet AU-DESSUS du texte au
+   *  lieu de le poser devant. */
+  variante?: 'center' | 'stack'
+  /** Le filet de spectre 56×2 devant le kicker. Premier des trois emplois
+   *  autorisés du spectre. */
+  filet?: boolean
+  surSombre?: boolean
+  className?: string
+  children?: ReactNode
+}
+
+export function Kicker({
+  variante,
+  filet = true,
+  surSombre,
+  className,
+  children,
+  ...reste
+}: KickerProps) {
+  return (
+    <div
+      className={cx('zv-kicker', variante && `zv-kicker--${variante}`, className)}
+      {...reste}
+    >
+      {filet && <Spec surSombre={surSombre} />}
+      {children}
+    </div>
+  )
+}
+
+/** Le filet de spectre seul. Décoratif : masqué aux lecteurs d'écran. */
+export function Spec({
+  petit,
+  surSombre,
+  className,
+  ...reste
+}: Span & { petit?: boolean; surSombre?: boolean; className?: string }) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cx(
+        'zv-spec',
+        petit && 'zv-spec--sm',
+        surSombre && 'zv-spec--on-dark',
+        className,
+      )}
+      {...reste}
+    />
+  )
+}
+
+/** Filet neutre de séparation de section. */
+export function Rule({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-rule', className)} {...reste} />
+}
+
+/* ─── Label mono ───────────────────────────────────────────────────── */
+
+export interface MonoProps extends Span {
+  /** Le ton, pas la taille : `label` est le gris d'intitulé, `ink` l'encre
+   *  pleine, `muted` le gris secondaire, `on-dark` la bande manifeste. */
+  ton?: 'label' | 'ink' | 'muted' | 'on-dark'
+  /** Le plus petit palier — badge dense, compteur de coque. */
+  micro?: boolean
+  className?: string
+}
+
+/** Capitales espacées. ⚠️ Réservé aux LIBELLÉS : une date ou un nom de
+ *  fichier passés en capitales espacées deviennent illisibles et s'alignent
+ *  mal — pour ceux-là, c'est `Meta` (bas de casse, chasse tabulaire). */
+export function Mono({ ton, micro, className, ...reste }: MonoProps) {
+  return (
+    <span
+      className={cx(
+        'zv-mono',
+        ton && `zv-mono--${ton}`,
+        micro && 'zv-mono--micro',
+        className,
+      )}
+      {...reste}
+    />
+  )
+}