# Announcer

> Headless queue of aria-live announcements: a live-region island subscribes to its state and re-renders on change.

```ts
import { Announcer } from "@sdxc/ui/behaviors";
```

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

```ts
new Announcer()
```

## 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

```tsx
announcer.addEventListener("change", () => handle.update(), { signal: handle.signal });
```

## Used with it

The events, constants and types its module publishes, each imported from `@sdxc/ui/behaviors` too.

### Announcer.Message

One queued announcement.

#### Members

| 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` |  |

### Announcer.Events

Events dispatched by Announcer.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `change` | `Event` | Dispatched after a message is queued, dismissed, advanced past, or the queue is cleared. |

### 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.

#### Signature

```ts
type Announcer.Priority = "polite" | "assertive"
```

One of `"polite"`, `"assertive"`.