Merge pull request #25 from storybookjs/docs/update-rule-docs

Docs/update rule docs
storybookjs · Nov 9, 2021 · f1badfa · f1badfa
2 parents 556cf4c + 1745736
commit f1badfa
Show file tree

Hide file tree

Showing 16 changed files with 155 additions and 114 deletions.
diff --git a/README.md b/README.md
@@ -105,7 +105,7 @@ Another approach for customizing ESLint config by paths is through [ESLint Casca
 
 | Name                                                                                       | Description                                       | 🔧  | Included in configurations      |
 | ------------------------------------------------------------------------------------------ | ------------------------------------------------- | --- | ------------------------------- |
-| [`storybook/await-interactions`](./docs/rules/await-interactions.md)                       | Interactions should be awaited                    |     | addon-interactions, recommended |
+| [`storybook/await-interactions`](./docs/rules/await-interactions.md)                       | Interactions should be awaited                    | 🔧  | addon-interactions, recommended |
 | [`storybook/csf-component`](./docs/rules/csf-component.md)                                 | The component property should be set              |     | csf                             |
 | [`storybook/default-exports`](./docs/rules/default-exports.md)                             | Story files should have a default export          |     | csf, recommended                |
 | [`storybook/hierarchy-separator`](./docs/rules/hierarchy-separator.md)                     | Deprecated hierachy separator in title property   | 🔧  | csf, recommended                |

diff --git a/docs/rules/await-interactions.md b/docs/rules/await-interactions.md
@@ -1,13 +1,14 @@
 # await-interactions
 
-Storybook provides an instrumented version of testing library in the [@storybook/testing-library](https://github.com/storybookjs/testing-library/) package. When [writing interactions](https://storybook.js.org/docs/react/essentials/interactions), make sure to **await** them, so that addon-interactions can intercept these helper functions and allow you to step through them when debugging.
-
 <!-- RULE-CATEGORIES:START -->
-<!-- RULE-LIST:END -->
+
+**Categories**: addon-interactions, recommended
+
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
-Interactions should be awaited.
+Storybook provides an instrumented version of testing library in the [@storybook/testing-library](https://github.com/storybookjs/testing-library/) package. When [writing interactions](https://storybook.js.org/docs/react/essentials/interactions), make sure to **await** them, so that addon-interactions can intercept these helper functions and allow you to step through them when debugging.
 
 Examples of **incorrect** code for this rule:
 

diff --git a/docs/rules/csf-component.md b/docs/rules/csf-component.md
@@ -1,36 +1,36 @@
 # Component property must be set in meta (csf-component)
 
-Please describe the origin of the rule here.
+<!-- RULE-CATEGORIES:START -->
+
+**Categories**: csf
+
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
-This rule aims to...
+This rule encourages you to set the `component` property of your CSF default export. The `component` property is optional, but configuring unlocks a variety of features in Storybook, including automatic prop table documentation in most frameworks, auto-generated controls for dynamically editing your stories, and in CSF3, a resonable default for rendering your component without having to define a render function.
 
 Examples of **incorrect** code for this rule:
 
 ```js
-export default { 
-  title: 'Button'
+export default {
+  title: 'Button',
 }
 ```
 
 Examples of **correct** code for this rule:
 
 ```js
-export default { 
-  title: 'Button', 
-  component: Button 
+export default {
+  title: 'Button',
+  component: Button,
 }
 ```
 
-### Options
-
-If there are any options, describe them here. Otherwise, delete this section.
-
 ## When Not To Use It
 
-Give a short description of when it would be appropriate to turn off this rule.
+While we encourage each CSF file to clearly correspond to a single component, it's possible to organize a Storybook in any way you choose. If you have some other organization scheme, especially if you're migrating from the legacy `storiesOf` API, this rule might not apply to you.
 
 ## Further Reading
 
-If there are other links that describe the issue this rule addresses, please include them here in a bulleted list.
+- [Automatic argType inference](https://storybook.js.org/docs/react/api/argtypes#automatic-argtype-inference)
diff --git a/docs/rules/default-exports.md b/docs/rules/default-exports.md
@@ -1,12 +1,14 @@
 # Stories file should have a default export (default-exports)
 
-Please describe the origin of the rule here.
+<!-- RULE-CATEGORIES:START -->
 
-@TODO: Explain the complications of not having component property (addon docs, controls, etc)
+**Categories**: csf, recommended
+
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
-This rule aims to...
+In [CSF](https://storybook.js.org/docs/react/writing-stories/introduction#component-story-format), a story file should contain a _default export_ that describes the component, and _named exports_ that describe the stories. This rule enforces the definition of a default export in story files.
 
 Examples of **incorrect** code for this rule:
 
@@ -18,22 +20,18 @@ export const Primary = {}
 Examples of **correct** code for this rule:
 
 ```js
-export default { 
+export default {
   title: 'Button',
   args: { primary: true },
-  component: Button
+  component: Button,
 }
 export const Primary = {}
 ```
 
-### Options
-
-If there are any options, describe them here. Otherwise, delete this section.
-
 ## When Not To Use It
 
-Give a short description of when it would be appropriate to turn off this rule.
+This rule should not only be applied in your `.stories.*` files. Please ensure you are defining the storybook rules only for story files. You can see more details [here](https://github.com/storybookjs/eslint-plugin-storybook#eslint-overrides).
 
 ## Further Reading
 
-If there are other links that describe the issue this rule addresses, please include them here in a bulleted list.
+More information about defining stories here: https://storybook.js.org/docs/react/writing-stories/introduction#defining-stories
diff --git a/docs/rules/hierarchy-separator.md b/docs/rules/hierarchy-separator.md
@@ -1,18 +1,14 @@
 # Deprecated hierarchy separator (hierarchy-separator)
 
-Please describe the origin of the rule here.
+<!-- RULE-CATEGORIES:START -->
 
-For more details: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#removed-hierarchy-separators
+**Categories**: csf, recommended
 
-To automatically migrate, run this codemod in the root folder of your project:
-
-```sh
-npx sb@next migrate upgrade-hierarchy-separators --glob="*/**/*.stories.@(tsx|jsx|ts|js)"
-```
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
-This rule aims to...
+Since Storybook 6.0, the ability to specify the hierarchy separators (how you control the grouping of story kinds in the sidebar) was removed. There is now a single separator `/`, which cannot be configured. If you are using `|` or `.` as a separator, you should change all of them to `/`.
 
 Examples of **incorrect** code for this rule:
 
@@ -32,14 +28,12 @@ export default {
 }
 ```
 
-### Options
-
-If there are any options, describe them here. Otherwise, delete this section.
-
-## When Not To Use It
+## Further Reading
 
-Give a short description of when it would be appropriate to turn off this rule.
+For more details about this change: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#removed-hierarchy-separators
 
-## Further Reading
+To automatically migrate all of your codebase and fix this issue, run this codemod in the root folder of your project:
 
-If there are other links that describe the issue this rule addresses, please include them here in a bulleted list.
+```sh
+npx sb@next migrate upgrade-hierarchy-separators --glob="*/**/*.stories.@(tsx|jsx|ts|js)"
+```
diff --git a/docs/rules/meta-inline-properties.md b/docs/rules/meta-inline-properties.md
@@ -1,10 +1,11 @@
 # Meta should only have inline properties (meta-inline-properties)
 
-Please describe the origin of the rule here.
+<!-- RULE-CATEGORIES:START -->
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
-This rule aims to...
+This rule encourages you to use inline property definitions for the default export in your CSF file. The reason is that there are a bunch of tools in Storybook that rely on static analysis of your CSF code, and inline properties (rather than variables, functions, etc.) are much easier to process. Authoring your files this way may save you headaches in the future when, for example, you try to run an automated codemod to upgrade your stories to the latest version of CSF.
 
 Examples of **incorrect** code for this rule:
 
@@ -29,14 +30,6 @@ export default {
 }
 ```
 
-### Options
-
-If there are any options, describe them here. Otherwise, delete this section.
-
-## When Not To Use It
-
-Give a short description of when it would be appropriate to turn off this rule.
-
 ## Further Reading
 
 If there are other links that describe the issue this rule addresses, please include them here in a bulleted list.
diff --git a/docs/rules/no-redundant-story-name.md b/docs/rules/no-redundant-story-name.md
@@ -1,10 +1,14 @@
 # Named exports should not use the name annotation if it is redundant to the name that would be generated by the export name (no-redundant-story-name)
 
-Please describe the origin of the rule here.
+<!-- RULE-CATEGORIES:START -->
+
+**Categories**: csf, recommended
+
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
-This rule aims to...
+Storybook automatically resolves a story name based on its named export. You can rename any particular story you'd like, but if the name is redundant to what Storybook will resolve, you don't need to do that.
 
 Examples of **incorrect** code for this rule:
 
@@ -19,18 +23,10 @@ Examples of **correct** code for this rule:
 
 ```js
 export const PrimaryButton = {
-  name: 'The Primary Button',
+  name: 'I am the primary',
 }
 ```
 
-### Options
-
-If there are any options, describe them here. Otherwise, delete this section.
-
 ## When Not To Use It
 
-Give a short description of when it would be appropriate to turn off this rule.
-
-## Further Reading
-
-If there are other links that describe the issue this rule addresses, please include them here in a bulleted list.
+When you set a custom name for a story, it will make sure that the resolved story name will always be that same name, regardless if you rename the export later on. If that is your reason to keep story names set even if they are redundant, you should turn this rule off.
diff --git a/docs/rules/no-stories-of.md b/docs/rules/no-stories-of.md
@@ -1,24 +1,22 @@
 # storiesOf is deprecated and should not be used (no-stories-of)
 
-Please describe the origin of the rule here.
+<!-- RULE-CATEGORIES:START -->
 
-To automatically migrate, run this codemod in the root folder of your project:
-```sh
-npx sb@next migrate storiesof-to-csf --glob="*/**/*.stories.@(tsx|jsx|ts|js)"
-```
+**Categories**: csf-strict
+
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
-This rule aims to...
+Since Storybook 5.2, the [CSF format](https://storybook.js.org/docs/react/api/csf) was introduced and the `storiesOf` API has been deprecated.
 
 Examples of **incorrect** code for this rule:
 
 ```js
-import { storiesOf } from '@storybook/react';
-import Button from '../components/Button';
+import { storiesOf } from '@storybook/react'
+import Button from '../components/Button'
 
-storiesOf('Button', module)
-  .add('primary', () => <Button primary />)
+storiesOf('Button', module).add('primary', () => <Button primary />)
 ```
 
 Examples of **correct** code for this rule:
@@ -33,14 +31,26 @@ export default = {
 export const Primary = () => <Button primary />
 ```
 
-### Options
-
-If there are any options, describe them here. Otherwise, delete this section.
+```js
+import Button from '../components/Button';
 
-## When Not To Use It
+export default = {
+  component: Button
+}
 
-Give a short description of when it would be appropriate to turn off this rule.
+export const Primary = {
+  args: {
+    primary: true
+  }
+}
+```
 
 ## Further Reading
 
-If there are other links that describe the issue this rule addresses, please include them here in a bulleted list.
+For more information about the change from `storiesOf` to `CSF`, read here: https://github.com/storybookjs/storybook/blob/master/lib/core/docs/storiesOf.md
+
+To automatically migrate all of your codebase, run this codemod in the root folder of your project:
+
+```sh
+npx sb@next migrate storiesof-to-csf --glob="*/**/*.stories.@(tsx|jsx|ts|js)"
+```
diff --git a/docs/rules/no-title-property-in-meta.md b/docs/rules/no-title-property-in-meta.md
@@ -1,10 +1,15 @@
 # Meta should not have a title property (no-title-property-in-meta)
 
-Please describe the origin of the rule here.
+<!-- RULE-CATEGORIES:START -->
+
+**Categories**: csf-strict
+
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
-This rule aims to...
+Starting in [CSF 3.0](https://storybook.js.org/blog/component-story-format-3-0/), story titles can be generated automatically. You can still specify a title like in CSF 2.0, but if you don't specify one, it can be inferred from the story's path on disk.
+This rule aims to enforce not setting a title, making the codebase consistent.
 
 Examples of **incorrect** code for this rule:
 
@@ -19,18 +24,14 @@ Examples of **correct** code for this rule:
 
 ```js
 export default {
-  component: Input,
+  component: Input, // no title necessary, it will be inferred from path on disk!
 }
 ```
 
-### Options
-
-If there are any options, describe them here. Otherwise, delete this section.
-
 ## When Not To Use It
 
-Give a short description of when it would be appropriate to turn off this rule.
+If you're not strictly enforcing this rule in your codebase (thus allowing custom titles), you should turn this rule off.
 
 ## Further Reading
 
-If there are other links that describe the issue this rule addresses, please include them here in a bulleted list.
+You can find more information about CSF3 and story titles here: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#optional-titles
diff --git a/docs/rules/prefer-pascal-case.md b/docs/rules/prefer-pascal-case.md
@@ -1,10 +1,14 @@
 # Prefer pascal case for story names (prefer-pascal-case)
 
-Please describe the origin of the rule here.
+<!-- RULE-CATEGORIES:START -->
+
+**Categories**: recommended
+
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
-This rule aims to...
+As a best practice, stories should be defined in [_PascalCase_](https://en.wiktionary.org/wiki/Pascal_case). This makes it simpler to visually differ stories to other code. Plus, it makes it simpler to define regexes for [non-story exports](https://storybook.js.org/docs/react/api/csf#non-story-exports).
 
 Examples of **incorrect** code for this rule:
 
@@ -18,14 +22,6 @@ Examples of **correct** code for this rule:
 export const PrimaryButton = {}
 ```
 
-### Options
-
-If there are any options, describe them here. Otherwise, delete this section.
-
-## When Not To Use It
-
-Give a short description of when it would be appropriate to turn off this rule.
-
 ## Further Reading
 
-If there are other links that describe the issue this rule addresses, please include them here in a bulleted list.
+More information about naming stories can be found here: https://storybook.js.org/docs/react/writing-stories/introduction#defining-stories
diff --git a/docs/rules/use-storybook-expect.md b/docs/rules/use-storybook-expect.md
@@ -1,9 +1,16 @@
 # Use expect from &#39;@storybook/expect&#39; (use-storybook-expect)
 
-Storybook provides a browser compatible version of Jest's expect via the [@storybook/expect](https://github.com/storybookjs/expect) library. When [writing interactions](https://storybook.js.org/docs/react/essentials/interactions) and asserting values, you should always use `expect` from the `@storybook/jest` library.
+<!-- RULE-CATEGORIES:START -->
+
+**Categories**: addon-interactions, recommended
+
+<!-- RULE-CATEGORIES:END -->
 
 ## Rule Details
 
+Storybook provides a browser compatible version of Jest's expect via the [@storybook/expect](https://github.com/storybookjs/expect) library.
+When [writing interactions](https://storybook.js.org/docs/react/essentials/interactions) and asserting values, you should always use `expect` from the `@storybook/jest` library.
+
 Examples of **incorrect** code for this rule:
 
 ```js