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

package/dist/options.d.ts

@@ -0,0 +1,224 @@
+/** An option's runtime value: a string (a choice) or a boolean. */
+export type OptionValue = string | boolean;
+/** One value a choice option offers. */
+export interface OptionChoice {
+    value: string;
+    label: string;
+}
+/** What kind of value an option holds: one of its `values`, or a boolean. */
+export type OptionKind = 'choice' | 'boolean';
+/** The group of the kit's own settings, such as its theme: what sets up the
+ *  kit as a whole rather than the setting a component is shown in. */
+export declare const KIT_OPTION_GROUP = "kit";
+/** The group of the options that set what a component is shown in, such as a
+ *  color mode, a surface or the padding around it. An option without a group
+ *  belongs to it. */
+export declare const CONTEXT_OPTION_GROUP = "context";
+/** The prefix of a shell option's id in the preview's state, address and
+ *  storage: a shell's `mode` is `shell.mode`, so it cannot collide with a kit
+ *  option of the same name. */
+export declare const SHELL_OPTION_PREFIX = "shell.";
+/** Which element an apply targets. `'root'` is the preview `<html>` (the
+ *  default), `'body'` is `<body>`, and `{ ref }` is a named node in the
+ *  kit's `mount` wrapper (resolved against the ref map). */
+export type ApplyTarget = 'root' | 'body' | {
+    ref: string;
+};
+/** How an option affects the preview canvas. The union is open by design - a
+ *  new strategy slots in without touching the registry. `root-attribute` /
+ *  `class` / `css-var` may carry a `target` to hit a `mount` wrapper
+ *  node instead of the document root. */
+export type OptionApply = 
+/** Set `<attribute>="<value>"` on the target element (default the preview
+ *  `<html>`); `false` or an empty value removes it. With `omitAtDefault`,
+ *  the option's default value removes it too, for a kit whose default
+ *  renders with no attribute, such as a default color mode. */
+{
+    type: 'root-attribute';
+    attribute: string;
+    target?: ApplyTarget;
+    omitAtDefault?: boolean;
+}
+/** Swap the active theme stylesheet by value (`themes/<id>/theme.css`
+ *  under the URL the preview is served from). */
+ | {
+    type: 'stylesheet';
+}
+/** Toggle `className` on the target by the value's truth; without
+ *  `className`, set the value as the target's `data-<namePrefix>-preview-class`
+ *  attribute for the kit's CSS to key off, `false` or an empty value removing
+ *  it. `on` names `'root'` or `'body'`; `target` names either as well, or
+ *  a wrapper node, and wins where both are given. */
+ | {
+    type: 'class';
+    on?: 'root' | 'body';
+    className?: string;
+    target?: ApplyTarget;
+}
+/** Set a CSS custom property to the value on the target element; `false` or
+ *  an empty value removes it. */
+ | {
+    type: 'css-var';
+    var: string;
+    target?: ApplyTarget;
+};
+/**
+ * One preview option: what it means, never where or how it is shown. Its kind
+ * follows from its fields - an option with `values` is a choice among them
+ * with a string `default`, and one without is a boolean with a boolean
+ * `default` - and the preview's interface picks the widget for that kind.
+ */
+export interface PreviewOption {
+    /** Stable key - the message payload key and the manifest per-story override key. */
+    id: string;
+    /** The option's name, as its control is labeled. */
+    label: string;
+    /** A longer description, such as a control's tooltip; markdown allowed. */
+    title?: string;
+    /** The values of a choice option. Omitted, the option is a boolean. */
+    values?: OptionChoice[];
+    /** The starting value: one of `values` for a choice, a boolean otherwise. */
+    default: OptionValue;
+    /** A free-form hint for where the option belongs: `'context'` (the
+     *  default) for the setting a component is shown in, such as its color
+     *  mode or the padding around it; `'kit'` for the kit's own settings, such
+     *  as its theme; or a name of the kit's choosing for a set that belongs
+     *  together, such as canvas settings. An interface places a group it does
+     *  not know in a default place. */
+    group?: string;
+    /** `global` = one value for the whole session; `story` = a value per
+     *  selected story, seeded from its story file, that lasts until another story
+     *  is selected. */
+    scope: 'global' | 'story';
+    /** How the value hits the canvas. */
+    apply: OptionApply;
+}
+/**
+ * An option a shell declares for itself, such as its own color mode or
+ * density: a {@link PreviewOption} without `apply` or `scope`. Its value
+ * never reaches the kit's iframes; the shell reads it from the preview's
+ * state under the id {@link shellOptionId} gives it, and it is global.
+ */
+export type PreviewShellOption = Omit<PreviewOption, 'apply' | 'scope'>;
+/**
+ * The id a shell option has in the preview's state, address and storage.
+ *
+ * @param id - The option's id as the shell declares it.
+ * @returns The id prefixed with `shell.`.
+ * @example
+ * ```ts
+ * shellOptionId('mode'); // 'shell.mode'
+ * ```
+ */
+export declare function shellOptionId(id: string): string;
+/** The kit-authored canvas styling: what the preview page paints with. The
+ *  preview's canvas stylesheet is a generic template over these values - the
+ *  kit's token vocabulary lives HERE, never in the preview. Any wrapper
+ *  geometry (surface fills, insets, padding) a kit wants lives in `extraCss`,
+ *  keyed off the nodes it declares in `mount`. Values are raw CSS. */
+export interface PreviewCanvasConfiguration {
+    /** Prefix for every preview-owned DOM name - injected element ids, the
+     *  class-apply data attribute (`data-<prefix>-preview-class`). */
+    namePrefix: string;
+    /** Canvas page background, painted on `<body>`. Optional: a kit whose
+     *  stylesheet already states its page canvas (the kit's own `html`/`body`
+     *  rules, loaded with the theme) omits it, and the preview paints nothing -
+     *  the preview document *is* the kit's page, and what the page is stays
+     *  the kit's (and the theme's) call rather than a value restated here. */
+    pageBackground?: string;
+    /** Extra kit-authored CSS appended to the canvas stylesheet - where a kit
+     *  styles its `mount` wrapper nodes and any option-driven geometry. */
+    extraCss?: string;
+}
+/** The canvas of a custom view's iframe, which shows a kit-authored view
+ *  rather than a mounted component: no `mount` wrapper, so none of the
+ *  component frame's geometry applies. A kit sets it as `viewCanvas`;
+ *  without it a view gets `canvas.pageBackground` and nothing else. The
+ *  name prefix stays `canvas.namePrefix`. Options still apply to a view,
+ *  except one targeting a `mount` node by `ref`, which a view lacks. */
+export interface PreviewViewCanvasConfiguration {
+    /** The view page's background, painted on `<body>`. */
+    pageBackground?: string;
+    /** Extra kit-authored CSS for the view page. */
+    extraCss?: string;
+}
+/** A node in a kit's `mount` wrapper tree - plain, framework-agnostic
+ *  DOM rendered around the `#app` mount, identical across every preview iframe.
+ *  The preview knows nothing of what these nodes mean; the kit styles them via
+ *  `canvas.extraCss` and targets options at them by `ref`. */
+export interface PreviewMountNode {
+    /** Element tag. Defaults to `'div'`. */
+    tag?: string;
+    /** Static attributes rendered on the element (e.g. a surface-cascade attribute). */
+    attributes?: Record<string, string>;
+    /** Static class names. */
+    classes?: string[];
+    /** Inline `style` text. */
+    style?: string;
+    /** Name for the ref map - the handle `apply.target = { ref }` resolves to,
+     *  and how kit CSS and option targeting address this node. */
+    ref?: string;
+    /** Child nodes, rendered in order. */
+    children?: PreviewMountNode[];
+    /** Marks the node the `#app` mount is reparented into. Exactly one node in
+     *  the tree sets this. */
+    mount?: boolean;
+}
+/**
+ * The kind of an option: a choice when it has `values`, a boolean otherwise.
+ *
+ * @param option - The option.
+ * @returns `'choice'` or `'boolean'`.
+ * @example
+ * ```ts
+ * optionKind({ values: [{ value: 'light', label: 'light' }] }); // 'choice'
+ * optionKind({}); // 'boolean'
+ * ```
+ */
+export declare function optionKind(option: Pick<PreviewOption, 'values'>): OptionKind;
+/**
+ * The group an option belongs to: its `group`, or `'context'` without one.
+ *
+ * @param option - The option.
+ * @returns The group name.
+ * @example
+ * ```ts
+ * optionGroup({ group: 'kit' }); // 'kit'
+ * optionGroup({}); // 'context'
+ * ```
+ */
+export declare function optionGroup(option: Pick<PreviewOption, 'group'>): string;
+/**
+ * Whether `value` is a value `option` can hold: one of its values for a
+ * choice, a boolean for a boolean.
+ *
+ * @param option - The option.
+ * @param value - The candidate value.
+ * @returns Whether the option accepts it.
+ */
+export declare function acceptsOptionValue(option: Pick<PreviewOption, 'values'>, value: unknown): value is OptionValue;
+/**
+ * The problems with a kit's options, each naming the option: a missing or
+ * repeated id, a scope other than `global` or `story`, an option whose
+ * kind is ambiguous - a choice needs `values` and a string `default` among
+ * them, a boolean no `values` and a boolean `default` - and a key the
+ * option, one of its values or its `apply` does not take. Empty when every
+ * option is sound.
+ *
+ * @param options - The preview block's `options`.
+ * @returns One message per problem.
+ */
+export declare function optionProblems(options: unknown): string[];
+/** The option registry keyed by id - O(1) lookup when applying a payload. */
+export declare function optionsById(options: PreviewOption[]): Record<string, PreviewOption>;
+/** Default values for the options in a scope (or all scopes). */
+export declare function optionDefaults(options: Array<Pick<PreviewOption, 'id' | 'default' | 'scope'>>, scope?: 'global' | 'story'): Record<string, OptionValue>;
+/**
+ * The served URL of a theme's stylesheet (the generator copies it there).
+ *
+ * @param themeId - The theme's id.
+ * @param baseUrl - The URL the preview is served under, ending in `/`; the
+ *   root of the origin, `/`, by default.
+ * @returns The stylesheet's URL, such as `/themes/light/theme.css`.
+ */
+export declare function themeHref(themeId: string, baseUrl?: string): string;

