@portnet/ui

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.

⚛️ 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 for the migration narrative.

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/ for the v1 → v2 migration history.

Install

npm install @portnet/ui

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

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.

5-minute boot

Mount once at app entry:

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";

injectCssVariables();
const theme = createPortnetTheme({ mode: "light", density: "comfortable" });

ReactDOM.createRoot(document.getElementById("root")).render(
  <ThemeProvider theme={theme}>
    <ToastProvider>
      <SkipLink href="#main-content" />
      <App />
    </ToastProvider>
  </ThemeProvider>
);

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 for the full pattern.

What's inside

• 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.

Docs

| Doc | When to read | |---|---| | 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/ | 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 | Component-by-component map, Formik adapter, theme customisation incl. brand override, charter compliance checklist. | | 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 | The historical v1 → v2 audit (May 2026): legacy component classification, 14 findings, refactor priority. | | CHANGELOG.md | Release notes per version. |

Storybook 8 (in .storybook/) showcases each primitive with live props. It is the primary design-system development environment since 0.4.0-react19.1.

Compliance

Every v2 primitive ships with:

• 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.

The full charter rule list is in the prototype's source PDF; the migration guide §9 is the per-PR compliance checklist.

Local development

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

R19 regression-guard pre-commit check (recommended):

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, 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+.