@portnet/ui 5.0.32 → 6.0.1

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

@@ -0,0 +1,22 @@
+/**
+ * useDelayedFlag — Portnet UI v2
+ *
+ * Returns `true` only when `active` has been continuously true for
+ * at least `delayMs` ms. Resets to `false` the moment `active` flips
+ * back to false. Charter R-Sk.1 — perception threshold.
+ *
+ *   const showSkeleton = useDelayedFlag(loading);
+ *   if (showSkeleton) return <Skeleton />;
+ *   if (loading)     return null;        // sub-threshold, render nothing
+ *   return <Data rows={rows} />;
+ *
+ * Use when:
+ *   - You want to delay showing a loading affordance (skeleton,
+ *     spinner overlay, "Loading…" text) until the user actually
+ *     perceives the wait.
+ *   - The flag has no tab/key semantics. For tab-aware loading
+ *     (preserves across tab swap to avoid flicker between two
+ *     consecutive skeletons), use `useTabLoading`.
+ */
+export default function useDelayedFlag(active: boolean, delayMs?: number): boolean;
+//# sourceMappingURL=useDelayedFlag.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useDelayedFlag.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/hooks/useDelayedFlag.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,MAAM,EAAE,OAAO,EACf,OAAO,GAAE,MAAgC,GACxC,OAAO,CAkBT"}

package/dist/v2/hooks/useDelayedFlag.js

@@ -0,0 +1,60 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = useDelayedFlag;
+var _react = require("react");
+var _useTabLoading = require("./useTabLoading");
+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; }
+/**
+ * useDelayedFlag — Portnet UI v2
+ *
+ * Returns `true` only when `active` has been continuously true for
+ * at least `delayMs` ms. Resets to `false` the moment `active` flips
+ * back to false. Charter R-Sk.1 — perception threshold.
+ *
+ *   const showSkeleton = useDelayedFlag(loading);
+ *   if (showSkeleton) return <Skeleton />;
+ *   if (loading)     return null;        // sub-threshold, render nothing
+ *   return <Data rows={rows} />;
+ *
+ * Use when:
+ *   - You want to delay showing a loading affordance (skeleton,
+ *     spinner overlay, "Loading…" text) until the user actually
+ *     perceives the wait.
+ *   - The flag has no tab/key semantics. For tab-aware loading
+ *     (preserves across tab swap to avoid flicker between two
+ *     consecutive skeletons), use `useTabLoading`.
+ */
+function useDelayedFlag(active) {
+  var delayMs = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : _useTabLoading.PERCEPTION_THRESHOLD_MS;
+  var _useState = (0, _react.useState)(false),
+    _useState2 = _slicedToArray(_useState, 2),
+    delayed = _useState2[0],
+    setDelayed = _useState2[1];
+  (0, _react.useEffect)(function () {
+    if (!active) {
+      // Inactive — drop any in-flight delayed flag immediately so
+      // the consumer can render the success path without waiting.
+      setDelayed(false);
+      return undefined;
+    }
+    // Schedule the flag flip. If `active` resolves false before the
+    // timer fires, cleanup clears the timer and the flag never goes
+    // true (the perception-threshold contract).
+    var t = setTimeout(function () {
+      return setDelayed(true);
+    }, delayMs);
+    return function () {
+      return clearTimeout(t);
+    };
+  }, [active, delayMs]);
+  return delayed;
+}
+//# sourceMappingURL=useDelayedFlag.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useDelayedFlag.js","names":["_react","require","_useTabLoading","_slicedToArray","arr","i","_arrayWithHoles","_iterableToArrayLimit","_unsupportedIterableToArray","_nonIterableRest","TypeError","o","minLen","_arrayLikeToArray","n","Object","prototype","toString","call","slice","constructor","name","Array","from","test","len","length","arr2","_i","Symbol","iterator","_s","_e","_x","_r","_arr","_n","_d","next","done","push","value","err","isArray","useDelayedFlag","active","delayMs","arguments","undefined","PERCEPTION_THRESHOLD_MS","_useState","useState","_useState2","delayed","setDelayed","useEffect","t","setTimeout","clearTimeout"],"sources":["../../../src/lib/v2/hooks/useDelayedFlag.ts"],"sourcesContent":["import { useState, useEffect } from \"react\";\r\nimport { PERCEPTION_THRESHOLD_MS } from \"./useTabLoading\";\r\n\r\n/**\r\n * useDelayedFlag — Portnet UI v2\r\n *\r\n * Returns `true` only when `active` has been continuously true for\r\n * at least `delayMs` ms. Resets to `false` the moment `active` flips\r\n * back to false. Charter R-Sk.1 — perception threshold.\r\n *\r\n *   const showSkeleton = useDelayedFlag(loading);\r\n *   if (showSkeleton) return <Skeleton />;\r\n *   if (loading)     return null;        // sub-threshold, render nothing\r\n *   return <Data rows={rows} />;\r\n *\r\n * Use when:\r\n *   - You want to delay showing a loading affordance (skeleton,\r\n *     spinner overlay, \"Loading…\" text) until the user actually\r\n *     perceives the wait.\r\n *   - The flag has no tab/key semantics. For tab-aware loading\r\n *     (preserves across tab swap to avoid flicker between two\r\n *     consecutive skeletons), use `useTabLoading`.\r\n */\r\nexport default function useDelayedFlag(\r\n  active: boolean,\r\n  delayMs: number = PERCEPTION_THRESHOLD_MS\r\n): boolean {\r\n  const [delayed, setDelayed] = useState(false);\r\n\r\n  useEffect(() => {\r\n    if (!active) {\r\n      // Inactive — drop any in-flight delayed flag immediately so\r\n      // the consumer can render the success path without waiting.\r\n      setDelayed(false);\r\n      return undefined;\r\n    }\r\n    // Schedule the flag flip. If `active` resolves false before the\r\n    // timer fires, cleanup clears the timer and the flag never goes\r\n    // true (the perception-threshold contract).\r\n    const t = setTimeout(() => setDelayed(true), delayMs);\r\n    return () => clearTimeout(t);\r\n  }, [active, delayMs]);\r\n\r\n  return delayed;\r\n}\r\n"],"mappings":"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","ignoreList":[]}

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

