@astryxdesign/core 0.7.3-canary.f94e962 → 0.7.3

package/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs

@@ -8,7 +8,52 @@ export const docs = {
   displayName: 'Dropdown Menu Radio Group',
   isHiddenFromOverview: true,
   description:
-    'A single-select group of radio menu items (role="group" of menuitemradio). Owns the selected value and lays its items out with the menu\'s inter-item gap.',
+    'A controlled, named single-select group of DropdownMenuRadioItem children (role="group" of menuitemradio). Owns value propagation, close policy, root composition, and the menu inter-item gap; the parent DropdownMenu owns keyboard navigation.',
+  usage: {
+    description:
+      'Use DropdownMenuRadioGroup inside compound-mode DropdownMenu when several commands represent one mutually exclusive choice. Keep value in caller state, provide a concise accessible label, and render each choice as DropdownMenuRadioItem.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Keep value controlled and update it from onChange so checked state follows caller data.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a concise label even when aria-labelledby points to visible text; label remains required and supplies the aria-label fallback.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set hasCloseOnSelect=false only when the menu must stay open to show another selection or an in-place result.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place buttons, links, checkboxes, or arbitrary menu rows inside the radio group.',
+      },
+      {
+        guidance: false,
+        description:
+          'Add a second key handler or roving-focus model; DropdownMenu owns keyboard navigation.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Group',
+        required: true,
+        description:
+          'The role="group" root that owns the accessible name, controlled-selection context, close policy, root inputs, and inter-item gap.',
+      },
+      {
+        name: 'Radio items',
+        required: true,
+        description:
+          'DropdownMenuRadioItem children; each child owns its menuitemradio role, checked state, content, and indicator paint.',
+      },
+    ],
+  },
   playground: {
     wrapper: {
       component: 'DropdownMenu',
@@ -42,17 +87,20 @@ export const docs = {
       type: 'string | undefined',
       description:
         'The currently selected value in the group. Pass undefined when nothing is selected yet.',
+      required: true,
     },
     {
       name: 'onChange',
       type: '(value: string) => void',
       description: 'Callback fired when the selected value changes.',
+      required: true,
     },
     {
       name: 'label',
       type: 'string',
       description:
-        '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.',
+        'Accessible name for the group, applied as aria-label so screen readers announce the radios as a named set, e.g. "Sort by". Required even when aria-labelledby (via base props) points to visible text; that visible reference becomes the computed name while label remains the fallback.',
+      required: true,
     },
     {
       name: 'hasCloseOnSelect',
@@ -61,40 +109,47 @@ export const docs = {
       description:
         'Whether selecting a value closes the menu. Radio items default to closing on selection (a single-choice commit).',
     },
+    {
+      name: 'ref',
+      type: 'React.Ref<HTMLDivElement>',
+      description: 'Ref forwarded to the role="group" root.',
+    },
     {
       name: 'children',
       type: 'ReactNode',
       description: 'The DropdownMenuRadioItems that make up the group.',
+      required: true,
     },
   ],
 };
 
 export const docsZh = {
   name: 'DropdownMenuRadioGroup',
-  isHiddenFromOverview: true,
   displayName: 'Dropdown Menu Radio Group',
   description:
-    '单选的单选菜单项组（menuitemradio 的 role="group"）。持有所选值，并以菜单的项间距布局其子项。',
+    'DropdownMenu 中由调用方控制且有名称的单选组（menuitemradio 的 role="group"）。该组负责值传递、关闭策略、根元素组合和菜单项间距；父 DropdownMenu 负责键盘导航。',
   propDescriptions: {
     value: '组中当前选中的值。尚无选中项时传 undefined。',
     onChange: '所选值变化时触发的回调。',
     label:
-      '组的无障碍名称，作为 aria-label 应用，以便屏幕阅读器将单选项作为命名集合朗读，例如“Sort by”。必需。当名称已作为可见元素存在时，可改用 aria-labelledby（通过基础属性）。',
+      '组的无障碍名称，作为 aria-label 应用。即使 aria-labelledby（通过基础属性）指向可见文本，label 仍然必需并作为后备名称。',
     hasCloseOnSelect: '选择某值是否关闭菜单。默认关闭。',
+    ref: '转发到 role="group" 根元素的 ref。',
     children: '组成该组的 DropdownMenuRadioItem。',
   },
 };
 
 export const docsDense = {
   name: 'DropdownMenuRadioGroup',
-  isHiddenFromOverview: true,
   displayName: 'Dropdown Menu Radio Group',
-  description: 'single-select group of menuitemradio; owns selected value',
+  description:
+    'controlled named menuitemradio group; owns value propagation, close policy, root inputs, and item gap',
   propDescriptions: {
     value: 'selected value (undefined = none)',
     onChange: 'fired when selected value changes',
     label: 'accessible group name (applied as aria-label); required',
     hasCloseOnSelect: 'close menu on select (default true)',
+    ref: 'forwarded to the role="group" root',
     children: 'the DropdownMenuRadioItems',
   },
 };

package/src/DropdownMenu/DropdownMenuRadioGroup.spec.md

@@ -0,0 +1,190 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuRadioGroup
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming, testing]
+verified_by:
+  [
+    packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx,
+    packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
+    packages/core/src/DropdownMenu/__tests__/Menu.a11y.test.tsx,
+    apps/storybook/stories/DropdownMenuRadioGroup.stories.tsx,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-test-sufficiency,
+    architecture:interaction-modality,
+  ]
+contributing: []
+system_specs: [spec:AST-020, spec:AST-029]
+---
+
+# DropdownMenuRadioGroup component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | One controlled, named single-selection group of `DropdownMenuRadioItem` children with value, change callback, close policy, root inputs, and an explicit React 19 ref.                            |
+| Behavior                | The group supplies selection and close-policy context; radio items emit values; the parent DropdownMenu owns keyboard navigation and menu lifecycle.                                              |
+| End-user impact         | Assistive technology encounters one named group with exactly one current choice when a value matches, while pointer and keyboard selection stay aligned.                                          |
+| Builder impact          | Keep the value controlled, provide a stable accessible label, and place only DropdownMenuRadioItem options inside the group.                                                                      |
+| Compatibility/readiness | Patch-compatible additive `ref` prop on the existing group root. Existing runtime behavior, exports, defaults, and theme surfaces remain unchanged; authority stays `draft` until owner approval. |
+| Review checks           | Reject unnamed groups, local selection state, dropped root inputs, a second keyboard owner, or a close policy that bypasses the controlled callback.                                              |
+| Governing rules         | WAI-ARIA menu pattern; `architecture:public-component-api/INV5–INV9`; `architecture:component-test-sufficiency/INV1–INV7`; `spec:AST-020/FR1,FR2,FR6`.                                            |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuRadioGroup renders one named `role="group"` wrapper inside the
+pointer presentation of DropdownMenu. It owns controlled selection context,
+close policy, root composition, and the tokenized gap between children.
+DropdownMenuRadioItem owns each `menuitemradio` row and its checked state;
+DropdownMenu owns focus movement, typeahead, keyboard activation, presentation,
+and menu open/close lifecycle.
+
+## Compatibility and migration
+
+- Released default preserved: yes (`hasCloseOnSelect=true`).
+- Compatibility class: additive patch; declares and forwards the React 19 `ref`
+  prop to the existing group root without changing existing behavior.
+- Controlled behavior: `value` is caller-owned and `onChange` is the only commit path.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One `role="group"` root with an `aria-label` from the required `label` prop.
+- Controlled `value`, `onChange`, and `hasCloseOnSelect` context for radio items.
+- Composition of `children`, supported host inputs, ref, `className`, `style`, and
+  `xstyle` on the group root.
+- Column layout and the semantic menu inter-item gap.
+
+**Does not own / non-goals**
+
+- The `menuitemradio` role, `aria-checked`, disabled behavior, indicator paint,
+  label, description, icon, or end content — owned by DropdownMenuRadioItem.
+- Focus entry, arrow-key navigation, typeahead, Enter/Space synthesis, and menu
+  close implementation — owned by DropdownMenu and shared menu hooks.
+- Touch and bottom-sheet selectable-row rendering — owned by the parent presentation.
+- Uncontrolled selection state or child-value registration.
+
+## Public concepts
+
+| Concept         | Closed values or states                       | Meaning                                                              | Default  | Owner                    | Stability | Invalid-value behavior                                |
+| --------------- | --------------------------------------------- | -------------------------------------------------------------------- | -------- | ------------------------ | --------- | ----------------------------------------------------- |
+| Selection       | matching value; no matching value             | Controls which child reports checked.                                | none     | caller and radio item    | stable    | No match leaves every child unchecked.                |
+| Commit          | child value                                   | Emits the selected child value through `onChange`.                   | required | group context            | stable    | Children outside the group throw from the item owner. |
+| Close policy    | close; remain open                            | Controls whether an item asks DropdownMenu to close after selection. | close    | group context and parent | stable    | Omission closes.                                      |
+| Accessible name | required label; optional labelledby           | Names the group; `aria-labelledby` may point at visible text.        | label    | group root               | stable    | `label` remains required by the public type.          |
+| Root surface    | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the group root while preserving its role and name.           | omitted  | public component API     | stable    | Accepted inputs compose; owned role and label win.    |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                                          | Basis                                                       | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
+| FR1 | The root MUST expose `role="group"` and a non-empty accessible name. The required `label` supplies `aria-label`; caller `aria-labelledby` MAY reference visible text.        | WAI-ARIA menu pattern; released source/docs                 | verify             |
+| FR2 | The group MUST remain controlled. It MUST compare each radio item's value with caller `value` and MUST emit a selected child value only through caller `onChange`.           | Released public API and focused tests                       | verify             |
+| FR3 | `hasCloseOnSelect` MUST default to true. When false, successful selection MUST update through `onChange` while the parent menu remains open.                                 | Released behavior and focused tests                         | verify             |
+| FR4 | DropdownMenu MUST remain the only keyboard owner. The group adds no tab stop, key handler, typeahead, or click synthesis; it only provides context to child rows.            | `architecture:interaction-modality`; parent tests           | verify             |
+| FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` MUST reach or compose on the group root without replacing the owned role or `aria-label`.    | `architecture:public-component-api/INV5–INV9`; source/tests | verify             |
+| FR6 | The wrapper MUST remain a logical column whose tokenized gap matches the surrounding menu's item rhythm; it MUST NOT add component-specific directional paint or navigation. | Current source; token and bidirectionality rules            | verify             |
+
+### Allowed variation
+
+- **AV1 — Children.** The number, labels, descriptions, icons, and supporting
+  content of DropdownMenuRadioItem children may vary.
+- **AV2 — Selection.** Any string value, including no matching value, may be
+  caller-controlled without adding local group state.
+- **AV3 — Root styling.** Caller style inputs may extend the wrapper while the
+  role, accessible label, column flow, and child semantics remain intact.
+
+### Representative states
+
+| State             | Required invariant                                                         | Allowed variation                    |
+| ----------------- | -------------------------------------------------------------------------- | ------------------------------------ |
+| Matching value    | Exactly the matching child reports `aria-checked=true`.                    | Child content and menu size.         |
+| No matching value | Every child reports `aria-checked=false`.                                  | Empty or unmatched caller value.     |
+| Default close     | Selection emits the value and closes through the parent.                   | Pointer or synthesized keyboard act. |
+| Retained open     | Selection emits the value, updates controlled state, and leaves menu open. | Result copy and selected child.      |
+| RTL / narrow      | Column order and tokenized gap hold with no horizontal overflow.           | Parent menu placement.               |
+
+### Transformation and precedence order
+
+- **ORD1 — Selection.** Child activation → disabled guard in the item owner →
+  group `onChange(value)` → optional parent close.
+- **ORD2 — Root composition.** Base column/gap → caller `xstyle`; supported host
+  inputs and class/style compose while owned role and label remain fixed.
+
+### Performance and resources
+
+- **PR1 — Context only.** The group memoizes a small context value and owns no
+  Effect, listener, observer, timer, request, DOM read, or resource lifecycle.
+
+## Accessibility contract
+
+- **AR1 — Named group.** The wrapper is one named `group` inside the parent menu.
+- **AR2 — Radio rows.** Child items own `menuitemradio` and `aria-checked`; the
+  group does not add nested native inputs or duplicate row semantics.
+- **AR3 — Keyboard ownership.** DropdownMenu owns focus collection and activation;
+  the group itself never enters the tab or arrow-key sequence.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                               | Representation authority           | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------- | ---------------------------------- | -------------- | ------------------ |
+| Group wrapper    | Logical column with the menu's semantic inter-item gap.          | Current source and spacing tokens  | structural     | FR1, FR5, FR6      |
+| Selected child   | One child reflects caller value through `aria-checked`.          | DropdownMenuRadioItem              | prominent      | FR2, AR2           |
+| Direction/narrow | Child order and gap hold without physical-direction assumptions. | Bidirectionality and parent layout | structural     | FR6                |
+
+No new component-local visual decision is settled by this draft.
+
+## Family and system relationships
+
+- `architecture:public-component-api` owns root input composition and released compatibility.
+- `architecture:component-test-sufficiency` owns proportionate observable evidence.
+- `architecture:interaction-modality` and DropdownMenu own keyboard behavior.
+- `spec:AST-020` supplies WCAG/APG adoption and evidence-layer boundaries.
+- `spec:AST-029` keeps this observational draft separate from the audit receipt.
+
+## Verification map
+
+| Contract       | Verification                                                                   | Representative states                | Mutation or failure expectation                                                           | Audit section                               |
+| -------------- | ------------------------------------------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------- |
+| FR1–FR4, AR1–3 | `DropdownMenuSelectable.test.tsx`; reusable Menu contracts; scoped axe         | matching, none, close, retained-open | An unnamed group, wrong checked row, skipped callback, unwanted close, or key owner fails | `audit:DropdownMenuRadioGroup/§1,§4,§6`     |
+| FR5            | root/ref/handler tests; lint and typecheck                                     | ref, host attributes, class/style    | An accepted input is dropped or overrides the owned role/name                             | `audit:DropdownMenuRadioGroup/§3`           |
+| FR6            | source-hashed RTL N/A receipt plus exact-head Neutral/Butter/RTL/narrow frames | LTR, RTL, 320px, light/dark          | Physical direction, lost tokenized gap, collapsed geometry, or horizontal overflow fails  | `audit:DropdownMenuRadioGroup/§2,§5,§9,§10` |
+
+## Decision log
+
+None. This draft records current facts and introduces no product decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit scores,
+screenshot matrices, implementation steps, or parent/item contracts. The audit
+pull request owns the closed run evidence required by `spec:AST-029/FR5`.

package/src/DropdownMenu/DropdownMenuRadioGroup.tsx

@@ -14,7 +14,7 @@
  * menuitemradio rows.
  */
 
-import {useMemo, type ReactNode} from 'react';
+import {useMemo, type ReactNode, type Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
@@ -51,9 +51,9 @@ export interface DropdownMenuRadioGroupProps extends Omit<
   /**
    * Accessible name for the group, announced by screen readers so the radios
    * read as a named set (e.g. "Sort by"). Applied as the group's `aria-label`.
-   * Required -- an unnamed radio group is an accessibility defect. Pass
-   * `aria-labelledby` (via base props) instead if the name already exists as a
-   * visible element on the page.
+   * Required even when `aria-labelledby` (via base props) points to visible
+   * text; that visible reference becomes the computed name while `label`
+   * remains the fallback.
    */
   label: string;
   /**
@@ -63,6 +63,10 @@ export interface DropdownMenuRadioGroupProps extends Omit<
    * @default true
    */
   hasCloseOnSelect?: boolean;
+  /**
+   * Ref forwarded to the role="group" root.
+   */
+  ref?: Ref<HTMLDivElement>;
   /**
    * The `DropdownMenuRadioItem`s that make up the group.
    */
@@ -92,6 +96,7 @@ export function DropdownMenuRadioGroup({
   label,
   hasCloseOnSelect = true,
   children,
+  ref,
   xstyle,
   className,
   style,
@@ -105,6 +110,7 @@ export function DropdownMenuRadioGroup({
   return (
     <div
       {...rest}
+      ref={ref}
       role="group"
       aria-label={label}
       {...mergeProps(stylex.props(styles.group, xstyle), {className, style})}>

package/src/DropdownMenu/DropdownMenuSelectable.test.tsx

@@ -9,6 +9,7 @@
  *   outcomes live in their reusable contracts; Menu retains navigation.
  */
 
+import {useState} from 'react';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -328,6 +329,98 @@ describe('DropdownMenuRadioGroup / RadioItem', () => {
       screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
     );
     expect(onChange).toHaveBeenCalledWith('oldest');
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveAttribute('aria-checked', 'true');
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    ).toHaveAttribute('aria-checked', 'false');
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the menu open while controlled selection updates when requested', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    function ControlledGroup() {
+      const [value, setValue] = useState('newest');
+      return (
+        <DropdownMenu button={{label: 'Sort'}}>
+          <DropdownMenuRadioGroup
+            value={value}
+            onChange={nextValue => {
+              onChange(nextValue);
+              setValue(nextValue);
+            }}
+            label="Sort by"
+            hasCloseOnSelect={false}>
+            <DropdownMenuRadioItem value="newest" label="Newest" />
+            <DropdownMenuRadioItem value="oldest" label="Oldest" />
+          </DropdownMenuRadioGroup>
+        </DropdownMenu>
+      );
+    }
+
+    render(<ControlledGroup />);
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+    const oldest = screen.getByRole('menuitemradio', {
+      name: 'Oldest',
+      hidden: true,
+    });
+    await user.click(oldest);
+
+    expect(onChange).toHaveBeenCalledWith('oldest');
+    expect(oldest).toHaveAttribute('aria-checked', 'true');
+    expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled();
+  });
+
+  it('names and composes the group root when no value matches', async () => {
+    const user = userEvent.setup();
+    const ref = vi.fn();
+    const onClick = vi.fn();
+    render(
+      <>
+        <span id="sort-label">Visible sort label</span>
+        <DropdownMenu button={{label: 'Sort'}}>
+          <DropdownMenuRadioGroup
+            ref={ref}
+            role="tree"
+            aria-label="Consumer label"
+            aria-labelledby="sort-label"
+            data-owner="consumer"
+            className="consumer-group"
+            style={{inlineSize: 240}}
+            onClick={onClick}
+            value={undefined}
+            onChange={() => {}}
+            label="Sort fallback">
+            <DropdownMenuRadioItem value="newest" label="Newest" />
+            <DropdownMenuRadioItem value="oldest" label="Oldest" />
+          </DropdownMenuRadioGroup>
+        </DropdownMenu>
+      </>,
+    );
+    await user.click(screen.getByRole('button', {name: /Sort/}));
+
+    const group = screen.getByRole('group', {
+      name: 'Visible sort label',
+      hidden: true,
+    });
+    expect(group).toHaveAttribute('role', 'group');
+    expect(group).toHaveAttribute('aria-label', 'Sort fallback');
+    expect(group).toHaveAttribute('aria-labelledby', 'sort-label');
+    expect(group).toHaveAttribute('data-owner', 'consumer');
+    expect(group).toHaveClass('consumer-group');
+    expect(group).toHaveStyle({inlineSize: '240px'});
+    expect(ref).toHaveBeenCalledWith(group);
+    expect(
+      screen
+        .getAllByRole('menuitemradio', {hidden: true})
+        .every(item => item.getAttribute('aria-checked') === 'false'),
+    ).toBe(true);
+
+    fireEvent.click(group);
+    expect(onClick).toHaveBeenCalledTimes(1);
   });
 
   it('throws when a radio item is used outside a group', () => {