Merge pull request #21113 from storybookjs/doc-blocks-docs

code/addons/docs/docs/multiframework.md

@@ -106,7 +106,7 @@ The input is the story function and the story context (id, parameters, args, etc
 
 ## Dynamic source rendering
 
-With the release of Storybook 6.0, we've improved how stories are rendered in the [Source doc block](https://storybook.js.org/docs/react/writing-docs/doc-blocks#source). One of such improvements is the `dynamic` source type, which renders a snippet based on the output the story function.
+With the release of Storybook 6.0, we've improved how stories are rendered in the [`Source` doc block](https://storybook.js.org/docs/7.0/react/api/doc-block-source). One of such improvements is the `dynamic` source type, which renders a snippet based on the output the story function.
 
 This dynamic rendering is framework-specific, meaning it needs a custom implementation for each framework.
 

docs/api/argtypes.md

@@ -12,9 +12,9 @@ ArgTypes are a first-class feature in Storybook for specifying the behaviour of
 
 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 [Args Table](../writing-docs/doc-block-argstable.md) doc block. Each row in the table corresponds to a single argType and the current value of that 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](./argstable.png)
+![Storybook inferring automatically the argType](./doc-block-argtypes.png)
 
 ## Automatic argType inference
 
@@ -48,6 +48,56 @@ 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:
+
+<div class="aside">
+💡 As with other Storybook properties (e.g., args, decorators), you can also override ArgTypes per story basis.
+</div>
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-customize-argtypes.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+The `values.description`, `table.type`, and `controls.type` are merged into the defaults extracted by Storybook. The final merged values would be:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-merged-argtypes.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+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. <br/> `argTypes: { label: { name: 'Something' } }`                                                                                                                       |
+| `type.name`                  | Sets a type for the property. <br/> `argTypes: { label: { type: { name: 'number' } } }`                                                                                                            |
+| `type.required`              | Sets the property as optional or required. <br/> `argTypes: { label: { type: { required: true } }`                                                                                                 |
+| `description`                | Sets a Markdown description for the property. <br/> `argTypes: { label: { description: 'Something' } }`                                                                                            |
+| `table.type.summary`         | Provide a short version of the type. <br/> `argTypes: { label: { table: { type: { summary: 'a short summary' } }}}`                                                                                |
+| `table.type.detail`          | Provides an extended version of the type. <br/> `argTypes: { label: { table: { type: { detail: 'something' } }}}`                                                                                  |
+| `table.defaultValue.summary` | Provide a short version of the default value. <br/> `argTypes: { label: { table: { defaultValue: { summary: 'Hello World' } }}}`                                                                   |
+| `table.defaultValue.detail`  | Provides a longer version of the default value. <br/> `argTypes: { label: { table: { defaultValue: { detail: 'Something' } }}}`                                                                    |
+| `control`                    | Associates a control for the property. <br/> `argTypes: { label: { control: { type: 'text'} } }` <br/>Read the [Essentials documentation](../essentials/controls.md) to learn more about controls. |
+
+#### Shorthands
+
 <div class="aside">
 
 💡 The `@storybook/addon-docs` provide a shorthand for common tasks:
@@ -57,37 +107,74 @@ This ArgTypes data structure, name, type, defaultValue, and description are stan
 
 </div>
 
-#### Manual specification
+### Grouping
 
-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:
+You can also manually specify groups to organize related `argTypes` into categories or even subcategories. Based on the following component implementation:
 
 <!-- prettier-ignore-start -->
 
 <CodeSnippets
   paths={[
-    'common/storybook-customize-argtypes.js.mdx',
+    'react/button-implementation.js.mdx',
+    'react/button-implementation.ts.mdx',
+    'angular/button-implementation.ts.mdx',
+    'vue/button-implementation.2.js.mdx',
+    'vue/button-implementation.ts-2.ts.mdx',
+    'vue/button-implementation.3.js.mdx',
+    'vue/button-implementation.ts-3.ts.mdx',
+    'svelte/button-implementation.js.mdx',
+    'web-components/button-implementation.js.mdx',
+    'web-components/button-implementation.ts.mdx',
   ]}
 />
 
 <!-- prettier-ignore-end -->
 
