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

package/dist/testing.d.ts

@@ -0,0 +1,218 @@
+import type { ManifestComponent } from './emit/manifest.js';
+import type { OptionValue } from './options.js';
+import { PREVIEW_MOUNT_ELEMENT_ID, PREVIEW_RENDER_ERROR_FLAG, type PreviewScriptedTarget } from './protocol.js';
+/** The id of the element a preview page mounts its story or view in. */
+export { PREVIEW_MOUNT_ELEMENT_ID };
+/** A component as the preview manifest lists it: the parts a browser test
+ *  reads. */
+export type PreviewManifestComponent = Pick<ManifestComponent, 'id' | 'name'> & Partial<Pick<ManifestComponent, 'defaultProps' | 'previewDefaults' | 'standalone' | 'targets' | 'bindings'>> & {
+    /** The story's scenarios, each with the props it sets over the defaults
+     *  and, for one with slot content of its own, that content and the id
+     *  its story mounts by. */
+    scenarios?: (Pick<ManifestComponent['scenarios'][number], 'id'> & Partial<Pick<ManifestComponent['scenarios'][number], 'label' | 'props' | 'content' | 'story'>>)[];
+};
+/**
+ * Read the components of a kit's preview manifest,
+ * `.preview-generated/manifest.json`, which the preview writes when it
+ * starts.
+ *
+ * @param kitRoot - The kit's root directory.
+ * @returns The components the manifest lists.
+ * @example
+ * ```ts
+ * for (const component of readPreviewManifest('.')) {
+ *   test(component.id, async ({ page }) => {});
+ * }
+ * ```
+ */
+export declare function readPreviewManifest(kitRoot: string): PreviewManifestComponent[];
+/** The window property a story page sets to what its story threw; see
+ *  {@link readRenderError}. */
+export { PREVIEW_RENDER_ERROR_FLAG };
+/** A target whose preview page the helpers load: `react`, `vue` or `svelte`. */
+export type { PreviewScriptedTarget };
+/** Preview option values keyed by option id, such as `{ mode: 'dark' }`. */
+export type PreviewOptionValues = Record<string, OptionValue>;
+/**
+ * The part of a browser page the helpers use. A Playwright `Page` satisfies
+ * it, as does any object with these three methods.
+ */
+export interface PreviewPage {
+    /** Navigate to `url`, resolving once the page has loaded. */
+    goto(url: string, options?: {
+        waitUntil?: 'load';
+    }): Promise<unknown>;
+    /** Resolve once `pageFunction`, run in the page with `argument`, returns a truthy value. */
+    waitForFunction<Argument>(pageFunction: (argument: Argument) => unknown, argument: Argument): Promise<unknown>;
+    /** Run `pageFunction` in the page with `argument` and resolve with its result. */
+    evaluate<Result, Argument>(pageFunction: (argument: Argument) => Result | Promise<Result>, argument: Argument): Promise<Result>;
+}
+/** Where the preview is served. */
+export interface PreviewLocationOptions {
+    /** Prefixed to the preview page's path, such as `http://localhost:6100`.
+     *  Omit it to navigate by path alone (resolved against the test runner's
+     *  base URL, such as Playwright's `use.baseURL`). */
+    baseUrl?: string;
+}
+/**
+ * Load a target's preview page and wait until it listens for messages. The
+ * page shows nothing until a story is set.
+ *
+ * @param page - The browser page.
+ * @param target - The target whose preview page to load.
+ * @param options - Where the preview is served.
+ * @throws When the target has no story page, the message naming those that
+ *   do, or when the page never starts listening, such as after an import
+ *   fails to load.
+ * @example
+ * ```ts
+ * test.beforeEach(async ({ page }) => {
+ *   await gotoPreview(page, 'vue');
+ * });
+ * ```
+ */
+export declare function gotoPreview(page: PreviewPage, target: PreviewScriptedTarget, options?: PreviewLocationOptions): Promise<void>;
+/**
+ * The ids of the stories a preview page can mount.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @returns The story ids.
+ * @throws When the page is not a preview page that mounts stories.
+ */
+export declare function readStoryIds(page: PreviewPage): Promise<string[]>;
+/**
+ * What the story mounted on a preview page threw as it rendered, as the pane
+ * reports it: only a throw that reaches the pane counts, so a story with its
+ * own error boundary, or the word "error" in its content, reads as rendering.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @returns The error's message, which may be empty, or `undefined` when the
+ *   story renders.
+ * @example
+ * ```ts
+ * await mountStory(page, 'components-button');
+ * await settle(page);
+ * expect(await readRenderError(page)).toBeUndefined();
+ * ```
+ */
+export declare function readRenderError(page: PreviewPage): Promise<string | undefined>;
+/**
+ * Mount a story by id with the given root props, replacing what the page
+ * shows. Setting the story already shown with other props keeps its component
+ * instance on some targets; use {@link mountStory} for a guaranteed fresh
+ * mount.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param id - The story's id.
+ * @param props - The story's root props.
+ * @throws When the page has no story with the id; the message lists those it
+ *   has.
+ */
+export declare function setStory(page: PreviewPage, id: string, props?: Record<string, unknown>): Promise<void>;
+/**
+ * Mount a story from nothing: blur the focused element, unmount the current
+ * story and wait for the mount point to empty, then set the story. The new
+ * story inherits neither focus nor component state from the one before, which
+ * a sweep over a component's states needs (a state read at mount, such as an
+ * initially open panel, only applies to a fresh instance).
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param id - The story's id.
+ * @param props - The story's root props.
+ * @throws When the page has no story with the id, the message listing those
+ *   it has, or when the mount is not empty within 15 seconds of the unmount.
+ */
+export declare function mountStory(page: PreviewPage, id: string, props?: Record<string, unknown>): Promise<void>;
+/**
+ * Wait until a story set with {@link mountStory} has finished mounting,
+ * whatever it rendered: a story can legitimately render nothing, which an
+ * element to wait for would never show, and a story that throws counts as
+ * mounted. It follows `mountStory`, which clears the page's last report;
+ * after {@link setStory} that report can be the same story's from before.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param id - The story's id.
+ * @throws When the story does not finish mounting within 15 seconds.
+ * @example
+ * ```ts
+ * await mountStory(page, 'components-banner', { visible: false });
+ * await waitForStory(page, 'components-banner');
+ * await expect(page.locator('#app > *')).toHaveCount(0);
+ * ```
+ */
+export declare function waitForStory(page: PreviewPage, id: string): Promise<void>;
+/**
+ * Replace the mounted story's root props, keeping its component instance (and
+ * any state machine driving it) alive.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param props - The story's new root props.
+ */
+export declare function setProps(page: PreviewPage, props: Record<string, unknown>): Promise<void>;
+/**
+ * Apply preview option values (a color mode, a surface, a frame around the
+ * story) to the page, as the preview's controls do.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param options - Option values keyed by option id.
+ * @throws When an id is not one of the kit's options, or a value is not one
+ *   the option takes, either of which the page would ignore; the message lists
+ *   what it defines.
+ */
+export declare function setOptions(page: PreviewPage, options: PreviewOptionValues): Promise<void>;
+/**
+ * Wait until the frame after the next paint. A component can show its final
+ * markup before the effects that attach its event handling have run; call this
+ * after asserting a change has rendered and before sending input, such as a
+ * key press, that would otherwise be dropped.
+ *
+ * @param page - The browser page.
+ */
+export declare function settle(page: PreviewPage): Promise<void>;
+/** What {@link openStory} loads and mounts. */
+export interface OpenStoryOptions extends PreviewLocationOptions {
+    /** The target whose preview page to load. */
+    target: PreviewScriptedTarget;
+    /** The story's id, as the catalog and the address name it, such as
+     *  `components-button` (`PreviewComponent.id`). */
+    id: string;
+    /** The story's root props. */
+    props?: Record<string, unknown>;
+    /** Preview option values applied before the story mounts. */
+    options?: PreviewOptionValues;
+}
+/** A story open in a page, with the page's controls bound to it. */
+export interface PreviewStory<Page extends PreviewPage = PreviewPage> {
+    /** The page showing the story; the preview page is loaded at the top level,
+     *  so locators and keyboard input go straight to it. */
+    page: Page;
+    /** The target the story renders in. */
+    target: PreviewScriptedTarget;
+    /** Replace the story's root props, keeping its component instance. */
+    setProps(props: Record<string, unknown>): Promise<void>;
+    /** Apply preview option values. */
+    setOptions(options: PreviewOptionValues): Promise<void>;
+    /** Show another story (see {@link setStory}). */
+    setStory(id: string, props?: Record<string, unknown>): Promise<void>;
+    /** Show another story from a fresh mount (see {@link mountStory}). */
+    mountStory(id: string, props?: Record<string, unknown>): Promise<void>;
+    /** Wait until the frame after the next paint (see {@link settle}). */
+    settle(): Promise<void>;
+}
+/**
+ * Load a target's preview page and mount one story in it.
+ *
+ * @param page - The browser page.
+ * @param options - The target, the story and its props, and option values.
+ * @returns The open story.
+ * @throws When the page has no story with the id, or an option id is not one
+ *   of the kit's; the message lists those it has.
+ * @example
+ * ```ts
+ * const story = await openStory(page, { target: 'vue', id: 'components-button', props: { variant: 'solid' } });
+ * await story.setProps({ variant: 'ghost' });
+ * await story.setOptions({ mode: 'dark' });
+ * await expect(story.page.getByRole('button')).toHaveClass(/ghost/);
+ * ```
+ */
+export declare function openStory<Page extends PreviewPage>(page: Page, options: OpenStoryOptions): Promise<PreviewStory<Page>>;

