@astryxdesign/core 0.7.3-canary.fba04ed → 0.7.3

package/src/Chat/ChatComposer.spec.md

@@ -104,7 +104,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | Primary action          | send; stop                                                   | Sends the current draft or requests interruption.                                                | Default ChatSendButton or a custom sendButton    | send                        | `component:ChatComposer`            | stable    | A shown Stop action without `onStop` is currently rendered but inert.         |
 | Density                 | compact; balanced; spacious                                  | Selects composer spacing.                                                                        | Every ChatComposer                               | balanced                    | `component:ChatComposer`            | stable    | Unknown values are rejected by TypeScript.                                    |
 | Elevation               | low; none                                                    | Selects a raised body or a flat bordered body.                                                   | Every ChatComposer                               | low                         | `component:ChatComposer`            | stable    | Unknown values are rejected by TypeScript.                                    |
-| Status                  | absent; error; warning; top; bottom                          | Adds semantic feedback before or after the body.                                                 | Optional status object                           | absent; bottom when present | `component:ChatComposer`            | stable    | An omitted message currently leaves the semantic status region empty.         |
+| Status                  | absent; error; warning; top; bottom                          | Adds announced feedback before or after the body.                                                | Optional status object                           | absent; bottom when present | `component:ChatComposer`            | stable    | An omitted message renders the bar and announces nothing.                     |
 | Named composition slots | drawer; header actions/context; input; footer/send actions   | Lets callers compose supporting controls and information around the draft.                       | Optional, independently supplied                 | omitted                     | `component:ChatComposer`            | stable    | Omitted slot groups emit no empty header; footer remains for the send action. |
 | BaseProps surface       | ref; DOM props/events; className/style; xstyle               | Extends the component with DOM identity, behavior, and styling.                                  | Every ChatComposer                               | omitted                     | `architecture:public-component-api` | stable    | These surfaces currently have split root/body ownership; see OQ2.             |
 
@@ -113,19 +113,19 @@ Consumer migration instructions belong in consumer docs and release notes.
 Draft requirements identify their basis so observed code is not mistaken for an
 intentional decision. A `current` contract contains no unresolved rows.
 
