mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-05 16:11:33 +08:00
writing stories
This commit is contained in:
Charles de Dreuille
parent
f376c6106a
commit
6cf15e0778
@ -163,10 +163,10 @@ However, providing the `Meta` Doc Block may not be required for certain use case
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
<Callout variant="info" icon="💡">
|
||||
If you're overriding an existing auto-generated documentation page enabled via [`tags`](./autodocs.md#setup-automated-docs) configuration property, we recommend removing it to avoid errors.
|
||||
If you're overriding an existing auto-generated documentation page enabled via [`tags`](./autodocs.mdx#setup-automated-docs) configuration property, we recommend removing it to avoid errors.
|
||||
</Callout>
|
||||
|
||||
Once the custom MDX documentation is loaded, Storybook will infer the title and location using the same heuristic rules to generate [auto-title stories](../configure/sidebar-and-urls.md#csf-30-auto-titles) and render it in the sidebar as a `Docs` entry.
|
||||
Once the custom MDX documentation is loaded, Storybook will infer the title and location using the same heuristic rules to generate [auto-title stories](../configure/user-interface/sidebar-and-urls.mdx#csf-30-auto-titles) and render it in the sidebar as a `Docs` entry.
|
||||
|
||||
#### Working with standalone documentation pages
|
||||
|
||||
@ -213,7 +213,7 @@ If you need to extend your documentation with additional content written in Mark
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
<Callout variant="info">
|
||||
The `Markdown` Doc Block provides additional configuration options to customize the rendering of your documentation. For more information, refer to the [API documentation](../api/doc-block-markdown.mdx).
|
||||
The `Markdown` Doc Block provides additional configuration options to customize the rendering of your documentation. For more information, refer to the [API documentation](../api/doc-blocks/doc-block-markdown.mdx).
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ A story is a component with a set of arguments that define how the component sho
|
||||
|
||||
When an arg’s value changes, the component re-renders, allowing you to interact with components in Storybook’s UI via addons that affect args.
|
||||
|
||||
Learn how and why to write stories in [the introduction](./index.md#using-args). For details on how args work, read on.
|
||||
Learn how and why to write stories in [the introduction](./index.mdx#using-args). For details on how args work, read on.
|
||||
|
||||
## Args object
|
||||
|
||||
@ -58,7 +58,7 @@ You can also define args at the global level; they will apply to every component
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
<Callout variant="info" icon="💡">
|
||||
For most uses of global args, [globals](../essentials/toolbars-and-globals.md) are a better tool for defining globally-applied settings, such as a theme. Using globals enables users to change the value with the toolbar menu.
|
||||
For most uses of global args, [globals](../essentials/toolbars-and-globals.mdx) are a better tool for defining globally-applied settings, such as a theme. Using globals enables users to change the value with the toolbar menu.
|
||||
</Callout>
|
||||
|
||||
## Args composition
|
||||
@ -99,7 +99,7 @@ Args are useful when writing stories for composite components that are assembled
|
||||
|
||||
## Setting args through the URL
|
||||
|
||||
You can also override the set of initial args for the active story by adding an `args` query parameter to the URL. Typically you would use the [Controls addon](../essentials/controls.md) to handle this. For example, here's how you could set a `size` and `style` arg in the Storybook's URL:
|
||||
You can also override the set of initial args for the active story by adding an `args` query parameter to the URL. Typically you would use the [Controls addon](../essentials/controls.mdx) to handle this. For example, here's how you could set a `size` and `style` arg in the Storybook's URL:
|
||||
|
||||
```
|
||||
?path=/story/avatar--default&args=style:rounded;size:100
|
||||
@ -146,7 +146,7 @@ Note that `mapping` does not have to be exhaustive. If the arg value is not a pr
|
||||
<details>
|
||||
<summary>Using args in addons</summary>
|
||||
|
||||
If you are [writing an addon](../addons/writing-addons.md) that wants to read or update args, use the `useArgs` hook exported by `@storybook/manager-api`:
|
||||
If you are [writing an addon](../addons/writing-addons.mdx) that wants to read or update args, use the `useArgs` hook exported by `@storybook/manager-api`:
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@ It's straightforward to write components to be fully presentational up to the sc
|
||||
The benefits:
|
||||
|
||||
* Easy to write stories once components are in this form.
|
||||
* All the data for the story is encoded in the args of the story, which works well with other parts of Storybook's tooling (e.g. [controls](../essentials/controls.md)).
|
||||
* All the data for the story is encoded in the args of the story, which works well with other parts of Storybook's tooling (e.g. [controls](../essentials/controls.mdx)).
|
||||
|
||||
The downsides:
|
||||
|
||||
@ -41,7 +41,7 @@ When you are building screens in this way, it is typical that the inputs of a co
|
||||
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
In such cases, it is natural to use [args composition](./args.md#args-composition) to build the stories for the page based on the stories of the sub-components:
|
||||
In such cases, it is natural to use [args composition](./args.mdx#args-composition) to build the stories for the page based on the stories of the sub-components:
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
@ -55,15 +55,15 @@ This approach is beneficial when the various subcomponents export a complex list
|
||||
|
||||
Connected components are components that depend on external data or services. For example, a full page component is often a connected component. When you render a connected component in Storybook, you need to mock the data or modules that the component depends on. There are various layers in which you can do that.
|
||||
|
||||
### [Mocking imports](./mocking-modules.md)
|
||||
### [Mocking imports](./mocking-data-and-modules/mocking-modules.mdx)
|
||||
|
||||
Components can depend on modules that are imported into the component file. These can be from external packages or internal to your project. When rendering those components in Storybook or testing them, you may want to mock those modules to control their behavior.
|
||||
|
||||
### [Mocking API Services](./mocking-network-requests.md)
|
||||
### [Mocking API Services](./mocking-data-and-modules/mocking-network-requests.mdx)
|
||||
|
||||
For components that make network requests (e.g., fetching data from a REST or GraphQL API), you can mock those requests in your stories.
|
||||
|
||||
### [Mocking providers](./mocking-providers.md)
|
||||
### [Mocking providers](./mocking-data-and-modules/mocking-providers.mdx)
|
||||
|
||||
Components can receive data or configuration from context providers. For example, a styled component might access its theme from a ThemeProvider or Redux uses React context to provide components access to app data. You can mock a provider and the value it's providing and wrap your component with it in your stories.
|
||||
|
||||
@ -118,7 +118,7 @@ Components can receive data or configuration from context providers. For example
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
<Callout variant="info">
|
||||
If the same context applies to all `ProfilePage` stories, we can use a [decorator](./decorators.md).
|
||||
If the same context applies to all `ProfilePage` stories, we can use a [decorator](./decorators.mdx).
|
||||
</Callout>
|
||||
|
||||
#### Providing containers to your application
|
||||
|
||||
@ -29,9 +29,9 @@ Some components require a “harness” to render in a useful way. For instance,
|
||||
|
||||
The second argument to a decorator function is the **story context** which contains the properties:
|
||||
|
||||
* `args` - the story arguments. You can use some [`args`](./args.md) in your decorators and drop them in the story implementation itself.
|
||||
* `argTypes`- Storybook's [argTypes](../api/arg-types.md) allow you to customize and fine-tune your stories [`args`](./args.md).
|
||||
* `globals` - Storybook-wide [globals](../essentials/toolbars-and-globals.md#globals). In particular you can use the [toolbars feature](../essentials/toolbars-and-globals.md#global-types-toolbar-annotations) to allow you to change these values using Storybook’s UI.
|
||||
* `args` - the story arguments. You can use some [`args`](./args.mdx) in your decorators and drop them in the story implementation itself.
|
||||
* `argTypes`- Storybook's [argTypes](../api/arg-types.mdx) allow you to customize and fine-tune your stories [`args`](./args.mdx).
|
||||
* `globals` - Storybook-wide [globals](../essentials/toolbars-and-globals.mdx#globals). In particular you can use the [toolbars feature](../essentials/toolbars-and-globals.mdx#global-types-toolbar-annotations) to allow you to change these values using Storybook’s UI.
|
||||
* `hooks` - Storybook's API hooks (e.g., useArgs).
|
||||
* `parameters`- the story's static metadata, most commonly used to control Storybook's behavior of features and addons.
|
||||
* `viewMode`- Storybook's current active window (e.g., canvas, docs).
|
||||
@ -46,12 +46,12 @@ This context can be used to adjust the behavior of your decorator based on the s
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
<Callout variant="info" icon="💡">
|
||||
For another example, see the section on [configuring the mock provider](./mocking-providers.md#configuring-the-mock-provider), which demonstrates how to use the same technique to change which theme is provided to the component.
|
||||
For another example, see the section on [configuring the mock provider](./mocking-data-and-modules/mocking-providers.mdx#configuring-the-mock-provider), which demonstrates how to use the same technique to change which theme is provided to the component.
|
||||
</Callout>
|
||||
|
||||
### Using decorators to provide data
|
||||
|
||||
If your components are “connected” and require side-loaded data to render, you can use decorators to provide that data in a mocked way without having to refactor your components to take that data as an arg. There are several techniques to achieve this. Depending on exactly how you are loading that data. Read more in the [building pages in Storybook](./build-pages-with-storybook.md) section.
|
||||
If your components are “connected” and require side-loaded data to render, you can use decorators to provide that data in a mocked way without having to refactor your components to take that data as an arg. There are several techniques to achieve this. Depending on exactly how you are loading that data. Read more in the [building pages in Storybook](./build-pages-with-storybook.mdx) section.
|
||||
|
||||
## Story decorators
|
||||
|
||||
@ -63,7 +63,7 @@ To define a decorator for a single story, use the `decorators` key on a named ex
|
||||
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
It is useful to ensure that the story remains a “pure” rendering of the component under test and that any extra HTML or components are used only as decorators. In particular the [Source](../api/doc-block-source.md) Doc Block works best when you do this.
|
||||
It is useful to ensure that the story remains a “pure” rendering of the component under test and that any extra HTML or components are used only as decorators. In particular the [Source](../api/doc-blocks/doc-block-source.mdx) Doc Block works best when you do this.
|
||||
|
||||
## Component decorators
|
||||
|
||||
@ -77,7 +77,7 @@ To define a decorator for all stories of a component, use the `decorators` key o
|
||||
|
||||
## Global decorators
|
||||
|
||||
We can also set a decorator for **all stories** via the `decorators` export of your [`.storybook/preview.js`](../configure/index.md#configure-story-rendering) file (this is the file where you configure all stories):
|
||||
We can also set a decorator for **all stories** via the `decorators` export of your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering) file (this is the file where you configure all stories):
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
|
||||
@ -24,7 +24,7 @@ components/
|
||||
|
||||
## Component Story Format
|
||||
|
||||
We define stories according to the [Component Story Format](../api/csf.md) (CSF), an ES6 module-based standard that is easy to write and portable between tools.
|
||||
We define stories according to the [Component Story Format](../api/csf.mdx) (CSF), an ES6 module-based standard that is easy to write and portable between tools.
|
||||
|
||||
The key ingredients are the [default export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#Using_the_default_export) that describes the component, and [named exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#Using_named_exports) that describe the stories.
|
||||
|
||||
@ -55,7 +55,7 @@ Use the *named* exports of a CSF file to define your component’s stories. We r
|
||||
<IfRenderer renderer="react">
|
||||
#### Working with React Hooks
|
||||
|
||||
[React Hooks](https://react.dev/reference/react) are convenient helper methods to create components using a more streamlined approach. You can use them while creating your component's stories if you need them, although you should treat them as an advanced use case. We **recommend** [args](./args.md) as much as possible when writing your own stories. As an example, here’s a story that uses React Hooks to change the button's state:
|
||||
[React Hooks](https://react.dev/reference/react) are convenient helper methods to create components using a more streamlined approach. You can use them while creating your component's stories if you need them, although you should treat them as an advanced use case. We **recommend** [args](./args.mdx) as much as possible when writing your own stories. As an example, here’s a story that uses React Hooks to change the button's state:
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
@ -67,7 +67,7 @@ Use the *named* exports of a CSF file to define your component’s stories. We r
|
||||
<IfRenderer renderer="solid">
|
||||
#### Working with Solid Signals
|
||||
|
||||
[Solid Signals](https://www.solidjs.com/docs/latest/api#basic-reactivity) are convenient helper methods to create components using a more streamlined approach. You can use them while creating your component's stories if you need them, although you should treat them as an advanced use case. We **recommend** [args](./args.md) as much as possible when writing your own stories. As an example, here’s a story that uses Solid Signals to change the button's state:
|
||||
[Solid Signals](https://www.solidjs.com/docs/latest/api#basic-reactivity) are convenient helper methods to create components using a more streamlined approach. You can use them while creating your component's stories if you need them, although you should treat them as an advanced use case. We **recommend** [args](./args.mdx) as much as possible when writing your own stories. As an example, here’s a story that uses Solid Signals to change the button's state:
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
@ -112,7 +112,7 @@ What’s more, you can import `args` to reuse when writing stories for other com
|
||||
|
||||
When Button’s signature changes, you only need to change Button’s stories to reflect the new schema, and ButtonGroup’s stories will automatically be updated. This pattern allows you to reuse your data definitions across the component hierarchy, making your stories more maintainable.
|
||||
|
||||
That’s not all! Each of the args from the story function are live editable using Storybook’s [Controls](../essentials/controls.md) panel. It means your team can dynamically change components in Storybook to stress test and find edge cases.
|
||||
That’s not all! Each of the args from the story function are live editable using Storybook’s [Controls](../essentials/controls.mdx) panel. It means your team can dynamically change components in Storybook to stress test and find edge cases.
|
||||
|
||||
<Video src="../_assets/writing-stories/addon-controls-demo-optimized.mp4" />
|
||||
|
||||
@ -120,7 +120,7 @@ You can also use the Controls panel to edit or save a new story after adjusting
|
||||
|
||||
<Video src="../_assets/get-started/edit-story-from-controls-optimized.mp4" />
|
||||
|
||||
Addons can enhance args. For instance, [Actions](../essentials/actions.md) auto-detects which args are callbacks and appends a logging function to them. That way, interactions (like clicks) get logged in the actions panel.
|
||||
Addons can enhance args. For instance, [Actions](../essentials/actions.mdx) auto-detects which args are callbacks and appends a logging function to them. That way, interactions (like clicks) get logged in the actions panel.
|
||||
|
||||
<Video src="../_assets/writing-stories/addon-actions-demo-optimized.mp4" />
|
||||
|
||||
@ -148,7 +148,7 @@ For instance, suppose you wanted to test your Button component against a differe
|
||||
|
||||
|
||||
|
||||
This parameter would instruct the backgrounds addon to reconfigure itself whenever a Button story is selected. Most addons are configured via a parameter-based API and can be influenced at a [global](./parameters.md#global-parameters), [component](./parameters.md#component-parameters) and [story](./parameters.md#story-parameters) level.
|
||||
This parameter would instruct the backgrounds addon to reconfigure itself whenever a Button story is selected. Most addons are configured via a parameter-based API and can be influenced at a [global](./parameters.mdx#global-parameters), [component](./parameters.mdx#component-parameters) and [story](./parameters.mdx#story-parameters) level.
|
||||
|
||||
### Using decorators
|
||||
|
||||
@ -162,7 +162,7 @@ A simple example is adding padding to a component’s stories. Accomplish this u
|
||||
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
Decorators [can be more complex](./decorators.md#context-for-mocking) and are often provided by [addons](../configure/storybook-addons.md). You can also configure decorators at the [story](./decorators.md#story-decorators), [component](./decorators.md#component-decorators) and [global](./decorators.md#global-decorators) level.
|
||||
Decorators [can be more complex](./decorators.mdx#context-for-mocking) and are often provided by [addons](../configure/user-interface/storybook-addons.mdx). You can also configure decorators at the [story](./decorators.mdx#story-decorators), [component](./decorators.mdx#component-decorators) and [global](./decorators.mdx#global-decorators) level.
|
||||
|
||||
## Stories for two or more components
|
||||
|
||||
@ -191,5 +191,5 @@ You can also reuse *story data* from the child `ListItem` in your `List` compone
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
<Callout variant="info" icon="💡">
|
||||
Note that there are disadvantages in writing stories like this as you cannot take full advantage of the args mechanism and composing args as you build even more complex composite components. For more discussion, see the [multi component stories](../writing-stories/stories-for-multiple-components.md) workflow documentation.
|
||||
Note that there are disadvantages in writing stories like this as you cannot take full advantage of the args mechanism and composing args as you build even more complex composite components. For more discussion, see the [multi component stories](../writing-stories/stories-for-multiple-components.mdx) workflow documentation.
|
||||
</Callout>
|
||||
|
||||
@ -5,15 +5,15 @@ sidebar:
|
||||
title: Loaders
|
||||
---
|
||||
|
||||
Loaders are asynchronous functions that load data for a story and its [decorators](./decorators.md). A story's loaders run before the story renders, and the loaded data injected into the story via its render context.
|
||||
Loaders are asynchronous functions that load data for a story and its [decorators](./decorators.mdx). A story's loaders run before the story renders, and the loaded data injected into the story via its render context.
|
||||
|
||||
Loaders can be used to load any asset, lazy load components, or fetch data from a remote API. This feature was designed as a performance optimization to handle large story imports. However, [args](./args.md) is the recommended way to manage story data. We're building up an ecosystem of tools and techniques around Args that might not be compatible with loaded data.
|
||||
Loaders can be used to load any asset, lazy load components, or fetch data from a remote API. This feature was designed as a performance optimization to handle large story imports. However, [args](./args.mdx) is the recommended way to manage story data. We're building up an ecosystem of tools and techniques around Args that might not be compatible with loaded data.
|
||||
|
||||
They are an advanced feature (i.e., escape hatch), and we only recommend using them if you have a specific need that other means can't fulfill.
|
||||
|
||||
## Fetching API data
|
||||
|
||||
Stories are isolated component examples that render internal data defined as part of the story or alongside the story as [args](./args.md).
|
||||
Stories are isolated component examples that render internal data defined as part of the story or alongside the story as [args](./args.mdx).
|
||||
|
||||
Loaders are helpful when you need to load story data externally (e.g., from a remote API). Consider the following example that fetches a todo item to display in a todo list:
|
||||
|
||||
@ -27,7 +27,7 @@ The response obtained from the remote API call is combined into a `loaded` field
|
||||
|
||||
## Global loaders
|
||||
|
||||
We can also set a loader for **all stories** via the `loaders` export of your [`.storybook/preview.js`](../configure/index.md#configure-story-rendering) file (this is the file where you configure all stories):
|
||||
We can also set a loader for **all stories** via the `loaders` export of your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering) file (this is the file where you configure all stories):
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
@ -39,7 +39,7 @@ In this example, we load a "current user" available as `loaded.currentUser` for
|
||||
|
||||
## Loader inheritance
|
||||
|
||||
Like [parameters](./parameters.md), loaders can be defined globally, at the component level, and for a single story (as we’ve seen).
|
||||
Like [parameters](./parameters.mdx), loaders can be defined globally, at the component level, and for a single story (as we’ve seen).
|
||||
|
||||
All loaders, defined at all levels that apply to a story, run before the story renders in Storybook's canvas.
|
||||
|
||||
|
||||
@ -60,7 +60,7 @@ export const uuidv4 = fn(actual.uuidv4).mockName('uuidv4');
|
||||
|
||||
## Subpath imports
|
||||
|
||||
The recommended method for mocking modules is to use [subpath imports](https://nodejs.org/api/packages.html#subpath-imports), a feature of Node packages that is supported by both [Vite](../builders/vite.md) and [Webpack](../builders/webpack.md).
|
||||
The recommended method for mocking modules is to use [subpath imports](https://nodejs.org/api/packages.html#subpath-imports), a feature of Node packages that is supported by both [Vite](../builders/vite.mdx) and [Webpack](../../builders/webpack.mdx).
|
||||
|
||||
To configure subpath imports, you define the `imports` property in your project's `package.json` file. This property maps the subpath to the actual file path. The example below configures subpath imports for four internal modules:
|
||||
|
||||
@ -119,12 +119,12 @@ Here, we define `beforeEach` on a story (which will run before the story is rend
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
<Callout variant="info">
|
||||
If you are [writing your stories in TypeScript](./typescript.md), you must import your mock modules using the full mocked file name to have the functions correctly typed in your stories. You do **not** need to do this in your component files. That's what the [subpath import](#subpath-imports) or [builder alias](#builder-aliases) is for.
|
||||
If you are [writing your stories in TypeScript](../typescript.mdx), you must import your mock modules using the full mocked file name to have the functions correctly typed in your stories. You do **not** need to do this in your component files. That's what the [subpath import](#subpath-imports) or [builder alias](#builder-aliases) is for.
|
||||
</Callout>
|
||||
|
||||
### Spying on mocked modules
|
||||
|
||||
The `fn` utility also spies on the original module's functions, which you can use to assert their behavior in your tests. For example, you can use [interaction tests](../writing-tests/interaction-testing.md) to verify that a function was called with specific arguments.
|
||||
The `fn` utility also spies on the original module's functions, which you can use to assert their behavior in your tests. For example, you can use [interaction tests](../../writing-tests/interaction-testing.mdx) to verify that a function was called with specific arguments.
|
||||
|
||||
For example, this story checks that the `saveNote` function was called when the user clicks the save button:
|
||||
|
||||
@ -141,7 +141,7 @@ Before the story renders, you can use the asynchronous `beforeEach` function to
|
||||
You can also return a cleanup function from `beforeEach` which will be called after your story unmounts. This is useful for tasks like unsubscribing observers, etc.
|
||||
|
||||
<Callout variant="info">
|
||||
It is *not* necessary to restore `fn()` mocks with the cleanup function, as Storybook will already do that automatically before rendering a story. See the [`parameters.test.restoreMocks` API](../api/parameters.md#restoremocks) for more information.
|
||||
It is *not* necessary to restore `fn()` mocks with the cleanup function, as Storybook will already do that automatically before rendering a story. See the [`parameters.test.restoreMocks` API](../../api/parameters.mdx#restoremocks) for more information.
|
||||
</Callout>
|
||||
|
||||
Here's an example of using the [`mockdate`](https://github.com/boblauer/MockDate) package to mock the [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) and reset it when the story unmounts.
|
||||
|
||||
@ -33,7 +33,7 @@ If you're not already using MSW, generate the service worker file necessary for
|
||||
</Callout>
|
||||
</If>
|
||||
|
||||
Then ensure the [`staticDirs`](../api/main-config-static-dirs.md) property in your Storybook configuration will include the generated service worker file (in `/public`, by default):
|
||||
Then ensure the [`staticDirs`](../../api/main-config/main-config-static-dirs.mdx) property in your Storybook configuration will include the generated service worker file (in `/public`, by default):
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
@ -41,7 +41,7 @@ Then ensure the [`staticDirs`](../api/main-config-static-dirs.md) property in yo
|
||||
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
Finally, initialize the addon and apply it to all stories with a [project-level loader](./loaders.md#global-loaders):
|
||||
Finally, initialize the addon and apply it to all stories with a [project-level loader](../loaders.mdx#global-loaders):
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
@ -95,4 +95,4 @@ The MSW addon allows you to write stories that use MSW to mock the GraphQL reque
|
||||
|
||||
## Configuring MSW for stories
|
||||
|
||||
In the examples above, note how each story is configured with `parameters.msw` to define the request handlers for the mock server. Because it uses parameters in this way, it can also be configured at the [component](./parameters.md#component-parameters) or even [project](./parameters.md#global-parameters) level, allowing you to share the same mock server configuration across multiple stories.
|
||||
In the examples above, note how each story is configured with `parameters.msw` to define the request handlers for the mock server. Because it uses parameters in this way, it can also be configured at the [component](../parameters.mdx#component-parameters) or even [project](../parameters.mdx#global-parameters) level, allowing you to share the same mock server configuration across multiple stories.
|
||||
|
||||
@ -14,7 +14,7 @@ sidebar:
|
||||
</If>
|
||||
|
||||
<If renderer={['preact', 'react', 'solid']}>
|
||||
Components can receive data or configuration from context providers. For example, a styled component might access its theme from a ThemeProvider or Redux uses React context to provide components access to app data. To mock a provider, you can wrap your component in a [decorator](./decorators.md) that includes the necessary context.
|
||||
Components can receive data or configuration from context providers. For example, a styled component might access its theme from a ThemeProvider or Redux uses React context to provide components access to app data. To mock a provider, you can wrap your component in a [decorator](../decorators.mdx) that includes the necessary context.
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
@ -38,7 +38,7 @@ sidebar:
|
||||
|
||||
One way to do this is to define the decorator for each story individually. But if you imagine a scenario where you wish to create stories for each of your components in both light and dark themes, this approach can quickly become cumbersome.
|
||||
|
||||
For a better way, with much less repetition, you can use the [decorator function's second "context" argument](./decorators.md#context-for-mocking) to access a story's [`parameters`](./parameters.md) and adjust the provided value. This way, you can define the provider once and adjust its value for each story.
|
||||
For a better way, with much less repetition, you can use the [decorator function's second "context" argument](../decorators.mdx#context-for-mocking) to access a story's [`parameters`](./parameters.mdx) and adjust the provided value. This way, you can define the provider once and adjust its value for each story.
|
||||
|
||||
For example, we can adjust the decorator from above to read from `parameters.theme` to determine which theme to provide:
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ Storybook provides a powerful way to organize your stories, giving you the neces
|
||||
|
||||
## Structure and hierarchy
|
||||
|
||||
When organizing your Storybook, there are two methods of structuring your stories: **implicit** and **explicit**. The [implicit method](../configure/sidebar-and-urls.md#csf-30-auto-titles) involves relying upon the physical location of your stories to position them in the sidebar, while the [explicit method](#naming-stories) involves utilizing the `title` parameter to place the story.
|
||||
When organizing your Storybook, there are two methods of structuring your stories: **implicit** and **explicit**. The [implicit method](../configure/user-interface/sidebar-and-urls.mdx#csf-30-auto-titles) involves relying upon the physical location of your stories to position them in the sidebar, while the [explicit method](#naming-stories) involves utilizing the `title` parameter to place the story.
|
||||
|
||||
|
||||
|
||||
@ -20,7 +20,7 @@ Based on how you structure your Storybook, you can see that the story hierarchy
|
||||
* **Category**: The top-level grouping of stories and documentation pages generated by Storybook
|
||||
* **Folder**: A mid-level organizational unit that groups components and stories in the sidebar, representing a feature or section of your application
|
||||
* **Component**: A low-level organizational unit representing the component that the story is testing
|
||||
* **Docs**: The automatically generated [documentation page](../writing-docs/autodocs.md) for the component
|
||||
* **Docs**: The automatically generated [documentation page](../writing-docs/autodocs.mdx) for the component
|
||||
* **Story**: The individual story testing a specific component state
|
||||
|
||||
## Naming stories
|
||||
@ -59,7 +59,7 @@ Yields this:
|
||||
|
||||
## Roots
|
||||
|
||||
By default, the top-level grouping will be displayed as “root” in the Storybook UI (i.e., the uppercased, non-expandable items). If you need, you can [configure Storybook](../configure/sidebar-and-urls.md#roots) and disable this behavior. Useful if you need to provide a streamlined experience for your users; nevertheless, if you have a large Storybook composed of multiple component stories, we recommend naming your components according to the file hierarchy.
|
||||
By default, the top-level grouping will be displayed as “root” in the Storybook UI (i.e., the uppercased, non-expandable items). If you need, you can [configure Storybook](../configure/user-interface/sidebar-and-urls.mdx#roots) and disable this behavior. Useful if you need to provide a streamlined experience for your users; nevertheless, if you have a large Storybook composed of multiple component stories, we recommend naming your components according to the file hierarchy.
|
||||
|
||||
## Single-story hoisting
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ sidebar:
|
||||
Parameters are a set of static, named metadata about a story, typically used to control the behavior of Storybook features and addons.
|
||||
|
||||
<Callout variant="info">
|
||||
Available parameters are listed in the [parameters API reference](../api/parameters.md#available-parameters).
|
||||
Available parameters are listed in the [parameters API reference](../api/parameters.mdx#available-parameters).
|
||||
</Callout>
|
||||
|
||||
For example, let’s customize the backgrounds addon via a parameter. We’ll use `parameters.backgrounds` to define which backgrounds appear in the backgrounds toolbar when a story is selected.
|
||||
@ -37,7 +37,7 @@ We can set the parameters for all stories of a component using the `parameters`
|
||||
|
||||
## Global parameters
|
||||
|
||||
We can also set the parameters for **all stories** via the `parameters` export of your [`.storybook/preview.js`](../configure/index.md#configure-story-rendering) file (this is the file where you configure all stories):
|
||||
We can also set the parameters for **all stories** via the `parameters` export of your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering) file (this is the file where you configure all stories):
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
@ -56,4 +56,4 @@ The way the global, component and story parameters are combined is:
|
||||
|
||||
The merging of parameters is important. It means it is possible to override a single specific sub-parameter on a per-story basis but still retain the majority of the parameters defined globally.
|
||||
|
||||
If you are defining an API that relies on parameters (e.g. an [**addon**](../addons/index.md)) it is a good idea to take this behavior into account.
|
||||
If you are defining an API that relies on parameters (e.g. an [**addon**](../addons/index.mdx)) it is a good idea to take this behavior into account.
|
||||
|
||||
@ -40,14 +40,14 @@ Storybook's `play` functions are small code snippets that run once the story fin
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
<Callout variant="info" icon="💡">
|
||||
See the [Interaction testing documentation](../writing-tests/interaction-testing.md#api-for-user-events) for an overview of the available API events.
|
||||
See the [Interaction testing documentation](../writing-tests/interaction-testing.mdx#api-for-user-events) for an overview of the available API events.
|
||||
</Callout>
|
||||
|
||||
When Storybook finishes rendering the story, it executes the steps defined within the `play` function, interacting with the component and filling the form's information. All of this without the need for user intervention. If you check your `Interactions` panel, you'll see the step-by-step flow.
|
||||
|
||||
## Composing stories
|
||||
|
||||
Thanks to the [Component Story Format](../api/csf.md), an ES6 module based file format, you can also combine your `play` functions, similar to other existing Storybook features (e.g., [args](./args.md)). For example, if you wanted to verify a specific workflow for your component, you could write the following stories:
|
||||
Thanks to the [Component Story Format](../api/csf.mdx), an ES6 module based file format, you can also combine your `play` functions, similar to other existing Storybook features (e.g., [args](./args.mdx)). For example, if you wanted to verify a specific workflow for your component, you could write the following stories:
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ sidebar:
|
||||
title: Stories for multiple components
|
||||
---
|
||||
|
||||
It's useful to write stories that [render two or more components](./index.md#stories-for-two-or-more-components) at once if those components are designed to work together. For example, `ButtonGroup`, `List`, and `Page` components.
|
||||
It's useful to write stories that [render two or more components](./index.mdx#stories-for-two-or-more-components) at once if those components are designed to work together. For example, `ButtonGroup`, `List`, and `Page` components.
|
||||
|
||||
## Subcomponents
|
||||
|
||||
@ -19,14 +19,14 @@ Here's an example with `List` and `ListItem` components:
|
||||
|
||||
{/* prettier-ignore-end */}
|
||||
|
||||
Note that by adding a `subcomponents` property to the default export, we get an extra panel on the [ArgTypes](../writing-docs/doc-blocks.md#argtypes) and [Controls](../essentials/controls.md#) tables, listing the props of `ListItem`:
|
||||
Note that by adding a `subcomponents` property to the default export, we get an extra panel on the [ArgTypes](../writing-docs/doc-blocks.mdx#argtypes) and [Controls](../essentials/controls.mdx#) tables, listing the props of `ListItem`:
|
||||
|
||||
|
||||
|
||||
Subcomponents are only intended for documentation purposes and have some limitations:
|
||||
|
||||
1. The [argTypes](../api/arg-types.md) of subcomponents are [inferred (for the renderers that support that feature)](../api/arg-types.md#automatic-argtype-inference) and cannot be manually defined or overridden.
|
||||
2. The table for each documented subcomponent does *not* include [controls](../essentials/controls.md) to change the value of the props, because controls always apply to the main component's args.
|
||||
1. The [argTypes](../api/arg-types.mdx) of subcomponents are [inferred (for the renderers that support that feature)](../api/arg-types.mdx#automatic-argtype-inference) and cannot be manually defined or overridden.
|
||||
2. The table for each documented subcomponent does *not* include [controls](../essentials/controls.mdx) to change the value of the props, because controls always apply to the main component's args.
|
||||
|
||||
Let's talk about some techniques you can use to mitigate the above, which are especially useful in more complicated situations.
|
||||
|
||||
@ -62,7 +62,7 @@ By rendering the `Unchecked` story with its args, we are able to reuse the input
|
||||
The `children` arg, just like all args, needs to be JSON serializable. To avoid errors with your Storybook, you should:
|
||||
|
||||
* Avoid using empty values
|
||||
* Use [mapping](../essentials/controls.md#dealing-with-complex-values) if you want to adjust the value with [controls](../essentials/controls.md)
|
||||
* Use [mapping](../essentials/controls.mdx#dealing-with-complex-values) if you want to adjust the value with [controls](../essentials/controls.mdx)
|
||||
* Use caution with components that include third party libraries
|
||||
|
||||
<Callout variant="info">
|
||||
|
||||
@ -5,7 +5,7 @@ sidebar:
|
||||
title: Tags
|
||||
---
|
||||
|
||||
Tags allow you to control which stories are included in your Storybook, enabling many different uses of the same total set of stories. For example, you can use tags to include/exclude tests from the [test runner](../writing-tests/test-runner.md#run-tests-for-a-subset-of-stories). For more complex use cases, see the [recipes](#recipes) section, below.
|
||||
Tags allow you to control which stories are included in your Storybook, enabling many different uses of the same total set of stories. For example, you can use tags to include/exclude tests from the [test runner](../writing-tests/test-runner.mdx#run-tests-for-a-subset-of-stories). For more complex use cases, see the [recipes](#recipes) section, below.
|
||||
|
||||
## Built-in tags
|
||||
|
||||
@ -13,9 +13,9 @@ The following tags are available in every Storybook project:
|
||||
|
||||
| Tag | Applied by default? | Description |
|
||||
| ---------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `autodocs` | No | Stories tagged with `autodocs` will be included in the [docs page](../writing-docs/autodocs.md). If a CSF file does not contain at least one story tagged with `autodocs`, that component will not generate a docs page. |
|
||||
| `autodocs` | No | Stories tagged with `autodocs` will be included in the [docs page](../writing-docs/autodocs.mdx). If a CSF file does not contain at least one story tagged with `autodocs`, that component will not generate a docs page. |
|
||||
| `dev` | Yes | Stories tagged with `dev` are rendered in Storybook's sidebar. |
|
||||
| `test` | Yes | Stories tagged with `test` do not currently affect Storybook's UI, but can be used to filter the [test runner](../writing-tests/test-runner.md#run-tests-for-a-subset-of-stories). |
|
||||
| `test` | Yes | Stories tagged with `test` do not currently affect Storybook's UI, but can be used to filter the [test runner](../writing-tests/test-runner.mdx#run-tests-for-a-subset-of-stories). |
|
||||
|
||||
The `dev` and `test` tags are automatically, implicitly applied to every story in your Storybook project.
|
||||
|
||||
@ -55,7 +55,7 @@ Tags can be removed for all stories in your project (in `.storybook/preview.js|t
|
||||
|
||||
### Docs-only stories
|
||||
|
||||
It can sometimes be helpful to provide example stories for documentation purposes, but you want to keep the sidebar navigation more focused on stories useful for development. By enabling the `autodocs` tag and removing the `dev` tag, a story becomes docs-only: appearing only in the [docs page](../writing-docs/autodocs.md) and not in Storybook's sidebar.
|
||||
It can sometimes be helpful to provide example stories for documentation purposes, but you want to keep the sidebar navigation more focused on stories useful for development. By enabling the `autodocs` tag and removing the `dev` tag, a story becomes docs-only: appearing only in the [docs page](../writing-docs/autodocs.mdx) and not in Storybook's sidebar.
|
||||
|
||||
{/* prettier-ignore-start */}
|
||||
|
||||
|
||||
@ -2,13 +2,13 @@
|
||||
title: 'Writing stories in TypeScript'
|
||||
---
|
||||
|
||||
Writing your stories in [TypeScript](https://www.typescriptlang.org/) makes you more productive. You don't have to jump between files to look up component props. Your code editor will alert you about missing required props and even autocomplete prop values, just like when using your components within your app. Plus, Storybook infers those component types to auto-generate the [Controls](../api/doc-block-controls.md) table.
|
||||
Writing your stories in [TypeScript](https://www.typescriptlang.org/) makes you more productive. You don't have to jump between files to look up component props. Your code editor will alert you about missing required props and even autocomplete prop values, just like when using your components within your app. Plus, Storybook infers those component types to auto-generate the [Controls](../api/doc-blocks/doc-block-controls.mdx) table.
|
||||
|
||||
Storybook has built-in TypeScript support, so you can get started with zero configuration required.
|
||||
|
||||
## Typing stories with `Meta` and `StoryObj`
|
||||
|
||||
When writing stories, there are two aspects that are helpful to type. The first is the [component meta](./index.md#default-export), which describes and configures the component and its stories. In a [CSF file](../api/csf.md), this is the default export. The second is the [stories themselves](./index.md#defining-stories).
|
||||
When writing stories, there are two aspects that are helpful to type. The first is the [component meta](./index.mdx#default-export), which describes and configures the component and its stories. In a [CSF file](../api/csf.mdx), this is the default export. The second is the [stories themselves](./index.mdx#defining-stories).
|
||||
|
||||
Storybook provides utility types for each of these, named `Meta` and `StoryObj`. Here's an example CSF file using those types:
|
||||
|
||||
@ -20,7 +20,7 @@ Storybook provides utility types for each of these, named `Meta` and `StoryObj`.
|
||||
|
||||
### Props type parameter
|
||||
|
||||
`Meta` and `StoryObj` types are both [generics](https://www.typescriptlang.org/docs/handbook/2/generics.html#working-with-generic-type-variables), so you can provide them with an optional prop type parameter for the component type or the component's props type (e.g., the `typeof Button` portion of `Meta<typeof Button>`). By doing so, TypeScript will prevent you from defining an invalid arg, and all [decorators](./decorators.md), [play functions](./play-function.md), or [loaders](./loaders.md) will type their function arguments.
|
||||
`Meta` and `StoryObj` types are both [generics](https://www.typescriptlang.org/docs/handbook/2/generics.html#working-with-generic-type-variables), so you can provide them with an optional prop type parameter for the component type or the component's props type (e.g., the `typeof Button` portion of `Meta<typeof Button>`). By doing so, TypeScript will prevent you from defining an invalid arg, and all [decorators](./decorators.mdx), [play functions](./play-function.mdx), or [loaders](./loaders.mdx) will type their function arguments.
|
||||
|
||||
The example above passes a component type. See [**Typing custom args**](#typing-custom-args) for an example of passing a props type.
|
||||
|
||||
@ -44,7 +44,7 @@ The example above passes a component type. See [**Typing custom args**](#typing-
|
||||
|
||||
If you are using TypeScript 4.9+, you can take advantage of the new [`satisfies`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html) operator to get stricter type checking. Now you will receive type errors for missing required args, not just invalid ones.
|
||||
|
||||
Using `satisfies` to apply a story's type helps maintain type safety when sharing a [play function](./play-function.md) across stories. Without it, TypeScript will throw an error that the `play` function may be undefined. The `satisfies` operator enables TypeScript to infer whether the play function is defined or not.
|
||||
Using `satisfies` to apply a story's type helps maintain type safety when sharing a [play function](./play-function.mdx) across stories. Without it, TypeScript will throw an error that the `play` function may be undefined. The `satisfies` operator enables TypeScript to infer whether the play function is defined or not.
|
||||
|
||||
Finally, use of `satisfies` allows you to pass `typeof meta` to the `StoryObj` generic. This informs TypeScript of the connection between the `meta` and `StoryObj` types, which allows it to infer the `args` type from the `meta` type. In other words, TypeScript will understand that args can be defined both at the story and meta level and won't throw an error when a required arg is defined at the meta level, but not at the story level.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user