@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/dist/HoverCard/HoverCard.js

@@ -21,6 +21,45 @@ import { useHoverCard } from "./useHoverCard.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars } from "../theme/tokens.stylex.js";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// `aria-haspopup` and `aria-controls` are global, so any trigger may carry
+// them. `aria-expanded` is not. This is the ARIA 1.2 "Supported States and
+// Properties" list for it — deliberately the narrow reading: axe accepts the
+// attribute on rather more roles, since it also allows every subclass of these,
+// so a role outside this set is not necessarily a violation. Widening it is
+// safe; the set is a floor, not the spec's ceiling. The same rule is applied in
+// Chat/useTriggerMenu.tsx, which only emits the combobox attributes once the
+// element is actually a combobox.
+const EXPANDABLE_ROLES = new Set(['application', 'button', 'checkbox', 'columnheader', 'combobox', 'gridcell', 'link', 'listbox', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'row', 'rowheader', 'switch', 'tab', 'treeitem']);
+const BUTTON_INPUT_TYPES = new Set(['button', 'submit', 'reset', 'image']);
+
+// Deliberately partial, and unlisted elements are read as role-less: dropping
+// aria-expanded where it might have been legal costs an AT user a state they
+// can still infer, whereas emitting it where it is illegal is a critical
+// aria-allowed-attr defect.
+function supportsAriaExpanded(el) {
+  const explicit = el.getAttribute('role')?.trim().split(/\s+/)[0];
+  if (explicit) {
+    return EXPANDABLE_ROLES.has(explicit);
+  }
+  switch (el.tagName) {
+    case 'BUTTON':
+    case 'SUMMARY':
+      return true;
+    case 'A':
+    case 'AREA':
+      return el.hasAttribute('href');
+    case 'INPUT':
+      // The button-flavoured input types map to role="button"; every other
+      // type maps to a textbox-family role, which does not take it.
+      return BUTTON_INPUT_TYPES.has(el.type?.toLowerCase());
+    case 'SELECT':
+      // combobox when it is a single-line picker, listbox otherwise; both
+      // support aria-expanded.
+      return true;
+    default:
+      return false;
+  }
+}
 /**
  * Check if children are text-only (no React elements)
  */
@@ -115,8 +154,65 @@ export function HoverCard({
 
     // Use combined ref for position + interaction
     hoverCard.ref(firstChild);
+    if (label) {
+      // When named, the hover card is a dialog. The trigger should advertise the
+      // popup relationship with aria-haspopup/aria-expanded, not describe the
+      // trigger with the dialog's content (aria-describedby is for plain-text
+      // descriptions, not navigable regions). See #5049.
+      //
+      // aria-expanded only goes on a trigger whose role permits it. A role-less
+      // trigger (Timestamp's <time>/<span>) gets haspopup + controls, which are
+      // global, and no expanded state.
+      //
+      // Merge rather than overwrite: the trigger may already carry its own
+      // popup semantics (e.g. a menu button wrapped in a labelled HoverCard),
+      // so preserve the existing values and restore them on cleanup.
+      const existingHaspopup = firstChild.getAttribute('aria-haspopup');
+      const existingControls = firstChild.getAttribute('aria-controls');
+      const existingExpanded = firstChild.getAttribute('aria-expanded');
+      const canExpand = supportsAriaExpanded(firstChild);
+      firstChild.setAttribute('aria-haspopup', 'dialog');
+      // Only point aria-controls at the layer while it is open and in the DOM.
+      // While closed, useLayer leaves only an inert <template> marker, so the
+      // id would reference nothing. DateInput gates it the same way. The
+      // trigger's own aria-controls (if any) is preserved either way.
+      if (hoverCard.isOpen) {
+        firstChild.setAttribute('aria-controls', mergeIds(existingControls, hoverCard.id) ?? '');
+      } else if (existingControls) {
+        firstChild.setAttribute('aria-controls', existingControls);
+      } else {
+        firstChild.removeAttribute('aria-controls');
+      }
+      if (canExpand) {
+        firstChild.setAttribute('aria-expanded', String(hoverCard.isOpen));
+      } else if (existingExpanded) {
+        firstChild.setAttribute('aria-expanded', existingExpanded);
+      } else {
+        firstChild.removeAttribute('aria-expanded');
+      }
+      return () => {
+        hoverCard.ref(null);
+        if (existingHaspopup) {
+          firstChild.setAttribute('aria-haspopup', existingHaspopup);
+        } else {
+          firstChild.removeAttribute('aria-haspopup');
+        }
+        if (existingControls) {
+          firstChild.setAttribute('aria-controls', existingControls);
+        } else {
+          firstChild.removeAttribute('aria-controls');
+        }
+        if (existingExpanded) {
+          firstChild.setAttribute('aria-expanded', existingExpanded);
+        } else {
+          firstChild.removeAttribute('aria-expanded');
+        }
+      };
+    }
 
-    // Set aria-describedby, merging with existing
+    // Unnamed fallback: the popup remains role="group", which is not a dialog,
+    // so keep the previous description relationship until a naming decision is
+    // made for the no-label case (tracked in #5049).
     const existingDescribedBy = firstChild.getAttribute('aria-describedby');
     firstChild.setAttribute('aria-describedby', mergeIds(existingDescribedBy, hoverCard.describedBy) ?? '');
     return () => {
@@ -127,7 +223,7 @@ export function HoverCard({
         firstChild.removeAttribute('aria-describedby');
       }
     };
-  }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
+  }, [textOnly, label, hoverCard.ref, hoverCard.id, hoverCard.isOpen, hoverCard.describedBy]);
 
   // While closed, useLayer leaves only an inert <template> marker at this JSX
   // position. When the card needs to open, it uses that marker to keep the
