feat(core): route announcer

packages/docusaurus/src/client/App.tsx

@@ -23,6 +23,10 @@ import './client-lifecycles-dispatcher';
 import ErrorBoundary from '@docusaurus/ErrorBoundary';
 import Error from '@theme/Error';
 
+// Add a route announcer
+import {Portal} from './exports/Portal';
+import {RouteAnnouncer} from './routeAnnouncer';
+
 export default function App(): JSX.Element {
   return (
     <ErrorBoundary fallback={Error}>
@@ -38,6 +42,9 @@ export default function App(): JSX.Element {
           </Root>
         </BrowserContextProvider>
       </DocusaurusContextProvider>
+      <Portal type="docusaurus-route-announcer">
+        <RouteAnnouncer />
+      </Portal>
     </ErrorBoundary>
   );
 }

packages/docusaurus/src/client/exports/Portal.tsx

@@ -0,0 +1,35 @@
+/**
+ * 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 {createPortal} from 'react-dom';
+
+type PortalProps = {
+  children: React.ReactNode;
+  type: string;
+};
+
+export function Portal({
+  children,
+  type = 'docusaurus-portal',
+}: // eslint-disable-next-line @typescript-eslint/no-explicit-any
+PortalProps): any {
+  const portalNode = React.useRef<HTMLElement | null>(null);
+  const [, forceUpdate] = React.useState<{[key: string]: unknown}>();
+  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;
+}

packages/docusaurus/src/client/routeAnnouncer.tsx

@@ -0,0 +1,66 @@
+/**
+ * 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;
+
+    const pageHeader = document.querySelector('h1');
+    const content = pageHeader?.innerText ?? pageHeader?.textContent;
+
+    // NOTE: when setTimeout isn't used it will keep the previous page's title,
+    // which may be annoying to some screen-reader users (in my testing).
+    // Similar issue regarding this is https://github.com/vercel/next.js/issues/32610
+    setTimeout(() => {
+      setRouteAnnouncement(document.title ?? content ?? pathname);
+    }, 50);
+  }, [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;

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==