@zevra/ui 0.15.0 → 0.16.0

package/react/layout.tsx

@@ -354,6 +354,59 @@ export function LockupWord({
   return <img alt={alt} className={cx('zv-lockup__word', className)} {...reste} />
 }
 
+/* ─── Rail de lecture ──────────────────────────────────────────────── */
+
+/** La table des matières d'une page longue, posée sur le côté. Elle navigue
+ *  (chaque entrée est une ancre) et elle suit — poser `data-zv-rail` et
+ *  importer `@zevra/ui/rail.js` pour que l'entrée courante s'allume. Sans le
+ *  module, le rail navigue toujours : rien ne casse, le suivi manque.
+ *
+ *  ⚠️ Elle demande de la place à côté du texte, et disparaît sous le point
+ *  de rupture : un rail fixe sur un téléphone se pose sur la lecture. */
+export function Rail({
+  gauche,
+  className,
+  ...reste
+}: Omit<HTMLAttributes<HTMLElement>, 'className'> & {
+  gauche?: boolean
+  className?: string
+  'aria-label': string
+}) {
+  return (
+    <nav
+      data-zv-rail
+      className={cx('zv-rail zv-layer-chrome', gauche && 'zv-rail--gauche', className)}
+      {...reste}
+    />
+  )
+}
+
+/** ⚠️ `href` doit désigner une ancre de la page (`#section`) : c'est elle
+ *  que le module surveille, et c'est le balisage qui fait foi — il n'y a
+ *  pas de liste de sections à tenir à jour ailleurs. */
+export function RailItem({
+  courant,
+  className,
+  children,
+  ...reste
+}: Omit<HTMLAttributes<HTMLAnchorElement>, 'className'> & {
+  courant?: boolean
+  href: string
+  className?: string
+  children?: ReactNode
+}) {
+  return (
+    <a
+      aria-current={courant ? 'true' : undefined}
+      className={cx('zv-rail__item', courant && 'zv-rail__item--on', className)}
+      {...reste}
+    >
+      <span className="zv-mono zv-mono--micro">{children}</span>
+      <span className="zv-rail__dot" aria-hidden="true" />
+    </a>
+  )
+}
+
 /* ─── Frise d'étapes ───────────────────────────────────────────────── */
 
 export interface StepsProps extends Div {

package/src/layout.css

@@ -313,88 +313,6 @@
   color: var(--label);
 }
 
-/* ─── Entrées à menu déroulant ──────────────────────────────────────────
- *
- * Une nav de vitrine qui porte l'architecture d'un site — des familles,
- * pas quatre liens — a besoin de déplier. Ouverture au survol ET au focus
- * (`:focus-within`) : en CSS seul, donc accessible au clavier sans une
- * ligne de JavaScript et sans état à tenir.
- *
- * Le panneau est le .zv-menu du paquet, simplement ancré sous l'entrée. */
-
-.zv-navdd {
-  position: relative;
-  display: inline-flex;
-}
-
-/* Le bouton porte .zv-navlink : il doit se rendre EXACTEMENT comme un lien
- * simple de la barre. Piège à éviter — un `font: inherit`, réflexe habituel
- * pour dénuder un bouton, remet la fonte du CONTENEUR (16px/400) là où
- * .zv-navlink pose 14px/500 : les entrées à menu deviennent plus grosses
- * que les autres. On ne reprend donc du bouton que ce qui doit disparaître. */
-.zv-navdd__btn {
-  display: inline-flex;
-  align-items: center;
-  gap: 5px;
-  padding: 0;
-  border: 0;
-  background: none;
-  cursor: pointer;
-  font-family: inherit;
-  line-height: inherit;
-}
-
-.zv-navdd__chevron {
-  width: 12px;
-  height: 12px;
-  fill: none;
-  stroke: currentColor;
-  stroke-width: 2;
-  /* Bouts francs : le trait carré du jeu d'icônes (25/08/2026). */
-  stroke-linecap: square;
-  stroke-linejoin: miter;
-  transition: transform 160ms var(--zv-easing, cubic-bezier(0.2, 0.7, 0.2, 1));
-}
-
-.zv-navdd:hover .zv-navdd__chevron,
-.zv-navdd:focus-within .zv-navdd__chevron {
-  transform: rotate(180deg);
-}
-
-/* Le pont invisible (::before) couvre l'interstice entre l'entrée et son
- * panneau : sans lui, le survol se rompt en descendant vers le menu et le
- * menu se referme sous le curseur. */
-.zv-navdd__menu {
-  position: absolute;
-  top: 100%;
-  left: 50%;
-  translate: -50% 0;
-  padding-top: 14px;
-  display: none;
-  min-width: 250px;
-  z-index: 50;
-}
-
-.zv-navdd__menu::before {
-  content: '';
-  position: absolute;
-  inset: 0 0 auto 0;
-  height: 14px;
-}
-
-.zv-navdd:hover .zv-navdd__menu,
-.zv-navdd:focus-within .zv-navdd__menu {
-  display: flex;
-  flex-direction: column;
-}
-
-.zv-navdd__sep {
-  display: block;
-  height: 1px;
-  margin: 6px 0;
-  background: var(--hairline);
-}
-
 /* ─── Sélecteur de langue ───────────────────────────────────────────────
  * Des initiales au registre mono, pas un menu : trois langues se lisent
  * d'un coup d'œil, et un menu pour trois entrées coûte un clic pour rien.
@@ -877,6 +795,107 @@
   }
 }
 
+/* ─── Rail de lecture ───────────────────────────────────────────────────
+ *
+ * La table des matières d'une page longue, posée sur le côté : un libellé,
+ * un point, et le point courant qui s'allume. Elle NAVIGUE (chaque entrée
+ * est une ancre) et elle SUIT (le module rail.js marque la section en
+ * cours) — les deux, sinon ce n'est qu'un décor qui occupe la marge.
+ *
+ * ⚠️ Elle demande de la place à côté du texte. Sous le point de rupture
+ * elle disparaît : un rail fixe sur un téléphone se pose sur la lecture.
+ * Au-dessus, c'est la mesure de la page qui décide — une page dont le
+ * contenu court d'un bord à l'autre jusqu'à 1100px gagnera à relever le
+ * seuil chez elle.
+ *
+ * L'empilement vient de .zv-layer-chrome, à poser avec : le rail est du
+ * chrome, il passe au-dessus des décors de scène. */
+
+.zv-rail {
+  position: fixed;
+  right: 40px;
+  top: 50%;
+  translate: 0 -50%;
+  display: none;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 16px;
+}
+
+@media (min-width: 768px) {
+  .zv-rail {
+    display: flex;
+  }
+}
+
+/* Sur la gauche, l'ordre s'inverse : le point précède le libellé, sinon il
+ * se retrouve au milieu de la colonne au lieu d'en tenir le bord. */
+.zv-rail--gauche {
+  right: auto;
+  left: 40px;
+  align-items: flex-start;
+}
+
+.zv-rail--gauche .zv-rail__item {
+  flex-direction: row-reverse;
+}
+
+.zv-rail__item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 3px 0;
+  color: var(--muted);
+  text-decoration: none;
+  /* Un rail flotte au-dessus de ce que la page met dans sa marge : un
+   * libellé gris pâle sur un décor pâle devient illisible par manque de
+   * contraste, sans qu'aucun empilement soit en cause. Le halo couleur
+   * papier le détache de tout ce qui passe dessous, sans lui donner de
+   * cadre. */
+  text-shadow:
+    0 0 6px var(--paper),
+    0 0 12px var(--paper);
+  transition: color 160ms var(--zv-easing, cubic-bezier(0.2, 0.7, 0.2, 1));
+}
+
+/* Le libellé est posé au registre mono par l'appelant : il doit suivre la
+ * couleur de son entrée, pas garder la sienne. */
+.zv-rail__item .zv-mono {
+  color: inherit;
+}
+
+.zv-rail__item:hover {
+  color: var(--accent-deep);
+}
+
+.zv-rail__dot {
+  width: 8px;
+  height: 8px;
+  flex: none;
+  border-radius: 50%;
+  background: var(--accent-line);
+  transition:
+    background 160ms var(--zv-easing, cubic-bezier(0.2, 0.7, 0.2, 1)),
+    scale 160ms var(--zv-easing, cubic-bezier(0.2, 0.7, 0.2, 1));
+}
+
+.zv-rail__item:hover .zv-rail__dot {
+  background: var(--accent);
+  scale: 1.35;
+}
+
+/* L'entrée courante, posée par rail.js. Le halo du point est le seul
+ * signal dont une navigation discrète a besoin — pas de fond, pas de
+ * filet. */
+.zv-rail__item--on {
+  color: var(--accent-deep);
+}
+
+.zv-rail__item--on .zv-rail__dot {
+  background: var(--iris);
+  box-shadow: 0 0 0 4px color-mix(in srgb, var(--iris) 18%, transparent);
+}
+
 /* ─── Le seuil d'une nav riche ──────────────────────────────────────────
  *
  * La bascule vers le tiroir est à 767px, réglée sur la nav de référence :

package/src/navigation.css

@@ -496,6 +496,95 @@
  * clic extérieur, fermeture à Échap. Le CSS ci-dessus est prêt à les recevoir
  * (aria-selected, :focus-visible) ; le composant doit les écrire. */
 
