@alfadocs/ui-kit-debug 0.72.2 → 0.75.0

package/dist/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../src/hooks/use-debounced-value.ts","../../src/hooks/use-focus-trap.ts"],"sourcesContent":["import { useEffect, useRef, useState } from 'react';\n\n/**\n * Returns a value that lags `input` by `delayMs`. Each new `input`\n * resets the timer; the returned value updates once `input` has been\n * stable for `delayMs` ms.\n *\n * Companion to `useDebouncedCallback` — use this when you want the\n * debounced *value* (to drive a derived effect, query, or render),\n * and use the callback hook when you want the debounced *action*.\n *\n * @example\n *   const [query, setQuery] = useState('');\n *   const debouncedQuery = useDebouncedValue(query, 250);\n *   useEffect(() => { void search(debouncedQuery); }, [debouncedQuery]);\n */\nexport function useDebouncedValue<T>(input: T, delayMs: number): T {\n  const [value, setValue] = useState<T>(input);\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n  useEffect(() => {\n    if (delayMs <= 0) {\n      // Flush any pending timer so a stale queued value can't land\n      // after the synchronous update below.\n      if (timerRef.current !== null) {\n        clearTimeout(timerRef.current);\n        timerRef.current = null;\n      }\n      setValue(input);\n      return;\n    }\n    const timer = setTimeout(() => {\n      setValue(input);\n      timerRef.current = null;\n    }, delayMs);\n    timerRef.current = timer;\n    return () => clearTimeout(timer);\n  }, [input, delayMs]);\n\n  return value;\n}\n","import { useEffect, useRef, type RefObject } from 'react';\n\n/* -------------------------------------------------------------------- */\n/* Focus trap                                                           */\n/*                                                                      */\n/* Lightweight focus-trap hook for components that compose a Radix      */\n/* primitive without the overlay primitive (Dialog, AlertDialog, Sheet) */\n/* — those handle focus trapping for free via `@radix-ui/react-dialog`. */\n/*                                                                      */\n/* This hook is intentionally NOT a Radix `<FocusScope>` re-export — it */\n/* is a hook so it composes inside `forwardRef` components without      */\n/* nesting another wrapper element. If you need the full Radix         */\n/* contract (return-focus management, loop, asChild), use               */\n/* `@radix-ui/react-focus-scope` directly.                              */\n/* -------------------------------------------------------------------- */\n\nexport interface UseFocusTrapOptions {\n  /** When `false` the trap is inert. Defaults to `true`. */\n  enabled?: boolean;\n  /**\n   * When `true`, focus initial autofocus into the first focusable\n   * descendant on mount / enable. @default true\n   */\n  autoFocus?: boolean;\n  /**\n   * When `true`, restores focus to the previously-focused element on\n   * unmount / disable. @default true\n   */\n  restoreFocus?: boolean;\n}\n\nconst FOCUSABLE_SELECTOR = [\n  'a[href]',\n  'button:not([disabled])',\n  'input:not([disabled]):not([type=\"hidden\"])',\n  'select:not([disabled])',\n  'textarea:not([disabled])',\n  '[tabindex]:not([tabindex=\"-1\"])',\n  '[contenteditable=\"true\"]',\n  'audio[controls]',\n  'video[controls]',\n].join(',');\n\nfunction getFocusable(container: HTMLElement): HTMLElement[] {\n  return Array.from(\n    container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),\n  ).filter((el) => {\n    if (el.hidden) return false;\n    // `inert` and `aria-hidden=\"true\"` block focus on the element AND\n    // all its descendants — walk the chain to catch either ancestor.\n    let node: HTMLElement | null = el;\n    while (node) {\n      if (node.hasAttribute('inert')) return false;\n      if (node.getAttribute('aria-hidden') === 'true') return false;\n      node = node.parentElement;\n    }\n    return true;\n  });\n}\n\n/**\n * Constrain Tab navigation to descendants of `containerRef`. Wraps Tab\n * forward from the last focusable to the first, and Shift+Tab back from\n * the first to the last. Optionally autofocuses on enable and restores\n * focus on disable.\n *\n * Use this for inline modal patterns or focus zones that don't ship\n * with their own Radix overlay. Don't stack it inside Dialog / Sheet —\n * Radix already traps focus in those.\n *\n * @example\n *   const ref = useRef<HTMLDivElement>(null);\n *   useFocusTrap(ref, { enabled: open });\n *   return <div ref={ref}>…</div>;\n */\nexport function useFocusTrap<T extends HTMLElement>(\n  containerRef: RefObject<T | null>,\n  options: UseFocusTrapOptions = {},\n): void {\n  const { enabled = true, autoFocus = true, restoreFocus = true } = options;\n  const previouslyFocused = useRef<HTMLElement | null>(null);\n\n  useEffect(() => {\n    if (!enabled) return;\n    const container = containerRef.current;\n    if (!container) return;\n\n    previouslyFocused.current =\n      typeof document !== 'undefined' &&\n      document.activeElement instanceof HTMLElement\n        ? document.activeElement\n        : null;\n\n    if (autoFocus) {\n      const focusable = getFocusable(container);\n      // Container itself is the fallback focus target — needs `tabIndex`\n      // to receive focus, but `-1` is fine.\n      const target =\n        focusable[0] ?? (container.tabIndex >= -1 ? container : null);\n      target?.focus();\n    }\n\n    function onKeyDown(event: KeyboardEvent) {\n      if (event.key !== 'Tab') return;\n      const root = containerRef.current;\n      if (!root) return;\n      const focusable = getFocusable(root);\n      if (focusable.length === 0) {\n        event.preventDefault();\n        return;\n      }\n      const first = focusable[0];\n      const last = focusable[focusable.length - 1];\n      const active = document.activeElement;\n\n      if (event.shiftKey) {\n        if (active === first || !root.contains(active)) {\n          event.preventDefault();\n          last.focus();\n        }\n      } else {\n        if (active === last || !root.contains(active)) {\n          event.preventDefault();\n          first.focus();\n        }\n      }\n    }\n\n    container.addEventListener('keydown', onKeyDown);\n\n    return () => {\n      container.removeEventListener('keydown', onKeyDown);\n      if (restoreFocus && previouslyFocused.current) {\n        // rAF lets parent unmounts settle before refocus — a microtask\n        // fires too early and can throw on a detached node.\n        const target = previouslyFocused.current;\n        requestAnimationFrame(() => {\n          if (target.isConnected) target.focus();\n        });\n      }\n    };\n  }, [enabled, autoFocus, restoreFocus, containerRef]);\n}\n"],"names":["useDebouncedValue","input","delayMs","value","setValue","useState","timerRef","useRef","useEffect","timer","FOCUSABLE_SELECTOR","getFocusable","container","el","node","useFocusTrap","containerRef","options","enabled","autoFocus","restoreFocus","previouslyFocused","target","onKeyDown","event","root","focusable","first","last","active"],"mappings":";;;;;;;;;;;;;;;;;AAgBO,SAASA,EAAqBC,GAAUC,GAAoB;AACjE,QAAM,CAACC,GAAOC,CAAQ,IAAIC,EAAYJ,CAAK,GACrCK,IAAWC,EAA6C,IAAI;AAElE,SAAAC,EAAU,MAAM;AACd,QAAIN,KAAW,GAAG;AAGhB,MAAII,EAAS,YAAY,SACvB,aAAaA,EAAS,OAAO,GAC7BA,EAAS,UAAU,OAErBF,EAASH,CAAK;AACd;AAAA,IACF;AACA,UAAMQ,IAAQ,WAAW,MAAM;AAC7B,MAAAL,EAASH,CAAK,GACdK,EAAS,UAAU;AAAA,IACrB,GAAGJ,CAAO;AACV,WAAAI,EAAS,UAAUG,GACZ,MAAM,aAAaA,CAAK;AAAA,EACjC,GAAG,CAACR,GAAOC,CAAO,CAAC,GAEZC;AACT;ACTA,MAAMO,IAAqB;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,EAAE,KAAK,GAAG;AAEV,SAASC,EAAaC,GAAuC;AAC3D,SAAO,MAAM;AAAA,IACXA,EAAU,iBAA8BF,CAAkB;AAAA,EAAA,EAC1D,OAAO,CAACG,MAAO;AACf,QAAIA,EAAG,OAAQ,QAAO;AAGtB,QAAIC,IAA2BD;AAC/B,WAAOC,KAAM;AAEX,UADIA,EAAK,aAAa,OAAO,KACzBA,EAAK,aAAa,aAAa,MAAM,OAAQ,QAAO;AACxD,MAAAA,IAAOA,EAAK;AAAA,IACd;AACA,WAAO;AAAA,EACT,CAAC;AACH;AAiBO,SAASC,EACdC,GACAC,IAA+B,IACzB;AACN,QAAM,EAAE,SAAAC,IAAU,IAAM,WAAAC,IAAY,IAAM,cAAAC,IAAe,OAASH,GAC5DI,IAAoBd,EAA2B,IAAI;AAEzD,EAAAC,EAAU,MAAM;AACd,QAAI,CAACU,EAAS;AACd,UAAMN,IAAYI,EAAa;AAC/B,QAAI,CAACJ,EAAW;AAQhB,QANAS,EAAkB,UAChB,OAAO,WAAa,OACpB,SAAS,yBAAyB,cAC9B,SAAS,gBACT,MAEFF,GAAW;AAIb,YAAMG,IAHYX,EAAaC,CAAS,EAI5B,CAAC,MAAMA,EAAU,YAAY,KAAKA,IAAY;AAC1D,MAAAU,KAAA,QAAAA,EAAQ;AAAA,IACV;AAEA,aAASC,EAAUC,GAAsB;AACvC,UAAIA,EAAM,QAAQ,MAAO;AACzB,YAAMC,IAAOT,EAAa;AAC1B,UAAI,CAACS,EAAM;AACX,YAAMC,IAAYf,EAAac,CAAI;AACnC,UAAIC,EAAU,WAAW,GAAG;AAC1B,QAAAF,EAAM,eAAA;AACN;AAAA,MACF;AACA,YAAMG,IAAQD,EAAU,CAAC,GACnBE,IAAOF,EAAUA,EAAU,SAAS,CAAC,GACrCG,IAAS,SAAS;AAExB,MAAIL,EAAM,YACJK,MAAWF,KAAS,CAACF,EAAK,SAASI,CAAM,OAC3CL,EAAM,eAAA,GACNI,EAAK,MAAA,MAGHC,MAAWD,KAAQ,CAACH,EAAK,SAASI,CAAM,OAC1CL,EAAM,eAAA,GACNG,EAAM,MAAA;AAAA,IAGZ;AAEA,WAAAf,EAAU,iBAAiB,WAAWW,CAAS,GAExC,MAAM;AAEX,UADAX,EAAU,oBAAoB,WAAWW,CAAS,GAC9CH,KAAgBC,EAAkB,SAAS;AAG7C,cAAMC,IAASD,EAAkB;AACjC,8BAAsB,MAAM;AAC1B,UAAIC,EAAO,eAAaA,EAAO,MAAA;AAAA,QACjC,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF,GAAG,CAACJ,GAASC,GAAWC,GAAcJ,CAAY,CAAC;AACrD;"}
+{"version":3,"file":"index.js","sources":["../../src/hooks/use-debounced-value.ts","../../src/hooks/use-focus-trap.ts"],"sourcesContent":["import { useEffect, useRef, useState } from 'react';\n\n/**\n * Returns a value that lags `input` by `delayMs`. Each new `input`\n * resets the timer; the returned value updates once `input` has been\n * stable for `delayMs` ms.\n *\n * Companion to `useDebouncedCallback` — use this when you want the\n * debounced *value* (to drive a derived effect, query, or render),\n * and use the callback hook when you want the debounced *action*.\n *\n * @example\n *   const [query, setQuery] = useState('');\n *   const debouncedQuery = useDebouncedValue(query, 250);\n *   useEffect(() => { void search(debouncedQuery); }, [debouncedQuery]);\n */\nexport function useDebouncedValue<T>(input: T, delayMs: number): T {\n  const [value, setValue] = useState<T>(input);\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n  useEffect(() => {\n    if (delayMs <= 0) {\n      // Flush any pending timer so a stale queued value can't land\n      // after the synchronous update below.\n      if (timerRef.current !== null) {\n        clearTimeout(timerRef.current);\n        timerRef.current = null;\n      }\n      setValue(input);\n      return;\n    }\n    const timer = setTimeout(() => {\n      setValue(input);\n      timerRef.current = null;\n    }, delayMs);\n    timerRef.current = timer;\n    return () => clearTimeout(timer);\n  }, [input, delayMs]);\n\n  return value;\n}\n","import { useEffect, useRef, type RefObject } from 'react';\n\n/* -------------------------------------------------------------------- */\n/* Focus trap                                                           */\n/*                                                                      */\n/* Lightweight focus-trap hook for components that compose a Radix      */\n/* primitive without the overlay primitive (Dialog, AlertDialog, Sheet) */\n/* — those handle focus trapping for free via `@radix-ui/react-dialog`. */\n/*                                                                      */\n/* This hook is intentionally NOT a Radix `<FocusScope>` re-export — it */\n/* is a hook so it composes inside `forwardRef` components without      */\n/* nesting another wrapper element. If you need the full Radix         */\n/* contract (return-focus management, loop, asChild), use               */\n/* `@radix-ui/react-focus-scope` directly.                              */\n/* -------------------------------------------------------------------- */\n\nexport interface UseFocusTrapOptions {\n  /** When `false` the trap is inert. Defaults to `true`. */\n  enabled?: boolean;\n  /**\n   * When `true`, focus initial autofocus into the first focusable\n   * descendant on mount / enable. @default true\n   */\n  autoFocus?: boolean;\n  /**\n   * When `true`, restores focus to the previously-focused element on\n   * unmount / disable. @default true\n   */\n  restoreFocus?: boolean;\n}\n\nconst FOCUSABLE_SELECTOR = [\n  'a[href]',\n  'button:not([disabled])',\n  'input:not([disabled]):not([type=\"hidden\"])',\n  'select:not([disabled])',\n  'textarea:not([disabled])',\n  '[tabindex]:not([tabindex=\"-1\"])',\n  '[contenteditable=\"true\"]',\n  'audio[controls]',\n  'video[controls]',\n].join(',');\n\nfunction getFocusable(container: HTMLElement): HTMLElement[] {\n  return Array.from(\n    container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),\n  ).filter((el) => {\n    if (el.hidden) return false;\n    // `inert` and `aria-hidden=\"true\"` block focus on the element AND\n    // all its descendants — walk the chain to catch either ancestor.\n    let node: HTMLElement | null = el;\n    while (node) {\n      if (node.hasAttribute('inert')) return false;\n      if (node.getAttribute('aria-hidden') === 'true') return false;\n      node = node.parentElement;\n    }\n    return true;\n  });\n}\n\n/**\n * Constrain Tab navigation to descendants of `containerRef`. Wraps Tab\n * forward from the last focusable to the first, and Shift+Tab back from\n * the first to the last. Optionally autofocuses on enable and restores\n * focus on disable.\n *\n * Use this for inline modal patterns or focus zones that don't ship\n * with their own Radix overlay. Don't stack it inside Dialog / Sheet —\n * Radix already traps focus in those.\n *\n * @example\n *   const ref = useRef<HTMLDivElement>(null);\n *   useFocusTrap(ref, { enabled: open });\n *   return <div ref={ref}>…</div>;\n */\nexport function useFocusTrap<T extends HTMLElement>(\n  containerRef: RefObject<T | null>,\n  options: UseFocusTrapOptions = {},\n): void {\n  const { enabled = true, autoFocus = true, restoreFocus = true } = options;\n  const previouslyFocused = useRef<HTMLElement | null>(null);\n\n  useEffect(() => {\n    if (!enabled) return;\n    const container = containerRef.current;\n    if (!container) return;\n\n    previouslyFocused.current =\n      typeof document !== 'undefined' &&\n      document.activeElement instanceof HTMLElement\n        ? document.activeElement\n        : null;\n\n    if (autoFocus) {\n      const focusable = getFocusable(container);\n      // Container itself is the fallback focus target — needs `tabIndex`\n      // to receive focus, but `-1` is fine.\n      const target =\n        focusable[0] ?? (container.tabIndex >= -1 ? container : null);\n      target?.focus();\n    }\n\n    function onKeyDown(event: KeyboardEvent) {\n      if (event.key !== 'Tab') return;\n      const root = containerRef.current;\n      if (!root) return;\n      const focusable = getFocusable(root);\n      if (focusable.length === 0) {\n        event.preventDefault();\n        return;\n      }\n      const first = focusable[0];\n      const last = focusable[focusable.length - 1];\n      const active = document.activeElement;\n\n      if (event.shiftKey) {\n        if (active === first || !root.contains(active)) {\n          event.preventDefault();\n          last.focus();\n        }\n      } else {\n        if (active === last || !root.contains(active)) {\n          event.preventDefault();\n          first.focus();\n        }\n      }\n    }\n\n    container.addEventListener('keydown', onKeyDown);\n\n    return () => {\n      container.removeEventListener('keydown', onKeyDown);\n      if (restoreFocus && previouslyFocused.current) {\n        // rAF lets parent unmounts settle before refocus — a microtask\n        // fires too early and can throw on a detached node.\n        const target = previouslyFocused.current;\n        requestAnimationFrame(() => {\n          if (target.isConnected) target.focus();\n        });\n      }\n    };\n  }, [enabled, autoFocus, restoreFocus, containerRef]);\n}\n"],"names":["useDebouncedValue","input","delayMs","value","setValue","useState","timerRef","useRef","useEffect","timer","FOCUSABLE_SELECTOR","getFocusable","container","el","node","useFocusTrap","containerRef","options","enabled","autoFocus","restoreFocus","previouslyFocused","target","onKeyDown","event","root","focusable","first","last","active"],"mappings":";;;;;;;;;;;;;;;;;;;AAgBO,SAASA,EAAqBC,GAAUC,GAAoB;AACjE,QAAM,CAACC,GAAOC,CAAQ,IAAIC,EAAYJ,CAAK,GACrCK,IAAWC,EAA6C,IAAI;AAElE,SAAAC,EAAU,MAAM;AACd,QAAIN,KAAW,GAAG;AAGhB,MAAII,EAAS,YAAY,SACvB,aAAaA,EAAS,OAAO,GAC7BA,EAAS,UAAU,OAErBF,EAASH,CAAK;AACd;AAAA,IACF;AACA,UAAMQ,IAAQ,WAAW,MAAM;AAC7B,MAAAL,EAASH,CAAK,GACdK,EAAS,UAAU;AAAA,IACrB,GAAGJ,CAAO;AACV,WAAAI,EAAS,UAAUG,GACZ,MAAM,aAAaA,CAAK;AAAA,EACjC,GAAG,CAACR,GAAOC,CAAO,CAAC,GAEZC;AACT;ACTA,MAAMO,IAAqB;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,EAAE,KAAK,GAAG;AAEV,SAASC,EAAaC,GAAuC;AAC3D,SAAO,MAAM;AAAA,IACXA,EAAU,iBAA8BF,CAAkB;AAAA,EAAA,EAC1D,OAAO,CAACG,MAAO;AACf,QAAIA,EAAG,OAAQ,QAAO;AAGtB,QAAIC,IAA2BD;AAC/B,WAAOC,KAAM;AAEX,UADIA,EAAK,aAAa,OAAO,KACzBA,EAAK,aAAa,aAAa,MAAM,OAAQ,QAAO;AACxD,MAAAA,IAAOA,EAAK;AAAA,IACd;AACA,WAAO;AAAA,EACT,CAAC;AACH;AAiBO,SAASC,EACdC,GACAC,IAA+B,IACzB;AACN,QAAM,EAAE,SAAAC,IAAU,IAAM,WAAAC,IAAY,IAAM,cAAAC,IAAe,OAASH,GAC5DI,IAAoBd,EAA2B,IAAI;AAEzD,EAAAC,EAAU,MAAM;AACd,QAAI,CAACU,EAAS;AACd,UAAMN,IAAYI,EAAa;AAC/B,QAAI,CAACJ,EAAW;AAQhB,QANAS,EAAkB,UAChB,OAAO,WAAa,OACpB,SAAS,yBAAyB,cAC9B,SAAS,gBACT,MAEFF,GAAW;AAIb,YAAMG,IAHYX,EAAaC,CAAS,EAI5B,CAAC,MAAMA,EAAU,YAAY,KAAKA,IAAY;AAC1D,MAAAU,KAAA,QAAAA,EAAQ;AAAA,IACV;AAEA,aAASC,EAAUC,GAAsB;AACvC,UAAIA,EAAM,QAAQ,MAAO;AACzB,YAAMC,IAAOT,EAAa;AAC1B,UAAI,CAACS,EAAM;AACX,YAAMC,IAAYf,EAAac,CAAI;AACnC,UAAIC,EAAU,WAAW,GAAG;AAC1B,QAAAF,EAAM,eAAA;AACN;AAAA,MACF;AACA,YAAMG,IAAQD,EAAU,CAAC,GACnBE,IAAOF,EAAUA,EAAU,SAAS,CAAC,GACrCG,IAAS,SAAS;AAExB,MAAIL,EAAM,YACJK,MAAWF,KAAS,CAACF,EAAK,SAASI,CAAM,OAC3CL,EAAM,eAAA,GACNI,EAAK,MAAA,MAGHC,MAAWD,KAAQ,CAACH,EAAK,SAASI,CAAM,OAC1CL,EAAM,eAAA,GACNG,EAAM,MAAA;AAAA,IAGZ;AAEA,WAAAf,EAAU,iBAAiB,WAAWW,CAAS,GAExC,MAAM;AAEX,UADAX,EAAU,oBAAoB,WAAWW,CAAS,GAC9CH,KAAgBC,EAAkB,SAAS;AAG7C,cAAMC,IAASD,EAAkB;AACjC,8BAAsB,MAAM;AAC1B,UAAIC,EAAO,eAAaA,EAAO,MAAA;AAAA,QACjC,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF,GAAG,CAACJ,GAASC,GAAWC,GAAcJ,CAAY,CAAC;AACrD;"}

package/dist/hooks/use-priority-overflow.d.ts

@@ -0,0 +1,63 @@
+export type PriorityOverflowStage = 'full' | 'icons';
+export interface PriorityLayoutInput {
+    /** Inline size of the box the strip must fit into. */
+    containerWidth: number;
+    /** Natural width of each item at the full (icon + label) stage. */
+    fullWidths: number[];
+    /** Whole-row natural width at the full stage (captures joins/margins). */
+    fullRowWidth: number;
+    /** Natural per-item widths at the icon-only stage; omit for single-stage. */
+    iconWidths?: number[];
+    /** Whole-row natural width at the icon-only stage. */
+    iconRowWidth?: number;
+    /** Natural width of the overflow trigger button. */
+    triggerWidth: number;
+    /** Items that must never move into the menu. */
+    pinned?: ReadonlyArray<boolean>;
+}
+export interface PriorityLayout {
+    stage: PriorityOverflowStage;
+    /** Per-item: true = rendered in the strip, false = moved to the menu. */
+    visible: boolean[];
+    /** True when at least one item moved to the menu (trigger shown). */
+    overflowing: boolean;
+}
+/**
+ * Pure priority+ maths: full row → icon-only row → trailing items into a
+ * menu behind a trigger. Width sums are direction-agnostic, so the result
+ * is identical in RTL. `+1` tolerances absorb sub-pixel rounding.
+ */
+export declare function computePriorityLayout(input: PriorityLayoutInput): PriorityLayout;
+export interface UsePriorityOverflowOptions {
+    /** Master switch — off = everything visible, nothing measured. */
+    enabled: boolean;
+    /** Number of items in the strip (drives re-measure on child changes). */
+    count: number;
+    /** Measure a second icon-only stage before spilling into the menu. */
+    twoStage?: boolean;
+    /** Per-index pin flags — pinned items never move into the menu. */
+    pinned?: ReadonlyArray<boolean>;
+}
+export interface UsePriorityOverflowReturn {
+    /** Attach to the block wrapper whose inline size is the budget. */
+    containerRef: (node: HTMLElement | null) => void;
+    /** Attach to the hidden row of full-stage clones. */
+    fullRowRef: (node: HTMLElement | null) => void;
+    /** Attach to the hidden row of icon-stage clones (twoStage only). */
+    iconRowRef: (node: HTMLElement | null) => void;
+    /** Attach to the hidden overflow-trigger probe. */
+    triggerProbeRef: (node: HTMLElement | null) => void;
+    stage: PriorityOverflowStage;
+    visible: boolean[];
+    overflowing: boolean;
+}
+/**
+ * Priority+ overflow for a horizontal control strip. The caller renders
+ * hidden measurement rows (always mounted, `aria-hidden` + `inert`,
+ * visibility-hidden — never display:none, they must keep layout) and this
+ * hook compares their natural widths against the container. Because the
+ * rows stay mounted, font swaps and label/locale changes resize them and
+ * the ResizeObserver re-measures — no font or i18n listeners needed.
+ */
+export declare function usePriorityOverflow(options: UsePriorityOverflowOptions): UsePriorityOverflowReturn;
+//# sourceMappingURL=use-priority-overflow.d.ts.map

package/dist/hooks/use-priority-overflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-priority-overflow.d.ts","sourceRoot":"","sources":["../../src/hooks/use-priority-overflow.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,qBAAqB,CAAC;IAC7B,yEAAyE;IACzE,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,qEAAqE;IACrE,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,GACzB,cAAc,CAqDhB;AAED,MAAM,WAAW,0BAA0B;IACzC,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,YAAY,EAAE,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACjD,qDAAqD;IACrD,UAAU,EAAE,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,qEAAqE;IACrE,UAAU,EAAE,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,mDAAmD;IACnD,eAAe,EAAE,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACpD,KAAK,EAAE,qBAAqB,CAAC;IAC7B,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;CACtB;AAQD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,yBAAyB,CAgG3B"}

package/dist/hooks/use-visual-viewport-pin.d.ts

@@ -0,0 +1,32 @@
+export interface VisualViewportPinOptions {
+    /** Which layout-viewport edge the element is pinned to (default `'top'`).
+     *  The hook assumes the element's untransformed position IS that edge —
+     *  true for `fixed` bars, and for `sticky` bars while stuck. */
+    edge?: 'top' | 'bottom';
+    /** Suspend pinning and hand the transform back to CSS — e.g. while a
+     *  `sticky="scroll-up"` header is hidden by its own translate. */
+    disabled?: boolean;
+}
+/**
+ * Keeps a fixed/sticky bar glued to the visual viewport while the user
+ * pinch-zooms or pans, so persistent chrome (and the CTA it carries) never
+ * leaves the visible screen. Returns a callback ref — attach it to the bar
+ * (composable via `composeRefs`); late-mounting and remounting nodes re-pin
+ * automatically.
+ *
+ * The pin engages only under real pinch-zoom (`visualViewport.scale > 1`):
+ * keyboard-driven viewport shrink (scale stays 1) and desktop scrollbar
+ * deltas never move the bar. Deliberate 1.4.4 trade-off: counter-scaled
+ * chrome cannot itself be magnified by pinch-zoom — its text sizes through
+ * rem tokens and OS text-size settings instead, while the pin keeps the
+ * controls reachable (a net gain for zoom accessibility).
+ *
+ * Writes `transform` / `transform-origin` imperatively (per-frame viewport
+ * geometry cannot be expressed as static classes) and suppresses the
+ * element's own transitions only while a pin is applied, so the bar tracks
+ * the viewport without transition lag. All geometry is in physical viewport
+ * coordinates by nature — this is not layout CSS, so the logical-properties
+ * rule does not apply.
+ */
+export declare function useVisualViewportPin<T extends HTMLElement>({ edge, disabled, }?: VisualViewportPinOptions): (node: T | null) => void;
+//# sourceMappingURL=use-visual-viewport-pin.d.ts.map

package/dist/hooks/use-visual-viewport-pin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-visual-viewport-pin.d.ts","sourceRoot":"","sources":["../../src/hooks/use-visual-viewport-pin.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,wBAAwB;IACvC;;oEAEgE;IAChE,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IACxB;sEACkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,WAAW,EAAE,EAC1D,IAAY,EACZ,QAAgB,GACjB,GAAE,wBAA6B,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAoD1D"}