@portnet/ui 5.0.32 → 6.0.1

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

package/dist/v2/hooks/useFormAutoSave.js

@@ -0,0 +1,186 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = useFormAutoSave;
+var _react = require("react");
+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 _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+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; }
+function _iterableToArrayLimit(arr, i) { var _i = null == arr ? null : "undefined" != typeof Symbol && arr[Symbol.iterator] || arr["@@iterator"]; if (null != _i) { var _s, _e, _x, _r, _arr = [], _n = !0, _d = !1; try { if (_x = (_i = _i.call(arr)).next, 0 === i) { if (Object(_i) !== _i) return; _n = !1; } else for (; !(_n = (_s = _x.call(_i)).done) && (_arr.push(_s.value), _arr.length !== i); _n = !0) { ; } } catch (err) { _d = !0, _e = err; } finally { try { if (!_n && null != _i["return"] && (_r = _i["return"](), Object(_r) !== _r)) return; } finally { if (_d) throw _e; } } return _arr; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+/**
+ * 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.
+ */
+
+function useFormAutoSave(_ref) {
+  var storageKey = _ref.storageKey,
+    values = _ref.values,
+    setValues = _ref.setValues,
+    _ref$enabled = _ref.enabled,
+    enabled = _ref$enabled === void 0 ? true : _ref$enabled,
+    _ref$debounceMs = _ref.debounceMs,
+    debounceMs = _ref$debounceMs === void 0 ? 800 : _ref$debounceMs,
+    _ref$initialEmptyChec = _ref.initialEmptyCheck,
+    initialEmptyCheck = _ref$initialEmptyChec === void 0 ? defaultEmptyCheck : _ref$initialEmptyChec;
+  var _useState = (0, _react.useState)(false),
+    _useState2 = _slicedToArray(_useState, 2),
+    hasDraft = _useState2[0],
+    setHasDraft = _useState2[1];
+  var _useState3 = (0, _react.useState)(null),
+    _useState4 = _slicedToArray(_useState3, 2),
+    lastSavedAt = _useState4[0],
+    setLastSavedAt = _useState4[1];
+  var debounceTimerRef = (0, _react.useRef)(null);
+  var mountedRef = (0, _react.useRef)(false);
+
+  /* ── Mount-time draft detection ────────────────── */
+  (0, _react.useEffect)(function () {
+    if (!enabled) return;
+    if (mountedRef.current) return;
+    mountedRef.current = true;
+    try {
+      var raw = localStorage.getItem(storageKey);
+      if (!raw) return;
+      var parsed = JSON.parse(raw);
+      if (parsed && _typeof(parsed) === "object" && "values" in parsed && parsed.values && _typeof(parsed.values) === "object") {
+        setHasDraft(true);
+        if ("savedAt" in parsed && typeof parsed.savedAt === "string") {
+          var d = new Date(parsed.savedAt);
+          if (!Number.isNaN(d.getTime())) setLastSavedAt(d);
+        }
+      } else {
+        localStorage.removeItem(storageKey);
+      }
+    } catch (_unused) {
+      try {
+        localStorage.removeItem(storageKey);
+      } catch (_unused2) {
+        /* ignore */
+      }
+    }
+  }, [enabled, storageKey]);
+
+  /* ── Debounced write on values change ──────────────────
+   *
+   * CRITICAL: do NOT write while hasDraft=true (draft not yet actioned).
+   *
+   * If we write immediately on mount, the empty initial values would
+   * overwrite the user's saved draft after `debounceMs` milliseconds.
+   * The user would see the "restore" banner, wait/hesitate, then click
+   * "Restaurer" only to find the form empty because restoreDraft() read
+   * the overwritten (empty) localStorage entry.
+   *
+   * We pause writes until hasDraft becomes false, which happens when:
+   *   - restoreDraft() is called (user chose to restore)
+   *   - clearDraft()   is called (user chose to ignore)
+   *   - No draft existed on mount (hasDraft was never set to true)
+   */
+  (0, _react.useEffect)(function () {
+    if (!enabled) return undefined;
+    if (hasDraft) return undefined; // ← PAUSE: preserve existing draft
+    if (initialEmptyCheck(values)) return undefined;
+    if (debounceTimerRef.current) {
+      clearTimeout(debounceTimerRef.current);
+    }
+    debounceTimerRef.current = setTimeout(function () {
+      try {
+        var now = new Date();
+        localStorage.setItem(storageKey, JSON.stringify({
+          values: values,
+          savedAt: now.toISOString()
+        }));
+        setLastSavedAt(now);
+      } catch (_unused3) {
+        // Quota full / private mode — no-op.
+      }
+    }, debounceMs);
+    return function () {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+    };
+  }, [values, enabled, hasDraft, storageKey, debounceMs, initialEmptyCheck]);
+
+  /* ── Restore draft ─────────────────────── */
+  var restoreDraft = (0, _react.useCallback)(function () {
+    if (!setValues) {
+      if (process.env["NODE_ENV"] !== "production") {
+        // eslint-disable-next-line no-console
+        console.warn("[v2.useFormAutoSave] restoreDraft called but setValues was not provided.");
+      }
+      return false;
+    }
+    try {
+      var raw = localStorage.getItem(storageKey);
+      if (!raw) return false;
+      var parsed = JSON.parse(raw);
+      if (!parsed || _typeof(parsed) !== "object" || !("values" in parsed) || !parsed.values) {
+        return false;
+      }
+      // Persisted draft payload is the form's Values, round-tripped
+      // through JSON; assert back to Values for the setter.
+      setValues(parsed.values);
+      setHasDraft(false); // ← resumes auto-save with restored values
+      return true;
+    } catch (_unused4) {
+      return false;
+    }
+  }, [storageKey, setValues]);
+
+  /* ── Clear draft ─────────────────────── */
+  var clearDraft = (0, _react.useCallback)(function () {
+    try {
+      localStorage.removeItem(storageKey);
+    } catch (_unused5) {
+      /* ignore */
+    }
+    setHasDraft(false); // ← resumes auto-save for new input
+    setLastSavedAt(null);
+  }, [storageKey]);
+  return {
+    hasDraft: hasDraft,
+    lastSavedAt: lastSavedAt,
+    restoreDraft: restoreDraft,
+    clearDraft: clearDraft
+  };
+}
+
+/* ── Helpers ───────────────────────────── */
+
+function isEmptyValue(v) {
+  if (v === null || v === undefined) return true;
+  if (typeof v === "string") return v.trim().length === 0;
+  if (Array.isArray(v)) return v.length === 0;
+  if (_typeof(v) === "object") return Object.keys(v).length === 0;
+  return false;
+}
+function defaultEmptyCheck(values) {
+  if (!values || _typeof(values) !== "object") return true;
+  return Object.values(values).every(isEmptyValue);
+}
+//# sourceMappingURL=useFormAutoSave.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFormAutoSave.js","names":["_react","require","_typeof","obj","Symbol","iterator","constructor","prototype","_slicedToArray","arr","i","_arrayWithHoles","_iterableToArrayLimit","_unsupportedIterableToArray","_nonIterableRest","TypeError","o","minLen","_arrayLikeToArray","n","Object","toString","call","slice","name","Array","from","test","len","length","arr2","_i","_s","_e","_x","_r","_arr","_n","_d","next","done","push","value","err","isArray","useFormAutoSave","_ref","storageKey","values","setValues","_ref$enabled","enabled","_ref$debounceMs","debounceMs","_ref$initialEmptyChec","initialEmptyCheck","defaultEmptyCheck","_useState","useState","_useState2","hasDraft","setHasDraft","_useState3","_useState4","lastSavedAt","setLastSavedAt","debounceTimerRef","useRef","mountedRef","useEffect","current","raw","localStorage","getItem","parsed","JSON","parse","savedAt","d","Date","Number","isNaN","getTime","removeItem","_unused","_unused2","undefined","clearTimeout","setTimeout","now","setItem","stringify","toISOString","_unused3","restoreDraft","useCallback","process","env","console","warn","_unused4","clearDraft","_unused5","isEmptyValue","v","trim","keys","every"],"sources":["../../../src/lib/v2/hooks/useFormAutoSave.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\r\n\r\n/**\r\n * useFormAutoSave — persist Formik (or any form) values to\r\n * localStorage with debounced writes, and expose draft-restore\r\n * affordances to the host. Pure orchestration; no UI.\r\n *\r\n * Usage:\r\n *   import { v2 } from \"@portnet/ui\";\r\n *   const { useFormAutoSave, Banner } = v2;\r\n *\r\n *   const { hasDraft, lastSavedAt, restoreDraft, clearDraft } =\r\n *     useFormAutoSave({\r\n *       storageKey: `addpe:autorisation:draft:${id || \"new\"}`,\r\n *       values: formik.values,\r\n *       setValues: formik.setValues,\r\n *       enabled: !id, // CREATE only, not edit\r\n *     });\r\n *\r\n * Safety:\r\n *   - All localStorage access is try/catch-wrapped.\r\n *   - Empty-state values are skipped so we don't produce noise entries.\r\n *   - When a draft exists but hasn't been actioned (hasDraft=true),\r\n *     the debounced write is PAUSED to prevent overwriting the draft\r\n *     with empty initial values before the user decides to restore/ignore.\r\n */\r\n\r\ntype FormAutoSaveOptions<Values> = {\r\n  storageKey: string;\r\n  values: Values;\r\n  /** Required if you call restoreDraft(). */\r\n  setValues?: (values: Values) => void;\r\n  enabled?: boolean;\r\n  debounceMs?: number;\r\n  initialEmptyCheck?: (values: Values) => boolean;\r\n};\r\n\r\ntype FormAutoSaveResult = {\r\n  hasDraft: boolean;\r\n  lastSavedAt: Date | null;\r\n  restoreDraft: () => boolean;\r\n  clearDraft: () => void;\r\n};\r\n\r\nexport default function useFormAutoSave<Values>({\r\n  storageKey,\r\n  values,\r\n  setValues,\r\n  enabled = true,\r\n  debounceMs = 800,\r\n  initialEmptyCheck = defaultEmptyCheck,\r\n}: FormAutoSaveOptions<Values>): FormAutoSaveResult {\r\n  const [hasDraft, setHasDraft] = useState(false);\r\n  const [lastSavedAt, setLastSavedAt] = useState<Date | null>(null);\r\n  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\r\n  const mountedRef = useRef(false);\r\n\r\n  /* ── Mount-time draft detection ────────────────── */\r\n  useEffect(() => {\r\n    if (!enabled) return;\r\n    if (mountedRef.current) return;\r\n    mountedRef.current = true;\r\n\r\n    try {\r\n      const raw = localStorage.getItem(storageKey);\r\n      if (!raw) return;\r\n      const parsed: unknown = JSON.parse(raw);\r\n      if (\r\n        parsed &&\r\n        typeof parsed === \"object\" &&\r\n        \"values\" in parsed &&\r\n        parsed.values &&\r\n        typeof parsed.values === \"object\"\r\n      ) {\r\n        setHasDraft(true);\r\n        if (\"savedAt\" in parsed && typeof parsed.savedAt === \"string\") {\r\n          const d = new Date(parsed.savedAt);\r\n          if (!Number.isNaN(d.getTime())) setLastSavedAt(d);\r\n        }\r\n      } else {\r\n        localStorage.removeItem(storageKey);\r\n      }\r\n    } catch {\r\n      try {\r\n        localStorage.removeItem(storageKey);\r\n      } catch {\r\n        /* ignore */\r\n      }\r\n    }\r\n  }, [enabled, storageKey]);\r\n\r\n  /* ── Debounced write on values change ──────────────────\r\n   *\r\n   * CRITICAL: do NOT write while hasDraft=true (draft not yet actioned).\r\n   *\r\n   * If we write immediately on mount, the empty initial values would\r\n   * overwrite the user's saved draft after `debounceMs` milliseconds.\r\n   * The user would see the \"restore\" banner, wait/hesitate, then click\r\n   * \"Restaurer\" only to find the form empty because restoreDraft() read\r\n   * the overwritten (empty) localStorage entry.\r\n   *\r\n   * We pause writes until hasDraft becomes false, which happens when:\r\n   *   - restoreDraft() is called (user chose to restore)\r\n   *   - clearDraft()   is called (user chose to ignore)\r\n   *   - No draft existed on mount (hasDraft was never set to true)\r\n   */\r\n  useEffect(() => {\r\n    if (!enabled) return undefined;\r\n    if (hasDraft) return undefined;           // ← PAUSE: preserve existing draft\r\n    if (initialEmptyCheck(values)) return undefined;\r\n\r\n    if (debounceTimerRef.current) {\r\n      clearTimeout(debounceTimerRef.current);\r\n    }\r\n\r\n    debounceTimerRef.current = setTimeout(() => {\r\n      try {\r\n        const now = new Date();\r\n        localStorage.setItem(\r\n          storageKey,\r\n          JSON.stringify({ values, savedAt: now.toISOString() })\r\n        );\r\n        setLastSavedAt(now);\r\n      } catch {\r\n        // Quota full / private mode — no-op.\r\n      }\r\n    }, debounceMs);\r\n\r\n    return () => {\r\n      if (debounceTimerRef.current) {\r\n        clearTimeout(debounceTimerRef.current);\r\n      }\r\n    };\r\n  }, [values, enabled, hasDraft, storageKey, debounceMs, initialEmptyCheck]);\r\n\r\n  /* ── Restore draft ─────────────────────── */\r\n  const restoreDraft = useCallback((): boolean => {\r\n    if (!setValues) {\r\n      if (process.env[\"NODE_ENV\"] !== \"production\") {\r\n        // eslint-disable-next-line no-console\r\n        console.warn(\"[v2.useFormAutoSave] restoreDraft called but setValues was not provided.\");\r\n      }\r\n      return false;\r\n    }\r\n    try {\r\n      const raw = localStorage.getItem(storageKey);\r\n      if (!raw) return false;\r\n      const parsed: unknown = JSON.parse(raw);\r\n      if (\r\n        !parsed ||\r\n        typeof parsed !== \"object\" ||\r\n        !(\"values\" in parsed) ||\r\n        !parsed.values\r\n      ) {\r\n        return false;\r\n      }\r\n      // Persisted draft payload is the form's Values, round-tripped\r\n      // through JSON; assert back to Values for the setter.\r\n      setValues(parsed.values as Values);\r\n      setHasDraft(false);  // ← resumes auto-save with restored values\r\n      return true;\r\n    } catch {\r\n      return false;\r\n    }\r\n  }, [storageKey, setValues]);\r\n\r\n  /* ── Clear draft ─────────────────────── */\r\n  const clearDraft = useCallback((): void => {\r\n    try {\r\n      localStorage.removeItem(storageKey);\r\n    } catch {\r\n      /* ignore */\r\n    }\r\n    setHasDraft(false);    // ← resumes auto-save for new input\r\n    setLastSavedAt(null);\r\n  }, [storageKey]);\r\n\r\n  return { hasDraft, lastSavedAt, restoreDraft, clearDraft };\r\n}\r\n\r\n/* ── Helpers ───────────────────────────── */\r\n\r\nfunction isEmptyValue(v: unknown): boolean {\r\n  if (v === null || v === undefined) return true;\r\n  if (typeof v === \"string\") return v.trim().length === 0;\r\n  if (Array.isArray(v)) return v.length === 0;\r\n  if (typeof v === \"object\") return Object.keys(v).length === 0;\r\n  return false;\r\n}\r\n\r\nfunction defaultEmptyCheck(values: unknown): boolean {\r\n  if (!values || typeof values !== \"object\") return true;\r\n  return Object.values(values).every(isEmptyValue);\r\n}\r\n"],"mappings":"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","ignoreList":[]}

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

@@ -0,0 +1,52 @@
+/**
+ * useFormCompletionProgress — derive required/overall completion
+ * percentages from current form values and a declared field list.
+ * Pure useMemo computation, no side effects.
+ *
+ * Usage:
+ *   import { v2 } from "@portnet/ui";
+ *   const { useFormCompletionProgress, ProgressBar } = v2;
+ *
+ *   const REQUIRED = ["typeAutorisation", "importer.id", "dateFinValidite"];
+ *   const OPTIONAL = ["referenceLicence", "region"];
+ *
+ *   const {
+ *     requiredPct,
+ *     overallPct,
+ *     isCompleteRequired,
+ *     missingRequired,
+ *     filledRequired,
+ *     totalRequired,
+ *   } = useFormCompletionProgress({
+ *     values: formik.values,
+ *     requiredFields: REQUIRED,
+ *     optionalFields: OPTIONAL,
+ *   });
+ *
+ *   <ProgressBar value={requiredPct} />
+ *   <span>{filledRequired}/{totalRequired} requis</span>
+ *
+ * Field paths support dot notation for nested values:
+ *   "importer.id"   → values.importer.id
+ *   "articles"      → values.articles (array length checked)
+ */
+type FormCompletionProgressOptions<Values> = {
+    values: Values;
+    /** Field keys / dot-paths that are required. */
+    requiredFields: string[];
+    /** Field keys / dot-paths that are optional. */
+    optionalFields?: string[];
+};
+type FormCompletionProgress = {
+    requiredPct: number;
+    overallPct: number;
+    filledRequired: number;
+    totalRequired: number;
+    filledOptional: number;
+    totalOptional: number;
+    isCompleteRequired: boolean;
+    missingRequired: string[];
+};
+export default function useFormCompletionProgress<Values>({ values, requiredFields, optionalFields, }: FormCompletionProgressOptions<Values>): FormCompletionProgress;
+export {};
+//# sourceMappingURL=useFormCompletionProgress.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFormCompletionProgress.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/hooks/useFormCompletionProgress.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,KAAK,6BAA6B,CAAC,MAAM,IAAI;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,KAAK,sBAAsB,GAAG;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAAC,MAAM,EAAE,EACxD,MAAM,EACN,cAAc,EACd,cAAmB,GACpB,EAAE,6BAA6B,CAAC,MAAM,CAAC,GAAG,sBAAsB,CAwChE"}