@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/src/DropdownMenu/DropdownMenu.ssr.test.tsx

@@ -4,21 +4,35 @@
  * @file DropdownMenu.ssr.test.tsx
  * @input DropdownMenu server markup and React hydration
  * @output Proves a bottom-sheet DropdownMenu hydrates without a recoverable
- *   error while its on-demand sheet has not loaded (spec:AST-013 FR9)
- * @position SSR acceptance test for DropdownMenu
+ *   error or a console error while its on-demand sheet has not loaded
+ *   (spec:AST-013 FR9)
+ * @position SSR acceptance test for DropdownMenu; it waits for the on-demand
+ *   sheet modules each hydration starts, so none loads after teardown
  */
 
 import {act} from 'react';
 import {afterEach, describe, expect, it, vi} from 'vitest';
 import {hydrateRoot} from 'react-dom/client';
 import {renderToString} from 'react-dom/server';
+// The menu and its on-demand sheet, loaded while this file is collected,
+// which is untimed: a first load can take seconds on a busy machine. Each
+// fresh module graph below runs these modules again without that cost.
+import './DropdownMenu';
+import './MenuBottomSheet';
+import './MenuBottomSheetActionList';
 
 afterEach(() => {
   vi.restoreAllMocks();
   document.body.replaceChildren();
 });
 
