mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-06 15:31:16 +08:00
Add Doc Blocks overview & API reference
- Remove Doc Blocks guides
- Update `docs/api/argtypes` to include information that was in `docs/writing-docs/doc-block-argstable`
- Update TOC
- Change `Write docs > Doc blocks` from a menu to a page
- Add `API > @storybook/blocks menu`
This commit is contained in:
Kyle Gach
parent
627a0f1f3b
commit
c03f0da058
@ -48,19 +48,14 @@ The format of the generated argType will look something like this:
|
||||
|
||||
This ArgTypes data structure, name, type, defaultValue, and description are standard fields in all ArgTypes (analogous to PropTypes in React). The table and control fields are addon-specific annotations. So, for example, the table annotation provides extra information to customize how the label gets rendered, and the control annotation includes additional information for the control editing the property.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 The `@storybook/addon-docs` provide a shorthand for common tasks:
|
||||
|
||||
- `type: 'number'` is shorthand for type: { name: 'number' }
|
||||
- `control: 'radio'` is shorthand for control: { type: 'radio' }
|
||||
|
||||
</div>
|
||||
|
||||
#### Manual specification
|
||||
## Manual specification
|
||||
|
||||
If you want more control over the args table or any other aspect of using argTypes, you can overwrite the generated argTypes for your component on a per-arg basis. For instance, with the above-inferred argTypes and the following default export:
|
||||
|
||||
<div class="aside">
|
||||
💡 As with other Storybook properties (e.g., args, decorators), you can also override ArgTypes per story basis.
|
||||
</div>
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
@ -85,10 +80,102 @@ The `values.description`, `table.type`, and `controls.type` are merged into the
|
||||
|
||||
In particular, this would render a row with a modified description, a type display with a dropdown that shows the detail, and no control.
|
||||
|
||||
### Available properties
|
||||
|
||||
Here's an explanation of each available property:
|
||||
|
||||
| Property | Description |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | The name of the property. <br/> `argTypes: { label: { name: 'Something' } }` |
|
||||
| `type.name` | Sets a type for the property. <br/> `argTypes: { label: { type: { name: 'number' } } }` |
|
||||
| `type.required` | Sets the property as optional or required. <br/> `argTypes: { label: { type: { required: true } }` |
|
||||
| `description` | Sets a Markdown description for the property. <br/> `argTypes: { label: { description: 'Something' } }` |
|
||||
| `table.type.summary` | Provide a short version of the type. <br/> `argTypes: { label: { table: { type: { summary: 'a short summary' } }}}` |
|
||||
| `table.type.detail` | Provides an extended version of the type. <br/> `argTypes: { label: { table: { type: { detail: 'something' } }}}` |
|
||||
| `table.defaultValue.summary` | Provide a short version of the default value. <br/> `argTypes: { label: { table: { defaultValue: { summary: 'Hello World' } }}}` |
|
||||
| `table.defaultValue.detail` | Provides a longer version of the default value. <br/> `argTypes: { label: { table: { defaultValue: { detail: 'Something' } }}}` |
|
||||
| `control` | Associates a control for the property. <br/> `argTypes: { label: { control: { type: 'text'} } }` <br/>Read the [Essentials documentation](../essentials/controls.md) to learn more about controls. |
|
||||
|
||||
#### Shorthands
|
||||
|
||||
<div class="aside">
|
||||
💡 As with other Storybook properties (e.g., args, decorators), you can also override ArgTypes per story basis.
|
||||
|
||||
💡 The `@storybook/addon-docs` provide a shorthand for common tasks:
|
||||
|
||||
- `type: 'number'` is shorthand for type: { name: 'number' }
|
||||
- `control: 'radio'` is shorthand for control: { type: 'radio' }
|
||||
|
||||
</div>
|
||||
|
||||
### Grouping
|
||||
|
||||
You can also extend the ArgsTable's customization by grouping related `argTypes` into categories or even subcategories. Based on the following component implementation:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/button-implementation.js.mdx',
|
||||
'react/button-implementation.ts.mdx',
|
||||
'angular/button-implementation.ts.mdx',
|
||||
'vue/button-implementation.2.js.mdx',
|
||||
'vue/button-implementation.ts-2.ts.mdx',
|
||||
'vue/button-implementation.3.js.mdx',
|
||||
'vue/button-implementation.ts-3.ts.mdx',
|
||||
'svelte/button-implementation.js.mdx',
|
||||
'web-components/button-implementation.js.mdx',
|
||||
'web-components/button-implementation.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
You could group similar properties for better organization and structure. Using the table below as a reference:
|
||||
|
||||
| Field | Category |
|
||||
| :------------------ | :------: |
|
||||
| **backgroundColor** | Colors |
|
||||
| **primary** | Colors |
|
||||
| **label** | Text |
|
||||
| **onClick** | Events |
|
||||
| **size** | Sizes |
|
||||
|
||||
Results in the following change into your story and UI.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/button-story-argtypes-with-categories.js.mdx'
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
|
||||
|
||||
You can also extend the formula above and introduce subcategories, allowing better structuring and organization. Using the table below as a reference leads to the following change to your story and UI:
|
||||
|
||||
| Field | Category | Subcategory |
|
||||
| :------------------ | :------: | :-------------: |
|
||||
| **backgroundColor** | Colors | Button colors |
|
||||
| **primary** | Colors | Button style |
|
||||
| **label** | Text | Button contents |
|
||||
| **onClick** | Events | Button Events |
|
||||
| **size** | Sizes | |
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/button-story-argtypes-with-subcategories.js.mdx'
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
|
||||
|
||||
#### Global `argTypes`
|
||||
|
||||
You can also define arg types at the global level; they will apply to every component's stories unless you overwrite them. To do so, export the `argTypes` key in your `preview.js`:
|
||||
|
||||
71
docs/api/doc-block-argtypes.md
Normal file
71
docs/api/doc-block-argtypes.md
Normal file
@ -0,0 +1,71 @@
|
||||
---
|
||||
title: 'ArgTypes'
|
||||
---
|
||||
|
||||
The `ArgTypes` block can be used to show a static table of [arg types](./argtypes.md) for a given component, as a way to document its interface.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 If you’re looking for a dynamic table that shows a story’s current arg values for a story and supports users changing them, see the [`Controls`](./doc-block-controls.md) block instead.
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { ArgTypes } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<ArgTypes of={ButtonStories} />;
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### ArgTypes
|
||||
|
||||
```js
|
||||
import { ArgTypes } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`ArgTypes` is a React component which accepts props of type `ArgTypesProps`.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
ℹ️ Like most blocks, the `ArgTypes` block can both be configured via props when using it directly in MDX, or with properties in `parameters.docs.argTypes`.
|
||||
|
||||
</div>
|
||||
|
||||
#### `ArgTypesProps`
|
||||
|
||||
##### `exclude`
|
||||
|
||||
Type: `string[] | RegExp`
|
||||
|
||||
Specifies which arg types to exclude from table. Any arg types whose name matches the regex or is part of the array will be left out.
|
||||
|
||||
##### `include`
|
||||
|
||||
Type: `string[] | RegExp`
|
||||
|
||||
Specifies which arg types to include in the table. Any arg types whose name doesn’t match the regex or is not part of the array will be left out.
|
||||
|
||||
##### `of`
|
||||
|
||||
Type: Story export or CSF file exports
|
||||
|
||||
Specifies which story to get the arg types from. If a CSF file exports is provided, it will use the primary (first) story in the file.
|
||||
|
||||
##### `sort`
|
||||
|
||||
Type: `'none' | 'alpha' | 'requiredFirst'`
|
||||
|
||||
Default: `'none'`
|
||||
|
||||
Specifies how the arg types are sorted.
|
||||
|
||||
- **none**: Unsorted, displayed in the same order the arg types are processed in
|
||||
- **alpha**: Sorted alphabetically, by the arg type's name
|
||||
- **requiredFirst**: Same as `alpha`, with any required arg types displayed first
|
||||
207
docs/api/doc-block-canvas.md
Normal file
207
docs/api/doc-block-canvas.md
Normal file
@ -0,0 +1,207 @@
|
||||
---
|
||||
title: 'Canvas'
|
||||
---
|
||||
|
||||
The `Canvas` block is a wrapper around a [`Story`](./doc-block-story.md), featuring a toolbar that allows you to interact with its content while automatically providing the required [`Source`](./doc-block-source.md) snippets.
|
||||
|
||||
|
||||
|
||||
When using the Canvas block in MDX, it references a story with the `of` prop:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Story, Canvas } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
<Canvas of={ButtonStories.Primary} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 In previous versions of Storybook it was possible to pass in arbitrary components as children to `Canvas`. That is deprecated and the `Canvas` block now only supports a single story.
|
||||
|
||||
</div>
|
||||
|
||||
## API
|
||||
|
||||
### Canvas
|
||||
|
||||
```js
|
||||
import { Canvas } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Canvas` is a React component which accepts props of type `CanvasProps`.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
ℹ️ Like most blocks, the `Canvas` block can both be configured via props when using it directly in MDX, or with properties in `parameters.docs.canvas`.
|
||||
|
||||
</div>
|
||||
|
||||
#### `CanvasProps`
|
||||
|
||||
##### `additionalActions`
|
||||
|
||||
Type:
|
||||
|
||||
```ts
|
||||
Array<{
|
||||
title: string | JSX.Element;
|
||||
className?: string;
|
||||
onClick: () => void;
|
||||
disabled?: boolean;
|
||||
}>
|
||||
```
|
||||
|
||||
Provides any additional custom actions to show in the bottom right corner. These are simple buttons that do anything you specify in the `onClick` function.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Story, Canvas, SourceState } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
{/* with an additional action */}
|
||||
<Canvas
|
||||
additionalActions={[
|
||||
{
|
||||
title: 'Open in GitHub',
|
||||
onClick: () => {
|
||||
window.open(
|
||||
'https://github.com/storybookjs/storybook/blob/next/code/ui/blocks/src/examples/Button.stories.tsx',
|
||||
'_blank'
|
||||
);
|
||||
},
|
||||
}
|
||||
]}
|
||||
of={ButtonStories.Primary}
|
||||
/>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
##### `className`
|
||||
|
||||
Type: `string`
|
||||
|
||||
Provides HTML class(es) to the preview element, for custom styling.
|
||||
|
||||
##### `layout`
|
||||
|
||||
Type: `'padded' | 'centered' | 'fullscreen'`
|
||||
|
||||
Default: `'padded'`
|
||||
|
||||
Specifies how the canvas should layout the story.
|
||||
|
||||
- **padded**: Add padding to the story
|
||||
- **centered**: Center the story within the canvas
|
||||
- **fullscreen**: Show the story as-is, without padding
|
||||
|
||||
The canvas in docs will respect the `parameters.layout` value that defines how a story is laid out in the regular story view, but that can also be overridden with this prop.
|
||||
|
||||
##### `meta`
|
||||
|
||||
Type: CSF file exports
|
||||
|
||||
Specifies the CSF file to which the story is associated.
|
||||
|
||||
You can render a story from a CSF file that you haven’t attached to the MDX file (via `Meta`) by using the `meta` prop. Pass the **full set of exports** from the CSF file (not the default export!).
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Canvas } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
import * as HeaderStories from './Header.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
{/* Although this MDX file is largely concerned with Button,
|
||||
it can render Header stories too */}
|
||||
<Canvas of={HeaderStories.LoggedIn} meta={HeaderStories} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
##### `of`
|
||||
|
||||
Type: Story export
|
||||
|
||||
Specifies which story's source is displayed.
|
||||
|
||||
##### `source`
|
||||
|
||||
Type: `Omit<SourceProps, 'dark'>`
|
||||
|
||||
See [SourceProps](./doc-block-source.md#sourceprops).
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 The dark prop is ignored, as the `Source` block is always rendered in dark mode when shown as part of a `Canvas` block.
|
||||
|
||||
</div>
|
||||
|
||||
##### `sourceState`
|
||||
|
||||
Type: `'hidden' | 'shown' | 'none'`
|
||||
|
||||
Default: `'hidden'`
|
||||
|
||||
Specifies the initial state of the source panel.
|
||||
|
||||
- **hidden**: the source panel is hidden by default
|
||||
- **shown**: the source panel is shown by default
|
||||
- **none**: the source panel is not available and the button to show it is not rendered
|
||||
|
||||
##### `story`
|
||||
|
||||
Type: `Pick<StoryProps, 'inline' | 'height' | 'autoplay'>`
|
||||
|
||||
Specifies props to pass to the inner `Story` block. See [StoryProps](./doc-block-story.md#storyprops).
|
||||
|
||||
##### `withToolbar`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
Determines whether to render a toolbar containing tools to interact with the story.
|
||||
|
||||
##### `children` (deprecated)
|
||||
|
||||
Type: `ReactNode`
|
||||
|
||||
Expects only [Story](./doc-block-story.md) children. Reference the story with the `of` prop instead.
|
||||
|
||||
##### `columns` (deprecated)
|
||||
|
||||
Type: `number`
|
||||
|
||||
Splits the stories based on the number of defined columns. Multiple stories are not supported.
|
||||
|
||||
##### `isColumn` (deprecated)
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
Displays the stories one above the other. Multiple stories are not supported.
|
||||
|
||||
##### `mdxSource` (deprecated)
|
||||
|
||||
Type: `string`
|
||||
|
||||
Provides source to display. Use [`source.code`](#source) instead.
|
||||
|
||||
##### `withSource` (deprecated)
|
||||
|
||||
Type: `DeprecatedSourceState`
|
||||
|
||||
Controls the source code block visibility. Use [`sourceState`](#sourcestate) instead.
|
||||
|
||||
##### `withToolbar` (deprecated)
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
Sets the Canvas toolbar visibility. Use [`story.withToolbar`](#story) instead.
|
||||
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 16 KiB |
|
Before Width: | Height: | Size: 41 KiB After Width: | Height: | Size: 41 KiB |
64
docs/api/doc-block-colorpalette.md
Normal file
64
docs/api/doc-block-colorpalette.md
Normal file
@ -0,0 +1,64 @@
|
||||
---
|
||||
title: 'ColorPalette'
|
||||
---
|
||||
|
||||
The `ColorPalette` block allows you to document all color-related items (e.g., swatches) used throughout your project.
|
||||
|
||||
<!-- TK -->
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/colorpalette-doc-block.starter-example.mdx.mdx',
|
||||
'common/colopalette-doc-block.advanced-example.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### ColorPalette
|
||||
|
||||
```js
|
||||
import { ColorPalette } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`ColorPalette` is a React component which accepts props of type `ColorPaletteProps`.
|
||||
|
||||
#### `ColorPaletteProps`
|
||||
|
||||
##### `children`
|
||||
|
||||
Type: `React.ReactNode`
|
||||
|
||||
`ColorPalette` expects only `ColorItem` children.
|
||||
|
||||
### ColorItem
|
||||
|
||||
```js
|
||||
import { ColorItem } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`ColorItem` is a React component which accepts props of type `ColorItemProps`.
|
||||
|
||||
#### `ColorItemProps`
|
||||
|
||||
##### `colors` (required)
|
||||
|
||||
Type: `string[] | { [key: string]: string }`
|
||||
|
||||
Provides the list of colors to be displayed.
|
||||
|
||||
##### `subtitle` (required)
|
||||
|
||||
Type: `string`
|
||||
|
||||
Provides an additional description to the color.
|
||||
|
||||
##### `title` (required)
|
||||
|
||||
Type: `string`
|
||||
|
||||
Sets the name of the color to be displayed.
|
||||
67
docs/api/doc-block-controls.md
Normal file
67
docs/api/doc-block-controls.md
Normal file
@ -0,0 +1,67 @@
|
||||
---
|
||||
title: 'Controls'
|
||||
---
|
||||
|
||||
Storybook’s `Controls` block can be used to show a dynamic table of args for a given story, as a way to document its interface, and to allow you to change the args for a (separately) rendered story (via the [`Story`](./doc-block-story.md) or [`Canvas`](./doc-block-canvas.md) blocks).
|
||||
|
||||
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Canvas, Controls } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories'
|
||||
|
||||
<Canvas of={ButtonStories.Primary} />
|
||||
|
||||
<Controls of={ButtonStories.Primary} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### Controls
|
||||
|
||||
```js
|
||||
import { Controls } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Controls` is a React component which accepts props of type `ControlsProps`.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
ℹ️ Like most blocks, the `Controls` block can both be configured via props when using it directly in MDX, or with properties in `parameters.docs.controls`.
|
||||
|
||||
</div>
|
||||
|
||||
#### `ControlsProps`
|
||||
|
||||
##### `exclude`
|
||||
|
||||
Type: `string[] | RegExp`
|
||||
|
||||
Specifies which args to exclude from table. Any args whose name matches the regex or is part of the array will be left out.
|
||||
|
||||
##### `include`
|
||||
|
||||
Type: `string[] | RegExp`
|
||||
|
||||
Specifies which args to include in the table. Any args whose name doesn’t match the regex or is not part of the array will be left out.
|
||||
|
||||
##### `of`
|
||||
|
||||
Type: Story export
|
||||
|
||||
Specifies which story to get the args from.
|
||||
|
||||
##### `sort`
|
||||
|
||||
Type: `'none' | 'alpha' | 'requiredFirst'`
|
||||
|
||||
Default: `'none'`
|
||||
|
||||
Specifies how the controls are sorted.
|
||||
|
||||
- **none**: Unsorted, displayed in the same order the args are processed in
|
||||
- **alpha**: Sorted alphabetically, by the arg's name
|
||||
- **requiredFirst**: Same as `alpha`, with any required args displayed first
|
||||
144
docs/api/doc-block-description.md
Normal file
144
docs/api/doc-block-description.md
Normal file
@ -0,0 +1,144 @@
|
||||
---
|
||||
title: 'Description'
|
||||
---
|
||||
|
||||
The `Description` block displays the description for a component, story, or meta, obtained from their respective JSDoc comments.
|
||||
|
||||
<!-- TK -->
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Description } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Description of={ButtonStories.Primary} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### Description
|
||||
|
||||
```js
|
||||
import { Description } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Description` is a React component which accepts props of type `DescriptionProps`.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
ℹ️ Like most blocks, the `Description` block can both be configured via props when using it directly in MDX, or with properties in `parameters.docs.description`.
|
||||
|
||||
</div>
|
||||
|
||||
#### `DescriptionProps`
|
||||
|
||||
##### `of`
|
||||
|
||||
Type: Story export or CSF file exports
|
||||
|
||||
Specifies where to pull the description from. It can either point to a story or a meta, depending on which description you want to show.
|
||||
|
||||
Descriptions are pulled from the JSDoc comments or parameters, and they are rendered as markdown. See [Writing descriptions](#writing-descriptions) for more details.
|
||||
|
||||
##### `children` (deprecated)
|
||||
|
||||
Type: `string`
|
||||
|
||||
See [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#description-block-parametersnotes-and-parametersinfo).
|
||||
|
||||
##### `markdown` (deprecated)
|
||||
|
||||
Type: `string`
|
||||
|
||||
See [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#description-block-parametersnotes-and-parametersinfo).
|
||||
|
||||
##### `type` (deprecated)
|
||||
|
||||
Type: `DescriptionType`
|
||||
|
||||
See [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#description-block-parametersnotes-and-parametersinfo).
|
||||
|
||||
## Writing descriptions
|
||||
|
||||
There are multiple places to write the description of a component/story, depending on what you want to achieve. Descriptions can be written at the story level to describe each story of a component, or they can be written at the meta or component level to describe the component in general.
|
||||
|
||||
Descriptions can be written as [JSDoc comments](https://jsdoc.app/about-getting-started.html) above stories, meta, or components. Alternatively it can also be added to `parameters`. To describe a story via parameters instead of comments, add it to `parameters.docs.description.story`; to describe meta/component, add it to `parameters.docs.description.component`.
|
||||
|
||||
We recommend using JSDoc comments for descriptions, and only use the `parameters.docs.description.X` properties in situations where comments are not possible to write for some reason, or where you want the description shown in Storybook to be different from the comments. Comments provide a better writing experience as you don’t have to worry about indentation, and they are more discoverable for other developers that are exploring the story/component sources.
|
||||
|
||||
When documenting a story, reference a story export in the `of` prop (see below) and the Description block will look for descriptions in the following order:
|
||||
|
||||
1. `parameters.docs.description.story` in the story
|
||||
2. JSDoc comments above the story
|
||||
|
||||
When documenting a component, reference a meta export in the `of` prop (see below) and the Description block will look for descriptions in the following order:
|
||||
|
||||
1. `parameters.docs.description.component` in the meta
|
||||
2. JSDoc comments above the meta
|
||||
3. JSDoc comments above the component
|
||||
|
||||
This flow gives you powerful ways to override the description for each scenario. Take the following example:
|
||||
|
||||
```jsx
|
||||
// Button.jsx
|
||||
|
||||
/**
|
||||
* # The Button component
|
||||
* Shows a button
|
||||
*/
|
||||
export const Button = () => <button>Click me</button>;
|
||||
```
|
||||
|
||||
```js
|
||||
// Button.stories.jsx
|
||||
import { Button } from './button.jsx';
|
||||
|
||||
/**
|
||||
* # Button stories
|
||||
* These stories showcases the button
|
||||
*/
|
||||
export default {
|
||||
component: Button
|
||||
parameters: {
|
||||
docs: {
|
||||
description: {
|
||||
component: "another description, overriding the comments"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* # Primary Button
|
||||
* This is the primary button
|
||||
*/
|
||||
export const Primary = {
|
||||
parameters: {
|
||||
docs: {
|
||||
description: {
|
||||
story: "another description on the story, overriding the comments"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Description } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
{/* Shows the description for the default export (the meta).
|
||||
If that didn't have any comments, it would show the
|
||||
comments from the component instead */}
|
||||
<Description of={ButtonStories} />
|
||||
|
||||
{/* Shows the description for the Primary export */}
|
||||
<Description of={ButtonStories.Primary} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 24 KiB |
|
Before Width: | Height: | Size: 19 KiB After Width: | Height: | Size: 19 KiB |
57
docs/api/doc-block-icongallery.md
Normal file
57
docs/api/doc-block-icongallery.md
Normal file
@ -0,0 +1,57 @@
|
||||
---
|
||||
title: 'IconGallery'
|
||||
---
|
||||
|
||||
The `IconGallery` block enables you to easily document all icons associated with your project, displayed in a neat grid.
|
||||
|
||||
<!-- TK -->
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/icongallery-doc-block.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### IconGallery
|
||||
|
||||
```js
|
||||
import { IconGallery } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`IconGallery` is a React component which accepts props of type `IconGalleryProps`.
|
||||
|
||||
#### `IconGalleryProps`
|
||||
|
||||
##### `children`
|
||||
|
||||
Type: `React.ReactNode`
|
||||
|
||||
`IconGallery` expects only `IconItem` children.
|
||||
|
||||
### IconItem
|
||||
|
||||
```js
|
||||
import { IconItem } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`IconItem` is a React component which accepts props of type `IconItemProps`.
|
||||
|
||||
#### `IconItemProps`
|
||||
|
||||
##### `children`
|
||||
|
||||
Type: `React.ReactNode`
|
||||
|
||||
Provides the icon to be displayed.
|
||||
|
||||
##### `name` (required)
|
||||
|
||||
Type: `string`
|
||||
|
||||
Sets the name of the icon.
|
||||
92
docs/api/doc-block-markdown.md
Normal file
92
docs/api/doc-block-markdown.md
Normal file
@ -0,0 +1,92 @@
|
||||
---
|
||||
title: 'Markdown'
|
||||
---
|
||||
|
||||
The `Markdown` block allows you to import and include plain markdown in your MDX files.
|
||||
|
||||
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
// DON'T do this, will error
|
||||
import ReadMe from './README.md';
|
||||
// DO this, will work
|
||||
import ReadMe from './README.md?raw';
|
||||
|
||||
import { Markdown } from '@storybook/blocks';
|
||||
|
||||
# A header
|
||||
|
||||
<Markdown>{ReadMe}</Markdown />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### Markdown
|
||||
|
||||
```js
|
||||
import { Markdown } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Markdown` is a React component which accepts props of type `MarkdownProps`.
|
||||
|
||||
#### `MarkdownProps`
|
||||
|
||||
##### `children`
|
||||
|
||||
Type: `string`
|
||||
|
||||
Provides the markdown-formatted string to parse and display.
|
||||
|
||||
##### `options`
|
||||
|
||||
Specifies the options passed to the underlying [`markdown-to-jsx` library](https://github.com/probablyup/markdown-to-jsx/blob/main/README.md).
|
||||
|
||||
## Why not import markdown directly?
|
||||
|
||||
From a purely technical standpoint, we could include the imported markdown directly in the MDX file like this:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* THIS WON'T WORK, THIS IS TO DEMONSTRATE AN ERROR */}
|
||||
|
||||
import ReadMe from './README.md';
|
||||
|
||||
# A header
|
||||
|
||||
{ReadMe}
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
However there are small syntactical differences between plain Markdown and MDX2. MDX2 is more strict and will interpret certain content as JSX expressions. Here’s an example of a perfectly valid Markdown file, that would break if it was handled directly by MDX2:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
# A header
|
||||
|
||||
{ this is valid in a plain Markdown file, but MDX2 will try to evaluate this as an expression }
|
||||
|
||||
<This is also valid, but MDX2 thinks this is a JSX component />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Furthermore MDX2 wraps all strings on newlines in p tags or similar, meaning that content would render different between a plain .md file and an .mdx file.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
# A header
|
||||
|
||||
<div>
|
||||
Some text
|
||||
</div>
|
||||
|
||||
The example above will remain as-is in plain Markdown, but MDX2 will compile it to:
|
||||
|
||||
# A header
|
||||
|
||||
<div>
|
||||
<p>Some text</p>
|
||||
</div>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
98
docs/api/doc-block-meta.md
Normal file
98
docs/api/doc-block-meta.md
Normal file
@ -0,0 +1,98 @@
|
||||
---
|
||||
title: 'Meta'
|
||||
---
|
||||
|
||||
The `Meta` block is used to **attach** a custom MDX docs page alongside a component’s list of stories. It doesn’t render any content, but serves two purposes in an MDX file:
|
||||
|
||||
- Attaches the MDX file to a component and its stories, or
|
||||
- Controls the location of the unattached docs entry in the sidebar.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 The Meta block doesn’t render anything visible.
|
||||
|
||||
</div>
|
||||
|
||||
## API
|
||||
|
||||
### Meta
|
||||
|
||||
```js
|
||||
import { Meta } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Meta` is a React component which accepts props of type `MetaProps`.
|
||||
|
||||
#### `MetaProps`
|
||||
|
||||
##### `name`
|
||||
|
||||
Type: `string`
|
||||
|
||||
Sets the name of the attached doc entry. You can attach more than one MDX file to the same component in the sidebar by setting different names for each file's `Meta`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* Component.mdx */}
|
||||
import { Meta } from '@storybook/blocks';
|
||||
import * as ComponentStories from './component.stories';
|
||||
|
||||
{/* This MDX file is now called "Special Docs" */}
|
||||
<Meta of={ComponentStories} name="Special Docs" />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
##### `of`
|
||||
|
||||
Type: CSF file exports
|
||||
|
||||
Specificies which CSF file is [attached](#attached-vs-unattached) to this MDX file. Pass the **full set of exports** from the CSF file (not the default export!).
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Story } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Attaching an MDX file to a component’s stories with the `of` prop serves two purposes:
|
||||
|
||||
1. Ensures the MDX content appears in the sidebar inside the component’s story list. By default, it will be named whatever the `docs.defaultName` (which defaults to `"Docs"`) option is set to in `main.js`. But this can be overridden with the [`name` prop](#name).
|
||||
2. Attaches the component and its stories to the MDX file, allowing you to use other doc blocks in “attached” mode (for instance to use the `Stories` block).
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 The `of` prop is optional. If you don’t want to attach a specific CSF file to this MDX file, you can either use the `title` prop to control the location, or emit `Meta` entirely, and let [autotitle](../configure/sidebar-and-urls.md#csf-30-auto-titles) decide where it goes.
|
||||
|
||||
</div >
|
||||
|
||||
##### `title`
|
||||
|
||||
Type: `string`
|
||||
|
||||
Sets the title of an unattached MDX file.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* Introduction.mdx */}
|
||||
import { Meta } from '@storybook/blocks';
|
||||
|
||||
{/* Override the docs entry's location in the sidebar with title */}
|
||||
<Meta title="path/to/Introduction" />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 If you want to change the sorting of the docs entry with the component’s stories, use [Story Sorting](../writing-stories/naming-components-and-hierarchy.md#sorting-stories), or add specific MDX files to your `stories` field in `main.js` in order.
|
||||
|
||||
</div>
|
||||
|
||||
## Attached vs. unattached
|
||||
|
||||
In Storybook, a docs entry (MDX file) is "attached" when it is associated with a stories file, via `Meta`'s [`of` prop](#of). Attached docs entries display next to the stories list under the component in the sidebar.
|
||||
|
||||
"Unattached" docs entries are not associated with a stories file and can be displayed anywhere in the sidebar via `Meta`'s [`title` prop](#title).
|
||||
25
docs/api/doc-block-primary.md
Normal file
25
docs/api/doc-block-primary.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
title: 'Primary'
|
||||
---
|
||||
|
||||
The `Primary` block displays the primary (first defined in the stories file) story, in a [`Story`](./doc-block-story.md) block. It is typically rendered immediately under the title in a docs entry.
|
||||
|
||||
|
||||
|
||||
## API
|
||||
|
||||
### Primary
|
||||
|
||||
```js
|
||||
import { Primary } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Primary` is a React component which accepts props of type `PrimaryProps`.
|
||||
|
||||
#### `PrimaryProps`
|
||||
|
||||
##### `name` (deprecated)
|
||||
|
||||
Type: `string`
|
||||
|
||||
Primary block should only be used to render the primary story, which is automatically found.
|
||||
116
docs/api/doc-block-source.md
Normal file
116
docs/api/doc-block-source.md
Normal file
@ -0,0 +1,116 @@
|
||||
---
|
||||
title: 'Source'
|
||||
---
|
||||
|
||||
The `Source` block is used to render a snippet of source code directly.
|
||||
|
||||
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Source } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
<Source of={ButtonStories.Primary} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### Source
|
||||
|
||||
```js
|
||||
import { Source } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Source` is a React component which accepts props of type `SourceProps`.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
ℹ️ Like most blocks, the `Source` block can both be configured via props when using it directly in MDX, or with properties in `parameters.docs.source`.
|
||||
|
||||
</div>
|
||||
|
||||
#### `SourceProps`
|
||||
|
||||
##### `code`
|
||||
|
||||
Type: `string`
|
||||
|
||||
Provides the source code to be rendered.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Source } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
<Source code={`const thisIsCustomSource = true;
|
||||
if (isSyntaxHighlighted) {
|
||||
console.log('syntax highlighting is working');
|
||||
}`} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
##### `dark`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
Determines if snippet is rendered in dark mode.
|
||||
|
||||
##### `format`
|
||||
|
||||
Type: `boolean | 'dedent' | BuiltInParserName`
|
||||
|
||||
Default: `true`
|
||||
|
||||
Specifies the formatting used on source code. Supports all valid [prettier parser names](https://prettier.io/docs/en/configuration.html#setting-the-parserdocsenoptionshtmlparser-option).
|
||||
|
||||
##### `language`
|
||||
|
||||
Type: `'jsextra' | 'jsx' | 'json' | 'yml' | 'md' | 'bash' | 'css' | 'html' | 'tsx' | 'typescript' | 'graphql'`
|
||||
|
||||
Default: `'jsx'`
|
||||
|
||||
Specifies the language used for syntax highlighting.
|
||||
|
||||
##### `of`
|
||||
|
||||
Type: Story export
|
||||
|
||||
Specifies which story's source is rendered.
|
||||
|
||||
##### `type`
|
||||
|
||||
Type: `'auto' | 'code' | 'dynamic'`
|
||||
|
||||
Default: `'auto'`
|
||||
|
||||
Specifies how the source code is rendered.
|
||||
|
||||
- **auto**: Same as `dynamic`, if supported by the framework in use; otherwise same as `code`
|
||||
- **code**: Renders the value of `code` prop, otherwise renders static story source
|
||||
- **dynamic**: Renders the story source with dynamically updated arg values
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 Note that dynamic snippets will only work if the Story block for the story is also rendered.
|
||||
|
||||
</div>
|
||||
|
||||
##### `id` (deprecated)
|
||||
|
||||
Type: `string`
|
||||
|
||||
Specifies the story id for which to render the source code. Referencing a story this way is no longer supported; use the [`of` prop](#of), instead.
|
||||
|
||||
##### `ids` (deprecated)
|
||||
|
||||
Type: `string[]`
|
||||
|
||||
Specifies the story ids for which to render source code. Multiple stories are no longer supported; to render a single story's source, use use the [`of` prop](#of).
|
||||
47
docs/api/doc-block-stories.md
Normal file
47
docs/api/doc-block-stories.md
Normal file
@ -0,0 +1,47 @@
|
||||
---
|
||||
title: 'Stories'
|
||||
---
|
||||
|
||||
The `Stories` block renders the full collection of stories in a stories file.
|
||||
|
||||
|
||||
|
||||
## API
|
||||
|
||||
### Stories
|
||||
|
||||
```js
|
||||
import { Stories } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Stories` is a React component which accepts props of type `StoriesProps`.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
ℹ️ Like most blocks, the `Stories` block can both be configured via props when using it directly in MDX, or with properties in `parameters.docs.stories`.
|
||||
|
||||
</div>
|
||||
|
||||
#### `StoriesProps`
|
||||
|
||||
##### `includePrimary`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
Default: `true`
|
||||
|
||||
Determines if the collection of stories includes the primary (first) story.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 If a stories file contains only one story and `includePrimary={true}`, the `Stories` block will render nothing to avoid a potentially confusing situation.
|
||||
|
||||
</div>
|
||||
|
||||
##### `title`
|
||||
|
||||
Type: `string`
|
||||
|
||||
Default: `'Stories'`
|
||||
|
||||
Sets the heading content preceding the collection of stories.
|
||||
164
docs/api/doc-block-story.md
Normal file
164
docs/api/doc-block-story.md
Normal file
@ -0,0 +1,164 @@
|
||||
---
|
||||
title: 'Story'
|
||||
---
|
||||
|
||||
Stories (component tests) are Storybook's fundamental building blocks.
|
||||
|
||||
In Storybook Docs, you can render any of your stories from your CSF files in the context of an MDX file with all annotations (parameters, args, loaders, decorators, play function) applied using the `Story` block.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
Typically you want to use the [`Canvas` block](./doc-block-canvas.md) to render a story with a surrounding border and the source block, but you can use the `Story` block to render just the story.
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Story } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
<Story of={ButtonStories.Primary} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### Story
|
||||
|
||||
```js
|
||||
import { Story } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Story` is a React component which accepts props of type `StoryProps`.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
ℹ️ Like most blocks, the `Story` block can both be configured via props when using it directly in MDX, or with properties in `parameters.docs.story`.
|
||||
|
||||
</div>
|
||||
|
||||
#### `StoryProps`
|
||||
|
||||
##### `autoplay`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
Determines whether a story's play function runs.
|
||||
|
||||
Because all stories render simultaneously in docs entries, play functions can perform arbitrary actions that can interact with each other (such as stealing focus or scrolling the screen). For that reason, by default, stories **do not run play functions in docs mode**.
|
||||
|
||||
However, if you know your play function is “safe” to run in docs, you can use this prop to run it automatically.
|
||||
|
||||
##### `height`
|
||||
|
||||
Type: `string`
|
||||
|
||||
Set a minimum height (note for an iframe this is the actual height) when rendering a story in an iframe or inline. This overrides `parameters.docs.story.iframeHeight` for iframes.
|
||||
|
||||
##### `inline`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
Default: `true`, for [supported frameworks](./frameworks-feature-support.md)
|
||||
|
||||
Determines whether the story is rendered `inline` (in the same browser frame as the other docs content) or in an iframe.
|
||||
|
||||
##### `meta`
|
||||
|
||||
Type: CSF file exports
|
||||
|
||||
Specifies the CSF file to which the story is associated.
|
||||
|
||||
You can render a story from a CSF file that you haven’t attached to the MDX file (via `Meta`) by using the `meta` prop. Pass the **full set of exports** from the CSF file (not the default export!).
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Story } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
import * as HeaderStories from './Header.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
{/* Although this MDX file is largely concerned with Button,
|
||||
it can render Header stories too */}
|
||||
<Story of={HeaderStories.LoggedIn} meta={HeaderStories} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
##### `of`
|
||||
|
||||
Type: Story export
|
||||
|
||||
Specifies which story is rendered by the `Story` block. If no `of` is defined and the MDX file is [attached](./doc-block-meta.md#attached-vs-unattached), the primary (first) story will be rendered.
|
||||
|
||||
##### `args` (deprecated)
|
||||
|
||||
Type: `Partial<TArgs>`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `argTypes` (deprecated)
|
||||
|
||||
Type: `Partial<ArgTypes<TArgs>>`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `decorators` (deprecated)
|
||||
|
||||
Type: `DecoratorFunction<TRenderer, TArgs>[]`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `loaders` (deprecated)
|
||||
|
||||
Type: `LoaderFunction<TRenderer, TArgs>[]`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `name` (deprecated)
|
||||
|
||||
Type: `StoryName`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `parameters` (deprecated)
|
||||
|
||||
Type: `Parameters`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `play` (deprecated)
|
||||
|
||||
Type: `PlayFunction<TRenderer, TArgs>`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `render` (deprecated)
|
||||
|
||||
Type: `ArgsStoryFn<TRenderer, TArgs>`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `story` (deprecated)
|
||||
|
||||
Type: `Omit<StoryAnnotations<TRenderer, TArgs>, 'story'>`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `storyName` (deprecated)
|
||||
|
||||
Type: `StoryName`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
|
||||
##### `tags` (deprecated)
|
||||
|
||||
Type: `Tag[]`
|
||||
|
||||
Defining and configuring stories in MDX is deprecated. See the [Migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#mdx-docs-files) for details.
|
||||
25
docs/api/doc-block-subtitle.md
Normal file
25
docs/api/doc-block-subtitle.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
title: 'Subtitle'
|
||||
---
|
||||
|
||||
The `Subtitle` block can serve as a secondary heading for your docs entry.
|
||||
|
||||
|
||||
|
||||
## API
|
||||
|
||||
### Subtitle
|
||||
|
||||
```js
|
||||
import { Subtitle } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Subtitle` is a React component which accepts props of type `SubtitleProps`.
|
||||
|
||||
#### `SubtitleProps`
|
||||
|
||||
##### `children`
|
||||
|
||||
Type: `JSX.Element | string`
|
||||
|
||||
Provides the content. Falls back to value of `parameters.componentSubtitle`.
|
||||
25
docs/api/doc-block-title.md
Normal file
25
docs/api/doc-block-title.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
title: 'Title'
|
||||
---
|
||||
|
||||
The `Title` block serves as the primary heading for your docs entry. It is typically used to provide the component or page name.
|
||||
|
||||
|
||||
|
||||
## API
|
||||
|
||||
### Title
|
||||
|
||||
```js
|
||||
import { Title } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Title` is a React component which accepts props of type `TitleProps`.
|
||||
|
||||
#### `TitleProps`
|
||||
|
||||
##### `children`
|
||||
|
||||
Type: `JSX.Element | string`
|
||||
|
||||
Provides the content. Falls back to value of `meta.title` (or value derived from [autotitle](../configure/sidebar-and-urls.md#csf-30-auto-titles)), trimmed to the last segment. For example, if the title value is `'path/to/components/Button'`, the default content is `'Button'`.
|
||||
|
Before Width: | Height: | Size: 61 KiB After Width: | Height: | Size: 61 KiB |
53
docs/api/doc-block-typeset.md
Normal file
53
docs/api/doc-block-typeset.md
Normal file
@ -0,0 +1,53 @@
|
||||
---
|
||||
title: 'Typeset'
|
||||
---
|
||||
|
||||
The `Typeset` block helps document the fonts used throughout your project.
|
||||
|
||||
<!-- TK -->
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/typeset-doc.block.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### Typeset
|
||||
|
||||
```js
|
||||
import { Typeset } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Typeset` is a React component which accepts props of type `TypesetProps`.
|
||||
|
||||
#### `TypesetProps`
|
||||
|
||||
##### `fontFamily`
|
||||
|
||||
Type: `string`
|
||||
|
||||
Provides a font family to be displayed.
|
||||
|
||||
##### `fontSizes`
|
||||
|
||||
Type: `number[]`
|
||||
|
||||
Provides a list of available font sizes (in `px`).
|
||||
|
||||
##### `fontWeight`
|
||||
|
||||
Type: `number`
|
||||
|
||||
Specifies the weight of the font to be displayed.
|
||||
|
||||
##### `sampleText`
|
||||
|
||||
Type: `string`
|
||||
|
||||
Sets the text to be displayed.
|
||||
68
docs/api/doc-block-unstyled.md
Normal file
68
docs/api/doc-block-unstyled.md
Normal file
@ -0,0 +1,68 @@
|
||||
---
|
||||
title: 'Unstyled'
|
||||
---
|
||||
|
||||
The `Unstyled` block is a special block that disables Storybook's default styling in MDX docs wherever it is added.
|
||||
|
||||
By default, most elements (like `h1`, `p`, etc.) in docs have a few default styles applied to ensure the docs look good. However, sometimes you might want some of your content to not have these styles applied. In those cases, wrap the content with the `Unstyled` block to remove the default styles.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
import { Unstyled } from '@storybook/blocks';
|
||||
|
||||
> This block quote will be styled
|
||||
|
||||
... and so will this paragraph.
|
||||
|
||||
<Unstyled>
|
||||
> This block quote will not be styled
|
||||
|
||||
... neither will this paragraph, nor the following component:
|
||||
<MyCustomComponent />
|
||||
</Unstyled>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Yields:
|
||||
|
||||
|
||||
|
||||
<div class="aside">
|
||||
|
||||
ℹ️ The other blocks like [`Story`](./doc-block-story.md) and [`Canvas`](./doc-block-canvas.md) are already unstyled, so there’s no need to wrap those in the `Unstyled` block to ensure that Storybook’s styles don’t bleed into the stories. However, if you import your components directly in the MDX, you most likely want to wrap them in the Unstyled block.
|
||||
|
||||
</div>
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 Due to how CSS inheritance works it’s best to always add the Unstyled block to the root of your MDX, and not nested into other elements. The following example will cause some Storybook styles like `color` to be inherited into `CustomComponent` because they are applied to the root `div`:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
<div>
|
||||
<Unstyled>
|
||||
<CustomComponent/>
|
||||
</Unstyled>
|
||||
</div>
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
</div>
|
||||
|
||||
## API
|
||||
|
||||
### Unstyled
|
||||
|
||||
```js
|
||||
import { Unstyled } from '@storybook/blocks';
|
||||
```
|
||||
|
||||
`Unstyled` is a React component which accepts props of type `UnstyledProps`.
|
||||
|
||||
#### `UnstyledProps`
|
||||
|
||||
##### `children`
|
||||
|
||||
Type: `React.ReactNode`
|
||||
|
||||
Provides the content to which you do _not_ want to apply default docs styles.
|
||||
111
docs/api/doc-block-useof.md
Normal file
111
docs/api/doc-block-useof.md
Normal file
@ -0,0 +1,111 @@
|
||||
---
|
||||
title: 'useOf'
|
||||
---
|
||||
|
||||
The default blocks supplied by Storybook do not fit all use cases, so you might want to write your own blocks.
|
||||
|
||||
If your own doc blocks need to interface with annotations from Storybook—that is stories, meta or components—you can use the `useOf` hook. Pass in a module export of a story, meta, or component and it will return its annotated form (with applied parameters, args, loaders, decorators, play function) that you can then use for anything you like. In fact, most of the existing blocks like [`Description`](./doc-block-description.md) and [`Canvas`](./doc-block-canvas.md) use `useOf` under the hood.
|
||||
|
||||
Here’s an example of how the`useOf` hook could be used to create a custom block that displays the name of the story:
|
||||
|
||||
```jsx
|
||||
// .storybook/blocks/StoryName.jsx
|
||||
|
||||
import { useOf } from '@storybook/blocks';
|
||||
|
||||
/**
|
||||
* A block that displays the story name or title from the of prop
|
||||
* - if a story reference is passed, it renders the story name
|
||||
* - if a meta reference is passed, it renders the stories' title
|
||||
* - if nothing is passed, it defaults to the primary story
|
||||
*/
|
||||
export const StoryName = ({ of }) => {
|
||||
const resolvedOf = useOf(of || 'story', ['story', 'meta']);
|
||||
switch (resolvedOf.type) {
|
||||
case 'story': {
|
||||
return <h1>{resolvedOf.story.name}</h1>;
|
||||
}
|
||||
case 'meta': {
|
||||
return <h1>{resolvedOf.preparedMeta.title}</h1>;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
};
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta } from '@storybook/blocks';
|
||||
import { StoryName } from '../.storybook/blocks/StoryName';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
{/* renders "Secondary" */}
|
||||
<StoryName of={ButtonStories.Secondary} />
|
||||
|
||||
{/* renders "Primary" */}
|
||||
<StoryName />
|
||||
|
||||
{/* renders "Button" */}
|
||||
<StoryName of={ButtonStories} />
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
## API
|
||||
|
||||
### useOf
|
||||
|
||||
#### Signature
|
||||
|
||||
```ts
|
||||
useOf = (
|
||||
moduleExportOrType: ModuleExport | 'story' | 'meta' | 'component',
|
||||
validTypes?: Array<'story' | 'meta' | 'component'>
|
||||
): EnhancedResolvedModuleExportType
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
##### `moduleExportOrType` (required)
|
||||
|
||||
Type: `ModuleExport | 'story' | 'meta' | 'component'`
|
||||
|
||||
Provides the story export, meta export, component export, or CSF file exports that you want to get annotations from.
|
||||
|
||||
When the custom block is in an [attached doc](./doc-block-meta.md#attached-vs-unattached), it’s also possible to get the primary (first) story, meta, or component by passing in a string instead. This is useful as a fallback, so the `of` prop can be omitted in your block. The most common pattern is using this as `useOf(props.of || 'story')` which will fall back to the primary story if no `of` prop is defined.
|
||||
|
||||
- `useOf('story')` returns the annotated primary story in attached mode, error in unattached mode
|
||||
- `useOf('meta')` returns the annotated meta in attached mode, error in unattached mode
|
||||
- `useOf('component')` returns the annotated component specified in the meta in attached mode, error in unattached mode
|
||||
|
||||
##### `validTypes`
|
||||
|
||||
Type: `Array<'story' | 'meta' | 'component'>`
|
||||
|
||||
Optionally specify an array of valid types that your block accepts. Ie. the Canvas block only accepts references to stories, not meta or component, so it has `useOf(of, ['story'])` . If anything else than the valid types are passed in, an error will be thrown.
|
||||
|
||||
#### Return
|
||||
|
||||
The return value depends on the matched type:
|
||||
|
||||
##### `EnhancedResolvedModuleExportType['type'] === 'story'`
|
||||
|
||||
Type: `{ type: 'story', story: PreparedStory }`
|
||||
|
||||
For stories, annotated stories are returned as is. They are prepared, meaning that they are already merged with project and meta annotations.
|
||||
|
||||
##### `EnhancedResolvedModuleExportType['type'] === 'meta'`
|
||||
|
||||
Type: `{ type: 'meta', csfFile: CSFFile, preparedMeta: PreparedMeta }`
|
||||
|
||||
For meta, the parsed CSF file is returned, along with prepared annotated meta. That is, project annotations merged with meta annotations, but no story annotations.
|
||||
|
||||
##### `EnhancedResolvedModuleExportType['type'] === 'component'`
|
||||
|
||||
Type: `{ type: 'component', component: Component, projectAnnotations: NormalizedProjectAnnotations }`
|
||||
|
||||
For components, the component is returned along with project annotations; no meta or story annotations.
|
||||
|
||||
Note that it’s often impossible for the hook to determine if a component is passed in or any other object, so it behaves like an `unknown` type as well.
|
||||
142
docs/toc.js
142
docs/toc.js
@ -121,51 +121,9 @@ module.exports = {
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: '',
|
||||
title: 'Doc Blocks',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'doc-block-argstable',
|
||||
title: 'ArgsTable',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-canvas',
|
||||
title: 'Canvas',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-colorpalette',
|
||||
title: 'ColorPalette',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-description',
|
||||
title: 'Description',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-icongallery',
|
||||
title: 'IconGallery',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-source',
|
||||
title: 'Source',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-story',
|
||||
title: 'Story',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-typeset',
|
||||
title: 'Typeset',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
pathSegment: 'doc-blocks',
|
||||
title: 'Doc blocks',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'build-documentation',
|
||||
@ -377,7 +335,7 @@ module.exports = {
|
||||
title: 'Integration',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
{
|
||||
pathSegment: 'frameworks',
|
||||
title: 'Frameworks',
|
||||
type: 'link',
|
||||
@ -480,6 +438,98 @@ module.exports = {
|
||||
pathSegment: 'api',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
title: '@storybook/blocks',
|
||||
pathSegment: '',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'doc-block-argtypes',
|
||||
title: 'ArgTypes',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-canvas',
|
||||
title: 'Canvas',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-colorpalette',
|
||||
title: 'ColorPalette',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-controls',
|
||||
title: 'Controls',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-description',
|
||||
title: 'Description',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-icongallery',
|
||||
title: 'IconGallery',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-markdown',
|
||||
title: 'Markdown',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-meta',
|
||||
title: 'Meta',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-primary',
|
||||
title: 'Primary',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-source',
|
||||
title: 'Source',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-stories',
|
||||
title: 'Stories',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-story',
|
||||
title: 'Story',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-subtitle',
|
||||
title: 'Subtitle',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-title',
|
||||
title: 'Title',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-typeset',
|
||||
title: 'Typeset',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-unstyled',
|
||||
title: 'Unstyled',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-block-useof',
|
||||
title: 'useOf',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Stories',
|
||||
pathSegment: '',
|
||||
|
||||
@ -1,190 +0,0 @@
|
||||
---
|
||||
title: 'ArgsTable'
|
||||
---
|
||||
|
||||
Storybook Docs automatically generates component args tables for components in supported frameworks. These tables list the arguments ([args for short](../writing-stories/args.md)) of the component, and even integrate with [controls](../essentials/controls.md) to allow you to change the args of the currently rendered story.
|
||||
|
||||
<video autoPlay muted playsInline loop>
|
||||
<source
|
||||
src="addon-controls-docs-optimized.mp4"
|
||||
type="video/mp4"
|
||||
/>
|
||||
</video>
|
||||
|
||||
This is extremely useful, but it can be further expanded. Additional information can be added to the component to better document it:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/button-component-with-proptypes.js.mdx',
|
||||
'react/button-component-with-proptypes.ts.mdx',
|
||||
'angular/button-component-with-proptypes.ts.mdx',
|
||||
'vue/button-component-with-proptypes.2.js.mdx',
|
||||
'vue/button-component-with-proptypes.ts-2.ts.mdx',
|
||||
'vue/button-component-with-proptypes.3.js.mdx',
|
||||
'vue/button-component-with-proptypes.ts-3.ts.mdx',
|
||||
'svelte/button-component-with-proptypes.js.mdx',
|
||||
'web-components/button-component-with-proptypes.js.mdx',
|
||||
'web-components/button-component-with-proptypes.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
The args tables will be updated accordingly by including the additional information (e.g., JSDocs comments), offering a richer experience for any stakeholders involved.
|
||||
|
||||
## Working with Automatic Docs
|
||||
|
||||
To use the `ArgsTable` Doc Block with Storybook's automatically generated documentation ([AutoDocs](./docs-page.md) for short), export a component property on your stories metadata:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/my-component-story.js.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Working with MDX
|
||||
|
||||
If you need, you can also include the `ArgsTable` block in your MDX stories. Below is a condensed table of available options and examples:
|
||||
|
||||
| Option | Description |
|
||||
| ------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `of` | Infers the args table from the component. <br/> `<ArgsTable of={MyComponent} />` |
|
||||
| `story` | Infers the args table based on a story. <br/> `<ArgsTable story="example-mycomponent--my-story" />` |
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/component-story-mdx-argstable-block-for-component.with-component.mdx.mdx',
|
||||
'common/component-story-mdx-argstable-block-for-story.with-story.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
### Customizing
|
||||
|
||||
`ArgsTables` are generated based on an internal data structure called [ArgTypes](../api/argtypes.md). When you define the component's metadata element in your story, Storybook's Docs will automatically extract the ArgTypes based on available properties.
|
||||
|
||||
If you need, you can customize what is displayed in the `ArgsTable` by extending the `ArgTypes` data, unless you're using the `ArgsTable of={component} />`. In this case, Storybook will infer the data automatically from the component.
|
||||
|
||||
Below is an abridged table and example featuring the available options.
|
||||
|
||||
|
||||
| Field | Description |
|
||||
|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `name` | The name of the property. <br/> `argTypes: { label: { name: 'Something' } }` |
|
||||
| `type.name` | Sets a type for the property. <br/> `argTypes: { label: { type: { name: 'number' } } }` |
|
||||
| `type.required` | Sets the property as optional or required. <br/> `argTypes: { label: { type: { required: true } }` |
|
||||
| `description` | Sets a Markdown description for the property. <br/> `argTypes: { label: { description: 'Something' } }` |
|
||||
| `table.type.summary` | Provide a short version of the type. <br/> `argTypes: { label: { table: { type: { summary: 'a short summary' } }}}` |
|
||||
| `table.type.detail` | Provides an extended version of the type. <br/> `argTypes: { label: { table: { type: { detail: 'something' } }}}` |
|
||||
| `table.defaultValue.summary` | Provide a short version of the default value. <br/> `argTypes: { label: { table: { defaultValue: { summary: 'Hello World' } }}}` |
|
||||
| `table.defaultValue.detail` | Provides a longer version of the default value. <br/> `argTypes: { label: { table: { defaultValue: { detail: 'Something' } }}}` |
|
||||
| `control` | Associates a control for the property. <br/> `argTypes: { label: { control: { type: 'text'} } }` <br/>Read the [Essentials documentation](../essentials/controls.md) to learn more about controls. |
|
||||
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/component-story-csf-argstable-customization.js.mdx',
|
||||
'common/component-story-mdx-argtypes.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 This API is experimental and may change outside the typical semver release cycle. Read the documentation to learn more about [ArgTypes](../api/argtypes.md).
|
||||
|
||||
</div>
|
||||
|
||||
This would render a row with a modified description, a type display with a dropdown that shows the detail, and no control.
|
||||
|
||||
#### Shorthands
|
||||
|
||||
To reduce the boilerplate code you have to write, Storybook provides some convenient shorthands to help you streamline your work. Below are some of the available shorthands.
|
||||
|
||||
| Type | Shorthand |
|
||||
| -------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `type.name` | Assigns the type to a number property. <br/> `argTypes: { label: { type: number }` |
|
||||
| `control.type` | Assigns a radio control for the property. <br/> `argTypes: { size: { control: 'radio' } }` |
|
||||
|
||||
### Grouping
|
||||
|
||||
You can also extend the ArgsTable's customization by grouping related `argTypes` into categories or even subcategories. Based on the following component implementation:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/button-implementation.js.mdx',
|
||||
'react/button-implementation.ts.mdx',
|
||||
'angular/button-implementation.ts.mdx',
|
||||
'vue/button-implementation.2.js.mdx',
|
||||
'vue/button-implementation.ts-2.ts.mdx',
|
||||
'vue/button-implementation.3.js.mdx',
|
||||
'vue/button-implementation.ts-3.ts.mdx',
|
||||
'svelte/button-implementation.js.mdx',
|
||||
'web-components/button-implementation.js.mdx',
|
||||
'web-components/button-implementation.ts.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
You could group similar properties for better organization and structure. Using the table below as a reference:
|
||||
|
||||
| Field | Category |
|
||||
| :------------------ | :------: |
|
||||
| **backgroundColor** | Colors |
|
||||
| **primary** | Colors |
|
||||
| **label** | Text |
|
||||
| **onClick** | Events |
|
||||
| **size** | Sizes |
|
||||
|
||||
Results in the following change into your story and UI.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/button-story-argtypes-with-categories.js.mdx'
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
|
||||
|
||||
You can also extend the formula above and introduce subcategories, allowing better structuring and organization. Using the table below as a reference leads to the following change to your story and UI:
|
||||
|
||||
| Field | Category | Subcategory |
|
||||
| :------------------ | :------: | :-------------: |
|
||||
| **backgroundColor** | Colors | Button colors |
|
||||
| **primary** | Colors | Button style |
|
||||
| **label** | Text | Button contents |
|
||||
| **onClick** | Events | Button Events |
|
||||
| **size** | Sizes | |
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/button-story-argtypes-with-subcategories.js.mdx'
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
|
||||
|
||||
### Controls
|
||||
|
||||
The controls inside an `ArgsTable` are configured in exactly the same way as the [controls](../essentials/controls.md) addon pane. You’ll probably notice the table is very similar! It uses the same component and mechanism behind the scenes.
|
||||
@ -1,68 +0,0 @@
|
||||
---
|
||||
title: 'Canvas'
|
||||
---
|
||||
|
||||
Storybook's `Canvas` Doc Block is a wrapper featuring a toolbar that allows you to interact with its content while automatically providing the required [Source](./doc-block-source.md) snippets.
|
||||
|
||||
|
||||
|
||||
## Working with Automatic Docs
|
||||
|
||||
Storybook's [AutoDocs](./docs-page.md) wraps each story inside a `Canvas` Doc Block. The first story rendered in the DocsPage is automatically configured with a toolbar and set as _primary_. All other existing stories will not feature the toolbar. It also includes a [Source](./doc-block-source.md) Doc Block to visualize the story code snippet.
|
||||
|
||||
## Working with MDX
|
||||
|
||||
The `Canvas` Doc Block includes additional customization options if you're writing MDX stories. Below is a condensed example and table featuring all the available options.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/mdx-canvas-doc-block.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
| Option | Description |
|
||||
| ------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `columns` | Splits the stories based on the number of defined columns. <br/> `<Canvas columns={2}></Canvas>` |
|
||||
| `isColumn` | Displays the stories one above the other. <br/> `<Canvas isColumn></Canvas>` |
|
||||
| `withSource` | Controls the source code block visibility. <br/> `Canvas withSource="open"></Canvas>` |
|
||||
| `withToolbar` | Sets the `Canvas` toolbar visibility. <br/> `<Canvas withToolbar></Canvas>` |
|
||||
|
||||
### Rendering multiple stories
|
||||
|
||||
If you want, you can also group multiple stories and render them inside a single `Canvas` Doc Block. For example:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/mdx-canvas-multiple-stories.mdx.mdx',
|
||||
'angular/mdx-canvas-multiple-stories.mdx.mdx',
|
||||
'vue/mdx-canvas-multiple-stories.mdx-2.mdx.mdx',
|
||||
'vue/mdx-canvas-multiple-stories.mdx-3.mdx.mdx',
|
||||
'svelte/mdx-canvas-multiple-stories.mdx.mdx',
|
||||
]}
|
||||
usesCsf3
|
||||
csf2Path="writing-docs/doc-block-canvas#snippet-mdx-canvas-multiple-stories"
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Non-story content
|
||||
|
||||
Additionally, you can also place non-story related content inside `Canvas` Doc Block allowing you to render the JSX content precisely as it would if you placed it inside an MDX file, for example:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/my-component-with-story-content.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
When rendered, Storybook will automatically generate the code snippet for this inside the [Source](./doc-block-source.md) block beneath the block.
|
||||
@ -1,28 +0,0 @@
|
||||
---
|
||||
title: 'ColorPalette'
|
||||
---
|
||||
|
||||
Storybook's `ColorPalette` Doc block allows you to document all color-related items (e.g., swatches) used throughout your project.
|
||||
|
||||
|
||||
|
||||
## Working with MDX
|
||||
|
||||
Similar to [`Typeset`](./doc-block-typeset.md), the `ColorPalette` Doc Block is also typically used with MDX. It supports additional customization via options. Below are some examples and a table with all the available options.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/colorpalette-doc-block.starter-example.mdx.mdx',
|
||||
'common/colopalette-doc-block.advanced-example.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
| Option | Description |
|
||||
| ---------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| `title` | Sets the name of the color to be displayed. <br/> `<ColorItem title='tomato' />` |
|
||||
| `subtitle` | Provides an additional description to the color. <br/> `<ColorItem subtitle='This is a bright red color' />` |
|
||||
| `colors` | Provides the list of colors to be displayed. <br/> `<ColorItem colors={{ White: '#FFFFFF', Concrete: '#F3F3F3' } />` |
|
||||
@ -1,44 +0,0 @@
|
||||
---
|
||||
title: 'Description'
|
||||
---
|
||||
|
||||
Storybook's `Description` Doc Block displays the component's description obtained from its source code or user-generated content.
|
||||
|
||||
|
||||
|
||||
## Working with Automatic Docs
|
||||
|
||||
Storybook extracts the component's description and renders it at the top of the page. It is automatically generated from the docgen component for the [supported frameworks](../api/frameworks-feature-support.md) based on the component's source code. Below is an abridged example and available options.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/component-story-csf-description.js.mdx',
|
||||
]}
|
||||
usesCsf3
|
||||
csf2Path="writing-docs/doc-block-description#snippet-component-story-csf-description"
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
| Option | Description |
|
||||
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `component` | Overrides the default component description. <br/> `description: { component:'An example component description' }` |
|
||||
| `markdown` | Provides custom Markdown for the component description. <br/> `<Description markdown={dedent'# Custom Description'} />` <br/> Only applicable to MDX. |
|
||||
| `story` | Overrides the story description. <br/> `description: { story: 'An example story description' }` |
|
||||
| `of` | Sets the description based either on a component or story. <br/> `<Description of={Component} />` <br/> `<Description of={'.'} />` <br/> Only applicable to MDX. |
|
||||
|
||||
## Working with MDX
|
||||
|
||||
If you need, you can also include the `Description` Doc Block in your MDX stories. It relies on the same heuristics as the one applied in the DocsPage. For example:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/component-story-mdx-description.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
@ -1,25 +0,0 @@
|
||||
---
|
||||
title: 'IconGallery'
|
||||
---
|
||||
|
||||
Storybook's `IconGallery` Doc Block enables you easily document all icons associated with your project.
|
||||
|
||||
|
||||
|
||||
## Working with MDX
|
||||
|
||||
Similar to other documentation-oriented Doc Blocks such as [`TypeSet`](./doc-block-typeset.md), or [`ColorPalette`](./doc-block-colorpalette.md), the `IconGallery` is also typically used with MDX. It allows you to provide additional customization via options. Below is a condensed example and table featuring all the available options.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/icongallery-doc-block.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
| Option | Description |
|
||||
| ------ | --------------------------------------------------------- |
|
||||
| `name` | Sets the name of the icon. <br/> `<IconItem name="add"/>` |
|
||||
@ -1,59 +0,0 @@
|
||||
---
|
||||
title: 'Source'
|
||||
---
|
||||
|
||||
Storybook's `Source` Doc Block displays the story's source code. It supports syntax highlighting for most languages (e.g., `javascript`, `jsx`, `json`, `yml`, `md`, `bash`, `css`, `html`) and can be copied with the click of a button.
|
||||
|
||||
|
||||
|
||||
## Working with Automatic Docs
|
||||
|
||||
Storybook automatically generates a `Source` Doc Block within the [Canvas](./doc-block-canvas.md) to display the story's code snippet.
|
||||
It includes additional customization via parameters. Below is a condensed example and tables featuring all the available options.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/component-story-custom-source.js.mdx',
|
||||
]}
|
||||
usesCsf3
|
||||
csf2Path="writing-docs/doc-block-source#snippet-component-story-custom-source"
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<div class="aside">
|
||||
|
||||
💡 The pattern demonstrated here applies only to the story. If you need, you can apply this to all the component stories, introducing a [component parameter](../writing-stories/parameters.md#component-parameters).
|
||||
|
||||
</div>
|
||||
|
||||
| Option | Description |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `code` | Customizes the code snippet to be displayed. <br/> `docs: { source: { code: '<h1>Hello world</h1>' } }`. <br/> Requires `language` for proper syntax highlighting. |
|
||||
| `dark` | Sets the background to dark mode. <br/> `<Source dark/>` <br/> Applies only to `MDX`. |
|
||||
| `id` | Supplies a unique story identifier. <br/> `<Source id="example-mycomponent--starter" />` <br/> Applies only to `MDX`. |
|
||||
| `language` | Sets the language for syntax highlighting. <br/> `docs: { source: { language: 'html'} }` |
|
||||
| `format` | Formats the code snippet. <br/> `docs: { source: { format:false } }` |
|
||||
| `type` | Sets how the story source snippet is auto-generated. See table below for available values. |
|
||||
|
||||
| Value | Description | Support |
|
||||
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
|
||||
| **auto** (default) | Use `dynamic` snippets if the story is written using [Args](../writing-stories/args.md) and the framework supports it.<br/> `docs: { source: { type: 'auto' } }` | All |
|
||||
| **dynamic** | Dynamically generated code snippet based on the output of the story function (e.g, JSX code for React). <br/> `docs: { source: { type: 'dynamic' } }` | [Limited](../api/frameworks-feature-support.md) |
|
||||
| **code** | Use the raw story source as written in the story file. <br/> `docs: { source: { type: 'code' } }` | All |
|
||||
|
||||
## Working with MDX
|
||||
|
||||
If you need, you can also include the `Source` Doc Block in your MDX stories. It accepts either a story ID or a code snippet. For example:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/component-story-mdx-dedent.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
@ -1,52 +0,0 @@
|
||||
---
|
||||
title: 'Story'
|
||||
---
|
||||
|
||||
Stories (component tests) are Storybook's fundamental building blocks.
|
||||
In Storybook Docs, stories are rendered in the `Story` block.
|
||||
|
||||
|
||||
|
||||
## Working with Automatic Docs
|
||||
|
||||
With each story you write, Storybook will automatically generate a new `Story` Doc Block, wrapped inside a [`Canvas`](./doc-block-canvas.md)(with a toolbar if it's the first "primary" story) alongside a [source code](./doc-block-source.md) preview underneath it. Below is a condensed table of the available configuration options.
|
||||
|
||||
| Option | Description |
|
||||
| --------------- | ------------------------------------------------------------------------------------- |
|
||||
| `inlineStories` | Configures Storybook to render stories inline. <br/> `docs: { inlineStories: false }` |
|
||||
|
||||
## Working with MDX
|
||||
|
||||
With MDX, the `Story` block is not only a way of rendering stories, but how you define them. Internally, Storybook looks for named `Story` instances located at the top of your document, or inside a [Canvas](./doc-block-canvas.md). Below is an abridged example and table featuring all the available options.
|
||||
|
||||
| Option | Description |
|
||||
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `args` | Provide the required component inputs (e.g., props). <br/> `<Story args={{ text: 'Button' }}/>` <br/> Read the [documentation](../writing-stories/args.md) to learn more. |
|
||||
| `decorators` | Provide additional markup or mock a data provider to allow proper story rendering. <br/> `<Story decorators={[(Story) => ( <div style={{ margin: '3em' }}><Story/></div>)]}/>` <br/> Read the [documentation](../writing-stories/decorators.md) to learn more. |
|
||||
| `id` | Storybook's internal story identifier. Used for embedding Storybook stories inside Docs. <br/> `<Story id="example-mycomponent--starter"/>` <br/> Read the <LinkWithVersion version="6.5" href="../api/mdx.md#embedding-stories">documentation</LinkWithVersion> to learn more. |
|
||||
| `inline` | Enables Storybook's inline renderer. <br/> `<Story inline={false}/>` <br/> Read the [documentation](./docs-page.md#inline-stories-vs-iframe-stories) to learn more. |
|
||||
| `loaders` | (Experimental) Asynchronous function for data fetching with stories. <br/> `<Story loaders={[async () => ({ data: await (await fetch('your-endpoint'))}) ]}/>` <br/> Read the [documentation](../writing-stories/loaders.md) to learn more. |
|
||||
| `name` | Adds a name to the component story. <br/> `<Story name="Example"/>` . |
|
||||
| `parameters` | Provides the necessary static named metadata related to the story. <br/> `Story parameters={{ backgrounds: { values: [{ name:'red', value:'#f00' }] } }} />` <br/> Read the [documentation](../writing-stories/parameters.md) to learn more. |
|
||||
| `play` | Generate component interactions. <br/> `<Story play={async () => { await userEvent.click(screen.getByRole('button')) }}/>` <br/> Read the [documentation](../writing-stories/play-function.md) to learn more. |
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'react/component-story-mdx-story-by-name.mdx.mdx',
|
||||
'angular/component-story-mdx-story-by-name.mdx.mdx',
|
||||
'vue/component-story-mdx-story-by-name.mdx-2.mdx.mdx',
|
||||
'vue/component-story-mdx-story-by-name.mdx-3.mdx.mdx',
|
||||
'svelte/component-story-mdx-story-by-name.mdx.mdx',
|
||||
'common/component-story-mdx-reference-storyid.mdx.mdx',
|
||||
]}
|
||||
usesCsf3
|
||||
csf2Path="writing-docs/doc-block-story#snippet-component-story-mdx-story-by-name"
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Inline rendering
|
||||
|
||||
All stories are rendered in the Preview iframe for isolated development in Storybook's Canvas. With Docs, if your framework supports inline rendering, it will be used by default for both performance and convenience. However, you can force this feature by providing the required configuration option (see tables above).
|
||||
@ -1,28 +0,0 @@
|
||||
---
|
||||
title: 'Typeset'
|
||||
---
|
||||
|
||||
Storybook's `Typeset` Doc Block helps document the fonts used throughout your project.
|
||||
|
||||
|
||||
|
||||
## Working with MDX
|
||||
|
||||
Similar to other documentation related Doc Blocks (e.g., `ColorPalette`, `IconGallery`), the `TypeSet` Doc Block is also commonly used with MDX. It allows additional customization via options. Below is a condensed example and table featuring all the available options.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'common/typeset-doc.block.mdx.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
| Option | Description |
|
||||
| ------------ | --------------------------------------------------------------------------------------- |
|
||||
| `fontFamily` | Provides a font family to be displayed . <br/> `<Typeset fontFamily={"Nunito Sans"} />` |
|
||||
| `fontSizes` | Provides a list of available font sizes. <br/> `<Typeset fontSizes={[ 12, 14, 20 ]} />` |
|
||||
| `fontWeight` | Defines the weight of the font to be displayed. <br/> `<Typeset fontWeight={800} />` |
|
||||
| `sampleText` | Defines the text to be displayed. <br/> `<Typeset sampleText='Example Text' />` |
|
||||
89
docs/writing-docs/doc-blocks.md
Normal file
89
docs/writing-docs/doc-blocks.md
Normal file
@ -0,0 +1,89 @@
|
||||
---
|
||||
title: Doc blocks
|
||||
---
|
||||
|
||||
Storybook offers a number of doc blocks to help document your components and other aspects of your project.
|
||||
|
||||
The blocks are most commonly used within Storybook's [MDX documentation](./mdx.md):
|
||||
|
||||
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```md
|
||||
{/* ButtonDocs.mdx */}
|
||||
import { Meta, Primary, Controls, Story } from '@storybook/blocks';
|
||||
import * as ButtonStories from './Button.stories';
|
||||
|
||||
<Meta of={ButtonStories} />
|
||||
|
||||
# Button
|
||||
|
||||
A button is ...
|
||||
|
||||
<Primary />
|
||||
|
||||
## Props
|
||||
|
||||
<Controls />
|
||||
|
||||
## Stories
|
||||
|
||||
### Primary
|
||||
|
||||
Button can be primary-colored
|
||||
|
||||
<Story of={ButtonStories.Primary} />
|
||||
|
||||
Button can be secondary-colored
|
||||
|
||||
<Story of={ButtonStories.Secondary} />
|
||||
|
||||
{/* ... */}
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
The blocks are also used in the default template for [automatics docs](./docs-page.md#setup-automated-documentation):
|
||||
|
||||
|
||||
|
||||
```jsx
|
||||
import { Title, Subtitle, Description, Primary, Controls, Stories } from '@storybook/blocks';
|
||||
|
||||
export const autoDocsTemplate = () => (
|
||||
<>
|
||||
<Title />
|
||||
<Subtitle />
|
||||
<Description />
|
||||
<Primary />
|
||||
<Controls />
|
||||
<Stories />
|
||||
</>
|
||||
);
|
||||
```
|
||||
|
||||
That template will show the primary (i.e. first) story for the component, a table documenting (and allowing you to control) the arg types of the primary story, and a list of all the stories in a condensed format.
|
||||
|
||||
## Available blocks
|
||||
|
||||
For a description and API details of each block, see the API reference:
|
||||
|
||||
- [`ArgTypes`](../api/doc-block-argtypes.md)
|
||||
- [`Canvas`](../api/doc-block-canvas.md)
|
||||
- [`ColorPalette`](../api/doc-block-colorpalette.md)
|
||||
- [`Controls`](../api/doc-block-controls.md)
|
||||
- [`Description`](../api/doc-block-description.md)
|
||||
- [`IconGallery`](../api/doc-block-icongallery.md)
|
||||
- [`Markdown`](../api/doc-block-markdown.md)
|
||||
- [`Meta`](../api/doc-block-meta.md)
|
||||
- [`Primary`](../api/doc-block-primary.md)
|
||||
- [`Source`](../api/doc-block-source.md)
|
||||
- [`Stories`](../api/doc-block-stories.md)
|
||||
- [`Story`](../api/doc-block-story.md)
|
||||
- [`Subtitle`](../api/doc-block-subtitle.md)
|
||||
- [`Title`](../api/doc-block-title.md)
|
||||
- [`Typeset`](../api/doc-block-typeset.md)
|
||||
- [`Unstyled`](../api/doc-block-unstyled.md)
|
||||
|
||||
## Make your own doc blocks
|
||||
|
||||
Storybook also provides a [`useOf` hook](../api/doc-block-useof.md) to make it easier to create your own blocks that function in the same manner as the built-in blocks.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 59 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 13 KiB |
Loading…
x
Reference in New Issue
Block a user