@astryxdesign/core 0.4.7 → 0.5.0-canary.32a62fd

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,14 +342,27 @@ 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]);
 
   // Render function that wraps layer.render with hover card behavior
   const renderHoverCard = useCallback((children, props) => {
     const renderPlacement = props?.placement ?? placement;
-    const themeClassName = themeProps('hovercard').className;
+    const themeClassName = themeProps('hover-card', undefined, {
+      // `hovercard` ran the compound name together; themes styling it keep
+      // working until the next major.
+      legacyNames: ['hovercard']
+    }).className;
     const renderProps = {
       placement: renderPlacement,
       alignment: props?.alignment ?? alignment,
@@ -343,20 +403,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;
@@ -383,7 +429,9 @@ export function useHoverCard(options = {}) {
     positionRef: layer.ref,
     interactionRef,
     anchorId: layer.anchorId,
+    id: layer.id,
     describedBy: layer.id,
+    isOpen: layer.isOpen,
     renderHoverCard,
     show: layer.show,
     hide: layer.hide

package/dist/Indicator/CheckboxIndicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CheckboxIndicator.d.ts","sourceRoot":"","sources":["../../src/Indicator/CheckboxIndicator.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAwI5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,IAAW,EACX,UAAkB,EAClB,QAAQ,EACR,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,IAAI,EACR,EAAE,cAAc,CAAC,gBAAgB,CAAC,+BAwElC;yBAlFe,iBAAiB"}
+{"version":3,"file":"CheckboxIndicator.d.ts","sourceRoot":"","sources":["../../src/Indicator/CheckboxIndicator.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAwI5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,IAAW,EACX,UAAkB,EAClB,QAAQ,EACR,GAAG,EACH,SAAS,EACT,KAAK,EACL,MAAM,EACN,GAAG,IAAI,EACR,EAAE,cAAc,CAAC,gBAAgB,CAAC,+BA8ElC;yBAxFe,iBAAiB"}

package/dist/Indicator/CheckboxIndicator.js

@@ -155,7 +155,9 @@ export function CheckboxIndicator({
     children: isRenderable(children) ? children : /*#__PURE__*/_jsxs(_Fragment, {
       children: [/*#__PURE__*/_jsx("svg", {
         viewBox: "0 0 10 10",
-        ...stylex.props(styles.checkmark, checkmarkSizeStyles[size], isChecked && styles.checkmarkVisible),
+        ...mergeProps(themeProps('checkbox-indicator-check', {
+          size
+        }), stylex.props(styles.checkmark, checkmarkSizeStyles[size], isChecked && styles.checkmarkVisible)),
         children: /*#__PURE__*/_jsx("path", {
           d: "M8.5 2.5L4 7.5L1.5 5",
           stroke: "currentColor",
@@ -165,7 +167,9 @@ export function CheckboxIndicator({
           strokeLinejoin: "round"
         })
       }), /*#__PURE__*/_jsx("span", {
-        ...stylex.props(styles.indeterminateMark, indeterminateSizeStyles[size], isIndeterminate && styles.indeterminateMarkVisible)
+        ...mergeProps(themeProps('checkbox-indicator-dash', {
+          size
+        }), stylex.props(styles.indeterminateMark, indeterminateSizeStyles[size], isIndeterminate && styles.indeterminateMarkVisible))
       })]
     })
   });

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;AAIlD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA0G5C,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

@@ -15,6 +15,7 @@
 import React, { useSyncExternalStore } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { mergeProps } from "../utils/index.js";
+import { isApplePlatform } from "../utils/isApplePlatform.js";
 import { themeProps } from "../utils/themeProps.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, radiusVars, typographyVars, fontWeightVars, typeScaleVars } from "../theme/tokens.stylex.js";
@@ -98,24 +99,6 @@ function subscribeToPlatformChanges() {
 function getServerPlatformSnapshot() {
   return false;
 }
-
-/**
- * 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).
- */
-function detectMac() {
-  if (typeof navigator === 'undefined') {
-    return false;
-  }
-  // 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 ?? '');
-  }
-  // Fallback: navigator.platform (deprecated but still shipped everywhere)
-  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
-}
 /**
  * Displays a keyboard shortcut as styled <kbd> elements.
  *
@@ -139,7 +122,7 @@ export function Kbd({
   style,
   ...rest
 }) {
-  const isMac = useSyncExternalStore(subscribeToPlatformChanges, detectMac, getServerPlatformSnapshot);
+  const isMac = useSyncExternalStore(subscribeToPlatformChanges, isApplePlatform, getServerPlatformSnapshot);
   const parts = keys.split('+').map(key => key.trim().toLowerCase());
 
   // Screen-reader name: the joined spoken labels (e.g. "Command + K"), since

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"}