feat(core): route announcer

packages/docusaurus/package.json

@@ -48,6 +48,7 @@
     "@docusaurus/utils": "2.0.0-beta.18",
     "@docusaurus/utils-common": "2.0.0-beta.18",
     "@docusaurus/utils-validation": "2.0.0-beta.18",
+    "@reach/portal": "^0.16.2",
     "@slorber/static-site-generator-webpack-plugin": "^4.0.4",
     "@svgr/webpack": "^6.2.1",
     "autoprefixer": "^10.4.4",

packages/docusaurus/src/client/routeAnnouncer.tsx

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import {useLocation} from 'react-router-dom';
+
+export function RouteAnnouncer() {
+  const {pathname} = useLocation();
+  const [routeAnnouncement, setRouteAnnouncement] = React.useState('');
+
+  // Only announce the path change, but not for the first load because screen
+  // reader will do that automatically.
+  const previouslyLoadedPath = React.useRef(pathname);
+
+  // Every time the path changes, announce the new page’s title following this
+  // priority: first the document title (from head), otherwise the first h1, or
+  // if none of these exist, then the pathname from 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/
+  React.useEffect(
+    () => {
+      // If the path hasn't change, we do nothing.
+      if (previouslyLoadedPath.current === pathname) {
+        return;
+      }
+      previouslyLoadedPath.current = pathname;
+
+      if (document.title) {
+        setTimeout(() => {
+          setRouteAnnouncement(document.title);
+        }, 1050);
+      } else {
+        const pageHeader = document.querySelector('h1');
+        const content = pageHeader?.innerText ?? pageHeader?.textContent;
+        setTimeout(() => {
+          setRouteAnnouncement(content || pathname);
+        }, 1050);
+      }
+    },
+    // TODO: switch to pathname + query object of dynamic route requirements
+    [pathname],
+  );
+
+  return (
+    <p
+      aria-live="assertive" // Make the announcement immediately.
+      id="__docusaurus-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;

packages/docusaurus/src/client/theme-fallback/Root/index.tsx

@@ -7,6 +7,8 @@
 
 import React from 'react';
 import type {Props} from '@theme/Root';
+import Portal from '@reach/portal';
+import {RouteAnnouncer} from '../../routeAnnouncer';
 
 // Wrapper at the very top of the app, that is applied constantly
 // and does not depend on current route (unlike the layout)
@@ -16,5 +18,12 @@ import type {Props} from '@theme/Root';
 //
 // See https://github.com/facebook/docusaurus/issues/3919
 export default function Root({children}: Props): JSX.Element {
-  return <>{children}</>;
+  return (
+    <>
+      {children}
+      <Portal type="docusaurus-route-announcer">
+        <RouteAnnouncer />
+      </Portal>
+    </>
+  );
 }

yarn.lock

@@ -3211,6 +3211,23 @@
   resolved "https://registry.yarnpkg.com/@popperjs/core/-/core-2.11.4.tgz#d8c7b8db9226d2d7664553a0741ad7d0397ee503"
   integrity sha512-q/ytXxO5NKvyT37pmisQAItCFqA7FD/vNb8dgaJy3/630Fsc+Mz9/9f2SziBoIZ30TJooXyTwZmhi1zjXmObYg==
 
+"@reach/portal@^0.16.2":
+  version "0.16.2"
+  resolved "https://registry.yarnpkg.com/@reach/portal/-/portal-0.16.2.tgz#ca83696215ee03acc2bb25a5ae5d8793eaaf2f64"
+  integrity sha512-9ur/yxNkuVYTIjAcfi46LdKUvH0uYZPfEp4usWcpt6PIp+WDF57F/5deMe/uGi/B/nfDweQu8VVwuMVrCb97JQ==
+  dependencies:
+    "@reach/utils" "0.16.0"
+    tiny-warning "^1.0.3"
+    tslib "^2.3.0"
+
+"@reach/[email protected]":
+  version "0.16.0"
+  resolved "https://registry.yarnpkg.com/@reach/utils/-/utils-0.16.0.tgz#5b0777cf16a7cab1ddd4728d5d02762df0ba84ce"
+  integrity sha512-PCggBet3qaQmwFNcmQ/GqHSefadAFyNCUekq9RrWoaU9hh/S4iaFgf2MBMdM47eQj5i/Bk0Mm07cP/XPFlkN+Q==
+  dependencies:
+    tiny-warning "^1.0.3"
+    tslib "^2.3.0"
+
 "@rollup/plugin-babel@^5.2.0":
   version "5.3.1"
   resolved "https://registry.yarnpkg.com/@rollup/plugin-babel/-/plugin-babel-5.3.1.tgz#04bc0608f4aa4b2e4b1aebf284344d0f68fda283"
@@ -18278,7 +18295,7 @@ tslib@^1.8.1, tslib@^1.9.0:
   resolved "https://registry.yarnpkg.com/tslib/-/tslib-1.14.1.tgz#cf2d38bdc34a134bcaf1091c41f6619e2f672d00"
   integrity sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==
 
-tslib@^2.0.1, tslib@^2.0.3, tslib@^2.1.0, tslib@^2.2.0, tslib@^2.3.1:
+tslib@^2.0.1, tslib@^2.0.3, tslib@^2.1.0, tslib@^2.2.0, tslib@^2.3.0, tslib@^2.3.1:
   version "2.3.1"
   resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.3.1.tgz#e8a335add5ceae51aa261d32a490158ef042ef01"
   integrity sha512-77EbyPPpMz+FRFRuAFlWMtmgUWGe9UOG2Z25NqCwiIjRhOf5iKGuzSe5P2w1laq+FkRy4p+PCuVkJSGkzTEKVw==