-The `values.description`, `table.type`, and `controls.type` are merged into the defaults extracted by Storybook. The final merged values would be:
+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.
 
 <!-- prettier-ignore-start -->
 
 <CodeSnippets
   paths={[
-    'common/storybook-merged-argtypes.js.mdx',
+    'common/button-story-argtypes-with-categories.js.mdx'
   ]}
 />
 
 <!-- prettier-ignore-end -->
 
-In particular, this would render a row with a modified description, a type display with a dropdown that shows the detail, and no control.
+![button story with args grouped into categories](./button-args-grouped-categories.png)
 
-<div class="aside">
-💡 As with other Storybook properties (e.g., args, decorators), you can also override ArgTypes per story basis.
-</div>
+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   |                 |
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/button-story-argtypes-with-subcategories.js.mdx'
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+![button story with args grouped into categories](./button-args-grouped-subcategories.png)
 
 #### Global `argTypes`
 

docs/api/doc-block-argtypes.md

@@ -0,0 +1,97 @@
+---
+title: 'ArgTypes'
+---
+
+The `ArgTypes` block can be used to show a static table of [arg types](./argtypes.md) for a given component, as a way to document its interface.
+
+<div class="aside">
+
+💡 If you’re looking for a dynamic table that shows a story’s current arg values for a story and supports users changing them, see the [`Controls`](./doc-block-controls.md) block instead.
+
+</div>
+
+![Screenshot of ArgTypes block](./doc-block-argtypes.png)
+
+<!-- prettier-ignore-start -->
+```md
+{/* ButtonDocs.mdx */}
+
+import { Meta, ArgTypes } from '@storybook/blocks';
+import * as ButtonStories from './Button.stories';
+
+<Meta of={ButtonStories} />
+
+<ArgTypes of={ButtonStories} />
+```
+<!-- prettier-ignore-end -->
+
+## ArgTypes
+
+```js
+import { ArgTypes } from '@storybook/blocks';
+```
+
+<details>
+<summary>Configuring with props <strong>and</strong> parameters</summary>
+
+ℹ️ Like most blocks, the `ArgTypes` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../writing-stories/parameters.md) in the block's namespace, `parameters.docs.argTypes`.
+
+The following `exclude` configurations are equivalent:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/api-doc-block-argtypes-parameter.js.mdx',
+    'common/api-doc-block-argtypes-parameter.ts.mdx',
+    'common/api-doc-block-argtypes-parameter.ts-4-9.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<!-- prettier-ignore-start -->
+```md
+{/* ButtonDocs.mdx */}
+
+<ArgTypes of={ButtonStories} exclude={['style']} />
+```
+<!-- prettier-ignore-end -->
+
+The example above applied the parameter at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level, but it could also be applied at the [project](../writing-stories/parameters.md#global-parameters) or [story](../writing-stories/parameters.md#story-parameters) level.
+
+</details>
+
+### `exclude`
+
+Type: `string[] | RegExp`
+
+Default: `parameters.docs.argTypes.exclude`
+
+Specifies which arg types to exclude from the args table. Any arg types whose names match the regex or are part of the array will be left out.
+
+### `include`
+
+Type: `string[] | RegExp`
+
+Default: `parameters.docs.argTypes.include`
+
+Specifies which arg types to include in the args table. Any arg types whose names don’t match the regex or are not part of the array will be left out.
+
+### `of`
+
+Type: Story export or CSF file exports
+
+Specifies which story to get the arg types from. If a CSF file exports is provided, it will use the primary (first) story in the file.
+
+### `sort`
+
+Type: `'none' | 'alpha' | 'requiredFirst'`
+
+Default: `parameters.docs.argTypes.sort` or `'none'`
+
+Specifies how the arg types 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