-async function serverRenderThenHydrate(): Promise<unknown[]> {
+/** What a hydration reported: its recoverable errors and its console errors. */
+interface Hydration {
+  recoverableErrors: unknown[];
+  consoleErrors: unknown[][];
+}
+
+async function serverRenderThenHydrate(): Promise<Hydration> {
   // A fresh module graph is a fresh server process: the sheet has not loaded.
   vi.resetModules();
   const {DropdownMenu} = await import('./DropdownMenu');
@@ -33,7 +47,9 @@ async function serverRenderThenHydrate(): Promise<unknown[]> {
   container.innerHTML = renderToString(tree);
   document.body.appendChild(container);
 
-  vi.spyOn(console, 'error').mockImplementation(() => {});
+  // Watched, not muted: React reports some mismatches (an attribute that
+  // differs, for one) only on the console.
+  const logged = vi.spyOn(console, 'error');
   const recoverableErrors: unknown[] = [];
   let root!: ReturnType<typeof hydrateRoot>;
   await act(async () => {
@@ -41,17 +57,37 @@ async function serverRenderThenHydrate(): Promise<unknown[]> {
       onRecoverableError: error => recoverableErrors.push(error),
     });
   });
+  // Right after hydration the sheet wrappers render and start loading the
+  // sheet on demand. Finish those loads before the test ends, or they
+  // resolve after this file's environment is torn down.
+  await act(async () => {
+    await Promise.all([
+      import('./MenuBottomSheet'),
+      import('./MenuBottomSheetActionList'),
+    ]);
+  });
   await act(async () => {
     root.unmount();
   });
   container.remove();
-  return recoverableErrors;
+  const consoleErrors = [...logged.mock.calls];
+  logged.mockRestore();
+  return {recoverableErrors, consoleErrors};
 }
 
 describe('DropdownMenu — SSR', () => {
   it('hydrates a bottom-sheet menu cleanly on the first renders of a server process', async () => {
-    expect(await serverRenderThenHydrate()).toEqual([]);
-    expect(await serverRenderThenHydrate()).toEqual([]);
-    expect(await serverRenderThenHydrate()).toEqual([]);
+    expect(await serverRenderThenHydrate()).toEqual({
+      recoverableErrors: [],
+      consoleErrors: [],
+    });
+    expect(await serverRenderThenHydrate()).toEqual({
+      recoverableErrors: [],
+      consoleErrors: [],
+    });
+    expect(await serverRenderThenHydrate()).toEqual({
+      recoverableErrors: [],
+      consoleErrors: [],
+    });
   }, 30000);
 });

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -34,6 +34,7 @@ import {rtlStyles} from '../utils';
 import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {spacingVars} from '../theme/tokens.stylex';
+import {COMPACT_TOUCH_PRESENTATION_QUERY} from '../hooks/useAdaptivePresentation';
 
 // Mock showPopover and hidePopover methods since they're not implemented in jsdom
 beforeEach(() => {
@@ -175,10 +176,16 @@ describe('DropdownMenu', () => {
 
     const heading = screen.getByRole('heading', {name: 'Project actions'});
     expect(heading).toHaveStyle({marginInlineStart: 'var(--spacing-3)'});
-    expect(heading.closest('.astryx-section')).toHaveStyle({
-      paddingInlineStart: 'var(--spacing-1)',
-      paddingInlineEnd: 'var(--spacing-1)',
+    // The menu's content element takes the sheet's content padding itself,
+    // with no wrapper: 16px above the first row, 4px at the sides.
+    const content = heading.closest('.astryx-dropdown-menu');
+    expect(content?.parentElement?.closest('.astryx-section')).toBeNull();
+    expect(content).toHaveStyle({
+      paddingTop: 'var(--spacing-4)',
+      paddingInline: 'var(--spacing-1)',
     });
+    // The root heading stands alone, with no row wrapper.
+    expect(heading.parentElement).toBe(content);
     expect(
       screen.getByRole('button', {name: 'Edit project'}).closest('li'),
     ).toHaveStyle({
@@ -187,6 +194,32 @@ describe('DropdownMenu', () => {
     });
   });
 
+  it('renders nothing of the sheet at rest and keeps it through its exit', async () => {
+    await warmMenuBottomSheet();
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu
+        button={{label: 'Project actions'}}
+        presentation="bottom-sheet"
+        items={[{label: 'Edit project'}]}
+      />,
+    );
+    expect(document.querySelector('dialog')).toBeNull();
+
+    await user.click(screen.getByRole('button', {name: /Project actions/}));
+    const dialog = document.querySelector('dialog');
+    expect(dialog).not.toBeNull();
+
+    await user.keyboard('{Escape}');
+    // Closed, the sheet stays until its dialog has closed (its exit).
+    expect(document.querySelector('dialog')).toBe(dialog);
+    act(() => {
+      dialog?.removeAttribute('open');
+      dialog?.dispatchEvent(new Event('close'));
+    });
+    expect(document.querySelector('dialog')).toBeNull();
+  });
+
   it('keeps bottom-sheet section groups inside semantic list items', async () => {
     const user = userEvent.setup();
 
@@ -341,7 +374,7 @@ describe('DropdownMenu', () => {
     vi.stubGlobal(
       'matchMedia',
       vi.fn().mockImplementation((query: string) => ({
-        matches: query === '(max-width: 768px) and (pointer: coarse)',
+        matches: query === COMPACT_TOUCH_PRESENTATION_QUERY,
         media: query,
         onchange: null,
         addEventListener: vi.fn(),
@@ -2262,11 +2295,37 @@ describe('DropdownMenu keyboard access for menuitemradio/menuitemcheckbox (#3829
     // focus-driven highlight follows the pointer instead of leaving two.
     // Focus must be scroll-free: scrolling the focused item into view moves
     // the next item under the stationary pointer, which re-highlights and
-    // scrolls again — a runaway auto-scroll loop.
+    // scrolls again — a runaway auto-scroll loop. And it is the mouse's focus,
+    // so it asks the browser not to match :focus-visible.
     const focusSpy = vi.spyOn(del, 'focus');
     fireEvent.pointerMove(del, {pointerType: 'mouse'});
     expect(del).toHaveFocus();
     expect(edit).not.toHaveFocus();
+    expect(focusSpy).toHaveBeenCalledWith({
+      preventScroll: true,
+      focusVisible: false,
+    });
+  });
+
+  it('after a keyboard open, focus that follows the mouse keeps the keyboard indicator (the last input)', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'Actions'}}>
+        <DropdownMenuItem label="Edit" onClick={() => {}} />
+        <DropdownMenuItem label="Delete" onClick={() => {}} />
+      </DropdownMenu>,
+    );
+    screen.getByRole('button', {name: /Actions/}).focus();
+    await user.keyboard('{ArrowDown}');
+    const edit = screen.getByRole('menuitem', {name: 'Edit', hidden: true});
+    await waitFor(() => expect(edit).toHaveFocus());
+
+    // No pointer press since the key: the browser keeps deciding the
+    // indicator, as for any focus the keyboard moved.
+    const del = screen.getByRole('menuitem', {name: 'Delete', hidden: true});
+    const focusSpy = vi.spyOn(del, 'focus');
+    fireEvent.pointerMove(del, {pointerType: 'mouse'});
+    expect(del).toHaveFocus();
     expect(focusSpy).toHaveBeenCalledWith({preventScroll: true});
   });
 

package/src/DropdownMenu/DropdownMenu.tsx

@@ -88,7 +88,9 @@ import {
 import {
   MenuBottomSheet,
   MenuBottomSheetActionList,
+  preloadMenuBottomSheetActionList,
 } from './lazyMenuBottomSheet';
+import {menuBottomSheetStyles} from './menuBottomSheet.stylex';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {
@@ -116,12 +118,13 @@ const MENU_MAX_BLOCK_SIZE_FALLBACK = `min(${MENU_BLOCK_CAP}, ${layerViewportInse
 const MENU_TRIGGER_OPEN_BACKGROUND = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`;
 
 // A sub-menu's drilled-in view with a header or footer renders in the surface
-// host that follows the menu, as the frame marked
-// `data-astryx-submenu-regions="view"` (hidden while a deeper view shows).
-// While one shows, the menu and its header and footer step aside. The rule
-// reads that from the DOM, so no state mirrors which view shows.
+// host that follows the menu (marked `data-astryx-submenu-host`), as the frame
+// marked `data-astryx-submenu-regions="view"` (hidden while a deeper view
+// shows). While one shows, the menu and its header and footer step aside. The
+// rule reads that from the DOM, so no state mirrors which view shows; it names
+// the host by its marker rather than a universal selector.
 const STEPS_ASIDE_FOR_VIEW =
-  ':has(~ * > [data-astryx-submenu-regions="view"]:not([hidden]))';
+  ':has(~ [data-astryx-submenu-host] > [data-astryx-submenu-regions="view"]:not([hidden]))';
 
 const styles = stylex.create({
   triggerOpen: {
@@ -652,6 +655,11 @@ function DropdownMenuBottomSheet({
       setSubmenuPath([]);
     }
   }
+  // The closed sheet renders nothing, so load its rows at rest: the first
+  // open shows the actions at once.
+  useEffect(() => {
+    preloadMenuBottomSheetActionList();
+  }, []);
   const currentSubmenu = submenuPath.at(-1);
   const currentItems = currentSubmenu?.items ?? items;
   const currentTitle = currentSubmenu?.label ?? button.label;
@@ -771,6 +779,23 @@ function DropdownMenuBottomSheet({
     setOpen(!isOpen);
   };
 
+  // The root view's heading stands alone; a sub-menu's sits in a row with its
+  // back button.
+  const viewHeading = (
+    <Heading
+      ref={viewHeadingRef}
+      level={3}
+      tabIndex={-1}
+      xstyle={[
+        bottomSheetStyles.viewHeading,
+        submenuPath.length === 0 && [
+          bottomSheetStyles.rootHeading,
+          menuBottomSheetStyles.headingAlone,
+        ],
+      ]}>
+      {currentTitle}
+    </Heading>
+  );
   return (
     <>
       {renderTrigger != null ? (
@@ -830,12 +855,16 @@ function DropdownMenuBottomSheet({
           {...rest}
           {...mergeProps(
             themeProps('dropdown-menu', {presentation: 'bottom-sheet'}),
-            stylex.props(bottomSheetStyles.content, xstyle),
+            stylex.props(
+              bottomSheetStyles.content,
+              menuBottomSheetStyles.content,
+              xstyle,
+            ),
             className,
             style,
           )}>
-          <div {...stylex.props(bottomSheetStyles.header)}>
-            {submenuPath.length > 0 && (
+          {submenuPath.length > 0 ? (
+            <div {...stylex.props(bottomSheetStyles.header)}>
               <Button
                 label={backLabel}
                 variant="ghost"
@@ -850,18 +879,11 @@ function DropdownMenuBottomSheet({
                 isIconOnly
                 onClick={() => setSubmenuPath(path => path.slice(0, -1))}
               />
-            )}
-            <Heading
-              ref={viewHeadingRef}
-              level={3}
-              tabIndex={-1}
-              xstyle={[
-                bottomSheetStyles.viewHeading,
-                submenuPath.length === 0 && bottomSheetStyles.rootHeading,
-              ]}>
-              {currentTitle}
-            </Heading>
-          </div>
+              {viewHeading}
+            </div>
+          ) : (
+            viewHeading
+          )}
           {isRenderable(header) && (
             <div {...stylex.props(bottomSheetStyles.region)}>{header}</div>
           )}
@@ -1533,7 +1555,11 @@ function DropdownMenuPopover({
   // menu too; while such a sub-menu's drilled-in view shows there, the menu and
   // the regions step aside (STEPS_ASIDE_FOR_VIEW).
   const surfaceHostElement = (
-    <div ref={attachSurfaceHost} {...stylex.props(styles.surfaceHost)} />
+    <div
+      ref={attachSurfaceHost}
+      data-astryx-submenu-host=""
+      {...stylex.props(styles.surfaceHost)}
+    />
   );
   const renderWithRegions = (menu: ReactNode): ReactNode =>
     hasRegions ? (

package/src/DropdownMenu/DropdownMenuItem.tsx

@@ -90,11 +90,11 @@ const menuItemStyles = stylex.create({
   destructive: {
     // Only recolor the text/icon; the hover / focus background stays the shared
     // neutral overlay from `root` so the hover state matches every other menu
-    // item. The root color covers the label/description via the Item custom
-    // properties (and any bare text). Semantic error tokens keep it theme-aware.
-    color: colorVars['--color-error'],
-    '--_item-label-color': colorVars['--color-error'],
-    '--_item-description-color': colorVars['--color-error'],
+    // item. The semantic status foreground covers the label, description, icon,
+    // and any bare text on a plain surface.
+    color: colorVars['--color-text-error'],
+    '--_item-label-color': colorVars['--color-text-error'],
+    '--_item-description-color': colorVars['--color-text-error'],
   },
 });
 

package/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs

@@ -26,12 +26,14 @@ export const docs = {
     {
       name: 'value',
       type: 'string',
+      required: true,
       description:
         "The value this item represents within its group. The group's value matches against this to determine the checked state.",
     },
     {
       name: 'label',
       type: 'ReactNode',
+      required: true,
       description: 'Primary label text identifying the option.',
     },
     {
@@ -50,7 +52,7 @@ export const docs = {
       type: 'boolean',
       default: 'false',
       description:
-        'Whether this individual radio item is disabled. Disabled items stay focusable (via aria-disabled) so they remain discoverable by keyboard and assistive technology, but selection is blocked.',
+        'Whether this individual radio item is disabled. Disabled items expose aria-disabled, block selection, and are currently skipped by DropdownMenu arrow-key navigation.',
     },
     {
       name: 'endContent',
@@ -94,7 +96,8 @@ export const docsDense = {
     label: 'primary label text',
     description: 'secondary text below label',
     icon: 'icon before label',
-    isDisabled: 'disabled; stays focusable via aria-disabled',
+    isDisabled:
+      'disabled; aria-disabled, blocks selection, skipped by arrow keys',
     endContent: 'content after label+description',
     ref: 'forwarded to the row root (the role="menuitemradio" element)',
   },

package/src/DropdownMenu/DropdownMenuRadioItem.spec.md

@@ -0,0 +1,226 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuRadioItem
+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/__tests__/Menu.a11y.test.tsx,
+    packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx,
+    packages/core/src/DropdownMenu/__tests__/DropdownMenuRadioItemAudit.a11y.chromium.spec.ts,
+    apps/storybook/stories/DropdownMenuRadioItem.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-theming-surface,
+    architecture:component-test-sufficiency,
+    architecture:interaction-modality,
+  ]
+contributing: []
+system_specs: [spec:AST-020, spec:AST-029]
+---
+
+# DropdownMenuRadioItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                     |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | One `menuitemradio` row inside a DropdownMenuRadioGroup with a required value and label, optional description, icon, end content, disabled state, root inputs, and an explicit React 19 ref. |
+| Behavior                | Enabled activation emits the row value through the group, applies the group close policy, then runs the caller click handler; disabled activation does none of these.                        |
+| End-user impact         | Assistive technology hears one radio option with its checked state; pointer and keyboard selection commit the same value, and a disabled option cannot be chosen.                            |
+| Builder impact          | Place the row inside a DropdownMenuRadioGroup and give it a unique value and a label; caller handlers run alongside the row's own behavior.                                                  |
+| Compatibility/readiness | Released subcomponent; observational draft of current behavior. Authority stays `draft` until owner approval.                                                                                |
+| Review checks           | Reject a nested semantic radio, a second keyboard owner, local selection state, a dropped caller input, or disabled activation that selects, closes, or calls the caller click handler.      |
+| Governing rules         | WAI-ARIA menu pattern; `architecture:public-component-api/INV5–INV8`; `architecture:component-theming-surface/INV4–INV6`; `spec:AST-020/FR1,FR2`.                                            |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuRadioItem renders one selectable option of a single-choice group in
+the pointer presentation of DropdownMenu. The row owns its `menuitemradio`
+semantics, checked state, decorative radio marker, visible content, disabled
+paint, and activation order. DropdownMenuRadioGroup owns the controlled value
+and close policy; DropdownMenu owns focus movement, typeahead, keyboard
+activation, and the menu lifecycle.
+
+## Compatibility and migration
+
+- Released default preserved: yes (`isDisabled=false`).
+- Compatibility class: no public API change; caller `onClick` and
+  `onPointerMove` compose with the row's own behavior.
+- Controlled behavior: the checked state always derives from the group `value`;
+  the row holds no selection state.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One row root with `role="menuitemradio"` and `aria-checked` derived from the
+  group value.
+- Selection order: disabled guard, group `onChange(value)`, optional close, then
+  the caller click handler.
+- The decorative shared radio marker, its size, and its inline placement.
+- Label, description, icon, and end content composition through Item.
+- Disabled state exposure and paint, and hover focus for enabled rows.
+- Root composition of ref, supported host inputs, `className`, `style`, and
+  `xstyle`.
+
+**Does not own / non-goals**
+
+- The selected value, change callback, and close policy — owned by
+  `component:DropdownMenuRadioGroup`.
+- Focus entry, arrow-key navigation, typeahead, Enter/Space click synthesis,
+  press gestures, and closing — owned by `component:DropdownMenu`.
+- Touch bottom-sheet rendering of selectable rows — owned by the parent
+  presentation.
+- The radio marker's paint — owned by the shared radio Indicator.
+
+## Public concepts
+
+| Concept      | Closed values or states                        | Meaning                                                           | Availability by variant/orientation/state | Default  | Owner                             | Stability | Invalid-value behavior                                   |
+| ------------ | ---------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------- | -------- | --------------------------------- | --------- | -------------------------------------------------------- |
+| Option value | any string                                     | The value the group emits and compares to decide the checked row. | Every row                                 | required | `component:DropdownMenuRadioItem` | stable    | A value no group value matches leaves the row unchecked. |
+| Checked      | checked; unchecked                             | Whether the group value equals this row's value.                  | Every row                                 | derived  | group context and row             | stable    | No local override exists.                                |
+| Availability | enabled; disabled                              | Whether the row can take hover focus and commit its value.        | Every row                                 | enabled  | `component:DropdownMenuRadioItem` | stable    | Disabled blocks every activation path.                   |
+| Content      | label; description; icon; end content          | Visible identification of the option, in reading order.           | Every row                                 | label    | row through Item                  | stable    | `label` is required by the public type.                  |
+| Root surface | ref; DOM/data/ARIA; class/style/xstyle; events | Extends the row root while preserving its role and checked state. | Every row                                 | omitted  | public component API              | stable    | `role`, `aria-checked`, and `tabIndex` are not accepted. |
+
+## 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 row MUST render one element with `role="menuitemradio"` whose `aria-checked` is true exactly when the group value equals the row value. It MUST NOT nest a native or ARIA radio.                                                                                                   | WAI-ARIA menu pattern; current source and focused tests                    | verify             |
+| FR2 | Rendering the row outside a DropdownMenuRadioGroup MUST throw.                                                                                                                                                                                                                         | Current source and focused tests                                           | verify             |
+| FR3 | Enabled activation, by pointer or by the parent's synthesized Enter/Space click, MUST call the group `onChange` with the row value, then ask DropdownMenu to close when the group's close policy is on, then call the caller `onClick`.                                                | Released behavior; `architecture:public-component-api/INV7`; focused tests | verify             |
+| FR4 | A disabled row MUST expose `aria-disabled="true"`, render no `tabindex`, take no hover focus, and on any activation, including an assistive-technology click, MUST NOT call `onChange`, close the menu, or call the caller `onClick`. It paints at half opacity with a default cursor. | Current source, focused tests, and browser evidence                        | verify             |
+| FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` MUST reach or compose on the row root. Caller `onPointerMove` MUST run after the row's hover focus, and caller handlers MUST NOT replace the row's own behavior.                                       | `architecture:public-component-api/INV5–INV8`; focused tests               | verify             |
+| FR6 | The marker MUST be the shared radio Indicator, hidden from assistive technology, never the pointer target, sized `sm` in a small menu and `md` otherwise, at the row's inline start on a fine pointer and its inline end on a coarse pointer.                                          | Current source, focused tests, and browser evidence                        | verify             |
+| FR7 | The row MUST carry the `dropdown-menu-item` target with the menu size and the marker MUST carry the `dropdown-menu-radio` target with size, checked, and disabled reflections.                                                                                                         | `architecture:component-theming-surface/INV4–INV6`; current source/docs    | verify             |
+| FR8 | The row MUST add no key handler or tab stop of its own: enabled rows are `tabindex="-1"` for the parent's roving focus, and keyboard selection arrives as the parent's synthesized click.                                                                                              | `architecture:interaction-modality`; parent keyboard tests                 | verify             |
+
+### Allowed variation
+
+- **AV1 — Content.** Label, description, icon, and end content may vary in
+  length and kind; long string labels truncate on one line.
+- **AV2 — Size.** The marker follows the parent menu size: `sm` in a small
+  menu, `md` otherwise. Row padding does not currently vary with the menu size,
+  unlike action rows; this is an observation, not an invariant.
+- **AV3 — Root styling.** Caller style inputs may extend the row while its role,
+  checked state, and marker remain intact.
+
+### Representative states
+
+| State          | Required invariant                                                        | Allowed variation                                              |
+| -------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Checked        | `aria-checked=true`; the marker shows its checked dot.                    | Content, size, theme, and mode.                                |
+| Unchecked      | `aria-checked=false`; the marker shows an empty circle.                   | Content, size, theme, and mode.                                |
+| Focused        | The row holds focus.                                                      | Pointer hover or keyboard arrival; focus paint is the AR4 gap. |
+| Disabled       | `aria-disabled=true`, no tab stop, half opacity, and no activation.       | Checked or unchecked value.                                    |
+| Coarse pointer | The marker sits at the inline end of the row.                             | Direction mirrors the placement.                               |
+| RTL / narrow   | Content and marker follow logical order with no horizontal page overflow. | Parent menu placement and width.                               |
+
+### Transformation and precedence order
+
+- **ORD1 — Activation.** Disabled guard → group `onChange(value)` → close when
+  the group's close policy is on → caller `onClick`.
+- **ORD2 — Pointer move.** Hover focus for an enabled row → caller
+  `onPointerMove`.
+- **ORD3 — Root composition.** Base row styles → disabled paint → caller
+  `xstyle`; caller `className` and `style` merge with the row target.
+
+### Performance and resources
+
+- **PR1 — Render only.** The row owns no Effect, listener, observer, timer,
+  request, or local state.
+
+## Accessibility contract
+
+- **AR1 — One radio option.** The row is the only announced control; its
+  accessible name comes from its visible content and its state from
+  `aria-checked`.
+- **AR2 — Disabled state.** A disabled row exposes `aria-disabled` and cannot
+  commit a value through any input.
+- **AR3 — Keyboard ownership.** DropdownMenu owns focus movement and activation;
+  the row adds no key handling. Whether disabled rows stay keyboard-discoverable
+  is owned by `component:DropdownMenu` (its OQ1).
+- **AR4 — Focus visibility (objective gap).** Keyboard focus MUST be
+  perceivable (WCAG 2.2 SC 2.4.7 and 1.4.11). The row currently paints focus
+  only as the menu overlay tint with no outline, which measures about 1.1:1
+  against the menu surface and paints nothing under forced colors. The
+  remediation is a shared row-visual decision with `component:DropdownMenuItem`
+  (its OQ2); this draft records the gap and does not settle it.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                               | Representation authority         | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------- | -------------------------------- | -------------- | ------------------ |
+| Row              | Menu row paint and radius; focus paint is the AR4 objective gap. | Current source and menu tokens   | structural     | FR7, AR4           |
+| Radio marker     | Shared radio Indicator at the menu's control size.               | Shared radio Indicator           | prominent      | FR1, FR6           |
+| Disabled         | Half-opacity row with a default cursor.                          | Current source                   | supporting     | FR4                |
+| Direction/touch  | Logical marker placement that mirrors and moves on touch.        | Bidirectionality and current CSS | structural     | FR6                |
+
+No new component-local visual decision is settled by this draft.
+
+## Family and system relationships
+
+- `component:DropdownMenuRadioGroup` owns value, change callback, and close policy.
+- `component:DropdownMenu` owns keyboard navigation, the press model, the
+  `dropdown-menu-item` and `dropdown-menu-radio` target inventory, disabled
+  keyboard discoverability (its OQ1), and forced-colors row focus together with
+  `component:DropdownMenuItem` (its OQ2).
+- `architecture:public-component-api` owns root input and handler composition.
+- `architecture:component-theming-surface` owns target placement and state
+  reflection.
+- `architecture:component-test-sufficiency` owns proportionate observable evidence.
+- `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, FR2, AR1 | `DropdownMenuSelectable.test.tsx`; reusable radio-group and Menu contracts; scoped axe              | checked, unchecked, outside a group                            | A nested radio, wrong checked row, extra announced control, or missing throw fails                                           | `audit:DropdownMenuRadioItem/§1,§4,§6`     |
+| FR3, FR5, FR8 | `DropdownMenuSelectable.test.tsx` handler, keyboard, close, and ref cases; browser fixture counters | pointer and keyboard activation, close on/off, caller handlers | A dropped caller handler, wrong order, or missing close fails                                                                | `audit:DropdownMenuRadioItem/§3,§4,§6`     |
+| FR4, AR2      | Disabled focused test with an assistive-technology click; browser disabled-hover frame              | disabled checked/unchecked                                     | Removing the disabled guard makes the focused test fail                                                                      | `audit:DropdownMenuRadioItem/§1,§4`        |
+| AR4           | Exact-head keyboard-focus and forced-colors frames with rendered contrast                           | Neutral/Butter light/dark focus, forced colors                 | Current frames record the gap; a remediation passes only with a perceivable indicator in every theme and under forced colors | `audit:DropdownMenuRadioItem/§1,§5`        |
+| FR6, FR7      | Marker and target tests; exact-head Neutral/Butter/RTL/narrow/size/coarse/focus frames              | sm/md/lg, fine/coarse, LTR/RTL, light/dark                     | A lost target or reflection, a marker that is announced, wrongly sized, or misplaced fails                                   | `audit:DropdownMenuRadioItem/§2,§5,§9,§10` |
+
+## Decision log
+
+None. This draft records current facts and introduces no product decision.
+
+## Open questions
+
+- **OQ1 — Should the shared `dropdown-menu-item` target reflect the disabled
+  state its rows paint?** (`human-api`) Selectable and action rows paint disabled
+  rows at half opacity, but the target reflects only size and variant, so a theme
+  cannot style disabled rows through it. The target inventory is owned by
+  `component:DropdownMenu`.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit scores,
+screenshot matrices, implementation steps, or group/parent contracts. The audit
+pull request owns the closed run evidence required by `spec:AST-029/FR5`.