@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/Divider/Divider.tsx

@@ -12,10 +12,10 @@
  * - /packages/core/src/Divider/Divider.doc.mjs
  * - /packages/core/src/Divider/Divider.test.tsx
  * - /apps/storybook/stories/Divider.stories.tsx
- * - /packages/cli/templates/blocks/components/Divider/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Divider/ (showcase blocks)
  */
 
-import type {ReactNode} from 'react';
+import {useId, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 
@@ -27,24 +27,7 @@ import {
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
-
-/**
- * Extensible variant map for Divider.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Divider' {
- *   interface DividerVariantMap {
- *     'accent': true;
- *   }
- * }
- * ```
- */
-export interface DividerVariantMap {
-  subtle: true;
-  strong: true;
-}
+import type {DividerVariantMap} from './index';
 
 /**
  * Divider variant type. Extensible via module augmentation of DividerVariantMap.
@@ -165,9 +148,19 @@ export function Divider({
   className,
   style,
   ref,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
   ...props
 }: DividerProps) {
   const isHorizontal = orientation === 'horizontal';
+  const labelId = useId();
+
+  // A separator does not derive its accessible name from its content, so the
+  // rendered label must be referenced explicitly via aria-labelledby to be
+  // exposed as the separator's name (WCAG 1.3.1). An explicit aria-label or
+  // aria-labelledby from the consumer takes precedence.
+  const resolvedLabelledBy =
+    ariaLabelledBy ?? (label && ariaLabel == null ? labelId : undefined);
 
   return (
     <div
@@ -175,6 +168,8 @@ export function Divider({
       {...props}
       role="separator"
       aria-orientation={orientation}
+      aria-label={ariaLabel}
+      aria-labelledby={resolvedLabelledBy}
       {...mergeProps(
         themeProps('divider', {variant, orientation}),
         stylex.props(
@@ -196,6 +191,7 @@ export function Divider({
       />
       {label && (
         <div
+          id={labelId}
           {...stylex.props(
             labelStyles.label,
             !isHorizontal && labelStyles.verticalLabel,

package/src/Divider/index.ts

@@ -11,9 +11,23 @@
  * SYNC: When modified, update /packages/core/src/Divider/Divider.doc.mjs
  */
 
+/**
+ * Extensible variant map for Divider.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Divider' {
+ *   interface DividerVariantMap {
+ *     'accent': true;
+ *   }
+ * }
+ * ```
+ */
+export interface DividerVariantMap {
+  subtle: true;
+  strong: true;
+}
+
 export {Divider} from './Divider';
-export type {
-  DividerProps,
-  DividerVariant,
-  DividerVariantMap,
-} from './Divider';
+export type {DividerProps, DividerVariant} from './Divider';

package/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenu',
@@ -26,15 +26,18 @@ export const docs = {
       {className: 'astryx-dropdown-menu'},
       {className: 'astryx-dropdown-menu-item', visualProps: ['size']},
       {
-        className: 'astryx-dropdown-menu-checkbox',
+        className: 'astryx-dropdown-menu-radio',
         visualProps: ['size'],
         states: ['checked', 'disabled'],
       },
       {
-        className: 'astryx-dropdown-menu-radio',
+        className: 'astryx-dropdown-menu-radio-dot',
         visualProps: ['size'],
         states: ['checked', 'disabled'],
       },
+      {className: 'astryx-dropdown-menu-section-heading'},
+      {className: 'astryx-dropdown-menu-divider'},
+      {className: 'astryx-dropdown-menu-indicator-icon'},
     ],
     vars: [
       {name: '--_dropdown-menu-radius', description: 'Border radius of the menu popup', default: 'var(--radius-element)', private: true},
@@ -104,7 +107,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface.',
@@ -117,7 +120,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'dropdown menu for actionable items in popup',
   usage: {

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -415,6 +415,41 @@ describe('DropdownMenu dividers', () => {
   });
 });
 
+describe('DropdownMenu theming slots', () => {
+  it('exposes a themeable slot on the section heading', () => {
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        items={[
+          {
+            type: 'section',
+            title: 'File Actions',
+            items: [{label: 'New'}],
+          },
+        ]}
+      />,
+    );
+
+    expect(screen.getByText('File Actions')).toHaveClass(
+      'astryx-dropdown-menu-section-heading',
+    );
+  });
+
+  it('exposes a themeable slot on the menu divider', () => {
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        items={[{label: 'Edit'}, {type: 'divider'}, {label: 'Delete'}]}
+      />,
+    );
+
+    const divider = screen.getByRole('separator', {hidden: true});
+    expect(divider).toHaveClass('astryx-dropdown-menu-divider');
+    // Still carries the base Divider slot so global divider theming applies too.
+    expect(divider).toHaveClass('astryx-divider');
+  });
+});
+
 describe('DropdownMenu button customization', () => {
   it('renders with different button variants', () => {
     const {rerender} = render(
@@ -781,4 +816,64 @@ describe('DropdownMenu keyboard access for menuitemradio/menuitemcheckbox (#3829
       screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
     ).toHaveFocus();
   });
+
+  it('moves focus to the item the mouse hovers, keeping a single highlight', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <DropdownMenuItem label="Duplicate" onClick={() => {}} />
+        <DropdownMenuItem label="Delete" onClick={() => {}} />
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    // Keyboard focus starts on the first item.
+    const edit = screen.getByRole('menuitem', {name: 'Edit', hidden: true});
+    const del = screen.getByRole('menuitem', {name: 'Delete', hidden: true});
+    edit.focus();
+    expect(edit).toHaveFocus();
+
+    // A mouse hover over another item moves focus to it, so the single
+    // focus-driven highlight follows the pointer instead of leaving two.
+    fireEvent.pointerMove(del, {pointerType: 'mouse'});
+    expect(del).toHaveFocus();
+    expect(edit).not.toHaveFocus();
+  });
+
+  it('does not move focus on hover for a disabled item', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <DropdownMenuItem label="Delete" isDisabled onClick={() => {}} />
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const edit = screen.getByRole('menuitem', {name: 'Edit', hidden: true});
+    const del = screen.getByRole('menuitem', {name: 'Delete', hidden: true});
+    edit.focus();
+
+    fireEvent.pointerMove(del, {pointerType: 'mouse'});
+    expect(edit).toHaveFocus();
+  });
+
+  it('does not move focus for a non-mouse (touch) pointer', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <DropdownMenuItem label="Delete" onClick={() => {}} />
+      </DropdownMenu>,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    const edit = screen.getByRole('menuitem', {name: 'Edit', hidden: true});
+    const del = screen.getByRole('menuitem', {name: 'Delete', hidden: true});
+    edit.focus();
+
+    fireEvent.pointerMove(del, {pointerType: 'touch'});
+    expect(edit).toHaveFocus();
+  });
 });

