@astryxdesign/core 0.1.2 → 0.1.3

package/dist/hooks/focusableSelector.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file focusableSelector.ts
+ * @input None (a plain CSS selector string constant)
+ * @output Exports FOCUSABLE_SELECTOR
+ * @position Internal utility; the canonical CSS selector for focusable
+ *   elements, shared by focus-management hooks (e.g. useFocusTrap) so the
+ *   selector isn't duplicated across components/hooks. Not exported from the
+ *   public barrel — internal implementation detail.
+ */
+/**
+ * Canonical CSS selector for commonly focusable elements. Includes the
+ * tabbable natives (button/link/input/select/textarea/[tabindex]) plus
+ * editable and media elements the browser also puts in the tab order —
+ * contenteditable, media with controls, iframe, and an open <details>'s
+ * <summary> — which a naive selector misses, letting Tab escape a trap whose
+ * only interactive content is (e.g.) a contenteditable composer (infra-8).
+ *
+ * This is the canonical focusable selector; prefer importing it here over
+ * re-declaring the string so behavior stays consistent across hooks.
+ */
+export declare const FOCUSABLE_SELECTOR = "button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"]):not([disabled]), [contenteditable]:not([contenteditable=\"false\"]), audio[controls], video[controls], iframe, details > summary:first-child";
+//# sourceMappingURL=focusableSelector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"focusableSelector.d.ts","sourceRoot":"","sources":["../../src/hooks/focusableSelector.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,4RACwP,CAAC"}

package/dist/hooks/focusableSelector.js

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file focusableSelector.ts
+ * @input None (a plain CSS selector string constant)
+ * @output Exports FOCUSABLE_SELECTOR
+ * @position Internal utility; the canonical CSS selector for focusable
+ *   elements, shared by focus-management hooks (e.g. useFocusTrap) so the
+ *   selector isn't duplicated across components/hooks. Not exported from the
+ *   public barrel — internal implementation detail.
+ */
+
+/**
+ * Canonical CSS selector for commonly focusable elements. Includes the
+ * tabbable natives (button/link/input/select/textarea/[tabindex]) plus
+ * editable and media elements the browser also puts in the tab order —
+ * contenteditable, media with controls, iframe, and an open <details>'s
+ * <summary> — which a naive selector misses, letting Tab escape a trap whose
+ * only interactive content is (e.g.) a contenteditable composer (infra-8).
+ *
+ * This is the canonical focusable selector; prefer importing it here over
+ * re-declaring the string so behavior stays consistent across hooks.
+ */
+export const FOCUSABLE_SELECTOR = 'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]):not([disabled]), [contenteditable]:not([contenteditable="false"]), audio[controls], video[controls], iframe, details > summary:first-child';

package/dist/hooks/index.d.ts

@@ -8,10 +8,18 @@
  */
 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 { useKeyboardHint } from './useKeyboardHint';
+export type { UseKeyboardHintOptions, UseKeyboardHintReturn, KeyboardHintOrientation, } from './useKeyboardHint';
+export type { UseTypeaheadOptions, UseTypeaheadReturn } from './useTypeahead';
 export { useMediaQuery } from './useMediaQuery';
 export { useOverflow } from './useOverflow';
 export type { UseOverflowOptions, UseOverflowReturn } from './useOverflow';
@@ -24,10 +32,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;AAE5C,OAAO,EAAC,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAClD,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,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,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AACjC,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,EAAC,mBAAmB,EAAE,oBAAoB,EAAC,MAAM,gBAAgB,CAAC"}

package/dist/hooks/index.js

@@ -11,8 +11,12 @@
  * 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 { useKeyboardHint } from "./useKeyboardHint.js";
 export { useMediaQuery } from "./useMediaQuery.js";
 export { useOverflow } from "./useOverflow.js";
 export { useScrollOverflow } from "./useScrollOverflow.js";
@@ -20,6 +24,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/useEntryAnimation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useEntryAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useEntryAnimation.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAwEnD,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,SAAS,GACT,QAAQ,GACR,SAAS,CAAC;AAEd;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,oBAAkC,GACzC,YAAY,GAAG,IAAI,CAGrB"}
+{"version":3,"file":"useEntryAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useEntryAnimation.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAoFnD,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,SAAS,GACT,QAAQ,GACR,SAAS,CAAC;AAEd;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,oBAAkC,GACzC,YAAY,GAAG,IAAI,CAGrB"}

package/dist/hooks/useEntryAnimation.js

@@ -38,28 +38,28 @@ const fadeIn = "x18re5ia-B";
 const scaleIn = "x1k48ry3-B";
 const styles = {
   slideDown: {
-    kKVMdj: "x1srr2gu",
+    kKVMdj: "x1srr2gu x1aquc0h",
     k44tkh: "x9uej1z",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true
   },
   slideUp: {
-    kKVMdj: "x1dvww92",
+    kKVMdj: "x1dvww92 x1aquc0h",
     k44tkh: "x9uej1z",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true
   },
   fadeIn: {
-    kKVMdj: "xqcmdr3",
+    kKVMdj: "xqcmdr3 x1aquc0h",
     k44tkh: "x9uej1z",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true
   },
   scaleIn: {
-    kKVMdj: "x97zbip",
+    kKVMdj: "x97zbip x1aquc0h",
     k44tkh: "x9uej1z",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",

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":"AA0EA;;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

@@ -15,17 +15,80 @@
  * - /packages/core/src/hooks/index.ts
  */
 import { useCallback, useEffect, useRef } from 'react';
+import { FOCUSABLE_SELECTOR } from "./focusableSelector.js";
 
 /**
- * Selector for commonly focusable elements.
+ * 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.
  */
-const FOCUSABLE_SELECTOR = 'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]):not([disabled])';
+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,
+ * which the browser skips for Tab.
+ */
+function isVisiblyFocusable(el) {
+  if (el.hasAttribute('inert') || el.closest('[inert]')) {
+    return false;
+  }
+  if (el.hidden || el.closest('[hidden]')) {
+    return false;
+  }
+  // offsetParent is null for display:none (and fixed elements); pair with a
+  // visibility check via getComputedStyle when available.
+  if (typeof window !== 'undefined' && window.getComputedStyle) {
+    const style = window.getComputedStyle(el);
+    if (style.visibility === 'hidden' || style.display === 'none') {
+      return false;
+    }
+  }
+  return true;
+}
 
 /**
  * Get all focusable elements within a container.
  */
 function getFocusableElements(container) {
-  return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR));
+  return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter(isVisiblyFocusable);
 }
 
 /**
@@ -171,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;
       }
@@ -208,6 +289,9 @@ export function useFocusTrap(options) {
     document.addEventListener('keydown', handleKeyDown);
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
+      if (onEscape) {
+        removeEscapeHandler(escapeHandler);
+      }
     };
   }, [isActive, onEscape]);
   return {