Skip to content

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

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

'use client';

/**
 * @file useAnnounceRenderedText.ts
 * @input A ref to a rendered element, whether it shows, and a token for each
 *   new occasion to speak
 * @output Announces the element's rendered text through the polite live
 *   region, or through the owner's announcer
 * @position Core a11y hook. It is not in hooks/index.ts, because that barrel
 *   is public and a new public hook needs admission (AST-002). Import it by
 *   path.
 */

// Some content reaches assistive technology only through a live region. For
// example, a listbox permits only `option` and `group` children, so a panel
// message in it has `role="presentation"`. When that content is a caller's
// `ReactNode`, announce what was rendered, not a built-in default (AST-056,
// AST-086).
//
// The text comes from the DOM after render, not from React children, so text
// that a child component generates is included. A live region that mounts
// with its content is not reliably announced, so the persistent `useAnnounce`
// region speaks it. Content with `aria-hidden` or `hidden` is left out. An
// `aria-label` on a descendant is not used.

import {useEffect, useRef, useState, type RefObject} from 'react';
import {
  useAnnounce,
  type AnnounceFn,
  type AnnouncePoliteness,
} from './useAnnounce';
import {useIsHydrating} from './useIsHydrating';

const LIVE_CONTAINER =
  '[role="log"], [role="status"], [role="alert"], [aria-live="polite"], [aria-live="assertive"]';
const HIDDEN = '[aria-hidden="true"], [hidden]';
const BLOCKS = 'p, div, li, br, h1, h2, h3, h4, h5, h6';

/**
 * Each child element's rendered text as its own block, joined by spaces. Text
 * placed directly in the element, beside its child elements, counts as a block
 * too (a status bar is an icon followed by its bare message).
 */
function blockText(element: HTMLElement): string {
  return Array.from(element.childNodes)
    .map(child => {
      if (child.nodeType === Node.TEXT_NODE) {
        return (child.textContent ?? '').replace(/\s+/g, ' ').trim();
      }
      // By node type, not `instanceof`: an element from another document's
      // window (a portal into a same-origin iframe) fails this window's
      // constructor checks.
      if (child.nodeType === Node.ELEMENT_NODE) {
        const part = child as HTMLElement;
        return part.matches(HIDDEN) ? '' : renderedText(part);
      }
      return '';
    })
    .filter(part => part !== '')
    .join(' ');
}

export interface AnnounceRenderedTextOptions {
  /**
   * Text that is present or changes while the document loads or hydrates is
   * silent. Text that appears or changes later is announced once. A mounted
   * live container speaks its own content, and each child is a block. A
   * reveal without a re-render is read on the next render.
   */
  skipFirstRender?: boolean;
  /**
   * The urgency: assertive for errors and time-critical failures, else
   * polite. Defaults to polite.
   */
  politeness?: AnnouncePoliteness;
  /** Accessible name to announce when the element has no rendered text. */
  fallbackText?: string;
  /**
   * The owner's announcer, when the rendered text states the next value of
   * that announcer's state. For example, a picker's empty-panel message goes
   * through its search's `hasReplace` instance, so the two replace each other
   * while not yet exposed. Defaults to this hook's own instance.
   */
  announce?: AnnounceFn;
}

/**
 * The rendered text an assistive technology would read from `element`. Block
 * boxes read apart: a block tag, an element whose computed display is not
 * inline, and any child of a flex or grid container (which the layout
 * blockifies), so two stacked `Text` spans never run together. Hidden parts
 * are skipped; nothing on screen changes.
 */
