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

package/application/preview/vue/main.ts

@@ -0,0 +1,145 @@
+// Vue preview entry. Mounts a generated render unit (components + template) with
+// a single reactive `props` object that is mutated in place on each update, so
+// v-bind="props" re-renders the same component instance - the Zag driver machine
+// stays alive across prop changes. Remounts each time the host sets a story or scenario.
+import { createApp, h, reactive, shallowRef, type App } from 'vue';
+import { registry } from '@preview-generated/vue/registry';
+// The scenario editor's regenerated scratch story, merged under its reserved id.
+import { registry as scratchRegistry } from '@preview-generated/scratch/vue';
+// The kit's per-target setup module (side effects only) - see react/main.tsx.
+import '@preview-setup/vue';
+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';
+
+let props = reactive<Record<string, unknown>>({});
+let application: App | null = null;
+// The story's events, recorded with each set of props it gets.
+let events: string[] = [];
+// The story's two-way props, each written back as its event reports a value.
+let bindings: PreviewWriteBack[] = [];
+// The host's mount of the story, which each recorded event carries.
+let mount: number | undefined;
+// 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();
+
+// A controlled story takes a two-way prop's new value here, in the event
+// that reports it, before the component puts a controlled input back to its
+// prop's value at Vue's next tick: the prop holds the new value by then, so
+// 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`).
+function setProps(given: Record<string, unknown>) {
+  const next = withWriteBacks(withEventRecorders(given, events, window, mount, pending), bindings, (prop, value) => {
+    pending.wrote(prop, value);
+    if (props[prop] !== undefined) props[prop] = value;
+  });
+  for (const key of Object.keys(props)) if (!(key in next)) delete props[key];
+  Object.assign(props, next);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// 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.
+function setStory(id: string, nextProps?: Record<string, unknown>) {
+  // Each mount reads props of its own: an application that failed to mount
+  // cannot be unmounted, and would re-render on what it subscribed to.
+  props = reactive({});
+  setProps(nextProps ?? {});
+  reportRenderError();
+  // No longer current before it unmounts, so nothing it throws from here on
+  // counts against the story mounted next.
+  const previous = application;
+  application = null;
+  if (previous) previous.unmount();
+  // An application that could not mount left only its error message behind.
+  else document.getElementById(PREVIEW_MOUNT_ELEMENT_ID)!.replaceChildren();
+  const unit = { ...registry, ...scratchRegistry }[id];
+  if (!unit) return;
+  // The story's components are values its template's expressions read
+  // (`:as="Button"`), as a script-setup import is in an SFC, as well as tags.
+  const story = {
+    components: unit.components,
+    setup: () => ({ ...unit.components, props }),
+    template: unit.template,
+  };
+  // The root stands apart from the story, so it can still show the error the
+  // story throws as it sets up or renders.
+  // The message of an error the story throws, shown in its place - the way
+  // the React page's error boundary shows one - rather than an empty pane,
+  // and told to the host, as each story mounted since is.
+  const renderError = shallowRef<string | null>(null);
+  const current = createApp({
+    render: () => (renderError.value === null ? h(story) : h('pre', `render error: ${renderError.value}`)),
+  });
+  current.config.errorHandler = (error) => {
+    // A late error from a story since replaced says nothing of this one.
+    if (application !== current) return;
+    console.error(error);
+    renderError.value = errorMessage(error);
+    reportRenderError(renderError.value);
+  };
+  application = current;
+  const container = document.getElementById(PREVIEW_MOUNT_ELEMENT_ID)!;
+  try {
+    current.mount(container);
+  } catch (error) {
+    // A failure the application could not handle itself leaves it unusable.
+    console.error(error);
+    application = null;
+    reportRenderError(errorMessage(error));
+    const message = document.createElement('pre');
+    message.textContent = `render error: ${errorMessage(error)}`;
+    container.replaceChildren(message);
+  }
+}
+
+window.addEventListener('message', (event: MessageEvent) => {
+  const message = readPreviewMessage(event.data);
+  if (!message) return;
+  if (message.type === PREVIEW_MESSAGE.setStory) {
+    events = message.events ?? [];
+    bindings = message.bindings ?? [];
+    mount = message.mount;
+    pending.clear();
+    setStory(message.id, message.props);
+    // The first story, once painted, lets the host show the pane.
+    announcePreviewShown();
+    announceStoryMounted(message.id);
+  }
+  else if (message.type === PREVIEW_MESSAGE.props) setProps(pending.reconcile(message.props, message.answers));
+  else if (message.type === PREVIEW_MESSAGE.globals) applyGlobals(message.options);
+});
+
+announcePreviewStories(Object.keys({ ...registry, ...scratchRegistry }));
+announcePreviewReady();
+// The story's size reaches the host on each change, so a shell can size the pane to it.
+reportContentSize(document.getElementById(PREVIEW_MOUNT_ELEMENT_ID)!);
+
+// The editor regenerates .preview-generated/scratch/vue.ts 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/vue', () => {});
+}

