[RFC] Story tags filtering

[shilman]

Update: An evolution of this RFC is available in 8.1.
See PR #26634 and docs at https://storybook.js.org/docs/8.1/writing-stories/tags
Search UI coming in a subsequent iteration

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 with tagsFilter=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 with tagsFilter=-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:

// main.js
tags: {
  a: { /* configuration for tag "a" */ },
}

The configuration takes several optional fields:

Field	Default	Description
excludeFromFilterUI	false	Don’t show this tag in the interactive filter UI
excludeFromSidebar	false	Don’t show stories with this tag in the sidebar.
excludeFromDocsStories	false	Don’t show stories with this tag in the Stories block, which lists stories in autodocs.

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.

const noUI = { excludeFromFilterUI: true }
export default {
  tags: {
    'docs-only': { ...noUI, excludeFromSidebar: true },
    'test-only': { ...noUI, excludeFromSidebar: true, excludeFromDocsStories: true },
    'dev-only': { ...noUI, excludeFromDocsStories: true }, // for completeness
    ‘autodocs’: { ...noUI },
  }
};

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:

• Static filtering
  • Main.js configuration for excludeFromSidebar and excludeFromDocsStories
  • Built-in dev-only, docs-only, and test-only tags
• Interactive filtering
  • Main.js configuration for excludeFromFilterUI
  • URL parameter support for tagsFilter
  • Sidebar UI for displaying/updating tagsFilter

Risks

This proposal has a few simplifying assumptions:

1. It is sufficient to exclude or include tags, and it is OK to not support complex combinations of exclusion & inclusion. Note that this risk is mitigated by the URL structure, which could accept 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.
2. Tags should show up in the filter UI by default. If the user uses lots of tags for other purpose, configuring them to hide from the filter UI would be tedious (but still possible).

Unresolved Questions

None yet

Alternatives considered / Abandoned Ideas

No response

[WalterWeidner]

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.

[yuri-scarbaci-lenio]

This would be extremely useful to also address scenarios where some stories gets created to be part of another story to show how iframe integrations would behave.

Our scenario would benefit a lot from being able to statistically-but-functionally define the tags tho, having to handle it at the "per story" level by adding/removing the tags per-story requires a lot of back and forth between files for completing a task that is arguably a "global" task (what does we want the sidebar to show? the filter to show? etc...)

Please consider an approach similar to what can be done via

addons.setConfig({
   ...
   patterns: (item) => bool
 })

so we can centralize the management of this without cluttering the RFC story declaration ( we have 2k stories, imagine searching the needle in that haystack without a centralized mechanism... )

also, if you actually give us a function to handle this, make sure you actually give us access to the "allStories" and "displayedStories" so while looping the stories we can handle scenarios like "if A exists, display B too" (which is needed for the microfront-end scenario I mentioned)

[shilman]

Can you clarify your request with more examples?

There is already a way to add a sidebar filter that's a function, which is used to implement the current tags filtering:

https://github.com/storybookjs/storybook/blob/next/code/lib/core-server/src/presets/common-manager.ts#L20-L27

Could you use this existing functionality to achieve what you want?

[yuri-scarbaci-lenio]

What I needed (and more info on why) is actually now part of storybook as per
#9209 (comment)

and this is your currently proposed api

which actually aligns with my previous comment request 🥇

thanks for this!

[yuri-scarbaci-lenio]

the only "missing" piece, which is more an API nice to have thing is

Given the way we need to use the storybook portal and other business requirement we want our "stories" to be void of storybook CSF syntaxes and just be components no more no less ( so without any storybook propietary syntax ), we want to be able to define the specific "story" parameters in the "index" centralized place
our currently workaround is isolate the "indexes" by "tags" and have the tags be defined as part of the default export

but it would be way better if we could do something like

export default {
  title: 'Components/TooltipV3/Examples',
  component: DSTooltipV3,
  parameters: {
    ...
  },
  URL_ONLY_IframeTooltipNoBoundries: {
    tags: ['no-sidebar']
  },
  ...
};
...
export { URL_ONLY_IframeTooltipNoBoundries } from './URL_ONLY_IframeTooltipNoBoundries';

[smlimasu]

Some other Ideas are to be able to use the tags to show badges or chips in other places.

For example to select a tag to be shown next to the doc/story in the sidebar, like the badges addon does, f.ex. "deprecated" or "new" or "version" tag.

It would be super cool if primary system tags like "design", "introduction", "components" could be configured to add a "new" heading section to the sidebars ui, maybe with a separator line to make the UI clearer to the users if you use the storybook like a design system for sections. Like if you guys do it in the sidebar when someone is composing different storybooks.

I have build myself a custom navbar which is displayed as a header bar, where I have 3-4 entries and a theme switcher to let users jump to the topics of my storybook. I am looking forward to use the tags filter function to configurate the shown sidebar entries when clicking on an entry there to have the visuals less overwhelming (when you have many components and unattached docs).

If I could add tags via meta to unattached, standalone MDX docs files that would also be cool.

Also, I build a custom tags component block that shows an array of tags as chips in the docs page over the docs title or over the story's title. These are meta-tags like "navigation" or "menu" and when a user clicks on it, it filters my (primary) stories for that.

If you guys ever implement a "stories overview" block that displays a grid of all stories (component overview or related docs overview) in smaller cards with links to that story or docs, it would be nice to have a tags filter on top of it - to filter for related entries to be shown. Could also be configurated in the preview file by the user with a tags array. I have build such an overview myself and found it pretty easy. My Cards display all tags under the storys title in the card and are also clickable.