@portnet/ui 5.0.32 → 6.0.1

package/README.md

@@ -1,70 +1,133 @@
-# Getting Started with Create React App
+# `@portnet/ui`
 
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+React component library for **PORTNET S.A.** Guichet Unique platforms (TradeDirect, PMPCE, GU2). Aligned with the **UX/UI Charter — Design System v1.0** for Guichet Unique. Built on **Material UI 9 + React 19**.
 
-## Available Scripts
+> ⚛️ **React 19 ready** since `0.4.0-react19.1`. Peer range admits both React 18 and React 19 — consumer apps on either major are supported. See [`docs/migration-react19/01-analysis-and-plan.md`](docs/migration-react19/01-analysis-and-plan.md) for the migration narrative.
 
-In the project directory, you can run:
+The library exposes a single v2 namespace at the package root. The legacy `Pui*` (v1) surface was removed in `0.3.0-mui9.0` — all consumers migrated to v2. See [`docs/migration-mui9/`](docs/migration-mui9/) for the v1 → v2 migration history.
 
-### `npm start`
+---
 
-Runs the app in the development mode.\
-Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
+## Install
 
-The page will reload when you make changes.\
-You may also see any lint errors in the console.
+```bash
+npm install @portnet/ui
+```
 
-### `npm test`
+Peer dependencies:
+- `react` `^18.0.0 || ^19.0.0`
+- `react-dom` `^18.0.0 || ^19.0.0`
+- `@mui/material` `^9.0.0`
+- `@mui/icons-material` `^9.0.0`
+- `@mui/system` `^9.0.0`
+- `@mui/x-date-pickers` `^9.0.0` *(optional — only needed if you use DatePicker / DateTimePicker / TimePicker)*
+- `@emotion/react` `>=11.13.0`
+- `@emotion/styled` `>=11.13.0`
+- `formik` `>=2.4.0` *(optional — only needed for the `Formik*` adapter components)*
+- `prop-types` `>=15.8.0`
+- `react-transition-group` `>=4.4.0`
 
-Launches the test runner in the interactive watch mode.\
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+*Note*: until the internal MUI v9 fork's peer range is widened to include React 19, clean install on R19 host apps may require `npm install --legacy-peer-deps`. Tracked as Batch 7 P1-A.
 
-### `npm run build`
+---
 
-Builds the app for production to the `build` folder.\
-It correctly bundles React in production mode and optimizes the build for the best performance.
+## 5-minute boot
 
-The build is minified and the filenames include the hashes.\
-Your app is ready to be deployed!
+Mount once at app entry:
 
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+```jsx
+import * as React from "react";
+import ReactDOM from "react-dom/client";
+import { ThemeProvider } from "@mui/material/styles";
+import {
+  injectCssVariables,
+  createPortnetTheme,
+  ToastProvider,
+  SkipLink,
+} from "@portnet/ui";
+import "@portnet/ui/styles";
 
-### `npm run eject`
+injectCssVariables();
+const theme = createPortnetTheme({ mode: "light", density: "comfortable" });
 
-**Note: this is a one-way operation. Once you `eject`, you can't go back!**
+ReactDOM.createRoot(document.getElementById("root")).render(
+  <ThemeProvider theme={theme}>
+    <ToastProvider>
+      <SkipLink href="#main-content" />
+      <App />
+    </ToastProvider>
+  </ThemeProvider>
+);
+```
 
-If you aren't satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
+For host-level brand override (TIJARIA, partner deployments, AfCFTA white-labelling), pass the same `{ brand }` object to both `injectCssVariables` and `createPortnetTheme`. Default brand is Portnet navy `#232F66`. See [`docs/V2_MIGRATION.md §7`](docs/V2_MIGRATION.md) for the full pattern.
 
-Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own.
+---
 
-You don't have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it.
+## What's inside
 
-## Learn More
+- **Tokens** — single source of truth (`tokens.json` + JS modules). Colours, typography, spacing, radius, shadows, motion, z-index, density, layout. Two parallel palettes: workflow status (six canonical keys) and semantic (success / warning / danger / info, each with paired fill + `*-fg` text tokens for WCAG 1.4.3).
+- **Theme** — `createPortnetTheme` (MUI factory) + `injectCssVariables` (`:root` emitter), both reading the same tokens. MUI v9 slot API throughout.
+- **Components** — charter primitives across the v2 surface: Button, Field/Input/Select/Textarea/Checkbox/Radio/Switch/Combobox/NumberInput/DatePicker/Dropzone, Status/Chip/KPICard/KV, Modal/Drawer/ConfirmDialog/Tabs/Stepper/FilterTab/Segmented, EmptyState/Banner/Skeleton family/Spinner, ToastProvider/CommandPalette/OverflowMenu/FieldHelp/SkipLink/Tooltip.
+- **Patterns** — composite blocks: ActionBar (sticky page header), BulkActionBar, FormSection, FormPageShell, FormErrorSummary, DataGrid (sticky header, multi-sort, four states, density toggle), DataGridVirtualized, SortableHeader, NetworkErrorBanner, ReferentielField, Tour, KeyboardShortcutsHelp.
+- **Formik adapters** — FormikInput, FormikTextarea, FormikCombobox, FormikDatePicker, FormikFile, FormikCheckboxGroup, FormikReferentielField, FormikDisplay.
+- **Hooks** — `useFocusTrap`, `useTabLoading`, `useDelayedFlag`, `useDensity`, `useResolvedDensity`, `useSortedRows`, `useFormAutoSave`, `useFormCompletionProgress`.
+- **Utils** — `cx`, `fmtMoney` (Intl-based, fr-FR locale), `contrast`.
 
-You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
+---
 
-To learn React, check out the [React documentation](https://reactjs.org/).
+## Docs
 
-### Code Splitting
+| Doc | When to read |
+|---|---|
+| [`docs/migration-react19/`](docs/migration-react19/) | You're migrating a host module to React 19. Eight-batch incremental plan, dependency / peer / component / Storybook / a11y validation contracts, consolidated follow-ups registry. Start with `01-analysis-and-plan.md`. |
+| [`docs/migration-mui9/`](docs/migration-mui9/) | You're migrating from `Pui*` (v1, MUI 5) → v2 (MUI 9). Component-by-component map, Formik adapter, `PuiTable` → `DataGrid` before/after. |
+| [`docs/V2_MIGRATION.md`](docs/V2_MIGRATION.md) | Component-by-component map, Formik adapter, theme customisation incl. brand override, charter compliance checklist. |
+| [`docs/V2_ARCHITECTURE.md`](docs/V2_ARCHITECTURE.md) | You're contributing to the library or evaluating it. Folder structure, design principles, token consumption hierarchy, palette canonicalisation. |
+| [`docs/V2_AUDIT.md`](docs/V2_AUDIT.md) | The historical v1 → v2 audit (May 2026): legacy component classification, 14 findings, refactor priority. |
+| [`CHANGELOG.md`](CHANGELOG.md) | Release notes per version. |
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting)
+**Storybook 8** (in `.storybook/`) showcases each primitive with live props. It is the primary design-system development environment since `0.4.0-react19.1`.
 
