@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/DropdownMenu/DropdownMenuGroup.spec.md

@@ -0,0 +1,145 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuGroup
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-31
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming]
+verified_by: [packages/core/src/DropdownMenu/DropdownMenu.test.tsx]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:public-component-api, architecture:component-theming-surface]
+contributing: []
+system_specs: [spec:AST-020]
+---
+
+# DropdownMenuGroup component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | A compound-mode group of rows with an optional `title`, `children`, root inputs, and a ref.                                                                                                |
+| Behavior                | Renders one `role="group"` named by its visible heading; the heading is plain text that roving focus and typeahead skip. An untitled group is an unnamed group unless the caller names it. |
+| End-user impact         | Screen-reader users hear a titled cluster of rows as one named group, as sighted users see it; arrow keys move across group boundaries as if the rows were flat.                           |
+| Builder impact          | Builders title compound rows with the same heading look as a data-mode section.                                                                                                            |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change.                                                                                                                                  |
+| Review checks           | Reject a heading that becomes a menu item or a focus stop, a titled group not named by its heading, or a lost section-heading target.                                                      |
+| Governing rules         | `component:DropdownMenu/DEC-6`; `architecture:public-component-api`; `architecture:component-theming-surface`.                                                                             |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuGroup gives compound-mode menus the titled grouping that data-mode
+`{type: 'section'}` entries already have (`component:DropdownMenu/DEC-6`).
+
+## Compatibility and migration
+
+- Released default preserved: yes.
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One `role="group"` root, its name from the heading, and the heading itself
+  with the `dropdown-menu-section-heading` target.
+- Root composition of ref, host attributes, and handlers.
+
+**Does not own / non-goals**
+
+- Roving focus and typeahead — owned by `component:DropdownMenu`.
+- The rows inside — owned by each row component.
+- Focusable content inside the heading: arrow keys cannot reach it.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning                                 | Availability  | Default | Owner     | Stability | Invalid-value behavior                            |
+| ------- | ----------------------- | --------------------------------------- | ------------- | ------- | --------- | --------- | ------------------------------------------------- |
+| Title   | absent; any React node  | A visible heading that names the group. | Compound mode | absent  | component | stable    | Absent renders no heading and no name of its own. |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                    | Basis                                              |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| FR1 | With a `title`, the group is one `role="group"` whose `aria-labelledby` names its visible heading; the heading carries `dropdown-menu-section-heading`, is plain text rather than a menu item, and is skipped by roving focus and typeahead. | DEC-6 of `component:DropdownMenu`; current tests   |
+| FR2 | Without a `title`, the group is an unnamed `role="group"`, or takes the name a caller supplies.                                                                                                                                              | Current tests                                      |
+| FR3 | Arrow keys step across a group boundary as if the rows were flat; a focusable node inside the heading is not reachable by them.                                                                                                              | Current tests                                      |
+| FR4 | A ref and host attributes and handlers reach the group element while it keeps its role and heading name.                                                                                                                                     | `architecture:public-component-api`; current tests |
+
+### Allowed variation
+
+- **AV1 — Heading content.** The title may be any React node.
+
+### Representative states
+
+| State    | Required invariant               | Allowed variation |
+| -------- | -------------------------------- | ----------------- |
+| Titled   | Named by its heading.            | Title content.    |
+| Untitled | Unnamed, or named by the caller. | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Name.** Title heading → caller name → none.
+
+### Performance and resources
+
+- **PR1 — Render only.** The group owns no state, effect, listener, or
+  observer.
+
+## Accessibility contract
+
+- **AR1 — Named group.** A titled group is announced with its heading's text;
+  the heading is not a menu item.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                         | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Heading          | Labels a cluster of rows like a data-mode section heading. | `component:DropdownMenu` | Supporting     | FR1                |
+
+`component:DropdownMenu` maps the `dropdown-menu-section-heading` target in its
+theming anatomy, so this record carries no anatomy-theming map.
+
+## Family and system relationships
+
+- `component:DropdownMenu` owns the keyboard model and the section-heading
+  target mapping.
+- `architecture:public-component-api` owns root composition.
+
+## Verification map
+
+| Contract       | Verification                                                                                                                                                                                                                                               | Representative states                    | Mutation or failure expectation                                                                                       | Audit section                           |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| FR1, AR1, ORD1 | `DropdownMenu.test.tsx` DropdownMenuGroup cases ("renders a role=\"group\" named by its heading", "renders the heading with the data-mode theme class", "the heading is not a menuitem and roving focus skips it", "typeahead never lands on the heading") | Titled group                             | A group not named by its heading, a missing heading target, or a heading that takes focus or a typeahead match fails. | `audit:DropdownMenuGroup/semantics`     |
+| FR2            | `DropdownMenu.test.tsx` "an untitled group is an unnamed role=\"group\"" and "an untitled group takes a caller-supplied accessible name"                                                                                                                   | Untitled, with and without a caller name | A name invented for an untitled group, or a dropped caller name, fails.                                               | `audit:DropdownMenuGroup/semantics`     |
+| FR3            | `DropdownMenu.test.tsx` "arrow navigation steps across a group boundary as if the rows were flat" and "a focusable node in the heading is not reachable by the arrow keys"                                                                                 | Two groups; focusable heading content    | A stop at the boundary or a focusable heading node reached by arrows fails.                                           | `audit:DropdownMenuGroup/accessibility` |
+| FR4            | `DropdownMenu.test.tsx` "forwards a ref to the group element" and "forwards host attributes to the group while keeping its role and heading name"                                                                                                          | Ref; host attributes                     | A dropped ref or attribute, or a replaced role or name, fails.                                                        | `audit:DropdownMenuGroup/api`           |
+| PR1            | Evidence gap: no test asserts the absence of lifecycle resources                                                                                                                                                                                           | —                                        | —                                                                                                                     | `audit:DropdownMenuGroup/behavior`      |
+
+## Decision log
+
+No component-local decision; `component:DropdownMenu/DEC-6` decides the
+component.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or parent contracts. It links to their owners.

