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

package/dist/emit/react.js

@@ -0,0 +1,210 @@
+// Emit the React render-registry: a map of component id → a render function
+// `(props) => <Component {...props}>...slots...</Component>`. React maps the default
+// slot to JSX children and named slots to props (e.g. a popover's `trigger`).
+// A story spells a component's attributes as HTML does in every target; the
+// fills here are spelled as React takes them (lib/react-spelling.ts), and the
+// registry exports what the React pane spells a story's live props with.
+import { effectiveDefaultSlot, namedSlots, serialize, } from './common.js';
+import { storyRegistryId } from '../lib/scenario-story.js';
+import { REACT_ATTRIBUTE_NAMES } from '@js-template-engine/extension-react';
+import { reactFill, styleProperties } from '../lib/react-spelling.js';
+import { singleJsxRoot } from '../lib/jsx-roots.js';
+import { collectParts } from '../lib/slot-fill.js';
+import { isVoidElement } from '../lib/void-elements.js';
+// A story file `style` string ('padding: 0 1ch;') → the React style object literal
+// source. Story files author plain CSS text (the natural cross-target form - Vue and
+// Svelte take it verbatim); only React needs the object mapping.
+function styleObjectSource(css) {
+    const entries = Object.entries(styleProperties(css)).map(([name, value]) => `${name.startsWith('--') ? JSON.stringify(name) : name}: ${JSON.stringify(value)}`);
+    return `{ ${entries.join(', ')} }`;
+}
+// A JSX attribute list from `props` (named slots become slot-as-prop attributes,
+// like reactEntry's top-level `namedProps`). For HTML tags, `class` maps to the
+// JSX `className` spelling and a `style` string becomes the object mapping React
+// requires.
+function jsxAttributes(props, slots, html) {
+    const parts = [];
+    for (const [propName, value] of Object.entries(props ?? {})) {
+        const key = html && propName === 'class' ? 'className' : propName;
+        if (html && propName === 'style' && typeof value === 'string') {
+            parts.push(`style={${styleObjectSource(value)}}`);
+            continue;
+        }
+        parts.push(typeof value === 'boolean' && value ? key : `${key}={${serialize(value)}}`);
+    }
+    for (const [slot, fill] of Object.entries(slots ?? {}))
+        parts.push(`${slot}={${slotExpression(fill)}}`);
+    return parts.length ? ' ' + parts.join(' ') : '';
+}
+function elementJsx(fill) {
+    const inner = fill.children ? slotJsx(fill.children) : '';
+    return `<${fill.component}${jsxAttributes(fill.props, fill.slots, false)}>${inner}</${fill.component}>`;
+}
+function htmlJsx(fill) {
+    // A void element (img, input, br) takes no children and no closing tag.
+    if (isVoidElement(fill.tag))
+        return `<${fill.tag}${jsxAttributes(fill.props, undefined, true)} />`;
+    const inner = fill.children ? slotJsx(fill.children) : '';
+    return `<${fill.tag}${jsxAttributes(fill.props, undefined, true)}>${inner}</${fill.tag}>`;
+}
+// A call to a part: the function component the story's entry declares.
+function partJsx(fill) {
+    return `<${fill.name}${jsxAttributes(fill.props, undefined, false)} />`;
+}
+function slotJsx(fill) {
+    if (fill.kind === 'text')
+        return `{${JSON.stringify(fill.value)}}`;
+    if (fill.kind === 'raw')
+        return fill.react;
+    if (fill.kind === 'part')
+        return partJsx(fill);
+    // A scoped fill is only valid at a top-level named slot (reactEntry); ignored nested.
+    if (fill.kind === 'scoped')
+        return '';
+    if (fill.kind === 'fragment')
+        return fill.children.map(slotJsx).join('');
+    if (fill.kind === 'html')
+        return htmlJsx(fill);
+    return elementJsx(fill);
+}
+// A scoped fill's React arrow head. Vue and Svelte always destructure `parameters` off
+// one scope object; React takes either shape, so the fill says which. The default
+// is the single scope object a generated component's scoped slot supplies - a
+// render prop there is always called with one object, so the same `parameters` list is
+// correct in all three emitters. `positional` keeps the separate-parameters form
+// for a hand-written driver prop whose React side really is positional.
+function reactArrowHead(fill) {
+    return fill.reactScope === 'positional'
+        ? `(${fill.parameters.join(', ')})`
+        : `({ ${fill.parameters.join(', ')} })`;
+}
+// A slot fill in *prop* position (a named slot mapped to a React prop, e.g.
+// `description={...}`). Unlike slotJsx (children position), the value must be a bare
+// JSX *expression* - so text is a plain string literal (not `{"..."}`, which would
+// double-brace) and a multi-child fragment is wrapped in `<>...</>` so it stays a
+// single expression.
+function slotExpression(fill) {
+    if (fill.kind === 'text')
+        return JSON.stringify(fill.value);
+    // A raw body of sibling roots, or of text, is one expression in a fragment.
+    if (fill.kind === 'raw')
+        return singleJsxRoot(fill.react);
+    if (fill.kind === 'part')
+        return partJsx(fill);
+    // A scoped fill becomes a render-prop arrow (handled in reactEntry, not here).
+    if (fill.kind === 'scoped')
+        return `${reactArrowHead(fill)} => (${singleJsxRoot(fill.react)})`;
+    if (fill.kind === 'fragment')
+        return `<>${fill.children.map(slotJsx).join('')}</>`;
+    if (fill.kind === 'html')
+        return htmlJsx(fill);
+    return elementJsx(fill);
+}
+function defaultJsx(def) {
+    if (!def)
+        return '';
+    if (def.kind === 'propText')
+        return `{props.${def.prop}}`;
+    // Scoped content for the default slot is the function child.
+    if (def.kind === 'scoped')
+        return def.react ? `{${slotExpression(def)}}` : '';
+    return slotJsx(def);
+}
+function reactEntry(model, declares) {
+    const given = effectiveDefaultSlot(model);
+    const def = given?.kind === 'propText'
+        ? given
+        : reactFill(given, declares, REACT_ATTRIBUTE_NAMES);
+    const named = Object.fromEntries(Object.entries(namedSlots(model)).map(([slot, fill]) => [
+        slot,
+        reactFill(fill, declares, REACT_ATTRIBUTE_NAMES),
+    ]));
+    const namedProps = Object.entries(named)
+        .map(([slot, fill]) => {
+        // A scoped fill maps to a render-prop named per target (`fill.slot.react`), not
+        // the map key; an empty target body omits the prop.
+        if (fill.kind === 'scoped')
+            return fill.react
+                ? ` ${fill.slot.react}={${slotExpression(fill)}}`
+                : '';
+        return ` ${slot}={${slotExpression(fill)}}`;
+    })
+        .join('');
+    const children = defaultJsx(def);
+    // The content beside the component: its siblings, in a fragment with it.
+    const before = reactFill(model.around?.before, declares, REACT_ATTRIBUTE_NAMES);
+    const after = reactFill(model.around?.after, declares, REACT_ATTRIBUTE_NAMES);
+    const beside = before !== undefined || after !== undefined;
+    const open = `${beside ? `<>${before ? slotJsx(before) : ''}` : ''}<${model.name} {...props}${namedProps}>`;
+    const close = `</${model.name}>${beside ? `${after ? slotJsx(after) : ''}</>` : ''}`;
+    const body = children ? `\n      ${children}\n    ` : '';
+    const key = JSON.stringify(storyRegistryId(model));
+    const parts = collectParts([
+        before,
+        model.slots?.default,
+        ...Object.values(named),
+        after,
+    ]);
+    if (parts.size === 0)
+        return `  ${key}: (props) => (\n    ${open}${body}${close}\n  ),`;
+    // The story's parts are function components declared in its entry, so two
+    // stories can each declare a part of one name.
+    const declarations = [...parts.values()]
+        .map((part) => `    function ${part.name}({ ${part.parameters.join(', ')} }: Record<string, any>) {\n` +
+        `      return ${part.react ? `(${singleJsxRoot(part.react)})` : 'null'};\n` +
+        `    }\n`)
+        .join('');
+    return (`  ${key}: (() => {\n${declarations}` +
+        `    return (props: Record<string, any>) => (\n      ${open}${children ? `\n        ${children}\n      ` : ''}${close}\n    );\n` +
+        `  })(),`);
+}
+// Group a component into its source's module bucket (insertion-ordered, so the core
+// source's import line comes first and other sources' lines append after it).
+function addImport(byModule, mod, name) {
+    let set = byModule.get(mod);
+    if (!set)
+        byModule.set(mod, (set = new Set()));
+    set.add(name);
+}
+/**
+ * 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 function emitReactRegistry(models, moduleFor, exportFor = (name) => name, declaredAttributes = () => []) {
+    const declares = (component, name) => declaredAttributes(component).includes(name);
+    const rootDeclarations = Object.fromEntries(models
+        .map((model) => [storyRegistryId(model), declaredAttributes(model.name)])
+        .filter(([, names]) => names.length > 0));
+    const byModule = new Map();
+    for (const model of models) {
+        addImport(byModule, moduleFor(model.name, 'react'), model.name);
+        for (const slotComponent of model.slotComponents)
+            addImport(byModule, moduleFor(slotComponent, 'react'), slotComponent);
+    }
+    // A component whose module export differs from its preview name is aliased on import
+    // (`Toast as NoticeToast`) so another package's clean export can't clash with a core name.
+    const importSpecifier = (name) => exportFor(name) === name ? name : `${exportFor(name)} as ${name}`;
+    const importLines = [...byModule.entries()]
+        .map(([mod, names]) => `import { ${[...names].map(importSpecifier).join(', ')} } from '${mod}';`)
+        .join('\n');
+    return (`// Generated by scaffold-ui-kit-preview - do not edit.\n` +
+        `${importLines}\n\n` +
+        `type RenderFn = (props: Record<string, any>) => any;\n\n` +
+        `export const registry: Record<string, RenderFn> = {\n` +
+        models.map((model) => reactEntry(model, declares)).join('\n') +
+        `\n};\n\n` +
+        `// How React spells the attributes it renames, by their HTML names.\n` +
+        `export const reactAttributeNames: Record<string, string> = ${JSON.stringify(REACT_ATTRIBUTE_NAMES)};\n\n` +
+        `// The names each story's root declares that React would otherwise respell.\n` +
+        `export const declaredAttributes: Record<string, string[]> = ${JSON.stringify(rootDeclarations)};\n`);
+}

package/dist/emit/scratch.d.ts

@@ -0,0 +1,40 @@
+import type { JsonValue, SlotPlan, StoryAround, Target } from '../lib/types.js';
+/** The module-resolution data the generator serializes beside the registries
+ *  (`<generatedRoot>/modules.json`), so this dev-middleware module needs no kit
+ *  imports: the default module for unregistered slot children, each manual
+ *  component's source module, per-target overrides, and export aliases. */
+export interface ScratchModules {
+    defaultModule: string;
+    moduleByName: Record<string, string>;
+    importOverrideByName: Record<string, Partial<Record<Target, string>>>;
+    exportByName: Record<string, string>;
+    /** The scripted targets the kit builds; a scratch registry for any other stays
+     *  empty. All three when absent. */
+    targets?: Target[];
+    /** The names each component declares that React would otherwise respell
+     *  (`class`, `style`, an attribute React renames), which it takes as they
+     *  are. A component missing here declares none. */
+    declaredAttributes?: Record<string, string[]>;
+}
+/** Reserved story id the editor renders under, in every target registry. */
+export declare const SCRATCH_ID = "scratch";
+/** The host posts this shape on every structural edit. */
+export interface ScratchPayload {
+    /** The root component name (e.g. `Button`), imported per the modules.json mapping. */
+    rootComponent: string;
+    /** The root component's own scalar props (also delivered live via the props channel). */
+    props: Record<string, JsonValue>;
+    /** The editable tree: the root's default-slot fill (and any named slots). */
+    slots?: SlotPlan;
+    /** The content beside the root, carried unchanged from the story. */
+    around?: StoryAround;
+}
+/** Placeholder registries so the previews' static scratch imports resolve before
+ *  the first edit. Written at `preview:generate` time. */
+export declare function writeScratchStubs(generatedRoot: string): void;
+/** Regenerate the scratch registries from an editor payload (one synthetic story
+ *  through the real emitters). Returns the absolute paths written, so the caller
+ *  can invalidate them in Vite's module graph before the previews reload (a plain
+ *  reload can otherwise serve Vite's stale transform if the file-change event
+ *  hasn't been processed yet). */
+export declare function writeScratch(payload: ScratchPayload, generatedRoot: string): string[];

