@portnet/ui 5.0.28 → 6.0.0

package/dist/v2/hooks/useFocusFirstError.js

@@ -0,0 +1,203 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = useFocusFirstError;
+exports.focusFieldByName = focusFieldByName;
+var _react = require("react");
+/**
+ * useFocusFirstError — Portnet UI v2
+ *
+ * Charter §05.3 R-F.3 MUST — "Submit form échoué → focus sur premier champ
+ * en erreur". Charter §04.1 R-FV.3 MUST — "Scroll auto vers premier champ
+ * en erreur + focus". Both are the same behaviour; this is it, once.
+ *
+ * Formik-FREE on purpose, exactly like useFormAutoSave: the caller passes
+ * `errors`, `submitCount` and the rendered field order as plain values.
+ * Formik coupling belongs in patterns/ — use <FormikErrorFocus /> when the
+ * form is a Formik form and this hook directly when it is not (a manual
+ * "Ajouter" guard, a non-Formik dropzone section, a reducer-driven form).
+ *
+ *   // Formik form — prefer the pattern, which wires this for you:
+ *   <FormikErrorFocus order={["numeroFacture", "fournisseur", "dateFacture"]} />
+ *
+ *   // Manual guard — call the imperative helper directly:
+ *   const missing = requiredFields.filter((f) => !f.value);
+ *   if (missing.length > 0) {
+ *     missing.forEach((f) => setFieldError(f.name, REQUIRED));
+ *     focusFieldByName(missing[0].name);
+ *     return;
+ *   }
+ *
+ * ── WHY THE `[id=]` LOOKUP COMES FIRST ──────────────────────────────
+ *
+ * Hosts have consistently written `[name="<field>"]`, which is wrong for
+ * most v2 fields. The Formik bridges wrap their control in Field, which
+ * does `htmlFor={htmlFor || name}` and then
+ * `cloneElement(child, { id: inputId })` — so the field NAME is published
+ * as the control's `id`, and whether it also appears as `name` depends
+ * entirely on which primitive is underneath. It does for Input/Textarea.
+ * It does not for Select, Combobox, DatePicker or ReferentielField.
+ *
+ * A `[name=]`-only selector therefore fails precisely on the compound
+ * fields, silently — the call runs, matches nothing, and the form reads as
+ * compliant. `[id=]` is guaranteed by the Field contract for every bridge,
+ * so it is tried first; `[name=]` and `[data-field=]` remain as fallbacks
+ * for hand-rolled controls that never went through Field.
+ *
+ * ── WHAT THIS DELIBERATELY DOES NOT DO ──────────────────────────────
+ *
+ * It does not focus a control it cannot see. A field inside a collapsed
+ * <details> (Accordion.Item) or a display:none branch has no client rects,
+ * and focusing it would scroll the page to an invisible target and strand
+ * the user with no visible focus ring. `focusFieldByName` returns false in
+ * that case and dev-warns rather than guessing — the inline error
+ * (role="alert" via Field) still carries the message, and R-FV.2's summary
+ * banner (FormErrorSummary) is the right affordance for reaching a field
+ * in a closed section.
+ *
+ * It also does not announce anything. Field already renders its error with
+ * role="alert"; a second live region would double-announce.
+ */
+
+/** Options for the imperative helper. */
+
+/**
+ * Focusable descendants, for the case where the resolved element is a
+ * wrapper rather than the control itself. Excludes tabindex="-1", which is
+ * programmatically focusable but deliberately out of the tab order — landing
+ * there would put the user somewhere Tab cannot return to.
+ */
+var FOCUSABLE_WITHIN = 'input,select,textarea,button,[href],[tabindex]:not([tabindex="-1"])';
+
+/**
+ * Escape a value for use inside an attribute selector.
+ *
+ * CSS.escape where available, with a manual quote/backslash escape as the
+ * fallback — same guard shape DataGrid uses for its reorder-grip lookup.
+ * Field names are developer-authored, so this is robustness rather than a
+ * sanitisation boundary.
+ */
+function escapeAttributeValue(value) {
+  if (typeof window !== "undefined" && window.CSS && typeof window.CSS.escape === "function") {
+    return window.CSS.escape(value);
+  }
+  return value.replace(/["\\]/g, "\\$&");
+}
+
+/**
+ * Is this element something a user can actually be sent to?
+ *
+ * `getClientRects().length === 0` is what excludes a field inside a
+ * collapsed <details> or a display:none branch. offsetParent alone is not
+ * enough — it is also null for position:fixed elements, which are visible.
+ */
+function isFocusableNow(el) {
+  if (!(el instanceof HTMLElement)) return false;
+  if (el.hasAttribute("disabled")) return false;
+  if (el.getAttribute("aria-hidden") === "true") return false;
+  if (el.getClientRects().length === 0) return false;
+  return true;
+}
+
+/**
+ * Focus the control registered under `name`, resolving it the way the v2
+ * Field contract publishes it.
+ *
+ * @returns true when a visible, enabled control was focused. False means
+ *          nothing matched, or the match was hidden or disabled — the
+ *          caller should keep its inline error and, ideally, render
+ *          FormErrorSummary so the field is still reachable.
+ */
+function focusFieldByName(name) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  if (typeof document === "undefined") return false;
+  if (!name) return false;
+  var escaped = escapeAttributeValue(name);
+
+  /* Order matters — see the `[id=]` note in the module docstring. */
+  var selectors = ["[id=\"".concat(escaped, "\"]"), "[name=\"".concat(escaped, "\"]"), "[data-field=\"".concat(escaped, "\"]")];
+  for (var _i = 0, _selectors = selectors; _i < _selectors.length; _i++) {
+    var selector = _selectors[_i];
+    var host = null;
+    try {
+      host = document.querySelector(selector);
+    } catch (_unused) {
+      /* Malformed selector — try the next shape rather than throwing into
+         the caller's validation branch. */
+      host = null;
+    }
+    if (host === null) continue;
+    var target = isFocusableNow(host) ? host : host.querySelector(FOCUSABLE_WITHIN);
+    if (!isFocusableNow(target)) continue;
+    if (options.scroll !== false) {
+      try {
+        target.scrollIntoView({
+          block: "center",
+          behavior: "auto"
+        });
+      } catch (_unused2) {
+        /* jsdom and older Safari lack the options overload. Focus below
+           still scrolls the control into view natively. */
+      }
+    }
+    target.focus();
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Move focus to the first field in error after each failed submit.
+ *
+ * Fires when `submitCount` increases AND an error is present. The two
+ * conditions are separate on purpose: Formik increments submitCount before
+ * async validation resolves, so on the render where the counter changes
+ * `errors` can still be empty. Marking the attempt handled only once an
+ * error is actually found lets the effect re-run when the errors land,
+ * without re-firing for the same attempt afterwards.
+ */
+function useFocusFirstError(_ref) {
+  var errors = _ref.errors,
+    order = _ref.order,
+    _ref$submitCount = _ref.submitCount,
+    submitCount = _ref$submitCount === void 0 ? 0 : _ref$submitCount,
+    _ref$enabled = _ref.enabled,
+    enabled = _ref$enabled === void 0 ? true : _ref$enabled,
+    _ref$scroll = _ref.scroll,
+    scroll = _ref$scroll === void 0 ? true : _ref$scroll;
+  /** Highest submitCount already acted on. */
+  var handledRef = (0, _react.useRef)(0);
+  (0, _react.useEffect)(function () {
+    if (!enabled) return undefined;
+    if (submitCount <= handledRef.current) return undefined;
+    if (!errors) return undefined;
+    var names = order !== undefined && order.length > 0 ? order : Object.keys(errors);
+    var first = names.find(function (name) {
+      return Boolean(errors[name]);
+    });
+
+    /* No error yet: either validation is still in flight for this attempt,
+       or it passed. Leave handledRef alone so a later errors update for the
+       SAME attempt is still honoured. */
+    if (first === undefined) return undefined;
+    handledRef.current = submitCount;
+
+    /* One frame, so the inline errors have rendered and the target exists
+       and is measurable before it is focused and scrolled to. */
+    var frame = requestAnimationFrame(function () {
+      var focused = focusFieldByName(first, {
+        scroll: scroll
+      });
+      if (!focused && process.env["NODE_ENV"] !== "production") {
+        // eslint-disable-next-line no-console
+        console.warn("[v2.useFocusFirstError] Could not focus \"".concat(first, "\" \u2014 no visible, ") + "enabled control matched [id], [name] or [data-field]. Either the " + "field is in a collapsed section, or its control does not publish " + "the field name (a hand-rolled control that skips Field). R-F.3 is " + "NOT satisfied for this field; render FormErrorSummary (R-FV.2) so " + "it stays reachable.");
+      }
+    });
+    return function () {
+      return cancelAnimationFrame(frame);
+    };
+  }, [errors, order, submitCount, enabled, scroll]);
+}
+//# sourceMappingURL=useFocusFirstError.js.map

package/dist/v2/hooks/useFocusFirstError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusFirstError.js","names":["_react","require","FOCUSABLE_WITHIN","escapeAttributeValue","value","window","CSS","escape","replace","isFocusableNow","el","HTMLElement","hasAttribute","getAttribute","getClientRects","length","focusFieldByName","name","options","arguments","undefined","document","escaped","selectors","concat","_i","_selectors","selector","host","querySelector","_unused","target","scroll","scrollIntoView","block","behavior","_unused2","focus","useFocusFirstError","_ref","errors","order","_ref$submitCount","submitCount","_ref$enabled","enabled","_ref$scroll","handledRef","useRef","useEffect","current","names","Object","keys","first","find","Boolean","frame","requestAnimationFrame","focused","process","env","console","warn","cancelAnimationFrame"],"sources":["../../../src/lib/v2/hooks/useFocusFirstError.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\r\n\r\n/**\r\n * useFocusFirstError — Portnet UI v2\r\n *\r\n * Charter §05.3 R-F.3 MUST — \"Submit form échoué → focus sur premier champ\r\n * en erreur\". Charter §04.1 R-FV.3 MUST — \"Scroll auto vers premier champ\r\n * en erreur + focus\". Both are the same behaviour; this is it, once.\r\n *\r\n * Formik-FREE on purpose, exactly like useFormAutoSave: the caller passes\r\n * `errors`, `submitCount` and the rendered field order as plain values.\r\n * Formik coupling belongs in patterns/ — use <FormikErrorFocus /> when the\r\n * form is a Formik form and this hook directly when it is not (a manual\r\n * \"Ajouter\" guard, a non-Formik dropzone section, a reducer-driven form).\r\n *\r\n *   // Formik form — prefer the pattern, which wires this for you:\r\n *   <FormikErrorFocus order={[\"numeroFacture\", \"fournisseur\", \"dateFacture\"]} />\r\n *\r\n *   // Manual guard — call the imperative helper directly:\r\n *   const missing = requiredFields.filter((f) => !f.value);\r\n *   if (missing.length > 0) {\r\n *     missing.forEach((f) => setFieldError(f.name, REQUIRED));\r\n *     focusFieldByName(missing[0].name);\r\n *     return;\r\n *   }\r\n *\r\n * ── WHY THE `[id=]` LOOKUP COMES FIRST ──────────────────────────────\r\n *\r\n * Hosts have consistently written `[name=\"<field>\"]`, which is wrong for\r\n * most v2 fields. The Formik bridges wrap their control in Field, which\r\n * does `htmlFor={htmlFor || name}` and then\r\n * `cloneElement(child, { id: inputId })` — so the field NAME is published\r\n * as the control's `id`, and whether it also appears as `name` depends\r\n * entirely on which primitive is underneath. It does for Input/Textarea.\r\n * It does not for Select, Combobox, DatePicker or ReferentielField.\r\n *\r\n * A `[name=]`-only selector therefore fails precisely on the compound\r\n * fields, silently — the call runs, matches nothing, and the form reads as\r\n * compliant. `[id=]` is guaranteed by the Field contract for every bridge,\r\n * so it is tried first; `[name=]` and `[data-field=]` remain as fallbacks\r\n * for hand-rolled controls that never went through Field.\r\n *\r\n * ── WHAT THIS DELIBERATELY DOES NOT DO ──────────────────────────────\r\n *\r\n * It does not focus a control it cannot see. A field inside a collapsed\r\n * <details> (Accordion.Item) or a display:none branch has no client rects,\r\n * and focusing it would scroll the page to an invisible target and strand\r\n * the user with no visible focus ring. `focusFieldByName` returns false in\r\n * that case and dev-warns rather than guessing — the inline error\r\n * (role=\"alert\" via Field) still carries the message, and R-FV.2's summary\r\n * banner (FormErrorSummary) is the right affordance for reaching a field\r\n * in a closed section.\r\n *\r\n * It also does not announce anything. Field already renders its error with\r\n * role=\"alert\"; a second live region would double-announce.\r\n */\r\n\r\n/** Options for the imperative helper. */\r\nexport type FocusFieldOptions = {\r\n  /**\r\n   * Scroll the resolved control into view before focusing.\r\n   *\r\n   * `behavior: \"auto\"` always — never \"smooth\". R-Tg.2 caps animation at\r\n   * 0.01 ms under prefers-reduced-motion, and a smooth scroll triggered by\r\n   * a failed submit is exactly the motion that rule exists to suppress.\r\n   *\r\n   * @default true\r\n   */\r\n  scroll?: boolean | undefined;\r\n};\r\n\r\nexport type UseFocusFirstErrorOptions = {\r\n  /**\r\n   * Field name -> error. Formik's `errors` satisfies this directly.\r\n   *\r\n   * Only truthiness is read, so any error shape works (string, node,\r\n   * nested object).\r\n   */\r\n  errors?: Readonly<Record<string, unknown>> | undefined;\r\n  /**\r\n   * Field names in RENDERED order — top-to-bottom as the user sees them.\r\n   *\r\n   * SUPPLY THIS. Without it the order falls back to `Object.keys(errors)`,\r\n   * which is the order the validator happened to write its keys in and has\r\n   * no relationship to the layout; \"first field in error\" then means\r\n   * \"whichever field Yup reached first\", which can be the last one on\r\n   * screen.\r\n   */\r\n  order?: readonly string[] | undefined;\r\n  /**\r\n   * Submit attempt counter. Formik's `submitCount`.\r\n   *\r\n   * This is the TRIGGER: focus moves when it increases, never on an\r\n   * ordinary re-render. Without it a persisting error would re-steal focus\r\n   * every time the component re-rendered, which is worse than not moving\r\n   * focus at all.\r\n   */\r\n  submitCount?: number | undefined;\r\n  /** @default true */\r\n  enabled?: boolean | undefined;\r\n  /** @default true */\r\n  scroll?: boolean | undefined;\r\n};\r\n\r\n/**\r\n * Focusable descendants, for the case where the resolved element is a\r\n * wrapper rather than the control itself. Excludes tabindex=\"-1\", which is\r\n * programmatically focusable but deliberately out of the tab order — landing\r\n * there would put the user somewhere Tab cannot return to.\r\n */\r\nconst FOCUSABLE_WITHIN =\r\n  'input,select,textarea,button,[href],[tabindex]:not([tabindex=\"-1\"])';\r\n\r\n/**\r\n * Escape a value for use inside an attribute selector.\r\n *\r\n * CSS.escape where available, with a manual quote/backslash escape as the\r\n * fallback — same guard shape DataGrid uses for its reorder-grip lookup.\r\n * Field names are developer-authored, so this is robustness rather than a\r\n * sanitisation boundary.\r\n */\r\nfunction escapeAttributeValue(value: string): string {\r\n  if (\r\n    typeof window !== \"undefined\" &&\r\n    window.CSS &&\r\n    typeof window.CSS.escape === \"function\"\r\n  ) {\r\n    return window.CSS.escape(value);\r\n  }\r\n  return value.replace(/[\"\\\\]/g, \"\\\\$&\");\r\n}\r\n\r\n/**\r\n * Is this element something a user can actually be sent to?\r\n *\r\n * `getClientRects().length === 0` is what excludes a field inside a\r\n * collapsed <details> or a display:none branch. offsetParent alone is not\r\n * enough — it is also null for position:fixed elements, which are visible.\r\n */\r\nfunction isFocusableNow(el: Element | null): el is HTMLElement {\r\n  if (!(el instanceof HTMLElement)) return false;\r\n  if (el.hasAttribute(\"disabled\")) return false;\r\n  if (el.getAttribute(\"aria-hidden\") === \"true\") return false;\r\n  if (el.getClientRects().length === 0) return false;\r\n  return true;\r\n}\r\n\r\n/**\r\n * Focus the control registered under `name`, resolving it the way the v2\r\n * Field contract publishes it.\r\n *\r\n * @returns true when a visible, enabled control was focused. False means\r\n *          nothing matched, or the match was hidden or disabled — the\r\n *          caller should keep its inline error and, ideally, render\r\n *          FormErrorSummary so the field is still reachable.\r\n */\r\nexport function focusFieldByName(\r\n  name: string,\r\n  options: FocusFieldOptions = {}\r\n): boolean {\r\n  if (typeof document === \"undefined\") return false;\r\n  if (!name) return false;\r\n\r\n  const escaped = escapeAttributeValue(name);\r\n\r\n  /* Order matters — see the `[id=]` note in the module docstring. */\r\n  const selectors = [\r\n    `[id=\"${escaped}\"]`,\r\n    `[name=\"${escaped}\"]`,\r\n    `[data-field=\"${escaped}\"]`,\r\n  ];\r\n\r\n  for (const selector of selectors) {\r\n    let host: Element | null = null;\r\n    try {\r\n      host = document.querySelector(selector);\r\n    } catch {\r\n      /* Malformed selector — try the next shape rather than throwing into\r\n         the caller's validation branch. */\r\n      host = null;\r\n    }\r\n    if (host === null) continue;\r\n\r\n    const target = isFocusableNow(host)\r\n      ? host\r\n      : host.querySelector(FOCUSABLE_WITHIN);\r\n\r\n    if (!isFocusableNow(target)) continue;\r\n\r\n    if (options.scroll !== false) {\r\n      try {\r\n        target.scrollIntoView({ block: \"center\", behavior: \"auto\" });\r\n      } catch {\r\n        /* jsdom and older Safari lack the options overload. Focus below\r\n           still scrolls the control into view natively. */\r\n      }\r\n    }\r\n\r\n    target.focus();\r\n    return true;\r\n  }\r\n\r\n  return false;\r\n}\r\n\r\n/**\r\n * Move focus to the first field in error after each failed submit.\r\n *\r\n * Fires when `submitCount` increases AND an error is present. The two\r\n * conditions are separate on purpose: Formik increments submitCount before\r\n * async validation resolves, so on the render where the counter changes\r\n * `errors` can still be empty. Marking the attempt handled only once an\r\n * error is actually found lets the effect re-run when the errors land,\r\n * without re-firing for the same attempt afterwards.\r\n */\r\nexport default function useFocusFirstError({\r\n  errors,\r\n  order,\r\n  submitCount = 0,\r\n  enabled = true,\r\n  scroll = true,\r\n}: UseFocusFirstErrorOptions): void {\r\n  /** Highest submitCount already acted on. */\r\n  const handledRef = useRef(0);\r\n\r\n  useEffect(() => {\r\n    if (!enabled) return undefined;\r\n    if (submitCount <= handledRef.current) return undefined;\r\n    if (!errors) return undefined;\r\n\r\n    const names =\r\n      order !== undefined && order.length > 0 ? order : Object.keys(errors);\r\n\r\n    const first = names.find((name) => Boolean(errors[name]));\r\n\r\n    /* No error yet: either validation is still in flight for this attempt,\r\n       or it passed. Leave handledRef alone so a later errors update for the\r\n       SAME attempt is still honoured. */\r\n    if (first === undefined) return undefined;\r\n\r\n    handledRef.current = submitCount;\r\n\r\n    /* One frame, so the inline errors have rendered and the target exists\r\n       and is measurable before it is focused and scrolled to. */\r\n    const frame = requestAnimationFrame(() => {\r\n      const focused = focusFieldByName(first, { scroll });\r\n\r\n      if (!focused && process.env[\"NODE_ENV\"] !== \"production\") {\r\n        // eslint-disable-next-line no-console\r\n        console.warn(\r\n          `[v2.useFocusFirstError] Could not focus \"${first}\" — no visible, ` +\r\n            \"enabled control matched [id], [name] or [data-field]. Either the \" +\r\n            \"field is in a collapsed section, or its control does not publish \" +\r\n            \"the field name (a hand-rolled control that skips Field). R-F.3 is \" +\r\n            \"NOT satisfied for this field; render FormErrorSummary (R-FV.2) so \" +\r\n            \"it stays reachable.\"\r\n        );\r\n      }\r\n    });\r\n\r\n    return () => cancelAnimationFrame(frame);\r\n  }, [errors, order, submitCount, enabled, scroll]);\r\n}\r\n"],"mappings":";;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAEA;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;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AA+CA;AACA;AACA;AACA;AACA;AACA;AACA,IAAMC,gBAAgB,GACpB,qEAAqE;;AAEvE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,oBAAoBA,CAACC,KAAa,EAAU;EACnD,IACE,OAAOC,MAAM,KAAK,WAAW,IAC7BA,MAAM,CAACC,GAAG,IACV,OAAOD,MAAM,CAACC,GAAG,CAACC,MAAM,KAAK,UAAU,EACvC;IACA,OAAOF,MAAM,CAACC,GAAG,CAACC,MAAM,CAACH,KAAK,CAAC;EACjC;EACA,OAAOA,KAAK,CAACI,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC;AACxC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,cAAcA,CAACC,EAAkB,EAAqB;EAC7D,IAAI,EAAEA,EAAE,YAAYC,WAAW,CAAC,EAAE,OAAO,KAAK;EAC9C,IAAID,EAAE,CAACE,YAAY,CAAC,UAAU,CAAC,EAAE,OAAO,KAAK;EAC7C,IAAIF,EAAE,CAACG,YAAY,CAAC,aAAa,CAAC,KAAK,MAAM,EAAE,OAAO,KAAK;EAC3D,IAAIH,EAAE,CAACI,cAAc,CAAC,CAAC,CAACC,MAAM,KAAK,CAAC,EAAE,OAAO,KAAK;EAClD,OAAO,IAAI;AACb;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,gBAAgBA,CAC9BC,IAAY,EAEH;EAAA,IADTC,OAA0B,GAAAC,SAAA,CAAAJ,MAAA,QAAAI,SAAA,QAAAC,SAAA,GAAAD,SAAA,MAAG,CAAC,CAAC;EAE/B,IAA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","ignoreList":[]}

package/dist/v2/hooks/useFocusTrap.d.ts

@@ -0,0 +1,3 @@
+import { type RefObject } from "react";
+export default function useFocusTrap<T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, isActive: boolean): void;
+//# sourceMappingURL=useFocusTrap.d.ts.map

package/dist/v2/hooks/useFocusTrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/hooks/useFocusTrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AA0IlD,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACtE,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EACxB,QAAQ,EAAE,OAAO,GAChB,IAAI,CAgGN"}

package/dist/v2/hooks/useFocusTrap.js

@@ -0,0 +1,207 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = useFocusTrap;
+var _react = require("react");
+/**
+ * useFocusTrap — Portnet UI v2
+ *
+ * Traps Tab / Shift+Tab inside `ref` while `isActive`.
+ * On activation, focuses the first `[autofocus]` / `[data-autofocus]`
+ * descendant if present, otherwise the first focusable child.
+ * On deactivation, restores focus to the element that previously held
+ * it (only if still in the DOM).
+ *
+ * WCAG 2.4.3, charter R-F.2.
+ *
+ * Implementation notes
+ *   - Keydown listener attached to `document` in capture phase. If
+ *     focus has somehow escaped the container, the next Tab is caught
+ *     and warped back inside.
+ *   - NESTED TRAPS — only the topmost trap on `trapStack` intercepts
+ *     Tab. Outer traps stay registered and resume duty when the inner
+ *     trap unmounts. This makes ConfirmDialog-in-Drawer-in-Modal
+ *     flows behave correctly.
+ *   - Focusable elements are filtered to exclude those inside
+ *     aria-hidden / inert / hidden / display:none subtrees, even
+ *     though querySelectorAll happily returns them.
+ *   - BOUNDARY SCOPE — Tab is intercepted only at the cycle edges
+ *     (Tab on `last`, Shift+Tab on `first`) plus the escaped-focus
+ *     recovery path. Mid-cycle moves are deliberately left to the
+ *     browser's native tab order.
+ *
+ *     Consequence worth knowing: the filter above decides what counts
+ *     as `first` / `last`, so the trap never DELIVERS focus into a
+ *     filtered element — but it cannot stop the browser tabbing into
+ *     one mid-cycle. `hidden` and `inert` are unaffected (both remove
+ *     an element from the native tab order); `aria-hidden` is NOT, as
+ *     per spec it annotates only the accessibility tree. So a
+ *     focusable control inside `aria-hidden="true"` IS still reachable
+ *     by Tab — that is a content defect (axe `aria-hidden-focus`), and
+ *     the fix is `inert` on the subtree, not more interception here.
+ *
+ *     Full per-Tab interception would close that gap, at the cost of
+ *     taking over native traversal for every Modal / Drawer /
+ *     ConfirmDialog in the fleet — which also breaks radio-group
+ *     roving tabindex and any positive `tabindex` ordering. Not done
+ *     without a browser-level test bed. See the aria-hidden case in
+ *     __tests__/useFocusTrap.test.tsx.
+ *   - Cleanup never calls focus() on an unmounted or detached
+ *     trigger and cancels the initial-focus rAF.
+ *
+ * Escape handling is INTENTIONALLY OUT OF SCOPE — the consumer (Modal,
+ * Drawer, ConfirmDialog) is responsible for closing on Escape per
+ * R-F.1. Mixing concerns here would force every trap user to opt out.
+ *
+ * @param ref      The container ref to trap focus inside. Accepts a
+ *                 nullable `current` (`RefObject<T | null>`) so callers
+ *                 can pass `useRef<HTMLElement>(null)` directly without a
+ *                 cast — the effect no-ops until `current` is populated.
+ * @param isActive Whether the trap is currently on.
+ */
+
+var FOCUSABLE_SELECTORS = ["a[href]", "button:not(:disabled)", "input:not(:disabled)", "select:not(:disabled)", "textarea:not(:disabled)", '[tabindex]:not([tabindex="-1"])', '[contenteditable]:not([contenteditable="false"])', "audio[controls]", "video[controls]"].join(", ");
+var AUTOFOCUS_SELECTORS = "[autofocus], [data-autofocus]";
+
+/**
+ * Module-level stack of active trap containers. Only the LAST entry
+ * (innermost trap) intercepts Tab; outer traps stay registered but
+ * pass-through. Cleanup pops by reference to tolerate out-of-order
+ * unmount sequences (portal teardown, hot-replace).
+ */
+var trapStack = [];
+
+/**
+ * Is `container` the INNERMOST active trap?
+ *
+ * ⚠ DO NOT REPLACE THIS WITH `trapStack[trapStack.length - 1] === container`.
+ *
+ * Stack POSITION does not track nesting depth. React runs CHILD effects before
+ * PARENT effects, so when an outer and an inner trap mount in the SAME commit
+ * (Modal rendering a ConfirmDialog, Drawer with a nested trap) the INNER trap is
+ * pushed FIRST and the OUTER one LAST — making the last entry the OUTERMOST trap,
+ * the exact opposite of the intent.
+ *
+ * Push order only happens to match nesting when the traps mount at different
+ * times, which is the common case and why the bug stayed hidden. The
+ * simultaneous-mount path gave Tab duty to the trap BEHIND the dialog the user
+ * was looking at (R-M.2 / R-F.2).
+ *
+ * Containment is order-independent: a trap is innermost when no other active
+ * trap lives inside it. Correct for both mount orderings, and for unmount — once
+ * the inner trap pops, the outer contains nothing and resumes duty.
+ */
+function isInnermostTrap(container) {
+  return !trapStack.some(function (other) {
+    return other !== container && container.contains(other);
+  });
+}
+
+/**
+ * True iff the element is rendered AND not inside an aria-hidden /
+ * inert / hidden / display:none ancestor. querySelectorAll picks
+ * those up indiscriminately, so re-filter at use time.
+ */
+function isVisuallyFocusable(el) {
+  if (!el) return false;
+  if ("disabled" in el && el.disabled) return false;
+  if (el.getAttribute && el.getAttribute("aria-disabled") === "true") return false;
+  // Cheap visibility test — covers display:none and visibility:hidden.
+  // Note: elements with `display: contents` may report 0 rects but have
+  // focusable descendants; the descendants themselves still match if
+  // they have their own boxes, so this filter is a reasonable trade-off.
+  if (typeof el.getClientRects === "function" && el.getClientRects().length === 0) {
+    return false;
+  }
+  // Walk ancestors for hidden / aria-hidden / inert.
+  var node = el;
+  while (node && node !== document.body) {
+    if (node.hasAttribute && (node.hasAttribute("inert") || node.hasAttribute("hidden") || node.getAttribute("aria-hidden") === "true")) {
+      return false;
+    }
+    node = node.parentElement;
+  }
+  return true;
+}
+function useFocusTrap(ref, isActive) {
+  (0, _react.useEffect)(function () {
+    if (!isActive || !ref.current) return undefined;
+    var container = ref.current;
+    trapStack.push(container);
+    var getFocusable = function getFocusable() {
+      return Array.from(container.querySelectorAll(FOCUSABLE_SELECTORS)).filter(isVisuallyFocusable);
+    };
+    var trigger = document.activeElement;
+
+    // Initial focus, deferred to next frame so React has finished
+    // painting any conditional content. Cancellation handle stored
+    // so unmount-within-same-frame cannot leak a stale .focus() call.
+    var rafId = requestAnimationFrame(function () {
+      /* Only the innermost trap claims initial focus — same predicate as `trap()`
+       * below, so keyboard duty and initial focus can never disagree.
+       *
+       * Initial focus was previously unguarded: every trap focused on
+       * activation regardless of nesting, so on simultaneous mount the outer
+       * trap's rAF fired last and overwrote the inner trap's focus. */
+      if (!isInnermostTrap(container)) return;
+      var explicit = container.querySelector(AUTOFOCUS_SELECTORS);
+      var target = explicit && isVisuallyFocusable(explicit) ? explicit : getFocusable()[0];
+      if (target && typeof target.focus === "function") target.focus();
+    });
+    var trap = function trap(e) {
+      if (e.key !== "Tab") return;
+      // Only the innermost trap acts. Outer traps stay registered and defer.
+      // Containment, NOT stack position — see isInnermostTrap.
+      if (!isInnermostTrap(container)) return;
+      var els = getFocusable();
+      if (!els.length) {
+        // Pathological case (no focusable inside): swallow Tab so
+        // focus cannot escape into the page behind the trap.
+        e.preventDefault();
+        return;
+      }
+      var first = els[0];
+      var last = els[els.length - 1];
+      if (!first || !last) return;
+      var active = document.activeElement;
+
+      // Recovery: if focus is currently OUTSIDE the container, warp it
+      // back to the first focusable. Without this, an escaped focus
+      // (mount race, programmatic blur, SR virtual cursor) leaks Tab
+      // navigation to the page behind the trap.
+      if (!container.contains(active)) {
+        e.preventDefault();
+        first.focus();
+        return;
+      }
+      if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", trap, true);
+    return function () {
+      cancelAnimationFrame(rafId);
+
+      // Pop by reference (NOT by index) — tolerates out-of-order
+      // unmount sequences during portal teardown or hot-replace.
+      var idx = trapStack.lastIndexOf(container);
+      if (idx >= 0) trapStack.splice(idx, 1);
+      document.removeEventListener("keydown", trap, true);
+
+      // Restore focus only if the trigger is still mounted, focusable,
+      // and not currently disabled. Calling .focus() on a detached or
+      // disabled node silently leaves focus on <body> with no visible
+      // indicator — actively user-hostile.
+      if (trigger && trigger !== document.body && "focus" in trigger && typeof trigger.focus === "function" && document.body.contains(trigger) && !("disabled" in trigger && trigger.disabled)) {
+        trigger.focus();
+      }
+    };
+  }, [isActive, ref]);
+}
+//# sourceMappingURL=useFocusTrap.js.map

package/dist/v2/hooks/useFocusTrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusTrap.js","names":["_react","require","FOCUSABLE_SELECTORS","join","AUTOFOCUS_SELECTORS","trapStack","isInnermostTrap","container","some","other","contains","isVisuallyFocusable","el","disabled","getAttribute","getClientRects","length","node","document","body","hasAttribute","parentElement","useFocusTrap","ref","isActive","useEffect","current","undefined","push","getFocusable","Array","from","querySelectorAll","filter","trigger","activeElement","rafId","requestAnimationFrame","explicit","querySelector","target","focus","trap","e","key","els","preventDefault","first","last","active","shiftKey","addEventListener","cancelAnimationFrame","idx","lastIndexOf","splice","removeEventListener"],"sources":["../../../src/lib/v2/hooks/useFocusTrap.ts"],"sourcesContent":["import { useEffect, type RefObject } from \"react\";\r\n\r\n/**\r\n * useFocusTrap — Portnet UI v2\r\n *\r\n * Traps Tab / Shift+Tab inside `ref` while `isActive`.\r\n * On activation, focuses the first `[autofocus]` / `[data-autofocus]`\r\n * descendant if present, otherwise the first focusable child.\r\n * On deactivation, restores focus to the element that previously held\r\n * it (only if still in the DOM).\r\n *\r\n * WCAG 2.4.3, charter R-F.2.\r\n *\r\n * Implementation notes\r\n *   - Keydown listener attached to `document` in capture phase. If\r\n *     focus has somehow escaped the container, the next Tab is caught\r\n *     and warped back inside.\r\n *   - NESTED TRAPS — only the topmost trap on `trapStack` intercepts\r\n *     Tab. Outer traps stay registered and resume duty when the inner\r\n *     trap unmounts. This makes ConfirmDialog-in-Drawer-in-Modal\r\n *     flows behave correctly.\r\n *   - Focusable elements are filtered to exclude those inside\r\n *     aria-hidden / inert / hidden / display:none subtrees, even\r\n *     though querySelectorAll happily returns them.\r\n *   - BOUNDARY SCOPE — Tab is intercepted only at the cycle edges\r\n *     (Tab on `last`, Shift+Tab on `first`) plus the escaped-focus\r\n *     recovery path. Mid-cycle moves are deliberately left to the\r\n *     browser's native tab order.\r\n *\r\n *     Consequence worth knowing: the filter above decides what counts\r\n *     as `first` / `last`, so the trap never DELIVERS focus into a\r\n *     filtered element — but it cannot stop the browser tabbing into\r\n *     one mid-cycle. `hidden` and `inert` are unaffected (both remove\r\n *     an element from the native tab order); `aria-hidden` is NOT, as\r\n *     per spec it annotates only the accessibility tree. So a\r\n *     focusable control inside `aria-hidden=\"true\"` IS still reachable\r\n *     by Tab — that is a content defect (axe `aria-hidden-focus`), and\r\n *     the fix is `inert` on the subtree, not more interception here.\r\n *\r\n *     Full per-Tab interception would close that gap, at the cost of\r\n *     taking over native traversal for every Modal / Drawer /\r\n *     ConfirmDialog in the fleet — which also breaks radio-group\r\n *     roving tabindex and any positive `tabindex` ordering. Not done\r\n *     without a browser-level test bed. See the aria-hidden case in\r\n *     __tests__/useFocusTrap.test.tsx.\r\n *   - Cleanup never calls focus() on an unmounted or detached\r\n *     trigger and cancels the initial-focus rAF.\r\n *\r\n * Escape handling is INTENTIONALLY OUT OF SCOPE — the consumer (Modal,\r\n * Drawer, ConfirmDialog) is responsible for closing on Escape per\r\n * R-F.1. Mixing concerns here would force every trap user to opt out.\r\n *\r\n * @param ref      The container ref to trap focus inside. Accepts a\r\n *                 nullable `current` (`RefObject<T | null>`) so callers\r\n *                 can pass `useRef<HTMLElement>(null)` directly without a\r\n *                 cast — the effect no-ops until `current` is populated.\r\n * @param isActive Whether the trap is currently on.\r\n */\r\n\r\nconst FOCUSABLE_SELECTORS = [\r\n  \"a[href]\",\r\n  \"button:not(:disabled)\",\r\n  \"input:not(:disabled)\",\r\n  \"select:not(:disabled)\",\r\n  \"textarea:not(:disabled)\",\r\n  '[tabindex]:not([tabindex=\"-1\"])',\r\n  '[contenteditable]:not([contenteditable=\"false\"])',\r\n  \"audio[controls]\",\r\n  \"video[controls]\",\r\n].join(\", \");\r\n\r\nconst AUTOFOCUS_SELECTORS = \"[autofocus], [data-autofocus]\";\r\n\r\n/**\r\n * Module-level stack of active trap containers. Only the LAST entry\r\n * (innermost trap) intercepts Tab; outer traps stay registered but\r\n * pass-through. Cleanup pops by reference to tolerate out-of-order\r\n * unmount sequences (portal teardown, hot-replace).\r\n */\r\nconst trapStack: HTMLElement[] = [];\r\n\r\n/**\r\n * Is `container` the INNERMOST active trap?\r\n *\r\n * ⚠ DO NOT REPLACE THIS WITH `trapStack[trapStack.length - 1] === container`.\r\n *\r\n * Stack POSITION does not track nesting depth. React runs CHILD effects before\r\n * PARENT effects, so when an outer and an inner trap mount in the SAME commit\r\n * (Modal rendering a ConfirmDialog, Drawer with a nested trap) the INNER trap is\r\n * pushed FIRST and the OUTER one LAST — making the last entry the OUTERMOST trap,\r\n * the exact opposite of the intent.\r\n *\r\n * Push order only happens to match nesting when the traps mount at different\r\n * times, which is the common case and why the bug stayed hidden. The\r\n * simultaneous-mount path gave Tab duty to the trap BEHIND the dialog the user\r\n * was looking at (R-M.2 / R-F.2).\r\n *\r\n * Containment is order-independent: a trap is innermost when no other active\r\n * trap lives inside it. Correct for both mount orderings, and for unmount — once\r\n * the inner trap pops, the outer contains nothing and resumes duty.\r\n */\r\nfunction isInnermostTrap(container: HTMLElement): boolean {\r\n  return !trapStack.some(\r\n    (other) => other !== container && container.contains(other)\r\n  );\r\n}\r\n\r\n/**\r\n * True iff the element is rendered AND not inside an aria-hidden /\r\n * inert / hidden / display:none ancestor. querySelectorAll picks\r\n * those up indiscriminately, so re-filter at use time.\r\n */\r\nfunction isVisuallyFocusable(el: Element | null): el is HTMLElement {\r\n  if (!el) return false;\r\n  if (\"disabled\" in el && el.disabled) return false;\r\n  if (el.getAttribute && el.getAttribute(\"aria-disabled\") === \"true\") return false;\r\n  // Cheap visibility test — covers display:none and visibility:hidden.\r\n  // Note: elements with `display: contents` may report 0 rects but have\r\n  // focusable descendants; the descendants themselves still match if\r\n  // they have their own boxes, so this filter is a reasonable trade-off.\r\n  if (typeof el.getClientRects === \"function\" && el.getClientRects().length === 0) {\r\n    return false;\r\n  }\r\n  // Walk ancestors for hidden / aria-hidden / inert.\r\n  let node: Element | null = el;\r\n  while (node && node !== document.body) {\r\n    if (node.hasAttribute && (\r\n      node.hasAttribute(\"inert\") ||\r\n      node.hasAttribute(\"hidden\") ||\r\n      node.getAttribute(\"aria-hidden\") === \"true\"\r\n    )) {\r\n      return false;\r\n    }\r\n    node = node.parentElement;\r\n  }\r\n  return true;\r\n}\r\n\r\nexport default function useFocusTrap<T extends HTMLElement = HTMLElement>(\r\n  ref: RefObject<T | null>,\r\n  isActive: boolean\r\n): void {\r\n  useEffect(() => {\r\n    if (!isActive || !ref.current) return undefined;\r\n\r\n    const container = ref.current;\r\n    trapStack.push(container);\r\n\r\n    const getFocusable = (): HTMLElement[] =>\r\n      Array.from(container.querySelectorAll(FOCUSABLE_SELECTORS)).filter(isVisuallyFocusable);\r\n\r\n    const trigger = document.activeElement;\r\n\r\n    // Initial focus, deferred to next frame so React has finished\r\n    // painting any conditional content. Cancellation handle stored\r\n    // so unmount-within-same-frame cannot leak a stale .focus() call.\r\n    const rafId = requestAnimationFrame(() => {\r\n      /* Only the innermost trap claims initial focus — same predicate as `trap()`\r\n       * below, so keyboard duty and initial focus can never disagree.\r\n       *\r\n       * Initial focus was previously unguarded: every trap focused on\r\n       * activation regardless of nesting, so on simultaneous mount the outer\r\n       * trap's rAF fired last and overwrote the inner trap's focus. */\r\n      if (!isInnermostTrap(container)) return;\r\n\r\n      const explicit = container.querySelector(AUTOFOCUS_SELECTORS);\r\n      const target = (explicit && isVisuallyFocusable(explicit))\r\n        ? explicit\r\n        : getFocusable()[0];\r\n      if (target && typeof target.focus === \"function\") target.focus();\r\n    });\r\n\r\n    const trap = (e: KeyboardEvent): void => {\r\n      if (e.key !== \"Tab\") return;\r\n      // Only the innermost trap acts. Outer traps stay registered and defer.\r\n      // Containment, NOT stack position — see isInnermostTrap.\r\n      if (!isInnermostTrap(container)) return;\r\n\r\n      const els = getFocusable();\r\n      if (!els.length) {\r\n        // Pathological case (no focusable inside): swallow Tab so\r\n        // focus cannot escape into the page behind the trap.\r\n        e.preventDefault();\r\n        return;\r\n      }\r\n      const first = els[0];\r\n      const last = els[els.length - 1];\r\n      if (!first || !last) return;\r\n      const active = document.activeElement;\r\n\r\n      // Recovery: if focus is currently OUTSIDE the container, warp it\r\n      // back to the first focusable. Without this, an escaped focus\r\n      // (mount race, programmatic blur, SR virtual cursor) leaks Tab\r\n      // navigation to the page behind the trap.\r\n      if (!container.contains(active)) {\r\n        e.preventDefault();\r\n        first.focus();\r\n        return;\r\n      }\r\n\r\n      if (e.shiftKey && active === first) {\r\n        e.preventDefault();\r\n        last.focus();\r\n      } else if (!e.shiftKey && active === last) {\r\n        e.preventDefault();\r\n        first.focus();\r\n      }\r\n    };\r\n\r\n    document.addEventListener(\"keydown\", trap, true);\r\n\r\n    return () => {\r\n      cancelAnimationFrame(rafId);\r\n\r\n      // Pop by reference (NOT by index) — tolerates out-of-order\r\n      // unmount sequences during portal teardown or hot-replace.\r\n      const idx = trapStack.lastIndexOf(container);\r\n      if (idx >= 0) trapStack.splice(idx, 1);\r\n\r\n      document.removeEventListener(\"keydown\", trap, true);\r\n\r\n      // Restore focus only if the trigger is still mounted, focusable,\r\n      // and not currently disabled. Calling .focus() on a detached or\r\n      // disabled node silently leaves focus on <body> with no visible\r\n      // indicator — actively user-hostile.\r\n      if (\r\n        trigger &&\r\n        trigger !== document.body &&\r\n        \"focus\" in trigger &&\r\n        typeof trigger.focus === \"function\" &&\r\n        document.body.contains(trigger) &&\r\n        !(\"disabled\" in trigger && trigger.disabled)\r\n      ) {\r\n        trigger.focus();\r\n      }\r\n    };\r\n  }, [isActive, ref]);\r\n}\r\n"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAEA;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;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,IAAMC,mBAAmB,GAAG,CAC1B,SAAS,EACT,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,iCAAiC,EACjC,kDAAkD,EAClD,iBAAiB,EACjB,iBAAiB,CAClB,CAACC,IAAI,CAAC,IAAI,CAAC;AAEZ,IAAMC,mBAAmB,GAAG,+BAA+B;;AAE3D;AACA;AACA;AACA;AACA;AACA;AACA,IAAMC,SAAwB,GAAG,EAAE;;AAEnC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,eAAeA,CAACC,SAAsB,EAAW;EACxD,OAAO,CAACF,SAAS,CAACG,IAAI,CACpB,UAACC,KAAK;IAAA,OAAKA,KAAK,KAAKF,SAAS,IAAIA,SAAS,CAACG,QAAQ,CAACD,KAAK,CAAC;EAAA,CAC7D,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA,SAASE,mBAAmBA,CAACC,EAAkB,EAAqB;EAClE,IAAI,CAACA,EAAE,EAAE,OAAO,KAAK;EACrB,IAAI,UAAU,IAAIA,EAAE,IAAIA,EAAE,CAACC,QAAQ,EAAE,OAAO,KAAK;EACjD,IAAID,EAAE,CAACE,YAAY,IAAIF,EAAE,CAACE,YAAY,CAAC,eAAe,CAAC,KAAK,MAAM,EAAE,OAAO,KAAK;EAChF;EACA;EACA;EACA;EACA,IAAI,OAAOF,EAAE,CAACG,cAAc,KAAK,UAAU,IAAIH,EAAE,CAACG,cAAc,CAAC,CAAC,CAACC,M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","ignoreList":[]}

package/dist/v2/hooks/useFormAutoSave.d.ts

@@ -0,0 +1,42 @@
+/**
+ * useFormAutoSave — persist Formik (or any form) values to
+ * localStorage with debounced writes, and expose draft-restore
+ * affordances to the host. Pure orchestration; no UI.
+ *
+ * Usage:
+ *   import { v2 } from "@portnet/ui";
+ *   const { useFormAutoSave, Banner } = v2;
+ *
+ *   const { hasDraft, lastSavedAt, restoreDraft, clearDraft } =
+ *     useFormAutoSave({
+ *       storageKey: `addpe:autorisation:draft:${id || "new"}`,
+ *       values: formik.values,
+ *       setValues: formik.setValues,
+ *       enabled: !id, // CREATE only, not edit
+ *     });
+ *
+ * Safety:
+ *   - All localStorage access is try/catch-wrapped.
+ *   - Empty-state values are skipped so we don't produce noise entries.
+ *   - When a draft exists but hasn't been actioned (hasDraft=true),
+ *     the debounced write is PAUSED to prevent overwriting the draft
+ *     with empty initial values before the user decides to restore/ignore.
+ */
+type FormAutoSaveOptions<Values> = {
+    storageKey: string;
+    values: Values;
+    /** Required if you call restoreDraft(). */
+    setValues?: (values: Values) => void;
+    enabled?: boolean;
+    debounceMs?: number;
+    initialEmptyCheck?: (values: Values) => boolean;
+};
+type FormAutoSaveResult = {
+    hasDraft: boolean;
+    lastSavedAt: Date | null;
+    restoreDraft: () => boolean;
+    clearDraft: () => void;
+};
+export default function useFormAutoSave<Values>({ storageKey, values, setValues, enabled, debounceMs, initialEmptyCheck, }: FormAutoSaveOptions<Values>): FormAutoSaveResult;
+export {};
+//# sourceMappingURL=useFormAutoSave.d.ts.map

package/dist/v2/hooks/useFormAutoSave.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFormAutoSave.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/hooks/useFormAutoSave.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,KAAK,mBAAmB,CAAC,MAAM,IAAI;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;CACjD,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,OAAO,CAAC;IAC5B,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,MAAM,EAAE,EAC9C,UAAU,EACV,MAAM,EACN,SAAS,EACT,OAAc,EACd,UAAgB,EAChB,iBAAqC,GACtC,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,kBAAkB,CA+HlD"}