package/src/DropdownMenu/DropdownMenuItem.spec.md

@@ -3,11 +3,11 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:DropdownMenuItem
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, accessibility, theming, testing]
 verified_by:
@@ -15,7 +15,6 @@ verified_by:
     packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
     packages/core/src/DropdownMenu/__tests__/Menu.a11y.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
-    apps/storybook/stories/DropdownMenuItem.stories.tsx,
     apps/storybook/rtl-audit/verified-not-applicable.json,
     scripts/check-knowledge.mjs,
   ]
@@ -30,7 +29,7 @@ architecture:
     architecture:interaction-modality,
   ]
 contributing: []
-system_specs: [spec:AST-020, spec:AST-029]
+system_specs: [spec:AST-020]
 ---
 
 # DropdownMenuItem component contract
@@ -43,7 +42,7 @@ system_specs: [spec:AST-020, spec:AST-029]
 | Behavior                | The parent menu owns roving focus and keyboard activation; the row owns click order, disabled suppression, close-on-select, destination handoff, hover focus, and its visible content composition. |
 | End-user impact         | Actions and destinations preserve keyboard, pointer, and browser link behavior while unavailable rows remain inert and destructive actions remain identifiable.                                    |
 | Builder impact          | Destinations use `href`; supporting content stays non-interactive; `hasCloseOnSelect=false` is reserved for in-place result feedback.                                                              |
