From 8c231c5afadc156da864d1e748db803eff2e53ff Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Tue, 13 Jun 2023 08:33:20 -0600 Subject: [PATCH 1/8] Merge pull request #22970 from storybookjs/api-reference-arg-types Docs: Add ArgTypes API reference (cherry picked from commit e39cc9f47307aefe087adeaf012d192f69f38743) --- docs/api/arg-types.md | 500 ++++++++++++++++++ docs/api/argtypes.md | 216 -------- .../snippets/angular/arg-types-control.ts.mdx | 23 + .../angular/arg-types-default-value.ts.mdx | 23 + .../angular/arg-types-description.ts.mdx | 18 + docs/snippets/angular/arg-types-if.ts.mdx | 40 ++ .../snippets/angular/arg-types-in-meta.ts.mdx | 20 + ...types.ts.mdx => arg-types-in-story.ts.mdx} | 22 +- ...apping.ts.mdx => arg-types-mapping.ts.mdx} | 8 +- docs/snippets/angular/arg-types-name.ts.mdx | 18 + .../snippets/angular/arg-types-options.ts.mdx | 18 + docs/snippets/angular/arg-types-table.ts.mdx | 21 + docs/snippets/angular/arg-types-type.ts.mdx | 16 + docs/snippets/common/arg-types-control.js.mdx | 19 + .../common/arg-types-control.ts-4-9.mdx | 24 + docs/snippets/common/arg-types-control.ts.mdx | 24 + .../common/arg-types-default-value.js.mdx | 19 + .../common/arg-types-default-value.ts-4-9.mdx | 24 + .../common/arg-types-default-value.ts.mdx | 24 + .../common/arg-types-description.js.mdx | 14 + .../common/arg-types-description.ts-4-9.mdx | 19 + .../common/arg-types-description.ts.mdx | 19 + docs/snippets/common/arg-types-if.js.mdx | 36 ++ docs/snippets/common/arg-types-if.ts-4-9.mdx | 41 ++ docs/snippets/common/arg-types-if.ts.mdx | 41 ++ docs/snippets/common/arg-types-in-meta.js.mdx | 16 + .../common/arg-types-in-meta.ts-4-9.mdx | 21 + docs/snippets/common/arg-types-in-meta.ts.mdx | 21 + .../common/arg-types-in-preview.js.mdx | 13 + .../common/arg-types-in-preview.ts-4-9.mdx | 18 + .../common/arg-types-in-preview.ts.mdx | 18 + .../snippets/common/arg-types-in-story.js.mdx | 19 + .../common/arg-types-in-story.ts-4-9.mdx | 26 + .../snippets/common/arg-types-in-story.ts.mdx | 26 + ...apping.js.mdx => arg-types-mapping.js.mdx} | 6 +- .../common/arg-types-mapping.ts-4-9.mdx | 23 + docs/snippets/common/arg-types-mapping.ts.mdx | 23 + docs/snippets/common/arg-types-name.js.mdx | 14 + .../snippets/common/arg-types-name.ts-4-9.mdx | 19 + docs/snippets/common/arg-types-name.ts.mdx | 19 + docs/snippets/common/arg-types-options.js.mdx | 14 + .../common/arg-types-options.ts-4-9.mdx | 19 + docs/snippets/common/arg-types-options.ts.mdx | 19 + docs/snippets/common/arg-types-table.js.mdx | 17 + .../common/arg-types-table.ts-4-9.mdx | 22 + docs/snippets/common/arg-types-table.ts.mdx | 22 + docs/snippets/common/arg-types-type.js.mdx | 12 + .../snippets/common/arg-types-type.ts-4-9.mdx | 17 + docs/snippets/common/arg-types-type.ts.mdx | 17 + .../button-story-project-args-theme.js.mdx | 11 - .../button-story-project-args-theme.ts.mdx | 16 - ...component-argtypes-with-mapping.ts-4-9.mdx | 23 - .../my-component-argtypes-with-mapping.ts.mdx | 23 - .../storybook-customize-argtypes.js.mdx | 23 - .../storybook-customize-argtypes.ts-4-9.mdx | 28 - .../storybook-customize-argtypes.ts.mdx | 28 - .../web-components/arg-types-control.js.mdx | 17 + .../web-components/arg-types-control.ts.mdx | 21 + .../arg-types-default-value.js.mdx | 17 + .../arg-types-default-value.ts.mdx | 21 + .../arg-types-description.js.mdx | 12 + .../arg-types-description.ts.mdx | 16 + .../web-components/arg-types-if.js.mdx | 34 ++ .../web-components/arg-types-if.ts.mdx | 38 ++ .../web-components/arg-types-in-meta.js.mdx | 14 + .../web-components/arg-types-in-meta.ts.mdx | 18 + .../web-components/arg-types-in-story.js.mdx | 17 + .../web-components/arg-types-in-story.ts.mdx | 23 + ...apping.js.mdx => arg-types-mapping.js.mdx} | 4 +- ...apping.ts.mdx => arg-types-mapping.ts.mdx} | 4 +- .../web-components/arg-types-name.js.mdx | 12 + .../web-components/arg-types-name.ts.mdx | 16 + .../web-components/arg-types-options.js.mdx | 12 + .../web-components/arg-types-options.ts.mdx | 16 + .../web-components/arg-types-table.js.mdx | 15 + .../web-components/arg-types-table.ts.mdx | 19 + .../web-components/arg-types-type.js.mdx | 10 + .../web-components/arg-types-type.ts.mdx | 14 + .../storybook-customize-argtypes.js.mdx | 21 - .../storybook-customize-argtypes.ts.mdx | 25 - docs/toc.js | 27 +- docs/writing-stories/args.md | 10 +- 82 files changed, 1834 insertions(+), 459 deletions(-) create mode 100644 docs/api/arg-types.md delete mode 100644 docs/api/argtypes.md create mode 100644 docs/snippets/angular/arg-types-control.ts.mdx create mode 100644 docs/snippets/angular/arg-types-default-value.ts.mdx create mode 100644 docs/snippets/angular/arg-types-description.ts.mdx create mode 100644 docs/snippets/angular/arg-types-if.ts.mdx create mode 100644 docs/snippets/angular/arg-types-in-meta.ts.mdx rename docs/snippets/angular/{storybook-customize-argtypes.ts.mdx => arg-types-in-story.ts.mdx} (52%) rename docs/snippets/angular/{my-component-argtypes-with-mapping.ts.mdx => arg-types-mapping.ts.mdx} (65%) create mode 100644 docs/snippets/angular/arg-types-name.ts.mdx create mode 100644 docs/snippets/angular/arg-types-options.ts.mdx create mode 100644 docs/snippets/angular/arg-types-table.ts.mdx create mode 100644 docs/snippets/angular/arg-types-type.ts.mdx create mode 100644 docs/snippets/common/arg-types-control.js.mdx create mode 100644 docs/snippets/common/arg-types-control.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-control.ts.mdx create mode 100644 docs/snippets/common/arg-types-default-value.js.mdx create mode 100644 docs/snippets/common/arg-types-default-value.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-default-value.ts.mdx create mode 100644 docs/snippets/common/arg-types-description.js.mdx create mode 100644 docs/snippets/common/arg-types-description.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-description.ts.mdx create mode 100644 docs/snippets/common/arg-types-if.js.mdx create mode 100644 docs/snippets/common/arg-types-if.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-if.ts.mdx create mode 100644 docs/snippets/common/arg-types-in-meta.js.mdx create mode 100644 docs/snippets/common/arg-types-in-meta.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-in-meta.ts.mdx create mode 100644 docs/snippets/common/arg-types-in-preview.js.mdx create mode 100644 docs/snippets/common/arg-types-in-preview.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-in-preview.ts.mdx create mode 100644 docs/snippets/common/arg-types-in-story.js.mdx create mode 100644 docs/snippets/common/arg-types-in-story.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-in-story.ts.mdx rename docs/snippets/common/{my-component-argtypes-with-mapping.js.mdx => arg-types-mapping.js.mdx} (66%) create mode 100644 docs/snippets/common/arg-types-mapping.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-mapping.ts.mdx create mode 100644 docs/snippets/common/arg-types-name.js.mdx create mode 100644 docs/snippets/common/arg-types-name.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-name.ts.mdx create mode 100644 docs/snippets/common/arg-types-options.js.mdx create mode 100644 docs/snippets/common/arg-types-options.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-options.ts.mdx create mode 100644 docs/snippets/common/arg-types-table.js.mdx create mode 100644 docs/snippets/common/arg-types-table.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-table.ts.mdx create mode 100644 docs/snippets/common/arg-types-type.js.mdx create mode 100644 docs/snippets/common/arg-types-type.ts-4-9.mdx create mode 100644 docs/snippets/common/arg-types-type.ts.mdx delete mode 100644 docs/snippets/common/button-story-project-args-theme.js.mdx delete mode 100644 docs/snippets/common/button-story-project-args-theme.ts.mdx delete mode 100644 docs/snippets/common/my-component-argtypes-with-mapping.ts-4-9.mdx delete mode 100644 docs/snippets/common/my-component-argtypes-with-mapping.ts.mdx delete mode 100644 docs/snippets/common/storybook-customize-argtypes.js.mdx delete mode 100644 docs/snippets/common/storybook-customize-argtypes.ts-4-9.mdx delete mode 100644 docs/snippets/common/storybook-customize-argtypes.ts.mdx create mode 100644 docs/snippets/web-components/arg-types-control.js.mdx create mode 100644 docs/snippets/web-components/arg-types-control.ts.mdx create mode 100644 docs/snippets/web-components/arg-types-default-value.js.mdx create mode 100644 docs/snippets/web-components/arg-types-default-value.ts.mdx create mode 100644 docs/snippets/web-components/arg-types-description.js.mdx create mode 100644 docs/snippets/web-components/arg-types-description.ts.mdx create mode 100644 docs/snippets/web-components/arg-types-if.js.mdx create mode 100644 docs/snippets/web-components/arg-types-if.ts.mdx create mode 100644 docs/snippets/web-components/arg-types-in-meta.js.mdx create mode 100644 docs/snippets/web-components/arg-types-in-meta.ts.mdx create mode 100644 docs/snippets/web-components/arg-types-in-story.js.mdx create mode 100644 docs/snippets/web-components/arg-types-in-story.ts.mdx rename docs/snippets/web-components/{my-component-argtypes-with-mapping.js.mdx => arg-types-mapping.js.mdx} (80%) rename docs/snippets/web-components/{my-component-argtypes-with-mapping.ts.mdx => arg-types-mapping.ts.mdx} (84%) create mode 100644 docs/snippets/web-components/arg-types-name.js.mdx create mode 100644 docs/snippets/web-components/arg-types-name.ts.mdx create mode 100644 docs/snippets/web-components/arg-types-options.js.mdx create mode 100644 docs/snippets/web-components/arg-types-options.ts.mdx create mode 100644 docs/snippets/web-components/arg-types-table.js.mdx create mode 100644 docs/snippets/web-components/arg-types-table.ts.mdx create mode 100644 docs/snippets/web-components/arg-types-type.js.mdx create mode 100644 docs/snippets/web-components/arg-types-type.ts.mdx delete mode 100644 docs/snippets/web-components/storybook-customize-argtypes.js.mdx delete mode 100644 docs/snippets/web-components/storybook-customize-argtypes.ts.mdx diff --git a/docs/api/arg-types.md b/docs/api/arg-types.md new file mode 100644 index 000000000000..cff029e9fc32 --- /dev/null +++ b/docs/api/arg-types.md @@ -0,0 +1,500 @@ +--- +title: 'ArgTypes' +--- + +ArgTypes specify the behavior of [args](../writing-stories/args.md). By specifying the type of an arg, you constrain the values that it can accept and provide information about args that are not explicitly set (i.e., [description](#description)). + +You can also use argTypes to β€œannotate” args with information used by addons that make use of those args. For instance, to instruct the [controls addon](../essentials/controls.md) to render a color picker, you could specify the `'color'` [control type](#control). + +The most concrete realization of argTypes is the [`ArgTypes` doc block](./doc-block-argtypes.md) ([`Controls`](./doc-block-controls.md) is similar). Each row in the table corresponds to a single argType and the current value of that arg. + +![ArgTypes table](./doc-block-argtypes.png) + +## Automatic argType inference + +If you are using the Storybook [docs](../writing-docs/introduction.md) addon (installed by default as part of [essentials](../essentials/introduction.md)), then Storybook will infer a set of argTypes for each story based on the `component` specified in the [default export](../writing-stories/introduction#default-export) of the CSF file. + +To do so, Storybook uses various static analysis tools depending on your framework. + +| Framework | Static analysis tool | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| React | [react-docgen](https://github.com/reactjs/react-docgen) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript) | +| Vue | [vue-docgen-api](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api) | +| Angular | [compodoc](https://compodoc.app/) | +| WebComponents | [custom-element.json](https://github.com/webcomponents/custom-elements-json) | +| Ember | [YUI doc](https://github.com/ember-learn/ember-cli-addon-docs-yuidoc#documenting-components) | + +The data structure of `argTypes` is designed to match the output of the these tools. Properties specified manually will override what is inferred. + +## Manually specifying argTypes + +For most Storybook projects, argTypes are [automatically inferred](#automatic-argtype-inference) from your components. Any argTypes specified manually will override the inferred values. + +ArgTypes are most often specified at the meta (component) level, in the [default export](../writing-stories/introduction#default-export) of the CSF file: + + + + + + + +They can apply to all stories when specified at the project (global) level, in the `preview.js|ts` configuration file: + + + + + + + +Or they can apply only to a [specific story](../writing-stories/introduction#defining-stories): + + + + + + + +## `argTypes` + +Type: + +```ts +{ + [key: string]: { + control?: ControlType | { type: ControlType; /* See below for more */ }; + description?: string; + if?: Conditional; + mapping?: { [key: string]: { [option: string]: any } }; + name?: string; + options?: string[]; + table?: { + category?: string; + defaultValue?: { summary: string; detail?: string }; + subcategory?: string; + type?: { summary?: string; detail?: string }; + }, + type?: SBType | SBScalarType['name']; + } +} +``` + +You configure argTypes using an object with keys matching the name of args. The value of each key is an object with the following properties: + +### `control` + +Type: + +```ts +| ControlType +| { + type: ControlType, + accept?: string; + labels?: { [option: string]: string }; + max?: number; + min?: number; + presetColors?: string[]; + step?: number; + } +``` + +Default: + +1. `'select'`, if [`options`](#options) are specified +2. Else, inferred from [`type`](#type) +3. Else, `'object'` + +Specify the behavior of the [controls addon](../essentials/controls.md) for the arg. If you specify a string, it's used as the [`type`](#controltype) of the control. If you specify an object, you can provide additional configuration. + + + + + + + +#### `control.type` + +Type: `ControlType | null` + +Default: [Inferred](#automatic-argtype-inference); `'select'`, if [`options`](#options) are specified; falling back to `'object'` + +Specifies the type of control used to change the arg value with the [controls addon](../essentials/controls.md). Here are the available types, `ControlType`, grouped by the type of data they handle: + +| Data type | ControlType | Description | +| -------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **array** | `'object'` | Provides a JSON-based editor to handle the values of the array. Also allows editing in raw mode.
`{ control: 'object' }` | +| **boolean** | `'boolean'` | Provides a toggle for switching between possible states.
`{ control: 'boolean' }` | +| **enum** | `'check'` | Provides a set of stacked checkboxes for selecting multiple options.
`{ control: 'check', options: ['email', 'phone', 'mail'] }` | +| | `'inline-check'` | Provides a set of inlined checkboxes for selecting multiple options.
`{ control: 'inline-check', options: ['email', 'phone', 'mail'] }` | +| | `'radio'` | Provides a set of stacked radio buttons based on the available options.
`{ control: 'radio', options: ['email', 'phone', 'mail'] }` | +| | `'inline-radio'` | Provides a set of inlined radio buttons based on the available options.
`{ control: 'inline-radio', options: ['email', 'phone', 'mail'] }` | +| | `'select'` | Provides a select to choose a single value from the options.
`{ control: 'select', options: [20, 30, 40, 50] }` | +| | `'multi-select'` | Provides a select to choose multiple values from the options.
`{ control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] }` | +| **number** | `'number'` | Provides a numeric input to include the range of all possible values.
`{ control: { type: 'number', min:1, max:30, step: 2 } }` | +| | `'range'` | Provides a range slider to include all possible values.
`{ control: { type: 'range', min: 1, max: 30, step: 3 } }` | +| **object** | `'file'` | Provides a file input that returns an array of URLs. Can be further customized to accept specific file types.
`{ control: { type: 'file', accept: '.png' } }` | +| | `'object'` | Provides a JSON-based editor to handle the object's values. Also allows editing in raw mode.
`{ control: 'object' }` | +| **string** | `'color'` | Provides a color picker to choose color values. Can be additionally configured to include a set of color presets.
`{ control: { type: 'color', presetColors: ['red', 'green']} }` | +| | `'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. + +
+ +#### `control.accept` + +Type: `string` + +When `type` is `'file'`, you can specify the file types that are accepted. The value should be a string of comma-separated MIME types. + +#### `control.labels` + +Type: `{ [option: string]: string }` + +Map [`options`](#options) to labels. `labels` doesn't have to be exhaustive. If an option is not in the object's keys, it's used verbatim. + +#### `control.max` + +Type: `number` + +When `type` is `'number'` or `'range'`, sets the maximum allowed value. + +#### `control.min` + +Type: `number` + +When `type` is `'number'` or `'range'`, sets the minimum allowed value. + +#### `control.presetColors` + +Type: `string[]` + +When `type` is `'color'`, defines the set of colors that are available in addition to the general color picker. The values in the array should be valid CSS color values. + +#### `control.step` + +Type: `number` + +When `type` is `'number'` or `'range'`, sets the granularity allowed when incrementing/decrementing the value. + +### `description` + +Type: `string` + +Default: [Inferred](#automatic-argtype-inference) + +Describe the arg. (If you intend to describe the type of the arg, you should use [`table.type`](#tabletype), instead.) + + + + + + + +### `if` + +Type: + +```ts +{ + [predicateType: 'arg' | 'global']: string; + eq?: any; + exists?: boolean; + neq?: any; + truthy?: boolean; +} +``` + +Conditionally render an argType based on the value of another [arg](../writing-stories/args.md) or [global](../essentials/toolbars-and-globals.md). + + + + + + + +### `mapping` + +Type: `{ [key: string]: { [option: string]: any } }` + +Map [`options`](#options) to values. + +When dealing with non-primitive values, you'll notice that you'll run into some limitations. The most obvious issue is that not every value can be represented as part of the `args` param in the URL, losing the ability to share and deeplink to such a state. Beyond that, complex values such as JSX cannot be synchronized between the manager (e.g., Controls addon) and the preview (your story). + +`mapping` doesn't have to be exhaustive. If the currently selected option is not listed, it's used verbatim. Can be used with [`control.labels`](#labels). + + + + + + + +### `name` + +Type: `string` + +The `argTypes` object uses the name of the arg as the key. By default, that key is used when displaying the argType in Storybook. You can override the displayed name by specifying a `name` property. + + + + + + + +
+ +πŸ’‘ 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` + +Type: `string[]` + +Default: [Inferred](#automatic-argtype-inference) + +If the arg accepts a finite set of values, you can specify them with `options`. If those values are [complex](../essentials/controls#dealing-with-complex-values), like JSX elements, you can use [`mapping`](#mapping) to map them to string values. You can use [`control.labels`](#labels) to provide custom labels for the options. + + + + + + + +### `table` + +Type: + +```ts +{ + category?: string; + defaultValue?: { + detail?: string; + summary: string; + }; + subcategory?: string; + type?: { + detail?: string; + summary: string; + }; +} +``` + +Default: [Inferred](#automatic-argtype-inference) + +Specify how the arg is documented in the [`ArgTypes` doc block](./doc-block-argtypes.md), [`Controls` doc block](./doc-block-controls.md), and [Controls addon panel](../essentials/controls.md). + + + + + + + +#### `table.category` + +Type: `string` + +Default: [Inferred](#automatic-argtype-inference), in some frameworks + +Display the argType under a category heading, with the label specified by `category`. + +#### `table.defaultValue` + +Type: `{ detail?: string; summary: string }` + +Default: [Inferred](#automatic-argtype-inference) + +The documented default value of the argType. `summary` is typically used for the value itself, while `detail` is used for additional information. + +#### `table.subcategory` + +Type: `string` + +Display the argType under a subcategory heading (which displays under the [`category`] heading), with the label specified by `subcategory`. + +#### `table.type` + +Type: `{ detail?: string; summary: string }` + +Default: Inferred from [`type`](#type) + +The documented type of the argType. `summary` is typically used for the type itself, while `detail` is used for additional information. + +If you need to specify the actual, semantic type, you should use [`type`](#type), instead. + +### `type` + +Type: `'boolean' | 'function' | 'number' | 'string' | 'symbol' | SBType` + +The full type of `SBType` is: + +
+SBType + +```ts +interface SBBaseType { + required?: boolean; + raw?: string; +} + +type SBScalarType = SBBaseType & { + name: 'boolean' | 'string' | 'number' | 'function' | 'symbol'; +}; + +type SBArrayType = SBBaseType & { + name: 'array'; + value: SBType; +}; +type SBObjectType = SBBaseType & { + name: 'object'; + value: Record; +}; +type SBEnumType = SBBaseType & { + name: 'enum'; + value: (string | number)[]; +}; +type SBIntersectionType = SBBaseType & { + name: 'intersection'; + value: SBType[]; +}; +type SBUnionType = SBBaseType & { + name: 'union'; + value: SBType[]; +}; +type SBOtherType = SBBaseType & { + name: 'other'; + value: string; +}; + +type SBType = + | SBScalarType + | SBEnumType + | SBArrayType + | SBObjectType + | SBIntersectionType + | SBUnionType + | SBOtherType; +``` + +
+ +Default: [Inferred](#automatic-argtype-inference) + +Specifies the semantic type of the argType. When an argType is [inferred](#automatic-argtype-inference), the information from the various tools is summarized in this property, which is then used to infer other properties, like [`control`](#control) and [`table.type`](#tabletype). + +If you only need to specify the documented type, you should use [`table.type`](#tabletype), instead. + + + + + + + +### `defaultValue` (deprecated) + +Type: `any` + +Define the default value of the argType. Deprecated in favor of defining the [`arg`](../writing-stories/args.md) value directly. + + + + + + diff --git a/docs/api/argtypes.md b/docs/api/argtypes.md deleted file mode 100644 index da1c1927e683..000000000000 --- a/docs/api/argtypes.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: 'ArgTypes' ---- - -ArgTypes are a first-class feature in Storybook for specifying the behaviour of [Args](../writing-stories/args.md). By specifying the type of an arg, you constrain the values that it can take and provide information about args that are not explicitly set (i.e., not required). - -You can also use argTypes to β€œannotate” args with information used by addons that make use of those args. For instance, to instruct the controls addon to render a color, you could choose a string-valued arg. - -The most concrete realization of argTypes is the [`ArgTypes` doc block](./doc-block-argtypes.md) ([`Controls`](./doc-block-controls.md) is similar). Each row in the table corresponds to a single argType and the current value of that arg. - -![Storybook inferring automatically the argType](./doc-block-argtypes.png) - -## Automatic argType inference - -If you are using the Storybook [docs](../writing-docs/introduction.md) addon (installed by default as part of [essentials](../essentials/introduction.md)), then Storybook will infer a set of argTypes for each story based on the `component` specified in the [default export](./csf.md#default-export) of the CSF file. - -To do so, Storybook uses various static analysis tools depending on your framework. - -- React - - [react-docgen](https://github.com/reactjs/react-docgen) - - [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript) -- Vue - - [vue-docgen-api](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api) -- Angular - - [compodoc](https://compodoc.app/) -- WebComponents - - [custom-element.json](https://github.com/webcomponents/custom-elements-json) -- Ember - - [YUI doc](https://github.com/ember-learn/ember-cli-addon-docs-yuidoc#documenting-components) - -The format of the generated argType will look something like this: - - - - - - - -This ArgTypes data structure, name, type, defaultValue, and description are standard fields in all ArgTypes (analogous to PropTypes in React). The table and control fields are addon-specific annotations. So, for example, the table annotation provides extra information to customize how the label gets rendered, and the control annotation includes additional information for the control editing the property. - -## Manual specification - -If you want more control over the args table or any other aspect of using argTypes, you can overwrite the generated argTypes for your component on a per-arg basis. For instance, with the above-inferred argTypes and the following default export: - -
-πŸ’‘ As with other Storybook properties (e.g., args, decorators), you can also override ArgTypes per story basis. -
- - - - - - - -The `values.description`, `table.type`, and `controls.type` are merged into the defaults extracted by Storybook. The final merged values would be: - - - - - - - -In particular, this would render a row with a modified description, a type display with a dropdown that shows the detail, and no control. - -### Available properties - -Here's an explanation of each available property: - -| Property | Description | -| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | The name of the property.
`argTypes: { label: { name: 'Something' } }` | -| `type.name` | Sets a type for the property.
`argTypes: { label: { type: { name: 'number' } } }` | -| `type.required` | Sets the property as optional or required.
`argTypes: { label: { type: { required: true } }` | -| `description` | Sets a Markdown description for the property.
`argTypes: { label: { description: 'Something' } }` | -| `table.type.summary` | Provide a short version of the type.
`argTypes: { label: { table: { type: { summary: 'a short summary' } }}}` | -| `table.type.detail` | Provides an extended version of the type.
`argTypes: { label: { table: { type: { detail: 'something' } }}}` | -| `table.defaultValue.summary` | Provide a short version of the default value.
`argTypes: { label: { table: { defaultValue: { summary: 'Hello World' } }}}` | -| `table.defaultValue.detail` | Provides a longer version of the default value.
`argTypes: { label: { table: { defaultValue: { detail: 'Something' } }}}` | -| `control` | Associates a control for the property.
`argTypes: { label: { control: { type: 'text'} } }`
Read the [Essentials documentation](../essentials/controls.md) to learn more about controls. | - -#### Shorthands - -
- -πŸ’‘ The `@storybook/addon-docs` provide a shorthand for common tasks: - -- `type: 'number'` is shorthand for type: { name: 'number' } -- `control: 'radio'` is shorthand for control: { type: 'radio' } - -
- -### Grouping - -You can also manually specify groups to organize related `argTypes` into categories or even subcategories. Based on the following component implementation: - - - - - - - -You could group similar properties for better organization and structure. Using the table below as a reference: - -| Field | Category | -| :------------------ | :------: | -| **backgroundColor** | Colors | -| **primary** | Colors | -| **label** | Text | -| **onClick** | Events | -| **size** | Sizes | - -Results in the following change into your story and UI. - - - - - - - -![button story with args grouped into categories](./button-args-grouped-categories.png) - -You can also extend the formula above and introduce subcategories, allowing better structuring and organization. Using the table below as a reference leads to the following change to your story and UI: - -| Field | Category | Subcategory | -| :------------------ | :------: | :-------------: | -| **backgroundColor** | Colors | Button colors | -| **primary** | Colors | Button style | -| **label** | Text | Button contents | -| **onClick** | Events | Button Events | -| **size** | Sizes | | - - - - - - - -![button story with args grouped into categories](./button-args-grouped-subcategories.png) - -#### Global `argTypes` - -You can also define arg types at the global level; they will apply to every component's stories unless you overwrite them. To do so, export the `argTypes` key in your `preview.js`: - - - - - - - -
-πŸ’‘ If you define a global arg type for a story that does not have that arg (e.g. if there is no corresponding global arg definition), then the arg type will have no effect. -
- -#### Using argTypes in addons - -If you want to access the argTypes of the current component inside an addon, you can use the `useArgTypes` hook from the `@storybook/manager-api` package: - - - - - - diff --git a/docs/snippets/angular/arg-types-control.ts.mdx b/docs/snippets/angular/arg-types-control.ts.mdx new file mode 100644 index 000000000000..94f8365e086e --- /dev/null +++ b/docs/snippets/angular/arg-types-control.ts.mdx @@ -0,0 +1,23 @@ +```ts +// Example.stories.ts + +import type { Meta } from '@storybook/angular'; + +import { Example } from './Example'; + +const meta: Meta = { + component: Example, + argTypes: { + value: { + control: { + type: 'number', + min: 0, + max: 100, + step: 10, + }, + }, + }, +}; + +export default meta; +``` diff --git a/docs/snippets/angular/arg-types-default-value.ts.mdx b/docs/snippets/angular/arg-types-default-value.ts.mdx new file mode 100644 index 000000000000..41e3d3987501 --- /dev/null +++ b/docs/snippets/angular/arg-types-default-value.ts.mdx @@ -0,0 +1,23 @@ +```ts +// Example.stories.ts + +import type { Meta } from '@storybook/angular'; + +import { Example } from './Example'; + +const meta: Meta = { + component: Example, + argTypes: { + value: { + // ❌ Deprecated + defaultValue: 0, + }, + }, + // βœ… Do this instead + args: { + value: 0, + }, +}; + +export default meta; +``` diff --git a/docs/snippets/angular/arg-types-description.ts.mdx b/docs/snippets/angular/arg-types-description.ts.mdx new file mode 100644 index 000000000000..154c1b1f4a6b --- /dev/null +++ b/docs/snippets/angular/arg-types-description.ts.mdx @@ -0,0 +1,18 @@ +```ts +// Example.stories.ts + +import type { Meta } from '@storybook/angular'; + +import { Example } from './Example'; + +const meta: Meta = { + component: Example, + argTypes: { + value: { + description: 'The value of the slider', + }, + }, +}; + +export default meta; +``` diff --git a/docs/snippets/angular/arg-types-if.ts.mdx b/docs/snippets/angular/arg-types-if.ts.mdx new file mode 100644 index 000000000000..d1887b8bfbcd --- /dev/null +++ b/docs/snippets/angular/arg-types-if.ts.mdx @@ -0,0 +1,40 @@ +```ts +// Example.stories.ts + +import type { Meta } from '@storybook/angular'; + +import { Example } from './Example'; + +const meta: Meta = { + component: Example, + argTypes: { + parent: { control: 'select', options: ['one', 'two', 'three'] }, + + // πŸ‘‡ Only shown when `parent` arg exists + parentExists: { if: { arg: 'parent', exists: true } }, + + // πŸ‘‡ Only shown when `parent` arg does not exist + parentDoesNotExist: { if: { arg: 'parent', exists: false } }, + + // πŸ‘‡ Only shown when `parent` arg value is truthy + parentIsTruthy: { if: { arg: 'parent' } }, + parentIsTruthyVerbose: { if: { arg: 'parent', truthy: true } }, + + // πŸ‘‡ Only shown when `parent` arg value is not truthy + parentIsNotTruthy: { if: { arg: 'parent', truthy: false } }, + + // πŸ‘‡ Only shown when `parent` arg value is 'three' + parentIsEqToValue: { if: { arg: 'parent', eq: 'three' } }, + + // πŸ‘‡ Only shown when `parent` arg value is not 'three' + parentIsNotEqToValue: { if: { arg: 'parent', neq: 'three' } }, + + // Each of the above can also be conditional on the value of a globalType, e.g.: + + // πŸ‘‡ Only shown when `theme` global exists + parentExists: { if: { global: 'theme', exists: true } }, + }, +}; + +export default meta; +``` diff --git a/docs/snippets/angular/arg-types-in-meta.ts.mdx b/docs/snippets/angular/arg-types-in-meta.ts.mdx new file mode 100644 index 000000000000..1cc7933b518a --- /dev/null +++ b/docs/snippets/angular/arg-types-in-meta.ts.mdx @@ -0,0 +1,20 @@ +```ts +// Button.stories.ts + +import type { Meta } from '@storybook/angular'; + +import { Button } from './button.component'; + +const meta: Meta