package/dist/options.js

@@ -0,0 +1,223 @@
+// The composable preview-options contract: the preview block's `options`,
+// `canvas`, `mount` and `viewCanvas`, and the derived helpers the host +
+// iframes share. Browser-safe - no node imports; both the Vite app and the
+// kit's configuration type against this file.
+/** The group of the kit's own settings, such as its theme: what sets up the
+ *  kit as a whole rather than the setting a component is shown in. */
+export const KIT_OPTION_GROUP = 'kit';
+/** The group of the options that set what a component is shown in, such as a
+ *  color mode, a surface or the padding around it. An option without a group
+ *  belongs to it. */
+export const CONTEXT_OPTION_GROUP = 'context';
+/** The prefix of a shell option's id in the preview's state, address and
+ *  storage: a shell's `mode` is `shell.mode`, so it cannot collide with a kit
+ *  option of the same name. */
+export const SHELL_OPTION_PREFIX = 'shell.';
+/**
+ * The id a shell option has in the preview's state, address and storage.
+ *
+ * @param id - The option's id as the shell declares it.
+ * @returns The id prefixed with `shell.`.
+ * @example
+ * ```ts
+ * shellOptionId('mode'); // 'shell.mode'
+ * ```
+ */
+export function shellOptionId(id) {
+    return `${SHELL_OPTION_PREFIX}${id}`;
+}
+/**
+ * The kind of an option: a choice when it has `values`, a boolean otherwise.
+ *
+ * @param option - The option.
+ * @returns `'choice'` or `'boolean'`.
+ * @example
+ * ```ts
+ * optionKind({ values: [{ value: 'light', label: 'light' }] }); // 'choice'
+ * optionKind({}); // 'boolean'
+ * ```
+ */
+export function optionKind(option) {
+    return option.values !== undefined ? 'choice' : 'boolean';
+}
+/**
+ * The group an option belongs to: its `group`, or `'context'` without one.
+ *
+ * @param option - The option.
+ * @returns The group name.
+ * @example
+ * ```ts
+ * optionGroup({ group: 'kit' }); // 'kit'
+ * optionGroup({}); // 'context'
+ * ```
+ */
+export function optionGroup(option) {
+    return option.group ?? CONTEXT_OPTION_GROUP;
+}
+/**
+ * Whether `value` is a value `option` can hold: one of its values for a
+ * choice, a boolean for a boolean.
+ *
+ * @param option - The option.
+ * @param value - The candidate value.
+ * @returns Whether the option accepts it.
+ */
+export function acceptsOptionValue(option, value) {
+    if (optionKind(option) === 'boolean')
+        return typeof value === 'boolean';
+    return (typeof value === 'string' &&
+        (option.values ?? []).some((choice) => choice.value === value));
+}
+/** The keys an option takes. */
+const OPTION_KEYS = Object.keys({
+    id: true,
+    label: true,
+    title: true,
+    values: true,
+    default: true,
+    group: true,
+    scope: true,
+    apply: true,
+});
+/** The keys a choice option's value takes. */
+const CHOICE_KEYS = Object.keys({
+    value: true,
+    label: true,
+});
+/** The keys each apply strategy takes, by its type: one entry per member of
+ *  `OptionApply`, listing every key of that member. A strategy of a type
+ *  the preview does not know is not checked. */
+const APPLY_KEY_SETS = {
+    'root-attribute': {
+        type: true,
+        attribute: true,
+        target: true,
+        omitAtDefault: true,
+    },
+    stylesheet: { type: true },
+    class: { type: true, on: true, className: true, target: true },
+    'css-var': { type: true, var: true, target: true },
+};
+const APPLY_KEYS = Object.fromEntries(Object.entries(APPLY_KEY_SETS).map(([type, keys]) => [
+    type,
+    Object.keys(keys),
+]));
+/** The keys of `value` that are not among `allowed`, `skipped` aside. A
+ *  key set to `undefined` is absent. */
+function unknownKeys(value, allowed, skipped = []) {
+    return Object.entries(value)
+        .filter(([key, entry]) => entry !== undefined && !allowed.includes(key) && !skipped.includes(key))
+        .map(([key]) => key);
+}
+/**
+ * The problems with a kit's options, each naming the option: a missing or
+ * repeated id, a scope other than `global` or `story`, an option whose
+ * kind is ambiguous - a choice needs `values` and a string `default` among
+ * them, a boolean no `values` and a boolean `default` - and a key the
+ * option, one of its values or its `apply` does not take. Empty when every
+ * option is sound.
+ *
+ * @param options - The preview block's `options`.
+ * @returns One message per problem.
+ */
+export function optionProblems(options) {
+    if (!Array.isArray(options))
+        return ['preview.options must be an array'];
+    const problems = [];
+    const seen = new Set();
+    options.forEach((candidate, index) => {
+        const option = candidate;
+        if (!option || typeof option !== 'object') {
+            problems.push(`preview.options[${index}] must be an object`);
+            return;
+        }
+        const name = typeof option.id === 'string' && option.id
+            ? `preview.options[${index}] ('${option.id}')`
+            : `preview.options[${index}]`;
+        if (typeof option.id !== 'string' || !option.id) {
+            problems.push(`${name}: id must be a non-empty string`);
+        }
+        else if (seen.has(option.id)) {
+            problems.push(`${name}: another option has the id '${option.id}'`);
+        }
+        else {
+            seen.add(option.id);
+        }
+        if (typeof option.label !== 'string')
+            problems.push(`${name}: label must be a string`);
+        if (option.scope !== 'global' && option.scope !== 'story')
+            problems.push(`${name}: scope must be 'global' or 'story'`);
+        if (option.group !== undefined &&
+            (typeof option.group !== 'string' || !option.group))
+            problems.push(`${name}: group must be a non-empty string`);
+        if ('slot' in option)
+            problems.push(`${name}: slot is not an option field - an option says where it belongs with group`);
+        if ('control' in option)
+            problems.push(`${name}: control is not an option field - an option with values is a choice, one with a boolean default a boolean`);
+        // `slot` and `control` are named above with where their meaning went.
+        for (const key of unknownKeys(option, OPTION_KEYS, ['slot', 'control']))
+            problems.push(`${name}: unknown key '${key}'; an option takes ${OPTION_KEYS.join(', ')}`);
+        if (option.values !== undefined) {
+            const values = option.values;
+            if (!Array.isArray(values) ||
+                values.length === 0 ||
+                values.some((choice) => !choice ||
+                    typeof choice.value !== 'string' ||
+                    typeof choice.label !== 'string')) {
+                problems.push(`${name}: values must be a non-empty list of { value, label } strings`);
+            }
+            else if (typeof option.default !== 'string') {
+                problems.push(`${name}: a choice option (one with values) needs a string default`);
+            }
+            else if (!values.some((choice) => choice.value === option.default)) {
+                problems.push(`${name}: default '${option.default}' is not one of its values`);
+            }
+        }
+        else if (typeof option.default !== 'boolean') {
+            problems.push(`${name}: an option without values is a boolean and needs a boolean default; a choice lists its values`);
+        }
+        if (Array.isArray(option.values))
+            option.values.forEach((choice, choiceIndex) => {
+                if (!choice || typeof choice !== 'object')
+                    return;
+                for (const key of unknownKeys(choice, CHOICE_KEYS))
+                    problems.push(`${name}: unknown key 'values[${choiceIndex}].${key}'; a value takes ${CHOICE_KEYS.join(', ')}`);
+            });
+        if (!option.apply || typeof option.apply !== 'object') {
+            problems.push(`${name}: apply must describe how the value hits the canvas`);
+        }
+        else {
+            const type = option.apply.type;
+            if (typeof type === 'string' && Object.hasOwn(APPLY_KEYS, type)) {
+                const allowed = APPLY_KEYS[type];
+                for (const key of unknownKeys(option.apply, allowed))
+                    problems.push(`${name}: unknown key 'apply.${key}'; a '${type}' apply takes ${allowed.join(', ')}`);
+            }
+        }
+    });
+    return problems;
+}
+/** The option registry keyed by id - O(1) lookup when applying a payload. */
+export function optionsById(options) {
+    return Object.fromEntries(options.map((option) => [option.id, option]));
+}
+/** Default values for the options in a scope (or all scopes). */
+export function optionDefaults(options, scope) {
+    const out = {};
+    for (const option of options) {
+        if (!scope || option.scope === scope)
+            out[option.id] = option.default;
+    }
+    return out;
+}
+/**
+ * The served URL of a theme's stylesheet (the generator copies it there).
+ *
+ * @param themeId - The theme's id.
+ * @param baseUrl - The URL the preview is served under, ending in `/`; the
+ *   root of the origin, `/`, by default.
+ * @returns The stylesheet's URL, such as `/themes/light/theme.css`.
+ */
+export function themeHref(themeId, baseUrl = '/') {
+    return `${baseUrl}themes/${themeId}/theme.css`;
+}

