0
# Framework Integration
1

2
Framework-specific utilities and components for extracting documentation from Angular, Vue, Svelte, Ember, and Web Components, providing specialized features tailored to each ecosystem's conventions and patterns.
3

4
## Capabilities
5

6
### Angular Integration
7

8
Angular-specific documentation extraction using Compodoc integration for comprehensive component documentation.
9

10
```typescript { .api }
11
/**
12
 * Sets Compodoc documentation JSON for Angular components
13
 * Enables automatic props table generation and component description extraction
14
 * @param compodocJson - Compodoc generated JSON documentation
15
 */
16
function setCompodocJson(compodocJson: CompodocJson): void;
17

18
interface CompodocJson {
19
  /** Component documentation entries */
20
  components?: CompodocComponent[];  
21
  /** Directive documentation entries */
22
  directives?: CompodocDirective[];
23
  /** Injectable service documentation */
24
  injectables?: CompodocInjectable[];
25
  /** Interface definitions */
26
  interfaces?: CompodocInterface[];
27
  /** Type alias definitions */
28
  typealiases?: CompodocTypeAlias[];
29
  /** Module documentation */
30
  modules?: CompodocModule[];
31
  [key: string]: any;
32
}
33

34
interface CompodocComponent {
35
  /** Component name */
36
  name: string;
37
  /** Component selector */
38
  selector: string;
39
  /** Component description */
40
  description?: string;
41
  /** Input properties */
42
  inputsClass?: CompodocProperty[];
43
  /** Output events */
44
  outputsClass?: CompodocProperty[];
45
  /** Component methods */
46
  methodsClass?: CompodocMethod[];
47
  /** File path */
48
  file: string;
49
  /** TypeScript source */
50
  sourceCode?: string;
51
}
52

53
interface CompodocProperty {
54
  /** Property name */
55
  name: string;
56
  /** Property type */
57
  type: string;
58
  /** Default value */
59
  defaultValue?: string;
60
  /** Property description */
61
  description?: string;
62
  /** Whether property is optional */
63
  optional?: boolean;
64
  /** Decorators applied */
65
  decorators?: CompodocDecorator[];
66
}
67

68
interface CompodocMethod {
69
  /** Method name */
70
  name: string;
71
  /** Return type */
72
  returnType: string;
73
  /** Method parameters */
74
  args?: CompodocMethodArg[];
75
  /** Method description */
76
  description?: string;
77
}
78

79
interface CompodocMethodArg {
80
  /** Parameter name */
81
  name: string;
82
  /** Parameter type */
83
  type: string;
84
  /** Whether parameter is optional */
85
  optional?: boolean;
86
}
87

88
interface CompodocDecorator {
89
  /** Decorator name */
90
  name: string;
91
  /** Decorator options */
92
  stringifiedOptions?: string;
93
}
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
// Configure Angular docs in .storybook/preview.js
100
import { setCompodocJson } from "@storybook/addon-docs/angular";
101
import docJson from "../documentation.json";
102

103
setCompodocJson(docJson);
104

105
export const parameters = {
106
  docs: {
107
    extractComponentDescription: (component, { notes }) => {
108
      if (notes) {
109
        return typeof notes === 'string' ? notes : notes.markdown || notes.text;
110
      }
111
      return null;
112
    },
113
  },
114
};
115
```
116

117
### Ember Integration
118

119
Ember-specific documentation extraction for Ember components and templates.
120