package/application/preview/vue/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 - vue</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

package/application/shells/charcell/components/Application/index.css

@@ -0,0 +1,37 @@
+@layer charcell.components {
+  /* The terminal screen: the shell is letterboxed to whole cells (round() snaps
+     both axes; older browsers fall back to the full viewport). Its ring is a
+     quiet charcell Frame, so the bars aren't edge to edge;
+     the Frame fills the screen as its one grid cell. The screen sits centered
+     in what is left over, by margins rounded down to whole pixels, so every
+     cell still starts on a whole pixel. */
+  .Application {
+    width: 100vw;
+    height: 100vh;
+    width: round(down, 100vw, 1ch);
+    height: round(down, 100vh, var(--charcell-row));
+    margin-left: round(down, calc((100vw - round(down, 100vw, 1ch)) / 2), 1px);
+    margin-top: round(down, calc((100vh - round(down, 100vh, var(--charcell-row))) / 2), 1px);
+    overflow: hidden;
+    display: grid;
+    grid-template: minmax(0, 1fr) / minmax(0, 1fr);
+  }
+  .Application__layout {
+    height: 100%;
+    display: grid;
+    grid-template-rows: auto 1fr auto;
+  }
+  /* The stage, a cell in from the ring at its sides; beside the navigation, the
+     split's handle is the cell at its start. */
+  .Application__main {
+    flex: 1 1 auto;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+    padding: 0 1ch;
+  }
+  .Application__main--beside {
+    padding-left: 0;
+  }
+}

package/application/shells/charcell/components/Application/index.tsx

@@ -0,0 +1,65 @@
+// The shell's interface: the terminal screen, letterboxed to whole cells, and
+// inside its ring the prompt bar (the top bar: the kit, its settings, and the
+// view and target toggles), the navigation beside the stage in a split the
+// reader can drag (NavigationSplit), and the status bar. The navigation is the
+// shell's `navigation` option, toggled from the prompt bar, so the address keeps
+// it; hidden, the stage takes the body's width, and shown again, its groups
+// are open and collapsed as they were left. The stage keeps a cell from
+// the ring at its sides; beside the navigation, the split's handle is the cell at
+// its start. The page's title names what the preview shows and the kit, so
+// each tab and history entry says which it is.
+// Styled in its index.css.
+import { Frame } from 'charcell/react/unlinked';
+import { useEffect, useState } from 'react';
+import { usePreviewController, usePreviewState } from '../../controller-context';
+import { ComponentStage } from '../ComponentStage';
+import { PromptBar } from '../PromptBar';
+import { NAVIGATION_OPTION } from '../../shell-options';
+import { Navigation } from '../Navigation';
+import { NavigationSplit } from '../NavigationSplit';
+import { StatusBar } from '../StatusBar';
+import { ViewStage } from '../ViewStage';
+import './index.css';
+
+export function Application() {
+  const { catalog } = usePreviewController();
+  const selection = usePreviewState((state) => state.selection);
+  const shown =
+    selection.kind === 'view'
+      ? catalog.views.find((view) => view.id === selection.id)?.label
+      : catalog.components.find((component) => component.id === selection.id)?.shortTitle;
+  useEffect(() => {
+    document.title = shown ? `${shown} · ${catalog.kitName} preview` : `${catalog.kitName} preview`;
+  }, [shown, catalog.kitName]);
+  const navigationShown = usePreviewState((state) => state.options[NAVIGATION_OPTION] !== false);
+  // The navigation's collapsed groups, kept here while it is hidden.
+  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(() => new Set());
+  return (
+    <div className="Application">
+      {/* The terminal screen: the outermost ring, faint, so it groups everything
+          without outshining the content it groups. */}
+      <Frame as="div" quiet flush>
+        <div className="Application__layout">
+          <PromptBar />
+          <NavigationSplit
+            shown={navigationShown}
+            navigation={<Navigation collapsed={collapsed} onCollapsedChange={setCollapsed} />}
+            main={
+              <main className={`Application__main${navigationShown ? ' Application__main--beside' : ''}`}>
+                {selection.kind === 'view' ? (
+                  // A custom view renders through the generic view iframe; the
+                  // controller drives only its globals (the ready handshake delivers
+                  // the current options, replayed on reload).
+                  <ViewStage viewId={selection.id} />
+                ) : (
+                  <ComponentStage />
+                )}
+              </main>
+            }
+          />
+          <StatusBar />
+        </div>
+      </Frame>
+    </div>
+  );
+}

