Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
23.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file useAnnounce.ts
 * @input React context; DOM live regions; animation frames
 * @output useAnnounce, AnnouncePoliteness, UseAnnounceOptions; the internal
 *   modal context, in-dialog region writer, and modal route hook
 * @position Core a11y hook for screen-reader announcements. A message goes to
 *   the nearest open native modal around its caller, else to the shared
 *   page-body regions. `modalAnnounce.ts` holds the modal route.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/hooks/index.ts
 */

import {use, useCallback, useRef, type RefObject} from 'react';
import {createSharedContext} from '../utils/sharedContext';

/**
 * Announcement urgency:
 * - `'polite'` (default): announced when the screen reader is idle. Use for
 *   status updates, result counts, "no results", non-urgent confirmations.
 * - `'assertive'`: interrupts the current announcement. Reserve for errors and
 *   time-sensitive alerts.
 */
export type AnnouncePoliteness = 'polite' | 'assertive';

/**
 * Imperative screen-reader announcement function.
 */
export type AnnounceFn = (
  message: string,
  politeness?: AnnouncePoliteness,
) => void;

/** Options for `useAnnounce`. */
export interface UseAnnounceOptions {
  /**
   * Each message from this instance withdraws the instance's previous message
   * if assistive technology has not exposed it yet, whatever its urgency. An
   * exposed message stays. Messages from other instances still join. Use one
   * instance for each state that a component reports, such as a result count.
   * @default false
   */
  hasReplace?: boolean;
}

/**
 * Takes back one announcer's share of a message while it is not yet exposed,
 * wherever the route put it. @internal
 */
export type WithdrawAnnouncement = () => void;

/**
 * One announcer's share of words on their way to being exposed. Whatever
 * holds the words keeps the receipt beside them; when the words move — a
 * modal hands them to the channel exposed after it, or releases words it
 * held through an exit — the mover points the receipt at the new place, so
 * the announcer's handle follows its words. @internal
 */
export interface AnnounceReceipt {
  withdraw: WithdrawAnnouncement | null;
}

/** Words waiting to be exposed, with their announcers' receipts. @internal */
export interface WaitingWords {
  readonly text: string;
  readonly receipts: ReadonlyArray<AnnounceReceipt>;
}

/**
 * The announcer's handle to `receipt`: it takes back the words wherever they
 * are now, once. @internal
 */
export function handleOf(receipt: AnnounceReceipt): WithdrawAnnouncement {
  return () => {
    const withdraw = receipt.withdraw;
    receipt.withdraw = null;
    withdraw?.();
  };
}

/**
 * Move `waiting` words elsewhere, one delivery per announcer and in order,
 * and point each receipt at its delivery, so every announcer can still take
 * back its own share. The deliveries join where they land, so the words are
 * spoken once. @internal
 */
export function forwardWaiting(
  waiting: ReadonlyArray<WaitingWords>,
  deliver: (text: string) => WithdrawAnnouncement | null,
): void {
  for (const {text, receipts} of waiting) {
    for (const receipt of receipts) {
      receipt.withdraw = deliver(text);
    }
  }
}

const CONTAINER_ATTR = 'data-astryx-live-region';

// The same clip as VisuallyHidden. It is inline, so the regions work without
// a stylesheet.
const VISUALLY_HIDDEN_CSS =
  'position:absolute;width:1px;height:1px;margin:-1px;padding:0;' +
  'overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;' +
  'inset-block-start:0;inset-inline-start:0;pointer-events:none;' +
  'user-select:none;';

interface LiveRegions {
  polite: HTMLElement;
  assertive: HTMLElement;
}

/**
 * Screen readers need this time to read the message. The clear then keeps
 * stale status text out of the accessibility tree.
 */
const CLEAR_DELAY_MS = 2000;

const clearTimers: {
  [K in AnnouncePoliteness]: ReturnType<typeof setTimeout> | null;
} = {
  polite: null,
  assertive: null,
};

