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

package/dist/generate.js

@@ -0,0 +1,302 @@
+// The preview generator: enumerate every source's component templates → build
+// one target-agnostic model per component → emit a per-target
+// render-registry + the host manifest into `<kitRoot>/.preview-generated/`. Pure
+// function of the preview context - no kit names or paths are baked in; the
+// kit supplies everything through its `preview` block (see context.ts).
+//
+// Every output is rendered before anything is written, so a kit module that
+// fails to load leaves the previous output in place. A file is written only
+// when its content differs from what is on disk, so a development server
+// serving the tree reloads only for what changed.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { kitPaneWidths, loadKit } from './load.js';
+import { landingProblems } from './landing.js';
+import { scenarioStories, storyOnScenario } from './lib/scenario-story.js';
+import { resolveStory } from './model.js';
+import { REACT_ATTRIBUTE_NAMES } from '@js-template-engine/extension-react';
+import { declaredAttributes } from './lib/react-spelling.js';
+import { emitReactRegistry } from './emit/react.js';
+import { emitVueRegistry } from './emit/vue.js';
+import { emitSvelteRegistry, emitSvelteWrapper } from './emit/svelte.js';
+import { buildManifest } from './emit/manifest.js';
+import { writeScratchStubs } from './emit/scratch.js';
+import { optionProblems } from './options.js';
+import { htmlWarningLine, printHtmlSource, sourceStoryOf, } from './story-source.js';
+import { htmlSourceResponse } from './html-stylesheet.js';
+import { HTML_SOURCE_DIRECTORY, } from './controller/html-source.js';
+import { exportedTypesOf } from './lib/exported-types.js';
+import { sanitize } from './lib/naming.js';
+import { moduleOfSource } from './lib/module-of-source.js';
+const targets = ['react', 'vue', 'svelte'];
+/** Every file under `directory`, as absolute paths. */
+function filesUnder(directory) {
+    return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(directory, entry.name);
+        return entry.isDirectory() ? filesUnder(path) : [path];
+    });
+}
+/** Writes `content` to `path` unless the file already holds exactly that. */
+function writeIfChanged(path, content) {
+    const bytes = typeof content === 'string' ? Buffer.from(content) : content;
+    if (existsSync(path) && readFileSync(path).equals(bytes))
+        return false;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, bytes);
+    return true;
+}
+/**
+ * Generates the preview into `<kitRoot>/.preview-generated/`: a render
+ * registry per target, the Svelte wrappers, the module-resolution data the
+ * scenario editor reads, the host manifest, and the themes' stylesheets.
+ *
+ * @param context - The kit's preview context.
+ * @param options - Whether the generated tree is emptied first.
+ * @returns The files written and removed.
+ * @example
+ * ```ts
+ * await generatePreview(loadPreviewContext(kitRoot));
+ * ```
+ */
+export async function generatePreview(context, options = {}) {
+    const { clean = true, htmlSources = false } = options;
+    const { generatedRoot, sources } = context;
+    const directory = {};
+    for (const target of targets) {
+        directory[target] = resolve(generatedRoot, target);
+    }
+    const { components } = await loadKit(context);
+    const hints = context.configuration.controlHints ?? {};
+    const problems = optionProblems(context.configuration.options);
+    if (problems.length > 0) {
+        throw new Error(`[preview] ${context.configurationPath} gives unsound preview.options:\n  ${problems.join('\n  ')}`);
+    }
+    const paneWidths = kitPaneWidths(context);
+    if (paneWidths.errors.length > 0)
+        throw new Error(`[preview] ${paneWidths.errors.join('\n[preview] ')}`);
+    // Each output, in the order it is written: a registry after the wrappers it
+    // imports, and the manifest, which names every story, last.
+    const outputs = [];
+    const themeSources = [];
+    // `moduleByName` remembers which module each component imports from, so the
+    // emitters group imports per source.
+    const moduleByName = new Map();
+    const importOverrideByName = new Map();
+    const exportByName = new Map();
+    for (const { component, source } of components) {
+        moduleByName.set(component.name, source.moduleBase);
+        if (component.importModule)
+            importOverrideByName.set(component.name, component.importModule);
+        if (component.exportName && component.exportName !== component.name) {
+            exportByName.set(component.name, component.exportName);
+        }
+    }
+    const built = components.map(({ component, story, source }) => ({
+        ...resolveStory(component, story, hints, context.configuration.labels, context.omitPattern, context.targets),
+        source: source.id,
+    }));
+    // A component's per-target import module: a per-component override (a
+    // playground fixture outside its source's published barrel) wins; otherwise
+    // the source's module for the target (`moduleOfSource`), defaulting slot children that belong to
+    // no registered source to the kit's own (first) source.
+    const defaultModule = sources[0].moduleBase;
+    const moduleFor = (name, target) => importOverrideByName.get(name)?.[target] ??
+        moduleOfSource(moduleByName.get(name) ?? defaultModule, target);
+    const exportFor = (name) => exportByName.get(name) ?? name;
+    // The names each component declares that React would otherwise respell
+    // (`class`, `style`, an attribute React renames): it takes them as they
+    // are, and every other attribute a story gives it as React spells it.
+    const declaredAttributesByName = new Map(components.map(({ component }) => [
+        component.name,
+        declaredAttributes(Object.keys(component.props), REACT_ATTRIBUTE_NAMES),
+    ]));
+    const declaredAttributesOf = (name) => declaredAttributesByName.get(name) ?? [];
+    const declaredAttributesRecord = Object.fromEntries([...declaredAttributesByName].filter(([, names]) => names.length > 0));
+    // Browseable stories get registries + a nav entry; components that are not
+    // standalone (compound parts, shared blocks) are editor-only; omitted parts
+    // drop out entirely.
+    const stories = [];
+    const editorOnly = [];
+    const omitted = [];
+    for (const model of built) {
+        if (model.omit) {
+            omitted.push(model.name);
+            continue;
+        }
+        (model.standalone ? stories : editorOnly).push(model);
+    }
+    const landing = landingProblems(context.configuration.landing, stories);
+    if (landing.length > 0)
+        throw new Error(`[preview] ${landing.join('\n[preview] ')}`);
+    // Per-target registries (id → render unit) across ALL sources. A component
+    // renders only into the targets it declares within the kit's, so each
+    // target's registry sees only its own stories; a target the kit does not
+    // build gets an empty registry, so its iframe entry still builds.
+    // A scenario with slot content of its own is a story beside its
+    // component's, so its content renders as the component's does.
+    const forTarget = (target) => stories
+        .filter((model) => model.targets.includes(target))
+        .flatMap((model) => [model, ...scenarioStories(model)]);
+    for (const model of forTarget('svelte')) {
+        const wrapper = emitSvelteWrapper(model, moduleFor, exportFor);
+        outputs.push([resolve(directory.svelte, wrapper.fileName), wrapper.source]);
+    }
+    outputs.push([
+        resolve(directory.react, 'registry.tsx'),
+        emitReactRegistry(forTarget('react'), moduleFor, exportFor, declaredAttributesOf),
+    ], [
+        resolve(directory.vue, 'registry.ts'),
+        emitVueRegistry(forTarget('vue'), moduleFor, exportFor),
+    ], [
+        resolve(directory.svelte, 'registry.ts'),
+        emitSvelteRegistry(forTarget('svelte')),
+    ]);
+    // The module-resolution data the scratch regeneration endpoint reads (it runs in the
+    // Vite dev middleware with no kit imports of its own).
+    const scratchModules = {
+        defaultModule,
+        moduleByName: Object.fromEntries(moduleByName),
+        importOverrideByName: Object.fromEntries(importOverrideByName),
+        exportByName: Object.fromEntries(exportByName),
+        targets: context.targets,
+        ...(Object.keys(declaredAttributesRecord).length > 0
+            ? { declaredAttributes: declaredAttributesRecord }
+            : {}),
+    };
+    outputs.push([
+        resolve(generatedRoot, 'modules.json'),
+        JSON.stringify(scratchModules, null, 2) + '\n',
+    ]);
+    // Framework-neutral host manifest (nav, controls, color tokens) - stories
+    // plus the editor-only components (the editor reads both; the nav leaves
+    // those out).
+    const sourceMeta = sources.map((source) => ({
+        id: source.id,
+        label: source.label,
+        order: source.order,
+        moduleBase: source.moduleBase,
+    }));
+    // How a consumer imports each component, omitted ones included: a story's
+    // source in the browser names what its slot content holds.
+    const imports = {};
+    for (const { component } of components) {
+        const types = exportedTypesOf(component, context.targets);
+        imports[component.name] = {
+            exportName: exportFor(component.name),
+            ...(declaredAttributesOf(component.name).length > 0
+                ? { declaredAttributes: declaredAttributesOf(component.name) }
+                : {}),
+            modules: Object.fromEntries(context.targets.map((target) => [
+                target,
+                moduleFor(component.name, target),
+            ])),
+            ...(types ? { types } : {}),
+        };
+    }
+    const manifest = [
+        resolve(generatedRoot, 'manifest.json'),
+        JSON.stringify(buildManifest([...stories, ...editorOnly], sourceMeta, hints.colorTokens ?? [], context.kitName, context.configuration.labels, context.kitVersion, context.configuration.persistence, context.buildsHtml ? [...context.targets, 'html'] : context.targets, imports, context.configuration.codeBlock
+            ? { framework: context.configuration.codeBlock.framework ?? 'dom' }
+            : undefined, paneWidths.paneWidths, context.targets.includes('svelte') ? context.svelteMode : undefined, context.targets.includes('react') ? REACT_ATTRIBUTE_NAMES : undefined, context.configuration.landing), null, 2) + '\n',
+    ];
+    // Themes: copy each theme's compiled stylesheet (+ optional asset dir) into
+    // the served tree - `<generatedRoot>/public` is the Vite publicDir, so the iframes
+    // link `themes/<id>/theme.css` (under the URL the preview is served from) by convention in dev and static build alike.
+    for (const theme of context.configuration.themes) {
+        const themeDirectory = resolve(generatedRoot, 'public/themes', theme.id);
+        const cssSource = resolve(context.kitRoot, theme.css);
+        if (!existsSync(cssSource)) {
+            throw new Error(`[preview] theme '${theme.id}' stylesheet not found: ${cssSource}`);
+        }
+        themeSources.push(cssSource);
+        outputs.push([
+            resolve(themeDirectory, 'theme.css'),
+            readFileSync(cssSource),
+        ]);
+        if (theme.assets) {
+            const assetsSource = resolve(context.kitRoot, theme.assets);
+            themeSources.push(assetsSource);
+            if (existsSync(assetsSource)) {
+                const assetsDestination = resolve(themeDirectory, basename(assetsSource));
+                const files = statSync(assetsSource).isDirectory()
+                    ? filesUnder(assetsSource)
+                    : [assetsSource];
+                for (const file of files) {
+                    outputs.push([
+                        resolve(assetsDestination, relative(assetsSource, file)),
+                        readFileSync(file),
+                    ]);
+                }
+            }
+        }
+    }
+    // The html of each story's scenarios, which the static build cannot print
+    // on request: one file per component, by scenario id, the anonymous
+    // default under ''.
+    if (htmlSources) {
+        const enumerated = components.map((entry) => entry.component);
+        for (const [index, model] of built.entries()) {
+            if (model.omit || !model.standalone)
+                continue;
+            const { component, story } = components[index];
+            const byScenario = {};
+            // What the html leaves out, once per story however many of its
+            // scenarios do.
+            const warnings = new Set();
+            const anonymous = { id: '', props: {} };
+            for (const scenario of [anonymous, ...model.scenarios]) {
+                const result = await printHtmlSource(context, enumerated, {
+                    component,
+                    // The html the panes render, the unfilled default slot's
+                    // placeholder included, as the scripted panes show it, and the
+                    // scenario's own slot content where it has any.
+                    ...sourceStoryOf(component, story, storyOnScenario(model, scenario), scenario.props ?? {}, { placeholder: true }),
+                });
+                if (result.markup !== undefined)
+                    for (const warning of result.warnings)
+                        warnings.add(warning);
+                byScenario[scenario.id] = htmlSourceResponse(context, enumerated, result);
+            }
+            if (warnings.size > 0)
+                console.warn(`[preview:generate] ${htmlWarningLine(model.name, [...warnings])}`);
+            outputs.push([
+                resolve(generatedRoot, 'public', HTML_SOURCE_DIRECTORY, `${sanitize(model.title)}.json`),
+                JSON.stringify(byScenario) + '\n',
+            ]);
+        }
+    }
+    outputs.push(manifest);
+    // Everything rendered: only now is the tree touched.
+    if (clean)
+        rmSync(generatedRoot, { recursive: true, force: true });
+    for (const target of targets) {
+        mkdirSync(directory[target], { recursive: true });
+    }
+    // Empty scratch registries so the previews' static scratch imports resolve;
+    // the scenario editor overwrites these on each edit (see emit/scratch.ts),
+    // so a kept tree keeps the story it holds.
+    if (clean || !existsSync(resolve(generatedRoot, 'scratch'))) {
+        writeScratchStubs(generatedRoot);
+    }
+    const written = outputs
+        .filter(([path, content]) => writeIfChanged(path, content))
+        .map(([path]) => path);
+    const produced = new Set(outputs.map(([path]) => path));
+    const removed = targets
+        .flatMap((target) => filesUnder(directory[target]))
+        .filter((path) => !produced.has(path));
+    for (const path of removed)
+        rmSync(path, { force: true });
+    const sourceSummary = sources
+        .map((source) => `${source.id}=${source.moduleBase}`)
+        .join(', ');
+    console.log(`[preview:generate] ${stories.length} components × ${context.targets.length} targets → .preview-generated/ (sources: ${sourceSummary})`);
+    if (editorOnly.length > 0)
+        console.log(`[preview:generate] ${editorOnly.length} not standalone (editor-only): ${editorOnly.map((model) => model.name).join(', ')}`);
+    const unlisted = stories.filter((model) => model.unlisted);
+    if (unlisted.length > 0)
+        console.log(`[preview:generate] unlisted ${unlisted.length} (reachable at their address): ${unlisted.map((model) => model.name).join(', ')}`);
+    if (omitted.length > 0)
+        console.log(`[preview:generate] omitted ${omitted.length} (by omit or omitPattern): ${omitted.join(', ')}`);
+    return { written, removed, themeSources };
+}

