Component Story Format 3.0

[shilman]

We just released experimental Component Story Format 3.0, a backwards-compatible improvement on Storybook stories.

CSF 3.0 eliminates boilerplate and adds support for scripted interactions:

• ♻️ Spreadable story objects for reuse
• 🌈 Default render functions for brevity
• 📓 Automatic titles for convenience
• ▶️ Play functions for scripted interaction
• ✅ 100% backwards compatible with CSF 2.0

We'd love your feedback to help us improve CSF3.0 through the 6.4 release cycle. Please comment below, or join us in the Storybook Discord in the #component-story-format channel. We've also labeled known issues with csf3.

If you're using Storybook 6.4 prerelease, turn on previewCsf3 in your .storybook/main.js config:

// .storybook/main.js
module.exports = {
  features: {
    previewCsfV3: true,
  }
};

CSF 3.0—except automatic title generation—is also available behind the same flag in SB 6.3.

[anilanar]

It would be great to extend CSF 3.0 to support dynamically creating an array of (named) stories.

In pseudo typescript, could be something like below:

export const group: Array<CSF3NamedExport> = [...]

and that would put those stories in a group named group, similar to how path separators in titles create new story groups.

[anilanar]

At Userlike, we already had an abstraction of some sorts over CSF 2.0 to have type safety (and to reduce boilerplate/weirdness). So with our abstraction, a story module looks as follows:

export default S.metadata({
  Component: Foobar,
  args: {
    ...
  },
  parameters: {
    ...
  }
});

export const example = S.story(Foobar);

export const example = S.story(Foobar, {
  args: {
    ...
  },
  parameters: {
    ...
  }
});