function cancelScheduledClear(politeness: AnnouncePoliteness): void {
  const timer = clearTimers[politeness];
  if (timer != null) {
    clearTimeout(timer);
    clearTimers[politeness] = null;
  }
}

// Messages written before the region exposes them wait here. One frame
// exposes them together and in order, so none is dropped. An identical repeat
// is kept once.
const pendingFrames: Record<AnnouncePoliteness, number | null> = {
  polite: null,
  assertive: null,
};
// Each pending message counts its waiting announcers. When one withdraws it
// (a busy start overtaken by its outcome), the message stays for the others.
interface PendingMessage {
  text: string;
  holders: number;
}
const pendingMessages: Record<AnnouncePoliteness, PendingMessage[]> = {
  polite: [],
  assertive: [],
};
// The pending message the latest announce joined, until its announcer takes it.
let lastJoined: PendingMessage | null = null;

function cancelPendingFrames(politeness: AnnouncePoliteness): void {
  const frame = pendingFrames[politeness];
  if (frame != null) {
    cancelAnimationFrame(frame);
    pendingFrames[politeness] = null;
  }
  pendingMessages[politeness] = [];
}

function scheduleClear(
  politeness: AnnouncePoliteness,
  target: HTMLElement,
): void {
  cancelScheduledClear(politeness);
  clearTimers[politeness] = setTimeout(() => {
    clearTimers[politeness] = null;
    target.textContent = '';
  }, CLEAR_DELAY_MS);
}

// The live regions are created once and stay mounted. Many screen readers do
// not announce a live region that is created with its content. They do
// announce a text change in an empty region that is already mounted.
let regions: LiveRegions | null = null;

function createRegion(politeness: AnnouncePoliteness): HTMLElement {
  const el = document.createElement('div');
  el.setAttribute(CONTAINER_ATTR, politeness);
  el.setAttribute('aria-live', politeness);
  el.setAttribute('aria-atomic', 'true');
  el.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');
  el.style.cssText = VISUALLY_HIDDEN_CSS;
  document.body.appendChild(el);
  return el;
}

function getRegions(): LiveRegions | null {
  if (typeof document === 'undefined') {
    return null;
  }
  if (regions) {
    // A test cleanup can remove a region from the DOM. Attach it again.
    if (!regions.polite.isConnected) {
      document.body.appendChild(regions.polite);
    }
    if (!regions.assertive.isConnected) {
      document.body.appendChild(regions.assertive);
    }
    return regions;
  }
  regions = {
    polite: createRegion('polite'),
    assertive: createRegion('assertive'),
  };
  return regions;
}

/**
 * Write `message` to the shared region for `politeness`, joining the messages
 * not yet exposed. Returns how to take this write back while it waits.
 */
export function announceMessage(
  message: string,
  politeness: AnnouncePoliteness,
): WithdrawAnnouncement | null {
  const r = getRegions();
  if (!r) {
    return null;
  }
  const target = politeness === 'assertive' ? r.assertive : r.polite;
  const repeat = pendingMessages[politeness].find(
    pending => pending.text === message,
  );
  if (repeat != null) {
    repeat.holders += 1;
    lastJoined = repeat;
    return () => withdrawPendingAnnouncement(repeat, politeness);
  }
  const pending = {text: message, holders: 1};
  pendingMessages[politeness].push(pending);
  lastJoined = pending;
  if (pendingFrames[politeness] == null) {
    // Clear first, so the change is seen when the new text equals the old
    // text. Some assistive technology ignores identical content.
    target.textContent = '';
    // Some assistive technology merges an immediate re-set with the clear. A
    // re-set in the next frame is more reliable.
    pendingFrames[politeness] = requestAnimationFrame(() => {
      pendingFrames[politeness] = null;
      target.textContent = pendingMessages[politeness]
        .map(pending => pending.text)
        .join(' ');
      pendingMessages[politeness] = [];
    });
  }
  // The clear keeps the last message out of the accessibility tree. Each
  // announce restarts the delay, which is much longer than the frame re-set.
  scheduleClear(politeness, target);
  return () => withdrawPendingAnnouncement(pending, politeness);
}

