@portnet/ui 5.0.27 → 6.0.0

package/dist/v2/types/datagrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datagrid.js","names":[],"sources":["../../../src/lib/v2/types/datagrid.ts"],"sourcesContent":["/**\r\n * @portnet/ui v2 — DataGrid generic contract.\r\n *\r\n * Derived verbatim from the DataGrid / SortableHeader / _dataGridShared\r\n * PropTypes + implementation (the executable contract). MUI-independent:\r\n * component-level composition with MUI prop types happens in the component\r\n * itself (Part 2), not here.\r\n */\r\n\r\nimport type { Dispatch, ReactNode, SetStateAction } from \"react\";\r\nimport type { Alignment, Breakpoint, Density, RowId, SortDescriptor } from \"./common\";\r\n\r\n/** A DataGrid column definition over row type `T`. */\r\nexport interface DataGridColumn<T> {\r\n  /** Unique column key; also the default value accessor (`row[key]`). */\r\n  key: string;\r\n  /** Header content. */\r\n  header: ReactNode;\r\n  align?: Alignment;\r\n  /** Right-align + tabular numerals. */\r\n  numeric?: boolean;\r\n  /** Monospaced cell font + tabular numerals. */\r\n  mono?: boolean;\r\n  /** Default true when `onSortChange` is set; `false` opts the column out of sorting. */\r\n  sortable?: boolean;\r\n  /** Default true when the grid is `resizable`; `false` opts the column out. */\r\n  resizable?: boolean;\r\n  /** Default true when the grid is `reorderable`; `false` opts the column out. */\r\n  reorderable?: boolean;\r\n  /** Reveal the cell only on row hover / focus-within / coarse pointer. */\r\n  hoverOnly?: boolean;\r\n  /** Column may be toggled by a column-visibility UI. */\r\n  toggleable?: boolean;\r\n  /** Preferred width (px number or CSS length). */\r\n  width?: number | string;\r\n  /** Hard max width (px number or CSS length). */\r\n  maxWidth?: number | string;\r\n  /** Wrap long content instead of truncating with an ellipsis. */\r\n  wrap?: boolean;\r\n  /** Custom cell renderer; overrides `getValue` / `row[key]`. */\r\n  render?: (row: T) => ReactNode;\r\n  /** Custom value accessor used when `render` is absent (default `row[key]`). */\r\n  getValue?: (row: T) => unknown;\r\n}\r\n\r\n/** Pagination model for DataGrid (`page` is 1-based). */\r\nexport interface DataGridPagination {\r\n  page: number;\r\n  pageSize: number;\r\n  total: number;\r\n  onPageChange: (page: number) => void;\r\n  onPageSizeChange?: (pageSize: number) => void;\r\n  pageSizes?: number[];\r\n}\r\n\r\n/** i18n labels for the DataGrid pagination bar. */\r\nexport interface DataGridPaginationLabels {\r\n  loading?: ReactNode;\r\n  rowsPerPage?: ReactNode;\r\n  firstPage?: string;\r\n  previousPage?: string;\r\n  nextPage?: string;\r\n  lastPage?: string;\r\n  /** Accessible name for the pagination navigation landmark (WCAG landmark / 2.4.1). */\r\n  navLabel?: string;\r\n  /** Range summary; `fmt` is the resolved locale number formatter. */\r\n  rangeOf?: (from: number, to: number, total: number, fmt: (n: number) => string) => ReactNode;\r\n}\r\n\r\n/** i18n labels for DataGrid. */\r\nexport interface DataGridLabels {\r\n  tableAria?: string;\r\n  selectAll?: string;\r\n  selectRow?: (id: RowId) => string;\r\n  actionsHeader?: string;\r\n  pagination?: DataGridPaginationLabels;\r\n}\r\n\r\n/** Context object passed to `renderMobileCard`. */\r\nexport interface DataGridMobileCardContext {\r\n  isActive: boolean;\r\n  isSelected: boolean;\r\n}\r\n\r\n/** Options accepted by the exported `applySort` helper. */\r\nexport interface ApplySortOptions {\r\n  /** BCP-47 locale for collation (default \"fr-FR\"). */\r\n  locale?: string;\r\n}\r\n\r\n/** Props for the DataGrid pattern over row type `T`. */\r\nexport interface DataGridProps<T> {\r\n  rows?: T[];\r\n  columns: DataGridColumn<T>[];\r\n  loading?: boolean;\r\n  /** Any truthy value switches the grid to its error branch (renders `errorState`). */\r\n  error?: unknown;\r\n  sort?: SortDescriptor[];\r\n  /**\r\n   * Sort-state setter. DataGrid forwards this straight to SortableHeader,\r\n   * which invokes it with an UPDATER function — so it must behave like a\r\n   * `useState` dispatcher (accepts a value OR a `(prev) => next` updater).\r\n   */\r\n  onSortChange?: Dispatch<SetStateAction<SortDescriptor[]>>;\r\n  selection?: Set<RowId> | RowId[];\r\n  /** Receives the next selection as a `Set`. Presence enables the checkbox column. */\r\n  onSelectionChange?: (selection: Set<RowId>) => void;\r\n  pagination?: DataGridPagination;\r\n  emptyState?: ReactNode;\r\n  filteredEmptyState?: ReactNode;\r\n  errorState?: ReactNode;\r\n  /** Row identity (default `(row) => row.id`). */\r\n  getRowId?: (row: T) => RowId;\r\n  onRowClick?: (row: T) => void;\r\n  rowFlashId?: RowId;\r\n  activeRowId?: RowId;\r\n  /** Renders the per-row actions overlay. Presence enables the actions column. */\r\n  rowActions?: (row: T) => ReactNode;\r\n  hiddenColumns?: Set<string> | string[];\r\n  /** Marks an empty result as filter-induced (renders `filteredEmptyState`). */\r\n  filtered?: boolean;\r\n  density?: Density;\r\n  /** Contextual accessible table name (WCAG 1.3.1 / Charter R-DG). */\r\n  ariaLabel?: string;\r\n  /** BCP-47 locale for number formatting (default \"fr-FR\"). */\r\n  locale?: string;\r\n  labels?: DataGridLabels;\r\n  maxBodyHeight?: number | string;\r\n  resizable?: boolean;\r\n  columnWidths?: Record<string, number>;\r\n  onColumnWidthsChange?: (widths: Record<string, number>) => void;\r\n  reorderable?: boolean;\r\n  columnOrder?: string[];\r\n  onColumnOrderChange?: (order: string[]) => void;\r\n  /** Opt-in mobile card renderer; below `mobileBreakpoint` the grid renders cards. */\r\n  renderMobileCard?: (row: T, ctx: DataGridMobileCardContext) => ReactNode;\r\n  mobileBreakpoint?: Breakpoint;\r\n}\r\n"],"mappings":"","ignoreList":[]}

