@portnet/ui 5.0.28 → 6.0.0

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/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @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.
+ */
+export * from "./v2/components";
+export * from "./v2/patterns";
+export * from "./v2/hooks";
+export { createPortnetTheme, getCssVariables, injectCssVariables, removeCssVariables, } from "./v2/theme";
+export { cx, fmtMoney, contrast, downloadBase64File, getMimeType, } from "./v2/utils";
+export { getApiErrorMessage, getApiErrorStatus, DEFAULT_API_ERROR_MESSAGE, networkStatus, createNetworkStatus, } from "./v2/utils";
+export type { NetworkStatus, NetworkStatusListener } from "./v2/utils";
+export { default as SkeletonPageShell } from "./v2/patterns/SkeletonPageShell";
+export type { SkeletonPageShellProps, SkeletonPageShellVariant, } from "./v2/patterns/SkeletonPageShell";
+export { MODAL_POPPER_PROPS, MODAL_ZINDEX } from "./v2/modalContext";
+export { UserPersonalizationProvider, createLocalStorageAdapter, createMemoryAdapter, registerCapability, useFavorites, useIsFavorite, useFavoritesView, filterRowsByFavorites, sortRowsByFavorites, FAVORITES_FILTER, FAVORITES_SORT, useSavedFilters, } from "./v2/personalization";
+export { ReferentielProvider, ReferentielContext, useReferentielClient, useReferentielOptions, useReferentielSearch, } from "./v2/referentiel";
+export * from "./v2/models";
+export * from "./v2/types";
+export * as v2 from "./v2";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAKH,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAOpB,OAAO,EACL,EAAE,EACF,QAAQ,EACR,QAAQ,EACR,kBAAkB,EAClB,WAAW,GACZ,MAAM,YAAY,CAAC;AAgBpB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,yBAAyB,EACzB,aAAa,EACb,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAUvE,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAC/E,YAAY,EACV,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,iCAAiC,CAAC;AAKzC,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AASrE,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAgB9B,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAW1B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAW3B,OAAO,KAAK,EAAE,MAAM,MAAM,CAAC"}