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

package/src/react-view.ts

@@ -0,0 +1,45 @@
+// A custom view written as a React render function, adapted to the
+// framework-neutral view contract (views.ts): it renders into its own React
+// root and re-renders with each new context, so the view's own state lasts
+// across option changes.
+
+import type { ReactNode } from 'react';
+import { createRoot } from 'react-dom/client';
+import type { RenderedView, ViewContext } from './views.js';
+
+/** A React view's render function: the view's element tree for a context. */
+export type ReactViewRender = (context: ViewContext) => ReactNode;
+
+/**
+ * Make a view's `framework` and `mount` from a React render function. The
+ * view iframe then loads the kit's React setup module before mounting it.
+ *
+ * @param render - Renders the view for a context; called again with each new one.
+ * @returns The view's `framework` (`'react'`) and `mount`, to spread into its entry.
+ * @example
+ * ```tsx
+ * export const views: PreviewView[] = [
+ *   {
+ *     id: 'foundations',
+ *     label: 'Foundations',
+ *     ...reactView((context) => <Foundations theme={String(context.options.theme)} />),
+ *   },
+ * ];
+ * ```
+ */
+export function reactView(
+  render: ReactViewRender
+): Required<Pick<RenderedView, 'framework' | 'mount'>> {
+  return {
+    framework: 'react',
+    mount(element, context, updates) {
+      const root = createRoot(element);
+      root.render(render(context));
+      const stop = updates?.subscribe((next) => root.render(render(next)));
+      return () => {
+        stop?.();
+        root.unmount();
+      };
+    },
+  };
+}

package/src/react.ts

@@ -0,0 +1,34 @@
+// React bindings for the preview controller: one hook that reads a slice of
+// its state and re-renders when that slice changes. A shell written in React
+// keeps the controller wherever it likes (a context of its own, a prop) and
+// passes it in; the bindings hold nothing of their own.
+
+import { useSyncExternalStore } from 'react';
+import type { PreviewController, PreviewState } from './controller/index.js';
+
+/**
+ * Read a slice of the controller's state. The component re-renders when the
+ * slice changes by identity, so `selector` returns a field of the state (or
+ * a primitive derived from it) rather than a fresh object or array; derive
+ * those from the slice afterwards.
+ *
+ * @param controller - The controller to read.
+ * @param selector - Picks the slice; the whole state when omitted.
+ * @returns The slice.
+ * @example
+ * ```tsx
+ * const scenario = usePreview(controller, (state) => state.scenario);
+ * const panes = usePreview(controller, (state) => state.targets.panes);
+ * ```
+ */
+export function usePreview<Selected = PreviewState>(
+  controller: PreviewController,
+  selector: (state: PreviewState) => Selected = (state) =>
+    state as unknown as Selected
+): Selected {
+  return useSyncExternalStore(
+    controller.subscribe,
+    () => selector(controller.getState()),
+    () => selector(controller.getState())
+  );
+}

package/src/sass-importers.ts

@@ -0,0 +1,45 @@
+// The Sass importers the preview compiles a kit's SCSS with, in the html
+// pane's stylesheets and in Vite: the kit's own `pkg:` URLs resolve as the
+// kit's build resolves them.
+
+import { createRequire } from 'node:module';
+import type { KitPackageImporter } from 'scaffold-ui-kit';
+
+/**
+ * The Sass importers the preview compiles a kit's SCSS with: one per
+ * package of the kit that resolves its own `pkg:` URLs, as the kit's build
+ * does. Sass's own package importer is left to the copy of Sass that
+ * compiles.
+ *
+ * @param kitRoot - The kit root.
+ * @param packageDirectories - The kit's other packages' directories, absolute,
+ *   for a kit built into one package per target.
+ * @returns The importers, the kit root's first; none for a package whose
+ *   package.json names no package.
+ */
+export function kitImporters(
+  kitRoot: string,
+  packageDirectories: readonly string[] = []
+): KitPackageImporter[] {
+  const { kitPackageImporter } = createRequire(import.meta.url)(
+    'scaffold-ui-kit'
+  ) as typeof import('scaffold-ui-kit');
+  return [kitRoot, ...packageDirectories]
+    .map((directory) => kitPackageImporter(directory))
+    .filter((importer) => importer !== undefined);
+}
+
+/**
+ * The directories of a kit's packages besides the kit root, for
+ * {@link kitImporters}: none for a kit built as one package.
+ *
+ * @param context - The preview context's `kitPackages`.
+ * @returns The directories, absolute.
+ */
+export function kitPackageDirectories(context: {
+  kitPackages?: Array<{ directoryAbsolute: string }>;
+}): string[] {
+  return (context.kitPackages ?? []).map(
+    ({ directoryAbsolute }) => directoryAbsolute
+  );
+}