-| Compatibility/readiness | Patch-compatible observational contract. Runtime, exports, defaults, and theme targets remain unchanged; authority stays `draft` until exact-head owner approval.                                  |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change.                                                                                                                                          |
 | Review checks           | Reject nested controls, disabled activation, lost destination safety, broken modified-click behavior, dropped root inputs, a second keyboard owner, or state/target reflection moved off the row.  |
 | Governing rules         | `family:navigation-destinations/FR1–FR5`; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV3–INV6`; `spec:AST-020/FR1,FR2,FR6,FR15`.                      |
 
@@ -61,7 +60,8 @@ lifecycle.
 ## Compatibility and migration
 
 - Released default preserved: yes.
-- Compatibility class: observational patch; no behavior or public surface changes.
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change.
 - Controlled/uncontrolled behavior: not applicable.
 - Migration decision: none.
 
@@ -101,19 +101,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## 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 pointer row MUST expose one `role="menuitem"` root. Label, description, icon, and end content remain presentational content of that row rather than nested controls.                                                                             | WAI-ARIA menu pattern; released source/docs                      | verify                                                       |
-| FR2 | Enabled activation MUST run the row callback before optional close. Disabled rows MUST expose `aria-disabled=true`, remove link destinations, and run neither callback nor close.                                                                    | Released behavior; focused tests                                 | verify                                                       |
-| FR3 | A destination row MUST render as the link root through LinkProvider. Plain activation runs the callback then closes and navigates; modified and middle clicks preserve browser behavior without running the callback; blocked schemes are inert.     | `family:navigation-destinations/FR1–FR5`; released tests         | verify                                                       |
-| FR4 | The parent menu MUST remain the only keyboard owner. It synthesizes click activation with modifiers, moves focus, and runs typeahead; the row MAY focus itself on pointer hover but MUST NOT create a second roving-focus model.                     | `architecture:interaction-modality`; current parent tests        | verify                                                       |
-| FR5 | The visible root MUST carry `dropdown-menu-item`; size and destructive state MUST reflect through `themeProps`; semantic tokens own layout and paint before caller styling inputs compose.                                                           | `architecture:component-theming-surface/INV3–INV6`; source/tests | verify                                                       |
-| FR6 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` MUST reach or compose on the row root without replacing owned role, tab stop, disabled behavior, destination handling, or activation order.                          | `architecture:public-component-api/INV5–INV9`; focused tests     | verify                                                       |
-| FR7 | Disabled menu rows remain inert. Whether the menu keyboard model should visit them is unresolved at the shared owner and MUST NOT be changed by a component-local audit.                                                                             | WAI-ARIA menu pattern; parent `component:DropdownMenu/OQ1`       | human API decision                                           |
-| FR8 | Keyboard focus MUST remain perceivable, including in forced-colors mode. The current background-only treatment is an objective gap; a remediation must preserve modality and row-content visibility without inventing new ordinary-theme appearance. | WCAG 2.2 SC 1.4.11 and 2.4.7; current rendered behavior          | objective gap; owner must confirm the shared visual boundary |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                    | Basis                                                              |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| FR1 | The pointer row exposes one `role="menuitem"` root. Label, description, icon, and end content are presentational content of that row rather than nested controls.                                                                                                                                                                            | `spec:AST-020` FR15; current source and docs                       |
+| FR2 | Enabled activation runs the row callback before optional close. Disabled rows expose `aria-disabled=true`, remove link destinations, and run neither callback nor close.                                                                                                                                                                     | Current behavior and tests                                         |
+| FR3 | A destination row renders as the link root through LinkProvider. Plain activation runs the callback then closes and navigates; a modified click does not run the callback, closes the menu, and is left to the browser; a middle click closes the menu (`hasCloseOnSelect`), then runs the caller's `onAuxClick`; blocked schemes are inert. | `family:navigation-destinations` FR1–FR5; current tests            |
+| FR4 | The parent menu is the only keyboard owner. It synthesizes click activation with modifiers, moves focus, and runs typeahead; the row focuses itself on mouse hover and creates no second roving-focus model.                                                                                                                                 | `architecture:interaction-modality`; current parent tests          |
+| FR5 | The visible root carries `dropdown-menu-item`; size and destructive state reflect on it (`data-size`, `data-variant`); semantic tokens own layout and paint before caller styling inputs compose.                                                                                                                                            | `architecture:component-theming-surface`; current source and tests |
+| FR6 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root without replacing owned role, tab stop, disabled behavior, destination handling, or activation order.                                                                                                                       | `architecture:public-component-api` INV5–INV9; current tests       |
+| FR7 | Disabled menu rows are inert, and the parent menu's arrow keys and typeahead skip them. Shipped behavior, not a requirement until OQ1 is ruled.                                                                                                                                                                                              | `component:DropdownMenu` FR17, OQ1                                 |
+| FR8 | Keyboard focus paints the row's hover background with no outline, about 1.1:1 against the menu surface in the default themes; in forced-colors mode that background is not drawn, so focus has no visible indicator. Shipped behavior; the focus treatment is OQ2.                                                                           | Current source                                                     |
 
 ### Allowed variation
 
@@ -145,10 +142,9 @@ intentional decision.
 
 ### Performance and resources
 
-- **PR1 — Shared press lifecycle.** DropdownMenuItem uses the shared counted press
-  controller through `usePressFeedback`; the first mounted pressable installs the
-  window listeners and the last removes them. The item adds no per-row listener,
-  observer, timer, request, or local resource owner.
+- **PR1 — Shared press listeners.** The row shares the press controller's
+  window and document listeners; it adds no per-row listener, observer, timer,
+  or request.
 
 ## Accessibility contract
 
