fold-ng 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -8,6 +8,223 @@ All notable changes to **fold-ng** are documented here. The format follows
 
 _Nothing yet._
 
+## [0.17.0] - 2026-08-26
+
+### Added
+
+- **`fold-fieldset`** — le groupe NOMMÉ de contrôles : la paire
+  `<fieldset>`/`<legend>`, son habillage navigateur neutralisé et son rythme sur
+  l'échelle des tokens.
+
+  Il existe parce que la paire native est inutilisable telle quelle : chaque
+  appelant réécrit les six mêmes lignes pour la défaire (`margin: 0; padding: 0;
+border: 0`, puis flex + gap, puis `legend { padding: 0 }`). Ce reset avait été
+  écrit **cinq fois, au caractère près**, dans deux applications. Une répétition
+  aussi exacte n'est pas une coïncidence, c'est un composant manquant.
+
+  Ce n'est ni une carte ni une section : `fold-card` est une surface,
+  `fold-page-section` un chapitre de page ; ceci est le **groupement
+  accessible** des contrôles qui répondent à une seule question. C'est le
+  `<legend>` qui nomme le groupe à un lecteur d'écran — et c'est toute la raison
+  de prendre un `fieldset` plutôt qu'un `div` : un titre au-dessus d'un `div`
+  aurait exactement la même allure et n'annoncerait rien.
+
+  **Ce que l'élément natif achète, et que le composant garde** :
+
+  - `disabled` — le **super-pouvoir** du `fieldset`, que rien d'autre en HTML
+    n'a : il désactive TOUS les contrôles qu'il contient, en un attribut, sans
+    câblage par contrôle. (La première `<legend>` en est exemptée par la spec.)
+  - `hint` — l'instruction du groupe (« au moins un jour »), pointée par
+    `aria-describedby`. Un indice seulement peint est un indice que la moitié
+    des lecteurs n'aura jamais. `hintPosition` la place `under` (défaut, sa
+    propre ligne : de la place pour une phrase) ou `inline` (sur la ligne de la
+    légende, pour l'incise courte qui qualifie le nom au lieu d'instruire).
+    L'annonce ne dépend pas de la position — seul l'œil change de chemin. Sans
+    légende, `inline` retombe sur `under` : il n'y a pas de ligne où se poser.
+  - `ariaLabel` — nomme un groupe qui ne doit pas afficher de légende visible.
+    Ignoré si `legend` est renseigné : deux noms pour un groupe, c'est ainsi
+    qu'ils divergent.
+  - `legend` vide **et** `ariaLabel` vide = groupe volontairement sans nom, et
+    sans `aria-label` vide non plus — un groupe qui réclame un nom et n'en donne
+    aucun est pire qu'un groupe muet. C'est le cas imbriqué, déjà nommé par son
+    parent.
+
+  `legendVariant` porte les **deux registres** que les formulaires réels
+  emploient — les mêmes mots que le `titleVariant` d'un `fold-page-section`, et
+  délibérément : on rencontre UN vocabulaire pour « petit et au-dessus » contre
+  « se lit comme de la prose », pas un par composant.
+
+  - `eyebrow` (défaut) — petit, capitales, tracé, atténué : le groupe est une
+    **partie d'un formulaire**, son nom se pose au-dessus sans disputer
+    l'attention aux contrôles.
+  - `heading` — au poids du libellé d'un champ : le groupe **est** une seule
+    chose aux yeux du formulaire (« Heures de retrait »), son nom se lit donc
+    comme les libellés qui l'entourent.
+
+  Ce n'est pas un réglage cosmétique : un eyebrow au-dessus d'un groupe qui est
+  en réalité UN champ fait paraître au formulaire plus de sections qu'il n'a de
+  questions.
+
+  `optional` marque le groupe ENTIER — même parenthèse, même mot et même
+  fournisseur (`FOLD_COMMON_LABELS`) que le marqueur d'un libellé de champ. Il
+  existe parce qu'un groupe peut être facultatif quand aucun de ses membres ne
+  l'est : un point GPS, ce sont deux champs qu'on donne ensemble ou pas du
+  tout, et écrire « optionnel » sur chacun dirait autre chose — que l'un
+  pourrait manquer sans l'autre.
+
+  Plus `direction` (`vertical` par défaut, `horizontal`) et `appearance`
+  (`plain` par défaut, `border` pour le groupe encadré qui doit se distinguer de
+  ses pairs d'un coup d'œil). `--fold-fieldset-gap` thème l'écart entre membres. Il vaut par défaut le
+  **rythme d'un formulaire** (`--fold-space-md`) : un champ, c'est un libellé,
+  une boîte et parfois un indice — il lui faut l'air que trois cases à cocher
+  n'exigent pas. Un groupe qu'on n'a pas réglé empile des champs ; les groupes
+  compacts (cases, lignes horaires, boutons radio) resserrent.
+
+  ⚠️ Une finesse que les cinq versions manuscrites avaient toutes redécouverte à
+  leurs dépens : **la légende n'est pas un élément flex**. La boîte flex d'un
+  `fieldset` est sa boîte de contenu anonyme, et la légende rendue vit en
+  dehors — le `gap` ne l'atteint donc jamais, et son espace en dessous doit être
+  sa propre marge.
+
+  ⚠️ Deuxième finesse, trouvée en écrivant le test : **`input.disabled` ne dit
+  pas la vérité** dans un `fieldset` désactivé. La propriété IDL ne reflète que
+  l'attribut PROPRE du contrôle et reste `false` ; seule la pseudo-classe
+  `:disabled` connaît l'ancêtre. Un test écrit sur la propriété serait passé au
+  vert sur un composant qui ne désactivait plus rien.
+
+- **`--fold-font-label`** — la face du registre **micro-libellé** : les libellés
+  2xs / gras / capitales / tracés qui titrent une section, coiffent une colonne
+  de tableau ou servent d'eyebrow. Elle vaut `inherit` par défaut, donc rien ne
+  change tant qu'un hôte ne la nomme pas — la règle « un composant porte la face
+  de son hôte » tient toujours. Elle existe parce que c'est précisément le rôle
+  où un hôte veut souvent une AUTRE face que son texte courant (un libellé
+  monospace se lit comme une parole du système, pas comme de la prose), et que
+  le dire sans elle obligeait à entrer dans les entrailles de trois composants —
+  avec la dérive garantie le jour où un quatrième rejoint le registre.
+
+- **`fold-page-section` gagne `collapsible` + `[(open)]`** — replier le CORPS
+  d'une section, et rien d'autre. Le titre, son sous-titre, sa description et
+  ses `[sectionActions]` restent en place, et c'est toute la différence entre
+  replier et **cacher** : un onglet cachait l'ÉTAT avec les champs, donc on ne
+  pouvait pas savoir ce qui manquait sans tout ouvrir. Replié, la section dit
+  encore ce qu'elle est et ce qu'elle fait — et ses actions restent cliquables,
+  donc elle s'enregistre sans se déplier.
+
+  Deux conséquences de cette règle, toutes deux voulues : le bouton est le
+  TITRE et non l'en-tête (un bouton autour de l'en-tête aurait imbriqué
+  « Enregistrer » dans un `<button>` — inerte, et invalide), et l'état par
+  défaut est **ouvert**, parce qu'une section qui démarre repliée est une
+  section qu'il faut découvrir.
+
+- **`fold-page-section` gagne `[sectionSubtitle]`, `titleVariant` et
+  `separator`** — les pendants exacts de ce que `fold-page-layout` a reçu, pour
+  la même raison : une section d'écran dense est une petite page.
+
+- **`fold-page-layout` sépare la PORTÉE de l'en-tête de son SOL** :
+  `headerBleed` (aller bord à bord) et `headerBand` (peindre la bande) sont deux
+  entrées, plus une seule. `headerBand` faisait les deux, donc un simple filet
+  pleine largeur sous l'en-tête — traitement courant et discret — obligeait à
+  peindre une bande. On ne pouvait pas demander la portée sans l'encre.
+
+- **Les bandes montent d'un cran : `fold-page-layout[headerBand]` et
+  `fold-aside-layout[band]`.** Une en-tête de page et un rail collant peuvent
+  enfin se poser sur `--fold-color-surface-band` — le rôle qui existait déjà et
+  que `fold-card` consomme par `raisedBands` : « un pas À L'ÉCART de son
+  conteneur, dans le sens que la polarité du thème impose ». Clair il fonce,
+  sombre il éclaircit ; le composant nomme le rôle et n'a jamais à savoir dans
+  quel sens.
+
+  **Ce n'est pas une `surface`, et c'est le point.** L'axe `surface` est une
+  IDENTITÉ (`chrome`, `accent`) et il repointe l'encre sans jamais peindre de
+  fond (`docs/surfaces.md`) ; « l'en-tête est du mobilier, pas du contenu » n'est
+  ni l'un ni l'autre — c'est une élévation. Un `surface="raised"` aurait mélangé
+  les deux axes et aurait menti sur ce qu'il fait.
+
+  Deux détails qui ne sont pas de la décoration : la bande d'en-tête **annule
+  exactement** ce que la page marge (les deux mêmes tokens, moitié à l'étroit),
+  puis rembourse ce padding à l'intérieur — la colonne de texte ne bouge pas
+  quand on l'allume. Et un rail bandé **ferme la gouttière de colonne** au profit
+  d'un filet : un fond tenu à 28px du contenu qu'il accompagne ne se lit pas
+  comme une bande mais comme une carte flottante. L'espace passe à l'intérieur,
+  donc le contenu se lit à la même largeur dans les deux cas.
+
+- **`fold-aside-layout[bleed]`** — sortir de la gouttière de page et atteindre
+  le bord, même mécanisme et même variable que `fold-page-section[bleed]`. C'est
+  le compagnon de `band` : un rail bandé tenu à distance du bord par une
+  gouttière est exactement la carte flottante que la bande sert à remplacer.
+
+- **`fold-view-toggle` : un segment peut porter un point d'état** (`dot` +
+  `dotLabel` sur une option). Un point dit « regarde ici », jamais _quoi_ — il
+  est donc `aria-hidden`, et son sens rejoint le **nom accessible** du segment
+  au lieu de disparaître. Sans ça, un lecteur d'écran entendait « EN » là où un
+  œil voyait « EN, il manque quelque chose ».
+
+### Changed
+
+- **BREAKING (visuel) — le segment choisi d'un `fold-view-toggle` est PLEIN**
+  (`activeStyle` passe de `raised` à `solid`, et gagne au passage la valeur
+  `accent`). Même raison que le bouton solide : un contrôle segmenté existe pour
+  montrer **lequel est choisi**, et le choisi doit être la chose la plus forte
+  du contrôle.
+
+  Trois registres, parce qu'aucun ne convient partout : `solid` (rempli),
+  `accent` (teinté — présent, plus discret, et il garde l'encre du segment
+  lisible au milieu de beaucoup de couleur), `raised` (puce neutre). La puce
+  confiait la distinction à une élévation qui disparaît entièrement sous
+  `forced-colors`. Rien ne verrouillait ce défaut non plus.
+
+  Un détail que le plein impose : sur un fond d'accent, un point d'état peint
+  dans sa propre teinte peut tomber à un cheveu du fond — un point ambre sur un
+  accent chaud s'efface. Sur `solid`, le point prend donc l'encre du segment,
+  la seule garantie d'y être lisible.
+
+- **BREAKING (visuel) — un `foldButton` est SOLIDE par défaut** (`emphasis`
+  passe de `soft` à `solid` ; `intent` reste `primary`). Le défaut, c'est ce
+  qu'une app écrit quand elle n'écrit rien — et ce qu'elle écrit le plus, c'est
+  **l'action principale** de l'écran, celle qu'elle veut qu'on presse. Avec un
+  défaut teinté, le bouton le plus fort d'une page était celui que quelqu'un
+  avait pensé à baliser : l'emphase suivait l'effort de rédaction plutôt que
+  l'importance. `soft` et `outline` se demandent maintenant exprès, pour les
+  actions qui accompagnent celle-là.
+
+  Rien ne verrouillait ce défaut : les vingt tests du bouton passaient à
+  l'identique avant et après le basculement. Un test le tient désormais.
+
+- **BREAKING (visuel) — un titre de `fold-page-section` porte le registre
+  MICRO-LIBELLÉ par défaut** : 2xs, gras, capitales, tracé, dans
+  `--fold-font-label`. Un titre de section est un **libellé du bloc qui le
+  suit** ; à l'échelle d'une page, une pile de titres en taille de corps entre en
+  concurrence avec le contenu même qu'elle est censée étiqueter. C'est le
+  registre que portent déjà une en-tête de colonne de tableau et un eyebrow de
+  `fold-element-title`, donc les trois s'accordent.
+
+  C'est une **peau**, jamais une sémantique : le titre reste le même `h2`, avec
+  le même `aria-level` et le même nom de région dans les deux registres — un
+  test le vérifie explicitement, parce qu'un titre qui cesserait d'être un titre
+  pour ressembler à un libellé coûterait son plan à la page sans que rien ne le
+  dise.
+
+  Pour retrouver l'ancien rendu : `titleVariant="heading"`.
+
+### Fixed
+
+- **Un `bleed` annule désormais la gouttière que la page PAYE, pas celle qu'on
+  lui a demandée.** Sous 640px, `fold-page-layout` réduit son inset de moitié —
+  et `fold-page-section[bleed]`, épinglé au token écrit, continuait d'annuler la
+  valeur entière : la section débordait d'une demi-gouttière de chaque côté,
+  précisément là où il y avait le moins de place. La page publie maintenant
+  `--fold-page-gutter-effective` et tout ce qui annule lit celle-là. Le bug était
+  invisible partout : aucune requête média ne s'évalue en test unitaire, et le
+  symptôme est un débordement horizontal. Un test de contrat sur les sources
+  tient l'invariant.
+
+- **`fold-page-layout` : les actions s'alignent sur la rangée du TITRE.** Elles
+  se calaient en haut de la colonne de texte ; depuis que `[pageEyebrow]`
+  existe, cette colonne commence par le fil d'Ariane — et les actions
+  remontaient se coller à lui. L'eyebrow sort donc de la colonne et coiffe
+  l'en-tête entier : c'est sa place logique (il désigne la page, pas le titre) et
+  la rangée titre + actions redevient une vraie rangée.
+
 ## [0.16.0] - 2026-08-24
 
 ### Added
