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

package/application/shells/charcell/shell.tsx

@@ -0,0 +1,25 @@
+// The charcell shell's root. The terminal look is charcell (the standalone kit
+// the look was extracted into); the shell's own surfaces (the editor panel,
+// controls, layout) are styled on charcell's tokens. The behavior is the
+// controller's: this component provides it and the shell's configuration to
+// the tree, and the interface inside lays out the prompt bar, navigation, stage
+// and status bar (Application). The stylesheets come in charcell's order:
+// charcell's own, then the shell's layers and page (shell.css), then each
+// component's, which it imports itself.
+import 'charcell/css/full';
+import './shell.css';
+import type { PreviewController } from '../../../src/shell';
+import { Application } from './components/Application';
+import type { CharcellShellConfiguration } from './configuration';
+import { PreviewControllerContext, ShellConfigurationContext } from './controller-context';
+
+/** The shell as one React element: the controller and the configuration provided, the interface inside. */
+export function CharcellApplication(props: { controller: PreviewController; configuration: CharcellShellConfiguration }) {
+  return (
+    <PreviewControllerContext.Provider value={props.controller}>
+      <ShellConfigurationContext.Provider value={props.configuration}>
+        <Application />
+      </ShellConfigurationContext.Provider>
+    </PreviewControllerContext.Provider>
+  );
+}

package/application/shells/charcell/split-reset.ts

@@ -0,0 +1,47 @@
+// The reset gesture on the stage grid's handles (PreviewGrid): a double-click
+// on a handle, or Enter while it holds the focus, puts the split it moves
+// back at its even distribution. The handle's own handlers, charcell's
+// dragging and stepping, run first and keep working as they do.
+
+/** The key that resets a focused handle. */
+export const RESET_KEY = 'Enter';
+
+/** A handle's props, as the grid hands them, with their event handlers. */
+type HandleProps = Record<string, unknown>;
+
+/** The handlers the reset gesture composes with a handle's own. */
+export interface ResetHandlers {
+  onDoubleClick: (event: { button?: number }) => void;
+  onKeyDown: (event: { key: string; ctrlKey?: boolean; altKey?: boolean; metaKey?: boolean; shiftKey?: boolean }) => void;
+}
+
+/** Calls the handler `props` holds under `name`, if it holds one. */
+function callOwn(props: HandleProps, name: string, event: unknown): void {
+  const own = props[name];
+  if (typeof own === 'function') own(event);
+}
+
+/**
+ * A handle's props with the reset gesture added: `reset` runs on a
+ * double-click on the handle, and on Enter while it holds the focus, after
+ * the handle's own `onDoubleClick` and `onKeyDown`.
+ *
+ * @param props - The handle's props, as the grid hands them.
+ * @param reset - Puts the handle's split back at its even distribution.
+ * @returns The props, their double-click and key handlers composed with the reset.
+ * @example
+ * <SplitGridHandle {...withResetGesture(grid.columnHandleProps(0), () => grid.columnsApi.resetSizes())} />
+ */
+export function withResetGesture<Props extends HandleProps>(props: Props, reset: () => void): Props & ResetHandlers {
+  return {
+    ...props,
+    onDoubleClick: (event) => {
+      callOwn(props, 'onDoubleClick', event);
+      if ((event.button ?? 0) === 0) reset();
+    },
+    onKeyDown: (event) => {
+      callOwn(props, 'onKeyDown', event);
+      if (event.key === RESET_KEY && !event.ctrlKey && !event.altKey && !event.metaKey && !event.shiftKey) reset();
+    },
+  };
+}

package/application/shells/charcell/stacked-rows.ts

