@astryxdesign/core 0.4.6 → 0.4.7-canary.20bae6c

package/dist/Heading/Heading.js

@@ -21,7 +21,8 @@ import * as stylex from '@stylexjs/stylex';
 import { colorStyles, sizeByLevelStyles, sizeByTypeStyles, defaultWeightByTypeStyles, displayStyles, justifyStyles, truncationStyles, wordBreakStyles, textWrapStyles, capsizeStyles, decorationStyles, truncationTooltipStyles } from "../Text/text.stylex.js";
 import { useTruncation } from "../Text/useTruncation.js";
 import { resolveStyleColor } from "../Text/Text.js";
-import { mergeProps, mergeRefs } from "../utils/index.js";
+import { mergeProps } from "../utils/index.js";
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { themeProps } from "../utils/themeProps.js";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 const LazyXDSTooltip = /*#__PURE__*/lazy(async () => import("../Tooltip/Tooltip.js").then(mod => ({
@@ -107,13 +108,16 @@ export function Heading({
   // Ref for the heading element (used as tooltip anchor)
   const headingRef = useRef(null);
 
+  // Keep the merged ref stable across rerenders.
+  const mergedRef = useMergedRefs(ref, truncation.ref, headingRef);
+
   // Build inline style for -webkit-line-clamp (dynamic value)
   const inlineStyle = maxLines > 1 ? {
     WebkitLineClamp: maxLines
   } : undefined;
   return /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Component, {
-      ref: mergeRefs(ref, truncation.ref, headingRef),
+      ref: mergedRef,
       ...mergeProps(themeProps('heading', {
         level,
         color,

package/dist/HoverCard/HoverCard.d.ts

@@ -97,6 +97,12 @@ export interface HoverCardProps extends Pick<BaseProps, 'xstyle' | 'className' |
      * - `true`: force-show the hover card (hover/focus hide is suppressed)
      * - `false`: force-hide the hover card
      * - `undefined`: uncontrolled — hover/focus triggers manage visibility
+     *
+     * A controlled hover card still takes Escape when it is the top-most layer,
+     * and answers by calling `onOpenChange(false)` without hiding itself —
+     * closing is your update's decision, exactly as for a controlled Dialog.
+     * Ignore the call and the card stays, and so does the press: nothing
+     * underneath dismisses.
      */
     isOpen?: boolean;
     /**

package/dist/HoverCard/HoverCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/HoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG7E,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,YAAY,EACV,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAiBxB,MAAM,WAAW,cAAe,SAAQ,IAAI,CAC1C,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,OAAO,EACP,SAAmB,EACnB,SAAoB,EACpB,KAAW,EACX,SAAe,EACf,YAAqB,EACrB,YAAqB,EACrB,SAAgB,EAChB,KAAK,EACL,YAAY,EACZ,kBAA2B,EAC3B,MAAM,EACN,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CA0G/B;yBA5He,SAAS"}
+{"version":3,"file":"HoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/HoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG7E,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,YAAY,EACV,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAiBxB,MAAM,WAAW,cAAe,SAAQ,IAAI,CAC1C,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEtC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,OAAO,EACP,SAAmB,EACnB,SAAoB,EACpB,KAAW,EACX,SAAe,EACf,YAAqB,EACrB,YAAqB,EACrB,SAAgB,EAChB,KAAK,EACL,YAAY,EACZ,kBAA2B,EAC3B,MAAM,EACN,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CA0G/B;yBA5He,SAAS"}

package/dist/HoverCard/useHoverCard.d.ts

@@ -78,6 +78,11 @@ export interface HoverCardOptions {
      * - `true`: force-show the hover card (hover/focus hide is suppressed)
      * - `false`: force-hide the hover card
      * - `undefined`: uncontrolled — hover/focus triggers manage visibility
+     *
+     * A controlled hover card still takes Escape when it is the top-most layer,
+     * and answers by calling `onHide` without hiding itself — closing is your
+     * update's decision, exactly as for a controlled Dialog. Ignore the call and
+     * the card stays, and so does the press: nothing underneath dismisses.
      */
     isOpen?: boolean;
     /**

package/dist/HoverCard/useHoverCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useHoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/useHoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,OAAO,CAAC;AAEf,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AA4BlC;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAE9B;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEtC;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;;OAOG;IACH,eAAe,EAAE,CACf,QAAQ,EAAE,SAAS,EACnB,KAAK,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,KAC5C,SAAS,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA8X5E"}
+{"version":3,"file":"useHoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/useHoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,OAAO,CAAC;AAEf,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AA6BlC;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAE9B;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEtC;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;;OAOG;IACH,eAAe,EAAE,CACf,QAAQ,EAAE,SAAS,EACnB,KAAK,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,KAC5C,SAAS,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA2a5E"}

package/dist/HoverCard/useHoverCard.js

@@ -16,6 +16,7 @@ import * as stylex from '@stylexjs/stylex';
 import { useLayer } from "../Layer/useLayer.js";
 import { useTouchTrigger } from "../Layer/useTouchTrigger.js";
 import { layerAnimations } from "../Layer/layerAnimations.stylex.js";
+import { useLayerDismissal } from "../Layer/useLayerDismissal.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, shadowVars, radiusVars, spacingVars } from "../theme/tokens.stylex.js";
 import { themeProps } from "../utils/themeProps.js";
@@ -216,16 +217,66 @@ export function useHoverCard(options = {}) {
     }
     scheduleHide();
   }, [layer.id, scheduleHide]);
-  const handleKeyDown = useCallback(e => {
-    if (e.key === 'Escape') {
-      // Stop propagation so parent components don't react to the same Escape
-      e.stopPropagation();
-      // Hide immediately without refocusing (we're already on trigger)
+
+  // Escape dismissal (WCAG 1.4.13) goes through the shared layer stack: a
+  // visible card is the top-most layer, so it takes the press and consumes it.
+  //
+  // This replaces a keydown listener on the TRIGGER that called
+  // stopPropagation() on any Escape while the trigger merely had focus — open
+  // card or not — so focusing a HoverCard trigger inside a Dialog silently ate
+  // the press that should have closed the Dialog. Presence is now answered from
+  // the DOM, so a closed card never claims a press.
+  // A controlled hover card stays on the stack and takes the press like any
+  // other layer, but answers it by reporting instead of hiding: `isOpen` is
+  // the consumer's value, so only their update may change it. Same contract as
+  // a controlled Dialog.
+  useLayerDismissal({
+    // Registered for the hook's lifetime rather than gated on `layer.isOpen`:
+    // that state can lag a frame behind the DOM, so a press arriving right after
+    // the layer appears would find nothing registered. Because this layer
+    // CONSUMES the press, a stale registration would be worse than a missed one
+    // — it would silently eat Escapes meant for the dialog underneath — so
+    // presence is answered from the DOM at press time instead of from state.
+    isActive: true,
+    isPresent: () => {
+      const el = typeof document === 'undefined' ? null : document.getElementById(layer.id);
+      if (el == null) {
+        return false;
+      }
+      try {
+        return el.matches(':popover-open');
+      } catch {
+        // Browsers without the Popover API (and some test environments) cannot
+        // answer the selector; fall back to the hook's own state.
+        return layer.isOpen;
+      }
+    },
+    onDismiss: () => {
       clearTimeouts();
       touch.clearTapOpen();
+      // Controlled: report and stop. The close — and the focus restore that
+      // goes with it — happens in the controlled effect if and when the
+      // consumer flips `isOpen`.
+      if (isOpen !== undefined) {
+        onHide?.();
+        return;
+      }
+      // Only when the card itself held focus, which is the one case the
+      // content-level handler this replaced could run in. Refocusing
+      // unconditionally would drag the caret out of a field the user was
+      // typing in while a hover card happened to be up; arming the re-show
+      // guard unconditionally would swallow their next focus on the trigger,
+      // because a focus() on the already-focused trigger fires no focusin to
+      // clear it.
+      const card = typeof document === 'undefined' ? null : document.getElementById(layer.id);
+      const hadFocus = card?.contains(document.activeElement) ?? false;
       layer.hide();
+      if (hadFocus) {
+        isEscapeDismissingRef.current = true;
+        triggerRef.current?.focus();
+      }
     }
-  }, [touch, clearTimeouts, layer]);
+  });
 
   // Interaction ref that handles event listeners only
   const {
@@ -238,7 +289,6 @@ export function useHoverCard(options = {}) {
       triggerRef.current.removeEventListener('mouseleave', handleMouseLeave);
       triggerRef.current.removeEventListener('focusin', handleFocusIn);
       triggerRef.current.removeEventListener('focusout', handleFocusOut);
-      triggerRef.current.removeEventListener('keydown', handleKeyDown);
       triggerRef.current.removeEventListener('pointerenter', handlePointerEnter);
       triggerRef.current.removeEventListener('pointerdown', handlePointerDown);
     }
@@ -257,12 +307,9 @@ export function useHoverCard(options = {}) {
         el.addEventListener('focusin', handleFocusIn);
         el.addEventListener('focusout', handleFocusOut);
       }
-
-      // Attach keydown for Escape handling
-      el.addEventListener('keydown', handleKeyDown);
     }
     triggerRef.current = el;
-  }, [focusTrigger, handleMouseEnter, handleMouseLeave, handleFocusIn, handleFocusOut, handleKeyDown, handlePointerEnter, handlePointerDown]);
+  }, [focusTrigger, handleMouseEnter, handleMouseLeave, handleFocusIn, handleFocusOut, handlePointerEnter, handlePointerDown]);
 
   // Combined ref - shorthand for calling both positionRef and interactionRef
   const ref = useCallback(el => {
@@ -295,7 +342,16 @@ export function useHoverCard(options = {}) {
       layer.show();
     } else {
       clearTimeouts();
+      // A consumer closing the card while it holds focus would strand focus on
+      // <body>. Arming the re-show guard is what keeps the refocus from
+      // reopening the card through `handleFocusIn`, which shows on any focusin.
+      const card = typeof document === 'undefined' ? null : document.getElementById(layer.id);
+      const hadFocus = card?.contains(document.activeElement) ?? false;
       layer.hide();
+      if (hadFocus) {
+        isEscapeDismissingRef.current = true;
+        triggerRef.current?.focus();
+      }
     }
   }, [isOpen, clearTimeouts, layer]);
 
@@ -343,20 +399,6 @@ export function useHoverCard(options = {}) {
         isHoveringContentRef.current = false;
         scheduleHide();
       },
-      onKeyDown: e => {
-        if (e.key === 'Escape') {
-          // Stop propagation so parent components don't react to the same Escape
-          e.stopPropagation();
-          // Set flag to prevent re-show when we refocus trigger
-          isEscapeDismissingRef.current = true;
-          // Hide immediately
-          clearTimeouts();
-          touch.clearTapOpen();
-          layer.hide();
-          // Refocus the trigger
-          triggerRef.current?.focus();
-        }
-      },
       onBlur: e => {
         // Check if focus is moving back to the trigger or staying within content
         const relatedTarget = e.relatedTarget;

package/dist/Item/Item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Item.d.ts","sourceRoot":"","sources":["../../src/Item/Item.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAa5C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,WAAW,CAAC;IACvD,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;OAGG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAE9B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAErD;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+LD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,EACnB,EAAE,EAAE,SAAiB,EACrB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,WAAW,EACX,UAAU,EACV,KAAgB,EAChB,OAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,MAAkB,EAClB,OAAO,EACP,cAAc,EACd,IAAI,EACJ,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,YAAY,EACjB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,IAAI,EACJ,GAAG,SAAS,EACb,EAAE,SAAS,+BAqNX;yBA/Oe,IAAI"}
+{"version":3,"file":"Item.d.ts","sourceRoot":"","sources":["../../src/Item/Item.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU7C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAc5C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC3C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,SAAU,SAAQ,SAAS,CAAC,WAAW,CAAC;IACvD,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;OAGG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAE9B;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAErD;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA+LD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,EACnB,EAAE,EAAE,SAAiB,EACrB,MAAM,EACN,YAAY,EACZ,KAAK,EACL,WAAW,EACX,UAAU,EACV,KAAgB,EAChB,OAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,MAAkB,EAClB,OAAO,EACP,cAAc,EACd,IAAI,EACJ,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,YAAY,EACjB,aAAqB,EACrB,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,IAAI,EACJ,GAAG,SAAS,EACb,EAAE,SAAS,+BAqNX;yBA/Oe,IAAI"}

package/dist/Item/Item.js

@@ -19,7 +19,8 @@ import { useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, radiusVars, spacingVars, durationVars, easeVars, typeScaleVars } from "../theme/tokens.stylex.js";
-import { mergeProps, mergeRefs } from "../utils/index.js";
+import { mergeProps } from "../utils/index.js";
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { computeTargetAndRel } from "../Link/computeTargetAndRel.js";
 import { useLinkComponent } from "../Link/useLinkComponent.js";
 import { useClickableContainer } from "../hooks/useClickableContainer.js";
@@ -352,8 +353,9 @@ export function Item({
       children: endContent
     })]
   });
+  const mergedRef = useMergedRefs(ref, containerRef);
   return /*#__PURE__*/_jsx(Component, {
-    ref: isDelegate ? mergeRefs(ref, containerRef) : ref,
+    ref: isDelegate ? mergedRef : ref,
     ...restProps,
     "aria-selected": allowsAriaSelected && isSelected || undefined
     // aria-selected is invalid on roles that don't permit it (listitem, a

package/dist/Kbd/Kbd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Kbd.d.ts","sourceRoot":"","sources":["../../src/Kbd/Kbd.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAGlD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA4H5C,MAAM,WAAW,QAAS,SAAQ,SAAS,CAAC,eAAe,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAAC,EAAE,QAAQ,qBAgC3E;yBAhCe,GAAG"}
+{"version":3,"file":"Kbd.d.ts","sourceRoot":"","sources":["../../src/Kbd/Kbd.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAGlD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAmI5C,MAAM,WAAW,QAAS,SAAQ,SAAS,CAAC,eAAe,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAAC,EAAE,QAAQ,qBAgC3E;yBAhCe,GAAG"}

package/dist/Kbd/Kbd.js

@@ -101,8 +101,9 @@ function getServerPlatformSnapshot() {
 
 /**
  * Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
- * falls back to navigator.platform (deprecated but universally supported).
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it is absent or blank.
  */
 function detectMac() {
   if (typeof navigator === 'undefined') {
@@ -111,7 +112,13 @@ function detectMac() {
   // Prefer User-Agent Client Hints API (not deprecated)
   const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
   if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
-    return /mac/i.test(uaData.platform ?? '');
+    const uaPlatform = uaData.platform;
+    // A blank platform is no answer, not a negative one. Builds that rewrite
+    // their client-hints identity ship '', so fall through rather than
+    // reading it as "not Apple".
+    if (typeof uaPlatform === 'string' && uaPlatform.trim() !== '') {
+      return /mac/i.test(uaPlatform);
+    }
   }
   // Fallback: navigator.platform (deprecated but still shipped everywhere)
   return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');

package/dist/Layer/LayerDepthContext.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file LayerDepthContext.tsx
+ * @input React context
+ * @output Exports LayerDepthContext, useLayerDepth, LayerDepthProvider
+ * @position Layer system; how the dismissal stack learns which layer is nested
+ *   inside which.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/index.ts
+ * - /packages/core/src/Layer/useLayerDismissal.ts
+ *
+ * Nesting is read from the React tree rather than the DOM. Two reasons:
+ *
+ * - **Portals.** A nested overlay routinely renders into `document.body` or the
+ *   native top layer, so DOM containment reports it as a sibling of the layer
+ *   it is logically inside. React context flows through `createPortal`, so the
+ *   tree keeps the relationship the DOM loses.
+ * - **Same-commit mounts.** Depth is fixed during render. Effect order is not
+ *   available then and is misleading anyway: React runs child effects before
+ *   parent effects, so an inner layer registers first and looks "older" than
+ *   the outer layer that contains it.
+ *
+ * There is nothing to mount at the app root: the context defaults to 0, and
+ * each layer provides depth for its OWN content, so nesting composes on its own.
+ */
+import { type ReactNode } from 'react';
+/**
+ * How many layers deep the current subtree is. 0 at the app root; each layer
+ * increments it for its own content.
+ */
+export declare const LayerDepthContext: import("react").Context<number>;
+/**
+ * Read the current nesting depth. A layer calls this to learn its OWN depth —
+ * the depth of the subtree it is rendered into, before it pushes its content
+ * one level deeper.
+ */
+export declare function useLayerDepth(): number;
+/**
+ * Wrap a layer's content so any layer opened from inside it registers as
+ * nested. Takes no depth prop on purpose: it reads the ambient depth and adds
+ * one, so nesting composes without anyone tracking absolute numbers.
+ *
+ * Renders no DOM element — it is a context boundary only, which is why it takes
+ * no `xstyle`/`ref` and exposes no props interface.
+ */
+export declare function LayerDepthProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare namespace LayerDepthProvider {
+    var displayName: string;
+}
+//# sourceMappingURL=LayerDepthContext.d.ts.map

package/dist/Layer/LayerDepthContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayerDepthContext.d.ts","sourceRoot":"","sources":["../../src/Layer/LayerDepthContext.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAqB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,iCAAmB,CAAC;AAGlD;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAC,QAAQ,EAAC,EAAE;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAC,+BAGnE;yBAHe,kBAAkB"}

package/dist/Layer/LayerDepthContext.js

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file LayerDepthContext.tsx
+ * @input React context
+ * @output Exports LayerDepthContext, useLayerDepth, LayerDepthProvider
+ * @position Layer system; how the dismissal stack learns which layer is nested
+ *   inside which.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/index.ts
+ * - /packages/core/src/Layer/useLayerDismissal.ts
+ *
+ * Nesting is read from the React tree rather than the DOM. Two reasons:
+ *
+ * - **Portals.** A nested overlay routinely renders into `document.body` or the
+ *   native top layer, so DOM containment reports it as a sibling of the layer
+ *   it is logically inside. React context flows through `createPortal`, so the
+ *   tree keeps the relationship the DOM loses.
+ * - **Same-commit mounts.** Depth is fixed during render. Effect order is not
+ *   available then and is misleading anyway: React runs child effects before
+ *   parent effects, so an inner layer registers first and looks "older" than
+ *   the outer layer that contains it.
+ *
+ * There is nothing to mount at the app root: the context defaults to 0, and
+ * each layer provides depth for its OWN content, so nesting composes on its own.
+ */
+import { createContext, use } from 'react';
+
+/**
+ * How many layers deep the current subtree is. 0 at the app root; each layer
+ * increments it for its own content.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export const LayerDepthContext = /*#__PURE__*/createContext(0);
+LayerDepthContext.displayName = 'LayerDepthContext';
+
+/**
+ * Read the current nesting depth. A layer calls this to learn its OWN depth —
+ * the depth of the subtree it is rendered into, before it pushes its content
+ * one level deeper.
+ */
+export function useLayerDepth() {
+  return use(LayerDepthContext);
+}
+
+/**
+ * Wrap a layer's content so any layer opened from inside it registers as
+ * nested. Takes no depth prop on purpose: it reads the ambient depth and adds
+ * one, so nesting composes without anyone tracking absolute numbers.
+ *
+ * Renders no DOM element — it is a context boundary only, which is why it takes
+ * no `xstyle`/`ref` and exposes no props interface.
+ */
+export function LayerDepthProvider({
+  children
+}) {
+  const depth = use(LayerDepthContext);
+  return /*#__PURE__*/_jsx(LayerDepthContext, {
+    value: depth + 1,
+    children: children
+  });
+}
+LayerDepthProvider.displayName = 'LayerDepthProvider';

package/dist/Layer/index.d.ts

@@ -13,6 +13,9 @@
  */
 export { useLayer } from './useLayer';
 export type { LayerAlignment, LayerPlacement, ContextRenderProps, FixedRenderProps, ContextLayerOptions, FixedLayerOptions, ContextLayerReturn, FixedLayerReturn, } from './useLayer';
+export { useLayerDismissal } from './useLayerDismissal';
+export type { LayerEscapeBehavior, UseLayerDismissalOptions, UseLayerDismissalReturn, } from './useLayerDismissal';
+export { LayerDepthProvider } from './LayerDepthContext';
 export { useTouchTrigger, isActionTrigger } from './useTouchTrigger';
 export type { LayerTouchTrigger, UseTouchTriggerOptions, UseTouchTriggerReturn, } from './useTouchTrigger';
 export { LayerProvider } from './LayerProvider';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Layer/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EACV,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAC,eAAe,EAAE,eAAe,EAAC,MAAM,mBAAmB,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAC,YAAY,EAAE,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAC7D,YAAY,EAAC,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EAAC,eAAe,EAAC,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAC,UAAU,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAC,YAAY,EAAE,SAAS,EAAC,MAAM,cAAc,CAAC;AACrD,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,cAAc,GACf,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAC,UAAU,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Layer/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AACpC,YAAY,EACV,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAC,kBAAkB,EAAC,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAC,eAAe,EAAE,eAAe,EAAC,MAAM,mBAAmB,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAC,YAAY,EAAE,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAC7D,YAAY,EAAC,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EAAC,eAAe,EAAC,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAC,UAAU,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAC,YAAY,EAAE,SAAS,EAAC,MAAM,cAAc,CAAC;AACrD,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,cAAc,GACf,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAC,UAAU,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/Layer/index.js

@@ -18,6 +18,10 @@
 
 // Core layer hook (remains in Layer)
 export { useLayer } from "./useLayer.js";
+// Layer dismissal stack — one Escape owner for every overlay family
+export { useLayerDismissal } from "./useLayerDismissal.js";
+export { LayerDepthProvider } from "./LayerDepthContext.js";
+
 // Shared touch behavior for the hover layers
 export { useTouchTrigger, isActionTrigger } from "./useTouchTrigger.js";
 // Layer provider

package/dist/Layer/layerStack.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What a layer does with an Escape press that reaches it.
+ *
+ * - `'close'` — dismiss this layer and consume the press. One Escape closes
+ *   exactly this layer. The default, and correct for every dismissible layer:
+ *   modals, popovers, menus, comboboxes, and hover layers alike.
+ * - `'block'` — consume the press WITHOUT dismissing. For a layer that requires
+ *   an explicit choice (`Dialog purpose="required"`): Escape must not dismiss
+ *   it, and must not fall through and dismiss something behind it either.
+ *
+ * There is deliberately no "dismiss but let the press continue" variant. Escape
+ * affects exactly one layer, always — a rule with no per-component exceptions
+ * is one users can predict. Hover layers were the tempting exception (the user
+ * never opened the tip, so why should it eat their press?), but guessing wrong
+ * that way is destructive: someone dismissing a stray tooltip over a form would
+ * lose the whole dialog. Guessing wrong the other way costs one keystroke.
+ */
+export type LayerEscapeBehavior = 'close' | 'block';
+export interface LayerStackEntry {
+    /**
+     * Identity for removal; also the equality check for top-most, and the key
+     * `seq` is assigned against so a layer keeps its place across re-registration.
+     */
+    token: object;
+    /**
+     * Nesting depth from the React tree (see LayerDepthContext), NOT the DOM.
+     * Context flows through portals and is known during render, so it is correct
+     * for layers that portal out and for an inner + outer layer that open in the
+     * same commit — the case where effect order lies, because React runs child
+     * effects before parent effects.
+     */
+    depth: number;
+    /**
+     * Monotonic registration order; breaks ties between unrelated layers. For a
+     * layer that registers when it opens this is open order; a hover layer
+     * registers at mount and answers `isPresent` instead, so for two of those it
+     * is mount order rather than which one appeared first.
+     *
+     * Keyed to `token`, not to the registration, because a layer re-registers
+     * whenever its behavior or depth changes and must not overtake the layers
+     * above it.
+     */
+    seq: number;
+    behavior: LayerEscapeBehavior;
+    /**
+     * The layer's container element, read lazily at press time. Used only to
+     * break ties between layers the React tree reports at the same depth — a raw
+     * `useFocusTrap` cannot wrap its content in a depth provider (it renders
+     * nothing), so DOM containment is the only nesting signal those have.
+     */
+    getContainer?: () => HTMLElement | null;
+    /**
+     * Whether the layer is really on screen right now, asked at press time.
+     *
+     * Registration alone is not proof: a layer whose open state lives in React
+     * state can lag a frame behind the DOM, so gating registration on that state
+     * drops presses that arrive in the gap. Such layers register for their whole
+     * lifetime and answer this from the DOM instead. Omit it to mean "registered
+     * means present", which is true for layers that register on open.
+     */
+    isPresent?: () => boolean;
+    dismiss: () => void;
+}
+/**
+ * Whether the user is part-way through composing text with an IME.
+ *
+ * The stack reads this to decide what an Escape means, and layers read it
+ * through `useLayerDismissal`'s `shouldDismissOnCloseRequest` for the close
+ * requests that arrive without a keydown to inspect — the Android back
+ * gesture, the platform close watcher, or a composing Escape whose keydown
+ * never reached this listener because content stopped it. Mid-composition,
+ * those are far more likely to be the user backing out of a half-formed
+ * character than a request to dismiss a layer, and guessing wrong that way
+ * costs them everything they have typed into it.
+ *
+ * Scope, deliberately page-wide: a composition in a field behind a non-modal
+ * layer also suppresses that layer's close requests. It is one keypress to
+ * recover from, and the alternative — matching the composing element against
+ * a layer's container — cannot work for the layers that do not have one.
+ *
+ * A composition already running when the first layer registers is invisible
+ * here: the listeners go on with the stack's own.
+ */
+export declare function isTextComposing(): boolean;
+/**
+ * Whether `token` identifies the top-most layer. Overlays that still own a
+ * dismissal channel the stack does not model yet (outside-press, swipe) can
+ * gate on this so every channel agrees on who is on top.
+ */
+export declare function isTopmostLayer(token: object): boolean;
+/**
+ * Add a layer to the stack for as long as it is active. Returns the unregister
+ * function; callers own calling it.
+ */
+export declare function registerLayer(entry: Omit<LayerStackEntry, 'seq'>): () => void;
+/** Test-only: drop all entries and detach the listener. */
+export declare function resetLayerStackForTests(): void;
+//# sourceMappingURL=layerStack.d.ts.map

package/dist/Layer/layerStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layerStack.d.ts","sourceRoot":"","sources":["../../src/Layer/layerStack.ts"],"names":[],"mappings":"AAoEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACxC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA2ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AA2BD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAwED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI,CAc7E;AAED,2DAA2D;AAC3D,wBAAgB,uBAAuB,IAAI,IAAI,CAM9C"}