Announce route changes for screen readers (#3332)

Similar deal to oxidecomputer/rfd-site#258

## 🤖 summary

A client-side nav doesn't tell a screen reader anything: React Router
swaps the DOM in place and focus stays on the link that was clicked,
which usually isn't in the document anymore. Next.js ships a route
announcer for this; RR leaves it to the app.

`useRouteAnnouncer` in `RootLayout` announces the crumbs deepest-first
("Instances, mock-project, Projects") through the react-aria live
announcer we already use for toasts and field errors. Polite rather than
assertive so it doesn't preempt the toast on flows that toast and then
navigate. It also puts focus on the existing skip link target, but only
when focus has fallen to `<body>` — if you clicked a sidebar link that's
still sitting there, leave it alone. Use `preventScroll` to avoid
conflicts with `useScrollRestoration` on back/forward.

Side modal forms get their own routes, so the announcer has to know that
a form opening on top of a page isn't a page change. It keys off
`titleOnly` crumbs, which already mark exactly those routes (had to fix
`ip-pool-edit` and `subnet-pool-edit`, which were using `makeCrumb`).
Detecting the open dialog in the DOM instead seemed simpler, but it ran
into races.

Author: david-crespo

app/forms/ip-pool-edit.tsx

@@ -16,7 +16,7 @@ import { NameField } from '~/components/form/fields/NameField'
 import { FormMetadata } from '~/components/form/FormMetadata'
 import { SideModalForm } from '~/components/form/SideModalForm'
 import { HL } from '~/components/HL'
-import { makeCrumb } from '~/hooks/use-crumbs'
+import { titleCrumb } from '~/hooks/use-crumbs'
 import { getIpPoolSelector, useIpPoolSelector } from '~/hooks/use-params'
 import { addToast } from '~/stores/toast'
 import { SideModalFormDocs } from '~/ui/lib/ModalLinks'
@@ -34,7 +34,7 @@ export async function clientLoader({ params }: LoaderFunctionArgs) {
   return null
 }
 
-export const handle = makeCrumb('Edit IP pool')
+export const handle = titleCrumb('Edit IP pool')
 
 export default function EditIpPoolSideModalForm() {
   const navigate = useNavigate()

app/forms/subnet-pool-edit.tsx

@@ -16,7 +16,7 @@ import { NameField } from '~/components/form/fields/NameField'
 import { FormMetadata } from '~/components/form/FormMetadata'
 import { SideModalForm } from '~/components/form/SideModalForm'
 import { HL } from '~/components/HL'
-import { makeCrumb } from '~/hooks/use-crumbs'
+import { titleCrumb } from '~/hooks/use-crumbs'
 import { getSubnetPoolSelector, useSubnetPoolSelector } from '~/hooks/use-params'
 import { addToast } from '~/stores/toast'
 import { SideModalFormDocs } from '~/ui/lib/ModalLinks'
@@ -35,7 +35,7 @@ export async function clientLoader({ params }: LoaderFunctionArgs) {
   return null
 }
 
-export const handle = makeCrumb('Edit subnet pool')
+export const handle = titleCrumb('Edit subnet pool')
 
 export default function EditSubnetPoolSideModalForm() {
   const navigate = useNavigate()

app/hooks/use-crumbs.ts

@@ -69,3 +69,14 @@ export const matchesToCrumbs = (matches: UIMatch[]) =>
     })
 
 export const useCrumbs = () => matchesToCrumbs(useMatches())
+
+/**
+ * Whether the current route is a side modal (form or detail panel) opening on
+ * top of a page. Keys off the `titleOnly` crumb flag because it exists for the
+ * same reason: the page underneath doesn't change.
+ *
+ * Not the same as `useIsInSideModal`, which asks whether the calling component
+ * is rendered inside a `SideModal`. That one is false on the page underneath;
+ * this one is true.
+ */
+export const useIsSideModalRoute = () => useCrumbs().some((c) => c.titleOnly)

app/hooks/use-route-announcer.ts

@@ -0,0 +1,89 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, you can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright Oxide Computer Company
+ */
+import { announce } from '@react-aria/live-announcer'
+import { useEffect, useRef } from 'react'
+import { useLocation } from 'react-router'
+
+import { useCrumbs, useIsSideModalRoute } from './use-crumbs'
+
+/**
+ * A real page load tells a screen reader where it landed: the new page gets
+ * announced and the reading position goes back to the top. A client-side nav
+ * does neither — React Router swaps the DOM in place and focus stays on the
+ * link that was clicked, which often doesn't exist anymore. Next.js ships a
+ * route announcer for this; React Router leaves it to the app.
+ *
+ * So on every page change we do it ourselves: announce the new page in a live
+ * region, and move focus to the top of the content, which is where the skip
+ * link points too.
+ */
+export function useRouteAnnouncer() {
+  const { pathname } = useLocation()
+  const crumbs = useCrumbs()
+
+  // deepest crumb first, like the document title, so the specific page comes
+  // before its containers: "Instances, mock-project, Projects"
+  const pageName = crumbs
+    .map((c) => c.label)
+    .reverse()
+    .join(', ')
+
+  const isSideModal = useIsSideModalRoute()
+
+  // initialized with the current path so we don't announce the page we loaded
+  // on — the browser already did that
+  const lastAnnounced = useRef(pathname)
+
+  useEffect(() => {
+    // A side modal is open, so we're still on the page underneath and there's
+    // nothing to announce. The dialog announces its own title and manages its
+    // own focus, so stay out of its way. Leaving the ref alone also makes
+    // dismissing it — a nav back to that same page — a no-op.
+    if (isSideModal) return
+
+    if (pathname === lastAnnounced.current) return
+    lastAnnounced.current = pathname
+
+    // polite rather than assertive so we don't cut off a toast announcing the
+    // result of the action that navigated us here
+    announce(pageName || 'Oxide Console', 'polite')
+
+    // Move focus to the top of the new page, like a real page load would.
+    // Leaving it where it was is unreliable anyway: Safari doesn't focus links
+    // on click, so after a sidebar click, focus is on the link in Firefox but
+    // on the body in Safari. The exception is tabs — the ARIA tabs pattern
+    // keeps focus on the tab after activating it, even when (as with VPC tabs)
+    // the tab is a route.
+    //
+    // Prefer the page's h1 over <main> itself. VoiceOver reads a focused
+    // heading's text, whereas focusing a big landmark container just gets
+    // "main" with no content. The h1 also remounts on every page change, while
+    // <main> persists across navs — refocusing an already-focused element is a
+    // no-op that fires no event, so the VO cursor would never move after the
+    // first nav. Focusing the destination page's heading is the standard
+    // recommendation for SPA route changes:
+    // https://www.deque.com/blog/single-page-apps-focus-management/
+    // https://www.gatsbyjs.com/blog/2019-07-11-user-testing-accessible-client-routing/
+    //
+    // preventScroll because scroll position is useScrollRestoration's job:
+    // without it, focusing the top of the page would clobber the restored
+    // position on back/forward nav.
+    if (document.activeElement?.getAttribute('role') !== 'tab') {
+      const main = document.getElementById('content')
+      const heading = main?.querySelector('h1')
+      if (heading) {
+        heading.tabIndex = -1 // headings aren't focusable by default
+        // Safari (unlike Chrome/FF) matches :focus-visible on programmatic
+        // focus even when the nav came from a click. The heading isn't
+        // interactive, so never show a ring.
+        heading.classList.add('outline-none')
+      }
+      ;(heading || main)?.focus({ preventScroll: true })
+    }
+  }, [pathname, pageName, isSideModal])
+}

app/layouts/RootLayout.tsx

@@ -10,6 +10,7 @@ import { Outlet, useNavigation } from 'react-router'
 
 import { ToastStack } from '~/components/ToastStack'
 import { useCrumbs } from '~/hooks/use-crumbs'
+import { useRouteAnnouncer } from '~/hooks/use-route-announcer'
 import { useApplyTheme } from '~/stores/theme'
 
 /**
@@ -29,6 +30,7 @@ const useTitle = () =>
  */
 export default function RootLayout() {
   useApplyTheme()
+  useRouteAnnouncer()
   const title = useTitle()
   useEffect(() => {
     document.title = title

app/layouts/helpers.tsx

@@ -10,7 +10,6 @@ import { Outlet } from 'react-router'
 import { PageActionsTarget } from '~/components/PageActions'
 import { Pagination } from '~/components/Pagination'
 import { useScrollRestoration } from '~/hooks/use-scroll-restoration'
-import { SkipLinkTarget } from '~/ui/lib/SkipLink'
 import { classed } from '~/util/classed'
 
 export const PageContainer = classed.div`min-h-full pt-[calc(var(--top-bar-height)+var(--preview-banner-height))]`
@@ -26,8 +25,10 @@ export function ContentPane() {
   return (
     <div className="light:bg-raise ml-(--sidebar-width) flex min-h-[calc(100vh-var(--top-bar-height)-var(--preview-banner-height))] flex-col">
       <div className="flex grow flex-col pb-8">
-        <SkipLinkTarget />
-        <main className="*:gutter">
+        {/* id/tabIndex make this the skip link target and where useRouteAnnouncer
+            puts focus after a nav. It has to be a real element in the a11y tree
+            (not an empty div) or the VoiceOver cursor won't follow the focus. */}
+        <main id="content" tabIndex={-1} className="*:gutter outline-none">
           <Outlet />
         </main>
       </div>
@@ -47,8 +48,7 @@ export function ContentPane() {
  */
 export const SerialConsoleContentPane = () => (
   <div className="ml-(--sidebar-width) flex h-[calc(100vh-var(--top-bar-height)-var(--preview-banner-height))] flex-col overflow-hidden">
-    <SkipLinkTarget />
-    <main className="*:gutter h-full">
+    <main id="content" tabIndex={-1} className="*:gutter h-full outline-none">
       <Outlet />
     </main>
   </div>

app/ui/lib/SkipLink.tsx

@@ -34,7 +34,3 @@ export const SkipLink = ({
     </a>
   )
 }
-
-export const SkipLinkTarget = ({ id = 'content' }) => {
-  return <div id={id} className="h-0" />
-}

app/ui/lib/modal-context.ts

@@ -12,4 +12,8 @@ export const ModalContext = createContext(false)
 export const useIsInModal = () => useContext(ModalContext)
 
 export const SideModalContext = createContext(false)
+/**
+ * Whether the calling component is rendered inside a `SideModal`. For "is a
+ * side modal open on top of the current page", see `useIsSideModalRoute`.
+ */
 export const useIsInSideModal = () => useContext(SideModalContext)

app/util/__snapshots__/path-builder.spec.ts.snap

@@ -442,10 +442,6 @@ exports[`breadcrumbs 2`] = `
       "label": "pl",
       "path": "/system/networking/ip-pools/pl",
     },
-    {
-      "label": "Edit IP pool",
-      "path": "/system/networking/ip-pools/pl/edit",
-    },
   ],
   "ipPoolRangeAdd (/system/networking/ip-pools/pl/ranges-add)": [
     {
@@ -870,10 +866,6 @@ exports[`breadcrumbs 2`] = `
       "label": "sp",
       "path": "/system/networking/subnet-pools/sp",
     },
-    {
-      "label": "Edit subnet pool",
-      "path": "/system/networking/subnet-pools/sp/edit",
-    },
   ],
   "subnetPoolMemberAdd (/system/networking/subnet-pools/sp/members-add)": [
     {

test/e2e/route-announcer.e2e.ts

@@ -0,0 +1,82 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, you can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * Copyright Oxide Computer Company
+ */
+import { expect, test, type Page } from '@playwright/test'
+
+// react-aria appends each announcement as a child of a hidden polite live
+// region shared with toasts. CSS locator because there's a second region for
+// assertive announcements and we only want the messages from this one.
+const announcements = (page: Page) =>
+  page.locator('[data-live-announcer] [aria-live="polite"] > div')
+
+test('route announcer', async ({ page }) => {
+  await page.goto('/projects')
+  await page.getByRole('heading', { name: 'Projects' }).waitFor()
+
+  // nothing on first load — the browser already announced the page
+  await expect(announcements(page)).toHaveCount(0)
+
+  // nav by a link inside the content, which unmounts along with the page
+  await page.getByRole('link', { name: 'mock-project' }).click()
+  await expect(announcements(page)).toHaveText(['Instances, mock-project, Projects'])
+  // focus goes to the new page's heading, like (better than) a real page load
+  await expect(page.getByRole('heading', { name: 'Instances' })).toBeFocused()
+
+  // nav by a sidebar link: the link survives the nav, but focus still moves to
+  // the top of the new page
+  const disksLink = page
+    .getByRole('navigation', { name: 'Sidebar navigation' })
+    .getByRole('link', { name: 'Disks' })
+  await disksLink.click()
+  await expect(announcements(page)).toHaveText([
+    'Instances, mock-project, Projects',
+    'Disks, mock-project, Projects',
+  ])
+  await expect(page.getByRole('heading', { name: 'Disks' })).toBeFocused()
+
+  // a side modal form is its own route, but it opens on top of the page rather
+  // than replacing it, so it doesn't announce or take focus from the dialog
+  await page.getByRole('link', { name: 'New Disk' }).click()
+  await expect(page.getByRole('dialog', { name: 'Create disk' })).toBeVisible()
+  await expect(announcements(page)).toHaveCount(2)
+
+  // ...and neither does dismissing it
+  await page.getByRole('button', { name: 'Cancel' }).click()
+  await expect(page.getByRole('dialog', { name: 'Create disk' })).toBeHidden()
+  await expect(announcements(page)).toHaveCount(2)
+})
+
+// tabs that live in the query param rather than the path aren't navigations as
+// far as the router is concerned, so there's nothing to announce
+test('route announcer ignores query param tabs', async ({ page }) => {
+  await page.goto('/system/utilization')
+  await page.getByRole('tab', { name: 'Metrics' }).click()
+  await expect(page).toHaveURL(/tab=metrics/)
+  await expect(announcements(page)).toHaveCount(0)
+})
+
+// VPC tabs, on the other hand, are real routes. Routes like these share a crumb
+// path with their siblings, which is why the announcer keys off the pathname.
+test('route announcer on tab routes', async ({ page }) => {
+  await page.goto('/projects/mock-project/vpcs/default/firewall-rules')
+  const tab = page.getByRole('tab', { name: 'Routers' })
+  await tab.click()
+  await expect(announcements(page)).toHaveText([
+    'Routers, default, VPCs, mock-project, Projects',
+  ])
+  // the tab is still there, so it keeps focus
+  await expect(tab).toBeFocused()
+})
+
+// the image detail side modal isn't a form, but it's still a dialog on top of
+// the list rather than a new page
+test('route announcer ignores detail side modals', async ({ page }) => {
+  await page.goto('/images')
+  await page.getByRole('link', { name: 'ubuntu-22-04' }).click()
+  await expect(page.getByRole('dialog', { name: 'Image details' })).toBeVisible()
+  await expect(announcements(page)).toHaveCount(0)
+})