se-design 1.0.81 → 1.0.83-dev.0

package/dist/index75.js.map

@@ -1 +1 @@
-{"version":3,"file":"index75.js","sources":["../src/utils/virtualClick.ts"],"sourcesContent":["/**\n * Input/virtual click detection helpers.\n */\n\nconst isAndroid = () =>\n  typeof navigator !== 'undefined' && /Android/i.test(navigator.userAgent);\n\nexport const isVirtualClick = (event: MouseEvent | PointerEvent): boolean => {\n  const pointerType = 'pointerType' in event ? event.pointerType : undefined;\n\n  // JAWS/NVDA with Firefox.\n  if (pointerType === '' && event.isTrusted) {\n    return true;\n  }\n\n  // Android TalkBack's detail value varies depending on listener type.\n  if (isAndroid() && pointerType) {\n    return event.type === 'click' && event.buttons === 1;\n  }\n\n  // Most browsers: virtual click has detail === 0 and no pointerType.\n  return event.detail === 0 && !pointerType;\n};\n\n\n"],"names":["isAndroid","navigator","test","userAgent","isVirtualClick","event","pointerType","undefined","isTrusted","type","buttons","detail"],"mappings":"AAIA,MAAMA,IAAYA,MAChB,OAAOC,YAAc,OAAe,WAAWC,KAAKD,UAAUE,SAAS,GAE5DC,IAAiBA,CAACC,MAA8C;AAC3E,QAAMC,IAAc,iBAAiBD,IAAQA,EAAMC,cAAcC;AAGjE,SAAID,MAAgB,MAAMD,EAAMG,YACvB,KAILR,EAAAA,KAAeM,IACVD,EAAMI,SAAS,WAAWJ,EAAMK,YAAY,IAI9CL,EAAMM,WAAW,KAAK,CAACL;AAChC;"}
+{"version":3,"file":"index75.js","sources":["../src/utils/a11y/focusableElements.ts"],"sourcesContent":["/**\n * Utilities for finding focusable elements within a container.\n * \n * Used for focus management in modals, popovers, and other interactive overlays.\n */\n\n/**\n * Base selector for standard focusable elements.\n * Matches: buttons, links, inputs, selects, textareas, elements with tabindex >= 0, contenteditable.\n */\nexport const FOCUSABLE_SELECTOR = [\n  'button:not([disabled]):not([tabindex=\"-1\"])',\n  '[href]:not([tabindex=\"-1\"])',\n  'input:not([disabled]):not([tabindex=\"-1\"])',\n  'select:not([disabled]):not([tabindex=\"-1\"])',\n  'textarea:not([disabled]):not([tabindex=\"-1\"])',\n  '[tabindex]:not([tabindex=\"-1\"]):not([disabled])',\n  '[contenteditable=\"true\"]:not([tabindex=\"-1\"])'\n].join(', ');\n\n/**\n * Extended selector that includes ARIA role-based focusable elements.\n * Useful for composite widgets like menus, listboxes, etc.\n */\nexport const FOCUSABLE_WITH_ROLES_SELECTOR = [\n  FOCUSABLE_SELECTOR,\n  '[role=\"menuitem\"]',\n  '[role=\"option\"]',\n  '[role=\"menuitemcheckbox\"]',\n  '[role=\"menuitemradio\"]'\n].join(', ');\n\n/**\n * Options for getFocusableElements\n */\nexport interface GetFocusableElementsOptions {\n  /**\n   * Container element to search within. If null/undefined, returns empty array.\n   */\n  container: HTMLElement | null;\n  /**\n   * Whether to include role-based focusable elements (menuitem, option, etc.).\n   * Default: false (uses base selector only)\n   */\n  includeRoles?: boolean;\n  /**\n   * Additional custom selectors to include.\n   */\n  additionalSelectors?: string[];\n  /**\n   * Whether to filter out hidden/invisible elements.\n   * Default: false (returns all matching elements regardless of visibility)\n   */\n  filterHidden?: boolean;\n}\n\n/**\n * Get all focusable elements within a container.\n * \n * @example Basic usage (standard focusable elements)\n * ```ts\n * const focusables = getFocusableElements({ container: dialogRef.current });\n * focusables[0]?.focus(); // Focus first element\n * ```\n * \n * @example With role-based elements (for menus/listboxes)\n * ```ts\n * const focusables = getFocusableElements({ \n *   container: menuRef.current,\n *   includeRoles: true \n * });\n * ```\n * \n * @example With custom selectors\n * ```ts\n * const focusables = getFocusableElements({ \n *   container: customWidgetRef.current,\n *   additionalSelectors: ['[data-focusable=\"true\"]']\n * });\n * ```\n */\nexport function getFocusableElements({\n  container,\n  includeRoles = false,\n  additionalSelectors = [],\n  filterHidden = false\n}: GetFocusableElementsOptions): HTMLElement[] {\n  if (!container) return [];\n\n  const selector = [\n    includeRoles ? FOCUSABLE_WITH_ROLES_SELECTOR : FOCUSABLE_SELECTOR,\n    ...additionalSelectors\n  ].filter(Boolean).join(', ');\n\n  const elements = Array.from(container.querySelectorAll<HTMLElement>(selector));\n\n  if (!filterHidden) return elements;\n\n  // Filter out hidden/invisible elements\n  return elements.filter((el) => {\n    const style = window.getComputedStyle(el);\n    return (\n      style.display !== 'none' &&\n      style.visibility !== 'hidden' &&\n      style.opacity !== '0' &&\n      !el.hasAttribute('hidden') &&\n      el.offsetWidth > 0 &&\n      el.offsetHeight > 0\n    );\n  });\n}\n\n/**\n * Get the first focusable element in a container.\n * Returns null if none found.\n */\nexport function getFirstFocusableElement(\n  options: GetFocusableElementsOptions\n): HTMLElement | null {\n  const focusables = getFocusableElements(options);\n  return focusables.length > 0 ? focusables[0] : null;\n}\n\n/**\n * Get the last focusable element in a container.\n * Returns null if none found.\n */\nexport function getLastFocusableElement(\n  options: GetFocusableElementsOptions\n): HTMLElement | null {\n  const focusables = getFocusableElements(options);\n  return focusables.length > 0 ? focusables[focusables.length - 1] : null;\n}\n"],"names":["FOCUSABLE_SELECTOR","join","FOCUSABLE_WITH_ROLES_SELECTOR","getFocusableElements","container","includeRoles","additionalSelectors","filterHidden","selector","filter","Boolean","elements","Array","from","querySelectorAll","el","style","window","getComputedStyle","display","visibility","opacity","hasAttribute","offsetWidth","offsetHeight","getFirstFocusableElement","options","focusables","length","getLastFocusableElement"],"mappings":"AAUO,MAAMA,IAAqB,CAChC,+CACA,+BACA,8CACA,+CACA,iDACA,mDACA,+CAA+C,EAC/CC,KAAK,IAAI,GAMEC,IAAgC,CAC3CF,GACA,qBACA,mBACA,6BACA,wBAAwB,EACxBC,KAAK,IAAI;AAmDJ,SAASE,EAAqB;AAAA,EACnCC,WAAAA;AAAAA,EACAC,cAAAA,IAAe;AAAA,EACfC,qBAAAA,IAAsB,CAAA;AAAA,EACtBC,cAAAA,IAAe;AACY,GAAkB;AAC7C,MAAI,CAACH,EAAW,QAAO,CAAA;AAEvB,QAAMI,IAAW,CACfH,IAAeH,IAAgCF,GAC/C,GAAGM,CAAmB,EACtBG,OAAOC,OAAO,EAAET,KAAK,IAAI,GAErBU,IAAWC,MAAMC,KAAKT,EAAUU,iBAA8BN,CAAQ,CAAC;AAE7E,SAAKD,IAGEI,EAASF,OAAQM,CAAAA,MAAO;AAC7B,UAAMC,IAAQC,OAAOC,iBAAiBH,CAAE;AACxC,WACEC,EAAMG,YAAY,UAClBH,EAAMI,eAAe,YACrBJ,EAAMK,YAAY,OAClB,CAACN,EAAGO,aAAa,QAAQ,KACzBP,EAAGQ,cAAc,KACjBR,EAAGS,eAAe;AAAA,EAEtB,CAAC,IAbyBb;AAc5B;AAMO,SAASc,EACdC,GACoB;AACpB,QAAMC,IAAaxB,EAAqBuB,CAAO;AAC/C,SAAOC,EAAWC,SAAS,IAAID,EAAW,CAAC,IAAI;AACjD;AAMO,SAASE,EACdH,GACoB;AACpB,QAAMC,IAAaxB,EAAqBuB,CAAO;AAC/C,SAAOC,EAAWC,SAAS,IAAID,EAAWA,EAAWC,SAAS,CAAC,IAAI;AACrE;"}

package/dist/index76.js

