0
# Advanced Functions
1

2
Internal and advanced utility functions for custom elements metadata processing and documentation generation. These functions are primarily used by Storybook's documentation addon but can be useful for advanced integrations.
3

4
## Core Imports
5

6
```typescript
7
import { 
8
  extractArgTypesFromElements, 
9
  extractArgTypes, 
10
  extractComponentDescription 
11
} from "@storybook/web-components";
12
```
13

14
## Capabilities
15

16
### Documentation Generation
17

18
Functions for extracting component information from custom elements manifests for documentation purposes.
19

20
```typescript { .api }
21
/**
22
 * Extracts arg types from custom elements manifest for a specific component.
23
 * @param tagName - The component tag name to extract arg types for
24
 * @param customElements - Custom elements manifest object
25
 * @returns Extracted arg types configuration object
26
 */
27
function extractArgTypesFromElements(
28
  tagName: string, 
29
  customElements: CustomElements
30
): Record<string, any>;
31

32
/**
33
 * Extracts arg types for a component from the global custom elements manifest.
34
 * @param tagName - The component tag name to extract arg types for
35
 * @returns Extracted arg types configuration object, or undefined if not found
36
 */
37
function extractArgTypes(tagName: string): Record<string, any> | undefined;
38

39
/**
40
 * Extracts component description from custom elements manifest.
41
 * @param tagName - The component tag name to get description for
42
 * @returns Component description string, or undefined if not found
43
 */
44
function extractComponentDescription(tagName: string): string | undefined;
45
```
46

47
## Usage Patterns
48

49
### Custom Documentation Integration
50

51
These functions are useful when building custom documentation tools or integrations:
52

53
```typescript
54
import { 
55
  extractArgTypes, 
56
  extractComponentDescription,
57
  getCustomElements 
58
} from "@storybook/web-components";
59

60
// Get component information for custom docs
61
const componentInfo = {
62
  tagName: "my-button",
63
  description: extractComponentDescription("my-button"),
64
  argTypes: extractArgTypes("my-button"),
65
};
66

67
console.log(componentInfo);
68
// {
69
//   tagName: "my-button",
70
//   description: "A customizable button component",
71
//   argTypes: {
72
//     label: { control: "text", description: "Button label text" },
73
//     variant: { control: "select", options: ["primary", "secondary"] }
74
//   }
75
// }
76
```
77

78
### Manual Arg Types Processing
79

80
When you need to process custom elements manifest data manually:
81

82
```typescript
83
import { extractArgTypesFromElements } from "@storybook/web-components";
84
import customElementsManifest from "./custom-elements.json";
85

86
// Extract arg types from a specific manifest (not global)
87
const argTypes = extractArgTypesFromElements("my-component", customElementsManifest);
88

89
// Use the extracted arg types in your own story configuration
90
const meta: Meta = {
91
  title: "Components/MyComponent",
92
  component: "my-component",
93
  argTypes, // Use the manually extracted arg types
94
};
95
```
96

97
### Component Validation Workflow
98

99
Combine these functions with validation functions for comprehensive component checking:
100

101
```typescript
102
import { 
103
  isValidComponent, 
104
  extractComponentDescription, 
105
  extractArgTypes 
106
} from "@storybook/web-components";
107

108
function validateAndDescribeComponent(tagName: string) {
109
  // First validate the component name
110
  if (!isValidComponent(tagName)) {
111
    throw new Error(`Invalid component: ${tagName}`);
112
  }
113
  
114
  // Extract documentation information
115
  const description = extractComponentDescription(tagName);
116
  const argTypes = extractArgTypes(tagName);
117
  
118
  if (!description || !argTypes) {
119
    console.warn(`Limited documentation available for ${tagName}`);
120
  }
121
  
122
  return {
123
    tagName,
124
    description: description || "No description available",
125
    argTypes: argTypes || {},
126
    hasDocumentation: !!(description && argTypes),
127
  };
128
}
129

130
// Use in component discovery
131
const componentInfo = validateAndDescribeComponent("my-button");
132
```
133

134
## Integration with Storybook Features
135

136
### Automatic Documentation
137

138
These functions power Storybook's automatic documentation generation:
139

140
- **Args Table**: Uses `extractArgTypes` to populate the props table
141
- **Component Description**: Uses `extractComponentDescription` for component docs
142
- **Controls**: Uses arg types to generate appropriate control types
143

144
### Custom Addons
145

146
When building custom Storybook addons that need component metadata:
147

148
```typescript
149
// In a custom addon
150
import { extractArgTypes, extractComponentDescription } from "@storybook/web-components";
151

152
export const myAddon = (context) => {
153
  const { component } = context.parameters;
154
  
155
  if (typeof component === "string") {
156
    const argTypes = extractArgTypes(component);
157
    const description = extractComponentDescription(component);
158
    
159
    // Use the extracted information in your addon logic
160
    return {
161
      argTypes,
162
      description,
163
      // ... other addon functionality
164
    };
165
  }
166
};
167
```
168

169
## Custom Elements Manifest Format
170

171
These functions work with both supported manifest formats:
172

173
### Tags-based Format (Experimental)
174
```json
175
{
176
  "version": "experimental",
177
  "tags": [
178
    {
179
      "name": "my-element",
180
      "description": "Element description",
181
      "attributes": [
182
        {
183
          "name": "label",
184
          "type": { "text": "string" },
185
          "description": "Button label"
186
        }
187
      ]
188
    }
189
  ]
190
}
191
```
192

193
### Modules-based Format (v1)
194
```json
195
{
196
  "modules": [
197
    {
198
      "declarations": [
199
        {
200
          "tagName": "my-element",
201
          "description": "Element description",
202
          "attributes": [
203
            {
204
              "name": "label",
205
              "type": { "text": "string" },
206
              "description": "Button label"
207
            }
208
          ]
209
        }
210
      ]
211
    }
212
  ]
213
}
214
```
215

216
## Error Handling
217

218
These functions are designed to be resilient:
219

220
```typescript
221
// Functions return undefined for missing components
222
const argTypes = extractArgTypes("non-existent-component");
223
console.log(argTypes); // undefined
224

225
const description = extractComponentDescription("non-existent-component");
226
console.log(description); // undefined
227

228
// They don't throw errors, allowing graceful degradation
229
```
230

231
## Performance Considerations
232

233
- These functions read from the global custom elements manifest
234
- Results are not cached, so consider caching in performance-critical scenarios
235
- The manifest is parsed each time, so avoid calling repeatedly in tight loops
236

237
```typescript
238
// Good: Cache results when processing multiple components
239
const componentsInfo = componentList.map(tagName => ({
240
  tagName,
241
  argTypes: extractArgTypes(tagName),
242
  description: extractComponentDescription(tagName),
243
}));
244

245
// Less optimal: Repeated calls in a loop without caching
246
componentList.forEach(tagName => {
247
  const argTypes = extractArgTypes(tagName); // Repeated manifest parsing
248
  // ... process each component
249
});
250
```