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

package/dist/declarations/src/protocol.d.ts

@@ -0,0 +1,541 @@
+import type { OptionValue, PreviewOption } from './options.js';
+import type { CodeBlockContent, ViewContextComponent, ViewContextSource, ViewFramework } from './views.js';
+/**
+ * What a story pane renders in: a scripted target, which a component preview
+ * iframe runs the story's script in, or `html`, the markup the story renders
+ * to with no JavaScript of its own.
+ */
+export declare const PREVIEW_TARGETS: readonly ["react", "vue", "svelte", "html"];
+/** What a story pane renders in: one of {@link PREVIEW_TARGETS}. */
+export type PreviewTarget = (typeof PREVIEW_TARGETS)[number];
+/** A target a component preview iframe runs a story's script in: every
+ *  target but `html`. */
+export type PreviewScriptedTarget = Exclude<PreviewTarget, 'html'>;
+/** The scripted targets, in the preview's order: {@link PREVIEW_TARGETS}
+ *  without `html`. */
+export declare const PREVIEW_SCRIPTED_TARGETS: readonly ["react", "vue", "svelte"];
+/** The `type` of each message, keyed by a short name. */
+export declare const PREVIEW_MESSAGE: {
+    /** Iframe → host: the iframe listens for messages now (sent on each load). */
+    readonly ready: "preview:ready";
+    /** Host → iframe: mount a story by id with its root props. */
+    readonly setStory: "preview:set-story";
+    /** Host → iframe: replace the mounted story's props in place. */
+    readonly props: "preview:props";
+    /** Host → iframe: the merged option values to apply to the document. */
+    readonly globals: "preview:globals";
+    /** Host → view iframe: the catalog a custom view builds its context from. */
+    readonly catalog: "preview:catalog";
+    /** View iframe → host: open a component story, as a navigation click does. */
+    readonly select: "preview:select";
+    /** Iframe → host: the size of what the iframe shows, sent once it renders
+     *  and again on each change. */
+    readonly contentSize: "preview:content-size";
+    /** Host → html iframe: the markup to show, or why there is none. */
+    readonly markup: "preview:markup";
+    /** Iframe → host: the story threw as it rendered, or, with no message,
+     *  the story it mounts since renders. */
+    readonly renderError: "preview:render-error";
+    /** Host → code iframe: the source the kit's code block shows. */
+    readonly code: "preview:code";
+    /** Iframe → host: the story called one of its events. */
+    readonly event: "preview:event";
+    /** Iframe → host: its first content has mounted and painted, so the host
+     *  can show the iframe. Sent once per document. */
+    readonly shown: "preview:shown";
+};
+/** The `type` of a preview message. */
+export type PreviewMessageType = (typeof PREVIEW_MESSAGE)[keyof typeof PREVIEW_MESSAGE];
+/** Sent by an iframe once its message listener is attached. */
+export interface PreviewReadyMessage {
+    type: typeof PREVIEW_MESSAGE.ready;
+}
+/** Sent by an iframe once its first content has mounted and painted. */
+export interface PreviewShownMessage {
+    type: typeof PREVIEW_MESSAGE.shown;
+}
+/** Mounts the story `id` afresh with `props` as its root props. */
+export interface PreviewSetStoryMessage {
+    type: typeof PREVIEW_MESSAGE.setStory;
+    id: string;
+    props: Record<string, unknown>;
+    /** The story's events: the function props a pane records the calls of,
+     *  reporting each as a `preview:event`. */
+    events?: string[];
+    /** The story's two-way props and the event each reports its new value
+     *  through. A pane may take a value a story's given prop reports as that
+     *  prop at once, as the host does after it (see {@link withWriteBacks}). */
+    bindings?: PreviewWriteBack[];
+    /** Which of the host's story mounts this is: a pane tags each event it
+     *  records with it, so the host can tell an event of a story it has since
+     *  replaced (see {@link withEventRecorders}). */
+    mount?: number;
+}
+/** A two-way prop and the event prop it reports each new value through. */
+export interface PreviewWriteBack {
+    /** The two-way prop. */
+    prop: string;
+    /** The event prop called with each new value. */
+    changeProp: string;
+}
+/** Replaces the mounted story's root props, keeping its component instance. */
+export interface PreviewPropsMessage {
+    type: typeof PREVIEW_MESSAGE.props;
+    props: Record<string, unknown>;
+    /** The newest of the receiving pane's own write-backs the host had taken
+     *  when it sent the props (the `write` of the pane's events, see
+     *  {@link PendingWriteBacks}): a pane keeps a later write of its own over
+     *  the value these props hold. Absent, the pane takes the props as they
+     *  are. */
+    answers?: number;
+}
+/** The option values (global and story-scoped, merged) the iframe applies. */
+export interface PreviewGlobalsMessage {
+    type: typeof PREVIEW_MESSAGE.globals;
+    options: Record<string, OptionValue>;
+}
+/** The catalog a custom view reads: the kit's name, its sources and its stories. */
+export interface PreviewCatalogPayload {
+    kitName: string;
+    sources: ViewContextSource[];
+    components: ViewContextComponent[];
+}
+/** Delivers the {@link PreviewCatalogPayload} to the view iframe. */
+export interface PreviewCatalogMessage extends PreviewCatalogPayload {
+    type: typeof PREVIEW_MESSAGE.catalog;
+}
+/** Asks the host to open a component story, optionally with root props. */
+export interface PreviewSelectMessage {
+    type: typeof PREVIEW_MESSAGE.select;
+    id: string;
+    props?: Record<string, unknown>;
+}
+/** The size of what a preview iframe shows, in whole CSS pixels. */
+export interface PreviewContentSize {
+    width: number;
+    height: number;
+}
+/**
+ * Reports the size of what an iframe shows: its story or view, with the
+ * padding, borders and margins of the elements around it, rounded up to
+ * whole CSS pixels, so an iframe of that size shows it all.
+ */
+export interface PreviewContentSizeMessage extends PreviewContentSize {
+    type: typeof PREVIEW_MESSAGE.contentSize;
+}
+/**
+ * The html iframe's story: its `markup`, or the `reason` it has none. With
+ * neither, the markup is being printed, and the iframe keeps what it shows.
+ */
+export interface PreviewMarkupMessage {
+    type: typeof PREVIEW_MESSAGE.markup;
+    markup?: string;
+    /** The styles of the components the markup renders, shown with it. */
+    stylesheet?: string;
+    reason?: string;
+}
+/**
+ * Reports what an iframe's story threw as it rendered (`message`), shown in
+ * the story's place; with no `message`, the story mounted since renders.
+ */
+export interface PreviewRenderErrorMessage {
+    type: typeof PREVIEW_MESSAGE.renderError;
+    message?: string;
+}
+/** The source a code iframe's block shows: a target's, in its language, or
+ *  why it has none; with neither, it is being printed. */
+export interface PreviewCodeMessage extends CodeBlockContent {
+    type: typeof PREVIEW_MESSAGE.code;
+}
+/** Reports a story's call of one of its events: its `name`, a readable
+ *  summary of what it was called with, and its first argument as `value`
+ *  when that is plain data (what JSON holds), such as the new value a
+ *  two-way prop's change callback reports. */
+export interface PreviewEventMessage {
+    type: typeof PREVIEW_MESSAGE.event;
+    name: string;
+    payload: string;
+    value?: unknown;
+    /** The `mount` of the set-story message the pane was showing. */
+    mount?: number;
+    /** The number of the newest value the pane wrote back itself since its
+     *  last report, when it wrote one (see {@link PendingWriteBacks}): the
+     *  host answers it on the pane's next props message. */
+    write?: number;
+}
+/** Any message the host and the iframes exchange. */
+export type PreviewMessage = PreviewReadyMessage | PreviewSetStoryMessage | PreviewPropsMessage | PreviewGlobalsMessage | PreviewCatalogMessage | PreviewSelectMessage | PreviewContentSizeMessage | PreviewMarkupMessage | PreviewRenderErrorMessage | PreviewCodeMessage | PreviewEventMessage | PreviewShownMessage;
+/** The message whose `type` is `Type`. */
+export type PreviewMessageOf<Type extends PreviewMessageType> = Extract<PreviewMessage, {
+    type: Type;
+}>;
+/**
+ * Read posted data as a preview message: the data itself when it is an object
+ * whose `type` is one of the preview's, otherwise `undefined`. Only the `type`
+ * is checked; a receiver validates the payload it relies on.
+ *
+ * @param data - A `MessageEvent`'s `data`.
+ * @returns The data as a {@link PreviewMessage}, or `undefined`.
+ */
+export declare function readPreviewMessage(data: unknown): PreviewMessage | undefined;
+/**
+ * Whether posted data is a preview message of one type.
+ *
+ * @param data - A `MessageEvent`'s `data`.
+ * @param type - The message type to match.
+ * @returns `true` when `data` is an object whose `type` is `type`.
+ */
+export declare function isPreviewMessage<Type extends PreviewMessageType>(data: unknown, type: Type): data is PreviewMessageOf<Type>;
+/** @returns A {@link PreviewReadyMessage}. */
+export declare function readyMessage(): PreviewReadyMessage;
+/**
+ * @param id - The story's id.
+ * @param props - Its root props.
+ * @param events - The function props a pane records the calls of.
+ * @param bindings - The two-way props and the events they report through.
+ * @param mount - Which of the host's story mounts this is.
+ * @returns A {@link PreviewSetStoryMessage}.
+ */
+export declare function setStoryMessage(id: string, props: Record<string, unknown>, events?: string[], bindings?: readonly PreviewWriteBack[], mount?: number): PreviewSetStoryMessage;
+/**
+ * The story's props with each two-way prop's change event writing the value
+ * it reports back as that prop at once, through `write`, while the story
+ * gives the prop: what the host does with the value after it hears of the
+ * call, done inside the pane, so a framework that restores a controlled
+ * input to its prop's value as the event ends (React) finds the new value
+ * there and keeps the caret where it was. The host's own write-back follows
+ * with the same value. Only plain data is written, as the host takes only
+ * plain data; a prop the story leaves out stays the component's own.
+ *
+ * @param props - The story's root props, its events' recorders in place.
+ * @param bindings - The two-way props and the events they report through.
+ * @param write - Takes a two-way prop's new value.
+ * @returns The props, each given two-way prop's change event writing back.
+ * @example
+ * ```ts
+ * withWriteBacks(props, [{ prop: 'value', changeProp: 'onValueChange' }], (prop, value) =>
+ *   setProps((current) => ({ ...current, [prop]: value }))
+ * );
+ * ```
+ */
+export declare function withWriteBacks(props: Record<string, unknown>, bindings: readonly PreviewWriteBack[] | undefined, write: (prop: string, value: unknown) => void): Record<string, unknown>;
+/**
+ * The values a pane has written back itself (see {@link withWriteBacks}) and
+ * the host has not yet answered, per two-way prop, oldest first. Each write
+ * gets a number, counting up for the life of the pane, which the next event
+ * the pane reports carries (`write`); each props message from the host
+ * names the newest write it had taken when it sent them (`answers`). Props
+ * the host sent before it took a write hold an older value for that prop,
+ * whether they answer the write's own echo or a change of another control,
+ * so `reconcile` keeps the pane's newest value over them.
+ *
+ * @example
+ * ```ts
+ * const pending = new PendingWriteBacks();
+ * pending.wrote('value', 'ab'); // 1
+ * pending.wrote('value', 'abc'); // 2
+ * pending.reconcile({ value: 'ab' }, 1); // { value: 'abc' }, still waiting for 2
+ * pending.reconcile({ value: 'abc' }, 2); // { value: 'abc' }, nothing waiting
+ * ```
+ */
+export declare class PendingWriteBacks {
+    private readonly pending;
+    private count;
+    private unreported;
+    /**
+     * Note a value the pane has written back for a prop.
+     *
+     * @param prop - The two-way prop.
+     * @param value - The value, plain data.
+     * @returns The write's number.
+     */
+    wrote(prop: string, value: unknown): number;
+    /**
+     * The number of the newest write since the last call, for the event the
+     * pane reports next to carry; `undefined` when there has been none.
+     *
+     * @returns The write's number, or `undefined`.
+     */
+    takeUnreported(): number | undefined;
+    /**
+     * The host's props as the pane takes them. The writes up to `answers` are
+     * done with: the host had them when it sent the props. A two-way prop the
+     * host gives with a later write still waiting keeps the newest value the
+     * pane wrote. Without `answers` the props are taken as they are, and
+     * every write is done with.
+     *
+     * @param props - The props the host sends.
+     * @param answers - The newest of the pane's writes the host had taken.
+     * @returns The props to take.
+     */
+    reconcile(props: Record<string, unknown>, answers?: number): Record<string, unknown>;
+    /** Forget every write, as a new story starts. The count goes on. */
+    clear(): void;
+}
+/**
+ * The story's props with a recorder for each of its events: a function that
+ * reports its call to the host as a `preview:event`, the event's name and a
+ * readable summary of what it was called with. A function the props hold
+ * already for an event is called too.
+ *
+ * @param props - The story's root props.
+ * @param events - The function props to record the calls of.
+ * @param target - The pane's window.
+ * @param mount - The `mount` of the set-story message the pane shows, which
+ *   each report carries.
+ * @param writes - The pane's own write-backs: a report carries the number of
+ *   the newest write since the last one (`write`), for the host to answer.
+ * @returns The props, an event's recorder in its place.
+ */
+export declare function withEventRecorders(props: Record<string, unknown>, events?: readonly string[], target?: Window, mount?: number, writes?: PendingWriteBacks): Record<string, unknown>;
+/**
+ * Whether a value is plain data, which survives `postMessage` and JSON as it
+ * is: `null`, a boolean, a finite number, a string, or an array or plain
+ * object of these.
+ *
+ * @param value - The value.
+ * @param depth - How deep the value sits in the one being read.
+ * @returns `true` when the value is plain data.
+ */
+export declare function isPlainData(value: unknown, depth?: number): boolean;
+/** A readable, one-line summary of what an event was called with. */
+export declare function summarizeArguments(parameters: unknown[]): string;
+/**
+ * @param props - The mounted story's new root props.
+ * @param answers - The newest of the receiving pane's write-backs the host
+ *   has taken.
+ * @returns A {@link PreviewPropsMessage}.
+ */
+export declare function propsMessage(props: Record<string, unknown>, answers?: number): PreviewPropsMessage;
+/**
+ * @param options - The option values, keyed by option id.
+ * @returns A {@link PreviewGlobalsMessage}.
+ */
+export declare function globalsMessage(options: Record<string, OptionValue>): PreviewGlobalsMessage;
+/**
+ * @param catalog - The kit's name, sources and browseable stories.
+ * @returns A {@link PreviewCatalogMessage}.
+ */
+export declare function catalogMessage(catalog: PreviewCatalogPayload): PreviewCatalogMessage;
+/**
+ * @param id - The component story to open.
+ * @param props - Root props to open it with, over the component's defaults.
+ * @returns A {@link PreviewSelectMessage}.
+ */
+export declare function selectMessage(id: string, props?: Record<string, unknown>): PreviewSelectMessage;
+/**
+ * @param content - The target's source, its language, or why it has none.
+ * @returns A {@link PreviewCodeMessage}.
+ */
+export declare function codeMessage(content: CodeBlockContent): PreviewCodeMessage;
+/**
+ * Tell the host what the iframe's story threw as it rendered, or, with no
+ * message, that the story mounted since renders.
+ *
+ * @param message - The error's message; omitted when a new story mounts.
+ * @param target - The iframe's window.
+ */
+export declare function reportRenderError(message?: string, target?: Window): void;
+/**
+ * @param size - The content's width and height in CSS pixels.
+ * @returns A {@link PreviewContentSizeMessage}.
+ */
+export declare function contentSizeMessage(size: PreviewContentSize): PreviewContentSizeMessage;
+/**
+ * @param story - The markup to show, the reason there is none, or neither
+ *   while it is being printed.
+ * @returns A {@link PreviewMarkupMessage}.
+ */
+export declare function markupMessage(story: {
+    markup: string;
+    stylesheet?: string;
+} | {
+    reason: string;
+} | Record<string, never>): PreviewMarkupMessage;
+/**
+ * Read posted data as a content size: its width and height when both are
+ * finite numbers of zero or more, otherwise `undefined`.
+ *
+ * @param message - A {@link PreviewContentSizeMessage} as it was received.
+ * @returns The size, or `undefined` for a malformed message.
+ */
+export declare function readContentSize(message: PreviewContentSizeMessage): PreviewContentSize | undefined;
+/** The window property an iframe sets to `true` once it can receive messages,
+ *  for a test that loads the iframe's page on its own (where the ready message
+ *  has no parent to reach). */
+export declare const PREVIEW_READY_FLAG = "__previewReady";
+/** The window property a story iframe sets to the ids of the stories it can
+ *  mount, for a test helper to reject an id that would mount nothing. */
+export declare const PREVIEW_STORIES_FLAG = "__previewStories";
+/** The window property a preview iframe sets to the kit's options, each with
+ *  the values a choice option offers, for a test helper to reject an id or a
+ *  value the iframe would ignore. */
+export declare const PREVIEW_OPTIONS_FLAG = "__previewOptions";
+/** The window property a story iframe sets to the message of what its story
+ *  threw as it rendered, or to `null` while the story mounted since renders,
+ *  for a test that loads the iframe's page on its own (where the report has no
+ *  parent to reach). The message is a string, and may be empty. */
+export declare const PREVIEW_RENDER_ERROR_FLAG = "__previewRenderError";
+/** The window property a story iframe sets to the id of the story it last
+ *  finished mounting, or to the empty string once a story has unmounted with
+ *  none set after it. Set after the story's first render and its effects, so
+ *  a test that loads the iframe's page on its own can tell a story that
+ *  rendered nothing from one still mounting. */
+export declare const PREVIEW_MOUNTED_STORY_FLAG = "__previewMountedStory";
+/** The id of the element each preview iframe mounts its story or view in. */
+export declare const PREVIEW_MOUNT_ELEMENT_ID = "app";
+/**
+ * Announce that an iframe shows its first content: post a
+ * {@link PreviewShownMessage} to the parent window once the content mounted
+ * now has painted, two animation frames on. Call it after the iframe mounts
+ * the first content the host sends; a later call in the same document sends
+ * nothing.
+ *
+ * @param target - The iframe's window.
+ */
+export declare function announcePreviewShown(target?: Window): void;
+/**
+ * Record under {@link PREVIEW_MOUNTED_STORY_FLAG} that the iframe has finished
+ * mounting a story. Call it once the framework has committed the mount,
+ * whatever the story rendered.
+ *
+ * @param id - The story's id, or the empty string after an unmount.
+ * @param target - The iframe's window.
+ */
+export declare function announceStoryMounted(id: string, target?: Window): void;
+/**
+ * List the stories an iframe can mount under {@link PREVIEW_STORIES_FLAG}.
+ * Call it before {@link announcePreviewReady}, so a test that waits for the
+ * iframe finds the list.
+ *
+ * @param ids - The ids of the stories.
+ * @param target - The iframe's window.
+ */
+export declare function announcePreviewStories(ids: readonly string[], target?: Window): void;
+/** An option as a preview iframe lists it: its id and, for a choice, the
+ *  values it offers; a boolean option has no `values`. */
+export interface PreviewListedOption {
+    /** The option's id. */
+    id: string;
+    /** The values of a choice option. */
+    values?: string[];
+}
+/**
+ * List the kit's options under {@link PREVIEW_OPTIONS_FLAG}.
+ *
+ * @param options - The options.
+ * @param target - The iframe's window.
+ */
+export declare function announcePreviewOptions(options: readonly Pick<PreviewOption, 'id' | 'values'>[], target?: Window): void;
+/**
+ * Announce that an iframe listens for messages: set {@link PREVIEW_READY_FLAG}
+ * and post a {@link PreviewReadyMessage} to the parent window. Call it right
+ * after attaching the message listener.
+ *
+ * @param target - The iframe's window.
+ */
+export declare function announcePreviewReady(target?: Window): void;
+/**
+ * Measure what an iframe shows: the mount element's own box, with the
+ * padding, borders and margins of the mount and every element around it up
+ * to the body, rounded up to whole CSS pixels. Nothing in it depends on the
+ * height of the iframe, so a host that sizes the iframe to it does not make
+ * it grow: a wrapper's `min-height: 100vh` adds nothing but its padding.
+ * Where the mount's own height may follow the layout around it (a minimum
+ * height of its own, or a flex or grid item), its children's extent stands
+ * in for it.
+ *
+ * @param mount - The element the story or view is mounted in.
+ * @returns The content's width and height.
+ */
+export declare function measureContentSize(mount: HTMLElement): PreviewContentSize;
+/**
+ * Report the size of what an iframe shows to the parent window as a
+ * {@link PreviewContentSizeMessage}: once now, and again whenever it
+ * changes, at most once per animation frame and only when the size differs
+ * from the last one reported. It watches the mount, its children and the
+ * elements around it for a change of size, the mount's content for a change
+ * of nodes or text, the elements around it for a change of class or style,
+ * and the window for a resize. Call it once the message listener is
+ * attached; a second call for the same mount returns the first one's stop.
+ *
+ * @param mount - The element the story or view is mounted in.
+ * @param target - The iframe's window.
+ * @returns A function that stops the reports.
+ */
+export declare function reportContentSize(mount: HTMLElement, target?: Window): () => void;
+/** The query parameter that names the view the view iframe renders. */
+export declare const VIEW_PARAMETER = "view";
+/** The query parameter that names the framework of the view the view iframe
+ *  renders, so the iframe loads that framework's setup module before the view. */
+export declare const VIEW_FRAMEWORK_PARAMETER = "framework";
+/** The query parameter that names the target whose source a code iframe
+ *  shows. */
+export declare const CODE_TARGET_PARAMETER = "target";
+/** The query parameter a component iframe's URL carries so that changing it
+ *  reloads the iframe. */
+export declare const RELOAD_PARAMETER = "r";
+/**
+ * The URL of a story pane's iframe: a target's, or the html one's.
+ *
+ * @param target - What the iframe renders in.
+ * @param reload - A counter whose change reloads the iframe; omitted, the URL
+ *   carries no reload parameter.
+ * @param baseUrl - The URL the preview is served under, ending in `/`; the
+ *   root of the origin, `/`, by default.
+ * @returns The page's URL, such as `/preview/vue/preview.html?r=0`.
+ */
+export declare function componentFrameUrl(target: PreviewTarget, reload?: number, baseUrl?: string): string;
+/** The query parameters a target's pane, opened on its own, reads its
+ *  story from: the story's id, its root props and the option values, the
+ *  latter two as JSON. */
+export declare const STANDALONE_PARAMETERS: {
+    readonly story: "story";
+    readonly props: "props";
+    readonly options: "options";
+};
+/**
+ * The URL of a target's pane opened on its own, outside the preview: it
+ * shows `story` with its props under its option values, as the preview's pane
+ * does, with no host to follow.
+ *
+ * @param target - The target to render the story in.
+ * @param story - The story's id, root props and option values.
+ * @param baseUrl - The URL the preview is served under, ending in `/`.
+ * @returns The pane's URL.
+ */
+export declare function standaloneFrameUrl(target: PreviewScriptedTarget, story: {
+    id: string;
+    props: Record<string, unknown>;
+    options: Record<string, OptionValue>;
+}, baseUrl?: string): string;
+/**
+ * The messages a pane opened on its own gives itself, from its address: the
+ * story to mount and the option values. None when the address names no story.
+ *
+ * @param search - The pane's `location.search`.
+ * @returns A set-story and a globals message, or none.
+ */
+export declare function standaloneMessages(search: string): PreviewMessage[];
+/**
+ * The URL of a code iframe: the kit's code block, showing one target's
+ * source.
+ *
+ * @param target - The target whose source the block shows.
+ * @param framework - The block's framework; a framework other than `'dom'`
+ *   is named in the URL, so the iframe loads its setup module first.
+ * @param baseUrl - The URL the preview is served under, ending in `/`.
+ * @returns The page's URL, such as `/preview/code/code.html?target=vue`.
+ */
+export declare function codeFrameUrl(target: PreviewTarget, framework?: ViewFramework, baseUrl?: string): string;
+/**
+ * The URL of the view iframe rendering one custom view.
+ *
+ * @param viewId - The view's id.
+ * @param framework - The view's framework; a framework other than `'dom'` is
+ *   named in the URL, so the iframe loads its setup module ahead of the views.
+ * @param baseUrl - The URL the preview is served under, ending in `/`; the
+ *   root of the origin, `/`, by default.
+ * @returns The page's URL, such as `/preview/view/view.html?view=tokens`.
+ */
+export declare function viewFrameUrl(viewId: string, framework?: ViewFramework, baseUrl?: string): string;

