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

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

package/src/HoverCard/HoverCard.test.tsx

@@ -365,7 +365,42 @@ describe('HoverCard', () => {
     );
   });
 
-  it('injects aria-describedby on trigger', () => {
+  it('advertises a dialog popup on the trigger when labelled', () => {
+    render(
+      <HoverCard content={<span>Card content</span>} label="Profile actions">
+        <button type="button">Trigger</button>
+      </HoverCard>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Trigger'});
+    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+    // While closed, the layer is not in the DOM, so aria-controls must not
+    // point at a missing id (see DateInput). It is set once the card opens.
+    expect(trigger).not.toHaveAttribute('aria-controls');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(trigger).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('merges existing popup attributes on the trigger when labelled', () => {
+    render(
+      <HoverCard content={<span>Card content</span>} label="Profile actions">
+        <button
+          type="button"
+          aria-haspopup="menu"
+          aria-controls="menu-id"
+          aria-expanded="true">
+          Trigger
+        </button>
+      </HoverCard>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Trigger'});
+    // The hover card's dialog popup is advertised, but the trigger's own
+    // popup semantics are preserved rather than overwritten.
+    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+    expect(trigger.getAttribute('aria-controls')).toContain('menu-id');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('keeps aria-describedby on the trigger when no label is provided', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
         <button type="button">Trigger</button>
@@ -373,9 +408,10 @@ describe('HoverCard', () => {
     );
     const trigger = screen.getByRole('button', {name: 'Trigger'});
     expect(trigger).toHaveAttribute('aria-describedby');
+    expect(trigger).not.toHaveAttribute('aria-haspopup');
   });
 
-  it('merges existing aria-describedby', () => {
+  it('preserves existing aria-describedby when no label is provided', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
         <button type="button" aria-describedby="existing-id">
@@ -388,6 +424,34 @@ describe('HoverCard', () => {
     expect(describedBy).toContain('existing-id');
   });
 
+  it('updates aria-expanded when the labelled hover card opens and closes', async () => {
+    render(
+      <HoverCard
+        content={<span>Card content</span>}
+        label="Profile actions"
+        delay={0}>
+        <button type="button">Trigger</button>
+      </HoverCard>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Trigger'});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(trigger).not.toHaveAttribute('aria-controls');
+
+    fireEvent.mouseEnter(trigger);
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+      // The layer is in the DOM now, so aria-controls points at it.
+      expect(trigger).toHaveAttribute('aria-controls');
+    });
+
+    fireEvent.mouseLeave(trigger);
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      // The layer is gone from the DOM, so aria-controls is cleared.
+      expect(trigger).not.toHaveAttribute('aria-controls');
+    });
+  });
+
   it('calls onOpenChange(true) when shown', async () => {
     const onOpenChange = vi.fn();
     render(
@@ -429,16 +493,32 @@ describe('HoverCard', () => {
 
   it('supports text-only children with inline wrapper', () => {
     render(
-      <HoverCard content={<span>Card content</span>}>
+      <HoverCard content={<span>Card content</span>} label="Profile actions">
         Just text, no element
       </HoverCard>,
     );
     // Text should be rendered
     expect(screen.getByText('Just text, no element')).toBeInTheDocument();
-    // Should have aria-describedby on the wrapper span
+    // When labelled, the wrapper advertises a dialog popup.
+    const wrapper = screen.getByText('Just text, no element');
+    expect(wrapper.tagName).toBe('SPAN');
+    expect(wrapper).toHaveAttribute('aria-haspopup', 'dialog');
+    expect(wrapper).toHaveAttribute('aria-expanded', 'false');
+    // While closed, the layer is not in the DOM, so aria-controls is unset.
+    expect(wrapper).not.toHaveAttribute('aria-controls');
+    expect(wrapper).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('keeps aria-describedby on text-only children when no label is provided', () => {
+    render(
+      <HoverCard content={<span>Card content</span>}>
+        Just text, no element
+      </HoverCard>,
+    );
     const wrapper = screen.getByText('Just text, no element');
     expect(wrapper.tagName).toBe('SPAN');
     expect(wrapper).toHaveAttribute('aria-describedby');
+    expect(wrapper).not.toHaveAttribute('aria-haspopup');
   });
 
   describe('isDefaultOpen', () => {
@@ -994,3 +1074,20 @@ describe('HoverCard', () => {
     });
   });
 });
+
+describe('HoverCard theme target names', () => {
+  it('renders the deprecated class beside the current one on the card surface', async () => {
+    render(
+      <HoverCard content={<span>Card content</span>} delay={0}>
+        <button type="button">Trigger</button>
+      </HoverCard>,
+    );
+    fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));
+
+    await waitFor(() => {
+      const layer = screen.getByText('Card content').closest('[popover]');
+      expect(layer).toHaveClass('astryx-hover-card');
+      expect(layer).toHaveClass('astryx-hovercard');
+    });
+  });
+});

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;
 
@@ -253,7 +259,59 @@ export function HoverCard({
     // Use combined ref for position + interaction
     hoverCard.ref(firstChild);
 
-    // Set aria-describedby, merging with existing
+    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.
+      //
+      // 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');
+
+      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');
+      }
+      firstChild.setAttribute('aria-expanded', String(hoverCard.isOpen));
+
+      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');
+        }
+      };
+    }
+
+    // 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',
@@ -268,7 +326,14 @@ 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
@@ -287,7 +352,10 @@ export function HoverCard({
         <span
           ref={hoverCard.ref}
           tabIndex={0}
-          aria-describedby={hoverCard.describedBy}
+          aria-haspopup={label ? 'dialog' : undefined}
+          aria-controls={label && hoverCard.isOpen ? hoverCard.id : undefined}
+          aria-expanded={label ? hoverCard.isOpen : undefined}
+          aria-describedby={label ? undefined : hoverCard.describedBy}
           {...stylex.props(
             styles.wrapperInline,
             showHoverIndication && styles.hoverIndication,