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

package/dist/emit/html-source.js

@@ -0,0 +1,322 @@
+// The html "source" of a story: not a source a consumer writes, but the markup
+// the story renders to - the template rendered once, at build time, for the
+// story's props and slot content. A kit's docs show it beside the React, Vue
+// and Svelte snippets. It is markup only: no behavior, no comments, and it
+// assumes the kit's stylesheet. A story with a part that has no markup form
+// has no html source.
+import { renderInstance, } from '@js-template-engine/core';
+import { bem } from '@js-template-engine/extension-bem';
+import { tailwind } from '@js-template-engine/extension-tailwind';
+import { componentNameFromFile } from '../lib/naming.js';
+import { styleDeclarations } from '../lib/react-spelling.js';
+import { collectParts, collectSlotComponents } from '../lib/slot-fill.js';
+/**
+ * Renders a story to markup. A component written by hand renders as the kit
+ * maps it - the content passed into it, at rest, or the template it names -
+ * inside one comment saying its behavior is not included; a slot fill
+ * written per framework (`raw`, `scoped`) renders its `html`. A part renders
+ * as a component whose template is its `html`, calling itself as deep as
+ * the data it is given goes. A component without a template that the kit
+ * does not map, or such a fill or part without `html`, leaves the story
+ * with no markup, and the result names them. What the render cannot work
+ * out at rest, such as an expression reading the component's script state,
+ * is left out of the markup and named in the result's warnings.
+ */
+export function htmlSource(story) {
+    const templates = new Map();
+    // The kit component each template key (a name or an export name) is.
+    const componentOf = new Map();
+    const fills = { markups: [], missing: [] };
+    // The story's parts, as components of its own; a part's name wins over a
+    // kit component's.
+    const parts = new Map();
+    const besideFills = [story.around?.before, story.around?.after];
+    for (const part of collectParts([
+        story.children,
+        ...Object.values(story.named),
+        ...besideFills,
+    ]).values()) {
+        if (part.html === undefined) {
+            fills.missing.push(`the part ${part.name}, with no html`);
+            continue;
+        }
+        parts.set(part.name, {
+            type: 'component',
+            name: part.name,
+            props: Object.fromEntries(part.parameters.map((name) => [name, { type: 'unknown' }])),
+            children: part.html,
+        });
+    }
+    for (const entry of story.components) {
+        const template = namedTemplate(entry);
+        if (template === undefined)
+            continue;
+        templates.set(entry.name, template);
+        componentOf.set(entry.name, entry.name);
+        if (entry.exportName !== undefined) {
+            templates.set(entry.exportName, template);
+            componentOf.set(entry.exportName, entry.name);
+        }
+    }
+    const rendered = new Set();
+    if (story.component.template !== undefined)
+        rendered.add(story.component.name);
+    // A hand-written component's own props, read from its specification.
+    const ownProps = new Map();
+    for (const entry of story.components) {
+        if (entry.template !== undefined)
+            continue;
+        ownProps.set(entry.name, entry.props);
+        if (entry.exportName !== undefined)
+            ownProps.set(entry.exportName, entry.props);
+    }
+    const slots = {};
+    for (const [name, fill] of Object.entries(story.named))
+        slots[name] = slotContent(fill, fills);
+    const children = story.children === undefined
+        ? undefined
+        : slotContent(story.children, fills);
+    // A component with no template renders as a reference to itself, which the
+    // resolver answers from the kit's map or leaves unresolved.
+    const template = namedTemplate(story.component) ?? [
+        {
+            type: 'element',
+            tag: story.component.exportName ?? story.component.name,
+            attributes: attributesOf(story.props),
+            ...(children === undefined
+                ? {}
+                : {
+                    children: children.content,
+                    ...(children.slotScope === undefined
+                        ? {}
+                        : { slotScope: children.slotScope }),
+                }),
+            ...(Object.keys(slots).length === 0 ? {} : { slots }),
+        },
+    ];
+    const resolveComponent = (tag) => {
+        const part = parts.get(tag);
+        if (part !== undefined)
+            return part;
+        const template = templates.get(tag);
+        if (template !== undefined) {
+            rendered.add(componentOf.get(tag) ?? tag);
+            return template;
+        }
+        const mapping = handWrittenMapping(story.handWrittenComponents[tag]);
+        if (mapping === undefined)
+            return undefined;
+        if (mapping.template === 'content')
+            return { rendersAs: 'content' };
+        const target = templates.get(mapping.template);
+        if (target !== undefined)
+            rendered.add(componentOf.get(mapping.template) ?? mapping.template);
+        return target === undefined
+            ? undefined
+            : {
+                rendersAs: target,
+                props: Object.keys(ownProps.get(tag) ?? {}),
+                ...(mapping.slots === undefined ? {} : { slots: mapping.slots }),
+            };
+    };
+    const shared = {
+        componentName: story.component.name,
+        resolveComponent,
+        scope: story.scope,
+        extensions: stylingExtensions(story.styling),
+        placement: story.styling.placement,
+    };
+    const own = renderInstance(template, {
+        ...shared,
+        props: story.props,
+        children,
+        slots,
+    });
+    // The content beside the component renders on its own, as its siblings.
+    const beside = besideFills.map((fill) => fill === undefined
+        ? undefined
+        : renderInstance(fillNodes(fill, fills), shared));
+    const renders = [beside[0], own, beside[1]].filter((result) => result !== undefined);
+    const markup = renders.map((result) => result.markup).join('\n');
+    const unresolved = [
+        ...new Set(renders.flatMap((result) => result.unresolved)),
+    ];
+    const warnings = renders.flatMap((result) => result.warnings);
+    const missing = [
+        ...unresolved.map((name) => story.handWrittenComponents[name] === undefined
+            ? `${name}, a component with no template that handWrittenComponents does not map`
+            : `${name}, mapped to ${handWrittenMapping(story.handWrittenComponents[name])?.template}, which is no template of the kit`),
+        ...fills.missing,
+    ];
+    if (missing.length > 0)
+        return { missing };
+    // Each fill's markup went in as a placeholder text node; it takes its place.
+    const filled = markup.replace(/\uE000(\d+)\uE001/g, (_, index) => fills.markups[Number(index)]);
+    // A fill written per framework names the kit components its markup holds.
+    const referenced = new Set();
+    for (const fill of [
+        story.children,
+        ...Object.values(story.named),
+        ...besideFills,
+    ])
+        collectSlotComponents(fill, referenced);
+    for (const name of referenced) {
+        const component = componentOf.get(name);
+        if (component !== undefined)
+            rendered.add(component);
+    }
+    return {
+        markup: `${filled}\n`,
+        components: [...rendered],
+        // Only the expressions left out: a styling extension's notices belong
+        // to the kit's build.
+        warnings: [
+            ...new Set(warnings
+                .filter((warning) => warning.kind === 'unevaluated')
+                .map((warning) => warning.message)),
+        ],
+    };
+}
+/**
+ * A component's template under the name the kit's build gives it. A bare
+ * node array takes its file-derived name, as the build does, so its
+ * `data-jte-node` markers match the kit's stylesheet whichever tag or
+ * hand-written component reaches it.
+ */
+function namedTemplate(entry) {
+    const template = entry.template;
+    if (template === undefined || !Array.isArray(template))
+        return template;
+    return {
+        type: 'component',
+        name: componentNameFromFile(entry.file),
+        children: template,
+    };
+}
+/** A hand-written component's entry in the kit's map, in its object form. */
+function handWrittenMapping(entry) {
+    return typeof entry === 'string' ? { template: entry } : entry;
+}
+/**
+ * A top-level fill as slot content. A scoped fill whose html is template
+ * nodes reads the values the slot exposes under its parameter names.
+ */
+function slotContent(fill, fills) {
+    const content = fillNodes(fill, fills);
+    return fill.kind === 'scoped' && Array.isArray(fill.html)
+        ? { content, slotScope: fill.parameters }
+        : { content };
+}
+function stylingExtensions(styling) {
+    return styling.extensions.map((name) => name === 'bem' ? bem(styling.bem) : tailwind(styling.tailwind));
+}
+/**
+ * A slot fill as template nodes. A fill written per framework becomes a
+ * placeholder for its html, which is markup and so cannot be a node.
+ */
+function fillNodes(fill, fills) {
+    switch (fill.kind) {
+        case 'text':
+            return [{ type: 'text', content: fill.value }];
+        case 'fragment':
+            return fill.children.flatMap((child) => fillNodes(child, fills));
+        case 'html':
+            return [
+                {
+                    type: 'element',
+                    tag: fill.tag,
+                    attributes: attributesOf(fill.props ?? {}),
+                    ...(fill.children === undefined
+                        ? {}
+                        : { children: fillNodes(fill.children, fills) }),
+                },
+            ];
+        case 'element': {
+            const slots = {};
+            for (const [name, slotFill] of Object.entries(fill.slots ?? {}))
+                slots[name] = fillNodes(slotFill, fills);
+            return [
+                {
+                    type: 'element',
+                    tag: fill.component,
+                    attributes: attributesOf(fill.props ?? {}),
+                    ...(fill.children === undefined
+                        ? {}
+                        : { children: fillNodes(fill.children, fills) }),
+                    ...(Object.keys(slots).length === 0 ? {} : { slots }),
+                },
+            ];
+        }
+        case 'part':
+            // The part renders as the component the story declares it as; one
+            // with no html is already named as missing.
+            if (fill.html === undefined)
+                return [];
+            return [
+                {
+                    type: 'element',
+                    tag: fill.name,
+                    attributes: attributesOf(fill.props ?? {}),
+                },
+            ];
+        case 'raw':
+        case 'scoped': {
+            // Template nodes render like any other content, composed components
+            // included.
+            if (Array.isArray(fill.html))
+                return fill.html;
+            if (fill.html === undefined) {
+                fills.missing.push(fill.kind === 'raw'
+                    ? 'a raw slot fill with no html'
+                    : `a scoped slot fill (${fill.parameters.join(', ')}) with no html`);
+            }
+            // A fill with no html still holds its place, so its slot is not empty;
+            // the story then has no markup at all.
+            fills.markups.push(typeof fill.html === 'string' ? fill.html : '');
+            return [
+                {
+                    type: 'text',
+                    content: `\uE000${fills.markups.length - 1}\uE001`,
+                },
+            ];
+        }
+    }
+}
+/**
+ * Props as template attributes. A value an attribute cannot hold - an
+ * object, an array - is passed as an expression, so it still reaches a
+ * resolved component as its prop. A `style`, given as CSS text or an object,
+ * is a whole-object style expression, so it is written inline.
+ */
+function attributesOf(props) {
+    const attributes = {};
+    for (const [name, value] of Object.entries(props)) {
+        if (value === undefined || value === null)
+            continue;
+        if (name === 'style') {
+            const style = typeof value === 'string' ? styleObject(value) : value;
+            attributes.style = { $expression: JSON.stringify(style) };
+            continue;
+        }
+        attributes[name] =
+            typeof value === 'object'
+                ? { $expression: JSON.stringify(value) }
+                : value;
+    }
+    return attributes;
+}
+/** CSS declarations - `padding-left: 2ch; color: red` - as a style object,
+ *  a `;` inside quotes or parentheses (`url("data:...;base64,...")`) kept. */
+function styleObject(css) {
+    const style = {};
+    for (const declaration of styleDeclarations(css)) {
+        const colon = declaration.indexOf(':');
+        if (colon === -1)
+            continue;
+        const property = declaration.slice(0, colon).trim();
+        const value = declaration.slice(colon + 1).trim();
+        if (property !== '' && value !== '')
+            style[property] = value;
+    }
+    return style;
+}

