forgebook 0.3.3 → 0.4.1

package/dist/src/frame/controlValues.js

@@ -0,0 +1,143 @@
+import { isArgValue, isUnsetArg } from "../messages.js";
+import { panelArgTypesOf } from "../storyArgTypes.js";
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * The controls the catalogue gives the component's props by type, by prop, from its docs as the plugin served them.
+ *
+ * @param docs - the docs module's value.
+ */
+const typedControlsOf = (docs) => {
+    const props = isRecord(docs) && Array.isArray(docs["props"]) ? docs["props"] : [];
+    return Object.fromEntries(props.flatMap((prop) => isRecord(prop) && typeof prop["name"] === "string" && typeof prop["customControl"] === "string"
+        ? [[prop["name"], prop["customControl"]]]
+        : []));
+};
+/**
+ * The custom control of each arg, as the panel draws it: a control the story's `argTypes` name, else the one the
+ * catalogue gives the prop by type, unless the `argTypes` name another control for it.
+ *
+ * @param argTypes - the story's `argTypes`, as the panel reads them.
+ * @param docs - its component's docs, as the plugin served them.
+ */
+export const argControlsOf = (argTypes, docs) => {
+    const typed = Object.entries(typedControlsOf(docs)).filter(([name]) => argTypes[name]?.control === undefined && argTypes[name]?.customControl === undefined);
+    const named = Object.entries(argTypes).flatMap(([name, argType]) => argType.customControl === undefined ? [] : [[name, argType.customControl]]);
+    return Object.fromEntries([...typed, ...named]);
+};
+/** Each story file's docs, loaded once by the frame. */
+const docsLoads = new Map();
+/**
+ * A story's component docs, or none when they cannot load: the panel then has no docs either, so no control by type.
+ *
+ * @param load - the loader.
+ */
+const loadedDocs = (load) => {
+    if (load === undefined)
+        return Promise.resolve(undefined);
+    // a load that failed is tried again by the next values: the docs may be there by then
+    const started = docsLoads.get(load) ??
+        load().catch(() => {
+            docsLoads.delete(load);
+            return undefined;
+        });
+    docsLoads.set(load, started);
+    return started;
+};
+/** Whether a module exports a `toStoryValue` function, and a `toPanelValue` function or none. */
+const isFrameModule = (value) => typeof value === "object" &&
+    value !== null &&
+    "toStoryValue" in value &&
+    typeof value.toStoryValue === "function" &&
+    (!("toPanelValue" in value) ||
+        value.toPanelValue === undefined ||
+        typeof value.toPanelValue === "function");
+/** Each frame module's load, kept: every value of a page shares one. */
+const loads = new Map();
+/** The reason an error gives. */
+const reasonOf = (error) => (error instanceof Error ? error.message : String(error));
+/** A frame module, loaded once, or why it cannot be. */
+const loadedModule = async (control, load) => {
+    try {
+        const started = loads.get(load) ?? load();
+        loads.set(load, started);
+        const module = await started;
+        return isFrameModule(module)
+            ? module
+            : `The control "${control}" names a frame module that exports no toStoryValue function`;
+    }
+    catch (error) {
+        return `The control "${control}" could not load its frame module: ${reasonOf(error)}`;
+    }
+};
+/**
+ * One arg's values as its control's frame module turns them.
+ *
+ * @param module - the module.
+ * @param control - the control's name.
+ * @param argType - the arg.
+ * @param args - the panel's values.
+ * @param story - the story.
+ */
+const argOutcome = (module, control, argType, args, story) => {
+    const { name } = argType;
+    const problems = [];
+    let own;
+    const ownValue = Object.hasOwn(story.args, name) ? story.args[name] : undefined;
+    if (module.toPanelValue !== undefined && ownValue !== undefined) {
+        try {
+            const named = module.toPanelValue(ownValue, argType);
+            own = named !== undefined && isArgValue(named) ? named : undefined;
+        }
+        catch (error) {
+            problems.push(`The control "${control}" could not name the story's value of "${name}": ${reasonOf(error)}`);
+        }
+    }
+    const named = own === undefined ? {} : { own };
+    const given = Object.hasOwn(args, name) ? args[name] : undefined;
+    if (given === undefined)
+        return { isDropped: false, problems, ...named };
+    // the panel's "no value" stays one: the story receives `undefined`, as for any arg
+    if (isUnsetArg(given))
+        return { value: { made: undefined }, isDropped: false, problems, ...named };
+    try {
+        return { value: { made: module.toStoryValue(given, argType) }, isDropped: false, problems, ...named };
+    }
+    catch (error) {
+        problems.push(`The control "${control}" could not turn the value of "${name}": ${reasonOf(error)}`);
+        return { isDropped: true, problems, ...named };
+    }
+};
+/**
+ * The values of the controls with a frame module, as the story and the panel take them.
+ *
+ * @param args - the panel's values, checked by the shell.
+ * @param loaders - the frame modules, by control.
+ * @param story - the story's own args, its `argTypes` and its docs.
+ */
+export const controlValuesOf = async (args, loaders, story) => {
+    const types = panelArgTypesOf(story.argTypes, []);
+    const controls = argControlsOf(types, await loadedDocs(story.loadDocs));
+    const outcomes = await Promise.all(Object.entries(controls).flatMap(([name, control]) => {
+        const load = Object.hasOwn(loaders, control) ? loaders[control] : undefined;
+        if (load === undefined)
+            return [];
+        const settings = Object.hasOwn(types, name) ? types[name]?.settings : undefined;
+        const argType = { name, ...(settings === undefined ? {} : { settings }) };
+        return [
+            loadedModule(control, load).then((module) => [
+                name,
+                typeof module === "string"
+                    ? { isDropped: Object.hasOwn(args, name), problems: [module] }
+                    : argOutcome(module, control, argType, args, story)
+            ])
+        ];
+    }));
+    return {
+        values: Object.fromEntries(outcomes.flatMap(([name, outcome]) => (outcome.value === undefined ? [] : [[name, outcome.value.made]]))),
+        dropped: outcomes.flatMap(([name, outcome]) => (outcome.isDropped ? [name] : [])),
+        own: Object.fromEntries(outcomes.flatMap(([name, outcome]) => (outcome.own === undefined ? [] : [[name, outcome.own]]))),
+        // a module that fails is said once, however many args use it
+        problems: [...new Set(outcomes.flatMap(([, outcome]) => outcome.problems))]
+    };
+};

