@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

package/src/Dialog/Dialog.tsx

@@ -8,6 +8,13 @@
  * @output Exports Dialog component, DialogProps, DialogVariant, DialogPurpose types
  * @position Core implementation; consumed by index.ts, tested by Dialog.test.tsx
  *
+ * The standard variant treats `width` as the preferred surface width, then
+ * clamps it to the dynamic viewport with spacing-token gutters so narrow
+ * viewports keep content and controls on screen without changing the public API.
+ * Fullscreen dialogs add safe-area protection to the default padding fallback
+ * while preserving explicit prop/theme padding overrides, and fade in without
+ * the centered-dialog translate/scale motion.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Dialog/Dialog.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Dialog/Dialog.test.tsx (tests for new/changed behavior)
@@ -27,14 +34,15 @@ import {
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {useScrollLock} from '../hooks/useScrollLock';
-import {hasActiveFocusTrapEscape} from '../hooks/useFocusTrap';
-import {isImeKeyEvent} from '../utils/ime';
+import {LayerDepthProvider} from '../Layer/LayerDepthContext';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {
   colorVars,
   radiusVars,
   durationVars,
   easeVars,
   shadowVars,
+  spacingVars,
 } from '../theme/tokens.stylex';
 import {container} from '../Layout/container.stylex';
 import type {SpacingToken} from '../Layout/container.stylex';
@@ -47,13 +55,14 @@ import {
   overlayPaddingReset,
 } from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {devWarn} from '../utils/devWarning';
 import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
 import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 /**
  * Calculate a directional translate offset for dialog entry animation.
  * Returns a normalized vector from the trigger element toward the viewport
@@ -118,6 +127,32 @@ const enterDirectional = stylex.keyframes({
   to: {opacity: 1, transform: 'translate(0, 0) scale(1)'},
 });
 
+const enterFullscreen = stylex.keyframes({
+  from: {opacity: 0},
+  to: {opacity: 1},
+});
+
+const dialogFullscreenSafeAreaBlockStartPadding = `var(--astryx-dialog-padding-block-start, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-top, 0px))))`;
+const dialogFullscreenSafeAreaBlockEndPadding = `var(--astryx-dialog-padding-block-end, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-bottom, 0px))))`;
+const dialogFullscreenSafeAreaInlineStartPaddingLtr = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;
+const dialogFullscreenSafeAreaInlineStartPaddingRtl = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
+const dialogFullscreenSafeAreaInlineEndPaddingLtr = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
+const dialogFullscreenSafeAreaInlineEndPaddingRtl = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;
+
+/** @internal Verified by Dialog.test.tsx; not re-exported from the package entry point. */
+export const dialogFullscreenSafeAreaPaddingContract = {
+  blockStart: dialogFullscreenSafeAreaBlockStartPadding,
+  blockEnd: dialogFullscreenSafeAreaBlockEndPadding,
+  inlineStart: {
+    ltr: dialogFullscreenSafeAreaInlineStartPaddingLtr,
+    rtl: dialogFullscreenSafeAreaInlineStartPaddingRtl,
+  },
+  inlineEnd: {
+    ltr: dialogFullscreenSafeAreaInlineEndPaddingLtr,
+    rtl: dialogFullscreenSafeAreaInlineEndPaddingRtl,
+  },
+} as const;
+
 /**
  * Dialog styles using native <dialog> element
  * Uses ::backdrop pseudo-element for overlay
@@ -171,6 +206,24 @@ const styles = stylex.create({
     margin: 0,
     inset: 0,
   },
+  fullscreenOpen: {
+    animationName: {
+      default: enterFullscreen,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+  },
+  fullscreenSafeArea: {
+    paddingBlockStart: dialogFullscreenSafeAreaBlockStartPadding,
+    paddingBlockEnd: dialogFullscreenSafeAreaBlockEndPadding,
+    paddingInlineStart: {
+      default: dialogFullscreenSafeAreaInlineStartPaddingLtr,
+      ':is([dir="rtl"] *)': dialogFullscreenSafeAreaInlineStartPaddingRtl,
+    },
+    paddingInlineEnd: {
+      default: dialogFullscreenSafeAreaInlineEndPaddingLtr,
+      ':is([dir="rtl"] *)': dialogFullscreenSafeAreaInlineEndPaddingRtl,
+    },
+  },
   inner: {
     display: 'flex',
     flexDirection: 'column',
@@ -194,12 +247,30 @@ const styles = stylex.create({
   },
 });
 
-// Dynamic styles for width, maxHeight, and position
+const STANDARD_DIALOG_VIEWPORT_GUTTER = spacingVars['--spacing-4'];
+const STANDARD_DIALOG_VIEWPORT_MAX_WIDTH = `calc(100dvw - ${STANDARD_DIALOG_VIEWPORT_GUTTER} - ${STANDARD_DIALOG_VIEWPORT_GUTTER})`;
+const STANDARD_DIALOG_MAX_WIDTH = `min(100%, ${STANDARD_DIALOG_VIEWPORT_MAX_WIDTH})`;
+
+function formatSizeValue(value: number | string): string {
+  return typeof value === 'number' ? `${value}px` : value;
+}
+
+function resolveDialogSizing(
+  width: number | string,
+  maxHeight: number | string,
+) {
+  return {
+    width: formatSizeValue(width),
+    maxWidth: STANDARD_DIALOG_MAX_WIDTH,
+    maxHeight: formatSizeValue(maxHeight),
+  };
+}
+
 const dynamicStyles = stylex.create({
-  sizing: (width: number | string, maxHeight: number | string) => ({
-    width: typeof width === 'number' ? `${width}px` : width,
-    maxWidth: '90vw',
-    maxHeight: typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight,
+  sizing: (width: string, maxWidth: string, maxHeight: string) => ({
+    width,
+    maxWidth,
+    maxHeight,
   }),
   position: (
     top: string,
@@ -288,7 +359,7 @@ export interface DialogProps extends BaseProps<HTMLDialogElement> {
    * The actual height will be the height of its content.
    * Numbers are treated as pixels, strings are used as-is.
    * Ignored when variant is 'fullscreen'.
-   * @default '75vh'
+   * @default '75dvh'
    */
   maxHeight?: number | string;
 
@@ -356,7 +427,7 @@ export function Dialog({
   isInline = false,
   onOpenChange,
   width = 400,
-  maxHeight = '75vh',
+  maxHeight = '75dvh',
   position,
   variant = 'standard',
   purpose = 'info',
@@ -374,6 +445,9 @@ export function Dialog({
   const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
 
   const isFullscreen = variant === 'fullscreen';
+  const standardSizing = isFullscreen
+    ? null
+    : resolveDialogSizing(width, maxHeight);
 
   // Default accessible name: publish a title id through DialogContext so a
   // DialogHeader applies it to its heading (mirrors AlertDialog's explicit
@@ -415,6 +489,8 @@ export function Dialog({
     [titleId, hasConsumerName],
   );
 
+  const mergedDialogRef = useMergedRefs(ref, attachDialog);
+
   // Capture the element that was focused when the dialog opened,
   // for directional animation origin and focus restoration on close.
   const triggerElementRef = useRef<HTMLElement | null>(null);
@@ -474,34 +550,24 @@ export function Dialog({
   // Skip for inline rendering — no modal overlay to compensate for.
   useScrollLock(isOpen && !isInline);
 
-  // Handle Escape key — skip for inline rendering
-  useEffect(() => {
-    if (isInline) {
-      return;
-    }
-    const dialog = dialogRef.current;
-    if (!dialog || !isOpen) {
-      return;
-    }
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        // Ignore IME composition-cancel, and defer to any popover/menu layered
-        // on top of this dialog so a single Escape closes only the top-most
-        // layer (the popover's own focus trap handles it and stops propagation).
-        if (isImeKeyEvent(event) || hasActiveFocusTrapEscape()) {
-          return;
-        }
-        event.preventDefault();
-        if (allowEscape) {
-          onOpenChange(false);
-        }
-      }
-    };
-
-    dialog.addEventListener('keydown', handleKeyDown);
-    return () => dialog.removeEventListener('keydown', handleKeyDown);
-  }, [isOpen, isInline, allowEscape, onOpenChange]);
+  // Join the shared layer dismissal stack. The stack owns the Escape listener
+  // and routes each press to the top-most layer, so this dialog does not listen
+  // itself — that is what stops a modal opened from inside another modal (or a
+  // popover opened inside this one) from closing two layers on one press.
+  //
+  // A `required` dialog registers as `block`: it must not be dismissed, and the
+  // press must not fall through and dismiss a layer behind it either.
+  //
+  // Inline mode opts out — it renders dialog content in normal flow, with
+  // nothing layered over anything.
+  const {shouldDismissOnCloseRequest} = useLayerDismissal({
+    isActive: isOpen,
+    isEnabled: !isInline,
+    escapeBehavior: allowEscape ? 'close' : 'block',
+    onDismiss: () => {
+      onOpenChange(false);
+    },
+  });
 
   // Dev-time guardrail: an open modal should always have an accessible name.
   // The header-title check reads the DOM, so this stays in an effect; the ref
@@ -537,12 +603,18 @@ export function Dialog({
     }
   };
 
-  // Handle native cancel event (browser Escape handling)
+  // The native `cancel` event is the browser's own close-watcher firing: an
+  // Android back gesture, or a close request the stack never saw a press for.
+  // Escape presses the stack owns never arrive here — it preventDefault()s
+  // those, which suppresses the close watcher.
+  //
+  // Always preventDefault so the browser cannot close a controlled <dialog>
+  // behind React's back, then answer the request with the stack's own rules:
+  // only the top-most layer dismisses, a `required` dialog swallows it, and
+  // nothing dismisses while an IME composition is in progress.
   const handleCancel = (event: React.SyntheticEvent<HTMLDialogElement>) => {
     event.preventDefault();
-    // Defer to a popover/menu layered on top of this dialog; it will dismiss
-    // itself on the same Escape press.
-    if (hasActiveFocusTrapEscape()) {
+    if (!shouldDismissOnCloseRequest()) {
       return;
     }
     if (allowEscape) {
@@ -550,7 +622,6 @@ export function Dialog({
     }
   };
 
-  // Shared inner content wrapper
   const innerContent = (
     <div
       {...stylex.props(
@@ -559,22 +630,14 @@ export function Dialog({
           useThemeDefault
             ? {
                 useThemeDefault: 'dialog',
-                maxHeight: isFullscreen
-                  ? undefined
-                  : typeof maxHeight === 'number'
-                    ? `${maxHeight}px`
-                    : maxHeight,
+                maxHeight: standardSizing?.maxHeight,
               }
             : {
                 paddingInnerX: paddingToken,
                 paddingInnerY: paddingToken,
                 paddingOuterX: paddingToken,
                 paddingOuterY: paddingToken,
-                maxHeight: isFullscreen
-                  ? undefined
-                  : typeof maxHeight === 'number'
-                    ? `${maxHeight}px`
-                    : maxHeight,
+                maxHeight: standardSizing?.maxHeight,
               },
         ),
         !useThemeDefault &&
@@ -589,6 +652,7 @@ export function Dialog({
         !useThemeDefault &&
           effectivePadding !== 4 &&
           containerPaddingBlockEndVarStyles[effectivePadding],
+        isFullscreen && useThemeDefault && styles.fullscreenSafeArea,
       )}>
       <DialogContext value={dialogContextValue}>{children}</DialogContext>
     </div>
@@ -612,7 +676,12 @@ export function Dialog({
           stylex.props(
             styles.inlineWrapper,
             overlayPaddingReset.reset,
-            !isFullscreen && dynamicStyles.sizing(width, maxHeight),
+            standardSizing &&
+              dynamicStyles.sizing(
+                standardSizing.width,
+                standardSizing.maxWidth,
+                standardSizing.maxHeight,
+              ),
             isFullscreen && styles.fullscreen,
             xstyle,
           ),
@@ -623,7 +692,7 @@ export function Dialog({
           (props as Record<string, unknown>)['data-testid'] as
             string | undefined
         }>
-        {innerContent}
+        <LayerDepthProvider>{innerContent}</LayerDepthProvider>
       </div>
     );
   }
@@ -632,7 +701,7 @@ export function Dialog({
 
   return (
     <dialog
-      ref={mergeRefs(ref, attachDialog)}
+      ref={mergedDialogRef}
       {...safeProps}
       {...mergeProps(
         themeProps('dialog', {variant}),
@@ -641,7 +710,12 @@ export function Dialog({
           overlayPaddingReset.reset,
           isOpen && styles.open,
           styles.backdrop,
-          !isFullscreen && dynamicStyles.sizing(width, maxHeight),
+          standardSizing &&
+            dynamicStyles.sizing(
+              standardSizing.width,
+              standardSizing.maxWidth,
+              standardSizing.maxHeight,
+            ),
           hasPosition &&
             (() => {
               const o = resolveDialogPositionOffsets(position);
@@ -653,6 +727,7 @@ export function Dialog({
               );
             })(),
           isFullscreen && styles.fullscreen,
+          isFullscreen && isOpen && styles.fullscreenOpen,
           xstyle,
         ),
         className,
@@ -665,7 +740,7 @@ export function Dialog({
       // imperatively in `attachDialog`; a consumer-provided aria-labelledby
       // flows through {...safeProps} above and wins.
       {...(purpose === 'required' ? {role: 'alertdialog'} : undefined)}>
-      {innerContent}
+      <LayerDepthProvider>{innerContent}</LayerDepthProvider>
     </dialog>
   );
 }

package/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -89,6 +89,12 @@ export const docs = {
       type: '() => void',
       description: 'Callback fired when the trigger button is clicked.',
     },
+    {
+      name: 'placement',
+      type: "'above' | 'below' | 'start' | 'end'",
+      description: 'Position placement for the menu popover relative to the trigger button.',
+      default: "'below'",
+    },
     {
       name: 'hasChevron',
       type: 'boolean',

package/src/DropdownMenu/DropdownMenuSubMenu.test.tsx

@@ -701,11 +701,14 @@ describe('DropdownMenuSubMenu theming slots', () => {
       name: /Move to/,
       hidden: true,
     });
-    // The indicator-icon slot wraps the chevron affordance inside the trigger
-    // row.
-    expect(
-      trigger.querySelector('.astryx-dropdown-menu-indicator-icon'),
-    ).toBeInTheDocument();
+    // The indicator-icon slot sits on the chevron glyph itself (the element
+    // that carries the icon size), so a theme can restyle its size/color
+    // directly.
+    const indicator = trigger.querySelector(
+      '.astryx-dropdown-menu-indicator-icon',
+    );
+    expect(indicator).toBeInTheDocument();
+    expect(indicator).toHaveClass('astryx-icon');
   });
 });
 

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/Field/FieldLabel.test.tsx

@@ -15,6 +15,7 @@ import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
 import {InternationalizationProvider} from '../i18n';
 import {FieldLabel} from './FieldLabel';
+import {themeProps} from '../utils/themeProps';
 
 describe('FieldLabel', () => {
   it('renders label text', () => {
@@ -197,4 +198,32 @@ describe('FieldLabel', () => {
       expect(description.closest('label')).toBeNull();
     });
   });
+
+  describe('a control can name its own label target', () => {
+    it('composes a passed target onto the field-label one', () => {
+      // How CheckboxInput and Switch reach their label: the control spreads
+      // its own themeProps in, and both classes end up on the same element,
+      // so a theme can style every label or just this kind.
+      render(
+        <FieldLabel
+          {...themeProps('checkbox-label')}
+          label="Notify me"
+          inputID="notify-input"
+        />,
+      );
+      const label = screen.getByText('Notify me').closest('label');
+      expect(label).toHaveClass('astryx-field-label');
+      expect(label).toHaveClass('astryx-checkbox-label');
+    });
+
+    it('describes no placement of its own', () => {
+      // The label cannot know how its caller arranged it, so it says nothing:
+      // a `data-layout` here would be a claim that is wrong for at least one
+      // caller (Field's horizontal-labels puts a label beside its control),
+      // and a consumer could set it untruthfully.
+      render(<FieldLabel label="Email" inputID="email-input" />);
+      const label = screen.getByText('Email').closest('label');
+      expect(label).not.toHaveAttribute('data-layout');
+    });
+  });
 });

package/src/Field/FieldLabel.tsx

@@ -285,6 +285,13 @@ export function FieldLabel({
         htmlFor={isGroupLabel ? undefined : inputID}
         {...rest}
         {...mergeProps(
+          // A control that knows what kind of label this is passes its own
+          // target down (CheckboxInput's `checkbox-label`, Switch's
+          // `switch-label`); it arrives as `className` and composes onto this
+          // one. The label itself does not describe its own placement — it
+          // cannot know it, and any encoding it guessed would be wrong for a
+          // caller that arranges labels differently (Field's
+          // `horizontal-labels`).
           themeProps('field-label'),
           stylex.props(
             styles.label,

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

@@ -16,7 +16,10 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-hovercard'},
+      {className: 'astryx-hover-card'},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-hovercard', deprecatedFor: 'hover-card'},
     ],
     vars: [
       {name: '--_hovercard-radius', description: 'Border radius of the hover card', default: 'var(--radius-container)', private: true},
@@ -109,6 +112,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.',
+        },
       ],
     },
   ],
@@ -139,7 +147,10 @@ export const docsZh = {
   displayName: 'Hover Card',
   theming: {
     targets: [
-      {className: 'astryx-hovercard'},
+      {className: 'astryx-hover-card'},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-hovercard', deprecatedFor: 'hover-card'},
     ],
     vars: [
       {name: '--_hovercard-radius', description: 'Border radius of the hover card', default: 'var(--radius-container)', private: true},