package/dist/prop-types.d.ts

@@ -0,0 +1,26 @@
+import type { PreviewControlHints, PropTypeSpecification, JsonValue } from './lib/types.js';
+/**
+ * The control a prop gets in the controls panel, from its declared type. A
+ * prop whose name ends in `color`, in any case (`color`, `borderColor`), and
+ * whose type is string-like gets the
+ * color select, offering the kit's color tokens, when the kit gives any;
+ * otherwise it is treated by its declared type like any other prop.
+ *
+ * @param componentName - The component the prop belongs to.
+ * @param propName - The prop's name.
+ * @param def - The prop's declared type, resolved type and default.
+ * @param hints - The kit's control hints; their `colorTokens` turn on the
+ *   color select.
+ * @returns The prop's control specification.
+ */
+export declare function propTypeForProp(componentName: string, propName: string, def: {
+    type: string;
+    resolvedType?: string;
+    default?: JsonValue;
+}, hints?: PreviewControlHints): PropTypeSpecification;
+/** Suggested default prop value from the template default (and the kit's
+ *  component-size hint, when it supplies one). */
+export declare function defaultPropForProp(componentName: string, propName: string, def: {
+    type: string;
+    default?: JsonValue;
+}, hints: PreviewControlHints): JsonValue | undefined;

