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

package/dist/controller/create-preview-controller.d.ts

@@ -0,0 +1,532 @@
+import { type OptionValue, type PreviewOption, type PreviewShellOption } from '../options.js';
+import { type PreviewContentSize, type PreviewScriptedTarget, type PreviewTarget } from '../protocol.js';
+import { type PreviewCatalog, type PreviewStoryReference } from './catalog.js';
+import { type DropTarget, type EditorNode, type EditorState, type SortableListAddress, type Step } from './editor-tree.js';
+import type { RegenerationTransport } from './regeneration.js';
+import type { HtmlSourceTransport, ScenarioHtmlSourceLoader } from './html-source.js';
+import { type PreviewTargetCode } from './source.js';
+import type { PreviewPersistence } from '../lib/types.js';
+import { type PreviewStorage } from './persistence.js';
+/** The time edits coalesce for before the preview regenerates what they
+ *  change, in milliseconds: the scratch story, and a story's html from the
+ *  development server. */
+export declare const REGENERATION_DEBOUNCE_MILLISECONDS = 250;
+/** The story id the regenerated scratch story is mounted under. */
+export declare const SCRATCH_STORY_ID = "scratch";
+/**
+ * The attribute the controller sets on an iframe it mounted once the iframe
+ * shows its first content, and takes away while it loads again. Until then
+ * the iframe is hidden; a shell's CSS can show a loading note beside one
+ * without it.
+ */
+export declare const PREVIEW_FRAME_SHOWN_ATTRIBUTE = "data-preview-shown";
+/**
+ * An option a shell shows a control for: one of the kit's, or one the shell
+ * declared for itself, whose id is namespaced under `shell.` and whose value
+ * stays in the host page.
+ */
+export interface PreviewOptionDescriptor extends Omit<PreviewOption, 'apply'> {
+    /** Whether the option is the kit's or the shell's own. */
+    origin: 'kit' | 'shell';
+}
+/** What the preview shows: a component story or a custom view. */
+export type PreviewSelection = {
+    kind: 'component';
+    id: string;
+} | {
+    kind: 'view';
+    id: string;
+};
+/** A preview iframe: a scripted target's pane, the html pane or the custom-view pane. */
+export type PreviewFrameTarget = PreviewTarget | 'view';
+/** Whether a mounted iframe has announced that it listens for messages. */
+export type PreviewFrameReadiness = 'loading' | 'ready';
+/** One call a story made of one of its events, as a pane recorded it. */
+export interface PreviewEvent {
+    /** Its number among the events recorded, for a stable key. */
+    id: number;
+    /** The pane it was recorded in. */
+    target: PreviewFrameTarget;
+    /** The event: the function prop the story called. */
+    name: string;
+    /** A readable, one-line summary of what it was called with. */
+    payload: string;
+    /** When, in milliseconds since the epoch. */
+    time: number;
+}
+/** Where the regeneration of the scratch story stands. */
+export interface PreviewRegenerationStatus {
+    /** `pending` from an edit until the story is written and the panes reloaded. */
+    status: 'idle' | 'pending' | 'error';
+    /** Why the last regeneration failed, while `status` is `error`. */
+    message?: string;
+}
+/** The scenario editor's state. */
+export interface PreviewEditorState {
+    /** Whether a shell shows the editor. */
+    open: boolean;
+    /** The tree being edited: the story's component, its props and its slot
+     *  content. Present while the editor is open or the Empty scenario is shown. */
+    tree?: EditorState;
+    /**
+     * Whether the tree's slot content differs from what it was seeded with:
+     * a node inserted, removed, moved or replaced, a nested node's props or a
+     * text changed. The root's props are not counted, as they live in `props`
+     * and the address. Content is compared by value, so an edit undone by hand
+     * counts as no change. A change of the root's text, which `props` shows as
+     * `children`, counts too. `false` without a tree, and again once the tree
+     * is seeded afresh (another story, or another scenario with the editor
+     * open). While it is `true` the address may not reproduce the panes, which
+     * show the edited content.
+     */
+    modified: boolean;
+}
+/**
+ * Where the html source of what the panes show stands: `ready` with the
+ * markup, `loading` while it is being printed, or `unavailable` with the
+ * reason, such as a story holding a part that has no markup, or a static
+ * build asked for props it printed no html for.
+ */
+export type PreviewHtmlSource = {
+    status: 'ready';
+    source: string;
+    /** The styles the kit's build wrote for the components the markup
+     *  renders, which the html pane shows it under. */
+    stylesheet?: string;
+    /** What the markup could not work out at rest and left out, such as
+     *  an expression reading the component's script state, so that part
+     *  shows at a default. Absent when there is nothing to name. */
+    warnings?: string[];
+} | {
+    status: 'loading';
+} | {
+    status: 'unavailable';
+    reason: string;
+};
+/** The code of what the selection's panes show. */
+export interface PreviewCode {
+    /**
+     * The code a consumer writes for the story, per target the story
+     * renders in (`targets.supported`), html aside: the component with the props the
+     * panes show and its slot content, or the editor's tree while it holds
+     * one, importing from the kit's package entry for each target. A prop is
+     * left out while it holds the component's declared default. Printed as the
+     * state changes, so it is always present.
+     */
+    targets: PreviewTargetCode;
+    /** The markup the story renders to, at rest, for a reader who works
+     *  without a framework. */
+    html: PreviewHtmlSource;
+}
+/**
+ * The preview's state as a shell reads it. Every field is plain data: a
+ * snapshot is immutable, and a new one replaces it on each change, with the
+ * unchanged fields kept by reference.
+ */
+export interface PreviewState {
+    selection: PreviewSelection;
+    /** The selected scenario's id; `''` is the anonymous default. */
+    scenario: string;
+    /**
+     * The root props the selection's panes show now: the scenario's over the
+     * component's defaults, then whatever `setProps` or the editor's root set.
+     * While the editor holds a tree, a string `children` the story draws its
+     * default slot from is the root's text: `children` is the text while the
+     * root's default slot holds one text node and nothing else, and absent
+     * otherwise, as other content in that slot takes its place on screen. A
+     * story with default-slot content of its own shows that content and not
+     * `children`, so its props carry no `children` then. While a view is
+     * selected, the last story's.
+     */
+    props: Record<string, unknown>;
+    /** Every option's current value, the story's own defaults applied, keyed by
+     *  option id; a shell's own options under their `shell.` ids. */
+    options: Record<string, OptionValue>;
+    /** The options a shell hides the controls of: those the selected story marks
+     *  unavailable, and every story option while a view is selected. */
+    unavailableOptions: string[];
+    /**
+     * The story panes, by what each renders in: the kit's scripted targets, and
+     * `html` after them where the kit builds html. The html pane shows the
+     * markup in `code.html`, with the kit's stylesheets and options and no
+     * behavior; every story supports it.
+     */
+    targets: {
+        /** What the selected story renders in, among the kit's. */
+        supported: PreviewTarget[];
+        /** What is turned on among the kit's, whether or not the story supports it. */
+        visible: PreviewTarget[];
+        /** The panes a shell mounts: the supported ones that are turned on, in order. */
+        panes: PreviewTarget[];
+    };
+    /**
+     * The width a shell lays each of the selection's story panes out at, in
+     * CSS pixels, so a component that responds to its width shows as it does
+     * on a screen that wide: one of `catalog.paneWidths`, or any width a link
+     * names. Absent while the panes fit the space the shell gives them. A
+     * shell decides how a pane wider than its space shows, such as scrolling
+     * across it. It outlasts the story, and a view's pane does not follow it.
+     */
+    paneWidth?: number;
+    /** The readiness of the selection's panes, by target (`html` among
+     *  them), and of the view pane under `view`. */
+    frames: Partial<Record<PreviewFrameTarget, PreviewFrameReadiness>>;
+    /** The readiness of the detached story panes `frames.mountStory` mounted,
+     *  by the key `storyFrameKey(target, story)` gives. */
+    storyFrames: Record<string, PreviewFrameReadiness>;
+    /**
+     * The size of what each of the selection's panes shows, by target, and
+     * of the view pane under `view`, as the pane last reported it: its story
+     * or view with the space the kit's canvas puts around it, in whole CSS
+     * pixels. A shell that sizes a pane to its content sets the iframe's height
+     * to `height`. An entry appears once the pane has rendered, keeps its last
+     * size while the pane reloads, and goes when the pane is unmounted. The
+     * width is the content's at the pane's current width, as block content
+     * fills the pane.
+     */
+    frameSizes: Partial<Record<PreviewFrameTarget, PreviewContentSize>>;
+    /** What each of the selection's panes threw as its story rendered, by
+     *  target: the error's message, shown in the story's place. An entry
+     *  goes when the pane mounts a story that renders, and when the pane is
+     *  unmounted. */
+    frameErrors: Partial<Record<PreviewFrameTarget, string>>;
+    /** The events the selection's panes recorded, oldest first and the last
+     *  hundred at most: each call a story made of one of its events
+     *  (`PreviewComponent.events`). Cleared when another story or a view is
+     *  selected, and by `actions.clearEvents`. */
+    events: PreviewEvent[];
+    /** The size of what each detached story pane shows, as `frameSizes` holds
+     *  the selection's, by the key `storyFrameKey(target, story)` gives. */
+    storyFrameSizes: Record<string, PreviewContentSize>;
+    editor: PreviewEditorState;
+    regeneration: PreviewRegenerationStatus;
+    /** The code of what the selection's panes show, per target and as
+     *  html. Absent while a view is selected. */
+    code?: PreviewCode;
+}
+/** What `createNode` makes: a text leaf, a plain HTML tag, or a component. */
+export type PreviewNodeRequest = {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'html';
+    tag: string;
+} | {
+    kind: 'component';
+    /** The component's export name. */
+    name: string;
+    /** What the component comes in with: nothing (`empty`, the default), its
+     *  curated defaults and slot content (`default`), or a scenario's props
+     *  over its defaults. A component with no slot content and no scenarios
+     *  always comes in with its defaults. */
+    importAs?: 'empty' | 'default' | {
+        scenario: string;
+    };
+};
+/** Where a node is inserted: into `slot` of the node at `parent` (the root's
+ *  slots when empty), before `index`, or at the end when `index` is omitted. */
+export interface PreviewInsertTarget {
+    parent: Step[];
+    slot: string;
+    index?: number;
+}
+/** What a shell's sortable lists report when a node is dropped. */
+export interface PreviewSortableDrop {
+    /** The list the node was dragged from. */
+    source: SortableListAddress;
+    /** The list it was dropped in. */
+    target: SortableListAddress;
+    /** Whether the two are the same list. */
+    sameList: boolean;
+    /** The node's index in the source list. */
+    fromIndex: number;
+    /** The index it was dropped at in the target list. */
+    toIndex: number;
+}
+/** The timers the controller debounces with; the global ones by default. */
+export interface PreviewTimers {
+    setTimeout(callback: () => void, milliseconds: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+/** What `createPreviewController` takes. */
+export interface PreviewControllerOptions {
+    /** The kit's catalog. */
+    catalog: PreviewCatalog;
+    /** The kit's preview options. */
+    options: PreviewOption[];
+    /** The shell's own options, as it declares them; the controller namespaces
+     *  their ids under `shell.`. */
+    shellOptions?: PreviewShellOption[];
+    /** Carries the scratch story to whatever writes it. Without one, the
+     *  preview cannot regenerate and `capabilities.regeneration` is `false`. */
+    regeneration?: RegenerationTransport;
+    /** Prints the html of any story, as the development server does. Asked
+     *  once a story's changes pause, and aborted when the story changes again. */
+    htmlSource?: HtmlSourceTransport;
+    /** Reads the html printed ahead of time for each scenario, as the static
+     *  build serves it. Used without `htmlSource`; the html of props that differ
+     *  from a scenario's, or of the editor's tree, is then unavailable. */
+    scenarioHtmlSources?: ScenarioHtmlSourceLoader;
+    /** The window the iframes post their messages to, and whose location holds
+     *  the preview's query parameters; the global one by default. */
+    window?: Window;
+    /** Where the controller remembers what a person chose: the query parameters
+     *  alone (`'url'`, the default), or also the global option values in local
+     *  storage, per kit name (`'url-and-local-storage'`). */
+    persistence?: PreviewPersistence;
+    /** The storage `'url-and-local-storage'` uses; the window's local storage by default. */
+    storage?: PreviewStorage;
+    /** The timers to debounce with; the global ones by default. */
+    timers?: PreviewTimers;
+    /** The URL the preview's pages are served under, ending in `/`, such as
+     *  `https://example.com/kit/`: the iframes load their pages from it. It
+     *  is fixed when the controller is created, so a shell that changes the
+     *  host page's path or hash for its own routing does not move the iframes.
+     *  `/`, the root of the host page's origin, by default. */
+    baseUrl?: string;
+}
+/** The preview's behavior, for a shell to render. */
+export interface PreviewController {
+    /** The version of this contract. */
+    readonly apiVersion: 1;
+    /** The kit's catalog, static for the controller's lifetime. */
+    readonly catalog: PreviewCatalog;
+    /** The options a shell shows controls for: the kit's, then the shell's own. */
+    readonly options: PreviewOptionDescriptor[];
+    readonly capabilities: {
+        /** Whether the scratch story can be regenerated, which the editor and the
+         *  Empty scenario need. False in a static build. */
+        regeneration: boolean;
+    };
+    /** The current state. */
+    getState(): PreviewState;
+    /**
+     * Call `listener` with each new state.
+     *
+     * @returns A function that stops the calls.
+     */
+    subscribe(listener: (state: PreviewState) => void): () => void;
+    actions: {
+        /**
+         * Show a component's story, on its baseline scenario, or with `props`
+         * over its defaults when given. The option values the baseline scenario
+         * sets are set as `pickScenario` sets them. A component that is not
+         * standalone and an unknown id are ignored.
+         */
+        selectComponent(id: string, props?: Record<string, unknown>): void;
+        /** Show a custom view. Unknown ids are ignored. */
+        selectView(id: string): void;
+        /**
+         * Show what `selection` names: a component's story on its baseline
+         * scenario, or a custom view. One navigation control can hand over the
+         * selection it lists without telling the two apart.
+         *
+         * @example
+         * ```ts
+         * controller.actions.select({ kind: 'view', id: 'swatches' });
+         * ```
+         */
+        select(selection: PreviewSelection): void;
+        /**
+         * Pick a scenario of the selected story; `''` is the anonymous default.
+         * The option values the scenario sets (`PreviewScenario.options`) are set
+         * as `setOption` sets them, so the panes, the controls and the address
+         * follow; the values it does not set stay as they are, and picking
+         * another scenario keeps them, apart from those the next one sets. The
+         * Empty scenario is ignored where the preview cannot regenerate.
+         */
+        pickScenario(id: string): void;
+        /** Set an option's value. A story option's value lasts until another story is selected. */
+        setOption(id: string, value: OptionValue): void;
+        /**
+         * Replace the selected story's root props with `props`, which are not
+         * merged into the current ones. They reach the panes live, with no
+         * regeneration, whether or not the editor is open; the editor's root
+         * takes them too. While the editor holds a tree, `children` is the
+         * root's text, as `state.props` shows it: a new string replaces the
+         * content of the root's default slot with that one text, and leaving
+         * `children` out removes a lone text, each an edit of the tree's content
+         * that regenerates the story; content other than a lone text stays while
+         * `children` is left out. A story with default-slot content of its own
+         * takes no `children` then. Props that are `undefined` are dropped. Ignored
+         * while a view is selected; picking a scenario or a story seeds them
+         * afresh.
+         *
+         * @example
+         * ```ts
+         * const { props } = controller.getState();
+         * controller.actions.setProps({ ...props, variant: 'ghost' });
+         * ```
+         */
+        setProps(props: Record<string, unknown>): void;
+        /** Turn a scripted target's pane, or the html pane, on or off. The choice
+         *  outlasts the story. */
+        setTargetVisible(target: PreviewTarget, visible: boolean): void;
+        /**
+         * Lay the story panes out at `width` CSS pixels, or, with `undefined`,
+         * fit them to the shell's space again (`state.paneWidth`). A width that
+         * is not a whole number from 1 to `MAXIMUM_PANE_WIDTH` (7680) is
+         * ignored. The choice outlasts the story.
+         *
+         * @example
+         * ```ts
+         * const medium = controller.catalog.paneWidths.find((paneWidth) => paneWidth.label === 'medium');
+         * controller.actions.setPaneWidth(medium?.width);
+         * ```
+         */
+        setPaneWidth(width: number | undefined): void;
+        /** Empty the log of recorded events. */
+        clearEvents(): void;
+    };
+    editor: {
+        /** Open the editor on the selected story, seeding its tree from the story's content. */
+        open(): void;
+        /** Close the editor. Its tree stays as it is until another story or scenario is selected. */
+        close(): void;
+        /**
+         * Make a node to insert, by the catalog's component data.
+         *
+         * @param request - What to make: a text leaf, an HTML tag, or a
+         *   component by its export name.
+         * @returns The tree's node: `{ kind: 'text', value }`,
+         *   `{ kind: 'html', tag, props, slots }`, or, for a component,
+         *   `{ kind: 'element', component, props, slots }`.
+         */
+        createNode(request: PreviewNodeRequest): EditorNode;
+        insert(target: PreviewInsertTarget, node: EditorNode): void;
+        /** Move the node at `from` to `to`, whose index is counted before the node
+         *  is taken out, as a drop reports it; a move into the node's own subtree
+         *  is ignored. */
+        move(from: Step[], to: DropTarget): void;
+        /**
+         * Move the node at `path` within its slot by `offset` places: `-1` one
+         * up, `1` one down. The move stops at either end of the slot, and a node
+         * already there stays put.
+         *
+         * @example
+         * ```ts
+         * controller.editor.moveBy(path, -1); // one place up
+         * ```
+         */
+        moveBy(path: Step[], offset: number): void;
+        /** Put `node` in place of the node at `path`. */
+        replace(path: Step[], node: EditorNode): void;
+        remove(path: Step[]): void;
+        /** Replace the props of the node at `path` with `props`, which are not
+         *  merged into the node's current ones. The empty path is the root: it
+         *  does what `actions.setProps(props)` does, live, without a regeneration,
+         *  except that the root's content, and so its `children`, stays as it
+         *  is, as the tree's root props never hold `children`. */
+        setNodeProps(path: Step[], props: Record<string, unknown>): void;
+        /** Set the value of the text node at `path`. */
+        setText(path: Step[], text: string): void;
+        /** The move a sortable drop amounts to. */
+        resolveDrop(drop: PreviewSortableDrop): {
+            from: Step[];
+            to: DropTarget;
+        };
+    };
+    frames: {
+        /**
+         * Mount a scripted target's pane, or the html pane, inside `element`: an
+         * iframe with no size of its own, which the shell sizes. The controller
+         * owns the iframe: it loads it, reloads a scripted target's after each
+         * regeneration and answers it. The html pane shows the markup of
+         * `code.html` as it changes, keeping what it shows while the next is
+         * printed and saying why when there is none; it runs none of the story's
+         * behavior. The pane's readiness reaches subscribers after this call
+         * returns, never during it, and the size of what it shows reaches
+         * `frameSizes` once it renders.
+         *
+         * @returns A function that unmounts the pane.
+         */
+        mount(element: HTMLElement, target: PreviewTarget): () => void;
+        /**
+         * Mount a custom view's pane inside `element`, as `mount` mounts a
+         * target's: a bare iframe the shell sizes, its readiness reported after
+         * this call returns.
+         *
+         * @returns A function that unmounts the pane.
+         */
+        mountView(element: HTMLElement, viewId: string): () => void;
+        /**
+         * Mount a read-only pane of any story inside `element`, apart from the
+         * selection: a bare iframe the shell sizes, as `mount` makes. Its props
+         * are the scenario's over the component's defaults, then `story.props`
+         * over those. `scenario` omitted is the story's starting scenario, as
+         * selecting the story picks it, and `''` the anonymous default. The pane
+         * follows the global options; its story options are the component's own,
+         * as selecting it would seed them, and the option values its scenario
+         * sets stay over both. It never shows the editor's content and is not
+         * reloaded by a regeneration. Its readiness is reported in
+         * `storyFrames` under `storyFrameKey(target, story)`, after this call
+         * returns, and the size of what it shows in `storyFrameSizes` under the
+         * same key.
+         *
+         * @param element - The element to append the iframe to.
+         * @param target - The target to render the story in.
+         * @param story - The story: a browseable component's id, a scenario and props.
+         * @returns A function that unmounts the pane.
+         * @throws When the component is unknown or not standalone, the target is
+         *   not among its targets, or the scenario is unknown or the Empty one,
+         *   which renders through the selection's regenerated story.
+         * @example
+         * ```ts
+         * for (const scenario of component.scenarios.filter((scenario) => !scenario.empty)) {
+         *   const cell = grid.appendChild(document.createElement('div'));
+         *   controller.frames.mountStory(cell, 'react', { component: component.id, scenario: scenario.id });
+         * }
+         * ```
+         */
+        mountStory(element: HTMLElement, target: PreviewScriptedTarget, story: PreviewStoryReference): () => void;
+        /**
+         * Mount the kit's code block inside `element`, showing `target`'s source
+         * of the selection: an iframe the shell sizes, which the block fills and
+         * scrolls as it likes. It follows the source as the story, its props and
+         * its content change, and the global option values: a story option sets
+         * nothing in a code block. For a kit that names a code block
+         * (`catalog.codeBlock`); its readiness and size are the block's own and
+         * reach no state.
+         *
+         * @returns A function that unmounts the block.
+         */
+        mountCode(element: HTMLElement, target: PreviewTarget): () => void;
+        /**
+         * Tell the kit's code blocks whether the shell wraps its code panes'
+         * long lines, as `wrap` in their content; false until a shell says. A
+         * shell with a wrap choice calls it as the choice changes.
+         */
+        wrapCode(wrap: boolean): void;
+        /**
+         * Load the selection's pane for `target` again: its readiness goes back
+         * to loading until it answers, and it shows the selection as it is now.
+         */
+        reload(target: PreviewFrameTarget): void;
+        /**
+         * The address of the selection's pane for a target opened on its own,
+         * outside the preview: the story it shows now - the scratch story while
+         * the editor's content renders - with its props and the option values.
+         * It follows nothing after it opens.
+         */
+        standaloneUrl(target: PreviewScriptedTarget): string;
+    };
+    /** Unmount every pane, drop a pending regeneration and stop listening. */
+    dispose(): void;
+}
+/**
+ * Create a preview controller.
+ *
+ * @param controllerOptions - The catalog, the options and the environment.
+ * @returns The controller.
+ * @example
+ * ```ts
+ * const controller = createPreviewController({
+ *   catalog: catalogFromManifest(manifest, views),
+ *   options: previewOptions,
+ *   regeneration: createFetchRegenerationTransport(),
+ * });
+ * const stop = controller.subscribe((state) => render(state));
+ * controller.actions.selectComponent('components-button');
+ * ```
+ */
+export declare function createPreviewController(controllerOptions: PreviewControllerOptions): PreviewController;