package/src/shell-acceptance.ts

@@ -0,0 +1,45 @@
+// How the preview takes a shell: whether a module's default export is a
+// shell this preview serves, and the shell's options for a kit. The host page
+// uses these; a shell does not. Browser-safe.
+
+import type { PreviewCatalog } from './controller/index.js';
+import type { PreviewShellOption } from './options.js';
+import { PREVIEW_SHELL_API_VERSION, type PreviewShell } from './shell.js';
+
+/**
+ * A shell's own options for a kit: its `options`, called with the catalog
+ * when it is a function.
+ *
+ * @param shell - The shell.
+ * @param catalog - The kit's catalog.
+ * @returns The options, none when the shell declares none.
+ */
+export function shellOptionsFor(
+  shell: Pick<PreviewShell, 'options'>,
+  catalog: PreviewCatalog
+): PreviewShellOption[] {
+  const options = shell.options;
+  return typeof options === 'function' ? options(catalog) : (options ?? []);
+}
+
+/**
+ * Why `candidate` cannot serve as this preview's shell: it is not a shell, or
+ * it was written against another contract version. The message names both
+ * versions.
+ *
+ * @param candidate - A shell module's default export.
+ * @returns The problem, or `undefined` when the candidate is a shell this preview serves.
+ */
+export function shellProblem(candidate: unknown): string | undefined {
+  if (typeof candidate !== 'object' || candidate === null) {
+    return 'The shell module does not default-export a shell: expected an object made with defineShell.';
+  }
+  const shell = candidate as Partial<PreviewShell>;
+  if (typeof shell.mount !== 'function') {
+    return 'The shell module does not default-export a shell: it has no mount function.';
+  }
+  if (shell.apiVersion !== PREVIEW_SHELL_API_VERSION) {
+    return `This preview serves shell API version ${PREVIEW_SHELL_API_VERSION}, and the shell declares version ${String(shell.apiVersion)}.`;
+  }
+  return undefined;
+}

package/src/shell-page.ts

