feat(core): route announcer by seyoon20087 · Pull Request #7074 · facebook/docusaurus

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 <24852454+seyoon20087@users.noreply.github.com>

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 <24852454+seyoon20087@users.noreply.github.com>

Someone suggested to put it in App.tsx instead of `@theme/Root`. Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

In my testing 50ms is ok to me. You may change it if it something goes wrong. Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

Josh-Cena

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

Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

Someone suggested to this to adjust some code and to prevent blocked on an external dep as commented. Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

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 <24852454+seyoon20087@users.noreply.github.com>

Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

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?

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

+
+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.

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

+ * 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

+    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


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

+      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 Josh-Cena, lex111 and slorber 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 <24852454+seyoon20087@users.noreply.github.com>

Josh-Cena reviewed Mar 30, 2022

View reviewed changes

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

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 <24852454+seyoon20087@users.noreply.github.com>

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 <24852454+seyoon20087@users.noreply.github.com>

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

Comment thread packages/docusaurus/package.json Outdated

Comment thread packages/docusaurus/src/client/routeAnnouncer.tsx Outdated

Comment thread packages/docusaurus/src/client/routeAnnouncer.tsx Outdated

seyoon20087 added 4 commits March 30, 2022 23:00

update code - use code suggested by @Josh-Cena

2c9ae8f

Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

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 <24852454+seyoon20087@users.noreply.github.com>

Update portal import.

df005b8

Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

update types

9608abe

Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

Josh-Cena reviewed Mar 30, 2022

View reviewed changes

Comment thread packages/docusaurus/src/client/exports/Portal.tsx Outdated

Josh-Cena reviewed Mar 30, 2022

View reviewed changes

Comment thread yarn.lock Outdated

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

update lockfile

6188ded

Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

update types

36a773d

Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

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 <24852454+seyoon20087@users.noreply.github.com>

Josh-Cena reviewed Apr 3, 2022

View reviewed changes

Comment thread packages/docusaurus/src/client/RouteAnnouncer.tsx Outdated

remove temporary fallback

1060785

Signed-off-by: Shinwon Elizabeth Yoon <24852454+seyoon20087@users.noreply.github.com>

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

Uh oh!

Uh oh!

Conversation

seyoon20087 commented Mar 30, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

Uh oh!

netlify Bot commented Mar 30, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ [V2]

Uh oh!

github-actions Bot commented Mar 30, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚡️ Lighthouse report for the deploy preview of this PR

Uh oh!

Uh oh!

Josh-Cena left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Josh-Cena commented Mar 31, 2022

Uh oh!

Uh oh!

Josh-Cena left a comment

Choose a reason for hiding this comment

Uh oh!

lex111 left a comment

Choose a reason for hiding this comment

Uh oh!

Josh-Cena commented Apr 3, 2022

Uh oh!

slorber left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

slorber Apr 7, 2022

Choose a reason for hiding this comment

Uh oh!

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Josh-Cena left a comment

Choose a reason for hiding this comment

Uh oh!

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

Uh oh!

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

Uh oh!

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

Uh oh!

Josh-Cena Apr 30, 2022

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

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