@astryxdesign/core 0.1.2-canary.bd8c3d3 → 0.1.2-canary.bfcbf64

package/dist/hooks/index.d.ts

@@ -8,10 +8,16 @@
  */
 export { useFocusTrap } from './useFocusTrap';
 export type { UseFocusTrapOptions, UseFocusTrapReturn } from './useFocusTrap';
+export { useAnnounce } from './useAnnounce';
+export type { AnnounceFn, AnnouncePoliteness } from './useAnnounce';
 export { useGridFocus } from './useGridFocus';
 export type { UseGridFocusOptions, UseGridFocusReturn } from './useGridFocus';
 export { useListFocus } from './useListFocus';
-export type { UseListFocusOptions, UseListFocusReturn } from './useListFocus';
+export type { UseListFocusOptions, UseListFocusReturn, ListFocusOrientation, } from './useListFocus';
+export { useTreeFocus } from './useTreeFocus';
+export type { UseTreeFocusOptions, UseTreeFocusReturn } from './useTreeFocus';
+export { useTypeahead } from './useTypeahead';
+export type { UseTypeaheadOptions, UseTypeaheadReturn } from './useTypeahead';
 export { useMediaQuery } from './useMediaQuery';
 export { useOverflow } from './useOverflow';
 export type { UseOverflowOptions, UseOverflowReturn } from './useOverflow';
@@ -24,10 +30,12 @@ export { useStreamingText } from './useStreamingText';
 export type { StreamingTextSpeed, UseStreamingTextOptions, } from './useStreamingText';
 export { useImageMode } from './useImageMode';
 export type { ImageSampleRegion, UseImageModeOptions } from './useImageMode';
-export { useClickableContainer } from './useClickableContainer';
+export { useClickableContainer, INTERACTIVE_SELECTORS } from './useClickableContainer';
 export type { UseClickableContainerOptions, ClickableContainerResult, } from './useClickableContainer';
 export { useInputContainer } from './useInputContainer';
 export type { UseInputContainerOptions } from './useInputContainer';
 export { useInteractiveRole } from './useInteractiveRole';
 export type { InteractiveRole, UseInteractiveRoleOptions, } from './useInteractiveRole';
+export { useLongPress } from './useLongPress';
+export type { UseLongPressOptions, UseLongPressHandlers, } from './useLongPress';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,iBAAiB,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EAAC,qBAAqB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,YAAY,EACV,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,wBAAwB,EAAC,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACxD,YAAY,EACV,eAAe,EACf,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAC,UAAU,EAAE,kBAAkB,EAAC,MAAM,eAAe,CAAC;AAElE,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,iBAAiB,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EAAC,qBAAqB,EAAE,qBAAqB,EAAC,MAAM,yBAAyB,CAAC;AACrF,YAAY,EACV,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,wBAAwB,EAAC,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACxD,YAAY,EACV,eAAe,EACf,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EACV,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC"}

package/dist/hooks/index.js

@@ -11,8 +11,11 @@
  * SYNC: When modified, update this header
  */
 export { useFocusTrap } from "./useFocusTrap.js";
+export { useAnnounce } from "./useAnnounce.js";
 export { useGridFocus } from "./useGridFocus.js";
 export { useListFocus } from "./useListFocus.js";
+export { useTreeFocus } from "./useTreeFocus.js";
+export { useTypeahead } from "./useTypeahead.js";
 export { useMediaQuery } from "./useMediaQuery.js";
 export { useOverflow } from "./useOverflow.js";
 export { useScrollOverflow } from "./useScrollOverflow.js";
@@ -20,6 +23,7 @@ export { useScrollLock } from "./useScrollLock.js";
 export { useEntryAnimation } from "./useEntryAnimation.js";
 export { useStreamingText } from "./useStreamingText.js";
 export { useImageMode } from "./useImageMode.js";
-export { useClickableContainer } from "./useClickableContainer.js";
+export { useClickableContainer, INTERACTIVE_SELECTORS } from "./useClickableContainer.js";
 export { useInputContainer } from "./useInputContainer.js";
-export { useInteractiveRole } from "./useInteractiveRole.js";
+export { useInteractiveRole } from "./useInteractiveRole.js";
+export { useLongPress } from "./useLongPress.js";

