Skip to content

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.md
index 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` and
the hook's current contract. Ordinary local objects and callbacks have no shared
identity 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.md
index 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 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
+ owner announces through the shared announcement channel, except as FR4, FR10,
+ and FR11 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.
@@ -90,12 +90,46 @@ announcement channel.
- **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.
+ 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 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.
+- **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 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
+- 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 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
@@ -142,9 +177,14 @@ announcement channel.
- 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.
+- 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 first
renders loading and the region mounts holding its text. Inside a live
container 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. 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.
+- 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 roles
together 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 live
region — 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 questions
None.