[ @sdxc/ui/behaviors ]
Announcer
Headless queue of aria-live announcements: a live-region island subscribes to its state and re-renders on change.
import { Announcer } from "@sdxc/ui/behaviors";Usage
Owns a priority-ordered queue of aria-live announcements. A live-region
island subscribes to "change", renders Announcer.current into an
aria-live element, and calls Announcer.next once it has been read.
Signature
new Announcer(options?: Announcer.Options)Parameters
| Parameter | Type | Description |
|---|---|---|
options? | Announcer.Options | How long each message holds before the queue advances on its own. |
Properties
| Property | Type | Description |
|---|---|---|
current | Announcer.Message | undefined | The message a live region should currently render, or undefined when the queue is empty. |
messages | readonly Announcer.Message[] | Every queued message, in the order a live region should announce them. |
Methods
| Method | Description |
|---|---|
announce(text: string, priority?: Announcer.Priority): string | Queues a message for announcement. Assertive messages are inserted ahead of any polite messages already queued so they interrupt the live region, and behind assertive messages queued earlier; polite messages append. |
dismiss(id: string): void | Removes one queued message by id, wherever it sits in the queue, dispatching "change" only when a message with that id was queued. |
next(): void | Advances past the current message so the next queued one becomes Announcer.current, dispatching "change" only when the queue held a message. |
clear(): void | Empties the queue, dispatching "change" only when it held messages. |
Examples
whileLive(handle, (model: Announcer, signal) => model.addEventListener("change", () => handle.update(), { signal }))(announcer);Used with it
The events, constants and types its module publishes, each imported from @sdxc/ui/behaviors too.
Interface
Announcer.Message
One queued announcement.
| Member | Type | Description |
|---|---|---|
id | readonly string | Stable id used to target this message with Announcer.dismiss. |
text | readonly string | Announcement copy, read verbatim by the live region. |
priority | readonly Priority |
Interface
Announcer.Options
Options for constructing an Announcer.
| Member | Type | Description |
|---|---|---|
hold? | number | Milliseconds each message stays current before the queue advances on its own: long enough for a screen reader to reach it, short enough that a run of quick changes is heard one by one. Omitted, the live region advances the queue with next(). |
Interface
Announcer.Events
Events dispatched by Announcer.
| Member | Type | Description |
|---|---|---|
change | Event | Dispatched after a message is queued, dismissed, advanced past, or the queue is cleared. |
Type
Announcer.Priority
Politeness a queued message announces with, mirrored onto a live
region's aria-live attribute. "assertive" interrupts the current
utterance and moves ahead of any "polite" messages already queued.
type Announcer.Priority = "polite" | "assertive"