@@ -0,0 +1,117 @@
+// The cells the stacked output rows start at (PreviewGrid): while the story
+// panes are laid out at a width wider than a column, the grid stacks a row
+// per target over the code row. Every row starts at its story's height when
+// the stories fit; when they don't, the rows share the space equally, a
+// shorter story keeping its own height. Each row has a least: a readable
+// height, or its story's when that is shorter. The grid is made tall enough
+// for every row's least and the code row's, and the stage scrolls past it
+// only when those don't fit.
+
+/** The code row under the stacked rows: the least it keeps and its share. */
+export interface StackedCodeRow {
+  /** The fewest cells the code row keeps. */
+  least: number;
+  /** The share of the rows' space it starts at, in percent, as far as the
+   *  output rows keep their least. */
+  share: number;
+}
+
+/**
+ * Each stacked output row's least, in cells: `least`, or the cells its
+ * story and the pane around it take when that is fewer. A story that has
+ * not reported its height (`undefined`) counts as `least`.
+ *
+ * @param wanted - The cells each output row's content takes.
+ * @param least - The readable least of an output row.
+ * @returns The least per row.
+ * @example
+ * stackedRowMinimums([4.2, undefined, 30], 10); // [5, 10, 10]
+ */
+export function stackedRowMinimums(wanted: readonly (number | undefined)[], least: number): number[] {
+  return wanted.map((cells) => (cells === undefined ? least : Math.max(1, Math.min(least, Math.ceil(cells)))));
+}
+
+/**
+ * The cells each stacked output row starts at, then the code row's when
+ * there is one. A row's `wanted` is the cells its story and the pane around
+ * it take (undefined while the story has not reported its height, which asks
+ * for as much as it can get); `total` is the cells the rows share. Rows that
+ * fit start at what they want, the space left over going to the code row, or
+ * to the last row without one, so no row above the last is taller than its
+ * story. Rows that don't fit share the space equally, a row that wants less
+ * than its share keeping what it wants. The code row starts at its share as
+ * far as the output rows keep their least (`stackedRowMinimums`). The rows
+ * share at least their leasts and the code row's, even when that is more
+ * than `total` holds.
+ *
+ * @param options.wanted - The cells each output row's content takes.
+ * @param options.total - The whole cells the rows share.
+ * @param options.least - The readable least of an output row.
+ * @param options.code - The code row under the output rows, if it shows.
+ * @returns The cells per row, the output rows first and then the code row.
+ * @example
+ * stackedRowCells({ wanted: [5, 40, 40], total: 60, least: 4 }); // [5, 27, 28]
+ */
+export function stackedRowCells({
+  wanted,
+  total,
+  least,
+  code,
+}: {
+  wanted: (number | undefined)[];
+  total: number;
+  least: number;
+  code?: StackedCodeRow;
+}): number[] {
+  const count = wanted.length;
+  const outputLeast = stackedRowMinimums(wanted, least).reduce((all, cells) => all + cells, 0);
+  const space = Math.max(Math.floor(total), outputLeast + (code ? code.least : 0));
+  const codeCells = code
+    ? Math.max(code.least, Math.min(Math.round((code.share / 100) * space), space - outputLeast))
+    : 0;
+  const output = space - codeCells;
+  const wants = wanted.map((cells) => Math.max(1, Math.ceil(cells ?? Number.POSITIVE_INFINITY)));
+  const sum = wants.reduce((all, cells) => all + cells, 0);
+  let cells: number[];
+  if (sum <= output) {
+    cells = [...wants];
+    // What is left over goes under the last story: to the code row, or the
+    // last output row.
+    if (code) return [...cells, codeCells + output - sum];
+    cells[count - 1] += output - sum;
+    return cells;
+  }
+  // The rows that want least first, each taking its want or an equal share
+  // of what is left, whichever is less; the one that wants most, the rest.
+  // Since the space holds every row's least, a row wanting more than
+  // `least` is left at least `least` this way.
+  cells = new Array<number>(count).fill(0);
+  const order = wants.map((_, index) => index).sort((first, second) => wants[first] - wants[second]);
+  let left = output;
+  order.forEach((index, position) => {
+    const share = position === count - 1 ? left : Math.min(wants[index], Math.floor(left / (count - position)));
+    cells[index] = share;
+    left -= share;
+  });
+  return code ? [...cells, codeCells] : cells;
+}
+
+/**
+ * The cells a stacked grid needs at least: each output row's least
+ * (`stackedRowMinimums`), the code row's, and a cell for each handle
+ * between two rows.
+ *
+ * @param wanted - The cells each output row's content takes.
+ * @param least - The readable least of an output row.
+ * @param code - The code row under the output rows, if it shows.
+ * @returns The grid's least height, in cells.
+ */
+export function stackedLeastCells(
+  wanted: readonly (number | undefined)[],
+  least: number,
+  code?: StackedCodeRow,
+): number {
+  const rows = wanted.length + (code ? 1 : 0);
+  const output = stackedRowMinimums(wanted, least).reduce((all, cells) => all + cells, 0);
+  return output + (code ? code.least : 0) + (rows - 1);
+}

