diff --git a/docs/api/argtypes.md b/docs/api/argtypes.md index 2771c73dc4b..945d74ab196 100644 --- a/docs/api/argtypes.md +++ b/docs/api/argtypes.md @@ -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. -
- -đź’ˇ 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' } - -
- -#### 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: +
+đź’ˇ As with other Storybook properties (e.g., args, decorators), you can also override ArgTypes per story basis. +
+ `argTypes: { label: { name: 'Something' } }` | +| `type.name` | Sets a type for the property.
`argTypes: { label: { type: { name: 'number' } } }` | +| `type.required` | Sets the property as optional or required.
`argTypes: { label: { type: { required: true } }` | +| `description` | Sets a Markdown description for the property.
`argTypes: { label: { description: 'Something' } }` | +| `table.type.summary` | Provide a short version of the type.
`argTypes: { label: { table: { type: { summary: 'a short summary' } }}}` | +| `table.type.detail` | Provides an extended version of the type.
`argTypes: { label: { table: { type: { detail: 'something' } }}}` | +| `table.defaultValue.summary` | Provide a short version of the default value.
`argTypes: { label: { table: { defaultValue: { summary: 'Hello World' } }}}` | +| `table.defaultValue.detail` | Provides a longer version of the default value.
`argTypes: { label: { table: { defaultValue: { detail: 'Something' } }}}` | +| `control` | Associates a control for the property.
`argTypes: { label: { control: { type: 'text'} } }`
Read the [Essentials documentation](../essentials/controls.md) to learn more about controls. | + +#### Shorthands +
-đź’ˇ 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' } +
+### Grouping + +You can also extend the ArgsTable's customization by grouping related `argTypes` into categories or even subcategories. Based on the following component implementation: + + + + + + + +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. + + + + + + + +![button story with args grouped into categories](./button-args-grouped-categories.png) + +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 | | + + + + + + + +![button story with args grouped into categories](./button-args-grouped-subcategories.png) + #### 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`: diff --git a/docs/api/doc-block-argtypes.md b/docs/api/doc-block-argtypes.md new file mode 100644 index 00000000000..fb08ae94cbe --- /dev/null +++ b/docs/api/doc-block-argtypes.md @@ -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. + +
+ +💡 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. + +
+ +![Screenshot of ArgTypes block](TK) + + +```md +{/* ButtonDocs.mdx */} +import { ArgTypes } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + +; +``` + + +## API + +### ArgTypes + +```js +import { ArgTypes } from '@storybook/blocks'; +``` + +`ArgTypes` is a React component which accepts props of type `ArgTypesProps`. + +
+ +ℹ️ 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`. + +
+ +#### `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 diff --git a/docs/api/doc-block-canvas.md b/docs/api/doc-block-canvas.md new file mode 100644 index 00000000000..99e0dce26ae --- /dev/null +++ b/docs/api/doc-block-canvas.md @@ -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. + +![Screenshot of Canvas block](./doc-block-canvas.png) + +When using the Canvas block in MDX, it references a story with the `of` prop: + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Story, Canvas } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + + + + +``` + + +
+ +đź’ˇ 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. + +
+ +## API + +### Canvas + +```js +import { Canvas } from '@storybook/blocks'; +``` + +`Canvas` is a React component which accepts props of type `CanvasProps`. + +
+ +ℹ️ 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`. + +
+ +#### `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. + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Story, Canvas, SourceState } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + + + +{/* with an additional action */} + { + window.open( + 'https://github.com/storybookjs/storybook/blob/next/code/ui/blocks/src/examples/Button.stories.tsx', + '_blank' + ); + }, + } + ]} + of={ButtonStories.Primary} +/> +``` + + +##### `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!). + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Canvas } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; +import * as HeaderStories from './Header.stories'; + + + +{/* Although this MDX file is largely concerned with Button, + it can render Header stories too */} + +``` + + +##### `of` + +Type: Story export + +Specifies which story's source is displayed. + +##### `source` + +Type: `Omit` + +See [SourceProps](./doc-block-source.md#sourceprops). + +
+ +đź’ˇ The dark prop is ignored, as the `Source` block is always rendered in dark mode when shown as part of a `Canvas` block. + +
+ +##### `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` + +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. diff --git a/docs/writing-docs/docblock-preview-toolbar.png b/docs/api/doc-block-canvas.png similarity index 100% rename from docs/writing-docs/docblock-preview-toolbar.png rename to docs/api/doc-block-canvas.png diff --git a/docs/writing-docs/doc-block-colorpalette-optimized.png b/docs/api/doc-block-colorpalette-optimized.png similarity index 100% rename from docs/writing-docs/doc-block-colorpalette-optimized.png rename to docs/api/doc-block-colorpalette-optimized.png diff --git a/docs/api/doc-block-colorpalette.md b/docs/api/doc-block-colorpalette.md new file mode 100644 index 00000000000..d506bc56125 --- /dev/null +++ b/docs/api/doc-block-colorpalette.md @@ -0,0 +1,64 @@ +--- +title: 'ColorPalette' +--- + +The `ColorPalette` block allows you to document all color-related items (e.g., swatches) used throughout your project. + +![Screenshot of ColorPalette and ColorItem blocks](./doc-block-colorpalette-optimized.png) + + + + + + + +## 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. diff --git a/docs/api/doc-block-controls.md b/docs/api/doc-block-controls.md new file mode 100644 index 00000000000..69679c3db0f --- /dev/null +++ b/docs/api/doc-block-controls.md @@ -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). + +![Screenshot of Controls block](TK) + + +```md +{/* ButtonDocs.mdx */} +import { Canvas, Controls } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories' + + + + +``` + + +## API + +### Controls + +```js +import { Controls } from '@storybook/blocks'; +``` + +`Controls` is a React component which accepts props of type `ControlsProps`. + +
+ +ℹ️ 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`. + +
+ +#### `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 diff --git a/docs/api/doc-block-description.md b/docs/api/doc-block-description.md new file mode 100644 index 00000000000..38cd9c8cdc7 --- /dev/null +++ b/docs/api/doc-block-description.md @@ -0,0 +1,144 @@ +--- +title: 'Description' +--- + +The `Description` block displays the description for a component, story, or meta, obtained from their respective JSDoc comments. + +![Screenshot of Description block](./doc-block-description.png) + + +```md +{/* ButtonDocs.mdx */} +import { Description } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + + +``` + + +## API + +### Description + +```js +import { Description } from '@storybook/blocks'; +``` + +`Description` is a React component which accepts props of type `DescriptionProps`. + +
+ +ℹ️ 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`. + +
+ +#### `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 = () => ; +``` + +```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" + } + } + } +} +``` + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Description } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + + + +{/* 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 */} + + +{/* Shows the description for the Primary export */} + +``` + diff --git a/docs/writing-docs/docblock-description.png b/docs/api/doc-block-description.png similarity index 100% rename from docs/writing-docs/docblock-description.png rename to docs/api/doc-block-description.png diff --git a/docs/writing-docs/doc-block-icon-gallery-optimized.png b/docs/api/doc-block-icon-gallery-optimized.png similarity index 100% rename from docs/writing-docs/doc-block-icon-gallery-optimized.png rename to docs/api/doc-block-icon-gallery-optimized.png diff --git a/docs/api/doc-block-icongallery.md b/docs/api/doc-block-icongallery.md new file mode 100644 index 00000000000..3ead24ad151 --- /dev/null +++ b/docs/api/doc-block-icongallery.md @@ -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. + +![Screenshot of IconGallery and IconItem blocks](./doc-block-icon-gallery-optimized.png) + + + + + + + +## 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. diff --git a/docs/api/doc-block-markdown.md b/docs/api/doc-block-markdown.md new file mode 100644 index 00000000000..aaa07c96dbb --- /dev/null +++ b/docs/api/doc-block-markdown.md @@ -0,0 +1,92 @@ +--- +title: 'Markdown' +--- + +The `Markdown` block allows you to import and include plain markdown in your MDX files. + +![Screenshot of Markdown block](TK) + + +```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 + +{ReadMe} +``` + + +## 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: + + +```md +{/* THIS WON'T WORK, THIS IS TO DEMONSTRATE AN ERROR */} + +import ReadMe from './README.md'; + +# A header + +{ReadMe} +``` + + +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: + + +```md +# A header + +{ this is valid in a plain Markdown file, but MDX2 will try to evaluate this as an expression } + + +``` + + +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. + + +```md +# A header + +
+ Some text +
+ +The example above will remain as-is in plain Markdown, but MDX2 will compile it to: + +# A header + +
+