package/dist/v2/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @portnet/ui v2 — Shared UI type architecture (barrel).
+ *
+ * Reusable UI/structural types. Business/domain models live under ../models.
+ * Topic modules are re-exported here; component-specific prop types are added
+ * as each component migrates (Part 2). The public typed surface is finalised
+ * in Batch 5 (barrels + `exports` type conditions).
+ */
+export * from "./common";
+export * from "./datagrid";
+//# sourceMappingURL=index.d.ts.map

package/dist/v2/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC"}

package/dist/v2/types/index.js

@@ -0,0 +1,28 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _common = require("./common");
+Object.keys(_common).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _common[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _common[key];
+    }
+  });
+});
+var _datagrid = require("./datagrid");
+Object.keys(_datagrid).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _datagrid[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _datagrid[key];
+    }
+  });
+});
+//# sourceMappingURL=index.js.map

package/dist/v2/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["_common","require","Object","keys","forEach","key","exports","defineProperty","enumerable","get","_datagrid"],"sources":["../../../src/lib/v2/types/index.ts"],"sourcesContent":["/**\r\n * @portnet/ui v2 — Shared UI type architecture (barrel).\r\n *\r\n * Reusable UI/structural types. Business/domain models live under ../models.\r\n * Topic modules are re-exported here; component-specific prop types are added\r\n * as each component migrates (Part 2). The public typed surface is finalised\r\n * in Batch 5 (barrels + `exports` type conditions).\r\n */\r\n\r\nexport * from \"./common\";\r\nexport * from \"./datagrid\";\r\n"],"mappings":";;;;;AASA,IAAAA,OAAA,GAAAC,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAH,OAAA,EAAAI,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAA,GAAA,IAAAC,OAAA,IAAAA,OAAA,CAAAD,GAAA,MAAAL,OAAA,CAAAK,GAAA;EAAAH,MAAA,CAAAK,cAAA,CAAAD,OAAA,EAAAD,GAAA;IAAAG,UAAA;IAAAC,GAAA,WAAAA,IAAA;MAAA,OAAAT,OAAA,CAAAK,GAAA;IAAA;EAAA;AAAA;AACA,IAAAK,SAAA,GAAAT,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAO,SAAA,EAAAN,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAA,GAAA,IAAAC,OAAA,IAAAA,OAAA,CAAAD,GAAA,MAAAK,SAAA,CAAAL,GAAA;EAAAH,MAAA,CAAAK,cAAA,CAAAD,OAAA,EAAAD,GAAA;IAAAG,UAAA;IAAAC,GAAA,WAAAA,IAAA;MAAA,OAAAC,SAAA,CAAAL,GAAA;IAAA;EAAA;AAAA","ignoreList":[]}

package/dist/v2/utils/apiError.d.ts

