feat(theme-classic): auto-collapse sibling categories in doc sidebar #3811

softwarecurator · 2020-11-24T22:01:42Z

Motivation

As a user having multiple opened categories in the sidebar, it got confusing and cluttered having that everything open on the left side of the screen.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Using the enabled themeConfig.autoCollapseSidebar option, you can make the sidebar only have one parent category open at a time, helping users not get cluttered and only focus on the content they selected. This is enabled by default, If you want them to be always opened, set themeConfig.autoCollapseSidebar to false:

module.exports = {
  // ...
  themeConfig: {
    autoCollapseSidebar: false,
    // ...
  },
};

Preview

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

netlify · 2020-11-24T22:08:22Z

✔️ [V2]
Built without sensitive environment variables

🔨 Explore the source changes: 976dd19

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/61d9550b6b03490008a4c7f0

😎 Browse the preview: https://deploy-preview-3811--docusaurus-2.netlify.app

website/docs/docs.md

packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx

slorber · 2020-11-25T11:20:36Z

Thanks, that looks like a useful new feature to add!

I'd rather not enable this by default without polling the community about that first.

Also, not totally fan of the mutations being done in the implementation. The collapsed state is currently in the category. If you want a category to collapse, it would be better to make sure that setCollapsed(true) is called.

I see 2 possible solutions:

lift the category collapsed state at the top to be to access this state from anywhere?
keep state at the category level, but use an imperative API to collapse it from the top (see https://reactjs.org/docs/hooks-reference.html#useimperativehandle)

Also the close animation seems to not work as reliably as before

rylandg · 2020-12-02T23:38:28Z

@slorber I'd love this feature, what is the current blocker?

slorber · 2020-12-03T09:45:11Z

@rylandg the problem is written in the comment just before: #3811 (comment)

If you are able to get it working with:

a less hacky implementation (ie not mutating objects)
the animations working as before
opt-in, configurable, default to former behavior (no breaking change)

If you are unable to get it working, I'll figure it out myself and merge it, but I'm still busy working on i18n and have no time to work on it in the short term.

github-actions · 2020-12-18T19:52:44Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	84
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-3811--docusaurus-2.netlify.app/

github-actions · 2020-12-18T19:59:50Z

Size Change: +13 B (0%)

Total Size: 155 kB

ℹ️ View Unchanged

Filename	Size	Change
`website/build/blog/2017/12/14/introducing-docusaurus/index.html`	20.7 kB	-1 B (0%)
`website/build/docs/introduction/index.html`	180 B	0 B
`website/build/index.html`	5.82 kB	+1 B (0%)
`website/build/main.********.js`	111 kB	+13 B (0%)
`website/build/styles.********.css`	17.6 kB	0 B

_{compressed-size-action}

website/docs/deployment.mdx

website/docs/sidebar.md

softwarecurator · 2021-01-20T19:36:41Z

@rylandg the problem is written in the comment just before: #3811 (comment)

If you are able to get it working with:

a less hacky implementation (ie not mutating objects)

the animations working as before

opt-in, configurable, default to former behavior (no breaking change)

If you are unable to get it working, I'll figure it out myself and merge it, but I'm still busy working on i18n and have no time to work on it in the short term.

hey @slorber ! I have implemented 2/3 of the changes you required before it gets push but wanted to get you opinion on making the animation to correctly work, I brought all the state up so now the all the collapsing happens at the same time which I think changes how the animation worked since it waited 100ms between each state change. What would be the best way for the animation to work and to get this merged in?

Thank you!

softwarecurator · 2021-01-25T19:32:19Z

just checking the status of this pull request @slorber thank you!

slorber

Hi @josephriosIO , thanks for your work on this

There are a few things that do not look good to me:

A map with labels as index is not a reliable solution to store the categories states (it does not look simple as we don't have any unique category id, and probably need some kind of recursive structure)
The current UX looks weird to me (I guess it's quite subjective, maybe ask for feedbacks of your colleagues at Temporal about what they think about keeping the active category unfolded?)

For the animation, I didn't implement it and not 100% sure why the timeout was needed in the first place. I guess it could be restored by using a useEffect() somewhere, or maybe const isCollapsedDebounced = useDebounce(isCollapsed,100) ?

Also, it'd be nice to update your PR and solve the conflicts with master

Let me know if you need any help (I can commit to your PR, that may be faster for me than writing down my ideas as comments)

packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx

packages/docusaurus/src/webpack/__tests__/utils.test.ts

packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx

Josh-Cena · 2022-01-08T08:57:59Z

@slorber I think this is good enough? Our sidebar is too complicated, just used even more hooks inside ㄟ(▔,▔)ㄏ Context providers aren't the cleanest solution IMO, since we don't pass this to deep children... But so far it seems it works

Josh-Cena · 2022-01-08T09:14:05Z

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/index.tsx

@@ -111,6 +114,28 @@ function DocSidebarItemCategory({
  });

  useAutoExpandActiveCategory({isActive, collapsed, setCollapsed});
+  const {expandedItem, setExpandedItem} = useDocSidebarItemsExpandedState();
+  function updateCollapsed(toCollapsed: boolean = !collapsed) {
+    setExpandedItem(toCollapsed ? null : index);


The only case we have to think twice about UX is when there are multiple sidebar categories expanded by default. In this implementation, the expandedItem context is initialized to null, and when the user collapses one of those default-expanded categories, the others remain expanded until any category is toggled to be expanded.

I’m excited this feature is finally getting some steam

Yes! This is the UX I've been looking forward to, so I did invest some time in this :D

I haven’t really looked at the code, just a quick glance but I would set the default setting to false, I know not everyone will want this feature on by default, and that was an issue when I first tried to get this in over a year ago 😂

Yes, it's indeed defaulted to false :) Just that it would be cool to be turned on for our website.

slorber

Alright, that's not the ideal implementation, but that seems good enough for now, so let's move on

The only case we have to think twice about UX is when there are multiple sidebar categories expanded by default. In this implementation, the expandedItem context is initialized to null, and when the user collapses one of those default-expanded categories, the others remain expanded until any category is toggled to be expanded.

That's true there are a few unhandled edge cases, but most users will likely not notice them.

We'll refactor this feature and make it more robust later.

Let's enable it on our own website for now to dogfood

But I'm very likely to turn this off later because for me it is a real pain to click on a category see it shift far away from your mouse cursor.

softwarecurator added 3 commits November 24, 2020 13:42

Added auto collapsible sidebar

54b0386

Added new sidebar type

67c516e

added documation

f7fb0be

facebook-github-bot added the CLA Signed Signed Facebook CLA label Nov 24, 2020

softwarecurator marked this pull request as ready for review November 25, 2020 01:08

softwarecurator requested review from lex111 and slorber as code owners November 25, 2020 01:08

feedmeapples suggested changes Nov 25, 2020

View reviewed changes

slorber reviewed Nov 25, 2020

View reviewed changes

packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx Outdated Show resolved Hide resolved

slorber reviewed Nov 25, 2020

View reviewed changes

packages/docusaurus-theme-classic/src/theme/DocSidebar/index.tsx Outdated Show resolved Hide resolved

softwarecurator added 2 commits December 17, 2020 17:36

Updated changes

1f3c78d

Merged branch master into auto-collapse-sidebar-v2

2413511

flossypurse reviewed Jan 6, 2021

View reviewed changes

website/docs/deployment.mdx Outdated Show resolved Hide resolved

flossypurse reviewed Jan 6, 2021

View reviewed changes

website/docs/sidebar.md Outdated Show resolved Hide resolved

auto collapse changes

8c8edb3

This comment has been minimized.

Sign in to view

slorber requested changes Jan 27, 2021

View reviewed changes

Josh-Cena added 2 commits October 28, 2021 14:56

Merge branch 'main' into auto-collapse-sidebar-v2

21cb8bb

Fix typing

18a8e31

Josh-Cena changed the title ~~Auto collapse sidebar v2~~ feat(theme-classic): auto-collapse sibling categories in doc sidebar Oct 28, 2021

Josh-Cena added the pr: new feature This PR adds a new API or behavior. label Oct 28, 2021

Don't pass autoCollapse as props

b25e2d9

Josh-Cena added 2 commits January 8, 2022 16:48

Merge branch 'main' into auto-collapse-sidebar-v2

79f5949

work

2570f90

softwarecurator requested a review from Josh-Cena as a code owner January 8, 2022 08:50

make it configurable

8bc85f8

Josh-Cena requested a review from slorber January 8, 2022 08:53

Josh-Cena added 3 commits January 8, 2022 16:59

refactor

1f480b1

docs

3f99671

oops

976dd19

Josh-Cena reviewed Jan 8, 2022

View reviewed changes

Josh-Cena added the status: awaiting review This PR is ready for review, will be merged after maintainers' approval label Jan 8, 2022

Josh-Cena mentioned this pull request Jan 12, 2022

Persist sidebar state (categories expanded state, hidden sidebar) #6319

Open

2 tasks

slorber approved these changes Jan 20, 2022

View reviewed changes

slorber merged commit 8ce3cee into facebook:main Jan 20, 2022

slorber removed the status: awaiting review This PR is ready for review, will be merged after maintainers' approval label Jan 20, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(theme-classic): auto-collapse sibling categories in doc sidebar #3811

feat(theme-classic): auto-collapse sibling categories in doc sidebar #3811

softwarecurator commented Nov 24, 2020 •

edited

Loading

netlify bot commented Nov 24, 2020 •

edited

Loading

slorber commented Nov 25, 2020 •

edited

Loading

rylandg commented Dec 2, 2020

slorber commented Dec 3, 2020 •

edited

Loading

github-actions bot commented Dec 18, 2020 •

edited

Loading

github-actions bot commented Dec 18, 2020 •

edited

Loading

This comment has been minimized.

softwarecurator commented Jan 20, 2021

softwarecurator commented Jan 25, 2021

slorber left a comment •

edited

Loading

Josh-Cena commented Jan 8, 2022

Josh-Cena Jan 8, 2022

softwarecurator Jan 8, 2022

Josh-Cena Jan 8, 2022

softwarecurator Jan 8, 2022

Josh-Cena Jan 8, 2022 •

edited

Loading

slorber left a comment •

edited

Loading

feat(theme-classic): auto-collapse sibling categories in doc sidebar #3811

feat(theme-classic): auto-collapse sibling categories in doc sidebar #3811

Conversation

softwarecurator commented Nov 24, 2020 • edited Loading

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

netlify bot commented Nov 24, 2020 • edited Loading

slorber commented Nov 25, 2020 • edited Loading

rylandg commented Dec 2, 2020

slorber commented Dec 3, 2020 • edited Loading

github-actions bot commented Dec 18, 2020 • edited Loading

github-actions bot commented Dec 18, 2020 • edited Loading

This comment has been minimized.

softwarecurator commented Jan 20, 2021

softwarecurator commented Jan 25, 2021

slorber left a comment • edited Loading

Choose a reason for hiding this comment

Josh-Cena commented Jan 8, 2022

Josh-Cena Jan 8, 2022

Choose a reason for hiding this comment

softwarecurator Jan 8, 2022

Choose a reason for hiding this comment

Josh-Cena Jan 8, 2022

Choose a reason for hiding this comment

softwarecurator Jan 8, 2022

Choose a reason for hiding this comment

Josh-Cena Jan 8, 2022 • edited Loading

Choose a reason for hiding this comment

slorber left a comment • edited Loading

Choose a reason for hiding this comment

softwarecurator commented Nov 24, 2020 •

edited

Loading

netlify bot commented Nov 24, 2020 •

edited

Loading

slorber commented Nov 25, 2020 •

edited

Loading

slorber commented Dec 3, 2020 •

edited

Loading

github-actions bot commented Dec 18, 2020 •

edited

Loading

github-actions bot commented Dec 18, 2020 •

edited

Loading

slorber left a comment •

edited

Loading

Josh-Cena Jan 8, 2022 •

edited

Loading

slorber left a comment •

edited

Loading