package/dist/prop-types.js

@@ -0,0 +1,102 @@
+// Map one component prop → a control spec for the host's controls panel. Pure
+// function of the prop (name, parsed type, default) plus the kit's control
+// hints (its token-config hook - see PreviewControlHints).
+import { parseType } from './lib/parse-type.js';
+function isColorProp(name) {
+    return name === 'color' || /color$/i.test(name);
+}
+/** Whether the kit gives color tokens for a color select to offer. */
+function hasColorTokens(hints) {
+    return (hints.colorTokens ?? []).some((token) => token != null);
+}
+/** A union of string literals, template literal types (`` `accent-${string}` ``),
+ *  `string`, or named types - the shapes a color-token type takes, which the
+ *  color select can offer from the kit's token list whatever they expand to. */
+const NON_STRING_KEYWORDS = new Set([
+    'boolean',
+    'number',
+    'bigint',
+    'object',
+    'symbol',
+    'unknown',
+    'any',
+    'never',
+    'null',
+    'void',
+]);
+function isStringLikeType(type) {
+    return type
+        .split('|')
+        .map((part) => part.trim())
+        .every((part) => part === 'string' ||
+        part === 'undefined' ||
+        /^'[^']*'$/.test(part) ||
+        /^"[^"]*"$/.test(part) ||
+        /^`[^`]*`$/.test(part) ||
+        (!NON_STRING_KEYWORDS.has(part) &&
+            /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/.test(part)));
+}
+/**
+ * The control a prop gets in the controls panel, from its declared type. A
+ * prop whose name ends in `color`, in any case (`color`, `borderColor`), and
+ * whose type is string-like gets the
+ * color select, offering the kit's color tokens, when the kit gives any;
+ * otherwise it is treated by its declared type like any other prop.
+ *
+ * @param componentName - The component the prop belongs to.
+ * @param propName - The prop's name.
+ * @param def - The prop's declared type, resolved type and default.
+ * @param hints - The kit's control hints; their `colorTokens` turn on the
+ *   color select.
+ * @returns The prop's control specification.
+ */
+export function propTypeForProp(componentName, propName, def, hints = {}) {
+    const parsed = parseType(def.resolvedType ?? def.type);
+    const hasDefault = def.default !== undefined;
+    if (hasColorTokens(hints) &&
+        isColorProp(propName) &&
+        (parsed.kind === 'string' ||
+            (parsed.kind === 'enum' &&
+                parsed.options.every((option) => typeof option === 'string')) ||
+            isStringLikeType(def.type))) {
+        return { name: propName, control: 'color-select', include: true };
+    }
+    switch (parsed.kind) {
+        case 'boolean':
+            return { name: propName, control: 'boolean', include: true };
+        case 'number': {
+            if (propName === 'size') {
+                return {
+                    name: propName,
+                    control: 'number',
+                    number: { min: 0.25, max: 4, step: 0.05 },
+                    include: true,
+                };
+            }
+            return { name: propName, control: 'number', include: true };
+        }
+        case 'enum': {
+            const options = [...parsed.options];
+            if (!hasDefault)
+                options.unshift(undefined);
+            return { name: propName, control: 'select', options, include: true };
+        }
+        case 'string':
+        case 'stringOrNumber':
+            return { name: propName, control: 'text', include: true };
+        case 'complex':
+            // Record<...>, X[], injected interfaces - driver-internal or too complex
+            // for a control. Omit; a story file can supply a default prop if required.
+            return { name: propName, control: 'text', include: false };
+    }
+}
+/** Suggested default prop value from the template default (and the kit's
+ *  component-size hint, when it supplies one). */
+export function defaultPropForProp(componentName, propName, def, hints) {
+    if (def.default !== undefined)
+        return def.default;
+    if (propName === 'size' && parseType(def.type).kind === 'number') {
+        return hints.componentSizeRem?.(componentName);
+    }
+    return undefined;
+}

package/dist/props-from.d.ts

@@ -0,0 +1,84 @@
+import ts from 'typescript';
+import type { EnumeratedComponent, ManualComponentSpecification } from './lib/types.js';
+/** The props read from one `propsFrom` interface. */
+export interface PropsFromResult {
+    props: EnumeratedComponent['props'];
+    /** Whether the interface declares a non-function `children` (the default slot;
+     *  a render-function `children` is a scoped slot instead). */
+    hasChildren: boolean;
+    /** Whether that default slot exposes values to its content (a scoped
+     *  slot): a template component's whose default slot does, read through
+     *  `ComponentProps<typeof X>`. */
+    childrenScoped: boolean;
+    /** Members whose type is not a control. */
+    hiddenProps: string[];
+    /** Every own member name, `children` included. */
+    memberNames: string[];
+}
+/** A type declaration found by name: an interface or a type alias, in its file. */
+type Declaration = {
+    kind: 'interface';
+    node: ts.InterfaceDeclaration;
+    file: ts.SourceFile;
+} | {
+    kind: 'alias';
+    node: ts.TypeAliasDeclaration;
+    file: ts.SourceFile;
+};
+/** Finds type declarations by name across a kit's source files, following
+ *  imports and re-exports with TypeScript's module resolution and the kit's
+ *  tsconfig. Parses each file once. */
+export declare class DeclarationResolver {
+    private readonly files;
+    private readonly options;
+    constructor(kitRoot: string);
+    /** Parses source that is not on disk, as if it were the file at `path`, so
+     *  its imports resolve from there. Not cached. */
+    virtual(path: string, text: string): ts.SourceFile;
+    file(path: string): ts.SourceFile;
+    private resolveModule;
+    /** The declaration `name` refers to inside `file`: declared there, or imported. */
+    find(name: string, file: ts.SourceFile, seen?: Set<string>): Declaration | undefined;
+    /** The declaration a module exports as `name`, through re-exports. */
+    private findExport;
+}
+/**
+ * Reads the own members of the interface (or object type alias, or intersection
+ * of them) `propsFrom` names into preview prop definitions.
+ *
+ * @param reference - `'<file relative to the kit root>#<InterfaceName>'`
+ * @param kitRoot - The kit root the file resolves against
+ * @param templates - The kit's template components, which a
+ *   `ComponentProps<typeof X>` in the type can name
+ * @returns The props, the default-slot flag, and the hidden and member names
+ */
+export declare function readPropsFrom(reference: string, kitRoot: string, templates?: readonly EnumeratedComponent[]): PropsFromResult;
+/**
+ * A template prop's type with the named types it uses expanded, read through
+ * the template's own import statements: an alias becomes its members (a
+ * generic one with its arguments in place), an interface reads as an object
+ * form, and a union is flattened. `undefined` when the type names nothing to
+ * expand, or expands to the same text.
+ *
+ * @param type - The prop's type as the template writes it
+ * @param templatePath - The template file, which its imports resolve from
+ * @param imports - The template's import statements
+ * @param resolver - The declaration resolver to read through
+ * @returns The expanded type, or `undefined`
+ * @example
+ * // With `import type { StackAlign } from '@acme/kit/scripts';`
+ * resolveNamedType('StackAlign', templatePath, imports, resolver);
+ * // "'start' | 'center' | 'end'"
+ */
+export declare function resolveNamedType(type: string, templatePath: string, imports: readonly string[], resolver: DeclarationResolver): string | undefined;
+/**
+ * Resolves a manual spec into an EnumeratedComponent, reading `propsFrom` when set.
+ *
+ * @param specification - The manual component's specification
+ * @param kitRoot - The kit root `propsFrom` resolves against
+ * @param templates - The kit's template components, which a
+ *   `ComponentProps<typeof X>` in the props type can name
+ * @returns The component, with its props read from `propsFrom` or given inline
+ */
+export declare function resolveManualComponent(specification: ManualComponentSpecification, kitRoot: string, templates?: readonly EnumeratedComponent[]): EnumeratedComponent;
+export {};