package/dist/emit/manifest.d.ts

@@ -0,0 +1,138 @@
+import type { ContentSlots, JsonValue, PreviewLabels, PreviewLandingConfiguration, PreviewPaneWidth, PreviewPersistence, SlotPlan, StoryAround, PreviewBinding, ResolvedStory, PreviewPropType, Target } from '../lib/types.js';
+import type { PreviewTarget } from '../protocol.js';
+import type { ViewFramework } from '../views.js';
+export interface ManifestComponent {
+    id: string;
+    name: string;
+    title: string;
+    /** What the component is, from its template. Absent when it has none. */
+    description?: string;
+    category: string;
+    /** Each prop's control and its declaration (type as written, whether it is
+     *  required, the component's own default). */
+    propTypes: PreviewPropType[];
+    /** The props that are events: functions returning nothing, which the
+     *  component calls as things happen. Absent when there are none. */
+    events?: string[];
+    /** The component's two-way props. Absent when there are none. */
+    bindings?: PreviewBinding[];
+    defaultProps: Record<string, JsonValue>;
+    /** The values in `defaultProps` the preview starts from on its own (a kit
+     *  hint's), which a consumer's source leaves out. Absent when there are none. */
+    previewDefaults?: Record<string, JsonValue>;
+    scenarios: {
+        id: string;
+        label: string;
+        /** What the scenario shows, from the story file. Absent when it has none. */
+        description?: string;
+        props: Record<string, JsonValue>;
+        /** The option values picking the scenario sets. Absent when it sets none. */
+        options?: Record<string, string | boolean>;
+        default?: boolean;
+        generated?: boolean;
+        /** The slot content the scenario shows, when it has content of its own:
+         *  its fills over the story's. Absent when it shows the story's. */
+        content?: SlotPlan;
+        /** The id the panes mount the scenario's story by, when it has content
+         *  of its own. Absent when the panes mount the component's story. */
+        story?: string;
+    }[];
+    /** The slots this component accepts - the editor's add-content targets. */
+    slots: ContentSlots;
+    /** `false` for a component with no story of its own: present for the
+     *  editor's picker, hidden from the story navigation (see
+     *  Story.standalone). Absent ⇒ a normal browseable story. */
+    standalone?: boolean;
+    /** A story reachable at its address but left out of the navigation, the
+     *  editor's picker and the counts (see Story.unlisted). Absent ⇒ listed. */
+    unlisted?: boolean;
+    /** The story file's curated slot content, so the per-story editor seeds its tree
+     *  from what the browse view already renders. Absent
+     *  when the component has no story file slot plan. */
+    content?: SlotPlan;
+    /** The content the story renders beside the component (see Story.around).
+     *  Absent when it has none. */
+    around?: StoryAround;
+    /** Per-story preview-option defaults / availability (see Story.options). Absent
+     *  when the component curates none. */
+    options?: Record<string, JsonValue | false>;
+    /** The preview source this component belongs to (`ManifestSource.id`). The host groups
+     *  the navigation by source; core components are `'core'`. */
+    source: string;
+    /** The targets this component renders into, within the kit's own. The host shows
+     *  a pane + toggle per kit target and disables the rest; a React-only fixture of
+     *  another package's components lists just `react`. */
+    targets: Target[];
+}
+/** A navigation source - the kit's own components or another package's. The host renders one
+ *  collapsible section per source, in `order`, its `label` the heading. */
+export interface ManifestSource {
+    id: string;
+    label: string;
+    order: number;
+    /** The package the source's components import from, per target
+     *  `<moduleBase>/<target>`, or `<moduleBase>` with `{target}` replaced by
+     *  the target when it names one. */
+    moduleBase?: string;
+}
+/** How a consumer imports one of the kit's components. */
+export interface ManifestImport {
+    /** The name the component is exported under. */
+    exportName: string;
+    /** The names it declares that React would otherwise respell (`class`,
+     *  `style`, an attribute React renames, such as `tabindex`), which React
+     *  takes as they are; any other attribute a story gives it is spelled as
+     *  React takes it. Absent when it declares none. */
+    declaredAttributes?: string[];
+    /** The module it is imported from, per target the kit builds. */
+    modules: Partial<Record<Target, string>>;
+    /** The type names its module exports, per target the kit builds, which
+     *  the module a consumer imports it from exports too. Absent where it
+     *  exports none. */
+    types?: Partial<Record<Target, string[]>>;
+}
+export interface Manifest {
+    /** The kit's name (the kit configuration's `name`) - the host's kit selector. */
+    kitName: string;
+    /** The kit's version (its package.json `version`) - the host's version label. */
+    kitVersion?: string;
+    colorOptions: (string | null)[];
+    /** What the kit builds that the host offers a pane for, and for these
+     *  alone: its targets, and `html` when it builds html. */
+    targets: PreviewTarget[];
+    /** The sources, for the navigation's per-source sections (ordered by the host). */
+    sources: ManifestSource[];
+    /** The kit's own code block, when it names one: the framework it mounts
+     *  with. A shell mounts it in place of its own code view. */
+    codeBlock?: {
+        framework: ViewFramework;
+    };
+    components: ManifestComponent[];
+    /** How a consumer imports each of the kit's components, by name: every
+     *  component, those with no story of their own included, so a story's
+     *  source can import what its slot content names. */
+    imports?: Record<string, ManifestImport>;
+    /** The host's own copy (the synthetic empty scenario's label), in the kit's casing. */
+    labels: {
+        emptyScenario: string;
+    };
+    /** Where the host remembers what a person chose (`preview.persistence`).
+     *  Absent means `'url'`. */
+    persistence?: PreviewPersistence;
+    /** The widths a shell offers to lay the story panes out at
+     *  (the configuration module's `previewPaneWidths`). Absent means the preview's own. */
+    paneWidths?: PreviewPaneWidth[];
+    /** The mode the kit builds its Svelte target in (`svelte.mode`), which a
+     *  story's Svelte source follows. Absent means `legacy`. */
+    svelteMode?: 'legacy' | 'runes';
+    /** The entry the host opens on when its address names none
+     *  (`preview.landing`). Absent means the first listed story. */
+    landing?: PreviewLandingConfiguration;
+    /** How React spells the HTML attributes it renames (`tabindex` as
+     *  `tabIndex`), by their HTML names, which a story's React source spells
+     *  a component's attributes with. */
+    reactAttributeNames?: Record<string, string>;
+}
+export declare function buildManifest(models: ResolvedStory[], sources: ManifestSource[], colorTokens?: (string | null | undefined)[], kitName?: string, labels?: PreviewLabels, kitVersion?: string, persistence?: PreviewPersistence, targets?: PreviewTarget[], imports?: Record<string, ManifestImport>, codeBlock?: {
+    framework: ViewFramework;
+}, paneWidths?: PreviewPaneWidth[], svelteMode?: 'legacy' | 'runes', reactAttributeNames?: Readonly<Record<string, string>>, landing?: PreviewLandingConfiguration): Manifest;