package/dist/src/frame/frame.css

@@ -5,6 +5,18 @@
     --forgebook-radius-control-small: 6px;
     --forgebook-radius-control: 7px;
     --forgebook-radius-card: 12px;
+    --forgebook-focus-edge: inset 0 0 0 1px var(--forgebook-accent);
+    --forgebook-focus-halo: color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    --forgebook-text-display: 700 1.375rem/1.2 var(--forgebook-font-sans);
+    --forgebook-text-card-title: 600 0.875rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-body: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    --forgebook-text-row-label: 500 0.8125rem/1.35 var(--forgebook-font-sans);
+    --forgebook-text-row-compact: 400 0.78125rem/1.4 var(--forgebook-font-sans);
+    --forgebook-text-control: 500 0.75rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-caption: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    --forgebook-text-label: 600 0.6875rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-mono: 400 0.71875rem/1.4 var(--forgebook-font-mono);
+    --forgebook-text-mono-small: 400 0.6875rem/1.6 var(--forgebook-font-mono);
     --forgebook-window: #f6f6f8;
     --forgebook-sidebar: #ebebef;
     --forgebook-surface: #fff;
@@ -19,6 +31,8 @@
     --forgebook-accent-text: #0059d2;
     --forgebook-on-accent: #fff;
     --forgebook-danger-text: #bc1f16;
+    --forgebook-caution-text: #935200;
+    --forgebook-positive-text: #077229;
     --forgebook-code-keyword: #7036c4;
     --forgebook-code-type: #0059d2;
     --forgebook-code-string: #077229;
@@ -59,7 +73,7 @@
   .forgebook-matrix__corner,
   .forgebook-matrix__name {
     padding: 0.5rem 0.75rem;
-    font: 400 0.6875rem/1.6 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono-small);
     text-align: start;
     white-space: nowrap;
     opacity: 0.7;
@@ -68,9 +82,28 @@
     padding: 0.75rem;
     vertical-align: middle;
   }