Some text

+
+``` + diff --git a/docs/api/doc-block-meta.md b/docs/api/doc-block-meta.md new file mode 100644 index 00000000000..8098bba7098 --- /dev/null +++ b/docs/api/doc-block-meta.md @@ -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. + +
+ +💡 The Meta block doesn’t render anything visible. + +
+ +## 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`. + + +```md +{/* Component.mdx */} +import { Meta } from '@storybook/blocks'; +import * as ComponentStories from './component.stories'; + +{/* This MDX file is now called "Special Docs" */} + +``` + + +##### `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!). + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Story } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + + +``` + + +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). + +
+ +💡 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. + +
+ +##### `title` + +Type: `string` + +Sets the title of an unattached MDX file. + + +```md +{/* Introduction.mdx */} +import { Meta } from '@storybook/blocks'; + +{/* Override the docs entry's location in the sidebar with title */} + +``` + + +
+ +💡 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. + +
+ +## 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). diff --git a/docs/api/doc-block-primary.md b/docs/api/doc-block-primary.md new file mode 100644 index 00000000000..68677b7d0a3 --- /dev/null +++ b/docs/api/doc-block-primary.md @@ -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. + +![Screenshot of Primary block](TK) + +## 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. diff --git a/docs/api/doc-block-source.md b/docs/api/doc-block-source.md new file mode 100644 index 00000000000..52f6c5f8dbc --- /dev/null +++ b/docs/api/doc-block-source.md @@ -0,0 +1,116 @@ +--- +title: 'Source' +--- + +The `Source` block is used to render a snippet of source code directly. + +![Screenshot of Source block](TK) + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Source } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + + + + +``` + + +## API + +### Source + +```js +import { Source } from '@storybook/blocks'; +``` + +`Source` is a React component which accepts props of type `SourceProps`. + +
+ +ℹ️ 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`. + +
+ +#### `SourceProps` + +##### `code` + +Type: `string` + +Provides the source code to be rendered. + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Source } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + + + + +``` + + +##### `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 + +
+ +đź’ˇ Note that dynamic snippets will only work if the Story block for the story is also rendered. + +
+ +##### `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). diff --git a/docs/api/doc-block-stories.md b/docs/api/doc-block-stories.md new file mode 100644 index 00000000000..35a2d1546ba --- /dev/null +++ b/docs/api/doc-block-stories.md @@ -0,0 +1,47 @@ +--- +title: 'Stories' +--- + +The `Stories` block renders the full collection of stories in a stories file. + +![Screenshot of Stories block](TK) + +## API + +### Stories + +```js +import { Stories } from '@storybook/blocks'; +``` + +`Stories` is a React component which accepts props of type `StoriesProps`. + +
+ +ℹ️ 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`. + +
+ +#### `StoriesProps` + +##### `includePrimary` + +Type: `boolean` + +Default: `true` + +Determines if the collection of stories includes the primary (first) story. + +
+ +đź’ˇ If a stories file contains only one story and `includePrimary={true}`, the `Stories` block will render nothing to avoid a potentially confusing situation. + +
+ +##### `title` + +Type: `string` + +Default: `'Stories'` + +Sets the heading content preceding the collection of stories. diff --git a/docs/api/doc-block-story.md b/docs/api/doc-block-story.md new file mode 100644 index 00000000000..771b238a1d5 --- /dev/null +++ b/docs/api/doc-block-story.md @@ -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. + +
+ +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. + +
+ +![Screenshot of Story block](TK) + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Story } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + + + + +``` + + +## API + +### Story + +```js +import { Story } from '@storybook/blocks'; +``` + +`Story` is a React component which accepts props of type `StoryProps`. + +
+ +ℹ️ 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`. + +
+ +#### `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!). + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Story } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; +import * as HeaderStories from './Header.stories'; + + + +{/* Although this MDX file is largely concerned with Button, + it can render Header stories too */} + +``` + + +##### `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` + +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>` + +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[]` + +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[]` + +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` + +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` + +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, '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. diff --git a/docs/api/doc-block-subtitle.md b/docs/api/doc-block-subtitle.md new file mode 100644 index 00000000000..86410908c61 --- /dev/null +++ b/docs/api/doc-block-subtitle.md @@ -0,0 +1,25 @@ +--- +title: 'Subtitle' +--- + +The `Subtitle` block can serve as a secondary heading for your docs entry. + +![Screenshot of Subtitle block](TK) + +## 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`. diff --git a/docs/api/doc-block-title.md b/docs/api/doc-block-title.md new file mode 100644 index 00000000000..3ee63ed04f5 --- /dev/null +++ b/docs/api/doc-block-title.md @@ -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. + +![Screenshot of Title block](TK) + +## 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'`. diff --git a/docs/writing-docs/doc-block-typeset-optimized.png b/docs/api/doc-block-typeset-optimized.png similarity index 100% rename from docs/writing-docs/doc-block-typeset-optimized.png rename to docs/api/doc-block-typeset-optimized.png diff --git a/docs/api/doc-block-typeset.md b/docs/api/doc-block-typeset.md new file mode 100644 index 00000000000..5fa970105ce --- /dev/null +++ b/docs/api/doc-block-typeset.md @@ -0,0 +1,53 @@ +--- +title: 'Typeset' +--- + +The `Typeset` block helps document the fonts used throughout your project. + +![Screenshot of Typeset block](./doc-block-typeset-optimized.png) + + + + + + + +## 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. diff --git a/docs/api/doc-block-unstyled.md b/docs/api/doc-block-unstyled.md new file mode 100644 index 00000000000..6a7420e390c --- /dev/null +++ b/docs/api/doc-block-unstyled.md @@ -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. + + +```md +import { Unstyled } from '@storybook/blocks'; + +> This block quote will be styled + +... and so will this paragraph. + + + > This block quote will not be styled + + ... neither will this paragraph, nor the following component: + + +``` + + +Yields: + +![Screenshot of Unstyled Doc Block](TK) + +
+ +ℹ️ 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. + +
+ +
+ +💡 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`: + + +```md +
+ + + +
+``` + + +
+ +## 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. diff --git a/docs/api/doc-block-useof.md b/docs/api/doc-block-useof.md new file mode 100644 index 00000000000..8a7ea9b3ba5 --- /dev/null +++ b/docs/api/doc-block-useof.md @@ -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