@@ -0,0 +1,90 @@
+/**
+ * apiError — narrow an `unknown` rejection into something displayable.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THIS BELONGS IN THE LIBRARY (capability gap 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. Between those two rules sits a
+ * narrowing helper that the library did not provide — so each module wrote its
+ * own, and the observed outcome was that they wrote it the forbidden way:
+ *
+ *     (error as { response?: { data?: { message?: unknown } } }).response
+ *
+ * i.e. an unchecked assertion on an `unknown`, used to work around a flag the
+ * platform imposes. Two modules audited (`procuration-portnet-fe`,
+ * `procuration-fe`) had independently reached for exactly that construct.
+ * A mandated strict-mode flag with no sanctioned escape hatch produces
+ * unsanctioned ones.
+ *
+ * Implementation notes
+ * --------------------
+ * `readPath` walks nested objects using the `in` operator, which narrows without
+ * an assertion, and `Reflect.get`, which returns the value as `unknown` rather
+ * than widening anything to `any`. No assertion appears anywhere in this file.
+ *
+ * Deliberately DUCK-TYPED rather than built on `axios.isAxiosError`. Three
+ * reasons: this library must not take a hard axios dependency for a string
+ * helper; a plain object shaped like an axios error (a hand-rolled reject, a
+ * test double, a non-axios transport) still resolves correctly; and the check
+ * stays valid across axios majors.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   getApiErrorMessage(err)                          → backend message, or the default
+ *   getApiErrorMessage(err, "Échec de l'envoi.")     → custom fallback
+ *   getApiErrorStatus(err)                           → 404 | undefined
+ */
+/**
+ * Default user-facing fallback. French per Charter §09 (voice, vouvoiement) and
+ * §09.3 (no raw technical detail — never "Erreur 422 Unprocessable Entity").
+ * Override per call site when a screen can say something more useful.
+ */
+export declare const DEFAULT_API_ERROR_MESSAGE = "Une erreur est survenue. Veuillez r\u00E9essayer.";
+/**
+ * Best available human-readable message for a rejection of unknown shape.
+ *
+ * Resolution order, first match wins:
+ *   1. the rejection itself, when it is a non-empty string;
+ *   2. `error.response.data.message` — the backend's own message;
+ *   3. `error.message` — **only when it is not a transport artefact** (G-07);
+ *   4. `fallback`.
+ *
+ * Step 3 is filtered: `"Request failed with status code 500"`, `"Network Error"`,
+ * timeouts and errno codes are SUPPRESSED so the caller's own French copy is
+ * used instead (Charter §09.3 — no raw technical detail). A message a module
+ * threw deliberately still passes through. Use `getApiErrorDetail` when you want
+ * the unfiltered string for a log.
+ *
+ * Never throws and never returns an empty string, so it is safe to render
+ * directly into a toast or a `Banner`.
+ *
+ * @param error    The caught value. `unknown` by design.
+ * @param fallback Message when nothing usable is found.
+ */
+export declare function getApiErrorMessage(error: unknown, fallback?: string): string;
+/**
+ * Unfiltered technical detail for LOGGING — never for display.
+ *
+ * `getApiErrorMessage` deliberately suppresses transport phrasings (G-07), which
+ * is right for a toast and wrong for a console or an APM breadcrumb, where
+ * `"Request failed with status code 502"` is exactly what an operator needs. This
+ * is the escape hatch: it returns the raw `error.message` when there is one,
+ * whatever its shape.
+ *
+ * Pair them:
+ *
+ *     toast(getApiErrorMessage(err, "Échec de l'envoi."), "error");
+ *     console.error("[submit]", getApiErrorStatus(err), getApiErrorDetail(err));
+ */
+export declare function getApiErrorDetail(error: unknown): string | undefined;
+/**
+ * HTTP status carried by a rejection, when there is one.
+ *
+ * Returns `undefined` for a network drop, a timeout, or any non-HTTP rejection —
+ * which is the signal callers use to distinguish "the server answered with an
+ * error" from "there was no answer at all" (Charter R-4.3: a status-less failure
+ * is a network banner, not a toast).
+ */
+export declare function getApiErrorStatus(error: unknown): number | undefined;
+//# sourceMappingURL=apiError.d.ts.map

package/dist/v2/utils/apiError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiError.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/utils/apiError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,sDACU,CAAC;AA6GjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAkC,GAC3C,MAAM,CAQR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGpE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGpE"}

package/dist/v2/utils/apiError.js

