origam 2.18.0 → 2.18.2

package/CHANGELOG.md

@@ -16,6 +16,291 @@ This project follows [Semantic Versioning](https://semver.org).
 
 ---
 
+## [Unreleased]
+
+Récolte de deux dépréciations posées "pour la prochaine majeure" avant que le
+`CLAUDE.md` n'acte que `3.0.0` est réservé à la séparation en modules et que
+les ruptures, elles, ne le sont pas — voir "Work priorities and versioning"
+du `CLAUDE.md`. `origam` n'a aucun consommateur : les deux ruptures
+ci-dessous partent en **mineure**, sans shim ni période de grâce.
+
+### ⚠️ BREAKING — `click:prepend` / `click:append` retirés d'`IBtnEmits` (#443, #577)
+
+`<OrigamBtn>` n'émet plus `click:prepend` ni `click:append` — ni au niveau du
+type, ni au niveau de l'exécution. `IBtnEmits` n'`extends` plus
+`IAdjacentEmits`, et les `<span>` `origam-btn__prepend` / `__append` ne
+portent plus de `@click` du tout : un clic souris dessus ne déclenche plus
+rien.
+
+**Pourquoi cette paire précisément, et pourquoi une suppression plutôt qu'un
+correctif.** Les deux émissions n'ont jamais été atteignables au clavier :
+l'événement partait d'un `<span>` descendant, alors qu'une activation clavier
+synthétise son clic sur la RACINE du composant — l'écouteur posé sur le
+descendant ne le voit jamais. Le correctif générique appliqué aux dix autres
+consommateurs d'`useAdjacent` (promouvoir la zone en `role="button"` + arrêt
+de tabulation) est **illégal** ici : `<OrigamBtn>` rend un `<button>` ou un
+`<a>`, et le modèle de contenu HTML interdit à tous deux un descendant de
+contenu interactif *et* tout descendant portant `tabindex`. Un
+`<button type="button">` imbriqué y est tout aussi invalide. La forme était
+fausse, pas seulement le balisage : un contrôle qui possède déjà une action
+ne peut pas en héberger une seconde — deux actions sont deux boutons,
+composés via `<origam-btn-group>`.
+
+**Ce qui NE bouge PAS** : les slots `prepend` / `append` (`IBtnSlots extends
+IAdjacentSlots`) restent intacts, ainsi que les props `prependIcon` /
+`appendIcon` / `prependAvatar` / `appendAvatar` — un contenu décoratif ou
+informationnel en prepend/append reste parfaitement légitime, seule
+l'émission d'un clic disparaît.
+
+**Preuve du comportement retiré** — A/B contre le commit parent, fonctionnel
+et pas seulement typé : `packages/tests/TU/components/Btn/OrigamBtn.adjacent-emit-removed.spec.ts`
+monte `<OrigamBtn>` avec un écouteur `onClick:prepend` / `onClick:append` et
+déclenche un vrai `click` DOM sur la zone. Sur le commit parent, ce même test
+appellerait l'écouteur (l'émission déclarée par `IAdjacentEmits` partait
+encore) ; sur ce commit, l'écouteur n'est jamais invoqué — vérifié en
+rejouant le fichier de spec avant/après le changement, pas seulement en le
+lisant une fois vert.
+
+Nettoyage induit : le helper `warnDeprecatedEmit` (`color.util.ts`) et la
+constante `ADJACENT_EMIT_REPLACEMENT` (`consts/Btn/btn.const.ts`) sont
+retirés — `<OrigamBtn>` était leur seul appelant, et le fichier `btn.const.ts`
+devenu vide est supprimé.
+
+**Migration.** Aucun consommateur interne (DS, marketing, stories, docs,
+tests) n'utilisait `click:prepend` / `click:append` sur `<OrigamBtn>` —
+balayage exhaustif, zéro résultat. Un consommateur externe qui les écoutait
+doit remplacer l'action posée sur la zone prepend/append par un second
+`<origam-btn>` dans un `<origam-btn-group>`.
+
+### ⚠️ BREAKING — `createOrigam()` nu n'installe plus le thème par défaut (#360)
+
+`createOrigam()` préfixait inconditionnellement chaque install avec le thème
+neutre interne `origamTheme` (`[...origamTheme, ...suppliedThemes]`) : même un
+appel nu, ou un `themes: []` explicite, recevait quand même les variables CSS
+et — surtout — les **props par défaut par composant** (ADR-005,
+`components: { 'origam-avatar': { rounded: 'full' }, … }`) de ce thème. Une
+application qui n'en voulait pas ne pouvait pas s'en défaire. Ce préfixage est
+retiré : `createOrigam()` installe désormais exactement ce qu'on lui passe,
+rien de plus.
+
+**Ce qui change concrètement.** Sans `themes`/`theme` explicite,
+`createOrigam()` n'injecte plus aucune variable `--origam-*` et le résolveur
+de props par défaut (`installThemePropsResolver`, ADR-005) n'a plus rien à
+résoudre — chaque composant retombe uniquement sur ses propres valeurs
+`withDefaults()`. Concrètement : un `<origam-avatar>` sans prop `rounded`
+explicite n'est plus automatiquement circulaire (`rounded="full"` venait du
+thème, pas du composant).
+
+**Le thème par défaut reste disponible, à la demande** — `origamTheme`,
+exporté par `origam/themes` (déjà public avant cette rupture, aucun nouvel
+export nécessaire) :
+
+```ts
+// AVANT (2.x) — enregistrait implicitement le thème origam par défaut
+import { createOrigam } from 'origam'
+app.use(createOrigam())
+
+// APRÈS — le thème par défaut est un choix explicite
+import { createOrigam } from 'origam'
+import { origamTheme } from 'origam/themes'
+app.use(createOrigam({ themes: origamTheme }))
+```
+
+**Rayon de souffle mesuré, corrigé dans le même lot** — quatre consommateurs
+directs de `createOrigam()` nu trouvés par balayage exhaustif (DS, marketing,
+stories, docs, tests) :
+- `packages/ds/src/nuxt/module.ts` — le module Nuxt officiel. **Non cassé** :
+  son propre `DEFAULT_THEMES` (utilisé quand l'option `origam.themes` du
+  consommateur est omise) passe désormais `origamTheme` explicitement à
+  `createOrigam()`, préservant à l'identique le comportement de tout
+  consommateur Nuxt existant (marketing compris) qui ne configurait rien.
+  Seul un `createOrigam()` direct, hors module Nuxt, doit s'adapter.
+- `packages/marketing/nuxt.config.ts` — configure `origam.themes`
+  explicitement (7 thèmes de marque + un thème `origam` renommé pour le
+  playground `/theming`), ce qui **contourne** le fallback du module. Le vrai
+  thème neutre non-nommé (celui que `activeDefaultsFor` fusionne toujours en
+  premier, avant la marque active) était fourni jusqu'ici par le préfixage
+  implicite de `createOrigam()` — invisible dans la config marketing. Il est
+  désormais listé explicitement, en premier, dans le tableau `themes`.
+- `packages/stories/histoire.setup.ts` — Histoire (utilisé par les ~208
+  stories de composants) appelait `createOrigam()` nu ; sans correction,
+  chaque story aurait silencieusement perdu les props par défaut du thème
+  (avatars carrés au lieu de circulaires, etc.). Passe désormais
+  `{ themes: origamTheme }`.
+- `packages/docs/.vitepress/theme/index.ts` — les démos de composants live de
+  la doc VitePress appelaient `createOrigam()` nu ; même correction.
+
+Les échantillons de code montrés au consommateur (`installation.const.ts` /
+`installation.vue` sur le marketing, `guide/usage.md` côté docs) sont mis à
+jour pour montrer la forme correcte — un utilisateur copiant l'ancien
+exemple aurait obtenu des composants non stylés selon le thème.
+
+**Tests adaptés** (comptés avant correction, comme demandé) — 3 fichiers /
+5 assertions reposaient sur l'enregistrement implicite et ont été corrigés
+pour installer `origamTheme` explicitement là où le test vérifie précisément
+une valeur par défaut issue du thème, ou réécrits pour pinner le NOUVEAU
+contrat plutôt que l'ancien :
+- `theme-props-resolver.spec.ts` (2 assertions — `origam-radio`/`origam-text-field`
+  vs `origam-input` density) ;
+- `installed-themes.composable.spec.ts` (describe block entier renommé
+  `origam baseline — explicit opt-in only (#360)`, 2 assertions corrigées et
+  2 nouvelles ajoutées pour couvrir explicitement le nouveau contrat) ;
+- `OrigamChip.spec.ts` (1 assertion — `components['origam-chip'].size`).
+
+**Preuve fonctionnelle** (pas seulement structurelle) —
+`packages/tests/TU/origam/createOrigam-bare-no-theme-360.spec.ts` monte un
+vrai `<OrigamAvatar>` : sans thème, la classe `origam--rounded-full` est
+absente ; avec `origamTheme` passé explicitement, elle est présente — la
+même monteuse prouve donc que le harnais peut actionner la prop avant de
+conclure qu'elle ne l'est plus par défaut.
+
+### Fixed
+
+- **#871 — le mode sombre ne peignait qu'à moitié dans un sous-arbre thémé.**
+  Les feuilles de tokens portent ~1 761 déclarations **dérivées**
+  (`--origam-title---color: var(--origam-color__text---primary)`). Une custom
+  property est substituée **sur l'élément qui la déclare** ; ce qu'un
+  descendant hérite est la valeur DÉJÀ substituée. Le bloc sombre étant ancré
+  à la racine (`:root:not([data-theme])[data-mode="dark"]`), un sous-arbre
+  `<OrigamThemeProvider mode="dark">` basculait bien les ~60 tokens
+  sémantiques — le bloc runtime, lui, émet `[data-mode="dark"]` — mais laissait
+  les 1 761 dérivés **gelés** sur les valeurs claires de la racine. Motif
+  dominant mesuré : `rgb(10,10,10)` sur `rgb(10,10,10)`, texte et fond
+  identiques.
+
+  Les deux feuilles s'accrochent désormais aussi à l'axe `data-mode` :
+
+  ```css
+  :root, [data-theme="light"], [data-mode="light"]      { /* clair */ }
+  [data-theme="dark"], [data-mode="dark"]:not([data-theme="light"]) { /* sombre */ }
+  ```
+
+  Rejoué sur 30 composants × 8 identités × 2 modes × 2 portées (racine ET
+  sous-arbre), soit **1 664 instances**, Chromium, contrôles positif et négatif
+  verts : **185 → 7 violations AA**, dont sombre **182 → 4** et clair
+  **3 → 3** (aucune régression). Les 7 restantes appartiennent toutes aux
+  palettes de marque de `packages/marketing`, aucune au DS, et aucune ne
+  descend sous 2:1. Harnais : `pnpm -F @origam/tests audit:dark-contrast`.
+
+  ⚠️ **Ces bornes ont d'abord été publiées à `189 → 11`, et les deux étaient
+  fausses de 4.** Le parseur de couleurs du harnais ne connaissait pas
+  `color(srgb …)`, que la palette `apple` émet : le fond translucide du
+  tooltip était pris pour « pas de fond », la remontée d'ancêtres sautait
+  jusqu'à la surface opaque et rapportait du noir sur noir à 1.00 — quatre
+  violations **fabriquées**, présentes des DEUX côtés de la mesure. Le
+  **delta de 178 n'a jamais été faux** ; seules les bornes l'étaient. Détail
+  et garde de non-récidive plus bas.
+
+- **#871 — le harnais de contraste ne savait pas lire `color(srgb …)`, et
+  FABRIQUAIT donc des violations.** Son `parse()` ne reconnaissait que
+  `rgb()` / `rgba()`. Un fond qu'il ne sait pas lire n'est pas « ignoré » : il
+  est traité comme **non peint**, la remontée d'ancêtres saute l'élément et
+  composite contre une couche qui n'est pas celle que voit l'œil. Sur le
+  tooltip `apple` — `color(srgb 0.898 0.898 0.906 / 0.94)` sur une surface
+  noire — cela donnait du noir sur noir à **1.00** là où le rendu réel est
+  ~`rgb(215,215,217)` sur noir. 4 instances (root + sous-arbre × clair +
+  sombre), des deux côtés de la mesure.
+
+  `parse()` reconnaît désormais `color(srgb r g b [/ a])`, avec **la même
+  expression régulière que `srgbToRgb` dans `contrast.directive.ts`** — la
+  vraie directive gérait déjà cette forme, et son commentaire le disait :
+  *« design tokens resolve to exactly this form in several themes »*.
+
+  ⛔ **Un quatrième contrôle, parce que le correctif ponctuel ne suffit pas.**
+  Le harnais échoue maintenant (`$? = 1`) dès qu'une chaîne de couleur non
+  vide lui est illisible, en listant les formes rencontrées. Sans lui, la
+  prochaine syntaxe (`oklch()`, `lab()`, résidu de `color-mix()`) décalerait
+  le chiffre en silence exactement de la même façon. Contrôle positif du
+  garde lui-même : branche `srgb` désactivée → `$? = 1`, 8 formes listées, et
+  le compte réaffiche l'ancien **11** ; branche active → `$? = 0`, tout lu,
+  **7**.
+
+  ⚠️ #871 listait déjà ce risque sous « non vérifié » — *« les couleurs
+  `oklch()` / `color(srgb …)` — aucun token actuel n'en emploie, mais un futur
+  thème invaliderait l'instrumentation »*. Un thème le faisait **déjà** au
+  moment où la phrase a été écrite. Écart signalé en marge de la **PR #882**
+  (#869, `v-contrast`) par l'agent qui rejouait ce harnais avec la vraie
+  directive au lieu du stub ; reproduit, remesuré et corrigé ici. Aucun ticket
+  propre n'a été ouvert : le défaut est dans l'instrumentation de #871, donc
+  il se règle sous #871.
+
+- **#871 — `system-bar` et `tooltip` illisibles en sombre.** Les deux peignent
+  une surface sombre dans les DEUX modes (`neutral---700` / `neutral---800`)
+  et lisaient `text---inverse`, qui vaut blanc en clair et **encre** en
+  sombre : 1.91:1 et 1.31:1. `dark.css` lit maintenant `text---primary` ;
+  `light.css` est inchangé.
+
+- **#871 — `bottom-nav` peignait une dalle claire dans une UI sombre.** Son
+  fond était épinglé à la primitive `neutral---200` (#e6e6e6) dans les deux
+  modes, sous un `text---primary` presque blanc (1.03:1). En sombre il passe
+  au token sémantique `surface---overlay`. Le clair est inchangé.
+
+### Changed — ⛔ RUPTURE (documentée, assumée)
+
+- **Les feuilles de tokens ne sont plus ancrées à `:root`.** Un consommateur
+  qui avait contourné le gel ci-dessus en re-déclarant lui-même des variables
+  de composant dans un sous-arbre `[data-mode]` voit désormais la feuille les
+  déclarer aussi, en (0,1,0) côté clair et (0,2,0) côté sombre. Son bloc de
+  contournement doit donc être au moins aussi spécifique, ou être retiré.
+
+  Concrètement dans ce dépôt : `packages/marketing` embarque
+  `ORIGAM_COMPONENT_RESET_LIGHT/DARK` (`themes/origam-reset.generated.ts`),
+  une re-déclaration GÉNÉRÉE de ~2 700 variables de composant, écrite
+  exactement pour ce défaut. Elle est maintenant redondante — **elle n'a pas
+  été retirée ici**, faute de mesure sur le rendu du site.
+
+  Ce qui NE change pas : `data-theme="light" data-mode="dark"` reste clair
+  (l'axe marque gouverne quand les deux se contredisent, règle #807),
+  `data-mode="light"` sous un OS sombre reste clair (#794), et une marque
+  claire continue de gagner sur la feuille par l'ordre source.
+
+### Documentation
+
+- `CLAUDE.md`, section *Multi-theme* : la note qui affirmait que le bloc
+  auto-mode ne porte que **11** déclarations est **fausse** — recompté en
+  parsant la feuille le 2026-09-22, les deux blocs en portent **2 731**
+  chacun. L'affirmation décrivait un état antérieur à #794 que plus rien ne
+  remesurait.
+
+### Fixed
+
+- **#371 (point 3) — le sélecteur « Items per page » du footer
+  DataTable n'avait aucun nom accessible**, déjà corrigé par `3f063d727`
+  (2026-09-10) — ce commit **citait #371 sans le fermer**, sixième
+  occurrence cette semaine du même motif (cf. #570, #682, #537, #371
+  point 1, #371 point 2/ADR-005). Re-mesuré ici avant tout travail sur les
+  points restants du ticket : le `<span>` visible est désormais associé au
+  `<origam-select>` via `aria-labelledby`, et la suite unitaire complète
+  reste verte (7120/7120) — aucun code de production retouché sur ce point,
+  seule la mesure manquait au tableau.
+
+- **`<OrigamDataTableRow>` ne fuit plus `index` / `mobile` en attributs DOM**
+  (#371, point 4). `itemSlotProps()` (`OrigamDataTableRows.vue`) construisait
+  la ligne d'item avec deux clés qu'`IDataTableRowProps` ne déclare pas —
+  `index`, jamais lu par le composant, et `mobile`, un résidu d'avant
+  l'ajout du forwarding de `mobileBreakpoint` (chaque ligne calcule déjà son
+  propre `mobile` à partir de ce dernier). Une clé non déclarée tombe dans
+  `$attrs`, et le `v-bind="$attrs"` du `<tr>` racine la posait en attribut
+  DOM littéral sur **chaque** ligne rendue — `index="0" mobile="false"`.
+  Même mécanisme que le point 1 de ce ticket (déjà corrigé, `08c30693a`),
+  une famille plus loin. `aria-rowindex`, seul attribut voulu de ce canal,
+  continue de passer.
+
+### Added
+
+- **`mobileBreakpoint` a désormais un contrôle de story sur
+  `<OrigamDataTable>`** (#371, point 5). La prop — dont le défaut `'xs'`
+  corrige un bug de production documenté en commentaire
+  (`OrigamDataTable.vue:190-199` : sans lui, `useDisplay` retombait sur le
+  seuil global `'lg'` et forçait le rendu mobile empilé sur tout viewport
+  sous 1280px) — n'apparaissait dans aucune des 30 Variants de
+  `OrigamDataTable.story.vue`. Ajout de la Variant « Prop —
+  mobileBreakpoint » (même jeu d'options que celui déjà utilisé par
+  `OrigamDataTableRow.story.vue`) et d'une section « Responsive » +
+  ligne de table dans `OrigamDataTable.md`.
+
+---
+
 ## [2.18.0] - 2026-09-19
 
 80 commits depuis `v2.17.1`. L'essentiel est du **correctif** : des tokens qui