/**
 * Clear any pending announcement from a region without announcing anything new.
 * Used when the triggering context goes away (e.g. a search query is cleared),
 * so stale status text does not linger in the accessibility tree.
 */
export function clearRegion(politeness: AnnouncePoliteness): void {
  cancelPendingFrames(politeness);
  cancelScheduledClear(politeness);
  if (!regions) {
    return;
  }
  const target =
    politeness === 'assertive' ? regions.assertive : regions.polite;
  target.textContent = '';
}

/**
 * Returns an imperative `announce(message, politeness?)` function that speaks a
 * message through a persistently-mounted, visually-hidden live region.
 *
 * The polite and assertive regions are created once on first use and kept
 * mounted, so announcements are reliable even for messages that appear
 * immediately (unlike a live region rendered together with its content).
 * Messages announced in the same frame are joined, in order, into one
 * announcement, and an identical repeat is kept once. Each message is automatically cleared a couple of seconds after being
 * announced, so users browsing the DOM later do not encounter stale status
 * text; announcing again before the clear simply resets the countdown.
 *
 * An instance created with `hasReplace` states one current state, such as a
 * search's result count: each message it writes withdraws its previous one
 * while that one is not yet exposed, so typing faster than a frame says only
 * the latest count.
 *
 * @param options - `hasReplace` (default false)
 * @example
 * ```
 * function Search() {
 *   const announce = useAnnounce();
 *   const onResults = (n: number) => {
 *     announce(n === 0 ? 'No results found' : `${n} results`);
 *   };
 *   // ...
 * }
 * ```
 */
export function useAnnounce({
  hasReplace = false,
}: UseAnnounceOptions = {}): AnnounceFn {
  const modal = use(ModalAnnounceContext);
  // The latest write of a `hasReplace` instance. Its next message withdraws
  // it if assistive technology has not had it yet.
  const withdrawPreviousRef = useRef<WithdrawAnnouncement | null>(null);
  return useCallback(
    (message: string, politeness: AnnouncePoliteness = 'polite') => {
      if (hasReplace) {
        const withdrawPrevious = withdrawPreviousRef.current;
        withdrawPreviousRef.current = null;
        withdrawPrevious?.();
      }
      let written: WithdrawAnnouncement | null;
      // `modal` is non-null only below a provider, and a provider loads the
      // route. The route decides where the caller is heard.
      if (modal != null && modalRoute != null) {
        written = modalRoute.announce(modal, message, politeness);
      } else if (!message) {
        // An empty message clears the region, with the messages that are
        // not yet exposed.
        clearRegion(politeness);
        written = null;
      } else {
        written = announceMessage(message, politeness);
      }
      if (hasReplace) {
        withdrawPreviousRef.current = written;
      }
    },
    [hasReplace, modal],
  );
}

// Inside an Astryx modal (AST-086 FR14)
//
// The modal route lives in `modalAnnounce.ts`. ModalAnnounceProvider imports
// it, and it installs itself here when it loads. A component that calls
// `useAnnounce` but renders no modal never loads it. This module keeps what a
// caller without an Astryx modal needs: the region writer for a native modal
// that an app renders, and the DOM walk that finds that modal.

const MODAL_REGION_ATTR = 'data-astryx-modal-live-region';

/**
 * What an Astryx modal tells the hooks beneath it: where its dialog element
 * is, and the modal above it, so a caller inside a non-modal sheet nested in
 * a modal still finds the modal.
 */
export interface ModalAnnounceScope {
  dialogRef: RefObject<HTMLDialogElement | null>;
  // The owner's intent: open or presented in this render. A dialog that is
  // meant to be open but is not open yet is being presented in this commit.
  isOpen: boolean;
  parent: ModalAnnounceScope | null;
}