@@ -157,18 +153,18 @@ intentional decision.
 - **AR2 — Disabled state.** Disabled rows expose state and cannot activate or navigate.
 - **AR3 — Keyboard ownership.** DropdownMenu owns focus collection and activation;
   the item remains a single row in that model.
-- **AR4 — Focus perception.** Focus remains visually perceivable in supported themes
-  and platform accessibility modes; the open forced-colors gap remains explicit.
+- **AR4 — Focus perception.** Focus paints a low-contrast row background in
+  ordinary themes and no indicator in forced-colors mode (FR8, OQ2).
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                                  | Representation authority                                           | Hierarchy role | Component contract |
-| ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------- | ------------------ |
-| Row              | One full-width action/destination target with tokenized insets and start alignment. | Current source and parent menu composition                         | prominent      | FR1–FR6            |
-| Supporting text  | Description and end content remain subordinate to the row label.                    | Delegated Item layout and current consumer docs                    | supporting     | FR1                |
-| Interaction      | Hover, focus, press, disabled, and destructive states remain distinguishable.       | Current source; forced-colors focus is an unresolved objective gap | prominent      | FR5, FR8, AR4      |
+| Anatomy or state | Design requirement                                                                  | Representation authority                        | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------- | -------------- | ------------------ |
+| Row              | One full-width action/destination target with tokenized insets and start alignment. | Current source and parent menu composition      | prominent      | FR1–FR6            |
+| Supporting text  | Description and end content remain subordinate to the row label.                    | Delegated Item layout and current consumer docs | supporting     | FR1                |
+| Interaction      | Hover, focus, press, disabled, and destructive states remain distinguishable.       | Current source; forced-colors focus is OQ2      | prominent      | FR5, FR8, AR4      |
 
-No new component-local visual decision is settled by this draft.
+No component-local visual decision is recorded.
 
 ## Family and system relationships
 
@@ -180,20 +176,30 @@ No new component-local visual decision is settled by this draft.
 - `architecture:component-test-sufficiency` owns proportionate observable evidence.
 - `architecture:interaction-modality` and DropdownMenu own parent 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–AR3 | `DropdownMenu.test.tsx`; reusable Menu accessibility tests; scoped axe        | action, destination, disabled, keyboard, modified clicks   | A nested control, activation while disabled, lost browser affordance, or second keyboard owner fails observable tests | `audit:DropdownMenuItem/§1,§4,§6` |