package/application/shells/charcell/components/Bar/index.css

@@ -0,0 +1,68 @@
+@layer charcell.components {
+  /* The bands: a content row and a rule row, the stroke centered in
+     its own row and the text on the other. The rule is `faint`, a separator.
+     When the zones do not fit on one row the content wraps onto more, a whole
+     row at a time, so no control is ever cut off; the rule row stays where it
+     was against the content, under it in a header and over it in a status
+     bar. */
+  .Bar {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+  }
+  .Bar--status {
+    color: var(--charcell-mid);
+  }
+  /* An unruled band's empty rule row. */
+  .Bar__space {
+    height: var(--charcell-row);
+  }
+  /* The two zones on one row while they fit: the start packed from the
+     start, the end against the end. Crowded,
+     the zones wrap, the end zone keeping to the end of its row, and a zone
+     that does not fit a row by itself wraps its own items. Items sit a row
+     tall and rows stack with no gap, so every line stays on the cell grid. */
+  .Bar__content {
+    padding: 0 1ch;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    column-gap: 2ch;
+    row-gap: 0;
+    min-width: 0;
+    min-height: var(--charcell-row);
+    white-space: nowrap;
+  }
+  .Bar--flush .Bar__content {
+    padding: 0;
+  }
+  .Bar__start,
+  .Bar__end {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    column-gap: 2ch;
+    row-gap: 0;
+    min-width: 0;
+    min-height: var(--charcell-row);
+  }
+  .Bar__end {
+    margin-left: auto;
+    justify-content: flex-end;
+  }
+  /* A bar's start zone cluster: the lead and a picker sit a cell apart, tighter
+     than the 2ch the band's zones space their items by. */
+  .Bar__cluster {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    column-gap: 1ch;
+    row-gap: 0;
+    min-width: 0;
+  }
+  /* The bold word leading a bar - the prompt, the selected component. charcell's
+     reset flattens <strong>, so the weight is stated here. */
+  .Bar__lead {
+    font-weight: 700;
+  }
+}

package/application/shells/charcell/components/Bar/index.tsx

@@ -0,0 +1,60 @@
+// The preview's bands: the prompt bar, the stage bar and the status bar. Two
+// rows, each with one job, the way a terminal prints them: `header` is a
+// content row over a rule row, `status` a rule row over a content row. The
+// content row has two zones - the children pack from the start, `end` packs
+// against the end. When they do not fit, the content wraps onto further rows, a whole row at a
+// time, so a control is never cut off.
+// `lead` is the bold word that opens the start zone (the prompt), the children beside it a cell apart. The rule row is a charcell
+// Separator across the band's full width; `joined` runs its ends on to meet
+// the lines beside the band (the frame's ring, a divider), as ├ and ┤.
+// `unruled`, the rule row is left empty: a band that sits inside a place with
+// edges of its own (the stage, beside the navigation's line), where a rule across
+// it would cross them. `flush`, the content row takes no cells at its sides,
+// the place around the band holding them.
+// Styled in its index.css.
+import { Separator } from 'charcell/react/unlinked';
+import type { ReactNode } from 'react';
+import './index.css';
+
+export function Bar({
+  variant = 'header',
+  joined,
+  unruled,
+  flush,
+  lead,
+  end,
+  children,
+}: {
+  variant?: 'header' | 'status';
+  joined?: boolean;
+  unruled?: boolean;
+  flush?: boolean;
+  lead?: ReactNode;
+  end?: ReactNode;
+  children?: ReactNode;
+}) {
+  const rule = unruled ? (
+    <div className="Bar__space" />
+  ) : (
+    <Separator decorative join={joined ? 'both' : undefined} />
+  );
+  return (
+    <div className={`Bar Bar--${variant}${flush ? ' Bar--flush' : ''}`}>
+      {variant === 'status' && rule}
+      <div className="Bar__content">
+        <div className="Bar__start">
+          {lead === undefined ? (
+            children
+          ) : (
+            <div className="Bar__cluster">
+              <strong className="Bar__lead">{lead}</strong>
+              {children}
+            </div>
+          )}
+        </div>
+        {end !== undefined && <div className="Bar__end">{end}</div>}
+      </div>
+      {variant === 'header' && rule}
+    </div>
+  );
+}