121
```typescript { .api }
122
/**
123
 * Sets Ember documentation JSON for component extraction
124
 * Enables automatic props and component documentation for Ember components  
125
 * @param jsonDoc - Ember documentation JSON structure
126
 */
127
function setJSONDoc(jsonDoc: EmberDocJson): void;
128

129
interface EmberDocJson {
130
  /** Component documentation entries */
131
  components?: EmberComponent[];
132
  /** Helper function documentation */
133
  helpers?: EmberHelper[];
134
  /** Service documentation */
135
  services?: EmberService[];
136
  /** Modifier documentation */
137
  modifiers?: EmberModifier[];
138
  [key: string]: any;
139
}
140

141
interface EmberComponent {
142
  /** Component name */
143
  name: string;
144
  /** Component description */
145
  description?: string;
146
  /** Component arguments */
147
  arguments?: EmberArgument[];
148
  /** Component attributes */
149
  attributes?: EmberAttribute[];
150
  /** Yielded values */
151
  yields?: EmberYield[];
152
  /** File location */
153
  file?: string;
154
}
155

156
interface EmberArgument {
157
  /** Argument name */
158
  name: string;
159
  /** Argument type */
160
  type: string;
161
  /** Argument description */
162
  description?: string;
163
  /** Whether argument is required */
164
  required?: boolean;
165
  /** Default value */
166
  defaultValue?: string;
167
}
168

169
interface EmberAttribute {
170
  /** Attribute name */
171
  name: string;
172
  /** Attribute type */
173
  type: string;
174
  /** Attribute description */
175
  description?: string;
176
}
177

178
interface EmberYield {
179
  /** Yield name */
180
  name: string;
181
  /** Yielded type */
182
  type: string;
183
  /** Yield description */
184
  description?: string;
185
}
186
```
187

188
### Svelte Integration
189

190
Svelte Higher-Order Component for documentation integration and component wrapping.
191

192
```typescript { .api }
193
/**
194
 * Svelte Higher-Order Component for docs integration
195
 * Provides wrapper functionality for Svelte components in Storybook
196
 * Located at: svelte/HOC.svelte
197
 */
198
interface SvelteHOC {
199
  /** Wrapped component */
200
  component: SvelteComponent;
201
  /** Component props */
202
  props?: Record<string, any>;
203
  /** Event handlers */
204
  on?: Record<string, (event: any) => void>;
205
  /** Slot content */
206
  slots?: Record<string, any>;
207
}
208

209
// Usage in Svelte stories
210
// import HOC from "@storybook/addon-docs/svelte/HOC.svelte";
211
```
212

213
### Web Components Integration
214

215
Utilities for documenting Web Components with custom element definitions and properties.
216

217
```typescript { .api }
218
/**
219
 * Sets custom elements manifest data for documentation extraction
220
 * Available from @storybook/web-components renderer package
221
 * @param customElementsManifest - Custom Elements Manifest data
222
 */
223
function setCustomElementsManifest(customElementsManifest: CustomElementsManifest): void;
224

225
/**
226
 * Alternative function name for setting custom elements data
227
 * @param customElements - Custom elements data
228
 */
229
function setCustomElements(customElements: any): void;
230

231
/**
232
 * Gets current custom elements data
233
 * @returns Current custom elements data or manifest
234
 */
235
function getCustomElements(): any;
236

237
interface CustomElementsManifest {
238
  /** Schema version */
239
  version?: string;
240
  /** Modules containing custom element declarations */
241
  modules?: Module[];
242
  /** Package metadata */
243
  package?: PackageMetadata;
244
}
245

246
interface Module {
247
  /** Module path */
248
  path?: string;
249
  /** Exported declarations */
250
  exports?: Export[];
251
  /** Declarations in this module */
252
  declarations?: Declaration[];
253
}
254

255
interface Declaration {
256
  /** Declaration kind */
257
  kind: string;
258
  /** Declaration name */
259
  name: string;
260
  /** Custom element tag name */
261
  tagName?: string;
262
  /** Description */
263
  description?: string;
264
  /** Class members */
265
  members?: Member[];
266
  /** Events */
267
  events?: Event[];
268
  /** Slots */
269
  slots?: Slot[];
270
  /** CSS properties */
271
  cssProperties?: CSSProperty[];
272
}
273

274
interface Member {
275
  /** Member kind */
276
  kind: string;
277
  /** Member name */
278
  name: string;
279
  /** Member type */
280
  type?: { text: string };
281
  /** Description */
282
  description?: string;
283
  /** Default value */
284
  default?: string;
285
  /** Corresponding attribute name */
286
  attribute?: string;
287
  /** Whether property reflects to attribute */
288
  reflects?: boolean;
289
}
290

291
// Web Components documentation extraction  
292
interface WebComponentDocs {
293
  /** Custom element tag name */
294
  tagName: string;
295
  /** Element description */
296
  description?: string;
297
  /** Element properties */
298
  properties?: WebComponentProperty[];
299
  /** Element attributes */
300
  attributes?: WebComponentAttribute[];  
301
  /** Element events */
302
  events?: WebComponentEvent[];
303
  /** Element slots */
304
  slots?: WebComponentSlot[];
305
  /** CSS custom properties */
306
  cssProperties?: WebComponentCSSProperty[];
307
}
308

309
interface WebComponentProperty {
310
  /** Property name */
311
  name: string;
312
  /** Property type */
313
  type: string;
314
  /** Property description */
315
  description?: string;
316
  /** Default value */
317
  default?: any;
318
  /** Whether property reflects to attribute */
319
  reflects?: boolean;
320
  /** Associated attribute name */
321
  attribute?: string;
322
}
323

324
interface WebComponentAttribute {
325
  /** Attribute name */
326
  name: string;
327
  /** Attribute type */
328
  type: string;
329
  /** Attribute description */
330
  description?: string;
331
  /** Default value */
332
  default?: string;
333
}
334

335
interface WebComponentEvent {
336
  /** Event name */
337
  name: string;
338
  /** Event type */
339
  type: string;
340
  /** Event description */
341
  description?: string;
342
  /** Event detail type */
343
  detail?: string;
344
}
345

346
interface WebComponentSlot {
347
  /** Slot name */
348
  name: string;
349
  /** Slot description */
350
  description?: string;
351
}
352

353
interface WebComponentCSSProperty {
354
  /** CSS property name */
355
  name: string;
356
  /** Property description */
357
  description?: string;
358
  /** Default value */
359
  default?: string;
360
  /** Property syntax */
361
  syntax?: string;
362
}
363
```
364

