1 | <h1>Storybook Docs for Web Components</h1>
|
2 |
|
3 | - [Installation](#installation)
|
4 | - [Props tables](#props-tables)
|
5 | - [Stories not inline](#stories-not-inline)
|
6 | - [More resources](#more-resources)
|
7 |
|
8 | ## Installation
|
9 |
|
10 | - Be sure to check the [installation section of the general addon-docs page](../README.md) before proceeding.
|
11 | - Be sure to have a [custom-elements.json](./#custom-elementsjson) file.
|
12 | - Add to your `.storybook/preview.js`
|
13 |
|
14 | ```js
|
15 | import { setCustomElementsManifest } from '@storybook/web-components';
|
16 | import customElements from '../custom-elements.json';
|
17 |
|
18 | setCustomElementsManifest(customElements);
|
19 | ```
|
20 |
|
21 | - Add to your story files
|
22 |
|
23 | ```js
|
24 | export default {
|
25 | title: 'Demo Card',
|
26 | component: 'your-component-name', // which is also found in the `custom-elements.json`
|
27 | };
|
28 | ```
|
29 |
|
30 | ## Props tables
|
31 |
|
32 | In order to get [Props tables](..docs/../../docs/props-tables.md) documentation for web-components you will need to have a [custom-elements.json](https://github.com/webcomponents/custom-elements-json) file.
|
33 |
|
34 | You can hand write it or better generate it. Depending on the web components sugar you are choosing your milage may vary.
|
35 |
|
36 | Known analyzers that output `custom-elements.json` v1.0.0:
|
37 |
|
38 | - [@custom-elements-manifest/analyzer](https://github.com/open-wc/custom-elements-manifest)
|
39 | - Supports Vanilla, LitElement, FASTElement, Stencil, Catalyst, Atomico
|
40 |
|
41 | Known analyzers that output older versions of `custom-elements.json`:
|
42 | - [web-component-analyzer](https://github.com/runem/web-component-analyzer)
|
43 | - Supports LitElement, Polymer, Vanilla, (Stencil)
|
44 | - [stenciljs](https://stenciljs.com/)
|
45 | - Supports Stencil (but does not have all metadata)
|
46 |
|
47 | To generate this file with Stencil, add `docs-vscode` to outputTargets in `stencil.config.ts`:
|
48 |
|
49 | ```
|
50 | {
|
51 | type: 'docs-vscode',
|
52 | file: 'custom-elements.json'
|
53 | },
|
54 | ```
|
55 |
|
56 | The file looks something like this:
|
57 |
|
58 | ```json
|
59 | {
|
60 | "schemaVersion": "1.0.0",
|
61 | "readme": "",
|
62 | "modules": [
|
63 | {
|
64 | "kind": "javascript-module",
|
65 | "path": "src/my-element.js",
|
66 | "declarations": [
|
67 | {
|
68 | "kind": "class",
|
69 | "description": "",
|
70 | "name": "MyElement",
|
71 | "members": [
|
72 | {
|
73 | "kind": "field",
|
74 | "name": "disabled"
|
75 | },
|
76 | {
|
77 | "kind": "method",
|
78 | "name": "fire"
|
79 | }
|
80 | ],
|
81 | "events": [
|
82 | {
|
83 | "name": "disabled-changed",
|
84 | "type": {
|
85 | "text": "Event"
|
86 | }
|
87 | }
|
88 | ],
|
89 | "superclass": {
|
90 | "name": "HTMLElement"
|
91 | },
|
92 | "tagName": "my-element"
|
93 | }
|
94 | ],
|
95 | "exports": [
|
96 | {
|
97 | "kind": "custom-element-definition",
|
98 | "name": "my-element",
|
99 | "declaration": {
|
100 | "name": "MyElement",
|
101 | "module": "src/my-element.js"
|
102 | }
|
103 | }
|
104 | ]
|
105 | }
|
106 | ]
|
107 | }
|
108 | ```
|
109 |
|
110 | For a full example see the [web-components-kitchen-sink/custom-elements.json](../../../examples/web-components-kitchen-sink/custom-elements.json).
|
111 |
|
112 | ## Stories not inline
|
113 |
|
114 | By default stories are rendered inline.
|
115 | For web components that is usually fine as they are style encapsulated via shadow dom.
|
116 | However when you have a style tag in you template it might be best to show them in an iframe.
|
117 |
|
118 | To always use iframes you can set
|
119 |
|
120 | ```js
|
121 | addParameters({
|
122 | docs: {
|
123 | inlineStories: false,
|
124 | },
|
125 | });
|
126 | ```
|
127 |
|
128 | or add it to individual stories.
|
129 |
|
130 | ```js
|
131 | <Story inline={false} />
|
132 | ```
|
133 |
|
134 | ## More resources
|
135 |
|
136 | Want to learn more? Here are some more articles on Storybook Docs:
|
137 |
|
138 | - References: [DocsPage](../docs/docspage.md) / [MDX](../docs/mdx.md) / [FAQ](../docs/faq.md) / [Recipes](../docs/recipes.md) / [Theming](../docs/theming.md) / [Props](../docs/props-tables.md)
|
139 | - Announcements: [Vision](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a) / [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf) / [MDX](https://medium.com/storybookjs/rich-docs-with-storybook-mdx-61bc145ae7bc) / [Framework support](https://medium.com/storybookjs/storybook-docs-for-new-frameworks-b1f6090ee0ea)
|
140 | - Example: [Storybook Design System](https://github.com/storybookjs/design-system)
|