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

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

@@ -0,0 +1,99 @@
+import type { PreviewCatalog, PreviewController } from './controller/index.js';
+import type { PreviewShellOption } from './options.js';
+export { childPath, DEFAULT_PANE_WIDTHS, DEFAULT_SLOT, defaultScenarioId, isContainer, MAXIMUM_PANE_WIDTH, PREVIEW_FRAME_SHOWN_ATTRIBUTE, nodeAt, nodeAddSlots, nodeSlots, previewStore, printStorySource, scenarioChoices, storyFrameKey, type AroundFill, type ContainerNode, type DropTarget, type EditorNode, type EditorState, type NodePath, type OpaqueFill, type PreviewBinding, type PreviewCatalog, type PreviewCatalogView, type PreviewComponent, type PreviewController, type PreviewEditorState, type PreviewEvent, type PreviewFrameReadiness, type PreviewFrameTarget, type PreviewTargetCode, type PreviewHtmlSource, type PreviewImport, type PreviewInsertTarget, type PreviewLanding, type PreviewNavigationNode, type PreviewNodeRequest, type PreviewOptionDescriptor, type PreviewPaneWidth, type PreviewPropType, type PreviewRegenerationStatus, type PreviewScenario, type PreviewSource, type PreviewSelection, type PreviewSortableDrop, type PreviewCode, type PreviewState, type PreviewStore, type PreviewStoryReference, type ScenarioChoice, type SortableListAddress, type Step, type StoryAround, } from './controller/index.js';
+export { CONTEXT_OPTION_GROUP, KIT_OPTION_GROUP, optionGroup, optionKind, shellOptionId, type OptionChoice, type OptionKind, type OptionValue, type PreviewShellOption, } from './options.js';
+export { PREVIEW_SCRIPTED_TARGETS, PREVIEW_TARGETS, type PreviewContentSize, type PreviewScriptedTarget, type PreviewTarget, } from './protocol.js';
+export type { ViewFramework } from './views.js';
+/** The version of the shell contract this preview serves. */
+export declare const PREVIEW_SHELL_API_VERSION = 1;
+/**
+ * What a shell module default-exports: the contract version it was written
+ * against, its own options, and how it mounts.
+ */
+export interface PreviewShell {
+    /** The shell contract version the shell was written against. The preview
+     *  refuses a shell whose version it does not serve. */
+    apiVersion: number;
+    /** The shell's own options, such as its color mode or density. The preview
+     *  keeps their values beside the kit's, under `shell.<id>`. A function is
+     *  called once with the kit's catalog before the preview starts, for options
+     *  that depend on the kit, such as a choice among its targets. */
+    options?: PreviewShellOption[] | ((catalog: PreviewCatalog) => PreviewShellOption[]);
+    /**
+     * Render the shell into `root`, reading and driving `controller`.
+     *
+     * @param root - The host page's root element, empty.
+     * @param controller - The preview's behavior.
+     * @returns A function that unmounts the shell, or nothing when there is
+     *   nothing to undo. The preview calls it before mounting a changed shell
+     *   over the same controller during development.
+     */
+    mount(root: HTMLElement, controller: PreviewController): (() => void) | void;
+}
+/**
+ * Declare a shell. The function only types its argument and returns it, so a
+ * shell module reads as one declaration.
+ *
+ * @param shell - The shell.
+ * @returns The shell, unchanged.
+ * @example
+ * ```ts
+ * export default defineShell({
+ *   apiVersion: 1,
+ *   options: [{ id: 'density', label: 'density', default: false }],
+ *   mount(root, controller) {
+ *     const stop = controller.subscribe((state) => render(root, state));
+ *     render(root, controller.getState());
+ *     return stop;
+ *   },
+ * });
+ * ```
+ */
+export declare function defineShell(shell: PreviewShell): PreviewShell;
+/** What a shell page's `head` and `root` functions are given. */
+export interface ShellPageContext {
+    /**
+     * The address of a file the page's markup references, such as a font to
+     * preload: the development server serves the file from where it is, and the
+     * static build copies it into its output.
+     *
+     * @param file - The file's absolute path.
+     * @returns The address to write into the markup, in an `href`, a `src` or
+     *   a CSS `url()`.
+     */
+    asset(file: string): string;
+}
+/** A part of the host page a shell supplies: markup, or a function that
+ *  gives it. */
+export type ShellPageMarkup = string | ((context: ShellPageContext) => string | Promise<string>);
+/**
+ * What a shell's page module default-exports: the static start of the host
+ * page, which shows before the shell's script has loaded. The module is
+ * evaluated in Node as the preview starts or builds, so it reads files and
+ * resolves packages freely and holds nothing that needs a browser.
+ */
+export interface ShellPage {
+    /** Markup for the end of the page's `<head>`: styles, a font face, links
+     *  that preload what the shell will need. It stays for the life of the
+     *  page. */
+    head?: ShellPageMarkup;
+    /** Markup for the page's root element, shown until the shell mounts: a
+     *  loading note, with the styles only it needs. The preview empties the
+     *  root before it mounts the shell. */
+    root?: ShellPageMarkup;
+}
+/**
+ * Declare a shell's page. The function only types its argument and returns
+ * it, so a page module reads as one declaration.
+ *
+ * @param page - The page.
+ * @returns The page, unchanged.
+ * @example
+ * ```ts
+ * export default defineShellPage({
+ *   head: '<style>html { background: #101010; }</style>',
+ *   root: '<p role="status">loading</p>',
+ * });
+ * ```
+ */
+export declare function defineShellPage(page: ShellPage): ShellPage;