export function renderedText(element: HTMLElement): string {
  const view = element.ownerDocument.defaultView;
  const displayOf = (node: Element) =>
    view?.getComputedStyle(node).display ?? '';
  const parts: string[] = [];
  const walk = (node: Node, parentDisplay: string) => {
    if (node.nodeType === Node.TEXT_NODE) {
      parts.push(node.textContent ?? '');
      return;
    }
    if (node.nodeType !== Node.ELEMENT_NODE) {
      return;
    }
    const part = node as Element;
    if (part.matches(HIDDEN)) {
      return;
    }
    const display = displayOf(part);
    const isBlock =
      part.matches(BLOCKS) ||
      (display !== '' &&
        display !== 'contents' &&
        !display.startsWith('inline')) ||
      /\b(flex|grid)\b/.test(parentDisplay);
    if (isBlock) {
      parts.push(' ');
    }
    part.childNodes.forEach(child => walk(child, display));
    if (isBlock) {
      parts.push(' ');
    }
  };
  const ownDisplay = displayOf(element);
  element.childNodes.forEach(child => walk(child, ownDisplay));
  return parts.join('').replace(/\s+/g, ' ').trim();
}

/**
 * Announce the text of a rendered element through the shared polite live
 * region, once per occasion.
 *
 * Announces when the element appears and whenever its rendered text changes.
 * Pass `isShown: false` for every state where the element is not on screen —
 * including while loading — and the hook stays silent and re-arms.
 *
 * @param ref - The element whose rendered text to speak
 * @param isShown - Whether that element is currently on screen
 * @param occasion - Marks a new reason to speak the same words again; for a
 *   search dead end this is the query, so each new query that matches nothing
 *   is announced rather than only the first
 *
 * @example
 * ```
 * const emptyStateRef = useRef<HTMLDivElement>(null);
 * useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery);
 * ```
 */
export function useAnnounceRenderedText(
  ref: RefObject<HTMLElement | null>,
  isShown: boolean,
  occasion: string,
  {
    skipFirstRender = false,
    politeness = 'polite',
    fallbackText,
    announce: ownerAnnounce,
  }: AnnounceRenderedTextOptions = {},
): void {
  const ownAnnounce = useAnnounce();
  const announce = ownerAnnounce ?? ownAnnounce;
  const spokenRef = useRef<string | null>(null);
  const isHydrating = useIsHydrating();
  // Captured once: an owner rendered before the document finished loading, or
  // hydrated from server HTML, is part of the page the person arrived at.
  const [renderedWithPage] = useState(
    () => isHydrating || document.readyState !== 'complete',
  );
  const isFirstRunRef = useRef(true);

  // Syncs the live region with the rendered text.
  // No dependency array: the text lives in the DOM, and a caller can change it
  // without a prop that this hook sees. One text read per render is cheap, and
  // the dedupe below makes later renders no-ops.
  useEffect(() => {
    const isFirstRun = isFirstRunRef.current;
    isFirstRunRef.current = false;
    const element = ref.current;
    if (
      !isShown ||
      element?.closest(HIDDEN) ||
      element?.checkVisibility?.() === false
    ) {
      spokenRef.current = null;
      return;
    }
    if (!element) {
      return;
    }
    if (skipFirstRender && element.parentElement?.closest(LIVE_CONTAINER)) {
      return;
    }
    let text = skipFirstRender ? blockText(element) : renderedText(element);
    if (text === '' && fallbackText !== undefined) {
      text =
        (element.getAttribute('aria-labelledby') ?? '')
          .split(/\s+/)
          .map(id => {
            // Each referenced element as read: its hidden parts dropped, as
            // the accessible name drops them.
            const target = element.ownerDocument.getElementById(id);
            return target == null ? '' : renderedText(target);
          })
          .join(' ')
          .replace(/\s+/g, ' ')
          .trim() || fallbackText;
    }
    if (text === '') {
      // Nothing readable on screen either, so there is no announcement that
      // would match what the sighted user is seeing.
      return;
    }
    const spoken = `${occasion}\u0000${text}`;
    if (spokenRef.current === spoken) {
      return;
    }
    spokenRef.current = spoken;
    const isPageLoad =
      (isFirstRun && renderedWithPage) || document.readyState !== 'complete';
    if (skipFirstRender && isPageLoad) {
      // Part of the page the person arrived at: remember it, say nothing.
      return;
    }
    announce(text, politeness);
  });
}