@@ -0,0 +1,23 @@
+/**
+ * useDensity — Portnet UI v2
+ *
+ * Reads / writes the user's density preference (charter R-DG.11).
+ * Applies it as `data-density` on <html> so all density-aware
+ * tokens cascade.
+ *
+ *   const [density, setDensity] = useDensity();
+ *   <button onClick={() => setDensity(density === "compact" ? "comfortable" : "compact")} />
+ *
+ * Synchronisation guarantees
+ *   - Multi-instance same-tab: every useDensity() consumer sees
+ *     the same value at all times. Implemented via a module-level
+ *     subscriber set fed by useSyncExternalStore.
+ *   - Cross-tab: a `storage` event listener at module load
+ *     propagates updates from sibling tabs sharing the origin.
+ *   - SSR-safe: server snapshot returns the DEFAULT; all DOM and
+ *     storage interactions are guarded.
+ */
+type DensityPref = "comfortable" | "compact";
+export default function useDensity(): [DensityPref, (value: DensityPref) => void];
+export {};
+//# sourceMappingURL=useDensity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useDensity.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/hooks/useDensity.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,KAAK,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;AAiG7C,MAAM,CAAC,OAAO,UAAU,UAAU,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC,CAGhF"}

package/dist/v2/hooks/useDensity.js

