An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-086): status announcements have one owner and use the shared channel (#7792)
Cindy Zhang31e06f44a72c
diff --git a/docs/specs/AST-086-status-announcements/spec.md b/docs/specs/AST-086-status-announcements/spec.mdnew file mode 100644index 0000000000..a8a5cfa318--- /dev/null+++ b/docs/specs/AST-086-status-announcements/spec.md@@ -0,0 +1,198 @@+---+schema_version: 4+template_version: 2+kind: system-spec+id: spec:AST-086+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-10-15+phase: accepted+owners: [cixzhang]+affects_architecture: [architecture:react-component-runtime]+affects_families: [family:input-fields]+affects_contributing: []+affects_consumer_docs:+ [+ useAnnounce,+ Toast,+ ChatSystemMessage,+ ChatTypingIndicator,+ Comments,+ FieldStatus,+ Banner,+ ]+---++# Status announcement delivery system spec++## Intent++A screen-reader user hears each status change once, when it happens, at the+right urgency. A message is never lost because its live region appeared+together with its text, and never heard twice because two parts of the page+both claim it.++Builders get one rule for every component that reports status: name the one+owner of the message, and deliver transient messages through the shared+announcement channel.++## Non-goals++- Which events a component reports. Component and family records decide what+ is a status message; this record decides how it is delivered.+- Exact wording. Text comes from `architecture:internationalization`.+- Focus movement. A status message never moves focus; focus rules stay with+ `architecture:interaction-modality` and component records.+- Modal alerts that take focus, such as AlertDialog. They are not status+ messages.+- Spoken output on a specific screen reader. `spec:AST-009` owns that evidence.+- Where the channel is hosted while a native modal makes the rest of the page+ inert. `spec:AST-003` (FR15, FR18, FR20) owns hosting.+- Equivalent internal implementations remain valid when they satisfy this+ contract.++## Requirements++- **FR1 — One owner per message.** Every status message Astryx announces has+ exactly one announcement owner. No other element that shows the same words+ carries a live role (`status`, `alert`, `log`) or `aria-live`.+- **FR2 — Transient messages use the shared channel.** When the element that+ shows a message mounts, unmounts, or is replaced together with its text, the+ owner announces through the shared announcement channel, except as FR4 and+ FR10 provide. The new element+ MUST NOT carry a live role or `aria-live`.+- **FR3 — Live roles only on persistent containers.** A component MAY own a+ live role only on an element that stays mounted while its content changes.+ It MUST NOT mount that element already holding the text to announce.+- **FR4 — A live container owns content added inside it.** Content added inside+ a mounted live container is delivered by that container, at its urgency. An+ element added with that content MUST NOT carry its own live role or announce+ the same content through the channel. A persistent component region that FR3+ allows, such as Button's loading region or an input's invalid-entry region,+ keeps its own role and delivers its own content at its own urgency.+- **FR5 — Urgency.** Outside a live container, errors and time-critical+ failures use the assertive channel. All other status messages use the polite+ channel. Inside a mounted live container, FR4 applies.+- **FR6 — Once per occasion.** An occasion is one state transition or one user+ action. The owner announces once per occasion. Rerender, StrictMode replay,+ and an update to the same value do not repeat it. A new occasion with the+ same words announces again.+- **FR7 — Shown words stay readable.** Delivering through the channel does not+ hide the visible message from assistive technology. The visible element stays+ available for browse mode and `aria-describedby`. The announced words match+ the shown words.+- **FR8 — Indicators inside an owner are silent.** A visual indicator composed+ inside a component that owns the task, such as a Spinner in a busy control,+ announces nothing and carries no live role. The owning component announces its busy state once per busy start (FR6), through the channel or through a persistent region that FR3 allows.+ A standalone indicator is its own owner and follows FR2.+- **FR9 — One shared channel per document.** The channel is one polite and one+ assertive region per document. They are created empty, stay mounted for the+ document's lifetime, and clear their text shortly after each announcement so+ stale text does not linger. `useAnnounce` is the public way to reach it.+- **FR10 — Modal-hosted owners keep their own channel.** While the shared+ channel is not admitted to modal hosting, a globally hosted owner that+ `spec:AST-003` rehosts above native modals (FR16, FR18) announces through its+ own persistent polite and assertive containers, which move with it. FR3, FR5,+ and FR6 apply to those containers.++### Platform support++- Supported feature/engine floor: the package's supported browsers.+- Unsupported behavior: without a document (server render), announcing is a+ no-op and renders nothing.+- While a native modal dialog is open, the shared channel on the page body is+ not exposed to assistive technology until `spec:AST-003` admits it to modal+ hosting. Owners rehosted above the modal use their own containers (FR10).+ Until then, a busy owner rendered inside a native modal announces its busy+ state through a persistent region inside that modal (FR3, FR8). Other+ delivery inside native modals is outside this record.+- Browser evidence: DOM and accessibility-tree checks prove routing (FR1–FR5,+ FR7–FR10). Spoken timing, order, and repetition (FR6 on real AT) require+ `spec:AST-009` FR4 evidence.++## Current-state impact++- `component:FieldStatus` AR1 and `component:Banner` FR8 defer to FR4 inside a+ mounted live container; elsewhere they already match FR2, FR5, and FR7.+- `architecture:react-component-runtime` INV5 gains the authority it requires+ for the document-owned channel (FR9). INV2 and INV3 already require FR6.+- Toast: the viewport announces each toast through the body-level channel, and+ each visible card also carries `role="status"`/`role="alert"` with+ `aria-live`. Under FR1 and FR10 the viewport's own persistent live containers,+ which `spec:AST-003` rehosts above native modals, is the one owner, and the+ card drops its live role. A toast shown over a Dialog stays announced.+- Switch: busy is announced through the channel, and the thumb Spinner also+ mounts with `role="status"`. Under FR8 the thumb Spinner is silent. Under FR6+ StrictMode replay does not repeat the busy announcement.+- Spinner (standalone): mounts with `role="status"` and its name. Under FR2 it+ announces its label through the channel when it appears. The role and name it+ exposes without a live role are outside this record.+- `family:input-fields` members and other busy controls (TextInput, TextArea,+ Selector, MultiSelector, ComplexSelector, Typeahead, Tokenizer, the date and+ time inputs, FileInput, CheckboxInput, CommandPaletteInput,+ DropdownMenuSubMenu, Thumbnail, and the lab EmojiPicker, Schedule, and+ Comments history loaders): each composes a Spinner with+ `role="status"` inside the busy control. Under FR8 that Spinner is silent and+ each control announces its own busy state through the channel. Switch+ already does. CommandPalette opens as a native modal, so it announces each busy+ start, including its load on opening or clearing the query, through a+ persistent region inside its dialog (FR3).+- ChatMessageList: its top loading Spinner is a `role="status"` child of the+ log. Under FR4 and FR8 it is silent, and ChatMessageList announces its loading+ through the channel.+- EmptyState, the ChatComposer status bar, and the chat trigger menu's loading+ row: each mounts a live role together with its text. Under FR2 the message+ goes through the channel and the element carries no live role.+- Button: its persistent loading region fits FR3, except when a Button first+ renders loading and the region mounts holding its text. Inside a live+ container it keeps its role and urgency (FR4).+- DateInput, DateTimeInput, TimeInput, and NumberInput: their persistent+ assertive invalid-entry regions fit FR3 and, inside a live container, keep+ their role and urgency (FR4).+- ChatSystemMessage: forces `role="status"` inside the `role="log"` list. Under+ FR4 the log delivers it; dividers and dates are ordinary log content.+- ChatTypingIndicator (lab): mounts with `role="status"` and text. It follows+ FR4 inside a live log, otherwise FR2.+- Comments (lab): its error banners and progress label mount live roles+ together with their text. Inside a live log they follow FR4; otherwise FR2.+- `spec:AST-037` FR9 (Timer adds no unsolicited live region) already conforms.+- Consumer tests that query these elements by `status` or `alert` role change.+ Release notes name each affected component.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |+| FR1, FR4 | Shared test: one live owner per announced message | Toast shown; busy Switch; system notice, FieldStatus error, and failure Banner inside a chat log; busy Button and invalid DateInput inside a chat log (pass) | A live role on a second element, or a channel announcement of content added inside a live container, fails |+| FR2, FR3 | Shared test: no live element mounts holding its text | Conditional status, toast card, standalone Spinner | Mounting `role="status"` with text fails |+| FR5 | Channel routing tests | Error, warning, success, loading | Routing an error to polite, or a success to assertive, fails |+| FR6 | StrictMode and rerender tests on the channel spy | Busy start, repeated rerender, same-value update, new occasion | Two announcements for one occasion, or none for a new one, fails |+| FR7 | Accessibility-tree check of the visible message | FieldStatus attached/detached, toast card | Hiding the visible text or a word mismatch fails |+| FR8 | Shared test: no live role inside a busy owner; channel spy on the owner | Busy TextInput, Selector, Switch thumb, ChatMessageList loader, busy CommandPalette (region inside its dialog) | A composed indicator with a live role or its own announcement, or a busy owner that announces nothing, fails |+| FR9 | `useAnnounce` tests | First use, many components, region removed, server render | A second region pair, or stale text after the clear delay, fails |+| FR10 | Accessibility-tree check with a Dialog open | Info and error toast shown over an open Dialog | A toast that reaches only the body-level channel, or no exposed live container, fails |+| FR6 (AT) | `spec:AST-009` real-AT receipt | Toast, busy Switch, chat notice | Missing, repeated, or out-of-order speech fails |++## Decision log++### DEC-1 — One owner per message, delivered through the shared channel++**Reference:** `spec:AST-086/DEC-1`+**Decider:** cixzhang, 2026-10-15++Several components show status while also claiming it in a second place, or+mount a live region already holding its text. Screen-reader users then hear a+message twice or not at all. One owner and one shared, always-mounted channel+removes both failures with a single rule, and matches the delivery+`component:FieldStatus` already uses.+Owners that `spec:AST-003` rehosts above native modals keep their own containers+until the shared channel can be hosted there (FR10).++Rejected: delivering transient messages through each component's own live+region — the page gains many competing regions and two-owner duplicates recur.++## Open questions++None.diff --git a/packages/core/src/Banner/Banner.spec.md b/packages/core/src/Banner/Banner.spec.mdindex 573f0acb25..f007291bb8 100644--- a/packages/core/src/Banner/Banner.spec.md+++ b/packages/core/src/Banner/Banner.spec.md@@ -42,29 +42,29 @@ separately targetable surface. The status and content targets remain unchanged.- Released default preserved: `no` — Banner no longer derives a live-region role from visual status- Compatibility class: breaking accessibility-semantic correction; visual output, DOM structure, props, theming targets, and interaction behavior are unchanged- Controlled/uncontrolled behavior: unchanged-- Migration decision: announce async outcomes in their transition handler with `useAnnounce`; add an explicit `role="status"` only for a persistent semantic mirror, and reserve `role="alert"` for genuinely urgent interruption+- Migration decision: announce async outcomes in their transition handler with `useAnnounce`; add an explicit `role="status"` only for a persistent semantic mirror, and reserve `role="alert"` for genuinely urgent interruption. Inside a mounted live container, `spec:AST-086` FR4 applies instead.Consumer migration instructions belong in consumer docs and release notes.### DEP-0007 — Deprecate live-region roles derived from `status`-| Field | Value |-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| id | `DEP-0007` |-| cleanup | `CLN-0015` |-| package | `@astryxdesign/core` |-| surface | Default ARIA role of `Banner`: `role="alert"` for `warning` and `error`, `role="status"` for `info` and `success`, derived from `status` when the caller passes no `role` |-| old contract | Visual `status` selects the live-region role of the Banner root |-| replacement | A caller that announces an async outcome calls `useAnnounce` from the transition that produced it. A caller whose Banner is a persistent semantic mirror passes `role="status"`; genuinely urgent content passes `role="alert"`. Both explicit roles already reach the Banner root |-| direct authority | `component:Banner`. Owners: `cixzhang`, `imdreamrunner` |-| warning | Consumer docs and the release notes name `DEP-0007` and the explicit `role` that keeps the released semantics. No runtime warning (`spec:AST-017` FR29) |-| migration | Non-mechanical: a caller that announces an async outcome calls `useAnnounce` from the transition that produced it; a caller whose Banner is a persistent mirror or urgent content passes `role="status"` or `role="alert"` |-| codemod | None: whether a Banner needs an announcement, and when, depends on the transition that renders it, which only the caller knows; adding the released role everywhere would restore the coupling this cleanup removes |-| downstream | Maintained docs teach `useAnnounce` for async outcomes and explicit `role` for persistent mirrors |-| transition | no prior transition |-| state | `proposed` |-| open decision | Banner FR and DEC entries that make `status` visual-only |-| target plan | `CLN-0015` in the next minor release |+| Field | Value |+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| id | `DEP-0007` |+| cleanup | `CLN-0015` |+| package | `@astryxdesign/core` |+| surface | Default ARIA role of `Banner`: `role="alert"` for `warning` and `error`, `role="status"` for `info` and `success`, derived from `status` when the caller passes no `role` |+| old contract | Visual `status` selects the live-region role of the Banner root |+| replacement | A caller that announces an async outcome calls `useAnnounce` from the transition that produced it. A caller whose Banner is a persistent semantic mirror passes `role="status"`; genuinely urgent content passes `role="alert"`. Both explicit roles already reach the Banner root. Inside a mounted live container, `spec:AST-086` FR4 applies instead. |+| direct authority | `component:Banner`. Owners: `cixzhang`, `imdreamrunner` |+| warning | Consumer docs and the release notes name `DEP-0007` and the explicit `role` that keeps the released semantics. No runtime warning (`spec:AST-017` FR29) |+| migration | Non-mechanical: a caller that announces an async outcome calls `useAnnounce` from the transition that produced it; a caller whose Banner is a persistent mirror or urgent content passes `role="status"` or `role="alert"`. Inside a mounted live container, `spec:AST-086` FR4 applies instead. |+| codemod | None: whether a Banner needs an announcement, and when, depends on the transition that renders it, which only the caller knows; adding the released role everywhere would restore the coupling this cleanup removes |+| downstream | Maintained docs teach `useAnnounce` for async outcomes and explicit `role` for persistent mirrors. Inside a mounted live container, `spec:AST-086` FR4 applies instead. |+| transition | no prior transition |+| state | `proposed` |+| open decision | Banner FR and DEC entries that make `status` visual-only |+| target plan | `CLN-0015` in the next minor release |### CLN-0015 — Banner renders no live-region role by default@@ -105,16 +105,16 @@ prop vocabulary or extensibility rule changes.The requirements below describe the current implementation and its additiveframe target contract.-| ID | Invariant | Basis | Contract state |-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |-| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`. | Current source, public docs, and tests | Current behavior |-| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`. | Current source and tests | Current behavior |-| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style. | Current source and elevation tests | Current behavior |-| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners. | Current source | Current behavior |-| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius. | Current compiler output and CSS inheritance | Current reachability gap |-| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element. | Owner decision; current source and tests | Current behavior |-| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged. | Current target inventory; compatibility policy | Current behavior |-| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role. Async outcomes MUST announce from the transition handler through `useAnnounce`; `role="alert"` is reserved for genuinely urgent interruptive content. | Accessibility Checklist §Announcements; owner decision | Current behavior |+| ID | Invariant | Basis | Contract state |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |+| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`. | Current source, public docs, and tests | Current behavior |+| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`. | Current source and tests | Current behavior |+| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style. | Current source and elevation tests | Current behavior |+| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners. | Current source | Current behavior |+| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius. | Current compiler output and CSS inheritance | Current reachability gap |+| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element. | Owner decision; current source and tests | Current behavior |+| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged. | Current target inventory; compatibility policy | Current behavior |+| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role, except on a Banner added inside a mounted live container (`spec:AST-086` FR4). Async outcomes MUST announce from the transition handler through `useAnnounce`, except inside a mounted live container, where `spec:AST-086` FR4 applies; `role="alert"` is reserved for genuinely urgent interruptive content. | Accessibility Checklist §Announcements; owner decision | Current behavior |### Allowed variation@@ -154,11 +154,15 @@ runtime work.`status` communicates visual category through color and icon; it does not chooseannouncement urgency. Banner renders no live-region role by default. A caller mayprovide `role="status"` through the standard DOM surface when the visible banner-is intentionally a persistent semantic mirror. Async outcomes use `useAnnounce`+is intentionally a persistent semantic mirror, except on a Banner added inside a+mounted live container. Async outcomes use `useAnnounce`from the transition handler, which writes into a previously mounted live region;+inside a mounted live container, that container delivers them+(`spec:AST-086` FR4);a Banner mounted together with its message is not a reliable announcement.`role="alert"` remains available as an explicit native role, but is reserved for-genuinely urgent content that should interrupt current speech.+genuinely urgent content that should interrupt current speech; it is not used on+a Banner added inside a mounted live container.Dismissal focus handoff, disclosure controls, and accessible control names remainunchanged.@@ -247,8 +251,9 @@ placement and would imply that the target must remain on the outermost element.Banner status selects color and icon only. It does not assign `role="status"` or`role="alert"`. Async outcomes announce through `useAnnounce` from the transitionhandler so the message reaches a persistent live region rather than one mounted-with its content. An explicit native role remains available through BaseProps for-a persistent semantic mirror or the rare genuinely urgent alert.+with its content; inside a mounted live container, `spec:AST-086` FR4 applies. An explicit native role remains available through BaseProps for+a persistent semantic mirror or the rare genuinely urgent alert, except on a+Banner added inside a mounted live container.Rejected: deriving alert urgency from `warning` or `error`. Severity and urgencyare independent, and a static error present on first paint is not an event thatdiff --git a/packages/core/src/FieldStatus/FieldStatus.spec.md b/packages/core/src/FieldStatus/FieldStatus.spec.mdindex 4a73e5c7e0..1d701cadbc 100644--- a/packages/core/src/FieldStatus/FieldStatus.spec.md+++ b/packages/core/src/FieldStatus/FieldStatus.spec.md@@ -38,7 +38,8 @@ detached presentations; consumer usage remains documented in- Released default preserved: `yes`- Compatibility class: additive documentation only; runtime, DOM, styling, and- public API remain unchanged+ public API remain unchanged, except that delivery inside a mounted live+ container follows `spec:AST-086` FR4- Controlled/uncontrolled behavior: not applicable- Migration decision: direct `FieldStatus variant="tooltip"` support is rejected.`tooltip` remains a field-family sentinel that MUST be handled before rendering@@ -127,7 +128,7 @@ intentional decision.- **AR1 — Programmatic announcement channel.** Errors MUST update the persistentassertive region; warnings and successes MUST update the persistent politeregion, including on first mount and when message or type changes, without- moving focus.+ moving focus. Inside a mounted live container, `spec:AST-086` FR4 applies.- **AR5 — Assistive-technology output.** Claims about whether, when, or how themessage is spoken or presented in braille MUST be verified through the real-ATevidence process in `spec:AST-009`; DOM and accessibility-tree checks prove