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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 9031d4554a..690c903092 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -2927,6 +2927,38 @@ jobs:retention-days: 30if-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.jsonindex 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.tsxnew file mode 100644index 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.jsonindex 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.jsonindex 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.mjsindex 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.mdnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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);+});