-### Analyzing the Bundle Size
+---
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size)
+## Compliance
 
-### Making a Progressive Web App
+Every v2 primitive ships with:
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)
+- **WCAG 2.2 AA contrast** — normal text ≥ 4.5:1; non-text UI ≥ 3:1. Toasts at 6.29 / 6.95 / 7.95:1 (success / warning / danger).
+- **Keyboard support** — `:focus-visible` ring, focus trap on overlays, Esc / backdrop / X dismissal, roving tabindex on radiogroups, Tab/Shift+Tab on tablists.
+- **`prefers-reduced-motion`** — every animation collapses to ≤ 0.01 ms.
+- **French as primary language** — copy in French, locale-formatted numbers (`Intl.NumberFormat("fr-FR")`), French aria-labels on icon-only and delete triggers.
+- **Token discipline** — no hex / px literal outside `/v2/tokens/`, enforced by ESLint rule `portnet/no-magic-color` + `portnet/no-magic-px`.
 
-### Advanced Configuration
+The full charter rule list is in the prototype's source PDF; the migration guide §9 is the per-PR compliance checklist.
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration)
+---
 
-### Deployment
+## Local development
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment)
+```bash
+npm install                  # use --legacy-peer-deps until MUI v9 fork peer is widened (Batch 7 P1-A)
+npm run storybook            # Storybook 8 on http://localhost:6006 — primary dev environment
+npm run build-storybook      # Static Storybook build → ./storybook-static/
+npm run storybook:clean      # Remove the static build
+npm run build                # Babel build of src/lib → dist
+npm run build:clean          # Same, but rm -rf dist first
+```
 
-### `npm run build` fails to minify
+**R19 regression-guard pre-commit check** (recommended):
 
