From b4f2b674c6587c7f89872a6408a988d20b6959a9 Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Fri, 7 Nov 2025 15:42:09 +0000 Subject: [PATCH] Docs: Fix Svelte references --- ...onent-story-with-custom-render-function.md | 28 ++++ .../svelte-framework-options-docgen.md | 27 ++++ docs/_snippets/sveltekit-mock-features.md | 142 ++++++++++++++++++ docs/_snippets/sveltekit-mock-links.md | 118 +++++++++++++++ docs/api/csf/index.mdx | 13 ++ docs/get-started/frameworks/svelte-vite.mdx | 21 +-- docs/get-started/frameworks/sveltekit.mdx | 139 ++++++----------- 7 files changed, 382 insertions(+), 106 deletions(-) create mode 100644 docs/_snippets/svelte-framework-options-docgen.md create mode 100644 docs/_snippets/sveltekit-mock-features.md create mode 100644 docs/_snippets/sveltekit-mock-links.md diff --git a/docs/_snippets/component-story-with-custom-render-function.md b/docs/_snippets/component-story-with-custom-render-function.md index 6dcfb9b69e08..22469fcfd584 100644 --- a/docs/_snippets/component-story-with-custom-render-function.md +++ b/docs/_snippets/component-story-with-custom-render-function.md @@ -325,3 +325,31 @@ export const Example = meta.story({ ), }); ``` + +```svelte filename="MyComponent.stories.svelte" renderer="svelte" language="js" + + + + {#snippet template(args)} + +
+

Example

+
+
+ +
+ + {/snippet} + +``` diff --git a/docs/_snippets/svelte-framework-options-docgen.md b/docs/_snippets/svelte-framework-options-docgen.md new file mode 100644 index 000000000000..ed1eb1da1d65 --- /dev/null +++ b/docs/_snippets/svelte-framework-options-docgen.md @@ -0,0 +1,27 @@ +```js filename=".storybook/main.js" renderer="svelte" language="js" +// Replace your-framework with svelte-vite or sveltekit +export default { + framework: { + name: '@storybook/your-framework', + options: { + docgen: false, // Disable docgen for better performance + }, + }, +}; +``` + +```ts filename=".storybook/main.ts" renderer="svelte" language="ts" +// Replace your-framework with svelte-vite or sveltekit +import type { StorybookConfig } from '@storybook/your-framework'; + +const config: StorybookConfig = { + framework: { + name: '@storybook/your-framework', + options: { + docgen: false, // Disable docgen for better performance + }, + }, +}; + +export default config; +``` diff --git a/docs/_snippets/sveltekit-mock-features.md b/docs/_snippets/sveltekit-mock-features.md new file mode 100644 index 000000000000..d6133ef12447 --- /dev/null +++ b/docs/_snippets/sveltekit-mock-features.md @@ -0,0 +1,142 @@ +```svelte filename="MyComponent.stories.svelte" renderer="svelte" language="js" tabTitle="Svelte CSF" + + + +``` + +```js filename="MyComponent.stories.js" renderer="svelte" language="js" tabTitle="CSF" +import MyComponent from './MyComponent.svelte'; + +export default { + component: MyComponent, +}; + +export const MyStory = { + parameters: { + sveltekit_experimental: { + state: { + page: { + data: { + test: 'passed', + }, + }, + navigating: { + to: { + route: { id: '/storybook' }, + params: {}, + url: new URL('http://localhost/storybook'), + }, + }, + updated: { + current: true, + }, + }, + }, + }, +}; +``` + +```svelte filename="MyComponent.stories.svelte" renderer="svelte" language="ts" tabTitle="Svelte CSF" + + + +``` + +```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts" tabTitle="CSF" +import type { Meta, StoryObj } from '@storybook/sveltekit'; + +import MyComponent from './MyComponent.svelte'; + +const meta = { + component: MyComponent, +} satisfies Meta; + +export default meta; +type Story = StoryObj; + +export const MyStory: Story = { + parameters: { + sveltekit_experimental: { + state: { + page: { + data: { + test: 'passed', + }, + }, + navigating: { + to: { + route: { id: '/storybook' }, + params: {}, + url: new URL('http://localhost/storybook'), + }, + }, + updated: { + current: true, + }, + }, + }, + }, +}; +``` diff --git a/docs/_snippets/sveltekit-mock-links.md b/docs/_snippets/sveltekit-mock-links.md new file mode 100644 index 000000000000..dab06cea2a63 --- /dev/null +++ b/docs/_snippets/sveltekit-mock-links.md @@ -0,0 +1,118 @@ +```svelte filename="MyComponent.stories.svelte" renderer="svelte" language="js" tabTitle="Svelte CSF" + + + { + console.log(to, event); + }, + '/root.*': { + callback: (to, event) => { + console.log(to, event); + }, + asRegex: true, + }, + }, + }, + }} +/> +``` + +```js filename="MyComponent.stories.js" renderer="svelte" language="js" tabTitle="CSF" +import MyComponent from './MyComponent.svelte'; + +export default { + component: MyComponent, +}; + +export const MyStory = { + parameters: { + sveltekit_experimental: { + hrefs: { + '/basic-href': (to, event) => { + console.log(to, event); + }, + '/root.*': { + callback: (to, event) => { + console.log(to, event); + }, + asRegex: true, + }, + }, + }, + }, +}; +``` + +```svelte filename="MyComponent.stories.svelte" renderer="svelte" language="ts" tabTitle="Svelte CSF" + + + { + console.log(to, event); + }, + '/root.*': { + callback: (to, event) => { + console.log(to, event); + }, + asRegex: true, + }, + }, + }, + }} +/> +``` + +```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts" tabTitle="CSF" +import type { Meta, StoryObj } from '@storybook/sveltekit'; + +import MyComponent from './MyComponent.svelte'; + +const meta = { + component: MyComponent, +} satisfies Meta; + +export default meta; +type Story = StoryObj; + +export const MyStory: Story = { + parameters: { + sveltekit_experimental: { + hrefs: { + '/basic-href': (to, event) => { + console.log(to, event); + }, + '/root.*': { + callback: (to, event) => { + console.log(to, event); + }, + asRegex: true, + }, + }, + }, + }, +}; +``` diff --git a/docs/api/csf/index.mdx b/docs/api/csf/index.mdx index b212450a8bfe..50afb12d6183 100644 --- a/docs/api/csf/index.mdx +++ b/docs/api/csf/index.mdx @@ -139,6 +139,19 @@ When the story renders in the UI, Storybook executes each step defined in the `p When Storybook loads this story, it will detect the existence of a `render` function and adjust the component rendering accordingly based on what's defined. + + ## Custom render functions + + If you're using Svelte CSF to write your stories, you can add a custom snippet to allow you additional control over how your story renders. For example, if you were writing a story and you wanted to specify how your component should render, you could write the following: + + {/* prettier-ignore-start */} + + + + {/* prettier-ignore-end */} + + + ## Storybook export vs. name handling Storybook handles named exports and the `name` option slightly differently. When should you use one vs. the other? diff --git a/docs/get-started/frameworks/svelte-vite.mdx b/docs/get-started/frameworks/svelte-vite.mdx index 46e0bd7e87a7..f38d41573155 100644 --- a/docs/get-started/frameworks/svelte-vite.mdx +++ b/docs/get-started/frameworks/svelte-vite.mdx @@ -203,21 +203,12 @@ Default: `true` Enables or disables automatic documentation generation for component properties. When disabled, Storybook will skip the docgen processing step during build, which can improve build performance. -```ts title=".storybook/main.ts" -import type { StorybookConfig } from '@storybook/svelte-vite'; - -const config: StorybookConfig = { - framework: { - name: '@storybook/svelte-vite', - options: { - docgen: false, // Disable docgen for better performance - }, - }, -}; - -export default config; -``` +{/* prettier-ignore-start */} + + + +{/* prettier-ignore-end */} -##### When to disable docgen +#### When to disable docgen Disabling docgen can improve build performance for large projects, but [argTypes won't be inferred automatically](../../api/arg-types.mdx#automatic-argtype-inference), which will prevent features like [Controls](../../essentials/controls.mdx) and [docs](../../writing-docs/autodocs.mdx) from working as expected. To use those features, you will need to [define `argTypes` manually](../../api/arg-types.mdx#manually-specifying-argtypes). diff --git a/docs/get-started/frameworks/sveltekit.mdx b/docs/get-started/frameworks/sveltekit.mdx index a099ef60c09a..84b787e96a3c 100644 --- a/docs/get-started/frameworks/sveltekit.mdx +++ b/docs/get-started/frameworks/sveltekit.mdx @@ -76,49 +76,29 @@ However, SvelteKit has some [Kit-specific modules](https://kit.svelte.dev/docs/m | Module | Status | Note | | ---------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| [`$app/environment`](https://kit.svelte.dev/docs/modules#$app-environment) | ✅ Supported | `version` is always empty in Storybook. | -| [`$app/forms`](https://kit.svelte.dev/docs/modules#$app-forms) | ⚠️ **Experimental** | See [How to mock](#how-to-mock). | -| [`$app/navigation`](https://kit.svelte.dev/docs/modules#$app-navigation) | ⚠️ **Experimental** | See [How to mock](#how-to-mock). | -| [`$app/paths`](https://kit.svelte.dev/docs/modules#$app-paths) | ✅ Supported | Requires SvelteKit 1.4.0 or newer. | +| [`$app/environment`](https://svelte.dev/docs/kit/$app-environment) | ✅ Supported | `version` is always empty in Storybook. | +| [`$app/forms`](https://svelte.dev/docs/kit/$app-forms) | ⚠️ **Experimental** | See [How to mock](#how-to-mock). | +| [`$app/navigation`](https://svelte.dev/docs/kit/$app-navigation) | ⚠️ **Experimental** | See [How to mock](#how-to-mock). | +| [`$app/paths`](https://svelte.dev/docs/kit/$app-paths) | ✅ Supported | Requires SvelteKit 1.4.0 or newer. | | [`$app/state`](https://svelte.dev/docs/kit/$app-state) | ⚠️ **Experimental** | Requires SvelteKit `v2.12` or newer. See [How to mock](#how-to-mock). | -| [`$app/stores`](https://kit.svelte.dev/docs/modules#$app-stores) | ⚠️ **Experimental** | See [How to mock](#how-to-mock). | -| [`$env/dynamic/public`](https://kit.svelte.dev/docs/modules#$env-dynamic-public) | 🚧 Partially supported | Only supported in development mode. Storybook is built as a static app with no server-side API, so it cannot dynamically serve content. | -| [`$env/static/public`](https://kit.svelte.dev/docs/modules#$env-static-public) | ✅ Supported | | -| [`$lib`](https://kit.svelte.dev/docs/modules#$lib) | ✅ Supported | | -| [`@sveltejs/kit/*`](https://kit.svelte.dev/docs/modules#sveltejs-kit) | ✅ Supported | | -| [`$env/dynamic/private`](https://kit.svelte.dev/docs/modules#$env-dynamic-private) | ⛔ Not supported | This is a server-side feature, and Storybook renders all components on the client. | -| [`$env/static/private`](https://kit.svelte.dev/docs/modules#$env-static-private) | ⛔ Not supported | This is a server-side feature, and Storybook renders all components on the client. | -| [`$service-worker`](https://kit.svelte.dev/docs/modules#$service-worker) | ⛔ Not supported | This is a service worker feature, which does not apply to Storybook. | +| [`$app/stores`](https://svelte.dev/docs/kit/$app-stores) | ⚠️ **Experimental** | See [How to mock](#how-to-mock). | +| [`$env/dynamic/public`](https://svelte.dev/docs/kit/$env-dynamic-public) | 🚧 Partially supported | Only supported in development mode. Storybook is built as a static app with no server-side API, so it cannot dynamically serve content. | +| [`$env/static/public`](https://svelte.dev/docs/kit/$env-static-public) | ✅ Supported | | +| [`$lib`](https://svelte.dev/docs/kit/$lib) | ✅ Supported | | +| [`@sveltejs/kit/*`](https://svelte.dev/docs/kit/@sveltejs-kit) | ✅ Supported | | +| [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private) | ⛔ Not supported | This is a server-side feature, and Storybook renders all components on the client. | +| [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private) | ⛔ Not supported | This is a server-side feature, and Storybook renders all components on the client. | +| [`$service-worker`](https://svelte.dev/docs/kit/$service-worker) | ⛔ Not supported | This is a service worker feature, which does not apply to Storybook. | ## How to mock To mock a SvelteKit import you can define it within `parameters.sveltekit_experimental`: -```ts title="MyComponent.stories.js|ts" -export const MyStory = { - parameters: { - sveltekit_experimental: { - state: { - page: { - data: { - test: 'passed', - }, - }, - navigating: { - to: { - route: { id: '/storybook' }, - params: {}, - url: new URL('http://localhost/storybook'), - }, - }, - updated: { - current: true, - }, - }, - }, - }, -}; -``` +{/* prettier-ignore-start */} + + + +{/* prettier-ignore-end */} The [available parameters](#parameters) are documented in the API section, below. @@ -128,25 +108,11 @@ The default link-handling behavior (e.g., when clicking an `` el You can override this by assigning an object to `parameters.sveltekit_experimental.hrefs`, where the keys are strings representing an href, and the values define your mock. For example: -```ts title="MyComponent.stories.js|ts" -export const MyStory = { - parameters: { - sveltekit_experimental: { - hrefs: { - '/basic-href': (to, event) => { - console.log(to, event); - }, - '/root.*': { - callback: (to, event) => { - console.log(to, event); - }, - asRegex: true, - }, - }, - }, - }, -}; -``` +{/* prettier-ignore-start */} + + + +{/* prettier-ignore-end */} See the [API reference](#hrefs) for more information. @@ -276,7 +242,7 @@ This framework contributes the following [parameters](../../writing-stories/para Type: `{ enhance: () => void }` -Provides mocks for the [`$app/forms`](https://kit.svelte.dev/docs/modules#$app-forms) module. +Provides mocks for the [`$app/forms`](https://svelte.dev/docs/kit/$app-forms) module. ##### `forms.enhance` @@ -292,69 +258,69 @@ If you have an `` tag inside your code with the `href` attribute that match #### `navigation` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-navigation) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation) -Provides mocks for the [`$app/navigation`](https://kit.svelte.dev/docs/modules#$app-navigation) module. +Provides mocks for the [`$app/navigation`](https://svelte.dev/docs/kit/$app-navigation) module. ##### `navigation.goto` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-navigation-goto) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#goto) -A callback that will be called whenever [`goto`](https://kit.svelte.dev/docs/modules#$app-navigation-goto) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). +A callback that will be called whenever [`goto`](https://svelte.dev/docs/kit/$app-navigation#goto) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). ##### `navigation.pushState` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-navigation-pushstate) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#pushState) -A callback that will be called whenever [`pushState`](https://kit.svelte.dev/docs/modules#$app-navigation-pushstate) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). +A callback that will be called whenever [`pushState`](https://svelte.dev/docs/kit/$app-navigation#pushState) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). ##### `navigation.replaceState` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-navigation-replacestate) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#replaceState) -A callback that will be called whenever [`replaceState`](https://kit.svelte.dev/docs/modules#$app-navigation-replacestate) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). +A callback that will be called whenever [`replaceState`](https://svelte.dev/docs/kit/$app-navigation#replaceState) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). ##### `navigation.invalidate` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-navigation-invalidate) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#invalidate) -A callback that will be called whenever [`invalidate`](https://kit.svelte.dev/docs/modules#$app-navigation-invalidate) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). +A callback that will be called whenever [`invalidate`](https://svelte.dev/docs/kit/$app-navigation#invalidate) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). ##### `navigation.invalidateAll` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-navigation-invalidateall) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#invalidateAll) -A callback that will be called whenever [`invalidateAll`](https://kit.svelte.dev/docs/modules#$app-navigation-invalidateall) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). +A callback that will be called whenever [`invalidateAll`](https://svelte.dev/docs/kit/$app-navigation#invalidateAll) is called. If no function is provided, an action will be logged to the [Actions panel](../../essentials/actions.mdx). ##### `navigation.afterNavigate` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-navigation-afternavigate) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-navigation#afterNavigate) -An object that will be passed to the [`afterNavigate`](https://kit.svelte.dev/docs/modules#$app-navigation-afternavigate) function, which will be invoked when the `onMount` event fires. +An object that will be passed to the [`afterNavigate`](https://svelte.dev/docs/kit/$app-navigation#afterNavigate) function, which will be invoked when the `onMount` event fires. #### `stores` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-stores) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-stores) -Provides mocks for the [`$app/stores`](https://kit.svelte.dev/docs/modules#$app-stores) module. +Provides mocks for the [`$app/stores`](https://svelte.dev/docs/kit/$app-stores) module. ##### `stores.navigating` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-stores-navigating) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-stores#navigating) -A partial version of the [`navigating`](https://kit.svelte.dev/docs/modules#$app-stores-navigating) store. +A partial version of the [`navigating`](https://svelte.dev/docs/kit/$app-stores#navigating) store. ##### `stores.page` -Type: See [SvelteKit docs](https://kit.svelte.dev/docs/modules#$app-stores-page) +Type: See [SvelteKit docs](https://svelte.dev/docs/kit/$app-stores#page) -A partial version of the [`page`](https://kit.svelte.dev/docs/modules#$app-stores-page) store. +A partial version of the [`page`](https://svelte.dev/docs/kit/$app-stores#page) store. ##### `stores.updated` Type: boolean -A boolean representing the value of [`updated`](https://kit.svelte.dev/docs/modules#$app-stores-updated) (you can also access `updated.check()` which will be a no-op). +A boolean representing the value of [`updated`](https://svelte.dev/docs/kit/$app-stores#updated) (you can also access `updated.check()` which will be a no-op). #### `state` @@ -406,22 +372,13 @@ Default: `true` Enables or disables automatic documentation generation for component properties. When disabled, Storybook will skip the docgen processing step during build, which can improve build performance. -```ts title=".storybook/main.ts" -import type { StorybookConfig } from '@storybook/sveltekit'; +{/* prettier-ignore-start */} -const config: StorybookConfig = { - framework: { - name: '@storybook/sveltekit', - options: { - docgen: false, // Disable docgen for better performance - }, - }, -}; + -export default config; -``` +{/* prettier-ignore-end */} -##### When to disable docgen +#### When to disable docgen Disabling docgen can improve build performance for large projects, but [argTypes won't be inferred automatically](../../api/arg-types.mdx#automatic-argtype-inference), which will prevent features like [Controls](../../essentials/controls.mdx) and [docs](../../writing-docs/autodocs.mdx) from working as expected. To use those features, you will need to [define `argTypes` manually](../../api/arg-types.mdx#manually-specifying-argtypes).