package/application/shells/charcell/components/CodePane/index.css

@@ -0,0 +1,60 @@
+@layer charcell.components {
+  /* A code pane: a quiet charcell Frame titled with its
+     target, filling its cell of the grid (PreviewGrid), which holds its
+     height in whole rows. Inside, a row saying what the pane holds, with the
+     copy button at its end, over the source. */
+  .CodePane {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+  }
+  .CodePane__content {
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+  }
+  /* In a pane too narrow for both, the actions wrap under the note, a whole
+     row down, rather than cutting the note short. */
+  /* The Frame is flush, so the scrollbars run beside its
+     ring: the row and the source each keep a cell from it. */
+  .CodePane__row {
+    padding: 0 1ch;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    column-gap: 2ch;
+    row-gap: 0;
+    min-height: var(--charcell-row);
+  }
+  .CodePane__note {
+    flex: 1 0 auto;
+    white-space: nowrap;
+    color: var(--charcell-mid);
+  }
+  /* How many warnings the html has, beside the note at its tone, the
+     count opening them (HtmlWarnings). */
+  .CodePane__warnings {
+    white-space: nowrap;
+    color: var(--charcell-mid);
+  }
+  .CodePane__actions {
+    display: flex;
+    align-items: center;
+    gap: 1ch;
+    margin-left: auto;
+  }
+  /* The source: pre-formatted in the shell's one monospace, in the charcell
+     ScrollArea that takes the rows the pane's row leaves, so
+     a long line never widens the stage and a long source never lengthens it.
+     Its lines keep to themselves, scrolling sideways, or wrap at the pane's
+     edge while the shell's wrap option is on. */
+  /* Why a pane has no source, in the box the source would fill. */
+  .CodePane__reason {
+    margin: 0;
+    padding: 0 1ch;
+    color: var(--charcell-mid);
+  }
+}

package/application/shells/charcell/components/CodePane/index.tsx

