forgebook 0.0.0-stage → 0.1.2

package/dist/src/frame/measureTools.js

@@ -0,0 +1,141 @@
+/** The id of the style sheet that draws the outlines and the grid. */
+const STYLE_ID = "forgebook-measure-style";
+/** The id of the overlay that draws the measured box. */
+const OVERLAY_ID = "forgebook-measure-overlay";
+/**
+ * The sheet for the outline and the grid tools.
+ *
+ * @param tools - the tools drawn.
+ * @param gridStep - the grid's step, in CSS px.
+ */
+const toolSheet = (tools, gridStep) => [
+    tools.includes("outline")
+        ? `body *:not(#root, #${OVERLAY_ID}, #${OVERLAY_ID} *) { ` +
+            "outline: 1px solid rgb(232 62 140 / 0.55) !important; outline-offset: -1px !important; }"
+        : "",
+    tools.includes("grid")
+        ? "#root { background-image: linear-gradient(rgb(23 104 228 / 0.12) 1px, transparent 1px), " +
+            "linear-gradient(90deg, rgb(23 104 228 / 0.12) 1px, transparent 1px) !important; " +
+            `background-size: ${gridStep}px ${gridStep}px !important; }`
+        : ""
+].join("\n");
+/** A length in CSS px, written short. */
+const px = (value) => `${Math.round(value * 10) / 10}`;
+/** The overlay of the measured box, made once. */
+const overlayOf = (document) => {
+    const existing = document.getElementById(OVERLAY_ID);
+    if (existing !== null)
+        return existing;
+    const overlay = document.createElement("div");
+    overlay.id = OVERLAY_ID;
+    overlay.setAttribute("aria-hidden", "true");
+    Object.assign(overlay.style, {
+        position: "fixed",
+        zIndex: "2147483647",
+        pointerEvents: "none",
+        boxSizing: "border-box",
+        display: "none"
+    });
+    document.body.append(overlay);
+    return overlay;
+};
+/** Draws an element's box on the overlay: its padding and margin shaded, its size in a label. */
+const drawBox = (overlay, element) => {
+    const view = element.ownerDocument.defaultView;
+    if (view === null)
+        return;
+    const rect = element.getBoundingClientRect();
+    const style = view.getComputedStyle(element);
+    const sides = ["top", "right", "bottom", "left"];
+    const lengths = (property) => sides.map((side) => Number.parseFloat(style.getPropertyValue(`${property}-${side}`)) || 0);
+    const margin = lengths("margin");
+    const padding = lengths("padding");
+    const [mt = 0, mr = 0, mb = 0, ml = 0] = margin;
+    const [pt = 0, pr = 0, pb = 0, pl = 0] = padding;
+    Object.assign(overlay.style, {
+        display: "block",
+        left: `${rect.left - ml}px`,
+        top: `${rect.top - mt}px`,
+        width: `${rect.width + ml + mr}px`,
+        height: `${rect.height + mt + mb}px`,
+        // the margin in orange, the padding in green, the content in blue: the colours browsers' inspectors use
+        borderStyle: "solid",
+        borderColor: "rgb(246 178 107 / 0.5)",
+        borderWidth: `${mt}px ${mr}px ${mb}px ${ml}px`,
+        background: "rgb(147 196 125 / 0.45)",
+        backgroundClip: "padding-box"
+    });
+    overlay.innerHTML = "";
+    const content = overlay.ownerDocument.createElement("div");
+    Object.assign(content.style, {
+        position: "absolute",
+        left: `${pl}px`,
+        top: `${pt}px`,
+        right: `${pr}px`,
+        bottom: `${pb}px`,
+        background: "rgb(111 168 220 / 0.55)"
+    });
+    const label = overlay.ownerDocument.createElement("div");
+    label.textContent = `${px(rect.width)} × ${px(rect.height)}`;
+    Object.assign(label.style, {
+        position: "absolute",
+        left: "0",
+        top: rect.top - mt >= 20 ? "-20px" : "100%",
+        padding: "1px 5px",
+        borderRadius: "3px",
+        background: "#1d1d1f",
+        color: "#fff",
+        font: "500 11px/16px ui-monospace, SFMono-Regular, Menlo, monospace",
+        whiteSpace: "nowrap"
+    });
+    overlay.append(content, label);
+};
+/** Stops measuring: the listener a call of `applyTools` added, if any. */
+let stopMeasuring;
+/**
+ * Draws the tools over the story, replacing the ones drawn before.
+ *
+ * @param document - the frame's document.
+ * @param tools - the tools to draw; none removes them all.
+ * @param gridStep - the grid's step, in CSS px; 8 by default.
+ */
+export const applyTools = (document, tools, gridStep = 8) => {
+    const sheet = toolSheet(tools, gridStep);
+    let style = document.getElementById(STYLE_ID);
+    if (style === null) {
+        style = document.createElement("style");
+        style.id = STYLE_ID;
+        document.head.append(style);
+    }
+    style.textContent = sheet;
+    stopMeasuring?.();
+    stopMeasuring = undefined;
+    const overlay = overlayOf(document);
+    overlay.style.display = "none";
+    if (!tools.includes("measure"))
+        return;
+    const measure = (event) => {
+        const target = event.target instanceof Element ? event.target : null;
+        // the story's elements and its portals: anything in the body but the root itself and the overlay
+        const isStoryElement = target !== null &&
+            target !== document.body &&
+            target.id !== "root" &&
+            document.body.contains(target) &&
+            !overlay.contains(target);
+        if (!isStoryElement) {
+            overlay.style.display = "none";
+            return;
+        }
+        drawBox(overlay, target);
+    };
+    const hide = () => {
+        overlay.style.display = "none";
+    };
+    document.addEventListener("pointermove", measure);
+    document.addEventListener("pointerleave", hide);
+    stopMeasuring = () => {
+        document.removeEventListener("pointermove", measure);
+        document.removeEventListener("pointerleave", hide);
+    };
+};
+//# sourceMappingURL=measureTools.js.map