package/dist/html-stylesheet.d.ts

@@ -0,0 +1,43 @@
+import type { PreviewContext } from './context.js';
+import type { HtmlSourceResponse } from './controller/html-source.js';
+import type { HtmlSourceResult } from './emit/html-source.js';
+import type { EnumeratedComponent } from './lib/types.js';
+/** Where the kit's build writes the html target, relative to the kit root. */
+export declare const HTML_DISTRIBUTION_DIRECTORY = "dist/html";
+/**
+ * The `<style>` blocks of a page, joined in document order.
+ *
+ * @param page - A page's markup.
+ * @returns The CSS its style blocks hold, or `''` when it has none.
+ * @example
+ * ```ts
+ * styleBlocksOf('<style>.a { color: red; }</style><p class="a"></p>');
+ * // '.a { color: red; }'
+ * ```
+ */
+export declare function styleBlocksOf(page: string): string;
+/**
+ * The CSS the kit's build wrote for the html target of each named
+ * component, in the order given: the `<style>` blocks of its page and its
+ * own stylesheet, when it has one. A component with no built output adds
+ * nothing.
+ *
+ * @param context - The kit's preview context.
+ * @param components - Every component of the kit.
+ * @param names - The components whose styles to read, by name.
+ * @returns The CSS, one comment-headed section per component, or `''`.
+ */
+export declare function htmlComponentStylesheet(context: PreviewContext, components: readonly EnumeratedComponent[], names: readonly string[]): string;
+/**
+ * A printed story as the html pane receives it: its markup with the styles
+ * of the components it renders and the warnings for what it leaves out,
+ * those one component gives for one reason counted on a single line, or
+ * what keeps it from having markup.
+ *
+ * @param context - The kit's preview context.
+ * @param components - Every component of the kit.
+ * @param result - The printed story.
+ * @returns The response the development server answers and the static
+ *   build stores.
+ */
+export declare function htmlSourceResponse(context: PreviewContext, components: readonly EnumeratedComponent[], result: HtmlSourceResult): HtmlSourceResponse;

