Repository navigation
Replies: 1 comment 2 replies
How can it be cleared? What if we just defined the clear behavior to be "reset to default" instead? |
2 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment

Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Summary
Controlling which stories appear in the sidebar is currently spread across five options in two files, one of which is documented:
main.ts→tags[tag]defaultFilterSelectionmain.ts→tags[tag]excludeFromSidebarmain.ts→tags[tag]excludeFromDocsStoriesmanager.ts→setConfigsidebar.filtersmanager.ts→ addon APIexperimental_setFilterA new option,
hideFromFilterPanel, which hides a tag from the sidebar's filter menu without affecting which stories are shown, is in flight in #35397, implementing #34186.There is some redundancy between these APIs, and it's generally speaking difficult for our users to use tag filter options since documentation is so spotty.
This RFC proposes to:
setFilter(droppingexperimental_and documenting it)hideFromSidebarexcludeFromDocsStoriestohideFromAutodocshideFromFilterPanelPR UI: Allow hiding tags from sidebar filters #35397Motivation
Some undocumented options are implementation leftovers. They were introduced to power the
dev-only,docs-onlyandtest-onlybuilt-in tags. Those built-in tags were superseded bydev,autodocsandtest, which offer finer control, and were removed in 10.0. The options that powered them stayed, and were never documented.excludeFromDocsStoriesnames the implementation, not the feature. It reads as "exclude from the docs stories", but the feature it configures is autodocs.hideFromAutodocsis what a user would search for.Two mechanisms exist for hiding stories, and neither is fully supported.
excludeFromSidebaris undocumented; the sidebar filter API is undocumented andexperimental_-prefixed. Users pick whichever they happen to find. Whichever direction this RFC takes, one of the two should become the answer.Prior art
excludeFromFilterUI, alongside the two under discussion here. That third option is effectively what is landing now. If we are completing the original set, this is the moment to settle the naming.excludeFromSidebarused in the wild to strip internal stories from production builds, driven by an environment variable. Any migration path has to keep that possible.Current state
The documented ways to achieve comparable results are per-story rather than per-tag:
tags: ['autodocs', '!dev']to keep a story in docs but out of the sidebar, andtags: ['!autodocs']to do the reverse.Proposal
experimental_setFiltertosetFilter: Keep the prefixed name as a deprecated alias for the remainder of 10.x, remove it in 11.0.setFilter(id, () => true); considersetFilter(id, null)orremoveFilter(id), or documentsetFilter(id, () => true)as the way to gosetFiltercontract:excludeFromDocsStoriestohideFromAutodocs: ** MatcheshideFromFilterPanelfrom #35397; keep the old name until Storybook 12 if there's evidence of usageexcludeFromSidebartohideFromSidebar(so that all options that hide a tag in a part of the UI are called hideFrom*)sidebar.filtersfor SB 12 removal, as it's redundant withhideFromSidebarThis would give us the following config shape:
Design questions this proposal has to answer
hideFromSidebarjust a composition of the other two?defaultFilterSelection: 'exclude'plushideFromFilterPanel: truegets close: the stories are filtered out and the user has no control in the panel to bring them back. It is not identical because the default filter can be cleared, which would result in the stories showing up in the sidebar.Migration
excludeFromDocsStoriesandexperimental_setFilteraccepted with a deprecation warning for SB 11, remove in 12, listed in MIGRATION.md. Both are automigratable: the first is a static object literal key, the second a plain identifier rename.excludeFromSidebar→hideFromSidebaris a key rename, automigratablesidebar.filtersdeprecated for 11, removed in 12, not automigratableAlternatives considered
Consolidate on filter functions, and remove tag-level hiding entirely
Rather than making the declarative form real, remove
excludeFromSidebarandsidebar.filters, and let a stabilisedsetFilterbe the single way to hide stories. Users express hiding in code:This is the smaller change to make: it is deletion rather than reimplementation. Filter functions are also strictly more expressive: they can depend on globals, status, import path, etc and can change at runtime.
It is rejected for these reasons:
It can't fully consolidate config: Hiding a tag from the filter menu is a property of the tag, not a predicate over stories, so no filter function can express it.
hideFromFilterPanelhas to exist regardless. And so we still need amain.tsconfig endpoint.It converts configuration into code: A key in
main.tscan be read by automigrations, telemetry, editor tooling, etc.; a closure inside a bundled manager module cannot be read by any of them.Document
excludeFromSidebaras-is and change nothing elseThe cheapest option: write documentation for what already ships, rename nothing. But it would be harder to harmonise names later if we went that way. Creating a clearer separation of names between the default filter behaviour (which uses include/exclude as user-facing copy) and options that hide tagged content in specific parts of the UI would help with usability.
Move the docs concern to
parameters.docsThis scopes a docs option to the docs feature, follows the established pattern where doc blocks read configuration from
parameters.docs.*and accept the same settings as props, and would allow the exclusion set to be overridden per component or per story rather than only per project. It could also surface as a prop on theStoriesblock alongsideincludePrimaryandtitle, giving MDX and custom templates control they do not have today.The cost is that tag configuration would then live in two files: filter behaviour in
main.ts, docs behaviour inpreview.ts. For a user asking what a given tag does in their project, that is a worse starting point than one bag. Worth adopting if per-component control over docs exclusion is wanted on its own merits. Otherwise the rename is the smaller change and does not foreclose this later.Remove
excludeFromDocsStoriesin favour of!autodocsThe two overlap but are not interchangeable.
!autodocson a story removes that story from its docs page; on a meta it suppresses the docs page entirely.excludeFromDocsStoriesapplies to every story carrying a given tag, across every docs page, from one line of configuration.Removing it converts a project-level policy into per-story edits, and is unavailable where the project does not own the story files e.g. in composed Storybooks.
Open questions
excludeFromSidebaraffect today — only the sidebar tree, or also search, direct URL navigation,docsMode, and composed refs? Proposal A collapses if a filter function is not a true replacement, and Proposal B needs the answer to avoid a silent behaviour change during reimplementation.SET_FILTERevent part of the public contract, or an internal detail that happens to be observable?Out of scope
defaultFilterSelectionsemanticsAll reactions