package/dist/declarations/src/react-view.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+import type { RenderedView, ViewContext } from './views.js';
+/** A React view's render function: the view's element tree for a context. */
+export type ReactViewRender = (context: ViewContext) => ReactNode;
+/**
+ * Make a view's `framework` and `mount` from a React render function. The
+ * view iframe then loads the kit's React setup module before mounting it.
+ *
+ * @param render - Renders the view for a context; called again with each new one.
+ * @returns The view's `framework` (`'react'`) and `mount`, to spread into its entry.
+ * @example
+ * ```tsx
+ * export const views: PreviewView[] = [
+ *   {
+ *     id: 'foundations',
+ *     label: 'Foundations',
+ *     ...reactView((context) => <Foundations theme={String(context.options.theme)} />),
+ *   },
+ * ];
+ * ```
+ */
+export declare function reactView(render: ReactViewRender): Required<Pick<RenderedView, 'framework' | 'mount'>>;

package/dist/declarations/src/react.d.ts

@@ -0,0 +1,17 @@
+import type { PreviewController, PreviewState } from './controller/index.js';
+/**
+ * Read a slice of the controller's state. The component re-renders 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; derive
+ * those from the slice afterwards.
+ *
+ * @param controller - The controller to read.
+ * @param selector - Picks the slice; the whole state when omitted.
+ * @returns The slice.
+ * @example
+ * ```tsx
+ * const scenario = usePreview(controller, (state) => state.scenario);
+ * const panes = usePreview(controller, (state) => state.targets.panes);
+ * ```
+ */
+export declare function usePreview<Selected = PreviewState>(controller: PreviewController, selector?: (state: PreviewState) => Selected): Selected;