feat(core): route announcer

packages/docusaurus/src/client/App.tsx

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-
+import {useLocation} from './exports/router';
 import routes from '@generated/routes';
 import renderRoutes from './exports/renderRoutes';
 import {BrowserContextProvider} from './browserContext';
@@ -16,6 +16,7 @@ import BaseUrlIssueBanner from './BaseUrlIssueBanner';
 import SiteMetadataDefaults from './SiteMetadataDefaults';
 import Root from '@theme/Root';
 import SiteMetadata from '@theme/SiteMetadata';
+import RouteAnnouncer from './RouteAnnouncer';
 
 import './clientLifecyclesDispatcher';
 
@@ -24,6 +25,7 @@ import ErrorBoundary from '@docusaurus/ErrorBoundary';
 import Error from '@theme/Error';
 
 export default function App(): JSX.Element {
+  const {pathname} = useLocation();
   return (
     <ErrorBoundary fallback={Error}>
       <DocusaurusContextProvider>
@@ -33,7 +35,9 @@ export default function App(): JSX.Element {
             <SiteMetadata />
             <BaseUrlIssueBanner />
             <PendingNavigation routes={routes} delay={1000}>
-              {renderRoutes(routes)}
+              <RouteAnnouncer location={pathname}>
+                {renderRoutes(routes)}
+              </RouteAnnouncer>
             </PendingNavigation>
           </Root>
         </BrowserContextProvider>

packages/docusaurus/src/client/RouteAnnouncer.tsx

@@ -0,0 +1,78 @@
+/**
+ * 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 {Portal} from './exports/Portal';
+
+type Props = {
+  // Force an update on route transition
+  // eslint-disable-next-line react/no-unused-prop-types
+  location: string;
+  children: React.ReactNode;
+};
+
+type State = {
+  routeAnnouncement: string;
+};
+
+class RouteAnnouncerWrapper extends React.Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = {
+      routeAnnouncement: '',
+    };
+  }
+
+  override componentDidUpdate(): void {
+    const {routeAnnouncement} = this.state;
+
+    requestAnimationFrame(() => {
+      const firstHeading = document.querySelectorAll(`#__docusaurus h1`)[0];
+      const pageName = firstHeading?.textContent ?? document.title;
+      const newAnnouncement = `Navigated to ${pageName}`;
+      const oldAnnouncement = routeAnnouncement;
+      if (oldAnnouncement !== newAnnouncement) {
+        this.setState({
+          routeAnnouncement: newAnnouncement,
+        });
+      }
+    });
+  }
+
+  override render(): JSX.Element {
+    const {children} = this.props;
+    const {routeAnnouncement} = this.state;
+    return (
+      <>
+        {children}
+        <Portal type="docusaurus-route-announcer">
+          <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>
+        </Portal>
+      </>
+    );
+  }
+}
+
+export default RouteAnnouncerWrapper;

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

@@ -0,0 +1,34 @@
+/**
+ * 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 {useRef, useState, useEffect, type ReactPortal} from 'react';
+import {createPortal} from 'react-dom';
+
+type PortalProps = {
+  children: React.ReactNode;
+  type: string;
+};
+
+export function Portal({
+  children,
+  type = 'docusaurus-portal',
+}: PortalProps): ReactPortal | null {
+  const portalNode = useRef<HTMLElement | null>(null);
+  const [, forceUpdate] = useState<unknown>();
+  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/webpack/__tests__/__snapshots__/base.test.ts.snap

@@ -10,6 +10,7 @@ exports[`base webpack config creates webpack aliases 1`] = `
   "@docusaurus/Interpolate": "../../../../client/exports/Interpolate.tsx",
   "@docusaurus/Link": "../../../../client/exports/Link.tsx",
   "@docusaurus/Noop": "../../../../client/exports/Noop.ts",
+  "@docusaurus/Portal": "../../../../client/exports/Portal.tsx",
   "@docusaurus/Translate": "../../../../client/exports/Translate.tsx",
   "@docusaurus/constants": "../../../../client/exports/constants.ts",
   "@docusaurus/isInternalUrl": "../../../../client/exports/isInternalUrl.ts",

packages/docusaurus/src/webpack/aliases/__tests__/__snapshots__/index.test.ts.snap

@@ -10,6 +10,7 @@ exports[`getDocusaurusAliases returns appropriate webpack aliases 1`] = `
   "@docusaurus/Interpolate": "<PROJECT_ROOT>/packages/docusaurus/src/client/exports/Interpolate.tsx",
   "@docusaurus/Link": "<PROJECT_ROOT>/packages/docusaurus/src/client/exports/Link.tsx",
   "@docusaurus/Noop": "<PROJECT_ROOT>/packages/docusaurus/src/client/exports/Noop.ts",
+  "@docusaurus/Portal": "<PROJECT_ROOT>/packages/docusaurus/src/client/exports/Portal.tsx",
   "@docusaurus/Translate": "<PROJECT_ROOT>/packages/docusaurus/src/client/exports/Translate.tsx",
   "@docusaurus/constants": "<PROJECT_ROOT>/packages/docusaurus/src/client/exports/constants.ts",
   "@docusaurus/isInternalUrl": "<PROJECT_ROOT>/packages/docusaurus/src/client/exports/isInternalUrl.ts",