@forgebook/svelte 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ensiria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @forgebook/svelte
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Svelte 5 for [Forgebook](https://www.npmjs.com/package/forgebook): the story types, the context helpers, the renderer the
+frame mounts a story with, and the adapter that reads a component's props, snippets and callback props from its types.
+
+**Requirements:** Svelte 5.46 · `forgebook` · Vite 8 · React in the project, for the catalogue's own interface (the frames
+that draw your components load none) · [MIT licence](https://github.com/ensiria/forgebook/blob/develop/packages/svelte/LICENSE)
+
+```sh
+npm install --save-dev forgebook @forgebook/svelte react react-dom
+```
+
+The catalogue's configuration names it as its framework:
+
+```ts
+// forgebook.config.ts
+import { svelte } from "@forgebook/svelte/vite";
+import { defineConfig } from "forgebook";
+
+export default defineConfig({ framework: svelte(), title: "My components", stories: ["src/**/*.stories.ts"] });
+```
+
+and the stories take their types from it:
+
+```ts
+import type { Meta, Story } from "@forgebook/svelte";
+
+import Badge from "./Badge.svelte";
+
+export default { title: "Components/Badge", component: Badge } satisfies Meta<typeof Badge>;
+
+// the component with its args: its props, its callback props (`onremove`) among them
+export const Default: Story<typeof Badge> = { args: { label: "New" } };
+
+// a snippet filled with a text, as `#name`: `#children` is the content
+export const WithIcon: Story<typeof Badge> = { args: { label: "New", "#icon": "*", "#children": "Details" } };
+
+// a render, returning the component with props of its choosing, as Storybook's Svelte stories do
+export const Danger: Story<typeof Badge> = {
+  render: (args) => ({ Component: Badge, props: { ...args, tone: "danger" } })
+};
+```
+
+A story is written in a `.ts` file, as CSF 3: a render returns a component, drawn with the args, or
+`{ Component, props }`. A story that needs markup of its own (a component inside a layout, a `bind:`) is a small
+`.svelte` file the render returns. A decorator returns the same, and the story reaches its component as `children`:
+
+```ts
+// forgebook.preview.ts
+import type { Preview } from "@forgebook/svelte";
+
+import ThemeFrame from "./ThemeFrame.svelte"; // sets its context, then {@render children()}
+
+export default {
+  decorators: [(_story, context) => ({ Component: ThemeFrame, props: { theme: context.globals["theme"] } })]
+} satisfies Preview;
+```
+
+A snippet a story passes itself goes under the prop's own name (`children: createRawSnippet(…)`); the panel edits a
+snippet as the text that fills it. The panel records a story's callback props in Events. A story file checked with `tsc`
+sees your `*.svelte` shim; `svelte-check` checks its args against the real component.
+
+| Import | What it is |
+|---|---|
+| `@forgebook/svelte` | `Meta`, `Story`, `Decorator`, `Preview`, `LogicMeta`: CSF 3 typed for Svelte, the args from the component's props |
+| `@forgebook/svelte/vite` | `svelte()`, the framework adapter of `forgebook.config.ts`, with Svelte's Vite plugin |
+| `@forgebook/svelte/texts`, `@forgebook/svelte/clock` | `getStoryText()`, a story's texts in the catalogue's language; `getStoryClock()` and `getStoryNow()`, the story clock, read as `.current` |
+
+## What the catalogue reads
+
+Props come from the component's types: `svelte2tsx`, which Svelte's language server and `svelte-check` use, writes each
+`.svelte` file as TypeScript, so a `$props()` typed in TypeScript and one typed with JSDoc read the same, and the
+destructuring gives each prop's default (`$bindable` included). The `<!-- @component -->` comment describes the
+component, with `@useWhen` and the other tags; a TSDoc block that opens its script, with `@module`, is its summary. A
+snippet is listed as the arg that fills it (`#icon`), a function prop named `on…` as an event, and what the component
+passes on to an element (`HTMLAttributes`) is left out. A function with runes in a `.svelte.ts` module is documented by its
+signature in a story about logic (`LogicMeta`).
+
+Svelte's own plugin is the adapter's, and it reads your `svelte.config.js`, so don't add `@sveltejs/vite-plugin-svelte` to
+a catalogue; in a Vite or Vitest configuration of your own that already has it, add `forgebookPlugin` without the
+adapter's `vitePlugins()`. `svelte({ plugin })` passes options to Svelte's plugin, over what it reads from
+`svelte.config.js`; they are `@sveltejs/vite-plugin-svelte`'s own, so they follow its major version. A SvelteKit app's components, which read `$app/*`, are drawn by
+[`@forgebook/sveltekit`](https://www.npmjs.com/package/@forgebook/sveltekit), built on this adapter. The frame says a story is drawn once Svelte has settled, so a component that awaits (`experimental.async`)
+is drawn before its play runs. Generated server tests take `svelteRenderer` from `@forgebook/svelte/renderer` and run in
+Node (`environment: "node"`), since Svelte compiles a component apart for the server; the catalogue's
+`forgebook new`, `forgebook docs --framework svelte` and `forgebook init --from storybook` (from `@storybook/svelte-vite`)
+read Svelte too.
+
+A snippet made from a text is drawn in a `span`, since Svelte draws a snippet made outside a component from one element.
+Stories written in `.stories.svelte` files (Svelte CSF) are not read: write them in CSF 3, as above. "Used in" follows
+React's JSX, not Svelte markup, so it lists nothing yet.
+
+The rest of its exports are what the catalogue loads itself. Getting started, the catalogue's features and its commands:
+[Forgebook's README](https://github.com/ensiria/forgebook/blob/develop/packages/forgebook/README.md).

package/dist/src/StoryHost.svelte

@@ -0,0 +1,34 @@
+<!--
+@component
+What the renderer mounts in a story's canvas, and renders on the server: the story's tree of components (`storyNode.ts`),
+each drawn with its props and the node inside it as its `children`, in an error boundary.
+
+The state lives in the renderer (`svelteRenderer.ts`), in values Svelte follows: new args draw again what read them, and a
+component whose node keeps its component keeps its state. A new try after an error draws the story anew. An error in an
+event handler is the handler's, as in a page: a boundary does not catch it. On the server a boundary catches nothing, so
+an error fails the render. The file imports nothing but types, so it is published as it is.
+-->
+<script lang="ts">
+import type { StoryNode } from "./storyNode.ts";
+import type { StoryScene } from "./svelteRenderer.ts";
+
+const { scene }: { readonly scene: StoryScene } = $props();
+</script>
+
+{#snippet draw(node: StoryNode)}
+  {#if node.inner === undefined}
+    <node.component {...node.props} />
+  {:else}
+    {@const inner = node.inner}
+    <node.component {...node.props}>{@render draw(inner)}</node.component>
+  {/if}
+{/snippet}
+
+{#key scene.attempt}
+  {#if !scene.isFailed}
+    <svelte:boundary onerror={scene.fail}>
+      {@const node = scene.node}
+      {@render draw(node)}
+    </svelte:boundary>
+  {/if}
+{/key}

package/dist/src/clock.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The story clock for Svelte components inside a story: the clock the catalogue runs, held at the Unix epoch outside a
+ * catalogue.
+ *
+ * @remarks
+ * The clock itself is the format's (`@forgebook/story-format/clock`); this module is how a Svelte component reads it,
+ * each value a `current` that a template follows, as Svelte's own reactive values are read. The moment follows the
+ * clock's ticks through `createSubscriber`, so it listens only while something reads it, and not at all on the server.
+ *
+ * @module
+ */
+import { type StoryClock } from "@forgebook/story-format/clock";
+/** A value of the moment, read as Svelte's reactive values are. */
+export type StoryValue<TValue> = {
+    /** The value; a template or an effect that reads it follows it. */
+    readonly current: TValue;
+};
+/**
+ * The story's clock, for a component inside a story; called while the component is initialised.
+ *
+ * @returns the clock the catalogue runs for the story, which is replaced when the story starts over.
+ */
+export declare const getStoryClock: () => StoryValue<StoryClock>;
+/**
+ * The story's current moment, which follows each tick of the clock; called while the component is initialised.
+ *
+ * @returns the moment, in milliseconds since the Unix epoch.
+ */
+export declare const getStoryNow: () => StoryValue<number>;

package/dist/src/clock.js

@@ -0,0 +1,54 @@
+/**
+ * The story clock for Svelte components inside a story: the clock the catalogue runs, held at the Unix epoch outside a
+ * catalogue.
+ *
+ * @remarks
+ * The clock itself is the format's (`@forgebook/story-format/clock`); this module is how a Svelte component reads it,
+ * each value a `current` that a template follows, as Svelte's own reactive values are read. The moment follows the
+ * clock's ticks through `createSubscriber`, so it listens only while something reads it, and not at all on the server.
+ *
+ * @module
+ */
+import { heldStoryClock } from "@forgebook/story-format/clock";
+import { createSubscriber } from "svelte/reactivity";
+import { storyView } from "./storyView.js";
+/** The clock outside a catalogue. */
+const HELD_CLOCK = heldStoryClock(0);
+/**
+ * The story's clock, for a component inside a story; called while the component is initialised.
+ *
+ * @returns the clock the catalogue runs for the story, which is replaced when the story starts over.
+ */
+export const getStoryClock = () => {
+    const view = storyView();
+    return {
+        get current() {
+            return view?.clock ?? HELD_CLOCK;
+        }
+    };
+};
+/**
+ * The story's current moment, which follows each tick of the clock; called while the component is initialised.
+ *
+ * @returns the moment, in milliseconds since the Unix epoch.
+ */
+export const getStoryNow = () => {
+    const clock = getStoryClock();
+    // one subscriber per clock: a story that starts over has a new clock, and what read the old one stops listening
+    const subscribers = new WeakMap();
+    const subscriberOf = (current) => {
+        const kept = subscribers.get(current);
+        if (kept !== undefined)
+            return kept;
+        const subscriber = createSubscriber((update) => current.subscribe(update));
+        subscribers.set(current, subscriber);
+        return subscriber;
+    };
+    return {
+        get current() {
+            const current = clock.current;
+            subscriberOf(current)();
+            return current.now();
+        }
+    };
+};

package/dist/src/mountFrame.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The frame page of a Svelte catalogue: Forgebook's frame, drawing its stories with Svelte. Called by the page the plugin
+ * generates from the catalogue's configuration, not by an app.
+ *
+ * @module
+ */
+import { type FrameConfig } from "forgebook/frame";
+/**
+ * Shows the story the address names in the given element, drawn with Svelte.
+ *
+ * @param container - the element the story renders into.
+ * @param config - the sources and the languages, as the shell's configuration gives them.
+ */
+export declare const mountFrame: (container: HTMLElement, config: Omit<FrameConfig, "renderer">) => Promise<void>;

package/dist/src/mountFrame.js

@@ -0,0 +1,15 @@
+/**
+ * The frame page of a Svelte catalogue: Forgebook's frame, drawing its stories with Svelte. Called by the page the plugin
+ * generates from the catalogue's configuration, not by an app.
+ *
+ * @module
+ */
+import { mountFrame as mountForgebookFrame } from "forgebook/frame";
+import { svelteRenderer } from "./svelteRenderer.js";
+/**
+ * Shows the story the address names in the given element, drawn with Svelte.
+ *
+ * @param container - the element the story renders into.
+ * @param config - the sources and the languages, as the shell's configuration gives them.
+ */
+export const mountFrame = (container, config) => mountForgebookFrame(container, { ...config, renderer: svelteRenderer });

package/dist/src/snippetArgs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Which args fill a snippet with a text: `#name`, the snippet prop `name` drawn as that text.
+ *
+ * @remarks
+ * A snippet is a prop like any other in Svelte 5, and a text passed to it would reach `{@render children()}` as a
+ * string, which throws: an arg has to say it is a snippet's text, so the renderer can make the snippet. A story that
+ * passes a snippet of its own passes it under the prop's name. Free of Svelte, since the shell's code writer reads it too
+ * and the shell loads no Svelte.
+ *
+ * @module
+ */
+/** What an arg's name starts with when it fills a snippet with a text. */
+export declare const SNIPPET_MARK = "#";
+/**
+ * The snippet prop an arg fills with a text.
+ *
+ * @param name - the arg's name.
+ * @returns the snippet prop's name, or none for any other arg.
+ */
+export declare const snippetOfArg: (name: string) => string | undefined;

package/dist/src/snippetArgs.js

@@ -0,0 +1,22 @@
+/**
+ * Which args fill a snippet with a text: `#name`, the snippet prop `name` drawn as that text.
+ *
+ * @remarks
+ * A snippet is a prop like any other in Svelte 5, and a text passed to it would reach `{@render children()}` as a
+ * string, which throws: an arg has to say it is a snippet's text, so the renderer can make the snippet. A story that
+ * passes a snippet of its own passes it under the prop's name. Free of Svelte, since the shell's code writer reads it too
+ * and the shell loads no Svelte.
+ *
+ * @module
+ */
+/** What an arg's name starts with when it fills a snippet with a text. */
+export const SNIPPET_MARK = "#";
+/**
+ * The snippet prop an arg fills with a text.
+ *
+ * @param name - the arg's name.
+ * @returns the snippet prop's name, or none for any other arg.
+ */
+export const snippetOfArg = (name) => name.startsWith(SNIPPET_MARK) && name.length > SNIPPET_MARK.length
+    ? name.slice(SNIPPET_MARK.length)
+    : undefined;

package/dist/src/stories.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The story types for Svelte: what a story file of a Svelte library is written with
+ * (`import type { Meta, Story } from "@forgebook/svelte"`).
+ *
+ * @remarks
+ * The format's types (`@forgebook/story-format/csf`) are generic over a framework; these name them for Svelte 5, so a
+ * meta writes `satisfies Meta<typeof Button>` and its stories' args are the component's props (its callback props
+ * among them), a prop that takes a text also as `storyText("key")`, and a snippet's text as `#name`. Types only: a
+ * library that writes stories depends on this package, never on the catalogue that shows them. A `.svelte` file has its
+ * real types under `svelte-check`; plain `tsc` sees the project's `*.svelte` shim.
+ *
+ * @module
+ */
+import type { Decorator as CsfDecorator, CsfMeta, CsfPreview, CsfStory, StoryParameters, WrittenArg } from "@forgebook/story-format/csf";
+import type { Component, Snippet } from "svelte";
+/**
+ * Any Svelte 5 component: what a `.svelte` file exports, whatever its props. Its props are `never` because a component
+ * that takes any props at all can stand for it.
+ */
+export type AnyComponent = Component<never, Record<string, unknown>, string>;
+/** A component drawn with these props: what a render returns to draw a component with props of its choosing. */
+export type StoryComponent = {
+    /** The component. */
+    readonly Component: AnyComponent;
+    /** Its props; a snippet's text as `#name`, as in the args. None draws it with none. */
+    readonly props?: Readonly<Record<string, unknown>>;
+};
+/**
+ * What a story draws: a component, drawn with the args, or a component with props of its choosing
+ * (`{ Component: Button, props: { ...args, tone: "danger" } }`), as Storybook's Svelte stories write it. What a
+ * decorator returns is drawn around the story, which reaches its component as `children`.
+ */
+export type SvelteStoryResult = AnyComponent | StoryComponent;
+/** Svelte, as the format's types read it. */
+export type SvelteRenderer = {
+    /** A component. */
+    readonly component: AnyComponent;
+    /** What a story draws. */
+    readonly storyResult: SvelteStoryResult;
+};
+/** A component's props, as its function is called with them. */
+type PropsOf<TComponent extends AnyComponent> = TComponent extends (internals: never, props: infer TProps) => unknown ? TProps : Readonly<Record<string, never>>;
+/** Whether a prop takes a snippet: what it renders is what a snippet returns. */
+type IsSnippet<TValue> = NonNullable<TValue> extends (...parameters: never) => infer TResult ? TResult extends ReturnType<Snippet> ? true : false : false;
+/** The args that fill a component's snippets with a text, each as `#name`. */
+type SnippetArgsOf<TComponent extends AnyComponent> = {
+    [TName in keyof PropsOf<TComponent> as TName extends string ? IsSnippet<PropsOf<TComponent>[TName]> extends true ? `#${TName}` : never : never]?: WrittenArg<string>;
+};
+/** A component's args, every one optional: what a story's args may set, and what its render receives. */
+export type ArgsOf<TComponent extends AnyComponent> = Partial<PropsOf<TComponent>> & SnippetArgsOf<TComponent>;
+/**
+ * What a story's `args` may write: the component's props, every one optional, a prop that takes a text also as
+ * `storyText("key")`, and its snippets' texts. The render and the play function receive `ArgsOf`, the text already in
+ * the shown language.
+ */
+export type WrittenArgsOf<TComponent extends AnyComponent> = {
+    [TName in keyof PropsOf<TComponent>]?: WrittenArg<PropsOf<TComponent>[TName]>;
+} & SnippetArgsOf<TComponent>;
+/** A page with no component (a foundations page): no args. */
+export type NoComponent = Component<Record<string, never>>;
+/** A Svelte story file's default export: `{ title, component, args… } satisfies Meta<typeof Button>`. */
+export type Meta<TComponent extends AnyComponent = NoComponent> = CsfMeta<SvelteRenderer, TComponent, ArgsOf<TComponent>, WrittenArgsOf<TComponent>>;
+/** A Svelte story: a named export of a story file. */
+export type Story<TComponent extends AnyComponent = NoComponent> = CsfStory<SvelteRenderer, ArgsOf<TComponent>, WrittenArgsOf<TComponent>>;
+/** Any function a story about logic documents; its parameter is `never` so any signature is assignable. */
+export type AnyFunction = (...parameters: never[]) => unknown;
+/** No args: a story about logic draws a scene of its own, which takes none. */
+type NoArgs = Readonly<Record<string, never>>;
+/**
+ * The default export of a story file about logic, written `satisfies LogicMeta<typeof createToggle>`: `parameters` must
+ * say `logic: true`, so a function's file is never taken for a component's. Its component is the function (in a
+ * `.svelte.ts` module, with runes), whose signature the catalogue documents.
+ */
+export type LogicMeta<TFunction extends AnyFunction> = CsfMeta<SvelteRenderer, TFunction, NoArgs, NoArgs> & {
+    /** The catalogue's settings, `logic: true` among them. */
+    readonly parameters: StoryParameters & {
+        readonly logic: true;
+    };
+};
+/**
+ * A story about logic: a `render` that draws a scene using the function, required (without one, the catalogue would
+ * draw the function as a component), and a `play` that tries it.
+ */
+export type LogicStory = CsfStory<SvelteRenderer, NoArgs, NoArgs> & Required<Pick<CsfStory<SvelteRenderer, NoArgs, NoArgs>, "render">>;
+/** Wraps a Svelte story: a provider, a container of a given width, drawn around it. */
+export type Decorator<TArgs> = CsfDecorator<SvelteRenderer, TArgs>;
+/**
+ * A Svelte catalogue's preview (`forgebook.preview.ts`): decorators around every story (its providers, the language's
+ * reading `context.globals.lang`), parameters under every meta's, a setup before any story renders.
+ */
+export type Preview = CsfPreview<SvelteRenderer>;
+export {};

package/dist/src/storyCell.d.ts

@@ -0,0 +1,17 @@
+/** A value Svelte follows. */
+export type StoryCell<TValue> = {
+    /** The value; a template, a derived value or an effect that reads it follows it. */
+    readonly current: TValue;
+    /**
+     * Replaces the value; what read it is drawn again, unless the new value is the same.
+     *
+     * @param value - the new value.
+     */
+    readonly set: (value: TValue) => void;
+};
+/**
+ * A value Svelte follows.
+ *
+ * @param initial - its first value.
+ */
+export declare const storyCell: <TValue>(initial: TValue) => StoryCell<TValue>;

package/dist/src/storyCell.js

@@ -0,0 +1,39 @@
+/**
+ * A value Svelte follows, held outside a component: what the renderer keeps of a drawn story (its args, its scene, its
+ * texts), so the host's template draws again what read a value that changed, and only that.
+ *
+ * @remarks
+ * Svelte's `$state` exists only in files its compiler reads; `createSubscriber` is its way for plain code to be followed,
+ * so the renderer stays a TypeScript module, built and published as one.
+ *
+ * @module
+ */
+import { createSubscriber } from "svelte/reactivity";
+/**
+ * A value Svelte follows.
+ *
+ * @param initial - its first value.
+ */
+export const storyCell = (initial) => {
+    let value = initial;
+    // set while something reads the value: no one is told when no one reads it
+    let notify = () => undefined;
+    const subscribe = createSubscriber((update) => {
+        notify = update;
+        return () => {
+            notify = () => undefined;
+        };
+    });
+    return {
+        get current() {
+            subscribe();
+            return value;
+        },
+        set: (next) => {
+            if (Object.is(next, value))
+                return;
+            value = next;
+            notify();
+        }
+    };
+};

package/dist/src/storyMarkup.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The markup of a story drawn from its args: the component with the values the story and the props panel set, as a
+ * developer would write it in a Svelte file, for the Code card.
+ *
+ * @remarks
+ * Attributes are written as Svelte writes them: a text in quotes, or as an expression when it holds a brace or a quote
+ * (`label={"a {b}"}`); a number, `null`, `false` or a list as an expression (`count={3}`, `options={["a", "b"]}`); `true`
+ * the bare name; a named value by its name (`icon={IconFolder}`). A snippet's text goes between the tags: `#children` as
+ * the content, any other in a `{#snippet name()}` block. Only the values that cross from the frame are known (texts,
+ * numbers, booleans, `null`, lists of texts and numbers, named values): a function the story passes is left out. Pure.
+ *
+ * @module
+ */
+import { type PanelArgs } from "forgebook/messages";
+import type { StoryCodeWriter } from "forgebook/renderer";
+/**
+ * A component's markup with these args.
+ *
+ * @param component - the component's name (`IconTile`).
+ * @param args - the values, in the order they are written.
+ */
+export declare const storyMarkup: (component: string, args: PanelArgs) => string;
+/** The code writer a Svelte catalogue's shell writes a story's code with: the name the generated pages import. */
+export declare const codeOf: StoryCodeWriter;

package/dist/src/storyMarkup.js

@@ -0,0 +1,89 @@
+/**
+ * The markup of a story drawn from its args: the component with the values the story and the props panel set, as a
+ * developer would write it in a Svelte file, for the Code card.
+ *
+ * @remarks
+ * Attributes are written as Svelte writes them: a text in quotes, or as an expression when it holds a brace or a quote
+ * (`label={"a {b}"}`); a number, `null`, `false` or a list as an expression (`count={3}`, `options={["a", "b"]}`); `true`
+ * the bare name; a named value by its name (`icon={IconFolder}`). A snippet's text goes between the tags: `#children` as
+ * the content, any other in a `{#snippet name()}` block. Only the values that cross from the frame are known (texts,
+ * numbers, booleans, `null`, lists of texts and numbers, named values): a function the story passes is left out. Pure.
+ *
+ * @module
+ */
+import { isNamedArg } from "forgebook/messages";
+import { snippetOfArg } from "./snippetArgs.js";
+/** The snippet a component's content fills. */
+const CHILDREN = "children";
+/** The longest line the attributes stay on one line for, in characters. */
+const ONE_LINE = 80;
+/** A text that reads the same between quotes: no brace, which opens an expression, and nothing to escape. */
+const isPlainText = (text) => !/[{}"&\n]/.test(text);
+/** A value as a JavaScript expression. */
+const expression = (value) => JSON.stringify(value);
+/** One attribute as Svelte writes it. */
+const attribute = (name, value) => {
+    if (value === true)
+        return name;
+    if (typeof value === "string")
+        return isPlainText(value) ? `${name}="${value}"` : `${name}={${expression(value)}}`;
+    // a named value is written by its name, as the source's module exports it (`icon={IconFolder}`)
+    if (isNamedArg(value))
+        return `${name}={${value.named}}`;
+    // a multiple choice's values, as the source writes a list
+    if (Array.isArray(value))
+        return `${name}={[${value.map(expression).join(", ")}]}`;
+    return `${name}={${String(value)}}`;
+};
+/** A text as Svelte's markup holds it: a tag or an expression it writes stays text. */
+const contentText = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/\{/g, "&#123;").replace(/\}/g, "&#125;");
+/** Whether a value fills a snippet: a text or a number, which is all the renderer draws in one. */
+const isShown = (value) => typeof value === "string" || typeof value === "number";
+/** A snippet's content as markup. */
+const snippetContent = (value) => contentText(String(value));
+/**
+ * What goes between a component's tags: each named snippet in its block, then the content.
+ *
+ * @param snippets - the args that fill a snippet, by the snippet's name.
+ */
+const contentOf = (snippets) => {
+    const shown = snippets.flatMap(([name, value]) => isShown(value) ? [[name, value]] : []);
+    if (shown.length === 0)
+        return undefined;
+    const [only] = shown;
+    if (shown.length === 1 && only?.[0] === CHILDREN)
+        return snippetContent(only[1]);
+    const named = shown
+        .filter(([name]) => name !== CHILDREN)
+        .map(([name, value]) => `  {#snippet ${name}()}${snippetContent(value)}{/snippet}`);
+    const children = shown
+        .filter(([name]) => name === CHILDREN)
+        .map(([, value]) => `  ${snippetContent(value)}`);
+    return `\n${[...named, ...children].join("\n")}\n`;
+};
+/**
+ * A component's markup with these args.
+ *
+ * @param component - the component's name (`IconTile`).
+ * @param args - the values, in the order they are written.
+ */
+export const storyMarkup = (component, args) => {
+    const entries = Object.entries(args);
+    const attributes = entries
+        .filter(([name]) => snippetOfArg(name) === undefined)
+        .map(([name, value]) => attribute(name, value));
+    const content = contentOf(entries.flatMap(([name, value]) => {
+        const snippet = snippetOfArg(name);
+        return snippet === undefined ? [] : [[snippet, value]];
+    }));
+    const oneLine = [component, ...attributes].join(" ");
+    const isOneLine = oneLine.length + 2 <= ONE_LINE;
+    const opening = isOneLine
+        ? `<${oneLine}`
+        : `<${component}\n${attributes.map((text) => `  ${text}`).join("\n")}\n`;
+    if (content === undefined)
+        return `${opening}${isOneLine ? " " : ""}/>`;
+    return `${opening}>${content}</${component}>`;
+};
+/** The code writer a Svelte catalogue's shell writes a story's code with: the name the generated pages import. */
+export const codeOf = storyMarkup;

package/dist/src/storyNode.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A story as Svelte draws it: its render (or the meta's component) inside its decorators, the story's, the meta's and the
+ * catalogue's (its preview's), in that order outward, as a tree of components with their props. The story's canvas, each
+ * cell of its matrix and the server draw it the same way, through `StoryHost.svelte`.
+ *
+ * @remarks
+ * Svelte has no function that draws a component from code, so the tree is data and the host's template draws it: each
+ * node's component with its props, the node inside it as its `children`. A render returns a component, drawn with the
+ * args, or `{ Component, props }`, as Storybook's Svelte stories do; a decorator returns the same, drawn around the story.
+ * A decorator's `story()` gives the story's node: one that returns it as it is adds nothing around it. A `#name` prop
+ * becomes the snippet of its text (`snippetArgs.ts`).
+ *
+ * @module
+ */
+import type { StoryContext } from "@forgebook/story-format/csf";
+import type { LoadedArgs, LoadedDecorator, LoadedStory } from "forgebook/story-module";
+import type { Component } from "svelte";
+import type { TextSnippets } from "./textSnippet.ts";
+/** A component as the host draws it: with whatever props the story gives. */
+export type DrawnComponent = Component<Record<string, unknown>>;
+/** One component of a story's tree, with its props and what it draws inside. */
+export type StoryNode = {
+    /** The component. */
+    readonly component: DrawnComponent;
+    /** Its props, the snippets of `#name` texts made. */
+    readonly props: Readonly<Record<string, unknown>>;
+    /** What it draws as its `children`: the story inside a decorator; none for the story itself. */
+    readonly inner?: StoryNode;
+};
+/**
+ * The story with these args: its render (or the meta's component), inside its decorators.
+ *
+ * @param loaded - the story.
+ * @param context - the args and the canvas its render, play and decorators read.
+ * @param outer - the catalogue's decorators, outside the story's and the meta's.
+ * @param snippetOf - makes the snippet of a `#name` text.
+ * @throws when the story has nothing to draw, or a render or a decorator returns what cannot be drawn.
+ */
+export declare const storyNode: (loaded: LoadedStory, context: StoryContext<LoadedArgs>, outer: readonly LoadedDecorator[], snippetOf: TextSnippets) => StoryNode;