@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

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/Field/Field.doc.mjs

@@ -11,7 +11,18 @@ export const docs = {
   playground: {
     defaults: {
       label: 'Email address',
-      children: {__element: 'TextInput', props: {label: 'Email', placeholder: 'you@example.com'}},
+      inputID: 'email-input',
+      description: 'Use Field for controls that do not already provide field under the hood.',
+      descriptionID: 'email-help',
+      children: {
+        __element: 'input',
+        props: {
+          id: 'email-input',
+          'aria-describedby': 'email-help',
+          placeholder: 'you@example.com',
+          type: 'email',
+        },
+      },
     },
   },
   theming: {
@@ -27,7 +38,7 @@ export const docs = {
       {property: 'borderRadius', vars: ['--_field-radius']},
     ],
   },
-  description: 'Form field wrapper that provides label, description, and optional/required indicators.',
+  description: 'Low-level form field wrapper for custom controls that need a label, description, and optional/required indicators.',
   props: [
     {
       name: 'label',
@@ -133,36 +144,65 @@ export const docs = {
     {name: 'FieldStatus'},
   ],
   usage: {
-    description: 'Field wraps any input control with a label, description, and validation status. Use it to build accessible forms with consistent labeling, optional/required indicators, and inline error, warning, or success feedback.',
+    description: 'Field is a low-level wrapper for custom, native, or third-party controls that do not already provide field label, description, and status UI. Use it when you need the Field shell around a control you own; use styled Astryx inputs like TextInput, Typeahead, and Select directly when they already expose label, description, and validation props.',
     bestPractices: [
+      { guidance: true, description: 'Wrap custom controls, native inputs, or third-party widgets that need labeling, helper text, optional/required indicators, or validation status.' },
       { guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
-      { guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },
-      { guidance: true, description: 'Add a description when the label alone does not explain what the field expects, like format hints or constraints.' },
+      { guidance: true, description: 'Use inputID and descriptionID to connect the label and description to the inner control with htmlFor and aria-describedby.' },
+      { guidance: false, description: 'Nest Field around styled inputs such as TextInput, Typeahead, Select, DateInput, or TextArea; those components already render their own Field shell.' },
+      { guidance: false, description: 'Use the attached status variant on non-bordered controls such as sliders, switches, or checkboxes; use detached so the message does not overlap the control.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
-      { guidance: false, description: 'Use the detached status variant on bordered inputs; reserve it for checkboxes, switches, and sliders.' },
       { guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text identifying the field. Always rendered for accessibility, optionally hidden visually.'},
       {name: 'Description', required: false, description: 'Helper text between the label and input explaining what to enter.'},
-      {name: 'Input slot', required: true, description: 'The input control wrapped by the field: TextInput, Select, DateInput, etc.'},
+      {name: 'Control slot', required: true, description: 'A custom, native, or third-party control that does not already render a field shell.'},
       {name: 'Status message', required: false, description: 'Inline validation feedback showing error, warning, or success with a message.'},
       {name: 'Optional/Required indicator', required: false, description: 'Badge next to the label showing whether the field is optional or required.'},
       {name: 'Label tooltip', required: false, description: 'Info icon at the end of the label with a tooltip explaining the field.'},
     ],
   },
+  examples: [
+    {
+      label: 'Wrap a custom control',
+      code: `
+function CustomSliderField() {
+  return (
+    <Field
+      label="Confidence"
+      inputID="confidence-slider"
+      description="Choose how strict the review should be."
+      descriptionID="confidence-help"
+      status={{type: 'success', message: 'Recommended default'}}
+      statusVariant="detached">
+      <input
+        id="confidence-slider"
+        type="range"
+        min={0}
+        max={100}
+        defaultValue={60}
+        aria-describedby="confidence-help"
+      />
+    </Field>
+  );
+}
+`,
+    },
+  ],
 };
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsZh = {
   usage: {
-    description: 'Field wraps any input control with a label, description, and validation status. Use it to build accessible forms with consistent labeling, optional/required indicators, and inline error, warning, or success feedback.',
+    description: 'Field is a low-level wrapper for custom, native, or third-party controls that do not already provide field label, description, and status UI. Use it when you need the Field shell around a control you own; use styled Astryx inputs like TextInput, Typeahead, and Select directly when they already expose label, description, and validation props.',
     bestPractices: [
+      { guidance: true, description: 'Wrap custom controls, native inputs, or third-party widgets that need labeling, helper text, optional/required indicators, or validation status.' },
       { guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
-      { guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },
-      { guidance: true, description: 'Add a description when the label alone does not explain what the field expects, like format hints or constraints.' },
+      { guidance: true, description: 'Use inputID and descriptionID to connect the label and description to the inner control with htmlFor and aria-describedby.' },
+      { guidance: false, description: 'Nest Field around styled inputs such as TextInput, Typeahead, Select, DateInput, or TextArea; those components already render their own Field shell.' },
+      { guidance: false, description: 'Use the attached status variant on non-bordered controls such as sliders, switches, or checkboxes; use detached so the message does not overlap the control.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
-      { guidance: false, description: 'Use the detached status variant on bordered inputs; reserve it for checkboxes, switches, and sliders.' },
       { guidance: false, description: 'Hide the label without providing an alternative way for the user to understand the field purpose.' },
     ],
   },
@@ -171,16 +211,17 @@ export const docsZh = {
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
   description:
-    'Form field wrapper providing label, description + optional/required indicators.',
+    'Low-level field shell for custom controls needing label/description/status.',
   usage: {
-    description: 'Field wraps input controls with label, description, and validation. Use for accessible forms with consistent labeling and inline feedback.',
+    description: 'Field wraps custom/native/third-party controls lacking field UI. Use TextInput, Typeahead, Select, DateInput, or TextArea directly when they already expose label/description/status props.',
     bestPractices: [
-      { guidance: true, description: 'Always provide a label for accessibility, even if visually hidden with isLabelHidden.' },
-      { guidance: true, description: 'Use the status prop with clear messages to provide inline validation feedback.' },
-      { guidance: true, description: 'Add a description when the label alone does not explain what the field expects: format hints or constraints.' },
+      { guidance: true, description: 'Wrap custom controls/widgets that need labeling, helper text, optional/required indicators, or validation status.' },
+      { guidance: true, description: 'Always provide a label; visually hide it only when context is clear.' },
+      { guidance: true, description: 'Wire inputID/descriptionID to htmlFor and aria-describedby on the inner control.' },
+      { guidance: false, description: 'Nest Field around styled inputs; it double-renders labels and status UI.' },
+      { guidance: false, description: 'Use attached status on sliders/switches/checkboxes; use detached so messages do not overlap.' },
       { guidance: false, description: 'Set both isOptional and isRequired on the same field.' },
-      { guidance: false, description: 'Use the detached status variant on bordered inputs; reserve it for checkboxes, switches, and sliders.' },
-      { guidance: false, description: 'Hide the label without providing an alternative way for user to understand the field purpose.' },
+      { guidance: false, description: 'Hide the label without another way to understand field purpose.' },
     ],
   },
 };

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}