0
# Framework Integration
1
2
Utility functions for managing custom elements metadata, component validation, and framework configuration. These functions enable Storybook to understand and document web components by processing custom elements manifests and validating component configurations.
3
4
## Capabilities
5
6
### Custom Elements Management
7
8
Functions for setting and retrieving custom elements metadata used for automatic documentation generation.
9
10
```typescript { .api }
11
/**
12
* Sets custom elements metadata globally for documentation generation.
13
* @param customElements - Custom elements manifest or metadata object
14
*/
15
function setCustomElements(customElements: any): void;
16
17
/**
18
* Sets custom elements manifest globally (alternative to setCustomElements).
19
* @param customElements - Custom elements manifest object
20
*/
21
function setCustomElementsManifest(customElements: any): void;
22
23
/**
24
* Retrieves stored custom elements metadata.
25
* @returns Custom elements metadata or manifest, or undefined if not set
26
*/
27
function getCustomElements(): any;
28
```
29
30
**Usage:**
31
32
```typescript
33
import { setCustomElements } from "@storybook/web-components";
34
import customElementsManifest from "./custom-elements.json";
35
36
// Set custom elements for automatic docs generation
37
setCustomElements(customElementsManifest);
38
39
// Example manifest structure
40
const manifest = {
41
"version": "experimental",
42
"tags": [
43
{
44
"name": "my-button",
45
"description": "A customizable button component",
46
"attributes": [
47
{
48
"name": "label",
49
"type": { "text": "string" },
50
"description": "Button label text",
51
"default": "Click me"
52
},
53
{
54
"name": "variant",
55
"type": { "text": "string" },
56
"description": "Button style variant",
57
"default": "primary"
58
}
59
],
60
"properties": [
61
{
62
"name": "disabled",
63
"type": { "text": "boolean" },
64
"description": "Whether the button is disabled",
65
"default": false
66
}
67
],
68
"events": [
69
{
70
"name": "click",
71
"description": "Fired when button is clicked"
72
}
73
],
74
"slots": [
75
{
76
"name": "icon",
77
"description": "Slot for button icon"
78
}
79
]
80
}
81
]
82
};
83
84
setCustomElements(manifest);
85
```
86
87
### Component Validation
88
89
Functions for validating component names and metadata structures.
90
91
```typescript { .api }
92
/**
93
* Validates if a component tag name is valid for web components.
94
* @param tagName - The component tag name to validate
95
* @returns true if valid, false if falsy, throws error for invalid types
96
* @throws Error if tagName is not a string when truthy
97
*/
98
function isValidComponent(tagName: string): boolean;
99
100
/**
101
* Validates custom elements metadata structure.
102
* @param customElements - Custom elements metadata to validate
103
* @returns true if valid, false if invalid
104
* @throws Error with setup instructions if invalid structure
105
*/
106
function isValidMetaData(customElements: any): boolean;
107
```
108
109
**Usage:**
110
111
```typescript
112
import { isValidComponent, isValidMetaData } from "@storybook/web-components";
113
114
// Component validation
115
try {
116
const isValid = isValidComponent("my-button");
117
console.log("Component is valid:", isValid); // true
118
119
const isEmpty = isValidComponent("");
120
console.log("Empty component:", isEmpty); // false
121
122
// This will throw an error
123
isValidComponent(123); // Error: Provided component needs to be a string
124
} catch (error) {
125
console.error(error.message);
126
}
127
128
// Metadata validation
129
const validManifest = {
130
tags: [
131
{ name: "my-button", description: "A button" }
132
]
133
};
134
135
const validModules = {
136
modules: [
137
{ declarations: [{ tagName: "my-button" }] }
138
]
139
};
140
141
try {
142
console.log(isValidMetaData(validManifest)); // true
143
console.log(isValidMetaData(validModules)); // true
144
console.log(isValidMetaData({})); // false
145
146
// This will throw an error
147
isValidMetaData({ invalid: "structure" });
148
} catch (error) {
149
console.error(error.message); // Setup instructions
150
}
151
```
152
153
## Custom Elements Manifest Integration
154
155
### Setting Up Documentation
156
157
To enable automatic documentation generation, you need to provide a custom elements manifest:
158
159
```typescript
160
// In .storybook/preview.js
161
import { setCustomElements } from "@storybook/web-components";
162
import customElements from "../custom-elements.json";
163
164
setCustomElements(customElements);
165
```
166
167
### Generating Custom Elements Manifest
168
169
You can generate a custom elements manifest using tools like `@custom-elements-manifest/analyzer`:
170
171
```bash
172
# Install the analyzer
173
npm install -D @custom-elements-manifest/analyzer
174
175
# Generate manifest
176
npx cem analyze --litelement
177
178
# Or add to package.json scripts
179
{
180
"scripts": {
181
"analyze": "cem analyze --litelement --outdir ."
182
}
183
}
184
```
185
186
### Manifest Formats
187
188
The package supports two manifest formats:
189
190
**Format 1: Tags-based (experimental)**
191
```json
192
{
193
"version": "experimental",
194
"tags": [
195
{
196
"name": "my-element",
197
"description": "Element description",
198
"attributes": [...],
199
"properties": [...],
200
"events": [...],
201
"slots": [...],
202
"methods": [...],
203
"cssProperties": [...],
204
"cssParts": [...]
205
}
206
]
207
}
208
```
209
210
**Format 2: Modules-based (v1)**
211
```json
212
{
213
"modules": [
214
{
215
"declarations": [
216
{
217
"tagName": "my-element",
218
"name": "MyElement",
219
"description": "Element description",
220
"attributes": [...],
221
"members": [...]
222
}
223
],
224
"exports": [...]
225
}
226
]
227
}
228
```
229
230
### Global Access
231
232
The custom elements metadata is stored globally and can be accessed anywhere in your Storybook setup:
233
234
```typescript
235
import { getCustomElements } from "@storybook/web-components";
236
237
// In a decorator or story
238
const customElements = getCustomElements();
239
if (customElements) {
240
// Use the metadata for custom documentation or behavior
241
}
242
```
243
244
## Integration with Storybook Features
245
246
### Automatic Args Generation
247
248
When custom elements are configured, Storybook automatically generates controls and documentation:
249
250
```typescript
251
// Story file - no manual argTypes needed
252
const meta: Meta = {
253
title: "Components/MyButton",
254
component: "my-button", // Storybook will look up this component in the manifest
255
};
256
257
export default meta;
258
type Story = StoryObj;
259
260
// Controls and docs are automatically generated from the manifest
261
export const Default: Story = {};
262
263
export const Configured: Story = {
264
args: {
265
label: "Custom Label",
266
variant: "secondary",
267
disabled: false,
268
},
269
};
270
```
271
272
### Documentation Generation
273
274
Custom elements metadata enables rich documentation:
275
276
- **Controls**: Automatic control generation for attributes and properties
277
- **Args Table**: Displays all available props with types and descriptions
278
- **Events**: Shows available events that can be listened to
279
- **Slots**: Documents available content slots
280
- **CSS Custom Properties**: Lists customizable CSS properties
281
- **CSS Parts**: Shows styleable parts for component customization
282
283
### Error Handling
284
285
The validation functions provide helpful error messages:
286
287
```typescript
288
// Component validation errors
289
isValidComponent(null); // returns false
290
isValidComponent(""); // returns false
291
isValidComponent(123); // throws: "Provided component needs to be a string. e.g. component: \"my-element\""
292
293
// Metadata validation errors
294
isValidMetaData({}); // throws: "You need to setup valid meta data in your config.js via setCustomElements()..."
295
```