package/src/DropdownMenu/DropdownMenu.tsx

@@ -19,7 +19,7 @@
  * - /packages/core/src/DropdownMenu/DropdownMenu.test.tsx
  * - /packages/core/src/DropdownMenu/index.ts
  * - /apps/storybook/stories/DropdownMenu.stories.tsx
- * - /packages/cli/templates/blocks/components/DropdownMenu/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/DropdownMenu/ (showcase blocks)
  */
 
 import React, {
@@ -38,7 +38,11 @@ import {Icon} from '../Icon';
 import type {IconType} from '../Icon';
 
 import {renderDropdownItems} from './renderDropdownItems';
-import {MENU_ITEM_ROLES, MENU_ITEM_SELECTOR} from './menuItemRoles';
+import {
+  MENU_ITEM_ROLES,
+  MENU_ITEM_SELECTOR,
+  MENU_BOUNDARY_SELECTOR,
+} from './menuItemRoles';
 import {
   DropdownMenuContext,
   type DropdownMenuContextValue,
@@ -100,6 +104,12 @@ export interface DropdownMenuItemData {
   onClick?: () => void;
   isDisabled?: boolean;
   icon?: ReactNode | IconType;
+  /**
+   * Nested submenu entries. When present, this row becomes a submenu (a
+   * flyout revealing `items`) instead of a leaf action — no separate item
+   * "type" is needed. Data-mode parity for the compound DropdownMenuSubMenu API.
+   */
+  items?: DropdownMenuOption[];
 }
 
 export interface DropdownMenuDivider {
@@ -200,6 +210,14 @@ export function DropdownMenu({
   const items = ('items' in props ? props.items : undefined) ?? [];
   const children = props.children;
 
+  // Extract BaseProps pass-throughs (aria-*, id, event handlers) from the
+  // discriminated-union rest bag so they can be forwarded to the menu element.
+  const {
+    items: _items,
+    children: _children,
+    ...rest
+  } = props as Record<string, unknown>;
+
   const menuId = useId();
   const menuSize = button.size ?? 'md';
   const buttonRef = useRef<HTMLButtonElement>(null);
@@ -265,23 +283,18 @@ export function DropdownMenu({
     handleKeyDown: listNavKeyDown,
     focusFirst,
     focusItem,
+    ownsEvent,
+    getItems: getMenuItems,
   } = useListFocus<HTMLDivElement>({
     itemSelector: MENU_ITEM_SELECTOR,
+    boundarySelector: MENU_BOUNDARY_SELECTOR,
     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>(MENU_ITEM_SELECTOR),
-          )
-        : [],
-    [listRef],
-  );
+  // item whose label starts with the typed text (menus-11). Reuses the hook's
+  // scoped item collection so an inline submenu flyout's items aren't swept in.
   const typeahead = useTypeahead({
     getItemLabels: () => getMenuItems().map(el => el.textContent),
     onMatch: focusItem,
@@ -307,6 +320,11 @@ export function DropdownMenu({
   // Extend useListFocus with Enter/Space activation + typeahead
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      // A submenu flyout renders inline inside this menu; its key events bubble
+      // up here. Let that level own them — only handle events from this level.
+      if (!ownsEvent(e)) {
+        return;
+      }
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();
         const focused = document.activeElement as HTMLElement | null;
@@ -334,7 +352,7 @@ export function DropdownMenu({
       }
       listNavKeyDown(e);
     },
-    [listNavKeyDown, closeMenu, typeahead],
+    [listNavKeyDown, closeMenu, typeahead, ownsEvent],
   );
 
   const openAndFocus = useCallback(() => {
@@ -435,6 +453,7 @@ export function DropdownMenu({
 
       {popover.render(
         <div
+          {...rest}
           ref={listRef}
           id={menuId}
           role="menu"

package/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenuCheckboxItem',

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -4,38 +4,39 @@
 
 /**
  * @file DropdownMenuCheckboxItem.tsx
- * @input React, stylex, Item + Icon + DropdownMenu context + tokens from core
+ * @input React, stylex, Item + CheckboxInput + DropdownMenu context + tokens from core
  * @output DropdownMenuCheckboxItem — a standalone checkable menu item.
  * @position Sub-component; used inside DropdownMenu.
  *
  * A menu item that toggles an independent boolean (role="menuitemcheckbox").
- * Unlike CheckboxInput, there is no nested native <input>: the row itself owns
- * the role and aria-checked, per the WAI-ARIA menuitemcheckbox pattern.
- * Keyboard navigation (arrows/typeahead) and Enter/Space activation come from
- * the parent DropdownMenu's useListFocus + activation path, which matches
- * menuitemcheckbox alongside plain menuitem rows.
+ * Unlike CheckboxInput, there is no nested native <input> that participates in
+ * accessibility: the row itself owns the role and aria-checked, per the
+ * WAI-ARIA menuitemcheckbox pattern. Keyboard navigation (arrows/typeahead) and
+ * Enter/Space activation come from the parent DropdownMenu's useListFocus +
+ * activation path, which matches menuitemcheckbox alongside plain menuitem rows.
  *
- * The square checkbox visual is decorative (aria-hidden) — the row owns the
- * checked state. Its size is derived from the menu's item size (a `sm` menu
- * gets the compact control; `md`/`lg` get the standard one) and it swaps to the
- * inline-end of the row on coarse-pointer (touch) devices via CSS `order`, so
- * it lands where selection toggles are conventionally placed on mobile. The
- * checkmark uses the `check` icon from the active theme's icon registry.
+ * The checkbox visual composes the real CheckboxInput primitive so its checkmark
+ * matches CheckboxListItem and picks up the standard `checkbox` theming slots.
+ * It is purely decorative: the composed control is wrapped in an element that is
+ * both `aria-hidden` and `inert`, so it contributes nothing to the row's
+ * accessible name, and its native <input> and sr-only label stay out of the tab
+ * order and the accessibility tree while pointer clicks fall through to the row
+ * — the same shim MultiSelector uses. The row owns the checked state and
+ * accessible name. The control size is derived from the menu's item size (a
+ * `sm` menu gets the compact control; `md`/`lg` get the standard one) and it
+ * swaps to the inline-end of the row on coarse-pointer (touch) devices via CSS
+ * `order`, so it lands where selection toggles are conventionally placed on
+ * mobile.
  */
 
-import {useCallback, type ReactNode} from 'react';
+import {useCallback, type PointerEvent, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Icon, renderIconSlot, type IconType} from '../Icon';
+import {renderIconSlot, type IconType} from '../Icon';
+import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
 import {Item} from '../Item';
 import {useDropdownMenuContext} from './DropdownMenuContext';
-import {
-  colorVars,
-  spacingVars,
-  radiusVars,
-  durationVars,
-  easeVars,
-  borderVars,
-} from '../theme/tokens.stylex';
+import {focusMenuItemOnHover} from './menuItemHover';
+import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {mergeProps, themeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 
@@ -47,7 +48,6 @@ const styles = stylex.create({
     backgroundColor: {
       default: 'transparent',
       ':focus': colorVars['--color-overlay-hover'],
-      ':hover': colorVars['--color-overlay-hover'],
     },
     cursor: 'pointer',
     outline: 'none',
@@ -58,22 +58,13 @@ const styles = stylex.create({
   },
   // Rendered in Item's `marker` slot as a raw flex child, so `order` moves it
   // relative to the label within the row. On touch it moves to the inline-end.
-  box: {
+  // `aria-hidden` + `inert` + pointer-events:none keep the composed CheckboxInput
+  // decorative: it adds no accessible name, and clicks fall through to the row,
+  // which owns the role and activation.
+  markerBox: {
     display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
     flexShrink: 0,
-    boxSizing: 'border-box',
-    borderWidth: borderVars['--border-width'],
-    borderStyle: 'solid',
-    borderRadius: radiusVars['--radius-inner'],
-    color: colorVars['--color-on-accent'],
-    transitionProperty: 'background-color, border-color',
-    transitionDuration: {
-      default: durationVars['--duration-fast'],
-      '@media (prefers-reduced-motion: reduce)': '0s',
-    },
-    transitionTimingFunction: easeVars['--ease-standard'],
+    pointerEvents: 'none',
     order: {
       default: 0,
       '@media (pointer: coarse)': 1,
@@ -83,19 +74,6 @@ const styles = stylex.create({
       '@media (pointer: coarse)': 'auto',
     },
   },
-  unchecked: {
-    borderColor: colorVars['--color-border-emphasized'],
-    backgroundColor: colorVars['--color-background-surface'],
-  },
-  checked: {
-    borderColor: colorVars['--color-accent'],
-    backgroundColor: colorVars['--color-accent'],
-  },
-});
-
-const boxSizeStyles = stylex.create({
-  sm: {width: 18, height: 18},
-  md: {width: 22, height: 22},
 });
 
 export interface DropdownMenuCheckboxItemProps extends Omit<
@@ -180,6 +158,12 @@ export function DropdownMenuCheckboxItem({
   const menuSize = ctx?.menuSize ?? 'md';
   const controlSize = menuSize === 'sm' ? 'sm' : 'md';
 
+  // The composed checkbox is decorative and inert, so its label never reaches
+  // the accessibility tree — the row's `label` prop provides the announced
+  // name. CheckboxInput still requires a string label, so pass one through when
+  // the row label is a plain string.
+  const checkboxLabel = typeof label === 'string' ? label : '';
+
   const handleClick = useCallback(() => {
     if (isDisabled) {
       return;
@@ -190,29 +174,28 @@ export function DropdownMenuCheckboxItem({
     }
   }, [isDisabled, onChange, value, hasCloseOnSelect, ctx]);
 
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
+    [isDisabled],
+  );
+
   return (
     <Item
       {...rest}
       role="menuitemcheckbox"
       aria-checked={value}
       tabIndex={isDisabled ? undefined : -1}
+      onPointerMove={handlePointerMove}
       marker={
-        <span
-          aria-hidden="true"
-          {...mergeProps(
-            themeProps('dropdown-menu-checkbox', {
-              size: controlSize,
-              checked: value ? 'checked' : null,
-              disabled: isDisabled ? 'disabled' : null,
-            }),
-            stylex.props(
-              styles.box,
-              boxSizeStyles[controlSize],
-              value ? styles.checked : styles.unchecked,
-            ),
-          )}>
-          {value && <Icon icon="check" size="sm" color="inherit" />}
-        </span>
+        <div aria-hidden="true" inert {...stylex.props(styles.markerBox)}>
+          <CheckboxInput
+            label={checkboxLabel}
+            isLabelHidden
+            value={value}
+            isDisabled={isDisabled}
+            size={controlSize}
+          />
+        </div>
       }
       startContent={
         icon

package/src/DropdownMenu/DropdownMenuItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenuItem',

package/src/DropdownMenu/DropdownMenuItem.tsx

@@ -20,10 +20,10 @@
  * - /packages/core/src/DropdownMenu/DropdownMenu.test.tsx
  * - /packages/core/src/DropdownMenu/index.ts
  * - /apps/storybook/stories/DropdownMenu.stories.tsx
- * - /packages/cli/templates/blocks/components/DropdownMenu/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/DropdownMenu/ (showcase blocks)
  */
 
-import {useCallback, type ReactNode} from 'react';
+import {useCallback, type PointerEvent, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {renderIconSlot, type IconType} from '../Icon';
 import {Item} from '../Item';
@@ -36,6 +36,7 @@ import {
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useDropdownMenuContext} from './DropdownMenuContext';
+import {focusMenuItemOnHover} from './menuItemHover';
 import {themeProps} from '../utils/themeProps';
 
 const menuItemStyles = stylex.create({
@@ -51,11 +52,10 @@ const menuItemStyles = stylex.create({
     backgroundColor: {
       default: 'transparent',
       ':focus': colorVars['--color-overlay-hover'],
-      ':hover': colorVars['--color-overlay-hover'],
     },
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left',
+    textAlign: 'start',
     outline: 'none',
   },
   disabled: {
@@ -129,10 +129,16 @@ export function DropdownMenuItem({
     ctx?.closeMenu();
   }, [isDisabled, onClick, ctx]);
 
+  const handlePointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
+    [isDisabled],
+  );
+
   return (
     <Item
       role="menuitem"
       tabIndex={isDisabled ? undefined : -1}
+      onPointerMove={handlePointerMove}
       startContent={
         icon
           ? renderIconSlot(icon, {size: 'sm', color: 'secondary'})

package/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenuRadioGroup',
@@ -22,16 +22,10 @@ export const docs = {
       description: 'Callback fired when the selected value changes.',
     },
     {
-      name: 'aria-label',
+      name: 'label',
       type: 'string',
       description:
-        'Accessible label for the group. Required (or aria-labelledby) so screen readers announce the radios as a named set, e.g. "Sort by".',
-    },
-    {
-      name: 'aria-labelledby',
-      type: 'string',
-      description:
-        'The id of an element that labels the group, as an alternative to aria-label.',
+        'Accessible name for the group, applied as aria-label so screen readers announce the radios as a named set, e.g. "Sort by". Required. Pass aria-labelledby (via base props) instead when the name already exists as a visible element.',
     },
     {
       name: 'hasCloseOnSelect',
@@ -57,8 +51,7 @@ export const docsZh = {
   propDescriptions: {
     value: '组中当前选中的值。尚无选中项时传 undefined。',
     onChange: '所选值变化时触发的回调。',
-    'aria-label': '组的无障碍标签。必需（或 aria-labelledby），以便屏幕阅读器将单选项作为命名集合朗读。',
-    'aria-labelledby': '标记该组的元素 id，作为 aria-label 的替代。',
+    label: '组的无障碍名称，作为 aria-label 应用，以便屏幕阅读器将单选项作为命名集合朗读，例如“Sort by”。必需。当名称已作为可见元素存在时，可改用 aria-labelledby（通过基础属性）。',
     hasCloseOnSelect: '选择某值是否关闭菜单。默认关闭。',
     children: '组成该组的 DropdownMenuRadioItem。',
   },
@@ -72,8 +65,7 @@ export const docsDense = {
   propDescriptions: {
     value: 'selected value (undefined = none)',
     onChange: 'fired when selected value changes',
-    'aria-label': 'accessible group name (or aria-labelledby); required',
-    'aria-labelledby': 'id of labelling element (alt to aria-label)',
+    label: 'accessible group name (applied as aria-label); required',
     hasCloseOnSelect: 'close menu on select (default true)',
     children: 'the DropdownMenuRadioItems',
   },