From b52d3c1e72a5d872a8ac187c7e712574602c7cb9 Mon Sep 17 00:00:00 2001 From: Shaun Lloyd Date: Fri, 3 Nov 2023 13:05:44 -0400 Subject: [PATCH 1/3] Replace aside with new Callout --- docs/addons/addon-knowledge-base.md | 12 +++-- docs/addons/addon-migration-guide.md | 4 +- docs/addons/addon-types.md | 10 ++-- docs/addons/addons-api.md | 14 +++--- docs/addons/install-addons.md | 20 +++++--- docs/addons/integration-catalog.md | 12 +++-- docs/addons/writing-addons.md | 12 ++--- docs/api/arg-types.md | 12 ++--- docs/api/cli-options.md | 18 ++++--- docs/api/csf.md | 6 +-- docs/api/doc-block-argtypes.md | 6 +-- docs/api/doc-block-canvas.md | 12 ++--- docs/api/doc-block-controls.md | 18 +++---- docs/api/doc-block-meta.md | 18 +++---- docs/api/doc-block-source.md | 12 ++--- docs/api/doc-block-stories.md | 6 +-- docs/api/doc-block-story.md | 4 +- docs/api/doc-block-unstyled.md | 12 ++--- docs/api/main-config-babel-default.md | 6 +-- docs/api/main-config-babel.md | 6 +-- docs/api/main-config-core.md | 6 +-- docs/api/main-config-indexers.md | 6 +-- docs/api/main-config-manager-head.md | 6 +-- docs/api/main-config-preview-annotations.md | 6 +-- docs/api/main-config-preview-body.md | 6 +-- docs/api/main-config-preview-head.md | 6 +-- docs/api/main-config-stories.md | 12 ++--- docs/builders/vite.md | 6 +-- docs/builders/webpack.md | 7 +-- docs/configure/babel.md | 10 ++-- docs/configure/environment-variables.md | 24 +++++---- docs/configure/overview.md | 10 ++-- docs/configure/story-rendering.md | 8 +-- docs/configure/telemetry.md | 6 +-- docs/configure/theming.md | 22 ++++---- docs/configure/typescript.md | 6 +-- docs/configure/upgrading.md | 8 +-- docs/configure/webpack.md | 16 +++--- docs/contribute/code.md | 30 +++++------ docs/contribute/how-to-reproduce.md | 22 ++++---- docs/contribute/new-snippets.md | 16 +++--- docs/essentials/actions.md | 6 +-- docs/essentials/controls.md | 32 ++++++------ docs/essentials/highlight.md | 12 ++--- docs/essentials/interactions.md | 12 ++--- docs/essentials/introduction.md | 6 +-- docs/essentials/measure-and-outline.md | 8 +-- docs/essentials/toolbars-and-globals.md | 24 ++++----- docs/faq.md | 29 +++++++---- docs/get-started/install.md | 10 ++-- docs/get-started/why-storybook.md | 2 +- docs/sharing/design-integrations.md | 8 +-- docs/sharing/package-composition.md | 4 +- docs/sharing/publish-storybook.md | 18 +++---- docs/sharing/storybook-composition.md | 32 ++++++------ docs/writing-docs/autodocs.md | 24 ++++----- docs/writing-docs/doc-blocks.md | 26 +++++----- docs/writing-docs/mdx.md | 50 ++++++++++--------- docs/writing-stories/args.md | 20 ++++---- .../build-pages-with-storybook.md | 22 ++++---- docs/writing-stories/decorators.md | 8 +-- docs/writing-stories/introduction.md | 26 ++++++---- .../naming-components-and-hierarchy.md | 6 +-- docs/writing-stories/play-function.md | 14 +++--- .../stories-for-multiple-components.md | 4 +- docs/writing-stories/typescript.md | 6 +-- docs/writing-tests/accessibility-testing.md | 6 +-- docs/writing-tests/interaction-testing.md | 6 +-- docs/writing-tests/snapshot-testing.md | 22 ++++---- .../stories-in-end-to-end-tests.md | 15 +++--- docs/writing-tests/stories-in-unit-tests.md | 12 ++--- docs/writing-tests/test-runner.md | 38 +++++++------- docs/writing-tests/visual-testing.md | 12 +++-- node_modules/.yarn-state.yml | 10 ---- 74 files changed, 531 insertions(+), 458 deletions(-) delete mode 100644 node_modules/.yarn-state.yml diff --git a/docs/addons/addon-knowledge-base.md b/docs/addons/addon-knowledge-base.md index 83f8d850d532..11cdfe497464 100644 --- a/docs/addons/addon-knowledge-base.md +++ b/docs/addons/addon-knowledge-base.md @@ -78,9 +78,11 @@ Complementing the components, also included is a set of UI primitives. Use the c | Icon | [See implementation](https://github.com/storybookjs/storybook/blob/main/code/ui/components/src/icon/icons.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-icon--labels) | | Typography | [See implementation](https://github.com/storybookjs/storybook/tree/master/code/ui/components/src/typography) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-typography--all) | -
+ + The color palette implemented by @storybook/components is a high-level abstraction of the @storybook/theming package. -
+ + ### Build system @@ -94,9 +96,11 @@ When you're developing your addon as a package, you can’t use `npm link` to ad } ``` -
+ + Run either yarn or npm install to install the addon. -
+ + ### Hot module replacement diff --git a/docs/addons/addon-migration-guide.md b/docs/addons/addon-migration-guide.md index f3e8b78a4812..8a7bd08c7470 100644 --- a/docs/addons/addon-migration-guide.md +++ b/docs/addons/addon-migration-guide.md @@ -4,11 +4,11 @@ title: Addon migration guide for Storybook 7.0 Storybook 7 is our first major release in over two years. While Storybook’s addon API has not changed much in the past couple of years, addons require several changes for compatibility with Storybook 7. This guide will walk you through the upgrade process. -
+ As we gather feedback from the community, we’ll update this page. We also have a general [Storybook migration guide](../migration-guide.md) if you’re looking for that. -
+ ## Dependencies diff --git a/docs/addons/addon-types.md b/docs/addons/addon-types.md index 8bb21021496d..d76edca7c7d6 100644 --- a/docs/addons/addon-types.md +++ b/docs/addons/addon-types.md @@ -44,11 +44,11 @@ Use this boilerplate code to add a new `button` to Storybook's Toolbar: -
+ The icon element used in the example loads the icons from the @storybook/components package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. -
+ ### Tabs @@ -68,9 +68,11 @@ Use this boilerplate code to add a new `Tab` to Storybook's UI: -
+ + Learn how to write your own addon that includes these UI elements here. -
+ + ## Preset addons diff --git a/docs/addons/addons-api.md b/docs/addons/addons-api.md index 17c05b0a50d5..42a3ccdbc24d 100644 --- a/docs/addons/addons-api.md +++ b/docs/addons/addons-api.md @@ -39,9 +39,11 @@ The `add` method allows you to register the type of UI component associated with -
-ℹ️ The render function is called with `active` and `key`. The `active` value will be true when the panel is focused on the UI. -
+ + +The render function is called with `active` and `key`. The `active` value will be true when the panel is focused on the UI. + + ### addons.register() @@ -89,11 +91,11 @@ Use the `makeDecorator` API to create decorators in the style of the official ad -
+ -ℹ️ If the story's parameters include `{ exampleParameter: { disable: true } }` (where `exampleParameter` is the `parameterName` of your addon), your decorator will not be called. + If the story's parameters include `{ exampleParameter: { disable: true } }` (where `exampleParameter` is the `parameterName` of your addon), your decorator will not be called. -
+ The `makeDecorator` API requires the following arguments: diff --git a/docs/addons/install-addons.md b/docs/addons/install-addons.md index 853ca0873c14..0990f3022ce2 100644 --- a/docs/addons/install-addons.md +++ b/docs/addons/install-addons.md @@ -35,9 +35,11 @@ Next, update [`.storybook/main.js|ts`](../configure/overview.md#configure-story- -
+ + Addons may also require addon-specific configuration. Read their respective READMEs. -
+ + Now when you run Storybook the accessibility testing addon will be enabled. @@ -60,9 +62,11 @@ For example, to use SCSS styling, run the following command to install the addon -
- 💡 Tip: Use the Webpack 5 snippet only if your framework already includes support for this version. Otherwise, use the Webpack 4 snippet. -
+ + +Use the Webpack 5 snippet only if your framework already includes support for this version. Otherwise, use the Webpack 4 snippet. + + Next, update [`.storybook/main.js|ts`](../configure/overview.md#configure-story-rendering) to the following: @@ -99,8 +103,10 @@ Consider the following example: -
+ + Preset addons may also have addon-specific configurations. Read their respective READMEs. -
+ + Now, when Storybook starts up, it will update webpack's CSS loader to use modules and adjust how styling is defined. diff --git a/docs/addons/integration-catalog.md b/docs/addons/integration-catalog.md index e2d1215c0a93..b6d018724c89 100644 --- a/docs/addons/integration-catalog.md +++ b/docs/addons/integration-catalog.md @@ -15,11 +15,11 @@ Add your addon to the catalog by publishing a npm package that follows these req - `/dist` directory containing transpiled ES5 code - `preset.js` file written as an ES5 module at the root level -
+ Get a refresher on how to [write a Storybook addon](./writing-addons.md). -
+ ### Addon metadata @@ -54,9 +54,11 @@ Use the list below as a reference when filling in the values for both the `suppo - preact - react-native -
-💡 Make sure to copy each item exactly as listed so that we can properly index your addon in our catalog. -
+ + +Make sure to copy each item exactly as listed so that we can properly index your addon in our catalog. + + ```json { diff --git a/docs/addons/writing-addons.md b/docs/addons/writing-addons.md index db951af33832..67875a7e6c3e 100644 --- a/docs/addons/writing-addons.md +++ b/docs/addons/writing-addons.md @@ -63,11 +63,11 @@ Clone the repository you just created and install its dependencies. When the ins -
+ -ℹ️ The Addon Kit uses [Typescript](https://www.typescriptlang.org/) by default. If you want to use JavaScript instead, you can run the `eject-ts` command to convert the project to JavaScript. +The Addon Kit uses [Typescript](https://www.typescriptlang.org/) by default. If you want to use JavaScript instead, you can run the `eject-ts` command to convert the project to JavaScript. -
+ ### Understanding the build system @@ -283,11 +283,11 @@ The second metadata category is related to the [integration catalog](https://sto } ``` -
+ -ℹ️ The `storybook` configuration element includes additional properties that help customize the addon's searchability and indexing. For more information, see the [Integration catalog documentation](./integration-catalog.md). +The `storybook` configuration element includes additional properties that help customize the addon's searchability and indexing. For more information, see the [Integration catalog documentation](./integration-catalog.md). -
+ One essential item to note is the `keywords` property as it maps to the catalog's tag system. Adding the `storybook-addons` ensures that the addon is discoverable in the catalog when searching for addons. The remaining keywords help with the searchability and categorization of the addon. diff --git a/docs/api/arg-types.md b/docs/api/arg-types.md index c6ae8fa6e056..5cf1a9006355 100644 --- a/docs/api/arg-types.md +++ b/docs/api/arg-types.md @@ -166,11 +166,11 @@ Specifies the type of control used to change the arg value with the [controls ad | | `'date'` | Provides a datepicker to choose a date.
`{ control: 'date' }` | | | `'text'` | Provides a freeform text input.
`{ control: 'text' }` | -
+ -💡 The `date` control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object. +The `date` control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object. -
+ #### `control.accept` @@ -304,13 +304,13 @@ The `argTypes` object uses the name of the arg as the key. By default, that key -
+ -💡 Be careful renaming args in this way. Users of the component you're documenting will not be able to use the documented name as a property of your component and the actual name will not displayed. +Be careful renaming args in this way. Users of the component you're documenting will not be able to use the documented name as a property of your component and the actual name will not displayed. For this reason, the `name` property is best used when defining an `argType` that is only used for documentation purposes and not an actual property of the component. For example, when [providing argTypes for each property of an object](https://stackblitz.com/edit/github-uplqzp?file=src/stories/Button.stories.tsx). -
+ ### `options` diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index e7dc90bda58b..3685881d8f75 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -4,11 +4,11 @@ title: 'CLI options' The Storybook command line interface (CLI) is the main tool you use to build and develop Storybook. -
+ Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may [opt-out](../configure/telemetry.md#how-to-opt-out) if you'd not like to share any information. -
+ ## API commands @@ -45,11 +45,11 @@ Options include: | `--docs` | Starts Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#preview-storybooks-documentation)
`storybook dev --docs` | | `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md)
`storybook dev --disable-telemetry` | -
+ -💡 Starting in 6.4 the `-s` flag is deprecated. Instead, use a configuration object in your `.storybook/main.js` file. See the [images and assets documentation](../configure/images-and-assets.md#serving-static-files-via-storybook) for more information. +Starting in 6.4 the `-s` flag is deprecated. Instead, use a configuration object in your `.storybook/main.js` file. See the [images and assets documentation](../configure/images-and-assets.md#serving-static-files-via-storybook) for more information. -
+ ### `build` @@ -75,6 +75,8 @@ Options include: | `--docs` | Builds Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#publish-storybooks-documentation)
`storybook build --docs` | | `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md).
`storybook build --disable-telemetry` | -
-💡 If you're using npm instead of yarn to publish Storybook, the commands work slightly different. For example, npm run storybook build -- -o ./path/to/build. -
+ + +If you're using npm instead of yarn to publish Storybook, the commands work slightly different. For example, npm run storybook build -- -o ./path/to/build. + + diff --git a/docs/api/csf.md b/docs/api/csf.md index 76388000ed3e..60c9ba5e4355 100644 --- a/docs/api/csf.md +++ b/docs/api/csf.md @@ -6,11 +6,11 @@ title: 'Component Story Format (CSF)' Component Story Format (CSF) is the recommended way to [write stories](../writing-stories/introduction.md). It's an [open standard](https://github.com/ComponentDriven/csf) based on ES6 modules that is portable beyond Storybook. -
+ -💡 If you are writing stories in the older `storiesOf()` syntax, you can find documentation in an [advanced README](https://github.com/storybookjs/storybook/blob/next/code/lib/preview-api/docs/storiesOf.md). +If you are writing stories in the older `storiesOf()` syntax, you can find documentation in an [advanced README](https://github.com/storybookjs/storybook/blob/next/code/lib/preview-api/docs/storiesOf.md). -
+ In CSF, stories and component metadata are defined as ES Modules. Every component story file consists of a required [default export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#Using_the_default_export) and one or more [named exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export). diff --git a/docs/api/doc-block-argtypes.md b/docs/api/doc-block-argtypes.md index 7ee304217ce5..2c0cc4d5b1e7 100644 --- a/docs/api/doc-block-argtypes.md +++ b/docs/api/doc-block-argtypes.md @@ -6,11 +6,11 @@ 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. +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](./doc-block-argtypes.png) diff --git a/docs/api/doc-block-canvas.md b/docs/api/doc-block-canvas.md index 8c27490bacb8..8c40eadd6bd1 100644 --- a/docs/api/doc-block-canvas.md +++ b/docs/api/doc-block-canvas.md @@ -23,11 +23,11 @@ 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. +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. -
+ ## Canvas @@ -172,11 +172,11 @@ Type: `SourceProps['code'] | SourceProps['format'] | SourceProps['language'] | S Specifies props passed to the inner `Source` block. 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. +The dark prop is ignored, as the `Source` block is always rendered in dark mode when shown as part of a `Canvas` block. -
+ ### `sourceState` diff --git a/docs/api/doc-block-controls.md b/docs/api/doc-block-controls.md index 835384203a5c..60334672163f 100644 --- a/docs/api/doc-block-controls.md +++ b/docs/api/doc-block-controls.md @@ -6,17 +6,17 @@ title: 'Controls' The `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). -
+ -💡 If you’re looking for a static table that shows a component's arg types with no controls, see the [`ArgTypes`](./doc-block-argtypes.md) block instead. +If you’re looking for a static table that shows a component's arg types with no controls, see the [`ArgTypes`](./doc-block-argtypes.md) block instead. -
+ -
+ -⚠️ The Controls doc block will only have functioning UI controls if you have also installed and registered [`@storybook/addon-controls`](../essentials/controls.md) (included in [`@storybook/addon-essentials`](../essentials/introduction.md)). +The Controls doc block will only have functioning UI controls if you have also installed and registered [`@storybook/addon-controls`](../essentials/controls.md) (included in [`@storybook/addon-essentials`](../essentials/introduction.md)). -
+ ![Screenshot of Controls block](./doc-block-controls.png) @@ -74,11 +74,11 @@ The example above applied the parameter at the [component](../writing-stories/pa -
+ -💡 This API configures Controls blocks used within docs pages. To configure the Controls addon panel, see the [Controls addon docs](../essentials/controls.md). To configure individual controls, you can specify [argTypes](./arg-types.md#control) for each. +This API configures Controls blocks used within docs pages. To configure the Controls addon panel, see the [Controls addon docs](../essentials/controls.md). To configure individual controls, you can specify [argTypes](./arg-types.md#control) for each. -
+ ### `exclude` diff --git a/docs/api/doc-block-meta.md b/docs/api/doc-block-meta.md index b4b165761353..0afcfae7de44 100644 --- a/docs/api/doc-block-meta.md +++ b/docs/api/doc-block-meta.md @@ -18,11 +18,11 @@ import * as ButtonStories from './Button.stories'; ``` -
+ -💡 The Meta block doesn’t render anything visible. +The Meta block doesn’t render anything visible. -
+ ## Meta @@ -78,11 +78,11 @@ Attaching an MDX file to a component’s stories with the `of` prop serves two p 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. +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` @@ -101,11 +101,11 @@ import { Meta } from '@storybook/blocks'; ``` -
+ -💡 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. +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 diff --git a/docs/api/doc-block-source.md b/docs/api/doc-block-source.md index 0595c387a238..c4a460050430 100644 --- a/docs/api/doc-block-source.md +++ b/docs/api/doc-block-source.md @@ -92,11 +92,11 @@ Default: `parameters.docs.source.dark` Determines if the snippet is rendered in dark mode. -
+ -💡 Light mode is only supported when the `Source` block is rendered independently. When rendered as part of a [`Canvas` block](./doc-block-canvas.md)—like it is in [autodocs](../writing-docs/autodocs.md)—it will always use dark mode. +Light mode is only supported when the `Source` block is rendered independently. When rendered as part of a [`Canvas` block](./doc-block-canvas.md)—like it is in [autodocs](../writing-docs/autodocs.md)—it will always use dark mode. -
+ ### `format` @@ -147,11 +147,11 @@ Specifies how the source code is rendered. - **code**: Renders the value of [`code` prop](#code), 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 uses [`args`](../writing-stories/args.md) and the [`Story` block](./doc-block-story.md) for that story is rendered along with the `Source` block. +Note that dynamic snippets will only work if the story uses [`args`](../writing-stories/args.md) and the [`Story` block](./doc-block-story.md) for that story is rendered along with the `Source` block. -
+ ### `id` diff --git a/docs/api/doc-block-stories.md b/docs/api/doc-block-stories.md index 75728b54df71..b20a3496ae61 100644 --- a/docs/api/doc-block-stories.md +++ b/docs/api/doc-block-stories.md @@ -37,11 +37,11 @@ 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. +If a stories file contains only one story and `includePrimary={true}`, the `Stories` block will render nothing to avoid a potentially confusing situation. -
+ ### `title` diff --git a/docs/api/doc-block-story.md b/docs/api/doc-block-story.md index 89499df3328c..0a3470429ace 100644 --- a/docs/api/doc-block-story.md +++ b/docs/api/doc-block-story.md @@ -8,11 +8,11 @@ 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](./doc-block-story.png) diff --git a/docs/api/doc-block-unstyled.md b/docs/api/doc-block-unstyled.md index 0fd5f03c6faa..4214e6e44c24 100644 --- a/docs/api/doc-block-unstyled.md +++ b/docs/api/doc-block-unstyled.md @@ -32,15 +32,15 @@ Yields: ![Screenshot of Unstyled Doc Block](./doc-block-unstyled.png) -
+ -ℹ️ 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. +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`: +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 @@ -52,7 +52,7 @@ Yields: ``` -
+ ## Unstyled diff --git a/docs/api/main-config-babel-default.md b/docs/api/main-config-babel-default.md index e09f66f34147..b79867e1dc34 100644 --- a/docs/api/main-config-babel-default.md +++ b/docs/api/main-config-babel-default.md @@ -8,11 +8,11 @@ Type: `(config: Babel.Config, options: Options) => Babel.Config | Promise + -💡 To adjust your Storybook's Babel setup directly—not via an addon—use [`babel`](./main-config-babel.md) instead. +To adjust your Storybook's Babel setup directly—not via an addon—use [`babel`](./main-config-babel.md) instead. - + diff --git a/docs/api/main-config-babel.md b/docs/api/main-config-babel.md index 3cb1865560f0..a84a938b5a35 100644 --- a/docs/api/main-config-babel.md +++ b/docs/api/main-config-babel.md @@ -8,11 +8,11 @@ Type: `(config: Babel.Config, options: Options) => Babel.Config | Promise + -💡 [Addon authors](../addons/writing-presets.md#babel) should use [`babelDefault`](./main-config-babel-default.md) instead, which is applied to the preview config before any user presets have been applied. +[Addon authors](../addons/writing-presets.md#babel) should use [`babelDefault`](./main-config-babel-default.md) instead, which is applied to the preview config before any user presets have been applied. - + diff --git a/docs/api/main-config-core.md b/docs/api/main-config-core.md index f2c16bf04913..e66bd5709740 100644 --- a/docs/api/main-config-core.md +++ b/docs/api/main-config-core.md @@ -36,13 +36,13 @@ Type: Configures Storybook's builder, [Vite](../builders/vite.md) or [Webpack](../builders/webpack.md). -
+ -💡 With the new [Framework API](./new-frameworks.md), [`framework.options.builder`](./main-config-framework.md#optionsbuilder) is now the preferred way to configure the builder. +With the new [Framework API](./new-frameworks.md), [`framework.options.builder`](./main-config-framework.md#optionsbuilder) is now the preferred way to configure the builder. You should only use `core.builder.options` if you need to configure a builder that is not part of a framework. -
+ diff --git a/docs/api/main-config-indexers.md b/docs/api/main-config-indexers.md index d5efd754787a..256dd9b2c990 100644 --- a/docs/api/main-config-indexers.md +++ b/docs/api/main-config-indexers.md @@ -4,11 +4,11 @@ title: 'indexers' (⚠️ **Experimental**) -
+ -🧪 While this feature is experimental, it must be specified by the `experimental_indexers` property of [`StorybookConfig`](./main-config.md). +While this feature is experimental, it must be specified by the `experimental_indexers` property of [`StorybookConfig`](./main-config.md). -
+ Parent: [main.js|ts configuration](./main-config.md) diff --git a/docs/api/main-config-manager-head.md b/docs/api/main-config-manager-head.md index d44eb52f4a83..04ea6f89eb42 100644 --- a/docs/api/main-config-manager-head.md +++ b/docs/api/main-config-manager-head.md @@ -8,11 +8,11 @@ Type: `(head: string) => string` Programmatically adjust the manager's `` of your Storybook. For example, load a custom font or add a script. Most often used by [addon authors](../addons/writing-presets.md#ui-configuration). -
+ -💡 If you don't need to programmatically adjust the manager head, you can add scripts and styles to `manager-head.html` instead. +If you don't need to programmatically adjust the manager head, you can add scripts and styles to `manager-head.html` instead. -
+ For example, you can conditionally add scripts or styles, depending on the environment: diff --git a/docs/api/main-config-preview-annotations.md b/docs/api/main-config-preview-annotations.md index ccea95d9ea8d..8e69ae265645 100644 --- a/docs/api/main-config-preview-annotations.md +++ b/docs/api/main-config-preview-annotations.md @@ -8,11 +8,11 @@ Type: `string[] | ((config: string[], options: Options) => string[] | Promise + -💡 Mostly used by [frameworks](../contribute/framework.md#previewjs-example). Storybook users and [addon authors](../addons/writing-presets.md) should add scripts to [`preview.js`](../configure/overview.md#configure-story-rendering) instead. +Mostly used by [frameworks](../contribute/framework.md#previewjs-example). Storybook users and [addon authors](../addons/writing-presets.md) should add scripts to [`preview.js`](../configure/overview.md#configure-story-rendering) instead. - + ```ts // @storybook/nextjs framework's src/preset.ts diff --git a/docs/api/main-config-preview-body.md b/docs/api/main-config-preview-body.md index f35a05a0c4e0..4ddbf9d71010 100644 --- a/docs/api/main-config-preview-body.md +++ b/docs/api/main-config-preview-body.md @@ -8,11 +8,11 @@ Type: `(body: string) => string` Programmatically adjust the [preview ``](../configure/story-rendering.md#adding-to-body) of your Storybook. Most often used by [addon authors](../addons/writing-presets.md#ui-configuration). -
+ -💡 If you don't need to programmatically adjust the preview body, you can add scripts and styles to [`preview-body.html`](../configure/story-rendering.md#adding-to-body) instead. +If you don't need to programmatically adjust the preview body, you can add scripts and styles to [`preview-body.html`](../configure/story-rendering.md#adding-to-body) instead. -
+ For example, you can conditionally add scripts or styles, depending on the environment: diff --git a/docs/api/main-config-preview-head.md b/docs/api/main-config-preview-head.md index af29ce4442f0..fcc5f1fd3076 100644 --- a/docs/api/main-config-preview-head.md +++ b/docs/api/main-config-preview-head.md @@ -8,11 +8,11 @@ Type: `(head: string) => string` Programmatically adjust the [preview ``](../configure/story-rendering.md#adding-to-head) of your Storybook. Most often used by [addon authors](../addons/writing-presets.md#ui-configuration). -
+ -💡 If you don't need to programmatically adjust the preview head, you can add scripts and styles to [`preview-head.html`](../configure/story-rendering.md#adding-to-head) instead. +If you don't need to programmatically adjust the preview head, you can add scripts and styles to [`preview-head.html`](../configure/story-rendering.md#adding-to-head) instead. -
+ For example, you can conditionally add scripts or styles, depending on the environment: diff --git a/docs/api/main-config-stories.md b/docs/api/main-config-stories.md index 9eefa1360565..9928131f5ca0 100644 --- a/docs/api/main-config-stories.md +++ b/docs/api/main-config-stories.md @@ -33,13 +33,13 @@ Configures Storybook to load stories from the specified locations. The intention -
+ -💡 If you want to use a different naming convention, you can alter the glob using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features). +If you want to use a different naming convention, you can alter the glob using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features). Keep in mind that some addons may assume Storybook's default naming convention. -
+ ## With an array of globs @@ -115,11 +115,11 @@ When [auto-titling](../configure/sidebar-and-urls.md#csf-30-auto-titles), prefix ## With a custom implementation -
+ -💡 With [`storyStoreV7`](./main-config-features.md#storystorev7) (the default in Storybook 7), Storybook now statically analyzes the configuration file to improve performance. Loading stories with a custom implementation may de-optimize or break this ability. +With [`storyStoreV7`](./main-config-features.md#storystorev7) (the default in Storybook 7), Storybook now statically analyzes the configuration file to improve performance. Loading stories with a custom implementation may de-optimize or break this ability. -
+ You can also adjust your Storybook configuration and implement custom logic to load your stories. For example, suppose you were working on a project that includes a particular pattern that the conventional ways of loading stories could not solve. In that case, you could adjust your configuration as follows: diff --git a/docs/builders/vite.md b/docs/builders/vite.md index 819c4278ed48..2302191fcae3 100644 --- a/docs/builders/vite.md +++ b/docs/builders/vite.md @@ -83,11 +83,11 @@ By default, the Vite builder in Storybook searches for the Vite configuration fi -
+ -💡 If you do not want Storybook to load the Vite configuration file automatically, you can use the `viteConfigPath` option to point to a non-existent file. +If you do not want Storybook to load the Vite configuration file automatically, you can use the `viteConfigPath` option to point to a non-existent file. -
+ ### TypeScript diff --git a/docs/builders/webpack.md b/docs/builders/webpack.md index 130ac9bd56e1..74964ff1c368 100644 --- a/docs/builders/webpack.md +++ b/docs/builders/webpack.md @@ -74,10 +74,11 @@ If you already have an existing Webpack configuration file that you need to reus -
-💡 Projects scaffolded based on generators may require that you import their specific Webpack configuration files. We suggest reading your generator's documentation for more information. + -
+Projects scaffolded based on generators may require that you import their specific Webpack configuration files. We suggest reading your generator's documentation for more information. + + ### Debug Webpack configuration diff --git a/docs/configure/babel.md b/docs/configure/babel.md index 331add4d5e6e..94bd83590288 100644 --- a/docs/configure/babel.md +++ b/docs/configure/babel.md @@ -4,11 +4,11 @@ title: 'Babel' As of version 7.0, Storybook now re-uses your project’s Babel configuration to apply the same Babel plugins and presets in your Storybook stories as you do in your app. This makes it simpler, less buggy, easier to troubleshoot, and more consistent with other tools in the JS ecosystem. -
+ If you're not using Storybook 7, please reference the [previous documentation](../../../release-6-5/docs/configure/babel.md) for guidance on configuring your Babel setup. -
+ ## CRA (Create React App) @@ -125,11 +125,11 @@ BABEL_SHOW_CONFIG_FOR=.storybook/preview.js yarn storybook When the command finishes running, it will display the available Babel configuration for the `.storybook/preview.js` file. You can use this information to debug issues with transpilation. -
+ -💡 Due to what appears to be a Babel bug, setting this flag causes Babel transpilation to fail on the file provided. Thus you cannot actually **run** Storybook using this command. However, it will print out the configuration information as advertised, and therefore you can use this to debug your Storybook. You'll need to remove the flag to actually run your Storybook. +Due to what appears to be a Babel bug, setting this flag causes Babel transpilation to fail on the file provided. Thus you cannot actually **run** Storybook using this command. However, it will print out the configuration information as advertised, and therefore you can use this to debug your Storybook. You'll need to remove the flag to actually run your Storybook. -
+ For more info, please refer to the [Babel documentation](https://babeljs.io/docs/en/configuration#print-effective-configs). diff --git a/docs/configure/environment-variables.md b/docs/configure/environment-variables.md index 4f32cac6c51b..f943b05c5237 100644 --- a/docs/configure/environment-variables.md +++ b/docs/configure/environment-variables.md @@ -9,11 +9,11 @@ If you supply an environment variable prefixed with `STORYBOOK_`, it will be ava STORYBOOK_THEME=red STORYBOOK_DATA_KEY=12345 npm run storybook ``` -
+ -💡 Do not store any secrets (e.g., private API keys) or other types of sensitive information in your Storybook. Environment variables are embedded into the build, meaning anyone can view them by inspecting your files. +Do not store any secrets (e.g., private API keys) or other types of sensitive information in your Storybook. Environment variables are embedded into the build, meaning anyone can view them by inspecting your files. -
+ Then we can access these environment variables anywhere inside our preview JavaScript code like below: @@ -48,11 +48,11 @@ Then we can access these environment variables anywhere inside our preview JavaS You can also access these variables in your custom ``/`` using the substitution `%STORYBOOK_X%`, for example: `%STORYBOOK_THEME%` will become `red`. -
+ -💡 If using the environment variables as attributes or values in JavaScript, you may need to add quotes, as the value will be inserted directly. e.g. `` +If using the environment variables as attributes or values in JavaScript, you may need to add quotes, as the value will be inserted directly. e.g. `` -
+ ### Using .env files @@ -99,11 +99,11 @@ Out of the box, Storybook provides a [Vite builder](../builders/vite.md), which -
+ You can also use specific files for specific modes. Add a `.env.development` or `.env.production` to apply different values to your environment variables. -
+ You can also pass these environment variables when you are [building your Storybook](../sharing/publish-storybook.md) with `build-storybook`. @@ -154,9 +154,11 @@ The table below lists the available options: | Firefox | `BROWSER="firefox"` | | Chromium | `BROWSER="chromium"` | -
-💡 By default, Storybook will open a new Chrome window as part of its startup process. If you don't have Chrome installed, make sure to include one of the following options, or set your default browser accordingly. -
+ + +By default, Storybook will open a new Chrome window as part of its startup process. If you don't have Chrome installed, make sure to include one of the following options, or set your default browser accordingly. + + ## Troubleshooting diff --git a/docs/configure/overview.md b/docs/configure/overview.md index a5e877a03e46..4e11a8f5c440 100644 --- a/docs/configure/overview.md +++ b/docs/configure/overview.md @@ -4,11 +4,11 @@ title: 'Configure Storybook' Storybook is configured via a folder called `.storybook`, which contains various configuration files. -
+ Note that you can change the folder that Storybook uses by setting the `-c` flag to your `storybook dev` and `storybook build` [CLI commands](../api/cli-options.md). -
+ ## Configure your Storybook project @@ -25,11 +25,11 @@ Storybook's main configuration (i.e., the `main.js|ts`) defines your Storybook p -
+ -ℹ️ This configuration file is a [preset](../addons/addon-types.md) and, as such, has a powerful interface, which can be further customized. Read our documentation on writing [presets](../addons/writing-presets.md) to learn more. +This configuration file is a [preset](../addons/addon-types.md) and, as such, has a powerful interface, which can be further customized. Read our documentation on writing [presets](../addons/writing-presets.md) to learn more. -
+ | Configuration element | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/configure/story-rendering.md b/docs/configure/story-rendering.md index b4b157569eab..ae98bac3d9f3 100644 --- a/docs/configure/story-rendering.md +++ b/docs/configure/story-rendering.md @@ -18,11 +18,11 @@ If you need to add extra elements to the `head` of the preview iframe, for insta -
+ Storybook will inject these tags into the _preview iframe_ where your components render, not the Storybook application UI. -
+ However, it's also possible to modify the preview head HTML programmatically using a preset defined in the `main.js` file. Read the [presets documentation](../addons/writing-presets.md#ui-configuration) for more information. @@ -54,10 +54,10 @@ If using relative sizing in your project (like `rem` or `em`), you may update th -
+ Storybook will inject these tags into the _preview iframe_ where your components render, not the Storybook application UI. -
+ Just like how you have the ability to customize the preview `head` HTML tag, you can also follow the same steps to customize the preview `body` with a preset. To obtain more information on how to do this, refer to the [presets documentation](../addons/writing-presets.md#ui-configuration). diff --git a/docs/configure/telemetry.md b/docs/configure/telemetry.md index ffd34f8069fa..1d1af24046c1 100644 --- a/docs/configure/telemetry.md +++ b/docs/configure/telemetry.md @@ -178,11 +178,11 @@ You may opt-out of the telemetry by setting Storybook's configuration element `d -
+ -💡 There is a `boot` event containing no metadata (used to ensure the telemetry is working). It is sent prior to evaluating your [Storybook configuration file](../api/main-config.md) (i.e., `main.js|ts`), so it is unaffected by the `disableTelemetry` option. If you want to ensure that the event is not sent, use the `STORYBOOK_DISABLE_TELEMETRY` environment variable. +There is a `boot` event containing no metadata (used to ensure the telemetry is working). It is sent prior to evaluating your [Storybook configuration file](../api/main-config.md) (i.e., `main.js|ts`), so it is unaffected by the `disableTelemetry` option. If you want to ensure that the event is not sent, use the `STORYBOOK_DISABLE_TELEMETRY` environment variable. -
+ ## Crash reports (disabled by default) diff --git a/docs/configure/theming.md b/docs/configure/theming.md index b7aebc90fb9e..d8a56e6e5458 100644 --- a/docs/configure/theming.md +++ b/docs/configure/theming.md @@ -87,9 +87,11 @@ Inside your `.storybook` directory, create a new file called `YourTheme.js` and -
-💡 If you're using brandImage to add your custom logo, you can use any of the most common image formats. -
+ + +If you're using brandImage to add your custom logo, you can use any of the most common image formats. + + Above, we're creating a new theme that will: @@ -135,9 +137,11 @@ With the new changes introduced, the custom theme should yield a similar result. ![Storybook custom theme loaded](./storybook-custom-theme.png) -
-💡 Many theme variables are optional, the base property is NOT. -
+ + +Many theme variables are optional, the base property is NOT. + + The `@storybook/theming` package is built using TypeScript, which should help create a valid theme for TypeScript users. The types are part of the package itself. @@ -150,11 +154,11 @@ To style these elements, insert style tags into: - For Storybook’s UI, use `.storybook/manager-head.html` - For Storybook Docs, use `.storybook/preview-head.html` -
+ -💡 Caution: The same way as you can adjust your [preview’s head tag](../configure/story-rendering.md#adding-to-head), Storybook allows you to modify the code on the manager's side, through .storybook/manager-head.html. It can be helpful when adding theme styles that target Storybook's HTML, but it comes with a cost as Storybook's inner HTML can change at any time through the release cycle. +The same way as you can adjust your [preview’s head tag](../configure/story-rendering.md#adding-to-head), Storybook allows you to modify the code on the manager's side, through .storybook/manager-head.html. It can be helpful when adding theme styles that target Storybook's HTML, but it comes with a cost as Storybook's inner HTML can change at any time through the release cycle. -
+ ## MDX component overrides diff --git a/docs/configure/typescript.md b/docs/configure/typescript.md index ba89ad2dcca4..dbe0453e399c 100644 --- a/docs/configure/typescript.md +++ b/docs/configure/typescript.md @@ -20,11 +20,11 @@ Storybook's configuration file (i.e., `main.ts`) is defined as an ESM module wri See the [main configuration API reference](../api/main-config) for more details and additional properties. -
+ -💡 See the Vite builder [TypeScript documentation](https://github.com/storybookjs/builder-vite#typescript) if using `@storybook/builder-vite`. +See the Vite builder [TypeScript documentation](https://github.com/storybookjs/builder-vite#typescript) if using `@storybook/builder-vite`. -
+ ### Extending the default configuration diff --git a/docs/configure/upgrading.md b/docs/configure/upgrading.md index 97b9d785fc20..c5e57d8d714e 100644 --- a/docs/configure/upgrading.md +++ b/docs/configure/upgrading.md @@ -27,11 +27,11 @@ After running the command the script will: - Upgrade all Storybook packages in your project to the latest stable version - Run the relevant [automigrations](../migration-guide.md#automatic-upgrade) factoring in the [breaking changes](../migration-guide.md#major-breaking-changes) between your current version and the latest stable version -
+ In addition to running the command, we also recommend checking the [MIGRATION.md file](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md), for the detailed log of relevant changes and deprecations that might affect your upgrade. -
+ ## Automigrate script @@ -71,8 +71,8 @@ To upgrade to the latest pre-release: If you'd like to downgrade to a stable version, manually edit the package version numbers in your `package.json` and re-install. -
+ Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may [opt-out](../configure/telemetry.md#how-to-opt-out) if you'd not like to share any information. -
+ diff --git a/docs/configure/webpack.md b/docs/configure/webpack.md index b23700a38ee2..61073d7b4374 100644 --- a/docs/configure/webpack.md +++ b/docs/configure/webpack.md @@ -173,9 +173,11 @@ The following code snippet shows how you can replace the loaders from Storybook -
-💡 Projects initialized via generators (e.g, Vue CLI) may require that you import their own webpack config file (i.e., /projectRoot/node_modules/@vue/cli-service/webpack.config.js) to use a certain feature with Storybook. For other generators, make sure to check the documentation for instructions. -
+ + +Projects initialized via generators (e.g, Vue CLI) may require that you import their own webpack config file (i.e., /projectRoot/node_modules/@vue/cli-service/webpack.config.js) to use a certain feature with Storybook. For other generators, make sure to check the documentation for instructions. + + ### TypeScript Module Resolution @@ -191,6 +193,8 @@ When working with TypeScript projects, the default Webpack configuration may fai -
-💡 Learn more about Storybook's built-in TypeScript support or see this issue for more information. -
+ + +Learn more about Storybook's built-in TypeScript support or see this issue for more information. + + diff --git a/docs/contribute/code.md b/docs/contribute/code.md index 21337442dd23..39a1818e2ee6 100644 --- a/docs/contribute/code.md +++ b/docs/contribute/code.md @@ -50,11 +50,11 @@ yarn task When prompted, answer the questions as accurately as possible to allow Storybook to determine your goals. After answering these questions, you should see the entire command with the options you've selected should you require to re-run it. -
+ -💡 The `yarn task` command takes a few development shortcuts that can catch you off guard when switching branches and may require you to re-run both the `install` and `compile` tasks. You can speed up the process by running the command with the `start-from=install` flag. +The `yarn task` command takes a few development shortcuts that can catch you off guard when switching branches and may require you to re-run both the `install` and `compile` tasks. You can speed up the process by running the command with the `start-from=install` flag. -
+ ## Running tests @@ -84,11 +84,11 @@ yarn build When prompted to start the build process in `watch` mode, answer **yes** to develop in interactive mode. Afterward, choose which packages you want to build. For example, if you're going to work on a feature for `@storybook/addon-docs`, you might want to select both `@storybook/addon-docs` and `@storybook/components`. -
+ -💡 Build's `watch` mode is great for interactive development. However, for performance reasons, it only transpiles your code and doesn't execute the TypeScript compiler. If something isn't working as expected, try running the `build` command WITHOUT enabling watch mode: it will re-generate TypeScript types and perform automatic type checking for you. +Build's `watch` mode is great for interactive development. However, for performance reasons, it only transpiles your code and doesn't execute the TypeScript compiler. If something isn't working as expected, try running the `build` command WITHOUT enabling watch mode: it will re-generate TypeScript types and perform automatic type checking for you. -
+ ![Storybook package selector](./storybook-build-packages-selection-optimized.png) @@ -144,11 +144,11 @@ Before submitting your contribution, run the test suite one last time with the f yarn test ``` -
+ -💡 Storybook relies on [Jest](https://jestjs.io/) as part of it's testing suite. During the test run, if you spot that snapshot tests are failing, re-run the command with the `-u` flag to update them. +Storybook relies on [Jest](https://jestjs.io/) as part of it's testing suite. During the test run, if you spot that snapshot tests are failing, re-run the command with the `-u` flag to update them. -
+ Doing this prevents last-minute bugs and is a great way to merge your contribution faster once you submit your pull request. Failing to do so will lead to one of the maintainers mark the pull request with the **Work in Progress** label until all tests pass. @@ -173,13 +173,13 @@ yarn task --task e2e-tests --template=react-vite/default-ts --start-from=install Typically it is a good idea to start from the `install` task to ensure your local code is completely up to date. If you reproduce the failure, you can try and make fixes, [compile them](#start-developing) with `build`, then rerun the task with `--start-from=auto`. -
+ -💡 The default instructions run the code in "linked" mode, meaning built changes to Storybook library code will be reflected in the sandbox immediately (the next time you run the task). However, CI runs in "unlinked" mode, which in rare cases, will behave differently.
+The default instructions run the code in "linked" mode, meaning built changes to Storybook library code will be reflected in the sandbox immediately (the next time you run the task). However, CI runs in "unlinked" mode, which in rare cases, will behave differently.
If you are having trouble reproducing, try rerunning the command with the `--no-link` flag. If you need to do that, you'll need to run it with `--start-from=compile` after each code change. -
+ ## How to work with reproductions @@ -199,11 +199,11 @@ If you already have a reproduction on your local machine, you can similarly link npx storybook@next link --local /path/to/local-repro-directory ``` -
+ -💡 The `storybook link` command relies on [Yarn 2 linking](https://yarnpkg.com/cli/link/) under the hood. It requires your local reproduction to be using [Yarn 2](https://yarnpkg.com/) as well, which is the case if you're already enabled it with the [`storybook sandbox`](./how-to-reproduce.md) command per our contribution guidelines. The process will fail if you're trying to link a non-Yarn 2 project. +The `storybook link` command relies on [Yarn 2 linking](https://yarnpkg.com/cli/link/) under the hood. It requires your local reproduction to be using [Yarn 2](https://yarnpkg.com/) as well, which is the case if you're already enabled it with the [`storybook sandbox`](./how-to-reproduce.md) command per our contribution guidelines. The process will fail if you're trying to link a non-Yarn 2 project. -
+ ## Developing a template diff --git a/docs/contribute/how-to-reproduce.md b/docs/contribute/how-to-reproduce.md index 361d14458d1e..737599351546 100644 --- a/docs/contribute/how-to-reproduce.md +++ b/docs/contribute/how-to-reproduce.md @@ -24,9 +24,10 @@ First, open a terminal and run the following command: npx storybook@next sandbox ``` -
-💡 You can append a template name in the command to get filtered results e.g. npx storybook@next sandbox react -
+ +You can append a template name in the command to get filtered results e.g. npx storybook@next sandbox react + + Next, choose the template you want to work with: @@ -36,9 +37,10 @@ Finally, enter a location for your reproduction: ![Storybook reproduction location](./storybook-reproduction-generator-location.png) -
-💡 If you don't provide a full path for the reproduction it will be generated in the current directory. -
+ + +If you don't provide a full path for the reproduction it will be generated in the current directory. + If everything worked as it should, you should have a fully functional Storybook set up in your local environment. @@ -62,9 +64,11 @@ Then, follow GitHub's instructions to set up the repository. ![github repository instructions](./github-repository-steps-optimized.png) -
- 💡 Don't forget to replace your-username with your own account name. -
+ + +Don't forget to replace your-username with your own account name. + + ## Publish diff --git a/docs/contribute/new-snippets.md b/docs/contribute/new-snippets.md index 1698945a64ac..2175556670bb 100644 --- a/docs/contribute/new-snippets.md +++ b/docs/contribute/new-snippets.md @@ -85,9 +85,11 @@ Create the file `ember/your-component.js.mdx`, similar to the other frameworks, ``` -
-💡 Code snippets are divided into various file extensions, if you're contributing a TypeScript file use .ts.mdx, or if you're adding JavaScript files use .js.mdx . -
+ + +Code snippets are divided into various file extensions, if you're contributing a TypeScript file use .ts.mdx, or if you're adding JavaScript files use .js.mdx. + + Go through the rest of the documentation and repeat the process. @@ -113,9 +115,11 @@ Next, make sure that you have running the `Synchronize documentation (sync-docs) yarn start:docs-only ``` -
-💡 During the start process if there's an issue with the documentation, the process will stop and you'll get a notification. -
+ + +During the start process if there's an issue with the documentation, the process will stop and you'll get a notification. + + Open a browser window to `http://localhost:8000`, click the Docs link, and select your framework from the dropdown. diff --git a/docs/essentials/actions.md b/docs/essentials/actions.md index 2ffc18444046..0077ab003631 100644 --- a/docs/essentials/actions.md +++ b/docs/essentials/actions.md @@ -70,11 +70,11 @@ If you need more granular control over which `argTypes` are matched, you can adj -
+ -💡 If you're generating argTypes with another addon (like [docs](../writing-docs/introduction.md), which is the common behavior), ensure the actions addon AFTER the other addon. You can do this by listing it later in the addons registration code in [`.storybook/main.js`](../configure/overview.md#configure-story-rendering). This is default in [essentials](./introduction.md). +If you're generating argTypes with another addon (like [docs](../writing-docs/introduction.md), which is the common behavior), ensure the actions addon AFTER the other addon. You can do this by listing it later in the addons registration code in [`.storybook/main.js`](../configure/overview.md#configure-story-rendering). This is default in [essentials](./introduction.md). -
+ ## Action event handlers diff --git a/docs/essentials/controls.md b/docs/essentials/controls.md index 893661782e90..a41caf4a3ac0 100644 --- a/docs/essentials/controls.md +++ b/docs/essentials/controls.md @@ -21,11 +21,11 @@ Controls do not require any modification to your components. Stories for control To use the Controls addon, you need to write your stories using [args](../writing-stories/args.md). Storybook will automatically generate UI controls based on your args and what it can infer about your component. Still, you can configure the controls further using [argTypes](../api/argtypes.md), see below. -
+ -💡 If you have stories in the older pre-Storybook 6 style, check the args & controls migration guide to learn how to convert your existing stories for args. +If you have stories in the older pre-Storybook 6 style, check the args & controls migration guide to learn how to convert your existing stories for args. -
+ ## Choosing the control type @@ -89,11 +89,11 @@ We can specify which controls get used by declaring a custom [argType](../api/ar -
+ -💡 ArgTypes are a powerful feature that can be used to customize the controls for your stories. See the documentation about [customizing controls](#annotation) with `argTypes` annotation for more information. +ArgTypes are a powerful feature that can be used to customize the controls for your stories. See the documentation about [customizing controls](#annotation) with `argTypes` annotation for more information. -
+ This replaces the input with a radio group for a more intuitive experience. @@ -229,9 +229,11 @@ As shown above, you can configure individual controls with the “control" annot | | `color` | Provides a color picker component to handle color values.
Can be additionally configured to include a set of color presets.
`argTypes: { color: { control: { type: 'color', presetColors: ['red', 'green']} }}` | | | `date` | Provides a datepicker component to handle date selection. `argTypes: { startDate: { control: 'date' }}` | -
-💡 The date control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object. -
+ + +The date control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object. + + @@ -248,9 +250,11 @@ As shown above, you can configure individual controls with the “control" annot -
-💡 Numeric data types will default to a number control unless additional configuration is provided. -
+ + +Numeric data types will default to a number control unless additional configuration is provided. + + ### Parameters @@ -339,11 +343,11 @@ The previous example also removed the prop documentation from the table. In some -
+ 💡 As with other Storybook properties, such as [decorators](../writing-stories/decorators.md), you can apply the same pattern at a story level for more granular cases. -
+ ### Conditional controls diff --git a/docs/essentials/highlight.md b/docs/essentials/highlight.md index 190cfe1e84f8..0968be5d36cc 100644 --- a/docs/essentials/highlight.md +++ b/docs/essentials/highlight.md @@ -26,11 +26,11 @@ To highlight DOM elements with the addon, you'll need to emit the `HIGHLIGHT` ev -
+ -💡 We recommend choosing the most specific selector possible to avoid highlighting elements other addons use. This is because the addon tries to match selectors against the entire DOM tree. +We recommend choosing the most specific selector possible to avoid highlighting elements other addons use. This is because the addon tries to match selectors against the entire DOM tree. -
+ ### Reset highlighted elements @@ -52,11 +52,11 @@ Out of the box, Storybook automatically removes highlighted elements when transi -
+ -ℹ️ The `emit` function derived from the `useChannel` API hook creates a communication channel in Storybook's UI to listen for events and update the UI accordingly. The Highlight addon uses this channel to listen to custom events and update the highlighted elements (if any) accordingly. +The `emit` function derived from the `useChannel` API hook creates a communication channel in Storybook's UI to listen for events and update the UI accordingly. The Highlight addon uses this channel to listen to custom events and update the highlighted elements (if any) accordingly. -
+ ## Customize style diff --git a/docs/essentials/interactions.md b/docs/essentials/interactions.md index 6baff2197774..bbc1207e7cca 100644 --- a/docs/essentials/interactions.md +++ b/docs/essentials/interactions.md @@ -45,11 +45,11 @@ Next, update [`.storybook/main.js|ts`](../configure/overview.md#configure-story- -
+ -💡 Make sure to list `@storybook/addon-interactions` **after** the [`@storybook/addon-essentials`](./introduction.md) addon (or the [`@storybook/addon-actions`](./actions.md) if you've installed it individually). +Make sure to list `@storybook/addon-interactions` **after** the [`@storybook/addon-essentials`](./introduction.md) addon (or the [`@storybook/addon-actions`](./actions.md) if you've installed it individually). -
+ Now when you run Storybook, the Interactions addon will be enabled. @@ -83,8 +83,8 @@ While you can refer to the [Testing Library documentation](https://testing-libra Any `args` that have been marked as an Action, either using the [argTypes annotation](./actions.md#action-argtype-annotation) or the [argTypesRegex](./actions.md#automatically-matching-args), will be automatically converted to a [Jest mock function](https://jestjs.io/docs/mock-function-api) (spy). This allows you to make assertions about calls to these functions. -
+ -ℹ️ To mock functions in your Storybook stories for reliable and isolated component testing, use the `jest` import from `@storybook/jest`. This allows you to avoid configuring Jest globally in your project. +To mock functions in your Storybook stories for reliable and isolated component testing, use the `jest` import from `@storybook/jest`. This allows you to avoid configuring Jest globally in your project. -
+ diff --git a/docs/essentials/introduction.md b/docs/essentials/introduction.md index 7a16ef0962d9..4e89178bad28 100644 --- a/docs/essentials/introduction.md +++ b/docs/essentials/introduction.md @@ -117,8 +117,8 @@ For example, if you wanted to disable the [backgrounds addon](./backgrounds.md), -
+ -💡 You can use the following keys for each individual addon: `actions`, `backgrounds`, `controls`, `docs`, `viewport`, `toolbars`, `measure`, `outline`, and `highlight`. +You can use the following keys for each individual addon: `actions`, `backgrounds`, `controls`, `docs`, `viewport`, `toolbars`, `measure`, `outline`, and `highlight`. -
+ diff --git a/docs/essentials/measure-and-outline.md b/docs/essentials/measure-and-outline.md index e4937e793dce..d4ebe622d6e1 100644 --- a/docs/essentials/measure-and-outline.md +++ b/docs/essentials/measure-and-outline.md @@ -16,9 +16,11 @@ With Storybook's Measure addon, you can quickly visualize each component's measu -
-💡 Alternatively you can press the m key on your keyboard to toggle the addon. -
+ + +Alternatively you can press the m key on your keyboard to toggle the addon. + + ## Outline addon diff --git a/docs/essentials/toolbars-and-globals.md b/docs/essentials/toolbars-and-globals.md index aac0ecb0ea20..6f7e2916daa0 100644 --- a/docs/essentials/toolbars-and-globals.md +++ b/docs/essentials/toolbars-and-globals.md @@ -29,11 +29,11 @@ Storybook has a simple, declarative syntax for configuring toolbar menus. In you -
+ -💡 As globals are _global_ you can _only_ set `globalTypes` in [`.storybook/preview.js|ts`](../configure/overview.md#configure-story-rendering). +As globals are _global_ you can _only_ set `globalTypes` in [`.storybook/preview.js|ts`](../configure/overview.md#configure-story-rendering). -
+ When you start your Storybook, you should see a new dropdown with the `light` and `dark` options in your toolbar. @@ -127,18 +127,18 @@ In your [`.storybook/preview.js|ts`](../configure/overview.md#configure-story-re -
+ -💡 The `icon` element used in the examples loads the icons from the `@storybook/components` package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. +The `icon` element used in the examples loads the icons from the `@storybook/components` package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. -
+ -
+ -💡 The `@storybook/addon-toolbars` addon is required to use toolbars. The toolbars addon is included by default in +The `@storybook/addon-toolbars` addon is required to use toolbars. The toolbars addon is included by default in `@storybook/addon-essentials`. -
+ By adding the configuration element `right`, the text will be displayed on the right side in the toolbar menu once you connect it to a decorator. @@ -181,9 +181,9 @@ Using the example above, you can modify any story to retrieve the **Locale** `gl -
+ -💡 In Storybook 6.0, if you set the global option `passArgsFirst: false` for backward compatibility, the story context is passed as the first argument: +In Storybook 6.0, if you set the global option `passArgsFirst: false` for backward compatibility, the story context is passed as the first argument: @@ -201,7 +201,7 @@ Using the example above, you can modify any story to retrieve the **Locale** `gl -
+ ## Consuming globals from within an addon diff --git a/docs/faq.md b/docs/faq.md index b26eb9ec12fe..a03b60cc9d52 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -91,9 +91,11 @@ Create React App does not allow providing options to Jest in your `package.json` npm test -- --coverage --collectCoverageFrom='["src/**/*.{js,jsx}","!src/**/stories/*"]' ``` -
-💡 If you're using yarn as a package manager, you'll need to adjust the command accordingly. -
+ + + If you're using yarn as a package manager, you'll need to adjust the command accordingly. + + ## I see `ReferenceError: React is not defined` when using Storybook with Next.js @@ -163,9 +165,11 @@ export default { }; ``` -
-💡 Fast Refresh only works in development mode with React 16.10 or higher. -
+ + +Fast Refresh only works in development mode with React 16.10 or higher. + + ## How do I setup the new React Context Root API with Storybook? @@ -343,9 +347,12 @@ We're only covering versions 5.3 and 5.0 as they were important milestones for S | | Frameworks | [See current documentation](./api/new-frameworks.md) | Non existing feature or undocumented | Non existing feature or undocumented | | | CLI options | [See current documentation](./api/cli-options.md) | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/cli-options) | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/cli-options) | -
+ + + With the release of version 5.3, we've updated how you can write your stories more compactly and easily. It doesn't mean that the storiesOf format has been removed. For the time being, we're still supporting it, and we have documentation for it. But be advised that this is bound to change in the future. -
+ + ## What icons are available for my toolbar or my addon? @@ -364,9 +371,11 @@ We recommend that you use [http-server](https://www.npmjs.com/package/http-serve npx http-server storybook-static ``` -
+ + Suppose you don't want to run the command above frequently. Add http-server as a development dependency and create a new script to preview your production build of Storybook. -
+ + ## Can I use Storybook with Vue 3? diff --git a/docs/get-started/install.md b/docs/get-started/install.md index ca46008635c3..beceee7c0401 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -18,11 +18,11 @@ Use the Storybook CLI to install it in a single command. Run this inside your _e -
+ -If you run into issues with the installation, check the [Troubleshooting section](#troubleshooting) below for guidance on how to solve it. +Check the [Troubleshooting section](#troubleshooting) below for guidance on how to solve it. -
+
@@ -110,11 +110,11 @@ Below are some of the most common installation issues and instructions on how to -
+ Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may [opt-out](../configure/telemetry.md#how-to-opt-out) if you'd not like to share any information. -
+ If all else fails, try asking for [help](https://storybook.js.org/community#support) diff --git a/docs/get-started/why-storybook.md b/docs/get-started/why-storybook.md index 39451d4ee4b7..7322d2d57c2e 100644 --- a/docs/get-started/why-storybook.md +++ b/docs/get-started/why-storybook.md @@ -83,7 +83,7 @@ During development, run it in a separate node process. If you’re working on UI
-Does Storybook work with X? +Does Storybook work with my favorite libraries? Storybook aims to integrate with industry-standard tools and platforms to simplify setup. Thanks to our ambitious developer community, we’ve made significant progress. There are hundreds of [addons](https://storybook.js.org/addons/) and tutorials that walk through how to set up Storybook in all types of projects. diff --git a/docs/sharing/design-integrations.md b/docs/sharing/design-integrations.md index cf2e5ac4934c..d2211a7b52d9 100644 --- a/docs/sharing/design-integrations.md +++ b/docs/sharing/design-integrations.md @@ -43,9 +43,11 @@ In Figma, select the component, open the plugin, and paste the URL. Chromatic will automatically update your linked stories to reflect the most recent Storybook published on the branch you linked. That means the link persists even as you push new code. -
-💡 The plugin does not support linking stories to Figma layers. -
+ + +The plugin does not support linking stories to Figma layers. + + #### View stories in Figma diff --git a/docs/sharing/package-composition.md b/docs/sharing/package-composition.md index b7b798936c50..ba94040b90b0 100644 --- a/docs/sharing/package-composition.md +++ b/docs/sharing/package-composition.md @@ -6,11 +6,11 @@ Storybook is widely used by component libraries and design systems. Design syste For example, if you use a design system package, its stories can appear alongside your own. That makes it convenient to cross reference usage documentation without leaving Storybook. -
+ Composition via a package requires a secure integration between the service where you publish Storybook and Storybook’s own APIs. We recommend [publishing Storybook to Chromatic](./publish-storybook.md#publish-storybook-with-chromatic) for full support of these features. -
+ ## For consumers diff --git a/docs/sharing/publish-storybook.md b/docs/sharing/publish-storybook.md index 96d4a1eaefb6..0c19cb4697c3 100644 --- a/docs/sharing/publish-storybook.md +++ b/docs/sharing/publish-storybook.md @@ -31,11 +31,11 @@ First, we'll need to build Storybook as a static web application. The functional -
+ -💡 You can provide additional flags to customize the command. Read more about the flag options [here](../api/cli-options.md). +You can provide additional flags to customize the command. Read more about the flag options [here](../api/cli-options.md). -
+ Storybook will create a static web application capable of being served by any web server. Preview it locally by running the following command: @@ -103,11 +103,11 @@ In your project's root directory, add a new file called `chromatic.yml` inside t -
+ -💡 Secrets are secure environment variables provided by GitHub so that you don't need to hard code your `project-token`. Read the [official documentation](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) to learn how to configure them. +Secrets are secure environment variables provided by GitHub so that you don't need to hard code your `project-token`. Read the [official documentation](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) to learn how to configure them. -
+ Commit and push the file. Congratulations, you've successfully automated publishing your Storybook. Now whenever you open a PR you’ll get a handy link to your published Storybook in your PR checks. @@ -134,11 +134,11 @@ When you publish Storybook, you also get component history and versioning down t Since Storybook is built as a static web application, you can also publish it to any web host, including [GitHub Pages](https://docs.github.com/en/pages), [Netlify](https://www.netlify.com/), [AWS S3](https://aws.amazon.com/s3/), and more. However, features such as [Composition](./storybook-composition.md), [embedding stories](./embed.md), history, and versioning require tighter integration with Storybook APIs and secure authentication. Your hosting provider may not be capable of supporting these features. Learn about the Component Publishing Protocol (CPP) to see what. -
+ -ℹ️ Additional header configuration may be required to serve Storybook's static files correctly on your host. For more information on the required headers, see the [Migration guide](https://github.com/storybookjs/storybook/blob/main/MIGRATION.md#deploying-build-artifacts). +Additional header configuration may be required to serve Storybook's static files correctly on your host. For more information on the required headers, see the [Migration guide](https://github.com/storybookjs/storybook/blob/main/MIGRATION.md#deploying-build-artifacts). -
+
diff --git a/docs/sharing/storybook-composition.md b/docs/sharing/storybook-composition.md index 04aa8440c533..a9e50a8c54d4 100644 --- a/docs/sharing/storybook-composition.md +++ b/docs/sharing/storybook-composition.md @@ -30,9 +30,11 @@ In your [`.storybook/main.js`](../configure/overview.md#configure-story-renderin -
- 💡 Limitation: Addons in composed Storybooks will not work as they normally do in a non-composed Storybook. -
+ + +Limitation: Addons in composed Storybooks will not work as they normally do in a non-composed Storybook. + + ## Compose local Storybooks @@ -66,11 +68,11 @@ You can also compose Storybooks based on the current development environment (e. -
+ -💡 Similar to the other fields available in Storybook’s configuration file, the `refs` field can also be a function that accepts a config parameter containing Storybook’s configuration object. Check the [Webpack documentation](../builders/webpack.md#override-the-default-configuration) to learn more about it. +Similar to the other fields available in Storybook’s configuration file, the `refs` field can also be a function that accepts a config parameter containing Storybook’s configuration object. Check the [Webpack documentation](../builders/webpack.md#override-the-default-configuration) to learn more about it. -
+ ## Improve your Storybook composition @@ -91,11 +93,11 @@ If you're using Storybook 6.4, or higher, you can optimize your composition via -
+ -💡 If you already enabled automatic code splitting via the [`storyStoreV7`](https://storybook.js.org/docs/react/builders/webpack#code-splitting), you won't need this flag as it will automatically generate the `index.json` file. +If you already enabled automatic code splitting via the [`storyStoreV7`](https://storybook.js.org/docs/react/builders/webpack#code-splitting), you won't need this flag as it will automatically generate the `index.json` file. -
+ When you compose a Storybook featuring this flag, it will use the information retrieved from the file to populate the UI with your composed Storybook stories automatically. Here's an example of the output generated by the `index.json` file: @@ -117,11 +119,11 @@ If you're working with an outdated Storybook version or have a project-specific npx storybook extract ``` -
+ -💡 `storybook extract` uses [Puppeteer](https://www.npmjs.com/package/puppeteer), which downloads and installs Chromium. Set the environment `SB_CHROMIUM_PATH` to configure your local Chromium installation. +`storybook extract` uses [Puppeteer](https://www.npmjs.com/package/puppeteer), which downloads and installs Chromium. Set the environment `SB_CHROMIUM_PATH` to configure your local Chromium installation. -
+ Although a good approach to improve composition, it comes with a cost, as it will require an additional dependency being added and increased build times. Once it finishes executing, it will generate an `index.json` file in the default build directory (`storybook-static`) with the information related to your Storybook. Here’s an example of the file contents: @@ -145,8 +147,8 @@ npx storybook extract my-built-storybook-directory my-other-directory/index.json When executed, it will look up a built Storybook in the `my-built-storybook-directory` and create the `index.json` file in the `my-other-directory` with all the necessary information. -
+ -💡 If you need to use the arguments, you’ll need to include both of them, or the command will fail. +If you need to use the arguments, you’ll need to include both of them, or the command will fail. -
+ diff --git a/docs/writing-docs/autodocs.md b/docs/writing-docs/autodocs.md index 10e2c730d076..bbf0e0d3e7d6 100644 --- a/docs/writing-docs/autodocs.md +++ b/docs/writing-docs/autodocs.md @@ -68,11 +68,11 @@ To replace the default documentation template used by Storybook, you can extend -
+ -💡 Internally, Storybook uses a similar implementation to generate the default template. See the Doc Blocks [API reference](./doc-blocks.md#available-blocks) to learn more about how Doc Blocks work. +Internally, Storybook uses a similar implementation to generate the default template. See the Doc Blocks [API reference](./doc-blocks.md#available-blocks) to learn more about how Doc Blocks work. -
+ Going over the code snippet in more detail. When Storybook starts up, it will override the default template with the custom one composed of the following: @@ -107,11 +107,11 @@ Then you can use it in your `.storybook/preview.js` or an individual story file -
+ -💡 If you only need to override the documentation page for a single component, we recommend creating an MDX file and referencing it directly via the `` Doc Block. +If you only need to override the documentation page for a single component, we recommend creating an MDX file and referencing it directly via the `` Doc Block. -
+ ### Generate a table of contents @@ -141,11 +141,11 @@ By default, the table of contents on the documentation page will only show the ` | `title` | Defines a title caption for the table of contents.
Accepts one of: `string`, `null`, React element
`toc: { title: 'Table of Contents' }` | | `unsafeTocbotOptions` | Provides additional [`TocBot`](https://tscanlin.github.io/tocbot/) configuration options
`toc: { unsafeTocbotOptions: { orderedList: true } }` | -
+ -ℹ️ The `contentsSelector`, `headingSelector`, and `ignoreSelector` properties allow additional customization. For more information on using them, see the [`Tocbot` documentation](https://tscanlin.github.io/tocbot/). +The `contentsSelector`, `headingSelector`, and `ignoreSelector` properties allow additional customization. For more information on using them, see the [`Tocbot` documentation](https://tscanlin.github.io/tocbot/). -
+ @@ -227,11 +227,11 @@ Out of the box, Storybook has a set of components that you can use to customize -
+ -💡 This is not a Storybook issue but a breaking change introduced with MDX 2. For more information on this and other breaking changes, see our [MDX documentation](./mdx.md#breaking-changes). +This is not a Storybook issue but a breaking change introduced with MDX 2. For more information on this and other breaking changes, see our [MDX documentation](./mdx.md#breaking-changes). -
+ ## Troubleshooting diff --git a/docs/writing-docs/doc-blocks.md b/docs/writing-docs/doc-blocks.md index 3a0da4aeb6f7..faacdf5fa588 100644 --- a/docs/writing-docs/doc-blocks.md +++ b/docs/writing-docs/doc-blocks.md @@ -107,11 +107,11 @@ For example, you can filter out the `style` prop from all [`Controls`](../api/do -
+ -ℹ️ Parameters can also be defined at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level or the [story](../writing-stories/parameters.md#story-parameters) level, allowing you to customize Doc Blocks exactly as you need, where you need. +Parameters can also be defined at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level or the [story](../writing-stories/parameters.md#story-parameters) level, allowing you to customize Doc Blocks exactly as you need, where you need. -
+ The blocks that accept customization via parameters are marked in the list of available blocks below. @@ -129,11 +129,11 @@ Each block has a dedicated API reference page detailing usage, available options ### [ArgTypes](../api/doc-block-argtypes.md) -
+ Accepts parameters in the namespace `parameters.docs.argTypes`. -
+ The `ArgTypes` block can be used to show a static table of [arg types](../api/argtypes.md) for a given component as a way to document its interface. @@ -141,11 +141,11 @@ The `ArgTypes` block can be used to show a static table of [arg types](../api/ar ### [Canvas](../api/doc-block-canvas.md) -
+ Accepts parameters in the namespace `parameters.docs.canvas`. -
+ The `Canvas` block is a wrapper around a [`Story`](../api/doc-block-story.md), featuring a toolbar that allows you to interact with its content while automatically providing the required [`Source`](../api/doc-block-source.md) snippets. @@ -159,11 +159,11 @@ The `ColorPalette` block allows you to document all color-related items (e.g., s ### [Controls](../api/doc-block-controls.md) -
+ Accepts parameters in the namespace `parameters.docs.controls`. -
+ The `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`](../api/doc-block-story.md) or [`Canvas`](../api/doc-block-canvas.md) blocks). @@ -202,11 +202,11 @@ The `Primary` block displays the primary (first defined in the stories file) sto ### [Source](../api/doc-block-source.md) -
+ Accepts parameters in the namespace `parameters.docs.source`. -
+ The `Source` block is used to render a snippet of source code directly. @@ -220,11 +220,11 @@ The `Stories` block renders the full collection of stories in a stories file. ### [Story](../api/doc-block-story.md) -
+ Accepts parameters in the namespace `parameters.docs.story`. -
+ Stories (component tests) are Storybook's fundamental building blocks. diff --git a/docs/writing-docs/mdx.md b/docs/writing-docs/mdx.md index 00142cc29d3c..1c21d78dcca7 100644 --- a/docs/writing-docs/mdx.md +++ b/docs/writing-docs/mdx.md @@ -10,11 +10,11 @@ In addition, you can write pure documentation pages in MDX and add them to Story ![MDX simple example result](./mdx-hero.png) -
+ Writing stories directly in MDX was deprecated in Storybook 7. Please reference the [previous documentation](../../../release-6-5/docs/writing-docs/mdx.md) for guidance on that feature. -
+ ## Basic example @@ -63,11 +63,11 @@ The first thing you'll notice is that the component documentation is divided int - **CSF** is great for succinctly defining stories (component examples). If you use TypeScript, it also provides type safety and auto-completion. - **MDX** is great for writing structured documentation and composing it with interactive JSX elements. -
+ -💡 If you’re coming from a previous version of Storybook, you might be accustomed to using MDX both for **documentation** and for defining **stories** in the same `.stories.mdx` file. We’ve deprecated this functionality and plan to remove it in a future version of Storybook. We provide [migration](#automigration) scripts to help you onto the new format. +If you’re coming from a previous version of Storybook, you might be accustomed to using MDX both for **documentation** and for defining **stories** in the same `.stories.mdx` file. We’ve deprecated this functionality and plan to remove it in a future version of Storybook. We provide [migration](#automigration) scripts to help you onto the new format. -
+ ### Anatomy of MDX @@ -109,11 +109,11 @@ Imports the components and stories that will be used in the JSX throughout the r -
+ -ℹ️ When providing the `of` prop to the `Meta` block, make sure that you're referencing the [**default export**](../api/csf.md#default-export) of the story file and not the component itself to prevent render issues with the generated documentation. +When providing the `of` prop to the `Meta` block, make sure that you're referencing the [**default export**](../api/csf.md#default-export) of the story file and not the component itself to prevent render issues with the generated documentation. -
+ The `Meta` block defines where the document will be placed in the sidebar. In this case, it is adjacent to the Checkbox’s stories. By default, the docs sidebar node is titled `"Docs"`, but this can be customized by passing a `name` prop (e.g., ``). If you want to place a docs node at an arbitrary point in the navigation hierarchy, you can use the `title` prop (e.g., ``). @@ -200,11 +200,11 @@ paths={[ -
+ -💡 The [`remark-gfm`](https://github.com/remarkjs/remark-gfm) package isn't provided by default during migration. We recommend installing it as a development dependency if you use its features. +The [`remark-gfm`](https://github.com/remarkjs/remark-gfm) package isn't provided by default during migration. We recommend installing it as a development dependency if you use its features. -
+ ### Automigration @@ -276,11 +276,11 @@ However, providing the `Meta` Doc Block may not be required for certain use case -
+ -💡 If you're overriding an existing auto-generated documentation page enabled via [`tags`](./autodocs.md#setup-automated-docs) configuration property, we recommend removing it to avoid errors. +If you're overriding an existing auto-generated documentation page enabled via [`tags`](./autodocs.md#setup-automated-docs) configuration property, we recommend removing it to avoid errors. -
+ Once the custom MDX documentation is loaded, Storybook will infer the title and location using the same heuristic rules to generate [auto-title stories](../configure/sidebar-and-urls.md#csf-30-auto-titles) and render it in the sidebar as a `Docs` entry. @@ -344,11 +344,11 @@ If you need to extend your documentation with additional content written in Mark -
+ -ℹ️ The `Markdown` Doc Block provides additional configuration options to customize the rendering of your documentation. For more information, refer to the [API documentation](../api/doc-block-markdown.md). +The `Markdown` Doc Block provides additional configuration options to customize the rendering of your documentation. For more information, refer to the [API documentation](../api/doc-block-markdown.md). -
+ ![Changelog markdown in an MDX story](./mdx-markdown-docs-import.png) @@ -376,9 +376,11 @@ However, cross-linking documentation isn't restricted to documentation pages. Yo -
-💡 By applying this pattern with the Controls addon, all anchors will be ignored in Canvas based on how Storybook handles URLs to track the args values. -
+ + +By applying this pattern with the Controls addon, all anchors will be ignored in Canvas based on how Storybook handles URLs to track the args values. + + ## Troubleshooting @@ -435,9 +437,11 @@ Start by running the following command inside your project directory: npx @hipster/mdx2-issue-checker ``` -
-💡 Depending on the volume, you may be required to run the command multiple times to fix all the issues. -
+ + +Depending on the volume, you may be required to run the command multiple times to fix all the issues. + + When it finishes, it will output the list of files causing issues. You can then use this information to fix the problems manually. diff --git a/docs/writing-stories/args.md b/docs/writing-stories/args.md index 26a61edfb322..e2553cfd6972 100644 --- a/docs/writing-stories/args.md +++ b/docs/writing-stories/args.md @@ -104,11 +104,11 @@ You can also define args at the global level; they will apply to every component -
+ -💡 For most uses of global args, [globals](../essentials/toolbars-and-globals.md) are a better tool for defining globally-applied settings, such as a theme. Using globals enables users to change the value with the toolbar menu. +For most uses of global args, [globals](../essentials/toolbars-and-globals.md) are a better tool for defining globally-applied settings, such as a theme. Using globals enables users to change the value with the toolbar menu. -
+ ## Args composition @@ -130,11 +130,11 @@ You can separate the arguments to a story to compose in other stories. Here's ho -
+ -💡 If you find yourself re-using the same args for most of a component's stories, you should consider using [component-level args](#component-args). +If you find yourself re-using the same args for most of a component's stories, you should consider using [component-level args](#component-args). -
+ Args are useful when writing stories for composite components that are assembled from other components. Composite components often pass their arguments unchanged to their child components, and similarly, their stories can be compositions of their child components stories. With args, you can directly compose the arguments: @@ -287,7 +287,9 @@ In Storybook 5 and before we passed the context as the first argument. If you’ -
- 💡 Note that `args` is still available as a key in the context. -
+ + + Note that `args` is still available as a key in the context. + +
diff --git a/docs/writing-stories/build-pages-with-storybook.md b/docs/writing-stories/build-pages-with-storybook.md index 07db61971f27..34dbc40c1274 100644 --- a/docs/writing-stories/build-pages-with-storybook.md +++ b/docs/writing-stories/build-pages-with-storybook.md @@ -101,11 +101,11 @@ Run the following commands to install MSW, the addon, and generate a mock servic -
+ -💡 If you're working with Angular, you'll need to adjust the command to save the mock service worker file in a different directory (e.g., `src`). +If you're working with Angular, you'll need to adjust the command to save the mock service worker file in a different directory (e.g., `src`). -
+ Update your `.storybook/preview.js` file and enable the addon via a [global decorator](./decorators.md#global-decorators). @@ -170,9 +170,11 @@ To test your screen with the mocked data, you could write a similar set of stori -
-💡 This example details how you can mock the REST request with fetch. Similar HTTP clients such as axios can be used as well. -
+ + +This example details how you can mock the REST request with fetch. Similar HTTP clients such as axios can be used as well. + + The mocked data (i.e., `TestData`) will be injected via [parameters](./parameters.md), enabling you to configure it per-story basis. @@ -306,11 +308,11 @@ ProfilePageContainer.js ProfilePageContext.js ``` -
+ It’s also often helpful to set up a “global” container context (perhaps named `GlobalContainerContext`) for container components that may be rendered on every page of your app and add them to the top level of your application. While it’s possible to place every container within this global context, it should only provide globally required containers. -
+ Let’s look at an example implementation of this approach. @@ -357,11 +359,11 @@ In the context of Storybook, instead of providing container components through c -
+ If the same context applies to all `ProfilePage` stories, we can use a [decorator](./decorators.md). -
+ #### Providing containers to your application diff --git a/docs/writing-stories/decorators.md b/docs/writing-stories/decorators.md index d8637bf72fef..ef45eec4c3c9 100644 --- a/docs/writing-stories/decorators.md +++ b/docs/writing-stories/decorators.md @@ -77,9 +77,11 @@ The second argument to a decorator function is the **story context** which in pa - `parameters`- the story's static metadata, most commonly used to control Storybook's behavior of features and addons. - `viewMode`- Storybook's current active window (e.g., canvas, docs). -
-💡 This pattern can also be applied to your own stories. Some of Storybook's supported frameworks already use it (e.g., vue 2). -
+ + +This pattern can also be applied to your own stories. Some of Storybook's supported frameworks already use it (e.g., vue 2). + + ### Using decorators to provide data diff --git a/docs/writing-stories/introduction.md b/docs/writing-stories/introduction.md index 82905a323984..146261d9af56 100644 --- a/docs/writing-stories/introduction.md +++ b/docs/writing-stories/introduction.md @@ -47,11 +47,11 @@ The _default_ export metadata controls how Storybook lists your stories and prov -
+ Starting with Storybook version 7.0, story titles are analyzed statically as part of the build process. The _default_ export must contain a `title` property that can be read statically or a `component` property from which an automatic title can be computed. Using the `id` property to customize your story URL must also be statically readable. -
+ ### Defining stories @@ -99,9 +99,11 @@ Use the _named_ exports of a CSF file to define your component’s stories. We r -
-💡 The recommendation mentioned above also applies to other frameworks, not only React. -
+ + +The recommendation mentioned above also applies to other frameworks, not only React. + + @@ -124,9 +126,11 @@ Use the _named_ exports of a CSF file to define your component’s stories. We r -
-💡 The recommendation mentioned above also applies to other frameworks, not only Solid. -
+ + +The recommendation mentioned above also applies to other frameworks, not only Solid. + + @@ -426,8 +430,8 @@ You can also reuse stories from the child `ListItem` in your `List` component. T -
+ -💡 Note that there are disadvantages in writing stories like this as you cannot take full advantage of the args mechanism and composing args as you build even more complex composite components. For more discussion, see the [multi component stories](../writing-stories/stories-for-multiple-components.md) workflow documentation. +Note that there are disadvantages in writing stories like this as you cannot take full advantage of the args mechanism and composing args as you build even more complex composite components. For more discussion, see the [multi component stories](../writing-stories/stories-for-multiple-components.md) workflow documentation. -
+ diff --git a/docs/writing-stories/naming-components-and-hierarchy.md b/docs/writing-stories/naming-components-and-hierarchy.md index 84cc47d70e0d..5757a2eda12a 100644 --- a/docs/writing-stories/naming-components-and-hierarchy.md +++ b/docs/writing-stories/naming-components-and-hierarchy.md @@ -127,11 +127,11 @@ Out of the box, Storybook sorts stories based on the order in which they are imp -
+ -ℹ️ Asides from the unique story identifier, you can also use the `title`, `name`, and import path to sort your stories using the `storySort` function. +Asides from the unique story identifier, you can also use the `title`, `name`, and import path to sort your stories using the `storySort` function. -
+ The `storySort` can also accept a configuration object. diff --git a/docs/writing-stories/play-function.md b/docs/writing-stories/play-function.md index a511792ffdd3..b83d22b3612f 100644 --- a/docs/writing-stories/play-function.md +++ b/docs/writing-stories/play-function.md @@ -57,11 +57,11 @@ Storybook's `play` functions are small code snippets that run once the story fin -
+ -💡 See the [Interaction testing documentation](../writing-tests/interaction-testing.md#api-for-user-events) for an overview of the available API events. +See the [Interaction testing documentation](../writing-tests/interaction-testing.md#api-for-user-events) for an overview of the available API events. -
+ When Storybook finishes rendering the story, it executes the steps defined within the `play` function, interacting with the component and filling the form's information. All of this without the need for user intervention. If you check your `Interactions` panel, you'll see the step-by-step flow. @@ -187,9 +187,11 @@ If you need, you can also adjust your `play` function to find elements based on -
- 💡 You can read more about the querying elements in the Testing library documentation. -
+ + +You can read more about the querying elements in the Testing library documentation. + + When Storybook loads the story, the `play` function starts its execution and queries the DOM tree expecting the element to be available when the story renders. In case there's a failure in your test, you'll be able to verify its root cause quickly. diff --git a/docs/writing-stories/stories-for-multiple-components.md b/docs/writing-stories/stories-for-multiple-components.md index f1f8c47b7bea..90e31f88f937 100644 --- a/docs/writing-stories/stories-for-multiple-components.md +++ b/docs/writing-stories/stories-for-multiple-components.md @@ -62,11 +62,11 @@ The `children` `args` as any other arg needs to be JSON serializable. It means t As they could lead into errors with your Storybook. -
+ We're currently working on improving the overall experience for the children arg and allow you to edit children arg in a control and allow you to use other types of components in the near future. But for now you need to factor in this caveat when you're implementing your stories. -
+ ## Creating a Template Component diff --git a/docs/writing-stories/typescript.md b/docs/writing-stories/typescript.md index 17d2c0b6eaca..0b7bba1a74c6 100644 --- a/docs/writing-stories/typescript.md +++ b/docs/writing-stories/typescript.md @@ -34,9 +34,9 @@ The example above passes a component type. See [**Typing custom args**](#typing- -
+ -ℹ️ We are not yet able to provide additional type safety using the `satisfies` operator with Angular and Web components. +We are not yet able to provide additional type safety using the `satisfies` operator with Angular and Web components.
More info @@ -49,7 +49,7 @@ For more information, please refer to [this discussion](https://github.com/story
-
+ diff --git a/docs/writing-tests/accessibility-testing.md b/docs/writing-tests/accessibility-testing.md index d6dbba00d27a..5d404fb3248f 100644 --- a/docs/writing-tests/accessibility-testing.md +++ b/docs/writing-tests/accessibility-testing.md @@ -203,11 +203,11 @@ Add a new [configuration file](./test-runner.md#test-hook-api-experimental) insi -
+ -💡 `preRender` and `postRender` are convenient hooks that allow you to extend the test runner's default configuration. They are **experimental** and subject to changes. Read more about them [here](./test-runner.md#test-hook-api-experimental). +`preRender` and `postRender` are convenient hooks that allow you to extend the test runner's default configuration. They are **experimental** and subject to changes. Read more about them [here](./test-runner.md#test-hook-api-experimental). -
+ When you execute the test runner (for example, with `yarn test-storybook`), it will run the accessibility audit and any [interaction tests](./interaction-testing.md) you might have configured for each component story. diff --git a/docs/writing-tests/interaction-testing.md b/docs/writing-tests/interaction-testing.md index 8f0fdd9cbab8..4080ce51ee5e 100644 --- a/docs/writing-tests/interaction-testing.md +++ b/docs/writing-tests/interaction-testing.md @@ -170,11 +170,11 @@ Storybook only runs the interaction test when you're viewing a story. Therefore, ![Interaction test with test runner](./storybook-interaction-test-runner-loginform-optimized.png) -
+ -💡 If you need, you can provide additional flags to the test-runner. Read the [documentation](./test-runner.md#cli-options) to learn more. +If you need, you can provide additional flags to the test-runner. Read the [documentation](./test-runner.md#cli-options) to learn more. -
+ ## Automate diff --git a/docs/writing-tests/snapshot-testing.md b/docs/writing-tests/snapshot-testing.md index 69b0c17c680a..8956db91bf0b 100644 --- a/docs/writing-tests/snapshot-testing.md +++ b/docs/writing-tests/snapshot-testing.md @@ -49,11 +49,11 @@ There are many other configuration options available, such as watch mode and cov ## Set up Storyshots -
+ -⛔️ Storyshots has been deprecated in favor of [test runner](./test-runner.md), which you can use for both snapshot and [visual testing](./visual-testing.md). +Storyshots has been deprecated in favor of [test runner](./test-runner.md), which you can use for both snapshot and [visual testing](./visual-testing.md). -
+ [Storyshots](https://storybook.js.org/addons/@storybook/addon-storyshots/) is a Storybook addon that enables snapshot testing, powered by [Jest](https://jestjs.io/docs/getting-started). @@ -82,9 +82,11 @@ Add a test file to your environment with the following contents to configure Sto -
-💡 You can name the test file differently to suit your needs. Bear in mind that it requires to be picked up by Jest. -
+ + +You can name the test file differently to suit your needs. Bear in mind that it requires to be picked up by Jest. + + Run your first test. Storyshots will recognize your stories (based on [.storybook/main.js's setup](https://storybook.js.org/docs/react/configure/story-rendering)) and save them in the **snapshots** directory. @@ -124,9 +126,11 @@ Next, update your test file (for example, `storybook.test.js`) to the following: -
-💡 Don't forget to replace your-custom-directory with your own. -
+ + +Don't forget to replace your-custom-directory with your own. + + When you run your tests, the snapshots will be available in the directory you've specified. diff --git a/docs/writing-tests/stories-in-end-to-end-tests.md b/docs/writing-tests/stories-in-end-to-end-tests.md index 66e068a89a71..50fa58ae0688 100644 --- a/docs/writing-tests/stories-in-end-to-end-tests.md +++ b/docs/writing-tests/stories-in-end-to-end-tests.md @@ -29,10 +29,11 @@ An example of an end-to-end test with Cypress and Storybook is testing a login c -
- 💡 The play function contains small snippets of code that run after the story renders. It allows you to sequence interactions in stories. + -
+The play function contains small snippets of code that run after the story renders. It allows you to sequence interactions in stories. + + With Cypress, you could write the following test: @@ -75,9 +76,11 @@ A real-life scenario of user flow testing with Playwright would be how to test a -
- 💡 The play function contains small snippets of code that run after the story renders. It allows you to sequence interactions in stories. -
+ + +The play function contains small snippets of code that run after the story renders. It allows you to sequence interactions in stories. + + With Playwright, you can write a test to check if the inputs are filled and match the story: diff --git a/docs/writing-tests/stories-in-unit-tests.md b/docs/writing-tests/stories-in-unit-tests.md index f96a72c9fef2..c79c31c8a901 100644 --- a/docs/writing-tests/stories-in-unit-tests.md +++ b/docs/writing-tests/stories-in-unit-tests.md @@ -28,11 +28,11 @@ Run the following command to install the addon. -
+ -ℹ️ If you're using Storybook 7 or higher, the `@storybook/testing-vue3` addon is the only one we support. For Vue 2 users, refer to the [troubleshooting section](#troubleshooting) for additional guidance. +If you're using Storybook 7 or higher, the `@storybook/testing-vue3` addon is the only one we support. For Vue 2 users, refer to the [troubleshooting section](#troubleshooting) for additional guidance. -
+ @@ -53,11 +53,11 @@ Run the following command to install the addon. -
+ -💡 You can use Testing Library out-of-the-box with [Storybook Interaction Testing](./interaction-testing.md). +You can use Testing Library out-of-the-box with [Storybook Interaction Testing](./interaction-testing.md). -
+ Once the test runs, it loads the story and renders it. [Testing Library](https://testing-library.com/) then emulates the user's behavior and checks if the component state has been updated. diff --git a/docs/writing-tests/test-runner.md b/docs/writing-tests/test-runner.md index e75bee68c549..96b08331cd75 100644 --- a/docs/writing-tests/test-runner.md +++ b/docs/writing-tests/test-runner.md @@ -52,9 +52,11 @@ Start your Storybook with: -
-💡 Storybook's test runner requires either a locally running Storybook instance or a published Storybook to run all the existing tests. -
+ + +Storybook's test runner requires either a locally running Storybook instance or a published Storybook to run all the existing tests. + + Finally, open a new terminal window and run the test-runner with: @@ -151,11 +153,11 @@ If you're publishing your Storybook with services such as [Vercel](https://verce -
+ -💡 The published Storybook must be publicly available for this example to work. We recommend running the test server using the recipe [below](#run-against-non-deployed-storybooks) if it requires authentication. +The published Storybook must be publicly available for this example to work. We recommend running the test server using the recipe [below](#run-against-non-deployed-storybooks) if it requires authentication. -
+ ### Run against non-deployed Storybooks @@ -171,11 +173,11 @@ You can use your CI provider (for example, [GitHub Actions](https://github.com/f -
+ -💡 By default Storybook outputs the [build](../sharing/publish-storybook.md#build-storybook-as-a-static-web-application) to the `storybook-static` directory. If you're using a different build directory, you'll need to adjust the recipe accordingly. +By default Storybook outputs the [build](../sharing/publish-storybook.md#build-storybook-as-a-static-web-application) to the `storybook-static` directory. If you're using a different build directory, you'll need to adjust the recipe accordingly. -
+ ### What's the difference between Chromatic and Test runner? @@ -204,11 +206,11 @@ Listed below are the available hooks and an overview of how to use them. | `preRender` | Executes before a story is rendered
`async preRender(page, context) {}` | | `postRender` | Executes after the story is rendered
`async postRender(page, context) {}` | -
+ -💡 These test hooks are experimental and may be subject to breaking changes. We encourage you to test as much as possible within the story's [play function](../writing-stories/play-function.md). +These test hooks are experimental and may be subject to breaking changes. We encourage you to test as much as possible within the story's [play function](../writing-stories/play-function.md). -
+ To enable the hooks API, you'll need to add a new configuration file inside your Storybook directory and set them up as follows: @@ -223,11 +225,11 @@ To enable the hooks API, you'll need to add a new configuration file inside your -
+ -💡 Except for the `setup` function, all other functions run asynchronously. Both `preRender` and `postRender` functions include two additional arguments, a [Playwright page](https://playwright.dev/docs/pages) and a context object which contains the `id`, `title`, and the `name` of the story. +Except for the `setup` function, all other functions run asynchronously. Both `preRender` and `postRender` functions include two additional arguments, a [Playwright page](https://playwright.dev/docs/pages) and a context object which contains the `id`, `title`, and the `name` of the story. -
+ When the test-runner executes, your existing tests will go through the following lifecycle: @@ -273,11 +275,11 @@ Suppose you run into a situation where the local and remote Storybooks appear ou -
+ -💡 The `index.json` mode is not compatible with watch mode. +The `index.json` mode is not compatible with watch mode. -
+ If you need to disable it, use the `--no-index-json` flag: diff --git a/docs/writing-tests/visual-testing.md b/docs/writing-tests/visual-testing.md index 7e303fcfa4aa..c70ed93d37e9 100644 --- a/docs/writing-tests/visual-testing.md +++ b/docs/writing-tests/visual-testing.md @@ -42,11 +42,11 @@ Run the following command after the package finishes installing: npx chromatic --project-token ``` -
+ Don't forget to replace `your-project-token` with the one provided by Chromatic. -
+ ```shell Build 1 published. @@ -54,9 +54,11 @@ Build 1 published. View it online at https://www.chromatic.com/build?appId=...&number=1. ``` -
-💡 Before running Chromatic's CLI ensure you have at least two commits added to the repository to prevent build failures, as Chromatic relies on a full Git history graph to establish the baselines. Read more about baselines in Chromatic's documentation -
+ + +Before running Chromatic's CLI ensure you have at least two commits added to the repository to prevent build failures, as Chromatic relies on a full Git history graph to establish the baselines. Read more about baselines in Chromatic's documentation + + When Chromatic finishes, it should have successfully deployed your Storybook and established the baselines, that is to say, the starting point for all your component's stories. Additionally, providing you with a link to the published Storybook that you can share with your team to gather feedback. diff --git a/node_modules/.yarn-state.yml b/node_modules/.yarn-state.yml deleted file mode 100644 index a6b1a224e847..000000000000 --- a/node_modules/.yarn-state.yml +++ /dev/null @@ -1,10 +0,0 @@ -# Warning: This file is automatically generated. Removing it is fine, but will -# cause your node_modules installation to become invalidated. - -__metadata: - version: 1 - nmMode: classic - -"@storybook/root@workspace:.": - locations: - - "" From 1318f0181b58387b369e2fdfab3b01679372b2d5 Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Sat, 4 Nov 2023 00:35:06 +0000 Subject: [PATCH 2/3] Fix links and issues --- docs/addons/addon-knowledge-base.md | 4 ++-- docs/addons/addon-types.md | 8 ++++---- docs/addons/integration-catalog.md | 2 +- docs/api/cli-options.md | 2 +- docs/api/doc-block-controls.md | 12 ++++++------ docs/configure/environment-variables.md | 2 +- docs/configure/theming.md | 6 +++--- docs/contribute/code.md | 4 ++-- docs/contribute/how-to-reproduce.md | 6 ++++-- docs/contribute/new-snippets.md | 2 +- docs/essentials/actions.md | 2 +- docs/essentials/controls.md | 6 +++--- docs/essentials/measure-and-outline.md | 2 +- docs/faq.md | 14 +++++++------- docs/writing-stories/args.md | 8 ++++---- docs/writing-stories/build-pages-with-storybook.md | 6 +++--- docs/writing-stories/play-function.md | 2 +- docs/writing-tests/visual-testing.md | 2 +- 18 files changed, 46 insertions(+), 44 deletions(-) diff --git a/docs/addons/addon-knowledge-base.md b/docs/addons/addon-knowledge-base.md index 11cdfe497464..a3ff08ac2500 100644 --- a/docs/addons/addon-knowledge-base.md +++ b/docs/addons/addon-knowledge-base.md @@ -80,7 +80,7 @@ Complementing the components, also included is a set of UI primitives. Use the c -The color palette implemented by @storybook/components is a high-level abstraction of the @storybook/theming package. +The color palette implemented by `@storybook/components` is a high-level abstraction of the [`@storybook/theming`](https://github.com/storybookjs/storybook/tree/next/code/lib/theming/src) package. @@ -98,7 +98,7 @@ When you're developing your addon as a package, you can’t use `npm link` to ad -Run either yarn or npm install to install the addon. +Run either `yarn` or `npm install` to install the addon. diff --git a/docs/addons/addon-types.md b/docs/addons/addon-types.md index d76edca7c7d6..10be1afd1c9b 100644 --- a/docs/addons/addon-types.md +++ b/docs/addons/addon-types.md @@ -10,7 +10,7 @@ UI-based addons allow you to customize Storybook's UI with the following element ### Panels -Panel addons allow you to add your own UI in Storybook's addon panel. This is the most common type of addon in the ecosystem. For example, the official [@storybook/actions](../essentials/actions.md) and [@storybook/a11y](https://github.com/storybookjs/storybook/tree/next/code/addons/a11y) use this pattern. +Panel addons allow you to add your own UI in Storybook's addon panel. This is the most common type of addon in the ecosystem. For example, the official [`@storybook/actions`](../essentials/actions.md) and [`@storybook/a11y`](https://github.com/storybookjs/storybook/tree/next/code/addons/a11y) use this pattern. ![Storybook panel](./storybook-panel.png) @@ -28,7 +28,7 @@ Use this boilerplate code to add a new `Panel` to Storybook's UI: ### Toolbars -Toolbar addons allow you to add your own custom tools in Storybook's Toolbar. For example, the official [@storybook/backgrounds](../essentials/backgrounds.md) and the [@storybook/addon-outline/](../essentials/measure-and-outline.md#outline-addon) use this pattern. +Toolbar addons allow you to add your own custom tools in Storybook's Toolbar. For example, the official [`@storybook/backgrounds`](../essentials/backgrounds.md) and the [`@storybook/addon-outline`](../essentials/measure-and-outline.md#outline-addon) use this pattern. ![Storybook toolbar addon](./storybook-toolbar.png) @@ -46,7 +46,7 @@ Use this boilerplate code to add a new `button` to Storybook's Toolbar: -The icon element used in the example loads the icons from the @storybook/components package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. +The `icon` element used in the example loads the icons from the `@storybook/components` package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. @@ -70,7 +70,7 @@ Use this boilerplate code to add a new `Tab` to Storybook's UI: -Learn how to write your own addon that includes these UI elements here. +Learn how to write your own addon that includes these UI elements [here](./writing-addons.md). diff --git a/docs/addons/integration-catalog.md b/docs/addons/integration-catalog.md index b6d018724c89..cdf96459eb75 100644 --- a/docs/addons/integration-catalog.md +++ b/docs/addons/integration-catalog.md @@ -56,7 +56,7 @@ Use the list below as a reference when filling in the values for both the `suppo -Make sure to copy each item exactly as listed so that we can properly index your addon in our catalog. +Make sure to copy each item **exactly** as listed so that we can properly index your addon in our catalog. diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index 3685881d8f75..a89d55a94d14 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -77,6 +77,6 @@ Options include: -If you're using npm instead of yarn to publish Storybook, the commands work slightly different. For example, npm run storybook build -- -o ./path/to/build. +If you're using npm instead of yarn to publish Storybook, the commands work slightly different. For example, `npm run storybook build -- -o ./path/to/build`. diff --git a/docs/api/doc-block-controls.md b/docs/api/doc-block-controls.md index 60334672163f..7079a6a43831 100644 --- a/docs/api/doc-block-controls.md +++ b/docs/api/doc-block-controls.md @@ -12,12 +12,6 @@ If you’re looking for a static table that shows a component's arg types with n - - -The Controls doc block will only have functioning UI controls if you have also installed and registered [`@storybook/addon-controls`](../essentials/controls.md) (included in [`@storybook/addon-essentials`](../essentials/introduction.md)). - - - ![Screenshot of Controls block](./doc-block-controls.png) @@ -35,6 +29,12 @@ import * as ButtonStories from './Button.stories' ``` + + +The Controls doc block will only have functioning UI controls if you have also installed and registered [`@storybook/addon-controls`](../essentials/controls.md) (included in [`@storybook/addon-essentials`](../essentials/introduction.md)). + + + ## Controls ```js diff --git a/docs/configure/environment-variables.md b/docs/configure/environment-variables.md index f943b05c5237..d4ba9252c58c 100644 --- a/docs/configure/environment-variables.md +++ b/docs/configure/environment-variables.md @@ -50,7 +50,7 @@ You can also access these variables in your custom ``/`` using the s -If using the environment variables as attributes or values in JavaScript, you may need to add quotes, as the value will be inserted directly. e.g. `` +If using the environment variables as attributes or values in JavaScript, you may need to add quotes, as the value will be inserted directly, for example: ``. diff --git a/docs/configure/theming.md b/docs/configure/theming.md index d8a56e6e5458..73cc315f5fc6 100644 --- a/docs/configure/theming.md +++ b/docs/configure/theming.md @@ -89,7 +89,7 @@ Inside your `.storybook` directory, create a new file called `YourTheme.js` and -If you're using brandImage to add your custom logo, you can use any of the most common image formats. +If you're using `brandImage` to add your custom logo, you can use any of the most common image formats. @@ -139,7 +139,7 @@ With the new changes introduced, the custom theme should yield a similar result. -Many theme variables are optional, the base property is NOT. +Many theme variables are optional, the base property is **NOT**. @@ -156,7 +156,7 @@ To style these elements, insert style tags into: -The same way as you can adjust your [preview’s head tag](../configure/story-rendering.md#adding-to-head), Storybook allows you to modify the code on the manager's side, through .storybook/manager-head.html. It can be helpful when adding theme styles that target Storybook's HTML, but it comes with a cost as Storybook's inner HTML can change at any time through the release cycle. +The same way as you can adjust your [preview’s head tag](../configure/story-rendering.md#adding-to-head), Storybook allows you to modify the code on the manager's side, through `.storybook/manager-head.html`. It can be helpful when adding theme styles that target Storybook's HTML, but it comes with a cost as Storybook's inner HTML can change at any time through the release cycle. diff --git a/docs/contribute/code.md b/docs/contribute/code.md index 39a1818e2ee6..7ce0068157bb 100644 --- a/docs/contribute/code.md +++ b/docs/contribute/code.md @@ -86,7 +86,7 @@ When prompted to start the build process in `watch` mode, answer **yes** to deve -Build's `watch` mode is great for interactive development. However, for performance reasons, it only transpiles your code and doesn't execute the TypeScript compiler. If something isn't working as expected, try running the `build` command WITHOUT enabling watch mode: it will re-generate TypeScript types and perform automatic type checking for you. +Build's `watch` mode is great for interactive development. However, for performance reasons, it only transpiles your code and doesn't execute the TypeScript compiler. If something isn't working as expected, try running the `build` command **WITHOUT** enabling watch mode: it will re-generate TypeScript types and perform automatic type checking for you. @@ -175,7 +175,7 @@ Typically it is a good idea to start from the `install` task to ensure your loca -The default instructions run the code in "linked" mode, meaning built changes to Storybook library code will be reflected in the sandbox immediately (the next time you run the task). However, CI runs in "unlinked" mode, which in rare cases, will behave differently.
+The default instructions run the code in "linked" mode, meaning built changes to Storybook library code will be reflected in the sandbox immediately (the next time you run the task). However, CI runs in "unlinked" mode, which in rare cases, will behave differently. If you are having trouble reproducing, try rerunning the command with the `--no-link` flag. If you need to do that, you'll need to run it with `--start-from=compile` after each code change. diff --git a/docs/contribute/how-to-reproduce.md b/docs/contribute/how-to-reproduce.md index 737599351546..90036ca37e89 100644 --- a/docs/contribute/how-to-reproduce.md +++ b/docs/contribute/how-to-reproduce.md @@ -25,7 +25,8 @@ npx storybook@next sandbox ``` -You can append a template name in the command to get filtered results e.g. npx storybook@next sandbox react + +You can append a template name in the command to get filtered results (e.g., `npx storybook@next sandbox react`). @@ -40,6 +41,7 @@ Finally, enter a location for your reproduction: If you don't provide a full path for the reproduction it will be generated in the current directory. + If everything worked as it should, you should have a fully functional Storybook set up in your local environment. @@ -66,7 +68,7 @@ Then, follow GitHub's instructions to set up the repository. -Don't forget to replace your-username with your own account name. +Don't forget to replace `your-username` with your own account name. diff --git a/docs/contribute/new-snippets.md b/docs/contribute/new-snippets.md index 2175556670bb..0ba9c72067f0 100644 --- a/docs/contribute/new-snippets.md +++ b/docs/contribute/new-snippets.md @@ -87,7 +87,7 @@ Create the file `ember/your-component.js.mdx`, similar to the other frameworks, -Code snippets are divided into various file extensions, if you're contributing a TypeScript file use .ts.mdx, or if you're adding JavaScript files use .js.mdx. +Code snippets are divided into various file extensions, if you're contributing a TypeScript file use `.ts.mdx`, or if you're adding JavaScript files use `.js.mdx`. diff --git a/docs/essentials/actions.md b/docs/essentials/actions.md index 0077ab003631..70a7496f9ee3 100644 --- a/docs/essentials/actions.md +++ b/docs/essentials/actions.md @@ -72,7 +72,7 @@ If you need more granular control over which `argTypes` are matched, you can adj -If you're generating argTypes with another addon (like [docs](../writing-docs/introduction.md), which is the common behavior), ensure the actions addon AFTER the other addon. You can do this by listing it later in the addons registration code in [`.storybook/main.js`](../configure/overview.md#configure-story-rendering). This is default in [essentials](./introduction.md). +If you're generating argTypes with another addon (like [docs](../writing-docs/introduction.md), which is the common behavior), ensure the actions addon **AFTER** the other addon. You can do this by listing it later in the addons registration code in [`.storybook/main.js`](../configure/overview.md#configure-story-rendering). This is default in [essentials](./introduction.md). diff --git a/docs/essentials/controls.md b/docs/essentials/controls.md index a41caf4a3ac0..fff305286b8b 100644 --- a/docs/essentials/controls.md +++ b/docs/essentials/controls.md @@ -23,7 +23,7 @@ To use the Controls addon, you need to write your stories using [args](../writin -If you have stories in the older pre-Storybook 6 style, check the args & controls migration guide to learn how to convert your existing stories for args. +If you have stories in the older pre-Storybook 6 style, check the [args & controls migration guide](https://medium.com/storybookjs/storybook-6-migration-guide-200346241bb5) to learn how to convert your existing stories for args. @@ -231,7 +231,7 @@ As shown above, you can configure individual controls with the “control" annot -The date control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object. +The `date` control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object. @@ -252,7 +252,7 @@ The date control will convert the date into a UNIX timestamp when t -Numeric data types will default to a number control unless additional configuration is provided. +Numeric data types will default to a `number` control unless additional configuration is provided. diff --git a/docs/essentials/measure-and-outline.md b/docs/essentials/measure-and-outline.md index d4ebe622d6e1..277e9ee4c164 100644 --- a/docs/essentials/measure-and-outline.md +++ b/docs/essentials/measure-and-outline.md @@ -18,7 +18,7 @@ With Storybook's Measure addon, you can quickly visualize each component's measu -Alternatively you can press the m key on your keyboard to toggle the addon. +Alternatively you can press the `m` key on your keyboard to toggle the addon. diff --git a/docs/faq.md b/docs/faq.md index a03b60cc9d52..6539f6a3431f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -93,7 +93,7 @@ npm test -- --coverage --collectCoverageFrom='["src/**/*.{js,jsx}","!src/**/stor - If you're using yarn as a package manager, you'll need to adjust the command accordingly. +If you're using [`Yarn`](https://yarnpkg.com/) as a package manager, you'll need to adjust the command accordingly. @@ -121,7 +121,7 @@ export default { ## How do I fix module resolution in special environments? -In case you are using [yarn Plug-n-Play](https://yarnpkg.com/features/pnp) or your project is set up within a mono repository environment, you might run into issues with module resolution similar to this when running Storybook: +In case you are using [Yarn Plug-n-Play](https://yarnpkg.com/features/pnp) or your project is set up within a mono repository environment, you might run into issues with module resolution similar to this when running Storybook: ```shell WARN Failed to load preset: "@storybook/react-webpack5/preset"` @@ -265,7 +265,7 @@ We're actively working to provide a better way to address this situation, but in ## Is it possible to browse the documentation for past versions of Storybook? -With the release of version 6.0, we updated our documentation as well. That doesn't mean that the old documentation was removed. We kept it to help you with your Storybook migration process. Use the content from the table below in conjunction with our migration guide . +With the release of version 6.0, we updated our documentation as well. That doesn't mean that the old documentation was removed. We kept it to help you with your Storybook migration process. Use the content from the table below in conjunction with our [migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md). We're only covering versions 5.3 and 5.0 as they were important milestones for Storybook. If you want to go back in time a little more, you'll have to check the specific release in the monorepo. @@ -350,7 +350,7 @@ We're only covering versions 5.3 and 5.0 as they were important milestones for S -With the release of version 5.3, we've updated how you can write your stories more compactly and easily. It doesn't mean that the storiesOf format has been removed. For the time being, we're still supporting it, and we have documentation for it. But be advised that this is bound to change in the future. +With the release of version 5.3, we've updated how you can write your stories more compactly and easily. It doesn't mean that the `storiesOf` format has been removed. For the time being, we're still supporting it, and we have documentation for it. But be advised that this is bound to change in the future. @@ -373,7 +373,7 @@ npx http-server storybook-static -Suppose you don't want to run the command above frequently. Add http-server as a development dependency and create a new script to preview your production build of Storybook. +Suppose you don't want to run the command above frequently. Add `http-server` as a development dependency and create a new script to preview your production build of Storybook. @@ -452,11 +452,11 @@ export default { }; ``` -With Angular, the most common issue is the placement of the `mockServiceWorker.js` file. Use this [example](https://github.com/mswjs/examples/tree/master/examples/rest-angular/) as a point of reference. +With Angular, the most common issue is the placement of the `mockServiceWorker.js` file. Use this [example](https://github.com/mswjs/examples/tree/main/examples/with-angular) as a point of reference. ## Can I use other GraphQL providers with Storybook's MSW addon? -Yes, check the [addon's examples](https://github.com/mswjs/msw-storybook-addon/tree/master/packages/docs/src/demos) to learn how to integrate different providers. +Yes, check the [addon's examples](https://github.com/mswjs/msw-storybook-addon/tree/main/packages/docs/src/demos) to learn how to integrate different providers. ## Can I mock GraphQL mutations with Storybook's MSW addon? diff --git a/docs/writing-stories/args.md b/docs/writing-stories/args.md index e2553cfd6972..b1f8adb992f7 100644 --- a/docs/writing-stories/args.md +++ b/docs/writing-stories/args.md @@ -287,9 +287,9 @@ In Storybook 5 and before we passed the context as the first argument. If you’ - + + +Note that `args` is still available as a key in the context. - Note that `args` is still available as a key in the context. - - +
diff --git a/docs/writing-stories/build-pages-with-storybook.md b/docs/writing-stories/build-pages-with-storybook.md index 12b661158809..677cf7f0199b 100644 --- a/docs/writing-stories/build-pages-with-storybook.md +++ b/docs/writing-stories/build-pages-with-storybook.md @@ -173,7 +173,7 @@ To test your screen with the mocked data, you could write a similar set of stori -This example details how you can mock the REST request with fetch. Similar HTTP clients such as axios can be used as well. +This example details how you can mock the REST request with fetch. Similar HTTP clients such as [`axios`](https://axios-http.com/) can be used as well. @@ -241,7 +241,7 @@ Inside a directory called `__mocks__`, create a new file called The code above creates a decorator which reads story-specific data off the story's [parameters](./parameters.md), enabling you to configure the mock on a per-story basis. -To use the mock in place of the real import, we use [webpack aliasing](https://webpack.js.org/configuration/resolve/#resolvealias): +To use the mock in place of the real import, we use [Webpack aliasing](https://webpack.js.org/configuration/resolve/#resolvealias): @@ -253,7 +253,7 @@ To use the mock in place of the real import, we use [webpack aliasing](https://w -Add the decorator you've just implemented to your [storybook/preview.js](../configure/overview.md#configure-story-rendering): +Add the decorator you've just implemented to your [`storybook/preview.js`](../configure/overview.md#configure-story-rendering): diff --git a/docs/writing-stories/play-function.md b/docs/writing-stories/play-function.md index b83d22b3612f..9fb0852d8f09 100644 --- a/docs/writing-stories/play-function.md +++ b/docs/writing-stories/play-function.md @@ -189,7 +189,7 @@ If you need, you can also adjust your `play` function to find elements based on -You can read more about the querying elements in the Testing library documentation. +You can read more about the querying elements in the [Testing Library documentation](https://testing-library.com/docs/queries/about/). diff --git a/docs/writing-tests/visual-testing.md b/docs/writing-tests/visual-testing.md index c70ed93d37e9..c4e2f66f68ac 100644 --- a/docs/writing-tests/visual-testing.md +++ b/docs/writing-tests/visual-testing.md @@ -56,7 +56,7 @@ View it online at https://www.chromatic.com/build?appId=...&number=1. -Before running Chromatic's CLI ensure you have at least two commits added to the repository to prevent build failures, as Chromatic relies on a full Git history graph to establish the baselines. Read more about baselines in Chromatic's documentation +Before running Chromatic's CLI ensure you have at least two commits added to the repository to prevent build failures, as Chromatic relies on a full Git history graph to establish the baselines. Read more about baselines in Chromatic's [documentation](https://www.chromatic.com/docs/branching-and-baselines?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook). From d869a868aafb90cfa51a569677905b4b98233096 Mon Sep 17 00:00:00 2001 From: Shaun Lloyd Date: Mon, 6 Nov 2023 09:25:51 -0500 Subject: [PATCH 3/3] Revert accidental deletion --- node_modules/.yarn-state.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 node_modules/.yarn-state.yml diff --git a/node_modules/.yarn-state.yml b/node_modules/.yarn-state.yml new file mode 100644 index 000000000000..af981fec0a05 --- /dev/null +++ b/node_modules/.yarn-state.yml @@ -0,0 +1,10 @@ +# Warning: This file is automatically generated. Removing it is fine, but will +# cause your node_modules installation to become invalidated. + +__metadata: + version: 1 + nmMode: classic + +"@storybook/root@workspace:.": + locations: + - "" \ No newline at end of file