@@ -0,0 +1,133 @@
+// The host page's start, as the shell's page module gives it: the module is
+// loaded in Node, its `head` and `root` are worked out once, and the files
+// they reference are given addresses the development server or the static
+// build serves.
+
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { PreviewContext } from './context.js';
+import type { ShellPage, ShellPageMarkup } from './shell.js';
+
+/** The host page shipped with the preview, which a shell's page is written
+ *  into. */
+export const HOST_PAGE = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '../application/index.html'
+);
+
+/** A shell's page, worked out: what goes where in the host page. */
+export interface ResolvedShellPage {
+  /** Markup for the end of the page's `<head>`; empty with none. */
+  head: string;
+  /** Markup for the page's root element; empty with none. */
+  root: string;
+  /** The directories of the files the markup references, which the
+   *  development server has to be allowed to serve. */
+  assetDirectories: string[];
+}
+
+/** Where the page is going. */
+export interface ShellPageTarget {
+  /** The host page's absolute path. */
+  hostPage: string;
+  /** Whether the development server serves the page; the static build
+   *  writes it otherwise. */
+  serving: boolean;
+}
+
+/**
+ * Load the shell's page module and work out its markup.
+ *
+ * @param context - The kit's preview context, for the page module and the
+ *   importer that loads it.
+ * @param target - Where the page is going.
+ * @returns The page's markup and the directories its files are in, or
+ *   `undefined` when the shell has no page.
+ * @throws When the module's default export is not a shell page, a part of
+ *   it is neither markup nor a function, a function gives something other
+ *   than markup, `asset` is given a path that is not absolute, or the module
+ *   cannot be loaded.
+ */
+export async function loadShellPage(
+  context: Pick<PreviewContext, 'shellPageAbsolute' | 'importModule'>,
+  target: ShellPageTarget
+): Promise<ResolvedShellPage | undefined> {
+  const modulePath = context.shellPageAbsolute;
+  if (modulePath === undefined) return undefined;
+  const fail = (problem: string): never => {
+    throw new Error(`[preview] The shell page ${modulePath} ${problem}`);
+  };
+  let loaded: { default?: unknown } | null | undefined;
+  try {
+    loaded = (await context.importModule(modulePath)) as typeof loaded;
+  } catch (error) {
+    return fail(`could not be loaded: ${(error as Error).message}`);
+  }
+  const page = loaded?.default as ShellPage | undefined;
+  if (typeof page !== 'object' || page === null || Array.isArray(page)) {
+    return fail(
+      'must default-export a shell page, as defineShellPage({ head, root }) gives.'
+    );
+  }
+  const unknown = Object.keys(page).filter(
+    (key) => key !== 'head' && key !== 'root'
+  );
+  if (unknown.length > 0) {
+    return fail(
+      `has the unknown key '${unknown[0]}'; a shell page takes head and root.`
+    );
+  }
+  const assetDirectories = new Set<string>();
+  const asset = (file: string): string => {
+    if (typeof file !== 'string' || !isAbsolute(file)) {
+      return fail(
+        `called asset(${JSON.stringify(file)}); asset takes a file's absolute path.`
+      );
+    }
+    assetDirectories.add(dirname(file));
+    if (target.serving) {
+      // The development server serves a file outside its root by its
+      // absolute path. Each segment is encoded, so a `#`, a `?` or a space
+      // in a directory's name stays part of the path; a drive's colon is
+      // kept. An `@` or a `+`, as a package manager's store has in its
+      // directory names, is left as it is: the server reads neither back
+      // from its encoded form.
+      const segments = resolve(file)
+        .split(sep)
+        .map((segment, index) =>
+          index === 0 && /^[A-Za-z]:$/.test(segment)
+            ? segment
+            : encodeURI(segment).replace(/#/g, '%23').replace(/\?/g, '%3F')
+        );
+      const path = segments.join('/');
+      return `/@fs${path.startsWith('/') ? '' : '/'}${path}`;
+    }
+    // The build takes the file relative to the page.
+    const fromPage = relative(dirname(target.hostPage), file);
+    if (isAbsolute(fromPage)) {
+      return fail(
+        `called asset(${JSON.stringify(file)}), a file on another drive than the preview, which the static build cannot reach.`
+      );
+    }
+    return fromPage.split(sep).join('/');
+  };
+  const markup = async (
+    name: 'head' | 'root',
+    part: ShellPageMarkup | undefined
+  ): Promise<string> => {
+    if (part === undefined) return '';
+    if (typeof part !== 'string' && typeof part !== 'function') {
+      return fail(`has a '${name}' that is neither markup nor a function.`);
+    }
+    const given = typeof part === 'function' ? await part({ asset }) : part;
+    if (typeof given !== 'string') {
+      return fail(`has a '${name}' function that gave no markup.`);
+    }
+    return given.trim();
+  };
+  return {
+    head: await markup('head', page.head),
+    root: await markup('root', page.root),
+    assetDirectories: [...assetDirectories],
+  };
+}

package/src/shell-peers.ts

@@ -0,0 +1,70 @@
+// The packages a shell needs installed beside the preview: the charcell
+// shell imports charcell and @zag-js/react, which the preview declares as
+// optional peers rather than installing for every kit. A kit that names the
+// shell without one would otherwise get a bundler error about an import it
+// cannot see, from inside the shell, once Vite runs.
+
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import type { PreviewContext } from './context.js';
+
+/** The packages the charcell shell imports that the kit installs: the
+ *  preview's peer dependencies. */
+export const CHARCELL_SHELL_PEERS = ['charcell', '@zag-js/react'] as const;
+
+/**
+ * Whether package `name` resolves from `directory` by Node's lookup: a
+ * `node_modules/<name>` in it or any directory above it.
+ *
+ * @param name - The package name.
+ * @param directory - The directory an import of it is made from.
+ * @returns Whether a `node_modules/<name>/package.json` is found.
+ */
+export function resolvesFrom(name: string, directory: string): boolean {
+  for (let current = directory; ; current = dirname(current)) {
+    if (existsSync(resolve(current, 'node_modules', name, 'package.json')))
+      return true;
+    if (current === dirname(current)) return false;
+  }
+}
+
+/**
+ * The packages the kit's shell imports that do not resolve from where the
+ * shell is, as the bundler would look for them: for the charcell shell,
+ * named as it is or configured through a module of the kit's, each of
+ * {@link CHARCELL_SHELL_PEERS} the kit has not installed. A shell of the
+ * kit's own, or from another package, declares its own dependencies, and
+ * gets nothing here.
+ *
+ * @param context - The preview context.
+ * @returns The missing packages' names, empty when none is missing.
+ */
+export function missingShellPeers(
+  context: Pick<PreviewContext, 'charcellShellAbsolute'>
+): string[] {
+  if (context.charcellShellAbsolute === undefined) return [];
+  const shellDirectory = dirname(context.charcellShellAbsolute);
+  return CHARCELL_SHELL_PEERS.filter(
+    (name) => !resolvesFrom(name, shellDirectory)
+  );
+}
+
+/**
+ * What to say of the shell's missing packages, or `undefined` when none is
+ * missing: the packages to install, and the command that installs them.
+ *
+ * @param missing - The packages {@link missingShellPeers} gives.
+ * @returns The message, naming each package.
+ * @example
+ * ```ts
+ * missingShellPeersProblem(['@zag-js/react']);
+ * // "the charcell shell needs @zag-js/react, which the kit has not installed: ..."
+ * ```
+ */
+export function missingShellPeersProblem(
+  missing: readonly string[]
+): string | undefined {
+  if (missing.length === 0) return undefined;
+  const names = missing.join(' and ');
+  return `the charcell shell needs ${names}, which the kit has not installed: add ${missing.length === 1 ? 'it' : 'them'} to the kit's devDependencies, as in \`npm install --save-dev ${missing.join(' ')}\``;
+}

package/src/shell.ts

@@ -0,0 +1,194 @@
+// The shell contract: what a module named by `preview.shell` exports, what a
+// shell's page module exports, and everything a shell author reads from the
+// preview - the controller's state and actions, a store view of that state,
+// the catalog, the editor's tree, the option helpers, the scenario helpers
+// and a story's source. A shell renders the whole host interface around the
+// preview's iframes, in React, Vue, Svelte or plain DOM; the preview provides
+// the behavior. Browser-safe: no node imports, and nothing here holds state
+// of its own.
+
+import type { PreviewCatalog, PreviewController } from './controller/index.js';
+import type { PreviewShellOption } from './options.js';
+
+export {
+  childPath,
+  DEFAULT_PANE_WIDTHS,
+  DEFAULT_SLOT,
+  defaultScenarioId,
+  isContainer,
+  MAXIMUM_PANE_WIDTH,
+  PREVIEW_FRAME_SHOWN_ATTRIBUTE,
+  nodeAt,
+  nodeAddSlots,
+  nodeSlots,
+  previewStore,
+  printStorySource,
+  scenarioChoices,
+  storyFrameKey,
+  type AroundFill,
+  type ContainerNode,
+  type DropTarget,
+  type EditorNode,
+  type EditorState,
+  type NodePath,
+  type OpaqueFill,
+  type PreviewBinding,
+  type PreviewCatalog,
+  type PreviewCatalogView,
+  type PreviewComponent,
+  type PreviewController,
+  type PreviewEditorState,
+  type PreviewEvent,
+  type PreviewFrameReadiness,
+  type PreviewFrameTarget,
+  type PreviewTargetCode,
+  type PreviewHtmlSource,
+  type PreviewImport,
+  type PreviewInsertTarget,
+  type PreviewLanding,
+  type PreviewNavigationNode,
+  type PreviewNodeRequest,
+  type PreviewOptionDescriptor,
+  type PreviewPaneWidth,
+  type PreviewPropType,
+  type PreviewRegenerationStatus,
+  type PreviewScenario,
+  type PreviewSource,
+  type PreviewSelection,
+  type PreviewSortableDrop,
+  type PreviewCode,
+  type PreviewState,
+  type PreviewStore,
+  type PreviewStoryReference,
+  type ScenarioChoice,
+  type SortableListAddress,
+  type Step,
+  type StoryAround,
+} from './controller/index.js';
+export {
+  CONTEXT_OPTION_GROUP,
+  KIT_OPTION_GROUP,
+  optionGroup,
+  optionKind,
+  shellOptionId,
+  type OptionChoice,
+  type OptionKind,
+  type OptionValue,
+  type PreviewShellOption,
+} from './options.js';
+export {
+  PREVIEW_SCRIPTED_TARGETS,
+  PREVIEW_TARGETS,
+  type PreviewContentSize,
+  type PreviewScriptedTarget,
+  type PreviewTarget,
+} from './protocol.js';
+export type { ViewFramework } from './views.js';
+
+/** The version of the shell contract this preview serves. */
+export const PREVIEW_SHELL_API_VERSION = 1;
+
+/**
+ * What a shell module default-exports: the contract version it was written
+ * against, its own options, and how it mounts.
+ */
+export interface PreviewShell {
+  /** The shell contract version the shell was written against. The preview
+   *  refuses a shell whose version it does not serve. */
+  apiVersion: number;
+  /** The shell's own options, such as its color mode or density. The preview
+   *  keeps their values beside the kit's, under `shell.<id>`. A function is
+   *  called once with the kit's catalog before the preview starts, for options
+   *  that depend on the kit, such as a choice among its targets. */
+  options?:
+    | PreviewShellOption[]
+    | ((catalog: PreviewCatalog) => PreviewShellOption[]);
+  /**
+   * Render the shell into `root`, reading and driving `controller`.
+   *
+   * @param root - The host page's root element, empty.
+   * @param controller - The preview's behavior.
+   * @returns A function that unmounts the shell, or nothing when there is
+   *   nothing to undo. The preview calls it before mounting a changed shell
+   *   over the same controller during development.
+   */
+  mount(root: HTMLElement, controller: PreviewController): (() => void) | void;
+}
+
+/**
+ * Declare a shell. The function only types its argument and returns it, so a
+ * shell module reads as one declaration.
+ *
+ * @param shell - The shell.
+ * @returns The shell, unchanged.
+ * @example
+ * ```ts
+ * export default defineShell({
+ *   apiVersion: 1,
+ *   options: [{ id: 'density', label: 'density', default: false }],
+ *   mount(root, controller) {
+ *     const stop = controller.subscribe((state) => render(root, state));
+ *     render(root, controller.getState());
+ *     return stop;
+ *   },
+ * });
+ * ```
+ */
+export function defineShell(shell: PreviewShell): PreviewShell {
+  return shell;
+}
+
+/** What a shell page's `head` and `root` functions are given. */
+export interface ShellPageContext {
+  /**
+   * The address of a file the page's markup references, such as a font to
+   * preload: the development server serves the file from where it is, and the
+   * static build copies it into its output.
+   *
+   * @param file - The file's absolute path.
+   * @returns The address to write into the markup, in an `href`, a `src` or
+   *   a CSS `url()`.
+   */
+  asset(file: string): string;
+}
+
+/** A part of the host page a shell supplies: markup, or a function that
+ *  gives it. */
+export type ShellPageMarkup =
+  | string
+  | ((context: ShellPageContext) => string | Promise<string>);
+
+/**
+ * What a shell's page module default-exports: the static start of the host
+ * page, which shows before the shell's script has loaded. The module is
+ * evaluated in Node as the preview starts or builds, so it reads files and
+ * resolves packages freely and holds nothing that needs a browser.
+ */
+export interface ShellPage {
+  /** Markup for the end of the page's `<head>`: styles, a font face, links
+   *  that preload what the shell will need. It stays for the life of the
+   *  page. */
+  head?: ShellPageMarkup;
+  /** Markup for the page's root element, shown until the shell mounts: a
+   *  loading note, with the styles only it needs. The preview empties the
+   *  root before it mounts the shell. */
+  root?: ShellPageMarkup;
+}
+
+/**
+ * Declare a shell's page. The function only types its argument and returns
+ * it, so a page module reads as one declaration.
+ *
+ * @param page - The page.
+ * @returns The page, unchanged.
+ * @example
+ * ```ts
+ * export default defineShellPage({
+ *   head: '<style>html { background: #101010; }</style>',
+ *   root: '<p role="status">loading</p>',
+ * });
+ * ```
+ */
+export function defineShellPage(page: ShellPage): ShellPage {
+  return page;
+}

package/src/shells/charcell/page.ts

@@ -0,0 +1,82 @@
+// The charcell shell's page: what the host page shows before the shell's
+// script has loaded. charcell's dark ground paints from the first frame, the
+// upright face is declared and its font preloaded, and the root holds the
+// loading note the shell mounts over.
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineShellPage } from '../../shell.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** The loading note and its styles, kept beside the shell. */
+const loadingNote = resolve(
+  here,
+  '../../../application/shells/charcell/page-loading.html'
+);
+
+/**
+ * charcell's upright face, as its base stylesheet declares it.
+ *
+ * @returns The `@font-face` rule, the address it gives the font file, and
+ *   the file's absolute path; or nothing when charcell or the rule cannot be
+ *   found.
+ */
+function uprightFace():
+  | { rule: string; address: string; file: string }
+  | undefined {
+  let stylesheet: string;
+  let source: string;
+  try {
+    stylesheet = createRequire(import.meta.url).resolve('charcell/css/base');
+    source = readFileSync(stylesheet, 'utf8');
+  } catch {
+    return undefined;
+  }
+  const rule = (source.match(/@font-face\s*\{[^}]*\}/g) ?? []).find((face) =>
+    /font-style:\s*normal/.test(face)
+  );
+  const address = rule?.match(/url\((["']?)([^"')]+)\1\)/)?.[2];
+  // Only a font file beside the stylesheet: an address of another kind, a
+  // data address or one with a query, names no file to preload.
+  if (
+    rule === undefined ||
+    address === undefined ||
+    !/^\.{0,2}\/?[\w./-]+\.woff2$/.test(address)
+  ) {
+    return undefined;
+  }
+  return { rule, address, file: resolve(dirname(stylesheet), address) };
+}
+
+/**
+ * The charcell shell's page: charcell's dark ground and its face in the
+ * head, the font preloaded, and the loading note in the root. A kit that
+ * names the charcell shell as it is gets it without naming it; a module of
+ * the kit's that configures the shell names it as `preview.shell.page`.
+ */
+export default defineShellPage({
+  head({ asset }) {
+    // The ground sits in the first, lowest cascade layer, so charcell's own
+    // page rule and a kit's overrides win once they load.
+    const ground =
+      '<style>@layer { html { color-scheme: dark; background: #000000; } }</style>';
+    const face = uprightFace();
+    if (face === undefined) return ground;
+    const font = asset(face.file);
+    // The face as charcell declares it, except that text waits for the font
+    // rather than showing in another face first: the loading note appears in
+    // the face the shell's text has, on the same cells.
+    const rule = face.rule
+      .replace(face.address, () => font)
+      .replace(/font-display:\s*[a-z]+/, 'font-display:block');
+    return [
+      ground,
+      `<link rel="preload" as="font" type="font/woff2" crossorigin href="${font}" />`,
+      `<style>${rule}</style>`,
+    ].join('\n');
+  },
+  root: () => readFileSync(loadingNote, 'utf8'),
+});