From 25f972c037105f2489a5993f82fbb1901485ee16 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Fri, 20 Oct 2023 16:00:54 -0600 Subject: [PATCH] WIP --- docs/api/doc-block-canvas.md | 4 +- docs/api/parameters.md | 225 ++++++++++++++++++ .../snippets/common/parameters-in-meta.js.mdx | 17 ++ .../snippets/common/parameters-in-meta.ts.mdx | 23 ++ .../common/parameters-in-preview.js.mdx | 14 ++ .../common/parameters-in-preview.ts.mdx | 19 ++ .../common/parameters-in-story.js.mdx | 18 ++ .../common/parameters-in-story.ts.mdx | 24 ++ docs/toc.js | 9 +- 9 files changed, 349 insertions(+), 4 deletions(-) create mode 100644 docs/api/parameters.md create mode 100644 docs/snippets/common/parameters-in-meta.js.mdx create mode 100644 docs/snippets/common/parameters-in-meta.ts.mdx create mode 100644 docs/snippets/common/parameters-in-preview.js.mdx create mode 100644 docs/snippets/common/parameters-in-preview.ts.mdx create mode 100644 docs/snippets/common/parameters-in-story.js.mdx create mode 100644 docs/snippets/common/parameters-in-story.ts.mdx diff --git a/docs/api/doc-block-canvas.md b/docs/api/doc-block-canvas.md index 8c27490bacb8..ce808430dc52 100644 --- a/docs/api/doc-block-canvas.md +++ b/docs/api/doc-block-canvas.md @@ -124,14 +124,14 @@ Provides HTML class(es) to the preview element, for custom styling. ### `layout` -Type: `'padded' | 'centered' | 'fullscreen'` +Type: `'centered' | 'fullscreen' | 'padded'` Default: `parameters.layout` or `parameters.docs.canvas.layout` or `'padded'` Specifies how the canvas should layout the story. -- **padded**: Add padding to the story - **centered**: Center the story within the canvas +- **padded**: (default) Add padding to the story - **fullscreen**: Show the story as-is, without padding In addition to the `parameters.docs.canvas.layout` property or the `layout` prop, the `Canvas` block will respect the `parameters.layout` value that defines [how a story is laid out](../configure/story-layout.md) in the regular story view. diff --git a/docs/api/parameters.md b/docs/api/parameters.md new file mode 100644 index 000000000000..15f681e0653e --- /dev/null +++ b/docs/api/parameters.md @@ -0,0 +1,225 @@ +--- +title: 'Parameters' +--- + +Parameters are static metadata used to configure your [stories](../get-started/whats-a-story.md) and [addons](../addons/introduction.md) in Storybook. They are specified at the story, meta (component), project (global) levels. + +## Story parameters + +
+ +ℹ️ Parameters specified at the story level will [override](#parameter-inheritance) those specified at the project level and meta (component) level. + +
+ +Parameters specified at the story level apply to that story only. They are defined in the `parameters` property of the story (named export): + + + + + + + +## Meta parameters + +
+ +ℹ️ Parameters specified at the meta (component) level will [override](#parameter-inheritance) those specified at the project level. + +
+ +Parameter's specified in a [CSF](../writing-stories/introduction.md#component-story-format-csf) file's meta configuration apply to all stories in that file. They are defined in the `parameters` property of the `meta` (default export): + + + + + + + +## Project parameters + +Parameters specified at the project (global) level apply to **all stories** in your Storybook. They are defined in the `parameters` property of the default export in your `.storybook/preview.js|ts` file: + + + + + + + +## Available parameters + +Storybook only accepts a few parameters directly. + +### `layout` + +Type: `'centered' | 'fullscreen' | 'padded'` + +Default: `'padded'` + +Specifies how the canvas should layout the story. + +- **centered**: Center the story within the canvas +- **padded**: (default) Add padding to the story +- **fullscreen**: Show the story as-is, without padding + +### `options` + +Type: + +```ts +{ + storySort?: StorySortConfig | StorySortFn; + // TK - necessary? + theme?: { + base: string; + brandTitle?: string; + }; + [key: string]: any; +} +``` + +TK + +#### `options.storySort` + +Type: `StorySortConfig | StorySortFn` + +```ts +type StorySortConfig = { + includeNames?: boolean; + locales?: string; + method?: 'alphabetical' | 'alphabetical-by-kind' | 'custom'; + order?: string[]; +}; + +type Story = { + id: string; + importPath: string; + name: string; + title: string; +}; + +type StorySortFn = (a: Story, b: Story) => number; +``` + +TK + +--- + +All other parameters are contributed by addons. The [essential addon's](../addons/essentials.md) parameters are documented on their individual pages: + +- [Actions](../essentials/actions.md) +- [Backgrounds](../essentials/backgrounds.md) +- [Controls](../essentials/controls.md) +- [Highlight](../essentials/highlight.md) +- [Interactions](../essentials/interactions.md) +- [Measure & Outline](../essentials/measure-and-outline.md) +- [Toolbars & globals](../essentials/toolbars-and-globals.md) +- [Viewport](../essentials/viewport.md) + +## Parameter inheritance + +No matter where they're specified, parameters are ultimately applied to a single story. Parameters specified at the project (global) level are applied to every story in that project. Those specified at the meta (component) level are applied to every story associated with that meta. And parameters specified for a story only apply to that story. + +When specifying parameters, they are merged together in order of increasing specificity: + +1. Project (global) parameters +2. Meta (component) parameters +3. Story parameters + +
+ +ℹ️ Parameters are **merged**, so individual keys are always overwritten, never dropped. + +
+ +In other words, the following specifications of parameters: + +```js +// .storybook/preview.js|ts + +const preview = { + // 👇 Project-level parameters + parameters: { + layout: 'centered', + viewport: { + viewports: defaultViewports, + }, + }, + // ... +}; +export default preview; +``` + +```js +// Dialog.stories.js|ts + +const meta = { + component: Dialog, + // 👇 Meta-level parameters + parameters: { + layout: 'fullscreen', + viewport: { + defaultViewport: 'medium', + viewports: viewportsForDialog, + }, + }, +}; +export default meta; + +// (no additional parameters specified) +export const Basic = {}; + +export const LargeScreen = { + // 👇 Story-level parameters + parameters: { + layout: 'padded', + viewport: { + defaultViewport: 'large', + }, + }, +}; +``` + +Will result in the following parameter values applied to each story: + +```js +// For the Basic story: +{ + layout: 'fullscreen', + viewport: { + defaultViewport: 'medium', + viewports: viewportsForDialog, + }, +} + +// For the LargeScreen story: +{ + layout: 'padded', + viewport: { + defaultViewport: 'large', + viewports: viewportsForDialog, + }, +} +``` diff --git a/docs/snippets/common/parameters-in-meta.js.mdx b/docs/snippets/common/parameters-in-meta.js.mdx new file mode 100644 index 000000000000..0a0445d81d00 --- /dev/null +++ b/docs/snippets/common/parameters-in-meta.js.mdx @@ -0,0 +1,17 @@ +```js +// Button.stories.js|jsx + +import { Button } from './Button'; + +export default { + component: Button, + // 👇 Meta-level parameters + parameters: { + backgrounds: { + default: 'dark', + }, + }, +}; + +export const Basic = {}; +``` diff --git a/docs/snippets/common/parameters-in-meta.ts.mdx b/docs/snippets/common/parameters-in-meta.ts.mdx new file mode 100644 index 000000000000..3fa59ece6b13 --- /dev/null +++ b/docs/snippets/common/parameters-in-meta.ts.mdx @@ -0,0 +1,23 @@ +```ts +// Button.stories.ts|tsx + +// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) +import type { Meta, StoryObj } from '@storybook/your-framework'; + +import { Button } from './Button'; + +const meta: Meta = { + component: Button, + // 👇 Meta-level parameters + parameters: { + backgrounds: { + default: 'dark', + }, + }, +}; +export default meta; + +type Story = StoryObj; + +export const Basic: Story = {}; +``` diff --git a/docs/snippets/common/parameters-in-preview.js.mdx b/docs/snippets/common/parameters-in-preview.js.mdx new file mode 100644 index 000000000000..b52009c83bc5 --- /dev/null +++ b/docs/snippets/common/parameters-in-preview.js.mdx @@ -0,0 +1,14 @@ +```ts +// .storybook/preview.ts + +export default { + parameters: { + backgrounds: { + values: [ + { name: 'light', value: '#fff' }, + { name: 'dark', value: '#333' }, + ], + }, + }, +}; +``` diff --git a/docs/snippets/common/parameters-in-preview.ts.mdx b/docs/snippets/common/parameters-in-preview.ts.mdx new file mode 100644 index 000000000000..617507ef45a3 --- /dev/null +++ b/docs/snippets/common/parameters-in-preview.ts.mdx @@ -0,0 +1,19 @@ +```ts +// .storybook/preview.ts + +// Replace your-renderer with the renderer you are using (e.g., react, vue3) +import { Preview } from '@storybook/your-renderer'; + +const preview: Preview = { + parameters: { + backgrounds: { + values: [ + { name: 'light', value: '#fff' }, + { name: 'dark', value: '#333' }, + ], + }, + }, +}; + +export default preview; +``` diff --git a/docs/snippets/common/parameters-in-story.js.mdx b/docs/snippets/common/parameters-in-story.js.mdx new file mode 100644 index 000000000000..ccc9d880a134 --- /dev/null +++ b/docs/snippets/common/parameters-in-story.js.mdx @@ -0,0 +1,18 @@ +```js +// Button.stories.js|jsx + +import { Button } from './Button'; + +export default { + component: Button, +}; + +export const OnDark = { + // 👇 Story-level parameters + parameters: { + backgrounds: { + default: 'dark', + }, + }, +}; +``` diff --git a/docs/snippets/common/parameters-in-story.ts.mdx b/docs/snippets/common/parameters-in-story.ts.mdx new file mode 100644 index 000000000000..605f1cbf1b8d --- /dev/null +++ b/docs/snippets/common/parameters-in-story.ts.mdx @@ -0,0 +1,24 @@ +```ts +// Button.stories.ts|tsx + +// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) +import type { Meta, StoryObj } from '@storybook/your-framework'; + +import { Button } from './Button'; + +const meta: Meta = { + component: Button, +}; +export default meta; + +type Story = StoryObj; + +export const OnDark: Story = { + // 👇 Story-level parameters + parameters: { + backgrounds: { + default: 'dark', + }, + }, +}; +``` diff --git a/docs/toc.js b/docs/toc.js index 9c773a493244..74b4a7d88cb2 100644 --- a/docs/toc.js +++ b/docs/toc.js @@ -589,14 +589,19 @@ module.exports = { }, ], }, + { + pathSegment: 'csf', + title: 'Component Story Format (CSF)', + type: 'link', + }, { pathSegment: 'arg-types', title: 'ArgTypes', type: 'link', }, { - pathSegment: 'csf', - title: 'Component Story Format (CSF)', + pathSegment: 'parameters', + title: 'Parameters', type: 'link', }, {