package/dist/emit/scratch.js

@@ -0,0 +1,116 @@
+// The scenario editor's regeneration target. The host's editable node tree is, in effect,
+// a one-entry story: a root component with `props` and a slot plan. We build a
+// synthetic `ResolvedStory` from the editor payload and run it through the *existing*
+// emitters verbatim - no new per-framework codegen - writing a `scratch/` sibling
+// of the generated registries. The preview's normal .preview-generated → Vite-HMR path
+// then reloads the previews.
+//
+// Loaded by the Vite dev middleware via `ssrLoadModule` (so it runs in Node with
+// fs + the TS emitters compiled on the fly). `writeScratchStubs` is also called at
+// `preview:generate` time so the previews' static scratch imports always resolve.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { emitReactRegistry } from './react.js';
+import { emitVueRegistry } from './vue.js';
+import { emitSvelteRegistry, emitSvelteWrapper } from './svelte.js';
+import { collectSlotComponents } from '../lib/slot-fill.js';
+import { moduleOfSource } from '../lib/module-of-source.js';
+import { ALL_TARGETS } from '../lib/types.js';
+// A component's per-target import module for the scratch registry, mirroring
+// generate.ts: a per-component `importModule` override (a playground fixture
+// outside its source's barrel) wins; otherwise the component's source module,
+// defaulting to the kit's own source. Read from the generator's modules.json.
+function loadResolvers(generatedRoot) {
+    const data = JSON.parse(readFileSync(resolve(generatedRoot, 'modules.json'), 'utf8'));
+    return {
+        targets: data.targets ?? ALL_TARGETS,
+        moduleFor: (name, target) => data.importOverrideByName[name]?.[target] ??
+            moduleOfSource(data.moduleByName[name] ?? data.defaultModule, target),
+        exportFor: (name) => data.exportByName[name] ?? name,
+        declaredAttributes: (name) => data.declaredAttributes?.[name] ?? [],
+    };
+}
+/** Reserved story id the editor renders under, in every target registry. */
+export const SCRATCH_ID = 'scratch';
+function buildScratchModel(payload) {
+    const slotComponents = new Set();
+    collectSlotComponents(payload.slots?.default, slotComponents);
+    for (const fill of Object.values(payload.slots?.named ?? {})) {
+        collectSlotComponents(fill, slotComponents);
+    }
+    collectSlotComponents(payload.around?.before, slotComponents);
+    collectSlotComponents(payload.around?.after, slotComponents);
+    slotComponents.delete(payload.rootComponent);
+    return {
+        name: payload.rootComponent,
+        title: SCRATCH_ID,
+        omit: false,
+        standalone: true,
+        unlisted: false,
+        propTypes: [],
+        defaultProps: payload.props ?? {},
+        slots: payload.slots,
+        ...(payload.around ? { around: payload.around } : {}),
+        scenarios: [],
+        slotComponents: [...slotComponents],
+        // The scratch story is rendered, never introspected for add-targets.
+        contentSlots: { default: false, named: [] },
+        // Unused by the scratch emitters (they emit the single model unconditionally), but
+        // the model shape requires it; the editor composes across all targets.
+        targets: ALL_TARGETS,
+    };
+}
+const EMPTY_REGISTRY = 'export const registry: Record<string, any> = {};\n';
+// The React page reads the names each story's root declares beside its
+// registry, so React's placeholder exports them too, none.
+const EMPTY_REACT_REGISTRY = EMPTY_REGISTRY +
+    'export const declaredAttributes: Record<string, string[]> = {};\n';
+function scratchDirectory(generatedRoot) {
+    const directory = resolve(generatedRoot, 'scratch');
+    mkdirSync(directory, { recursive: true });
+    return directory;
+}
+/** Placeholder registries so the previews' static scratch imports resolve before
+ *  the first edit. Written at `preview:generate` time. */
+export function writeScratchStubs(generatedRoot) {
+    const directory = scratchDirectory(generatedRoot);
+    writeFileSync(resolve(directory, 'react.tsx'), EMPTY_REACT_REGISTRY);
+    writeFileSync(resolve(directory, 'vue.ts'), EMPTY_REGISTRY);
+    writeFileSync(resolve(directory, 'registry.ts'), EMPTY_REGISTRY);
+}
+/** Regenerate the scratch registries from an editor payload (one synthetic story
+ *  through the real emitters). Returns the absolute paths written, so the caller
+ *  can invalidate them in Vite's module graph before the previews reload (a plain
+ *  reload can otherwise serve Vite's stale transform if the file-change event
+ *  hasn't been processed yet). */
+export function writeScratch(payload, generatedRoot) {
+    const model = buildScratchModel(payload);
+    const directory = scratchDirectory(generatedRoot);
+    const { moduleFor, exportFor, targets, declaredAttributes } = loadResolvers(generatedRoot);
+    // A target the kit does not build keeps its empty registry: its
+    // components have no module to import.
+    const files = [
+        [
+            resolve(directory, 'react.tsx'),
+            targets.includes('react')
+                ? emitReactRegistry([model], moduleFor, exportFor, declaredAttributes)
+                : EMPTY_REACT_REGISTRY,
+        ],
+        [
+            resolve(directory, 'vue.ts'),
+            targets.includes('vue')
+                ? emitVueRegistry([model], moduleFor, exportFor)
+                : EMPTY_REGISTRY,
+        ],
+    ];
+    if (targets.includes('svelte')) {
+        const wrapper = emitSvelteWrapper(model, moduleFor, exportFor);
+        files.push([resolve(directory, 'registry.ts'), emitSvelteRegistry([model])], [resolve(directory, wrapper.fileName), wrapper.source]);
+    }
+    else {
+        files.push([resolve(directory, 'registry.ts'), EMPTY_REGISTRY]);
+    }
+    for (const [path, source] of files)
+        writeFileSync(path, source);
+    return files.map(([path]) => path);
+}

