feat(core): route announcer #7074

seyoon20087 · 2022-03-30T12:52:34Z

Motivation

By doing this, client-side route changes will be announced to screen readers, improving accessibility to screen-reader users.

This was heavily inspired by https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/cache-dir/navigation.js#L173-L202.

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

Add the route announcer component
Include the route announcer component in the root

Related PRs

N/A

By doing this, client-side route changes will be announced to screen readers, improving accessibility to screen-reader users. This was heavily inspired by https://github.com/vercel/next.js/blob/canary/packages/next/client/route-announcer.tsx. Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

netlify · 2022-03-30T13:01:25Z

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`7d67a48`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/628dcf2b15c35e00083b43b0
😎 Deploy Preview	https://deploy-preview-7074--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

github-actions · 2022-03-30T13:01:56Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 71	🟢 100	🟢 100	🟢 100	🟢 90	Report
/docs/installation	🟠 84	🟢 99	🟢 100	🟢 100	🟢 90	Report

I have dived in the codebase, and it looks like it has a 1000 second wait time before a new route can load. Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

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

Someone suggested to put it in App.tsx instead of `@theme/Root`. Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

In my testing 50ms is ok to me. You may change it if it something goes wrong. Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Josh-Cena

Thanks, seems to work great 👍 Will leave it to others to review as well. Left some more suggestions.

packages/docusaurus/package.json

packages/docusaurus/src/client/routeAnnouncer.tsx

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Someone suggested to this to adjust some code and to prevent blocked on an external dep as commented. Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

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

yarn.lock

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Josh-Cena · 2022-03-31T07:52:01Z

The timeout unfortunately doesn't work if the network is slow and the bundle preloading takes more than 50ms. I think this should better be implemented as a client module since it seems pretty decoupled from the main app. We can do this after fixing #6732

…-- similarly to gatsby 4 Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

packages/docusaurus/src/client/RouteAnnouncer.tsx

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Josh-Cena

The current behavior looks cool to me. I still somehow believe this can be factored out into a separate client module and not in the main component tree (since all it does is consuming the location and portaling to a DOM element), but I'll let @slorber take a look first. At least now we can be unblocked from #6732

lex111

Perhaps we should move this component to the classic-theme area to make related message translatable?

Josh-Cena · 2022-04-03T22:07:20Z

I agree. Given the current architecture, it seems feasible to put this in layout as well.

slorber

Hey, looks like an interesting addition.

I don't know how route announcement is supposed to be implemented theoretically, can you explain, please? Particularly the thing about using a custom element, a portal, rAF...

I don't understand a few choices in this PR that looks weird to me, but maybe I'm wrong

The announcement label template should rather be translatable, and this does not really belong in core

Maybe this feature could be a route announcement plugin using a client module?

packages/docusaurus/src/client/RouteAnnouncer.tsx

slorber · 2022-04-07T16:48:48Z

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