@@ -1,57 +1,111 @@
-import { useState as m, useEffect as w, useCallback as b } from "react";
-import { useScrollActiveIntoView as x } from "./index80.js";
-function s({
-  items: c,
-  isOpen: t,
-  onSelect: l,
-  onClose: i,
-  onOpen: n,
-  loop: o = !0,
-  disabled: h = !1,
-  listboxRef: k,
-  optionSelector: g = '[role="option"]'
-}) {
-  const [f, r] = m(-1);
-  w(() => {
-    t || r(-1);
-  }, [t]), x({
-    containerRef: k,
-    activeIndex: f,
-    itemSelector: g,
-    enabled: t
+import { useRef as p, useLayoutEffect as a } from "react";
+import { getFirstFocusableElement as A, getFocusableElements as L } from "./index75.js";
+let f = null;
+function F(e) {
+  const n = e.composedPath();
+  for (const s of n)
+    if (s instanceof HTMLElement && s.tabIndex >= 0) {
+      f = s;
+      return;
+    }
+}
+function k(e) {
+  (e.key === "Enter" || e.key === " ") && (f = document.activeElement);
+}
+typeof document < "u" && (document.addEventListener("pointerdown", F, !0), document.addEventListener("keydown", k, !0));
+function T() {
+  const e = f;
+  return f = null, e;
+}
+let m = null, l = null;
+function _(e) {
+  l !== null && cancelAnimationFrame(l), m = e, l = requestAnimationFrame(() => {
+    m = null, l = null;
   });
-  const D = b((a) => {
-    if (h) {
-      a.key === "Escape" && t && (a.preventDefault(), i());
+}
+function I() {
+  l !== null && (cancelAnimationFrame(l), l = null);
+  const e = m;
+  return m = null, e;
+}
+function w(e, n) {
+  return n === "none" ? null : n === "first" ? A({
+    container: e
+  }) || e : n === "container" ? e : typeof n == "string" ? e.querySelector(n) : n instanceof HTMLElement ? n : null;
+}
+function C({
+  enabled: e,
+  containerRef: n,
+  restoreFocus: s = !0,
+  initialFocus: d = "first",
+  returnFocusRef: g,
+  portalContainerRefs: h
+}) {
+  const u = p(null), E = p(null);
+  return a(() => {
+    if (!e) {
+      if (s && u.current) {
+        const t = u.current;
+        u.current = null, requestAnimationFrame(() => {
+          t.isConnected && t.focus();
+        });
+      }
       return;
     }
-    const e = c.length;
-    switch (a.key) {
-      case "ArrowDown":
-        a.preventDefault(), !t && e > 0 ? (n?.(), r(0)) : t && e > 0 && r((u) => o ? (u + 1) % e : Math.min(u + 1, e - 1));
-        break;
-      case "ArrowUp":
-        a.preventDefault(), t && e > 0 && r((u) => u === -1 ? e - 1 : o ? (u - 1 + e) % e : Math.max(u - 1, 0));
-        break;
-      case "Enter":
-        a.preventDefault(), t ? f >= 0 && c[f] && (l(c[f], f), r(-1)) : (n?.(), r(0));
-        break;
-      case "Escape":
-        t && (a.preventDefault(), i(), r(-1));
-        break;
-      case "Tab":
-        t && (i(), r(-1));
-        break;
+    const r = n.current;
+    if (!r) return;
+    const c = g?.current ?? I() ?? f ?? document.activeElement;
+    if (f = null, c?.tagName === "IFRAME") {
+      u.current = null;
+      return;
     }
-  }, [h, c, t, f, l, i, n, o]), d = b((a, e) => `${a}-option-${e}`, []);
-  return {
-    highlightedIndex: f,
-    setHighlightedIndex: r,
-    handleKeyDown: D,
-    getOptionId: d
+    return u.current = c, r.contains(document.activeElement) || requestAnimationFrame(() => {
+      w(r, d)?.focus();
+    }), () => {
+      if (s && u.current) {
+        const t = u.current;
+        u.current = null, requestAnimationFrame(() => {
+          t.isConnected && t.focus();
+        });
+      }
+    };
+  }, [e, n, s, d]), a(() => {
+    if (!e) return;
+    const r = n.current;
+    if (!r) return;
+    const c = (t) => {
+      if (t.key === "Tab") {
+        const o = L({
+          container: r
+        });
+        if (o.length === 0) {
+          t.preventDefault(), r.focus();
+          return;
+        }
+        const i = o[0], v = o[o.length - 1], y = document.activeElement;
+        t.shiftKey && y === i ? (t.preventDefault(), v.focus()) : !t.shiftKey && y === v && (t.preventDefault(), i.focus());
+      }
+    };
+    return document.addEventListener("keydown", c, !0), () => document.removeEventListener("keydown", c, !0);
+  }, [e, n]), a(() => {
+    if (!e) return;
+    const r = n.current;
+    if (!r) return;
+    const c = (t) => {
+      const o = t.target;
+      o?.tagName !== "IFRAME" && (r.contains(o) ? E.current = o : h?.current?.some((i) => i.current?.contains(o)) || (E.current || A({
+        container: r
+      }) || r).focus());
+    };
+    return document.addEventListener("focusin", c, !0), () => document.removeEventListener("focusin", c, !0);
+  }, [e, n]), {
+    triggerRef: u
   };
 }
 export {
-  s as useComboboxNavigation
+  I as consumeFocusAnchor,
+  T as consumeLastInteractedElement,
+  _ as setFocusAnchor,
+  C as useFocusTrap
 };
 //# sourceMappingURL=index76.js.map

package/dist/index76.js.map

@@ -1 +1 @@
-{"version":3,"file":"index76.js","sources":["../src/utils/a11y/useComboboxNavigation.ts"],"sourcesContent":["import { useCallback, useState, useEffect } from 'react';\nimport type { RefObject } from 'react';\nimport { useScrollActiveIntoView } from './useScrollActiveIntoView';\n\nexport interface UseComboboxNavigationOptions<T = any> {\n  /**\n   * Array of items to navigate through\n   */\n  items: T[];\n  \n  /**\n   * Whether the dropdown is currently open\n   */\n  isOpen: boolean;\n  \n  /**\n   * Callback when an item is selected (Enter key)\n   */\n  onSelect: (item: T, index: number) => void;\n  \n  /**\n   * Callback to close the dropdown\n   */\n  onClose: () => void;\n  \n  /**\n   * Optional: Callback to open the dropdown\n   */\n  onOpen?: () => void;\n  \n  /**\n   * Whether to wrap around at the ends of the list.\n   * Default: true\n   */\n  loop?: boolean;\n  \n  /**\n   * Whether keyboard navigation is disabled\n   * (e.g., for custom rendered content)\n   */\n  disabled?: boolean;\n  \n  /**\n   * Ref to the listbox container for scroll management\n   */\n  listboxRef?: RefObject<HTMLElement | null>;\n  \n  /**\n   * CSS selector for option elements (default: '[role=\"option\"]')\n   */\n  optionSelector?: string;\n}\n\nexport interface UseComboboxNavigationReturn {\n  /**\n   * Currently highlighted index (-1 if none)\n   */\n  highlightedIndex: number;\n  \n  /**\n   * Set the highlighted index manually\n   */\n  setHighlightedIndex: (index: number | ((prev: number) => number)) => void;\n  \n  /**\n   * Keyboard event handler for the combobox input\n   */\n  handleKeyDown: (e: React.KeyboardEvent) => void;\n  \n  /**\n   * Generate stable ID for an option\n   */\n  getOptionId: (listboxId: string, index: number) => string;\n  \n}\n\n/**\n * Hook for managing combobox keyboard navigation with aria-activedescendant.\n * \n * Implements WAI-ARIA 1.2 Combobox pattern:\n * - Arrow Up/Down to navigate options\n * - Enter to select highlighted option\n * - Escape to close dropdown\n * - Tab to close and move focus\n * - Auto-scrolls highlighted option into view\n * \n * @example\n * ```tsx\n * const { \n *   highlightedIndex, \n *   handleKeyDown, \n *   getOptionId \n * } = useComboboxNavigation({\n *   items: suggestions,\n *   isOpen: isDropdownOpen,\n *   onSelect: (item, idx) => handleSelect(item),\n *   onClose: () => setIsOpen(false),\n *   listboxRef\n * });\n * \n * <input\n *   role=\"combobox\"\n *   onKeyDown={handleKeyDown}\n *   aria-activedescendant={highlightedIndex >= 0 ? getOptionId(listboxId, highlightedIndex) : undefined}\n * />\n * ```\n */\nexport function useComboboxNavigation<T = any>({\n  items,\n  isOpen,\n  onSelect,\n  onClose,\n  onOpen,\n  loop = true,\n  disabled = false,\n  listboxRef,\n  optionSelector = '[role=\"option\"]'\n}: UseComboboxNavigationOptions<T>): UseComboboxNavigationReturn {\n  const [highlightedIndex, setHighlightedIndex] = useState<number>(-1);\n  \n  // Reset highlighted index when dropdown closes\n  useEffect(() => {\n    if (!isOpen) {\n      setHighlightedIndex(-1);\n    }\n  }, [isOpen]);\n  \n  // Auto-scroll highlighted item into view\n  useScrollActiveIntoView({\n    containerRef: listboxRef,\n    activeIndex: highlightedIndex,\n    itemSelector: optionSelector,\n    enabled: isOpen\n  });\n  \n  const handleKeyDown = useCallback(\n    (e: React.KeyboardEvent) => {\n      if (disabled) {\n        // For disabled navigation, still handle Escape\n        if (e.key === 'Escape' && isOpen) {\n          e.preventDefault();\n          onClose();\n        }\n        return;\n      }\n      \n      const itemCount = items.length;\n      \n      switch (e.key) {\n        case 'ArrowDown':\n          e.preventDefault();\n          if (!isOpen && itemCount > 0) {\n            // Open dropdown and highlight first item\n            onOpen?.();\n            setHighlightedIndex(0);\n          } else if (isOpen && itemCount > 0) {\n            // Navigate down\n            setHighlightedIndex((prev) => {\n              if (loop) {\n                return (prev + 1) % itemCount;\n              }\n              return Math.min(prev + 1, itemCount - 1);\n            });\n          }\n          break;\n          \n        case 'ArrowUp':\n          e.preventDefault();\n          if (isOpen && itemCount > 0) {\n            // Navigate up\n            setHighlightedIndex((prev) => {\n              // If nothing highlighted, go to last item\n              if (prev === -1) {\n                return itemCount - 1;\n              }\n              if (loop) {\n                return (prev - 1 + itemCount) % itemCount;\n              }\n              return Math.max(prev - 1, 0);\n            });\n          }\n          break;\n          \n        case 'Enter':\n          e.preventDefault();\n          if (!isOpen) {\n            onOpen?.();\n            setHighlightedIndex(0);\n          } else if (highlightedIndex >= 0 && items[highlightedIndex]) {\n            onSelect(items[highlightedIndex], highlightedIndex);\n            setHighlightedIndex(-1);\n          }\n          break;\n\n        case 'Escape':\n          if (isOpen) {\n            e.preventDefault();\n            onClose();\n            setHighlightedIndex(-1);\n          }\n          break;\n          \n        case 'Tab':\n          // Close dropdown on Tab (don't preventDefault - let focus move naturally)\n          if (isOpen) {\n            onClose();\n            setHighlightedIndex(-1);\n          }\n          break;\n      }\n    },\n    [disabled, items, isOpen, highlightedIndex, onSelect, onClose, onOpen, loop]\n  );\n  \n  const getOptionId = useCallback(\n    (listboxId: string, index: number) => `${listboxId}-option-${index}`,\n    []\n  );\n  \n  return {\n    highlightedIndex,\n    setHighlightedIndex,\n    handleKeyDown,\n    getOptionId\n  };\n}\n"],"names":["useState","useEffect","useCallback","useScrollActiveIntoView","useComboboxNavigation","items","isOpen","onSelect","onClose","onOpen","loop","disabled","listboxRef","optionSelector","highlightedIndex","setHighlightedIndex","containerRef","activeIndex","itemSelector","enabled","handleKeyDown","e","key","preventDefault","itemCount","length","prev","Math","min","max","getOptionId","listboxId","index"],"mappings":"AA2GO,SAAA,YAAAA,GAAA,aAAAC,GAAA,eAAAC,SAAA;AAAA,SAAA,2BAAAC,SAAA;AAAA,SAASC,EAA+B;AAAA,EAC7CC,OAAAA;AAAAA,EACAC,QAAAA;AAAAA,EACAC,UAAAA;AAAAA,EACAC,SAAAA;AAAAA,EACAC,QAAAA;AAAAA,EACAC,MAAAA,IAAO;AAAA,EACPC,UAAAA,IAAW;AAAA,EACXC,YAAAA;AAAAA,EACAC,gBAAAA,IAAiB;AACc,GAAgC;AAC/D,QAAM,CAACC,GAAkBC,CAAmB,IAAIf,EAAiB,EAAE;AAGnEC,EAAAA,EAAU,MAAM;AACd,IAAKK,KACHS,EAAoB,EAAE;AAAA,EAE1B,GAAG,CAACT,CAAM,CAAC,GAGXH,EAAwB;AAAA,IACtBa,cAAcJ;AAAAA,IACdK,aAAaH;AAAAA,IACbI,cAAcL;AAAAA,IACdM,SAASb;AAAAA,EAAAA,CACV;AAED,QAAMc,IAAgBlB,EACpB,CAACmB,MAA2B;AAC1B,QAAIV,GAAU;AAEZ,MAAIU,EAAEC,QAAQ,YAAYhB,MACxBe,EAAEE,eAAAA,GACFf,EAAAA;AAEF;AAAA,IACF;AAEA,UAAMgB,IAAYnB,EAAMoB;AAExB,YAAQJ,EAAEC,KAAAA;AAAAA,MACR,KAAK;AACHD,QAAAA,EAAEE,eAAAA,GACE,CAACjB,KAAUkB,IAAY,KAEzBf,IAAAA,GACAM,EAAoB,CAAC,KACZT,KAAUkB,IAAY,KAE/BT,EAAqBW,CAAAA,MACfhB,KACMgB,IAAO,KAAKF,IAEfG,KAAKC,IAAIF,IAAO,GAAGF,IAAY,CAAC,CACxC;AAEH;AAAA,MAEF,KAAK;AACHH,QAAAA,EAAEE,eAAAA,GACEjB,KAAUkB,IAAY,KAExBT,EAAqBW,CAAAA,MAEfA,MAAS,KACJF,IAAY,IAEjBd,KACMgB,IAAO,IAAIF,KAAaA,IAE3BG,KAAKE,IAAIH,IAAO,GAAG,CAAC,CAC5B;AAEH;AAAA,MAEF,KAAK;AACHL,QAAAA,EAAEE,eAAAA,GACGjB,IAGMQ,KAAoB,KAAKT,EAAMS,CAAgB,MACxDP,EAASF,EAAMS,CAAgB,GAAGA,CAAgB,GAClDC,EAAoB,EAAE,MAJtBN,IAAAA,GACAM,EAAoB,CAAC;AAKvB;AAAA,MAEF,KAAK;AACH,QAAIT,MACFe,EAAEE,eAAAA,GACFf,EAAAA,GACAO,EAAoB,EAAE;AAExB;AAAA,MAEF,KAAK;AAEH,QAAIT,MACFE,EAAAA,GACAO,EAAoB,EAAE;AAExB;AAAA,IAAA;AAAA,EAEN,GACA,CAACJ,GAAUN,GAAOC,GAAQQ,GAAkBP,GAAUC,GAASC,GAAQC,CAAI,CAC7E,GAEMoB,IAAc5B,EAClB,CAAC6B,GAAmBC,MAAkB,GAAGD,CAAS,WAAWC,CAAK,IAClE,CAAA,CACF;AAEA,SAAO;AAAA,IACLlB,kBAAAA;AAAAA,IACAC,qBAAAA;AAAAA,IACAK,eAAAA;AAAAA,IACAU,aAAAA;AAAAA,EAAAA;AAEJ;"}
+{"version":3,"file":"index76.js","sources":["../src/utils/a11y/useFocusTrap.ts"],"sourcesContent":["import { useLayoutEffect, useRef } from 'react';\nimport type { MutableRefObject, RefObject } from 'react';\nimport { getFocusableElements, getFirstFocusableElement } from './focusableElements';\n\nexport interface UseFocusTrapOptions<T extends HTMLElement = HTMLElement> {\n  /**\n   * Whether the focus trap is active.\n   */\n  enabled: boolean;\n  /**\n   * Container element ref to trap focus within.\n   */\n  containerRef: React.RefObject<T | null>;\n  /**\n   * Whether to restore focus to the element that had focus before trap activated.\n   * Default: true\n   */\n  restoreFocus?: boolean;\n  /**\n   * Initial focus target when trap activates.\n   * - 'first': Focus first focusable element (default)\n   * - 'container': Focus the container itself\n   * - 'none': Skip initial focus — browser handles it (e.g. autofocus attribute)\n   * - CSS selector: Focus element matching selector\n   * - HTMLElement: Focus this specific element\n   */\n  initialFocus?: 'first' | 'container' | 'none' | string | HTMLElement;\n  /**\n   * Explicit element to restore focus to when the trap deactivates.\n   * Overrides the automatic trigger capture (_lastInteractedElement / document.activeElement).\n   * Use when the opener is known at call-site (e.g. a ref on the toggle button).\n   */\n  returnFocusRef?: React.RefObject<HTMLElement | null>;\n  /**\n   * Additional container refs that are logically part of this focus trap\n   * (e.g., portal-rendered content from Popover/Dropdown). Focus moving to\n   * these containers will NOT trigger the safety net redirect.\n   */\n  portalContainerRefs?: MutableRefObject<RefObject<HTMLElement | null>[]>;\n}\n\nexport interface UseFocusTrapReturn {\n  /**\n   * Ref to the element that had focus before trap activated.\n   * Useful for manual focus restoration if needed.\n   */\n  triggerRef: React.MutableRefObject<HTMLElement | null>;\n}\n\n// Module-level trigger tracking: React's commit phase is bottom-up, so by the\n// time useFocusTrap's useLayoutEffect runs, document.activeElement may already\n// be the autoFocus element inside the modal rather than the opener button.\n// We capture the last interacted element via pointerdown/keydown listeners\n// (which fire before any React state update commits) to work around this.\nlet _lastInteractedElement: HTMLElement | null = null;\n\nfunction _onPointerDown(e: PointerEvent): void {\n  // Walk composedPath to find the nearest focusable element being pressed.\n  const path = e.composedPath();\n  for (const node of path) {\n    if (node instanceof HTMLElement && node.tabIndex >= 0) {\n      _lastInteractedElement = node;\n      return;\n    }\n  }\n}\n\nfunction _onKeyDown(e: KeyboardEvent): void {\n  // Enter/Space on a focused button will synthesise a click — capture before that.\n  if (e.key === 'Enter' || e.key === ' ') {\n    _lastInteractedElement = document.activeElement as HTMLElement;\n  }\n}\n\nif (typeof document !== 'undefined') {\n  document.addEventListener('pointerdown', _onPointerDown, true);\n  document.addEventListener('keydown', _onKeyDown, true);\n}\n\n/**\n * Returns (and clears) the last element interacted with before a React commit.\n * Used by SidebarOverlay complementary mode to seed its trigger ref without\n * relying on document.activeElement timing.\n */\nexport function consumeLastInteractedElement(): HTMLElement | null {\n  const el = _lastInteractedElement;\n  _lastInteractedElement = null;\n  return el;\n}\n\n// Focus anchor — explicit stable return-focus target, higher priority than\n// _lastInteractedElement. Auto-clears via setTimeout(0) to prevent a stale\n// anchor leaking to an unrelated open.\nlet _focusAnchor: HTMLElement | null = null;\nlet _focusAnchorClearFrame: ReturnType<typeof requestAnimationFrame> | null = null;\n\n/**\n * Sets an explicit focus-return anchor element.\n * Call this before dispatching an action that will open a modal or sidebar,\n * when the natural last-interacted element is not the right return target\n * (e.g. a popover menu item that will be unmounted when the popover closes).\n */\nexport function setFocusAnchor(el: HTMLElement | null): void {\n  if (_focusAnchorClearFrame !== null) cancelAnimationFrame(_focusAnchorClearFrame);\n  _focusAnchor = el;\n  // Auto-clear if not consumed — prevents stale anchor leaking to unrelated opens.\n  // rAF fires after React has committed and painted, giving useFocusTrap time to\n  // consume the anchor before it is discarded.\n  _focusAnchorClearFrame = requestAnimationFrame(() => {\n    _focusAnchor = null;\n    _focusAnchorClearFrame = null;\n  });\n}\n\n/**\n * Returns (and clears) the focus anchor if one was set, otherwise null.\n * Used internally by useFocusTrap and SidebarOverlay.\n */\nexport function consumeFocusAnchor(): HTMLElement | null {\n  if (_focusAnchorClearFrame !== null) {\n    cancelAnimationFrame(_focusAnchorClearFrame);\n    _focusAnchorClearFrame = null;\n  }\n  const el = _focusAnchor;\n  _focusAnchor = null;\n  return el;\n}\n\n/**\n * Resolve the initial focus target based on the initialFocus option.\n */\nfunction resolveInitialFocusTarget(\n  container: HTMLElement,\n  initialFocus: 'first' | 'container' | 'none' | string | HTMLElement\n): HTMLElement | null {\n  if (initialFocus === 'none') return null;\n  if (initialFocus === 'first') {\n    return getFirstFocusableElement({ container }) || container;\n  }\n  if (initialFocus === 'container') {\n    return container;\n  }\n  if (typeof initialFocus === 'string') {\n    return container.querySelector<HTMLElement>(initialFocus);\n  }\n  if (initialFocus instanceof HTMLElement) {\n    return initialFocus;\n  }\n  return null;\n}\n\n/**\n * Hook to trap focus within a container (for modals, dialogs, drawers).\n *\n * Implements WCAG 2.1 focus trap pattern:\n * - Moves focus into container on activation\n * - Wraps Tab/Shift+Tab navigation within container\n * - Restores focus to trigger element on deactivation\n * - Safety net: catches focus escaping via other means\n * - Handles autoFocus content: captures trigger before autoFocus fires\n * - Handles {isOpen && <Modal>} pattern: restores focus on unmount\n *\n * Note: For Escape key handling, use `useDismissOnEscape` hook separately.\n * This keeps focus trap (accessibility) separate from Escape handling (UX).\n *\n * @example\n * ```tsx\n * const MyModal = ({ isOpen, onClose }) => {\n *   const containerRef = useRef<HTMLDivElement>(null);\n *\n *   // Escape handling (UX)\n *   useDismissOnEscape({\n *     containerRef,\n *     onDismiss: onClose,\n *     enabled: isOpen\n *   });\n *\n *   // Focus trap (accessibility)\n *   const { triggerRef } = useFocusTrap({\n *     enabled: isOpen,\n *     containerRef,\n *     restoreFocus: true\n *   });\n *\n *   return (\n *     <div ref={containerRef}>\n *       <button>First</button>\n *       <button>Second</button>\n *     </div>\n *   );\n * };\n * ```\n */\nexport function useFocusTrap<T extends HTMLElement = HTMLElement>({\n  enabled,\n  containerRef,\n  restoreFocus = true,\n  initialFocus = 'first',\n  returnFocusRef,\n  portalContainerRefs,\n}: UseFocusTrapOptions<T>): UseFocusTrapReturn {\n  const triggerRef = useRef<HTMLElement | null>(null);\n  const lastFocusedInContainer = useRef<HTMLElement | null>(null);\n\n  // Focus management: save trigger, move focus into container on activate, restore on deactivate\n  useLayoutEffect(() => {\n    if (!enabled) {\n      // Restore focus to trigger when trap deactivates\n      if (restoreFocus && triggerRef.current) {\n        const el = triggerRef.current;\n        triggerRef.current = null;\n        requestAnimationFrame(() => {\n          if (el.isConnected) el.focus();\n        });\n      }\n      return;\n    }\n\n    const container = containerRef.current;\n    if (!container) return;\n\n    // Resolve trigger: explicit returnFocusRef wins, then focusAnchor (explicitly set\n    // by caller for two-step flows like popover menu → modal), then the pre-commit\n    // interaction record, then document.activeElement as final fallback.\n    const previousActiveElement = returnFocusRef?.current ?? consumeFocusAnchor() ?? _lastInteractedElement ?? (document.activeElement as HTMLElement);\n    _lastInteractedElement = null;\n\n    // iframes manage their own internal focus. document.activeElement only ever\n    // resolves to the <iframe> element from the parent doc — calling .focus()\n    // on any parent-doc element forcibly blurs the iframe content (kills caret\n    // in textareas, cancels native <select> dropdowns). Skip capture so the\n    // auto-focus on open and focus-restore on close short-circuit on null trigger.\n    if (previousActiveElement?.tagName === 'IFRAME') {\n      triggerRef.current = null;\n      return;\n    }\n\n    triggerRef.current = previousActiveElement;\n\n    // Only move initial focus if autoFocus hasn't already placed it inside the container.\n    if (!container.contains(document.activeElement)) {\n      requestAnimationFrame(() => {\n        resolveInitialFocusTarget(container, initialFocus)?.focus();\n      });\n    }\n\n    // Restore focus on unmount while enabled (covers {isOpen && <Modal>} pattern\n    // where the component unmounts before enabled can transition true → false)\n    return () => {\n      if (restoreFocus && triggerRef.current) {\n        const el = triggerRef.current;\n        triggerRef.current = null;\n        requestAnimationFrame(() => {\n          if (el.isConnected) el.focus();\n        });\n      }\n    };\n  }, [enabled, containerRef, restoreFocus, initialFocus]);\n\n  // Focus trap: Tab wrapping (only when enabled)\n  useLayoutEffect(() => {\n    if (!enabled) return;\n\n    const container = containerRef.current;\n    if (!container) return;\n\n    const handleKeyDown = (e: KeyboardEvent) => {\n      // Tab wrapping\n      if (e.key === 'Tab') {\n        const focusables = getFocusableElements({ container });\n\n        if (focusables.length === 0) {\n          e.preventDefault();\n          container.focus();\n          return;\n        }\n\n        const first = focusables[0];\n        const last = focusables[focusables.length - 1];\n        const activeElement = document.activeElement;\n\n        if (e.shiftKey && activeElement === first) {\n          e.preventDefault();\n          last.focus();\n        } else if (!e.shiftKey && activeElement === last) {\n          e.preventDefault();\n          first.focus();\n        }\n      }\n    };\n\n    document.addEventListener('keydown', handleKeyDown, true);\n    return () => document.removeEventListener('keydown', handleKeyDown, true);\n  }, [enabled, containerRef]);\n\n  // Focus trap safety net: catch focus escaping\n  useLayoutEffect(() => {\n    if (!enabled) return;\n\n    const container = containerRef.current;\n    if (!container) return;\n\n    const handleFocusIn = (e: FocusEvent) => {\n      const target = e.target as Node;\n\n      // iframe focus is opaque from the parent doc — leave it alone, otherwise\n      // a click into the iframe gets yanked back into the trap.\n      if ((target as Element | null)?.tagName === 'IFRAME') return;\n\n      if (container.contains(target)) {\n        lastFocusedInContainer.current = target as HTMLElement;\n      } else if (portalContainerRefs?.current?.some(ref => ref.current?.contains(target))) {\n        // Focus is in a registered portal — allow it, but don't update\n        // lastFocusedInContainer so safety net restores to the last main-container\n        // element (e.g., the dropdown trigger) when the portal unmounts\n      } else {\n        // Focus escaped — redirect back\n        const fallback = lastFocusedInContainer.current\n          || getFirstFocusableElement({ container })\n          || container;\n        fallback.focus();\n      }\n    };\n\n    document.addEventListener('focusin', handleFocusIn, true);\n    return () => document.removeEventListener('focusin', handleFocusIn, true);\n  }, [enabled, containerRef]);\n\n  return { triggerRef };\n}\n"],"names":["_lastInteractedElement","_onPointerDown","e","path","composedPath","node","HTMLElement","tabIndex","_onKeyDown","key","document","activeElement","addEventListener","consumeLastInteractedElement","el","_focusAnchor","_focusAnchorClearFrame","setFocusAnchor","cancelAnimationFrame","requestAnimationFrame","consumeFocusAnchor","resolveInitialFocusTarget","container","initialFocus","getFirstFocusableElement","querySelector","useFocusTrap","enabled","containerRef","restoreFocus","returnFocusRef","portalContainerRefs","triggerRef","useRef","lastFocusedInContainer","useLayoutEffect","current","isConnected","focus","previousActiveElement","tagName","contains","handleKeyDown","focusables","getFocusableElements","length","preventDefault","first","last","shiftKey","removeEventListener","handleFocusIn","target","some","ref"],"mappings":"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"}

package/dist/index77.js

@@ -1,27 +1,65 @@
-import * as e from "react";
-function p({
-  disabled: t = !1,
-  onFocusIn: u,
-  onFocusOut: n,
-  onEscape: a,
-  closeOnEscape: c = !0
+import { useCallback as c } from "react";
+import { useRovingFocus as d } from "./index74.js";
+const s = (r, t) => `tab${t ? `-${t}` : ""}-${r}`, l = (r, t) => `panel${t ? `-${t}` : ""}-${r}`, C = (r, t) => ({
+  id: l(r, t),
+  role: "tabpanel",
+  "aria-labelledby": s(r, t)
+});
+function R({
+  itemIds: r,
+  orientation: t = "horizontal",
+  activeItem: n,
+  idBase: e = "",
+  includePanelLinks: a = !0,
+  externalPanelId: u
 }) {
-  const f = e.useCallback((r) => {
-    t || u?.();
-  }, [t, u]), s = e.useCallback((r) => {
-    if (t) return;
-    const o = r.relatedTarget;
-    o && r.currentTarget.contains(o) || n?.();
-  }, [t, n]), C = e.useCallback((r) => {
-    t || !c || r.key !== "Escape" || (r.preventDefault(), a?.());
-  }, [t, c, a]);
+  const {
+    setFocusedId: f,
+    handleKeyDown: p,
+    getRovingItemProps: b,
+    getContainerProps: g
+  } = d({
+    itemIds: r,
+    defaultFocusedId: n,
+    orientation: t,
+    loop: !0,
+    role: "tablist"
+  }), P = c((o) => {
+    const {
+      ref: $,
+      tabIndex: x,
+      onFocus: F
+    } = b(o), y = n === o;
+    return {
+      ref: $,
+      tabIndex: x,
+      onFocus: F,
+      id: s(o, e),
+      ...a && {
+        "aria-controls": u ?? l(o, e)
+      },
+      "aria-selected": y,
+      role: "tab"
+    };
+  }, [n, b, e, a, u]), T = c((o) => ({
+    id: l(o, e),
+    role: "tabpanel",
+    "aria-labelledby": s(o, e)
+  }), [e]);
   return {
-    onFocusCapture: f,
-    onBlurCapture: s,
-    onKeyDownCapture: C
+    getTabProps: P,
+    getPanelProps: T,
+    getTabListProps: g,
+    setFocusedTabId: f,
+    handleKeyDown: p,
+    getPanelId: (o) => l(o, e),
+    getTabId: (o) => s(o, e)
   };
 }
 export {
-  p as useDismissOnFocusOut
+  l as getPanelId,
+  s as getTabId,
+  C as getTabPanelProps,
+  R as useTabsA11y
 };
 //# sourceMappingURL=index77.js.map

package/dist/index77.js.map

@@ -1 +1 @@
-{"version":3,"file":"index77.js","sources":["../src/utils/a11y/useDismissOnFocusOut.ts"],"sourcesContent":["import * as React from 'react';\n\nexport type UseDismissOnFocusOutOptions = {\n  /**\n   * Disable all handlers (no-ops). Useful when a component provides alternate\n   * focus/keyboard behavior (e.g., disabled-trigger tooltip wrapper).\n   */\n  disabled?: boolean;\n  /**\n   * Called when focus enters anywhere within the target.\n   */\n  onFocusIn?: () => void;\n  /**\n   * Called when focus leaves the target (i.e., focus moves to an element\n   * outside the currentTarget).\n   */\n  onFocusOut?: () => void;\n  /**\n   * Called when Escape is pressed while focus is within the target.\n   */\n  onEscape?: () => void;\n  /**\n   * Whether Escape should trigger dismissal. Default: true.\n   */\n  closeOnEscape?: boolean;\n};\n\nexport type UseDismissOnFocusOutReturn<T extends HTMLElement = HTMLElement> = {\n  onFocusCapture: (e: React.FocusEvent<T>) => void;\n  onBlurCapture: (e: React.FocusEvent<T>) => void;\n  onKeyDownCapture: (e: React.KeyboardEvent<T>) => void;\n};\n\n/**\n * Returns capture-phase handlers to \"show on focus within\" and \"dismiss on focus out\",\n * with optional Escape-to-dismiss.\n *\n * Intended for non-interactive surfaces like tooltips where content should remain\n * visible while focus stays within the wrapper.\n */\nexport function useDismissOnFocusOut<T extends HTMLElement = HTMLElement>({\n  disabled = false,\n  onFocusIn,\n  onFocusOut,\n  onEscape,\n  closeOnEscape = true\n}: UseDismissOnFocusOutOptions): UseDismissOnFocusOutReturn<T> {\n  const onFocusCapture = React.useCallback(\n    (_e: React.FocusEvent<T>) => {\n      if (disabled) return;\n      onFocusIn?.();\n    },\n    [disabled, onFocusIn]\n  );\n\n  const onBlurCapture = React.useCallback(\n    (e: React.FocusEvent<T>) => {\n      if (disabled) return;\n\n      const nextFocused = e.relatedTarget as Node | null;\n      if (nextFocused && e.currentTarget.contains(nextFocused)) return;\n\n      onFocusOut?.();\n    },\n    [disabled, onFocusOut]\n  );\n\n  const onKeyDownCapture = React.useCallback(\n    (e: React.KeyboardEvent<T>) => {\n      if (disabled || !closeOnEscape || e.key !== 'Escape') return;\n\n      e.preventDefault();\n      onEscape?.();\n    },\n    [disabled, closeOnEscape, onEscape]\n  );\n\n  return { onFocusCapture, onBlurCapture, onKeyDownCapture };\n}\n\n"],"names":["React","useDismissOnFocusOut","disabled","onFocusIn","onFocusOut","onEscape","closeOnEscape","onFocusCapture","useCallback","_e","onBlurCapture","e","nextFocused","relatedTarget","currentTarget","contains","onKeyDownCapture","key","preventDefault"],"mappings":"AAwCO,YAAAA,OAAA;AAAA,SAASC,EAA0D;AAAA,EACxEC,UAAAA,IAAW;AAAA,EACXC,WAAAA;AAAAA,EACAC,YAAAA;AAAAA,EACAC,UAAAA;AAAAA,EACAC,eAAAA,IAAgB;AACW,GAAkC;AAC7D,QAAMC,IAAiBP,EAAMQ,YAC3B,CAACC,MAA4B;AAC3B,IAAIP,KACJC,IAAAA;AAAAA,EACF,GACA,CAACD,GAAUC,CAAS,CACtB,GAEMO,IAAgBV,EAAMQ,YAC1B,CAACG,MAA2B;AAC1B,QAAIT,EAAU;AAEd,UAAMU,IAAcD,EAAEE;AACtB,IAAID,KAAeD,EAAEG,cAAcC,SAASH,CAAW,KAEvDR,IAAAA;AAAAA,EACF,GACA,CAACF,GAAUE,CAAU,CACvB,GAEMY,IAAmBhB,EAAMQ,YAC7B,CAACG,MAA8B;AAC7B,IAAIT,KAAY,CAACI,KAAiBK,EAAEM,QAAQ,aAE5CN,EAAEO,eAAAA,GACFb,IAAAA;AAAAA,EACF,GACA,CAACH,GAAUI,GAAeD,CAAQ,CACpC;AAEA,SAAO;AAAA,IAAEE,gBAAAA;AAAAA,IAAgBG,eAAAA;AAAAA,IAAeM,kBAAAA;AAAAA,EAAAA;AAC1C;"}
+{"version":3,"file":"index77.js","sources":["../src/utils/a11y/useTabsA11y.ts"],"sourcesContent":["import { useCallback } from 'react';\nimport { useRovingFocus } from './useRovingFocus';\n\nexport const getTabId = (itemId: string, idBase: string) => {\n  const suffix = idBase ? `-${idBase}` : '';\n  return `tab${suffix}-${itemId}`;\n};\n\nexport const getPanelId = (itemId: string, idBase: string) => {\n  const suffix = idBase ? `-${idBase}` : '';\n  return `panel${suffix}-${itemId}`;\n};\n\nexport const getTabPanelProps = (tabId: string, idBase: string) => ({\n  id: getPanelId(tabId, idBase),\n  role: 'tabpanel' as const,\n  'aria-labelledby': getTabId(tabId, idBase)\n});\n\ninterface UseTabsA11yProps {\n  itemIds: string[];\n  orientation?: 'horizontal' | 'vertical';\n  activeItem: string;\n  idBase?: string;\n  includePanelLinks?: boolean; // Set to false when consumer manages their own panels externally\n  externalPanelId?: string; // When set, all tabs point aria-controls to this single external panel id\n}\n\ninterface TabA11yProps {\n  ref: (el: HTMLElement | null) => void;\n  tabIndex: number;\n  onFocus: () => void;\n  id: string;\n  'aria-controls'?: string;\n  'aria-selected': boolean;\n  role: 'tab';\n}\n\ninterface PanelA11yProps {\n  id: string;\n  role: 'tabpanel';\n  'aria-labelledby': string;\n}\n\n/**\n * Hook for managing Tabs (NavigationBar) focus and ARIA props.\n * Handles roving tabindex pattern and generates tab-specific ARIA attributes.\n * \n * @example\n * const itemIds = useMemo(() => navigationItems.map(item => item.id), [navigationItems]);\n * const { getTabProps, setFocusedTabId, handleKeyDown } = useTabsA11y({\n *   itemIds,\n *   activeNavigationItem: 'tab-1',\n *   orientation: 'horizontal',\n *   idBase: 'settings'\n * });\n */\nexport function useTabsA11y({\n  itemIds,\n  orientation = 'horizontal',\n  activeItem,\n  idBase = '',\n  includePanelLinks = true,\n  externalPanelId\n}: UseTabsA11yProps) {\n  const {\n    setFocusedId: setFocusedTabId,\n    handleKeyDown,\n    getRovingItemProps,\n    getContainerProps\n  } = useRovingFocus({\n    itemIds,\n    defaultFocusedId: activeItem,\n    orientation,\n    loop: true,\n    role: 'tablist'\n  });\n\n  /**\n   * Get all props needed for a tab button.\n   * Combines roving focus props (ref, tabIndex) with tab-specific ARIA attributes.\n   */\n  const getTabProps = useCallback((itemId: string): TabA11yProps => {\n    const { ref, tabIndex, onFocus } = getRovingItemProps(itemId);\n    const isSelected = activeItem === itemId;\n\n    return {\n      ref,\n      tabIndex,\n      onFocus,\n      id: getTabId(itemId, idBase),\n      ...(includePanelLinks && { 'aria-controls': externalPanelId ?? getPanelId(itemId, idBase) }),\n      'aria-selected': isSelected,\n      role: 'tab'\n    };\n  }, [activeItem, getRovingItemProps, idBase, includePanelLinks, externalPanelId]);\n\n  /**\n   * Get all props needed for a tab panel.\n   * Provides ARIA attributes to associate the panel with its tab.\n   */\n  const getPanelProps = useCallback((itemId: string): PanelA11yProps => {\n    return {\n      id: getPanelId(itemId, idBase),\n      role: 'tabpanel',\n      'aria-labelledby': getTabId(itemId, idBase)\n    };\n  }, [idBase]);\n\n  return {\n    getTabProps,\n    getPanelProps,\n    getTabListProps: getContainerProps,\n    setFocusedTabId,\n    handleKeyDown,\n    getPanelId: (itemId: string) => getPanelId(itemId, idBase),\n    getTabId: (itemId: string) => getTabId(itemId, idBase)\n  };\n}\n\n"],"names":["useCallback","useRovingFocus","getTabId","itemId","idBase","getPanelId","getTabPanelProps","tabId","id","role","useTabsA11y","itemIds","orientation","activeItem","includePanelLinks","externalPanelId","setFocusedId","setFocusedTabId","handleKeyDown","getRovingItemProps","getContainerProps","defaultFocusedId","loop","getTabProps","ref","tabIndex","onFocus","isSelected","getPanelProps","getTabListProps"],"mappings":"AAGO,SAAA,eAAAA,SAAA;AAAA,SAAA,kBAAAC,SAAA;AAAA,MAAMC,IAAWA,CAACC,GAAgBC,MAEhC,MADQA,IAAS,IAAIA,CAAM,KAAK,EACpB,IAAID,CAAM,IAGlBE,IAAaA,CAACF,GAAgBC,MAElC,QADQA,IAAS,IAAIA,CAAM,KAAK,EAClB,IAAID,CAAM,IAGpBG,IAAmBA,CAACC,GAAeH,OAAoB;AAAA,EAClEI,IAAIH,EAAWE,GAAOH,CAAM;AAAA,EAC5BK,MAAM;AAAA,EACN,mBAAmBP,EAASK,GAAOH,CAAM;AAC3C;AAwCO,SAASM,EAAY;AAAA,EAC1BC,SAAAA;AAAAA,EACAC,aAAAA,IAAc;AAAA,EACdC,YAAAA;AAAAA,EACAT,QAAAA,IAAS;AAAA,EACTU,mBAAAA,IAAoB;AAAA,EACpBC,iBAAAA;AACgB,GAAG;AACnB,QAAM;AAAA,IACJC,cAAcC;AAAAA,IACdC,eAAAA;AAAAA,IACAC,oBAAAA;AAAAA,IACAC,mBAAAA;AAAAA,EAAAA,IACEnB,EAAe;AAAA,IACjBU,SAAAA;AAAAA,IACAU,kBAAkBR;AAAAA,IAClBD,aAAAA;AAAAA,IACAU,MAAM;AAAA,IACNb,MAAM;AAAA,EAAA,CACP,GAMKc,IAAcvB,EAAY,CAACG,MAAiC;AAChE,UAAM;AAAA,MAAEqB,KAAAA;AAAAA,MAAKC,UAAAA;AAAAA,MAAUC,SAAAA;AAAAA,IAAAA,IAAYP,EAAmBhB,CAAM,GACtDwB,IAAad,MAAeV;AAElC,WAAO;AAAA,MACLqB,KAAAA;AAAAA,MACAC,UAAAA;AAAAA,MACAC,SAAAA;AAAAA,MACAlB,IAAIN,EAASC,GAAQC,CAAM;AAAA,MAC3B,GAAIU,KAAqB;AAAA,QAAE,iBAAiBC,KAAmBV,EAAWF,GAAQC,CAAM;AAAA,MAAA;AAAA,MACxF,iBAAiBuB;AAAAA,MACjBlB,MAAM;AAAA,IAAA;AAAA,EAEV,GAAG,CAACI,GAAYM,GAAoBf,GAAQU,GAAmBC,CAAe,CAAC,GAMzEa,IAAgB5B,EAAY,CAACG,OAC1B;AAAA,IACLK,IAAIH,EAAWF,GAAQC,CAAM;AAAA,IAC7BK,MAAM;AAAA,IACN,mBAAmBP,EAASC,GAAQC,CAAM;AAAA,EAAA,IAE3C,CAACA,CAAM,CAAC;AAEX,SAAO;AAAA,IACLmB,aAAAA;AAAAA,IACAK,eAAAA;AAAAA,IACAC,iBAAiBT;AAAAA,IACjBH,iBAAAA;AAAAA,IACAC,eAAAA;AAAAA,IACAb,YAAYA,CAACF,MAAmBE,EAAWF,GAAQC,CAAM;AAAA,IACzDF,UAAUA,CAACC,MAAmBD,EAASC,GAAQC,CAAM;AAAA,EAAA;AAEzD;"}

package/dist/index78.js

@@ -1,12 +1,24 @@
-function f({
-  ariaLabel: e,
-  ariaLabelledBy: i,
-  ariaDescribedBy: r
+import { useEffect as u } from "react";
+import { getFirstFocusableElement as f } from "./index75.js";
+function s({
+  focusRef: r,
+  containerRef: t,
+  isReady: e,
+  shouldFocus: n
 }) {
-  const t = {};
-  return i ? t["aria-labelledby"] = i : e && (t["aria-label"] = e), r && (t["aria-describedby"] = r), t;
+  u(() => {
+    if (e && !(n && !n())) {
+      if (r?.current) {
+        r.current.focus();
+        return;
+      }
+      t?.current && f({
+        container: t.current
+      })?.focus();
+    }
+  }, [e]);
 }
 export {
-  f as getA11yNameAttributes
+  s as useFocusOnReady
 };
 //# sourceMappingURL=index78.js.map

package/dist/index78.js.map

@@ -1 +1 @@
-{"version":3,"file":"index78.js","sources":["../src/utils/a11y/accessibleName.ts"],"sourcesContent":["/**\n * Accessible name/description utilities following WCAG precedence rules.\n * \n * **When to use:**\n * - `ariaLabelledBy`: visible label exists (preferred - keeps SR and visual text in sync)\n * - `ariaLabel`: no visible label (e.g., icon-only buttons)\n * - `ariaDescribedBy`: additional context needed (warnings, hints, constraints)\n * \n * **Precedence:** ariaLabelledBy > ariaLabel > visible text content\n * \n * @example Icon-only button\n * ```tsx\n * <Button iconProps={{ name: 'close' }} ariaLabel=\"Close dialog\" />\n * ```\n * \n * @example Disambiguate generic labels\n * ```tsx\n * <Button label=\"Edit\" ariaLabel=\"Edit name\" />\n * <Button label=\"Edit\" ariaLabel=\"Edit email\" />\n * ```\n */\n\nexport type AccessibleNameInput = {\n  /** Accessible name when no visible label exists (icon-only buttons). */\n  ariaLabel?: string;\n  /** ID(s) of visible element(s) that label this control. Preferred over ariaLabel. */\n  ariaLabelledBy?: string;\n  /** ID(s) of element(s) providing additional description (additive). */\n  ariaDescribedBy?: string;\n};\n\n/**\n * Returns ARIA attributes with correct precedence.\n * Prefer ariaLabelledBy > ariaLabel. ariaDescribedBy is always additive.\n */\nexport function getA11yNameAttributes({\n  ariaLabel,\n  ariaLabelledBy,\n  ariaDescribedBy\n}: AccessibleNameInput): Record<string, string> {\n  const props: Record<string, string> = {};\n\n  if (ariaLabelledBy) props['aria-labelledby'] = ariaLabelledBy;\n  else if (ariaLabel) props['aria-label'] = ariaLabel;\n\n  if (ariaDescribedBy) props['aria-describedby'] = ariaDescribedBy;\n\n  return props;\n}\n"],"names":["getA11yNameAttributes","ariaLabel","ariaLabelledBy","ariaDescribedBy","props"],"mappings":"AAmCO,SAASA,EAAsB;AAAA,EACpCC,WAAAA;AAAAA,EACAC,gBAAAA;AAAAA,EACAC,iBAAAA;AACmB,GAA2B;AAC9C,QAAMC,IAAgC,CAAA;AAEtC,SAAIF,IAAgBE,EAAM,iBAAiB,IAAIF,IACtCD,MAAWG,EAAM,YAAY,IAAIH,IAEtCE,MAAiBC,EAAM,kBAAkB,IAAID,IAE1CC;AACT;"}
+{"version":3,"file":"index78.js","sources":["../src/utils/a11y/useFocusOnReady.ts"],"sourcesContent":["import { useEffect } from 'react';\nimport type { RefObject } from 'react';\nimport { getFirstFocusableElement } from './focusableElements';\n\nexport interface UseFocusOnReadyOptions {\n  /**\n   * Specific element to focus. Takes priority over containerRef.\n   */\n  focusRef?: RefObject<HTMLElement | null>;\n  /**\n   * Container to search for first focusable element.\n   * Used as fallback when focusRef is not provided or its current is null.\n   */\n  containerRef?: RefObject<HTMLElement | null>;\n  /**\n   * When this transitions to true, focus is triggered.\n   */\n  isReady: boolean;\n  /**\n   * Optional guard for async content — evaluated at the moment isReady becomes true.\n   * Return false to skip focusing (e.g. if the user has tabbed away while content was loading).\n   * Not needed for synchronous open/close like modals or dropdowns where focus is immediate.\n   */\n  shouldFocus?: () => boolean;\n}\n\n/**\n * Moves focus to an element when an async condition becomes ready.\n *\n * When `focusRef` is provided, focuses that element directly.\n * When only `containerRef` is provided, finds and focuses the first focusable child.\n * When both are provided, `focusRef` takes priority; `containerRef` is the fallback.\n *\n * @example Focus first focusable in container after loading\n * ```tsx\n * useFocusOnReady({\n *   containerRef: panelRef,\n *   isReady: !isLoading,\n *   shouldFocus: () => document.activeElement === panelRef.current\n * });\n * ```\n *\n * @example Focus a specific element when modal opens\n * ```tsx\n * useFocusOnReady({\n *   focusRef: closeButtonRef,\n *   isReady: isOpen\n * });\n * ```\n *\n * @example Specific element with container fallback\n * ```tsx\n * useFocusOnReady({\n *   focusRef: preferredRef,\n *   containerRef: dialogRef,\n *   isReady: isOpen\n * });\n * ```\n */\nexport function useFocusOnReady({\n  focusRef,\n  containerRef,\n  isReady,\n  shouldFocus\n}: UseFocusOnReadyOptions): void {\n  useEffect(() => {\n    if (!isReady) return;\n    if (shouldFocus && !shouldFocus()) return;\n\n    if (focusRef?.current) {\n      focusRef.current.focus();\n      return;\n    }\n\n    if (containerRef?.current) {\n      const first = getFirstFocusableElement({ container: containerRef.current });\n      first?.focus();\n    }\n  }, [isReady]);\n}\n"],"names":["useEffect","getFirstFocusableElement","useFocusOnReady","focusRef","containerRef","isReady","shouldFocus","current","focus","container"],"mappings":"AA2DO,SAAA,aAAAA,SAAA;AAAA,SAAA,4BAAAC,SAAA;AAAA,SAASC,EAAgB;AAAA,EAC9BC,UAAAA;AAAAA,EACAC,cAAAA;AAAAA,EACAC,SAAAA;AAAAA,EACAC,aAAAA;AACsB,GAAS;AAC/BN,EAAAA,EAAU,MAAM;AACd,QAAKK,KACDC,EAAAA,KAAe,CAACA,MAEpB;AAAA,UAAIH,GAAUI,SAAS;AACrBJ,QAAAA,EAASI,QAAQC,MAAAA;AACjB;AAAA,MACF;AAEA,MAAIJ,GAAcG,WACFN,EAAyB;AAAA,QAAEQ,WAAWL,EAAaG;AAAAA,MAAAA,CAAS,GACnEC,MAAAA;AAAAA;AAAAA,EAEX,GAAG,CAACH,CAAO,CAAC;AACd;"}

package/dist/index79.js

@@ -1,26 +1,8 @@
-import { useEffect as d } from "react";
-function p({
-  containerRef: r,
-  onDismiss: e,
-  enabled: n = !0,
-  preventDefault: u = !0,
-  stopPropagation: c = !0
-}) {
-  d(() => {
-    if (!n || !e) return;
-    const o = r.current;
-    if (!o) return;
-    const a = (t) => {
-      t.key === "Escape" && o.contains(document.activeElement) && (u && t.preventDefault(), c && t.stopPropagation(), e());
-    };
-    return document.addEventListener("keydown", a, {
-      capture: !0
-    }), () => document.removeEventListener("keydown", a, {
-      capture: !0
-    });
-  }, [n, e, r, u, c]);
-}
+const t = () => typeof navigator < "u" && /Android/i.test(navigator.userAgent), o = (i) => {
+  const r = "pointerType" in i ? i.pointerType : void 0;
+  return r === "" && i.isTrusted ? !0 : t() && r ? i.type === "click" && i.buttons === 1 : i.detail === 0 && !r;
+};
 export {
-  p as useDismissOnEscape
+  o as isVirtualClick
 };
 //# sourceMappingURL=index79.js.map

package/dist/index79.js.map

@@ -1 +1 @@
-{"version":3,"file":"index79.js","sources":["../src/utils/a11y/useDismissOnEscape.ts"],"sourcesContent":["import { useEffect } from 'react';\nimport type { RefObject } from 'react';\n\nexport interface UseDismissOnEscapeOptions<T extends HTMLElement = HTMLElement> {\n  /**\n   * Container element ref to check if focus is within.\n   * Escape will only trigger if focus is within this container.\n   */\n  containerRef: RefObject<T | null>;\n  /**\n   * Callback when Escape key is pressed and focus is within container.\n   */\n  onDismiss?: () => void;\n  /**\n   * Whether the Escape handler is active.\n   * Default: true\n   */\n  enabled?: boolean;\n  /**\n   * Whether to call preventDefault() when handling Escape.\n   * Default: true\n   */\n  preventDefault?: boolean;\n  /**\n   * Whether to call stopPropagation() when handling Escape.\n   * Default: true\n   */\n  stopPropagation?: boolean;\n}\n\n/**\n * Hook to handle Escape key dismissal when focus is within a container.\n *\n * This is a UX pattern: if user is interacting with an overlay/sidebar\n * (indicated by focus being within it), Escape should close it.\n *\n * @example\n * ```tsx\n * const MySidebar = ({ isOpen, onClose }) => {\n *   const containerRef = useRef<HTMLDivElement>(null);\n *\n *   useDismissOnEscape({\n *     containerRef,\n *     onDismiss: onClose,\n *     enabled: isOpen\n *   });\n *\n *   return <div ref={containerRef}>...</div>;\n * };\n * ```\n */\nexport function useDismissOnEscape<T extends HTMLElement = HTMLElement>({\n  containerRef,\n  onDismiss,\n  enabled = true,\n  preventDefault = true,\n  stopPropagation = true\n}: UseDismissOnEscapeOptions<T>): void {\n  useEffect(() => {\n    if (!enabled || !onDismiss) return;\n\n    const container = containerRef.current;\n    if (!container) return;\n\n    const handleEscape = (e: KeyboardEvent) => {\n      if (e.key === 'Escape' && container.contains(document.activeElement)) {\n        preventDefault && e.preventDefault();\n        stopPropagation && e.stopPropagation();\n        onDismiss();\n      }\n    };\n\n    document.addEventListener('keydown', handleEscape, { capture: true });\n    return () => document.removeEventListener('keydown', handleEscape, { capture: true });\n  }, [enabled, onDismiss, containerRef, preventDefault, stopPropagation]);\n}\n"],"names":["useEffect","useDismissOnEscape","containerRef","onDismiss","enabled","preventDefault","stopPropagation","container","current","handleEscape","e","key","contains","document","activeElement","addEventListener","capture","removeEventListener"],"mappings":"AAmDO,SAAA,aAAAA,SAAA;AAAA,SAASC,EAAwD;AAAA,EACtEC,cAAAA;AAAAA,EACAC,WAAAA;AAAAA,EACAC,SAAAA,IAAU;AAAA,EACVC,gBAAAA,IAAiB;AAAA,EACjBC,iBAAAA,IAAkB;AACU,GAAS;AACrCN,EAAAA,EAAU,MAAM;AACd,QAAI,CAACI,KAAW,CAACD,EAAW;AAE5B,UAAMI,IAAYL,EAAaM;AAC/B,QAAI,CAACD,EAAW;AAEhB,UAAME,IAAeA,CAACC,MAAqB;AACzC,MAAIA,EAAEC,QAAQ,YAAYJ,EAAUK,SAASC,SAASC,aAAa,MACjET,KAAkBK,EAAEL,eAAAA,GACpBC,KAAmBI,EAAEJ,gBAAAA,GACrBH,EAAAA;AAAAA,IAEJ;AAEAU,oBAASE,iBAAiB,WAAWN,GAAc;AAAA,MAAEO,SAAS;AAAA,IAAA,CAAM,GAC7D,MAAMH,SAASI,oBAAoB,WAAWR,GAAc;AAAA,MAAEO,SAAS;AAAA,IAAA,CAAM;AAAA,EACtF,GAAG,CAACZ,GAASD,GAAWD,GAAcG,GAAgBC,CAAe,CAAC;AACxE;"}
+{"version":3,"file":"index79.js","sources":["../src/utils/virtualClick.ts"],"sourcesContent":["/**\n * Input/virtual click detection helpers.\n */\n\nconst isAndroid = () =>\n  typeof navigator !== 'undefined' && /Android/i.test(navigator.userAgent);\n\nexport const isVirtualClick = (event: MouseEvent | PointerEvent): boolean => {\n  const pointerType = 'pointerType' in event ? event.pointerType : undefined;\n\n  // JAWS/NVDA with Firefox.\n  if (pointerType === '' && event.isTrusted) {\n    return true;\n  }\n\n  // Android TalkBack's detail value varies depending on listener type.\n  if (isAndroid() && pointerType) {\n    return event.type === 'click' && event.buttons === 1;\n  }\n\n  // Most browsers: virtual click has detail === 0 and no pointerType.\n  return event.detail === 0 && !pointerType;\n};\n\n\n"],"names":["isAndroid","navigator","test","userAgent","isVirtualClick","event","pointerType","undefined","isTrusted","type","buttons","detail"],"mappings":"AAIA,MAAMA,IAAYA,MAChB,OAAOC,YAAc,OAAe,WAAWC,KAAKD,UAAUE,SAAS,GAE5DC,IAAiBA,CAACC,MAA8C;AAC3E,QAAMC,IAAc,iBAAiBD,IAAQA,EAAMC,cAAcC;AAGjE,SAAID,MAAgB,MAAMD,EAAMG,YACvB,KAILR,EAAAA,KAAeM,IACVD,EAAMI,SAAS,WAAWJ,EAAMK,YAAY,IAI9CL,EAAMM,WAAW,KAAK,CAACL;AAChC;"}

package/dist/index80.js

@@ -1,22 +1,57 @@
-import { useEffect as s } from "react";
-const u = {
-  block: "nearest"
-};
-function m({
-  containerRef: t,
-  activeIndex: o,
-  itemSelector: r = '[role="option"]',
-  enabled: c = !0,
-  scrollOptions: e = u
+import { useState as m, useEffect as w, useCallback as b } from "react";
+import { useScrollActiveIntoView as x } from "./index247.js";
+function s({
+  items: c,
+  isOpen: t,
+  onSelect: l,
+  onClose: i,
+  onOpen: n,
+  loop: o = !0,
+  disabled: h = !1,
+  listboxRef: k,
+  optionSelector: g = '[role="option"]'
 }) {
-  s(() => {
-    if (!c || o < 0 || !t?.current)
+  const [f, r] = m(-1);
+  w(() => {
+    t || r(-1);
+  }, [t]), x({
+    containerRef: k,
+    activeIndex: f,
+    itemSelector: g,
+    enabled: t
+  });
+  const D = b((a) => {
+    if (h) {
+      a.key === "Escape" && t && (a.preventDefault(), i());
       return;
-    const n = t.current.querySelectorAll(r)[o];
-    n && n.scrollIntoView(e);
-  }, [o, t, r, c, e]);
+    }
+    const e = c.length;
+    switch (a.key) {
+      case "ArrowDown":
+        a.preventDefault(), !t && e > 0 ? (n?.(), r(0)) : t && e > 0 && r((u) => o ? (u + 1) % e : Math.min(u + 1, e - 1));
+        break;
+      case "ArrowUp":
+        a.preventDefault(), t && e > 0 && r((u) => u === -1 ? e - 1 : o ? (u - 1 + e) % e : Math.max(u - 1, 0));
+        break;
+      case "Enter":
+        a.preventDefault(), t ? f >= 0 && c[f] && (l(c[f], f), r(-1)) : (n?.(), r(0));
+        break;
+      case "Escape":
+        t && (a.preventDefault(), i(), r(-1));
+        break;
+      case "Tab":
+        t && (i(), r(-1));
+        break;
+    }
+  }, [h, c, t, f, l, i, n, o]), d = b((a, e) => `${a}-option-${e}`, []);
+  return {
+    highlightedIndex: f,
+    setHighlightedIndex: r,
+    handleKeyDown: D,
+    getOptionId: d
+  };
 }
 export {
-  m as useScrollActiveIntoView
+  s as useComboboxNavigation
 };
 //# sourceMappingURL=index80.js.map

package/dist/index80.js.map

@@ -1 +1 @@
-{"version":3,"file":"index80.js","sources":["../src/utils/a11y/useScrollActiveIntoView.ts"],"sourcesContent":["import { useEffect } from 'react';\nimport type { RefObject } from 'react';\n\nconst DEFAULT_SCROLL_OPTIONS: ScrollIntoViewOptions = { block: 'nearest' };\n\nexport interface UseScrollActiveIntoViewOptions {\n  /**\n   * Ref to the container element\n   */\n  containerRef?: RefObject<HTMLElement | null>;\n  \n  /**\n   * Index of the currently active/highlighted item (-1 if none)\n   */\n  activeIndex: number;\n  \n  /**\n   * CSS selector for item elements\n   * Default: '[role=\"option\"]'\n   */\n  itemSelector?: string;\n  \n  /**\n   * Whether scrolling is enabled\n   * Default: true\n   */\n  enabled?: boolean;\n  \n  /**\n   * ScrollIntoView options\n   * Default: { block: 'nearest' }\n   */\n  scrollOptions?: ScrollIntoViewOptions;\n}\n\n/**\n * Hook to automatically scroll the active item into view.\n * \n * Useful for aria-activedescendant patterns where DOM focus stays\n * on the container (e.g., input field) but we need to visually show\n * which descendant option is logically active.\n * \n * Common use cases:\n * - Combobox dropdown options\n * - Menu items with virtual focus\n * - Grid cells with keyboard navigation\n * - Tree view items\n * - Listbox options\n * \n * @example\n * ```tsx\n * const [highlightedIndex, setHighlightedIndex] = useState(-1);\n * const listboxRef = useRef<HTMLDivElement>(null);\n * \n * useScrollActiveIntoView({\n *   containerRef: listboxRef,\n *   activeIndex: highlightedIndex,\n *   itemSelector: '[role=\"option\"]'\n * });\n * \n * // Now when highlightedIndex changes, the item scrolls into view\n * ```\n * \n * @example Custom scroll behavior\n * ```tsx\n * useScrollActiveIntoView({\n *   containerRef: menuRef,\n *   activeIndex: activeMenuIndex,\n *   itemSelector: '[role=\"menuitem\"]',\n *   scrollOptions: { block: 'center', behavior: 'smooth' }\n * });\n * ```\n */\nexport function useScrollActiveIntoView({\n  containerRef,\n  activeIndex,\n  itemSelector = '[role=\"option\"]',\n  enabled = true,\n  scrollOptions = DEFAULT_SCROLL_OPTIONS\n}: UseScrollActiveIntoViewOptions): void {\n  useEffect(() => {\n    // Early returns for disabled states\n    if (!enabled || activeIndex < 0 || !containerRef?.current) {\n      return;\n    }\n    \n    const container = containerRef.current;\n    const items = container.querySelectorAll(itemSelector);\n    const activeItem = items[activeIndex] as HTMLElement;\n    \n    if (activeItem) {\n      activeItem.scrollIntoView(scrollOptions);\n    }\n  }, [activeIndex, containerRef, itemSelector, enabled, scrollOptions]);\n}\n"],"names":["useEffect","DEFAULT_SCROLL_OPTIONS","block","useScrollActiveIntoView","containerRef","activeIndex","itemSelector","enabled","scrollOptions","current","activeItem","querySelectorAll","scrollIntoView"],"mappings":"AAGA,SAAA,aAAAA,SAAA;AAAA,MAAMC,IAAgD;AAAA,EAAEC,OAAO;AAAU;AAsElE,SAASC,EAAwB;AAAA,EACtCC,cAAAA;AAAAA,EACAC,aAAAA;AAAAA,EACAC,cAAAA,IAAe;AAAA,EACfC,SAAAA,IAAU;AAAA,EACVC,eAAAA,IAAgBP;AACc,GAAS;AACvCD,EAAAA,EAAU,MAAM;AAEd,QAAI,CAACO,KAAWF,IAAc,KAAK,CAACD,GAAcK;AAChD;AAKF,UAAMC,IAFYN,EAAaK,QACPE,iBAAiBL,CAAY,EAC5BD,CAAW;AAEpC,IAAIK,KACFA,EAAWE,eAAeJ,CAAa;AAAA,EAE3C,GAAG,CAACH,GAAaD,GAAcE,GAAcC,GAASC,CAAa,CAAC;AACtE;"}
+{"version":3,"file":"index80.js","sources":["../src/utils/a11y/useComboboxNavigation.ts"],"sourcesContent":["import { useCallback, useState, useEffect } from 'react';\nimport type { RefObject } from 'react';\nimport { useScrollActiveIntoView } from './useScrollActiveIntoView';\n\nexport interface UseComboboxNavigationOptions<T = any> {\n  /**\n   * Array of items to navigate through\n   */\n  items: T[];\n  \n  /**\n   * Whether the dropdown is currently open\n   */\n  isOpen: boolean;\n  \n  /**\n   * Callback when an item is selected (Enter key)\n   */\n  onSelect: (item: T, index: number) => void;\n  \n  /**\n   * Callback to close the dropdown\n   */\n  onClose: () => void;\n  \n  /**\n   * Optional: Callback to open the dropdown\n   */\n  onOpen?: () => void;\n  \n  /**\n   * Whether to wrap around at the ends of the list.\n   * Default: true\n   */\n  loop?: boolean;\n  \n  /**\n   * Whether keyboard navigation is disabled\n   * (e.g., for custom rendered content)\n   */\n  disabled?: boolean;\n  \n  /**\n   * Ref to the listbox container for scroll management\n   */\n  listboxRef?: RefObject<HTMLElement | null>;\n  \n  /**\n   * CSS selector for option elements (default: '[role=\"option\"]')\n   */\n  optionSelector?: string;\n}\n\nexport interface UseComboboxNavigationReturn {\n  /**\n   * Currently highlighted index (-1 if none)\n   */\n  highlightedIndex: number;\n  \n  /**\n   * Set the highlighted index manually\n   */\n  setHighlightedIndex: (index: number | ((prev: number) => number)) => void;\n  \n  /**\n   * Keyboard event handler for the combobox input\n   */\n  handleKeyDown: (e: React.KeyboardEvent) => void;\n  \n  /**\n   * Generate stable ID for an option\n   */\n  getOptionId: (listboxId: string, index: number) => string;\n  \n}\n\n/**\n * Hook for managing combobox keyboard navigation with aria-activedescendant.\n * \n * Implements WAI-ARIA 1.2 Combobox pattern:\n * - Arrow Up/Down to navigate options\n * - Enter to select highlighted option\n * - Escape to close dropdown\n * - Tab to close and move focus\n * - Auto-scrolls highlighted option into view\n * \n * @example\n * ```tsx\n * const { \n *   highlightedIndex, \n *   handleKeyDown, \n *   getOptionId \n * } = useComboboxNavigation({\n *   items: suggestions,\n *   isOpen: isDropdownOpen,\n *   onSelect: (item, idx) => handleSelect(item),\n *   onClose: () => setIsOpen(false),\n *   listboxRef\n * });\n * \n * <input\n *   role=\"combobox\"\n *   onKeyDown={handleKeyDown}\n *   aria-activedescendant={highlightedIndex >= 0 ? getOptionId(listboxId, highlightedIndex) : undefined}\n * />\n * ```\n */\nexport function useComboboxNavigation<T = any>({\n  items,\n  isOpen,\n  onSelect,\n  onClose,\n  onOpen,\n  loop = true,\n  disabled = false,\n  listboxRef,\n  optionSelector = '[role=\"option\"]'\n}: UseComboboxNavigationOptions<T>): UseComboboxNavigationReturn {\n  const [highlightedIndex, setHighlightedIndex] = useState<number>(-1);\n  \n  // Reset highlighted index when dropdown closes\n  useEffect(() => {\n    if (!isOpen) {\n      setHighlightedIndex(-1);\n    }\n  }, [isOpen]);\n  \n  // Auto-scroll highlighted item into view\n  useScrollActiveIntoView({\n    containerRef: listboxRef,\n    activeIndex: highlightedIndex,\n    itemSelector: optionSelector,\n    enabled: isOpen\n  });\n  \n  const handleKeyDown = useCallback(\n    (e: React.KeyboardEvent) => {\n      if (disabled) {\n        // For disabled navigation, still handle Escape\n        if (e.key === 'Escape' && isOpen) {\n          e.preventDefault();\n          onClose();\n        }\n        return;\n      }\n      \n      const itemCount = items.length;\n      \n      switch (e.key) {\n        case 'ArrowDown':\n          e.preventDefault();\n          if (!isOpen && itemCount > 0) {\n            // Open dropdown and highlight first item\n            onOpen?.();\n            setHighlightedIndex(0);\n          } else if (isOpen && itemCount > 0) {\n            // Navigate down\n            setHighlightedIndex((prev) => {\n              if (loop) {\n                return (prev + 1) % itemCount;\n              }\n              return Math.min(prev + 1, itemCount - 1);\n            });\n          }\n          break;\n          \n        case 'ArrowUp':\n          e.preventDefault();\n          if (isOpen && itemCount > 0) {\n            // Navigate up\n            setHighlightedIndex((prev) => {\n              // If nothing highlighted, go to last item\n              if (prev === -1) {\n                return itemCount - 1;\n              }\n              if (loop) {\n                return (prev - 1 + itemCount) % itemCount;\n              }\n              return Math.max(prev - 1, 0);\n            });\n          }\n          break;\n          \n        case 'Enter':\n          e.preventDefault();\n          if (!isOpen) {\n            onOpen?.();\n            setHighlightedIndex(0);\n          } else if (highlightedIndex >= 0 && items[highlightedIndex]) {\n            onSelect(items[highlightedIndex], highlightedIndex);\n            setHighlightedIndex(-1);\n          }\n          break;\n\n        case 'Escape':\n          if (isOpen) {\n            e.preventDefault();\n            onClose();\n            setHighlightedIndex(-1);\n          }\n          break;\n          \n        case 'Tab':\n          // Close dropdown on Tab (don't preventDefault - let focus move naturally)\n          if (isOpen) {\n            onClose();\n            setHighlightedIndex(-1);\n          }\n          break;\n      }\n    },\n    [disabled, items, isOpen, highlightedIndex, onSelect, onClose, onOpen, loop]\n  );\n  \n  const getOptionId = useCallback(\n    (listboxId: string, index: number) => `${listboxId}-option-${index}`,\n    []\n  );\n  \n  return {\n    highlightedIndex,\n    setHighlightedIndex,\n    handleKeyDown,\n    getOptionId\n  };\n}\n"],"names":["useState","useEffect","useCallback","useScrollActiveIntoView","useComboboxNavigation","items","isOpen","onSelect","onClose","onOpen","loop","disabled","listboxRef","optionSelector","highlightedIndex","setHighlightedIndex","containerRef","activeIndex","itemSelector","enabled","handleKeyDown","e","key","preventDefault","itemCount","length","prev","Math","min","max","getOptionId","listboxId","index"],"mappings":"AA2GO,SAAA,YAAAA,GAAA,aAAAC,GAAA,eAAAC,SAAA;AAAA,SAAA,2BAAAC,SAAA;AAAA,SAASC,EAA+B;AAAA,EAC7CC,OAAAA;AAAAA,EACAC,QAAAA;AAAAA,EACAC,UAAAA;AAAAA,EACAC,SAAAA;AAAAA,EACAC,QAAAA;AAAAA,EACAC,MAAAA,IAAO;AAAA,EACPC,UAAAA,IAAW;AAAA,EACXC,YAAAA;AAAAA,EACAC,gBAAAA,IAAiB;AACc,GAAgC;AAC/D,QAAM,CAACC,GAAkBC,CAAmB,IAAIf,EAAiB,EAAE;AAGnEC,EAAAA,EAAU,MAAM;AACd,IAAKK,KACHS,EAAoB,EAAE;AAAA,EAE1B,GAAG,CAACT,CAAM,CAAC,GAGXH,EAAwB;AAAA,IACtBa,cAAcJ;AAAAA,IACdK,aAAaH;AAAAA,IACbI,cAAcL;AAAAA,IACdM,SAASb;AAAAA,EAAAA,CACV;AAED,QAAMc,IAAgBlB,EACpB,CAACmB,MAA2B;AAC1B,QAAIV,GAAU;AAEZ,MAAIU,EAAEC,QAAQ,YAAYhB,MACxBe,EAAEE,eAAAA,GACFf,EAAAA;AAEF;AAAA,IACF;AAEA,UAAMgB,IAAYnB,EAAMoB;AAExB,YAAQJ,EAAEC,KAAAA;AAAAA,MACR,KAAK;AACHD,QAAAA,EAAEE,eAAAA,GACE,CAACjB,KAAUkB,IAAY,KAEzBf,IAAAA,GACAM,EAAoB,CAAC,KACZT,KAAUkB,IAAY,KAE/BT,EAAqBW,CAAAA,MACfhB,KACMgB,IAAO,KAAKF,IAEfG,KAAKC,IAAIF,IAAO,GAAGF,IAAY,CAAC,CACxC;AAEH;AAAA,MAEF,KAAK;AACHH,QAAAA,EAAEE,eAAAA,GACEjB,KAAUkB,IAAY,KAExBT,EAAqBW,CAAAA,MAEfA,MAAS,KACJF,IAAY,IAEjBd,KACMgB,IAAO,IAAIF,KAAaA,IAE3BG,KAAKE,IAAIH,IAAO,GAAG,CAAC,CAC5B;AAEH;AAAA,MAEF,KAAK;AACHL,QAAAA,EAAEE,eAAAA,GACGjB,IAGMQ,KAAoB,KAAKT,EAAMS,CAAgB,MACxDP,EAASF,EAAMS,CAAgB,GAAGA,CAAgB,GAClDC,EAAoB,EAAE,MAJtBN,IAAAA,GACAM,EAAoB,CAAC;AAKvB;AAAA,MAEF,KAAK;AACH,QAAIT,MACFe,EAAEE,eAAAA,GACFf,EAAAA,GACAO,EAAoB,EAAE;AAExB;AAAA,MAEF,KAAK;AAEH,QAAIT,MACFE,EAAAA,GACAO,EAAoB,EAAE;AAExB;AAAA,IAAA;AAAA,EAEN,GACA,CAACJ,GAAUN,GAAOC,GAAQQ,GAAkBP,GAAUC,GAASC,GAAQC,CAAI,CAC7E,GAEMoB,IAAc5B,EAClB,CAAC6B,GAAmBC,MAAkB,GAAGD,CAAS,WAAWC,CAAK,IAClE,CAAA,CACF;AAEA,SAAO;AAAA,IACLlB,kBAAAA;AAAAA,IACAC,qBAAAA;AAAAA,IACAK,eAAAA;AAAAA,IACAU,aAAAA;AAAAA,EAAAA;AAEJ;"}