-| ID   | Candidate invariant                                                                                                                                                                                                                                    | Basis                                                                                                 | Draft review state |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------ |
-| FR1  | Controlled mode MUST report changes through `onChange`; uncontrolled mode MUST retain them locally. Every successful submit MUST trim and deliver the value supplied to that operation, then clear through the same value channel.                     | public types and docs; `architecture:public-component-api/INV3, INV9, INV12`; focused tests           | settled            |
-| FR2  | The default editor MUST serialize its current text/tokens, submit Enter without Shift, preserve Shift+Enter, defer during IME composition, and allow a caller key handler to prevent the default operation.                                            | implementation, docs, and focused tests                                                               | verify             |
-| FR3  | `isDisabled` MUST prevent draft edits and submissions and MUST expose `aria-disabled="true"` on the default textbox; removing the prop MUST remove that state.                                                                                         | `spec:AST-020/FR1` (WCAG 2.2 4.1.2); `architecture:interaction-modality/INV5`; red/green focused test | settled            |
-| FR4  | When `isStopShown` is true, the default primary action MUST remain an enabled, named Stop button and call `onStop`; if editing is also disabled, ancestor styling MUST NOT block its pointer, touch, or keyboard activation.                           | `architecture:interaction-modality/INV4, INV7, INV9`; red/green focused and browser-story tests       | settled            |
-| FR5  | Omitted header slots MUST omit the header row; the drawer precedes the body; input fills the body between header and footer; footer actions precede send actions and the primary action; status follows `statusPosition`.                              | implementation, props, stories, and blocks                                                            | verify             |
-| FR6  | Compact currently reduces body padding and gap. Balanced and spacious currently use the same body spacing. Whether spacious needs distinct output MUST remain unresolved until a component/design owner decides it.                                    | implementation and published union; no current owner selects distinct spacious geometry               | human decision     |
-| FR7  | `low` currently applies low rest and medium hover/focus-within elevation; `none` applies no shadow and a border. Public theme reachability MUST cover the painting body or the public target/model MUST change through an approved compatibility path. | implementation; `architecture:component-theming-surface/INV4, INV6`; existing public issue            | human decision     |
-| FR8  | Keyboard focus entering the registered/default editor MUST add the shared focus indication to the body; pointer focus MUST not add that extra ring. Clicking non-interactive body space MUST focus the registered control, then a textarea fallback.   | implementation; `architecture:interaction-modality/INV1–INV3, INV9`; focused tests                    | verify             |
-| FR9  | Error status currently renders an alert; warning status renders a status; both pair a semantic icon with color and can render above or below the body.                                                                                                 | implementation, docs, and stories; `spec:AST-020/FR1`                                                 | verify             |
-| FR10 | BaseProps currently split across elements: ref, DOM props/events, `className`, and `style` reach the outer frame while `xstyle` reaches the painted body. The owning element MUST remain unresolved pending compatibility review.                      | implementation; `architecture:public-component-api/INV5–INV6, INV8`                                   | human decision     |
-| FR11 | The exported context MUST expose the current value, change and submit operations, placeholder, disabled/stop/send state, stop callback, and mutable input focus control to custom composition.                                                         | public export, types, docs, stories, and focused tests; `architecture:public-component-api/INV12`     | verify             |
+| ID   | Candidate invariant                                                                                                                                                                                                                                                                                                                                                | Basis                                                                                                 | Draft review state |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------ |
+| FR1  | Controlled mode MUST report changes through `onChange`; uncontrolled mode MUST retain them locally. Every successful submit MUST trim and deliver the value supplied to that operation, then clear through the same value channel.                                                                                                                                 | public types and docs; `architecture:public-component-api/INV3, INV9, INV12`; focused tests           | settled            |
+| FR2  | The default editor MUST serialize its current text/tokens, submit Enter without Shift, preserve Shift+Enter, defer during IME composition, and allow a caller key handler to prevent the default operation.                                                                                                                                                        | implementation, docs, and focused tests                                                               | verify             |
+| FR3  | `isDisabled` MUST prevent draft edits and submissions and MUST expose `aria-disabled="true"` on the default textbox; removing the prop MUST remove that state.                                                                                                                                                                                                     | `spec:AST-020/FR1` (WCAG 2.2 4.1.2); `architecture:interaction-modality/INV5`; red/green focused test | settled            |
+| FR4  | When `isStopShown` is true, the default primary action MUST remain an enabled, named Stop button and call `onStop`; if editing is also disabled, ancestor styling MUST NOT block its pointer, touch, or keyboard activation.                                                                                                                                       | `architecture:interaction-modality/INV4, INV7, INV9`; red/green focused and browser-story tests       | settled            |
+| FR5  | Omitted header slots MUST omit the header row; the drawer precedes the body; input fills the body between header and footer; footer actions precede send actions and the primary action; status follows `statusPosition`.                                                                                                                                          | implementation, props, stories, and blocks                                                            | verify             |
+| FR6  | Compact currently reduces body padding and gap. Balanced and spacious currently use the same body spacing. Whether spacious needs distinct output MUST remain unresolved until a component/design owner decides it.                                                                                                                                                | implementation and published union; no current owner selects distinct spacious geometry               | human decision     |
+| FR7  | `low` currently applies low rest and medium hover/focus-within elevation; `none` applies no shadow and a border. Public theme reachability MUST cover the painting body or the public target/model MUST change through an approved compatibility path.                                                                                                             | implementation; `architecture:component-theming-surface/INV4, INV6`; existing public issue            | human decision     |
+| FR8  | Keyboard focus entering the registered/default editor MUST add the shared focus indication to the body; pointer focus MUST not add that extra ring. Clicking non-interactive body space MUST focus the registered control, then a textarea fallback.                                                                                                               | implementation; `architecture:interaction-modality/INV1–INV3, INV9`; focused tests                    | verify             |
+| FR9  | Error status is announced assertively and warning status politely through the shared announcement channel, once per occasion: one state transition, which a rerender or an update to the same value does not repeat (`spec:AST-086` FR6); the status bar itself carries no live role. Both pair a semantic icon with color and can render above or below the body. | implementation, docs, and stories; `spec:AST-020/FR1`; `spec:AST-086/FR2, FR5, FR6`                   | verify             |
+| FR10 | BaseProps currently split across elements: ref, DOM props/events, `className`, and `style` reach the outer frame while `xstyle` reaches the painted body. The owning element MUST remain unresolved pending compatibility review.                                                                                                                                  | implementation; `architecture:public-component-api/INV5–INV6, INV8`                                   | human decision     |
+| FR11 | The exported context MUST expose the current value, change and submit operations, placeholder, disabled/stop/send state, stop callback, and mutable input focus control to custom composition.                                                                                                                                                                     | public export, types, docs, stories, and focused tests; `architecture:public-component-api/INV12`     | verify             |
 
 ### Allowed variation
 