+  .forgebook-frame-pending {
+    margin: 0;
+    padding: 0.5rem 0.75rem;
+    font: var(--forgebook-text-mono-small);
+    color: #fff;
+    background: #8a1c1c;
+  }
   .forgebook-frame-error {
+    --forgebook-focus-edge: inset 0 0 0 1px var(--forgebook-accent);
+    --forgebook-focus-halo: color-mix(in srgb, var(--forgebook-accent) 35%, transparent);
+    --forgebook-text-display: 700 1.375rem/1.2 var(--forgebook-font-sans);
+    --forgebook-text-card-title: 600 0.875rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-body: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    --forgebook-text-row-label: 500 0.8125rem/1.35 var(--forgebook-font-sans);
+    --forgebook-text-row-compact: 400 0.78125rem/1.4 var(--forgebook-font-sans);
+    --forgebook-text-control: 500 0.75rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-caption: 400 0.6875rem/1.35 var(--forgebook-font-sans);
+    --forgebook-text-label: 600 0.6875rem/1.3 var(--forgebook-font-sans);
+    --forgebook-text-mono: 400 0.71875rem/1.4 var(--forgebook-font-mono);
+    --forgebook-text-mono-small: 400 0.6875rem/1.6 var(--forgebook-font-mono);
     margin: 1.5rem;
-    font: 400 0.8125rem/1.4 var(--forgebook-font-sans);
+    font: var(--forgebook-text-body);
     color: var(--forgebook-danger-text);
   }
   .forgebook-frame-error__message {
@@ -80,7 +113,7 @@
   .forgebook-frame-error__stack {
     margin: 0.75rem 0 0;
     overflow-x: auto;
-    font: 400 0.6875rem/1.6 var(--forgebook-font-mono);
+    font: var(--forgebook-text-mono-small);
     color: var(--forgebook-text-secondary);
     white-space: pre;
   }

package/dist/src/frame/frameStatus.d.ts

@@ -3,7 +3,22 @@
  *
  * @module
  */
-/** `ready` once the story rendered and its play function is over, `error` when it could not render. */
+/**
+ * `ready` once the story rendered, what it waits for came and its play function is over; `error` when it could not
+ * render; `pending` when the frame gave up waiting, or cannot tell, so what it shows was not seen in its final state: a
+ * check reads that as not verified, never as passed.
+ */
 export declare const STATUS_ATTRIBUTE = "data-forgebook-status";
+/** The root's attribute that says why the status is `pending`, in a sentence a person reads. */
+export declare const PENDING_REASON_ATTRIBUTE = "data-forgebook-pending-reason";
+/**
+ * The root's attribute set on a story that says it stays in a loading state (`parameters.suspense.expected`): the frame
+ * did not wait for it, and a check says so rather than let a preview turn the wait off unseen.
+ */
+export declare const NOT_AWAITED_ATTRIBUTE = "data-forgebook-not-awaited";
 /** The root's attribute set once the frame's code runs; the page's guard against code that fails earlier reads it. */
 export declare const FRAME_STARTED_ATTRIBUTE = "data-forgebook-started";
+/** The class of the text saying why a frame's story could not be drawn: what a check reports as the reason. */
+export declare const ERROR_MESSAGE_CLASS = "forgebook-frame-error__message";
+/** The class of a thrown error's stack under its message: the dev server's answer rewrites it in the lines as written. */
+export declare const ERROR_STACK_CLASS = "forgebook-frame-error__stack";

package/dist/src/frame/frameStatus.js

@@ -3,7 +3,22 @@
  *
  * @module
  */
-/** `ready` once the story rendered and its play function is over, `error` when it could not render. */
+/**
+ * `ready` once the story rendered, what it waits for came and its play function is over; `error` when it could not
+ * render; `pending` when the frame gave up waiting, or cannot tell, so what it shows was not seen in its final state: a
+ * check reads that as not verified, never as passed.
+ */
 export const STATUS_ATTRIBUTE = "data-forgebook-status";
+/** The root's attribute that says why the status is `pending`, in a sentence a person reads. */
+export const PENDING_REASON_ATTRIBUTE = "data-forgebook-pending-reason";
+/**
+ * The root's attribute set on a story that says it stays in a loading state (`parameters.suspense.expected`): the frame
+ * did not wait for it, and a check says so rather than let a preview turn the wait off unseen.
+ */
+export const NOT_AWAITED_ATTRIBUTE = "data-forgebook-not-awaited";
 /** The root's attribute set once the frame's code runs; the page's guard against code that fails earlier reads it. */
 export const FRAME_STARTED_ATTRIBUTE = "data-forgebook-started";
+/** The class of the text saying why a frame's story could not be drawn: what a check reports as the reason. */
+export const ERROR_MESSAGE_CLASS = "forgebook-frame-error__message";
+/** The class of a thrown error's stack under its message: the dev server's answer rewrites it in the lines as written. */
+export const ERROR_STACK_CLASS = "forgebook-frame-error__stack";

package/dist/src/frame/frameView.js

@@ -4,7 +4,7 @@
  *
  * @module
  */
-import { switchValueOf, switchWithRole } from "../switches.js";
+import { shownSwitches, switchValueOf, switchWithRole } from "../switches.js";
 import { schemeOf } from "../viewState.js";
 import { backdropSheet } from "./backdropPictures.js";
 /** The id of the style sheet that draws the backdrop. */
@@ -96,12 +96,13 @@ const applySwitch = (root, each, value) => {
  * @param catalogue - the catalogue's switches and backdrops.
  */
 export const applyView = (root, view, catalogue) => {
+    const shown = shownSwitches(view.switches, catalogue.switches);
     for (const each of catalogue.switches)
-        applySwitch(root, each, view.switches[each.id]);
+        applySwitch(root, each, shown[each.id]);
     // a language read right to left draws the story right to left; leaving it gives the root its own direction back,
     // unless a switch writes `dir` itself (the direction switch, applied above)
     const language = switchWithRole(catalogue.switches, "language");
-    const isRightToLeft = language !== undefined && switchValueOf(language, view.switches[language.id])?.isRightToLeft === true;
+    const isRightToLeft = language !== undefined && switchValueOf(language, shown[language.id])?.isRightToLeft === true;
     const isDirWritten = catalogue.switches.some((each) => each.apply.kind === "attribute" && each.apply.name === "dir");
     if (isRightToLeft)
         root.setAttribute("dir", "rtl");

package/dist/src/frame/mountFrame.d.ts

@@ -5,7 +5,7 @@
  * @remarks
  * One document per story: the style sheets of the Styles setting, the switches on the root and anything the
  * story mounts on `body` stay in this document. The tests open the same address and wait for `data-forgebook-status`
- * on the root (`ready` or `error`), never for a delay. A Live story's clock runs from its start, or stays held there when
+ * on the root (`ready`, `error` or `pending`), never for a delay. A Live story's clock runs from its start, or stays held there when
  * the address says so (`clock=held`, what the tests open). The framework is the renderer the framework package
  * passes (`renderer.ts`); nothing here depends on one.
  *
@@ -16,9 +16,11 @@ import type { StoryLanguage, StorySource } from "@forgebook/story-format/source"
 import { type CatalogueLists } from "../catalogue.ts";
 import { type FramesPlacement } from "../frameOrigins.ts";
 import { type ViewSwitch } from "../switches.ts";
+import { type ControlFrameLoaders } from "./panelControls.ts";
 import type { PlayToolsLoader } from "./playStory.ts";
 import { type FramePlugin } from "./pluginFrames.ts";
 import type { FrameRenderer } from "./renderer.ts";
+import type { ValueSheets } from "./valueSheets.ts";
 /** What an app passes to the frame. */
 export type FrameConfig = {
     /** The framework that draws the stories (`@forgebook/react` passes its own). */
@@ -36,6 +38,11 @@ export type FrameConfig = {
     readonly previews?: readonly unknown[];
     /** The switches of the toolbar and the View menu, as the shell's configuration gives them; the theme and contrast by default. */
     readonly switches?: readonly ViewSwitch[];
+    /**
+     * The address of each switch value's own style sheet, by `<switch id>=<value>`; none when no value has one. The
+     * generated frame gives addresses the configuration's check allowed; the page checks nothing itself.
+     */
+    readonly valueSheets?: ValueSheets;
     /** The catalogue's lists (its backgrounds, text sizes, grid step, accessibility rules…); the defaults when none. */
     readonly lists?: CatalogueLists;
     /** Loads the play tools, when the project installs Testing Library (the generated frame passes it then). */
@@ -44,6 +51,8 @@ export type FrameConfig = {
     readonly plugins?: readonly FramePlugin[];
     /** Where the frames run, so the frame hears only its shell: on the catalogue's own origin by default. */
     readonly frames?: FramesPlacement;
+    /** The custom controls' frame modules, by control, each loaded when first needed (the generated frame passes them). */
+    readonly argControls?: ControlFrameLoaders;
 };
 /**
  * Shows the story the address names in the given element.