export const ModalAnnounceContext =
  createSharedContext<ModalAnnounceScope | null>(
    'ModalAnnounceContext',
    1,
    null,
  );
ModalAnnounceContext.displayName = 'ModalAnnounceContext';

/** The modal route `modalAnnounce.ts` installs when a provider loads it. */
export interface ModalRoute {
  /**
   * `useAnnounce` from inside `scope`: route `message` by where it is, and
   * return how to take this write back while it waits (a `hasReplace`
   * instance's next message does).
   */
  announce(
    scope: ModalAnnounceScope,
    message: string,
    politeness: AnnouncePoliteness,
  ): WithdrawAnnouncement | null;
  /**
   * Speak inside `dialog` with the exposure, covered and hold rules, and
   * return how to take this write back while it waits.
   */
  announceInModal(
    dialog: HTMLDialogElement,
    message: string,
    politeness: AnnouncePoliteness,
  ): WithdrawAnnouncement | null;
}

let modalRoute: ModalRoute | null = null;

/** Called once by `modalAnnounce.ts` as it loads. @internal */
export function installModalRoute(route: ModalRoute): void {
  modalRoute = route;
}

/** Whether `dialog` is open as a native modal right now. */
export function isOpenModal(
  dialog: HTMLDialogElement | null | undefined,
): boolean {
  return dialog != null && dialog.open && dialog.matches(':modal');
}

/**
 * The nearest open native modal dialog enclosing `element` in the DOM, Astryx
 * or app-rendered. Internal: the busy-announcement hook routes by its owner's
 * element so a busy start inside a native modal an app renders without Astryx
 * is still heard inside it.
 */
export function enclosingModalDialog(
  element: Element | null | undefined,
): HTMLDialogElement | null {
  let dialog = element?.closest('dialog') ?? null;
  while (dialog != null) {
    if (isOpenModal(dialog)) {
      return dialog;
    }
    dialog = dialog.parentElement?.closest('dialog') ?? null;
  }
  return null;
}

/**
 * Speak `message` through the modal `dialog`'s own live region. With the
 * modal route loaded (an Astryx modal is in the tree) the route applies its
 * exposure, covered and hold rules; without it — a native modal an app
 * renders without Astryx, and no Astryx modal anywhere — the words are
 * written to the dialog while it is open as a modal, else to the shared
 * channel. Returns how to take the words back while they wait, wherever they
 * move, so a busy start overtaken by its own outcome is never heard ahead of
 * it inside a modal. Internal: used by the busy-announcement hook.
 */
export function announceInModal(
  dialog: HTMLDialogElement,
  message: string,
  politeness: AnnouncePoliteness = 'polite',
): WithdrawAnnouncement | null {
  if (modalRoute != null) {
    return modalRoute.announceInModal(dialog, message, politeness);
  }
  if (isOpenModal(dialog)) {
    return writeModalRegion(dialog, message, politeness);
  }
  return announceMessage(message, politeness);
}

/** What the route asks of the writer in the write frame. @internal */
export interface ModalWriteGuard {
  isExposed: () => boolean;
  /** Deliver the waiting words elsewhere, forwarding their receipts. */
  redirect: (waiting: ReadonlyArray<WaitingWords>) => void;
}

// The pending state of each in-dialog region: the messages written since its
// text was last exposed, the frame that exposes them, the next frame, and the
// clear timer. Assistive technology does not take text in the frame that sets
// it. So a message that arrives before the next frame joins the words.
interface ModalPending {
  messages: string[];
  // One receipt for each announcer of a message. When one announcer withdraws
  // its share, the message stays for the others. The map is new after each
  // exposure, so a receipt never reaches equal words written later.
  receipts: Map<string, AnnounceReceipt[]>;
  frame: number | null;
  settleFrame: number | null;
  timer: ReturnType<typeof setTimeout> | null;
}

const pendingByRegion = new WeakMap<HTMLElement, ModalPending>();

