sailfork / t3code-github / apps/ web/ src/ lib/ announce.ts

// Screen readers skip a live region that appears already filled, and moving focus cuts off
// whatever they were saying. So the regions exist before the first message lands, and
// messages wait until focus has stayed put for a moment, then are spoken together.
const FOCUS_SETTLE_MS = 250;

let regions: readonly [HTMLElement, HTMLElement] | null = null;
let pending: { message: string; source: string | undefined }[] = [];
let flushTimer: ReturnType<typeof setTimeout> | undefined;

function scheduleFlush() {
  clearTimeout(flushTimer);
  flushTimer = setTimeout(flush, FOCUS_SETTLE_MS);
}

function flush() {
  if (!regions || pending.length === 0) return;
  const [first, second] = regions;
  // Alternating between two regions lets the same message be spoken twice in a row.
  const target = first.textContent ? second : first;
  first.textContent = "";
  second.textContent = "";
  target.textContent = pending.map((entry) => entry.message).join(". ");
  pending = [];
}

function createRegion() {
  const region = document.createElement("div");
  region.className = "sr-only";
  region.setAttribute("aria-live", "polite");
  region.setAttribute("aria-atomic", "true");
  document.body.append(region);
  return region;
}

/**
 * Tells screen reader users what an action did when focus alone doesn't show it. A message
 * replaces one still waiting from the same `source`, so a superseded status isn't read out.
 */
export function announce(message: string, source?: string) {
  // Stores announce without a mounted owner, so they also run where no DOM exists (unit tests).
  if (typeof document === "undefined") return;
  if (!regions) {
    regions = [createRegion(), createRegion()];
    document.addEventListener("focusin", () => {
      if (pending.length > 0) scheduleFlush();
    });
  }
  if (source !== undefined) pending = pending.filter((entry) => entry.source !== source);
  if (pending.at(-1)?.message !== message) pending.push({ message, source });
  scheduleFlush();
}

/** Drops a message from `source` that hasn't been spoken yet, once it no longer applies. */
export function cancelAnnouncement(source: string) {
  pending = pending.filter((entry) => entry.source !== source);
}