@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -61,14 +61,7 @@ export const docs = {
       type: 'boolean',
       description: 'Whether to show a chevron icon on the trigger button. Set to false for icon-only triggers.',
       default: 'true',
-    },
-    {
-      name: 'hasAutoFocus',
-      type: 'boolean',
-      description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases or documentation previews.',
-      default: 'true',
-    },
-    {
+    },    {
       name: 'children',
       type: '(item: DropdownMenuItemData) => ReactNode',
       description: 'Custom render function for each item in the list.',

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -45,30 +45,43 @@ beforeEach(() => {
 describe('DropdownMenu', () => {
   it('renders trigger button with label', () => {
     render(
-      <DropdownMenu
-        button={{label: 'Actions'}}
-        items={[{label: 'Item 1'}]}
-      />,
+      <DropdownMenu button={{label: 'Actions'}} items={[{label: 'Item 1'}]} />,
     );
     expect(screen.getByRole('button', {name: /Actions/})).toBeInTheDocument();
   });
 
   it('renders menu with role="menu"', () => {
     render(
-      <DropdownMenu
-        button={{label: 'Actions'}}
-        items={[{label: 'Item 1'}]}
-      />,
+      <DropdownMenu button={{label: 'Actions'}} items={[{label: 'Item 1'}]} />,
     );
     expect(screen.getByRole('menu', {hidden: true})).toBeInTheDocument();
   });
 
+  it('names the menu from the trigger label (menus-13)', () => {
+    render(
+      <DropdownMenu button={{label: 'Actions'}} items={[{label: 'Item 1'}]} />,
+    );
+    expect(
+      screen.getByRole('menu', {name: 'Actions', hidden: true}),
+    ).toBeInTheDocument();
+  });
+
+  it('does not wrap the menu in a role="dialog" aria-modal element', () => {
+    render(
+      <DropdownMenu button={{label: 'Actions'}} items={[{label: 'Item 1'}]} />,
+    );
+    // The popup exposes its own role="menu"; it must not be nested inside a
+    // modal dialog, which would announce an unnamed dialog around the menu
+    // while focus stays on the trigger.
+    expect(screen.queryByRole('dialog', {hidden: true})).not.toBeInTheDocument();
+    expect(
+      document.querySelector('[aria-modal="true"]'),
+    ).not.toBeInTheDocument();
+  });
+
   it('defaults menu placement below', () => {
     render(
-      <DropdownMenu
-        button={{label: 'Actions'}}
-        items={[{label: 'Item 1'}]}
-      />,
+      <DropdownMenu button={{label: 'Actions'}} items={[{label: 'Item 1'}]} />,
     );
     const popover = screen
       .getByRole('menu', {hidden: true})
@@ -96,10 +109,7 @@ describe('DropdownMenu', () => {
 
   it('has aria-haspopup and aria-expanded attributes', () => {
     render(
-      <DropdownMenu
-        button={{label: 'Actions'}}
-        items={[{label: 'Item 1'}]}
-      />,
+      <DropdownMenu button={{label: 'Actions'}} items={[{label: 'Item 1'}]} />,
     );
     const button = screen.getByRole('button', {name: /Actions/});
     expect(button).toHaveAttribute('aria-haspopup', 'menu');
@@ -107,16 +117,43 @@ describe('DropdownMenu', () => {
   });
 
   it('opens menu when button is clicked', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}} items={[{label: 'Item 1'}]} />,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+  });
+
+  it('closes the menu when Tab is pressed inside it (APG menu-button)', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}} items={[{label: 'Item 1'}]} />,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    fireEvent.keyDown(menu, {key: 'Tab'});
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
+  });
+
+  it('typeahead focuses the item matching the typed character (menus-11)', async () => {
     const user = userEvent.setup();
     render(
       <DropdownMenu
         button={{label: 'Actions'}}
-        items={[{label: 'Item 1'}]}
+        items={[{label: 'Cut'}, {label: 'Copy'}, {label: 'Delete'}]}
       />,
     );
-
     await user.click(screen.getByRole('button', {name: /Actions/}));
-    expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+    const menu = screen.getByRole('menu', {hidden: true});
+    fireEvent.keyDown(menu, {key: 'd'});
+    expect(
+      screen.getByRole('menuitem', {name: 'Delete', hidden: true}),
+    ).toHaveFocus();
   });
 
   it('calls onClick callback when button is clicked', async () => {
@@ -212,29 +249,6 @@ describe('DropdownMenu controlled mode', () => {
   });
 });
 
-describe('DropdownMenu hasAutoFocus', () => {
-  it('does not focus menu items when hasAutoFocus is false and isMenuOpen is true', () => {
-    const focusSpy = vi.spyOn(HTMLElement.prototype, 'focus');
-    render(
-      <DropdownMenu
-        button={{label: 'Actions'}}
-        items={[{label: 'Edit'}, {label: 'Delete'}]}
-        isMenuOpen={true}
-        hasAutoFocus={false}
-        onOpenChange={() => {}}
-      />,
-    );
-
-    const menuItems = screen.getAllByRole('menuitem', {hidden: true});
-    const menuItemFocusCalls = focusSpy.mock.calls.filter((_, i) => {
-      const ctx = focusSpy.mock.contexts[i];
-      return menuItems.includes(ctx as HTMLElement);
-    });
-    expect(menuItemFocusCalls).toHaveLength(0);
-    focusSpy.mockRestore();
-  });
-});
-
 describe('DropdownMenu items', () => {
   it('renders items with labels', () => {
     render(

package/src/DropdownMenu/DropdownMenu.tsx

@@ -43,6 +43,7 @@ import {
   type DropdownMenuContextValue,
 } from './DropdownMenuContext';
 import {useListFocus} from '../hooks/useListFocus';
+import {useTypeahead} from '../hooks/useTypeahead';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import type {LayerPlacement} from '../Layer/useLayer';
 import {
@@ -134,13 +135,6 @@ interface DropdownMenuBaseProps extends BaseProps {
    */
   placement?: LayerPlacement;
 
-  /**
-   * Whether to auto-focus the first menu item when the menu opens.
-   * Set to `false` for inline showcases or documentation previews
-   * where stealing focus is undesirable.
-   * @default true
-   */
-  hasAutoFocus?: boolean;
   'data-testid'?: string;
 }
 
@@ -192,7 +186,6 @@ export function DropdownMenu({
   onClick,
   hasChevron = true,
   placement = 'below',
-  hasAutoFocus = true,
   className,
   style,
   xstyle,
@@ -249,6 +242,9 @@ export function DropdownMenu({
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
+    // The popup's own role="menu" is the exposed semantics; wrapping it in a
+    // modal dialog would announce an unnamed dialog around the menu.
+    role: 'none',
   });
 
   const closeMenu = useCallback(() => {
@@ -260,27 +256,49 @@ export function DropdownMenu({
     listRef,
     handleKeyDown: listNavKeyDown,
     focusFirst,
+    focusItem,
   } = useListFocus<HTMLDivElement>({
     itemSelector: '[role="menuitem"]:not([aria-disabled="true"])',
     wrap: false,
     onEscape: closeMenu,
   });
 
+  // First-character typeahead over the (enabled) menu items — jump to the next
+  // item whose label starts with the typed text (menus-11).
+  const getMenuItems = useCallback(
+    (): HTMLElement[] =>
+      listRef.current
+        ? Array.from(
+            listRef.current.querySelectorAll<HTMLElement>(
+              '[role="menuitem"]:not([aria-disabled="true"])',
+            ),
+          )
+        : [],
+    [listRef],
+  );
+  const typeahead = useTypeahead({
+    getItemLabels: () => getMenuItems().map(el => el.textContent),
+    onMatch: focusItem,
+    getCurrentIndex: () =>
+      getMenuItems().findIndex(
+        el =>
+          el === document.activeElement || el.contains(document.activeElement),
+      ),
+  });
+
   // Sync controlled open state → popover, and focus first item on open
   useEffect(() => {
     if (isControlled) {
       if (controlledIsOpen && !popover.isOpen) {
         popover.show();
-        if (hasAutoFocus) {
-          requestAnimationFrame(() => focusFirst());
-        }
+        requestAnimationFrame(() => focusFirst());
       } else if (!controlledIsOpen && popover.isOpen) {
         popover.hide();
       }
     }
-  }, [controlledIsOpen, isControlled, popover, hasAutoFocus, focusFirst]);
+  }, [controlledIsOpen, isControlled, popover, focusFirst]);
 
-  // Extend useListFocus with Enter/Space activation
+  // Extend useListFocus with Enter/Space activation + typeahead
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
       if (e.key === 'Enter' || e.key === ' ') {
@@ -291,17 +309,29 @@ export function DropdownMenu({
         }
         return;
       }
+      // APG menu-button pattern: Tab closes the menu. Menu items are
+      // tabIndex={-1} so the focus trap has nothing trappable and Tab would
+      // otherwise leak into the page while the menu stayed open (menus-5).
+      // Do NOT preventDefault — closing restores focus to the trigger, and the
+      // browser's default Tab then continues from there to the next element.
+      if (e.key === 'Tab') {
+        closeMenu();
+        return;
+      }
+      // Type-to-focus next; if it consumed a printable key, stop here.
+      if (typeahead.onKeyDown(e)) {
+        e.preventDefault();
+        return;
+      }
       listNavKeyDown(e);
     },
-    [listNavKeyDown],
+    [listNavKeyDown, closeMenu, typeahead],
   );
 
   const openAndFocus = useCallback(() => {
     popover.show();
-    if (hasAutoFocus) {
-      requestAnimationFrame(() => focusFirst());
-    }
-  }, [popover, hasAutoFocus, focusFirst]);
+    requestAnimationFrame(() => focusFirst());
+  }, [popover, focusFirst]);
 
   const handleButtonClick = useCallback(() => {
     // If the menu was just closed by light dismiss (e.g. iOS Safari fires
@@ -399,6 +429,10 @@ export function DropdownMenu({
           ref={listRef}
           id={menuId}
           role="menu"
+          // Give the menu an accessible name from its trigger's label, so
+          // screen readers announce e.g. "Actions menu" rather than an unnamed
+          // menu (menus-13).
+          aria-label={button.label}
           onKeyDown={listKeyDown}
           {...mergeProps(
             themeProps('dropdown-menu'),

package/src/EmptyState/EmptyState.test.tsx

@@ -45,11 +45,13 @@ describe('EmptyState', () => {
       />,
     );
     expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
+    // Description renders as <div> (never <p>) so block content composes safely.
+    expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
   });
 
   it('does not render description when not provided', () => {
-    const {container} = render(<EmptyState title="No results" />);
-    expect(container.querySelector('p')).not.toBeInTheDocument();
+    render(<EmptyState title="No results" />);
+    expect(screen.queryByText('Try adjusting your search.')).toBeNull();
   });
 
   it('renders with icon', () => {

package/src/EmptyState/EmptyState.tsx

@@ -174,13 +174,17 @@ export function EmptyState({
           title,
         )}
         {description != null && (
-          <p
+          // Rendered as <div> (not <p>): description accepts ReactNode and a
+          // <p> cannot legally contain block children, which causes hydration
+          // mismatches. The StyleX style sets margin: 0, so appearance is
+          // unchanged.
+          <div
             {...stylex.props(
               styles.description,
               isCompact && styles.descriptionCompact,
             )}>
             {description}
-          </p>
+          </div>
         )}
       </div>
       {actions != null && (

package/src/Field/Field.test.tsx

@@ -93,6 +93,38 @@ describe('Field', () => {
     expect(label).toBeVisible();
   });
 
+  it('renders a single-control label as a <label> with htmlFor', () => {
+    render(
+      <Field label="Email" inputID="email-input">
+        <input id="email-input" />
+      </Field>,
+    );
+    const labelEl = screen.getByText('Email');
+    expect(labelEl.tagName).toBe('LABEL');
+    expect(labelEl).toHaveAttribute('for', 'email-input');
+  });
+
+  it('renders a group label as a <span> (not <label>) with no htmlFor', () => {
+    render(
+      <Field
+        label="Plan"
+        inputID="plan-group"
+        labelID="plan-label"
+        isGroupLabel>
+        <div role="radiogroup" aria-labelledby="plan-label" />
+      </Field>,
+    );
+    const labelEl = screen.getByText('Plan');
+    // A group's accessible-name element must not be a literal <label>.
+    expect(labelEl.tagName).toBe('SPAN');
+    expect(labelEl.closest('label')).toBeNull();
+    expect(labelEl).not.toHaveAttribute('for');
+    // labelID is applied to the label element and referenced by the group.
+    expect(labelEl).toHaveAttribute('id', 'plan-label');
+    const group = screen.getByRole('radiogroup', {name: 'Plan'});
+    expect(group.getAttribute('aria-labelledby')).toBe(labelEl.id);
+  });
+
   it('forwards ref correctly', () => {
     const ref = vi.fn();
     render(

package/src/Field/Field.tsx

@@ -99,9 +99,26 @@ export interface FieldProps extends Omit<
    */
   description?: string;
   /**
-   * ID for the input element (used for label's htmlFor attribute).
+   * ID of the input element this label points AT (used as the label's
+   * `htmlFor`). This is the id of the *control*, not of the label element —
+   * see `labelID` for the latter.
    */
   inputID: string;
+  /**
+   * The `id` applied TO the label element itself (distinct from `inputID`,
+   * which is the control the label points at). A grouping control
+   * (radiogroup, checkbox group) references this via `aria-labelledby` to take
+   * the label as its accessible name. Pair with `isGroupLabel`.
+   */
+  labelID?: string;
+  /**
+   * When the field wraps a group of controls rather than a single input, set
+   * this so the label renders as a non-`<label>` element (a `<span>`): a
+   * `<label>` semantically names one control and can't be associated with a
+   * group. Pair with `labelID` + `aria-labelledby` on the group.
+   * @default false
+   */
+  isGroupLabel?: boolean;
   /**
    * ID for the description element (use for aria-describedby on the input).
    */
@@ -172,6 +189,8 @@ export function Field({
   isLabelHidden = false,
   description,
   inputID,
+  labelID,
+  isGroupLabel = false,
   descriptionID,
   isOptional = false,
   isRequired = false,
@@ -206,6 +225,8 @@ export function Field({
     <FieldLabel
       label={label}
       inputID={inputID}
+      labelID={labelID}
+      isGroupLabel={isGroupLabel}
       isLabelHidden={isLabelHidden}
       isDisabled={isDisabled}
       isOptional={isOptional}
@@ -245,10 +266,7 @@ export function Field({
         <div {...stylex.props(styles.horizontalLabelAlign)}>{labelNode}</div>
         <div {...stylex.props(styles.inputStatusWrapper)}>
           {description && (
-            <Text
-              type="supporting"
-              display="block"
-              id={resolvedDescriptionID}>
+            <Text type="supporting" display="block" id={resolvedDescriptionID}>
               {description}
             </Text>
           )}

package/src/Field/FieldLabel.tsx

@@ -35,6 +35,7 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-1'],
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-label-size'],
+    lineHeight: typeScaleVars['--text-label-leading'],
     fontWeight: fontWeightVars['--font-weight-medium'],
     color: colorVars['--color-text-secondary'],
     cursor: 'pointer',
@@ -61,6 +62,7 @@ const styles = stylex.create({
   optionalRequired: {
     fontWeight: fontWeightVars['--font-weight-normal'],
     fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
     color: colorVars['--color-text-secondary'],
   },
   description: {
@@ -80,9 +82,28 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
    */
   label: string;
   /**
-   * ID of the input element this label is for.
+   * ID of the input element this label points AT (rendered as `htmlFor` on the
+   * label). This is *not* the id of the label element itself — see
+   * `labelID` for that.
    */
   inputID: string;
+  /**
+   * The `id` applied TO the label element itself (not the element it points
+   * at — that's `inputID`). A grouping control (e.g. `role="radiogroup"`) can
+   * reference this via `aria-labelledby` to take the label as its accessible
+   * name.
+   */
+  labelID?: string;
+  /**
+   * When true, the field wraps a *group* of controls (e.g. a radiogroup)
+   * rather than a single input. In that case the label is rendered as a
+   * `<span>` instead of a `<label>` — a `<label>` semantically names one form
+   * control and can't be associated with a group, so it must not be a literal
+   * label element. The group takes the label as its name via
+   * `labelID` + `aria-labelledby`.
+   * @default false
+   */
+  isGroupLabel?: boolean;
   /**
    * Whether to visually hide the label and description (still accessible
    * to screen readers). When hidden, the entire label group is rendered
@@ -140,6 +161,8 @@ export interface FieldLabelProps extends BaseProps<HTMLLabelElement> {
 export function FieldLabel({
   label,
   inputID,
+  labelID,
+  isGroupLabel = false,
   isLabelHidden = false,
   isDisabled = false,
   isOptional = false,
@@ -152,11 +175,38 @@ export function FieldLabel({
 }: FieldLabelProps) {
   const statusText = isOptional ? 'Optional' : isRequired ? 'Required' : null;
 
+  // A group label (e.g. for a radiogroup) must not be a literal `<label>`
+  // element: a `<label>` semantically names a single form control and can't be
+  // associated with a group. Render it as a `<span>` instead, keeping all the
+  // label styling and slots. The group references it via `aria-labelledby`.
+  const LabelElement = isGroupLabel ? 'span' : 'label';
+
+  const labelContent = (
+    <>
+      {labelIcon && renderIconSlot(labelIcon, {size: 'sm', color: 'inherit'})}
+      {label}
+      {statusText && (
+        <span {...stylex.props(styles.optionalRequired)}>
+          <span aria-hidden="true"> ∙ </span>
+          {statusText}
+        </span>
+      )}
+      {labelTooltip && (
+        <Tooltip content={labelTooltip} placement="above">
+          <Icon icon="info" size="sm" color="inherit" />
+        </Tooltip>
+      )}
+    </>
+  );
+
   return (
     <>
-      <label
+      <LabelElement
         ref={ref}
-        htmlFor={inputID}
+        id={labelID}
+        // `htmlFor` only applies to a real `<label>` associating with a single
+        // control; a group label (span) has no `htmlFor`.
+        htmlFor={isGroupLabel ? undefined : inputID}
         {...mergeProps(
           themeProps('field-label'),
           stylex.props(
@@ -165,20 +215,8 @@ export function FieldLabel({
             isLabelHidden && styles.srOnly,
           ),
         )}>
-        {labelIcon && renderIconSlot(labelIcon, {size: 'sm', color: 'inherit'})}
-        {label}
-        {statusText && (
-          <span {...stylex.props(styles.optionalRequired)}>
-            <span aria-hidden="true"> ∙ </span>
-            {statusText}
-          </span>
-        )}
-        {labelTooltip && (
-          <Tooltip content={labelTooltip} placement="above">
-            <Icon icon="info" size="sm" color="inherit" />
-          </Tooltip>
-        )}
-      </label>
+        {labelContent}
+      </LabelElement>
       {description && (
         <span
           id={descriptionID}

package/src/FileInput/FileInput.doc.mjs

@@ -88,6 +88,12 @@ export const docs = {
         'Disables the input, preventing interaction and dimming the element.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the trigger focusable via aria-disabled (opening the file picker stays blocked). Use this instead of wrapping a disabled FileInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -135,6 +141,7 @@ export const docs = {
       {guidance: true, description: 'Use changeAction for immediate upload workflows that benefit from optimistic UI.'},
       {guidance: false, description: "Don't use FileInput for directory or folder uploads; that is not supported in v1."},
       {guidance: false, description: "Don't avoid dropzone mode unless space is constrained; drag-and-drop is the expected interaction for file uploads."},
+      {guidance: false, description: "Don't wrap a disabled FileInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},
@@ -211,6 +218,12 @@ export const docsZh = {
       description: '禁用输入框，阻止交互并使元素变暗。',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        '说明输入框被禁用的原因。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示工具提示，并通过 aria-disabled 保持触发器可聚焦（打开文件选择器仍被阻止）。请使用此属性，而不是用 Tooltip 包裹已禁用的 FileInput。',
+    },
     {
       name: 'isLoading',
       type: 'boolean',
@@ -248,6 +261,7 @@ export const docsZh = {
       {guidance: true, description: 'Add a description to communicate constraints.'},
       {guidance: false, description: "Don't use FileInput for directory uploads."},
       {guidance: false, description: "Don't use mode='input' unless space is constrained; dropzone mode provides a better experience."},
+      {guidance: false, description: "Don't wrap a disabled FileInput in Tooltip to explain the disabled state; use the disabledMessage prop instead."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text identifying the field.'},
@@ -272,6 +286,7 @@ export const docsDense = {
       {guidance: true, description: 'Use changeAction for immediate upload workflows that benefit from optimistic UI.'},
       {guidance: false, description: "Don't use FileInput for directory uploads."},
       {guidance: false, description: "Don't use mode='input' unless space is constrained; dropzone mode provides a better experience."},
+      {guidance: false, description: "Don't wrap a disabled FileInput in Tooltip to explain the disabled state; use the disabledMessage prop instead."},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text identifying the field.'},
@@ -295,6 +310,8 @@ export const docsDense = {
     isOptional: 'Shows "Optional" indicator.',
     isRequired: 'Shows "Required" indicator+sets aria-required.',
     isDisabled: 'Disables input, prevents interaction.',
+    disabledMessage:
+      'Explains why input is disabled. With isDisabled, shows tooltip on hover/focus + keeps trigger focusable via aria-disabled (opening picker stays blocked). Use instead of wrapping a disabled FileInput in Tooltip.',
     isLoading: 'Loading state w/ spinner+aria-busy.',
     placeholder: 'Placeholder when no files selected.',
     mode: "Visual mode: 'input' (compact) or 'dropzone' (drag-and-drop).",