package/dist/hooks/useAnnounce.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Announcement urgency:
+ * - `'polite'` (default): announced when the screen reader is idle. Use for
+ *   status updates, result counts, "no results", non-urgent confirmations.
+ * - `'assertive'`: interrupts the current announcement. Reserve for errors and
+ *   time-sensitive alerts.
+ */
+export type AnnouncePoliteness = 'polite' | 'assertive';
+/**
+ * Imperative screen-reader announcement function.
+ */
+export type AnnounceFn = (message: string, politeness?: AnnouncePoliteness) => void;
+/**
+ * Returns an imperative `announce(message, politeness?)` function that speaks a
+ * message through a persistently-mounted, visually-hidden live region.
+ *
+ * The polite and assertive regions are created once on first use and kept
+ * mounted, so announcements are reliable even for messages that appear
+ * immediately (unlike a live region rendered together with its content).
+ *
+ * @example
+ * ```
+ * function Search() {
+ *   const announce = useAnnounce();
+ *   const onResults = (n: number) => {
+ *     announce(n === 0 ? 'No results found' : `${n} results`);
+ *   };
+ *   // ...
+ * }
+ * ```
+ */
+export declare function useAnnounce(): AnnounceFn;
+/**
+ * Test-only helper: removes the singleton live regions and resets state so
+ * each test starts clean. Not part of the public runtime API.
+ *
+ * @internal
+ */
+export declare function __resetLiveRegionsForTest(): void;
+//# sourceMappingURL=useAnnounce.d.ts.map

package/dist/hooks/useAnnounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounce.ts"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,kBAAkB,KAC5B,IAAI,CAAC;AAyFV;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,IAAI,UAAU,CAaxC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD"}

package/dist/hooks/useAnnounce.js

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAnnounce.ts
+ * @input Uses React useCallback; DOM APIs for a singleton live-region pair
+ * @output Exports useAnnounce hook and AnnouncePoliteness type
+ * @position Core a11y hook; provides imperative screen-reader announcements
+ *   via persistently-mounted polite/assertive live regions
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+import { useCallback } from 'react';
+
+/**
+ * Announcement urgency:
+ * - `'polite'` (default): announced when the screen reader is idle. Use for
+ *   status updates, result counts, "no results", non-urgent confirmations.
+ * - `'assertive'`: interrupts the current announcement. Reserve for errors and
+ *   time-sensitive alerts.
+ */
+
+/**
+ * Imperative screen-reader announcement function.
+ */
+
+const CONTAINER_ATTR = 'data-astryx-live-region';
+
+// Visually-hidden clip block (matches the VisuallyHidden primitive). Applied
+// inline so the regions work without any stylesheet being present.
+const VISUALLY_HIDDEN_CSS = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;' + 'overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;' + 'inset-block-start:0;inset-inline-start:0;pointer-events:none;' + 'user-select:none;';
+// Singleton: the live regions are created ONCE and stay mounted for the
+// lifetime of the document. This is the crux of reliable announcements — many
+// screen readers will not announce content injected into a live region that is
+// created together with its content ("born with content"). By mounting empty
+// regions up front and only mutating their text later, updates are announced.
+let regions = null;
+function createRegion(politeness) {
+  const el = document.createElement('div');
+  el.setAttribute(CONTAINER_ATTR, politeness);
+  el.setAttribute('aria-live', politeness);
+  el.setAttribute('aria-atomic', 'true');
+  el.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');
+  el.style.cssText = VISUALLY_HIDDEN_CSS;
+  document.body.appendChild(el);
+  return el;
+}
+function getRegions() {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+  if (regions) {
+    // Re-attach if a region was removed from the DOM (e.g. by a test cleanup).
+    if (!regions.polite.isConnected) {
+      document.body.appendChild(regions.polite);
+    }
+    if (!regions.assertive.isConnected) {
+      document.body.appendChild(regions.assertive);
+    }
+    return regions;
+  }
+  regions = {
+    polite: createRegion('polite'),
+    assertive: createRegion('assertive')
+  };
+  return regions;
+}
+function announceMessage(message, politeness) {
+  const r = getRegions();
+  if (!r) {
+    return;
+  }
+  const target = politeness === 'assertive' ? r.assertive : r.polite;
+  // Clearing first guarantees the mutation is observed even when the new
+  // message equals the current text — some AT deduplicate identical content.
+  target.textContent = '';
+  // A microtask/rAF-free re-set in the next frame is more reliable across AT
+  // than an immediate re-set, which can be coalesced with the clear.
+  requestAnimationFrame(() => {
+    target.textContent = message;
+  });
+}
+
+/**
+ * Clear any pending announcement from a region without announcing anything new.
+ * Used when the triggering context goes away (e.g. a search query is cleared),
+ * so stale status text does not linger in the accessibility tree.
+ */
+function clearRegion(politeness) {
+  if (!regions) {
+    return;
+  }
+  const target = politeness === 'assertive' ? regions.assertive : regions.polite;
+  target.textContent = '';
+}
+
+/**
+ * Returns an imperative `announce(message, politeness?)` function that speaks a
+ * message through a persistently-mounted, visually-hidden live region.
+ *
+ * The polite and assertive regions are created once on first use and kept
+ * mounted, so announcements are reliable even for messages that appear
+ * immediately (unlike a live region rendered together with its content).
+ *
+ * @example
+ * ```
+ * function Search() {
+ *   const announce = useAnnounce();
+ *   const onResults = (n: number) => {
+ *     announce(n === 0 ? 'No results found' : `${n} results`);
+ *   };
+ *   // ...
+ * }
+ * ```
+ */
+export function useAnnounce() {
+  return useCallback((message, politeness = 'polite') => {
+    if (!message) {
+      // An empty message clears any lingering status from the region rather
+      // than announcing nothing — useful when the triggering context ends.
+      clearRegion(politeness);
+      return;
+    }
+    announceMessage(message, politeness);
+  }, []);
+}
+
+/**
+ * Test-only helper: removes the singleton live regions and resets state so
+ * each test starts clean. Not part of the public runtime API.
+ *
+ * @internal
+ */
+export function __resetLiveRegionsForTest() {
+  if (regions) {
+    regions.polite.remove();
+    regions.assertive.remove();
+    regions = null;
+  }
+}

