[a11y] Route Announcements (#20428)

# Route Announcements ## Summary This PR improves the accessibility of NextJS's client-side navigation by announcing route changes to screen readers. ## Context When a user who is sighted clicks on a link, they can see the content change. It's an affirmation that what the user intended to do by clicking a link actually worked! Users navigating the page via a screen-reader will not get this feedback on NextJS sites (This is an issue on many SPA-like architectures). https://user-images.githubusercontent.com/4213649/103017382-63b02b00-44f8-11eb-9940-fb530d2d3018.mov ## Solution Whenever there is a route change, the new `<RouteAnnouncer />` will look for a name to give the new page and then announce it! The name is found by first looking for an `h1`, falling back to `document.title`, and lastly to `pathname`. `<RouteAnnouncer />` is a visually hidden component placed within the `<AppContainer />`. ## Demo https://user-images.githubusercontent.com/4213649/103017401-6ad73900-44f8-11eb-8050-b3e9a7e0c3f2.mov ## Inspiration First and foremost, this PR was inspired by @marcysutton's studies and writing, [What we learned from user testing of accessible client-side routing techniques with Fable Tech Labs ](https://www.gatsbyjs.com/blog/2019-07-11-user-testing-accessible-client-routing/) as well as @madalynrose's [Accessible Routing](gatsbyjs/gatsby#19290) PR for Gatsby. There were also learnings gleaned from the conversations within #7681. ### Related Issues & PRs - Resolves #7681 - Relates to #19963
vercel · Mar 15, 2021 · 688611a · 688611a
1 parent 4f894a3
commit 688611a
Show file tree

Hide file tree

Showing 14 changed files with 260 additions and 12 deletions.
diff --git a/packages/next/client/index.tsx b/packages/next/client/index.tsx
@@ -21,9 +21,11 @@ import {
   NEXT_DATA,
   ST,
 } from '../next-server/lib/utils'
+import { Portal } from './portal'
 import initHeadManager from './head-manager'
 import PageLoader, { StyleSheetTuple } from './page-loader'
 import measureWebVitals from './performance-relayer'
+import { RouteAnnouncer } from './route-announcer'
 import { createRouter, makePublicRouterInstance } from './router'
 
 /// <reference types="react-dom/experimental" />
@@ -784,6 +786,9 @@ function doRender(input: RenderRouteInfo): Promise<any> {
       <Head callback={onHeadCommit} />
       <AppContainer>
         <App {...appProps} />
+        <Portal type="next-route-announcer">
+          <RouteAnnouncer />
+        </Portal>
       </AppContainer>
     </Root>
   )

diff --git a/packages/next/client/link.tsx b/packages/next/client/link.tsx
@@ -103,12 +103,6 @@ function linkClicked(
     shallow,
     locale,
     scroll,
-  }).then((success: boolean) => {
-    if (!success) return
-    if (scroll) {
-      // FIXME: proper route announcing at Router level, not Link:
-      document.body.focus()
-    }
   })
 }
 