package/dist/src/frame/measureTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measureTools.js","sourceRoot":"","sources":["../../../src/frame/measureTools.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,47 @@
+/**
+ * The entry of a story's frame: reads the story and the view from the address, loads the source's style sheets for
+ * the view, then has the framework draw the story and, once its play function is over, tells the shell it is ready.
+ *
+ * @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
+ * 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.
+ *
+ * @module
+ */
+import "./frame.scss";
+import type { StoryLanguage, StorySource } from "@forgebook/story-format/source";
+import { type CatalogueLists } from "../catalogue.ts";
+import { type ViewSwitch } from "../switches.ts";
+import type { PlayToolsLoader } from "./playStory.ts";
+import type { StoryRenderer } from "./renderer.ts";
+/** What an app passes to the frame. */
+export type FrameConfig = {
+    /** The framework that draws the stories (`@forgebook/react` passes its own). */
+    readonly renderer: StoryRenderer;
+    /** The sources the shell shows, in the same order. */
+    readonly sources: readonly StorySource[];
+    /** The languages every story can be drawn in, as the shell's configuration gives them; none turns them off. */
+    readonly languages?: readonly StoryLanguage[];
+    /**
+     * The catalogue's previews, as their modules: its presets' first, its own last (`forgebook.preview.ts`). Their
+     * decorators wrap every story, their parameters sit under every meta's, their setups run before any story renders.
+     */
+    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 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). */
+    readonly playTools?: PlayToolsLoader;
+};
+/**
+ * Shows the story the address names in the given element.
+ *
+ * @param container - the element the story renders into.
+ * @param config - the sources.
+ */
+export declare const mountFrame: (container: HTMLElement, config: FrameConfig) => Promise<void>;
+//# sourceMappingURL=mountFrame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mountFrame.d.ts","sourceRoot":"","sources":["../../../src/frame/mountFrame.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAIjF,OAAO,EAAqB,KAAK,cAAc,EAAqB,MAAM,iBAAiB,CAAC;AAiB5F,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAOpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,eAAe,CAAC;AAKjE,uCAAuC;AACvC,MAAM,MAAM,WAAW,GAAG;IACxB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,+GAA+G;IAC/G,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACvC,iIAAiI;IACjI,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC1C,oHAAoH;IACpH,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,4GAA4G;IAC5G,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;CACtC,CAAC;AA0CF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAU,WAAW,WAAW,EAAE,QAAQ,WAAW,KAAG,OAAO,CAAC,IAAI,CAqJ1F,CAAC"}