@@ -0,0 +1,227 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DEFAULT_API_ERROR_MESSAGE = void 0;
+exports.getApiErrorDetail = getApiErrorDetail;
+exports.getApiErrorMessage = getApiErrorMessage;
+exports.getApiErrorStatus = getApiErrorStatus;
+function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (obj) { return typeof obj; } : function (obj) { return obj && "function" == typeof Symbol && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }, _typeof(obj); }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it["return"] != null) it["return"](); } finally { if (didErr) throw err; } } }; }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+/**
+ * apiError — narrow an `unknown` rejection into something displayable.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THIS BELONGS IN THE LIBRARY (capability gap 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. Between those two rules sits a
+ * narrowing helper that the library did not provide — so each module wrote its
+ * own, and the observed outcome was that they wrote it the forbidden way:
+ *
+ *     (error as { response?: { data?: { message?: unknown } } }).response
+ *
+ * i.e. an unchecked assertion on an `unknown`, used to work around a flag the
+ * platform imposes. Two modules audited (`procuration-portnet-fe`,
+ * `procuration-fe`) had independently reached for exactly that construct.
+ * A mandated strict-mode flag with no sanctioned escape hatch produces
+ * unsanctioned ones.
+ *
+ * Implementation notes
+ * --------------------
+ * `readPath` walks nested objects using the `in` operator, which narrows without
+ * an assertion, and `Reflect.get`, which returns the value as `unknown` rather
+ * than widening anything to `any`. No assertion appears anywhere in this file.
+ *
+ * Deliberately DUCK-TYPED rather than built on `axios.isAxiosError`. Three
+ * reasons: this library must not take a hard axios dependency for a string
+ * helper; a plain object shaped like an axios error (a hand-rolled reject, a
+ * test double, a non-axios transport) still resolves correctly; and the check
+ * stays valid across axios majors.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   getApiErrorMessage(err)                          → backend message, or the default
+ *   getApiErrorMessage(err, "Échec de l'envoi.")     → custom fallback
+ *   getApiErrorStatus(err)                           → 404 | undefined
+ */
+
+/**
+ * Default user-facing fallback. French per Charter §09 (voice, vouvoiement) and
+ * §09.3 (no raw technical detail — never "Erreur 422 Unprocessable Entity").
+ * Override per call site when a screen can say something more useful.
+ */
+var DEFAULT_API_ERROR_MESSAGE = exports.DEFAULT_API_ERROR_MESSAGE = "Une erreur est survenue. Veuillez réessayer.";
+
+/**
+ * Walk `path` through nested non-null objects, returning the value at the end,
+ * or `undefined` if any hop is missing. Assertion-free.
+ */
+var readPath = function readPath(source, path) {
+  var current = source;
+  var _iterator = _createForOfIteratorHelper(path),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var key = _step.value;
+      if (_typeof(current) !== "object" || current === null || !(key in current)) {
+        return undefined;
+      }
+      current = Reflect.get(current, key);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return current;
+};
+var asNonEmptyString = function asNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+
+/**
+ * Transport-layer phrasings that must NEVER reach a user — capability gap G-07.
+ *
+ * ──────────────────────────────────────────────────────────────────────
+ * THE DEFECT THIS FIXES
+ *
+ * `getApiErrorMessage` resolved `error.message` BEFORE its fallback. An
+ * `AxiosError` always has `.message`, so on any server error carrying no
+ * `response.data.message` — a 500 with an empty body, a gateway error, a
+ * timeout — step 3 won and the user was shown:
+ *
+ *     "Request failed with status code 500"
+ *
+ * English, technical, and precisely the shape Charter §09.3 names as forbidden
+ * ("✗ « Erreur 422 — Unprocessable Entity »"). Worse, it made every consuming
+ * module's carefully-written French fallback effectively UNREACHABLE — the
+ * argument was accepted and then almost never used. Found during the
+ * `procuration-portnet-fe` Area 10 audit, where 12 call sites pass a considered
+ * fallback that could essentially never render.
+ *
+ * WHY A DENY-LIST AND NOT SIMPLY DROPPING STEP 3
+ *
+ * Step 3 also carries LEGITIMATE messages: any `throw new Error("Ce titre ne
+ * peut pas être supprimé car il est en cours de validation.")` in module code
+ * arrives through exactly the same path. Removing the hop would trade a leak of
+ * technical strings for the loss of real business messages across the whole
+ * platform — a worse outcome. So the hop stays and only transport phrasings are
+ * suppressed.
+ *
+ * The list is deliberately CONSERVATIVE: anything not recognised passes through,
+ * on the assumption a human wrote it. A false negative shows one ugly string; a
+ * false positive silently replaces a real business message with a generic
+ * fallback, which is the more damaging error.
+ *
+ * Sourced from axios's own message construction (`settle`, `AxiosError` codes
+ * ECONNABORTED / ETIMEDOUT / ERR_NETWORK / ERR_CANCELED) plus the Node socket
+ * phrasing that surfaces through SSR and test doubles.
+ * ──────────────────────────────────────────────────────────────────────
+ */
+var TRANSPORT_MESSAGE_PATTERNS = [/^request failed with status code \d+$/i, /^network error$/i, /^timeout of \d+ms exceeded$/i, /^timeout exceeded$/i, /^request aborted$/i, /^canceled$/i, /^unsupported protocol/i, /^maximum content size exceeded$/i, /^socket hang up$/i,
+/* ── errno codes and axios error codes ── CASE-SENSITIVE, DELIBERATELY ─────
+ *
+ * These two are the only patterns here NOT marked `/i`, and the asymmetry is
+ * load-bearing. errno constants are uppercase by universal convention
+ * (`ETIMEDOUT`, `ECONNREFUSED`, `ENOTFOUND`, `EPIPE`), so an uppercase-only
+ * match identifies them precisely. Matching case-insensitively would make
+ * `/^e[a-z]+$/i` swallow ordinary French words beginning with "e" — "erreur",
+ * "expiré", "échec" — turning a real business message into a generic fallback,
+ * which is the more damaging failure this list is tuned against.
+ *
+ * ⚠ An earlier version of the first pattern was `/^ec[a-z]+$/i`, which matched
+ * `ECONNREFUSED` (it begins "EC") but silently MISSED `ETIMEDOUT` ("ET"),
+ * despite the comment claiming otherwise. The unit test caught it. Do not
+ * narrow the prefix again: the family is "E + uppercase word", not "EC...".
+ *
+ * Residual, accepted: an all-caps single word like "ERREUR" is treated as an
+ * errno code. A module should not be throwing all-caps single-word messages at
+ * users, and replacing one with a proper French fallback is an improvement. */
+/^E[A-Z]{3,}$/,
+// errno: ETIMEDOUT, ECONNREFUSED, ECONNRESET, ENOTFOUND, EPIPE
+/^ERR_[A-Z_]+$/ // axios: ERR_NETWORK, ERR_CANCELED, ERR_BAD_RESPONSE
+];
+
+/** Is this string an axios/transport artefact rather than something for a user? */
+var isTransportMessage = function isTransportMessage(value) {
+  return TRANSPORT_MESSAGE_PATTERNS.some(function (pattern) {
+    return pattern.test(value.trim());
+  });
+};
+
+/**
+ * `error.message`, but only when it is fit to show a user.
+ *
+ * Suppresses transport phrasings (G-07) so the caller's French fallback is
+ * reached instead. Module-thrown `Error` messages pass through untouched.
+ */
+var asUserFacingMessage = function asUserFacingMessage(value) {
+  var text = asNonEmptyString(value);
+  if (text === undefined) return undefined;
+  return isTransportMessage(text) ? undefined : text;
+};
+
+/**
+ * Best available human-readable message for a rejection of unknown shape.
+ *
+ * Resolution order, first match wins:
+ *   1. the rejection itself, when it is a non-empty string;
+ *   2. `error.response.data.message` — the backend's own message;
+ *   3. `error.message` — **only when it is not a transport artefact** (G-07);
+ *   4. `fallback`.
+ *
+ * Step 3 is filtered: `"Request failed with status code 500"`, `"Network Error"`,
+ * timeouts and errno codes are SUPPRESSED so the caller's own French copy is
+ * used instead (Charter §09.3 — no raw technical detail). A message a module
+ * threw deliberately still passes through. Use `getApiErrorDetail` when you want
+ * the unfiltered string for a log.
+ *
+ * Never throws and never returns an empty string, so it is safe to render
+ * directly into a toast or a `Banner`.
+ *
+ * @param error    The caught value. `unknown` by design.
+ * @param fallback Message when nothing usable is found.
+ */
+function getApiErrorMessage(error) {
+  var _ref, _asNonEmptyString;
+  var fallback = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : DEFAULT_API_ERROR_MESSAGE;
+  if (typeof error === "string" && error.length > 0) return error;
+  return (_ref = (_asNonEmptyString = asNonEmptyString(readPath(error, ["response", "data", "message"]))) !== null && _asNonEmptyString !== void 0 ? _asNonEmptyString : asUserFacingMessage(readPath(error, ["message"]))) !== null && _ref !== void 0 ? _ref : fallback;
+}
+
+/**
+ * Unfiltered technical detail for LOGGING — never for display.
+ *
+ * `getApiErrorMessage` deliberately suppresses transport phrasings (G-07), which
+ * is right for a toast and wrong for a console or an APM breadcrumb, where
+ * `"Request failed with status code 502"` is exactly what an operator needs. This
+ * is the escape hatch: it returns the raw `error.message` when there is one,
+ * whatever its shape.
+ *
+ * Pair them:
+ *
+ *     toast(getApiErrorMessage(err, "Échec de l'envoi."), "error");
+ *     console.error("[submit]", getApiErrorStatus(err), getApiErrorDetail(err));
+ */
+function getApiErrorDetail(error) {
+  if (typeof error === "string" && error.length > 0) return error;
+  return asNonEmptyString(readPath(error, ["message"]));
+}
+
+/**
+ * HTTP status carried by a rejection, when there is one.
+ *
+ * Returns `undefined` for a network drop, a timeout, or any non-HTTP rejection —
+ * which is the signal callers use to distinguish "the server answered with an
+ * error" from "there was no answer at all" (Charter R-4.3: a status-less failure
+ * is a network banner, not a toast).
+ */
+function getApiErrorStatus(error) {
+  var status = readPath(error, ["response", "status"]);
+  return typeof status === "number" ? status : undefined;
+}
+//# sourceMappingURL=apiError.js.map