function cancelPending(pending: ModalPending): void {
  if (pending.frame != null) {
    cancelAnimationFrame(pending.frame);
  }
  if (pending.settleFrame != null) {
    cancelAnimationFrame(pending.settleFrame);
  }
  if (pending.timer != null) {
    clearTimeout(pending.timer);
  }
}

/** Words written to `target` that assistive technology has not had yet. */
export function unexposedMessages(target: HTMLElement): string[] {
  return unexposedWords(target).map(words => words.text);
}

function waitingIn(pending: ModalPending): WaitingWords[] {
  return pending.messages.map(text => ({
    text,
    receipts: pending.receipts.get(text) ?? [],
  }));
}

/**
 * The words written to `target` that assistive technology has not had yet,
 * with their announcers' receipts, for a hand-off that forwards them.
 */
export function unexposedWords(target: HTMLElement): WaitingWords[] {
  const pending = pendingByRegion.get(target);
  if (pending == null) {
    return [];
  }
  return pending.frame != null || pending.settleFrame != null
    ? waitingIn(pending)
    : [];
}

export function modalRegion(
  dialog: HTMLDialogElement,
  politeness: AnnouncePoliteness,
): HTMLElement | null {
  return dialog.querySelector<HTMLElement>(
    `:scope > [${MODAL_REGION_ATTR}="${politeness}"]`,
  );
}

/**
 * The dialog's own live region for one urgency, created empty on first use
 * and kept as a direct child of the dialog so it survives the dialog's
 * content re-rendering.
 */
function ensureModalRegion(
  dialog: HTMLDialogElement,
  politeness: AnnouncePoliteness,
): HTMLElement {
  let region = modalRegion(dialog, politeness);
  if (region == null) {
    region = document.createElement('div');
    region.setAttribute(MODAL_REGION_ATTR, politeness);
    region.setAttribute(
      'role',
      politeness === 'assertive' ? 'alert' : 'status',
    );
    region.setAttribute('aria-live', politeness);
    region.setAttribute('aria-atomic', 'true');
    region.style.cssText = VISUALLY_HIDDEN_CSS;
    dialog.appendChild(region);
  }
  return region;
}

/**
 * Write `message` to the modal `dialog`'s own live region for `politeness`,
 * joining it to messages written there that are not yet exposed and saying
 * an identical repeat once. The region-writing core, shared by the full
 * modal route and by the busy-announcement hook's fallback for a native
 * modal an app renders without Astryx. `guard`, supplied by the route,
 * re-checks exposure in the write frame and redirects the waiting words when
 * the dialog stopped being exposed meanwhile. Returns this announcer's
 * handle: it takes back only its own share, only while the words wait, and
 * follows them when the route moves them.
 */
export function writeModalRegion(
  dialog: HTMLDialogElement,
  message: string,
  politeness: AnnouncePoliteness,
  guard?: ModalWriteGuard,
): WithdrawAnnouncement {
  const target = ensureModalRegion(dialog, politeness);
  const unexposed = unexposedMessages(target);
  const messages = unexposed.includes(message)
    ? unexposed
    : [...unexposed, message];
  const previous = pendingByRegion.get(target);
  const receipts =
    unexposed.length > 0 && previous != null
      ? previous.receipts
      : new Map<string, AnnounceReceipt[]>();
  const receipt: AnnounceReceipt = {withdraw: null};
  receipts.set(message, [...(receipts.get(message) ?? []), receipt]);
  if (previous != null) {
    cancelPending(previous);
  }
  // Clear first, so the change is seen when the new text equals the old
  // text. Some assistive technology ignores identical content.
  target.textContent = '';
  const pending: ModalPending = {
    messages,
    receipts,
    frame: null,
    settleFrame: null,
    timer: null,
  };
  pending.frame = requestAnimationFrame(() => {
    pending.frame = null;
    if (guard != null && !guard.isExposed()) {
      // The region stopped being exposed after the call. Send the words and
      // their receipts to where they will be heard.
      pendingByRegion.delete(target);
      guard.redirect(waitingIn(pending));
      return;
    }
    target.textContent = pending.messages.join(' ');
    pending.settleFrame = requestAnimationFrame(() => {
      pending.settleFrame = null;
    });
    pending.timer = setTimeout(() => {
      target.textContent = '';
      pendingByRegion.delete(target);
    }, CLEAR_DELAY_MS);
  });
  pendingByRegion.set(target, pending);
  receipt.withdraw = () => withdrawFromRegion(target, message, receipt);
  return handleOf(receipt);
}