@@ -0,0 +1,124 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = useDensity;
+var _react = require("react");
+/**
+ * useDensity — Portnet UI v2
+ *
+ * Reads / writes the user's density preference (charter R-DG.11).
+ * Applies it as `data-density` on <html> so all density-aware
+ * tokens cascade.
+ *
+ *   const [density, setDensity] = useDensity();
+ *   <button onClick={() => setDensity(density === "compact" ? "comfortable" : "compact")} />
+ *
+ * Synchronisation guarantees
+ *   - Multi-instance same-tab: every useDensity() consumer sees
+ *     the same value at all times. Implemented via a module-level
+ *     subscriber set fed by useSyncExternalStore.
+ *   - Cross-tab: a `storage` event listener at module load
+ *     propagates updates from sibling tabs sharing the origin.
+ *   - SSR-safe: server snapshot returns the DEFAULT; all DOM and
+ *     storage interactions are guarded.
+ */
+
+var STORAGE_KEY = "portnet-ui-density";
+var DEFAULT = "comfortable";
+var VALID = Object.freeze(["comfortable", "compact"]);
+var VALID_SET = new Set(VALID);
+function isDensityPref(v) {
+  return typeof v === "string" && VALID_SET.has(v);
+}
+
+/* ── Module-level store ───────────────────────────────── */
+
+/** Source of truth. Lazy-read from storage at module load on the client. */
+var memoryValue = readInitialValue();
+
+/** Active hook subscribers — notified on every value change. */
+var subscribers = new Set();
+function readInitialValue() {
+  if (typeof window === "undefined") return DEFAULT;
+  try {
+    var raw = window.localStorage.getItem(STORAGE_KEY);
+    return isDensityPref(raw) ? raw : DEFAULT;
+  } catch (_unused) {
+    return DEFAULT;
+  }
+}
+function applyToDom(value) {
+  if (typeof document === "undefined") return;
+  document.documentElement.dataset["density"] = value;
+}
+
+/** Apply the initial value to the DOM at module load (client-side). */
+applyToDom(memoryValue);
+
+/* Cross-tab sync. The `storage` event fires in OTHER tabs only —
+ * the writing tab is informed via the in-memory subscribers path. */
+if (typeof window !== "undefined") {
+  window.addEventListener("storage", function (e) {
+    if (e.key !== STORAGE_KEY) return;
+    if (!isDensityPref(e.newValue)) return;
+    if (e.newValue === memoryValue) return;
+    memoryValue = e.newValue;
+    applyToDom(memoryValue);
+    // No storage write here — the originating tab already wrote.
+    notify();
+  });
+}
+function notify() {
+  // Iterate a snapshot — a subscriber that unmounts during notify
+  // would otherwise mutate the Set under iteration.
+  for (var _i = 0, _Array$from = Array.from(subscribers); _i < _Array$from.length; _i++) {
+    var cb = _Array$from[_i];
+    cb();
+  }
+}
+function subscribe(callback) {
+  subscribers.add(callback);
+  return function () {
+    return subscribers["delete"](callback);
+  };
+}
+function getSnapshot() {
+  return memoryValue;
+}
+function getServerSnapshot() {
+  return DEFAULT;
+}
+
+/* ── Setter (module-level so identity is stable across renders) ── */
+
+/**
+ * Set the density preference. Ignores invalid values silently
+ * (consumer-supplied data sanitation is not this hook's job) and
+ * short-circuits when the value is unchanged.
+ */
+function setDensityValue(value) {
+  if (!VALID_SET.has(value)) return;
+  if (value === memoryValue) return;
+  memoryValue = value;
+  applyToDom(value);
+  if (typeof window !== "undefined") {
+    try {
+      window.localStorage.setItem(STORAGE_KEY, value);
+    } catch (err) {
+      // Quota, private mode, or sandboxed iframe — preference is
+      // applied for this session but won't persist. Surface in dev.
+      if (typeof console !== "undefined" && console.warn) {
+        // eslint-disable-next-line no-console
+        console.warn("[@portnet/ui v2] useDensity: localStorage write failed", err);
+      }
+    }
+  }
+  notify();
+}
+function useDensity() {
+  var density = (0, _react.useSyncExternalStore)(subscribe, getSnapshot, getServerSnapshot);
+  return [density, setDensityValue];
+}
+//# sourceMappingURL=useDensity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useDensity.js","names":["_react","require","STORAGE_KEY","DEFAULT","VALID","Object","freeze","VALID_SET","Set","isDensityPref","v","has","memoryValue","readInitialValue","subscribers","window","raw","localStorage","getItem","_unused","applyToDom","value","document","documentElement","dataset","addEventListener","e","key","newValue","notify","_i","_Array$from","Array","from","length","cb","subscribe","callback","add","getSnapshot","getServerSnapshot","setDensityValue","setItem","err","console","warn","useDensity","density","useSyncExternalStore"],"sources":["../../../src/lib/v2/hooks/useDensity.ts"],"sourcesContent":["import { useSyncExternalStore } from \"react\";\r\n\r\n/**\r\n * useDensity — Portnet UI v2\r\n *\r\n * Reads / writes the user's density preference (charter R-DG.11).\r\n * Applies it as `data-density` on <html> so all density-aware\r\n * tokens cascade.\r\n *\r\n *   const [density, setDensity] = useDensity();\r\n *   <button onClick={() => setDensity(density === \"compact\" ? \"comfortable\" : \"compact\")} />\r\n *\r\n * Synchronisation guarantees\r\n *   - Multi-instance same-tab: every useDensity() consumer sees\r\n *     the same value at all times. Implemented via a module-level\r\n *     subscriber set fed by useSyncExternalStore.\r\n *   - Cross-tab: a `storage` event listener at module load\r\n *     propagates updates from sibling tabs sharing the origin.\r\n *   - SSR-safe: server snapshot returns the DEFAULT; all DOM and\r\n *     storage interactions are guarded.\r\n */\r\n\r\ntype DensityPref = \"comfortable\" | \"compact\";\r\n\r\nconst STORAGE_KEY = \"portnet-ui-density\";\r\nconst DEFAULT: DensityPref = \"comfortable\";\r\nconst VALID = Object.freeze([\"comfortable\", \"compact\"]);\r\nconst VALID_SET = new Set<string>(VALID);\r\n\r\nfunction isDensityPref(v: unknown): v is DensityPref {\r\n  return typeof v === \"string\" && VALID_SET.has(v);\r\n}\r\n\r\n/* ── Module-level store ───────────────────────────────── */\r\n\r\n/** Source of truth. Lazy-read from storage at module load on the client. */\r\nlet memoryValue: DensityPref = readInitialValue();\r\n\r\n/** Active hook subscribers — notified on every value change. */\r\nconst subscribers = new Set<() => void>();\r\n\r\nfunction readInitialValue(): DensityPref {\r\n  if (typeof window === \"undefined\") return DEFAULT;\r\n  try {\r\n    const raw = window.localStorage.getItem(STORAGE_KEY);\r\n    return isDensityPref(raw) ? raw : DEFAULT;\r\n  } catch {\r\n    return DEFAULT;\r\n  }\r\n}\r\n\r\nfunction applyToDom(value: DensityPref): void {\r\n  if (typeof document === \"undefined\") return;\r\n  document.documentElement.dataset[\"density\"] = value;\r\n}\r\n\r\n/** Apply the initial value to the DOM at module load (client-side). */\r\napplyToDom(memoryValue);\r\n\r\n/* Cross-tab sync. The `storage` event fires in OTHER tabs only —\r\n * the writing tab is informed via the in-memory subscribers path. */\r\nif (typeof window !== \"undefined\") {\r\n  window.addEventListener(\"storage\", (e) => {\r\n    if (e.key !== STORAGE_KEY) return;\r\n    if (!isDensityPref(e.newValue)) return;\r\n    if (e.newValue === memoryValue) return;\r\n    memoryValue = e.newValue;\r\n    applyToDom(memoryValue);\r\n    // No storage write here — the originating tab already wrote.\r\n    notify();\r\n  });\r\n}\r\n\r\nfunction notify(): void {\r\n  // Iterate a snapshot — a subscriber that unmounts during notify\r\n  // would otherwise mutate the Set under iteration.\r\n  for (const cb of Array.from(subscribers)) cb();\r\n}\r\n\r\nfunction subscribe(callback: () => void): () => void {\r\n  subscribers.add(callback);\r\n  return () => subscribers.delete(callback);\r\n}\r\n\r\nfunction getSnapshot(): DensityPref {\r\n  return memoryValue;\r\n}\r\n\r\nfunction getServerSnapshot(): DensityPref {\r\n  return DEFAULT;\r\n}\r\n\r\n/* ── Setter (module-level so identity is stable across renders) ── */\r\n\r\n/**\r\n * Set the density preference. Ignores invalid values silently\r\n * (consumer-supplied data sanitation is not this hook's job) and\r\n * short-circuits when the value is unchanged.\r\n */\r\nfunction setDensityValue(value: DensityPref): void {\r\n  if (!VALID_SET.has(value)) return;\r\n  if (value === memoryValue) return;\r\n  memoryValue = value;\r\n  applyToDom(value);\r\n  if (typeof window !== \"undefined\") {\r\n    try {\r\n      window.localStorage.setItem(STORAGE_KEY, value);\r\n    } catch (err) {\r\n      // Quota, private mode, or sandboxed iframe — preference is\r\n      // applied for this session but won't persist. Surface in dev.\r\n      if (typeof console !== \"undefined\" && console.warn) {\r\n        // eslint-disable-next-line no-console\r\n        console.warn(\"[@portnet/ui v2] useDensity: localStorage write failed\", err);\r\n      }\r\n    }\r\n  }\r\n  notify();\r\n}\r\n\r\nexport default function useDensity(): [DensityPref, (value: DensityPref) => void] {\r\n  const density = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\r\n  return [density, setDensityValue];\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;;AAIA,IAAMC,WAAW,GAAG,oBAAoB;AACxC,IAAMC,OAAoB,GAAG,aAAa;AAC1C,IAAMC,KAAK,GAAGC,MAAM,CAACC,MAAM,CAAC,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;AACvD,IAAMC,SAAS,GAAG,IAAIC,GAAG,CAASJ,KAAK,CAAC;AAExC,SAASK,aAAaA,CAACC,CAAU,EAAoB;EACnD,OAAO,OAAOA,CAAC,KAAK,QAAQ,IAAIH,SAAS,CAACI,GAAG,CAACD,CAAC,CAAC;AAClD;;AAEA;;AAEA;AACA,IAAIE,WAAwB,GAAGC,gBAAgB,CAAC,CAAC;;AAEjD;AACA,IAAMC,WAAW,GAAG,IAAIN,GAAG,CAAa,CAAC;AAEzC,SAASK,gBAAgBA,CAAA,EAAgB;EACvC,IAAI,OAAOE,MAAM,KAAK,WAAW,EAAE,OAAOZ,OAAO;EACjD,IAAI;IACF,IAAMa,GAAG,GAAGD,MAAM,CAACE,YAAY,CAACC,OAAO,CAAChB,WAAW,CAAC;IACpD,OAAOO,aAAa,CAACO,GAAG,CAAC,GAAGA,GAAG,GAAGb,OAAO;EAC3C,CAAC,CAAC,OAAAgB,OAAA,EAAM;IACN,OAAOhB,OAAO;EAChB;AACF;AAEA,SAASiB,UAAUA,CAACC,KAAkB,EAAQ;EAC5C,IAAI,OAAOC,QAAQ,KAAK,WAAW,EAAE;EACrCA,QAAQ,CAACC,eAAe,CAACC,OAAO,CAAC,SAAS,CAAC,GAAGH,KAAK;AACrD;;AAEA;AACAD,UAAU,CAACR,WAAW,CAAC;;AAEvB;AACA;AACA,IAAI,OAAOG,MAAM,KAAK,WAAW,EAAE;EACjCA,MAAM,CAACU,gBAAgB,CAAC,SAAS,EAAE,UAACC,CAAC,EAAK;IACxC,IAAIA,CAAC,CAACC,GAAG,KAAKzB,WAAW,EAAE;IAC3B,IAAI,CAACO,aAAa,CAACiB,CAAC,CAACE,QAAQ,CAAC,EAAE;IAChC,IAAIF,CAAC,CAACE,QAAQ,KAAKhB,WAAW,EAAE;IAChCA,WAAW,GAAGc,CAAC,CAACE,QAAQ;IACxBR,UAAU,CAACR,WAAW,CAAC;IACvB;IACAiB,MAAM,CAAC,CAAC;EACV,CAAC,CAAC;AACJ;AAEA,SAASA,MAAMA,CAAA,EAAS;EACtB;EACA;EACA,SAAAC,EAAA,MAAAC,WAAA,GAAiBC,KAAK,CAACC,IAAI,CAACnB,WAAW,CAAC,EAAAgB,EAAA,GAAAC,WAAA,CAAAG,MAAA,EAAAJ,EAAA;IAAnC,IAAMK,EAAE,GAAAJ,WAAA,CAAAD,EAAA;IAA6BK,EAAE,CAAC,CAAC;EAAC;AACjD;AAEA,SAASC,SAASA,CAACC,QAAoB,EAAc;EACnDvB,WAAW,CAACwB,GAAG,CAACD,QAAQ,CAAC;EACzB,OAAO;IAAA,OAAMvB,WAAW,UAAO,CAACuB,QAAQ,CAAC;EAAA;AAC3C;AAEA,SAASE,WAAWA,CAAA,EAAgB;EAClC,OAAO3B,WAAW;AACpB;AAEA,SAAS4B,iBAAiBA,CAAA,EAAgB;EACxC,OAAOrC,OAAO;AAChB;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,SAASsC,eAAeA,CAACpB,KAAkB,EAAQ;EACjD,IAAI,CAACd,SAAS,CAACI,GAAG,CAACU,KAAK,CAAC,EAAE;EAC3B,IAAIA,KAAK,KAAKT,WAAW,EAAE;EAC3BA,WAAW,GAAGS,KAAK;EACnBD,UAAU,CAACC,KAAK,CAAC;EACjB,IAAI,OAAON,MAAM,KAAK,WAAW,EAAE;IACjC,IAAI;MACFA,MAAM,CAACE,YAAY,CAACyB,OAAO,CAACxC,WAAW,EAAEmB,KAAK,CAAC;IACjD,CAAC,CAAC,OAAOsB,GAAG,EAAE;MACZ;MACA;MACA,IAAI,OAAOC,OAAO,KAAK,WAAW,IAAIA,OAAO,CAACC,IAAI,EAAE;QAClD;QACAD,OAAO,CAACC,IAAI,CAAC,wDAAwD,EAAEF,GAAG,CAAC;MAC7E;IACF;EACF;EACAd,MAAM,CAAC,CAAC;AACV;AAEe,SAASiB,UAAUA,CAAA,EAAgD;EAChF,IAAMC,OAAO,GAAG,IAAAC,2BAAoB,EAACZ,SAAS,EAAEG,WAAW,EAAEC,iBAAiB,CAAC;EAC/E,OAAO,CAACO,OAAO,EAAEN,eAAe,CAAC;AACnC","ignoreList":[]}

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

