Route Announcer

1import { LiveRegion } from "@ngrok/mantle/live-region";2import { useEffect, useRef, useState } from "react";3import { useLocation } from "react-router";4 5/**6 * Announces completed client-side navigations to assistive technology.7 *8 * React Router swaps the route without a document load, so screen readers9 * hear nothing. This component publishes "Navigated to {page}" to a10 * persistent polite `LiveRegion` after each pathname change. The prefix marks11 * the message as a navigation, so it does not read as unrelated status text.12 *13 * The announcement prefers the page `<h1>` over `document.title` because14 * routes without a `meta` export keep the previous document title. The15 * pathname is the last resort.16 *17 * Deliberate non-behaviors:18 * - The initial document load stays silent; assistive technology reads the19 *   document title itself.20 * - Search-param and hash changes stay silent; they are in-page state.21 * - Focus never moves; a focus move announces on its own, and the two22 *   announcements would race.23 *24 * Render it once, inside the router context in the root layout.25 *26 * @example27 * ```tsx28 * <RouteAnnouncer />29 * <ScrollRestoration />30 * <Scripts />31 * ```32 */33function RouteAnnouncer() {⋯34	const { pathname } = useLocation();35	const [announcement, setAnnouncement] = useState("");36	const previousPathname = useRef(pathname);37 38	useEffect(() => {⋯39		if (previousPathname.current === pathname) {⋯40			return;41		}42		previousPathname.current = pathname;43 44		const pageHeading = document.querySelector("h1")?.textContent?.trim();45		const pageName = pageHeading || document.title || pathname;46		const message = `Navigated to ${pageName}`;47 48		// Clear first, then publish on the next frame. Consecutive pages can49		// resolve to the same text, and a live region only announces a DOM change.50		setAnnouncement("");51		const frame = requestAnimationFrame(() => {⋯52			setAnnouncement(message);53		});54		return () => {⋯55			cancelAnimationFrame(frame);56		};57	}, [pathname]);58 59	return <LiveRegion>{announcement}</LiveRegion>;60}61 62export {63	//,64	RouteAnnouncer,65};

1<body>⋯2	<AppShell>{children}</AppShell>3	<RouteAnnouncer />4	<ScrollRestoration />5	<Scripts />6</body>

1// @vitest-environment happy-dom2import { act, cleanup, render, screen } from "@testing-library/react";3import { renderToString } from "react-dom/server";4import { createMemoryRouter, MemoryRouter, Outlet, RouterProvider } from "react-router";5import { afterEach, beforeEach, describe, expect, test } from "vitest";6import { RouteAnnouncer } from "./route-announcer";7 8afterEach(() => {⋯9	cleanup();10});11 12/**13 * Renders the announcer in a persistent layout route, the way the app root14 * hosts it, with leaf routes that cover the heading/no-heading branches.15 */16function renderWithRouter(initialPath = "/") {⋯17	const router = createMemoryRouter(18		[⋯19			{⋯20				element: (21					<>⋯22						<RouteAnnouncer />23						<button type="button">persistent control</button>24						<Outlet />25					</>26				),27				children: [⋯28					{ path: "/", element: <h1>Home</h1> },29					{ path: "/components", element: <h1>Components</h1> },30					{ path: "/no-heading", element: <p>A page without a heading</p> },31					{ path: "/components/feedback/alert", element: <h1>Alert</h1> },32					{ path: "/components/feedback/toast", element: <h1>Alert</h1> },33				],34			},35		],36		{ initialEntries: [initialPath] },37	);38	render(<RouterProvider router={router} />);39	return router;40}41 42/** Runs the announcer's next-frame publish, which follows the clearing write. */43async function flushAnnouncement() {⋯44	await act(async () => {⋯45		await new Promise<void>((resolve) => {⋯46			requestAnimationFrame(() => {⋯47				resolve();48			});49		});50	});51}52 53describe("RouteAnnouncer", () => {⋯54	beforeEach(() => {⋯55		document.title = "";56	});57 58	test("server-renders an empty polite live region", () => {⋯59		const html = renderToString(60			<MemoryRouter>⋯61				<RouteAnnouncer />62			</MemoryRouter>,63		);64 65		const region = new DOMParser()66			.parseFromString(html, "text/html")67			.querySelector('[role="status"]');68		expect(region).not.toBeNull();69		expect(region?.textContent).toBe("");70	});71 72	test("does not announce the initial page load", async () => {⋯73		renderWithRouter();74 75		await flushAnnouncement();76 77		expect(screen.getByRole("status").textContent).toBe("");78	});79 80	test("announces the page heading over a stale document title", async () => {⋯81		const router = renderWithRouter();82		document.title = "Stale title from the previous page";83 84		await act(() => router.navigate("/components"));85		await flushAnnouncement();86 87		expect(screen.getByRole("status").textContent).toBe("Navigated to Components");88	});89 90	test("falls back to the document title when the page has no heading", async () => {⋯91		const router = renderWithRouter();92		document.title = "Kbd — @ngrok/mantle";93 94		await act(() => router.navigate("/no-heading"));95		await flushAnnouncement();96 97		expect(screen.getByRole("status").textContent).toBe("Navigated to Kbd — @ngrok/mantle");98	});99 100	test("falls back to the pathname when there is no heading and no title", async () => {⋯101		const router = renderWithRouter();102 103		await act(() => router.navigate("/no-heading"));104		await flushAnnouncement();105 106		expect(screen.getByRole("status").textContent).toBe("Navigated to /no-heading");107	});108 109	test("stays silent when only the search params or hash change", async () => {⋯110		const router = renderWithRouter();111 112		await act(() => router.navigate("/?tab=examples#api-reference"));113		await flushAnnouncement();114 115		expect(screen.getByRole("status").textContent).toBe("");116	});117 118	test("announces again when the user returns to a previous page", async () => {⋯119		const router = renderWithRouter();120 121		await act(() => router.navigate("/components"));122		await flushAnnouncement();123		await act(() => router.navigate("/"));124		await flushAnnouncement();125 126		expect(screen.getByRole("status").textContent).toBe("Navigated to Home");127	});128 129	test("mutates the region even when two pages share the same heading", async () => {⋯130		const router = renderWithRouter();131 132		await act(() => router.navigate("/components/feedback/alert"));133		await flushAnnouncement();134		const region = screen.getByRole("status");135		expect(region.textContent).toBe("Navigated to Alert");136 137		// A live region only announces a DOM change. The clear-then-publish138		// sequence must mutate the region even when the text is identical.139		const mutations: MutationRecord[] = [];140		const observer = new MutationObserver((records) => {⋯141			mutations.push(...records);142		});143		observer.observe(region, { characterData: true, childList: true, subtree: true });144 145		await act(() => router.navigate("/components/feedback/toast"));146		await flushAnnouncement();147		mutations.push(...observer.takeRecords());148		observer.disconnect();149 150		expect(region.textContent).toBe("Navigated to Alert");151		expect(mutations.length).toBeGreaterThan(0);152	});153 154	test("does not move focus when it announces", async () => {⋯155		const router = renderWithRouter();156		const control = screen.getByRole("button", { name: "persistent control" });157		control.focus();158 159		await act(() => router.navigate("/components"));160		await flushAnnouncement();161 162		expect(document.activeElement).toBe(control);163	});164});