-| FR5, FR8, AR4    | theming-target tests; exact-head Neutral/Butter/RTL/narrow/focus/hover frames | default, destructive, disabled, focus, hover               | Target/state reflection disappears, paint is absent, or focus becomes unobservable                                    | `audit:DropdownMenuItem/§2,§5`    |
-| FR6              | root/ref/handler tests; lint and typecheck                                    | ref, host attributes, class/style/xstyle, pointer handlers | An accepted input is dropped or overrides component-owned semantics                                                   | `audit:DropdownMenuItem/§3`       |
-| RTL / responsive | source-hashed verified-N/A receipt plus exact-head browser frames             | LTR, RTL, 320px                                            | Physical direction leaks into the row or narrow layout overflows                                                      | `audit:DropdownMenuItem/§9,§10`   |
+| Contract       | Verification                                                                                                                                                                                                                                                                                                               | Representative states                                     | Mutation or failure expectation                                                                                                                                                                | Audit section                          |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| FR1, AR1       | `DropdownMenu.test.tsx` compound-mode cases ("renders JSX children as menu items", "renders endContent after the item label"); `Menu.a11y.test.tsx` menu binding cases                                                                                                                                                     | Action row with content                                   | A row that is not a `menuitem` or loses its content fails. Evidence gap: no test asserts that supporting content holds no nested control.                                                      | `audit:DropdownMenuItem/semantics`     |
+| FR2, AR2, ORD1 | `DropdownMenu.test.tsx` item cases ("calls onClick when item is clicked", "closes the menu after an item is activated", "keeps the menu open when the item opts out of closing", "does not call onClick when disabled"), "has aria-disabled on disabled compound items", and "a disabled href row renders no address"      | Enabled, disabled, close and stay-open                    | A callback while disabled, a missing `aria-disabled`, a close that ignores the policy, or a disabled row with an address fails. Evidence gap: no test asserts the callback-before-close order. | `audit:DropdownMenuItem/behavior`      |
+| FR3            | `DropdownMenu.test.tsx` "DropdownMenuItem href" and "link rows — the browser's own clicks" cases; "a middle click on a link row runs the caller's onAuxClick and still closes the menu"                                                                                                                                    | Plain, modified, middle, right click; blocked destination | A non-anchor row, a modified click that runs the callback, a middle click that does not close, or a live blocked destination fails.                                                            | `audit:DropdownMenuItem/behavior`      |
+| FR4, AR3       | `DropdownMenu.test.tsx` keyboard-access cases ("moves focus to the item the mouse hovers, keeping a single highlight", "does not move focus on hover for a disabled item", "does not move focus for a non-mouse (touch) pointer") and "keeps the row's own role, tab stop and hover focus beside a caller's onPointerMove" | Mouse hover, touch, disabled                              | A second highlight, hover focus on a disabled row or under touch, or a lost tab stop fails.                                                                                                    | `audit:DropdownMenuItem/accessibility` |
+| FR5            | `DropdownMenu.test.tsx` destructive-variant cases; `themingTargets.test.ts`                                                                                                                                                                                                                                                | Default and destructive; data and compound mode           | A missing `data-variant` fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts the `dropdown-menu-item` class or `data-size`.                        | `audit:DropdownMenuItem/theming`       |
+| FR6            | `DropdownMenu.test.tsx` ref and host-attribute cases ("a ref reaches the menuitem element", "puts aria-\*, data-\* and id on the row root, a link row included", "runs the DOM handlers the caller attaches, such as a drop target")                                                                                       | Ref; host attributes; caller handlers                     | A dropped ref, attribute, or handler fails. Evidence gap: no test asserts `className`, `style`, or `xstyle` on the row.                                                                        | `audit:DropdownMenuItem/api`           |
+| FR7            | `DropdownMenu.test.tsx` "skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation" (the shipped behavior OQ1 leaves open)                                                                                                                                                                      | Disabled rows                                             | A disabled row that activates fails.                                                                                                                                                           | `audit:DropdownMenuItem/accessibility` |
+| FR8, AR4, PR1  | Evidence gap: no test asserts the focus paint, forced-colors focus, or the listener bound                                                                                                                                                                                                                                  | —                                                         | —                                                                                                                                                                                              | `audit:DropdownMenuItem/visual`        |
+| RTL            | `apps/storybook/rtl-audit/verified-not-applicable.json` DropdownMenuItem entry                                                                                                                                                                                                                                             | LTR and RTL                                               | A changed source hash fails the receipt.                                                                                                                                                       | `audit:DropdownMenuItem/rtl`           |
+
+## Current-state impact
+
+- **Focus visibility (FR8).** Keyboard focus on a row shows only a background
+  tint about 1.1:1 against the menu surface, and no indicator in forced-colors
+  mode; the treatment is OQ2.
 
 ## Decision log
 
-None. This draft records current facts and introduces no product decision.
+No component-local decision.
 
 ## Open questions
 
@@ -205,5 +211,5 @@ None. This draft records current facts and introduces no product decision.
 ## Content boundary
 
 This file does not duplicate consumer prop tables/examples, current audit scores,
-screenshot matrices, implementation steps, or family/system rules. The audit pull
-request owns the closed run evidence required by `spec:AST-029/FR5`.
+screenshot matrices, implementation steps, or family/system rules. It links to
+their owners.

package/src/DropdownMenu/DropdownMenuRadioGroup.spec.md

@@ -3,11 +3,11 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:DropdownMenuRadioGroup
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, accessibility, theming, testing]
 verified_by:
@@ -15,7 +15,6 @@ 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,
   ]
@@ -29,22 +28,22 @@ architecture:
     architecture:interaction-modality,
   ]
 contributing: []
-system_specs: [spec:AST-020, spec:AST-029]
+system_specs: [spec:AST-020]
 ---
 
 # 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`.                                            |
