# Announcements

> Saying aloud what happened where focus is not: once, politely, in a region beside what speaks.

Some of what an interface does happens where nobody is looking: rows removed,
cells pasted, a shape moved by a key, a value held to its range. Someone who
sees the screen sees it happen. Someone listening to a screen reader hears only
what has focus — unless the interface says the rest aloud. An announcement is
that sentence: brief, polite, and said once.

## Best practices

**Say what was done, not what was pressed.** "Removed 2 rows.", "Pasted 4 cells;
1 is read-only and was left.", "Moved to 20, 30." A person who pressed Delete
knows they pressed it; what they need is the outcome, with the numbers that tell
them it was what they meant.

**Say only what focus does not.** When focus moves, the screen reader reads what
it lands on — its name, its state, its place. Do not repeat that. A calendar
that moves to the next month as an arrow key crosses into it says nothing: the
day that takes focus is named with its month. The same change made from a
"Next month" button, which keeps focus, is said, because nothing else would say
it.

**Say what was refused, and why.** A paste that left cells out, a value moved
into its range, a change a lock would not allow: each is said with its reason,
as the interface marks it where it happened. Nothing typed is lost without a
word.

**Be polite.** An announcement waits for the screen reader to finish what it is
saying. Interrupting — an assertive announcement — is for what cannot wait,
which in an editing interface is almost nothing: a refused change is told
politely, beside the mark that shows it.

**Say one thing per act.** When one act changes several things — a removal
that also empties the selection — what is said is what the act came to: the
removal. Where two things both matter, say them together in one sentence, in
the order they happened.

**Say the same thing twice when it happened twice.** Undo pressed twice is two
undos, and is heard twice, though the words are the same.

**Keep up with the hand.** Words that are out of date before they are heard are
noise: an act that is repeated faster than it can be said — a key held down —
says each step only as it is reached, each replacing the last that was not yet
heard, not a queue of every step.

**Never move focus to say something.** An announcement is heard where the
person is. Taking focus to a message, to make it read, takes them away from
their work and leaves them to find their way back.

**Withdraw what is no longer true.** A reason that no longer holds — text
corrected, so it reads — is taken back, so that someone who goes looking for it
does not find a reason for nothing.

**Speak in the interface's language.** Announcements are words like any other
label, and are given in the language of the interface, with its numbers.

## Where it is said from

Each component that speaks keeps its own region, beside it in the page. Several
components on one page each say their own words. A region in the part of the
page that is in use is heard: when a sheet makes the rest of the page inert, a
component inside the sheet is still heard, and one behind it is quiet, as the
rest of what is behind it is.

## Platform considerations

**Screen readers.** A live region is heard only for what changes in it, so it is
in the page, empty, before anything is said into it; and each announcement is
new content in it, so that the same words said again are not taken for nothing
new.

**Visual.** An announcement is for those who cannot see the change. What is
announced is also shown — a cell marked, a count changed — so nobody depends on
the announcement alone, and the region itself is not seen.

## Behaviour

Each statement is verified by a test in Chromium, Chromium (touch), Firefox, WebKit, WebKit (touch), unless it names the environments it applies to or is marked open.

### Saying

- What is said goes into a polite status region, which is there, and empty, from the start.
- The same words said twice are heard twice: each time they are new in the region.
- What is said in one turn is one announcement: the last, which is what the act came to.
- Words that come faster than they can be heard are paced, and each that comes while one waits takes its place.
- Saying nothing withdraws what was said.
- Words said after the region has gone are let go, not failed on.

### Focus

- Saying something leaves focus where it is.
- The region is never in the Tab order.

### Several on a page

- Each speaker has its own region, beside it: one's words are not said in another's.

## Reference implementation

React: `npx shadcn@latest add https://ui.publictheta.com/r/announcements.json`