@astryxdesign/core 0.4.6 → 0.4.7-canary.019ae5a

package/src/DropdownMenu/DropdownMenuSubMenu.tsx

@@ -476,20 +476,17 @@ export function DropdownMenuSubMenu(
   );
 
   const endAffordance = hasSpinner ? (
-    <span
-      {...mergeProps(
-        themeProps('dropdown-menu-indicator-icon'),
-        stylex.props(triggerStyles.caret),
-      )}>
+    <span {...stylex.props(triggerStyles.caret)}>
       <Spinner size="sm" />
     </span>
   ) : (
-    <span
-      {...mergeProps(
-        themeProps('dropdown-menu-indicator-icon'),
-        stylex.props(triggerStyles.caret),
-      )}>
-      <Icon icon="chevronRight" size="sm" color="secondary" />
+    <span {...stylex.props(triggerStyles.caret)}>
+      <Icon
+        icon="chevronRight"
+        size="sm"
+        color="secondary"
+        {...themeProps('dropdown-menu-indicator-icon')}
+      />
     </span>
   );
 

package/src/Field/Field.doc.mjs

@@ -39,8 +39,8 @@ export const docs = {
     ],
     vars: [
       {name: '--_field-radius', description: 'Border radius of input fields', default: 'var(--radius-element)', private: true},
-      {name: '--_input-clear-hit-inset', description: 'Outset of the clear (\u2715) button\u2019s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
-      {name: '--_input-clear-hit-content', description: 'Whether the clear (\u2715) button\u2019s invisible hit overlay exists. `none` on a fine pointer, so no ::after is generated and hover still reaches the glyph; `""` on a coarse one, where the overlay provides the 24px touch target.', default: 'none', private: true},
+      {name: '--_input-clear-hit-inset', description: 'Outset of the clear (\u2715) button\'s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
+      {name: '--_input-clear-hit-content', description: 'Whether the clear (\u2715) button\'s invisible hit overlay exists. `none` on a fine pointer, so no ::after is generated and hover still reaches the glyph; `""` on a coarse one, where the overlay provides the 24px touch target.', default: 'none', private: true},
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_field-radius']},
@@ -60,6 +60,17 @@ export const docs = {
       description: 'ID for the input element (used for the label htmlFor attribute).',
       required: true,
     },
+    {
+      name: 'labelID',
+      type: 'string',
+      description: 'ID applied to the label element itself for group accessibility.',
+    },
+    {
+      name: 'isGroupLabel',
+      type: 'boolean',
+      description: 'Renders the label as a span for control groups (radiogroup, checkbox list).',
+      default: 'false',
+    },
     {
       name: 'children',
       type: 'ReactNode',

package/src/FileInput/FileInput.tsx

@@ -54,13 +54,14 @@ export type {
   InputStatus as FileInputStatus,
   InputStatusType as FileInputStatusType,
 } from '../Field';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 import type {TranslatorFn} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 function formatFileSize(bytes: number): string {
   if (bytes < 1024) {
     return `${bytes} B`;
@@ -827,7 +828,7 @@ export function FileInput({
         </VisuallyHidden>
         <input
           {...rest}
-          ref={mergeRefs(ref, inputRef)}
+          ref={useMergedRefs(ref, inputRef)}
           id={id}
           type="file"
           accept={accept}

package/src/Heading/Heading.test.tsx

@@ -6,7 +6,7 @@
  */
 
 import {render, screen} from '@testing-library/react';
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import {Heading} from './Heading';
 
 describe('Heading', () => {
@@ -16,6 +16,28 @@ describe('Heading', () => {
       expect(screen.getByText('Page Title')).toBeInTheDocument();
     });
 
+    it('keeps a forwarded ref attached across rerenders', () => {
+      const ref = vi.fn();
+      const {rerender} = render(
+        <Heading ref={ref} level={1}>
+          Before
+        </Heading>,
+      );
+
+      const element = screen.getByText('Before');
+      expect(ref).toHaveBeenLastCalledWith(element);
+      ref.mockClear();
+
+      rerender(
+        <Heading ref={ref} level={1}>
+          After
+        </Heading>,
+      );
+
+      expect(ref).not.toHaveBeenCalled();
+      expect(screen.getByText('After')).toBe(element);
+    });
+
     it('renders h1 for level 1', () => {
       render(<Heading level={1}>H1</Heading>);
       const element = screen.getByText('H1');

package/src/Heading/Heading.tsx

@@ -43,7 +43,8 @@ import {
 import {useTruncation} from '../Text/useTruncation';
 import {resolveStyleColor} from '../Text/Text';
 import type {LayerPlacement} from '../Layer';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
@@ -242,13 +243,16 @@ export function Heading({
   // Ref for the heading element (used as tooltip anchor)
   const headingRef = useRef<HTMLHeadingElement>(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 (
     <>
       <Component
-        ref={mergeRefs(ref, truncation.ref, headingRef)}
+        ref={mergedRef}
         {...mergeProps(
           themeProps('heading', {level, color, ...(type && {type})}),
           stylex.props(

package/src/HoverCard/HoverCard.doc.mjs

@@ -109,6 +109,11 @@ export const docs = {
           type: 'boolean',
           description: 'Whether the hover card should be shown on mount. Still dismissible.',
         },
+        {
+          name: 'isOpen',
+          type: 'boolean',
+          description: 'Controlled open state for the hover card.',
+        },
       ],
     },
   ],

package/src/HoverCard/HoverCard.tsx

@@ -144,6 +144,12 @@ export interface HoverCardProps extends Pick<
    * - `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/src/HoverCard/useHoverCard.tsx

@@ -31,6 +31,7 @@ import {
   type LayerTouchTrigger,
 } from '../Layer/useTouchTrigger';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {
   colorVars,
   shadowVars,
@@ -135,6 +136,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;
 
@@ -409,19 +415,71 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     [layer.id, scheduleHide],
   );
 
-  const handleKeyDown = useCallback(
-    (e: KeyboardEvent) => {
-      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)
-        clearTimeouts();
-        touch.clearTapOpen();
-        layer.hide();
+  // 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;
       }
     },
-    [touch, clearTimeouts, layer],
-  );
+    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();
+      }
+    },
+  });
 
   // Interaction ref that handles event listeners only
   const {handlePointerEnter} = touch;
@@ -436,7 +494,6 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
           'focusout',
           handleFocusOut as EventListener,
         );
-        triggerRef.current.removeEventListener('keydown', handleKeyDown);
         triggerRef.current.removeEventListener(
           'pointerenter',
           handlePointerEnter,
@@ -465,9 +522,6 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
           el.addEventListener('focusin', handleFocusIn);
           el.addEventListener('focusout', handleFocusOut as EventListener);
         }
-
-        // Attach keydown for Escape handling
-        el.addEventListener('keydown', handleKeyDown);
       }
 
       triggerRef.current = el;
@@ -478,7 +532,6 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       handleMouseLeave,
       handleFocusIn,
       handleFocusOut,
-      handleKeyDown,
       handlePointerEnter,
       handlePointerDown,
     ],
@@ -518,7 +571,19 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       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]);
 
@@ -576,20 +641,6 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
             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 as HTMLElement | null;

package/src/Item/Item.tsx

@@ -27,7 +27,8 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {computeTargetAndRel} from '../Link/computeTargetAndRel';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {useClickableContainer} from '../hooks/useClickableContainer';
@@ -579,11 +580,11 @@ export function Item({
     </>
   );
 
+  const mergedRef = useMergedRefs(ref, containerRef);
+
   return (
     <Component
-      ref={
-        (isDelegate ? mergeRefs(ref, containerRef) : ref) as React.Ref<never>
-      }
+      ref={(isDelegate ? mergedRef : ref) as React.Ref<never>}
       {...restProps}
       aria-selected={(allowsAriaSelected && isSelected) || undefined}
       // aria-selected is invalid on roles that don't permit it (listitem, a

package/src/Kbd/Kbd.test.tsx

@@ -23,6 +23,7 @@ describe('Kbd', () => {
       value: originalPlatform,
       configurable: true,
     });
+    delete (navigator as {userAgentData?: unknown}).userAgentData;
   });
 
   it('renders a single key', () => {
@@ -54,6 +55,22 @@ describe('Kbd', () => {
     expect(screen.getByText('\u2318')).toBeInTheDocument(); // \u2318
   });
 
+  it('reads a blank userAgentData.platform as unknown, not as non-Mac', () => {
+    // Builds that rewrite their client-hints identity expose the key with an
+    // empty value; navigator.platform is the only surface left that answers.
+    Object.defineProperty(navigator, 'userAgentData', {
+      value: {platform: ''},
+      configurable: true,
+    });
+    Object.defineProperty(navigator, 'platform', {
+      value: 'MacIntel',
+      configurable: true,
+    });
+
+    render(<Kbd keys="mod" />);
+    expect(screen.getByText('\u2318')).toBeInTheDocument();
+  });
+
   it('maps modifier keys to symbols', () => {
     render(<Kbd keys="ctrl+alt+shift+k" />);
     expect(screen.getByText('\u2303')).toBeInTheDocument(); // \u2303

package/src/Kbd/Kbd.tsx

@@ -124,8 +124,9 @@ function getServerPlatformSnapshot(): boolean {
 
 /**
  * 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(): boolean {
   if (typeof navigator === 'undefined') {
@@ -134,7 +135,13 @@ function detectMac(): boolean {
   // 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 as {platform: string}).platform ?? '');
+    const uaPlatform = (uaData as {platform?: unknown}).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/src/Layer/LayerDepthContext.tsx

@@ -0,0 +1,62 @@
+// 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, 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 const LayerDepthContext = 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(): number {
+  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}: {children: ReactNode}) {
+  const depth = use(LayerDepthContext);
+  return <LayerDepthContext value={depth + 1}>{children}</LayerDepthContext>;
+}
+
+LayerDepthProvider.displayName = 'LayerDepthProvider';

package/src/Layer/index.ts

@@ -29,6 +29,15 @@ export type {
   FixedLayerReturn,
 } from './useLayer';
 
+// Layer dismissal stack — one Escape owner for every overlay family
+export {useLayerDismissal} from './useLayerDismissal';
+export type {
+  LayerEscapeBehavior,
+  UseLayerDismissalOptions,
+  UseLayerDismissalReturn,
+} from './useLayerDismissal';
+export {LayerDepthProvider} from './LayerDepthContext';
+
 // Shared touch behavior for the hover layers
 export {useTouchTrigger, isActionTrigger} from './useTouchTrigger';
 export type {