{resolvedOf.story.name}

; + } + case 'meta': { + return

{resolvedOf.preparedMeta.title}

; + } + } + return null; +}; +``` + + +```md +{/* ButtonDocs.mdx */} +import { Meta } from '@storybook/blocks'; +import { StoryName } from '../.storybook/blocks/StoryName'; +import * as ButtonStories from './Button.stories'; + + + +{/* renders "Secondary" */} + + +{/* renders "Primary" */} + + +{/* renders "Button" */} + +``` + + +## 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. diff --git a/docs/toc.js b/docs/toc.js index 1ff26398043..cb9bc891f84 100644 --- a/docs/toc.js +++ b/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: '', diff --git a/docs/writing-docs/doc-block-argstable.md b/docs/writing-docs/doc-block-argstable.md deleted file mode 100644 index b112256e6a6..00000000000 --- a/docs/writing-docs/doc-block-argstable.md +++ /dev/null @@ -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. - - - -This is extremely useful, but it can be further expanded. Additional information can be added to the component to better document it: - - - - - - - -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: - - - - - - - -### 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.
`` | -| `story` | Infers the args table based on a story.
`` | - - - - - -### 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.
`argTypes: { label: { name: 'Something' } }` | -| `type.name` | Sets a type for the property.
`argTypes: { label: { type: { name: 'number' } } }` | -| `type.required` | Sets the property as optional or required.
`argTypes: { label: { type: { required: true } }` | -| `description` | Sets a Markdown description for the property.
`argTypes: { label: { description: 'Something' } }` | -| `table.type.summary` | Provide a short version of the type.
`argTypes: { label: { table: { type: { summary: 'a short summary' } }}}` | -| `table.type.detail` | Provides an extended version of the type.
`argTypes: { label: { table: { type: { detail: 'something' } }}}` | -| `table.defaultValue.summary` | Provide a short version of the default value.
`argTypes: { label: { table: { defaultValue: { summary: 'Hello World' } }}}` | -| `table.defaultValue.detail` | Provides a longer version of the default value.
`argTypes: { label: { table: { defaultValue: { detail: 'Something' } }}}` | -| `control` | Associates a control for the property.
`argTypes: { label: { control: { type: 'text'} } }`
Read the [Essentials documentation](../essentials/controls.md) to learn more about controls. | - - - - - - - - -
- -đź’ˇ This API is experimental and may change outside the typical semver release cycle. Read the documentation to learn more about [ArgTypes](../api/argtypes.md). - -
- -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.
`argTypes: { label: { type: number }` | -| `control.type` | Assigns a radio control for the property.
`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: - - - - - - - -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. - - - - - - - -![button story with args grouped into categories](./button-args-grouped-categories.png) - -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 | | - - - - - - - -![button story with args grouped into categories](./button-args-grouped-subcategories.png) - -### 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. diff --git a/docs/writing-docs/doc-block-canvas.md b/docs/writing-docs/doc-block-canvas.md deleted file mode 100644 index 7eeb45d6a3e..00000000000 --- a/docs/writing-docs/doc-block-canvas.md +++ /dev/null @@ -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. - -![Docs block with a story preview](./docblock-preview.png) - -## 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. - - - - - - - -| Option | Description | -| ------------- | ------------------------------------------------------------------------------------------------ | -| `columns` | Splits the stories based on the number of defined columns.
`` | -| `isColumn` | Displays the stories one above the other.
`` | -| `withSource` | Controls the source code block visibility.
`Canvas withSource="open">` | -| `withToolbar` | Sets the `Canvas` toolbar visibility.
`` | - -### Rendering multiple stories - -If you want, you can also group multiple stories and render them inside a single `Canvas` Doc Block. For example: - - - - - - - -### 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: - - - - - - - -When rendered, Storybook will automatically generate the code snippet for this inside the [Source](./doc-block-source.md) block beneath the block. diff --git a/docs/writing-docs/doc-block-colorpalette.md b/docs/writing-docs/doc-block-colorpalette.md deleted file mode 100644 index 6b82131d53d..00000000000 --- a/docs/writing-docs/doc-block-colorpalette.md +++ /dev/null @@ -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. - -![Storybook color palette doc block](./doc-block-colorpalette-optimized.png) - -## 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. - - - - - - - -| Option | Description | -| ---------- | -------------------------------------------------------------------------------------------------------------------- | -| `title` | Sets the name of the color to be displayed.
`` | -| `subtitle` | Provides an additional description to the color.
`` | -| `colors` | Provides the list of colors to be displayed.
`` | diff --git a/docs/writing-docs/doc-block-description.md b/docs/writing-docs/doc-block-description.md deleted file mode 100644 index a39f0a7d654..00000000000 --- a/docs/writing-docs/doc-block-description.md +++ /dev/null @@ -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. - -![Docs blocks with description](./docblock-description.png) - -## 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. - - - - - - - -| Option | Description | -| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `component` | Overrides the default component description.
`description: { component:'An example component description' }` | -| `markdown` | Provides custom Markdown for the component description.
``
Only applicable to MDX. | -| `story` | Overrides the story description.
`description: { story: 'An example story description' }` | -| `of` | Sets the description based either on a component or story.
``
``
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: - - - - - - diff --git a/docs/writing-docs/doc-block-icongallery.md b/docs/writing-docs/doc-block-icongallery.md deleted file mode 100644 index 32aa4fd0c07..00000000000 --- a/docs/writing-docs/doc-block-icongallery.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: 'IconGallery' ---- - -Storybook's `IconGallery` Doc Block enables you easily document all icons associated with your project. - -![Storybook gallery icon doc block](./doc-block-icon-gallery-optimized.png) - -## 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. - - - - - - - -| Option | Description | -| ------ | --------------------------------------------------------- | -| `name` | Sets the name of the icon.
`` | diff --git a/docs/writing-docs/doc-block-source.md b/docs/writing-docs/doc-block-source.md deleted file mode 100644 index 53101fb449e..00000000000 --- a/docs/writing-docs/doc-block-source.md +++ /dev/null @@ -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. - -![Docs blocks with source](./docblock-source.png) - -## 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. - - - - - - - -
- -đź’ˇ 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). - -
- -| Option | Description | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `code` | Customizes the code snippet to be displayed.
`docs: { source: { code: '

Hello world

' } }`.
Requires `language` for proper syntax highlighting. | -| `dark` | Sets the background to dark mode.
``
Applies only to `MDX`. | -| `id` | Supplies a unique story identifier.
``
Applies only to `MDX`. | -| `language` | Sets the language for syntax highlighting.
`docs: { source: { language: 'html'} }` | -| `format` | Formats the code snippet.
`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.
`docs: { source: { type: 'auto' } }` | All | -| **dynamic** | Dynamically generated code snippet based on the output of the story function (e.g, JSX code for React).
`docs: { source: { type: 'dynamic' } }` | [Limited](../api/frameworks-feature-support.md) | -| **code** | Use the raw story source as written in the story file.
`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: - - - - - - diff --git a/docs/writing-docs/doc-block-story.md b/docs/writing-docs/doc-block-story.md deleted file mode 100644 index ded43a3d258..00000000000 --- a/docs/writing-docs/doc-block-story.md +++ /dev/null @@ -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. - -![Docs blocks with stories](./docblock-story.png) - -## 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.
`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).
``
Read the [documentation](../writing-stories/args.md) to learn more. | -| `decorators` | Provide additional markup or mock a data provider to allow proper story rendering.
` (
)]}/>`
Read the [documentation](../writing-stories/decorators.md) to learn more. | -| `id` | Storybook's internal story identifier. Used for embedding Storybook stories inside Docs.
``
Read the documentation to learn more. | -| `inline` | Enables Storybook's inline renderer.
``
Read the [documentation](./docs-page.md#inline-stories-vs-iframe-stories) to learn more. | -| `loaders` | (Experimental) Asynchronous function for data fetching with stories.
` ({ data: await (await fetch('your-endpoint'))}) ]}/>`
Read the [documentation](../writing-stories/loaders.md) to learn more. | -| `name` | Adds a name to the component story.
`` . | -| `parameters` | Provides the necessary static named metadata related to the story.
`Story parameters={{ backgrounds: { values: [{ name:'red', value:'#f00' }] } }} />`
Read the [documentation](../writing-stories/parameters.md) to learn more. | -| `play` | Generate component interactions.
` { await userEvent.click(screen.getByRole('button')) }}/>`
Read the [documentation](../writing-stories/play-function.md) to learn more. | - - - - - - - -### 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). diff --git a/docs/writing-docs/doc-block-typeset.md b/docs/writing-docs/doc-block-typeset.md deleted file mode 100644 index 3563915a8a4..00000000000 --- a/docs/writing-docs/doc-block-typeset.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: 'Typeset' ---- - -Storybook's `Typeset` Doc Block helps document the fonts used throughout your project. - -![Docs blocks with typography](./doc-block-typeset-optimized.png) - -## 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. - - - - - - - -| Option | Description | -| ------------ | --------------------------------------------------------------------------------------- | -| `fontFamily` | Provides a font family to be displayed .
`` | -| `fontSizes` | Provides a list of available font sizes.
`` | -| `fontWeight` | Defines the weight of the font to be displayed.
`` | -| `sampleText` | Defines the text to be displayed.
`` | diff --git a/docs/writing-docs/doc-blocks.md b/docs/writing-docs/doc-blocks.md new file mode 100644 index 00000000000..a645dec1716 --- /dev/null +++ b/docs/writing-docs/doc-blocks.md @@ -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): + +![Screenshot of mdx content](TK) + + +```md +{/* ButtonDocs.mdx */} +import { Meta, Primary, Controls, Story } from '@storybook/blocks'; +import * as ButtonStories from './Button.stories'; + + + +# Button + +A button is ... + + + +## Props + + + +## Stories + +### Primary + +Button can be primary-colored + + + +Button can be secondary-colored + + + +{/* ... */} +``` + + +The blocks are also used in the default template for [automatics docs](./docs-page.md#setup-automated-documentation): + +![Screenshot of automatic docs template](TK) + +```jsx +import { Title, Subtitle, Description, Primary, Controls, Stories } from '@storybook/blocks'; + +export const autoDocsTemplate = () => ( + <> + + <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. diff --git a/docs/writing-docs/docblock-preview-multi-mdx.png b/docs/writing-docs/docblock-preview-multi-mdx.png deleted file mode 100644 index ee65b50c921..00000000000 Binary files a/docs/writing-docs/docblock-preview-multi-mdx.png and /dev/null differ diff --git a/docs/writing-docs/docblock-preview.png b/docs/writing-docs/docblock-preview.png deleted file mode 100644 index 60f79185339..00000000000 Binary files a/docs/writing-docs/docblock-preview.png and /dev/null differ diff --git a/docs/writing-docs/docblock-source.png b/docs/writing-docs/docblock-source.png deleted file mode 100644 index 9799656cac2..00000000000 Binary files a/docs/writing-docs/docblock-source.png and /dev/null differ diff --git a/docs/writing-docs/docblock-story.png b/docs/writing-docs/docblock-story.png deleted file mode 100644 index 1f93b4b36ef..00000000000 Binary files a/docs/writing-docs/docblock-story.png and /dev/null differ