[RFC] default tag filter

[unional]

Summary

Introduce a way to define a default filter when the Storybook starts.

This idea can be extended to a Persona/Profile concept to quickly change the filter selection based on the current audience.

Problem Statement

Storybook can contain stories created for different reasons.

Filter by tags is a good way to quickly reduce the number of stories shown to de-clutter the Storybook, especially for designers and managers who may not be tech savvy.

Showing all stories and ask them to filter to a set of tags is still quite daunting to them.

At the same time, it is still beneficial to include all stories in the production Storybook so the engineers and package/app authors can rely on Storybook as the holy place to gather or validate information.

Non-goals

No response

Implementation

There are a few things can be done:

Enhance Filter capabilities

• Support Docs-only mode (hiding all stories)
• Support Select All/Clear All tag filters

Support Initial Filter values

For example:

// .storybook/main.ts

export default {
  filters: {
    init: {
      docsMode: boolean (default: false)
      tags: [] // default: none
      tags: ['*'] // all
      tags: ['tag-a', 'tag-b', ... ] // filter by include
      tags: ['!tag-a', '!tag-b', ...] // filter by exclude
    }
  }
}

(or) Support Persona/Profiles

// .storybook/main.ts

export default {
  persona: [{
    name: 'UX',
    docs: { docsMode: true }
  }, {
    name: 'Designer',
    docs: { docsMode: false },
    filters: {
      init: {
        docsMode: true,
        tags: [...]
      }
    }
  }, {
    name: 'Engineer',
    default: true, // first entry wins
    filters: {
      init: {
        docsMode: false,
        tags: [...]
      }
    }
  }, {
    name: 'Author',
    filters: {
      init: {
        docsMode: false,
        tags: [...]
      }
    }
  }]
}

Prior Art

No response

Deliverables

No response

Risks

No response

Unresolved Questions

• Using a to do list makes it easy to resolve the questions as we move the RFC along.

Alternatives considered / Abandoned Ideas

No response

[mrginglymus]

As I started populating my storybook with more chromatic stories, it became apparent that something like this was needed to allow me to develop the chromatic stories locally and see them, but not have them visible on my published storybook. A similar use case was QA wanting obscure stories for edge cases that were only relevant to them.

The quick and dirty solution I had to this was something like this:

// .storybook/manager.ts

import { GLOBALS_UPDATED } from "storybook/internal/core-events";
import type { Globals, API_FilterFunction } from "storybook/internal/types";
import { addons } from "storybook/manager-api";

function filter(persona: Globals["persona"]): API_FilterFunction {
  return function (item) {
    switch (item.type) {
      case "docs":
        return true;
      case "story":
        if (persona === "dev") {
          return !item.importPath.includes("chromatic");
        }
        return persona === "QA";
      default:
        return true;
    }
  };
}

addons.register("shenanigans", (api) => {
  void api.experimental_setFilter("shenanigans", filter("standard"));

  api.on(GLOBALS_UPDATED, ({ globals: { persona } }: { globals: Globals }) => {
    void api.experimental_setFilter("shenanigans", filter(persona));
  });
});

So - by default, only docs are visible. Devs can see full stories, QA can also see chromatic.

The implementation of this should be left very much up to the user - I haven't made extensive use of tags, in part because I'm still waiting for a meta.extend, but that along with a globalTypes.persona.toolbar definition in preview.tsx gets you a lot of the way there.

[mrginglymus]

I will attempt to generalise this into a plugin; probably something with a config on the line of:

type BasicFilter = {
  // Set to false to hide stories
  story?: boolean;
  // Set to false to hide docs
  docs?: boolean;
  // Only include the following tags
  tags?: string[];
}

type Config<Persona extends string> = {
  defaultPersona: Persona;
  personas: Record<Persona, BasicFilter | API_FilterFunction>;
}

[Sidnioulz]

@unional some of the things on this RFC are possible, but documentation for them is very difficult to stumble into. See below for applicable solutions.

Enhance Filter capabilities ✔️

Tip

A Storybook instance can be focused on documentation via the docsMode option. It's also possible to exclude stories from the sidebar using the !dev tag (but still show them in autodocs).
Select All and Clear All are available in the Storybook UI for filtering tags. It's also possible to filter to show all docs, stories or tests.

Support Initial Filter values ✔️

Tip

This is a well hidden feature, but it exists. You can configure the filter UI to include or exclude some tags by default. See examples in https://storybook.js.org/docs/writing-stories/tags#custom-tags.

 tags: {
   haha: {
     defaultFilterSelection: 'include',
   },
   hoho: {
     defaultFilterSelection: 'exclude',
   },
   'some-tag': {
     excludeFromSidebar: true,
   },
 },

---

I think we should look at this RFC from two perspectives:

• do we need to support alternative UIs for configuring tag filters (which can have implications on our filter APIs: do we want users to override / replace our own UI, or add their own custom filtering logic on top of ours? If so, how do both logics interact with each other (e.g. how do we count stories that would be included by a specific tag filter))
• how well do we document tag filtering exactly? Should we have a broader guide/tutorial on categorising content in Storybook, like we have guides for testing and visual testing? (cc @kylegach @jonniebigodes)

[unional]

Thanks for the info. I think defaultFilterSelection would definitely help.

I would like to look at it from use case perspective.

There is what I'm thinking of. The sub items are the kind of docs/stories they are interested in, in the order of importance to them:

A. As a designer consuming the library, I would like to see just the docs
  1. Documentation (MDX/autodocs/`docMode`)
B. As an engineer consuming the library,
   I would like to see the specification and use cases of the components,
   as well as any real world examples and edge cases I should aware of.
  1. Documentation
  2. Use Cases
  3. Examples
  4. Component specification
  5. Edge cases
C. As a designer working on the library,
   I would like to see the specification of each component.
  1. Component specification
  2. Documentation (to know what do the consuming designers see)
  3. Use Cases
D. As the author (developers),
   I would like to see all stories I have created
   (no order of importance in this case).
  - Documentation
  - Use Cases
  - Examples
  - Component specification
  - Edge cases
  - Unit Tests

With the current tag options, we can choose one of A/B/C as the target audience.
A persona or saving the filter selection in localStorage is needed to support multiple audiences.

I think the persona feature can build on top of the existing feature, not replacing it.
It can really be an addon, as long as Storybook provides an API to add the persona switcher on the sidebar.

[Sidnioulz]

@mrginglymus would you like to publish such an addon seeing as you've already put the pieces together? 😄

I'm also convinced that quick switching between presets offers a more flexible and powerful experience to teams than default filters in the Storybook UI. I think it's the only bit that's missing.

[mrginglymus]

@Sidnioulz I think that should be doable - will ping you in the new year about infra