diff --git a/packages/next/client/portal/LICENSE b/packages/next/client/portal/LICENSE
@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2018-present, React Training LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/packages/next/client/portal/index.tsx b/packages/next/client/portal/index.tsx
@@ -0,0 +1,24 @@
+import * as React from 'react'
+import { createPortal } from 'react-dom'
+
+type PortalProps = {
+  children: React.ReactNode
+  type: string
+}
+
+export const Portal: React.FC<PortalProps> = ({ children, type }) => {
+  let portalNode = React.useRef<HTMLElement | null>(null)
+  let [, forceUpdate] = React.useState<{}>()
+  React.useEffect(() => {
+    portalNode.current = document.createElement(type)
+    document.body.appendChild(portalNode.current)
+    forceUpdate({})
+    return () => {
+      if (portalNode.current) {
+        document.body.removeChild(portalNode.current)
+      }
+    }
+  }, [type])
+
+  return portalNode.current ? createPortal(children, portalNode.current) : null
+}
diff --git a/packages/next/client/route-announcer.tsx b/packages/next/client/route-announcer.tsx
@@ -0,0 +1,67 @@
+import React, { useEffect, useState, useRef } from 'react'
+import { useRouter } from './router'
+
+export function RouteAnnouncer() {
+  const { asPath } = useRouter()
+  const [routeAnnouncement, setRouteAnnouncement] = useState('')
+
+  // Only announce the path change, but not for the first load because screen reader will do that automatically.
+  const initialPathLoaded = useRef(false)
+
+  // Every time the path changes, announce the route change. The announcement will be prioritized by h1, then title
+  // (from metadata), and finally if those don't exist, then the pathName that is in the URL. This methodology is
+  // inspired by Marcy Sutton's accessible client routing user testing. More information can be found here:
+  // https://www.gatsbyjs.com/blog/2019-07-11-user-testing-accessible-client-routing/
+  useEffect(
+    () => {
+      if (!initialPathLoaded.current) {
+        initialPathLoaded.current = true
+        return
+      }
+
+      let newRouteAnnouncement
+      const pageHeader = document.querySelector('h1')
+
+      if (pageHeader) {
+        newRouteAnnouncement = pageHeader.innerText || pageHeader.textContent
+      }
+      if (!newRouteAnnouncement) {
+        if (document.title) {
+          newRouteAnnouncement = document.title
+        } else {
+          newRouteAnnouncement = asPath
+        }
+      }
+
+      setRouteAnnouncement(newRouteAnnouncement)
+    },
+    // TODO: switch to pathname + query object of dynamic route requirements
+    [asPath]
+  )
+
+  return (
+    <p
+      aria-live="assertive" // Make the announcement immediately.
+      id="__next-route-announcer__"
+      role="alert"
+      style={{
+        border: 0,
+        clip: 'rect(0 0 0 0)',
+        height: '1px',
+        margin: '-1px',
+        overflow: 'hidden',
+        padding: 0,
+        position: 'absolute',
+        width: '1px',
+
+        // https://medium.com/@jessebeach/beware-smushed-off-screen-accessible-text-5952a4c2cbfe
+        whiteSpace: 'nowrap',
+        wordWrap: 'normal',
+      }}
+    >
+      {routeAnnouncement}
+    </p>
+  )
+}
+
+export default RouteAnnouncer
diff --git a/test/integration/build-output/test/index.test.js b/test/integration/build-output/test/index.test.js
@@ -94,17 +94,17 @@ describe('Build Output', () => {
       expect(parseFloat(indexSize) - 266).toBeLessThanOrEqual(0)
       expect(indexSize.endsWith('B')).toBe(true)
 
-      // should be no bigger than 63.9 kb
-      expect(parseFloat(indexFirstLoad)).toBeCloseTo(64.1, 1)
+      // should be no bigger than 64.6 kb
+      expect(parseFloat(indexFirstLoad)).toBeCloseTo(64.6, 1)
       expect(indexFirstLoad.endsWith('kB')).toBe(true)
 
       expect(parseFloat(err404Size) - 3.7).toBeLessThanOrEqual(0)
       expect(err404Size.endsWith('kB')).toBe(true)
 
-      expect(parseFloat(err404FirstLoad)).toBeCloseTo(67.1, 0)
+      expect(parseFloat(err404FirstLoad)).toBeCloseTo(67.8, 0)
       expect(err404FirstLoad.endsWith('kB')).toBe(true)
 
-      expect(parseFloat(sharedByAll)).toBeCloseTo(63.9, 1)
+      expect(parseFloat(sharedByAll)).toBeCloseTo(64.4, 1)
       expect(sharedByAll.endsWith('kB')).toBe(true)
 
       if (_appSize.endsWith('kB')) {

diff --git a/test/integration/client-navigation-a11y/next.config.js b/test/integration/client-navigation-a11y/next.config.js
@@ -0,0 +1 @@
+module.exports = {}
diff --git a/test/integration/client-navigation-a11y/pages/index.js b/test/integration/client-navigation-a11y/pages/index.js
@@ -0,0 +1,19 @@
+import Link from 'next/link'
+
+export default () => (
+  <div id="page-container">
+    <Link href="/page-with-h1">
+      <a id="page-with-h1-link">Go to a page with an h1</a>
+    </Link>
+    <Link href="/page-with-title">
+      <a id="page-with-title-link">
+        Go to a page without an h1, but with a title
+      </a>
+    </Link>
+    <Link href="/page-without-h1-or-title">
+      <a id="page-without-h1-or-title-link">
+        Go to a page without an h1 or a title
+      </a>
+    </Link>
+  </div>
+)
diff --git a/test/integration/client-navigation-a11y/pages/page-with-h1.js b/test/integration/client-navigation-a11y/pages/page-with-h1.js
@@ -0,0 +1,11 @@
+import Head from 'next/head'
+
+export default () => (
+  <div id="page-with-h1">
+    <Head>
+      <title>Another Page's Title</title>
+    </Head>
+    <h1>My heading</h1>
+    <div>Extraneous stuff</div>
+  </div>
+)
diff --git a/test/integration/client-navigation-a11y/pages/page-with-title.js b/test/integration/client-navigation-a11y/pages/page-with-title.js
@@ -0,0 +1,11 @@
+import Head from 'next/head'
+
+export default () => (
+  <div id="page-with-title">
+    <Head>
+      <title>Another Page's Title</title>
+    </Head>
+    <div>My heading</div>
+    <div>Extraneous stuff</div>
+  </div>
+)
diff --git a/test/integration/client-navigation-a11y/pages/page-without-h1-or-title.js b/test/integration/client-navigation-a11y/pages/page-without-h1-or-title.js
@@ -0,0 +1,6 @@
+export default () => (
+  <div id="page-without-h1-or-title">
+    <div>My heading</div>
+    <div>Extraneous stuff</div>
+  </div>
+)
diff --git a/test/integration/client-navigation-a11y/test/index.test.js b/test/integration/client-navigation-a11y/test/index.test.js
@@ -0,0 +1,101 @@
+/* eslint-env jest */
+
+import {
+  findPort,
+  killApp,
+  launchApp,
+  renderViaHTTP,
+} from '../../../lib/next-test-utils'
+import webdriver from 'next-webdriver'
+import { join } from 'path'
+
+const context = {}
+jest.setTimeout(1000 * 60 * 5)
+
+describe('Client Navigation accessibility', () => {
+  beforeAll(async () => {
+    context.appPort = await findPort()
+    context.server = await launchApp(join(__dirname, '../'), context.appPort, {
+      env: { __NEXT_TEST_WITH_DEVTOOL: 1 },
+    })
+
+    const prerender = [
+      '/page-with-h1, /page-with-title, /page-without-h1-or-title',
+    ]
+
+    await Promise.all(
+      prerender.map((route) => renderViaHTTP(context.appPort, route))
+    )
+  })
+
+  afterAll(() => killApp(context.server))
+
+  describe('<RouteAnnouncer />', () => {
+    it('has aria-live="assertive" and role="alert"', async () => {
+      const browser = await webdriver(context.appPort, '/')
+      const routeAnnouncer = await browser.waitForElementByCss(
+        '#__next-route-announcer__'
+      )
+      const ariaLiveValue = await routeAnnouncer.getAttribute('aria-live')
+      const roleValue = await routeAnnouncer.getAttribute('role')
+
+      expect(ariaLiveValue).toBe('assertive')
+      expect(roleValue).toBe('alert')
+      await browser.close()
+    })
+    describe('There is an h1 tag', () => {
+      it('has the same innerText value as the h1 tag', async () => {
+        const browser = await webdriver(context.appPort, '/')
+        const h1Value = await browser
+          .waitForElementByCss('#page-with-h1-link')
+          .click()
+          .waitForElementByCss('#page-with-h1')
+          .elementByCss('h1')
+          .text()
+
+        const routeAnnouncerValue = await browser
+          .waitForElementByCss('#__next-route-announcer__')
+          .text()
+
+        expect(h1Value).toBe(routeAnnouncerValue)
+        await browser.close()
+      })
+    })
+    describe('There is a document.title, but no h1 tag', () => {
+      it('has the innerText equal to the value of document.title', async () => {
+        const browser = await webdriver(context.appPort, '/')
+        await browser
+          .waitForElementByCss('#page-with-title-link')
+          .click()
+          .waitForElementByCss('#page-with-title')
+
+        const title = await browser.eval('document.title')
+
+        const routeAnnouncerValue = await browser
+          .waitForElementByCss('#__next-route-announcer__')
+          .text()
+
+        expect(title).toBe(routeAnnouncerValue)
+        await browser.close()
+      })
+    })
+    describe('There is neither an h1 or a title tag', () => {
+      it('has the innerText equal to the value of the pathname', async () => {
+        const browser = await webdriver(context.appPort, '/')
+        await browser
+          .waitForElementByCss('#page-without-h1-or-title-link')
+          .click()
+          .waitForElementByCss('#page-without-h1-or-title')
+
+        const pathname = '/page-without-h1-or-title'
+
+        const routeAnnouncerValue = await browser
+          .waitForElementByCss('#__next-route-announcer__')
+          .text()
+
+        expect(pathname).toBe(routeAnnouncerValue)
+        await browser.close()
+      })
+    })
+  })
+})
diff --git a/test/integration/fallback-modules/test/index.test.js b/test/integration/fallback-modules/test/index.test.js
@@ -44,7 +44,7 @@ describe('Build Output', () => {
       expect(parseFloat(indexSize)).toBeGreaterThanOrEqual(2)
       expect(indexSize.endsWith('kB')).toBe(true)
 
-      expect(parseFloat(indexFirstLoad)).toBeLessThanOrEqual(67.5)
+      expect(parseFloat(indexFirstLoad)).toBeLessThanOrEqual(67.8)
       expect(parseFloat(indexFirstLoad)).toBeGreaterThanOrEqual(60)
       expect(indexFirstLoad.endsWith('kB')).toBe(true)
     })

diff --git a/test/integration/size-limit/test/index.test.js b/test/integration/size-limit/test/index.test.js
@@ -81,6 +81,6 @@ describe('Production response size', () => {
     const delta = responseSizesBytes / 1024
 
     // Expected difference: < 0.5
-    expect(delta).toBeCloseTo(285.3, 0)
+    expect(delta).toBeCloseTo(286.7, 0)
   })
 })