package/application/shells/charcell/stage-toggles.ts

@@ -0,0 +1,93 @@
+// Showing and hiding the stage's views and targets, from the top bar's
+// toggles and the shell's keys alike. In a narrow window the stage shows one
+// view and one target at a time: the first of each the state turns on, and
+// turning one on turns the others off, the one showing staying on. The
+// narrow layout starts below a width of the window's (NARROW_WIDTH). It
+// narrows what the stage shows, not the state: a window that loads or
+// becomes narrow changes no option and leaves the address as it is, and
+// widening it shows every view and target the state turns on again. Only a
+// toggle a person turns writes the state.
+import { useEffect, useMemo, useState } from 'react';
+import type { OptionValue, PreviewController, PreviewTarget } from '../../../src/shell';
+import { usePreviewState } from './controller-context';
+import { CODE_VIEW_OPTION, EVENTS_VIEW_OPTION, OUTPUT_VIEW_OPTION, SCENARIO_VIEW_OPTION } from './shell-options';
+
+/** The window width, in CSS pixels, below which the stage is narrow. */
+export const NARROW_WIDTH = 900;
+
+/** The views' options, top to bottom. */
+export const VIEW_OPTIONS = [SCENARIO_VIEW_OPTION, OUTPUT_VIEW_OPTION, CODE_VIEW_OPTION, EVENTS_VIEW_OPTION] as const;
+
+/** Whether a view's option turns it on, by its value: output unless turned
+ *  off, the others once turned on. */
+export function viewShown(option: string, value: unknown): boolean {
+  return option === OUTPUT_VIEW_OPTION ? value !== false : value === true;
+}
+
+/** The views the stage shows, top to bottom: those the options turn on, or,
+ *  narrow, the first of them. */
+export function stageViews(options: Record<string, OptionValue | undefined>, narrow: boolean): string[] {
+  const views = VIEW_OPTIONS.filter((option) => viewShown(option, options[option]));
+  return narrow ? views.slice(0, 1) : views;
+}
+
+/** The panes the stage shows: the state's, or, narrow, the first of them. */
+export function stagePanes(panes: PreviewTarget[], narrow: boolean): PreviewTarget[] {
+  return narrow ? panes.slice(0, 1) : panes;
+}
+
+/** Whether the window is narrow, following it as it resizes. */
+export function useNarrow(): boolean {
+  const query = `(max-width: ${NARROW_WIDTH - 1}px)`;
+  const [narrow, setNarrow] = useState(() => typeof matchMedia === 'function' && matchMedia(query).matches);
+  useEffect(() => {
+    if (typeof matchMedia !== 'function') return;
+    const list = matchMedia(query);
+    const follow = () => setNarrow(list.matches);
+    follow();
+    list.addEventListener('change', follow);
+    return () => list.removeEventListener('change', follow);
+  }, [query]);
+  return narrow;
+}
+
+/** What the stage shows now: whether it is narrow, which views show, and the
+ *  panes, following the state and the window. */
+export function useStage(): { narrow: boolean; views: ReadonlySet<string>; panes: PreviewTarget[] } {
+  const narrow = useNarrow();
+  const options = usePreviewState((state) => state.options);
+  const panes = usePreviewState((state) => state.targets.panes);
+  return useMemo(
+    () => ({ narrow, views: new Set(stageViews(options, narrow)), panes: stagePanes(panes, narrow) }),
+    [narrow, options, panes],
+  );
+}
+
+/** Show or hide a view; narrow, showing one hides the others, and the one
+ *  showing stays. */
+export function toggleView(controller: PreviewController, option: string, narrow: boolean): void {
+  const { options } = controller.getState();
+  if (!narrow) {
+    controller.actions.setOption(option, !viewShown(option, options[option]));
+    return;
+  }
+  if (stageViews(options, true)[0] === option) return;
+  controller.actions.setOption(option, true);
+  for (const other of VIEW_OPTIONS) {
+    if (other !== option && viewShown(other, options[other])) controller.actions.setOption(other, false);
+  }
+}
+
+/** Show or hide a target; narrow, showing one hides the others, and the one
+ *  showing stays. */
+export function toggleTarget(controller: PreviewController, target: PreviewTarget, narrow: boolean): void {
+  const { visible, supported, panes } = controller.getState().targets;
+  if (!supported.includes(target)) return;
+  if (!narrow) {
+    controller.actions.setTargetVisible(target, !visible.includes(target));
+    return;
+  }
+  if (stagePanes(panes, true)[0] === target) return;
+  controller.actions.setTargetVisible(target, true);
+  for (const other of visible) if (other !== target) controller.actions.setTargetVisible(other, false);
+}

