feat: allow searching and filtering doc sidebar items

[lex111]

Motivation

The idea for this feature came to me a bit spontaneously when I had a lot of time to think, so when I had the opportunity, I decided to implement it right away. It's not the final implementation, I guess it needs more elaboration in terms of performance and UX/UI.

In any case, this is roughly how it should work:

I think it's a pretty handy feature, which will be especially useful in sidebars with lots of items. The end-user can try to filter doc items by title (label) without using full text search. Google Web Docs (https://developers.google.com/ ) has a similar feature, for reference.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Preview

Related PRs

[netlify[bot]]

✅ [V2]

Name	Link
🔨 Latest commit	d2fa385eed35440d8e7a9ff5e09ac95f29cd4d6f
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/624b22c7f215350008f99f6b
😎 Deploy Preview	https://deploy-preview-6945--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[bot]]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🔴 Performance	43
🟢 Accessibility	100
🟢 Best practices	92
🟢 SEO	100
🟢 PWA	90

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

[github-actions[bot]]

Size Change: -750 B (0%)

Total Size: 806 kB

Filename	Size	Change
website/build/assets/css/styles.********.css	106 kB	+1.01 kB (+1%)
website/build/assets/js/main.********.js	611 kB	-1.85 kB (0%)
website/build/index.html	38.5 kB	+90 B (0%)

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	49.9 kB

_{compressed-size-action}

[Josh-Cena]

This produces a weird UX when combined with autocollapsing sidebar:

First is that the search expands all items, even when the query is later emptied. Currently, there's no way to fold them back on one click, so this could be rather inconvenient.

Second is that when a category is expanded before entering the query, the category becomes collapsed.

The collapsed state management is quite messy. If we can refactor that as well it would be great, but I don't know how to sort it out😅

[lex111]

Yep, I'm aware of this bug :(, so far I have not been able to fix it, at the moment it is the biggest problem with introducing this feature.

[Josh-Cena]

My idea is that we eventually need to implement some type of "global collapsed state store", managed at the sidebar level, not at each category level. However, there's currently no way to uniquely identify a sidebar item within the sidebar tree, like a "sidebar item key" that's both unique and persistent (i.e. not array index)

[lex111]

@slorber could you please take a look at this PR? Does this feature make sense in Docusaurus at all?

[slorber]

🤷‍♂️ not 100% convinced that this kind of UX is worth it. Have you seen this UX implemented anywhere so far? Why would users use this instead of the regular search?

At least it should probably not be enabled by default (and we don't have a way to add sidebar-specific config)

[Josh-Cena]

The TS-ESLint website will benefit from it: https://typescript-eslint.io/rules/

And yes, we should really figure out adding metadata for each sidebar very soon.

[lex111]

Yes, this feature can be useful in the case of categories with API functions for example. Or even just for doc sites like Redux, which have a lot of doc pages with pretty good titles for searching. The user can quickly find the desired function or page without using a regular full-text search which may not be available or produce too many irrelevant results. So using the filter is quite handy and easy for users in that case.

Docs sites that have a similar filter for reference:

• https://developers.google.com/drive/api/v3/reference (or any other developers Google site)
• https://developer.microsoft.com/en-us/fluentui#/styles/web
• https://docs.devexpress.com/TestCafeStudio/400157/testcafe-studio
• https://react.semantic-ui.com/

You can see how works the filter on these sites. I think the UI/UX in my implementation is not that bad, but I definitely need help with getting the filter to work nice with autocollapsing sidebar feature.

[slorber]

Thanks for the refs 👍 yes that looks like useful in some specific cases

I suggest postponing this implementation a bit because I planned to refactor the sidebar asap (was next on my list), so maybe it will be easier to implement/review once it's refactored.

we eventually need to implement some type of "global collapsed state store", managed at the sidebar level

Yes that's what I want to have too instead of state at every level

[lex111]

I curious if we can get this feature for the next release? Then when "global collapsed state store" is implemented, we just refactor the current implementation. How's that sound?

[slorber]

@lex111 as I mentioned in Discord I'd really like to focus on 2.0 launch. I only have a limited time and there are too many PRs to review for this to happen so I'm likely to not even take a look at this PR and other non-mandatory refactors until 2.0 is launched unfortunately, otherwise it will never happen 😅

[lex111]

@slorber I understand you, but it seems not so critical and risky change, perhaps we as an experiment can include it in the new beta release?

[Babilinski]

I think this would be helpful ^ especially when using Docusaurus for API docs. DocFX has something like this -https://docs.unity3d.com/Packages/[email protected]/manual/index.html

[sserrata]

I agree that this would be very useful when using Docusaurus for API docs. Now that 2.0 has been released, I'm happy to help test or work on this if there's still interest.