Function calls are usually easier to use than type annotations and allows us to manipulate options. For example, we have our own layout parameter (because storybook's layout param is lackluster). Another example is, migrating to CSF 3.0 will be trivial for us due to this abstraction. Otherwise, the main goal is to provide Typescript type safety for args and parameters (and others such as argTypes).

I'm not giving a concrete suggestion here, but when we switch to CSF 3.0, we will keep our abstraction because I think it's more powerful.

[shilman]

The problem with abstractions over CSF is that CSF codemods and other static analysis can't run against them. For example, starting in SB 7.0, we'll be analyzing the AST to quickly produce a list of stories in the sidebar (this is already implemented experimentally behind the feature flag storyStoreV7). We lose this ability with abstractions like yours. We might also provide a dynamic version, but it will be much slower to produce the list because it will need to execute each file.

[anilanar]

@shilman You could still analyze the AST quickly if you followed the same approach, by (optionally) allowing a function call like above, and the function would be imported from @storybook/{somewhere} so that you would know what to look for when parsing story files. This function, by default, can be equal to identity function. As an improvement, users can specify what function should be used instead in main.js, similar to emotion's use of importMap for their babel plugin.

What do we gain for the complexity? The first one is easier ts types and auto completion for js users. Another is a hook for users to maybe do additional stuff for these stories, that is not easily achievable by other means. For example, decorators, according to the public interface, cannot access args nor parameters that a story receives. You introduce render functions with CSF 3.0 but that doesn't entirely solve this problem. This function as a hook on the other hand, is capable of customizing stories further.

But I understand why you wouldn't do it too. Who's going go use it except us? 🤷 Maybe someone but who knows.

[shilman]

@anilanar CSF is an evolving standard and I won't rule anything out, but it definitely sounds more complex than we're equipped to deal with right now. cc @tmeasday

[anilanar]

Moving forward with CSF, what's the official stance on how to handle cases like component libraries in which each component has a few variants and perhaps each variant has a few sub-variants? And what about their visual reg. tests using chromatic?

[anilanar]

Usually, they are the same component with different props, such as <Button variant="solid" colorScheme="green" /> or something like <Input variant="outline" size="lg" isInvalid isDisabled />.

[tmeasday]

@anilanar I'm a little confused -- aren't these just classic stories?

[anilanar]

@tmeasday

Sorry for late response.

Displaying permutations of all variant vectors of a component and visual regression testing them in isolation is quite a common requirement. You can see that many component libraries are doing it. Sadly, dynamically generating permutations at runtime isn't compatible with CSF 3.0 and sometimes hand-typing all permutations is such a chore and deal breaker. Manually putting variants in a grid isn't ideal either.

e.g. https://github.com/chromaui/shapes/blob/master/src/components/Button.stories.tsx

This story only displays variants individually but not permutation of multiple variant vectors. E.g. maybe secondary disabled button in normal size looks fine but looks completely bonkers when large+compact.

[anilanar]

Chromatic covers this requirement specifically for viewports by internally implementing something to multiply stories. Storybook somewhat covers this requirement with controls addon but it's not exactly the same thing.

We somehow need a marriage of two approaches.

[tmeasday]

Hey @anilanar -- yes, this is a common request and definitely a feature we'd like to get into CSF at some stage. The name we've used here and there has been "story combos". I think the CSF3 pattern will dovetail quite well with it but there's a fair bit more still to figure out with it.

[webholics]

We are reusing stories a lot in other stories with CSF2:

export const Base = (args: FilterSelectFlyoutProps) => <FilterSelectFlyout {...args} />
Base.displayName = 'FilterSelectFlyout'
Base.args = {
  submitButton: <ButtonStory.Tiny {...ButtonStory.Tiny.args} />,
  children: 'Content',
}

But how is this supposed to work with CSF3? In this case stories are no functions anymore.

[anilanar]

@webholics

Like

export default {
  component: FilterSelectFlyout
};

export const Base = { args: { ... } };

If you want to make named export stories use different component than the default export, then I'm not sure. Hopefully named exports can also provide a component property. If not, this feature should be added to CSF 3.0 because render functions isn't exactly the same thing as in this case, we don't want args to be shared from the default export.
Or maybe with CSF 3.0, every module needs to represent a single component?

export const Base = { 
  component: FilterSelectFlyout,
  args: { ... },
};

[webholics]

I think this is the discussion I was searching for: #15954
Unfortunately there doesn't seem to be a final solution for now.

[fwouts]

Thank you for designing a simpler, more framework-independent format!

As far as I understand, CSF2 stories that encompass multiple components cannot be translated for CSF3. Here is a problematic example:

// buttons.stories.jsx (CSF2)

import { Button, LinkButton } from './buttons';

export default {
  title: "Button",
  component: Button,
}

export const Default = Button.bind({});
Default.args = {
  label: "a button"
};

export const Link = LinkButton.bind({});
Link.args = {
  label: "a link",
  href: "https://www.example.com"
};

Arguably, the most natural solution would be what @anilanar mentioned before, i.e. allowing each example to override the component property:

// buttons.stories.jsx (CSF3)

import { Button, LinkButton } from './buttons'.;

export default {
  title: "Button",
  component: Button,
}

export const Default = {
  args: {
    label: "a button"
  }
};

export const Link = {
  component: LinkButton,
  args: {
    label: "a button",
    href: "https://www.example.com"
  }
};

How much work would it be to support this? I'm asking because I plan to use CSF3 with this additional component property to store custom previews in Preview.js and I'd love if we can be aligned :)

[shilman]

We encourage users to group component stories by file, so that's why we only support the component at the file level.

However, it would be easy to support it at the story level too. I'd want to discuss with the team before committing to that, but there's nothing blocking us technically.

Currently, if you wanted to do that in CSF3, you could use custom render functions:

export const Link = {
  render: (args) => <LinkButton {...args} />,
  args: {
    label: "a button",
    href: "https://www.example.com"
  }
};

It's a little clunky, but it gives you all the flexibility of CSF2 if you need it.

[manuelmeister]

This is also so important for us. I think with MDX and the docs, storybook moves into a direction that is not only for dev documentation (in the sense of an API docs) but also for concept / design folks that want to test out the real thing. For this, I think it is very important to allow component definition on the story level, without the need for a render function. Because while it may not be the exact same component, it could be used for the same thing, and therefore be grouped on the same page.

[shilman]

cc @tmeasday

[aarjithn]

Saw this CSF3 as part of 7 beta announcement. Currently CSF2 stories are components and can use imported in Jest to run tests against it.

How is that going to work in CSF3 where exports are objects?

[anilanar]

@aarjithn I think what you are looking for is composeStories from https://www.npmjs.com/package/@storybook/testing-react

[aarjithn]

@anilanar Thank you! Exactly what I was looking for. Related note: I did not see this as part of CSF3 changelog, I think it would be good to mention it there since many might be using CSF2 stories directly without this.