package/dist/hooks/useClickableContainer.d.ts

@@ -1,13 +1,28 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container
+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list
  * @position Core hook for clickable containers that safely handle nested interactive elements
  *
  * Solves the "nested interactive elements" problem: when a card is clickable
  * but contains buttons/links, clicking those should NOT trigger the card's action.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (export)
  */
 import { type RefObject, type MouseEvent } from 'react';
+/**
+ * Canonical list of interactive element selectors — native controls plus
+ * role-based interactive elements. Clicks on these (or their descendants)
+ * should NOT bubble to a clickable container's click handler.
+ *
+ * Exported so other focus/interaction utilities can share one comprehensive
+ * definition of "interactive target" rather than hand-rolling divergent lists.
+ * Note: this list is about "don't bubble clicks", not focus-eligibility —
+ * consumers that need focusable elements must additionally exclude
+ * unfocusable/disabled targets (e.g. `[tabindex="-1"]`, `:disabled`).
+ */
+export declare const INTERACTIVE_SELECTORS: string;
 export interface UseClickableContainerOptions {
     /** Ref to the outer container element */
     containerRef: RefObject<HTMLElement | null>;

package/dist/hooks/useClickableContainer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useClickableContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useClickableContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAC,MAAM,OAAO,CAAC;AA0D9E,MAAM,WAAW,4BAA4B;IAC3C,yCAAyC;IACzC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,mEAAmE;IACnE,cAAc,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACnD,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,YAAY,EACZ,cAAc,EACd,OAAO,EAAE,WAAW,EACpB,IAAI,EACJ,MAAM,EACN,QAAgB,GACjB,EAAE,4BAA4B,GAAG,wBAAwB,CA6GzD"}
+{"version":3,"file":"useClickableContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useClickableContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAC,MAAM,OAAO,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAmBvB,CAAC;AAmCZ,MAAM,WAAW,4BAA4B;IAC3C,yCAAyC;IACzC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,mEAAmE;IACnE,cAAc,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACnD,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,YAAY,EACZ,cAAc,EACd,OAAO,EAAE,WAAW,EACpB,IAAI,EACJ,MAAM,EACN,QAAgB,GACjB,EAAE,4BAA4B,GAAG,wBAAwB,CA6GzD"}

package/dist/hooks/useClickableContainer.js

@@ -5,17 +5,29 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container
+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list
  * @position Core hook for clickable containers that safely handle nested interactive elements
  *
  * Solves the "nested interactive elements" problem: when a card is clickable
  * but contains buttons/links, clicking those should NOT trigger the card's action.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (export)
  */
 import { useCallback, useEffect } from 'react';
 
-// Interactive element selectors — clicks on these (or their descendants)
-// should NOT bubble to the container's click handler.
-const INTERACTIVE_SELECTORS = ['button', 'a', 'input', 'select', 'textarea', '[role="button"]', '[role="link"]', '[role="checkbox"]', '[role="radio"]', '[role="switch"]', '[role="tab"]', '[role="menuitem"]', '[role="option"]', '[role="combobox"]', '[role="listbox"]', '[role="slider"]', '[role="spinbutton"]', '[data-pressable-container]'].join(',');
+/**
+ * Canonical list of interactive element selectors — native controls plus
+ * role-based interactive elements. Clicks on these (or their descendants)
+ * should NOT bubble to a clickable container's click handler.
+ *
+ * Exported so other focus/interaction utilities can share one comprehensive
+ * definition of "interactive target" rather than hand-rolling divergent lists.
+ * Note: this list is about "don't bubble clicks", not focus-eligibility —
+ * consumers that need focusable elements must additionally exclude
+ * unfocusable/disabled targets (e.g. `[tabindex="-1"]`, `:disabled`).
+ */
+export const INTERACTIVE_SELECTORS = ['button', 'a', 'input', 'select', 'textarea', '[role="button"]', '[role="link"]', '[role="checkbox"]', '[role="radio"]', '[role="switch"]', '[role="tab"]', '[role="menuitem"]', '[role="option"]', '[role="combobox"]', '[role="listbox"]', '[role="slider"]', '[role="spinbutton"]', '[data-pressable-container]'].join(',');
 const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';
 
 /**

package/dist/hooks/useFocusTrap.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Whether any focus-trap Escape handler is currently active (i.e. a popover
+ * layer is open). Other overlay primitives that manage their own Escape (e.g.
+ * Dialog) can consult this to defer to a popover layered on top of them,
+ * giving topmost-only dismissal until a full layer stack exists.
+ */
+export declare function hasActiveFocusTrapEscape(): boolean;
+/**
+ * Whether an Escape keydown should be ignored because it is cancelling an
+ * in-progress IME composition. CJK/IME users press Escape to cancel
+ * composition; that must not close the surrounding overlay. `keyCode === 229`
+ * covers browsers that fire keydown before `isComposing` is set. Exported so
+ * other overlays (Dialog, Drawer, CommandPalette) share one definition.
+ */
+export declare function isImeKeyEvent(event: {
+    isComposing?: boolean;
+    keyCode?: number;
+}): boolean;
 /**
  * Configuration for focus trap behavior
  */

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

@@ -1 +1 @@
-{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AA6FA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CA2HvB"}
+{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AA+CA;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAEV;AA0ED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAoJvB"}

package/dist/hooks/useFocusTrap.js

@@ -17,6 +17,50 @@
 import { useCallback, useEffect, useRef } from 'react';
 import { FOCUSABLE_SELECTOR } from "./focusableSelector.js";
 
+/**
+ * Module-level stack of active focus-trap Escape handlers.
+ *
+ * Every active `useFocusTrap` used to attach its own document-level `keydown`
+ * listener with no coordination, so a single Escape press closed *every* open
+ * layer at once (e.g. a popover nested inside a Dialog closed both). Tracking
+ * traps in a shared stack lets only the most recently activated (top-most)
+ * trap respond to Escape.
+ */
+const escapeStack = [];
+function pushEscapeHandler(handler) {
+  escapeStack.push(handler);
+}
+function removeEscapeHandler(handler) {
+  const index = escapeStack.lastIndexOf(handler);
+  if (index !== -1) {
+    escapeStack.splice(index, 1);
+  }
+}
+function isTopEscapeHandler(handler) {
+  return escapeStack[escapeStack.length - 1] === handler;
+}
+
+/**
+ * Whether any focus-trap Escape handler is currently active (i.e. a popover
+ * layer is open). Other overlay primitives that manage their own Escape (e.g.
+ * Dialog) can consult this to defer to a popover layered on top of them,
+ * giving topmost-only dismissal until a full layer stack exists.
+ */
+export function hasActiveFocusTrapEscape() {
+  return escapeStack.length > 0;
+}
+
+/**
+ * Whether an Escape keydown should be ignored because it is cancelling an
+ * in-progress IME composition. CJK/IME users press Escape to cancel
+ * composition; that must not close the surrounding overlay. `keyCode === 229`
+ * covers browsers that fire keydown before `isComposing` is set. Exported so
+ * other overlays (Dialog, Drawer, CommandPalette) share one definition.
+ */
+export function isImeKeyEvent(event) {
+  return event.isComposing === true || event.keyCode === 229;
+}
+
 /**
  * Whether an element is currently perceivable/focusable — excludes ones hidden
  * via `display:none`/`visibility:hidden` or inside an `inert`/`hidden` subtree,
@@ -190,13 +234,31 @@ export function useFocusTrap(options) {
     if (!isActive) {
       return;
     }
+
+    // Register this trap on the shared Escape stack so only the top-most
+    // active trap responds to Escape. A stable identity per active period is
+    // enough — we push on activate and remove on cleanup.
+    const escapeHandler = () => {
+      onEscape?.();
+    };
+    if (onEscape) {
+      pushEscapeHandler(escapeHandler);
+    }
     const handleKeyDown = event => {
       const container = containerRef.current;
       if (!container) {
         return;
       }
       if (event.key === 'Escape' && onEscape) {
+        // Ignore Escape that is cancelling an IME composition, already handled
+        // by a nested handler, or not targeting the top-most trap.
+        if (event.defaultPrevented || isImeKeyEvent(event) || !isTopEscapeHandler(escapeHandler)) {
+          return;
+        }
+        // Mark handled and stop propagation so an outer layer (e.g. a Dialog
+        // hosting this popover) does not also dismiss on the same press.
         event.preventDefault();
+        event.stopPropagation();
         onEscape();
         return;
       }
@@ -227,6 +289,9 @@ export function useFocusTrap(options) {
     document.addEventListener('keydown', handleKeyDown);
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
+      if (onEscape) {
+        removeEscapeHandler(escapeHandler);
+      }
     };
   }, [isActive, onEscape]);
   return {

package/dist/hooks/useListFocus.d.ts

@@ -1,10 +1,17 @@
+/**
+ * Navigation orientation for a linear list.
+ * - `'horizontal'`: ArrowLeft/ArrowRight move between items.
+ * - `'vertical'`: ArrowUp/ArrowDown move between items.
+ * - `'both'`: all four arrows move between items (in linear DOM order).
+ */
+export type ListFocusOrientation = 'horizontal' | 'vertical' | 'both';
 /**
  * Configuration for list focus behavior
  */
 export interface UseListFocusOptions {
     /**
      * Selector for focusable items within the list.
-     * @default '[role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"]'
+     * @default '[role="menuitem"]'
      */
     itemSelector?: string;
     /**
@@ -17,11 +24,47 @@ export interface UseListFocusOptions {
      */
     onEscape?: () => void;
     /**
-     * Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight,
-     * 'vertical' uses ArrowUp/ArrowDown.
+     * Navigation orientation. `'horizontal'` uses ArrowLeft/ArrowRight,
+     * `'vertical'` uses ArrowUp/ArrowDown, `'both'` accepts all four arrows.
      * @default 'vertical'
      */
-    orientation?: 'horizontal' | 'vertical';
+    orientation?: ListFocusOrientation;
+    /**
+     * Whether Home/End jump to the first/last enabled item.
+     * @default true
+     */
+    hasHomeEnd?: boolean;
+    /**
+     * Whether the list is in a right-to-left context. When true, ArrowLeft and
+     * ArrowRight are swapped so horizontal navigation follows visual direction.
+     * Only affects horizontal (`'horizontal'`/`'both'`) navigation.
+     * @default false
+     */
+    isRtl?: boolean;
+    /**
+     * Roving-tabindex ownership. When true, the hook manages a single tab stop
+     * across the items: exactly one enabled item carries `tabindex="0"` and the
+     * rest `tabindex="-1"`. The tab stop is stamped on mount and repaired
+     * whenever items mount/unmount or toggle disabled, and moves with arrow
+     * navigation. Attach the returned {@link UseListFocusReturn.handleFocus} to
+     * the container's `onFocus` to keep the stop in sync after clicks or
+     * programmatic focus.
+     *
+     * When false (the default), the hook only *moves* focus (`.focus()`) and
+     * never touches `tabindex` — the caller owns tab-stop management.
+     * @default false
+     */
+    hasRovingTabIndex?: boolean;
+    /**
+     * When true, arrow keys are not stolen from a nested text input/textarea
+     * whose caret is not at the boundary in the direction of travel (or that has
+     * a non-collapsed selection), and are never stolen from a nested
+     * `contenteditable` (rich-text editor / chat composer). This preserves
+     * normal caret movement while the user is editing inline within the list
+     * (e.g. a toolbar search field or composer).
+     * @default false
+     */
+    hasCaretGuard?: boolean;
 }
 /**
  * Return type for useListFocus hook
@@ -35,18 +78,24 @@ export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
      * Key down handler to attach to the list container.
      */
     handleKeyDown: (e: React.KeyboardEvent) => void;
+    /**
+     * Focus handler to attach to the container's `onFocus`. Keeps the roving tab
+     * stop in sync when `hasRovingTabIndex` is enabled; a no-op otherwise, so it is
+     * always safe to attach.
+     */
+    handleFocus: (e: React.FocusEvent) => void;
     /**
      * Focus a specific item by index.
      */
     focusItem: (index: number) => void;
     /**
-     * Focus the first focusable item.
+     * Focus the first enabled item. Returns true when an item was focused.
      */
-    focusFirst: () => void;
+    focusFirst: () => boolean;
     /**
-     * Focus the last focusable item.
+     * Focus the last enabled item. Returns true when an item was focused.
      */
-    focusLast: () => void;
+    focusLast: () => boolean;
 }
 /**
  * Hook for managing keyboard navigation within a linear list.
@@ -58,6 +107,12 @@ export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
  * - End: Move to last item
  * - Escape: Custom callback (e.g., close menu)
  *
+ * By default the hook only *moves* focus and leaves `tabindex` management to
+ * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook
+ * that owns a single tab stop (roving tabindex) across the items — stamping and
+ * repairing it as items mount/unmount or toggle disabled — for toolbars,
+ * segmented controls, tab strips, and similar composite widgets.
+ *
  * @example
  * ```
  * const {listRef, handleKeyDown} = useListFocus({
@@ -68,6 +123,22 @@ export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
  *   {items.map(item => <div role="menuitem" tabIndex={0}>{item}</div>)}
  * </div>
  * ```
+ *
+ * Roving-tabindex composite (e.g. a toolbar):
+ *
+ * @example
+ * ```
+ * const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+ *   itemSelector: 'button, input, [tabindex]',
+ *   orientation: 'horizontal',
+ *   hasRovingTabIndex: true,
+ *   hasCaretGuard: true,
+ * });
+ *
+ * <div ref={listRef} role="toolbar" onKeyDown={handleKeyDown} onFocus={handleFocus}>
+ *   {children}
+ * </div>
+ * ```
  */
 export declare function useListFocus<T extends HTMLElement = HTMLElement>(options?: UseListFocusOptions): UseListFocusReturn<T>;
 //# sourceMappingURL=useListFocus.d.ts.map

package/dist/hooks/useListFocus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAuLvB"}
+{"version":3,"file":"useListFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useListFocus.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IAEnC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;CAC1B;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAwSvB"}