Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[Component Audit] DropdownMenuRadioGroup: let builders reach the group root (#7911)

Cindy Zhang2f47a4afe886
diff --git a/.changeset/dropdown-menu-radio-group-audit-docs.md b/.changeset/dropdown-menu-radio-group-audit-docs.md
new file mode 100644
index 0000000000..10bb5ea39d
--- /dev/null
+++ b/.changeset/dropdown-menu-radio-group-audit-docs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Forward DropdownMenuRadioGroup refs and clarify its controlled selection, naming, close policy, and root composition guidance.
+
+@cixzhang
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9031d4554a..690c903092 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2927,6 +2927,38 @@ jobs:
retention-days: 30
if-no-files-found: error
+ # DropdownMenuRadioGroup owns controlled value propagation, the named
+ # role=group wrapper, close policy, and the tokenized gap between radio
+ # rows. Parent DropdownMenu owns keyboard navigation; each radio item owns
+ # menuitemradio semantics and indicator paint.
+ - name: Run DropdownMenuRadioGroup audit browser evidence
+ if: ${{ !cancelled() && github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, '[Component Audit] DropdownMenuRadioGroup:') }}
+ env:
+ ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ run: |
+ status=0
+ node .github/scripts/accessibility-audit.js \
+ --storybook-dir apps/storybook/dist \
+ --output dropdown-menu-radio-group-a11y-report.json \
+ --components DropdownMenuRadioGroup \
+ --baseline .github/a11y-baseline.json \
+ --fail-on-new || status=1
+ pnpm exec playwright test \
+ packages/core/src/DropdownMenu/__tests__/DropdownMenuRadioGroupAudit.a11y.chromium.spec.ts \
+ --project chromium || status=1
+ exit "$status"
+
+ - name: Upload DropdownMenuRadioGroup audit evidence
+ if: always() && github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, '[Component Audit] DropdownMenuRadioGroup:')
+ uses: actions/upload-artifact@v7
+ with:
+ name: dropdown-menu-radio-group-audit-evidence-${{ needs.build-storybook.outputs.short_hash }}
+ path: |
+ dropdown-menu-radio-group-a11y-report.json
+ dropdown-menu-radio-group-audit-evidence/
+ retention-days: 30
+ if-no-files-found: error
+
# ContextMenu owns pointer and touch presentations across cursor anchoring,
# selectable rows, sections, inline triggers, RTL, and narrow viewports.
# Its audit lane binds the rendered matrix to the exact pull-request head.
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index 889476ffaf..5206f413bf 100644
--- a/apps/storybook/rtl-audit/verified-not-applicable.json
+++ b/apps/storybook/rtl-audit/verified-not-applicable.json
@@ -406,5 +406,14 @@
"packages/core/src/DropdownMenu/index.ts": "sha256:59bf02be4a577cbecf3ad7e981e2577602375892f74548593aa9b998cae733fa",
"packages/core/src/Divider/Divider.tsx": "sha256:37bfa57103fdc546226fe751844bb193490439bd990b6bc9bced8f6ced99618d"
}
+ },
+ {
+ "component": "core/DropdownMenuRadioGroup",
+ "reason": "DropdownMenuRadioGroup owns one block-axis role=group wrapper whose children remain in document order with a symmetric tokenized gap. It renders no component-owned text, directional glyph, physical inline placement, reordered control, horizontal scroll or drag, side-placed overlay, or horizontal keyboard behavior; DropdownMenu owns placement and navigation, while DropdownMenuRadioItem owns each row and indicator. Exact-head frames still render RTL to confirm inherited direction without adding a component-owned RTL dimension.",
+ "evidence": {
+ "apps/storybook/stories/DropdownMenuRadioGroup.stories.tsx": "sha256:7548ad7bf7c06f438e243774a8f41d4043defc1a122467747c5ff955f202aee1",
+ "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.tsx": "sha256:3be897ab21dcc6a37fb7ab8a1b6d48254e406c544d95a3b939dfc6593ea99cf1",
+ "packages/core/src/DropdownMenu/index.ts": "sha256:59bf02be4a577cbecf3ad7e981e2577602375892f74548593aa9b998cae733fa"
+ }
}
]
diff --git a/apps/storybook/stories/DropdownMenuRadioGroup.stories.tsx b/apps/storybook/stories/DropdownMenuRadioGroup.stories.tsx
new file mode 100644
index 0000000000..e541152e8e
--- /dev/null
+++ b/apps/storybook/stories/DropdownMenuRadioGroup.stories.tsx
@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuRadioGroup.stories.tsx
+ * @input Uses one controlled open-menu fixture covering selected, unselected, described, and retained-open states
+ * @output Component-owned rendered evidence for DropdownMenuRadioGroup semantics, selection, layout, and direction
+ * @position Storybook audit surface; keeps the group contract reachable without auditing the aggregate DropdownMenu story
+ */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {useState} from 'react';
+import {expect, within} from 'storybook/test';
+import {
+ DropdownMenu,
+ DropdownMenuRadioGroup,
+ DropdownMenuRadioItem,
+} from '@astryxdesign/core/DropdownMenu';
+
+const meta: Meta<typeof DropdownMenuRadioGroup> = {
+ title: 'Core/DropdownMenuRadioGroup',
+ component: DropdownMenuRadioGroup,
+ tags: ['autodocs', 'visual-theme-matrix'],
+ parameters: {
+ layout: 'centered',
+ docs: {
+ description: {
+ component:
+ 'A named controlled single-selection group inside DropdownMenu. The group owns value propagation and close policy; DropdownMenu owns keyboard navigation and each DropdownMenuRadioItem owns its row semantics and paint.',
+ },
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof DropdownMenuRadioGroup>;
+
+function ControlledSelectionFixture() {
+ const [sort, setSort] = useState('newest');
+ const [closeRequestCount, setCloseRequestCount] = useState(0);
+ return (
+ <div
+ data-testid="dropdown-menu-radio-group-audit"
+ data-close-request-count={closeRequestCount}>
+ <DropdownMenu
+ button={{label: 'Sort'}}
+ isMenuOpen
+ onOpenChange={isOpen => {
+ if (!isOpen) {
+ setCloseRequestCount(count => count + 1);
+ }
+ }}
+ menuWidth={280}
+ presentation="popover">
+ <DropdownMenuRadioGroup
+ data-testid="sort-group"
+ value={sort}
+ onChange={setSort}
+ label="Sort options"
+ hasCloseOnSelect={false}>
+ <DropdownMenuRadioItem value="newest" label="Newest first" />
+ <DropdownMenuRadioItem
+ value="oldest"
+ label="Oldest first"
+ description="Use creation date"
+ />
+ <DropdownMenuRadioItem value="name" label="Name" />
+ </DropdownMenuRadioGroup>
+ </DropdownMenu>
+ </div>
+ );
+}
+
+export const ControlledSelection: Story = {
+ render: () => <ControlledSelectionFixture />,
+ play: async () => {
+ const menu = await within(document.body).findByRole('menu');
+ const scope = within(menu);
+ const group = scope.getByRole('group', {name: 'Sort options'});
+ await expect(within(group).getAllByRole('menuitemradio')).toHaveLength(3);
+ await expect(
+ within(group).getByRole('menuitemradio', {name: 'Newest first'}),
+ ).toHaveAttribute('aria-checked', 'true');
+ },
+};
diff --git a/packages/cli/test/core-doc-types.known-drift.json b/packages/cli/test/core-doc-types.known-drift.json
index a6827fbe59..25023e62b7 100644
--- a/packages/cli/test/core-doc-types.known-drift.json
+++ b/packages/cli/test/core-doc-types.known-drift.json
@@ -43,8 +43,6 @@
"packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsDense isHiddenFromOverview unknown_field",
"packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs docsZh isHiddenFromOverview unknown_field",
"packages/core/src/DropdownMenu/DropdownMenuDivider.doc.mjs docsDense isHiddenFromOverview unknown_field",
- "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsDense isHiddenFromOverview unknown_field",
- "packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs docsZh isHiddenFromOverview unknown_field",
"packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsDense isHiddenFromOverview unknown_field",
"packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs docsZh isHiddenFromOverview unknown_field",
"packages/core/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs docsDense isHiddenFromOverview unknown_field",
diff --git a/packages/cli/test/core-prop-docs.known-drift.json b/packages/cli/test/core-prop-docs.known-drift.json
index 73a1e07d3c..0f47af79ed 100644
--- a/packages/cli/test/core-prop-docs.known-drift.json
+++ b/packages/cli/test/core-prop-docs.known-drift.json
@@ -20,10 +20,6 @@
"src/DropdownMenu/DropdownMenu.doc.mjs DropdownMenu.items required_mismatch",
"src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs DropdownMenuCheckboxItem.label required_mismatch",
"src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs DropdownMenuCheckboxItem.value required_mismatch",
- "src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs DropdownMenuRadioGroup.children required_mismatch",
- "src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs DropdownMenuRadioGroup.label required_mismatch",
- "src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs DropdownMenuRadioGroup.onChange required_mismatch",
- "src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs DropdownMenuRadioGroup.value required_mismatch",
"src/DropdownMenu/DropdownMenuRadioItem.doc.mjs DropdownMenuRadioItem.label required_mismatch",
"src/DropdownMenu/DropdownMenuRadioItem.doc.mjs DropdownMenuRadioItem.value required_mismatch",
"src/DropdownMenu/DropdownMenuSubMenu.doc.mjs DropdownMenuSubMenu.children required_mismatch",
diff --git a/packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs
index fef9014eb8..55f89f367d 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs
+++ b/packages/core/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',
},
};
diff --git a/packages/core/src/DropdownMenu/DropdownMenuRadioGroup.spec.md b/packages/core/src/DropdownMenu/DropdownMenuRadioGroup.spec.md
new file mode 100644
index 0000000000..178dda62e2
--- /dev/null
+++ b/packages/core/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`.
diff --git a/packages/core/src/DropdownMenu/DropdownMenuRadioGroup.tsx b/packages/core/src/DropdownMenu/DropdownMenuRadioGroup.tsx
index 83932be7dd..3697fb2ecb 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuRadioGroup.tsx
+++ b/packages/core/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})}>
diff --git a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx b/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
index 6bb4fbfef8..06577e89f3 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
+++ b/packages/core/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', () => {
diff --git a/packages/core/src/DropdownMenu/__tests__/DropdownMenuRadioGroupAudit.a11y.chromium.spec.ts b/packages/core/src/DropdownMenu/__tests__/DropdownMenuRadioGroupAudit.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..2a200af3b6
--- /dev/null
+++ b/packages/core/src/DropdownMenu/__tests__/DropdownMenuRadioGroupAudit.a11y.chromium.spec.ts
@@ -0,0 +1,327 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuRadioGroupAudit.a11y.chromium.spec.ts
+ * @input Exact-head DropdownMenuRadioGroup story across themes, modes, direction, and viewport widths
+ * @output Screenshots and fail-closed sensor receipts for the DropdownMenuRadioGroup component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a DropdownMenuRadioGroup audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('dropdown-menu-radio-group-audit-evidence');
+const STORY_ID = 'core-dropdownmenuradiogroup--controlled-selection';
+const WIDE = {width: 1024, height: 768};
+const NARROW = {width: 320, height: 720};
+
+type Mode = 'light' | 'dark';
+type Direction = 'ltr' | 'rtl';
+type Theme = 'neutral' | 'butter';
+type AuditCase = {
+ key: string;
+ mode: Mode;
+ direction: Direction;
+ theme: Theme;
+ viewport: {width: number; height: number};
+};
+
+const cases: AuditCase[] = [
+ {
+ key: 'neutral-light',
+ mode: 'light',
+ direction: 'ltr',
+ theme: 'neutral',
+ viewport: WIDE,
+ },
+ {
+ key: 'neutral-dark',
+ mode: 'dark',
+ direction: 'ltr',
+ theme: 'neutral',
+ viewport: WIDE,
+ },
+ {
+ key: 'butter-light',
+ mode: 'light',
+ direction: 'ltr',
+ theme: 'butter',
+ viewport: WIDE,
+ },
+ {
+ key: 'butter-dark',
+ mode: 'dark',
+ direction: 'ltr',
+ theme: 'butter',
+ viewport: WIDE,
+ },
+ {
+ key: 'rtl-light',
+ mode: 'light',
+ direction: 'rtl',
+ theme: 'neutral',
+ viewport: WIDE,
+ },
+ {
+ key: 'rtl-dark',
+ mode: 'dark',
+ direction: 'rtl',
+ theme: 'neutral',
+ viewport: WIDE,
+ },
+ {
+ key: 'narrow-light',
+ mode: 'light',
+ direction: 'ltr',
+ theme: 'neutral',
+ viewport: NARROW,
+ },
+ {
+ key: 'narrow-dark',
+ mode: 'dark',
+ direction: 'ltr',
+ theme: 'neutral',
+ viewport: NARROW,
+ },
+];
+
+test.describe.configure({mode: 'serial', retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: AuditCase) {
+ return `${server.origin}/iframe.html?id=${STORY_ID}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;
+}
+
+async function settle(page: Page) {
+ await holdMotionStill(page);
+ await page.evaluate(async () => document.fonts.ready);
+ await page.waitForTimeout(40);
+}
+
+test.beforeAll(async () => {
+ fs.rmSync(OUTPUT, {recursive: true, force: true});
+ fs.mkdirSync(OUTPUT, {recursive: true});
+ checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+ encoding: 'utf8',
+ }).trim();
+ const expected = process.env.ASTRYX_HEAD_SHA;
+ if (expected && expected !== checkoutSha) {
+ throw new Error(
+ `checkout ${checkoutSha} does not match expected head ${expected}`,
+ );
+ }
+ server = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+ const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+ if (!response.ok) {
+ throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+ }
+ storybookSha = (await response.text()).trim();
+ if (storybookSha !== checkoutSha) {
+ throw new Error(
+ `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+ );
+ }
+});
+
+test.afterAll(async () => {
+ await server?.close();
+});
+
+for (const item of cases) {
+ test(item.key, async ({browser}) => {
+ const context = await browser.newContext({
+ viewport: item.viewport,
+ colorScheme: item.mode,
+ reducedMotion: 'reduce',
+ });
+ const page = await context.newPage();
+ const pageErrors: string[] = [];
+ page.on('pageerror', error => pageErrors.push(String(error)));
+ await page.goto(storyUrl(item), {waitUntil: 'load'});
+ await page.locator('#storybook-root').waitFor();
+
+ const fixture = page.getByTestId('dropdown-menu-radio-group-audit');
+ const menu = page.getByRole('menu').last();
+ const group = menu.getByRole('group', {name: 'Sort options'});
+ await expect(group).toBeVisible();
+ const radios = group.getByRole('menuitemradio');
+ await expect(radios).toHaveCount(3);
+ await expect(fixture).toHaveAttribute('data-close-request-count', '0');
+ await expect(radios.first()).toHaveAttribute('aria-checked', 'true');
+ await radios.nth(1).click();
+ await expect(radios.nth(1)).toHaveAttribute('aria-checked', 'true');
+ await expect(fixture).toHaveAttribute('data-close-request-count', '0');
+ await expect(menu).toBeVisible();
+ await settle(page);
+
+ const observed = await group.evaluate(element => {
+ const currentRadios = Array.from(
+ element.querySelectorAll<HTMLElement>('[role="menuitemradio"]'),
+ );
+ const groupStyle = getComputedStyle(element);
+ const groupBox = element.getBoundingClientRect();
+ const currentMenu = element.closest<HTMLElement>('[role="menu"]');
+ const rows = currentRadios.map(row => {
+ const box = row.getBoundingClientRect();
+ const style = getComputedStyle(row);
+ const indicator = row.querySelector<HTMLElement>(
+ '.astryx-dropdown-menu-radio',
+ );
+ const indicatorBox = indicator?.getBoundingClientRect() ?? null;
+ return {
+ role: row.getAttribute('role'),
+ checked: row.getAttribute('aria-checked'),
+ text: row.textContent?.replace(/\s+/g, ' ').trim() ?? null,
+ color: style.color,
+ geometry: {x: box.x, y: box.y, width: box.width, height: box.height},
+ indicator:
+ indicatorBox === null
+ ? null
+ : {width: indicatorBox.width, height: indicatorBox.height},
+ };
+ });
+ return {
+ theme: document
+ .querySelector('[data-astryx-theme]')
+ ?.getAttribute('data-astryx-theme'),
+ mode: document.documentElement.getAttribute('data-theme'),
+ direction: groupStyle.direction,
+ viewport: {width: innerWidth, height: innerHeight},
+ reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+ closeRequestCount:
+ element
+ .closest('[data-close-request-count]')
+ ?.getAttribute('data-close-request-count') ?? null,
+ horizontalOverflow:
+ document.documentElement.scrollWidth > innerWidth + 1,
+ fonts: document.fonts.status,
+ group: {
+ role: element.getAttribute('role'),
+ ariaLabel: element.getAttribute('aria-label'),
+ display: groupStyle.display,
+ flexDirection: groupStyle.flexDirection,
+ rowGap: groupStyle.rowGap,
+ menuRowGap:
+ currentMenu === null ? null : getComputedStyle(currentMenu).rowGap,
+ geometry: {
+ x: groupBox.x,
+ y: groupBox.y,
+ width: groupBox.width,
+ height: groupBox.height,
+ },
+ },
+ rows,
+ };
+ });
+
+ const semanticsPass =
+ observed.group.role === 'group' &&
+ observed.group.ariaLabel === 'Sort options' &&
+ observed.rows.length === 3 &&
+ observed.rows.every(row => row.role === 'menuitemradio') &&
+ observed.rows.filter(row => row.checked === 'true').length === 1 &&
+ observed.rows[1]?.checked === 'true' &&
+ observed.rows[1]?.text?.includes('Oldest first') === true &&
+ observed.closeRequestCount === '0';
+ const layoutPass =
+ observed.group.display === 'flex' &&
+ observed.group.flexDirection === 'column' &&
+ observed.group.menuRowGap !== null &&
+ observed.group.rowGap === observed.group.menuRowGap &&
+ Number.parseFloat(observed.group.rowGap) > 0 &&
+ observed.group.geometry.width > 0 &&
+ observed.group.geometry.height > 0 &&
+ observed.rows.every(
+ row => row.geometry.width > 0 && row.geometry.height > 0,
+ ) &&
+ (observed.rows[1]?.geometry.y ?? 0) >
+ (observed.rows[0]?.geometry.y ?? Number.POSITIVE_INFINITY);
+ const paintPass = observed.rows.every(
+ row =>
+ row.color !== 'rgba(0, 0, 0, 0)' &&
+ row.indicator !== null &&
+ row.indicator.width > 0 &&
+ row.indicator.height > 0,
+ );
+
+ const png = await page.screenshot({animations: 'disabled', fullPage: true});
+ const image = `${item.key}.png`;
+ const receipt = {
+ schemaVersion: 1,
+ expected: {
+ build: checkoutSha,
+ storyId: STORY_ID,
+ mode: item.mode,
+ direction: item.direction,
+ theme: item.theme,
+ viewport: item.viewport,
+ },
+ observed: {build: storybookSha, ...observed, pageErrors},
+ image: {
+ file: image,
+ sha256: createHash('sha256').update(png).digest('hex'),
+ width: png.readUInt32BE(16),
+ height: png.readUInt32BE(20),
+ },
+ checks: {semanticsPass, layoutPass, paintPass},
+ passed:
+ storybookSha === checkoutSha &&
+ pageErrors.length === 0 &&
+ observed.theme === item.theme &&
+ observed.mode === item.mode &&
+ observed.direction === item.direction &&
+ observed.viewport.width === item.viewport.width &&
+ observed.viewport.height === item.viewport.height &&
+ observed.reducedMotion &&
+ !observed.horizontalOverflow &&
+ observed.fonts === 'loaded' &&
+ semanticsPass &&
+ layoutPass &&
+ paintPass,
+ };
+ fs.writeFileSync(path.join(OUTPUT, image), png);
+ fs.writeFileSync(
+ path.join(OUTPUT, `${item.key}.sensors.json`),
+ `${JSON.stringify(receipt, null, 2)}\n`,
+ );
+ expect(receipt.passed).toBe(true);
+ await context.close();
+ });
+}
+
+test('manifest is complete', () => {
+ const receipts = fs
+ .readdirSync(OUTPUT)
+ .filter(file => file.endsWith('.sensors.json'));
+ fs.writeFileSync(
+ path.join(OUTPUT, 'manifest.json'),
+ `${JSON.stringify(
+ {
+ schemaVersion: 1,
+ component: 'core/DropdownMenuRadioGroup',
+ build: checkoutSha,
+ frames: cases.map(item => ({
+ key: item.key,
+ image: `${item.key}.png`,
+ receipt: `${item.key}.sensors.json`,
+ })),
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ expect(receipts).toHaveLength(cases.length);
+});