@@ -144,7 +144,7 @@ intentional decision. A `current` contract contains no unresolved rows.
 | Disabled editing             | Default textbox exposes disabled state and cannot edit or submit.                                   | Supporting content remains visible.                          |
 | Disabled, interruptible work | Stop remains named, enabled, and reachable by pointer, touch, and keyboard.                         | Product cancellation behavior varies.                        |
 | Flat elevation               | Body has no shadow and uses its bordered presentation; keyboard focus indication remains available. | Theme tokens vary.                                           |
-| Status above or below        | Semantic role, icon, color, and selected placement remain synchronized.                             | Message content and status type vary.                        |
+| Status above or below        | Announcement urgency, icon, color, and selected placement remain synchronized.                      | Message content and status type vary.                        |
 | Narrow viewport              | Composer remains within its containing inline size and the primary action remains operable.         | Available inline size and optional slot content vary.        |
 
 ### Transformation and precedence order
@@ -165,20 +165,20 @@ intentional decision. A `current` contract contains no unresolved rows.
 - **AR2 — Native actions.** The default Send and Stop controls remain native buttons with translated accessible names; disabled Send uses native disabled behavior, while explicit Stop remains operable.
 - **AR3 — Keyboard editing.** Enter submission MUST preserve Shift+Enter newline behavior, IME composition, and caller cancellation through `preventDefault()`.
 - **AR4 — Focus indication.** Keyboard focus in the editor MUST produce the shared visible focus treatment; pointer focus does not claim keyboard modality, and focus on an internal action remains owned by that action.
-- **AR5 — Status feedback.** Error feedback uses `role="alert"`; warning feedback uses `role="status"`; visible icon and color do not replace the caller's message content.
+- **AR5 — Status feedback.** Error feedback is announced assertively and warning feedback politely through the shared announcement channel (`spec:AST-086` FR2, FR5); the visible status bar carries no live role and stays readable. Visible icon and color do not replace the caller's message content.
 
 ## Design relationships
 