package/dist/html-stylesheet.js

@@ -0,0 +1,145 @@
+// The component styles the html pane shows its markup under: what the kit's
+// build wrote for the html target, read from `dist/html` for the components a
+// story renders. Under `in-file` each page carries its styles in `<style>`
+// blocks; under `separate-file` each component has a stylesheet of its own,
+// compiled when it is SCSS with the kit's own Sass and load paths. The markup
+// is printed from the templates on request, so a component changed since the
+// last build shows its last built styles until the kit builds again.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { summarizeHtmlWarnings } from './lib/html-warnings.js';
+import { kitImporters, kitPackageDirectories } from './sass-importers.js';
+/** Where the kit's build writes the html target, relative to the kit root. */
+export const HTML_DISTRIBUTION_DIRECTORY = 'dist/html';
+const STYLE_BLOCK = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+/**
+ * The `<style>` blocks of a page, joined in document order.
+ *
+ * @param page - A page's markup.
+ * @returns The CSS its style blocks hold, or `''` when it has none.
+ * @example
+ * ```ts
+ * styleBlocksOf('<style>.a { color: red; }</style><p class="a"></p>');
+ * // '.a { color: red; }'
+ * ```
+ */
+export function styleBlocksOf(page) {
+    return [...page.matchAll(STYLE_BLOCK)]
+        .map((match) => match[1].trim())
+        .filter((css) => css !== '')
+        .join('\n');
+}
+/** A component name a built file can carry: an identifier, so it names a
+ *  file in the html directory and nothing outside it. */
+const BUILT_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Each compiled SCSS sheet, by path, with the modification time it was
+ *  compiled at. */
+const compiledSheets = new Map();
+/** The sheets already reported as left out, each reported once. */
+const reportedSheets = new Set();
+/** Compiles an SCSS file with the kit's own Sass, or says why it cannot.
+ *  A sheet unchanged since it last compiled is not compiled again. */
+function compileScss(path, context) {
+    const modified = statSync(path).mtimeMs;
+    const cached = compiledSheets.get(path);
+    if (cached && cached.modified === modified)
+        return { css: cached.css };
+    let sass;
+    try {
+        const kitRequire = createRequire(resolve(context.kitRoot, 'package.json'));
+        sass = kitRequire('sass');
+    }
+    catch {
+        return { problem: 'the kit has no sass installed to compile it' };
+    }
+    try {
+        const loadPaths = [
+            dirname(path),
+            ...context.sassLoadPathsAbsolute,
+            ...(context.configuration.scssLoadPaths ?? []).map((loadPath) => resolve(context.kitRoot, loadPath)),
+        ];
+        // The kit's own `pkg:` URLs resolve through its package.json exports,
+        // as its build resolves them, and any other through Sass's own importer.
+        const importers = [
+            ...kitImporters(context.kitRoot, kitPackageDirectories(context)),
+            ...(sass.NodePackageImporter
+                ? [new sass.NodePackageImporter(context.kitRoot)]
+                : []),
+        ];
+        const css = sass.compile(path, { loadPaths, importers }).css;
+        compiledSheets.set(path, { modified, css });
+        return { css };
+    }
+    catch (error) {
+        return { problem: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * The CSS the kit's build wrote for the html target of each named
+ * component, in the order given: the `<style>` blocks of its page and its
+ * own stylesheet, when it has one. A component with no built output adds
+ * nothing.
+ *
+ * @param context - The kit's preview context.
+ * @param components - Every component of the kit.
+ * @param names - The components whose styles to read, by name.
+ * @returns The CSS, one comment-headed section per component, or `''`.
+ */
+export function htmlComponentStylesheet(context, components, names) {
+    const directory = resolve(context.kitRoot, HTML_DISTRIBUTION_DIRECTORY);
+    if (!existsSync(directory))
+        return '';
+    const sections = [];
+    for (const name of names) {
+        if (!components.some((candidate) => candidate.name === name))
+            continue;
+        if (!BUILT_NAME.test(name))
+            continue;
+        const parts = [];
+        const page = resolve(directory, `${name}.html`);
+        if (existsSync(page))
+            parts.push(styleBlocksOf(readFileSync(page, 'utf8')));
+        const css = resolve(directory, `${name}.css`);
+        if (existsSync(css))
+            parts.push(readFileSync(css, 'utf8').trim());
+        const scss = resolve(directory, `${name}.scss`);
+        if (existsSync(scss)) {
+            const compiled = compileScss(scss, context);
+            if ('css' in compiled)
+                parts.push(compiled.css.trim());
+            else if (!reportedSheets.has(scss)) {
+                reportedSheets.add(scss);
+                console.warn(`[preview] ${name}: the html pane leaves out ${name}.scss, as ${compiled.problem}`);
+            }
+        }
+        const styles = parts.filter((part) => part !== '').join('\n');
+        if (styles !== '')
+            sections.push(`/* ${name} */\n${styles}`);
+    }
+    return sections.join('\n\n');
+}
+/**
+ * A printed story as the html pane receives it: its markup with the styles
+ * of the components it renders and the warnings for what it leaves out,
+ * those one component gives for one reason counted on a single line, or
+ * what keeps it from having markup.
+ *
+ * @param context - The kit's preview context.
+ * @param components - Every component of the kit.
+ * @param result - The printed story.
+ * @returns The response the development server answers and the static
+ *   build stores.
+ */
+export function htmlSourceResponse(context, components, result) {
+    if (result.markup === undefined)
+        return { missing: result.missing };
+    const stylesheet = htmlComponentStylesheet(context, components, result.components);
+    return {
+        markup: result.markup,
+        ...(stylesheet === '' ? {} : { stylesheet }),
+        ...(result.warnings.length === 0
+            ? {}
+            : { warnings: summarizeHtmlWarnings(result.warnings) }),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { jsonProblems, loadPreviewContext, type PreviewContext, type ResolvedSource, } from './context.js';
+export { generatePreview } from './generate.js';
+export { checkPreview, type PreviewCheckOptions, type PreviewCheckReport, } from './check.js';
+export { storySource, type SourceTarget, type StorySource, type StorySourceOptions, } from './story-source.js';
+export { loadKit, kitPaneWidths, type KitPaneWidths, type LoadedComponent, type LoadedKit, } from './load.js';
+export { readPropsFrom, resolveManualComponent, type PropsFromResult, } from './props-from.js';
+export { applicationRoot, buildViteConfiguration, type DevelopmentServerOverrides, } from './vite-configuration.js';
+export { enumerateComponents } from './enumerate.js';
+export { resolveStory } from './model.js';
+export { propTypeForProp, defaultPropForProp } from './prop-types.js';
+export { loadStory, isStructurallyOmitted } from './story.js';
+export { emitReactRegistry } from './emit/react.js';
+export { emitVueRegistry } from './emit/vue.js';
+export { emitSvelteRegistry, emitSvelteWrapper } from './emit/svelte.js';
+export { buildManifest, type Manifest, type ManifestComponent, type ManifestSource, } from './emit/manifest.js';
+export { writeScratch, writeScratchStubs, SCRATCH_ID, type ScratchPayload, } from './emit/scratch.js';
+export * from './lib/types.js';
+export * from './options.js';

package/dist/index.js

@@ -0,0 +1,21 @@
+// Programmatic surface: everything a consumer's own scripts (or tests) need -
+// the context loader, the generator, the Vite configuration factory, and the model /
+// emit layer the registries are built from.
+export { jsonProblems, loadPreviewContext, } from './context.js';
+export { generatePreview } from './generate.js';
+export { checkPreview, } from './check.js';
+export { storySource, } from './story-source.js';
+export { loadKit, kitPaneWidths, } from './load.js';
+export { readPropsFrom, resolveManualComponent, } from './props-from.js';
+export { applicationRoot, buildViteConfiguration, } from './vite-configuration.js';
+export { enumerateComponents } from './enumerate.js';
+export { resolveStory } from './model.js';
+export { propTypeForProp, defaultPropForProp } from './prop-types.js';
+export { loadStory, isStructurallyOmitted } from './story.js';
+export { emitReactRegistry } from './emit/react.js';
+export { emitVueRegistry } from './emit/vue.js';
+export { emitSvelteRegistry, emitSvelteWrapper } from './emit/svelte.js';
+export { buildManifest, } from './emit/manifest.js';
+export { writeScratch, writeScratchStubs, SCRATCH_ID, } from './emit/scratch.js';
+export * from './lib/types.js';
+export * from './options.js';

package/dist/landing.d.ts

@@ -0,0 +1,16 @@
+import type { PreviewLandingConfiguration, ResolvedStory } from './lib/types.js';
+/**
+ * What is wrong with the landing entry a kit names, against its stories:
+ * a component with no story, or a scenario the story does not have. A
+ * view's id is not checked here. Empty when the entry is sound or unset.
+ *
+ * @param landing - The kit's `preview.landing`.
+ * @param stories - The kit's browseable stories: omitted components and those
+ *   that are not standalone left out.
+ * @returns One message per problem.
+ * @example
+ * ```ts
+ * landingProblems({ component: 'components-button', scenario: 'primary' }, stories);
+ * ```
+ */
+export declare function landingProblems(landing: PreviewLandingConfiguration | undefined, stories: readonly ResolvedStory[]): string[];

package/dist/landing.js

@@ -0,0 +1,45 @@
+// The entry a kit names for the preview to open on (`preview.landing`),
+// checked against the kit's stories: the generator and the check both refuse
+// a story or scenario the kit has none of. A view's id is the views module's,
+// which only the browser loads, so the preview's controller checks that one.
+import { sanitize } from './lib/naming.js';
+/** The id of the synthetic scenario that renders a story with no content. */
+const EMPTY_SCENARIO_ID = 'empty';
+/**
+ * What is wrong with the landing entry a kit names, against its stories:
+ * a component with no story, or a scenario the story does not have. A
+ * view's id is not checked here. Empty when the entry is sound or unset.
+ *
+ * @param landing - The kit's `preview.landing`.
+ * @param stories - The kit's browseable stories: omitted components and those
+ *   that are not standalone left out.
+ * @returns One message per problem.
+ * @example
+ * ```ts
+ * landingProblems({ component: 'components-button', scenario: 'primary' }, stories);
+ * ```
+ */
+export function landingProblems(landing, stories) {
+    if (!landing || !('component' in landing))
+        return [];
+    const story = stories.find((candidate) => sanitize(candidate.title) === landing.component);
+    if (!story)
+        return [
+            `preview.landing names component '${landing.component}', which has no story; a story's id is the one the preview's address carries as component=`,
+        ];
+    const scenario = landing.scenario;
+    if (scenario === undefined)
+        return [];
+    const hasContent = story.contentSlots.default || story.contentSlots.named.length > 0;
+    const scenarios = [
+        ...(hasContent ? [EMPTY_SCENARIO_ID] : []),
+        ...story.scenarios.map((candidate) => candidate.id),
+    ];
+    return scenarios.includes(scenario)
+        ? []
+        : [
+            `preview.landing names scenario '${scenario}' of '${landing.component}', which has ${scenarios.length > 0
+                ? `the scenarios ${scenarios.join(', ')}`
+                : 'no scenarios'}`,
+        ];
+}

package/dist/lib/exported-types.d.ts

@@ -0,0 +1,42 @@
+import type { Target } from './types.js';
+/**
+ * The type names one module-scope line exports. A value-only export list
+ * (`export { a }`) names no type unless a member is marked `type`, as a value
+ * cannot be told from a type there.
+ *
+ * @param line - A verbatim module-scope line.
+ * @returns The type names it exports, in order.
+ */
+export declare function exportedTypeNamesOf(line: string): string[];
+/** The parts of a template the exported types are read from. */
+export interface ExportingTemplate {
+    imports?: string[];
+    extensions?: Record<string, unknown>;
+}
+/**
+ * The type names a template's generated module exports in one scripted
+ * target: those its module-scope lines declare, the target's own `imports`
+ * merged in (or in their place, with `importsStrategy: 'replace'`).
+ *
+ * @param template - The component's template.
+ * @param target - The scripted target.
+ * @returns The exported type names, each once.
+ * @example
+ * ```ts
+ * exportedTypeNames({ imports: ['export interface DateValue { day: string }'] }, 'react');
+ * // ['DateValue']
+ * ```
+ */
+export declare function exportedTypeNames(template: ExportingTemplate, target: Target): string[];
+/**
+ * The type names a component's generated module exports, per scripted
+ * target: none for a component written by hand, whose module the preview
+ * does not read.
+ *
+ * @param component - The component, with the template it was read from.
+ * @param targets - The scripted targets the kit builds.
+ * @returns The names per target that exports any, or `undefined` when none does.
+ */
+export declare function exportedTypesOf(component: {
+    template?: unknown;
+}, targets: readonly Target[]): Partial<Record<Target, string[]>> | undefined;