vercel · kodiakhq · Mar 15, 2021 · Dec 23, 2020 · Dec 23, 2020 · Dec 28, 2020
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" />
@@ -777,6 +779,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,39 @@
+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 [isMounted, setMounted] = React.useState(false)
+  let mountNode = React.useRef<HTMLDivElement | null>(null)
+  let portalNode = React.useRef<HTMLElement | null>(null)
+  let [, forceUpdate] = React.useState<{}>()
+  React.useEffect(() => {
+    setMounted(true)
+  }, [])
+  React.useEffect(() => {
+    if (!isMounted) return
+    // This ref may be null when a hot-loader replaces components on the page
+    if (!mountNode.current) return
+    // It's possible that the content of the portal has, itself, been portaled.
+    // In that case, it's important to append to the correct document element.
+    const ownerDocument = mountNode.current!.ownerDocument
+    portalNode.current = ownerDocument?.createElement(type)!
+    ownerDocument!.body.appendChild(portalNode.current)
+    forceUpdate({})
+    return () => {
+      if (portalNode.current && portalNode.current.ownerDocument) {
+        portalNode.current.ownerDocument.body.removeChild(portalNode.current)
+      }
+    }
+  }, [type, forceUpdate, isMounted])
+
+  return portalNode.current ? (
+    createPortal(children, portalNode.current)
+  ) : isMounted ? (
+    <span ref={mountNode} />
+  ) : null
+}
diff --git a/packages/next/client/route-announcer.tsx b/packages/next/client/route-announcer.tsx
@@ -0,0 +1,58 @@
+import React, { useEffect, useState } from 'react'
+import { useRouter } from './router'
+
+export function RouteAnnouncer() {
+  const router = useRouter()
+  const [routeAnnouncement, setRouteAnnouncement] = useState('')
+
+  const { asPath } = router
+
+  // 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(
+    () => {
+      let newRouteAnnouncement
+      const pageHeader = document.querySelector('h1')
+
+      if (pageHeader) {
+        newRouteAnnouncement = pageHeader.innerText
+      } else if (document.title) {
+        newRouteAnnouncement = document.title
+      } else {
+        newRouteAnnouncement = asPath
+      }
+
+      setRouteAnnouncement(newRouteAnnouncement)
+    },
+    // TODO: switch to pathname + query object of dynamic route requirements
+    [asPath]
+  )
+
+  return (
+    <div
+      aria-atomic // Always announce the entire path.
+      aria-live="assertive" // Make the announcement immediately.
+      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}
+    </div>
+  )
+}
+
+export default RouteAnnouncer
diff --git a/packages/next/next-server/lib/router/router.ts b/packages/next/next-server/lib/router/router.ts
@@ -338,6 +338,36 @@ function prepareUrlAs(router: NextRouter, url: Url, as?: Url) {
   }
 }
 
+// Focus a user's attention to the beginning of new content. This is done by focusing the first h1 tag. If an h1 does
+// not exist, focus the main semantic tag. If this does not exist, focus the cursor on the body. 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/
+function a11ySmartFocus() {
+  const elementToFocus =
+    document.querySelector('h1') ||
+    document.querySelector('main') ||
+    document.body
+
+  if (elementToFocus) {
+    const didTabIndexExist = elementToFocus.getAttribute('tabIndex')
+
+    // Only elements with a tabIndex are focusable. So we add a tabIndex here just to make it focusable.
+    if (!didTabIndexExist) {
+      elementToFocus.setAttribute('tabIndex', '-1')
+    }
+
+    elementToFocus.focus()
+
+    // Once the focus leaves the element, we should clean up the tabIndex, if we added one. This is so the screen-reader
+    // does not try to focus the element for purposes other than the initial client-navigation.
+    if (!didTabIndexExist) {
+      elementToFocus.addEventListener('blur', () => {
+        elementToFocus.removeAttribute('tabIndex')
+      })
+    }
+  }
+}
+
 export type BaseRouter = {
   route: string
   pathname: string
@@ -1129,6 +1159,11 @@ export default class Router implements BaseRouter {
           document.documentElement.lang = this.locale
         }
       }
+
+      if (!options.shallow) {
+        a11ySmartFocus()
+      }
+
       Router.events.emit('routeChangeComplete', as, routeProps)
 
       return true

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.8 kb
-      expect(parseFloat(indexFirstLoad)).toBeCloseTo(63.8, 1)
+      // should be no bigger than 64.4 kb
+      expect(parseFloat(indexFirstLoad)).toBeCloseTo(64.4, 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)
+      expect(parseFloat(err404FirstLoad)).toBeCloseTo(67.6, 1)
       expect(err404FirstLoad.endsWith('kB')).toBe(true)
 
