GitHub/storybook
1
0
Fork 0
mirror of https://github.com/storybookjs/storybook.git synced 2025-04-07 04:51:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

svelte docgen: enrich stories

Browse Source
This commit is contained in:
Taku Fukada 2024-07-12 16:53:10 +09:00
parent a4f4a6a2b0
commit 43bc7d51a7
No known key found for this signature in database
14 changed files with 354 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
code/frameworks/svelte-vite/package.json
View File

@ -47,6 +47,8 @@
"prep": "node --loader ../../../scripts/node_modules/esbuild-register/loader.js -r ../../../scripts/node_modules/esbuild-register/register.js ../../../scripts/prepare/bundle.ts"
},
"dependencies": {
"@babel/generator": "^7.24.8",
"@babel/parser": "^7.24.8",
"@babel/traverse": "^7.24.7",
"@storybook/builder-vite": "workspace:*",
"@storybook/svelte": "workspace:*",

112
code/frameworks/svelte-vite/src/plugins/generateDocgen.ts
View File

@ -20,10 +20,6 @@ export type PropInfo = {
runes?: boolean;
};
export type EventInfo = {
name: string;
};
type BaseType = {
/** Permits undefined or not */
optional?: boolean;
@ -32,41 +28,33 @@ type BaseType = {
type ScalarType = BaseType & {
type: 'number' | 'string' | 'boolean' | 'symbol' | 'any' | 'null';
};
type FunctionType = BaseType & {
type: 'function';
text: string;
};
type LiteralType = BaseType & {
type: 'literal';
value: string | number | boolean;
text: string;
};
type ArrayType = BaseType & {
type: 'array';
};
type ObjectType = BaseType & {
type: 'object';
};
type UnionType = BaseType & {
type: 'union';
types: Type[];
};
type IntersectionType = BaseType & {
type: 'intersection';
types: Type[];
};
type ReferenceType = BaseType & {
type: 'reference';
text: string;
};
type OtherType = BaseType & {
type: 'other';
text: string;
@ -84,7 +72,7 @@ export type Type =
| IntersectionType;
/**
* Try to infer a type from a initializer expression (for when there is no type annotation)
* Try to infer a type from an initializer expression (for when there is no type annotation)
*/
function inferTypeFromInitializer(expr: Expression): Type | undefined {
switch (expr.type) {
@ -171,11 +159,11 @@ function parseType(type: TSType): Type | undefined {
}
} else if (type.type == 'TSIntersectionType') {
// e.g. `A & B`
const types: Type[] = type.types
const types = type.types
.map((t) => {
return parseType(t);
})
.filter((t) => t !== undefined);
.filter((t) => t !== undefined) as Type[];
return { type: 'intersection', types };
}
return undefined;
@ -197,8 +185,7 @@ function tryParseJSDocType(text: string): Type | undefined {
for (const decl of stmt.declarations) {
if (decl.id.type == 'Identifier') {
if (decl.id.typeAnnotation?.type === 'TSTypeAnnotation') {
const a = parseType(decl.id.typeAnnotation.typeAnnotation);
return a;
return parseType(decl.id.typeAnnotation.typeAnnotation);
}
}
}
@ -207,7 +194,7 @@ function tryParseJSDocType(text: string): Type | undefined {
}
/**
* Extract JSDoc comments
* Parse JSDoc comments
*/
function parseComments(leadingComments?: Comment[] | null) {
if (!leadingComments) {
@ -267,7 +254,7 @@ export function generateDocgen(fileContent: string): Docgen {
}
const propMap: Map<string, PropInfo> = new Map();
// const events: EventInfo[] = [];
let propTypeName = '$$ComponentProps';
traverse(ast, {
FunctionDeclaration: (funcPath) => {
@ -275,38 +262,29 @@ export function generateDocgen(fileContent: string): Docgen {
return;
}
funcPath.traverse({
TSTypeAliasDeclaration(path) {
if (
path.node.id.name !== '$$ComponentProps' ||
path.node.typeAnnotation.type !== 'TSTypeLiteral'
) {
ReturnStatement: (path) => {
// For runes mode: Get the name of props type alias from `return { props: {} as MyProps, ... }`
if (path.parent !== funcPath.node.body) {
return;
}
const members = path.node.typeAnnotation.members;
members.forEach((member) => {
if (member.type === 'TSPropertySignature' && member.key.type === 'Identifier') {
const name = member.key.name;
const type =
member.typeAnnotation && member.typeAnnotation.type === 'TSTypeAnnotation'
? parseType(member.typeAnnotation.typeAnnotation)
: undefined;
if (type && member.optional) {
type.optional = true;
const argument = path.node.argument;
if (argument?.type === 'ObjectExpression') {
argument.properties.forEach((property) => {
if (property.type === 'ObjectProperty') {
if (property.key.type === 'Identifier' && property.key.name === 'props') {
if (property.value.type == 'TSAsExpression') {
const typeAnnotation = property.value.typeAnnotation;
if (
typeAnnotation?.type === 'TSTypeReference' &&
typeAnnotation.typeName.type === 'Identifier'
) {
propTypeName = typeAnnotation.typeName.name;
}
}
}
}
const { description } = parseComments(member.leadingComments);
propMap.set(name, {
...propMap.get(name),
name,
type: type,
description,
runes: true,
});
}
});
});
}
},
VariableDeclaration: (path) => {
if (path.node.kind !== 'let' || path.parent !== funcPath.node.body) {
@ -319,7 +297,7 @@ export function generateDocgen(fileContent: string): Docgen {
declaration.id.typeAnnotation &&
declaration.id.typeAnnotation.type === 'TSTypeAnnotation'
) {
// Get default values from Svelte 5's `let { ... } = $props();`
// For runes mode: Collect default values from `let { ... } = $props();`
const typeAnnotation = declaration.id.typeAnnotation.typeAnnotation;
if (
@ -350,7 +328,7 @@ export function generateDocgen(fileContent: string): Docgen {
}
});
} else if (declaration.id.type === 'Identifier') {
// Get props from Svelte 4's `export let a = ...`
// For legacy mode: Collect props info from `export let a = ...`
const name = declaration.id.name;
if (tsx.exportedNames.has(name)) {
@ -393,6 +371,40 @@ export function generateDocgen(fileContent: string): Docgen {
},
});
// For runes mode: Try to find and parse the props type alias.
traverse(ast, {
TSTypeAliasDeclaration(path) {
if (path.node.id.name !== propTypeName || path.node.typeAnnotation.type !== 'TSTypeLiteral') {
return;
}
const members = path.node.typeAnnotation.members;
members.forEach((member) => {
if (member.type === 'TSPropertySignature' && member.key.type === 'Identifier') {
const name = member.key.name;
const type =
member.typeAnnotation && member.typeAnnotation.type === 'TSTypeAnnotation'
? parseType(member.typeAnnotation.typeAnnotation)
: undefined;
if (type && member.optional) {
type.optional = true;
}
const { description } = parseComments(member.leadingComments);
propMap.set(name, {
...propMap.get(name),
name,
type: type,
description,
runes: true,
});
}
});
},
});
return {
props: Array.from(propMap.values()),
};

16
code/frameworks/svelte-vite/src/plugins/svelte-docgen.ts
View File

@ -3,7 +3,12 @@ import MagicString from 'magic-string';
import path from 'path';
import fs from 'fs';
import svelteDoc from 'sveltedoc-parser';
import type { SvelteComponentDoc, SvelteParserOptions, JSDocType } from 'sveltedoc-parser';
import type {
SvelteComponentDoc,
SvelteDataItem,
SvelteParserOptions,
JSDocType,
} from 'sveltedoc-parser';
import { logger } from 'storybook/internal/node-logger';
import { preprocess } from 'svelte/compiler';
import { replace, typescript } from 'svelte-preprocess';
@ -98,8 +103,8 @@ function formatToSvelteDocParserType(type: Type): JSDocType {
}
}
function emulateSvelteDocParserDataItems(docgen: Docgen) {
const data = docgen.props.map((p) => {
function transformToSvelteDocParserDataItems(docgen: Docgen): SvelteDataItem[] {
return docgen.props.map((p) => {
const required = p.runes && p.defaultValue === undefined && p.type && !p.type.optional;
return {
name: p.name,
@ -114,9 +119,8 @@ function emulateSvelteDocParserDataItems(docgen: Docgen) {
originalName: undefined,
localName: undefined,
defaultValue: p.defaultValue,
};
} satisfies SvelteDataItem;
});
return data;
}
export async function svelteDocgen(svelteOptions: Record<string, any> = {}): Promise<PluginOption> {
@ -140,7 +144,7 @@ export async function svelteDocgen(svelteOptions: Record<string, any> = {}): Pro
// Get props information
const docgen = generateDocgen(rawSource);
const hasRuneProps = docgen.props.some((p) => p.runes);
const data = emulateSvelteDocParserDataItems(docgen);
const data = transformToSvelteDocParserDataItems(docgen);
let componentDoc: SvelteComponentDoc & { keywords?: string[] } = {};

21
code/frameworks/svelte-vite/template/stories_svelte-vite-default-ts/ButtonTypeScript.svelte
View File

@ -7,6 +7,8 @@
// @ts-ignore
const Button = globalThis.Components?.Button;
import { createEventDispatcher } from 'svelte';
/**
* Rounds the button
*/
@ -23,14 +25,31 @@
*/
export let text: string = 'You clicked';
const dispatch = createEventDispatcher();
function handleClick(_event: MouseEvent) {
count += 1;
}
function onMouseHover(event) {
dispatch('mousehover', event);
}
</script>
<h1>Button TypeScript</h1>
<Button {primary} on:click on:click={handleClick} label="{text}: {count}" />
<Button
{primary}
on:click
on:click={handleClick}
on:mousehover={onMouseHover}
label="{text}: {count}"
/>
<!-- Default slot -->
<slot foo={count} />
<!-- Named slot -->
<slot name="namedSlot1" bar={text} />
<p>A little text to show this is a view.</p>
<p>If we need to test components in a Svelte environment, for instance to test slot behaviour,</p>

27
code/frameworks/sveltekit/template/stories_svelte-kit-prerelease-ts/ButtonTypeScript.svelte
View File

@ -7,6 +7,8 @@
// @ts-ignore
const Button = globalThis.Components?.Button;
import { createEventDispatcher } from 'svelte';
/**
* Rounds the button
*/
@ -23,14 +25,37 @@
*/
export let text: string = 'You clicked';
/**
* How large should the button be?
*/
export let size: 'large' | 'medium' | 'small' = 'medium';
const dispatch = createEventDispatcher();
function handleClick(_event: MouseEvent) {
count += 1;
}
function onMouseHover(event) {
dispatch('mousehover', event);
}
</script>
<h1>Button TypeScript</h1>
<Button {primary} on:click on:click={handleClick} label="{text}: {count}" />
<Button
{primary}
{size}
on:click
on:click={handleClick}
on:mousehover={onMouseHover}
label="{text}: {count}"
/>
<!-- Default slot -->
<slot foo={count} />
<!-- Named slot -->
<slot name="namedSlot1" bar={text} />
<p>A little text to show this is a view.</p>
<p>If we need to test components in a Svelte environment, for instance to test slot behaviour,</p>

1
code/frameworks/sveltekit/template/stories_svelte-kit-prerelease-ts/ButtonTypeScriptRunes.svelte → code/frameworks/sveltekit/template/stories_svelte-kit-prerelease-ts/ButtonTypeScriptRunes1.svelte
View File

@ -9,6 +9,7 @@
children,
label,
}: {
/**
* Is this the principal call to action on the page?
*/

55
code/frameworks/sveltekit/template/stories_svelte-kit-prerelease-ts/ButtonTypeScriptRunes2.svelte Normal file
View File

@ -0,0 +1,55 @@
<script lang="ts">
import type { Snippet } from "svelte";
type MyProps = {
/**
* Is this the principal call to action on the page?
*/
primary?: boolean;
/**
* What background color to use
*/
backgroundColor?: string;
/**
* How large should the button be?
*/
size?: 'small' | 'medium' | 'large';
/**
* Snippet contents
*/
children?: Snippet;
/**
* Text contents
*/
label: string;
/**
* Click handler
*/
onclick?: () => void;
};
let {
primary = true,
backgroundColor,
size = 'medium',
onclick,
children,
label,
}: MyProps = $props();
let mode = $derived(primary ? 'storybook-button--primary' : 'storybook-button--secondary');
let style = $derived(backgroundColor ? `background-color: ${backgroundColor}` : '');
</script>
<button
type="button"
class={['storybook-button', `storybook-button--${size}`, mode].join(' ')}
{style}
{onclick}
>
{#if label}
{label}
{:else if children}
{@render children()}
{/if}
</button>

4
code/frameworks/sveltekit/template/stories_svelte-kit-prerelease-ts/ts-runes-docs.stories.js → code/frameworks/sveltekit/template/stories_svelte-kit-prerelease-ts/ts-runes1-docs.stories.js
View File

@ -1,7 +1,7 @@
import ButtonTypescriptRunes from './ButtonTypeScriptRunes.svelte';
import ButtonTypescriptRunes from './ButtonTypeScriptRunes1.svelte';
export default {
title: 'stories/renderers/svelte/ts-runes-docs',
title: 'stories/renderers/svelte/ts-runes1-docs',
component: ButtonTypescriptRunes,
args: {
primary: true,

13
code/frameworks/sveltekit/template/stories_svelte-kit-prerelease-ts/ts-runes2-docs.stories.js Normal file
View File

@ -0,0 +1,13 @@
import ButtonTypescriptRunes from './ButtonTypeScriptRunes2.svelte';
export default {
title: 'stories/renderers/svelte/ts-runes2-docs',
component: ButtonTypescriptRunes,
args: {
primary: true,
label: 'Button',
},
tags: ['autodocs'],
};
export const Primary = {};

21
code/frameworks/sveltekit/template/stories_svelte-kit-skeleton-ts/ButtonTypeScript.svelte
View File

@ -7,6 +7,8 @@
// @ts-ignore
const Button = globalThis.Components?.Button;
import { createEventDispatcher } from 'svelte';
/**
* Rounds the button
*/
@ -23,14 +25,31 @@
*/
export let text: string = 'You clicked';
const dispatch = createEventDispatcher();
function handleClick(_event: MouseEvent) {
count += 1;
}
function onMouseHover(event) {
dispatch('mousehover', event);
}
</script>
<h1>Button TypeScript</h1>
<Button {primary} on:click on:click={handleClick} label="{text}: {count}" />
<Button
{primary}
on:click
on:click={handleClick}
on:mousehover={onMouseHover}
label="{text}: {count}"
/>
<!-- Default slot -->
<slot foo={count} />
<!-- Named slot -->
<slot name="namedSlot1" bar={text} />
<p>A little text to show this is a view.</p>
<p>If we need to test components in a Svelte environment, for instance to test slot behaviour,</p>

11
code/renderers/svelte/template/stories/jsdoc-docs.stories.js Normal file
View File

@ -0,0 +1,11 @@
import ButtonJavaScript from './views/ButtonJSDoc.svelte';
export default {
component: ButtonJavaScript,
args: {
primary: true,
},
tags: ['autodocs'],
};
export const Primary = {};

64
code/renderers/svelte/template/stories/views/ButtonJSDoc.svelte Normal file
View File

@ -0,0 +1,64 @@
<script>
/**
* @component Button View
* @wrapper
*/
import { global as globalThis } from '@storybook/global';
// @ts-ignore
const Button = globalThis.Components?.Button;
import { createEventDispatcher } from 'svelte';
/**
* @type {boolean} Rounds the button
*/
export let primary = false;
/**
* @type {number} Counter
*/
export let count = 0;
/**
* How large should the button be?
* @type {'large' | 'medium' | 'small'}
*/
export let size = 'medium';
/**
* Button text
* @slot
*/
export let text = 'You clicked';
const dispatch = createEventDispatcher();
function handleClick(_event) {
count += 1;
}
function onMouseHover(event) {
dispatch('mousehover', event);
}
</script>
<h1>Button view</h1>
<Button
{primary}
{size}
on:click
on:click={handleClick}
on:mousehover={onMouseHover}
label="{text}: {count}"
/>
<!-- Default slot -->
<slot foo={count} />
<!-- Named slot -->
<slot name="namedSlot1" bar={text} />
<p>A little text to show this is a view.</p>
<p>If we need to test components in a Svelte environment, for instance to test slot behaviour,</p>
<p>then wrapping the component up in a view</p>
<p>made just for the story is the simplest way to achieve this.</p>

29
code/renderers/svelte/template/stories/views/ButtonJavaScript.svelte
View File

@ -7,6 +7,8 @@
// @ts-ignore
const Button = globalThis.Components?.Button;
import { createEventDispatcher } from 'svelte';
/**
* Rounds the button
*/
@ -15,7 +17,12 @@
/**
* Displays the count
*/
let count = 0;
export let count = 0;
/**
* How large should the button be?
*/
export let size = 'medium';
/**
* Button text
@ -23,14 +30,32 @@
*/
export let text = 'You clicked';
const dispatch = createEventDispatcher();
function handleClick(_event) {
count += 1;
}
function onMouseHover(event) {
dispatch('mousehover', event);
}
</script>
<h1>Button view</h1>
<Button {primary} on:click on:click={handleClick} label="{text}: {count}" />
<Button
{primary}
{size}
on:click
on:click={handleClick}
on:mousehover={onMouseHover}
label="{text}: {count}"
/>
<!-- Default slot -->
<slot foo={count} />
<!-- Named slot -->
<slot name="namedSlot1" bar={text} />
<p>A little text to show this is a view.</p>
<p>If we need to test components in a Svelte environment, for instance to test slot behaviour,</p>

41
code/yarn.lock
View File

@ -470,6 +470,18 @@ __metadata:
languageName: node
linkType: hard
"@babel/generator@npm:^7.24.8":
version: 7.24.8
resolution: "@babel/generator@npm:7.24.8"
dependencies:
"@babel/types": "npm:^7.24.8"
"@jridgewell/gen-mapping": "npm:^0.3.5"
"@jridgewell/trace-mapping": "npm:^0.3.25"
jsesc: "npm:^2.5.1"
checksum: 10c0/e8a278e75a895f13a7b17dd79abe1e894fe82a5ed3abb127c33c14c66773d69993762521c094c6c364723f8f7375683b0d4a96097781175a29407baedf67b769
languageName: node
linkType: hard
"@babel/helper-annotate-as-pure@npm:7.22.5":
version: 7.22.5
resolution: "@babel/helper-annotate-as-pure@npm:7.22.5"
@ -723,6 +735,13 @@ __metadata:
languageName: node
linkType: hard
"@babel/helper-string-parser@npm:^7.24.8":
version: 7.24.8
resolution: "@babel/helper-string-parser@npm:7.24.8"
checksum: 10c0/6361f72076c17fabf305e252bf6d580106429014b3ab3c1f5c4eb3e6d465536ea6b670cc0e9a637a77a9ad40454d3e41361a2909e70e305116a23d68ce094c08
languageName: node
linkType: hard
"@babel/helper-validator-identifier@npm:^7.24.7":
version: 7.24.7
resolution: "@babel/helper-validator-identifier@npm:7.24.7"
@ -780,6 +799,15 @@ __metadata:
languageName: node
linkType: hard
"@babel/parser@npm:^7.24.8":
version: 7.24.8
resolution: "@babel/parser@npm:7.24.8"
bin:
parser: ./bin/babel-parser.js
checksum: 10c0/ce69671de8fa6f649abf849be262707ac700b573b8b1ce1893c66cc6cd76aeb1294a19e8c290b0eadeb2f47d3f413a2e57a281804ffbe76bfb9fa50194cf3c52
languageName: node
linkType: hard
"@babel/plugin-bugfix-firefox-class-in-computed-class-key@npm:^7.24.7":
version: 7.24.7
resolution: "@babel/plugin-bugfix-firefox-class-in-computed-class-key@npm:7.24.7"
@ -2278,6 +2306,17 @@ __metadata:
languageName: node
linkType: hard
"@babel/types@npm:^7.24.8":
version: 7.24.8
resolution: "@babel/types@npm:7.24.8"
dependencies:
"@babel/helper-string-parser": "npm:^7.24.8"
"@babel/helper-validator-identifier": "npm:^7.24.7"
to-fast-properties: "npm:^2.0.0"
checksum: 10c0/2d7bf561ae993e794cb052c5a81d3a6d1877da13e1e2eb2a59ae75a8fb1c965b618fb3e4abd42548f5f9a4587d3a149185a32d6c4c4ea82195da7dd86f2da0f1
languageName: node
linkType: hard
"@base2/pretty-print-object@npm:1.0.1":
version: 1.0.1
resolution: "@base2/pretty-print-object@npm:1.0.1"
@ -6654,6 +6693,8 @@ __metadata:
version: 0.0.0-use.local
resolution: "@storybook/svelte-vite@workspace:frameworks/svelte-vite"
dependencies:
"@babel/generator": "npm:^7.24.8"
"@babel/parser": "npm:^7.24.8"
"@babel/traverse": "npm:^7.24.7"
"@storybook/builder-vite": "workspace:*"
"@storybook/svelte": "workspace:*"