365
## Framework-Specific Usage Patterns
366

367
### Angular with Compodoc
368

369
Complete setup for Angular component documentation using Compodoc.
370

371
```typescript
372
// Generate Compodoc documentation
373
// npm run compodoc -- -p ./tsconfig.json -e json -d .
374

375
// .storybook/preview.js
376
import { setCompodocJson } from "@storybook/addon-docs/angular";
377
import docJson from "../documentation.json";
378

379
setCompodocJson(docJson);
380

381
// Story example with Angular component
382
export default {
383
  title: "Components/Button",
384
  component: ButtonComponent,
385
  parameters: {
386
    docs: {
387
      description: {
388
        component: "A reusable button component with multiple variants",
389
      },
390
    },
391
  },
392
  argTypes: {
393
    variant: {
394
      control: { type: "select" },
395
      options: ["primary", "secondary", "danger"],
396
    },
397
    disabled: {
398
      control: { type: "boolean" },
399
    },
400
  },
401
};
402

403
export const Primary = {
404
  args: {
405
    label: "Primary Button",
406
    variant: "primary",
407
    disabled: false,
408
  },
409
};
410
```
411

412
### Ember Component Documentation
413

414
Setting up Ember component documentation with automatic extraction.
415

416
```typescript  
417
// .storybook/preview.js
418
import { setJSONDoc } from "@storybook/addon-docs/ember";
419
import emberDocJson from "../ember-docs.json";
420

421
setJSONDoc(emberDocJson);
422

423
// Ember story example
424
export default {
425
  title: "Components/Card",
426
  component: "ui-card",
427
  parameters: {
428
    docs: {
429
      description: {
430
        component: "A flexible card component for displaying content",
431
      },
432
    },
433
  },
434
};
435

436
export const Default = {
437
  args: {
438
    title: "Card Title",
439
    content: "Card content goes here",
440
    actions: true,
441
  },
442
  render: (args) => ({
443
    template: hbs`
444
      <UiCard 
445
        @title={{this.title}}
446
        @content={{this.content}} 
447
        @showActions={{this.actions}}
