diff --git a/docs/_snippets/addon-backgrounds-disabled.md b/docs/_snippets/addon-backgrounds-disabled.md index 140dd63610dd..366edee9c399 100644 --- a/docs/_snippets/addon-backgrounds-disabled.md +++ b/docs/_snippets/addon-backgrounds-disabled.md @@ -27,8 +27,8 @@ export const Large = { ``` ```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="Without globals API" -// Replace your-framework with the name of your framework -import type { Meta, StoryObj } from '@storybook/your-framework'; +// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.) +import { Meta, StoryObj } from '@storybook/your-renderer'; import { Button } from './Button'; @@ -47,8 +47,8 @@ export const Large: Story = { ``` ```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="With globals API" -// Replace your-framework with the name of your framework -import type { Meta, StoryObj } from '@storybook/your-framework'; +// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.) +import { Meta, StoryObj } from '@storybook/your-renderer'; import { Button } from './Button'; @@ -67,8 +67,8 @@ export const Large: Story = { ``` ```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="Without globals API" -// Replace your-framework with the name of your framework -import type { Meta, StoryObj } from '@storybook/your-framework'; +// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.) +import { Meta, StoryObj } from '@storybook/your-renderer'; import { Button } from './Button'; @@ -87,8 +87,8 @@ export const Large: Story = { ``` ```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="With globals API" -// Replace your-framework with the name of your framework -import type { Meta, StoryObj } from '@storybook/your-framework'; +// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.) +import { Meta, StoryObj } from '@storybook/your-renderer'; import { Button } from './Button'; diff --git a/docs/_snippets/addon-backgrounds-values-in-meta.md b/docs/_snippets/addon-backgrounds-values-in-meta.md index cdb9f6d9cc31..aa621c8d0200 100644 --- a/docs/_snippets/addon-backgrounds-values-in-meta.md +++ b/docs/_snippets/addon-backgrounds-values-in-meta.md @@ -35,7 +35,7 @@ export default { ``` ```ts filename="Button.stories.ts" renderer="web-components" language="ts" -import type { Meta, StoryObj } from '@storybook/web-components'; +import type { Meta } from '@storybook/web-components'; const meta: Meta = { component: 'demo-button', diff --git a/docs/_snippets/addon-viewport-add-viewport-in-preview.md b/docs/_snippets/addon-viewport-add-viewport-in-preview.md index 6808cb604d51..990f952e2ef2 100644 --- a/docs/_snippets/addon-viewport-add-viewport-in-preview.md +++ b/docs/_snippets/addon-viewport-add-viewport-in-preview.md @@ -99,8 +99,8 @@ export default { ``` ```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="With globals API" -// Replace your-framework with the framework you are using (e.g., react, vue3) -import { Preview } from '@storybook/your-framework'; +// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.) +import { Preview } from '@storybook/your-renderer'; import { MINIMAL_VIEWPORTS } from '@storybook/addon-viewport'; const kindleViewports = { diff --git a/docs/_snippets/addon-viewport-define-globals.md b/docs/_snippets/addon-viewport-define-globals.md index 29dec7e660f9..f15c367fb14c 100644 --- a/docs/_snippets/addon-viewport-define-globals.md +++ b/docs/_snippets/addon-viewport-define-globals.md @@ -42,8 +42,8 @@ export const OnPhone = { ``` ```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" -// Replace your-framework with the name of your framework -import type { Meta, StoryObj } from '@storybook/your-framework'; +// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.) +import type { Meta, StoryObj } from '@storybook/your-renderer'; import { Button } from './Button'; @@ -67,8 +67,8 @@ export const OnPhone: Story = { ``` ```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" -// Replace your-framework with the name of your framework -import type { Meta, StoryObj } from '@storybook/your-framework'; +// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.) +import type { Meta, StoryObj } from '@storybook/your-renderer'; import { Button } from './Button'; diff --git a/docs/_snippets/storybook-preview-configure-background-colors.md b/docs/_snippets/storybook-preview-configure-background-colors.md deleted file mode 100644 index b28b04f64312..000000000000 --- a/docs/_snippets/storybook-preview-configure-background-colors.md +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/docs/api/main-config/main-config-features.mdx b/docs/api/main-config/main-config-features.mdx index 933c1d0d96d6..47dd9c107d49 100644 --- a/docs/api/main-config/main-config-features.mdx +++ b/docs/api/main-config/main-config-features.mdx @@ -12,60 +12,60 @@ Type: ```ts { argTypeTargetsV7?: boolean; + backgroundsStoryGlobals?: boolean; legacyDecoratorFileOrder?: boolean; viewportStoryGlobals?: boolean; - backgroundsStoryGlobals?: boolean; } ``` Enables Storybook's additional features. -## `legacyDecoratorFileOrder` +## `argTypeTargetsV7` + +(⚠️ **Experimental**) Type: `boolean` -Apply decorators from preview.js before decorators from addons or frameworks. [More information](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#changed-decorator-order-between-previewjs-and-addonsframeworks). +Filter args with a "target" on the type from the render function. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} -## `argTypeTargetsV7` - -(⚠️ **Experimental**) +## `backgroundsStoryGlobals` Type: `boolean` -Filter args with a "target" on the type from the render function. +Configures the [Backgrounds addon](../../essentials/backgrounds.mdx) to opt-in to the new story globals API for configuring backgrounds. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} -## `viewportStoryGlobals` +## `legacyDecoratorFileOrder` Type: `boolean` -Configures the [Viewports addon](../../essentials/viewport.mdx) to opt-in to the new story globals API for configuring viewports. +Apply decorators from preview.js before decorators from addons or frameworks. [More information](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#changed-decorator-order-between-previewjs-and-addonsframeworks). {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} -## `backgroundsStoryGlobals` +## `viewportStoryGlobals` Type: `boolean` -Configures the [Backgrounds addon](../../essentials/backgrounds.mdx) to opt-in to the new story globals API for configuring backgrounds. +Configures the [Viewports addon](../../essentials/viewport.mdx) to opt-in to the new story globals API for configuring viewports. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/essentials/backgrounds.mdx b/docs/essentials/backgrounds.mdx index 68151756ecab..2d5eea3f50bd 100644 --- a/docs/essentials/backgrounds.mdx +++ b/docs/essentials/backgrounds.mdx @@ -12,7 +12,7 @@ The backgrounds toolbar addon allows you to set the background color on which th **`globals` API** - This addon has been updated to use the `globals` API when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled. With `globals`, when you specify a background value for a story, it cannot be overridden from the toolbar. This ensures a consistent experience while navigating between stories. This will be the default behavior and API in Storybook 9. + This addon has been updated to use the `globals` API when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled. With `globals`, when you specify a background value for a story, it cannot be overridden from the toolbar, which ensures a consistent experience while navigating between stories. This will be the default behavior and API in Storybook 9. ## Configuration @@ -240,12 +240,24 @@ Default: `0.5` The opacity of the grid lines. +#### `values` + +(Required, see description) + +Type: `{ name: string; value: string }[]` + +Available background colors. See above for a [usage example](#configuration). + +When defining the `backgrounds` parameter at the project level (in `.storybook/preview.js|ts`), you _must_ define the `values` property. + **With the [`globals` API](#globals-api)** #### `options` + (Required, see description) + Type: ```ts @@ -257,20 +269,10 @@ The opacity of the grid lines. } ``` - Required: See description + Replaces: [`values`](#values) - Defines the background colors. Replaces [`values`](#values). The key is used to reference the color, and the value is an object to define it. See above for a [usage example](#configuration). + Available background colors. See above for a [usage example](#configuration). When defining the `backgrounds` parameter at the project level (in `.storybook/preview.js|ts`), you _must_ define the `options` property. - - -#### `values` - -Type: `{ name: string; value: string }[]` - -Required: See description - -Available background colors. See above for a [usage example](#configuration). - -When defining the `backgrounds` parameter at the project level (in `.storybook/preview.js|ts`), you _must_ define the `values` property. + \ No newline at end of file diff --git a/docs/essentials/toolbars-and-globals.mdx b/docs/essentials/toolbars-and-globals.mdx index 18ab6bdbb721..69fc41f1b1b6 100644 --- a/docs/essentials/toolbars-and-globals.mdx +++ b/docs/essentials/toolbars-and-globals.mdx @@ -82,7 +82,7 @@ We have a `global` implemented. Let's wire it up! We can consume our new `theme` ## Setting globals on a story - The ability to set globals on a story or component is available in Storybook 8.3+. Some addons, like [backgrounds](./backgrounds.mdx) and [viewport](./viewport.mdx), have been updated to use the `globals` API when a feature flag is enabled. + The ability to set globals on a story or component is available in Storybook 8.3+. Some addons, like [backgrounds](./backgrounds.mdx) and [viewport](./viewport.mdx), have been updated to use the `globals` API when a [feature flag](../api/main-config/main-config-features.mdx) is enabled. When a global value is changed with a toolbar menu in Storybook, that value continues to be used as you navigate between stories. But sometimes a story requires a specific value to render correctly, e.g., when testing against a particular environment. @@ -95,7 +95,7 @@ To ensure that a story always uses a specific global value, regardless of what h {/* prettier-ignore-end */} -In the example above, Storybook will force all Button stories to use a gray background color, except the `OnDark` story, which will use the dark background. For all Buttons stories, the toolbar menu will be disabled for the `backgrounds` global, with a tooltip explaining that the global is set at the story level. +In the example above, Storybook will force all Button stories to use a gray background color, except the `OnDark` story, which will use the dark background. For all Button stories, the toolbar menu will be disabled for the `backgrounds` global, with a tooltip explaining that the global is set at the story level. diff --git a/docs/essentials/viewport.mdx b/docs/essentials/viewport.mdx index d685ecf7649a..a72db24c034d 100644 --- a/docs/essentials/viewport.mdx +++ b/docs/essentials/viewport.mdx @@ -14,14 +14,14 @@ The Viewport toolbar item allows you to adjust the dimensions of the iframe your **`globals` API** - This addon has been updated to use the `globals` API when the [`viewportStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#viewportstoryglobals) is enabled. With `globals`, when you specify a viewport for a story, it cannot be overridden from the toolbar. This ensures a consistent experience while navigating between stories. This will be the default behavior and API in Storybook 9. + This addon has been updated to use the `globals` API when the [`viewportStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#viewportstoryglobals) is enabled. With `globals`, when you specify a viewport for a story, it cannot be overridden from the toolbar, which ensures a consistent experience while navigating between stories. This will be the default behavior and API in Storybook 9. ## Configuration Out of the box, the Viewport addon offers you a standard set of viewports that you can use. If you want to change the default set of viewports, you can configure your own viewports with the `viewport` [parameter](../writing-stories/parameters.mdx) in your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering). -You can define the available viewports using the [`viewports` property](#viewports) and set the initial viewport using the [`defaultViewport` property](#default): +You can define the available viewports using the [`viewports` property](#viewports) and set the initial viewport using the [`defaultViewport` property](#defaultViewport): {/* prettier-ignore-start */} @@ -229,6 +229,22 @@ Turn off this addon's behavior. If you wish to turn off this addon for the entir This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could be re-enabled by setting it to `false` at the meta (component) or story level. +#### `viewports` + +Type: + +```ts +{ + [key: string]: { + name: string; + styles: { height: string, width: string }; + type: 'desktop' | 'mobile' | 'tablet'; + }; +} +``` + +Specify the available viewports. See [usage example](#add-new-devices) above. The `width` and `height` values must include the unit, e.g. `'320px'`. + **With the [`globals` API](#globals-api)** @@ -247,25 +263,11 @@ This parameter is most useful to allow overriding at more specific levels. For e } ``` - Specify the available viewports. Replaces [`viewports`](#viewports). The key is used to reference the viewport, and the value is an object to define it. See [usage example](#add-new-devices) above. The `width` and `height` values must include the unit, e.g. `'320px'`. + Replaces: [`viewports`](#viewports) - + Specify the available viewports. See [usage example](#add-new-devices) above. The `width` and `height` values must include the unit, e.g. `'320px'`. -#### `viewports` - -Type: - -```ts -{ - [key: string]: { - name: string; - styles: { height: string, width: string }; - type: 'desktop' | 'mobile' | 'tablet'; - }; -} -``` - -Specify the available viewports. The key is used to reference the viewport, and the value is an object to define it. See [usage example](#add-new-devices) above. The `width` and `height` values must include the unit, e.g. `'320px'`. + ### Exports