An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-086): announce a message when it appears after the page loads (#7961)
Cindy Zhangf2dafed1bd76
diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.mdindex 6f085213c8..96673a649f 100644--- a/docs/architecture/react-component-runtime.md+++ b/docs/architecture/react-component-runtime.md@@ -15,7 +15,7 @@ verified_by:packages/core/src/Layer/useLayer.test.tsx,packages/core/src/utils/sharedResizeObserver.test.ts,]-deciding_specs: []+deciding_specs: [spec:AST-086/DEC-2]---# React component runtime architecture@@ -26,7 +26,16 @@ deciding_specs: []{"scope": "global","triggers": {- "react-runtime": ["INV1", "INV2", "INV3", "INV4", "INV5", "INV6", "INV8"]+ "react-runtime": [+ "INV1",+ "INV2",+ "INV3",+ "INV4",+ "INV5",+ "INV6",+ "INV8",+ "INV10"+ ]}}```@@ -119,6 +128,14 @@ those contracts.hook-result identity remains owned by `architecture:public-component-api` andthe hook's current contract. Ordinary local objects and callbacks have no sharedidentity promise.+- **INV10 — Own-content announcements live in one module.** In+ `@astryxdesign/core`, announcing a component's own rendered content+ (`spec:AST-086` FR11) is done by one shared internal module, which is not+ exported; making it public needs `spec:AST-002` admission. Packages outside+ core cannot import it and keep one well-behaved Effect per adopter. Core+ adopting components hold no Effect, observer, timer, or+ listener of their own to detect page load, read rendered text, or write that+ announcement. The module follows INV3 and INV5.## Authoring guidance@@ -236,8 +253,11 @@ contracts.## Deciding specs-None. Component, family, API, accessibility, layer, interaction, and style records-remain authoritative for the user-facing outcomes delegated above.+- `spec:AST-086/DEC-2` — own-content announcements behave the same in every+ component that announces its own rendered content (INV10).++Component, family, API, accessibility, layer, interaction, and style records+remain authoritative for the other user-facing outcomes delegated above.## Verification@@ -256,3 +276,4 @@ component suite is not blanket conformance with every invariant.| INV7 | Real-browser geometry plus N-consumer observer-instance/subscription mutations | Geometry is invalid, observer instances grow with repeated consumers, one unsubscribe silences peers, or cleanup removes another subscriber || INV8 | Owner-observable behavior across documented composition replacement; optional focused internal mechanism tests | Behavior disappears or changes owner when a documented subpart is replaced || INV9 | Provider/external-store identity and render-count tests | Unchanged semantic payload changes identity, or snapshot identity creates a render loop |+| INV10 | Shared test over every adopter of the announcement module | An adopter holding its own Effect, observer, timer, or listener for its own-content announcement |diff --git a/docs/specs/AST-086-status-announcements/spec.md b/docs/specs/AST-086-status-announcements/spec.mdindex 76de830555..6681061e59 100644--- a/docs/specs/AST-086-status-announcements/spec.md+++ b/docs/specs/AST-086-status-announcements/spec.md@@ -60,8 +60,8 @@ announcement channel.carries a live role (`status`, `alert`, `log`) or `aria-live`.- **FR2 — Transient messages use the shared channel.** When the element thatshows 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+ owner announces through the shared announcement channel, except as FR4, FR10,+ and FR11 provide. The new elementMUST NOT carry a live role or `aria-live`.- **FR3 — Live roles only on persistent containers.** A component MAY own alive role only on an element that stays mounted while its content changes.@@ -90,12 +90,46 @@ announcement channel.- **FR9 — One shared channel per document.** The channel is one polite and oneassertive region per document. They are created empty, stay mounted for thedocument's lifetime, and clear their text shortly after each announcement so- stale text does not linger. `useAnnounce` is the public way to reach it.+ stale text does not linger. Messages written to a region before the previous+ one is exposed are joined in order into one announcement; none is dropped. An+ empty message clears the region, including messages joined but not yet+ exposed.+ `useAnnounce` is the public way to reach it.- **FR10 — Modal-hosted owners keep their own channel.** While the sharedchannel is not admitted to modal hosting, a globally hosted owner that`spec:AST-003` rehosts above native modals (FR16, FR18) announces through itsown persistent polite and assertive containers, which move with it. FR3, FR5,and FR6 apply to those containers.+- **FR11 — A message announces when it appears after the page loads.** Page+ load covers everything committed until the document finishes loading,+ including the page's first render from the server or the client. A message+ present during page load is not announced. A message inserted after the+ document finishes loading, or whose text changes after that, is announced+ once. That includes a message brought in by a client-rendered route change and+ a server-rendered message inserted by client navigation. A message that+ reaches assistive technology only through its announcement, such as a picker's+ empty-panel message under `spec:AST-056` FR3, announces even during page load.+ FR4 applies inside a mounted live container, and FR6 governs repeats. FR11+ covers components that announce their own rendered content;+ `component:FieldStatus`, a grouped field's status message (as in TimeInput+ inside an input group), and `component:Banner` keep their own announcement+ rules.+- **FR12 — Own-content announcements behave the same everywhere.** Every+ component FR11 covers announces the element's+ rendered text, or its accessible name when it renders no text, leaving out+ `aria-hidden` content. It stays silent for text present during page load+ (except as FR11 provides for announcement-only messages), announces once per later appearance or text change, and re-arms when+ the element is hidden. During a server render it announces nothing and adds no+ live role, and a server-renderable adopter stays server-renderable and passes+ the server-safe component boundary check. Any mechanism that satisfies this is+ valid; `architecture:react-component-runtime` INV10 places it.+- **FR13 — Own-content announcements are well behaved.** Announcing a+ component's own rendered content (FR11) happens once per occasion under+ rerender, dependency change, and StrictMode replay, does no work while the+ element is hidden, and leaves nothing behind after unmount. Action+ announcements, such as a result count from a query handler or FR8 busy+ starts, keep their own owner. `architecture:react-component-runtime` INV10+ owns where this work lives.### Platform support@@ -126,8 +160,9 @@ announcement channel.- Switch: busy is announced through the channel, and the thumb Spinner alsomounts with `role="status"`. Under FR8 the thumb Spinner is silent. Under FR6StrictMode 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+- Spinner (standalone): mounts with `role="status"` and its name. Under FR2 and+ FR11 it announces its label through the channel when it appears after page+ load, and stays silent when present at page load. The role and name itexposes 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@@ -142,9 +177,14 @@ announcement channel.- ChatMessageList: its top loading Spinner is a `role="status"` child of thelog. Under FR4 and FR8 it is silent, and ChatMessageList announces its loadingthrough 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.+- EmptyState: its root mounts a live role together with its text. Under FR2,+ FR11, and FR12 it carries no live role and announces when it appears+ after page load. EmptyState stays server-renderable.+- The ChatComposer status bar carries no live role and announces the caller's+ status message from its own Effect. That is own content, so under+ `architecture:react-component-runtime` INV10 it moves onto the shared module.+- The chat trigger menu's loading row carries no live role. Its "Searching…"+ announcement is the menu's busy start under FR8 and keeps its own owner.- Button: its persistent loading region fits FR3, except when a Button firstrenders loading and the region mounts holding its text. Inside a livecontainer it keeps its role and urgency (FR4).@@ -153,27 +193,43 @@ announcement channel.their role and urgency (FR4).- ChatSystemMessage: forces `role="status"` inside the `role="log"` list. UnderFR4 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.+- ChatTypingIndicator (lab): announces its label from its own Effect. Inside a+ live log it follows FR4; otherwise it follows FR11 through FR13. It keeps its+ own Effect because the core module is not published to lab (INV10).- Comments (lab): its error banners and progress label mount live rolestogether with their text. Inside a live log they follow FR4; otherwise FR2.+- Selector and MultiSelector render their empty-panel message as+ `role="presentation"`, so it reaches assistive technology only through the+ announcement and announces even at page load (FR11, `spec:AST-056`+ FR3). Typeahead and CommandPalette announce their empty state after page load and are otherwise unchanged.+- `component:FieldStatus` AR1 is unchanged: a field message announces on first+ mount, because it reports the field's state when the field appears.+- `component:Banner` FR8 is unchanged: the caller announces an async outcome+ from its transition handler, because only the caller knows whether a Banner+ is a new outcome or persistent content. FR11 and FR12 cover components that+ announce their own content.+- `useAnnounce`: messages written in the same frame are joined instead of the+ last one replacing the others (FR9).- `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) | Recommended `spec:AST-009` real-AT follow-up | Toast, busy Switch, chat notice | Missing, repeated, or out-of-order speech fails |+| 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, two messages in one frame, clear after a joined message | A second region pair, stale text after the clear delay, a dropped same-frame message, or a joined message surviving a clear 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 |+| FR11, FR12 | Helper and component tests | EmptyState present at page load, server-rendered, inserted later, text changed, hidden and shown again, brought in by a client-rendered route change, inside a chat log, empty Selector panel open at page load, server-rendered message inserted by client navigation, message inserted after first render but before the document finishes loading (silent) | Announcing at page load or during a server render (other than an announcement-only message), missing a later insertion or a server-rendered message inserted by client navigation, a client-rendered route change, or an empty Selector panel at page load, repeating one occasion, or also using the channel inside a live container fails |+| FR12 (server) | Server-safe component boundary check plus a server render of each adopter | EmptyState rendered on the server and hydrated | An adopter that fails the boundary check, or emits an announcement or live role from a server render, fails |+| FR13 | Helper StrictMode, hide/show, and unmount tests on each adopter | EmptyState, Spinner, ChatComposer status bar, ChatTypingIndicator | A duplicate announcement under StrictMode, work while hidden, or a resource left after unmount fails |+| FR6 (AT) | Recommended `spec:AST-009` real-AT follow-up | Toast, busy Switch, chat notice | Missing, repeated, or out-of-order speech fails |## Decision log@@ -193,6 +249,20 @@ until the shared channel can be hosted there (FR10).Rejected: delivering transient messages through each component's own liveregion — the page gains many competing regions and two-owner duplicates recur.+### DEC-2 — A message announces when it appears after the page loads++**Reference:** `spec:AST-086/DEC-2`+**Decider:** cixzhang, 2026-10-22++A message that is on the page when it loads is read with the page. Announcing it+interrupts people with something they are about to read. A message that appears+later is news and is announced once. Page load is the boundary because it is the+one every app shares without extra code.+Every self-announcing component behaves the same way (FR12).++Rejected: announcing on every mount — page loads would speak every empty state+and spinner on screen.+## Open questionsNone.