@@ -1955,7 +2172,8 @@ design-token stylesheet.
   `currentColor`; `prefers-reduced-motion` + `forced-colors` are respected;
   strings localise via inputs / providers (`provideFoldPanelLabels`).
 
-[unreleased]: https://github.com/hugoheynard/fold-ng/compare/v0.16.0...HEAD
+[unreleased]: https://github.com/hugoheynard/fold-ng/compare/v0.17.0...HEAD
+[0.17.0]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.17.0
 [0.16.0]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.16.0
 [0.15.0]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.15.0
 [0.14.0]: https://github.com/hugoheynard/fold-ng/releases/tag/v0.14.0

package/README.md

@@ -350,6 +350,7 @@ ships it.
 | `FoldDateComponent`                                      | `fold-date`                            | Native calendar-date wrapper (`type` = date · datetime-local · month · week) — keeps the OS picker, hands back a typed `[(value)]` string (`YYYY-MM-DD`). `min`/`max`/`step` pass through. Time-of-day → `fold-time`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `FoldTimeComponent`                                      | `fold-time`                            | Native time-of-day wrapper (`<input type="time">`) — typed `[(value)]` string (`HH:mm`), `min`/`max`/`step`. The sibling of `fold-date`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `FoldCheckboxComponent`                                  | `fold-checkbox`                        | Boolean control — a native `<input type="checkbox">` (keyboard, `indeterminate`, forms) restyled to tokens. Signal Forms (`[formField]`, a `FormCheckboxControl`) or standalone `[(checked)]`; `indeterminate`, `label`/`ariaLabel`, `hint`/`errors`, `size`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `FoldFieldsetComponent`                                  | `fold-fieldset`                        | Named group of controls — a real `<fieldset>`/`<legend>` with the browser's margin/padding/3D border undone and the rhythm on tokens. `disabled` disables every control inside (the element's unique power); `hint` wired through `aria-describedby` (`hintPosition` `under`/`inline`); `legend` (empty renders none) or `ariaLabel`; `optional` marks the whole group (not each member); `legendVariant` (`eyebrow`/`heading` — the same two registers as a page-section's title), `direction` (`vertical`/`horizontal`), `appearance` (`plain`/`border`); `--fold-fieldset-gap`.                                                                                                                                                                          |
 | `FoldPasswordFieldComponent`                             | `fold-password-field`                  | Password input + a live requirements checklist (a dot/tick per rule). Rules injected via `FoldPasswordRule` (`{ label, test }` — regex/zod/anything); `revealable` eye (a `fold-input` capability); `marker` dot/check; `[rules]` slot to redesign the list; `validChange`; Signal Forms.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `FoldViewToggleComponent`                                | `fold-view-toggle`                     | Segmented single-select (Cards/Table, density, chart-mode…). Generic `options` (`{ value, icon?, label?, ariaLabel?, disabled? }`) + `[(value)]`; a real `role="radiogroup"` — roving tabindex, arrow keys, Home/End, disabled-skip; `size`, `iconOnly`, `activeStyle` (raised / accent).                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `FoldSearchComponent`                                    | `fold-search`                          | Debounced search box — an `fold-input` that emits `searchChange` once typing settles (`delayMs`), trimmed + de-duplicated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |