@scaffold-ui-kit/preview 0.0.0-stage → 2.3.0

package/dist/declarations/src/controller/editor-tree.d.ts

@@ -0,0 +1,161 @@
+import type { AroundFill, JsonValue, SlotFill, SlotPlan, StoryAround } from '../lib/types.js';
+export type { AroundFill, SlotFill, SlotPlan, StoryAround };
+type Json = unknown;
+/** A fill the editor cannot author: a `raw` body, a `scoped` slot or a
+ *  `part` call, each per-target strings. It is held verbatim, so it can be
+ *  moved or removed but not edited, and serializes back unchanged. */
+export type OpaqueFill = Extract<SlotFill, {
+    kind: 'raw' | 'scoped' | 'part';
+}>;
+export type EditorNode = {
+    kind: 'text';
+    value: string;
+    id?: string;
+} | {
+    kind: 'element';
+    component: string;
+    props: Record<string, Json>;
+    slots: Record<string, EditorNode[]>;
+    id?: string;
+} | {
+    kind: 'html';
+    tag: string;
+    props: Record<string, Json>;
+    slots: Record<string, EditorNode[]>;
+    id?: string;
+} | {
+    kind: 'opaque';
+    fill: OpaqueFill;
+    id?: string;
+};
+/** A node that holds content of its own: an element or an HTML tag. */
+export type ContainerNode = Extract<EditorNode, {
+    kind: 'element' | 'html';
+}>;
+export declare function isContainer(node: EditorNode): node is ContainerNode;
+export declare const DEFAULT_SLOT = "default";
+/** The plain wrapper tags an HTML node can be, picked from a list rather than
+ *  typed: the layout and content elements a slot fill might need around its
+ *  children. */
+export declare const HTML_TAGS: string[];
+/** Gives every node in the content an id, in place: idempotent, and the spreads
+ *  every update makes carry a node's id along. */
+export declare function ensureIds(content: Record<string, EditorNode[]>): void;
+/** The root's state: its component, its props and its content keyed by
+ *  slot. The content the story renders beside the root is not the tree's: it
+ *  is the story's (`PreviewComponent.around`), which no edit reaches. */
+export interface EditorState {
+    root: string;
+    props: Record<string, Json>;
+    slots: Record<string, EditorNode[]>;
+}
+/** One hop into a slot: which slot, and the node's index in it. */
+export interface Step {
+    slot: string;
+    index: number;
+}
+/** A node's address: the hops from the root, one per slot it descends into.
+ *  The empty path `[]` addresses the root itself. */
+export type NodePath = Step[];
+/** Where a move lands: into `slot` of the node at `parent`, before `index`
+ *  (counted before the moved node is removed). */
+export interface DropTarget {
+    parent: Step[];
+    slot: string;
+    index: number;
+}
+/** Apply `transform` to the node at `path` (path must be non-empty). */
+export declare function updateAt(content: Record<string, EditorNode[]>, path: Step[], transform: (node: EditorNode) => EditorNode): Record<string, EditorNode[]>;
+/** Insert `child` into `slot` of the node at `parentPath` (empty path = the
+ *  root's slots) at `index`; an omitted index appends. */
+export declare function insertAt(content: Record<string, EditorNode[]>, parentPath: Step[], slot: string, child: EditorNode, index?: number): Record<string, EditorNode[]>;
+/** Remove the node at `path` (path must be non-empty). */
+export declare function removeAt(content: Record<string, EditorNode[]>, path: Step[]): Record<string, EditorNode[]>;
+/** The node at `path`, or null when nothing is there. The root is the tree
+ *  itself rather than a node of its content, so the empty path gives null. */
+export declare function nodeAt(content: Record<string, EditorNode[]>, path: Step[]): EditorNode | null;
+/**
+ * The path of a child: the node at `index` in `slot` of the node at `parent`.
+ *
+ * @param parent - The parent's path; `[]` for the root.
+ * @param slot - The slot the child is in.
+ * @param index - The child's index in the slot.
+ * @returns The child's path.
+ */
+export declare function childPath(parent: NodePath, slot: string, index: number): NodePath;
+/**
+ * A string that identifies a path, for a key or a lookup: `'root'` for the
+ * root, otherwise each step's slot and index.
+ *
+ * @param path - The path.
+ * @returns The key, such as `'default:0/header:1'`.
+ */
+export declare function pathKey(path: NodePath): string;
+/** Move the node at `from` to `target`: remove it, then insert it, adjusting the
+ *  target for the index shift the removal causes in a shared sibling list. The
+ *  root, a missing node, and a drop into the node's own subtree leave the
+ *  content unchanged (the same object back). */
+export declare function moveNode(content: Record<string, EditorNode[]>, from: Step[], target: DropTarget): Record<string, EditorNode[]>;
+/** A sortable list's address: the parent whose slot it lists, and the slot. */
+export interface SortableListAddress {
+    parent: Step[];
+    slot: string;
+}
+/** Translate a sortable move (where the node ends up in its list) into the path
+ *  it leaves and the drop target `moveNode` takes (the index it goes before,
+ *  counted before the removal). */
+export declare function resolveSortableMove(source: SortableListAddress, target: SortableListAddress, sameList: boolean, fromIndex: number, toIndex: number): {
+    from: Step[];
+    target: DropTarget;
+};
+/** What the editor reads of a manifest component to seed a node from it. */
+export interface SeedableComponent {
+    name: string;
+    defaultProps: Record<string, Json>;
+    content?: SlotPlan;
+}
+/** A component swapped in under an existing node: its default props, with a
+ *  string `children` default as a default-slot text child (children is the
+ *  default slot, not a prop). */
+export declare function seedNode(component: SeedableComponent): EditorNode;
+/** A component added through the add dialog. With `props` the node carries them
+ *  plus the component's curated slot content (the default or a named scenario);
+ *  without, it comes in empty - no props, no content. */
+export declare function seedComponentNode(component: SeedableComponent, props?: Record<string, Json>): EditorNode;
+/** The root seeded from its story file content, so the tree starts from what the
+ *  browse view renders, with `props` (a story's scenario-merged props) or the
+ *  component's defaults. */
+export declare function seedRoot(component: SeedableComponent, props?: Record<string, Json>): EditorState;
+/**
+ * A key for a tree's slot content, equal for two trees of the same content
+ * whatever their node ids or the order of their props' keys: what the
+ * regeneration payload would carry, serialized with sorted keys.
+ */
+export declare function slotsKey(slots: Record<string, EditorNode[]>): string;
+/** A value as JSON with every object's keys sorted, so two values equal by
+ *  content serialize the same; `undefined` entries are left out. */
+export declare function stableStringify(value: unknown): string;
+/**
+ * The props as JSON, each one left unset (`undefined`) left out. An empty
+ * string is a value like any other and stays, so a component given `''`
+ * keeps it on every update; a story unsets a prop with `null`.
+ *
+ * @param record - The props, from the controls or a pane's write-back.
+ * @returns The props that are set.
+ */
+export declare function cleanRecord(record: Record<string, Json>): Record<string, JsonValue>;
+export declare function namedFills(slots: Record<string, EditorNode[]>): Record<string, SlotFill>;
+export declare function fillToNodes(fill: SlotFill | undefined): EditorNode[];
+/** Seed a root component's slot content from its story file SlotPlan, falling back to
+ *  a default-slot text child when a string `children` prop is the only content. */
+export declare function seedSlots(content: SlotPlan | undefined, props: Record<string, Json>): Record<string, EditorNode[]>;
+/** The regeneration payload for a root component, its props and its slot
+ *  content. */
+export declare function toPayload(state: EditorState): {
+    rootComponent: string;
+    props: Record<string, JsonValue>;
+    slots: {
+        named?: Record<string, SlotFill> | undefined;
+        default?: SlotFill | undefined;
+    } | undefined;
+};

package/dist/declarations/src/controller/html-source.d.ts

@@ -0,0 +1,62 @@
+import type { JsonValue, SlotPlan, StoryAround } from '../lib/types.js';
+/** A story to print as html: the root component, its props and its slot content. */
+export interface HtmlSourceRequest {
+    /** The root component's name. */
+    rootComponent: string;
+    /** The props to render it with. */
+    props: Record<string, JsonValue>;
+    /** Its slot content: the default slot and the named slots. */
+    slots?: SlotPlan;
+    /** The content beside the root, as its siblings: `before` and `after` it. */
+    around?: StoryAround;
+}
+/**
+ * A story's html: its markup, with the styles the kit's build wrote for the
+ * components it renders when there are any and the warnings for what the
+ * markup leaves out when there are any, or what keeps it from having markup.
+ */
+export type HtmlSourceResponse = {
+    markup: string;
+    stylesheet?: string;
+    warnings?: string[];
+} | {
+    missing: string[];
+};
+/**
+ * Prints a story's html. It resolves with the markup or what the story holds
+ * that has no markup, and rejects with the reason it could not print; the
+ * controller aborts `signal` when the story changes before it answers.
+ */
+export type HtmlSourceTransport = (request: HtmlSourceRequest, signal: AbortSignal) => Promise<HtmlSourceResponse>;
+/**
+ * Reads the html printed ahead of time for a component's scenarios, by
+ * scenario id (`''` for the anonymous default). It rejects when there is
+ * none to read.
+ */
+export type ScenarioHtmlSourceLoader = (componentId: string) => Promise<Record<string, HtmlSourceResponse>>;
+/** The path the preview's development server answers html source requests on. */
+export declare const HTML_SOURCE_ENDPOINT = "/__preview_html_source";
+/** The directory, under the URL the preview is served from, that the static
+ *  build keeps each component's scenario html in, one `<component id>.json`
+ *  each. */
+export declare const HTML_SOURCE_DIRECTORY = "html-source";
+/**
+ * A transport that POSTs the story as JSON to the development server's html
+ * source endpoint and reads the JSON it answers. A response that is not ok
+ * rejects with the response's text, or its status when the text is empty.
+ *
+ * @param endpoint - The endpoint's path; the development server's by default.
+ * @param fetchImplementation - The `fetch` to use; the global one by default.
+ * @returns The transport.
+ */
+export declare function createFetchHtmlSourceTransport(endpoint?: string, fetchImplementation?: typeof fetch): HtmlSourceTransport;
+/**
+ * A loader that fetches a component's scenario html from the files the
+ * static build serves, `<baseUrl>html-source/<component id>.json`, once per
+ * component.
+ *
+ * @param baseUrl - The URL the preview is served under, ending in `/`.
+ * @param fetchImplementation - The `fetch` to use; the global one by default.
+ * @returns The loader.
+ */
+export declare function createStaticHtmlSourceLoader(baseUrl: string, fetchImplementation?: typeof fetch): ScenarioHtmlSourceLoader;

package/dist/declarations/src/controller/index.d.ts

@@ -0,0 +1,9 @@
+export { createPreviewController, PREVIEW_FRAME_SHOWN_ATTRIBUTE, REGENERATION_DEBOUNCE_MILLISECONDS, SCRATCH_STORY_ID, type PreviewController, type PreviewControllerOptions, type PreviewEditorState, type PreviewEvent, type PreviewFrameReadiness, type PreviewFrameTarget, type PreviewHtmlSource, type PreviewInsertTarget, type PreviewNodeRequest, type PreviewOptionDescriptor, type PreviewRegenerationStatus, type PreviewSelection, type PreviewSortableDrop, type PreviewCode, type PreviewState, type PreviewTimers, } from './create-preview-controller.js';
+export { printStorySource, type PreviewTargetCode } from './source.js';
+export { createFetchHtmlSourceTransport, createStaticHtmlSourceLoader, HTML_SOURCE_DIRECTORY, HTML_SOURCE_ENDPOINT, type HtmlSourceRequest, type HtmlSourceResponse, type HtmlSourceTransport, type ScenarioHtmlSourceLoader, } from './html-source.js';
+export { previewStore, type PreviewStore } from './store.js';
+export type { PreviewPaneWidth } from '../lib/types.js';
+export { catalogFromManifest, DEFAULT_PANE_WIDTHS, defaultScenarioId, nodeAddSlots, nodeSlots, scenarioChoices, storyFrameKey, type CatalogManifest, type PreviewBinding, type PreviewCatalog, type PreviewCatalogView, type PreviewComponent, type PreviewImport, type PreviewLanding, type PreviewNavigationNode, type PreviewPropType, type PreviewScenario, type PreviewSource, type PreviewStoryReference, type ScenarioChoice, } from './catalog.js';
+export { acceptsPropValue, changedProps, isPaneWidth, MAXIMUM_PANE_WIDTH, parseTargets, parseOptionValue, parsePaneWidth, parseProps, readUrlState, storageKey, URL_PARAMETER, writeUrlState, type PreviewStorage, type UrlState, type UrlStateToWrite, } from './persistence.js';
+export { createFetchRegenerationTransport, REGENERATION_ENDPOINT, type RegenerationPayload, type RegenerationTransport, } from './regeneration.js';
+export { childPath, cleanRecord, DEFAULT_SLOT, HTML_TAGS, isContainer, nodeAt, pathKey, seedNode, type AroundFill, type ContainerNode, type DropTarget, type EditorNode, type EditorState, type NodePath, type OpaqueFill, type SortableListAddress, type Step, type StoryAround, } from './editor-tree.js';

package/dist/declarations/src/controller/persistence.d.ts

@@ -0,0 +1,191 @@
+import type { PreviewPropType } from '../lib/types.js';
+import { type OptionValue, type PreviewOption } from '../options.js';
+import type { PreviewTarget } from '../protocol.js';
+/** The host page's query parameters the controller reads and writes. */
+export declare const URL_PARAMETER: {
+    /** The selected component story's id. */
+    readonly component: "component";
+    /** The selected custom view's id. */
+    readonly view: "view";
+    /** The selected scenario's id. */
+    readonly scenario: "scenario";
+    /** The story's root props that differ from its scenario's, as JSON. */
+    readonly props: "props";
+    /** The visible targets, comma-separated, when not every one is visible. */
+    readonly targets: "targets";
+    /** The width the story panes are laid out at, in CSS pixels, when they
+     *  are not fitted to the space the shell gives them. */
+    readonly width: "width";
+    /** The prefix of an option's parameter: `option.<id>=<value>`. */
+    readonly optionPrefix: "option.";
+};
+/** The part of the Web Storage interface the controller uses. */
+export type PreviewStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/** What the query parameters say, before it is checked against the catalog. */
+export interface UrlState {
+    component?: string;
+    view?: string;
+    scenario?: string;
+    /** The root props as written: JSON, unparsed. */
+    props?: string;
+    /** The visible targets as written: a comma-separated list. */
+    targets?: string;
+    /** The story panes' width as written. */
+    width?: string;
+    /** Option values as written, keyed by option id. */
+    options: Record<string, string>;
+}
+/** What the controller writes to the query parameters. */
+export interface UrlStateToWrite {
+    selection: {
+        kind: 'component' | 'view';
+        id: string;
+    };
+    /** The scenario, when it is not the story's default. */
+    scenario?: string;
+    /** The root props that differ from the scenario's, a prop of the
+     *  scenario's the story leaves out set to `null`. */
+    props?: Record<string, unknown>;
+    /** The visible targets, `html` among them, when not every one of the
+     *  kit's is visible. */
+    targets?: readonly PreviewTarget[];
+    /** The story panes' width in CSS pixels, when they are not fitted. */
+    width?: number;
+    /** The option values to keep, keyed by option id. */
+    options: Record<string, OptionValue>;
+}
+/**
+ * Read the controller's parameters from a query string.
+ *
+ * @param search - The query string, with or without its leading `?`.
+ * @returns The parameters, unchecked.
+ */
+export declare function readUrlState(search: string): UrlState;
+/**
+ * An option's value as written in a query parameter or storage: `true` or
+ * `false` for a boolean, one of its values for a choice.
+ *
+ * @param option - The option.
+ * @param raw - The value as written.
+ * @returns The value, or `undefined` when the option cannot hold it.
+ */
+export declare function parseOptionValue(option: Pick<PreviewOption, 'values'>, raw: unknown): OptionValue | undefined;
+/**
+ * The visible targets a query parameter names, among the kit's, `html`
+ * included where the kit builds it. An empty parameter names none; one that
+ * names none of the kit's is ignored.
+ *
+ * @param raw - The parameter as written: a comma-separated list.
+ * @param targets - The kit's targets (`PreviewCatalog.targets`).
+ * @returns The targets in the kit's order, or `undefined` when the
+ *   parameter is to be ignored.
+ */
+export declare function parseTargets(raw: string, targets: readonly PreviewTarget[]): PreviewTarget[] | undefined;
+/** The widest a story pane is laid out at, in CSS pixels: an 8K screen's width. */
+export declare const MAXIMUM_PANE_WIDTH = 7680;
+/**
+ * Whether `value` can be a story pane's width: a whole number of CSS pixels,
+ * from 1 to `MAXIMUM_PANE_WIDTH`.
+ *
+ * @param value - The candidate width.
+ * @returns Whether it is one.
+ */
+export declare function isPaneWidth(value: unknown): value is number;
+/**
+ * The story panes' width a query parameter names: a whole number of CSS
+ * pixels, from 1 to `MAXIMUM_PANE_WIDTH`.
+ *
+ * @param raw - The parameter as written, such as `768`.
+ * @returns The width, or `undefined` when the parameter is to be ignored.
+ */
+export declare function parsePaneWidth(raw: string): number | undefined;
+/**
+ * Whether a prop's control can hold `value`: a boolean for a toggle, a
+ * finite number for a number input, one of its values for a select, one of
+ * the color tokens for a color select, and a string or a number for a text
+ * input.
+ *
+ * @param propType - The prop.
+ * @param value - The candidate value.
+ * @param colorTokens - The color tokens a color select offers.
+ * @returns Whether the prop accepts the value.
+ */
+export declare function acceptsPropValue(propType: Pick<PreviewPropType, 'control' | 'options'>, value: unknown, colorTokens: readonly (string | null)[]): boolean;
+/**
+ * The props that differ from `base`, as the address holds them: each prop
+ * whose value differs, and each prop of `base` the props leave out, as
+ * `null`, so a link opens on what renders. {@link parseProps} reads them
+ * back over the same `base`.
+ *
+ * @param props - The props the story renders with.
+ * @param base - The props the story starts from: its scenario's.
+ * @param marksMissing - Whether a prop of `base` the props leave out is
+ *   written as `null`.
+ * @returns The props that differ, in their order, then those left out.
+ * @example
+ * ```ts
+ * changedProps({ selected: 'b', items }, { selected: 'a', items, icon: 'plus' }, () => true);
+ * // { selected: 'b', icon: null }
+ * ```
+ */
+export declare function changedProps(props: Record<string, unknown>, base: Record<string, unknown>, marksMissing: (name: string) => boolean): Record<string, unknown>;
+/**
+ * The root props a query parameter gives, checked against the component's
+ * props. The parameter holds the props that differ from the scenario's: a
+ * prop it leaves out takes its value in `defaults`, the scenario's props, as
+ * a freshly picked scenario does, and a prop it sets to `null` is left out
+ * of the result, unless `fallback` holds `null` for it, which keeps the
+ * `null`.
+ * Only props the component declares, with a value its control
+ * accepts, are kept; a declared prop whose value is refused keeps its value
+ * in `fallback`, the scenario's props, or else its default. A parameter that
+ * is not a JSON object is ignored.
+ *
+ * @param raw - The parameter as written.
+ * @param propTypes - The component's props.
+ * @param defaults - The props a prop left out keeps: the scenario's.
+ * @param fallback - The scenario's props, for a refused value.
+ * @param colorTokens - The color tokens a color select offers.
+ * @returns The props, or `undefined` when the parameter is to be ignored.
+ * @example
+ * ```ts
+ * parseProps('{"variant":"ghost","icon":null}', propTypes, { size: 'md', icon: 'plus' }, {}, []);
+ * // { size: 'md', variant: 'ghost' }
+ * ```
+ */
+export declare function parseProps(raw: string, propTypes: readonly Pick<PreviewPropType, 'name' | 'control' | 'options'>[], defaults: Record<string, unknown>, fallback: Record<string, unknown>, colorTokens: readonly (string | null)[]): Record<string, unknown> | undefined;
+/**
+ * Write the controller's parameters into a query string, keeping every
+ * parameter that is not the controller's.
+ *
+ * @param search - The current query string.
+ * @param state - What to write.
+ * @returns The new query string, without its leading `?`.
+ */
+export declare function writeUrlState(search: string, state: UrlStateToWrite): string;
+/**
+ * The local-storage key a kit's remembered option values live under.
+ *
+ * @param kitName - The kit's name.
+ * @returns The key.
+ */
+export declare function storageKey(kitName: string): string;
+/**
+ * The option values remembered under `key`, those the options can still
+ * hold. Storage that cannot be read, or holds something else, gives none.
+ *
+ * @param storage - The storage.
+ * @param key - The key.
+ * @param options - The options the values may belong to.
+ * @returns The values, keyed by option id.
+ */
+export declare function readStoredOptions(storage: PreviewStorage, key: string, options: Array<Pick<PreviewOption, 'id' | 'values'>>): Record<string, OptionValue>;
+/**
+ * Remember option values under `key`; with none, forget them. A storage that
+ * refuses the write (private browsing, a full or blocked store) is ignored.
+ *
+ * @param storage - The storage.
+ * @param key - The key.
+ * @param values - The values to remember, keyed by option id.
+ */
+export declare function writeStoredOptions(storage: PreviewStorage, key: string, values: Record<string, OptionValue>): void;

package/dist/declarations/src/controller/regeneration.d.ts

@@ -0,0 +1,30 @@
+import type { JsonValue, SlotPlan, StoryAround } from '../lib/types.js';
+/** The scratch story to regenerate: the root component, its props and its slot content. */
+export interface RegenerationPayload {
+    /** The root component's export name. */
+    rootComponent: string;
+    /** The root's own props. */
+    props: Record<string, JsonValue>;
+    /** The root's slot content: its default slot and its named slots. */
+    slots?: SlotPlan;
+    /** The content beside the root, as its siblings: `before` and `after` it. */
+    around?: StoryAround;
+}
+/**
+ * Carries a regeneration payload to whatever writes the scratch story. It resolves
+ * once the story is written and rejects with the reason it was not; the
+ * controller reports the rejection's message.
+ */
+export type RegenerationTransport = (payload: RegenerationPayload) => Promise<void>;
+/** The path the preview's development server answers regeneration requests on. */
+export declare const REGENERATION_ENDPOINT = "/__preview_regenerate";
+/**
+ * A transport that POSTs the payload as JSON to the development server's
+ * regeneration endpoint. A response that is not ok rejects with the response's text,
+ * or its status when the text is empty.
+ *
+ * @param endpoint - The endpoint's path; the development server's by default.
+ * @param fetchImplementation - The `fetch` to use; the global one by default.
+ * @returns The transport.
+ */
+export declare function createFetchRegenerationTransport(endpoint?: string, fetchImplementation?: typeof fetch): RegenerationTransport;

package/dist/declarations/src/controller/source.d.ts

@@ -0,0 +1,80 @@
+import { type SourceBinding } from '../emit/source.js';
+import type { JsonValue, SlotFill, StoryAround } from '../lib/types.js';
+import type { PreviewScriptedTarget } from '../protocol.js';
+import { type PreviewCatalog, type PreviewComponent, type PreviewScenario, type PreviewStoryReference } from './catalog.js';
+import { type EditorState } from './editor-tree.js';
+/** A story's source, by scripted target: what a consumer writes. */
+export type PreviewTargetCode = Partial<Record<PreviewScriptedTarget, string>>;
+/** A story resolved for printing: its component, the props to print and its
+ *  slot content. */
+export interface ResolvedSourceStory {
+    /** The root component's name. */
+    component: string;
+    /** The props a consumer writes: those that differ from what the component
+     *  and the preview start from. */
+    props: Record<string, JsonValue>;
+    /** Default-slot content. */
+    children?: SlotFill;
+    /** Named-slot content, by slot name. */
+    named: Record<string, SlotFill>;
+    /** The content beside the component, as its siblings. */
+    around?: StoryAround;
+    /** The two-way props the story gives, which the printed source binds to
+     *  state of its own. Absent when it gives none. */
+    bindings?: SourceBinding[];
+}
+/** The catalog fields the printing reads. */
+export type SourceCatalog = Pick<PreviewCatalog, 'imports' | 'sources' | 'kitName'> & Partial<Pick<PreviewCatalog, 'svelteMode' | 'reactAttributeNames'>>;
+/**
+ * Whether a story's default-slot text is the component's name the preview
+ * shows in a default slot the story leaves unfilled, which a consumer never
+ * writes: the preview's own starting text, while the scenario does not give
+ * `children` itself.
+ */
+export declare function isPlaceholder(component: PreviewComponent, text: string, input: {
+    scenario?: PreviewScenario;
+}): boolean;
+/**
+ * Resolve what a story's source prints. Without a tree, the slot content is
+ * the story's own and a string `children` is its default-slot text; with the
+ * editor's tree, the root's props and content are the tree's. A prop is left
+ * out while it holds the component's declared default, or the preview's own
+ * starting value that the scenario does not set, as is the component's name
+ * the preview shows in a default slot the story leaves unfilled.
+ */
+export declare function resolveSourceStory(component: PreviewComponent, input: {
+    props: Record<string, unknown>;
+    scenario?: PreviewScenario;
+    tree?: EditorState;
+}): ResolvedSourceStory;
+/**
+ * Print a resolved story in each of `targets`: a two-way prop it gives
+ * bound to state of the source's own, in the catalog's Svelte mode.
+ *
+ * @param catalog - The catalog the components' imports are read from.
+ * @param story - The story, resolved.
+ * @param targets - The targets to print.
+ * @returns The source per target.
+ */
+export declare function printSourceStory(catalog: SourceCatalog, story: ResolvedSourceStory, targets: readonly PreviewScriptedTarget[]): PreviewTargetCode;
+/**
+ * Print any story of the catalog as the source a consumer writes, per
+ * target the component renders in: the component with the props of the
+ * scenario over its defaults and `props` over those, its slot content, and
+ * imports from the kit's package entry for each target. A prop is left
+ * out while it holds the component's declared default. It takes the story
+ * reference `frames.mountStory` takes, so a shell can show the code beside a
+ * detached pane. The html source is the preview's own (`state.code.html`)
+ * and is not printed here.
+ *
+ * @param catalog - The controller's catalog.
+ * @param story - The story: a component's id, a scenario (omitted, the one
+ *   the story starts on; `''`, the anonymous default) and props over its own.
+ * @returns The source per target, in the component's targets.
+ * @throws When the component or the scenario is unknown.
+ * @example
+ * ```ts
+ * const { react } = printStorySource(controller.catalog, { component: 'components-button', scenario: 'ghost' });
+ * ```
+ */
+export declare function printStorySource(catalog: PreviewCatalog, story: PreviewStoryReference): PreviewTargetCode;

package/dist/declarations/src/controller/store.d.ts

@@ -0,0 +1,27 @@
+import type { PreviewController, PreviewState } from './create-preview-controller.js';
+/** A readable store: `subscribe` calls `listener` with the current value
+ *  immediately, then with each new value, until the returned function is called. */
+export interface PreviewStore<Value> {
+    subscribe(listener: (value: Value) => void): () => void;
+}
+/**
+ * A store of the controller's state, or of a slice of it. Each subscriber is
+ * called with the current slice when it subscribes, and again only when the
+ * slice changes by identity, so `selector` returns a field of the state (or a
+ * primitive derived from it) rather than a fresh object or array.
+ *
+ * @param controller - The controller to read.
+ * @param selector - Picks the slice; the whole state when omitted.
+ * @returns The store.
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { previewStore } from '@scaffold-ui-kit/preview/shell';
+ *   const preview = previewStore(controller);
+ *   const scenario = previewStore(controller, (state) => state.scenario);
+ * </script>
+ *
+ * <p>{$preview.selection.id}: {$scenario}</p>
+ * ```
+ */
+export declare function previewStore<Selected = PreviewState>(controller: Pick<PreviewController, 'getState' | 'subscribe'>, selector?: (state: PreviewState) => Selected): PreviewStore<Selected>;

package/dist/declarations/src/emit/common.d.ts

@@ -0,0 +1,103 @@
+import type { JsonValue, SlotFill, ResolvedStory } from '../lib/types.js';
+export declare function serialize(value: JsonValue): string;
+/**
+ * Text as a Vue or Svelte template reads it back: `&` and `<` escaped, as
+ * either would start a character reference or open a tag.
+ *
+ * @param value - The text as the story gives it.
+ * @returns The text as markup.
+ */
+export declare function markupText(value: string): string;
+/**
+ * Whether a text has whitespace a template does not keep as written:
+ * whitespace at an edge, a run of it or a line break, which a template
+ * trims, collapses, or loses where the printed element breaks over lines.
+ *
+ * @param value - The text as the story gives it.
+ * @returns Whether the text has to be printed as a string expression.
+ */
+export declare function hasFragileWhitespace(value: string): boolean;
+/**
+ * Text as a Vue template reads it back: markup text with each `{{` held in
+ * an interpolation of its own, so it does not open one.
+ *
+ * @param value - The text as the story gives it.
+ * @returns The text as Vue template content.
+ * @example
+ * vueText('Type {{ name }} here');
+ * // 'Type {{ "{{" }} name }} here'
+ */
+export declare function vueText(value: string): string;
+/**
+ * Text as a printed Vue template keeps it: {@link vueText}, or one string
+ * interpolation for a text with whitespace at an edge, a run of it or a
+ * line break, which Vue condenses and a printed element's line breaks
+ * replace.
+ *
+ * @param value - The text as the story gives it.
+ * @returns The text as Vue template content.
+ * @example
+ * vueSourceText(' 1 ripburger');
+ * // '{{ " 1 ripburger" }}'
+ */
+export declare function vueSourceText(value: string): string;
+/**
+ * The Vue template content before a junction, given the content joined onto
+ * it: a trailing `{` before content starting with one is held in an
+ * interpolation of its own, as the two would otherwise open one.
+ *
+ * @param before - The content before the junction.
+ * @param next - The content joined onto it.
+ * @returns The content before the junction, safe to join.
+ * @example
+ * vueJunction('Price: {', '{ amount }}');
+ * // "Price: {{ '{' }}"
+ */
+export declare function vueJunction(before: string, next: string): string;
+/**
+ * Vue template pieces joined into one, each junction separated by
+ * {@link vueJunction}.
+ *
+ * @param pieces - The template content, in order.
+ * @returns The joined content.
+ */
+export declare function joinVue(pieces: string[]): string;
+/**
+ * Text as a Svelte template reads it back: markup text with each brace held
+ * in an expression of its own, so none opens one. Svelte trims the whitespace
+ * at the edges of an element's or a component's content and collapses a run
+ * of it, so a text with whitespace at an edge, a run of it or a line break
+ * is one string expression instead, which Svelte renders as it is.
+ *
+ * @param value - The text as the story gives it.
+ * @returns The text as Svelte markup.
+ * @example
+ * svelteText('Price: {amount}');
+ * // "Price: {'{'}amount{'}'}"
+ * svelteText(' 1 ripburger');
+ * // '{" 1 ripburger"}'
+ */
+export declare function svelteText(value: string): string;
+/**
+ * A value as a Vue template's bound attribute holds it, single-quoted:
+ * the value's expression with `&` and `'` as character references, which
+ * the template reads back as the characters, so neither ends the attribute
+ * nor starts a reference of its own.
+ *
+ * @param value - The prop's value.
+ * @returns The attribute's text, quotes included.
+ * @example
+ * vueBoundAttribute("Don't");
+ * // `'"Don&#39;t"'`
+ */
+export declare function vueBoundAttribute(value: JsonValue): string;
+export declare function needsColor(model: ResolvedStory): boolean;
+export declare function propTypesBody(model: ResolvedStory): string;
+/** The effective default-slot fill: an explicit story file fill, or the `children`
+ *  text prop for components that have a default slot and no story file fill. */
+export type DefaultSlot = SlotFill | {
+    kind: 'propText';
+    prop: string;
+} | undefined;
+export declare function effectiveDefaultSlot(model: ResolvedStory): DefaultSlot;
+export declare function namedSlots(model: ResolvedStory): Record<string, SlotFill>;