@portnet/ui 5.0.32 → 6.0.1

package/CHANGELOG.md

@@ -0,0 +1,524 @@
+# Changelog
+
+All notable changes to `@portnet/ui` are documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — with the addition of `-muiN.M` / `-react19.N` pre-release tags during ecosystem migrations.
+
+---
+
+## [Unreleased]
+
+### Added
+
+- **`SkeletonPageShell` — the route-level `Suspense` fallback R-P.1 requires (G-02).**
+
+  R-P.1 MUST says "routing avec `React.lazy` + `Suspense`, **fallback skeleton page**". The library shipped every skeleton *part* — `Skeleton`, `SkeletonRow`, `SkeletonKPI`, `SkeletonDetailHero`, `SkeletonTabContent`, `SkeletonText` — plus `PageBusy`, and yet nothing that satisfies the rule: `PageBusy` is a full-viewport spinner, which R-8.1 MUST forbids for navigation, and the parts are shaped for the inside of a page rather than the page frame.
+
+  Two audited modules had each hand-built a `RoutePageFallback`. **The coupling is the whole argument for owning this here:** to avoid the layout shift a skeleton exists to prevent, the fallback's padding must equal `ActionBar`'s and `PageContent`'s exactly — which a module can only achieve by copying literals out of this library, where they then rot silently the next time either component's padding changes.
+
+  Three variants mime the three page archetypes per R-Sk.2 ("forme et nombre miment le contenu réel"): `list` (filter strip + table), `form` (stepper + two-column grid), `detail` (hero + tabs).
+
+  Reserved dimensions use the density tokens `--btn-h`, `--input-h` and `--row-h` rather than px literals, so the placeholder follows a `data-density="compact"` switch instead of sitting 6–8 px wrong under it.
+
+  Deliberately does **not** compose `SkeletonText` / `SkeletonTabContent`: each carries its own `aria-busy` + `aria-label`, and nesting live regions makes a screen reader announce one page load two or three times. One labelled region wraps the shell; every child is an `aria-hidden` primitive (R-Sk.3).
+
+- **`getApiErrorMessage` / `getApiErrorStatus` — sanctioned narrowing for `unknown` rejections (G-04).**
+
+  The Platform TypeScript Guidelines mandate `useUnknownInCatchVariables`, so `catch (e)` binds `unknown` in every saga of every consuming module. The same guidelines forbid `any` and unsafe assertions. The library provided nothing between those two rules — and the modules that filled the gap filled it the forbidden way:
+
+  ```ts
+  (error as { response?: { data?: { message?: unknown } } }).response
+  ```
+
+  Two audited modules (`procuration-portnet-fe`, `procuration-fe`) had independently written that same unchecked assertion. **A mandated strict-mode flag with no sanctioned escape hatch produces unsanctioned ones**, so this is a library gap rather than two module defects.
+
+  Both helpers are assertion-free: `in` narrows each hop, `Reflect.get` returns the value as `unknown`. Deliberately duck-typed rather than built on `axios.isAxiosError` — the library must not take a hard axios dependency for a string helper, and a hand-rolled reject or a test double still resolves correctly.
+
+  `getApiErrorStatus` returning `undefined` is the documented signal for "no answer at all" (network drop, timeout) as opposed to "the server answered with an error", which is exactly the distinction Charter R-4.3 / R-A.4 require when choosing a persistent banner over a toast.
+
+  `DEFAULT_API_ERROR_MESSAGE` is exported and the fallback is per-call overridable, so a screen that can say something more useful is not forced into the generic string.
+
+- **`networkStatus` / `createNetworkStatus` — the feed behind `NetworkErrorBanner` (G-03).**
+
+  `NetworkErrorBanner` shipped as a presentational component with its trigger contract left to consumers. Charter R-A.3 / R-4.3 make the banner **mandatory**, so every module had to invent the same subscribe / report / clear channel plus the same transport-interceptor bridge — and two audited modules had each written their own `networkStatus.ts`.
+
+  A presentational component whose trigger contract lives outside the library guarantees divergence in the state users meet least often and trust least: the offline path.
+
+  Not a redux slice, deliberately — the state is presentation-only, high-frequency on a flaky link, and the library must not take an opinion on the host's store. Reports are de-duplicated so a failing link cannot re-render every subscriber per retry, and late subscribers are hydrated on `subscribe` so a lazily-mounted banner does not miss the transition.
+
+  `createNetworkStatus()` is exported alongside the shared singleton so tests can use an isolated channel instead of leaking state between cases.
+
+  Both additions are **flat-root-only**, per the standing policy in `src/lib/index.ts`: capability added after the `v2.*` deprecation is not surfaced on the retiring namespace. Raised from the `procuration-portnet-fe` Area 5 gap-leakage audit; same route previously used for `downloadBase64File` / `getMimeType`.
+
+### Fixed
+
+- **`ActionBar` — the page subtitle is no longer hidden on phones (S-01).**
+
+  The subtitle was rendered with `display: { xs: "none", sm: "block" }`, so below the `sm` token (481 px) it was removed from the layout **and from the accessibility tree**. On a 320–414 px viewport it did not exist for any user, sighted or not.
+
+  This made every consuming module fail three normative rules simultaneously: *Platform Mandatory UX Patterns → Page Subtitle* ("Mandatory… **Never omit subtitles**"), the same document's **Forbidden Practices** list (`missing subtitle` = certification failure), and the **Responsive Pattern** requirement to support from 320 px. Charter §7.1 bis places "Page title (H1) + subtitle + CTA" in the canonical vertical order with no breakpoint exemption.
+
+  The subtitle now renders at every breakpoint. The original vertical-space concern is met by **bounding** the height rather than deleting the content: two lines via line-clamp on `xs`, mirroring the `EmptyState` rule already in this library ("description ≤ 2 lignes"). Clamped text remains in the accessibility tree, so screen-reader users receive the full string.
+
+  **Scoped to `xs` deliberately — zero regression surface.** At `sm` and above `display: block` makes the line-clamp inert, so rendering is byte-identical to before. Clamping desktop as well would have been a *new* restriction on existing behaviour and could truncate a subtitle that a module currently renders over three lines.
+
+  No API change: no prop added, removed or renamed; no call site needs to change. Backward-compatible for the ~150 services consuming the component.
+
+  Raised from the `procuration-portnet-fe` migration (Batch 3), where it was recorded as finding **S-01**. Fixed in the library rather than worked around locally, per the platform gap-management rule: a module-side subtitle would duplicate a shared component's responsibility (R-2.1 / R-AI.2) and would have required local breakpoint logic to avoid doubling at ≥ `sm`.
+
+- **`Input` — `label` is no longer accepted, so an unlabelled field is now a compile error (S-02).**
+
+  `InputProps` inherited `label` from `OutlinedInputProps`. On `OutlinedInput` that prop only **sizes the notch in the outline**: it renders no text and creates no `<label>` element. So `<Input label="Description" … />` compiled cleanly and produced a field with **no visible label and no accessible name** — a silent violation of Charter **R-I.1**, compliance checklist **A5**, and **WCAG 2.2 AA 1.3.1 / 4.1.2**.
+
+  `label` is now omitted from the inherited surface. The correct usage is unchanged and was always documented in the component's own docstring:
+
+  ```tsx
+  <Field label="Référence"><Input value={v} onChange={…} /></Field>
+  ```
+
+  **Backward-compatible for every correct caller**: a consumer already wrapping in `<Field>` never passed `label` to `Input`. Only the incorrect usage stops compiling — which is the point.
+
+  This mirrors what `FormikInputProps` already did one file away (it omits `"label"` and re-declares it to forward to `Field`); the pattern existed but had not been applied to the bare primitive.
+
+  **Not hypothetical.** The `procuration-portnet-fe` migration shipped **six such fields across five files** — all passing `tsc --strict` with the full mandated flag set, plus lint and review — before the omission was noticed. The asymmetry with `Select`, which has no `label` prop at all and therefore fails loudly, is what exposed it. The only gate that would otherwise have caught them is a manual Axe / screen-reader pass, i.e. after the code had been written and replicated three times.
+
+  Raised from that migration as finding **S-02**.
+
+- **`FormikDatePicker` — `outputFormat` now round-trips; it was write-only (S-03). ⚠️ silent data corruption.**
+
+  The bridge serialised OUT through `moment(date).format(outputFormat)` but read BACK through `new Date(raw)`, ignoring `outputFormat` entirely. For any non-ISO format the stored value could not be parsed back:
+
+  | Stored | `new Date(…)` gave | Effect |
+  |---|---|---|
+  | `"31-12-2026"` | `Invalid Date` → `null` | field rendered **empty** on re-populate |
+  | `"05-03-2026"` | **3 May** (V8 reads MM-DD) | wrong date shown; saving untouched wrote back `"03-05-2026"` — **corruption** |
+
+  `coerceToDate` now parses with the same format it was written with, in moment's **strict** mode, so a value that does not match yields `null` rather than a plausible wrong date. A missing date is recoverable; one quietly off by two months is not.
+
+  **The docstring recommended the failing usage**, giving `outputFormat="DD-MM-YYYY"` as its worked example — so a consumer following the documentation got corruption. That example is now correct, and the round-trip requirement is stated explicitly.
+
+  **Failure mode worth internalising:** the WRITE path worked. A form filled in and submitted immediately behaved correctly; the damage only surfaced on **re-populate**, i.e. an edit flow — the path a smoke test is least likely to exercise. `procuration-portnet-fe` shipped it for **seven batches** under a clean `tsc --strict`, and its own notes had listed "the DD-MM-YYYY round-trip" as the top runtime risk on the assumption that only execution could reveal it. It was found statically, by reading `coerceToDate` instead of the prop signature.
+
+  **Backward compatibility:** callers passing nothing, or `"iso"`, are on the identical code path. Callers passing a moment token were mis-parsing before — their result changes from wrong to right, which is the point but is still a change.
+
+  **Audit performed:** this is the only Formik date bridge in the library. `DateTimePicker`, `TimePicker` and `DateRangePicker` are exposed as bare components exchanging `Date` objects, so they have no serialisation step and no equivalent asymmetry; `_pickerShared` carries only `Date`↔`Moment` converters, not string parsing. **The defect was contained to one file.**
+
+  Raised from the `procuration-portnet-fe` migration (Batch 12) as finding **S-03**.
+
+### Known gaps in this entry
+
+- **Sibling primitives not yet audited.** Any other bare primitive inheriting from a MUI input type may carry the same trap: a `label` it inherits but does not render. `Textarea`, `NumberInput`, `TelInput` and `Combobox` need the same check. Deliberately **not** done blind in this entry — each requires reading the component to establish whether it renders a label, and guessing is precisely the mistake that produced S-02.
+- **No version number assigned yet.** Per Charter §10.1 this is a PATCH (bug fix). Releasing it requires bumping `package.json` **and** the `VERSION` constant in `src/lib/v2/index.ts` **together** — that constant carries an explicit warning about the silent metadata drift that once left it stuck at `0.1.4`. Left to the DS team's release cadence rather than decided here.
+- **`0.7.0-react19.1` is not documented in this file.** `package.json` and `VERSION` both report it, but the most recent entry below is `0.6.0-react19.1`. Pre-existing gap, not introduced by this change; flagged so it is not mistaken for the present entry being misplaced.
+- **`ActionBar` has no Storybook story and no Jest test** — there is no `ActionBar.stories.*` or `ActionBar.test.*` anywhere in the repository. Charter §10.3 R-G.6 requires both for a component change. This is a pre-existing gap for this component rather than a regression, and adding coverage was deliberately not bundled into a one-property fix; it needs its own scoped change with a visual-regression baseline.
+
+---
+
+## [0.6.0-react19.1] — 2026-06-05 (pre-release)
+
+> **Theme**: User Personalization Foundation — a reusable favorites + saved-filters framework on an extensible provider / adapter architecture. Purely additive; zero breaking changes to the v2 surface.
+
+This release adds a per-user personalization layer to the v2 Design System: users can favorite rows and save / recall named filters on any list, and the framework is built to extend to saved views, column preferences, density, and dashboard layout with no redesign. Built across a strict 10-batch program (architecture → provider → favorites → saved filters → DataGrid integration → responsive → accessibility → performance → Storybook → certification); each batch was analyse → implement → validate → commit.
+
+Hosts already on `0.5.0-react19.1` upgrade transparently — nothing in the existing surface changed; the personalization API is entirely new exports.
+
+### New public surface
+
+Available flat from `@portnet/ui` / `@portnet/ui/v2`, and via the dedicated subpaths `@portnet/ui/personalization` and `@portnet/ui/v2/personalization`.
+
+- **Provider** — `UserPersonalizationProvider` (single configuration point; scope `{ userId, tenantId?, appId? }`).
+- **Adapters** — `createLocalStorageAdapter` (default, SSR-safe, cross-tab via the `storage` event), `createMemoryAdapter` (tests / Storybook).
+- **Favorites** — `FavoriteToggle` (presentational ☆/★), `useFavorites`, `useIsFavorite`, `makeFavoriteColumn` (always-visible DataGrid column), `FavoritesFilter` (all / favorites-only), `useFavoritesView` + `filterRowsByFavorites` / `sortRowsByFavorites`, and the `FAVORITES_FILTER` / `FAVORITES_SORT` enums.
+- **Saved filters** — `useSavedFilters`, `SaveFilterDialog` (presentational), `SavedFiltersMenu` (connected dropdown).
+- **Extension seam** — `registerCapability` for host-defined capability slices.
+- **`DataGridToolbar` `actions` slot** — a generic node slot to host `FavoritesFilter` / `SavedFiltersMenu` without coupling the toolbar to the personalization layer.
+
+### Architecture
+
+Documented in `docs/PERSONALIZATION_ARCHITECTURE.md`.
+
+- **One provider, capability slices.** A single store holds all capabilities; each slice (favorites, savedFilters, …) self-registers at import time and owns its payload shape. The store is capability-agnostic — adding a capability needs no store change.
+- **Sync snapshot + async adapter.** Reads are synchronous and render-safe (`useSyncExternalStore`); writes are optimistic and persisted asynchronously, keeping the optimistic value on failure and surfacing `onError`. Swapping a remote adapter changes only *when* bytes hit the wire, never how components read.
+- **Storage** is per-capability opaque envelopes `{ schemaVersion, updatedAt, payload }` with a per-capability `migrate()`; localStorage key `portnet-ui:perso:v1:{tenantId?}:{userId}:{capabilityId}`.
+- **Performance** — split config / store contexts, cached selector subscriptions, structural sharing (sibling slices keep their reference → no cross-capability re-renders), a per-row boolean selector for favorites (only the toggled row re-renders), and a no-op write short-circuit.
+- **React 18 / 19 compatible** — the peer range admits both; no 19-only API is required (19-only behaviour would only ever be a guarded enhancement).
+
+### Validation records
+
+- `docs/PERSONALIZATION_RESPONSIVE_VALIDATION.md` — responsive review 320→1920 (**PASS**; `FavoritesFilter` `fullWidth` added; mobile-card favorites guidance).
+- `docs/PERSONALIZATION_A11Y_VALIDATION.md` — WCAG 2.2 AA review (**PASS**; apply-button accessible name reflects the visible default badge, 2.5.3).
+- `docs/PERSONALIZATION_PERF_VALIDATION.md` — performance review grounded in the actual store / selector / hook / provider source (**PASS**; re-render-optimal as built).
+
+Runtime confirmation (axe-core, Playwright keyboard / timing, React Profiler commit counts, screen-reader spot-checks) is delegated to the Storybook stories + CI.
+
+### Storybook
+
+Stories under `src/stories/v2/`, grouped as `V2/Personalization/*`: `FavoriteToggle`, `FavoritesFilter`, `SaveFilterDialog`, `SavedFiltersMenu`, and a Favorites-in-DataGrid integration (Basic + the full filter / sort / saved-filters composition). Connected stories use `createMemoryAdapter` for deterministic, isolated state, seeded via the provider `defaults` prop.
+
+### Phase 1 scope
+
+- Persistence is **localStorage only**; the adapter contract is remote-ready (a REST / backend adapter is a drop-in for a later phase).
+- `shared` is **modelled but not enforced** locally — it round-trips for a future backend and lets the UI show a shared indicator.
+- Density stays a global concern (`useDensity`); the personalization store does not own it.
+
+### Metadata
+
+- `package.json.version`: `0.5.0-react19.1` → `0.6.0-react19.1`.
+- `VERSION` constant in `src/lib/v2/index.js` synced to `"0.6.0-react19.1"` — manual single-source-of-truth sync per the B6-EXT-1 invariant.
+- New `exports` subpaths `./personalization` and `./v2/personalization`.
+- Runtime dependency `uuid` (`^9`) — used to mint saved-filter ids.
+
+### No breaking changes
+
+Every existing v2 import resolves the same export with the same signature. The only change to an existing component is the additive, optional `DataGridToolbar` `actions` node slot.
+
+---
+
+## [0.4.0-react19.1] — 2026-05-22 (pre-release)
+
+> **Theme**: React 18.3 → 19 platform foundation migration. Storybook 6/7 → 8 (the first SB major with formal React 19 support). v2 Design System surface remains byte-for-byte unchanged.
+
+This release upgrades the platform foundation to React 19 while preserving every v2 component API and visual contract. Consuming modules already on `0.3.0-mui9.1` upgrade transparently — the migration is **opt-in at the consumer level**: apps still on React 18 keep working unchanged (peer range admits both majors via the canonical R18→R19 union pattern), apps on React 19 are now explicitly supported.
+
+The complete migration documentation lives under `docs/migration-react19/`:
+
+| Doc | Batch | Scope |
+|---|---|---|
+| `01-analysis-and-plan.md` | 1 | Dependency analysis + 8-batch incremental roadmap |
+| `02-batch2-react-bump.md` | 2 | React + ReactDOM upgrade to v19 |
+| `03-batch3-peer-deps.md` | 3 | Peer / tooling compatibility (formik, emotion) |
+| `04-batch4-audit.md` + `04-batch4-grep.sh` | 4 | Exhaustive component R19 audit + regression-guard grep script |
+| `05-batch5-storybook-v8.md` | 5 | Storybook 6/7 → 8 framework migration |
+| `05_1-batch5_1-v2-skeleton-stories.md` | 5.1 | First three v2 stories (Button, Modal, DataGrid) |
+| `06-batch6-validation.md` | 6 | A11y + rendering validation contract |
+| `06_1-batch6_1-additional-stories.md` | 6.1 | Five additional v2 stories (Drawer, Tooltip, CommandPalette, OverflowMenu, DatePicker) |
+| `07-batch7-cleanup-and-followups.md` | 7 | Workaround audit + consolidated follow-ups registry |
+| `08-batch8-final-validation.md` | 8 | Final validation contract + MR readiness |
+
+### Foundation changes
+
+#### React 19 runtime (Batch 2)
+- `devDependencies.react`: `^18.3.1` → `^19.0.0`
+- `devDependencies.react-dom`: `^18.3.1` → `^19.0.0`
+- `peerDependencies.react`: `>=18.0.0` → `^18.0.0 || ^19.0.0` (canonical ecosystem union — consumer apps on R18 remain supported)
+- `peerDependencies.react-dom`: `>=18.0.0` → `^18.0.0 || ^19.0.0`
+
+#### Peer + devDep alignment (Batch 3)
+- `peerDependencies.formik`: `>=2.2.0` → `>=2.4.0` (calibrated tightening — formik is a direct dep via the 8 Formik adapters in `src/lib/v2/patterns/`)
+- `devDependencies.@emotion/react`: `^11.13.0` → `^11.14.0` (first emotion release explicitly declaring R19 in its peer range)
+- `devDependencies.@emotion/styled`: `^11.13.0` → `^11.14.0`
+- `devDependencies.formik`: `^2.2.9` → `^2.4.5`
+
+Transitive deps left untouched at the peer level by design — only directly-imported deps justify a peer-range tightening. `react-transition-group` and `@emotion/*` peer ranges intentionally remain at their pre-migration floors; MUI v9 pilots their resolution.
+
+#### Storybook 8 migration (Batch 5)
+
+Resolves the "Storybook 6.x → 8 migration" item explicitly listed in the 0.3.0-mui9.0 "Out of scope (deferred to 0.4.0)" section.
+
+- `.storybook/main.js` migrated from SB 6/7 schema to SB 8:
+  - `framework`: string `"@storybook/react"` → object `{ name: "@storybook/react-webpack5", options: {} }`
+  - `core.builder`: removed (now subsumed by the framework key)
+  - addon `@storybook/preset-create-react-app`: removed (deleted upstream in SB 8 — CSS, JSX, and asset handling are now built into `@storybook/react-webpack5` directly)
+  - `docs.autodocs`: `true` → `"tag"` (per-story opt-in via `tags: ["autodocs"]` — SB 8 convention)
+  - CommonJS `module.exports` → ESM `export default`
+- `.storybook/manager.js`: `@storybook/addons` → `@storybook/manager-api` (package renamed in SB 8). `addons.setConfig` API surface unchanged.
+- `.storybook/preview.js`, `.storybook/defaultTheme.js`: unchanged — already SB 8 compatible.
+
+Eight Storybook 8 packages declared explicitly in `devDependencies` (previously resolved externally via private registry / hoisted workspace):
+- `storybook` (CLI)
+- `@storybook/react` (renderer)
+- `@storybook/react-webpack5` (framework)
+- `@storybook/addon-essentials`, `@storybook/addon-links`, `@storybook/addon-interactions`
+- `@storybook/manager-api` (consumed by `manager.js`)
+- `@storybook/theming` (consumed by `defaultTheme.js`)
+
+All at `^8.0.0` floor — explicit major lock to v8.x; no silent jump to v9.
+
+Three new scripts:
+- `storybook` → `storybook dev -p 6006`
+- `build-storybook` → `storybook build`
+- `storybook:clean` → `rimraf storybook-static`
+
+The Dockerfile already expected `./storybook-static/` at COPY time; `npm run build-storybook` now produces it as a documented script.
+
+### R19 compatibility — verified exhaustively (Batch 4)
+
+The executable grep script at `docs/migration-react19/04-batch4-grep.sh` validates the entire `src/lib/v2/**` tree against every R19 blocker pattern. **All zero**:
+
+| Blocker pattern | Hits in `src/lib/v2/**` |
+|---|---|
+| `findDOMNode` | 0 |
+| String refs (`ref="literal"`) | 0 |
+| `.defaultProps =` on function components | 0 (destructured defaults used throughout) |
+| Legacy lifecycles (`componentWillMount` / `componentWillReceiveProps` / `componentWillUpdate` / `UNSAFE_*` aliases) | 0 (codebase is 100% functional components) |
+| `ReactDOM.render` / `unmountComponentAtNode` / `hydrate` | 0 (`src/index.js` already on `createRoot` pre-migration) |
+| `React.createFactory` | 0 |
+| `react-test-renderer/shallow`, `react-dom/test-utils` | 0 |
+
+The grep script is committed to `docs/migration-react19/04-batch4-grep.sh` as a permanent regression guard. Recommended CI integration: pre-merge gate on every MR touching `src/lib/v2/**`.
+
+### Storybook coverage (Batches 5.1 + 6.1)
+
+Eight v2 stories landed under `src/stories/v2/`, exercising every R19-relevant signal Batch 4 inventoried:
+
+| Story path | Batch | R19 signals exercised |
+|---|---|---|
+| `V2/Components/Button` | 5.1 | `React.forwardRef` chain through MUI v9 |
+| `V2/Components/Modal` | 5.1 | `useId` + `useFocusTrap` + `slotProps.paper.ref` + zIndex 1350 |
+| `V2/Components/Drawer` | 6.1 | Focus trap + J/K navigation + `isEditableTarget` gating + Modal-from-Drawer stacking |
+| `V2/Components/Tooltip` | 6.1 | `cloneElement` aria-label injection + disabled-trigger span wrap |
+| `V2/Components/CommandPalette` | 6.1 | Full ARIA combobox + fuzzy matching + diacritics folding + Cmd+K shortcut |
+| `V2/Components/OverflowMenu` | 6.1 | Menu pattern + chained `onClick` on custom trigger + >7-item dev warn |
+| `V2/Components/DatePicker` | 6.1 | MUI X v9 slotProps + Date/moment boundary + `MODAL_POPPER_PROPS` spread inside Drawer |
+| `V2/Patterns/DataGrid` | 5.1 | Heaviest hook concentration: `useMemo` / `useEffect` via `useAriaLabelWarn` / `useMediaQuery` / `useTheme` / `useDelayedFlag` |
+
+These are skeleton stories — minimum-viable smoke-test coverage. Full Pui*→v2 story rewrites are tracked as Batch 7 P2-C.
+
+### No public API change
+
+**Zero modification to any file under `src/lib/v2/**`**. Every consumer import continues to resolve the same export with the same signature. The migration is purely tooling and metadata.
+
+### Accessibility + rendering validation (Batch 6)
+
+Operator-runnable validation contract under `docs/migration-react19/06-batch6-validation.md` §5 with eleven sections covering Modal / Drawer / ConfirmDialog / Tooltip / CommandPalette / OverflowMenu / Toast / DataGrid / DatePicker plus a console-warning baseline and a React DevTools concurrent-rendering verification track.
+
+The contract is the safety net for the platform's a11y + R19 StrictMode + portal stacking behaviour. Run before merging.
+
+### Metadata
+
+- `VERSION` constant in `src/lib/v2/index.js` bumped to `"0.4.0-react19.1"` — **manual sync with `package.json.version`** per the established footgun mitigation (B6-EXT-1 of 0.3.0-mui9.1). Build-time generation still tracked as Batch 7 P3 backlog.
+- `package.json.version`: `0.3.0-mui9.1` → `0.4.0-react19.1`
+- `package.json.description`: amended with "React 19 ready" signal
+- `package.json.keywords`: added `"react19"`
+
+### Backlog 0.4.0 — status update vs 0.3.0-mui9.1 entry
+
+The 0.3.0-mui9.1 changelog listed ten "Backlog 0.4.0" items. Status after this release:
+
+| Source | Item | Status post-0.4.0-react19.1 |
+|---|---|---|
+| B1-6 | `.npmrc legacy-peer-deps=true` removal | **NOT ADDRESSED** — coupled to the MUI v9 fork peer-widening (Batch 7 P1-A) |
+| B2-EXT-4 | `v2.Select` Switch-style gap | NOT ADDRESSED — hygiene (Batch 7 P3 candidate) |
+| B2-5/B2-6 | `cssVariables: true` adoption | NOT ADDRESSED — architectural 0.5.0+ change |
+| B2-7 / B4-EXT-3 | brandSecondary teal text contrast | NOT ADDRESSED — design-system concern, separate ticket |
+| B4-EXT-3 | borderStrong contrast | NOT ADDRESSED — same |
+| B5-1 | WCAG 2.5.5 tactile on FilterTab / Segmented / NumberInput | NOT ADDRESSED — charter exception assumed |
+| B6-3 | ActionBar inline-sx hoisting | NOT ADDRESSED — perf marginal |
+| B6-4 | `useColumnResize` rAF debouncing | NOT ADDRESSED — perf sub-frame on 144Hz+ |
+| B6-EXT-2 | `moment` → `dayjs` / `date-fns` | **PROMOTED** to Batch 7 P3-A — DSI coordination still required |
+| B6-EXT-1 fu | `VERSION` constant build-time generation | **PROMOTED** to Batch 7 P3 hygiene |
+
+This release intentionally did NOT bundle the Backlog 0.4.0 items — each is independent of the React 19 migration and bundling them would have diluted the diff and complicated rollback. They remain tracked.
+
+### Consolidated post-release follow-ups
+
+`docs/migration-react19/07-batch7-cleanup-and-followups.md` §3 organises 21 deferred concerns by priority (P1-P4) with source batch, defer rationale, trigger conditions, effort estimates, and ownership suggestions. Highlights:
+
+- **P1-A** — MUI v9 internal fork peer-range widening (external dep — internal MUI v9 team)
+- **P1-B** — `src/index.js` broken Pui v1 import (coupled to P2-A — CRA replacement)
+- **P2-A** — CRA → Vite dev playground replacement (1-2 dev-days)
+- **P2-B** — ESLint flat-config migration (0.5-1 dev-day, after P2-A)
+- **P2-C** — Stale v1 Pui* stories rewrite OR delete (~30 stories)
+- **P2-D** — `@storybook/addon-a11y` integration (1 dev-day)
+- **P2-E** — Visual regression Chromatic / Loki / Percy (2-3 dev-days)
+- **P3** — Hygiene bumps (`moment`, `uuid` v10, `@tanstack/react-virtual`, `yup` v1, `@babel/*`) + legacy `src/lib/components/` deletion
+- **P4** — Strategic: TypeScript migration, Formik replacement, Storybook 8 → 9, MUI v9 fork alignment
+
+### Known limitations carried forward
+
+- **Physical v1 file deletion** (same as 0.3.0-mui9.1) — GitLab MCP server doesn't expose `delete_file`. The 49 v1 files tombstoned in 0.3.0 remain on disk; needs `git rm` run by operator. Tracked.
+- **`src/index.js` + `src/App.js` broken** — both reference v1 Pui* components purged in 0.3.0. The dev playground is irrecoverable without a full rewrite; Storybook 8 (this release) replaces its role. Tracked as Batch 7 P1-B + P2-A.
+- **MUI v9 internal fork peer range** — same dep coupling as 0.3.0-mui9.1; clean `npm install` may require `--legacy-peer-deps` until P1-A resolves upstream.
+- **README not touched in this release** — automated README update via the GitLab MCP was blocked by repeated transient timeouts during Batch 8. Recommended manual touch-up: add a "React 19 ready" note + link to `docs/migration-react19/01-analysis-and-plan.md`. Trivial; operator runs locally as Batch 8.1.
+- **Storybook stale Pui* stories** — the legacy `src/stories/content/Pui*.stories.jsx` files surface per-story import errors in the SB 8 UI. SB 8 isolates these failures so the global build still exits 0. Tracked as Batch 7 P2-C.
+
+### Verification commands
+
+```bash
+# Regression guard (must exit 0):
+bash docs/migration-react19/04-batch4-grep.sh
+
+# Babel build (must produce dist/ with same module count as baseline):
+npm run build
+
+# Storybook 8 boot (must serve on :6006):
+npm run storybook
+
+# Storybook 8 static build (must exit 0 — per-story Pui* warnings tolerated):
+npm run build-storybook
+
+# Single-copy React resolution sanity:
+npm ls react react-dom
+```
+
+---
+
+## [0.3.0-mui9.1] — 2026-05-22 (pre-release)
+
+> **Theme**: Post-internal-audit fixes (internal Batch 6) + 7 external release-gate fixes from an independent second-pass audit.
+
+This release iterates on `0.3.0-mui9.0` with non-API-breaking polish + 1 critical a11y fix (B4-EXT-1 heading hierarchy on error pages). Hosts already on `0.3.0-mui9.0` upgrade transparently — no migration steps required for the `*-mui9.1` increment beyond what was already documented for `*-mui9.0`.
+
+### Critical accessibility fixes (audit external Batch 4)
+
+- **`_ErrorPageBody` heading hierarchy** (B4-EXT-1) — WCAG 1.3.1 + 2.4.6. Every error page (ForbiddenPage, NotFoundPage, ServerErrorPage, NetworkErrorPage) was rendering TWO `<h1>` elements: one from ActionBar (`title="Accès refusé"`) and one from ErrorPageBody (`code="403"`). The visually-dominant heading contained only the HTTP code, so SR users navigating by `H` key heard "403" instead of "Accès refusé". The semantic title ("Vous n'avez pas accès à cette page") was a non-heading `<Box>`. The fix:
+  - HTTP code becomes `<div aria-hidden="true">` (visual ornament, AT-invisible)
+  - Title promoted to `<h2>` (sits in hierarchy under ActionBar `<h1>`)
+  - Visual contract unchanged (font-size/weight tokens preserved)
+
+- **`FormErrorSummary` jump-button focus** (B4-EXT-2) — R-F.1 / WCAG 2.4.7 defensive. Jump-buttons used inline `style={{...}}` which left the browser default focus ring on `danger-soft` background (~2:1 contrast, poorly visible). Migrated to `Box component="button" sx={...}` with explicit `:focus-visible` outline on `var(--danger-fg)` (6.94:1 verified on danger-soft).
+
+### Switch-style MUI v9 atoms (audit external Batch 2)
+
+The MUI v9 v5/v6 → v9 migration centred on the `inputProps` → `slotProps.input` "Switch-style" routing. Internal Batch 3 fixed `Input.js` and `NumberInput.js`. External Batch 2 found 3 atoms that had the same gap but weren't caught:
+
+- **`Checkbox.js`** (B2-EXT-1) — routes `inputProps={...}` through `slotProps.input` so canonical v5 idiom `inputProps={{'aria-label': '...'}}` reaches the native `<input type="checkbox">` instead of dying on the wrapper.
+- **`Radio.js`** (B2-EXT-2) — same fix on the single `Radio` export. `RadioGroup` was already fixed by internal B3-3.
+- **`Textarea.js`** (B2-EXT-3) — same fix.
+
+These were prophylactic — the consumer-facing impact in v9 was silent prop-loss, not a crash, but it would have shipped silently broken contracts to every host using the canonical v5 idiom on these atoms.
+
+### Internal coherence (audit external Batch 5)
+
+- **`FormPageShell.defaultProps`** (B5-EXT-1) → migrated to inline default parameters. DataGridToolbar had already migrated in Batch 14 with an explicit "`defaultProps` SUPPRIMÉ" comment; FormPageShell was inconsistently left on the old pattern. React 18.3+ deprecates `defaultProps` on function components (emits warning at every mount; cease to work in React 19). This was a Bastien & Scapin Homogénéité/Cohérence + Nielsen H4 violation on top of the React deprecation.
+
+### Metadata (audit external Batch 6)
+
+- **`VERSION` constant** (B6-EXT-1) — synced from stale `"0.1.4"` to `"0.3.0-mui9.1"`. The constant exported by `src/lib/v2/index.js` had drifted across the entire v0.2.x cycle + MUI v9 migration. Any host introspecting the version (analytics, debug panes, DSI dashboards, error reports) was getting a falsified string. Backlog 0.4.0 candidate: generate at build via `babel-plugin-transform-define`.
+
+### Verified post-internal-audit (no new fixes)
+
+External audits Batches 1, 3 reconfirmed all internal findings without divergence:
+- **Batch 1 (theme + styling)** — 9 internal B2 findings reconfirmed.
+- **Batch 3 (complex shared components)** — 22 composites + 6 Formik bridges reconfirmed clean, no v9 deprecation residue.
+
+### Backlog 0.4.0 (documented, NOT fixed in 9.1)
+
+| Source | Item | Reason for deferral |
+|---|---|---|
+| B1-6 | `.npmrc legacy-peer-deps=true` removal | needs `npm install --strict-peer-deps` local validation |
+| B2-EXT-4 | `v2.Select` Switch-style gap | MuiSelect slot mapping non-trivial (hidden input for form submit), low consumer risk |
+| B2-5/B2-6 | `cssVariables: true` adoption | architectural 0.4.0 change |
+| B2-7 / B4-EXT-3 (revised) | `brandSecondary` teal text contrast 2.31:1 | recommend `ink.fg` on teal (7.87:1) as default text in 0.4.0 |
+| B4-EXT-3 | `borderStrong` contrast 2.87:1 light / 2.41:1 dark | WCAG 1.4.11 marginal, non-text usage acceptable for 0.3.0 |
+| B5-1 charter exception | WCAG 2.5.5 tactile on `FilterTab`/`Segmented`/`NumberInput` stepper | charter exception assumée — consider `size="lg"` AAA opt-in |
+| B6-3 | `ActionBar` inline sx hoisting | perf marginal (renders once per page) |
+| B6-4 | `useColumnResize` rAF debouncing | perf sub-frame on 144 Hz+ screens, React 18 auto-batching covers 80% |
+| **B6-EXT-2** | **`moment` → `dayjs` / `date-fns`** | **RGESN R-7.5 sobriété — ~280 KB economy per host bundle. Breaking change for hosts using moment elsewhere — DSI coordination required.** |
+| B6-EXT-1 follow-up | VERSION constant generated at build time | eliminate manual-sync footgun |
+
+### Known limitations (carried forward from 9.0)
+
+- **Physical v1 file deletion**: GitLab MCP server doesn't expose `delete_file`. The 49 v1 files were tombstoned via the index/exports but their physical bytes remain in the working tree until Nabil runs the `git rm` block documented in `docs/migration-mui9/03-batch3-purge-v1.md` §5.
+- **`docs/migration-mui9/.probe.txt`** — transient probe file from external audit Batch 2 that the MCP could not delete. Needs `git rm docs/migration-mui9/.probe.txt` Nabil-side.
+- **MUI X DataPickers default endAdornment forwarding** — workaround in place in v2.Combobox, validate in Storybook.
+
+---
+
+## [0.3.0-mui9.0] — 2026-05-21 (pre-release)
+
+> **Theme**: MUI ecosystem v5 → v9 baseline migration. v1 Pui* legacy purged.
+
+This is a **major breaking release**. Consuming modules must follow the migration guide in `docs/migration-mui9/03-batch3-purge-v1.md` (§7 table).
+
+### Breaking changes
+
+- **MUI ecosystem peer bumped to v9**:
+  - `@mui/material` ^5.10 → ^9.0
+  - `@mui/icons-material` ^5 → ^9
+  - `@mui/x-date-pickers` ^5 → ^9 (new application-based licensing model — verify with DSI)
+  - `@mui/system` ^9.0 declared explicitly (was transitive in v5)
+  - React floor raised to `>=18`
+  - Emotion floor raised to `^11.13`
+- **v1 `Pui*` surface entirely removed**. All ~12 consuming modules (TradeDirect, PMPCE, gestionTI, ms-ti-fe, etc.) must migrate to the v2 namespace. See migration table in Batch 3 §7.
+- **Package exports flattened**:
+  - `import { Button } from "@portnet/ui"` ← was `@portnet/ui/v2`
+  - `import { createPortnetTheme } from "@portnet/ui/theme"` ← was `@portnet/ui/v2/theme`
+  - Legacy `@portnet/ui/v2/*` subpaths kept transitionally and scheduled for removal in 0.4.0.
+- **`@mui/lab` dropped** from peer dependencies — zero v2 callsites detected (audit Batch 5).
+- **`@mui/x-data-grid` dropped** from peer dependencies — v2 DataGrid is a clean-slate Table-based implementation, no MUI X DataGrid surface ever used.
+- **`axios` and `moment`** removed from runtime dependencies — were only used by v1 hooks (useAxios, useQuery, useAlert) and v1 referentiel components.
+- **Browserslist tightened** to MUI v9 minimum targets: Chrome 117+, Edge 121+, Firefox 121+, Safari 17+, iOS Safari 17+.
+- **`dl` deprecated alias removed** from `@portnet/ui/v2/tokens` (was tombstoned since 0.2.x for removal in 0.3.0). Migration:
+  ```diff
+  - import { dl } from "@portnet/ui/v2/tokens";
+  + import { densityLayout } from "@portnet/ui/v2/tokens";
+  ```
+  Trivially scriptable across hosts: `grep -rn 'from "@portnet/ui[^"]*tokens"' src | xargs sed -i 's/\bdl\b/densityLayout/g'`. Audit Batch 6 (resolves Batch 2 finding B2-8).
+- **`MODAL_POPPER_PROPS` migrated to slotProps**. The previous shape used `componentsProps` (Combobox) and `PopperProps` (DatePicker) — both removed in MUI v9, making the constant silently broken in v9 builds before this fix. New shape is symmetric: both `combobox` and `datepicker` keys are spread, both carry `{ slotProps: { popper: { sx: { zIndex: 1400 } } } }`:
+  ```diff
+  // Combobox / FormikCombobox inside a Drawer
+  - <FormikCombobox {...MODAL_POPPER_PROPS.combobox} />  // visually identical, but inner shape migrated
+  + <FormikCombobox {...MODAL_POPPER_PROPS.combobox} />  // now actually works in v9
+
+  // DatePicker / FormikDatePicker inside a Drawer
+  - <FormikDatePicker PopperProps={MODAL_POPPER_PROPS.datepicker} />  // was already broken in v9
+  + <FormikDatePicker {...MODAL_POPPER_PROPS.datepicker} />            // symmetric with combobox
+  ```
+  Hosts using `PopperProps={...}` syntax MUST update to spread. Audit Batch 6 (B6-1).
+
+### Migration table (consuming modules)
+
+See `docs/migration-mui9/03-batch3-purge-v1.md` §7 for the exhaustive `Pui* → v2` mapping. Highlights:
+
+| v1 (removed) | v2 (replacement) |
+|---|---|
+| `PuiButton` | `Button` |
+| `PuiTextField` | `<Field><Input /></Field>` |
+| `PuiAutocomplete` | `Combobox` |
+| `PuiDialog` | `Modal` |
+| `PuiDateField` | `DatePicker` (inside `<Field>`) |
+| `PuiGrid container item xs={...}` | `FormGrid columns={N}` (CSS Grid) |
+| `PuiTable` | `DataGrid` (pattern) |
+| `PuiTooltip` | `Tooltip` |
+| `useAlert` | `useToast` |
+
+### MUI v9 surface refactors (no public API change for v2 consumers)
+
+- `Tabs.TabIndicatorProps` → `slotProps.indicator`
+- `Combobox` Autocomplete `renderInput` → TextField `slotProps.input`
+- `Modal` Dialog `PaperProps`/`BackdropProps` → `slotProps.{paper,backdrop}`
+- `Drawer` `PaperProps` → `slotProps.paper`
+- `OverflowMenu` `MenuListProps` → `slotProps.list`
+- `CommandPalette` Dialog `PaperProps`/`BackdropProps` → `slotProps.{paper,backdrop}`
+- `Modal.MuiTextField.defaultProps.InputLabelProps` → `slotProps.inputLabel` (theme override)
+- `DatePicker`/`DateTimePicker`/`TimePicker` v5 `renderInput`+`inputFormat`+`mask` → v9 `slotProps.textField`+`format` (MUI X v6+ field components API)
+- `DataGridSettingsMenu`/`ColumnsToggle` Popover `PaperProps` → `slotProps.paper`
+- `DataGrid`/`DataGridVirtualized`/`DataGridSettingsMenu`/`ColumnsToggle` Checkbox `inputProps` → `slotProps.input`
+- `Input` `inputProps` → `slotProps.input` (audit Batch 3, B3-1)
+- `NumberInput` aria spinbutton contract via `inputProps` → `slotProps.input` (audit Batch 3, B3-2 — critical a11y for financial forms)
+- `MODAL_POPPER_PROPS` (modalContext) `componentsProps`/`PopperProps` → `slotProps.popper` (audit Batch 6, B6-1 — see Breaking Changes)
+
+### Accessibility (audit Batch 5)
+
+- `RadioGroup` option `helper` text linked to inner `<input type="radio">` via `aria-describedby` (B3-3). SR users now hear the helper alongside the label.
+- `ReferentielField` trigger aria-* (haspopup, expanded, invalid, required, describedby) routed through `inputProps` → `slotProps.input` so they land on the focusable `<input/>` rather than the OutlinedInput wrapper `<div>` (B4-3). The combobox/disclosure nature of the trigger is now exposed to AT.
+- `FieldHelp` popover trigger carries `aria-haspopup="dialog"` + `aria-expanded` (B5-1).
+- `ProgressBar` `helper` linked via `aria-describedby` so qualitative context reaches AT alongside `aria-valuenow` (B5-2).
+
+### Internal
+
+- Theme override on `MuiTextField.defaultProps` updated to v9 slotProps (`InputLabelProps` → `slotProps.inputLabel`).
+- Color-mix(in srgb, …) tokens preserved — already aligned with v9 CSS variable theming.
+- `package.json` `sideEffects` switched from `false` to an array (`["*.css", "./dist/v2/styles/index.js", "./dist/v2/styles/base.css"]`) so bundlers preserve the CSS import while keeping JS tree-shaking gains. Without this fix, webpack 5 strict tree-shake could drop `base.css` from production builds (audit Batch 6, B6-2).
+
+### Out of scope (deferred to 0.4.0)
+
+- Removal of transitional alias `@portnet/ui/v2` namespace + `v2.*` re-export at root.
+- Storybook 6.x → 8 migration (Storybook 6 is EOL since 2024).
+- Performance benchmark on `sx` prop (MUI v9 announces +30% perf on heavy `sx` usage — to confirm).
+- Exhaustive runtime audit of the 30+ v2 components not formally scanned in Batches 3-5 (relying on MUI v9 dev warnings + Storybook validation instead).
+- `.npmrc legacy-peer-deps=true` removal — needs a local clean-install validation with MUI v9 peer ranges (audit Batch 6, B1-6 deferred).
+- ActionBar inline-sx hoisting (audit Batch 6, B6-3 — non-blocking, polish for high-frequency re-render scenarios).
+- `useColumnResize` requestAnimationFrame debouncing during mousemove (audit Batch 6 — polish, sub-frame perf gain on 144Hz screens).
+
+### Known limitations
+
+- **Lifecycle of physical file deletion (v1 purge)**: the GitLab MCP server used during this migration does not expose `delete_file`. The 49 v1 files were tombstoned via the index/exports but their physical bytes remain in the working tree until Nabil runs the `git rm` block documented in `docs/migration-mui9/03-batch3-purge-v1.md` §5.
+- **MUI X DataPickers default endAdornment forwarding** (issue mui/material-ui#46911): edge case where Autocomplete + Combobox migration of `params.InputProps` to `slotProps.input` may drop the default dropdown adornment. v2.Combobox re-injects the adornment explicitly inside `slotProps.input.endAdornment` to work around this — to validate in Storybook.
+
+---
+
+## [0.2.x] — historical
+
+The 0.2.x series shipped the v1 Pui* surface on MUI v5. See git history for incremental changes. Future maintenance on the 0.2.x branch is not planned — all consumers are expected to migrate to 0.3.x.