-      expect(parseFloat(sharedByAll)).toBeCloseTo(63.5, 1)
+      expect(parseFloat(sharedByAll)).toBeCloseTo(64.1, 1)
       expect(sharedByAll.endsWith('kB')).toBe(true)
 
       if (_appSize.endsWith('kB')) {
@@ -168,7 +168,7 @@ describe('Build Output', () => {
       expect(parseFloat(indexSize)).toBeGreaterThanOrEqual(2)
       expect(indexSize.endsWith('kB')).toBe(true)
 
-      expect(parseFloat(indexFirstLoad)).toBeLessThanOrEqual(66.6)
+      expect(parseFloat(indexFirstLoad)).toBeLessThanOrEqual(67.2)
       expect(parseFloat(indexFirstLoad)).toBeGreaterThanOrEqual(60)
       expect(indexFirstLoad.endsWith('kB')).toBe(true)
     })

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,20 @@
+import Link from 'next/link'
+
+export default () => (
+  <>
+    <Link href="/with-h1">
+      <a id="with-h1-link">With h1 element</a>
+    </Link>
+    <Link href="/with-h1-and-tab-index">
+      <a id="with-h1-and-tab-index-link">
+        With h1 element that has a tab index
+      </a>
+    </Link>
+    <Link href="/with-main">
+      <a id="with-main-link">With main element</a>
+    </Link>
+    <Link href="/without-main">
+      <a id="without-main-link">Without main element</a>
+    </Link>
+  </>
+)
diff --git a/test/integration/client-navigation-a11y/pages/with-h1-and-tab-index.js b/test/integration/client-navigation-a11y/pages/with-h1-and-tab-index.js
@@ -0,0 +1,6 @@
+export default () => (
+  <main id="navigation-result-container">
+    <h1 tabIndex="2">My heading</h1>
+    <div>Extraneous stuff</div>
+  </main>
+)
diff --git a/test/integration/client-navigation-a11y/pages/with-h1.js b/test/integration/client-navigation-a11y/pages/with-h1.js
@@ -0,0 +1,6 @@
+export default () => (
+  <main id="navigation-result-container">
+    <h1>My heading</h1>
+    <div>Extraneous stuff</div>
+  </main>
+)
diff --git a/test/integration/client-navigation-a11y/pages/with-main.js b/test/integration/client-navigation-a11y/pages/with-main.js
@@ -0,0 +1,6 @@
+export default () => (
+  <main id="navigation-result-container">
+    <div>My heading</div>
+    <div>Extraneous stuff</div>
+  </main>
+)
diff --git a/test/integration/client-navigation-a11y/pages/without-main.js b/test/integration/client-navigation-a11y/pages/without-main.js
@@ -0,0 +1,6 @@
+export default () => (
+  <div id="navigation-result-container">
+    <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,115 @@
+/* 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 = [
+      '/with-h1',
+      '/with-h1-and-tab-index',
+      '/with-main',
+      '/without-main',
+    ]
+
+    await Promise.all(
+      prerender.map((route) => renderViaHTTP(context.appPort, route))
+    )
+  })
+
+  afterAll(() => killApp(context.server))
+
+  describe('the next route has an h1 element', () => {
+    it('brings focus to the h1 element', async () => {
+      const browser = await webdriver(context.appPort, '/')
+      await browser
+        .waitForElementByCss('#with-h1-link')
+        .click()
+        .waitForElementByCss('#navigation-result-container')
+
+      const isH1Focused = await browser.eval(
+        'document.activeElement === document.querySelector("h1")'
+      )
+      expect(isH1Focused).toBe(true)
+
+      await browser.close()
+    })
+  })
+
+  describe('the next route has a main element', () => {
+    it('brings focus to the main element', async () => {
+      const browser = await webdriver(context.appPort, '/')
+      await browser
+        .waitForElementByCss('#with-main-link')
+        .click()
+        .waitForElementByCss('#navigation-result-container')
+
+      const isMainFocused = await browser.eval(
+        'document.activeElement === document.querySelector("main")'
+      )
+      expect(isMainFocused).toBe(true)
+
+      await browser.close()
+    })
+  })
+
+  describe('the next route has neither a main nor h1 element', () => {
+    it('brings focus to the body', async () => {
+      const browser = await webdriver(context.appPort, '/')
+      await browser
+        .waitForElementByCss('#without-main-link')
+        .click()
+        .waitForElementByCss('#navigation-result-container')
+
+      const isBodyFocused = await browser.eval(
+        'document.activeElement === document.body'
+      )
+      expect(isBodyFocused).toBe(true)
+    })
+  })
+
+  describe('tabIndex of focused element does not exist', () => {
+    it('is set to -1', async () => {
+      const browser = await webdriver(context.appPort, '/')
+      const tabIndex = await browser
+        .waitForElementByCss('#with-h1-link')
+        .click()
+        .waitForElementByCss('#navigation-result-container')
+        .elementByCss('h1')
+        .getAttribute('tabIndex')
+
+      expect(tabIndex).toBe('-1')
+      await browser.close()
+    })
+  })
+
+  describe('tabIndex of focused element exists', () => {
+    it('does not change', async () => {
+      const browser = await webdriver(context.appPort, '/')
+      const tabIndex = await browser
+        .waitForElementByCss('#with-h1-and-tab-index-link')
+        .click()
+        .waitForElementByCss('#navigation-result-container')
+        .elementByCss('h1')
+        .getAttribute('tabIndex')
+
+      expect(tabIndex).toBe('2')
+
+      await browser.close()
+    })
+  })
+})