@@ -0,0 +1,113 @@
+// One code pane, under a target's preview pane in the stage's grid
+// (PreviewGrid): the story's source as a consumer writes it for that
+// target, in a quiet charcell Frame titled with the target. A row says what
+// the pane holds, with a copy button at its end, over the source in a
+// charcell CodeBlock that fills the rest of the pane and scrolls a whole row
+// (and column) at a time. Wrapping is the
+// shell's `wrap` option, toggled for every pane from the code view's heading
+// row (WrapToggle): on, a long line wraps at the pane's edge and the source
+// scrolls only down; off, a long line runs on and the source scrolls across
+// too. A kit that names its own code block (KitCodeBlock) shows the source
+// there instead, the row's note and copy button kept, and the block follows
+// the same option. Without
+// source, the row says so in a word (`printing`, `unavailable`) and the box
+// says why, the copy button disabled. html that leaves out what it cannot
+// evaluate at rest (script-held state) says how many warnings beside the
+// note, the count opening them, one to a line, in a popover
+// (HtmlWarnings), as the html pane's legend does. The
+// code is the controller's (`state.code`), printed as the panes change,
+// so the pane follows a scenario pick, a prop edit and the editor's tree.
+// The scroll area takes keyboard focus and shows it as charcell's do, its
+// scrollbar's thumb climbing to the foreground. The Frame is flush, so the scroll area's bars
+// run beside its ring; the row and the source keep their own cell from it.
+// Styled in its index.css.
+import { useEffect, useState } from 'react';
+import { Button, CodeBlock, Frame, ScrollArea } from 'charcell/react/unlinked';
+import type { PreviewTarget } from '../../../../../src/shell';
+import { usePreviewController, usePreviewState } from '../../controller-context';
+import { KitCodeBlock } from '../KitCodeBlock';
+import { WRAP_OPTION } from '../../shell-options';
+import { HtmlWarnings } from '../HtmlWarnings';
+import './index.css';
+
+/** How long the copy button's confirmation shows, in milliseconds. */
+const COPIED_MILLISECONDS = 1500;
+
+/** What a code pane shows: the source, or, without it, a word and why. */
+interface Shown {
+  text?: string;
+  status?: string;
+  reason?: string;
+  /** What the html leaves out at rest. */
+  warnings?: string[];
+}
+
+export function CodePane({ target }: { target: PreviewTarget }) {
+  const code = usePreviewState((state) => state.code);
+  // A kit's own code block shows the source in its place.
+  const kitBlock = usePreviewController().catalog.codeBlock !== undefined;
+  const wrapped = usePreviewState((state) => state.options[WRAP_OPTION] !== false);
+  const [copied, setCopied] = useState(false);
+  useEffect(() => {
+    if (!copied) return;
+    const timer = setTimeout(() => setCopied(false), COPIED_MILLISECONDS);
+    return () => clearTimeout(timer);
+  }, [copied]);
+  // html is printed apart from the other targets, so it can be on its way or
+  // not to be had; another target's code is always there.
+  const { text, status, reason, warnings }: Shown = !code
+    ? {}
+    : target !== 'html'
+      ? { text: code.targets[target] }
+      : code.html.status === 'ready'
+        ? { text: code.html.source, warnings: code.html.warnings }
+        : code.html.status === 'loading'
+          ? { status: 'printing' }
+          : { status: 'unavailable', reason: code.html.reason };
+  const copy = () => {
+    if (text === undefined) return;
+    navigator.clipboard?.writeText(text).then(
+      () => setCopied(true),
+      () => undefined,
+    );
+  };
+  const lines = text === undefined ? 0 : text.split('\n').length - 1;
+  return (
+    <div className="CodePane" data-preview-code={target}>
+      <Frame title={target} quiet flush fill>
+        <div className="CodePane__content">
+          <div className="CodePane__row">
+            {/* The live region says how the code stands and that it was
+                copied; the line count, which follows every edit, sits
+                beside it, read but not announced. */}
+            <span className="CodePane__note">
+              <span role="status">{text === undefined ? (status ?? '') : copied ? `${target} copied` : ''}</span>
+              {text !== undefined && !copied ? `${lines} ${lines === 1 ? 'line' : 'lines'}` : null}
+            </span>
+            {warnings && warnings.length > 0 ? (
+              <HtmlWarnings warnings={warnings} className="CodePane__warnings" />
+            ) : null}
+            <span className="CodePane__actions">
+              <Button variant="dense" label="copy" disabled={text === undefined} onClick={copy} />
+            </span>
+          </div>
+          {kitBlock ? (
+            <KitCodeBlock target={target} />
+          ) : text !== undefined ? (
+            <CodeBlock
+              label={`${target} code`}
+              code={text}
+              wrap={wrapped}
+              orientation="both"
+              fill
+            />
+          ) : (
+            <ScrollArea label={`${target} code`} overscroll="none" fill>
+              <p className="CodePane__reason">{reason}</p>
+            </ScrollArea>
+          )}
+        </div>
+      </Frame>
+    </div>
+  );
+}

package/application/shells/charcell/components/ComponentStage/index.css

@@ -0,0 +1,26 @@
+@layer charcell.components {
+  /* A component story's stage: its bar, and its body
+     taking the rest of the height - the grid of panes, under the scenario row
+     while it shows, in a stacked charcell Splitter (StageSplit) that
+     fills the body. The body ends on a whole row, as everything above it
+     does, so the split's rows and the grid's do too. */
+  .ComponentStage {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+  }
+  .ComponentStage__body {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+  }
+  /* What the body says while no view shows. */
+  .ComponentStage__note {
+    margin: 0;
+    color: var(--charcell-mid);
+  }
+}