package/dist/emit/manifest.js

@@ -0,0 +1,74 @@
+// Emit the framework-neutral host manifest (manifest.json): the nav list, the
+// per-component controls (propTypes/defaultProps/scenarios), and the shared color
+// token list for color-select controls. Custom views own their data outside
+// this manifest, so it privileges no single view.
+import { sanitize, scenarioStoryId } from '../lib/naming.js';
+import { scenarioSlotPlan } from '../lib/scenario-story.js';
+import { ALL_TARGETS } from '../lib/types.js';
+function manifestComponent(model) {
+    return {
+        id: sanitize(model.title),
+        name: model.name,
+        title: model.title,
+        ...(model.description !== undefined
+            ? { description: model.description }
+            : {}),
+        category: model.title.split('/').slice(0, -1).join('/'),
+        propTypes: model.propTypes,
+        ...(model.events?.length ? { events: model.events } : {}),
+        ...(model.bindings?.length ? { bindings: model.bindings } : {}),
+        defaultProps: model.defaultProps,
+        ...(model.previewDefaults
+            ? { previewDefaults: model.previewDefaults }
+            : {}),
+        scenarios: model.scenarios.map((scenario) => ({
+            id: scenario.id,
+            label: scenario.label ?? scenario.id,
+            ...(scenario.description !== undefined
+                ? { description: scenario.description }
+                : {}),
+            props: scenario.props ?? {},
+            ...(scenario.options !== undefined &&
+                Object.keys(scenario.options).length > 0
+                ? { options: scenario.options }
+                : {}),
+            ...(scenario.default ? { default: true } : {}),
+            ...(scenario.generated ? { generated: true } : {}),
+            ...(scenario.slots === undefined
+                ? {}
+                : {
+                    content: scenarioSlotPlan(model.slots, scenario.slots) ?? {},
+                    story: scenarioStoryId(sanitize(model.title), scenario.id),
+                }),
+        })),
+        slots: model.contentSlots,
+        source: model.source ?? 'core',
+        targets: model.targets,
+        ...(model.slots ? { content: model.slots } : {}),
+        ...(model.around ? { around: model.around } : {}),
+        ...(model.standalone ? {} : { standalone: false }),
+        ...(model.unlisted ? { unlisted: true } : {}),
+        ...(model.options ? { options: model.options } : {}),
+    };
+}
+export function buildManifest(models, sources, colorTokens = [], kitName = 'kit', labels = {}, kitVersion, persistence = 'url', targets = ALL_TARGETS, imports, codeBlock, paneWidths, svelteMode, reactAttributeNames, landing) {
+    return {
+        kitName,
+        ...(kitVersion ? { kitVersion } : {}),
+        targets,
+        // JSON has no `undefined`; the unset color option serializes to null.
+        colorOptions: colorTokens.map((colorToken) => colorToken ?? null),
+        sources,
+        components: models.map(manifestComponent),
+        ...(imports ? { imports } : {}),
+        ...(codeBlock ? { codeBlock } : {}),
+        labels: { emptyScenario: labels.emptyScenario ?? 'Empty' },
+        persistence,
+        ...(paneWidths ? { paneWidths } : {}),
+        ...(svelteMode ? { svelteMode } : {}),
+        ...(reactAttributeNames
+            ? { reactAttributeNames: { ...reactAttributeNames } }
+            : {}),
+        ...(landing ? { landing: { ...landing } } : {}),
+    };
+}

package/dist/emit/react.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedStory, Target } from '../lib/types.js';
+/**
+ * The React render-registry module: each story's id → its render function.
+ *
+ * @param models - The stories React renders.
+ * @param moduleFor - The module a component is imported from, per target.
+ * @param exportFor - The name a component is exported under.
+ * @param declaredAttributes - The names a component declares that React
+ *   would otherwise respell (`class`, `style`, an attribute React renames),
+ *   which it takes as they are; every other attribute a story gives a
+ *   component is spelled as React takes it.
+ * @returns The registry module's source: the `registry`, and the
+ *   `reactAttributeNames` and `declaredAttributes` (of each story's root, by
+ *   id) the React pane spells a story's live props with.
+ */
+export declare function emitReactRegistry(models: ResolvedStory[], moduleFor: (name: string, target: Target) => string, exportFor?: (name: string) => string, declaredAttributes?: (component: string) => readonly string[]): string;