+| Area                    | Contract                                                                                                                                                 |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | One controlled, named single-selection group of `DropdownMenuRadioItem` children with value, change callback, close policy, root inputs, and a 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 | Records shipped behavior; no API, default, or DOM change.                                                                                                |
+| 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         | `spec:AST-020`; `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.
 
@@ -60,8 +59,8 @@ 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.
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change.
 - Controlled behavior: `value` is caller-owned and `onChange` is the only commit path.
 - Migration decision: none.
 
@@ -98,17 +97,14 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## 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             |
+| ID  | Invariant                                                                                                                                                                              | Basis                                                        |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| FR1 | The root exposes `role="group"` and a non-empty accessible name. The required `label` supplies `aria-label`; a caller `aria-labelledby` may reference visible text.                    | `spec:AST-020`; current source and tests                     |
+| FR2 | The group is controlled. It compares each radio item's value with caller `value` and emits a selected child value only through caller `onChange`; a radio item outside a group throws. | Current public API and tests                                 |
+| FR3 | `hasCloseOnSelect` defaults to true. When false, a selection updates through `onChange` while the parent menu stays open.                                                              | Current behavior and tests                                   |
+| FR4 | DropdownMenu is 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            |
+| FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the group root without replacing the owned role or `aria-label`.                   | `architecture:public-component-api` INV5–INV9; current tests |
+| FR6 | The wrapper is a logical column whose tokenized gap matches the surrounding menu's item rhythm; it adds no component-specific directional paint or navigation.                         | Current source                                               |
 
 ### Allowed variation
 
@@ -157,7 +153,7 @@ intentional decision.
 | 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.
+No component-local visual decision is recorded.
 
 ## Family and system relationships
 
@@ -165,19 +161,21 @@ No new component-local visual decision is settled by this draft.
 - `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` |
+| Contract      | Verification                                                                                                                                                                                                    | Representative states                                | Mutation or failure expectation                                                                                                              | Audit section                                |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| FR1, AR1      | `DropdownMenuSelectable.test.tsx` "names and composes the group root when no value matches"                                                                                                                     | Label and caller `aria-labelledby`                   | A missing group role, `aria-label`, or caller `aria-labelledby` fails.                                                                       | `audit:DropdownMenuRadioGroup/semantics`     |
+| FR2           | `DropdownMenuSelectable.test.tsx` "calls onChange with the selected value", "names and composes the group root when no value matches" (no item checked), and "throws when a radio item is used outside a group" | Matching and no matching value; item outside a group | A wrong checked row, a selection that skips `onChange`, or an item that works outside a group fails.                                         | `audit:DropdownMenuRadioGroup/behavior`      |
+| FR3           | `DropdownMenuSelectable.test.tsx` "keeps the menu open while controlled selection updates when requested"                                                                                                       | `hasCloseOnSelect={false}`                           | A close despite the opt-out fails. Evidence gap: no test here asserts the default close after a selection.                                   | `audit:DropdownMenuRadioGroup/behavior`      |
+| FR4, AR2, AR3 | `DropdownMenu.test.tsx` "arrow navigation reaches consumer-rendered menuitemradio and menuitemcheckbox items" and "activates a focused menuitemradio with Enter and a menuitemcheckbox with Space"              | Arrow keys and Enter on radio rows                   | A radio row the arrows skip or Enter does not activate fails. Evidence gap: no test asserts that the group adds no tab stop or key handler.  | `audit:DropdownMenuRadioGroup/accessibility` |
+| FR5           | `DropdownMenuSelectable.test.tsx` "names and composes the group root when no value matches"                                                                                                                     | Ref, host attribute, class, style, handler           | A dropped ref, attribute, class, style, or handler, or a replaced role or label, fails. Evidence gap: no test asserts `xstyle` on the group. | `audit:DropdownMenuRadioGroup/api`           |
+| FR6, PR1      | `apps/storybook/rtl-audit/verified-not-applicable.json` DropdownMenuRadioGroup entry. Evidence gap: no test asserts the column gap or the absence of lifecycle resources                                        | LTR and RTL                                          | A changed source hash fails the receipt.                                                                                                     | `audit:DropdownMenuRadioGroup/layout`        |
 
 ## Decision log
 
-None. This draft records current facts and introduces no product decision.
+No component-local decision.
 
 ## Open questions
 
@@ -186,5 +184,4 @@ 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`.
+screenshot matrices, implementation steps, or parent/item contracts. It links to their owners.