-| Anatomy or state    | Design requirement                                                  | Representation authority                                                                 | Hierarchy role | Component contract |
-| ------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------- | ------------------ |
-| Composer frame      | Groups body and optional status into one compositional shell.       | observed implementation                                                                  | container      | FR5                |
-| Composer body       | Provides the painted rounded input/action surface and elevation.    | elevation is shipped; public theme reachability is unsettled                             | prominent      | FR7                |
-| Drawer              | Places attachment/context content before the body.                  | delegated to `component:ChatComposerDrawer`                                              | supporting     | FR5                |
-| Header              | Places caller actions at start and caller context at end.           | observed implementation                                                                  | supporting     | FR5                |
-| Input               | Owns or hosts the editing surface and its focus control.            | delegated to `component:ChatComposerInput` or caller custom input                        | prominent      | FR1–FR3, FR8, FR11 |
-| Footer              | Places caller actions and the primary action on the final body row. | observed implementation                                                                  | supporting     | FR4–FR5            |
-| Send or stop action | Presents the current primary operation.                             | delegated to `component:ChatSendButton` or caller custom send button                     | prominent      | FR1, FR4           |
-| Status message      | Adds error or warning feedback before or after the body.            | semantic role/color are shipped; separate public theme reachability is not asserted here | supporting     | FR5, FR9, AR5      |
+| Anatomy or state    | Design requirement                                                  | Representation authority                                                                                   | Hierarchy role | Component contract |
+| ------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------- | ------------------ |
+| Composer frame      | Groups body and optional status into one compositional shell.       | observed implementation                                                                                    | container      | FR5                |
+| Composer body       | Provides the painted rounded input/action surface and elevation.    | elevation is shipped; public theme reachability is unsettled                                               | prominent      | FR7                |
+| Drawer              | Places attachment/context content before the body.                  | delegated to `component:ChatComposerDrawer`                                                                | supporting     | FR5                |
+| Header              | Places caller actions at start and caller context at end.           | observed implementation                                                                                    | supporting     | FR5                |
+| Input               | Owns or hosts the editing surface and its focus control.            | delegated to `component:ChatComposerInput` or caller custom input                                          | prominent      | FR1–FR3, FR8, FR11 |
+| Footer              | Places caller actions and the primary action on the final body row. | observed implementation                                                                                    | supporting     | FR4–FR5            |
+| Send or stop action | Presents the current primary operation.                             | delegated to `component:ChatSendButton` or caller custom send button                                       | prominent      | FR1, FR4           |
+| Status message      | Adds error or warning feedback before or after the body.            | shared-channel announcement and color are shipped; separate public theme reachability is not asserted here | supporting     | FR5, FR9, AR5      |
 
 The aggregate Chat record currently owns the public `chat-composer` target. That
 target sits on the frame and cannot select the body's non-inherited elevation and

package/src/Chat/ChatComposer.test.tsx

@@ -1,15 +1,23 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {beforeEach, describe, it, expect, vi} from 'vitest';
-import {act, render, fireEvent} from '@testing-library/react';
+import {act, render, fireEvent, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {useEffect, useRef} from 'react';
+import {StrictMode, useEffect, useRef} from 'react';
 import {ChatComposer} from './ChatComposer';
 import {useChatComposerContext} from './ChatContext';
 import {__resetInteractionModalityForTest} from '../utils/interactionModality';
+import type * as AnnounceModule from '../hooks/useAnnounce';
+
+const announce = vi.fn();
+vi.mock('../hooks/useAnnounce', async importOriginal => ({
+  ...(await importOriginal<typeof AnnounceModule>()),
+  useAnnounce: () => announce,
+}));
 
 beforeEach(() => {
   __resetInteractionModalityForTest();
+  announce.mockClear();
 });
 
 // The composer body — the elevated surface — is the div that wraps the input
@@ -252,3 +260,51 @@ describe('ChatComposer input composition contract', () => {
     expect(document.activeElement).toBe(textarea);
   });
 });
+
+describe('ChatComposer status announcement (spec:AST-086)', () => {
+  const composer = (status?: {type: 'error' | 'warning'; message?: string}) => (
+    <ChatComposer onSubmit={() => {}} input={<div />} status={status} />
+  );
+
+  it('shows the status message but carries no live role (FR2)', () => {
+    render(composer({type: 'error', message: 'Send failed'}));
+    const message = screen.getByText('Send failed');
+    expect(
+      message.closest('[role="alert"], [role="status"], [aria-live]'),
+    ).toBeNull();
+  });
+
+  it('announces an error assertively and a warning politely (FR5)', () => {
+    const {rerender} = render(composer());
+    expect(announce).not.toHaveBeenCalled();
+    rerender(composer({type: 'error', message: 'Send failed'}));
+    rerender(composer({type: 'warning', message: 'Offline'}));
+    expect(announce.mock.calls).toEqual([
+      ['Send failed', 'assertive'],
+      ['Offline', 'polite'],
+    ]);
+  });
+
+  it('announces a mounted status once, even under StrictMode (FR6)', () => {
+    const status = {type: 'error' as const, message: 'Send failed'};
+    const {rerender} = render(<StrictMode>{composer(status)}</StrictMode>);
+    rerender(<StrictMode>{composer({...status})}</StrictMode>);
+    expect(announce.mock.calls).toEqual([['Send failed', 'assertive']]);
+  });
+
+  it('announces the same message again after the status clears (FR6)', () => {
+    const status = {type: 'error' as const, message: 'Send failed'};
+    const {rerender} = render(composer(status));
+    rerender(composer());
+    rerender(composer(status));
+    expect(announce.mock.calls).toEqual([
+      ['Send failed', 'assertive'],
+      ['Send failed', 'assertive'],
+    ]);
+  });
+
+  it('announces nothing for a status without a message', () => {
+    render(composer({type: 'warning'}));
+    expect(announce).not.toHaveBeenCalled();
+  });
+});

