GitHub/storybook
1
0
Fork 0
mirror of https://github.com/storybookjs/storybook.git synced 2025-03-18 05:02:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #11807 from storybookjs/6.0-docs-snippets

Browse Source 
6.0 docs snippets initial setup
This commit is contained in:
Kyle Suss 2020-08-06 10:43:48 -06:00 committed by GitHub
commit 234103b28b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 120 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/api/argtypes.md
View File

@ -6,8 +6,7 @@ title: 'ArgTypes'
NOTE: This API is experimental and may change outside of the typical semver release cycle
<div>
</div>
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 can also provide information about args that are not explicitly set (i.e. not required).
@ -19,23 +18,21 @@ The most concrete realization of argTypes is the [Args Table](../writing-docs/do
## 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](#default-export) of the CSF file.
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](#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)
- 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)
- [vue-docgen-api](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api)
- Angular
- [compodoc](https://compodoc.app/)
- [compodoc](https://compodoc.app/)
- WebComponents
- [custom-element.json](https://github.com/webcomponents/custom-elements-json)
- [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)
- [YUI doc](https://github.com/ember-learn/ember-cli-addon-docs-yuidoc#documenting-components)
The format of the generated argType will look something like:
@ -61,18 +58,18 @@ In this ArgTypes data structure, name, type, defaultValue, and description are s
<div class="aside">
`@storybook/addon-docs` provide shorthand for common tasks:
`@storybook/addon-docs` provide shorthand for common tasks:
- `type: 'number'` is shorthand for type: { name: 'number' }
- `control: 'radio'` is shorthand for control: { type: 'radio' }
<div>
</div>
#### Manual specification
If you want more control over the props table or any other aspect of using argTypes, you can overwrite the generated argTypes for you component on a per-arg basis. For instance, with the above inferred argTypes and the following default export:
If you want more control over the props table or any other aspect of using argTypes, you can overwrite the generated argTypes for you component on a per-arg basis. For instance, with the above inferred argTypes and the following default export:
```js
export default {
title: 'Button',
component: Button,

63
docs/api/cli-options.md
View File

@ -12,25 +12,24 @@ You can pass these commands the following options to alter Storybook's behavior.
Usage: start-storybook [options]
```
| Options |Description |Example |
|-----------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------|
|--help |Output usage information |`start-storybook --help` |
|-V, --version |Output the version number |`start-storybook -V` |
|-p, --port [number] |Port to run Storybook |`start-storybook -p 9009` |
|-h, --host [string] |Host to run Storybook |`start-storybook -h http://my-host.com` |
|-s, --static-dir <dir-names> |Directory where to load static files from, comma-separated list |`start-storybook -s public` |
|-c, --config-dir [dir-name] |Directory where to load Storybook configurations from |`start-storybook -c .storybook` |
|--https |Serve Storybook over HTTPS. Note: You must provide your own certificate information. |`start-storybook --https` |
|--ssl-ca <ca> |Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate) |`start-storybook --ssl-ca my-certificate` |
|--ssl-cert <cert> |Provide an SSL certificate. (Required with --https) |`start-storybook --ssl-cert my-ssl-certificate`|
|--ssl-key <key> |Provide an SSL key. (Required with --https) |`start-storybook --ssl-key my-ssl-key` |
|--smoke-test |Exit after successful start |`start-storybook --smoke-test` |
|--ci |CI mode (skip interactive prompts, don't open browser) |`start-storybook --ci` |
|--quiet |Suppress verbose build output |`start-storybook --quiet` |
|--no-dll |Do not use dll reference |`start-storybook --no-dll` |
|--debug-webpack |Display final webpack configurations for debugging purposes |`start-storybook --debug-webpack` |
|--docs |Starts Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#preview-storybooks-documentation)|`start-storybook --docs` |
| Options | Description | Example |
| ------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------- |
| --help | Output usage information | `start-storybook --help` |
| -V, --version | Output the version number | `start-storybook -V` |
| -p, --port [number] | Port to run Storybook | `start-storybook -p 9009` |
| -h, --host [string] | Host to run Storybook | `start-storybook -h http://my-host.com` |
| -s, --static-dir `<dir-names>` | Directory where to load static files from, comma-separated list | `start-storybook -s public` |
| -c, --config-dir [dir-name] | Directory where to load Storybook configurations from | `start-storybook -c .storybook` |
| --https | Serve Storybook over HTTPS. Note: You must provide your own certificate information. | `start-storybook --https` |
| --ssl-ca `<ca>` | Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate) | `start-storybook --ssl-ca my-certificate` |
| --ssl-cert `<cert>` | Provide an SSL certificate. (Required with --https) | `start-storybook --ssl-cert my-ssl-certificate` |
| --ssl-key `<key>` | Provide an SSL key. (Required with --https) | `start-storybook --ssl-key my-ssl-key` |
| --smoke-test | Exit after successful start | `start-storybook --smoke-test` |
| --ci | CI mode (skip interactive prompts, don't open browser) | `start-storybook --ci` |
| --quiet | Suppress verbose build output | `start-storybook --quiet` |
| --no-dll | Do not use dll reference | `start-storybook --no-dll` |
| --debug-webpack | Display final webpack configurations for debugging purposes | `start-storybook --debug-webpack` |
| --docs | Starts Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#preview-storybooks-documentation) | `start-storybook --docs` |
## For build-storybook
@ -38,16 +37,16 @@ Usage: start-storybook [options]
Usage: build-storybook [options]
```
| Options |Description |Example |
|-----------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------|
|-h, --help |Output usage information |`build-storybook --help` |
|-V, --version |Output the version number |`build-storybook -V` |
|-s, --static-dir <dir-names> |Directory where to load static files from, comma-separated list |`build-storybook -s public` |
|-o, --output-dir [dir-name] |Directory where to store built files |`build-storybook -o /my-deployed-storybook` |
|-c, --config-dir [dir-name] |Directory where to load Storybook configurations from |`build-storybook -o .storybook` |
|-w, --watch |Enables watch mode |`build-storybook -w` |
|--loglevel [level] |Controls level of logging during build. Can be one of: [silly, verbose, info (default), warn, error, silent] |`build-storybook --loglevel warn` |
|--quiet |Suppress verbose build output |`build-storybook --quiet` |
|--no-dll |Do not use dll reference |`build-storybook --no-dll` |
|--debug-webpack |Display final webpack configurations for debugging purposes |`build-storybook --debug-webpack` |
|--docs |Builds Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#publish-storybooks-documentation))|`start-storybook --docs` |
| Options | Description | Example |
| ------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
| -h, --help | Output usage information | `build-storybook --help` |
| -V, --version | Output the version number | `build-storybook -V` |
| -s, --static-dir `<dir-names>` | Directory where to load static files from, comma-separated list | `build-storybook -s public` |
| -o, --output-dir [dir-name] | Directory where to store built files | `build-storybook -o /my-deployed-storybook` |
| -c, --config-dir [dir-name] | Directory where to load Storybook configurations from | `build-storybook -o .storybook` |
| -w, --watch | Enables watch mode | `build-storybook -w` |
| --loglevel [level] | Controls level of logging during build. Can be one of: [silly, verbose, info (default), warn, error, silent] | `build-storybook --loglevel warn` |
| --quiet | Suppress verbose build output | `build-storybook --quiet` |
| --no-dll | Do not use dll reference | `build-storybook --no-dll` |
| --debug-webpack | Display final webpack configurations for debugging purposes | `build-storybook --debug-webpack` |
| --docs | Builds Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#publish-storybooks-documentation)) | `start-storybook --docs` |

36
docs/api/csf.md
View File

@ -10,7 +10,7 @@ Storybook's Component Story Format (CSF) is the recommended way to [write storie
TODO: vet storiesOf links
</div>
<div class="aside"
<div class="aside">
If you are writing stories in the older `storiesOf()` syntax, you can find documentation in an [advanced README](../../lib/core/ADVANCED.md).
@ -22,7 +22,7 @@ CSF is supported in all frameworks except React Native, where you should use the
#### Default export
The default export defines metadata about your component, including the `component` itself, its `title` (where it will show up in the [navigation UI story hierarchy](../writing-stories/docs/writing-stories/naming-components-and-hierarchy.md#sorting-stories)), [decorators](../writing-stories/decorators.md), and [parameters](../writing-stories/parameters.md).
The default export defines metadata about your component, including the `component` itself, its `title` (where it will show up in the [navigation UI story hierarchy](../writing-stories/docs/writing-stories/naming-components-and-hierarchy.md#sorting-stories)), [decorators](../writing-stories/decorators.md), and [parameters](../writing-stories/parameters.md).
The `component` field is optional (but encouraged!), and is used by addons for automatic prop table generation and display of other component metadata. `title` should be unique, i.e. not re-used across files.
@ -49,9 +49,9 @@ With CSF, every named export in the file represents a story function by default.
import MyComponent from './MyComponent';
export default {
title: 'Path/To/MyComponent',
component: MyComponent,
}
title: 'Path/To/MyComponent',
component: MyComponent,
};
export const Basic = () => <MyComponent />;
export const WithProp = () => <MyComponent prop="value" />;
@ -59,24 +59,20 @@ export const WithProp = () => <MyComponent prop="value" />;
The exported identifiers will be converted to "start case" using Lodash's [startCase](https://lodash.com/docs/#startCase) function. For example:
| Identifier | Transformation |
| ------------------------ |:--------------------:|
| **name** |**Name** |
| **someName** | **Some Name** |
| **someNAME** | **SSome NAME** |
| **some_custom_NAME** | **Some Custom NAME** |
| **someName1234** | **ome Name 1 2 3 4** |
| Identifier | Transformation |
| -------------------- | :------------------: |
| **name** | **Name** |
| **someName** | **Some Name** |
| **someNAME** | **SSome NAME** |
| **some_custom_NAME** | **Some Custom NAME** |
| **someName1234** | **ome Name 1 2 3 4** |
It's recommended to start export names with a capital letter.
Story functions can be annotated with a few different fields to define story-level [decorators](../writing-stories/decorators.md) and [parameters](../writing-stories/parameters.md), and also to define the `storyName` of the story.
The `storyName` is useful if you want to use names with special characters, names that correspond to restricted keywords in Javascript, or names that collide with other variables in the file. If it's not specified, the export name will be used instead.
```jsx
// MyComponent.story.js
@ -99,9 +95,9 @@ Consider Storybook’s ["Button" example](../writing-stories/introduction.md#def
import { action } from '@storybook/addon-actions';
import { Button } from './Button';
export default {
title: 'Button',
component: Button
export default {
title: 'Button',
component: Button
};
export const Text = () => <Button label=’Hello’ onClick={action('clicked')} />;
```
@ -200,4 +196,4 @@ For this specific example the equivalent result can be achieved in a few ways de
- `includeStories: ['SimpleStory', 'ComplexStory']`
- `includeStories: /.*Story$/`
- `excludeStories: ['simpleData', 'complexData']`
- `excludeStories: /.*Data$/`
- `excludeStories: /.*Data$/`

2
docs/api/new-frameworks.md
View File

@ -8,7 +8,7 @@ Storybook is architected to support diverse web frameworks including React, Vue,
The first thing to do is scaffold your framework support in its own repo.
We recommend adopting the same project structure as the Storybook monorepo. That structure contains the framework package (“app/<framework>”) and an example app (“examples/<framework>-kitchen-sink”) as well as other associated documentation and configuration as needed.
We recommend adopting the same project structure as the Storybook monorepo. That structure contains the framework package (`app/<framework>`) and an example app (`examples/<framework>-kitchen-sink`) as well as other associated documentation and configuration as needed.
This may seem like a little more hierarchy than what’s necessary. But because the structure mirrors the way Storybook’s own monorepo is structured, you can reuse Storybook’s tooling and it also makes it easier to move the framework into the Storybook into the monorepo at a later point if that is desirable.

34
docs/get-started/setup.md
View File

@ -13,7 +13,7 @@ import { YourComponent } from './YourComponent';
export default {
component: YourComponent,
title: 'YourComponent',
}
};
const Template = (args) => <YourComponent {...args} />;
@ -26,23 +26,23 @@ FirstStory.args = {
Go to your Storybook to view the rendered component. It’s OK if it looks a bit unusual right now.
Depending on your technology stack, you also might need to configure the Storybook environment further.
Depending on your technology stack, you also might need to configure the Storybook environment further.
### Configure Storybook for your stack
Storybook comes with a permissive [default configuration](../configure/overview.md). It attempts to customize itself to fit your setup. But it’s not foolproof.
Storybook comes with a permissive [default configuration](../configure/overview.md). It attempts to customize itself to fit your setup. But it’s not foolproof.
Your project may have additional requirements before components can be rendered in isolation. This warrants customizing configuration further. There are three broad categories of configuration you might need.
Your project may have additional requirements before components can be rendered in isolation. This warrants customizing configuration further. There are three broad categories of configuration you might need.
<details>
<summary>Build configuration like webpack and Babel</summary>
If you see errors on the CLI when you run the `yarn storybook` command. It’s likely you need to make changes to Storybook’s build configuration. Here are some things to try:
- [Presets](../api/presets.md) bundle common configurations for various technologies into Storybook. In particular presets exist for Create React App, SCSS and Ant Design.
- Specify a custom [Babel configuration](../configure/integration.md#custom-babel-config) for Storybook. Storybook automatically tries to use your project’s config if it can.
- Adjust the [webpack configuration](../configure/integration.md#webpack) that Storybook uses. Try patching in your own configuration if needed.
- [Presets](../api/presets.md) bundle common configurations for various technologies into Storybook. In particular presets exist for Create React App, SCSS and Ant Design.
- Specify a custom [Babel configuration](../configure/integration.md#custom-babel-config) for Storybook. Storybook automatically tries to use your project’s config if it can.
- Adjust the [webpack configuration](../configure/integration.md#webpack) that Storybook uses. Try patching in your own configuration if needed.
</details>
<details>
@ -54,7 +54,7 @@ Your project may have additional requirements before components can be rendered
<details id="component-context" name="component-context">
<summary>Component context</summary>
If a particular story has a problem rendering, often it means your component expects a certain environment is available to the component.
If a particular story has a problem rendering, often it means your component expects a certain environment is available to the component.
A common frontend pattern is for components to assume that they render in a certain “context” with parent components higher up the rendering hierarchy (for instance theme providers)
@ -65,23 +65,26 @@ Use [decorators](../writing-stories/decorators.md) to “wrap” every story in
import { ThemeProvider } from 'styled-components';
export const decorators = [
(Story) => <ThemeProvider theme="default"><Story/></ThemeProvider>,
(Story) => (
<ThemeProvider theme="default">
<Story />
</ThemeProvider>
),
];
```
</details>
</details>
### Render component styles
Storybook isn’t opinionated about how you generate or load CSS. It renders whatever DOM elements you provide. But sometimes things won’t “look right” out of the box.
Storybook isn’t opinionated about how you generate or load CSS. It renders whatever DOM elements you provide. But sometimes things won’t “look right” out of the box.
You may have to configure your CSS tooling for Storybook’s rendering environment. Here are some tips on what could help:
<details>
<summary>CSS-in-JS like styled-components and Emotion</summary>
If you are using CSS-in-JS, chances are your styles are working because they’re generated in JavaScript and served alongside each component.
If you are using CSS-in-JS, chances are your styles are working because they’re generated in JavaScript and served alongside each component.
Theme users may need to add a decorator to `.storybook/preview.js`, [see above](#component-context).
@ -108,9 +111,8 @@ Alternatively if you want to inject a CSS link tag to the `<head>` directly (or
</details>
### Load assets and resources
If you want to link to static files in your project or stories (e.g. `/fonts/XYZ.woff`), use the `-s path/to/folder` to specify a static folder to serve from when you start up Storybook. To do so, edit the `storybook` and `build-storybook` scripts in `package. json`.
We recommend serving external resources and assets requested in your components statically with Storybook. This ensures that assets are always available to your stories.
We recommend serving external resources and assets requested in your components statically with Storybook. This ensures that assets are always available to your stories.

19
docs/get-started/whats-a-story.md
View File

@ -10,14 +10,18 @@ Each example component has a set of stories that show the states it supports. Yo
Let’s start with the `Button` component. A story is a function that describes how to render the component in question. Here’s how to render `Button` in the “primary” state and export a story called `Primary`.
```js
// Button.stories.js
<!-- prettier-ignore-start -->
import React from 'react';
import { Button } from './Button';
<CodeSnippets
paths={[
'react/button-story.js.mdx',
'react/button-story.ts.mdx',
'react/button-story.md.mdx',
'angular/button-story.js.mdx',
]}
/>
export const Primary = () => <Button primary>Button</Button>;
```
<!-- prettier-ignore-end -->
![Initial button story](./example-button-noargs.png)
@ -58,7 +62,6 @@ Storybook makes it easy to work on one component in one state (aka a story) at a
Update the `label` of the `Primary` story then see your change in Storybook.
<video autoPlay muted playsInline loop>
<source
src="example-button-hot-module-reload-optimized.mp4"
@ -77,4 +80,4 @@ Stories are also useful for checking that UI continues to look correct as you ma
Checking a component’s stories as you develop helps prevent accidental regressions. Tools that integrate with Storybook can also [automate](..workflows/testing-with-storybook.md) this for you.
Now we’ve seen the basic anatomy of a story, let’s see how we use Storybook’s UI to develop stories
Now we’ve seen the basic anatomy of a story, let’s see how we use Storybook’s UI to develop stories

3
docs/guides/guide-react-native/index.md
View File

@ -207,7 +207,8 @@ npm run storybook
**Note** You can change port to custom with `start-storybook -p=YOUR_PORT_NUMBER`, but then you also have to pass it as an option to `getStorybookUI({port: YOUR_PORT_NUMBER})`. If you are running on android, there might be need to run `adb reverse tcp:YOUR_PORT_NUMBER tcp:YOUR_PORT_NUMBER`.
### Start App
To see your Storybook stories on the device, you should start your mobile app for the <platform> of your choice (typically ios or android). (Note that due to an implementation detail, your stories will only show up in the left pane of your browser window after your device has connected to this storybook server.)
To see your Storybook stories on the device, you should start your mobile app for the `<platform>` of your choice (typically ios or android). (Note that due to an implementation detail, your stories will only show up in the left pane of your browser window after your device has connected to this storybook server.)
### Historical notes

4
docs/snippets/angular/button-story.js.mdx Normal file
View File

@ -0,0 +1,4 @@
```js
import Angular from 'angular';
// And some other Angular code
```

8
docs/snippets/react/button-story.js.mdx Normal file
View File

@ -0,0 +1,8 @@
```js
// Button.stories.js
import React from 'react';
import { Button } from './Button';
export const Primary = () => <Button primary>Button</Button>;
```

5
docs/snippets/react/button-story.md.mdx Normal file
View File

@ -0,0 +1,5 @@
```md
# This is a level 1 heading
It is just a test to make sure raw markdown can be passed through.
```

8
docs/snippets/react/button-story.ts.mdx Normal file
View File

@ -0,0 +1,8 @@
```ts
// Button.stories.js
import React from 'react';
import { Button } from './Button';
export const Primary: React.SFC<{}> = () => <Button primary>Button</Button>;
```

8
docs/workflows/snapshot-testing.md
View File

@ -4,7 +4,7 @@ title: 'Snapshot testing'
Snapshot tests compare the rendered markup of every story against known baselines. It’s an easy way to identify markup changes that trigger rendering errors and warnings.
Storybook is a convenient tool for snapshot testing because every story is essentially a test specification. Any time you write or update a story you get a snapshot test for free.
Storybook is a convenient tool for snapshot testing because every story is essentially a test specification. Any time you write or update a story you get a snapshot test for free.
<div class="aside">
@ -35,7 +35,6 @@ You can name the file whatever you like as long as it's picked up by Jest.
</div>
Run your first test. Storyshot will recognize all your CSF files (based on [`.storybook/main.js`](../configure/overview.md#configure-story-rendering)) and produces snapshots.
```shell
@ -50,8 +49,7 @@ TODO: ask for clarification on this note below. What extra steps?
If you are loading stories via `.storybook/main.js`, you will need to follow some more steps to ensure Jest finds them.
<div>
</div>
This will create an initial set of snapshots inside your Storybook config directory.
@ -63,4 +61,4 @@ When you make changes to your components or stories, run the test again to ident
If the changes are intentional we can accept them as new baselines. If the changes are bugs, fix the underlying code then run the snapshot tests again.
Storyshots has many options for advanced use cases; read more in the [addon’s documentation](https://github.com/storybookjs/storybook/tree/master/addons/storyshots/storyshots-core).
Storyshots has many options for advanced use cases; read more in the [addon’s documentation](https://github.com/storybookjs/storybook/tree/master/addons/storyshots/storyshots-core).