package/dist/src/frame/mountFrame.js

@@ -0,0 +1,229 @@
+/**
+ * The entry of a story's frame: reads the story and the view from the address, loads the source's style sheets for
+ * the view, then has the framework draw the story and, once its play function is over, tells the shell it is ready.
+ *
+ * @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
+ * 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.
+ *
+ * @module
+ */
+import "./frame.css";
+import { storyTextOf } from "@forgebook/story-format/texts";
+import { actionNames, excludedControls, panelArgTypesOf } from "../argTypes.js";
+import { catalogueSettings } from "../catalogue.js";
+import { shownLanguage } from "../languages.js";
+import { detailOf, isShellMessage, previewValue } from "../messages.js";
+import { panelArgsOf, storyArgsOf } from "../namedValues.js";
+import { sourceFiles } from "../sourceFiles.js";
+import { isClockHeldIn } from "../storyClock.js";
+import { fixedViewOf, NOT_FIXED, withFixed } from "../storyGlobals.js";
+import { shownTexts, storyTextKeysOf, withStoryTexts } from "../storyTexts.js";
+import { findStory, storyTree } from "../storyTree.js";
+import { catalogueSwitches } from "../switches.js";
+import { codeGlobalsOf, frameAddress, languageOf, parseView } from "../viewState.js";
+import { checkStory } from "./checkStory.js";
+import { storyFrameClock } from "./frameClock.js";
+import { STATUS_ATTRIBUTE } from "./frameStatus.js";
+import { applyView, loadSheets, viewSheets } from "./frameView.js";
+import { applyTools } from "./measureTools.js";
+import { clearRetry, isStaleModuleError, markRetry, sessionStorageOf } from "./staleModule.js";
+import { mergedPreviews, readPreview, readStory } from "./storyModule.js";
+import { runStory } from "./storyRun.js";
+/** Tells the shell, which is the parent page on the same origin. */
+const tellShell = (message) => {
+    if (window.parent !== window)
+        window.parent.postMessage(message, window.location.origin);
+};
+/**
+ * Does what a message of the shell asks of the rendered story; the view's live part is applied apart, before the story
+ * loads.
+ *
+ * @param message - the message.
+ * @param controls - the rendered story's controls.
+ * @param storyId - the story's id, for the answers.
+ * @param rules - the catalogue's accessibility rules, for a check.
+ */
+const answerShell = (message, controls, storyId, rules) => {
+    if (message.type === "forgebook:replay")
+        void controls.replay();
+    else if (message.type === "forgebook:args")
+        controls.setPanelArgs(message.args);
+    else if (message.type === "forgebook:events")
+        controls.setEvents(message.names);
+    else if (message.type === "forgebook:matrix")
+        controls.setMatrix(message.matrix ?? undefined);
+    else if (message.type === "forgebook:play-again")
+        controls.playAgain();
+    else if (message.type === "forgebook:clock")
+        controls.setClock(message.state);
+    else if (message.type === "forgebook:clock-restart")
+        controls.restartClock();
+    else if (message.type === "forgebook:check") {
+        checkStory(document, rules)
+            .then((violations) => tellShell({ type: "forgebook:checked", storyId, violations }))
+            .catch((error) => tellShell({
+            type: "forgebook:check-error",
+            storyId,
+            message: error instanceof Error ? error.message : String(error)
+        }));
+    }
+};
+/**
+ * Shows the story the address names in the given element.
+ *
+ * @param container - the element the story renders into.
+ * @param config - the sources.
+ */
+export const mountFrame = async (container, config) => {
+    const params = new URLSearchParams(window.location.search);
+    const storyId = params.get("story") ?? "";
+    const languages = config.languages ?? [];
+    const switches = catalogueSwitches(config.switches, languages);
+    const catalogue = catalogueSettings("", switches, config.lists);
+    const preview = mergedPreviews((config.previews ?? []).map(readPreview));
+    const view = parseView(window.location.search, catalogue);
+    applyView(document.documentElement, view, catalogue);
+    // what the story fixes of the view, once it is read: every view the frame applies has it over the shell's
+    let fixed = NOT_FIXED;
+    // set once the story runs: a view the shell sends then changes its language and its globals without a new mount
+    let changeShown;
+    // the shell sends the live part of a changed view: applied on the root, and kept in the address so a reload (an
+    // edit, a stale module) shows the same view
+    window.addEventListener("message", (event) => {
+        if (event.origin !== window.location.origin || !isShellMessage(event.data))
+            return;
+        if (event.data.type === "forgebook:tools")
+            applyTools(document, event.data.tools, catalogue.gridStep);
+        if (event.data.type !== "forgebook:view")
+            return;
+        applyView(document.documentElement, withFixed(event.data.view, fixed), catalogue);
+        changeShown?.(event.data.view);
+        const address = frameAddress(window.location.pathname, storyId, { ...view, ...event.data.view }, switches);
+        window.history.replaceState(null, "", address);
+    });
+    // observed from the start, so the shell sizes the frame to an error as well as to a story
+    const reportSize = () => {
+        // the body's own height: the root's scroll height never drops below the frame's, so a story could not shrink
+        const height = Math.ceil(document.body.getBoundingClientRect().height);
+        tellShell({ type: "forgebook:size", storyId, height });
+    };
+    new ResizeObserver(reportSize).observe(document.body);
+    const reportError = (message) => {
+        document.documentElement.setAttribute(STATUS_ATTRIBUTE, "error");
+        tellShell({ type: "forgebook:error", storyId, message });
+    };
+    const fail = (message) => {
+        const box = document.createElement("div");
+        box.className = "forgebook-frame-error";
+        box.setAttribute("role", "alert");
+        const text = document.createElement("p");
+        text.className = "forgebook-frame-error__message";
+        text.textContent = message;
+        box.append(text);
+        container.replaceChildren(box);
+        reportError(message);
+    };
+    const location = findStory(storyTree(config.sources), storyId);
+    const source = config.sources.find((candidate) => candidate.id === location?.source.id);
+    const load = location === undefined || source === undefined
+        ? undefined
+        : sourceFiles(source).stories[location.component.file];
+    if (location === undefined || source === undefined || load === undefined) {
+        fail(`No story "${storyId}"`);
+        return;
+    }
+    try {
+        await source.setup?.();
+        await preview.setup?.();
+        await loadSheets(document, viewSheets(source.sheets, view));
+        const story = readStory(await load(), location.story.exportName, preview);
+        if (typeof story === "string") {
+            fail(story);
+            return;
+        }
+        fixed = fixedViewOf(story.globals, story.parameters, catalogue);
+        applyView(document.documentElement, withFixed(view, fixed), catalogue);
+        let controls;
+        const clock = storyFrameClock(story.clockStart, isClockHeldIn(window.location.search));
+        window.addEventListener("message", (event) => {
+            if (event.origin !== window.location.origin || !isShellMessage(event.data))
+                return;
+            if (controls !== undefined)
+                answerShell(event.data, controls, storyId, catalogue.a11y);
+        });
+        // the language's texts, and the switches the story reads (the language's provider reads its id among them)
+        const shownFor = (live) => {
+            const switchesShown = { switches: { ...live.switches, ...fixed.switches } };
+            return {
+                texts: shownTexts(source.texts, shownLanguage(languages, languageOf(switchesShown, switches))),
+                globals: codeGlobalsOf(switchesShown, switches)
+            };
+        };
+        const shown = shownFor(view);
+        const { texts } = shown;
+        const running = runStory({
+            container,
+            story,
+            identity: { id: storyId, name: location.story.name, title: location.component.title },
+            ...(config.playTools === undefined ? {} : { playTools: config.playTools }),
+            renderer: config.renderer,
+            clock,
+            decorators: preview.decorators,
+            ...shown,
+            resolveArgs: (args) => storyArgsOf(args, source.namedValues),
+            onControlsReady: (next) => {
+                controls = next;
+                clearRetry(sessionStorageOf(window), window.location.href);
+                // the height first: the shell sizes the frame to the drawn story before anything reads it as ready, instead of
+                // waiting on the resize observer, which may report after the ready status
+                reportSize();
+                document.documentElement.setAttribute(STATUS_ATTRIBUTE, "ready");
+                // the panel shows a text an arg names as the story shows it, with its key beside it
+                const args = panelArgsOf(withStoryTexts(story.args, storyTextOf(texts)), source.namedValues);
+                const textKeys = storyTextKeysOf(story.args);
+                tellShell({
+                    type: "forgebook:ready",
+                    storyId,
+                    canReplay: story.replay !== undefined,
+                    hasClock: story.clockStart !== undefined,
+                    args,
+                    textKeys,
+                    argTypes: panelArgTypesOf(story.argTypes, excludedControls(story.parameters["controls"])),
+                    controls: story.controls,
+                    actions: actionNames(story.args, story.argTypes),
+                    fixed
+                });
+                changeShown = (live) => running.setShown(shownFor(live));
+            },
+            onError: reportError,
+            onTrace: (trace) => tellShell({ type: "forgebook:play", storyId, trace }),
+            onEvent: (name, values) => tellShell({
+                type: "forgebook:call",
+                storyId,
+                name,
+                values: values.map(previewValue),
+                details: values.map(detailOf)
+            })
+        });
+        // the shell opens another story by loading another page: the set-ups' cleanups run as this one goes (a page kept
+        // for the back button keeps its story)
+        window.addEventListener("pagehide", (event) => {
+            if (!event.persisted)
+                running.leave();
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // a stale module (dependencies prepared again, a new build): one reload fetches the new one
+        if (isStaleModuleError(message) && markRetry(sessionStorageOf(window), window.location.href)) {
+            window.location.reload();
+            return;
+        }
+        fail(message);
+    }
+};
+//# sourceMappingURL=mountFrame.js.map

package/dist/src/frame/mountFrame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mountFrame.js","sourceRoot":"","sources":["../../../src/frame/mountFrame.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,40 @@
+/**
+ * Runs a story's play function, records its trace, and says when it is over, so the frame tells the tests it is
+ * ready only then.
+ *
+ * @remarks
+ * A play may change the story over time (press buttons, wait for a state); a check that ran before it finished would
+ * read a half-played story. The frame's ready status therefore waits for this. A play that fails is still over: the
+ * frame becomes ready and the failure surfaces as an unhandled rejection, which the tests record as a page error.
+ * The trace (the play's status, its time, each `step` it named) goes to the shell's Interactions tab after every
+ * change; a story without a play has no trace.
+ *
+ * @module
+ */
+import type { StoryContext } from "@forgebook/story-format/csf";
+import type { PlayTrace } from "../playTrace.ts";
+import type { LoadedArgs, LoadedStory } from "./storyModule.ts";
+/** The play tools a project's Testing Library gives, as the frame uses them without depending on it. */
+export type PlayTools = {
+    /** Testing Library's `within`: its queries bound to an element. */
+    readonly within: (element: HTMLElement) => unknown;
+    /** Testing Library's `userEvent`. */
+    readonly userEvent: unknown;
+};
+/**
+ * Loads the play tools, on the first play that runs: a catalogue whose stories have no play never loads them. The
+ * generated frame passes one when the project installs Testing Library.
+ */
+export type PlayToolsLoader = () => Promise<PlayTools>;
+/**
+ * Plays a story, then calls `onPlayed`.
+ *
+ * @param play - the story's play function, if it has one.
+ * @param context - the args and the canvas the play reads; the play's `step` is added here.
+ * @param onPlayed - called once the play is over, at once when there is none, whether it passed or failed.
+ * @param onTrace - called with the trace after every change; never without a play.
+ * @param tools - the play tools to hand the play (`canvas` bound to its canvas, `userEvent`); none without them.
+ * @returns the play's promise, rejected when the play failed.
+ */
+export declare const playStory: (play: LoadedStory["play"], context: Omit<StoryContext<LoadedArgs>, "step">, onPlayed: () => void, onTrace?: (trace: PlayTrace) => void, tools?: PlayTools | undefined) => Promise<void>;
+//# sourceMappingURL=playStory.d.ts.map

package/dist/src/frame/playStory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playStory.d.ts","sourceRoot":"","sources":["../../../src/frame/playStory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE9E,OAAO,KAAK,EAAY,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQhE,wGAAwG;AACxG,MAAM,MAAM,SAAS,GAAG;IACtB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC;IACnD,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;AAEvD;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,GACpB,MAAM,WAAW,CAAC,MAAM,CAAC,EACzB,SAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,EAC/C,UAAU,MAAM,IAAI,EACpB,UAAS,CAAC,KAAK,EAAE,SAAS,KAAK,IAA4B,EAC3D,QAAO,SAAS,GAAG,SAAqB,KACvC,OAAO,CAAC,IAAI,CAqCd,CAAC"}

package/dist/src/frame/playStory.js

@@ -0,0 +1,55 @@
+/** A thrown value's message. */
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+/** Milliseconds since an instant, rounded. */
+const since = (start) => Math.round(performance.now() - start);
+/**
+ * Plays a story, then calls `onPlayed`.
+ *
+ * @param play - the story's play function, if it has one.
+ * @param context - the args and the canvas the play reads; the play's `step` is added here.
+ * @param onPlayed - called once the play is over, at once when there is none, whether it passed or failed.
+ * @param onTrace - called with the trace after every change; never without a play.
+ * @param tools - the play tools to hand the play (`canvas` bound to its canvas, `userEvent`); none without them.
+ * @returns the play's promise, rejected when the play failed.
+ */
+export const playStory = async (play, context, onPlayed, onTrace = () => undefined, tools = undefined) => {
+    if (play === undefined) {
+        onPlayed();
+        return;
+    }
+    let steps = [];
+    const report = (trace) => onTrace({ ...trace, steps });
+    const setStep = (index, step) => {
+        steps = steps.map((current, at) => (at === index ? step : current));
+        report({ status: "running" });
+    };
+    const step = async (label, run) => {
+        const index = steps.length;
+        const start = performance.now();
+        steps = [...steps, { label, status: "running" }];
+        report({ status: "running" });
+        try {
+            await run();
+            setStep(index, { label, status: "passed", ms: since(start) });
+        }
+        catch (error) {
+            setStep(index, { label, status: "failed", ms: since(start), error: messageOf(error) });
+            throw error;
+        }
+    };
+    const start = performance.now();
+    report({ status: "running" });
+    try {
+        const toolsContext = tools === undefined ? {} : { canvas: tools.within(context.canvasElement), userEvent: tools.userEvent };
+        await play({ ...context, step, ...toolsContext });
+        report({ status: "passed", ms: since(start) });
+    }
+    catch (error) {
+        report({ status: "failed", ms: since(start), error: messageOf(error) });
+        throw error;
+    }
+    finally {
+        onPlayed();
+    }
+};
+//# sourceMappingURL=playStory.js.map

package/dist/src/frame/playStory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playStory.js","sourceRoot":"","sources":["../../../src/frame/playStory.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,85 @@
+/**
+ * The contract between Forgebook and a framework: how the frame draws one story in one canvas, draws it again with
+ * other args and takes it away, and how the shell writes a story drawn from its args as code.
+ *
+ * @remarks
+ * The frame owns everything a framework does not need to know: the address and the view, the messages with the
+ * shell, the style sheets, the play function, Replay, the matrix's layout, the story clock and the error shown in
+ * place of a story. A framework package (`@forgebook/react`) implements this type and hands it to the frame; another
+ * framework implements the same type. A story's decorators, providers and error capture are the framework's, since
+ * they return or catch the framework's own output.
+ *
+ * @module
+ */
+import type { StoryClock } from "@forgebook/story-format/clock";
+import type { StepFunction, StoryContext } from "@forgebook/story-format/csf";
+import type { StoryTextTable } from "@forgebook/story-format/texts";
+import type { PanelArgs } from "../messages.ts";
+import type { LoadedArgs, LoadedDecorator, LoadedStory } from "./storyModule.ts";
+/** Which story is drawn: its id, its name and its file's title, as its context gives them. */
+export type StoryIdentity = Pick<StoryContext<LoadedArgs>, "id" | "name" | "title">;
+/** One story to draw, as the frame hands it to the framework. */
+export type StoryDrawing = {
+    /** Which story it is. */
+    readonly identity: StoryIdentity;
+    /** The story: its render or component, its decorators, its layout. */
+    readonly story: LoadedStory;
+    /** The args as the story receives them: the texts named by key resolved, the recorded events wrapped. */
+    readonly args: LoadedArgs;
+    /** The texts inside the stories in the shown language, for the story's `text` and its text hooks. */
+    readonly texts: StoryTextTable;
+    /** The story clock the story reads (held at its start, or running for a Live story). */
+    readonly clock: StoryClock;
+    /**
+     * The catalogue's decorators (its preview's), outside the meta's and the story's own: the providers every story
+     * is drawn in, the language's among them (it reads `context.globals.lang`).
+     */
+    readonly decorators: readonly LoadedDecorator[];
+    /** The values of the switches applied by code, by id: the story's `context.globals`. */
+    readonly globals: Readonly<Record<string, string>>;
+    /** What the story's loaders returned: its `context.loaded`. */
+    readonly loaded: Readonly<Record<string, unknown>>;
+};
+/** What the frame keeps of a story drawn in a canvas. */
+export type MountedStory = {
+    /**
+     * Resolves once the story is drawn in its canvas, so the play function finds what it drives; never resolves when the
+     * story throws while it is first drawn (the error goes to `onError` instead).
+     */
+    readonly drawn: Promise<void>;
+    /**
+     * Draws the story again, keeping its state: other args, other switch values, another language; a story that threw
+     * is tried again.
+     */
+    readonly update: (drawing: StoryDrawing) => void;
+    /** Takes the story away from its canvas. */
+    readonly unmount: () => void;
+};
+/** A framework, as the frame uses it. */
+export type StoryRenderer = {
+    /**
+     * Draws a story in a canvas the frame owns.
+     *
+     * @param canvas - the element the story is drawn in.
+     * @param drawing - the story, its args, texts, clock and language.
+     * @param onError - called with the error when the story throws while it is drawn; the frame shows it instead.
+     */
+    readonly mount: (canvas: HTMLElement, drawing: StoryDrawing, onError: (error: Error) => void) => MountedStory;
+    /**
+     * The story drawn as HTML on the server, for the generated server tests; throws when the story throws.
+     *
+     * @param drawing - the story, its args, texts, clock and language.
+     */
+    readonly renderToString: (drawing: StoryDrawing) => string;
+};
+/**
+ * Writes a story drawn from its args as the framework's code, for the Code tab and Show code (`<Button tone="danger" />`
+ * in React): the shell knows the component's name and the panel's values, and the framework knows its syntax.
+ *
+ * @param component - the component's name, as its documentation names it.
+ * @param args - the values of the moment, a named value by its name.
+ */
+export type StoryCodeWriter = (component: string, args: PanelArgs) => string;
+/** The `step` a render and a decorator receive: outside a play there is no trace, so a step only runs its part. */
+export declare const untracedStep: StepFunction;
+//# sourceMappingURL=renderer.d.ts.map