@@ -145,7 +241,12 @@ export function HoverCard({
       children: [/*#__PURE__*/_jsx("span", {
         ref: hoverCard.ref,
         tabIndex: 0,
-        "aria-describedby": hoverCard.describedBy,
+        "aria-haspopup": label ? 'dialog' : undefined,
+        "aria-controls": label && hoverCard.isOpen ? hoverCard.id : undefined
+        // No aria-expanded: this wrapper is a role-less <span>, and
+        // aria-expanded is invalid on it (see EXPANDABLE_ROLES above).
+        ,
+        "aria-describedby": label ? undefined : hoverCard.describedBy,
         ...{
           0: {
             className: "xt0psk2"

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;
     /**
@@ -119,10 +124,22 @@ export interface HoverCardReturn {
      */
     anchorId: string;
     /**
-     * ID for aria-describedby on the trigger element.
-     * Caller should compose with other IDs using mergeIds utility.
+     * Unique ID for the hover card container.
+     * Useful for `aria-controls` or `aria-owns` on the trigger.
+     */
+    id: string;
+    /**
+     * Deprecated alias of `id`. Kept for backwards compatibility; prefer `id`.
      */
     describedBy: string;
+    /**
+     * Whether the hover card is currently open.
+     * Useful for driving `aria-expanded` on the trigger — but only when the
+     * trigger's role permits it (`button`, `link`, `combobox`, …). On a role-less
+     * trigger `aria-expanded` is invalid; use `aria-haspopup`/`aria-controls`
+     * alone there.
+     */
+    isOpen: boolean;
     /**
      * Render function for hover card content.
      * Returns anchor-positioned popover element.

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,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;;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,CAib5E"}

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/gestureCounter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Identifies the user gesture in flight. Two reads returning the same value
+ * happened within one press (or one keystroke).
+ */
+export declare function currentGesture(): number;
+/** Whether the click belonging to the current gesture already bubbled. */
+export declare function currentGestureHasClicked(): boolean;
+//# sourceMappingURL=gestureCounter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gestureCounter.d.ts","sourceRoot":"","sources":["../../src/Layer/gestureCounter.ts"],"names":[],"mappings":"AA2CA;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,IAAI,OAAO,CAGlD"}

package/dist/Layer/gestureCounter.js

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file gestureCounter.ts
+ * @input Listens for pointerdown, keydown, and click on the document
+ * @output Exports the current gesture identity and whether its click has run
+ * @position Internal to Layer; used by useLayer to tell a click that belongs
+ *   to a dismissing press from a fresh one
+ *
+ * A browser light-dismiss and the trigger's own click come from ONE press, and
+ * which of them React sees first is a race. Comparing timestamps against a
+ * window guesses; counting gestures does not. The counter advances on every
+ * new press or keystroke, so "the click from the gesture that dismissed the
+ * layer" is exactly "the click while the counter still reads what it read at
+ * the dismissal", no matter how long the main thread was blocked in between.
+ */
+let gesture = 0;
+let clickedGesture = null;
+let isListening = false;
+function advance() {
+  gesture += 1;
+}
+function markClicked() {
+  clickedGesture = gesture;
+}
+function listen() {
+  if (isListening || typeof document === 'undefined') {
+    return;
+  }
+  isListening = true;
+  // Capture phase: the count must advance before any handler reads it.
+  document.addEventListener('pointerdown', advance, true);
+  document.addEventListener('keydown', advance, true);
+  // Capture phase observes the click even when a consumer stops propagation.
+  document.addEventListener('click', markClicked, true);
+}
+
+/**
+ * Identifies the user gesture in flight. Two reads returning the same value
+ * happened within one press (or one keystroke).
+ */
+export function currentGesture() {
+  listen();
+  return gesture;
+}
+
+/** Whether the click belonging to the current gesture already bubbled. */
+export function currentGestureHasClicked() {
+  listen();
+  return clickedGesture === gesture;
+}

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';