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

package/src/emit/react.ts

@@ -0,0 +1,263 @@
+// 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,
+  type DefaultSlot,
+} 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';
+import type {
+  JsonValue,
+  PartFill,
+  SlotFill,
+  ResolvedStory,
+  Target,
+} from '../lib/types.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: string): string {
+  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: Record<string, JsonValue> | undefined,
+  slots: Record<string, SlotFill> | undefined,
+  html: boolean
+): string {
+  const parts: string[] = [];
+  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: Extract<SlotFill, { kind: 'element' }>): string {
+  const inner = fill.children ? slotJsx(fill.children) : '';
+  return `<${fill.component}${jsxAttributes(fill.props, fill.slots, false)}>${inner}</${fill.component}>`;
+}
+
+function htmlJsx(fill: Extract<SlotFill, { kind: 'html' }>): string {
+  // 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: PartFill): string {
+  return `<${fill.name}${jsxAttributes(fill.props, undefined, false)} />`;
+}
+
+function slotJsx(fill: SlotFill): string {
+  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: Extract<SlotFill, { kind: 'scoped' }>): string {
+  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: SlotFill): string {
+  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: DefaultSlot): string {
+  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: ResolvedStory,
+  declares: (component: string, name: string) => boolean
+): string {
+  const given = effectiveDefaultSlot(model);
+  const def: DefaultSlot =
+    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: Map<string, Set<string>>,
+  mod: string,
+  name: string
+): void {
+  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: ResolvedStory[],
+  moduleFor: (name: string, target: Target) => string,
+  exportFor: (name: string) => string = (name) => name,
+  declaredAttributes: (component: string) => readonly string[] = () => []
+): string {
+  const declares = (component: string, name: string): boolean =>
+    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<string, Set<string>>();
+  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: string): string =>
+    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/src/emit/scratch.ts

@@ -0,0 +1,175 @@
+// 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';
+import type {
+  JsonValue,
+  SlotPlan,
+  StoryAround,
+  ResolvedStory,
+  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[]>;
+}
+
+// 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: string): {
+  moduleFor: (name: string, target: Target) => string;
+  exportFor: (name: string) => string;
+  targets: Target[];
+  declaredAttributes: (name: string) => string[];
+} {
+  const data = JSON.parse(
+    readFileSync(resolve(generatedRoot, 'modules.json'), 'utf8')
+  ) as ScratchModules;
+  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';
+
+/** 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;
+}
+
+function buildScratchModel(payload: ScratchPayload): ResolvedStory {
+  const slotComponents = new Set<string>();
+  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: string): string {
+  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: string): void {
+  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: ScratchPayload,
+  generatedRoot: string
+): string[] {
+  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: [string, string][] = [
+    [
+      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);
+}