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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// The preview CLI: `scaffold-ui-kit-preview <command>` run from (or pointed at)
+// a kit root whose configuration carries a `preview` block. `dev` is the daily driver:
+// generate, then serve the host + per-target iframes on one Vite server,
+// regenerating as the kit changes.
+import { resolve } from 'node:path';
+import { Command } from 'commander';
+import { buildPreview } from './build.js';
+import { checkPreview } from './check.js';
+import { loadPreviewContext } from './context.js';
+import { generatePreview } from './generate.js';
+import { DEFAULT_PORT } from './vite-configuration.js';
+const program = new Command();
+program
+    .name('scaffold-ui-kit-preview')
+    .description('Preview for scaffold-ui-kit kits')
+    .option('--kit <path>', 'kit root', '.')
+    .option('--configuration <path>', "the kit configuration file (default: the one the kit's package.json names, else scaffold-ui-kit.ts or scaffold-ui-kit.json in the kit root)");
+function kitRoot() {
+    return resolve(process.cwd(), program.opts().kit);
+}
+/** The kit configuration file `--configuration` names, if any. */
+function configurationOptions() {
+    const { configuration } = program.opts();
+    return configuration === undefined ? {} : { configuration };
+}
+function context() {
+    const loaded = loadPreviewContext(kitRoot(), configurationOptions());
+    for (const line of loaded.warnings)
+        console.warn(`warning ${line}`);
+    return loaded;
+}
+program
+    .command('generate')
+    .description('one-shot: render the registries + manifest into .preview-generated/')
+    .action(async () => {
+    await generatePreview(context());
+});
+program
+    .command('dev')
+    .description('generate, then serve the preview (host + framework iframes), regenerating as the kit changes')
+    .option('--port <number>', `dev-server port (default: the kit's configured port, else ${DEFAULT_PORT})`, Number)
+    .option('--host [address]', "the address to listen on, or every address without one, so another device on the network can open the preview (default: the kit's configured host, else this machine only)")
+    .action(async (options) => {
+    const { startDevelopmentServer } = await import('./development-server.js');
+    await startDevelopmentServer(kitRoot(), { port: options.port, host: options.host }, configurationOptions());
+});
+program
+    .command('check')
+    .description('check the story files, the manual specs and the build against the components')
+    .option('--strict', 'fail on every warning the check itself raises, such as a select value or boolean no scenario sets')
+    .action(async (options) => {
+    const report = await checkPreview(kitRoot(), {
+        strict: options.strict,
+        ...configurationOptions(),
+    });
+    for (const line of report.errors)
+        console.error(`error   ${line}`);
+    for (const line of report.warnings)
+        console.warn(`warning ${line}`);
+    for (const line of report.hidden)
+        console.log(`hidden  ${line}`);
+    for (const line of report.ungenerated)
+        console.log(`ungenerated ${line}`);
+    console.log(`[preview:check] ${report.errors.length} errors, ${report.warnings.length} warnings, ${report.hidden.length} hidden props, ${report.ungenerated.length} ungenerated props`);
+    if (report.errors.length > 0)
+        process.exitCode = 1;
+});
+program
+    .command('build')
+    .description('check, then generate and build the static preview into .preview-static/; a check error stops it')
+    .action(async () => {
+    // A check error stops the build, with the errors printed as `check`
+    // prints them.
+    const { built, errors, warnings } = await buildPreview(kitRoot(), undefined, configurationOptions());
+    for (const line of warnings)
+        console.warn(`warning ${line}`);
+    if (built)
+        return;
+    for (const line of errors)
+        console.error(`error   ${line}`);
+    console.error(`[preview:build] ${errors.length} ${errors.length === 1 ? 'error' : 'errors'} from the check; the preview is not built`);
+    process.exitCode = 1;
+});
+program.parseAsync().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/context.d.ts

