This document is meant to make contributing to our Storybook a bit easier by giving some tips, pointing out a few gotchas, making the editing experience smoother, and reducing the friction to adding a new story.
## Adding new stories
To easily scaffold a new story for your component you need a few steps, but most things are already configured to reduce friction.
1. Make sure you add a `stories` directory within your component directory.
2. You can name the files within the directory however you want. Usually, it's best to have one `index.tsx` file including all your stories. However, if you are having several components under the same directory (e.g. `Chip` and `RemovableChip`), it might be best to have one file per component ([see below](#one-file-per-component)).
3. You will need a `default` export which defines the metadata for the component and one named export for each story you want to create.
Let's see the code in detail.
### Scaffold tour
This is the minimal scaffold you need for your new Story:
The above code will already generate a story that you can tweak, but let's look at the code in-depth.
First of all, by using TypeScript and exporting your component's props, Storybook will automatically show the documentation associated with your props and also generate the controls which are more appropriate for each property.
Also, if you follow the naming convention of starting your event handlers with `on` (e.g. `onChange`, `onRemove`, etc.), Storybook will automatically make those props uncontrollable and generate events from them (this convention can be changed in `preview.js`).
Sometimes you will need to manually change those assumptions, and we'll see how in a moment. But let's go step-by-step:
#### The `default` export
The default export defines the metadata for your component. The most important things you should be aware of:
```ts
{
/**
* This is how your component is going to be named in the Storybook UI.
* You can use slashed-paths to define hierarchies and categories.
* At the time of writing, we don't have well defined categories, but we
* are working on making that clearer.
*/
title: string;
/**
* You should always pass your component here.
*/
component: ComponentType<any>;
/**
* You can define here the default props for the components on all your
* stories. This is pretty useful when you have required props.
*/
args: Partial<MyComponentProps>;
/**
* Here you can define how the Storybook controls look like. More info
* below.
*/
argTypes: Partial<ArgTypes<MyComponentProps> >;
}
```
#### Defining controls
As mentioned, Storybook will try to infer the best control for your property type (e.g. an on/off switch for a `boolean`, etc.). However, there are times in which you want different options.
The recommended way to create a story is by creating a template function and duplicating it for each story, to avoid extra scaffolding. The simplest form of the template is as follows:
In this way, you are rendering the component in the viewport and binding the component properties to the Storybook controls.
In this template function, however, you might put any extra logic that your component rendering might need. Common use-cases are [wrapping them in context providers](#context-providers), or [simulating controlled components](#controlled-components).
#### Defining Stories
If you have followed this scaffold, defining a new story is as simple as this:
```ts
export const Default = Template.bind( {} );
```
Usually, you want a story with the name `Default`, and other stories with interesting variations of your component ([see below](#what-should-constitute-a-story)). In order to create those variations, you should work with some of the properties of this function prototype. Here are the most common:
```ts
{
/**
* Define the properties to pass for this specific story. Often,
*`Default` stories wouldn't even need this.
*/
args: Partial<MyComponentProps>;
/**
* You will rarely need this, as story names are automatically generated
* from your constant name. But that's good to know if you ever need.
If you are using [VSCode](https://code.visualstudio.com/), this repo includes some helpful snippets that will become available inside `.ts` and `.tsx` files. You can find them inside `.vscode/storybook.code-snippets`.
The `sbs` (“Storybook story”) will scaffold the entire code in the [section above](#scaffold-tour). If you have respected the naming conventions, it will also properly import your component and the properties with the correct names, saving you a bunch of time.
The `sbt` (“Storybook story template”) will create a new story by binding your default template and prompting you to provide specific arguments.
## FAQ
### What should constitute a story?
Stories should show the component in its different shapes.
The most obvious way is when a component has a few variations (such as a button with a `primary` attribute being larger and bolder, for example).
However, a common misconception is that, since full controls are enabled and allow the user to explore the component by playing around with its properties interactively, there is no need to provide stories which are just the component with different default properties.
While this is true for many cases (often you don't need to create a different story by replacing the `label` of a component, if that's just text; though it might be argued that it could be interesting to have a story showing how a very long text behaves, especially in [combined stories](#can-i-create-stories-with-mixed-components)), it is very useful to create stories for components in their loading or error states.
Yes, and it'd be awesome to see how our components interact with each other, especially in the context of blocks. At the time of writing, we have no such stories, however, here is a link to the official docs if you want to give a go at implementing this: <https://storybook.js.org/docs/react/writing-stories/stories-for-multiple-components>
While stories for closely related components could technically be living within the same file, we advise that you keep one file per component, as this works best with the automatic organization of the components within storybook and using [`default` exports in the Story](https://storybook.js.org/docs/react/api/csf#default-export).
An exception to this, might be when there is only one mainly used component and the other defined ones are just used internally.
E.g. compare `Chip/RemovableChip` with `ProductPrice/Sale/Range`. In the latter case, `Sale` and `Range` components are actually rendered depending on the props passed to the `ProductPrice` component, so they might as well be stories of their parent component.
### Custom controls
Sometimes the inferred text input is not good enough, and you need something more complex. If those controls happen to be shared among many components, please write them in `storybook/custom-controls`.
An example there is the `currency` control. Since many of our components expect `Currency` objects in their props, we can make sure we give a few examples Storybook users can play with, without having to manually create the object themselves.
// These are the options which will appear in the <select> control
options: Object.keys( currencies ),
};
```
Then we can just pass the `currencyControl` to our component `argTypes`.
```ts
export default {
// ...
argTypes: {
currency: currencyControl,
},
};
```
## Common gotchas and examples
### Named exports
Your component files can have `default` exports, but in order to play well with the automatic doc generation, they should **always** have named exports as well.
Your component is not managing its own state and expects it to be passed as a prop, but you want to create a self-contained story. You can then edit your main `Template` function to manage the state, for example through hooks.
You will notice that when you do this, your controls will not be in sync anymore: when you change the state through your story interaction, the control for `state` will not equal `myState`.
Often, it is enough to disable the control for `state` as it's not required.
If you want to keep them in sync, you'll have to use `useArgs` from the Storybook client API.
Note that this makes things a bit more complex, so it is recommended to do only when it makes sense for a controlled value to still have a Storybook control.
First of all, note that all the props starting with `on` as described above trigger “actions” in Storybook, which is basically just a way to see how data gets passed to a handler via the _Actions_ tab.
You can also manually mark props as actions in the `argTypes`, like so:
**However**, you might want to simulate some sort of behavior from your component, for example show how a `Retry` button triggers a loading state. In this case you can use `useArgs`:
🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce/issues/new?assignees=&labels=type%3A+documentation&template=suggestion-for-documentation-improvement-correction.md&title=Feedback%20on%20./docs/contributors/block-assets.md)
