[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?