448
      />
449
    `,
450
    context: args,
451
  }),
452
};
453
```
454

455
### Svelte Component Integration
456

457
Using the Svelte HOC for component documentation and story creation.
458

459
```javascript
460
// Button.stories.js
461
import Button from "./Button.svelte";
462
import HOC from "@storybook/addon-docs/svelte/HOC.svelte";
463

464
export default {
465
  title: "Components/Button",
466
  component: HOC,
467
  parameters: {
468
    docs: {
469
      description: {
470
        component: "A Svelte button component with customizable styling",
471
      },
472
    },
473
  },
474
};
475

476
export const Primary = {
477
  args: {
478
    component: Button,
479
    props: {
480
      label: "Primary Button",
481
      variant: "primary",
482
      disabled: false,
483
    },
484
  },
485
};
486
```
487

488
### Web Components Documentation
489

490
Documenting custom elements with automatic property extraction.
491

492
```typescript
493
// .storybook/preview.js
494
import { setCustomElementsManifest } from "@storybook/web-components";
495
import customElementsManifest from "../custom-elements.json";
496

497
// Set custom elements manifest for documentation
498
setCustomElementsManifest(customElementsManifest);
499

500
// Alternative: Direct manifest setup
501
setCustomElementsManifest({
502
  version: "experimental",
503
  modules: [
504
    {
505
      declarations: [
506
        {
507
          kind: "class",
508
          name: "MyButton",
509
          tagName: "my-button",
510
          description: "A custom button element",
511
          members: [
512
            {
513
              kind: "field",
514
              name: "variant",
515
              type: { text: "string" },
516
              description: "Button variant style",
517
              default: '"primary"',
518
              attribute: "variant"
519
            },
520
            {
521
              kind: "field",
522
              name: "disabled",
523
              type: { text: "boolean" },
524
              description: "Whether button is disabled",
525
              default: "false",
526
              reflects: true
527
            }
528
          ],
529
          events: [
530
            {
531
              name: "click",
532
              type: { text: "CustomEvent" },
533
              description: "Fired when button is clicked"
534
            }
535
          ]
536
        }
537
      ]
538
    }
539
  ]
540
});
541

542
// Web Component story
543
export default {
544
  title: "Components/MyButton",
545
  component: "my-button",
546
  parameters: {
547
    docs: {
548
      description: {
549
        component: "Custom button web component with accessibility features",
550
      },
551
    },
552
  },
553
};
554

555
export const Primary = {
556
  args: {
557
    variant: "primary",
558
    disabled: false,
559
  },
560
  render: (args) => 
561
    `<my-button variant="${args.variant}" ${args.disabled ? 'disabled' : ''}>
562
       Click me
563
     </my-button>`,
564
};
565
```
566

567
## Common Integration Patterns
568

569
### Cross-Framework Type Definitions
570

571
Shared type definitions used across framework integrations.
572

573
```typescript { .api }
574
interface FrameworkComponent {
575
  /** Component name */
576
  name: string;
577
  /** Component description */
578
  description?: string;
579
  /** Component properties/inputs */
580
  props?: FrameworkProperty[];
581
  /** Component events/outputs */
582
  events?: FrameworkEvent[];
583
  /** Component slots/content projection */
584
  slots?: FrameworkSlot[];
585
}
586

587
interface FrameworkProperty {
588
  /** Property name */
589
  name: string;
590
  /** Property type */
591
  type: string;
592
  /** Property description */
593
  description?: string;
594
  /** Default value */
595
  defaultValue?: any;
596
  /** Whether property is required */
597
  required?: boolean;
598
}
599

600
interface FrameworkEvent {
601
  /** Event name */
602
  name: string;
603
  /** Event type */
604
  type: string;
605
  /** Event description */
606
  description?: string;
607
  /** Event payload type */
608
  detail?: string;
609
}
610

611
interface FrameworkSlot {
612
  /** Slot name */
613
  name: string;
614
  /** Slot description */
615
  description?: string;
616
  /** Slot content type */
617
  type?: string;
618
}
619
```