Replies: 1 comment
-
Would it be possible to add a tag by typing the tag name in the search? I am thinking that a user could type something like "input" into the search and then if they select the tag it would also apply the filter as if you had clicked the filter button and selected one of the tags from the menu. Seems like that could be a future iteration because it would also require the search results UI to be updated. |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Summary
This RFC proposes a tags-based approach to improve organization in Storybook and reduce clutter. It includes a way to globally exclude stories from the sidebar and docs by tag, and a UI for interactively filtering the sidebar.
Problem Statement
This RFC attempts to solve two distinct problems:
Organization. Large Storybooks can become overwhelming, mixing components and stories from different teams, targeting different personas (e.g. developers vs designers), different states of completeness (unstable, alpha, stable, deprecated), and so forth. Storybook’s hierarchical sidebar can organize along a single dimension, but falls down once there are more attributes to encode.
Clutter. Storybooks can also contain stories that clutter the sidebar. For example, some stories are useful for automated testing, but aren’t meaningful documentation. Other stories just exist to be inline examples in the documentation, but are not intended to be in the sidebar.
Non-goals
Tags were introduced in 7.0 as a general way to add tag-like metadata to stories and components. The first tag was autodocs, which indicates to Storybook that it should auto-generate documentation for a component, and is unrelated to filtering. This RFC does not concern itself with non-filtering tags (although the existence of “other” tags is part of the design).
Implementation
We propose two different mechanisms to address the problems above.
Interactive filtering
For better organization, we propose a new URL parameter:
tagsFilter
, which accepts a comma-separated list of tags. If you open Storybook withtagsFilter=a,b
, it will only show stories in the sidebar that are tagged with'a'
or'b'
.The of tags can also be negated by prefixing with a hyphen
-
. If you open Storybook withtagsFilter=-a,-b
, it will hide stories in the sidebar that are tagged with'a'
or'b'
.We also propose a new UI for adjusting the filters interactively:
When you update the filters in the UI, they will persist in the URL so that you can link to your Storybook in a filtered state. In the example above, the URL would be updated with
tagsFilter=-design
.NOTE: that this filtering UI also constrains the search behavior, i.e. if the tag filtering excludes a story, that story will not be a candidate in the search results.
Static filtering
While the interactive filtering mechanism is pretty flexible, it is not great for reducing clutter. When you tag a story as
'docs-only'
, for example, it should simply disappear from the sidebar without requiring any adjustment to the URL or the UI that is required with the interactive filtering solution.To that end, we propose a
main.js
configuration that statically configures your tags:The configuration takes several optional fields:
excludeFromFilterUI
false
excludeFromSidebar
false
excludeFromDocsStories
false
We also propose the following built-in “system” tags to Storybook so that there is a zero-config solution to hiding docs-only and test-only stories, and to rationalize the existing built-in
autodocs
tag.Users and addons can also use the main.js / presets API to configure their own tags.
Prior Art
There are lots of tags implementations in the broader ecosystem. This proposal takes particular inspiration from Github labels and Notion tags.
Deliverables
There are two main deliverables:
excludeFromSidebar
andexcludeFromDocsStories
dev-only
,docs-only
, andtest-only
tagsexcludeFromFilterUI
tagsFilter
tagsFilter
Risks
This proposal has a few simplifying assumptions:
filterTags=a,-b
which is not possible to construct in the current UI, but which gives us room to grow the UI in the future if needed without making a breaking change to the URL structure.Unresolved Questions
None yet
Alternatives considered / Abandoned Ideas
No response
Beta Was this translation helpful? Give feedback.
All reactions