-This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)
+```bash
+bash docs/migration-react19/04-batch4-grep.sh
+```
+
+Must exit 0. Detects re-introduction of any React 19 blocker pattern (`findDOMNode`, string refs, `defaultProps` on function components, legacy lifecycles, `ReactDOM.render`).
+
+---
+
+## Versioning
+
+[Semantic Versioning](https://semver.org), with the addition of `-muiN.M` / `-react19.N` pre-release tags during ecosystem migrations. Current release: `0.4.0-react19.1` (first React-19-ready release on the design system).
+
+The v1 `Pui*` namespace was removed in `0.3.0-mui9.0`. The transitional `@portnet/ui/v2/*` subpath aliases (kept for the v1 → v2 cross-fade) are scheduled for removal in a future `0.5.0+`.

package/dist/esm/index.js

@@ -0,0 +1,196 @@
+/**
+ * @portnet/ui — root entry (MUI v9)
+ *
+ * The v1 Pui* surface was REMOVED in 0.3.0-mui9. The package now
+ * exposes the modernised v2 Design System directly at its root.
+ *
+ * Imports
+ * -------
+ *
+ *   // Components (flat — preferred)
+ *   import { Button, Modal, FormGrid, Combobox, ... } from "@portnet/ui";
+ *
+ *   // Theme + CSS variables + tokens + hooks (flat, or subpath entrypoints)
+ *   import { createPortnetTheme, injectCssVariables } from "@portnet/ui";
+ *   import { palette, spacing }     from "@portnet/ui/tokens";
+ *   import { useFocusTrap }         from "@portnet/ui/hooks";
+ *
+ *   // Misc utils (flat) — class names, money formatting, WCAG contrast,
+ *   // and base64 → browser download
+ *   import { cx, fmtMoney, contrast, downloadBase64File } from "@portnet/ui";
+ *
+ *   // Modal layering constants (flat)
+ *   import { MODAL_POPPER_PROPS, MODAL_ZINDEX } from "@portnet/ui";
+ *
+ *   // Personalization foundation (flat, or "@portnet/ui/personalization")
+ *   import { UserPersonalizationProvider, createLocalStorageAdapter } from "@portnet/ui";
+ *
+ *   // Referentiel data layer (flat) — backs ReferentielField /
+ *   // FormikReferentielField. Mount the provider once at the app root.
+ *   import { ReferentielProvider, useReferentielSearch } from "@portnet/ui";
+ *
+ *   // Domain models + UI types (flat, type-only)
+ *   import type { FavoriteItem, SavedFilter, GridColumn } from "@portnet/ui";
+ *
+ *   // Legacy `@portnet/ui/v2/*` paths still resolve transitionally
+ *   // through the v2 re-export below, deprecated and scheduled for
+ *   // removal in 0.4.0. NOTE: capability added after that deprecation
+ *   // is surfaced flat ONLY and is deliberately absent from `v2.*`.
+ *
+ * No v1 surface remains. Consuming modules that still import any
+ * Pui* component will fail to resolve and must migrate per the
+ * table in docs/migration-mui9/03-batch3-purge-v1.md.
+ */
+
+// Flat re-export of every v2 component, pattern, hook, and the
+// theme factory. This is what consuming modules pin against
+// (`import { Button } from "@portnet/ui"`).
+export * from "./v2/components";
+export * from "./v2/patterns";
+export * from "./v2/hooks";
+export { createPortnetTheme, getCssVariables, injectCssVariables, removeCssVariables } from "./v2/theme";
+
+// Theme factory typed contract, flat + type-only (capability gap G-33).
+//
+// The theme VALUES were flat-exported above while the types describing their
+// options were reachable ONLY from the deprecated `@portnet/ui/v2` subpath.
+// Every host module wraps createPortnetTheme in a local `build<Module>Theme`
+// helper (see the GU modules' utils/appearance), so every host needs this
+// contract to type its own wrapper — and had exactly two ways to get it:
+// import from a surface scheduled for removal in 0.4.0, or fall back to
+// `brand?: object` + `as Parameters<typeof createPortnetTheme>[0]`, both on
+// the Platform TypeScript Guidelines FORBIDDEN list. ./v2/theme's own doc
+// comment already names that anti-pattern as the reason these types were
+// published; it just never reached the surface consumers are told to migrate
+// TO. Closing that here removes the last reason a module needs `@portnet/ui/v2`
+// for the theme layer.
+//
+// Flat-only, per the `v2` policy note at the bottom of this file.
+// Purely additive and type-only; nothing existing changed.
+
+// Added while migrating ms-dfd-fe to TypeScript: cx / fmtMoney / contrast had
+// no flat or subpath route, only the deprecated `v2.*` namespace below.
+// downloadBase64File + getMimeType were added later (mjcc-fe Area 5) and are
+// flat-only by policy — see the note on `v2` at the bottom of this file.
+// Purely additive re-exports; nothing existing changed.
+//
+// G-34 (caution-ui Area 6) — openBase64FileInTab + downloadBlobFile added.
+// These two were NOT flat-only additions: ./v2/index.ts has exported them all
+// along, so the FLAT ROOT — the surface the policy at the bottom of this file
+// tells every module to migrate TO — was a strict SUBSET of the deprecated
+// surface it replaces. A module obeying the migration policy lost access to
+// both, which is how caution-ui's Area 6 build broke:
+//
+//     Attempted import error: 'downloadBlobFile' is not exported
+//     from '@portnet/ui'
+//
+// Root cause is mechanical, and worth fixing properly rather than name by name:
+// ./v2/components, ./v2/patterns and ./v2/hooks are re-exported above with
+// `export *`, so anything added to them surfaces automatically. ./v2/utils is
+// re-exported by EXPLICIT NAME LIST, so every new util silently fails to reach
+// consumers until someone hits a build error. A wildcard is not a safe swap
+// here — ./v2/utils also carries `mergeLabels`, an internal label-merging
+// helper with no host use case, and widening a certified public surface by
+// accident is worse than the drift. The list stays, and the invariant is stated
+// instead: ANY addition to ./v2/utils intended for hosts must be added here in
+// the same commit.
+export { cx, fmtMoney, contrast, downloadBase64File, getMimeType, openBase64FileInTab, downloadBlobFile } from "./v2/utils";
+
+// Error narrowing + the network-status channel. Flat-only per the `v2` policy
+// note at the bottom of this file. Both were added from the
+// procuration-portnet-fe Area 5 gap audit (G-04, G-03):
+//
+//   - getApiErrorMessage / getApiErrorStatus close the hole between two rules
+//     the platform imposes together — `useUnknownInCatchVariables` is mandatory
+//     and `any` / unsafe assertions are forbidden, with nothing sanctioned in
+//     between. Every audited module had bridged it with
+//     `error as { response?: { data?: { message?: unknown } } }`.
+//
+//   - networkStatus is the feed for NetworkErrorBanner, which shipped as a
+//     presentational component with its trigger contract left to consumers.
+//
+// G-34 — getApiErrorDetail added. Its own docstring PRESCRIBES a pairing that
+// was impossible to write, because the companion was never surfaced:
+//
+//     toast(getApiErrorMessage(err, "Échec de l'envoi."), "error");
+//     console.error("[submit]", getApiErrorStatus(err), getApiErrorDetail(err));
+//
+// The split exists because getApiErrorMessage deliberately SUPPRESSES transport
+// phrasings (G-07) — right for a toast, wrong for a console or an APM
+// breadcrumb, where "Request failed with status code 502" is exactly what an
+// operator needs. Without the escape hatch a host either logs the sanitised
+// string (losing the diagnostic) or re-reads `error.message` by hand with an
+// assertion (the very thing G-04 exists to prevent).
+//
+// Purely additive; nothing existing changed.
+export { getApiErrorMessage, getApiErrorDetail, getApiErrorStatus, DEFAULT_API_ERROR_MESSAGE, networkStatus, createNetworkStatus } from "./v2/utils";
+// Route-level Suspense fallback. R-P.1 MUST requires a "fallback skeleton page",
+// and the library had every skeleton PART plus PageBusy, but nothing satisfying
+// the rule: PageBusy is a full-screen spinner, which R-8.1 MUST forbids for
+// navigation. So every module hand-built one, and to avoid the CLS a skeleton
+// exists to prevent it had to copy ActionBar's and PageContent's padding
+// literals out of this library. Owning it here keeps the three in lockstep.
+// Capability gap G-02 (procuration-portnet-fe Area 5). Flat-only, per the policy
+// note below.
+export { default as SkeletonPageShell } from "./v2/patterns/SkeletonPageShell";
+// Modal/Drawer/Combobox/DatePicker layering constants - needed by any
+// consumer stacking a popover-ish component (Combobox, DateTimePicker)
+// above a Modal or Drawer. Was v2-namespace-only.
+export { MODAL_POPPER_PROPS, MODAL_ZINDEX } from "./v2/modalContext";
+
+// Personalization foundation runtime API (favorites, saved filters).
+// Named re-export, not a wildcard: ./v2/personalization also carries
+// the Scope/FavoriteRef/SavedFilter model types for its own internal
+// use, which are already flat-exported canonically via ./v2/models
+// below - a wildcard here would re-export them a second time and
+// collide (TS2308). Mirrors exactly what ./v2/index.ts already does
+// internally for the same reason.
+export { UserPersonalizationProvider, createLocalStorageAdapter, createMemoryAdapter, registerCapability, useFavorites, useIsFavorite, useFavoritesView, filterRowsByFavorites, sortRowsByFavorites, FAVORITES_FILTER, FAVORITES_SORT, useSavedFilters } from "./v2/personalization";
+
+// Referentiel data layer runtime API (config provider + hooks). Backs
+// ReferentielField / FormikReferentielField, which are flat-exported
+// above via ./v2/patterns - the field UI was reachable while the data
+// layer that feeds it was not, so consumers had to either import from
+// the deprecated `@portnet/ui/v2` surface or rebuild the client
+// locally. Added while auditing mjcc-fe, which had done the latter.
+//
+// Named re-export, not a wildcard, for the SAME reason as
+// personalization above: ./v2/referentiel also re-exports
+// ReferentielSearchArgs, ReferentielSearchResult and
+// ReferentielSearchFn for its own use, and those names are already
+// flat-exported canonically through ./v2/models below. A wildcard
+// would export them twice and collide (TS2308). The type layer keeps
+// its single canonical route.
+export { ReferentielProvider, ReferentielContext, useReferentielClient, useReferentielOptions, useReferentielSearch } from "./v2/referentiel";
+
+// Domain models & shared UI/structural types, flat + type-only (no
+// runtime cost). Mirrors the same re-export already done inside
+// ./v2 — added here so consumers migrating off `v2.*` have a route
+// to the shared types the platform guidelines require reusing
+// (DrawerProps, FavoriteItem, SavedFilter, GridColumn, GridAction,
+// WizardStep, Notification, FormField, etc.) without falling back to
+// the deprecated namespace just to get a type import. Conflicting
+// names across the two star-exports are omitted per ES module
+// semantics rather than erroring.
+export * from "./v2/models";
+export * from "./v2/types";
+
+// Transitional alias — the `@portnet/ui/v2` subpath kept resolving
+// for one minor cycle so consuming modules can migrate their
+// imports independently of the package bump. Scheduled removal:
+// 0.4.0. Track removal in the Batch 5 cleanup ticket.
+//
+// POLICY: capability added after this deprecation is surfaced on the
+// flat root ONLY and is not added to ./v2/index.ts — adding it there
+// would hand consumers a new reason to stay on a retiring surface.
+// downloadBase64File / getMimeType are the first such additions.
+//
+// COROLLARY, learned the hard way (G-34): the policy only works if the flat
+// root is a strict SUPERSET of ./v2. It was not — downloadBlobFile and
+// openBase64FileInTab were on v2 and missing here, so "migrate off v2" meant
+// "lose two utilities". Before deprecating anything further, diff the two
+// surfaces; `npm run api:check` covers the root but does not compare it against
+// ./v2.
+import * as _v from "./v2";
+export { _v as v2 };
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["createPortnetTheme","getCssVariables","injectCssVariables","removeCssVariables","cx","fmtMoney","contrast","downloadBase64File","getMimeType","openBase64FileInTab","downloadBlobFile","getApiErrorMessage","getApiErrorDetail","getApiErrorStatus","DEFAULT_API_ERROR_MESSAGE","networkStatus","createNetworkStatus","default","SkeletonPageShell","MODAL_POPPER_PROPS","MODAL_ZINDEX","UserPersonalizationProvider","createLocalStorageAdapter","createMemoryAdapter","registerCapability","useFavorites","useIsFavorite","useFavoritesView","filterRowsByFavorites","sortRowsByFavorites","FAVORITES_FILTER","FAVORITES_SORT","useSavedFilters","ReferentielProvider","ReferentielContext","useReferentielClient","useReferentielOptions","useReferentielSearch","_v","v2"],"sources":["../../src/lib/index.ts"],"sourcesContent":["/**\r\n * @portnet/ui — root entry (MUI v9)\r\n *\r\n * The v1 Pui* surface was REMOVED in 0.3.0-mui9. The package now\r\n * exposes the modernised v2 Design System directly at its root.\r\n *\r\n * Imports\r\n * -------\r\n *\r\n *   // Components (flat — preferred)\r\n *   import { Button, Modal, FormGrid, Combobox, ... } from \"@portnet/ui\";\r\n *\r\n *   // Theme + CSS variables + tokens + hooks (flat, or subpath entrypoints)\r\n *   import { createPortnetTheme, injectCssVariables } from \"@portnet/ui\";\r\n *   import { palette, spacing }     from \"@portnet/ui/tokens\";\r\n *   import { useFocusTrap }         from \"@portnet/ui/hooks\";\r\n *\r\n *   // Misc utils (flat) — class names, money formatting, WCAG contrast,\r\n *   // and base64 → browser download\r\n *   import { cx, fmtMoney, contrast, downloadBase64File } from \"@portnet/ui\";\r\n *\r\n *   // Modal layering constants (flat)\r\n *   import { MODAL_POPPER_PROPS, MODAL_ZINDEX } from \"@portnet/ui\";\r\n *\r\n *   // Personalization foundation (flat, or \"@portnet/ui/personalization\")\r\n *   import { UserPersonalizationProvider, createLocalStorageAdapter } from \"@portnet/ui\";\r\n *\r\n *   // Referentiel data layer (flat) — backs ReferentielField /\r\n *   // FormikReferentielField. Mount the provider once at the app root.\r\n *   import { ReferentielProvider, useReferentielSearch } from \"@portnet/ui\";\r\n *\r\n *   // Domain models + UI types (flat, type-only)\r\n *   import type { FavoriteItem, SavedFilter, GridColumn } from \"@portnet/ui\";\r\n *\r\n *   // Legacy `@portnet/ui/v2/*` paths still resolve transitionally\r\n *   // through the v2 re-export below, deprecated and scheduled for\r\n *   // removal in 0.4.0. NOTE: capability added after that deprecation\r\n *   // is surfaced flat ONLY and is deliberately absent from `v2.*`.\r\n *\r\n * No v1 surface remains. Consuming modules that still import any\r\n * Pui* component will fail to resolve and must migrate per the\r\n * table in docs/migration-mui9/03-batch3-purge-v1.md.\r\n */\r\n\r\n// Flat re-export of every v2 component, pattern, hook, and the\r\n// theme factory. This is what consuming modules pin against\r\n// (`import { Button } from \"@portnet/ui\"`).\r\nexport * from \"./v2/components\";\r\nexport * from \"./v2/patterns\";\r\nexport * from \"./v2/hooks\";\r\nexport {\r\n  createPortnetTheme,\r\n  getCssVariables,\r\n  injectCssVariables,\r\n  removeCssVariables,\r\n} from \"./v2/theme\";\r\n\r\n// Theme factory typed contract, flat + type-only (capability gap G-33).\r\n//\r\n// The theme VALUES were flat-exported above while the types describing their\r\n// options were reachable ONLY from the deprecated `@portnet/ui/v2` subpath.\r\n// Every host module wraps createPortnetTheme in a local `build<Module>Theme`\r\n// helper (see the GU modules' utils/appearance), so every host needs this\r\n// contract to type its own wrapper — and had exactly two ways to get it:\r\n// import from a surface scheduled for removal in 0.4.0, or fall back to\r\n// `brand?: object` + `as Parameters<typeof createPortnetTheme>[0]`, both on\r\n// the Platform TypeScript Guidelines FORBIDDEN list. ./v2/theme's own doc\r\n// comment already names that anti-pattern as the reason these types were\r\n// published; it just never reached the surface consumers are told to migrate\r\n// TO. Closing that here removes the last reason a module needs `@portnet/ui/v2`\r\n// for the theme layer.\r\n//\r\n// Flat-only, per the `v2` policy note at the bottom of this file.\r\n// Purely additive and type-only; nothing existing changed.\r\nexport type {\r\n  CreatePortnetThemeOptions,\r\n  BrandTokens,\r\n  BrandSecondaryTokens,\r\n} from \"./v2/theme\";\r\n\r\n// Added while migrating ms-dfd-fe to TypeScript: cx / fmtMoney / contrast had\r\n// no flat or subpath route, only the deprecated `v2.*` namespace below.\r\n// downloadBase64File + getMimeType were added later (mjcc-fe Area 5) and are\r\n// flat-only by policy — see the note on `v2` at the bottom of this file.\r\n// Purely additive re-exports; nothing existing changed.\r\n//\r\n// G-34 (caution-ui Area 6) — openBase64FileInTab + downloadBlobFile added.\r\n// These two were NOT flat-only additions: ./v2/index.ts has exported them all\r\n// along, so the FLAT ROOT — the surface the policy at the bottom of this file\r\n// tells every module to migrate TO — was a strict SUBSET of the deprecated\r\n// surface it replaces. A module obeying the migration policy lost access to\r\n// both, which is how caution-ui's Area 6 build broke:\r\n//\r\n//     Attempted import error: 'downloadBlobFile' is not exported\r\n//     from '@portnet/ui'\r\n//\r\n// Root cause is mechanical, and worth fixing properly rather than name by name:\r\n// ./v2/components, ./v2/patterns and ./v2/hooks are re-exported above with\r\n// `export *`, so anything added to them surfaces automatically. ./v2/utils is\r\n// re-exported by EXPLICIT NAME LIST, so every new util silently fails to reach\r\n// consumers until someone hits a build error. A wildcard is not a safe swap\r\n// here — ./v2/utils also carries `mergeLabels`, an internal label-merging\r\n// helper with no host use case, and widening a certified public surface by\r\n// accident is worse than the drift. The list stays, and the invariant is stated\r\n// instead: ANY addition to ./v2/utils intended for hosts must be added here in\r\n// the same commit.\r\nexport {\r\n  cx,\r\n  fmtMoney,\r\n  contrast,\r\n  downloadBase64File,\r\n  getMimeType,\r\n  openBase64FileInTab,\r\n  downloadBlobFile,\r\n} from \"./v2/utils\";\r\n\r\n// Error narrowing + the network-status channel. Flat-only per the `v2` policy\r\n// note at the bottom of this file. Both were added from the\r\n// procuration-portnet-fe Area 5 gap audit (G-04, G-03):\r\n//\r\n//   - getApiErrorMessage / getApiErrorStatus close the hole between two rules\r\n//     the platform imposes together — `useUnknownInCatchVariables` is mandatory\r\n//     and `any` / unsafe assertions are forbidden, with nothing sanctioned in\r\n//     between. Every audited module had bridged it with\r\n//     `error as { response?: { data?: { message?: unknown } } }`.\r\n//\r\n//   - networkStatus is the feed for NetworkErrorBanner, which shipped as a\r\n//     presentational component with its trigger contract left to consumers.\r\n//\r\n// G-34 — getApiErrorDetail added. Its own docstring PRESCRIBES a pairing that\r\n// was impossible to write, because the companion was never surfaced:\r\n//\r\n//     toast(getApiErrorMessage(err, \"Échec de l'envoi.\"), \"error\");\r\n//     console.error(\"[submit]\", getApiErrorStatus(err), getApiErrorDetail(err));\r\n//\r\n// The split exists because getApiErrorMessage deliberately SUPPRESSES transport\r\n// phrasings (G-07) — right for a toast, wrong for a console or an APM\r\n// breadcrumb, where \"Request failed with status code 502\" is exactly what an\r\n// operator needs. Without the escape hatch a host either logs the sanitised\r\n// string (losing the diagnostic) or re-reads `error.message` by hand with an\r\n// assertion (the very thing G-04 exists to prevent).\r\n//\r\n// Purely additive; nothing existing changed.\r\nexport {\r\n  getApiErrorMessage,\r\n  getApiErrorDetail,\r\n  getApiErrorStatus,\r\n  DEFAULT_API_ERROR_MESSAGE,\r\n  networkStatus,\r\n  createNetworkStatus,\r\n} from \"./v2/utils\";\r\nexport type { NetworkStatus, NetworkStatusListener } from \"./v2/utils\";\r\n\r\n// Route-level Suspense fallback. R-P.1 MUST requires a \"fallback skeleton page\",\r\n// and the library had every skeleton PART plus PageBusy, but nothing satisfying\r\n// the rule: PageBusy is a full-screen spinner, which R-8.1 MUST forbids for\r\n// navigation. So every module hand-built one, and to avoid the CLS a skeleton\r\n// exists to prevent it had to copy ActionBar's and PageContent's padding\r\n// literals out of this library. Owning it here keeps the three in lockstep.\r\n// Capability gap G-02 (procuration-portnet-fe Area 5). Flat-only, per the policy\r\n// note below.\r\nexport { default as SkeletonPageShell } from \"./v2/patterns/SkeletonPageShell\";\r\nexport type {\r\n  SkeletonPageShellProps,\r\n  SkeletonPageShellVariant,\r\n} from \"./v2/patterns/SkeletonPageShell\";\r\n\r\n// Modal/Drawer/Combobox/DatePicker layering constants - needed by any\r\n// consumer stacking a popover-ish component (Combobox, DateTimePicker)\r\n// above a Modal or Drawer. Was v2-namespace-only.\r\nexport { MODAL_POPPER_PROPS, MODAL_ZINDEX } from \"./v2/modalContext\";\r\n\r\n// Personalization foundation runtime API (favorites, saved filters).\r\n// Named re-export, not a wildcard: ./v2/personalization also carries\r\n// the Scope/FavoriteRef/SavedFilter model types for its own internal\r\n// use, which are already flat-exported canonically via ./v2/models\r\n// below - a wildcard here would re-export them a second time and\r\n// collide (TS2308). Mirrors exactly what ./v2/index.ts already does\r\n// internally for the same reason.\r\nexport {\r\n  UserPersonalizationProvider,\r\n  createLocalStorageAdapter,\r\n  createMemoryAdapter,\r\n  registerCapability,\r\n  useFavorites,\r\n  useIsFavorite,\r\n  useFavoritesView,\r\n  filterRowsByFavorites,\r\n  sortRowsByFavorites,\r\n  FAVORITES_FILTER,\r\n  FAVORITES_SORT,\r\n  useSavedFilters,\r\n} from \"./v2/personalization\";\r\n\r\n// Referentiel data layer runtime API (config provider + hooks). Backs\r\n// ReferentielField / FormikReferentielField, which are flat-exported\r\n// above via ./v2/patterns - the field UI was reachable while the data\r\n// layer that feeds it was not, so consumers had to either import from\r\n// the deprecated `@portnet/ui/v2` surface or rebuild the client\r\n// locally. Added while auditing mjcc-fe, which had done the latter.\r\n//\r\n// Named re-export, not a wildcard, for the SAME reason as\r\n// personalization above: ./v2/referentiel also re-exports\r\n// ReferentielSearchArgs, ReferentielSearchResult and\r\n// ReferentielSearchFn for its own use, and those names are already\r\n// flat-exported canonically through ./v2/models below. A wildcard\r\n// would export them twice and collide (TS2308). The type layer keeps\r\n// its single canonical route.\r\nexport {\r\n  ReferentielProvider,\r\n  ReferentielContext,\r\n  useReferentielClient,\r\n  useReferentielOptions,\r\n  useReferentielSearch,\r\n} from \"./v2/referentiel\";\r\n\r\n// Domain models & shared UI/structural types, flat + type-only (no\r\n// runtime cost). Mirrors the same re-export already done inside\r\n// ./v2 — added here so consumers migrating off `v2.*` have a route\r\n// to the shared types the platform guidelines require reusing\r\n// (DrawerProps, FavoriteItem, SavedFilter, GridColumn, GridAction,\r\n// WizardStep, Notification, FormField, etc.) without falling back to\r\n// the deprecated namespace just to get a type import. Conflicting\r\n// names across the two star-exports are omitted per ES module\r\n// semantics rather than erroring.\r\nexport * from \"./v2/models\";\r\nexport * from \"./v2/types\";\r\n\r\n// Transitional alias — the `@portnet/ui/v2` subpath kept resolving\r\n// for one minor cycle so consuming modules can migrate their\r\n// imports independently of the package bump. Scheduled removal:\r\n// 0.4.0. Track removal in the Batch 5 cleanup ticket.\r\n//\r\n// POLICY: capability added after this deprecation is surfaced on the\r\n// flat root ONLY and is not added to ./v2/index.ts — adding it there\r\n// would hand consumers a new reason to stay on a retiring surface.\r\n// downloadBase64File / getMimeType are the first such additions.\r\n//\r\n// COROLLARY, learned the hard way (G-34): the policy only works if the flat\r\n// root is a strict SUPERSET of ./v2. It was not — downloadBlobFile and\r\n// openBase64FileInTab were on v2 and missing here, so \"migrate off v2\" meant\r\n// \"lose two utilities\". Before deprecating anything further, diff the two\r\n// surfaces; `npm run api:check` covers the root but does not compare it against\r\n// ./v2.\r\nexport * as v2 from \"./v2\";\r\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA,cAAc,iBAAiB;AAC/B,cAAc,eAAe;AAC7B,cAAc,YAAY;AAC1B,SACEA,kBAAkB,EAClBC,eAAe,EACfC,kBAAkB,EAClBC,kBAAkB,QACb,YAAY;;AAEnB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAOA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SACEC,EAAE,EACFC,QAAQ,EACRC,QAAQ,EACRC,kBAAkB,EAClBC,WAAW,EACXC,mBAAmB,EACnBC,gBAAgB,QACX,YAAY;;AAEnB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SACEC,kBAAkB,EAClBC,iBAAiB,EACjBC,iBAAiB,EACjBC,yBAAyB,EACzBC,aAAa,EACbC,mBAAmB,QACd,YAAY;AAGnB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,OAAO,IAAIC,iBAAiB,QAAQ,iCAAiC;AAM9E;AACA;AACA;AACA,SAASC,kBAAkB,EAAEC,YAAY,QAAQ,mBAAmB;;AAEpE;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SACEC,2BAA2B,EAC3BC,yBAAyB,EACzBC,mBAAmB,EACnBC,kBAAkB,EAClBC,YAAY,EACZC,aAAa,EACbC,gBAAgB,EAChBC,qBAAqB,EACrBC,mBAAmB,EACnBC,gBAAgB,EAChBC,cAAc,EACdC,eAAe,QACV,sBAAsB;;AAE7B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SACEC,mBAAmB,EACnBC,kBAAkB,EAClBC,oBAAoB,EACpBC,qBAAqB,EACrBC,oBAAoB,QACf,kBAAkB;;AAEzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,cAAc,aAAa;AAC3B,cAAc,YAAY;;AAE1B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAAA,YAAAC,EAAA,MACoB,MAAM;AAAA,SAAAA,EAAA,IAAdC,EAAE","ignoreList":[]}

package/dist/esm/v2/__tests__/FieldError.test.js

@@ -0,0 +1,160 @@
+import "@testing-library/jest-dom";
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import FieldError from "../components/FieldError";
+import Field from "../components/Field";
+
+/**
+ * FieldError — contract tests, including its integration into Field.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * §10.3 R-G.6 MUST. But the real reason is narrower and worth stating: the
+ * contract this component carries is INVISIBLE. `Field` supplies an id, and that
+ * id must reach the control's `aria-describedby` so a screen reader announces
+ * the error when focus lands on the input. Break that wiring and NOTHING
+ * changes: same pixels, same screenshot, same visual review — only a blind user
+ * silently stops being told why their submit failed. There is no way to catch
+ * that except by asserting it.
+ *
+ * The assertions below use `toHaveAccessibleDescription`, not id comparisons, on
+ * purpose. It resolves aria-describedby to the text a screen reader would
+ * actually announce, so the test states the USER-FACING outcome and stays true
+ * if the id-generation scheme ever changes.
+ *
+ * NOT COVERED — deliberately
+ * R-4.1's visual half ("sous le champ, en rouge, avec icône") and the
+ * first-line icon alignment on a wrapping message are layout and colour. jsdom
+ * resolves neither CSS variables nor flexbox, so asserting them here would pass
+ * while the message rendered black and centred. Those live in
+ * FieldError.stories.tsx.
+ */
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+describe("FieldError — standalone", function () {
+  test("announces itself as an alert carrying the message", function () {
+    render(/*#__PURE__*/_jsx(FieldError, {
+      children: "Ajoutez au moins un article avant de soumettre."
+    }));
+    expect(screen.getByRole("alert")).toHaveTextContent("Ajoutez au moins un article avant de soumettre.");
+  });
+  test("forwards id so a host can wire its own aria-describedby", function () {
+    render(/*#__PURE__*/_jsx(FieldError, {
+      id: "articles-error",
+      children: "Ajoutez au moins un article."
+    }));
+    expect(screen.getByRole("alert")).toHaveAttribute("id", "articles-error");
+  });
+  test("omits id when none is supplied", function () {
+    /* The list-level case usually has nothing to bind to. Emitting an empty or
+     * generated id would create a describedby target nobody references. */
+    render(/*#__PURE__*/_jsx(FieldError, {
+      children: "Ajoutez au moins un article."
+    }));
+    expect(screen.getByRole("alert")).not.toHaveAttribute("id");
+  });
+  test("the icon is hidden from assistive tech", function () {
+    /* R-Ar.2 — the message IS the announcement; an announced glyph would double
+     * it. No semantic query reaches a role-less, name-less element, hence the
+     * testid the component exposes for exactly this assertion. */
+    render(/*#__PURE__*/_jsx(FieldError, {
+      children: "Message"
+    }));
+    expect(screen.getByTestId("fielderror-icon")).toHaveAttribute("aria-hidden", "true");
+  });
+});
+describe("FieldError — inside Field (the wiring that has no visual tell)", function () {
+  test("the error becomes the control's accessible description", function () {
+    render(/*#__PURE__*/_jsx(Field, {
+      label: "Num\xE9ro de titre",
+      error: "Le num\xE9ro est invalide. Format : AAAA-IM-NNNNN.",
+      children: /*#__PURE__*/_jsx("input", {})
+    }));
+    expect(screen.getByRole("textbox")).toHaveAccessibleDescription("Le numéro est invalide. Format : AAAA-IM-NNNNN.");
+  });
+  test("the control is marked invalid", function () {
+    render(/*#__PURE__*/_jsx(Field, {
+      label: "Num\xE9ro",
+      error: "Invalide.",
+      children: /*#__PURE__*/_jsx("input", {})
+    }));
+    // jest-dom's toBeInvalid reads aria-invalid — R-I.3.
+    expect(screen.getByRole("textbox")).toBeInvalid();
+  });
+  test("a host-supplied aria-describedby is PRESERVED, not replaced", function () {
+    /* The merge is the fragile part. Overwriting instead of merging silently
+     * drops a consumer's external help text, and again nothing visual changes.
+     * Asserted with two order-independent regexes rather than one exact string,
+     * so the test does not encode which fragment Field puts first. */
+    render(/*#__PURE__*/_jsxs(_Fragment, {
+      children: [/*#__PURE__*/_jsx("span", {
+        id: "host-help",
+        children: "Format attendu : AAAA-IM-NNNNN."
+      }), /*#__PURE__*/_jsx(Field, {
+        label: "Num\xE9ro",
+        error: "Le num\xE9ro est incomplet.",
+        children: /*#__PURE__*/_jsx("input", {
+          "aria-describedby": "host-help"
+        })
+      })]
+    }));
+    var input = screen.getByRole("textbox");
+    expect(input).toHaveAccessibleDescription(/Format attendu/);
+    expect(input).toHaveAccessibleDescription(/incomplet/);
+  });
+  test("the hint is suppressed while an error is shown", function () {
+    /* Two competing descriptions under one field is worse than one. The hint
+     * returns once the error clears — verified by the rerender below. */
+    var _render = render(/*#__PURE__*/_jsx(Field, {
+        label: "Num\xE9ro",
+        hint: "Format : AAAA-IM-NNNNN",
+        error: "Le num\xE9ro est incomplet.",
+        children: /*#__PURE__*/_jsx("input", {})
+      })),
+      rerender = _render.rerender;
+    expect(screen.getByRole("alert")).toHaveTextContent("Le numéro est incomplet.");
+    expect(screen.queryByText("Format : AAAA-IM-NNNNN")).not.toBeInTheDocument();
+    rerender(/*#__PURE__*/_jsx(Field, {
+      label: "Num\xE9ro",
+      hint: "Format : AAAA-IM-NNNNN",
+      children: /*#__PURE__*/_jsx("input", {})
+    }));
+    expect(screen.getByText("Format : AAAA-IM-NNNNN")).toBeInTheDocument();
+  });
+});
+describe("FieldError — live-region mounting contract", function () {
+  test("no alert exists until an error appears", function () {
+    /* THE contract. `role=\"alert\"` announces on INSERTION: an element mounted
+     * permanently with empty content announces nothing when it later fills, so
+     * a well-meaning refactor that always renders the container — to \"avoid
+     * layout shift\", say — silently kills the announcement while every pixel
+     * and every screenshot stays identical. */
+    var _render2 = render(/*#__PURE__*/_jsx(Field, {
+        label: "Num\xE9ro",
+        children: /*#__PURE__*/_jsx("input", {})
+      })),
+      rerender = _render2.rerender;
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+    rerender(/*#__PURE__*/_jsx(Field, {
+      label: "Num\xE9ro",
+      error: "Le num\xE9ro est incomplet.",
+      children: /*#__PURE__*/_jsx("input", {})
+    }));
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+  });
+  test("the alert unmounts when the error clears", function () {
+    var _render3 = render(/*#__PURE__*/_jsx(Field, {
+        label: "Num\xE9ro",
+        error: "Le num\xE9ro est incomplet.",
+        children: /*#__PURE__*/_jsx("input", {})
+      })),
+      rerender = _render3.rerender;
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    rerender(/*#__PURE__*/_jsx(Field, {
+      label: "Num\xE9ro",
+      children: /*#__PURE__*/_jsx("input", {})
+    }));
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+    expect(screen.getByRole("textbox")).not.toBeInvalid();
+  });
+});
+//# sourceMappingURL=FieldError.test.js.map

package/dist/esm/v2/__tests__/FieldError.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldError.test.js","names":["React","render","screen","FieldError","Field","jsx","_jsx","Fragment","_Fragment","jsxs","_jsxs","describe","test","children","expect","getByRole","toHaveTextContent","id","toHaveAttribute","not","getByTestId","label","error","toHaveAccessibleDescription","toBeInvalid","input","_render","hint","rerender","queryByText","toBeInTheDocument","getByText","_render2","queryByRole","_render3"],"sources":["../../../../src/lib/v2/__tests__/FieldError.test.tsx"],"sourcesContent":["import \"@testing-library/jest-dom\";\r\nimport * as React from \"react\";\r\nimport { render, screen } from \"@testing-library/react\";\r\nimport FieldError from \"../components/FieldError\";\r\nimport Field from \"../components/Field\";\r\n\r\n/**\r\n * FieldError — contract tests, including its integration into Field.\r\n *\r\n * WHY THIS FILE EXISTS\r\n * --------------------\r\n * §10.3 R-G.6 MUST. But the real reason is narrower and worth stating: the\r\n * contract this component carries is INVISIBLE. `Field` supplies an id, and that\r\n * id must reach the control's `aria-describedby` so a screen reader announces\r\n * the error when focus lands on the input. Break that wiring and NOTHING\r\n * changes: same pixels, same screenshot, same visual review — only a blind user\r\n * silently stops being told why their submit failed. There is no way to catch\r\n * that except by asserting it.\r\n *\r\n * The assertions below use `toHaveAccessibleDescription`, not id comparisons, on\r\n * purpose. It resolves aria-describedby to the text a screen reader would\r\n * actually announce, so the test states the USER-FACING outcome and stays true\r\n * if the id-generation scheme ever changes.\r\n *\r\n * NOT COVERED — deliberately\r\n * R-4.1's visual half (\"sous le champ, en rouge, avec icône\") and the\r\n * first-line icon alignment on a wrapping message are layout and colour. jsdom\r\n * resolves neither CSS variables nor flexbox, so asserting them here would pass\r\n * while the message rendered black and centred. Those live in\r\n * FieldError.stories.tsx.\r\n */\r\ndescribe(\"FieldError — standalone\", () => {\r\n  test(\"announces itself as an alert carrying the message\", () => {\r\n    render(<FieldError>Ajoutez au moins un article avant de soumettre.</FieldError>);\r\n    expect(screen.getByRole(\"alert\")).toHaveTextContent(\r\n      \"Ajoutez au moins un article avant de soumettre.\"\r\n    );\r\n  });\r\n\r\n  test(\"forwards id so a host can wire its own aria-describedby\", () => {\r\n    render(<FieldError id=\"articles-error\">Ajoutez au moins un article.</FieldError>);\r\n    expect(screen.getByRole(\"alert\")).toHaveAttribute(\"id\", \"articles-error\");\r\n  });\r\n\r\n  test(\"omits id when none is supplied\", () => {\r\n    /* The list-level case usually has nothing to bind to. Emitting an empty or\r\n     * generated id would create a describedby target nobody references. */\r\n    render(<FieldError>Ajoutez au moins un article.</FieldError>);\r\n    expect(screen.getByRole(\"alert\")).not.toHaveAttribute(\"id\");\r\n  });\r\n\r\n  test(\"the icon is hidden from assistive tech\", () => {\r\n    /* R-Ar.2 — the message IS the announcement; an announced glyph would double\r\n     * it. No semantic query reaches a role-less, name-less element, hence the\r\n     * testid the component exposes for exactly this assertion. */\r\n    render(<FieldError>Message</FieldError>);\r\n    expect(screen.getByTestId(\"fielderror-icon\")).toHaveAttribute(\"aria-hidden\", \"true\");\r\n  });\r\n});\r\n\r\ndescribe(\"FieldError — inside Field (the wiring that has no visual tell)\", () => {\r\n  test(\"the error becomes the control's accessible description\", () => {\r\n    render(\r\n      <Field label=\"Numéro de titre\" error=\"Le numéro est invalide. Format : AAAA-IM-NNNNN.\">\r\n        <input />\r\n      </Field>\r\n    );\r\n\r\n    expect(screen.getByRole(\"textbox\")).toHaveAccessibleDescription(\r\n      \"Le numéro est invalide. Format : AAAA-IM-NNNNN.\"\r\n    );\r\n  });\r\n\r\n  test(\"the control is marked invalid\", () => {\r\n    render(\r\n      <Field label=\"Numéro\" error=\"Invalide.\">\r\n        <input />\r\n      </Field>\r\n    );\r\n    // jest-dom's toBeInvalid reads aria-invalid — R-I.3.\r\n    expect(screen.getByRole(\"textbox\")).toBeInvalid();\r\n  });\r\n\r\n  test(\"a host-supplied aria-describedby is PRESERVED, not replaced\", () => {\r\n    /* The merge is the fragile part. Overwriting instead of merging silently\r\n     * drops a consumer's external help text, and again nothing visual changes.\r\n     * Asserted with two order-independent regexes rather than one exact string,\r\n     * so the test does not encode which fragment Field puts first. */\r\n    render(\r\n      <>\r\n        <span id=\"host-help\">Format attendu : AAAA-IM-NNNNN.</span>\r\n        <Field label=\"Numéro\" error=\"Le numéro est incomplet.\">\r\n          <input aria-describedby=\"host-help\" />\r\n        </Field>\r\n      </>\r\n    );\r\n\r\n    const input = screen.getByRole(\"textbox\");\r\n    expect(input).toHaveAccessibleDescription(/Format attendu/);\r\n    expect(input).toHaveAccessibleDescription(/incomplet/);\r\n  });\r\n\r\n  test(\"the hint is suppressed while an error is shown\", () => {\r\n    /* Two competing descriptions under one field is worse than one. The hint\r\n     * returns once the error clears — verified by the rerender below. */\r\n    const { rerender } = render(\r\n      <Field label=\"Numéro\" hint=\"Format : AAAA-IM-NNNNN\" error=\"Le numéro est incomplet.\">\r\n        <input />\r\n      </Field>\r\n    );\r\n\r\n    expect(screen.getByRole(\"alert\")).toHaveTextContent(\"Le numéro est incomplet.\");\r\n    expect(screen.queryByText(\"Format : AAAA-IM-NNNNN\")).not.toBeInTheDocument();\r\n\r\n    rerender(\r\n      <Field label=\"Numéro\" hint=\"Format : AAAA-IM-NNNNN\">\r\n        <input />\r\n      </Field>\r\n    );\r\n    expect(screen.getByText(\"Format : AAAA-IM-NNNNN\")).toBeInTheDocument();\r\n  });\r\n});\r\n\r\ndescribe(\"FieldError — live-region mounting contract\", () => {\r\n  test(\"no alert exists until an error appears\", () => {\r\n    /* THE contract. `role=\\\"alert\\\"` announces on INSERTION: an element mounted\r\n     * permanently with empty content announces nothing when it later fills, so\r\n     * a well-meaning refactor that always renders the container — to \\\"avoid\r\n     * layout shift\\\", say — silently kills the announcement while every pixel\r\n     * and every screenshot stays identical. */\r\n    const { rerender } = render(\r\n      <Field label=\"Numéro\">\r\n        <input />\r\n      </Field>\r\n    );\r\n    expect(screen.queryByRole(\"alert\")).not.toBeInTheDocument();\r\n\r\n    rerender(\r\n      <Field label=\"Numéro\" error=\"Le numéro est incomplet.\">\r\n        <input />\r\n      </Field>\r\n    );\r\n    expect(screen.getByRole(\"alert\")).toBeInTheDocument();\r\n  });\r\n\r\n  test(\"the alert unmounts when the error clears\", () => {\r\n    const { rerender } = render(\r\n      <Field label=\"Numéro\" error=\"Le numéro est incomplet.\">\r\n        <input />\r\n      </Field>\r\n    );\r\n    expect(screen.getByRole(\"alert\")).toBeInTheDocument();\r\n\r\n    rerender(\r\n      <Field label=\"Numéro\">\r\n        <input />\r\n      </Field>\r\n    );\r\n    expect(screen.queryByRole(\"alert\")).not.toBeInTheDocument();\r\n    expect(screen.getByRole(\"textbox\")).not.toBeInvalid();\r\n  });\r\n});\r\n"],"mappings":"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","ignoreList":[]}