/**
 * Withdraw one announcer's share of `message` from `target` while it is not
 * yet exposed. Then a busy start overtaken by its outcome is never heard, and
 * a `hasReplace` instance's next message replaces its previous one. The
 * message stays while another announcer holds it. A receipt that is not among
 * the waiting words takes back nothing.
 */
function withdrawFromRegion(
  target: HTMLElement,
  message: string,
  receipt: AnnounceReceipt,
): void {
  const pending = pendingByRegion.get(target);
  if (
    pending == null ||
    (pending.frame == null && pending.settleFrame == null)
  ) {
    return;
  }
  const receipts = pending.receipts.get(message);
  const at = receipts?.indexOf(receipt) ?? -1;
  if (receipts == null || at < 0) {
    return;
  }
  receipts.splice(at, 1);
  if (receipts.length > 0) {
    return;
  }
  pending.receipts.delete(message);
  pending.messages = pending.messages.filter(text => text !== message);
  if (pending.messages.length === 0) {
    cancelPending(pending);
    pendingByRegion.delete(target);
    target.textContent = '';
  } else if (pending.frame == null) {
    // Already written this frame, not yet taken: show the rest.
    target.textContent = pending.messages.join(' ');
  }
}

/**
 * Withdraw whatever the dialog's region for `politeness` holds or is about to
 * hold, as an empty message does on the shared channel. A dialog that never
 * announced has no region and nothing to clear.
 */
export function clearModalRegion(
  dialog: HTMLDialogElement,
  politeness: AnnouncePoliteness,
): void {
  const region = modalRegion(dialog, politeness);
  if (region == null) {
    return;
  }
  const pending = pendingByRegion.get(region);
  if (pending != null) {
    cancelPending(pending);
    pendingByRegion.delete(region);
  }
  region.textContent = '';
}

/**
 * Takes the pending message the latest announce joined, so that announcer can
 * withdraw its own share of it later. Shared with useBusyAnnouncement; not
 * exported from the hooks index.
 *
 * @internal
 */
export function takeJoinedAnnouncement(): object | null {
  const joined = lastJoined;
  lastJoined = null;
  return joined;
}

// A busy start overtaken by its own outcome is never spoken (AST-086 FR8).
/**
 * Withdraws one announcer's share of a message still waiting to be exposed, so
 * a busy start overtaken by its own outcome is never spoken.
 * The message stays while another announcer still holds it.
 *
 * @internal
 */
export function withdrawPendingAnnouncement(
  joined: object,
  politeness: AnnouncePoliteness,
): void {
  const pending = pendingMessages[politeness];
  const index = pending.indexOf(joined as PendingMessage);
  if (index < 0) {
    return;
  }
  pending[index].holders -= 1;
  if (pending[index].holders <= 0) {
    pending.splice(index, 1);
  }
}

/**
 * Test-only helper: removes the singleton live regions and resets state so
 * each test starts clean. Not part of the public runtime API.
 *
 * @internal
 */
export function __resetLiveRegionsForTest(): void {
  cancelPendingFrames('polite');
  cancelPendingFrames('assertive');
  cancelScheduledClear('polite');
  cancelScheduledClear('assertive');
  lastJoined = null;
  if (regions) {
    regions.polite.remove();
    regions.assertive.remove();
    regions = null;
  }
}