An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-086): announcements inside a modal reach that modal, including useAnnounce (#8115)
Cindy Zhangfccda0f7a04a
diff --git a/docs/specs/AST-086-status-announcements/spec.md b/docs/specs/AST-086-status-announcements/spec.mdindex dfeee04b8e..3f90139264 100644--- a/docs/specs/AST-086-status-announcements/spec.md+++ b/docs/specs/AST-086-status-announcements/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-10-15+approved_at: 2026-10-23phase: acceptedowners: [cixzhang]affects_architecture: [architecture:react-component-runtime]@@ -61,7 +61,7 @@ announcement channel.- **FR2 — Transient messages use the shared channel.** When the element thatshows a message mounts, unmounts, or is replaced together with its text, theowner announces through the shared announcement channel, except as FR4, FR10,- and FR11 provide. The new element+ FR11, and FR14 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.@@ -74,7 +74,8 @@ announcement channel.keeps its own role and delivers its own content at its own urgency.- **FR5 — Urgency.** Outside a live container, errors and time-criticalfailures use the assertive channel. All other status messages use the polite- channel. Inside a mounted live container, FR4 applies.+ channel. Inside a mounted live container, FR4 applies. Inside an open native+ modal, FR14's containers carry the same two urgencies.- **FR6 — Once per occasion.** An occasion is one state transition or one useraction. 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@@ -95,7 +96,8 @@ announcement channel.identical message repeated within the same frame is one message (FR6). Anempty message clears the region, including messages joined but not yetexposed.- `useAnnounce` is the public way to reach it.+ `useAnnounce` is the public way to reach it. When an open native modal encloses the+ caller, it follows FR14 instead.- **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 its@@ -131,6 +133,53 @@ announcement channel.announcements, such as a result count from a query handler or FR8 busystarts, keep their own owner. `architecture:react-component-runtime` INV10owns where this work lives.+- **FR14 — Owners inside an open modal deliver inside it.** While the+ shared channel is not exposed inside native modals (Platform support), a+ message its owner would otherwise send through the shared channel — an FR2+ message or an action announcement such as a result count, a selection+ change, or a busy start — follows the nearest open native modal that+ encloses its owner. When Astryx renders that modal (such as a Dialog, a+ modal BottomSheet, a modal Drawer, a Lightbox, or CommandPalette), the+ message is delivered through a persistent polite container and a persistent+ assertive container inside it. When an app renders that modal without+ Astryx, the last sentence of FR14 applies. When no open native modal+ encloses the owner, the message uses the shared channel. The public `useAnnounce` takes this route: a message sent with it+ from inside such a modal, by a component or by app code, is delivered+ through that modal's containers, with no separate path. The route follows+ where the owner is when it announces, so one owner that is sometimes inside+ a modal and sometimes not needs no second announcement path. An Astryx component that+ renders an Astryx modal and announces about that modal's content, such as+ CommandPalette's result counts or Lightbox's position, is inside that modal+ for this route while it is open. App code reaches a modal's containers by+ calling `useAnnounce` from a component rendered inside that modal; a call+ made outside the modal, even by the component that renders it, takes the+ route of where that call is. When a modal closes while a message in its+ containers is not yet exposed, that message is delivered through the channel+ exposed after the close — the containers of the native modal then on top+ when Astryx renders it, or the shared channel when no native modal is open+ — so a message sent just before its modal closes, such as "Saved" followed+ by closing a Dialog, is not lost. When the modal then on top is one an app+ renders without Astryx, delivery of that message is outside this record. FR14 adds one+ container of each urgency per modal for these messages; an owner's own+ persistent FR3 region — Button's loading region, an input's invalid-entry+ region — keeps its role and urgency inside the modal as FR4 says, and an+ owner that `spec:AST-003` rehosts above the modal keeps FR10's own+ containers. FR14's containers are direct children of the modal's dialog+ element, created empty on first use (FR3), carry `status` and `alert`+ respectively (FR5), and clear shortly after each announcement; messages+ written to one before the previous is exposed are joined in order, an+ identical message repeated within the same frame is one message, and an+ empty message clears it, including messages joined but not yet exposed, as+ FR9 says of the shared channel. FR6 applies to each owner's messages. A busy owner's FR8 region inside a modal is+ FR14's polite container. When a later modal opens above the owner's modal+ (`spec:AST-003` FR17), the owner's containers are inert with its modal, and+ a message it announces while covered is not heard — the container clears it+ before the modal is on top again — as the owner itself is not operable+ until then. When the nearest open native modal enclosing a busy owner is+ one an app renders without Astryx, the owner announces its busy start+ through a persistent region inside that modal (FR3, FR8), including when+ that modal is itself inside an open Astryx modal; other delivery from an+ owner inside such a modal is outside this record.### Platform support@@ -139,12 +188,16 @@ announcement channel.no-op and renders nothing.- While a native modal dialog is open, the shared channel on the page body isnot 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.+ hosting. Owners rehosted above the modal use their own containers (FR10),+ and an owner rendered inside the modal — a busy control (FR8), a picker's+ selection and result messages, a sheet's search outcome — announces through+ the persistent containers inside that modal (FR14). Delivery from an owner+ that is neither inside the modal nor rehosted above it is outside this+ record. Inside a native modal that Astryx does not render, a busy owner+ announces its busy start through a persistent region inside that modal+ (FR3, FR8), and other delivery is outside this record.- Browser evidence: DOM and accessibility-tree checks prove routing (FR1–FR5,- FR7–FR10). Spoken timing, order, and repetition on real AT are+ FR7–FR10, FR14). Spoken timing, order, and repetition on real AT arerecommended `spec:AST-009` follow-up, not a merge or release requirement.## Current-state impact@@ -174,7 +227,28 @@ announcement channel.each control announces its own busy state through the channel. Switchalready does. CommandPalette opens as a native modal, so it announces each busystart, including its load on opening or clearing the query, through a- persistent region inside its dialog (FR3).+ persistent region inside its dialog (FR3); under FR14 that region is the+ dialog's polite container.+- Owners inside Astryx modals (FR14): `useAnnounce` writes only to the+ page-body channel. Under FR14 it follows the nearest open native modal+ enclosing the caller, delivering into that modal's containers when Astryx+ renders it, so owners and app code rendered inside a modal need no separate+ path. Channel messages that are not exposed inside a modal and become+ audible, including app messages sent with `useAnnounce`: a Selector, MultiSelector, Typeahead, Tokenizer, date or time+ input, or any other channel caller rendered inside a Dialog, a modal+ BottomSheet, a modal Drawer, or a Lightbox. A busy owner inside a modal+ already announces its busy start inside the dialog; its region is FR14's+ polite container, so busy starts written to it before the previous is+ exposed are joined instead of the last one replacing the others, and a busy+ owner in a non-modal sheet or drawer nested inside an open modal announces+ in that modal rather than on the page body. CommandPalette's result counts+ and empty results (its busy starts already use its in-dialog region) and+ Lightbox's position and zoom messages are sent from above the modal each+ renders, so routing by where the caller is does not reach the modal; under+ FR14 each delivers them into its own open modal, a change in each component+ beside `useAnnounce`. A message pending when its modal closes is+ written inside the dialog or on the inert page body; under FR14 it moves to+ the channel exposed after the close.- 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.@@ -220,20 +294,21 @@ announcement channel.## 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), operation that settles before its busy announcement is exposed | A composed indicator with a live role or its own announcement, or a busy owner that announces nothing, fails, or a busy start announced after its outcome, fails |-| FR9 | `useAnnounce` tests | First use, many components, region removed, server render, two messages in one frame, clear after a joined message, the same message twice in one frame | A second region pair, stale text after the clear delay, a dropped same-frame message, or a joined message surviving a clear fails, or an identical same-frame repeat announced twice, 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 |+| 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), operation that settles before its busy announcement is exposed | A composed indicator with a live role or its own announcement, or a busy owner that announces nothing, fails, or a busy start announced after its outcome, fails |+| FR9 | `useAnnounce` tests | First use, many components, region removed, server render, two messages in one frame, clear after a joined message, the same message twice in one frame | A second document-level region pair, stale text after the clear delay, a dropped same-frame message, or a joined message surviving a clear fails, or an identical same-frame repeat announced twice, 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 |+| FR14 | Hook tests and an accessibility-tree check with an Astryx modal open | Owner outside any modal, inside an open non-modal dialog, inside an open modal (polite and assertive, repeat of the same words, empty message), busy start inside a modal, busy start inside a native modal an app renders without Astryx, alone and opened inside an Astryx Dialog; a modal sheet's row toggle in a real engine, app code calling `useAnnounce` inside a Dialog, CommandPalette result count and Lightbox position message while each is open, a message followed by closing its Dialog before it is exposed (inside another open modal and on the page), a message pending when a CommandPalette opened over a Dialog closes, app code calling `useAnnounce` outside the Dialog it renders (body-level channel) | A channel message from inside an open modal that reaches only the body-level channel, an FR14 container mounted holding its text, a second FR14 container of one urgency in one dialog, an FR14 container the engine's accessibility tree omits, a dropped message of two written before the first is exposed, an empty message that leaves text in the modal's FR14 container, an app `useAnnounce` message from inside an Astryx modal that reaches only the body-level channel, a CommandPalette or Lightbox message about its open modal that reaches only the body-level channel, a message lost when its modal closes before it is exposed, or a pending message handed to a channel still inert after the close, a busy start inside an app-rendered native modal that reaches only the body-level channel, or one inside an app-rendered native modal nested in an Astryx Dialog that is delivered to the Dialog's FR14 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@@ -267,6 +342,29 @@ Every self-announcing component behaves the same way (FR12).Rejected: announcing on every mount — page loads would speak every empty stateand spinner on screen.+### DEC-3 — An owner inside an Astryx modal announces inside it++**Reference:** `spec:AST-086/DEC-3`+**Decider:** cixzhang, 2026-10-23++A control rendered inside an open Astryx modal — a modal sheet's checkbox rows,+its search, a busy control — is heard only through containers inside that+dialog, because the page-body channel is outside the modal's exposed subtree.+Busy starts already took that route (FR8); FR14 gives every status message+from such an owner the same route, chosen per announcement by where the owner+is, so a component that is sometimes modal-hosted and sometimes inline keeps+one announcement path. One FR14 container per urgency per dialog keeps FR1's+single owner and FR9's joining and clearing inside the modal, beside the+owners' own FR3 regions, which FR4 already lets stand. The public+`useAnnounce` follows the same route, so a message an app sends from inside a+modal is heard as well as one a component sends.++Rejected: an internal route that each component adopts while the public+`useAnnounce` keeps writing to the page body — app messages from inside a modal+stay silent; admitting the shared channel to modal hosting — `spec:AST-003` owns+hosting and has not admitted it; a per-component region for each message —+competing regions and two-owner duplicates inside one dialog.+## Open questionsNone.