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

package/application/preview/react/main.tsx

@@ -0,0 +1,146 @@
+// React preview entry. Mounts the generated render-registry by id, holds props in
+// state, and updates reactively from the host over postMessage - the same App
+// instance re-renders, so the Zag driver machine stays alive across prop changes.
+import { Component, useEffect, useState, type ReactNode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { declaredAttributes, reactAttributeNames, registry } from '@preview-generated/react/registry';
+// The scenario editor's regenerated scratch story, merged under its reserved id.
+// Its module is a placeholder registry until the editor's first edit.
+import * as scratch from '@preview-generated/scratch/react';
+// The kit's per-target setup module (side effects only): ambient providers a
+// story needs mounted once (a toast container), another package's stylesheets, and any
+// other integration the kit's react stories assume. Aliased to the kit's
+// `preview.setupModules.react` (or an empty module).
+import '@preview-setup/react';
+import { applyGlobals } from '../globals';
+import {
+  announcePreviewReady,
+  announcePreviewShown,
+  announcePreviewStories,
+  announceStoryMounted,
+  PREVIEW_MESSAGE,
+  PREVIEW_MOUNT_ELEMENT_ID,
+  readPreviewMessage,
+  reportContentSize,
+  reportRenderError,
+  withEventRecorders,
+  withWriteBacks,
+  PendingWriteBacks,
+  type PreviewWriteBack,
+} from '../../../src/protocol';
+import { reactProps } from '../../../src/lib/react-spelling';
+
+// What a story threw as a message; it need not have thrown an Error.
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// Isolate a throwing component so it can't poison the persistent root (which
+// would blank every later story). Reset per story via a `key` on the boundary;
+// the host hears of the error, and of each story mounted since.
+class ErrorBoundary extends Component<{ children: ReactNode }, { message: string | null }> {
+  state = { message: null as string | null };
+  static getDerivedStateFromError(error: unknown) {
+    return { message: errorMessage(error) };
+  }
+  componentDidCatch(error: unknown) {
+    reportRenderError(errorMessage(error));
+  }
+  render() {
+    if (this.state.message !== null) return <pre>render error: {this.state.message}</pre>;
+    return this.props.children;
+  }
+}
+
+// The values this pane has written back itself and the host has not yet
+// answered: props the host sent before it took the newest keep that value.
+const pending = new PendingWriteBacks();
+
+function Application() {
+  const [id, setId] = useState('');
+  const [props, setProps] = useState<Record<string, unknown>>({});
+  // The story's events, recorded with each set of props it gets.
+  const [events, setEvents] = useState<string[]>([]);
+  // The story's two-way props, each written back as its event reports a value.
+  const [bindings, setBindings] = useState<PreviewWriteBack[]>([]);
+  // Each story or scenario the host sets mounts fresh, so uncontrolled state
+  // never carries over from the last one; live prop edits update in place.
+  const [mount, setMount] = useState(0);
+  // The host's mount of the story, which each recorded event carries.
+  const [hostMount, setHostMount] = useState<number | undefined>(undefined);
+
+  useEffect(() => {
+    function onMessage(event: MessageEvent) {
+      const message = readPreviewMessage(event.data);
+      if (!message) return;
+      if (message.type === PREVIEW_MESSAGE.setStory) {
+        reportRenderError();
+        pending.clear();
+        setId(message.id);
+        setProps(message.props ?? {});
+        setEvents(message.events ?? []);
+        setBindings(message.bindings ?? []);
+        setHostMount(message.mount);
+        setMount((count) => count + 1);
+      } else if (message.type === PREVIEW_MESSAGE.props) {
+        setProps(pending.reconcile(message.props, message.answers));
+      } else if (message.type === PREVIEW_MESSAGE.globals) {
+        applyGlobals(message.options);
+      }
+    }
+    window.addEventListener('message', onMessage);
+    announcePreviewStories(Object.keys({ ...registry, ...scratch.registry }));
+    announcePreviewReady();
+    return () => window.removeEventListener('message', onMessage);
+  }, []);
+
+  // The first story the host sets, once painted, lets the host show the pane.
+  // The story's own effects have run by now, so a test can read the mount.
+  useEffect(() => {
+    if (mount === 0) return;
+    announcePreviewShown();
+    announceStoryMounted(id);
+  }, [mount]);
+
+  const render = { ...registry, ...scratch.registry }[id];
+  if (!render) return null;
+  // A story spells the attributes it gives the component as HTML does:
+  // React takes `class` as `className`, a `style` string as an object and
+  // the attributes it renames by their React names, unless the component
+  // declares a prop by that name.
+  const declared = { ...declaredAttributes, ...scratch.declaredAttributes }[id] ?? [];
+  // A controlled story takes a two-way prop's new value here, in the event
+  // that reports it, before React restores a controlled input to its prop's
+  // value: typing mid-text keeps the caret where it is. The host's
+  // write-back follows with the same value. Each write is numbered, the
+  // event reporting it carries the number, and props the host sent before
+  // it took the newest keep the pane's own value (`pending`).
+  const story = withWriteBacks(withEventRecorders(props, events, window, hostMount, pending), bindings, (prop, value) => {
+    pending.wrote(prop, value);
+    setProps((current) => (current[prop] === undefined ? current : { ...current, [prop]: value }));
+  });
+  const spelled = reactProps(story, (name) => declared.includes(name), reactAttributeNames ?? {});
+  return <ErrorBoundary key={`${id}:${mount}`}>{render(spelled)}</ErrorBoundary>;
+}
+
+// Cache the root across HMR: when the editor's scratch registry hot-updates,
+// Fast Refresh re-runs this module - reuse the existing root (and re-render Application so
+// it picks up the new scratch registry) instead of calling createRoot twice.
+const container = document.getElementById(PREVIEW_MOUNT_ELEMENT_ID)!;
+const store = window as unknown as {
+  __previewRoot?: ReturnType<typeof createRoot>;
+};
+const root = store.__previewRoot ?? (store.__previewRoot = createRoot(container));
+root.render(<Application />);
+// The story's size reaches the host on each change, so a shell can size the pane to it.
+reportContentSize(container);
+
+// The editor regenerates .preview-generated/scratch/react.tsx on each edit. Self-accept
+// that dep (a no-op) so Vite scopes the change to *this* iframe instead of
+// broadcasting a full-reload to every client on the shared dev server - which
+// would wipe the host's editor state. The actual refresh is host-driven: after a
+// regeneration it bumps this iframe's src, reloading it to pick up the new (invalidated)
+// scratch module - deterministic, unlike relying on Vite's HMR event delivery.
+if (import.meta.hot) {
+  import.meta.hot.accept('@preview-generated/scratch/react', () => {});
+}

package/application/preview/react/preview.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>preview - react</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/application/preview/svelte/Preview.svelte

@@ -0,0 +1,104 @@
+<script lang="ts">
+  // Runes-mode host for the Svelte preview. The generated wrappers (registry
+  // values) are runes components. The wrapper gets one object for the
+  // story's props that never changes, each of whose props is a signal of its
+  // own: an update sets the props that changed alone - a prop update on the
+  // same instance, not a remount, keeping the Zag driver machine alive - and
+  // a prop the story leaves out is never set, so a component keeps its own
+  // two-way value while another prop changes.
+  // Each story or scenario the host sets mounts fresh (`mount`), so
+  // uncontrolled state never carries over from the last one. An error the
+  // story throws shows in its place, as the React page's error boundary
+  // shows one, rather than an empty pane, and the host hears of it, and of
+  // each story mounted since.
+  import { flushSync } from 'svelte';
+  import { registry } from '@preview-generated/svelte/registry';
+  // The scenario editor's regenerated scratch story, merged under its reserved id.
+  import { registry as scratchRegistry } from '@preview-generated/scratch/registry';
+  import { applyGlobals } from '../globals';
+  import { paneProps, storyProps, type GivenProps } from './story-props';
+  import {
+    announcePreviewReady,
+    announcePreviewShown,
+    announcePreviewStories,
+    announceStoryMounted,
+    PREVIEW_MESSAGE,
+    readPreviewMessage,
+    reportRenderError,
+  } from '../../../src/protocol';
+
+  const all = { ...registry, ...scratchRegistry };
+
+  let id = $state('');
+  let mount = $state(0);
+
+  // The story's props, each a signal of its own (see story-props.ts).
+  const given = $state<GivenProps>({});
+  const props = storyProps(given);
+  // The story's events recorded and its two-way props written back as they
+  // report a value, props the host sent before it took the newest keeping
+  // the pane's own value (see story-props.ts).
+  const story = paneProps(given);
+
+  // Apply what is pending now, so what follows sees the story mounted or
+  // gone. An error the flush lets through (one a story throws as it unmounts,
+  // past the boundary) is the host's to hear of, not the pane's to stop on.
+  function flush(): void {
+    try {
+      flushSync();
+    } catch (error) {
+      console.error(error);
+      reportRenderError(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  $effect(() => {
+    function onMessage(event: MessageEvent) {
+      const message = readPreviewMessage(event.data);
+      if (!message) return;
+      if (message.type === PREVIEW_MESSAGE.setStory) {
+        reportRenderError();
+        // The story mounted comes down before its props change: set first,
+        // the next story's props would reach the one still mounted as it
+        // unmounts, and a story that reads a prop it needs then, as one
+        // stopping a headless machine does, would read it gone and throw.
+        id = '';
+        flush();
+        story.setStory(message.props ?? {}, message);
+        id = message.id;
+        mount += 1;
+        // Mounted, its effects run: the host may show the pane, and a test
+        // may read the mount. Reported here rather than from an effect of
+        // this component, which an error let through would stop for good.
+        flush();
+        announcePreviewShown();
+        announceStoryMounted(message.id);
+      } else if (message.type === PREVIEW_MESSAGE.props) {
+        story.setProps(message.props, message.answers);
+      } else if (message.type === PREVIEW_MESSAGE.globals) {
+        applyGlobals(message.options);
+      }
+    }
+    window.addEventListener('message', onMessage);
+    announcePreviewStories(Object.keys(all));
+    announcePreviewReady();
+    return () => window.removeEventListener('message', onMessage);
+  });
+</script>
+
+{#if id && all[id]}
+  {@const Comp = all[id]}
+  {#key mount}
+    <svelte:boundary
+      onerror={(error) => {
+        console.error(error);
+        reportRenderError(error instanceof Error ? error.message : String(error));
+      }}
+    >
+      <Comp {props} />
+      {#snippet failed(error)}
+        <pre>render error: {error instanceof Error ? error.message : String(error)}</pre>
+      {/snippet}
+    </svelte:boundary>
+  {/key}
+{/if}

package/application/preview/svelte/main.ts

@@ -0,0 +1,13 @@
+// Svelte preview entry. The postMessage wiring + reactive props live in
+// Preview.svelte (runes); this just mounts it. The theme stylesheet is loaded
+// by globals.ts (imported via Preview.svelte).
+// The kit's per-target setup module (side effects only) - see react/main.tsx.
+import '@preview-setup/svelte';
+import { mount } from 'svelte';
+import Preview from './Preview.svelte';
+import { PREVIEW_MOUNT_ELEMENT_ID, reportContentSize } from '../../../src/protocol';
+
+const target = document.getElementById(PREVIEW_MOUNT_ELEMENT_ID)!;
+mount(Preview, { target });
+// The story's size reaches the host on each change, so a shell can size the pane to it.
+reportContentSize(target);

package/application/preview/svelte/preview.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>preview - svelte</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

package/application/preview/svelte/story-props.ts

@@ -0,0 +1,172 @@
+// The Svelte pane's story props: one object for the component's props that
+// never changes, each of whose props reads a signal of its own. An update
+// sets the props whose values changed alone, and a prop the story leaves out
+// is never set, as a parent leaves it. Were the whole object replaced, every
+// prop would read as set again, and a component's own two-way value (a
+// bindable the story leaves out) would go back to its default whenever
+// another prop changed: Svelte keeps a prop the component assigns only until
+// the prop is read anew. An array or object the story gives again with the
+// same content, as each message from the host does, is the same value: the
+// host compares values the same way.
+
+import { stableStringify } from '../../../src/controller/editor-tree';
+import {
+  isPlainData,
+  PendingWriteBacks,
+  withEventRecorders,
+  withWriteBacks,
+  type PreviewWriteBack,
+} from '../../../src/protocol';
+
+/** A prop's value in a box, so it stays the value it is: a `$state` record
+ *  wraps an array or plain object in a proxy of its own, a class instance not. */
+export class GivenProp {
+  constructor(readonly value: unknown) {}
+}
+
+/** The props a story gives, by name, each in a box: a `$state` record, so
+ *  each prop is a signal of its own. */
+export type GivenProps = Record<string, GivenProp>;
+
+/**
+ * The component's props, read from `given`: an object that never changes,
+ * whose each prop reads its own box, so a read of one prop depends on that
+ * prop alone.
+ *
+ * @param given - The story's props, a `$state` record of boxes.
+ * @returns The props to spread on the component.
+ * @example
+ * ```ts
+ * const given = $state<GivenProps>({});
+ * const props = storyProps(given);
+ * ```
+ */
+export function storyProps(given: GivenProps): Record<string, unknown> {
+  return new Proxy(
+    {},
+    {
+      get: (_, key) =>
+        typeof key === 'string' ? given[key]?.value : undefined,
+      has: (_, key) => typeof key === 'string' && key in given,
+      ownKeys: () => Reflect.ownKeys(given),
+      getOwnPropertyDescriptor: (_, key) =>
+        typeof key === 'string' && key in given
+          ? {
+              value: given[key].value,
+              enumerable: true,
+              configurable: true,
+              writable: true,
+            }
+          : undefined,
+    }
+  );
+}
+
+/**
+ * Whether a prop's value is the one it had: the same value, or arrays or
+ * plain objects of plain data holding the same content.
+ *
+ * @param previous - The value it had.
+ * @param next - The value it is given.
+ * @returns `true` when nothing changed.
+ */
+export function sameValue(previous: unknown, next: unknown): boolean {
+  if (Object.is(previous, next)) return true;
+  return (
+    typeof previous === 'object' &&
+    previous !== null &&
+    typeof next === 'object' &&
+    next !== null &&
+    isPlainData(previous) &&
+    isPlainData(next) &&
+    stableStringify(previous) === stableStringify(next)
+  );
+}
+
+/**
+ * Set the story's props to `next`: a prop whose value changed gets a new box,
+ * one `next` leaves out is deleted, and the others stay as they are. An array
+ * or object with the content it had stays as it is (see {@link sameValue}).
+ *
+ * @param given - The story's props, a `$state` record of boxes.
+ * @param next - The props the story gives now.
+ */
+export function setStoryProps(
+  given: GivenProps,
+  next: Record<string, unknown>
+): void {
+  for (const key of Object.keys(given)) if (!(key in next)) delete given[key];
+  for (const [key, value] of Object.entries(next))
+    if (!(key in given) || !sameValue(given[key].value, value))
+      given[key] = new GivenProp(value);
+}
+
+/** What a story the host sets brings beside its props. */
+export interface StorySettings {
+  /** The function props whose calls the pane records. */
+  events?: readonly string[];
+  /** The two-way props and the events they report through. */
+  bindings?: readonly PreviewWriteBack[];
+  /** The host's mount of the story, which each recorded event carries. */
+  mount?: number;
+}
+
+/**
+ * The Svelte pane's story props as the host's messages set them. A story's
+ * events are recorded, and a controlled story takes a two-way prop's new
+ * value in the event that reports it, as the React and Vue panes do: the
+ * story's prop holds the value the component has taken by the time the
+ * host echoes it, and props the host sent before it took the pane's newest
+ * write keep that value (`answers`, see {@link PendingWriteBacks}). A new
+ * story forgets the last one's writes.
+ *
+ * @param given - The story's props, a `$state` record of boxes.
+ * @param target - The pane's window, which events are reported from.
+ * @returns `setStory` for a story the host sets, `setProps` for its props.
+ * @example
+ * ```ts
+ * const story = paneProps(given);
+ * story.setStory({ value: 'a' }, { bindings: [{ prop: 'value', changeProp: 'onValueChange' }] });
+ * story.setProps({ value: 'ab' }, 1);
+ * ```
+ */
+export function paneProps(
+  given: GivenProps,
+  target: Window = window
+): {
+  setStory: (props: Record<string, unknown>, settings?: StorySettings) => void;
+  setProps: (props: Record<string, unknown>, answers?: number) => void;
+} {
+  let settings: StorySettings = {};
+  const pending = new PendingWriteBacks();
+  function apply(next: Record<string, unknown>): void {
+    setStoryProps(
+      given,
+      withWriteBacks(
+        withEventRecorders(
+          next,
+          settings.events,
+          target,
+          settings.mount,
+          pending
+        ),
+        settings.bindings,
+        (prop, value) => {
+          pending.wrote(prop, value);
+          if (prop in given && !sameValue(given[prop].value, value))
+            given[prop] = new GivenProp(value);
+        }
+      )
+    );
+  }
+  return {
+    setStory(props, next = {}) {
+      settings = next;
+      pending.clear();
+      apply(props);
+    },
+    setProps(props, answers) {
+      apply(pending.reconcile(props, answers));
+    },
+  };
+}

package/application/preview/view/main.ts

@@ -0,0 +1,124 @@
+// Generic custom-view iframe entry. The host points this iframe at a registered
+// view by `?view=<id>` and drives its globals over the same postMessage handshake
+// the component previews use. The entry loads the kit's setup module for the
+// view's framework (named by `?framework=`, so its stylesheets come first, as
+// in the framework iframes), then the theme and canvas, then the kit's views;
+// it mounts the view under the live theme and options (so a tokens view paints
+// from the kit's real custom properties, with its theme stylesheet in scope).
+// The view stays mounted and hears of each new context - the options the host
+// applies, and the catalog once the handshake delivers it - through the
+// `updates` it mounts with. No view is named here - the kit's views module is
+// the only place a view is registered, so a new view needs no change to this
+// entry or the host.
+import type {
+  RenderedView,
+  ViewContext,
+  ViewFramework,
+} from '../../../src/views';
+import { options as previewOptions } from '@preview-configuration';
+import { optionDefaults } from '../../../src/options';
+import {
+  announcePreviewReady,
+  announcePreviewShown,
+  PREVIEW_MESSAGE,
+  PREVIEW_MOUNT_ELEMENT_ID,
+  readPreviewMessage,
+  reportContentSize,
+  selectMessage,
+  VIEW_FRAMEWORK_PARAMETER,
+  VIEW_PARAMETER,
+} from '../../../src/protocol';
+
+const parameters = new URLSearchParams(window.location.search);
+const viewId = parameters.get(VIEW_PARAMETER) ?? '';
+
+type SetupFramework = Exclude<ViewFramework, 'dom'>;
+
+// Each framework's setup module, loaded only for a view of that framework.
+const SETUP_MODULES: Record<SetupFramework, () => Promise<unknown>> = {
+  react: () => import('@preview-setup/react'),
+  vue: () => import('@preview-setup/vue'),
+  svelte: () => import('@preview-setup/svelte'),
+};
+const loadedSetups = new Set<ViewFramework>(['dom']);
+
+async function loadSetup(framework: ViewFramework): Promise<void> {
+  if (loadedSetups.has(framework)) return;
+  loadedSetups.add(framework);
+  await SETUP_MODULES[framework as SetupFramework]();
+}
+
+function isSetupFramework(value: string | null): value is SetupFramework {
+  return value !== null && Object.hasOwn(SETUP_MODULES, value);
+}
+
+// The view-side half of the select back-channel: ViewContext exposes this as
+// `selectComponent`, and this iframe relays it to the host as `preview:select` -
+// a view never learns the postMessage vocabulary.
+function selectComponent(id: string, props?: Record<string, unknown>) {
+  window.parent?.postMessage(selectMessage(id, props), '*');
+}
+
+let context: ViewContext = {
+  options: optionDefaults(previewOptions),
+  kitName: '',
+  sources: [],
+  components: [],
+  selectComponent,
+};
+const listeners = new Set<(context: ViewContext) => void>();
+
+function update(changes: Partial<ViewContext>): void {
+  context = { ...context, ...changes };
+  for (const listener of listeners) listener(context);
+}
+
+async function start(): Promise<void> {
+  const named = parameters.get(VIEW_FRAMEWORK_PARAMETER);
+  if (isSetupFramework(named)) await loadSetup(named);
+  const { applyGlobals } = await import('../globals');
+  const { viewById } = await import('@preview-views');
+  const entry = viewById(viewId);
+  // A component-tree entry is navigation only (no mount); only a rendered view mounts here.
+  const view: RenderedView | undefined =
+    entry && !entry.componentTree ? entry : undefined;
+  // A page loaded without `?framework=` still gets the view's setup module.
+  await loadSetup(view?.framework ?? 'dom');
+  const element = document.getElementById(PREVIEW_MOUNT_ELEMENT_ID);
+  if (view && element) {
+    view.mount(element, context, {
+      subscribe(listener) {
+        listeners.add(listener);
+        return () => {
+          listeners.delete(listener);
+        };
+      },
+    });
+  }
+
+  window.addEventListener('message', (event: MessageEvent) => {
+    const message = readPreviewMessage(event.data);
+    if (!message) return;
+    if (message.type === PREVIEW_MESSAGE.globals) {
+      applyGlobals(message.options);
+      update({ options: message.options ?? {} });
+    }
+    if (message.type === PREVIEW_MESSAGE.catalog) {
+      update({
+        kitName: message.kitName ?? '',
+        sources: message.sources ?? [],
+        components: message.components ?? [],
+      });
+      // The view with its catalog, once painted, lets the host show the pane.
+      announcePreviewShown();
+    }
+  });
+  // Signal readiness so the host replays the current globals (an iframe
+  // re-handshakes after each reload), and set the ready flag a test that
+  // loads this page on its own waits on.
+  announcePreviewReady();
+  // The view's size reaches the host on each change, so a shell can size the pane to it.
+  if (element) reportContentSize(element);
+}
+
+void start();

package/application/preview/view/view.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>preview - view</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>