package/application/types/manifest.d.ts

@@ -0,0 +1,6 @@
+// The generated manifest (`@preview-generated/manifest.json`), typed as the
+// generator emits it.
+import type { Manifest } from '../../src/emit/manifest';
+
+declare const manifest: Manifest;
+export default manifest;

package/application/types/preview-configuration.d.ts

@@ -0,0 +1,10 @@
+// The data of the kit's preview block as the app type-checks against it:
+// exactly what the `@preview-configuration` module the preview serves
+// exports, one constant per key the pages read.
+import type { PreviewBrowserConfiguration } from '../../src/lib/types';
+
+export declare const options: PreviewBrowserConfiguration['options'];
+export declare const canvas: PreviewBrowserConfiguration['canvas'];
+export declare const themes: PreviewBrowserConfiguration['themes'];
+export declare const mount: PreviewBrowserConfiguration['mount'];
+export declare const viewCanvas: PreviewBrowserConfiguration['viewCanvas'];

package/application/types/preview-shell.d.ts

@@ -0,0 +1,7 @@
+// The shell module as the app type-checks against it: `@preview-shell` is
+// aliased at build time to the module `preview.shell` names, whose
+// default export is a shell.
+import type { PreviewShell } from '../../src/shell';
+
+declare const shell: PreviewShell;
+export default shell;

package/application/types/react-registry.d.ts

@@ -0,0 +1,15 @@
+// A generated React render-registry (`@preview-generated/react/registry`,
+// `@preview-generated/scratch/react`): component id to a render function,
+// and what the React pane spells a story's props with. The scratch module is
+// a placeholder holding an empty `registry` alone until the editor's first
+// edit, so its other exports may be absent.
+import type { ReactNode } from 'react';
+
+export declare const registry: Record<
+  string,
+  (props: Record<string, unknown>) => ReactNode
+>;
+/** How React spells the HTML attributes it renames, by their HTML names. */
+export declare const reactAttributeNames: Record<string, string> | undefined;
+/** The names each story's root declares that React would otherwise respell. */
+export declare const declaredAttributes: Record<string, string[]> | undefined;

package/application/types/vue-registry.d.ts

@@ -0,0 +1,6 @@
+// A generated Vue render-registry (`@preview-generated/vue/registry`,
+// `@preview-generated/scratch/vue`): component id to the components a string
+// template mounts.
+import type { Component } from 'vue';
+
+export declare const registry: Record<string, { components: Record<string, Component>; template: string }>;

package/dist/build.d.ts

@@ -0,0 +1,24 @@
+import type { ConfigurationLookupOptions } from 'scaffold-ui-kit';
+import type { InlineConfig } from 'vite';
+/** What a static build did. */
+export interface PreviewBuildResult {
+    /** Whether the preview was built: false when the check found errors. */
+    built: boolean;
+    /** The check's errors, each a line naming its component. */
+    errors: string[];
+    /** The check's warnings, which do not stop the build. */
+    warnings: string[];
+}
+/**
+ * Builds a kit's static preview: removes the previous build, checks the
+ * kit's story files and manual specs, and, when the check finds no errors,
+ * generates the preview with every story's html and builds it with Vite.
+ *
+ * @param kitRoot - The kit root (where its package.json lives).
+ * @param build - The Vite build to run; Vite's own by default.
+ * @param options - The kit configuration file, when it is not the one the
+ *   kit root gives.
+ * @returns Whether it built, the check's errors that stopped it, and its
+ *   warnings.
+ */
+export declare function buildPreview(kitRoot: string, build?: (configuration: InlineConfig) => Promise<unknown>, options?: ConfigurationLookupOptions): Promise<PreviewBuildResult>;