package/dist/v2/utils/apiError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiError.js","names":["DEFAULT_API_ERROR_MESSAGE","exports","readPath","source","path","current","_iterator","_createForOfIteratorHelper","_step","s","n","done","key","value","_typeof","undefined","Reflect","get","err","e","f","asNonEmptyString","length","TRANSPORT_MESSAGE_PATTERNS","isTransportMessage","some","pattern","test","trim","asUserFacingMessage","text","getApiErrorMessage","error","_ref","_asNonEmptyString","fallback","arguments","getApiErrorDetail","getApiErrorStatus","status"],"sources":["../../../src/lib/v2/utils/apiError.ts"],"sourcesContent":["/**\r\n * apiError — narrow an `unknown` rejection into something displayable.\r\n *\r\n * ─────────────────────────────────────────────────────────────────────────────\r\n * WHY THIS BELONGS IN THE LIBRARY (capability gap G-04)\r\n *\r\n * The Platform TypeScript Guidelines mandate `useUnknownInCatchVariables`, so\r\n * `catch (e)` binds `unknown` in EVERY saga of EVERY consuming module. The same\r\n * guidelines forbid `any` and unsafe assertions. Between those two rules sits a\r\n * narrowing helper that the library did not provide — so each module wrote its\r\n * own, and the observed outcome was that they wrote it the forbidden way:\r\n *\r\n *     (error as { response?: { data?: { message?: unknown } } }).response\r\n *\r\n * i.e. an unchecked assertion on an `unknown`, used to work around a flag the\r\n * platform imposes. Two modules audited (`procuration-portnet-fe`,\r\n * `procuration-fe`) had independently reached for exactly that construct.\r\n * A mandated strict-mode flag with no sanctioned escape hatch produces\r\n * unsanctioned ones.\r\n *\r\n * Implementation notes\r\n * --------------------\r\n * `readPath` walks nested objects using the `in` operator, which narrows without\r\n * an assertion, and `Reflect.get`, which returns the value as `unknown` rather\r\n * than widening anything to `any`. No assertion appears anywhere in this file.\r\n *\r\n * Deliberately DUCK-TYPED rather than built on `axios.isAxiosError`. Three\r\n * reasons: this library must not take a hard axios dependency for a string\r\n * helper; a plain object shaped like an axios error (a hand-rolled reject, a\r\n * test double, a non-axios transport) still resolves correctly; and the check\r\n * stays valid across axios majors.\r\n * ─────────────────────────────────────────────────────────────────────────────\r\n *\r\n *   getApiErrorMessage(err)                          → backend message, or the default\r\n *   getApiErrorMessage(err, \"Échec de l'envoi.\")     → custom fallback\r\n *   getApiErrorStatus(err)                           → 404 | undefined\r\n */\r\n\r\n/**\r\n * Default user-facing fallback. French per Charter §09 (voice, vouvoiement) and\r\n * §09.3 (no raw technical detail — never \"Erreur 422 Unprocessable Entity\").\r\n * Override per call site when a screen can say something more useful.\r\n */\r\nexport const DEFAULT_API_ERROR_MESSAGE =\r\n  \"Une erreur est survenue. Veuillez réessayer.\";\r\n\r\n/**\r\n * Walk `path` through nested non-null objects, returning the value at the end,\r\n * or `undefined` if any hop is missing. Assertion-free.\r\n */\r\nconst readPath = (source: unknown, path: readonly string[]): unknown => {\r\n  let current: unknown = source;\r\n\r\n  for (const key of path) {\r\n    if (typeof current !== \"object\" || current === null || !(key in current)) {\r\n      return undefined;\r\n    }\r\n    current = Reflect.get(current, key);\r\n  }\r\n\r\n  return current;\r\n};\r\n\r\nconst asNonEmptyString = (value: unknown): string | undefined =>\r\n  typeof value === \"string\" && value.length > 0 ? value : undefined;\r\n\r\n/**\r\n * Transport-layer phrasings that must NEVER reach a user — capability gap G-07.\r\n *\r\n * ──────────────────────────────────────────────────────────────────────\r\n * THE DEFECT THIS FIXES\r\n *\r\n * `getApiErrorMessage` resolved `error.message` BEFORE its fallback. An\r\n * `AxiosError` always has `.message`, so on any server error carrying no\r\n * `response.data.message` — a 500 with an empty body, a gateway error, a\r\n * timeout — step 3 won and the user was shown:\r\n *\r\n *     \"Request failed with status code 500\"\r\n *\r\n * English, technical, and precisely the shape Charter §09.3 names as forbidden\r\n * (\"✗ « Erreur 422 — Unprocessable Entity »\"). Worse, it made every consuming\r\n * module's carefully-written French fallback effectively UNREACHABLE — the\r\n * argument was accepted and then almost never used. Found during the\r\n * `procuration-portnet-fe` Area 10 audit, where 12 call sites pass a considered\r\n * fallback that could essentially never render.\r\n *\r\n * WHY A DENY-LIST AND NOT SIMPLY DROPPING STEP 3\r\n *\r\n * Step 3 also carries LEGITIMATE messages: any `throw new Error(\"Ce titre ne\r\n * peut pas être supprimé car il est en cours de validation.\")` in module code\r\n * arrives through exactly the same path. Removing the hop would trade a leak of\r\n * technical strings for the loss of real business messages across the whole\r\n * platform — a worse outcome. So the hop stays and only transport phrasings are\r\n * suppressed.\r\n *\r\n * The list is deliberately CONSERVATIVE: anything not recognised passes through,\r\n * on the assumption a human wrote it. A false negative shows one ugly string; a\r\n * false positive silently replaces a real business message with a generic\r\n * fallback, which is the more damaging error.\r\n *\r\n * Sourced from axios's own message construction (`settle`, `AxiosError` codes\r\n * ECONNABORTED / ETIMEDOUT / ERR_NETWORK / ERR_CANCELED) plus the Node socket\r\n * phrasing that surfaces through SSR and test doubles.\r\n * ──────────────────────────────────────────────────────────────────────\r\n */\r\nconst TRANSPORT_MESSAGE_PATTERNS: readonly RegExp[] = [\r\n  /^request failed with status code \\d+$/i,\r\n  /^network error$/i,\r\n  /^timeout of \\d+ms exceeded$/i,\r\n  /^timeout exceeded$/i,\r\n  /^request aborted$/i,\r\n  /^canceled$/i,\r\n  /^unsupported protocol/i,\r\n  /^maximum content size exceeded$/i,\r\n  /^socket hang up$/i,\r\n  /* ── errno codes and axios error codes ── CASE-SENSITIVE, DELIBERATELY ─────\r\n   *\r\n   * These two are the only patterns here NOT marked `/i`, and the asymmetry is\r\n   * load-bearing. errno constants are uppercase by universal convention\r\n   * (`ETIMEDOUT`, `ECONNREFUSED`, `ENOTFOUND`, `EPIPE`), so an uppercase-only\r\n   * match identifies them precisely. Matching case-insensitively would make\r\n   * `/^e[a-z]+$/i` swallow ordinary French words beginning with \"e\" — \"erreur\",\r\n   * \"expiré\", \"échec\" — turning a real business message into a generic fallback,\r\n   * which is the more damaging failure this list is tuned against.\r\n   *\r\n   * ⚠ An earlier version of the first pattern was `/^ec[a-z]+$/i`, which matched\r\n   * `ECONNREFUSED` (it begins \"EC\") but silently MISSED `ETIMEDOUT` (\"ET\"),\r\n   * despite the comment claiming otherwise. The unit test caught it. Do not\r\n   * narrow the prefix again: the family is \"E + uppercase word\", not \"EC...\".\r\n   *\r\n   * Residual, accepted: an all-caps single word like \"ERREUR\" is treated as an\r\n   * errno code. A module should not be throwing all-caps single-word messages at\r\n   * users, and replacing one with a proper French fallback is an improvement. */\r\n  /^E[A-Z]{3,}$/, // errno: ETIMEDOUT, ECONNREFUSED, ECONNRESET, ENOTFOUND, EPIPE\r\n  /^ERR_[A-Z_]+$/, // axios: ERR_NETWORK, ERR_CANCELED, ERR_BAD_RESPONSE\r\n];\r\n\r\n/** Is this string an axios/transport artefact rather than something for a user? */\r\nconst isTransportMessage = (value: string): boolean =>\r\n  TRANSPORT_MESSAGE_PATTERNS.some((pattern) => pattern.test(value.trim()));\r\n\r\n/**\r\n * `error.message`, but only when it is fit to show a user.\r\n *\r\n * Suppresses transport phrasings (G-07) so the caller's French fallback is\r\n * reached instead. Module-thrown `Error` messages pass through untouched.\r\n */\r\nconst asUserFacingMessage = (value: unknown): string | undefined => {\r\n  const text = asNonEmptyString(value);\r\n  if (text === undefined) return undefined;\r\n  return isTransportMessage(text) ? undefined : text;\r\n};\r\n\r\n/**\r\n * Best available human-readable message for a rejection of unknown shape.\r\n *\r\n * Resolution order, first match wins:\r\n *   1. the rejection itself, when it is a non-empty string;\r\n *   2. `error.response.data.message` — the backend's own message;\r\n *   3. `error.message` — **only when it is not a transport artefact** (G-07);\r\n *   4. `fallback`.\r\n *\r\n * Step 3 is filtered: `\"Request failed with status code 500\"`, `\"Network Error\"`,\r\n * timeouts and errno codes are SUPPRESSED so the caller's own French copy is\r\n * used instead (Charter §09.3 — no raw technical detail). A message a module\r\n * threw deliberately still passes through. Use `getApiErrorDetail` when you want\r\n * the unfiltered string for a log.\r\n *\r\n * Never throws and never returns an empty string, so it is safe to render\r\n * directly into a toast or a `Banner`.\r\n *\r\n * @param error    The caught value. `unknown` by design.\r\n * @param fallback Message when nothing usable is found.\r\n */\r\nexport function getApiErrorMessage(\r\n  error: unknown,\r\n  fallback: string = DEFAULT_API_ERROR_MESSAGE\r\n): string {\r\n  if (typeof error === \"string\" && error.length > 0) return error;\r\n\r\n  return (\r\n    asNonEmptyString(readPath(error, [\"response\", \"data\", \"message\"])) ??\r\n    asUserFacingMessage(readPath(error, [\"message\"])) ??\r\n    fallback\r\n  );\r\n}\r\n\r\n/**\r\n * Unfiltered technical detail for LOGGING — never for display.\r\n *\r\n * `getApiErrorMessage` deliberately suppresses transport phrasings (G-07), which\r\n * is right for a toast and wrong for a console or an APM breadcrumb, where\r\n * `\"Request failed with status code 502\"` is exactly what an operator needs. This\r\n * is the escape hatch: it returns the raw `error.message` when there is one,\r\n * whatever its shape.\r\n *\r\n * Pair them:\r\n *\r\n *     toast(getApiErrorMessage(err, \"Échec de l'envoi.\"), \"error\");\r\n *     console.error(\"[submit]\", getApiErrorStatus(err), getApiErrorDetail(err));\r\n */\r\nexport function getApiErrorDetail(error: unknown): string | undefined {\r\n  if (typeof error === \"string\" && error.length > 0) return error;\r\n  return asNonEmptyString(readPath(error, [\"message\"]));\r\n}\r\n\r\n/**\r\n * HTTP status carried by a rejection, when there is one.\r\n *\r\n * Returns `undefined` for a network drop, a timeout, or any non-HTTP rejection —\r\n * which is the signal callers use to distinguish \"the server answered with an\r\n * error\" from \"there was no answer at all\" (Charter R-4.3: a status-less failure\r\n * is a network banner, not a toast).\r\n */\r\nexport function getApiErrorStatus(error: unknown): number | undefined {\r\n  const status = readPath(error, [\"response\", \"status\"]);\r\n  return typeof status === \"number\" ? status : undefined;\r\n}\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;;AAEA;AACA;AACA;AACA;AACA;AACO,IAAMA,yBAAyB,GAAAC,OAAA,CAAAD,yBAAA,GACpC,8CAA8C;;AAEhD;AACA;AACA;AACA;AACA,IAAME,QAAQ,GAAG,SAAXA,QAAQA,CAAIC,MAAe,EAAEC,IAAuB,EAAc;EACtE,IAAIC,OAAgB,GAAGF,MAAM;EAAC,IAAAG,SAAA,GAAAC,0BAAA,CAEZH,IAAI;IAAAI,KAAA;EAAA;IAAtB,KAAAF,SAAA,CAAAG,CAAA,MAAAD,KAAA,GAAAF,SAAA,CAAAI,CAAA,IAAAC,IAAA,GAAwB;MAAA,IAAbC,GAAG,GAAAJ,KAAA,CAAAK,KAAA;MACZ,IAAIC,OAAA,CAAOT,OAAO,MAAK,QAAQ,IAAIA,OAAO,KAAK,IAAI,IAAI,EAAEO,GAAG,IAAIP,OAAO,CAAC,EAAE;QACxE,OAAOU,SAAS;MAClB;MACAV,OAAO,GAAGW,OAAO,CAACC,GAAG,CAACZ,OAAO,EAAEO,GAAG,CAAC;IACrC;EAAC,SAAAM,GAAA;IAAAZ,SAAA,CAAAa,CAAA,CAAAD,GAAA;EAAA;IAAAZ,SAAA,CAAAc,CAAA;EAAA;EAED,OAAOf,OAAO;AAChB,CAAC;AAED,IAAMgB,gBAAgB,GAAG,SAAnBA,gBAAgBA,CAAIR,KAAc;EAAA,OACtC,OAAOA,KAAK,KAAK,QAAQ,IAAIA,KAAK,CAACS,MAAM,GAAG,CAAC,GAAGT,KAAK,GAAGE,SAAS;AAAA;;AAEnE;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,IAAMQ,0BAA6C,GAAG,CACpD,wCAAwC,EACxC,kBAAkB,EAClB,8BAA8B,EAC9B,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,wBAAwB,EACxB,kCAAkC,EAClC,mBAAmB;AACnB;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACE,cAAc;AAAE;AAChB,eAAe,CAAE;AAAA,CAClB;;AAED;AACA,IAAMC,kBAAkB,GAAG,SAArBA,kBAAkBA,CAAIX,KAAa;EAAA,OACvCU,0BAA0B,CAACE,IAAI,CAAC,UAACC,OAAO;IAAA,OAAKA,OAAO,CAACC,IAAI,CAACd,KAAK,CAACe,IAAI,CAAC,CAAC,CAAC;EAAA,EAAC;AAAA;;AAE1E;AACA;AACA;AACA;AACA;AACA;AACA,IAAMC,mBAAmB,GAAG,SAAtBA,mBAAmBA,CAAIhB,KAAc,EAAyB;EAClE,IAAMiB,IAAI,GAAGT,gBAAgB,CAACR,KAAK,CAAC;EACpC,IAAIiB,IAAI,KAAKf,SAAS,EAAE,OAAOA,SAAS;EACxC,OAAOS,kBAAkB,CAACM,IAAI,CAAC,GAAGf,SAAS,GAAGe,IAAI;AACpD,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,kBAAkBA,CAChCC,KAAc,EAEN;EAAA,IAAAC,IAAA,EAAAC,iBAAA;EAAA,IADRC,QAAgB,GAAAC,SAAA,CAAAd,MAAA,QAAAc,SAAA,QAAArB,SAAA,GAAAqB,SAAA,MAAGpC,yBAAyB;EAE5C,IAAI,OAAOgC,KAAK,KAAK,QAAQ,IAAIA,KAAK,CAACV,MAAM,GAAG,CAAC,EAAE,OAAOU,KAAK;EAE/D,QAAAC,IAAA,IAAAC,iBAAA,GACEb,gBAAgB,CAACnB,QAAQ,CAAC8B,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,cAAAE,iBAAA,cAAAA,iBAAA,GAClEL,mBAAmB,CAAC3B,QAAQ,CAAC8B,KAAK,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,cAAAC,IAAA,cAAAA,IAAA,GACjDE,QAAQ;AAEZ;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,iBAAiBA,CAACL,KAAc,EAAsB;EACpE,IAAI,OAAOA,KAAK,KAAK,QAAQ,IAAIA,KAAK,CAACV,MAAM,GAAG,CAAC,EAAE,OAAOU,KAAK;EAC/D,OAAOX,gBAAgB,CAACnB,QAAQ,CAAC8B,KAAK,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;AACvD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASM,iBAAiBA,CAACN,KAAc,EAAsB;EACpE,IAAMO,MAAM,GAAGrC,QAAQ,CAAC8B,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;EACtD,OAAO,OAAOO,MAAM,KAAK,QAAQ,GAAGA,MAAM,GAAGxB,SAAS;AACxD","ignoreList":[]}