+/* ─── Entrées à menu déroulant de la barre vitrine ──────────────────────
+ *
+ * ⚠️ CE BLOC DOIT RESTER APRÈS `.zv-menu`, et donc dans CE fichier. Le
+ * panneau d'une entrée porte les deux classes ; `.zv-navdd__menu` reprend à
+ * `.zv-menu` son display, sa position et son ancrage, à spécificité égale —
+ * c'est l'ORDRE qui tranche. Posé dans layout.css, qu'index.css importe
+ * AVANT navigation.css, il perdait : les trois menus d'une barre
+ * s'affichaient en même temps, ouverts en permanence.
+ *
+ * Une nav de vitrine qui porte l'architecture d'un site — des familles,
+ * pas quatre liens — a besoin de déplier. Ouverture au survol ET au focus
+ * (`:focus-within`) : en CSS seul, donc accessible au clavier sans une
+ * ligne de JavaScript et sans état à tenir.
+ *
+ * Le panneau est le .zv-menu du paquet, simplement ancré sous l'entrée. */
+
+.zv-navdd {
+  position: relative;
+  display: inline-flex;
+}
+
+/* Le bouton porte .zv-navlink : il doit se rendre EXACTEMENT comme un lien
+ * simple de la barre. Piège à éviter — un `font: inherit`, réflexe habituel
+ * pour dénuder un bouton, remet la fonte du CONTENEUR (16px/400) là où
+ * .zv-navlink pose 14px/500 : les entrées à menu deviennent plus grosses
+ * que les autres. On ne reprend donc du bouton que ce qui doit disparaître. */
+.zv-navdd__btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 0;
+  border: 0;
+  background: none;
+  cursor: pointer;
+  font-family: inherit;
+  line-height: inherit;
+}
+
+.zv-navdd__chevron {
+  width: 12px;
+  height: 12px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  /* Bouts francs : le trait carré du jeu d'icônes (25/08/2026). */
+  stroke-linecap: square;
+  stroke-linejoin: miter;
+  transition: transform 160ms var(--zv-easing, cubic-bezier(0.2, 0.7, 0.2, 1));
+}
+
+.zv-navdd:hover .zv-navdd__chevron,
+.zv-navdd:focus-within .zv-navdd__chevron {
+  transform: rotate(180deg);
+}
+
+/* Le pont invisible (::before) couvre l'interstice entre l'entrée et son
+ * panneau : sans lui, le survol se rompt en descendant vers le menu et le
+ * menu se referme sous le curseur. */
+.zv-navdd__menu {
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  translate: -50% 0;
+  padding-top: 14px;
+  display: none;
+  min-width: 250px;
+  z-index: 50;
+}
+
+.zv-navdd__menu::before {
+  content: '';
+  position: absolute;
+  inset: 0 0 auto 0;
+  height: 14px;
+}
+
+.zv-navdd:hover .zv-navdd__menu,
+.zv-navdd:focus-within .zv-navdd__menu {
+  display: flex;
+  flex-direction: column;
+}
+
+.zv-navdd__sep {
+  display: block;
+  height: 1px;
+  margin: 6px 0;
+  background: var(--hairline);
+}
+
 /* ─── Popover ───────────────────────────────────────────────────────────
  * HORS RELEVÉ (25/08/2026, voir DECISIONS.md). Le menu impose ses items ;
  * il n'existait aucune surface ancrée LIBRE — aide contextuelle,

package/src/rail.js

@@ -0,0 +1,94 @@
+/* Zevra UI — rail.js : le rail de lecture suit la section en cours.
+ *
+ * Rôle exact, et rien d'autre : poser `.zv-rail__item--on` et
+ * `aria-current` sur l'entrée dont la section est à l'écran. La navigation
+ * elle-même est du HTML — chaque entrée est une ancre, et elle fonctionne
+ * sans ce module.
+ *
+ * Le contrat, en un attribut :
+ *   [data-zv-rail]   le rail (.zv-rail). Ses entrées sont ses <a href="#…">,
+ *                    et chaque href désigne la cible à surveiller.
+ *
+ * Rien à déclarer d'autre : l'ordre des entrées, leurs cibles et leur
+ * nombre se lisent dans le balisage. Un rail dont une ancre ne résout pas
+ * garde l'entrée cliquable et l'ignore au suivi, plutôt que de décaler
+ * tout le reste — c'est le décalage silencieux qui coûte cher.
+ *
+ * ─── Pourquoi pas un IntersectionObserver ───────────────────────────────
+ * Parce que les ancres d'un rail sont souvent des points MATÉRIELS de 1px
+ * posés en tête de section. Réduit à sa bande centrale, l'observateur ne
+ * les voit traverser que pendant quelques images — un défilement rapide
+ * saute la bande entière et l'entrée ne s'allume jamais. On lit donc la
+ * position : l'entrée courante est la DERNIÈRE dont l'ancre a passé la
+ * ligne de lecture. C'est déterministe, quelle que soit la vitesse.
+ *
+ * S'importe une fois par page : `import '@zevra/ui/rail.js'`. Sans lui, le
+ * rail navigue mais ne suit pas — dégradation douce, pas de page cassée.
+ */
+(() => {
+  if (typeof document === 'undefined') return
+  if (document.documentElement.dataset.zvRail === 'on') return
+  document.documentElement.dataset.zvRail = 'on'
+
+  /** Hauteur de la ligne de lecture, en fraction du viewport. 45 % : un peu
+   *  au-dessus du milieu, là où l'œil se pose vraiment. */
+  const LIGNE = 0.45
+
+  const rails = () => Array.from(document.querySelectorAll('[data-zv-rail]'))
+
+  const suivre = (rail) => {
+    const entrees = Array.from(rail.querySelectorAll('a[href^="#"]'))
+    if (!entrees.length) return
+
+    const cibles = entrees.map((a) => {
+      const id = decodeURIComponent(a.getAttribute('href').slice(1))
+      return id ? document.getElementById(id) : null
+    })
+    if (!cibles.some(Boolean)) return
+
+    let courant = -1
+    const marquer = (i) => {
+      if (i === courant) return
+      courant = i
+      entrees.forEach((a, k) => {
+        a.classList.toggle('zv-rail__item--on', k === i)
+        if (k === i) a.setAttribute('aria-current', 'true')
+        else a.removeAttribute('aria-current')
+      })
+    }
+
+    const relire = () => {
+      const ligne = window.innerHeight * LIGNE
+      let actif = 0
+      for (let i = 0; i < cibles.length; i++) {
+        const c = cibles[i]
+        if (c && c.getBoundingClientRect().top <= ligne) actif = i
+      }
+      marquer(actif)
+    }
+
+    // Une lecture par image au plus : le défilement émet bien plus souvent
+    // que l'écran ne se rafraîchit, et chaque lecture coûte un reflow.
+    let prevu = false
+    const planifier = () => {
+      if (prevu) return
+      prevu = true
+      requestAnimationFrame(() => {
+        prevu = false
+        relire()
+      })
+    }
+
+    addEventListener('scroll', planifier, { passive: true })
+    addEventListener('resize', planifier, { passive: true })
+    relire()
+  }
+
+  const demarrer = () => rails().forEach(suivre)
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', demarrer, { once: true })
+  } else {
+    demarrer()
+  }
+})()