@astryxdesign/core 0.7.3-canary.f94e962 → 0.7.3

package/src/Button/Button.tsx

@@ -18,7 +18,13 @@
  * Last synced props: label, variant, size, isDisabled, isLoading, isInterruptible, clickAction, icon, isIconOnly, width, children, tooltip, endContent, href, as, target, rel
  */
 
-import {useRef, useTransition, type ReactNode} from 'react';
+import {
+  useEffect,
+  useRef,
+  useState,
+  useTransition,
+  type ReactNode,
+} from 'react';
 import type {BaseProps} from '../BaseProps';
 import type {Elevation, SizeValue} from '../utils/types';
 import * as stylex from '@stylexjs/stylex';
@@ -587,6 +593,21 @@ export function Button({
   // re-click can land and interrupt the in-flight action with a fresh one.
   const actionInFlightRef = useRef(false);
   const isLoadingState = isLoading || isPending;
+  // The loading live region must exist empty before it receives "Loading":
+  // many screen readers skip a live region that mounts already holding its
+  // text, which is what a Button first rendered loading did (spec:AST-086
+  // FR3). Only that case holds the text back, until the frame after the
+  // region mounts; a Button mounted idle never re-renders for this.
+  const [isLiveRegionReady, setIsLiveRegionReady] = useState(
+    () => !isLoadingState,
+  );
+  useEffect(() => {
+    if (isLiveRegionReady) {
+      return;
+    }
+    const frame = requestAnimationFrame(() => setIsLiveRegionReady(true));
+    return () => cancelAnimationFrame(frame);
+  }, [isLiveRegionReady]);
   // Delay the spinner reveal for action-driven loading (clickAction's own
   // transition) so a fast action that settles within the delay does not flash
   // a spinner. Interruptible loading is delayed too, so rapid re-clicks settle
@@ -767,7 +788,7 @@ export function Button({
       </span>
       {/* Live region for loading state announcements */}
       <VisuallyHidden role="status" aria-live="polite">
-        {isLoadingState ? t('@astryx.button.loading') : ''}
+        {isLoadingState && isLiveRegionReady ? t('@astryx.button.loading') : ''}
       </VisuallyHidden>
     </>
   );

package/src/Button/__tests__/Button.a11y.states.ts

@@ -8,7 +8,8 @@
  *   BUTTON_PATTERN_EXCLUSIONS, the parts deliberately left to another pattern.
  * @position The binding inventory required before any assertion moves
  *   (`docs/specs/AST-021/spec.md` FR2, FR4), and the single definition of what
- *   each state IS.
+ *   each state IS. Disabled ClickableCard remains focusable and inert under
+ *   `docs/specs/AST-085-focusable-disabled/spec.md` FR1 and FR2.
  *
  * A state earns a row when it can change what the button pattern promises: a
  * different name source, a different operability, a different exposure of
@@ -223,8 +224,8 @@ export const BUTTON_BINDING_STATES = [
   {
     id: 'clickable-card-disabled',
     binding: 'ClickableCard',
-    summary: 'a disabled action card',
-    facts: facts({operable: false, focusable: false, unavailable: true}),
+    summary: 'a disabled action card: focusable, unavailable, and inert',
+    facts: facts({operable: false, focusable: true, unavailable: true}),
     visibleLabel: null,
     pointerTargetSelector: '[data-a11y-pointer-target]',
     storyId: 'a11y-button-pattern--clickable-card-disabled',

package/src/Calendar/Calendar.test.tsx

@@ -382,25 +382,35 @@ describe('Calendar', () => {
   // ─── Date Constraints ────────────────────────────────────────
 
   it('respects min date constraint', () => {
-    render(<Calendar focusDate="2026-01-01" min="2026-01-10" />);
+    const onChange = vi.fn();
+    render(
+      <Calendar focusDate="2026-01-01" min="2026-01-10" onChange={onChange} />,
+    );
 
     // Day 5 should be disabled (before min)
     const day5 = getDayButton(5);
-    expect(day5).toBeDisabled();
+    expect(day5).toHaveAttribute('aria-disabled', 'true');
+    // spec:AST-085 FR1: focusable through aria-disabled, not natively disabled;
+    // a click still selects nothing.
+    expect(day5).not.toHaveAttribute('disabled');
+    day5.focus();
+    expect(day5).toHaveFocus();
+    day5.click();
+    expect(onChange).not.toHaveBeenCalled();
 
     // Day 15 should be enabled (after min)
     const day15 = getDayButton(15);
-    expect(day15).not.toBeDisabled();
+    expect(day15).not.toHaveAttribute('aria-disabled', 'true');
   });
 
   it('respects max date constraint', () => {
     render(<Calendar focusDate="2026-01-01" max="2026-01-20" />);
 
     const day25 = getDayButton(25);
-    expect(day25).toBeDisabled();
+    expect(day25).toHaveAttribute('aria-disabled', 'true');
 
     const day15 = getDayButton(15);
-    expect(day15).not.toBeDisabled();
+    expect(day15).not.toHaveAttribute('aria-disabled', 'true');
   });
 
   // ─── Initial Visible Month ───────────────────────────────────
@@ -424,14 +434,20 @@ describe('Calendar', () => {
       render(<Calendar min="2027-03-04" max="2027-06-30" />);
 
       expect(screen.getByText('March 2027')).toBeInTheDocument();
-      expect(getDayButton(4, 'March', 2027)).not.toBeDisabled();
+      expect(getDayButton(4, 'March', 2027)).not.toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
     });
 
     it('opens on max when the window is entirely in the past', () => {
       render(<Calendar min="2019-01-01" max="2019-04-30" />);
 
       expect(screen.getByText('April 2019')).toBeInTheDocument();
-      expect(getDayButton(30, 'April', 2019)).not.toBeDisabled();
+      expect(getDayButton(30, 'April', 2019)).not.toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
     });
 
     it('keeps max in the last pane in the two-month layout', () => {
@@ -466,7 +482,7 @@ describe('Calendar', () => {
 
     // January 4, 2026 is a Sunday - should be disabled
     const sunday = getDayButton(4);
-    expect(sunday).toBeDisabled();
+    expect(sunday).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('caps the end date to maxRangeSpan once a start is picked', async () => {
@@ -475,15 +491,43 @@ describe('Calendar', () => {
     render(<Calendar mode="range" focusDate="2026-01-01" maxRangeSpan={7} />);
 
     // Before a start is picked every day is selectable.
-    expect(getDayButton(20)).not.toBeDisabled();
+    expect(getDayButton(20)).not.toHaveAttribute('aria-disabled', 'true');
 
     // Pick Jan 10 as the start. A 7-day window spans Jan 4–16 (start ± 6).
     await user.click(getDayButton(10));
 
-    expect(getDayButton(16)).not.toBeDisabled(); // 6 days after — the edge
-    expect(getDayButton(17)).toBeDisabled(); // 7 days after — beyond the cap
-    expect(getDayButton(4)).not.toBeDisabled(); // 6 days before — symmetric
-    expect(getDayButton(3)).toBeDisabled(); // 7 days before — beyond the cap
+    expect(getDayButton(16)).not.toHaveAttribute('aria-disabled', 'true'); // 6 days after — the edge
+    expect(getDayButton(17)).toHaveAttribute('aria-disabled', 'true'); // 7 days after — beyond the cap
+    expect(getDayButton(4)).not.toHaveAttribute('aria-disabled', 'true'); // 6 days before — symmetric
+    expect(getDayButton(3)).toHaveAttribute('aria-disabled', 'true'); // 7 days before — beyond the cap
+  });
+
+  it('keeps one Tab stop when the span cap disables the day that held it', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar mode="range" focusDate="2026-01-01" maxRangeSpan={7} />);
+
+    // Arrow from Jan 1 to Jan 25 so Jan 25 holds the grid's Tab stop.
+    getDayButton(1).focus();
+    await user.keyboard('{ArrowDown}{ArrowDown}{ArrowDown}');
+    for (let i = 0; i < 3; i += 1) {
+      await user.keyboard('{ArrowRight}');
+    }
+    expect(getDayButton(25)).toHaveFocus();
+
+    // Picking Jan 10 as the start disables Jan 25 (beyond the 7-day cap).
+    await user.click(getDayButton(10));
+    expect(getDayButton(25)).toHaveAttribute('aria-disabled', 'true');
+
+    // spec:AST-085 FR1: a disabled day stays focusable but never keeps the
+    // grid's Tab stop, so the grid still has exactly one, on an enabled day.
+    const grid = screen.getByRole('grid');
+    const stops = Array.from(
+      grid.querySelectorAll<HTMLElement>('button[data-date][tabindex="0"]'),
+    );
+    expect(stops).toHaveLength(1);
+    expect(stops[0]).not.toHaveAttribute('aria-disabled', 'true');
+    expect(getDayButton(25)).toHaveAttribute('tabindex', '-1');
   });
 
   it('enforces minRangeSpan once a start is picked', async () => {
@@ -496,11 +540,11 @@ describe('Calendar', () => {
 
     // The picked start itself stays enabled — it is the active selection
     // anchor, not an unreachable end.
-    expect(getDayButton(10)).not.toBeDisabled();
-    expect(getDayButton(11)).toBeDisabled(); // 1 day apart — too short
-    expect(getDayButton(12)).not.toBeDisabled(); // 3-day span — allowed
-    expect(getDayButton(8)).not.toBeDisabled(); // 3-day span the other way
-    expect(getDayButton(9)).toBeDisabled(); // 2-day span — too short
+    expect(getDayButton(10)).not.toHaveAttribute('aria-disabled', 'true');
+    expect(getDayButton(11)).toHaveAttribute('aria-disabled', 'true'); // 1 day apart — too short
+    expect(getDayButton(12)).not.toHaveAttribute('aria-disabled', 'true'); // 3-day span — allowed
+    expect(getDayButton(8)).not.toHaveAttribute('aria-disabled', 'true'); // 3-day span the other way
+    expect(getDayButton(9)).toHaveAttribute('aria-disabled', 'true'); // 2-day span — too short
   });
 
   it('commits a same-day range with the default minimum', async () => {
@@ -565,8 +609,8 @@ describe('Calendar', () => {
 
     // …and the start is cleared: the days that minRangeSpan disabled around
     // the old anchor are selectable again, so a new start can be placed there.
-    expect(getDayButton(11)).not.toBeDisabled();
-    expect(getDayButton(9)).not.toBeDisabled();
+    expect(getDayButton(11)).not.toHaveAttribute('aria-disabled', 'true');
+    expect(getDayButton(9)).not.toHaveAttribute('aria-disabled', 'true');
   });
 
   it('announces the cleared range in the provider locale', async () => {
@@ -603,7 +647,7 @@ describe('Calendar', () => {
 
     // A picked single date must not disable far-away days.
     await user.click(getDayButton(10));
-    expect(getDayButton(25)).not.toBeDisabled();
+    expect(getDayButton(25)).not.toHaveAttribute('aria-disabled', 'true');
   });
 
   it('keeps a controlled value that is wider than maxRangeSpan (selection-only)', () => {
@@ -621,7 +665,7 @@ describe('Calendar', () => {
 
     // No selection is in progress (both endpoints are set), so no anchor →
     // every day is pickable and both endpoints render selected.
-    expect(getDayButton(20)).not.toBeDisabled();
+    expect(getDayButton(20)).not.toHaveAttribute('aria-disabled', 'true');
     expect(getDayButton(5).closest('[role="gridcell"]')).toHaveAttribute(
       'aria-selected',
       'true',
@@ -1713,7 +1757,7 @@ describe('Calendar', () => {
     render(<Calendar focusDate="2026-01-01" min="2026-01-05" />);
 
     const day1 = getDayButton(1);
-    expect(day1).toBeDisabled();
+    expect(day1).toHaveAttribute('aria-disabled', 'true');
 
     const day8 = getDayButton(8);
     day8.focus();
@@ -1741,7 +1785,7 @@ describe('Calendar', () => {
     render(<Calendar focusDate="2026-01-01" dateConstraints={[disableJan8]} />);
 
     const day8 = getDayButton(8);
-    expect(day8).toBeDisabled();
+    expect(day8).toHaveAttribute('aria-disabled', 'true');
 
     const day15 = getDayButton(15);
     day15.focus();

package/src/Calendar/Calendar.tsx

@@ -1372,7 +1372,8 @@ function DayCell({
         // Mark today's cell programmatically (APG date-picker pattern), not just
         // visually, so screen-reader users can identify the current date.
         aria-current={state.isToday ? 'date' : undefined}
-        disabled={isDisabled}
+        // A disabled day stays focusable through aria-disabled (spec:AST-085
+        // FR1); arrows still skip it and its click and hover are guarded.
         // Initial roving tab-stop seed; useGridFocus owns it after mount.
         tabIndex={isTabbableDay ? 0 : -1}
         onClick={() => !state.effectivelyDisabled && onDayClick(date)}

package/src/Carousel/Carousel.spec.md

@@ -0,0 +1,146 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Carousel
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-22
+owners: [cixzhang]
+review_triggers: [behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/Carousel/Carousel.test.tsx,
+    packages/core/src/Carousel/__tests__/Carousel.a11y.chromium.spec.ts,
+  ]
+modules: []
+families: [family:buttons]
+design_specs: []
+architecture: [architecture:interaction-modality]
+contributing: []
+system_specs: [spec:AST-085, spec:AST-025]
+---
+
+# Carousel component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes.                                                                                                                                                                                                                                                                      |
+| Behavior                | An edge scroll button whose direction has run out is hidden and takes no tab stop. When the focused edge button runs out, focus moves to the scroll area.                                                                                                                          |
+| End-user impact         | A keyboard user who scrolls to the first or last item stays inside the carousel instead of landing on the page body or on an invisible control. The scroll area has no role or name yet, so screen-reader users hear little at the destination until it meets `spec:AST-025` FR12. |
+| Builder impact          | None.                                                                                                                                                                                                                                                                              |
+| Compatibility/readiness | No API change. Shipped Carousel and its current tests still use native `disabled` and hand focus to the opposite button; they change with conformance work.                                                                                                                        |
+| Review checks           | Reject focus left on a hidden edge button, focus dropped to the page body, or an edge handoff that moves focus to anything but the scroll area.                                                                                                                                    |
+| Governing rules         | `spec:AST-085` FR1, FR4; `spec:AST-025` FR12; `architecture:interaction-modality` INV1.                                                                                                                                                                                            |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Carousel shows a horizontally scrolling row of items inside a labelled region,
+with optional scroll buttons at each edge. This record covers only what the edge
+scroll buttons do when their direction runs out. Other Carousel behavior is
+uncontracted until this record grows.
+
+## Compatibility and migration
+
+- Released default preserved: yes, except where focus lands at an edge.
+- Compatibility class: behavior correction; no API change.
+- Controlled/uncontrolled behavior: unchanged.
+- Migration decision: DEC-1.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Edge scroll button visibility, tab order, and the focus destination when one
+  runs out.
+
+**Does not own / non-goals**
+
+- Scroll area keyboard access and naming — `spec:AST-025`.
+- Disabled control semantics in general — `spec:AST-085`.
+- Button naming, sizing, and activation — `family:buttons`.
+- Looping, snapping, edge fades, and slide semantics — uncontracted.
+
+## Public concepts
+
+| Concept            | Closed values or states | Meaning                                            | Availability by variant/orientation/state | Default | Owner                | Stability | Invalid-value behavior |
+| ------------------ | ----------------------- | -------------------------------------------------- | ----------------------------------------- | ------- | -------------------- | --------- | ---------------------- |
+| Edge scroll button | available, run out      | Whether content remains in that button's direction | Both edges when the carousel overflows    | —       | `component:Carousel` | stable    | not applicable         |
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                    | Basis                                    | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------ |
+| FR1 | An edge scroll button whose direction has run out is hidden. While hidden it takes no tab stop and is not exposed to assistive technology. It stays mounted so layout does not shift. This is removal under `spec:AST-085` FR4, not a disabled control.                                                                | DEC-1                                    | settled            |
+| FR2 | When the focused edge scroll button runs out, focus moves to the scroll area without scrolling it. This holds when the content no longer overflows and the scroll area is out of the tab order (`spec:AST-025` FR12): it still takes focus programmatically. Focus never lands on the page body or on a hidden button. | DEC-1; `spec:AST-085` FR4                | settled            |
+| FR3 | The handoff happens once per edge transition, and only while the edge button held focus. An edge reached by swipe, resize, or wheel while focus is elsewhere moves nothing.                                                                                                                                            | `architecture:interaction-modality` INV8 | settled            |
+| FR4 | An edge scroll button that is available behaves as an ordinary Button.                                                                                                                                                                                                                                                 | `family:buttons`                         | settled            |
+
+### Representative states
+
+| State                                  | Required invariant                                              | Allowed variation       |
+| -------------------------------------- | --------------------------------------------------------------- | ----------------------- |
+| Mid-scroll                             | Both edge buttons available                                     | Loop keeps both enabled |
+| Focused "Scroll right" reaches the end | Button hides; focus is on the scroll area; no extra scroll      | Reduced motion          |
+| Edge reached by swipe, focus elsewhere | Button hides; focus does not move                               | —                       |
+| Content shrinks to fit                 | Both buttons hidden; a focused one hands off to the scroll area | —                       |
+
+## Accessibility contract
+
+- **AR1 — No invisible tab stops.** A hidden edge button is not focusable and is
+  not exposed to assistive technology (FR1).
+- **AR2 — Focus stays in the region.** The edge handoff keeps focus inside the
+  labelled carousel region (FR2), and the keyboard focus indicator follows
+  `architecture:interaction-modality` INV1.
+
+## Design relationships
+
+No design record governs Carousel yet. Edge button visuals stay in code and
+visual evidence.
+
+## Family and system relationships
+
+- `spec:AST-085` FR4 lets a component name a focus destination for a control it
+  removes; FR2 names the scroll area.
+- `spec:AST-025` FR12 owns the scroll area's tab stop and naming.
+- `family:buttons` owns the edge buttons' behavior while available.
+
+## Verification map
+
+| Contract | Verification                            | Representative states                                    | Mutation or failure expectation                                                | Audit section                  |
+| -------- | --------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------ |
+| FR1, AR1 | Unit and accessibility-tree tests       | at rest at each edge; no overflow                        | A hidden button that is focusable or exposed fails                             | `audit:Carousel/accessibility` |
+| FR2, AR2 | Real-browser keyboard test              | Enter on "Scroll right" until the end; same on the start | Focus on the page body, a hidden button, or the opposite button fails          | `audit:Carousel/accessibility` |
+| FR3      | Real-browser test with swipe and resize | edge reached with focus outside the carousel             | Focus moving without an edge-button press, or moving twice for one edge, fails | `audit:Carousel/accessibility` |
+
+## Decision log
+
+### DEC-1 — The scroll area receives focus when an edge button runs out
+
+**Reference:** `component:Carousel/DEC-1`
+**Decider:** cixzhang, 2026-10-22
+
+Carousel hides an edge button whose direction has run out, so keeping focus on
+it would leave a keyboard user on an invisible control. The scroll area is always
+mounted inside the labelled region and can take focus whether or not it is in the
+tab order, so focus moving there keeps the user in place inside the carousel.
+
+Rejected: the opposite edge button — it may be hidden too, and focus would jump
+across the carousel.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

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();
+  });
+});