package/dist/v2/utils/contrast.d.ts

@@ -0,0 +1,68 @@
+/**
+ * WCAG 2.1 contrast utilities — Portnet UI v2
+ *
+ * Reference: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+ *
+ * Pure functions, framework-agnostic, no deps. Reusable by any
+ * host module that needs to validate a runtime brand override
+ * against WCAG 1.4.3 AA (typical scenario: a host-shell event
+ * injects a tenant brand and the consumer wants to dev-warn when
+ * the resulting accent/foreground pair drops below 4.5:1).
+ *
+ * Also used by the dark-mode work (F29) to audit dual-mode token
+ * pairs and by Storybook contrast stories.
+ */
+/** Normal text contrast ratio threshold (AA). */
+export declare const WCAG_AA_NORMAL = 4.5;
+/** Large text (≥ 18pt or ≥ 14pt bold) contrast ratio threshold (AA). */
+export declare const WCAG_AA_LARGE = 3;
+/** UI components & graphical objects contrast ratio threshold (AA 1.4.11). */
+export declare const WCAG_AA_UI_NON_TEXT = 3;
+type RGB = {
+    r: number;
+    g: number;
+    b: number;
+};
+/**
+ * Parse a CSS color string into an { r, g, b } object with 0..255
+ * channels. Returns null for unparseable input.
+ *
+ * Supported formats:
+ *   - "#RGB"      (3-digit hex shorthand)
+ *   - "#RRGGBB"   (6-digit hex)
+ *   - "#RRGGBBAA" (8-digit hex; alpha channel is dropped)
+ *   - "rgb(r, g, b)"
+ *   - "rgba(r, g, b, a)" (alpha dropped)
+ *
+ * HSL / HWB / LAB / named-colors are NOT supported — the v2 token
+ * surface and observed host-shell brand payloads are always hex
+ * or rgb(). A wider parser can be swapped in later without
+ * changing the public API of this function.
+ */
+export declare function parseColor(input: unknown): RGB | null;
+/**
+ * Compute relative luminance of an sRGB color per WCAG 2.1.
+ * Accepts an { r, g, b } object (channels in 0..255).
+ * Returns a number in 0..1, or null if input is invalid.
+ */
+export declare function relativeLuminance(rgb: RGB | null | undefined): number | null;
+/**
+ * WCAG contrast ratio between two colors.
+ *
+ * Accepts either CSS color strings (parsed via parseColor) or
+ * already-parsed { r, g, b } objects. Returns a number in
+ * [1.0, 21.0], or null if either input is unparseable.
+ */
+export declare function contrastRatio(c1: string | RGB, c2: string | RGB): number | null;
+/**
+ * Verdict helper — `passesContrast(ratio, "normal")` returns true
+ * if the ratio meets the requested WCAG AA threshold. Returns
+ * false on null ratios so callers can treat unparseable inputs as
+ * failures.
+ *
+ * `level` accepts "normal" | "large" | "ui". Unknown levels default
+ * to the strictest threshold.
+ */
+export declare function passesContrast(ratio: number | null | undefined, level?: "normal" | "large" | "ui"): boolean;
+export {};
+//# sourceMappingURL=contrast.d.ts.map

package/dist/v2/utils/contrast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/utils/contrast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,iDAAiD;AACjD,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,wEAAwE;AACxE,eAAO,MAAM,aAAa,IAAM,CAAC;AAEjC,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,IAAM,CAAC;AAIvC,KAAK,GAAG,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,GAAG,IAAI,CAyCrD;AAUD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAU5E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,GAAG,GAAG,EAChB,EAAE,EAAE,MAAM,GAAG,GAAG,GACf,MAAM,GAAG,IAAI,CASf;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,KAAK,GAAE,QAAQ,GAAG,OAAO,GAAG,IAAe,GAC1C,OAAO,CAgBT"}