package/dist/testing.js

@@ -0,0 +1,284 @@
+// Browser-test helpers for a kit's components: load one target's preview page
+// on its own and drive it over the messages the preview host sends it. The page
+// object is typed structurally, so a Playwright `Page` fits without the preview
+// depending on Playwright. The functions handed to `evaluate` and
+// `waitForFunction` run in the browser, so they read only their argument and
+// browser globals, never this module's bindings.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { componentFrameUrl, globalsMessage, PREVIEW_MOUNT_ELEMENT_ID, PREVIEW_MOUNTED_STORY_FLAG, PREVIEW_OPTIONS_FLAG, PREVIEW_READY_FLAG, PREVIEW_RENDER_ERROR_FLAG, PREVIEW_SCRIPTED_TARGETS, PREVIEW_STORIES_FLAG, propsMessage, setStoryMessage, } from './protocol.js';
+/** The id of the element a preview page mounts its story or view in. */
+export { PREVIEW_MOUNT_ELEMENT_ID };
+/**
+ * Read the components of a kit's preview manifest,
+ * `.preview-generated/manifest.json`, which the preview writes when it
+ * starts.
+ *
+ * @param kitRoot - The kit's root directory.
+ * @returns The components the manifest lists.
+ * @example
+ * ```ts
+ * for (const component of readPreviewManifest('.')) {
+ *   test(component.id, async ({ page }) => {});
+ * }
+ * ```
+ */
+export function readPreviewManifest(kitRoot) {
+    const manifest = JSON.parse(readFileSync(join(kitRoot, '.preview-generated', 'manifest.json'), 'utf8'));
+    return manifest.components;
+}
+/** The window property a story page sets to what its story threw; see
+ *  {@link readRenderError}. */
+export { PREVIEW_RENDER_ERROR_FLAG };
+/** How long a loaded preview page has to start listening. The page's load
+ *  has already waited for its modules, so only a page that failed to run
+ *  them comes near this. */
+const READY_TIMEOUT_MILLISECONDS = 15_000;
+/** How long a story set on a loaded page has to finish mounting. Mounting
+ *  needs no network, so only a page that has stopped comes near this. */
+const STORY_TIMEOUT_MILLISECONDS = 15_000;
+/** Wait for `wait`, or throw `message` past the deadline. A wait left past
+ *  the deadline rejects when the page closes, which is ignored. */
+async function withinDeadline(wait, milliseconds, message) {
+    wait.catch(() => { });
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), milliseconds);
+    });
+    try {
+        await Promise.race([wait, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Load a target's preview page and wait until it listens for messages. The
+ * page shows nothing until a story is set.
+ *
+ * @param page - The browser page.
+ * @param target - The target whose preview page to load.
+ * @param options - Where the preview is served.
+ * @throws When the target has no story page, the message naming those that
+ *   do, or when the page never starts listening, such as after an import
+ *   fails to load.
+ * @example
+ * ```ts
+ * test.beforeEach(async ({ page }) => {
+ *   await gotoPreview(page, 'vue');
+ * });
+ * ```
+ */
+export async function gotoPreview(page, target, options = {}) {
+    if (!PREVIEW_SCRIPTED_TARGETS.includes(target)) {
+        throw new Error(`'${target}' has no story page; the story pages are ${PREVIEW_SCRIPTED_TARGETS.join(', ')}`);
+    }
+    const baseUrl = (options.baseUrl ?? '').replace(/\/+$/, '');
+    const url = `${baseUrl}${componentFrameUrl(target)}`;
+    await page.goto(url, { waitUntil: 'load' });
+    await withinDeadline(page.waitForFunction((flag) => window[flag] === true, PREVIEW_READY_FLAG), READY_TIMEOUT_MILLISECONDS, `gotoPreview: the preview page at ${url} never announced itself: look for a page error (an import that fails to load) in the browser console or the web server log.`);
+}
+/** Post a preview message to the page's own window, where the preview listens. */
+async function post(page, message) {
+    await page.evaluate((posted) => window.postMessage(posted, '*'), message);
+}
+/**
+ * What a preview page lists under a window property. A message posted to a
+ * page that lists nothing would reach nothing, so that throws, saying whether
+ * the page is a preview page at all.
+ */
+async function listedEntries(page, flag, helper) {
+    const read = (name) => window[name];
+    const ids = await page.evaluate(read, flag);
+    if (!Array.isArray(ids)) {
+        throw new Error((await page.evaluate(read, PREVIEW_READY_FLAG)) === true
+            ? `${helper}: this is a preview page that mounts no story (its html or view page, or a preview older than these helpers).`
+            : `${helper} needs a loaded preview page, and this page is not one: load it with gotoPreview first.`);
+    }
+    return ids;
+}
+/**
+ * The ids of the stories a preview page can mount.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @returns The story ids.
+ * @throws When the page is not a preview page that mounts stories.
+ */
+export function readStoryIds(page) {
+    return listedEntries(page, PREVIEW_STORIES_FLAG, 'readStoryIds');
+}
+/**
+ * What the story mounted on a preview page threw as it rendered, as the pane
+ * reports it: only a throw that reaches the pane counts, so a story with its
+ * own error boundary, or the word "error" in its content, reads as rendering.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @returns The error's message, which may be empty, or `undefined` when the
+ *   story renders.
+ * @example
+ * ```ts
+ * await mountStory(page, 'components-button');
+ * await settle(page);
+ * expect(await readRenderError(page)).toBeUndefined();
+ * ```
+ */
+export async function readRenderError(page) {
+    const message = await page.evaluate((flag) => window[flag], PREVIEW_RENDER_ERROR_FLAG);
+    return typeof message === 'string' ? message : undefined;
+}
+/** Throw unless the page can mount the story: a page shows nothing for an id
+ *  it does not know, and every check on the empty mount would pass. */
+async function requireStory(page, id, helper) {
+    const known = await listedEntries(page, PREVIEW_STORIES_FLAG, helper);
+    if (!known.includes(id)) {
+        throw new Error(`${helper}: this preview has no story with the id '${id}'. Its stories: ${known.join(', ') || 'none'}.`);
+    }
+}
+/**
+ * Mount a story by id with the given root props, replacing what the page
+ * shows. Setting the story already shown with other props keeps its component
+ * instance on some targets; use {@link mountStory} for a guaranteed fresh
+ * mount.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param id - The story's id.
+ * @param props - The story's root props.
+ * @throws When the page has no story with the id; the message lists those it
+ *   has.
+ */
+export async function setStory(page, id, props = {}) {
+    await requireStory(page, id, 'setStory');
+    await post(page, setStoryMessage(id, props));
+}
+/**
+ * Mount a story from nothing: blur the focused element, unmount the current
+ * story and wait for the mount point to empty, then set the story. The new
+ * story inherits neither focus nor component state from the one before, which
+ * a sweep over a component's states needs (a state read at mount, such as an
+ * initially open panel, only applies to a fresh instance).
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param id - The story's id.
+ * @param props - The story's root props.
+ * @throws When the page has no story with the id, the message listing those
+ *   it has, or when the mount is not empty within 15 seconds of the unmount.
+ */
+export async function mountStory(page, id, props = {}) {
+    await requireStory(page, id, 'mountStory');
+    await page.evaluate(() => document.activeElement?.blur?.(), undefined);
+    // No story is registered under the empty id, so every target unmounts.
+    await post(page, setStoryMessage('', {}));
+    await withinDeadline(page.waitForFunction((mountId) => document.getElementById(mountId)?.childElementCount === 0, PREVIEW_MOUNT_ELEMENT_ID), STORY_TIMEOUT_MILLISECONDS, `mountStory: the page never cleared the mount ahead of the story '${id}': the story before it may have thrown as it unmounted; look for a page error in the browser console.`);
+    // The page's last report is cleared here, not awaited from the page: the
+    // pane reports its own unmount, but after its paint in React, which a mount
+    // already empty may be read before, and a story set twice in a row would
+    // then pass {@link waitForStory} on its first mount's report.
+    await page.evaluate((flag) => {
+        window[flag] = '';
+    }, PREVIEW_MOUNTED_STORY_FLAG);
+    await post(page, setStoryMessage(id, props));
+}
+/**
+ * Wait until a story set with {@link mountStory} has finished mounting,
+ * whatever it rendered: a story can legitimately render nothing, which an
+ * element to wait for would never show, and a story that throws counts as
+ * mounted. It follows `mountStory`, which clears the page's last report;
+ * after {@link setStory} that report can be the same story's from before.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param id - The story's id.
+ * @throws When the story does not finish mounting within 15 seconds.
+ * @example
+ * ```ts
+ * await mountStory(page, 'components-banner', { visible: false });
+ * await waitForStory(page, 'components-banner');
+ * await expect(page.locator('#app > *')).toHaveCount(0);
+ * ```
+ */
+export async function waitForStory(page, id) {
+    await withinDeadline(page.waitForFunction((argument) => window[argument.flag] ===
+        argument.id, { id, flag: PREVIEW_MOUNTED_STORY_FLAG }), STORY_TIMEOUT_MILLISECONDS, `waitForStory: the story '${id}' never finished mounting: look for a page error in the browser console, or a page that has stopped responding.`);
+}
+/**
+ * Replace the mounted story's root props, keeping its component instance (and
+ * any state machine driving it) alive.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param props - The story's new root props.
+ */
+export async function setProps(page, props) {
+    await post(page, propsMessage(props));
+}
+/**
+ * Apply preview option values (a color mode, a surface, a frame around the
+ * story) to the page, as the preview's controls do.
+ *
+ * @param page - A page {@link gotoPreview} loaded.
+ * @param options - Option values keyed by option id.
+ * @throws When an id is not one of the kit's options, or a value is not one
+ *   the option takes, either of which the page would ignore; the message lists
+ *   what it defines.
+ */
+export async function setOptions(page, options) {
+    const listed = await listedEntries(page, PREVIEW_OPTIONS_FLAG, 'setOptions');
+    const known = listed.map((option) => option.id);
+    const unknown = Object.keys(options).filter((id) => !known.includes(id));
+    if (unknown.length > 0) {
+        throw new Error(`setOptions: this preview defines no option ${unknown.map((id) => `'${id}'`).join(', ')}. Its options: ${known.join(', ') || 'none'}.`);
+    }
+    for (const [id, value] of Object.entries(options)) {
+        const { values } = listed.find((option) => option.id === id);
+        if (values ? !values.includes(value) : typeof value !== 'boolean') {
+            throw new Error(values
+                ? `setOptions: option '${id}' has no value ${JSON.stringify(value)}. Its values: ${values.join(', ')}.`
+                : `setOptions: option '${id}' takes true or false, not ${JSON.stringify(value)}.`);
+        }
+    }
+    await post(page, globalsMessage(options));
+}
+/**
+ * Wait until the frame after the next paint. A component can show its final
+ * markup before the effects that attach its event handling have run; call this
+ * after asserting a change has rendered and before sending input, such as a
+ * key press, that would otherwise be dropped.
+ *
+ * @param page - The browser page.
+ */
+export async function settle(page) {
+    await page.evaluate(() => new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    }), undefined);
+}
+/**
+ * Load a target's preview page and mount one story in it.
+ *
+ * @param page - The browser page.
+ * @param options - The target, the story and its props, and option values.
+ * @returns The open story.
+ * @throws When the page has no story with the id, or an option id is not one
+ *   of the kit's; the message lists those it has.
+ * @example
+ * ```ts
+ * const story = await openStory(page, { target: 'vue', id: 'components-button', props: { variant: 'solid' } });
+ * await story.setProps({ variant: 'ghost' });
+ * await story.setOptions({ mode: 'dark' });
+ * await expect(story.page.getByRole('button')).toHaveClass(/ghost/);
+ * ```
+ */
+export async function openStory(page, options) {
+    const { target, id, props = {}, options: optionValues, baseUrl } = options;
+    await gotoPreview(page, target, { baseUrl });
+    if (optionValues)
+        await setOptions(page, optionValues);
+    await requireStory(page, id, 'openStory');
+    await post(page, setStoryMessage(id, props));
+    return {
+        page,
+        target,
+        setProps: (next) => setProps(page, next),
+        setOptions: (next) => setOptions(page, next),
+        setStory: (nextId, nextProps) => setStory(page, nextId, nextProps),
+        mountStory: (nextId, nextProps) => mountStory(page, nextId, nextProps),
+        settle: () => settle(page),
+    };
+}

package/dist/views.d.ts

@@ -0,0 +1,152 @@
+import type { OptionValue } from './options.js';
+export { reactView, type ReactViewRender } from './react-view.js';
+/** One entry of the component index a view receives: a browseable story the
+ *  view can cross-reference or select. */
+export interface ViewContextComponent {
+    /** The component's selection id - pass to `selectComponent` to open its story. */
+    id: string;
+    /** The full title (source label prefix included). */
+    title: string;
+    /** The preview source (navigation section) the component belongs to. */
+    source: string;
+}
+/** A source as a view sees it - the kit's own source plus any other package whose components it shows. */
+export interface ViewContextSource {
+    id: string;
+    label: string;
+    order: number;
+}
+/** What the preview passes a view. `options` is live (a new context arrives
+ *  on every change, see `ViewContextUpdates`); the catalog fields are a
+ *  read-only snapshot of the kit's catalog, so a view can cross-link into a
+ *  component story. A view reads
+ *  what it needs (a foundations view reads `options.theme` to pick its palette;
+ *  a gallery resolves a component from `components` and deep-links via
+ *  `selectComponent`). */
+export interface ViewContext {
+    options: Record<string, OptionValue>;
+    /** The kit being previewed. Empty until the host handshake delivers the catalog. */
+    kitName: string;
+    /** The sources, ordered. Empty until the handshake delivers the catalog. */
+    sources: ViewContextSource[];
+    /** The browseable component stories (components that are not standalone and unlisted
+     *  stories excluded; an unlisted story's id still selects it). Empty until
+     *  the handshake delivers the catalog. */
+    components: ViewContextComponent[];
+    /**
+     * Ask the preview to select a component story, as choosing it in the
+     * preview's navigation does. With `props`, the story opens with those root props merged
+     * over the component's defaults (a gallery opens the clicked entry's variant);
+     * without, it opens on its baseline scenario. Unknown ids are ignored.
+     */
+    selectComponent: (id: string, props?: Record<string, unknown>) => void;
+}
+/** Fields common to every navigation entry a kit registers. */
+interface PreviewEntryBase {
+    /** Reserved selection id - also the view iframe's `?view=` parameter. */
+    id: string;
+    /** The entry's name in the navigation. */
+    label: string;
+    /** The source whose entries list this one (a source id from
+     *  `preview.sources`); defaults to the kit's own (first) source. */
+    source?: string;
+    /** Position among the source's entries - lower first. Views and the
+     *  auto-generated component tree interleave by this. */
+    order?: number;
+}
+/** The framework a view mounts with. The view iframe loads the kit's setup
+ *  module for that framework (`preview.setupModules`) before it
+ *  mounts the view; `'dom'` loads none. */
+export type ViewFramework = 'react' | 'vue' | 'svelte' | 'dom';
+/** How a mounted view hears of a changed context: the options as the
+ *  preview applies them, and the catalog once the handshake delivers it. */
+export interface ViewContextUpdates {
+    /**
+     * Call `listener` with each new context.
+     *
+     * @returns A function that stops the calls.
+     */
+    subscribe(listener: (context: ViewContext) => void): () => void;
+}
+/**
+ * Mount a view into `element` with the context as it stands. The view stays
+ * mounted for the life of the view iframe and follows later changes through
+ * `updates`; a view that ignores them shows the context it mounted with.
+ *
+ * @param element - The element the view renders into.
+ * @param context - The context as it stands when the view mounts.
+ * @param updates - Delivers each new context.
+ * @returns A function that unmounts the view, or nothing.
+ */
+export type ViewMount = (element: HTMLElement, context: ViewContext, updates: ViewContextUpdates) => (() => void) | void;
+/** A consumer-authored panel: the preview lists it beside the component stories
+ *  and mounts it in the generic view iframe (`?view=<id>`) under the live
+ *  options. */
+export interface RenderedView extends PreviewEntryBase {
+    /** Discriminant - omit (or `false`) for a rendered view. */
+    componentTree?: false;
+    /** The framework `mount` renders with. Default `'dom'`. */
+    framework?: ViewFramework;
+    /** Mount the view inside the view iframe. */
+    mount: ViewMount;
+}
+/** The "magic" entry standing in for the source's auto-generated component tree (its
+ *  stories) at a chosen position. It mounts no iframe, so it carries no `mount`. */
+export interface ComponentTreeEntry extends PreviewEntryBase {
+    componentTree: true;
+    mount?: never;
+}
+/** A navigation entry a kit's `viewsModule` registers: either a rendered view or the
+ *  component-tree marker. The two interleave by `order`. */
+export type PreviewView = RenderedView | ComponentTreeEntry;
+/** What the kit's `viewsModule` must export. */
+export interface PreviewViewsModule {
+    views: PreviewView[];
+    viewById: (id: string) => PreviewView | undefined;
+}
+/** The language of a code block's source, as a highlighter names it: a
+ *  scripted target's file (`tsx`, `vue`, `svelte`) or the html target's
+ *  markup. */
+export type CodeBlockLanguage = 'tsx' | 'vue' | 'svelte' | 'html';
+/** What a code block shows: one target's source of the story, or, while it
+ *  has none, nothing (it is being printed) or why there is none. */
+export interface CodeBlockContent {
+    /** The target the source is for: a scripted target, or `html`. */
+    target: 'react' | 'vue' | 'svelte' | 'html';
+    language: CodeBlockLanguage;
+    /** The source, as a consumer writes it. */
+    source?: string;
+    /** Why the target has no source, when it has none to be had. */
+    reason?: string;
+    /** Whether the shell wraps its code panes' long lines: the block wraps
+     *  them when true and scrolls sideways when false. A shell with no such
+     *  choice sends false. */
+    wrap: boolean;
+}
+/** How a mounted code block hears of a new source: each time the story, its
+ *  props or its content change, or the shell's wrapping does. */
+export interface CodeBlockUpdates {
+    /**
+     * Call `listener` with each new content.
+     *
+     * @returns A function that stops the calls.
+     */
+    subscribe(listener: (content: CodeBlockContent) => void): () => void;
+}
+/**
+ * Mount a kit's code block into `element`, showing `content`, the default
+ * export of the module the kit names as its `codeBlock`. The block stays
+ * mounted for the life of its iframe, one per code pane, and follows later
+ * sources through `updates`. It wraps long lines while `content.wrap` is
+ * true and scrolls sideways while it is false, as the shell's own panes do.
+ * The iframe's page is the block's alone: its root carries
+ * `data-preview-frame="code"`, so the kit's stylesheet may style the frame's
+ * `html` and `body` by it, say in the block's background so an overscroll
+ * shows no other color.
+ *
+ * @param element - The element the block renders into.
+ * @param content - The source as it stands when the block mounts.
+ * @param updates - Delivers each new source.
+ * @returns A function that unmounts the block, or nothing.
+ */
+export type CodeBlockMount = (element: HTMLElement, content: CodeBlockContent, updates: CodeBlockUpdates) => (() => void) | void;

package/dist/views.js

@@ -0,0 +1,7 @@
+// The custom-view contract: what a kit's `viewsModule` exports. A view is a
+// consumer-authored panel the preview lists beside the component stories and
+// mounts in the dedicated view iframe (`?view=<id>`) under the live options
+// context - tokens pages, galleries, composed demos. A view mounts itself into
+// an element in any of the preview's frameworks, or in plain DOM; `reactView`
+// adapts a React render function. Browser-safe.
+export { reactView } from './react-view.js';