@zevra/ui 0.38.1 → 0.39.1

package/react/overlays.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-// Enrobages : voile, tiroir, modale, notification flottante.
+// Enrobages : voile, tiroir, volet, 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
@@ -40,6 +40,19 @@ export function useOverlay({ ouvert, onClose, panneau, verrouille = true }: UseO
   // utilisateur au clavier perd sa place dans la page.
   const origine = useRef<HTMLElement | null>(null)
 
+  // ⚠️ `onClose` NE FIGURE PAS dans les dépendances de l'effet, et ce n'est pas
+  // un oubli. L'effet ne se contente pas d'écouter Échap : il mémorise le
+  // nœud focalisé, verrouille le défilement et donne le focus au premier
+  // élément du panneau. Le rejouer, ce n'est donc pas re-souscrire, c'est
+  // ROUVRIR l'enrobage. Or `onClose` est presque toujours une fonction
+  // anonyme, recréée à chaque rendu du parent : le focus repartait sur le
+  // premier bouton du panneau à chaque rendu de la page derrière, et un champ
+  // qui s'enregistre tout seul devenait impossible à remplir (la note d'une
+  // pièce dans Tésope, 30/09/2026). L'effet lit ici la dernière fonction
+  // connue ; ses dépendances ne portent que l'état.
+  const fermer = useRef(onClose)
+  fermer.current = onClose
+
   useEffect(() => {
     if (!ouvert) return
     const cible = panneau?.current
@@ -62,7 +75,7 @@ export function useOverlay({ ouvert, onClose, panneau, verrouille = true }: UseO
     function onKey(e: KeyboardEvent) {
       if (e.key === 'Escape') {
         e.stopPropagation()
-        onClose()
+        fermer.current()
         return
       }
       if (e.key !== 'Tab' || !cible) return
@@ -89,7 +102,7 @@ export function useOverlay({ ouvert, onClose, panneau, verrouille = true }: UseO
       if (overflowPrecedent !== null) docu.body.style.overflow = overflowPrecedent
       origine.current?.focus?.()
     }
-  }, [ouvert, onClose, panneau, verrouille])
+  }, [ouvert, panneau, verrouille])
 }
 
 /* ─── Voile ────────────────────────────────────────────────────────── */
@@ -209,6 +222,84 @@ export function Modal({
   )
 }
 