package/dist/build.js

@@ -0,0 +1,34 @@
+// The static build, as `scaffold-ui-kit-preview build` runs it: check the
+// story files and manual specs first, then generate and build the preview into
+// the kit's static root. A check error stops the build, as it would leave a
+// story the preview shows wrong or not at all.
+import { rmSync } from 'node:fs';
+import { checkPreview } from './check.js';
+import { loadPreviewContext } from './context.js';
+import { generatePreview } from './generate.js';
+import { buildViteConfiguration } from './vite-configuration.js';
+/**
+ * Builds a kit's static preview: removes the previous build, checks the
+ * kit's story files and manual specs, and, when the check finds no errors,
+ * generates the preview with every story's html and builds it with Vite.
+ *
+ * @param kitRoot - The kit root (where its package.json lives).
+ * @param build - The Vite build to run; Vite's own by default.
+ * @param options - The kit configuration file, when it is not the one the
+ *   kit root gives.
+ * @returns Whether it built, the check's errors that stopped it, and its
+ *   warnings.
+ */
+export async function buildPreview(kitRoot, build, options = {}) {
+    const context = loadPreviewContext(kitRoot, options);
+    // The previous build goes first, so a build that fails leaves no output
+    // behind that looks current.
+    rmSync(context.staticRoot, { recursive: true, force: true });
+    const { errors, warnings } = await checkPreview(kitRoot, options);
+    if (errors.length > 0)
+        return { built: false, errors, warnings };
+    await generatePreview(context, { htmlSources: true });
+    const runBuild = build ?? (await import('vite')).build;
+    await runBuild(buildViteConfiguration(context));
+    return { built: true, errors, warnings };
+}

package/dist/check.d.ts

@@ -0,0 +1,48 @@
+import type { ConfigurationLookupOptions } from 'scaffold-ui-kit';
+export interface PreviewCheckOptions extends ConfigurationLookupOptions {
+    /** Report missing scenario coverage as errors, not warnings. */
+    strict?: boolean;
+}
+/** The check's findings, each a line naming its component. */
+export interface PreviewCheckReport {
+    /** Story file or manual-spec mistakes, and what fails `scaffold-ui-kit
+     *  build` for a template in the kit's `src/components/` (a line naming the
+     *  template's path, as the build prints it); under `strict`, coverage
+     *  gaps too. */
+    errors: string[];
+    /** What reading the kit configuration warns of, such as its old file
+     *  name, which stays a warning under `strict`; an enum value or boolean
+     *  no scenario sets, among the props generation
+     *  covers: a curated scenario that takes a generated id replaces that
+     *  scenario, and is named when it does not set the value (an error under
+     *  `strict`); a scenario prop set to `undefined` that the story's starting
+     *  value covers, which `null` would unset (an error under `strict`); and
+     *  what `scaffold-ui-kit build` warns of for a template in
+     *  `src/components/`, named by its path, which stays a warning under
+     *  `strict`. The build's lines cover validating and
+     *  rendering each template, by the kit's own installed scaffolder; a
+     *  driver colliding with a generated file and the stylesheets compiled
+     *  under `stylesheetLink: 'both'` are reported by the build alone. */
+    warnings: string[];
+    /** Props hidden from the controls because their type is not a control. */
+    hidden: string[];
+    /** Select and boolean props the story file's `generate` leaves out of scenario
+     *  generation and coverage: still controls, but no scenario is expected. */
+    ungenerated: string[];
+}
+/**
+ * Checks a kit's preview story files and manual specs against its components.
+ *
+ * @param kitRoot - The kit root (where its package.json lives)
+ * @param options - `strict` turns coverage warnings into errors; `configuration`
+ *   names the kit configuration file, as `--configuration` does
+ * @returns The errors, warnings and hidden props, each a line naming its component
+ * @example
+ * ```ts
+ * it('keeps the preview in step with the components', async () => {
+ *   const report = await checkPreview(process.cwd());
+ *   expect(report.errors).toEqual([]);
+ * });
+ * ```
+ */
+export declare function checkPreview(kitRoot: string, options?: PreviewCheckOptions): Promise<PreviewCheckReport>;