From dd20d23757f0f87889bb89a2b9bf49ae85493db8 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Fri, 5 Jan 2024 16:54:47 -0700 Subject: [PATCH] Add Parameters API reference - Add API references for all essential addons - Consolidate related snippets --- docs/api/doc-block-canvas.md | 4 +- docs/api/index.md | 6 + docs/api/parameters.md | 247 ++++++++++++++++++ docs/essentials/actions.md | 56 ++++ docs/essentials/backgrounds.md | 87 ++++++ docs/essentials/controls.md | 56 ++++ docs/essentials/highlight.md | 36 ++- docs/essentials/interactions.md | 14 + docs/essentials/measure-and-outline.md | 14 + docs/essentials/viewport.md | 136 +++++++--- .../addon-actions-action-function.ts.mdx | 17 ++ ...-args.ts.mdx => parameters-in-meta.ts.mdx} | 0 ...rams.ts.mdx => parameters-in-story.ts.mdx} | 6 +- .../addon-actions-action-function.js.mdx | 14 + .../addon-actions-action-function.ts-4-9.mdx | 18 ++ .../addon-actions-action-function.ts.mdx | 18 ++ .../component-story-custom-params.js.mdx | 25 -- .../component-story-custom-params.ts-4-9.mdx | 31 --- .../snippets/common/parameters-in-meta.js.mdx | 17 ++ .../common/parameters-in-meta.ts-4-9.mdx | 23 ++ .../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-4-9.mdx | 24 ++ ...rams.ts.mdx => parameters-in-story.ts.mdx} | 17 +- .../common/preview-story-custom-params.js.mdx | 14 - .../common/preview-story-custom-params.ts.mdx | 19 -- .../html/button-story-with-blue-args.js.mdx | 23 -- .../html/button-story-with-blue-args.ts.mdx | 27 -- .../react/button-story-with-blue-args.js.mdx | 19 -- .../button-story-with-blue-args.ts-4-9.mdx | 23 -- .../react/button-story-with-blue-args.ts.mdx | 23 -- .../solid/button-story-with-blue-args.js.mdx | 19 -- .../button-story-with-blue-args.ts-4-9.mdx | 23 -- .../solid/button-story-with-blue-args.ts.mdx | 23 -- .../svelte/button-story-with-blue-args.js.mdx | 19 -- ...ton-story-with-blue-args.native-format.mdx | 13 - .../button-story-with-blue-args.ts-4-9.mdx | 23 -- .../svelte/button-story-with-blue-args.ts.mdx | 23 -- .../vue/button-story-with-blue-args.js.mdx | 19 -- .../button-story-with-blue-args.ts-4-9.mdx | 24 -- .../vue/button-story-with-blue-args.ts.mdx | 24 -- .../addon-actions-action-function.js.mdx | 12 + .../addon-actions-action-function.ts.mdx | 15 ++ ...-args.js.mdx => parameters-in-meta.js.mdx} | 0 ...-args.ts.mdx => parameters-in-meta.ts.mdx} | 0 ...rams.js.mdx => parameters-in-story.js.mdx} | 0 ...rams.ts.mdx => parameters-in-story.ts.mdx} | 0 docs/toc.js | 9 +- docs/writing-stories/index.md | 18 +- docs/writing-stories/parameters.md | 30 +-- 52 files changed, 882 insertions(+), 500 deletions(-) create mode 100644 docs/api/parameters.md create mode 100644 docs/snippets/angular/addon-actions-action-function.ts.mdx rename docs/snippets/angular/{button-story-with-blue-args.ts.mdx => parameters-in-meta.ts.mdx} (100%) rename docs/snippets/angular/{component-story-custom-params.ts.mdx => parameters-in-story.ts.mdx} (80%) create mode 100644 docs/snippets/common/addon-actions-action-function.js.mdx create mode 100644 docs/snippets/common/addon-actions-action-function.ts-4-9.mdx create mode 100644 docs/snippets/common/addon-actions-action-function.ts.mdx delete mode 100644 docs/snippets/common/component-story-custom-params.js.mdx delete mode 100644 docs/snippets/common/component-story-custom-params.ts-4-9.mdx create mode 100644 docs/snippets/common/parameters-in-meta.js.mdx create mode 100644 docs/snippets/common/parameters-in-meta.ts-4-9.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-4-9.mdx rename docs/snippets/common/{component-story-custom-params.ts.mdx => parameters-in-story.ts.mdx} (51%) delete mode 100644 docs/snippets/common/preview-story-custom-params.js.mdx delete mode 100644 docs/snippets/common/preview-story-custom-params.ts.mdx delete mode 100644 docs/snippets/html/button-story-with-blue-args.js.mdx delete mode 100644 docs/snippets/html/button-story-with-blue-args.ts.mdx delete mode 100644 docs/snippets/react/button-story-with-blue-args.js.mdx delete mode 100644 docs/snippets/react/button-story-with-blue-args.ts-4-9.mdx delete mode 100644 docs/snippets/react/button-story-with-blue-args.ts.mdx delete mode 100644 docs/snippets/solid/button-story-with-blue-args.js.mdx delete mode 100644 docs/snippets/solid/button-story-with-blue-args.ts-4-9.mdx delete mode 100644 docs/snippets/solid/button-story-with-blue-args.ts.mdx delete mode 100644 docs/snippets/svelte/button-story-with-blue-args.js.mdx delete mode 100644 docs/snippets/svelte/button-story-with-blue-args.native-format.mdx delete mode 100644 docs/snippets/svelte/button-story-with-blue-args.ts-4-9.mdx delete mode 100644 docs/snippets/svelte/button-story-with-blue-args.ts.mdx delete mode 100644 docs/snippets/vue/button-story-with-blue-args.js.mdx delete mode 100644 docs/snippets/vue/button-story-with-blue-args.ts-4-9.mdx delete mode 100644 docs/snippets/vue/button-story-with-blue-args.ts.mdx create mode 100644 docs/snippets/web-components/addon-actions-action-function.js.mdx create mode 100644 docs/snippets/web-components/addon-actions-action-function.ts.mdx rename docs/snippets/web-components/{button-story-with-blue-args.js.mdx => parameters-in-meta.js.mdx} (100%) rename docs/snippets/web-components/{button-story-with-blue-args.ts.mdx => parameters-in-meta.ts.mdx} (100%) rename docs/snippets/web-components/{component-story-custom-params.js.mdx => parameters-in-story.js.mdx} (100%) rename docs/snippets/web-components/{component-story-custom-params.ts.mdx => parameters-in-story.ts.mdx} (100%) diff --git a/docs/api/doc-block-canvas.md b/docs/api/doc-block-canvas.md index 8c40eadd6bd1..f0702461e402 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/index.md b/docs/api/index.md index e49768d52a69..168f0d0456a4 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -79,6 +79,12 @@ An overview of all available API references for Storybook. about args that are not explicitly set. + + Parameters + + Parameters are static metadata used to configure your stories addons in Storybook. They are specified at the story, meta (component), project (global) levels. + + diff --git a/docs/api/parameters.md b/docs/api/parameters.md new file mode 100644 index 000000000000..53174e387492 --- /dev/null +++ b/docs/api/parameters.md @@ -0,0 +1,247 @@ +--- +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 [lay out the story](../configure/story-layout.md). + +- **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; +} +``` + + + +The `options` parameter can _only_ be applied at the [project level](#project-parameters). + + + +#### `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; +``` + +Specifies the order in which stories are displayed in the Storybook UI. + +When specifying a configuration object, the following options are available: + +- **includeNames**: Whether to include the story name in the sorting algorithm. Defaults to `false`. +- **locales**: The locale to use when sorting stories. Defaults to your system locale. +- **method**: The sorting method to use. Defaults to `alphabetical`. + - **alphabetical**: Sort stories alphabetically by name. + - **alphabetical-by-kind**: Sort stories alphabetically by kind, then by name. + - **custom**: Use a custom sorting function. +- **order**: Stories in the specified order will be displayed first, in the order specified. All other stories will be displayed after, in alphabetical order. The order array can accept a nested array to sort 2nd-level story kinds, e.g. `['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components']`. + +When specifying a custom sorting function, the function behaves like a typical JavaScript sorting function. It accepts two stories to compare and returns a number. For example: + +```js +(a, b) => (a.id === b.id ? 0 : a.id.localeCompare(b.id, undefined, { numeric: true })); +``` + +See [the guide](../writing-stories/naming-components-and-hierarchy/#sorting-stories) for usage examples. + +--- + +### Essential addons + +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#parameters) +- [Backgrounds](../essentials/backgrounds.md#parameters) +- [Controls](../essentials/controls.md#parameters) +- [Highlight](../essentials/highlight.md#parameters) +- [Interactions](../essentials/interactions.md#parameters) +- [Measure & Outline](../essentials/measure-and-outline.md#parameters) +- [Viewport](../essentials/viewport.md#parameters) + +## 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 objects are deep-merged, but arrays and other properties are overwritten. + +
+ +In other words, the following specifications of parameters: + +```js +// .storybook/preview.js|ts + +const preview = { + // 👇 Project-level parameters + parameters: { + layout: 'centered', + demo: { + demoProperty: 'a', + demoArray: [1, 2], + }, + }, + // ... +}; +export default preview; +``` + +```js +// Dialog.stories.js|ts + +const meta = { + component: Dialog, + // 👇 Meta-level parameters + parameters: { + layout: 'fullscreen', + demo: { + demoProperty: 'b', + anotherDemoProperty: 'b', + }, + }, +}; +export default meta; + +// (no additional parameters specified) +export const Basic = {}; + +export const LargeScreen = { + // 👇 Story-level parameters + parameters: { + layout: 'padded', + demo: { + demoArray: [3, 4], + }, + }, +}; +``` + +Will result in the following parameter values applied to each story: + +```js +// Applied story parameters + +// For the Basic story: +{ + layout: 'fullscreen', + demo: { + demoProperty: 'b', + anotherDemoProperty: 'b', + demoArray: [1, 2], + }, +} + +// For the LargeScreen story: +{ + layout: 'padded', + demo: { + demoProperty: 'b', + anotherDemoProperty: 'b', + demoArray: [3, 4], + }, +} +``` diff --git a/docs/essentials/actions.md b/docs/essentials/actions.md index 99f56c1d7905..f3b22db33230 100644 --- a/docs/essentials/actions.md +++ b/docs/essentials/actions.md @@ -97,6 +97,62 @@ It is also possible to detect if your component is emitting the correct HTML eve This will bind a standard HTML event handler to the outermost HTML element rendered by your component and trigger an action when the event is called for a given selector. The format is ` `. The selector is optional; it defaults to all elements. +## API + +### Parameters + +This addon contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `actions` namespace: + +#### `argTypesRegex` + +Type: `string` + +Create actions for each arg that matches the regex. Please note the significant [limitations of this approach](#automatically-matching-args), as described above. + +#### `disable` + +Type: `boolean` + +Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.md#disabling-addons) for more information. + +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 then be re-enabled by setting it to `false` at the meta (component) or story level. + +#### `handles` + +Type: `string[]` + +Binds a standard HTML event handler to the outermost HTML element rendered by your component and triggers an action when the event is called for a given selector. The format is ` `. The selector is optional; it defaults to all elements. + +See the [action event handlers](#action-event-handlers) section, above, for more information. + +### Exports + +This addon contributes the following exports to Storybook: + +```js +import { action } from '@storybook/addon-actions'; +``` + +#### `action` + +Type: `(name?: string) => void` + +Allows you to create an action that appears in the actions panel of the Storybook UI when clicked. The action function takes an optional name parameter, which is used to identify the action in the UI. + + + + + + + ## Advanced / legacy usage There are also some older ways to use actions as documented in the [advanced README](../../addons/actions/ADVANCED.md). diff --git a/docs/essentials/backgrounds.md b/docs/essentials/backgrounds.md index 3c295a12b360..c1a51bc9aab4 100644 --- a/docs/essentials/backgrounds.md +++ b/docs/essentials/backgrounds.md @@ -125,3 +125,90 @@ If you need to disable the grid for a specific story, set the `backgrounds` para /> + +## API + +### Parameters + +This addon contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `backgrounds` namespace: + +#### `default` + +Type: `string` + +Default background color. Must match the `name` property of one of the [available colors](#values). + +#### `disable` + +Type: `boolean` + +Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.md#disabling-addons) for more information. + +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 then be re-enabled by setting it to `false` at the meta (component) or story level. + +#### `grid` + +Type: + +```ts +{ + cellAmount?: number; + cellSize?: number; + disable?: boolean; + offsetX: number; + offsetY: number; + opacity?: number; +} +``` + +##### `grid.cellAmount` + +Type: `number` + +Default: `5` + +Specify the size of the minor grid lines. + +##### `grid.cellSize` + +Type: `number` + +Default: `20` + +Specify the size of the major grid lines. + +##### `grid.disable` + +Type: `boolean` + +Disable the grid. + +##### `grid.offsetX` + +Type: `number` + +Default: `0` if [story layout](../api/parameters.md#layout) is `'fullscreen'`; `16` if story layout is `'padded'` + +Horizontal offset of the grid. + +##### `grid.offsetY` + +Type: `number` + +Default: `0` if [story layout](../api/parameters.md#layout) is `'fullscreen'`; `16` if story layout is `'padded'` + +Vertical offset of the grid. + +##### `grid.opacity` + +Type: `number` + +Default: `0.5` + +Opacity of the grid lines. + +#### `values` + +Type: `{ name: string; value: string }[]` + +Available background colors. See above for a [usage example](#configuration). diff --git a/docs/essentials/controls.md b/docs/essentials/controls.md index 5d86420c4ab0..51d27d976687 100644 --- a/docs/essentials/controls.md +++ b/docs/essentials/controls.md @@ -647,3 +647,59 @@ Enabling this feature will generate a `storybook-docgen/index.json` automaticall + +## API + +### Parameters + +This addon contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `controls` namespace: + +#### `disable` + +Type: `boolean` + +Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.md#disabling-addons) for more information. + +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 then be re-enabled by setting it to `false` at the meta (component) or story level. + +#### `exclude` + +Type: `string[] | RegExp` + +Specifies which properties to exclude from the Controls addon panel. Any properties whose names match the regex or are part of the array will be left out. See [usage example](#filtering-controls), above. + +#### `expanded` + +Type: `boolean` + +Show the full documentation, including description and default value, for each property in the Controls addon panel. See [usage example](#show-full-documentation-for-each-property), above. + +#### `hideNoControlsWarning` + +Type: `boolean` + +Hide the warning that appears when no controls are defined for a story. See [usage example](#hide-nocontrols-warning), above. + +#### `include` + +Type: `string[] | RegExp` + +Specifies which properties to include in the Controls addon panel. Any properties whose names don't match the regex or are not part of the array will be left out. See [usage example](#filtering-controls), above. + +#### `presetColors` + +Type: `(string | { color: string; title?: string })[]` + +Specify preset color swatches for the color picker control. Color value many be any valid CSS color. See [usage example](#specify-initial-preset-color-swatches), above. + +#### `sort` + +Type: `'none' | 'alpha' | 'requiredFirst'` + +Default: `'none'` + +Specifies how the controls are sorted. + +- **none**: Unsorted, displayed in the same order the arg types are processed in +- **alpha**: Sorted alphabetically, by the arg type's name +- **requiredFirst**: Same as `alpha`, with any required arg types displayed first diff --git a/docs/essentials/highlight.md b/docs/essentials/highlight.md index 0968be5d36cc..6a266a2d0a02 100644 --- a/docs/essentials/highlight.md +++ b/docs/essentials/highlight.md @@ -76,4 +76,38 @@ By default, the addon applies a standard style to the highlighted elements you'v ]} /> - \ No newline at end of file + + +## API + +### Parameters + +This addon contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `highlight` namespace: + +#### `disable` + +Type: `boolean` + +Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.md#disabling-addons) for more information. + +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 then be re-enabled by setting it to `false` at the meta (component) or story level. + +### Exports + +This addon contributes the following exports to Storybook: + +```js +import { HIGHLIGHT, RESET_HIGHLIGHT } from '@storybook/addon-highlight'; +``` + +#### `HIGHLIGHT` + +Type: `string` + +An event that highlights DOM elements. The event payload must contain an `elements` property assigned to an array of selectors matching the elements you want to highlight. See the [usage example](#highlighting-dom-elements), above. + +#### `RESET_HIGHLIGHT` + +Type: `string` + +An event to clear all highlights from highlighted elements. See the [usage example](#reset-highlighted-elements), above. diff --git a/docs/essentials/interactions.md b/docs/essentials/interactions.md index dc86f7b94f9a..47554e2b70fd 100644 --- a/docs/essentials/interactions.md +++ b/docs/essentials/interactions.md @@ -88,3 +88,17 @@ Any `args` that have been marked as an Action, either using the [argTypes annota 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. + +## API + +### Parameters + +This addon contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `interactions` namespace: + +#### `disable` + +Type: `boolean` + +Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.md#disabling-addons) for more information. + +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 then be re-enabled by setting it to `false` at the meta (component) or story level. diff --git a/docs/essentials/measure-and-outline.md b/docs/essentials/measure-and-outline.md index 277e9ee4c164..883c9ac90a39 100644 --- a/docs/essentials/measure-and-outline.md +++ b/docs/essentials/measure-and-outline.md @@ -31,3 +31,17 @@ With Storybook's Outline addon, you can toggle the outlines associated with all + +## API + +### Parameters + +This addon contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `measure` or `outline` namespace: + +#### `disable` + +Type: `boolean` + +Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.md#disabling-addons) for more information. + +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 then be re-enabled by setting it to `false` at the meta (component) or story level. diff --git a/docs/essentials/viewport.md b/docs/essentials/viewport.md index 99a34875da31..b601ad531c7e 100644 --- a/docs/essentials/viewport.md +++ b/docs/essentials/viewport.md @@ -49,39 +49,39 @@ The viewports object needs the following keys: The Viewport addon includes a selection of devices that you can use to test your components. Listed below are the available devices and examples of how to use them. -| Device | Description | Dimensions (px) | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | -| iPhone 5 | Configures the iPhone 5 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone5', }},` | Width: 320, Height: 568 | -| iPhone 6 | Enables the iPhone 6 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone6', }},` | Width: 375, Height: 667 | -| iPhone 6 Plus | Includes the iPhone 6 Plus as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone6p', }},` | Width: 414, Height: 736 | -| iPhone 8 Plus | Sets the iPhone 8 Plus as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone8p', }},` | Width: 414, Height: 736 | -| iPhone X | Configures the iPhone X as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonex', }},` | Width: 375, Height: 812 | -| iPhone XR | Includes the iPhone XR as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonexr', }},` | Width: 414, Height: 896 | -| iPhone XS Max | Sets the iPhone XS Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonexsmax', }},` | Width: 414, Height: 896 | -| iPhone SE (2nd generation) | Configures the iPhone SE (2nd generation) as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonese2', }},` | Width: 375, Height: 667 | -| iPhone 12 mini | Enables the iPhone 12 Mini to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12mini', }},` | Width: 375, Height: 812 | -| iPhone 12 | Includes the iPhone 12 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12', }},` | Width: 390, Height: 844 | -| iPhone 12 Pro Max | Configures the iPhone 12 Pro Max as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12promax', }},` | Width: 428, Height: 926 | -| iPhone SE 3rd generation | Enables the iPhone SE (3rd generation) to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphoneSE3', }},` | Width: 375, Height: 667 | -| iPhone 13 | Includes the iPhone 13 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13', }},` | Width: 390, Height: 844 | -| iPhone 13 Pro | Enables the iPhone 13 Pro to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13pro', }},` | Width: 390, Height: 844 | -| iPhone 13 Pro Max | Configures the iPhone 13 Pro Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13promax', }},` | Width: 428, Height: 926 | -| iPhone 14 | Enables the iPhone 14 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14', }},` | Width: 390, Height: 844 | -| iPhone 14 Pro | Includes the iPhone 14 Pro as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14pro', }},` | Width: 393, Height: 852 | -| iPhone 14 Pro Max | Sets the iPhone 14 Pro Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14promax', }},` | Width: 430, Height: 932 | -| Galaxy S5 | Configures the Galaxy S5 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'galaxys5', }},` | Width: 360, Height: 640 | -| Galaxy S9 | Enables the Galaxy S9 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'galaxys9', }},` | Width: 360, Height: 740 | -| Nexus 5X | Includes the Nexus 5x as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'nexus5x', }},` | Width: 412, Height: 668 | -| Nexus 6P | Sets the Nexus 6P as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'nexus6p', }},` | Width: 412, Height: 732 | -| Pixel | Configures the Pixel as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'pixel', }},` | Width: 540, Height: 960 | -| Pixel XL | Enables the Pixel XL to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'pixelxl', }},` | Width: 720, Height: 1280 | -| Small mobile | Enabled by default.
Configures a small form factor generic mobile device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'mobile1', }},` | Width: 320, Height: 568 | -| Large mobile | Enabled by default.
Configures a large form factor mobile device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'mobile2', }},` | Width: 414, Height: 896 | -| iPad | Includes the iPad as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad', }},` | Width: 768, Height: 1024 | -| iPad Pro 10.5-in | Enables the iPad Pro (10.5-inch) to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad10p', }},` | Width: 834, Height: 112 | -| iPad Pro 11-in | Configures the iPad Pro (11-inch) as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad11p', }},` | Width: 834, Height: 1194 | -| iPad Pro 12.9-in | Sets the iPad Pro (12.9-inch) as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad12p', }},` | Width: 1024, Height: 1366 | -| Tablet | Enabled by default.
Configures a standard form factor tablet device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'tablet', }},` | Width: 834, Height: 1112 | +| Device | Description | Dimensions
(w×h, px) | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| iPhone 5 | Configures the iPhone 5 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone5', }},` | 320 × 568 | +| iPhone 6 | Enables the iPhone 6 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone6', }},` | 375 × 667 | +| iPhone 6 Plus | Includes the iPhone 6 Plus as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone6p', }},` | 414 × 736 | +| iPhone 8 Plus | Sets the iPhone 8 Plus as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone8p', }},` | 414 × 736 | +| iPhone X | Configures the iPhone X as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonex', }},` | 375 × 812 | +| iPhone XR | Includes the iPhone XR as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonexr', }},` | 414 × 896 | +| iPhone XS Max | Sets the iPhone XS Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonexsmax', }},` | 414 × 896 | +| iPhone SE (2nd generation) | Configures the iPhone SE (2nd generation) as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonese2', }},` | 375 × 667 | +| iPhone 12 mini | Enables the iPhone 12 Mini to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12mini', }},` | 375 × 812 | +| iPhone 12 | Includes the iPhone 12 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12', }},` | 390 × 844 | +| iPhone 12 Pro Max | Configures the iPhone 12 Pro Max as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12promax', }},` | 428 × 926 | +| iPhone SE 3rd generation | Enables the iPhone SE (3rd generation) to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphoneSE3', }},` | 375 × 667 | +| iPhone 13 | Includes the iPhone 13 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13', }},` | 390 × 844 | +| iPhone 13 Pro | Enables the iPhone 13 Pro to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13pro', }},` | 390 × 844 | +| iPhone 13 Pro Max | Configures the iPhone 13 Pro Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13promax', }},` | 428 × 926 | +| iPhone 14 | Enables the iPhone 14 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14', }},` | 390 × 844 | +| iPhone 14 Pro | Includes the iPhone 14 Pro as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14pro', }},` | 393 × 852 | +| iPhone 14 Pro Max | Sets the iPhone 14 Pro Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14promax', }},` | 430 × 932 | +| Galaxy S5 | Configures the Galaxy S5 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'galaxys5', }},` | 360 × 640 | +| Galaxy S9 | Enables the Galaxy S9 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'galaxys9', }},` | 360 × 740 | +| Nexus 5X | Includes the Nexus 5x as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'nexus5x', }},` | 412 × 668 | +| Nexus 6P | Sets the Nexus 6P as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'nexus6p', }},` | 412 × 732 | +| Pixel | Configures the Pixel as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'pixel', }},` | 540 × 960 | +| Pixel XL | Enables the Pixel XL to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'pixelxl', }},` | 720 × 1280 | +| Small mobile | Enabled by default.
Configures a small form factor generic mobile device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'mobile1', }},` | 320 × 568 | +| Large mobile | Enabled by default.
Configures a large form factor mobile device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'mobile2', }},` | 414 × 896 | +| iPad | Includes the iPad as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad', }},` | 768 × 1024 | +| iPad Pro 10.5-in | Enables the iPad Pro (10.5-inch) to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad10p', }},` | 834 × 112 | +| iPad Pro 11-in | Configures the iPad Pro (11-inch) as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad11p', }},` | 834 × 1194 | +| iPad Pro 12.9-in | Sets the iPad Pro (12.9-inch) as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad12p', }},` | 1024 × 1366 | +| Tablet | Enabled by default.
Configures a standard form factor tablet device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'tablet', }},` | 834 × 1112 | @@ -181,3 +181,73 @@ Update your story through [parameters](../writing-stories/parameters.md) to incl - Reset viewport: alt + v If you need, you can edit them on the shortcuts page. + +## API + +### Parameters + +This addon contributes the following [parameters](../writing-stories/parameters.md) to Storybook, under the `viewport` namespace: + +#### `defaultOrientation` + +Type: `'portrait' | 'landscape'` + +Default: `'portrait'` + +Specifies the default orientation used when viewing a story. + +#### `defaultViewport` + +Type: `string` + +Specifies the default viewport used when viewing a story. Must match a key in the [`viewports`](#viewports) object. + +#### `disable` + +Type: `boolean` + +Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.md#disabling-addons) for more information. + +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 then 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. 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 + +This addon contributes the following exports to Storybook: + +```js +import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from '@storybook/addon-viewports'; +``` + +#### `INITIAL_VIEWPORTS` + +Type: `object` + +The default set of viewports provided by the Viewport addon, [listed above](#use-a-detailed-set-of-devices). + +#### `MINIMAL_VIEWPORTS` + +Type: `object` + +A minimal set of viewports provided by the Viewport addon, listed below: + +| Device | Description | Dimensions
(w×h, px) | +| ------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| Small mobile | A small mobile device size
`parameters: { viewport: { defaultViewport: 'mobile1', }},` | 320 × 568 | +| Large mobile | A large mobile device size
`parameters: { viewport: { defaultViewport: 'mobile2', }},` | 414 × 896 | +| Tablet | A tablet device size
`parameters: { viewport: { defaultViewport: 'tablet', }},` | 834 × 1112 | diff --git a/docs/snippets/angular/addon-actions-action-function.ts.mdx b/docs/snippets/angular/addon-actions-action-function.ts.mdx new file mode 100644 index 000000000000..49506c07f517 --- /dev/null +++ b/docs/snippets/angular/addon-actions-action-function.ts.mdx @@ -0,0 +1,17 @@ +```ts +// Button.stories.ts +import type { Meta } from '@storybook/angular'; +import { action } from '@storybook/addon-actions'; + +import Button from './button.component'; + +const meta: Meta