package/dist/declarations/src/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/development-server.d.ts

@@ -0,0 +1,121 @@
+import type { ConfigurationLookupOptions } from 'scaffold-ui-kit';
+import { type Plugin, type ViteDevServer } from 'vite';
+import { type PreviewContext } from './context.js';
+import { type DevelopmentServerOverrides } from './vite-configuration.js';
+/** How long a burst of saves settles before the preview regenerates. */
+export declare const REGENERATION_DELAY_MILLISECONDS = 100;
+/**
+ * The kit's own modules generation has loaded: the templates and story files,
+ * and every module of the kit they import.
+ *
+ * @param context - The kit's preview context.
+ * @returns Their absolute paths.
+ */
+export declare function loadedKitModules(context: PreviewContext): string[];
+/**
+ * Forgets the kit's loaded modules, so the next generation imports each one
+ * afresh from disk. Installed packages stay loaded.
+ *
+ * @param context - The kit's preview context.
+ * @returns The absolute paths forgotten.
+ */
+export declare function forgetKitModules(context: PreviewContext): string[];
+/** What the last successful generation read from a kit, beyond the paths
+ *  its preview context names. */
+export interface GenerationInputs {
+    /** The kit modules it loaded (`loadedKitModules`). */
+    loadedModules?: readonly string[];
+    /** The theme stylesheets and assets it copied (`generatePreview`'s
+     *  `themeSources`). */
+    themeSources?: readonly string[];
+}
+/** What the development server watches in a kit. */
+export interface KitWatchPaths {
+    /** The files and directories whose changes regenerate the preview. */
+    regeneration: string[];
+    /** The kit configuration file, whose changes restart the server. */
+    kitConfiguration: string;
+    /** The kit's modules a `.ts` configuration imports. A change to one
+     *  restarts the server too. */
+    configurationModules: string[];
+}
+/**
+ * The paths the development server watches in a kit: each source's templates
+ * and stories directories (so an added or deleted component is noticed),
+ * its manual components module, the shared
+ * modules templates import, every other kit module generation loaded, and
+ * the themes' stylesheets and assets. The custom views module, the shell and
+ * the setup modules are left to Vite, which serves them and reloads them
+ * itself; generation reads none of them.
+ *
+ * @param context - The kit's preview context.
+ * @param inputs - What the last successful generation read.
+ * @returns The paths, absolute.
+ */
+export declare function kitWatchPaths(context: PreviewContext, inputs?: GenerationInputs): KitWatchPaths;
+/** What a change to a file means for the development server. */
+export type KitChange = 'regenerate' | 'restart';
+/**
+ * What a change to `path` asks of the development server: a restart for the
+ * kit configuration file and the kit modules it loads; a regeneration for a template (a TypeScript module
+ * directly in a templates directory), a story file, a theme's stylesheet or a
+ * file in its assets, or a module named in `kitWatchPaths`; nothing for any
+ * other file.
+ *
+ * @param path - The absolute path that changed, was added or was deleted.
+ * @param context - The kit's preview context.
+ * @param inputs - What the last successful generation read.
+ * @returns The change, or `undefined` when the file is none of the kit's inputs.
+ */
+export declare function classifyKitChange(path: string, context: PreviewContext, inputs?: GenerationInputs): KitChange | undefined;
+/** What the kit-watching plugin is told to do beyond regenerating. */
+export interface KitWatchOptions {
+    /** Called when the kit configuration file changes; settles once the
+     *  server is replaced, or kept because the new configuration did not load. */
+    onKitConfigurationChange: () => Promise<void>;
+    /** What the generation before the server started read; later ones
+     *  replace it. */
+    inputs?: GenerationInputs;
+    /** How long a burst of saves settles first. */
+    delayMilliseconds?: number;
+}
+/**
+ * A Vite plugin that watches a kit's preview inputs while the development
+ * server runs and regenerates the preview when one changes. Saves arriving
+ * within the delay of each other regenerate once. A regeneration imports the
+ * kit's modules afresh, keeps Vite's cache and the scenario editor's story,
+ * and writes only the files whose content changed; Vite then reloads the
+ * pages importing them. A kit with an html pane also reloads its pages when
+ * a regeneration writes nothing, since the pane prints the templates' markup
+ * itself and a change to it writes no generated file. A kit module that fails to load is
+ * logged and the last good output stays until a later save loads.
+ *
+ * @param context - The kit's preview context.
+ * @param options - What a change to the kit configuration file does, and the delay.
+ * @returns The plugin.
+ */
+export declare function kitWatchPlugin(context: PreviewContext, options: KitWatchOptions): Plugin;
+/** A running development server. */
+export interface DevelopmentServer {
+    /** The Vite server currently serving; replaced when the kit configuration changes. */
+    readonly server: ViteDevServer;
+    /** Stops serving. */
+    close(): Promise<void>;
+}
+/**
+ * Generates a kit's preview and serves it, regenerating as the kit's
+ * preview inputs change and starting a new server, from the new
+ * configuration, when the kit configuration changes. A configuration that
+ * fails to load is logged and the running server kept.
+ *
+ * @param kitRoot - The kit root (where its package.json lives).
+ * @param overrides - The port and host, over the kit's configured ones.
+ * @param options - The kit configuration file, when it is not the one the
+ *   kit root gives.
+ * @returns The running server.
+ * @example
+ * ```ts
+ * const development = await startDevelopmentServer(kitRoot, { port: 6100 });
+ * ```
+ */
+export declare function startDevelopmentServer(kitRoot: string, overrides?: DevelopmentServerOverrides, options?: ConfigurationLookupOptions): Promise<DevelopmentServer>;