package/dist/emit/source.d.ts

@@ -0,0 +1,87 @@
+import type { JsonValue, SlotFill, StoryAround, Target } from '../lib/types.js';
+/**
+ * A two-way prop the story gives, which the printed source binds to state of
+ * its own so the component's changes come back: React holds it in `useState`
+ * and passes the setter as `changeProp`, Vue binds it with `v-model` (bare
+ * with `vueModel`) or `v-model:<prop>`, and Svelte with `bind:<prop>`.
+ */
+export interface SourceBinding {
+    /** The two-way prop. */
+    prop: string;
+    /** The event prop called with each new value. Without one, React prints
+     *  the prop's value alone, as it has no way to hear a change. */
+    changeProp?: string;
+    /** The prop the component's own value starts from when the two-way prop
+     *  is not given, which the source leaves out while it gives the prop. */
+    defaultProp?: string;
+    /** Whether a Vue consumer binds the prop with a bare `v-model`. */
+    vueModel?: boolean;
+    /** The prop's type as the component declares it, which types the state
+     *  where the value alone would read narrower. */
+    declaredType?: string;
+    /** Whether the component takes type parameters, so its prop's type is
+     *  the consumer's to infer rather than to name. */
+    generic?: boolean;
+}
+/** A story resolved for printing: its root component, props and slot content. */
+export interface SourceStory {
+    /** The root component's local name (its export name). */
+    component: string;
+    /** The props to print, already merged and filtered. */
+    props: Record<string, JsonValue>;
+    /** Default-slot content. */
+    children?: SlotFill;
+    /** Named-slot content, keyed by slot name. */
+    named: Record<string, SlotFill>;
+    /** The content beside the component, printed as its siblings: React holds
+     *  them in a fragment, Vue's template and Svelte's markup list them. */
+    around?: StoryAround;
+    /** Import lines' modules per local component name, and the names the
+     *  component declares that React would otherwise respell
+     *  (`declaredAttributes`: `class`, `style`, an attribute React renames),
+     *  which React takes as they are. */
+    imports: Map<string, {
+        module: string;
+        exported: string;
+        declaredAttributes?: string[];
+    }>;
+    /** The root component's two-way props, those given in `props` bound to
+     *  state of the source's own. */
+    bindings?: SourceBinding[];
+    /** The mode the kit builds its Svelte target in, which the state a bound
+     *  prop is held in follows: `$state` in runes mode, a plain `let` in
+     *  legacy mode (the default). */
+    svelteMode?: 'legacy' | 'runes';
+    /** How React spells the HTML attributes it renames (`tabindex` as
+     *  `tabIndex`), by their HTML names. A story spells a component's
+     *  attributes as HTML does; React's source takes `class` as `className`,
+     *  a `style` string as a style object and these by their React names,
+     *  unless the component declares a prop by that name. Without it, only
+     *  `class` and `style` are respelled. */
+    reactAttributeNames?: Readonly<Record<string, string>>;
+    /** The type names the kit's package entries export, each with the module
+     *  it is imported from for this target: a bound prop's state is typed by
+     *  its declared type where it names these and the language's own types
+     *  alone, importing them. */
+    exportedTypes?: ReadonlyMap<string, string>;
+}
+/** The story as a React component module, the attributes it gives a
+ *  component spelled as React takes them (see `reactAttributeNames`). */
+export declare function reactSource(given: SourceStory): string;
+/** The story as a Vue single-file component. */
+export declare function vueSource(given: SourceStory): string;
+/** The story as a Svelte component. */
+export declare function svelteSource(given: SourceStory): string;
+/**
+ * A story's props in the order the component declares them, so the source
+ * prints them alike however they were gathered (the template's defaults, the
+ * story file's, a scenario's); a prop the component does not declare follows,
+ * in the order given.
+ *
+ * @param props - The props to print.
+ * @param declared - The component's prop names, in declaration order.
+ * @returns The same props, reordered.
+ */
+export declare function inDeclarationOrder(props: Record<string, JsonValue>, declared: readonly string[]): Record<string, JsonValue>;
+/** The printer per target. */
+export declare const SOURCE_PRINTERS: Record<Target, (story: SourceStory) => string>;