+
+export function Portal({
+  children,
+  type = 'docusaurus-portal',


are other portal types planned?

What is the purpose of calling document.createElement("docusaurus-portal"); ?

@slorber This is the container node's tag name. Portal elements can often be custom elements so as not to have any default user-agent styles.

packages/docusaurus/src/client/RouteAnnouncer.tsx

Josh-Cena

@slorber @lex111 I've move the announcer implementation to theme-classic so we can translate it. Because the client module has just been fixed, I decided to go with a pure-DOM solution without wiring it to a theme component, so that we have a use-case of reading and manipulating DOM in client module. I doubt if anyone wants to swizzle the announcement anyways. I've kept the Portal core component for now, although we don't use it anymore, in case it's useful in the future. Tell me what you think.

Josh-Cena · 2022-04-30T03:18:18Z

packages/docusaurus-theme-classic/src/routeAnnouncer.css

+ * LICENSE file in the root directory of this source tree.
+ */
+
+#docusaurus-route-announcer-content {


Using an ID selector here. Not sure if we necessarily want a class name here, or if we want to use inline styles.

Josh-Cena · 2022-04-30T03:20:48Z

packages/docusaurus-theme-classic/src/routeAnnouncer.ts

+    const announcerContainer = document.createElement(
+      'docusaurus-route-announcer',
+    );
+    const announcement = document.createElement('p');
+    Object.assign(announcement, {
+      ariaLive: 'assertive', // Make the announcement immediately.
+      id: 'docusaurus-route-announcer-content',
+      role: 'alert',
+    });


Pure DOM manipulation. Because client modules don't have access to the React context, it would be quite cumbersome if we want to use React to do this. The alternative will be to put this in Layout, but there may be other edge-cases (for example, the layout doesn't re-mount between doc pages)

Josh-Cena · 2022-04-30T03:24:43Z

website/testCSSOrder.mjs

@@ -49,6 +48,7 @@ const EXPECTED_CSS_MARKERS = [

  // Lazy-loaded lib
  '.DocSearch-Modal',
+  '.DocSearch-Hit-content-wrapper',


I'm surprised that this moved, but it makes more sense this way? Not sure why it was loaded so early before.

Josh-Cena · 2022-04-30T03:29:34Z

packages/docusaurus/src/client/ClientLifecyclesDispatcher.tsx

+      return dispatchLifecycleAction('onRouteDidUpdate', {
+        previousLocation,
+        location,
+      });


Exposed the cleanup function here, so we can clean up the side-effect of appending DOM child.

seyoon20087 requested review from slorber, lex111 and Josh-Cena as code owners March 30, 2022 12:52

facebook-github-bot added the CLA Signed Signed Facebook CLA label Mar 30, 2022

Delay some time for the route announcer to change state.

1af1a6c

I have dived in the codebase, and it looks like it has a 1000 second wait time before a new route can load. Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Josh-Cena reviewed Mar 30, 2022

View reviewed changes

packages/docusaurus/src/client/theme-fallback/Root/index.tsx Outdated Show resolved Hide resolved

seyoon20087 added 2 commits March 30, 2022 22:13

Move route announcer to App.tsx.

2ada5fc

Someone suggested to put it in App.tsx instead of `@theme/Root`. Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Decrease the wait time.

ebd259f

In my testing 50ms is ok to me. You may change it if it something goes wrong. Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

seyoon20087 requested a review from Josh-Cena March 30, 2022 13:19

Josh-Cena changed the title ~~Add a route announcer~~ feat(core): route announcer Mar 30, 2022

Josh-Cena added the pr: new feature This PR adds a new API or behavior. label Mar 30, 2022

Josh-Cena reviewed Mar 30, 2022

View reviewed changes

packages/docusaurus/package.json Outdated Show resolved Hide resolved

packages/docusaurus/src/client/routeAnnouncer.tsx Outdated Show resolved Hide resolved

packages/docusaurus/src/client/routeAnnouncer.tsx Outdated Show resolved Hide resolved

seyoon20087 added 4 commits March 30, 2022 23:00

update code - use code suggested by @Josh-Cena

2c9ae8f

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Remove @reach/portal dep in favor of built-in portal

f271f17

Someone suggested to this to adjust some code and to prevent blocked on an external dep as commented. Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Update portal import.

df005b8

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

update types

9608abe

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Josh-Cena reviewed Mar 30, 2022

View reviewed changes

packages/docusaurus/src/client/exports/Portal.tsx Outdated Show resolved Hide resolved

Josh-Cena reviewed Mar 30, 2022

View reviewed changes

yarn.lock Outdated Show resolved Hide resolved

seyoon20087 and others added 4 commits March 30, 2022 23:29

update lockfile

6188ded

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

update types

36a773d

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

refactor

a5cd567

comment fix

fd8018d

Josh-Cena added the status: don't merge yet This PR is completed, but we are still waiting for other things to be ready. label Mar 31, 2022

Josh-Cena marked this pull request as draft March 31, 2022 07:52

Merge branch 'facebook:main' into create-route-announcer

6686055

Josh-Cena removed the status: don't merge yet This PR is completed, but we are still waiting for other things to be ready. label Apr 3, 2022

Josh-Cena added 3 commits April 3, 2022 21:59

refactor

90e07e3

add return type

49e20e7

quick fix

37cafa3

Josh-Cena added status: awaiting review This PR is ready for review, will be merged after maintainers' approval and removed status: blocked This issue is blocked by another issue or external dep and can't be pushed further. labels Apr 3, 2022

Josh-Cena marked this pull request as ready for review April 3, 2022 14:12

fallback to page path when first h1 or document.title does not exist …

7cc8df3

…-- similarly to gatsby 4 Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Josh-Cena reviewed Apr 3, 2022

View reviewed changes

packages/docusaurus/src/client/RouteAnnouncer.tsx Outdated Show resolved Hide resolved

remove temporary fallback

1060785

Signed-off-by: Shinwon Elizabeth Yoon <[email protected]>

Josh-Cena approved these changes Apr 3, 2022

View reviewed changes

lex111 reviewed Apr 3, 2022

View reviewed changes

slorber requested changes Apr 7, 2022

View reviewed changes

Josh-Cena mentioned this pull request Apr 10, 2022

feat(core): rework client modules lifecycles, officially make API public #6732

Merged

slorber marked this pull request as draft April 21, 2022 15:03

Josh-Cena added 2 commits April 30, 2022 09:53

Merge branch 'main' into create-route-announcer

bbb2ffb

reimplement with client module

8704767

Josh-Cena requested review from lex111 and slorber April 30, 2022 02:59

make text label translatable

6104fcb

Josh-Cena marked this pull request as ready for review April 30, 2022 03:02

Josh-Cena added 2 commits April 30, 2022 11:17

fixes

4e2319d

fix CSS order?

00956fd

Josh-Cena reviewed Apr 30, 2022

View reviewed changes

use cleanup function

8833c65

Josh-Cena reviewed Apr 30, 2022

View reviewed changes

Josh-Cena removed the status: awaiting review This PR is ready for review, will be merged after maintainers' approval label May 2, 2022

Merge branch 'main' into create-route-announcer

7d67a48

seyoon20087 closed this by deleting the head repository Sep 9, 2022

Josh-Cena mentioned this pull request Sep 18, 2022

Route Announcer for Docusaurus 📢 #8110

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(core): route announcer #7074

feat(core): route announcer #7074

seyoon20087 commented Mar 30, 2022 •

edited

Loading

netlify bot commented Mar 30, 2022 •

edited

Loading

github-actions bot commented Mar 30, 2022 •

edited

Loading

Josh-Cena left a comment

Josh-Cena commented Mar 31, 2022

Josh-Cena left a comment

lex111 left a comment

Josh-Cena commented Apr 3, 2022

slorber left a comment •

edited

Loading

slorber Apr 7, 2022

Josh-Cena Apr 30, 2022

Josh-Cena left a comment

Josh-Cena Apr 30, 2022

Josh-Cena Apr 30, 2022

Josh-Cena Apr 30, 2022

Josh-Cena Apr 30, 2022

feat(core): route announcer #7074

feat(core): route announcer #7074

Conversation

seyoon20087 commented Mar 30, 2022 • edited Loading

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

netlify bot commented Mar 30, 2022 • edited Loading

✅ [V2]

github-actions bot commented Mar 30, 2022 • edited Loading

⚡️ Lighthouse report for the deploy preview of this PR

Josh-Cena left a comment

Choose a reason for hiding this comment

Josh-Cena commented Mar 31, 2022

Josh-Cena left a comment

Choose a reason for hiding this comment

lex111 left a comment

Choose a reason for hiding this comment

Josh-Cena commented Apr 3, 2022

slorber left a comment • edited Loading

Choose a reason for hiding this comment

slorber Apr 7, 2022

Choose a reason for hiding this comment

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

Josh-Cena left a comment

Choose a reason for hiding this comment

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

seyoon20087 commented Mar 30, 2022 •

edited

Loading

netlify bot commented Mar 30, 2022 •

edited

Loading

github-actions bot commented Mar 30, 2022 •

edited

Loading

slorber left a comment •

edited

Loading