generative-a11y
GitHubnpm
DOM

createDOMAnnouncer

Create an owned browser announcer with progressive ariaNotify delivery, stable live-region fallback, diagnostics, and cleanup.

Signature and import

auto mode attempts ariaNotify when available, then falls back to the selected polite or assertive live region.

typescript
import { createDOMAnnouncer } from "@generative-a11y/dom";

const announcer = createDOMAnnouncer({
  mode: "auto",
  onDiagnostic(result) {
    console.log(result.status, result.method);
  },
});

const result = announcer.announce(intent);
announcer.dispose();

How this code works

  1. 01
    Use progressive delivery

    auto keeps the fallback available when ariaNotify is absent or throws.

  2. 02
    Observe the attempt

    DOMDeliveryResult reports the browser action without making a speech claim.

  3. 03
    Release owned nodes

    Dispose removes only live regions created by this announcer.

Options and return values

optionsDOMAnnouncerOptionsOptional

Selects document, delivery mode, supplied regions, and diagnostic observation.

Default
{}
returnDOMAnnouncerReturn

Owned announcer with announce, getRegions, and dispose methods.

Default
n/a

DOMAnnouncerOptions

Supplying regions transfers neither node ownership nor removal responsibility to the library.

Options and return values

documentDocumentOptional

Document used to create live regions. Without a document, the announcer remains inert and reports unavailable.

Default
global document
modeauto | aria-notify | live-regionOptional

Selects progressive enhancement or a forced test path.

Default
"auto"
regionsDOMLiveRegionsOptional

Supplies stable polite and assertive elements. Both must belong to the same document.

Default
owned regions
onDiagnostic(result) => voidOptional

Observes each delivery attempt. Callback failures cannot alter delivery.

Default
undefined

DOMDeliveryResult

announce returns one result synchronously.

StatusMethodMeaning
notifiedaria-notifyariaNotify returned without throwing
mutatedlive-regionSelected stable region text changed
unavailablenoneNo usable document or region exists
disposednoneannounce was called after disposal

Options and return values

channelpolite | assertiveRequired

Intent channel selected for this attempt.

Default
n/a
announcementIdstringRequired

Stable ID copied from the AnnouncementIntent for diagnostic correlation.

Default
n/a
sourceTypeGenerativeA11yEvent['type']Required

Event type that produced the announcement intent.

Default
n/a
atnumberRequired

Injected-clock timestamp copied from the announcement intent.

Default
n/a
sourceEventIdstringOptional

Application event ID when the source event supplied one.

Default
undefined
responseId / toolId / interactionIdstringOptional

Entity IDs copied from the announcement intent when present.

Default
undefined
error{ name, message }Optional

Serializable ariaNotify failure information when fallback was needed.

Default
undefined