/** * vapor-chamber/router - tell assistive technology that the page changed. * * A full page load does two things a client-side navigation does not: a screen * reader announces the new page, and focus starts again from the top. Without * them a keyboard or screen-reader user is left on the link they pressed (or on * , when the old page took that link with it) and is told nothing. * * Two sources set the rules (tests/router/announce.test.ts pins each): * - Next.js announces every client-side navigation in an assertive live * region, reading `document.title`, then the first `

`, then the path. * - Gatsby's user testing with disabled users (Marcy Sutton, Fable Tech Labs, * 2019): focus on a SMALL element (a heading, a skip link) served best; on a * large wrapper it broke magnification, and a live region alone did not * help magnification users. * So announcing is on by default (it is invisible and only adds), and moving * focus is an option naming an element THE APP provides, since it changes what * a sighted keyboard user sees. * * Not announced: the initial load (the browser already read the page; the * router installs this once that navigation has settled), and a query-only * change (sorting or paging is not a new page). Read one frame after the * commit, so the new view and any title it sets are in place. */ import { announce as speak } from '../a11y'; import type { AfterEachHook, RouteLocation } from './types'; export type AnnounceOption = boolean | ((to: RouteLocation) => string | null | undefined); export type RouteAnnouncerOptions = { announce?: AnnounceOption; /** CSS selector of the element to focus after each client-side navigation. */ focusOnNavigate?: string; }; function pageName(to: RouteLocation): string { const title = document.title.trim(); if (title) return title; const h1 = document.querySelector('h1')?.textContent?.trim(); return h1 || to.path; } /** * Install on a router's `afterEach`. Returns the teardown. The live region is * the document's shared one (src/a11y.ts), not the router's, so it outlives the * router. A no-op outside a browser. */ export function installRouteAnnouncer( afterEach: (hook: AfterEachHook) => () => void, options: RouteAnnouncerOptions, ): () => void { const { announce = true, focusOnNavigate } = options; if (typeof document === 'undefined' || (announce === false && !focusOnNavigate)) return () => {}; let frame = 0; // A query-only change never reaches here: the engine's afterEach fires only // after a committed PATH navigation (engine.ts), so paging or sorting is // not announced without a check of this module's own. const off = afterEach((to) => { cancelAnimationFrame(frame); frame = requestAnimationFrame(() => { if (announce !== false) { const text = typeof announce === 'function' ? announce(to) : pageName(to); if (text) speak(text, { assertive: true }); } if (focusOnNavigate) { const target = document.querySelector(focusOnNavigate); if (target) { // The platform knows what is focusable: anything that is not reports // tabIndex -1 with no attribute (a heading); links, buttons, summary // report 0. Editable content is the exception: Chromium reports it -1 // though it is in the tab order, so `isContentEditable` is read too // (tests/browser/route-announce.browser.test.ts). No hand-kept list. if (target.tabIndex < 0 && !target.hasAttribute('tabindex') && !target.isContentEditable) target.setAttribute('tabindex', '-1'); target.focus({ preventScroll: true }); } } }); }); return () => { off(); cancelAnimationFrame(frame); }; }