@@ -0,0 +1,121 @@
+/**
+ * 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. */
+export type FocusFieldOptions = {
+    /**
+     * Scroll the resolved control into view before focusing.
+     *
+     * `behavior: "auto"` always — never "smooth". R-Tg.2 caps animation at
+     * 0.01 ms under prefers-reduced-motion, and a smooth scroll triggered by
+     * a failed submit is exactly the motion that rule exists to suppress.
+     *
+     * @default true
+     */
+    scroll?: boolean | undefined;
+};
+export type UseFocusFirstErrorOptions = {
+    /**
+     * Field name -> error. Formik's `errors` satisfies this directly.
+     *
+     * Only truthiness is read, so any error shape works (string, node,
+     * nested object).
+     */
+    errors?: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * Field names in RENDERED order — top-to-bottom as the user sees them.
+     *
+     * SUPPLY THIS. Without it the order falls back to `Object.keys(errors)`,
+     * which is the order the validator happened to write its keys in and has
+     * no relationship to the layout; "first field in error" then means
+     * "whichever field Yup reached first", which can be the last one on
+     * screen.
+     */
+    order?: readonly string[] | undefined;
+    /**
+     * Submit attempt counter. Formik's `submitCount`.
+     *
+     * This is the TRIGGER: focus moves when it increases, never on an
+     * ordinary re-render. Without it a persisting error would re-steal focus
+     * every time the component re-rendered, which is worse than not moving
+     * focus at all.
+     */
+    submitCount?: number | undefined;
+    /** @default true */
+    enabled?: boolean | undefined;
+    /** @default true */
+    scroll?: boolean | undefined;
+};
+/**
+ * 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.
+ */
+export declare function focusFieldByName(name: string, options?: FocusFieldOptions): boolean;
+/**
+ * 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.
+ */
+export default function useFocusFirstError({ errors, order, submitCount, enabled, scroll, }: UseFocusFirstErrorOptions): void;
+//# sourceMappingURL=useFocusFirstError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useFocusFirstError.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/hooks/useFocusFirstError.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,yCAAyC;AACzC,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACvD;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACtC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,oBAAoB;IACpB,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,oBAAoB;IACpB,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B,CAAC;AA6CF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CA4CT;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,EACzC,MAAM,EACN,KAAK,EACL,WAAe,EACf,OAAc,EACd,MAAa,GACd,EAAE,yBAAyB,GAAG,IAAI,CAyClC"}

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