@@ -0,0 +1,179 @@
+import type { BemOptions } from '@js-template-engine/extension-bem';
+import type { TailwindOptions } from '@js-template-engine/extension-tailwind';
+import type { StylesheetPlacement } from '@js-template-engine/types';
+import type { ConfigurationLookupOptions } from 'scaffold-ui-kit';
+import { type ModuleImporter, type PreviewBrowserConfiguration, type PreviewConfiguration, type PreviewSourceConfiguration, type Target } from './lib/types.js';
+export interface ResolvedSource extends PreviewSourceConfiguration {
+    /** Absolute (resolved against the kit root). */
+    templatesDirectoryAbsolute?: string;
+    manualModuleAbsolute?: string;
+    storiesDirectoryAbsolute?: string;
+}
+/**
+ * A package of a kit built into one package per target (the kit
+ * configuration's `packages`), other than the kit root's own.
+ */
+export interface KitLayoutPackage {
+    /** The target the package is built for, or `styles` for the package of
+     *  the kit's stylesheets. */
+    role: Target | 'styles';
+    /** The package name. */
+    name: string;
+    /** The package's directory, absolute. */
+    directoryAbsolute: string;
+}
+export interface PreviewContext {
+    /** The kit's root (where its package.json lives). */
+    kitRoot: string;
+    /**
+     * The kit's other packages, when its configuration builds it into one
+     * package per target (`packages`): the styles package first,
+     * then each target's. Absent for a kit built as one package.
+     */
+    kitPackages?: KitLayoutPackage[];
+    /** The kit configuration file, absolute. */
+    configurationPath: string;
+    /** The kit's own modules a `.ts` configuration loaded beside its file. */
+    configurationModules: string[];
+    /** What reading the kit configuration warns of, such as its old file
+     *  name. */
+    warnings: string[];
+    /** The kit's name (the kit configuration's `name`). */
+    kitName: string;
+    /** The kit's version (its package.json `version`), when it has one. */
+    kitVersion?: string;
+    /**
+     * The scripted targets the kit builds (the kit configuration's `targets`, its
+     * `html` target left out), in the preview's order; all three when the kit
+     * names none. A component renders only in these, whatever its own targets.
+     */
+    targets: Target[];
+    /** Whether the kit builds html (`html` among the kit configuration's
+     *  `targets`), so the preview shows an html pane beside the other targets'. */
+    buildsHtml?: boolean;
+    /** The mode the kit builds its Svelte target in (the kit configuration's
+     *  `svelte.mode`), `legacy` when it names none. */
+    svelteMode: 'legacy' | 'runes';
+    /** The generated tree (`<kitRoot>/.preview-generated`). */
+    generatedRoot: string;
+    /** The static-build output (`<kitRoot>/.preview-static`). */
+    staticRoot: string;
+    /** The preview block, with `options` and `themes` defaulted to none and
+     *  `controlHints.colorTokens`' unset choice as `null`. */
+    configuration: PreviewConfiguration & Pick<PreviewBrowserConfiguration, 'options' | 'themes' | 'canvas'>;
+    sources: ResolvedSource[];
+    /** Absolute path of the kit's custom-views module, when registered. */
+    viewsModuleAbsolute?: string;
+    /** Absolute path of the kit's code-block module, when it names one. */
+    codeBlockModuleAbsolute?: string;
+    /** Absolute path of the shell module `preview.shell` names. */
+    shellModuleAbsolute: string;
+    /** Absolute path of the shell's page module, when it has one: the module
+     *  `preview.shell.page` names, or the one its package ships. */
+    shellPageAbsolute?: string;
+    /**
+     * Absolute path of the shell shipped with the preview, when the kit's
+     * shell is it: named as it is, or through a module of the kit's that
+     * imports it to configure it (`charcellShell({ ... })`). Absent under a
+     * shell of the kit's own.
+     */
+    charcellShellAbsolute?: string;
+    /** The kit's `omitPattern`, compiled. */
+    omitPattern?: RegExp;
+    importModule: ModuleImporter;
+    /** The kit's styling settings, which the html source renders with. */
+    styling: KitStyling;
+    /**
+     * The kit's shared modules templates import by specifier (`add.shared`
+     * code modules the kit's `package.json` exports), resolved against the
+     * kit root. The html
+     * source puts their exports in scope, so an expression calling a kit helper
+     * evaluates.
+     */
+    sharedModulesAbsolute: string[];
+    /**
+     * The framework-free entries of `@scaffold-ui-kit/helpers` (`/runtime`
+     * and `/zag`) as installed for the kit, resolved from the kit root or one
+     * of its packages. The html source puts their exports in scope beside the
+     * shared modules', so an expression calling a helper evaluates. Empty when
+     * the kit does not have the package.
+     */
+    helperModulesAbsolute: string[];
+    /**
+     * The kit's shared modules with the package path its built files import
+     * each by (the one the kit's `package.json` exports give it, or an older
+     * configuration's `specifier`), the source relative to the kit root as
+     * written.
+     */
+    sharedSpecifiers: {
+        source: string;
+        specifier: string;
+    }[];
+    /**
+     * The kit's Sass load paths (the kit configuration's top-level
+     * `loadPaths`), resolved against the kit root, which the kit's build
+     * compiles its SCSS with.
+     */
+    sassLoadPathsAbsolute: string[];
+    /**
+     * The parts of each compound whose root has no template, such as a
+     * hand-written component (the kit configuration's `parts`), by root name.
+     */
+    parts: Record<string, string[]>;
+}
+/** The styling keys of the kit configuration the html source reads. */
+export interface KitStyling {
+    /** The styling extensions, in configuration order. */
+    extensions: Array<'bem' | 'tailwind'>;
+    /** Where each component's stylesheet is placed (the kit configuration's
+     *  `stylesheetPlacement`), `in-file` when it names none. */
+    placement: StylesheetPlacement;
+    /** The BEM extension's options (the kit configuration's `bem` block). */
+    bem?: BemOptions;
+    /** The Tailwind extension's options (the kit configuration's `tailwind`
+     *  block). */
+    tailwind?: TailwindOptions;
+}
+/**
+ * What is wrong with a list of pane widths, or nothing: it must be a list of
+ * `{ label, width }`, each label a non-empty string and each width a whole
+ * number of CSS pixels from 1 to the most a pane is laid out at, no label
+ * and no width named twice.
+ *
+ * @param paneWidths - The list, as the kit gives it.
+ * @param name - Where the kit gives it, for the message.
+ * @returns The problem, or `undefined` when the list is sound.
+ * @example
+ * ```ts
+ * paneWidthsProblem([{ label: 'small', width: 375 }], 'paneWidths'); // undefined
+ * ```
+ */
+export declare function paneWidthsProblem(paneWidths: unknown, name: string): string | undefined;
+/** The shell shipped with the preview, named when a kit configures none. */
+export declare const CHARCELL_SHELL = "@scaffold-ui-kit/preview/shells/charcell";
+/**
+ * The problems that keep a value from reaching the browser as JSON, each
+ * naming where in the value it sits: a function, `undefined` in a list, a
+ * number JSON has no form for, and an object other than a plain one or a
+ * list (a regular expression, a date, a map).
+ *
+ * @param value - The value.
+ * @param path - Where the value sits, as `preview.options`.
+ * @returns One message per problem.
+ * @example
+ * ```ts
+ * jsonProblems({ apply: () => {} }, 'preview.options[0]');
+ * // ["preview.options[0].apply is a function, which can't be sent to the browser as JSON"]
+ * ```
+ */
+export declare function jsonProblems(value: unknown, path: string, ancestors?: WeakMap<object, string>): string[];
+/**
+ * Finds the kit configuration (`--configuration`, the kit's `package.json`
+ * pointer, or `scaffold-ui-kit.ts` or `scaffold-ui-kit.json` at the kit
+ * root) and resolves the preview context from its `preview` block.
+ *
+ * @param kitRoot - The kit root.
+ * @param options - The configuration file a command was given, if any.
+ * @returns The context.
+ */
+export declare function loadPreviewContext(kitRoot: string, options?: ConfigurationLookupOptions): PreviewContext;