package/src/Chat/ChatComposer.tsx

@@ -26,6 +26,7 @@
 import React, {
   useState,
   useCallback,
+  useEffect,
   useRef,
   useMemo,
   type ReactNode,
@@ -53,6 +54,7 @@ import type {ChatComposerInputControl} from './ChatContext';
 import {ChatSendButton} from './ChatSendButton';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {
   getInteractionModality,
@@ -455,9 +457,31 @@ export function ChatComposer(props: ChatComposerProps) {
     [],
   );
 
+  // The status bar mounts together with its message, and a live region born
+  // holding its text is not reliably announced, so the message goes through
+  // the shared channel instead: errors assertively, warnings politely
+  // (spec:AST-086 FR2, FR5). The ref keeps a rerender or a StrictMode effect
+  // replay from repeating it; clearing the status re-arms it, so the same
+  // message shown again is a new occasion (FR6).
+  const announce = useAnnounce();
+  const statusType = status?.type;
+  const statusMessage = status?.message;
+  const announcedStatusRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!statusMessage) {
+      announcedStatusRef.current = null;
+      return;
+    }
+    const occasion = `${statusType}\u0000${statusMessage}`;
+    if (announcedStatusRef.current === occasion) {
+      return;
+    }
+    announcedStatusRef.current = occasion;
+    announce(statusMessage, statusType === 'error' ? 'assertive' : 'polite');
+  }, [announce, statusType, statusMessage]);
+
   const statusEl = status ? (
     <div
-      role={status.type === 'error' ? 'alert' : 'status'}
       {...stylex.props(
         styles.statusBar,
         statusPosition === 'top' ? styles.statusTop : styles.statusBottom,

package/src/Chat/ChatSystemMessage.doc.mjs

@@ -52,7 +52,7 @@ export const docs = {
   },
   usage: {
     description:
-      'Use ChatSystemMessage for concise, non-sender content inside a chat transcript. Choose the default variant for factual status notices and the divider variant for date or section breaks. Long default content wraps within the available width. The component exposes status semantics and the divider branch includes a labelled separator.',
+      'Use ChatSystemMessage for concise, non-sender content inside a chat transcript. Choose the default variant for factual status notices and the divider variant for date or section breaks. Long default content wraps within the available width. It carries no live role: inside a ChatMessageList, the log announces new notices. The divider branch includes a labelled separator.',
     bestPractices: [
       {
         guidance: true,

package/src/Chat/ChatSystemMessage.test.tsx

@@ -4,6 +4,7 @@ import {createRef, Fragment} from 'react';
 import {describe, expect, it} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
+import {ChatMessageList} from './ChatMessageList';
 import {ChatSystemMessage} from './ChatSystemMessage';
 
 const xstyleProbe = stylex.create({
@@ -100,7 +101,7 @@ describe('ChatSystemMessage', () => {
       expect(root).toHaveStyle({outlineOffset: '3px'});
       expectProbeClasses(root);
       expect(root).toHaveAttribute('aria-label', `${variant} system message`);
-      expect(root).toHaveAttribute('role', 'status');
+      expect(root).toHaveAttribute('role', 'note');
       expect(root).toHaveAttribute('data-variant', variant);
     },
   );
@@ -125,7 +126,7 @@ describe('ChatSystemMessage', () => {
       </ChatSystemMessage>,
     );
     const root = screen.getByTestId('empty-partition');
-    expect(root).toHaveAttribute('role', 'status');
+    expect(root).not.toHaveAttribute('role');
     expect(root).toHaveTextContent(text);
   });
 
@@ -148,7 +149,7 @@ describe('ChatSystemMessage', () => {
       </ChatSystemMessage>,
     );
     const root = screen.getByTestId('empty-partition');
-    expect(root).toHaveAttribute('role', 'status');
+    expect(root).not.toHaveAttribute('role');
     expect(root).toContainElement(screen.getByRole('separator'));
   });
 
@@ -164,4 +165,25 @@ describe('ChatSystemMessage', () => {
     expect(separator).toHaveAccessibleName('0');
     expect(separator).toHaveAttribute('aria-labelledby');
   });
+
+  it.each(['default', 'divider'] as const)(
+    'leaves a %s row inside a chat log to the log (spec:AST-086 FR4)',
+    variant => {
+      render(
+        <ChatMessageList>
+          <ChatSystemMessage variant={variant} data-testid="notice">
+            Ana joined
+          </ChatSystemMessage>
+        </ChatMessageList>,
+      );
+      const notice = screen.getByTestId('notice');
+      expect(notice.closest('[role="log"]')).not.toBeNull();
+      for (const el of [notice, ...notice.querySelectorAll('*')]) {
+        expect(el).not.toHaveAttribute('aria-live');
+        expect(['status', 'alert', 'log']).not.toContain(
+          el.getAttribute('role'),
+        );
+      }
+    },
+  );
 });

package/src/Chat/ChatSystemMessage.tsx

@@ -104,6 +104,10 @@ const styles = stylex.create({
  * "user joined", status changes. Supports a divider variant with horizontal
  * lines on each side of the text.
  *
+ * It carries no live role: a notice added to a `ChatMessageList` is announced
+ * by the list's log, which owns content added inside it (`spec:AST-086` FR4),
+ * and a date or divider row is ordinary transcript content.
+ *
  * @example
  * ```
  * <ChatSystemMessage>Conversation started</ChatSystemMessage>
@@ -131,8 +135,7 @@ export function ChatSystemMessage({
           className,
           styleProp,
         )}
-        {...rest}
-        role="status">
+        {...rest}>
         <Divider label={children} />
       </div>
     );
@@ -147,8 +150,7 @@ export function ChatSystemMessage({
         className,
         styleProp,
       )}
-      {...rest}
-      role="status">
+      {...rest}>
       <span {...stylex.props(styles.content)}>
         {icon != null && <span {...stylex.props(styles.icon)}>{icon}</span>}
         {children}

package/src/Chat/__tests__/ChatSystemMessage.a11y.chromium.spec.ts

@@ -458,7 +458,8 @@ async function capture(
     forcedColors: false,
     coarsePointer: options.coarsePointer ?? false,
     touchPoints: options.touchPoints ?? false,
-    role: 'status',
+    // No live role of its own: the chat log delivers it (spec:AST-086 FR4).
+    role: null,
     variant: auditCase.variant,
     text: auditCase.text,
     separatorCount: auditCase.variant === 'divider' ? 1 : 0,
@@ -488,7 +489,7 @@ async function capture(
   check(actual.selectorCount === 1, 'expected exactly one audit subject');
   check(actual.visible, 'audit subject has no visible geometry');
   check(actual.text === expected.text, 'visible content drifted');
-  check(actual.role === expected.role, 'status role drifted');
+  check(actual.role === expected.role, 'root role drifted');
   check(actual.variant === expected.variant, 'variant reflection drifted');
   check(
     actual.separatorCount === expected.separatorCount,
@@ -915,11 +916,11 @@ test.afterAll(async () => {
           },
           emptyContentPartitions: {
             emptyString:
-              'Focused unit evidence: the default variant keeps role=status and renders the content unchanged (empty). In the divider variant, the status root and separator remain; no visible label or accessible name is produced.',
+              'Focused unit evidence: the default variant has no root role and renders the content unchanged (empty). In the divider variant, the root and separator remain; no visible label or accessible name is produced.',
             numericZero:
-              'Focused unit evidence: the default variant keeps role=status and renders the content unchanged as one 0. In the divider variant, the status root and separator remain; Divider paints two zero text nodes (textContent="00") with no accessible name.',
+              'Focused unit evidence: the default variant has no root role and renders the content unchanged as one 0. In the divider variant, the root and separator remain; Divider paints two zero text nodes (textContent="00") with no accessible name.',
             emptyFragment:
-              'Focused unit evidence: the default variant keeps role=status and renders the content unchanged (empty). In the divider variant, the status root and separator remain; no visible label or accessible name is produced.',
+              'Focused unit evidence: the default variant has no root role and renders the content unchanged (empty). In the divider variant, the root and separator remain; no visible label or accessible name is produced.',
           },
           sharedAdvisories: {
             dividerFalseyLabel:
@@ -933,9 +934,7 @@ test.afterAll(async () => {
             forcedColors:
               'Forced-colors rendering was not exercised. The default row makes no support claim, and the disappearing Divider rule is a shared component:Divider advisory.',
             assistiveTechnology:
-              'Browser role exposure is measured, but spoken announcement timing and output were not verified with real assistive technology.',
-            nestedLiveRegions:
-              'The nested-log frame records role=status inside ChatMessageList role=log aria-live=polite, but double-announcement behavior is unverified under spec:AST-009/FR4 and FR10.',
+              'Browser role exposure is measured; spoken output was not recorded with real assistive technology, which spec:AST-009 does not require for routing claims.',
           },
           stateVisualConformance: {
             default: ['text', 'text-with-icon', 'wrapped-long-content'],
@@ -943,7 +942,7 @@ test.afterAll(async () => {
               'labelled-separator',
               'unresolved-divider-icon-observation',
             ],
-            nestedLiveLog: ['status-inside-polite-log-unverified'],
+            nestedLiveLog: ['no-live-role-inside-polite-log'],
             colorModes: ['light', 'dark'],
             narrowCoarsePointer: [
               'default-with-icon',

package/src/CheckboxList/__tests__/CheckboxList.a11y.chromium.spec.ts

@@ -10,7 +10,8 @@
  *   indicators, row paint, hit targets, wrapping, list structure) are recorded
  *   for the audit and never gate. Only frames that prove a shipped remediation
  *   gate on its outcome. The select-all CLI block renders through its own
- *   story, and its source blob is bound in the manifest.
+ *   story, and its source blob is bound in the manifest. Disabled rows expect
+ *   focusable aria-disabled controls under AST-085 FR1 and FR7.
  */
 
 import {createHash} from 'node:crypto';
@@ -271,9 +272,9 @@ const CASES: AuditCase[] = [
     expect: {
       groupName: GROUP,
       rows: [
-        {checked: true, disabled: 'native'},
-        {checked: false, disabled: 'native'},
-        {checked: false, disabled: 'native'},
+        {checked: true, disabled: 'focusable'},
+        {checked: false, disabled: 'focusable'},
+        {checked: false, disabled: 'focusable'},
       ],
     },
   },
@@ -285,7 +286,7 @@ const CASES: AuditCase[] = [
       groupName: GROUP,
       rows: [
         {checked: false, disabled: false},
-        {checked: false, disabled: 'native'},
+        {checked: false, disabled: 'focusable'},
         {checked: false, disabled: false},
       ],
     },
@@ -471,7 +472,7 @@ const CASES: AuditCase[] = [
       rows: [
         {checked: true},
         {checked: false},
-        {checked: false, disabled: 'native'},
+        {checked: false, disabled: 'focusable'},
       ],
     },
   },

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',
   },
 };