+/* ─── Volet ────────────────────────────────────────────────────────── */
+
+export interface VoletProps extends Omit<Div, 'title'> {
+  ouvert: boolean
+  onClose: () => void
+  titre?: ReactNode
+  /** Nom du dialogue quand le titre n'est pas une chaîne. */
+  label?: string
+  /** Actions de tête, à droite du titre (la croix, en général). */
+  actions?: ReactNode
+  /** Pied d'actions, fixe quand le corps défile. */
+  pied?: ReactNode
+  /** `normale` pour une fiche, `large` pour un document à lire. */
+  largeur?: 'normale' | 'large'
+  /** Vrai par défaut : dialogue modal, page voilée et figée. Faux : la page
+   *  reste utilisable derrière (passer d'une pièce à l'autre d'une liste sans
+   *  refermer). Échap ferme dans les deux cas. */
+  voile?: boolean
+  /** `nu` : corps sans marge, pour un document bord à bord (PDF, image). */
+  corps?: 'normal' | 'nu'
+  className?: string
+  children?: ReactNode
+}
+
+/** Panneau latéral DROIT, à toutes les largeurs : un contenu qu'on consulte
+ *  à côté d'une liste (un document, une fiche). Ne remplace ni le tiroir,
+ *  qui est la navigation mobile, ni la modale, qui interrompt pour une
+ *  décision. Reste monté fermé, comme le tiroir, pour glisser dehors. */
+export function Volet({
+  ouvert,
+  onClose,
+  titre,
+  label,
+  actions,
+  pied,
+  largeur = 'normale',
+  voile = true,
+  corps = 'normal',
+  className,
+  children,
+  ...reste
+}: VoletProps) {
+  const panneau = useRef<HTMLDivElement>(null)
+  // Sans voile, la page reste à l'utilisateur : ni verrou de défilement, ni
+  // piège de focus (Tab doit pouvoir revenir à la liste). Échap ferme.
+  useOverlay({ ouvert, onClose, panneau: voile ? panneau : undefined, verrouille: voile })
+  const fermer = useCallback(() => onClose(), [onClose])
+
+  return (
+    <div
+      role="dialog"
+      aria-modal={voile ? 'true' : undefined}
+      aria-label={label ?? (typeof titre === 'string' ? titre : undefined)}
+      aria-hidden={!ouvert}
+      className={cx(
+        'zv-volet',
+        ouvert && 'zv-volet--open',
+        largeur === 'large' && 'zv-volet--large',
+        !voile && 'zv-volet--sans-voile',
+        className,
+      )}
+      {...reste}
+    >
+      {voile && <div className="zv-scrim" onClick={fermer} aria-hidden="true" />}
+      <div className="zv-volet__panel" ref={panneau}>
+        {(titre || actions) && (
+          <div className="zv-volet__head">
+            {titre && <h2 className="zv-volet__title">{titre}</h2>}
+            {actions && <div className="zv-volet__actions">{actions}</div>}
+          </div>
+        )}
+        <div className={cx('zv-volet__body', corps === 'nu' && 'zv-volet__body--nu')}>{children}</div>
+        {pied && <div className="zv-volet__foot">{pied}</div>}
+      </div>
+    </div>
+  )
+}
+
 /* ─── Notification flottante ───────────────────────────────────────── */
 
 /** Le conteneur ne capte RIEN : seules les notifications le font, sans quoi

package/src/overlays.css

@@ -12,7 +12,8 @@
  * l'échappement au clavier est du ressort du gabarit, que le CSS ne peut pas
  * assurer seul.
  *
- * Empilement, dans l'ordre : voile 60, tiroir 80, modale 90, notification 100.
+ * Empilement, dans l'ordre : voile 60, tiroir 80, volet 85, modale 90,
+ * notification 100.
  * Les couches inférieures (2, 5, 40, 50) sont dans layout.css.
  *
  * OUVERTURE, deux écritures équivalentes, au choix du gabarit :
@@ -51,7 +52,8 @@
 html:has(.zv-drawer[data-open]),
 html:has(.zv-drawer--open),
 html:has(.zv-modal[data-open]),
-html:has(.zv-modal--open) {
+html:has(.zv-modal--open),
+html:has(.zv-volet--open:not(.zv-volet--sans-voile)) {
   overflow: hidden;
 }
 
@@ -255,6 +257,135 @@ html:has(.zv-modal--open) {
   border-top: 3px solid var(--err);
 }
 
+/* ─── Volet ─────────────────────────────────────────────────────────────
+ * ⚠️ HORS RELEVÉ (DECISIONS.md, 26/09/2026). Panneau latéral DROIT, à toutes
+ * les largeurs : il porte un contenu (un document, une fiche) qu'on consulte
+ * à côté d'une liste. Dérivé du tiroir (le glissement, le voile) et de la
+ * modale (tête, corps qui défile, pied fixe) ; seules ses deux largeurs sont
+ * nouvelles.
+ *
+ * Empilement 85 : devant le tiroir (80), derrière la modale (90), pour
+ * qu'une confirmation ouverte depuis le volet passe devant lui.
+ *
+ * Sans voile (`zv-volet--sans-voile`), le conteneur ne capte rien : seul le
+ * panneau reçoit les clics, et la page reste utilisable derrière. */
+
+.zv-volet {
+  --zv-volet-largeur: min(560px, 92vw);
+  position: fixed;
+  inset: 0;
+  z-index: 85;
+  /* `visibility` plutôt que `display`, comme le tiroir : le panneau reste
+   * à l'écran le temps qu'il glisse dehors. */
+  visibility: hidden;
+  transition: visibility 200ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.zv-volet--large {
+  --zv-volet-largeur: min(960px, 96vw);
+}
+
+.zv-volet[data-open],
+.zv-volet--open {
+  visibility: visible;
+}
+
+.zv-volet--sans-voile {
+  pointer-events: none;
+}
+
+/* Le voile du volet existe à toutes les largeurs, comme celui de la modale. */
+.zv-volet .zv-scrim {
+  z-index: 0;
+  display: block;
+  opacity: 0;
+  transition: opacity 200ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.zv-volet[data-open] .zv-scrim,
+.zv-volet--open .zv-scrim {
+  opacity: 1;
+}
+
+.zv-volet__panel {
+  pointer-events: auto;
+  position: absolute;
+  z-index: 1;
+  inset-block: 0;
+  right: 0;
+  display: flex;
+  width: var(--zv-volet-largeur);
+  flex-direction: column;
+  border-left: 1px solid var(--line);
+  border-radius: 0;
+  background: var(--white);
+  box-shadow: var(--shadow-panel);
+  transform: translateX(100%);
+  transition: transform 200ms cubic-bezier(0, 0, 0.2, 1);
+}
+
+.zv-volet[data-open] .zv-volet__panel,
+.zv-volet--open .zv-volet__panel {
+  transform: translateX(0);
+}
+
+.zv-volet__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  border-bottom: 1px solid var(--hairline);
+  padding: 14px 18px;
+}
+
+.zv-volet__title {
+  min-width: 0;
+  margin: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-family: var(--font-display);
+  letter-spacing: -0.02em;
+  font-size: var(--app-h2);
+  font-weight: 400;
+  color: var(--ink);
+}
+
+.zv-volet__actions {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  gap: 6px;
+}
+
+/* Le corps seul défile : tête et pied restent, les actions ne sortent
+ * jamais de l'écran. */
+.zv-volet__body {
+  display: flex;
+  min-height: 0;
+  flex: 1;
+  flex-direction: column;
+  overflow: auto;
+  padding: 14px 18px;
+  font-size: var(--app);
+  line-height: 1.6;
+  color: var(--muted);
+}
+
+/* Un document qui doit aller bord à bord (PDF, image) : pas de marge. */
+.zv-volet__body--nu {
+  padding: 0;
+}
+
+.zv-volet__foot {
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+  border-top: 1px solid var(--hairline);
+  background: var(--white);
+  padding: 12px 18px;
+}
+
 /* ─── Notification flottante ────────────────────────────────────────────
  * ⚠️ HORS RELEVÉ, même raison : Mémoire signale tout en place, par une
  * alerte de bloc. Cette notification est l'alerte du module de retours,
@@ -318,6 +449,13 @@ html:has(.zv-modal--open) {
     display: block;
   }
 
+  /* Sous le seuil, le volet prend toute la largeur : une bande de page de
+   * 30 px à gauche ne sert à rien, le voile se ferme par Échap ou la croix. */
+  .zv-volet,
+  .zv-volet--large {
+    --zv-volet-largeur: 100vw;
+  }
+
   /* La notification prend la largeur : un coin de 380px sur un écran de 390
    * n'est plus un coin. */
   .zv-toasts {