@astryxdesign/core 0.7.3-canary.d421aed → 0.7.3-canary.da1020b

package/dist/DropdownMenu/DropdownMenuRadioGroup.d.ts

@@ -9,7 +9,7 @@
  * comes from the parent DropdownMenu's useListFocus, which matches
  * menuitemradio rows.
  */
-import { type ReactNode } from 'react';
+import { type ReactNode, type Ref } from 'react';
 import type { BaseProps } from '../BaseProps';
 export interface DropdownMenuRadioGroupProps extends Omit<BaseProps, 'onChange'> {
     /**
@@ -24,9 +24,9 @@ export interface DropdownMenuRadioGroupProps extends Omit<BaseProps, 'onChange'>
     /**
      * 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;
     /**
@@ -36,6 +36,10 @@ export interface DropdownMenuRadioGroupProps extends Omit<BaseProps, 'onChange'>
      * @default true
      */
     hasCloseOnSelect?: boolean;
+    /**
+     * Ref forwarded to the role="group" root.
+     */
+    ref?: Ref<HTMLDivElement>;
     /**
      * The `DropdownMenuRadioItem`s that make up the group.
      */
@@ -58,7 +62,7 @@ export interface DropdownMenuRadioGroupProps extends Omit<BaseProps, 'onChange'>
  * </DropdownMenu>
  * ```
  */
-export declare function DropdownMenuRadioGroup({ value, onChange, label, hasCloseOnSelect, children, xstyle, className, style, ...rest }: DropdownMenuRadioGroupProps): import("react").JSX.Element;
+export declare function DropdownMenuRadioGroup({ value, onChange, label, hasCloseOnSelect, children, ref, xstyle, className, style, ...rest }: DropdownMenuRadioGroupProps): import("react").JSX.Element;
 export declare namespace DropdownMenuRadioGroup {
     var displayName: string;
 }

package/dist/DropdownMenu/DropdownMenuRadioGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DropdownMenuRadioGroup.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenuRadioGroup.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAI9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiB5C,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,SAAS,EACT,UAAU,CACX;IACC;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,KAAK,EACL,QAAQ,EACR,KAAK,EACL,gBAAuB,EACvB,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,2BAA2B,+BAiB7B;yBA3Be,sBAAsB"}
+{"version":3,"file":"DropdownMenuRadioGroup.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenuRadioGroup.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAE,KAAK,GAAG,EAAC,MAAM,OAAO,CAAC;AAIxD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiB5C,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,SAAS,EACT,UAAU,CACX;IACC;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;OAEG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,KAAK,EACL,QAAQ,EACR,KAAK,EACL,gBAAuB,EACvB,QAAQ,EACR,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,2BAA2B,+BAkB7B;yBA7Be,sBAAsB"}

package/dist/DropdownMenu/DropdownMenuRadioGroup.js

@@ -51,6 +51,7 @@ export function DropdownMenuRadioGroup({
   label,
   hasCloseOnSelect = true,
   children,
+  ref,
   xstyle,
   className,
   style,
@@ -63,6 +64,7 @@ export function DropdownMenuRadioGroup({
   }), [value, onChange, hasCloseOnSelect]);
   return /*#__PURE__*/_jsx("div", {
     ...rest,
+    ref: ref,
     role: "group",
     "aria-label": label,
     ...mergeProps(stylex.props(styles.group, xstyle), {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.3-canary.d421aed",
+  "version": "0.7.3-canary.da1020b",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,8 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.3-canary.d421aed",
-    "@astryxdesign/cli": "0.7.3-canary.d421aed",
+    "@astryxdesign/a11y-spec": "0.7.3-canary.da1020b",
+    "@astryxdesign/cli": "0.7.3-canary.da1020b",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/DropdownMenu/DropdownMenuItem.doc.mjs

@@ -8,7 +8,50 @@ export const docs = {
   displayName: 'Dropdown Menu Item',
   isHiddenFromOverview: true,
   description:
-    'Helper component for custom item rendering with consistent styling. Host attributes and DOM event handlers (aria-*, data-*, id, drag and drop) reach the row root, the element carrying role="menuitem".',
+    'One action or destination row in the pointer presentation of DropdownMenu. The parent menu owns keyboard navigation; the row owns activation, disabled state, destination behavior, content layout, and its theme target. Supported host attributes, DOM handlers, className, style, xstyle, and ref reach or compose on the role="menuitem" root.',
+  usage: {
+    description:
+      'Use DropdownMenuItem inside DropdownMenu compound mode for one action or destination. Keep label, description, icon, and endContent non-interactive; controls belong in separate rows or the menu header/footer.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use href for a destination so LinkProvider, modified clicks, middle clicks, and browser link affordances remain available.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use hasCloseOnSelect=false only when activation reports a result in place on the same row.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put buttons, links, or other focusable controls inside label, description, or endContent. Each menu row is one interactive target.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Row',
+        required: true,
+        description:
+          'The role="menuitem" root that owns activation, disabled state, destination behavior, and theme state.',
+      },
+      {
+        name: 'Content',
+        required: true,
+        description:
+          'The non-interactive label plus optional icon, description, and end content.',
+      },
+    ],
+  },
+  theming: {
+    targets: [
+      {
+        className: 'astryx-dropdown-menu-item',
+        visualProps: ['size', 'variant'],
+      },
+    ],
+  },
   playground: {
     // Standalone DropdownMenuItem has no required props, so the properties-tab
     // preview renders an empty row without seeded content. Seed a label and
@@ -26,6 +69,7 @@ export const docs = {
       name: 'label',
       type: 'ReactNode',
       description: 'Primary label text.',
+      required: true,
     },
     {
       name: 'description',
@@ -55,11 +99,18 @@ export const docs = {
       description:
         'Link relationship. noopener noreferrer is added for target="_blank". Only used with href.',
     },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description:
+        'Whether the row is unavailable. Disabled rows expose aria-disabled, remove link destinations, and suppress activation.',
+      default: 'false',
+    },
     {
       name: 'endContent',
       type: 'ReactNode',
       description:
-        'Additional content rendered after the label and description.',
+        'Non-interactive content rendered after the label and description.',
     },
     {
       name: 'hasCloseOnSelect',
@@ -95,7 +146,7 @@ export const docsZh = {
   isHiddenFromOverview: true,
   displayName: 'Dropdown Menu Item',
   description:
-    '用于自定义项渲染的辅助组件，提供一致的样式。宿主属性和 DOM 事件处理器（aria-*、data-*、id、拖放）会落在行根元素上，即带 role="menuitem" 的元素。',
+    'DropdownMenu 指针呈现中的一个操作或目标行。父菜单负责键盘导航；该行负责激活、禁用状态、目标行为、内容布局和主题目标。支持的宿主属性、DOM 处理程序、className、style、xstyle 和 ref 会落在或组合到 role="menuitem" 根元素上。',
   props: [
     {
       name: 'icon',
@@ -106,6 +157,7 @@ export const docsZh = {
       name: 'label',
       type: 'ReactNode',
       description: '主标签文本。',
+      required: true,
     },
     {
       name: 'description',
@@ -134,10 +186,16 @@ export const docsZh = {
       type: 'string',
       description: '链接关系。target="_blank" 时自动加入 noopener noreferrer。',
     },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description: '该行是否不可用；不可用的行不会激活或导航。',
+      default: 'false',
+    },
     {
       name: 'endContent',
       type: 'ReactNode',
-      description: '在标签和描述之后渲染的附加内容。',
+      description: '在标签和描述之后渲染的非交互式附加内容。',
     },
     {
       name: 'hasCloseOnSelect',
@@ -168,9 +226,9 @@ export const docsZh = {
 
 export const docsDense = {
   name: 'DropdownMenuItem',
-  isHiddenFromOverview: true,
   displayName: 'Dropdown Menu Item',
-  description: 'helper for custom item rendering w/ consistent styling',
+  description:
+    'one pointer-menu action/destination row; parent owns keyboard, row owns activation, state, destination, content, and root inputs',
   propDescriptions: {
     icon: 'icon before label',
     label: 'primary label text',
@@ -180,7 +238,8 @@ export const docsDense = {
     href: 'row is a real anchor w/ role=menuitem; modified/middle click keeps browser meaning',
     target: "link target ('_blank' | '_self'), with href",
     rel: 'link rel; noopener noreferrer added for _blank',
-    endContent: 'additional content after label+description',
+    isDisabled: 'unavailable; removes destinations and suppresses activation',
+    endContent: 'non-interactive content after label+description',
     hasCloseOnSelect:
       'false keeps the menu open on activation (in-place result on the item)',
     variant:

package/src/DropdownMenu/DropdownMenuItem.spec.md

@@ -0,0 +1,209 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuItem
+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/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,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+    architecture:interaction-modality,
+  ]
+contributing: []
+system_specs: [spec:AST-020, spec:AST-029]
+---
+
+# DropdownMenuItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | One compound pointer-menu row for an action or destination, with label, supporting content, disabled state, destructive paint, optional close suppression, root inputs, and a forwarded ref.       |
+| 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.                                  |
+| 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`.                      |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuItem renders one compound-mode row in the pointer presentation of
+DropdownMenu. It owns the row element, content slots, action-versus-destination
+branch, activation order, disabled and destructive state, root composition, and
+`dropdown-menu-item` theme target. DropdownMenu owns the surrounding menu,
+keyboard collection, focus movement, typeahead, presentation choice, and close
+lifecycle.
+
+## Compatibility and migration
+
+- Released default preserved: yes.
+- Compatibility class: observational patch; no behavior or public surface changes.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One `role="menuitem"` root and its label, description, icon, end content,
+  disabled state, destructive variant, ref, supported host inputs, and styling inputs.
+- Action callback order and `hasCloseOnSelect` behavior.
+- Link-row rendering, destination handoff, modified/middle-click preservation,
+  target and relationship handling, and disabled-link inertness.
+- Pointer hover focus and the row's press/hover/focus paint.
+- The `dropdown-menu-item` target and its size/variant state reflection.
+
+**Does not own / non-goals**
+
+- Menu naming, open/close state, focus entry, roving focus, typeahead, and keyboard
+  click synthesis — owned by DropdownMenu and its shared hooks.
+- Touch and bottom-sheet row rendering — the parent presentation delegates those
+  rows to List.
+- Destination acceptance and blocking — owned by `family:navigation-destinations`.
+- Interactive controls inside label, description, or end content. Controls belong
+  beside the menu or as separate rows.
+
+## Public concepts
+
+| Concept      | Closed values or states                             | Meaning                                                                        | Availability                | Default | Owner                           | Stability | Invalid-value behavior                                       |
+| ------------ | --------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------- | ------- | ------------------------------- | --------- | ------------------------------------------------------------ |
+| Row act      | action; destination                                 | Runs a callback or exposes a browser/router destination from the row itself.   | Every enabled row           | action  | component and navigation family | stable    | A blocked destination is inert; a disabled link has no href. |
+| Availability | enabled; disabled                                   | Controls whether the row can receive focus or activate.                        | Every row                   | enabled | component and parent menu       | stable    | Disabled suppresses activation and destination.              |
+| Close policy | close; remain open                                  | Whether successful activation closes the parent menu.                          | Action and destination rows | close   | component                       | stable    | Omission closes.                                             |
+| Visual state | default; destructive; hover; focus; press; disabled | Paints row meaning and interaction state without changing menuitem semantics.  | Pointer row                 | default | component                       | stable    | Unknown variants are rejected by the public type.            |
+| Root surface | ref; DOM/data/ARIA; class/style/xstyle/events       | Extends the row root while preserving component-owned role and keyboard state. | Every pointer row           | omitted | public component API            | stable    | Accepted inputs compose; owned role/tab stop remain fixed.   |
+
+## 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 |
+
+### Allowed variation
+
+- **AV1 — Content.** Non-interactive icons, text, descriptions, shortcuts, badges,
+  and status text may vary without changing the row's menuitem semantics.
+- **AV2 — Theme paint.** A theme may restyle the target's admitted properties while
+  preserving visible state distinctions and forced-colors focus.
+- **AV3 — Parent size.** The parent menu supplies `sm`, `md`, or `lg`; the row reflects
+  that state and may vary its tokenized insets.
+
+### Representative states
+
+| State                  | Required invariant                                                                  | Allowed variation                            |
+| ---------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- |
+| Enabled action         | Callback runs, then close follows the close policy.                                 | Content, size, and visual variant.           |
+| In-place result action | Callback runs and the menu remains open.                                            | Label/end content may update.                |
+| Disabled action        | `aria-disabled=true`; callback, hover focus, and close are suppressed.              | Content remains visible.                     |
+| Destination            | One anchor root preserves safe destination and browser activation behavior.         | Target, rel, router provider, and content.   |
+| Destructive            | Error-role paint applies to label, icon, and description without changing behavior. | Other row content remains consumer-authored. |
+| Keyboard focus         | Parent focus lands on the row and remains visible.                                  | Exact theme-owned paint may vary.            |
+| RTL / narrow viewport  | Logical insets and start alignment follow direction without horizontal overflow.    | Menu placement remains parent-owned.         |
+
+### Transformation and precedence order
+
+- **ORD1 — Activation.** Disabled guard → browser-navigation classification → row
+  callback where applicable → close policy → browser/router navigation.
+- **ORD2 — Root composition.** Parent size → base row styles → variant/disabled state
+  → caller `xstyle`; target metadata and caller class/style compose on the same root.
+
+### 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.
+
+## Accessibility contract
+
+- **AR1 — Menu item semantics.** The root is one named `menuitem`; supporting content
+  does not introduce a nested interactive descendant.
+- **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.
+
+## 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      |
+
+No new component-local visual decision is settled by this draft.
+
+## Family and system relationships
+
+- `family:navigation-destinations` owns destination acceptance and blocked-scheme
+  behavior; this component supplies the destination-bearing row.
+- `architecture:public-component-api` owns root input composition, refs, and released
+  compatibility.
+- `architecture:component-theming-surface` owns target placement and state reflection.
+- `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`   |
+
+## Decision log
+
+None. This draft records current facts and introduces no product decision.
+
+## Open questions
+
+- **OQ1 — Which shared keyboard owner should keep disabled menu items discoverable
+  while preserving their inert behavior?** (`human-api`)
+- **OQ2 — Should forced-colors focus use a component-specific system outline, or a
+  shared row-focus treatment that also governs ordinary themes?** (`human-design`)
+
+## 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`.

package/src/DropdownMenu/DropdownMenuRadioGroup.doc.mjs

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