forgebook 0.0.0-stage → 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/frame/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEjF,8FAA8F;AAC9F,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEpF,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG;IACzB,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,qGAAqG;IACrG,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACpD,CAAC;AAEF,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG;IACzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IACjD,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAC5B,YAAY,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,MAAM,CAAC;CAC5D,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC;AAE7E,mHAAmH;AACnH,eAAO,MAAM,YAAY,EAAE,YAK1B,CAAC"}

package/dist/src/frame/renderer.js

@@ -0,0 +1,18 @@
+/**
+ * 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
+ */
+/** The `step` a render and a decorator receive: outside a play there is no trace, so a step only runs its part. */
+export const untracedStep = async (_label, run) => {
+    await run();
+};
+//# sourceMappingURL=renderer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../../src/frame/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkFH,mHAAmH;AACnH,MAAM,CAAC,MAAM,YAAY,GAAiB,KAAK,EAC7C,MAAc,EACd,GAA+B,EAChB,EAAE;IACjB,MAAM,GAAG,EAAE,CAAC;AACd,CAAC,CAAC"}

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

@@ -0,0 +1,24 @@
+/**
+ * Waiting for a story's animations to end, for the Replay control's exit.
+ *
+ * @remarks
+ * An endless animation (a loading shimmer, a spinner) never finishes, so waiting for every animation of the document
+ * would never return: only the animations with an end are awaited.
+ *
+ * @module
+ */
+/** An animation as the wait reads it: its timing, and the promise of its end. */
+export type SettlingAnimation = Pick<Animation, "effect" | "finished">;
+/**
+ * The animations that end: every one but the endless ones.
+ *
+ * @param animations - the document's animations.
+ */
+export declare const endingAnimations: <TAnimation extends SettlingAnimation>(animations: readonly TAnimation[]) => TAnimation[];
+/**
+ * Resolves once every animation of the document that ends has finished or been cancelled, a frame after the call.
+ *
+ * @param document - the frame's document.
+ */
+export declare const animationsSettled: (document: Document) => Promise<void>;
+//# sourceMappingURL=settle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../../src/frame/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,UAAU,CAAC,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,UAAU,SAAS,iBAAiB,EACnE,YAAY,SAAS,UAAU,EAAE,KAChC,UAAU,EAA6F,CAAC;AAE3G;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAU,UAAU,QAAQ,KAAG,OAAO,CAAC,IAAI,CAGxE,CAAC"}

package/dist/src/frame/settle.js

@@ -0,0 +1,25 @@
+/**
+ * Waiting for a story's animations to end, for the Replay control's exit.
+ *
+ * @remarks
+ * An endless animation (a loading shimmer, a spinner) never finishes, so waiting for every animation of the document
+ * would never return: only the animations with an end are awaited.
+ *
+ * @module
+ */
+/**
+ * The animations that end: every one but the endless ones.
+ *
+ * @param animations - the document's animations.
+ */
+export const endingAnimations = (animations) => animations.filter((animation) => animation.effect?.getTiming().iterations !== Infinity);
+/**
+ * Resolves once every animation of the document that ends has finished or been cancelled, a frame after the call.
+ *
+ * @param document - the frame's document.
+ */
+export const animationsSettled = async (document) => {
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+    await Promise.allSettled(endingAnimations(document.getAnimations()).map((animation) => animation.finished));
+};
+//# sourceMappingURL=settle.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"settle.js","sourceRoot":"","sources":["../../../src/frame/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,UAAiC,EACnB,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC;AAE3G;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,QAAkB,EAAiB,EAAE;IAC3E,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/D,MAAM,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC9G,CAAC,CAAC"}

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

@@ -0,0 +1,40 @@
+/**
+ * A frame's one retry when its story's module is stale: after the dev server prepared its dependencies again (a new
+ * dependency arrived) or a new build replaced the files, a dynamic import of the old module fails, and reloading the
+ * frame fetches the new one.
+ *
+ * @remarks
+ * The frame reloads once per address; the mark lives in `sessionStorage`, so a second failure shows the error instead
+ * of reloading forever. Where the storage is unavailable (a private window, blocked site data) the frame does not
+ * retry and shows the error.
+ *
+ * @module
+ */
+/**
+ * Whether an error message is a dynamic import that failed to load.
+ *
+ * @param message - the error's message.
+ */
+export declare const isStaleModuleError: (message: string) => boolean;
+/**
+ * Marks an address as retried, unless it already is.
+ *
+ * @param storage - the session storage, or `undefined` where it is unavailable.
+ * @param address - the frame's address.
+ * @returns whether the frame should reload: `false` when it already did, or when there is nowhere to remember it.
+ */
+export declare const markRetry: (storage: Storage | undefined, address: string) => boolean;
+/**
+ * Forgets an address's retry once its story rendered, so a later stale module gets its retry too.
+ *
+ * @param storage - the session storage, or `undefined` where it is unavailable.
+ * @param address - the frame's address.
+ */
+export declare const clearRetry: (storage: Storage | undefined, address: string) => void;
+/**
+ * The window's session storage, or `undefined` where reading it throws.
+ *
+ * @param target - the frame's window.
+ */
+export declare const sessionStorageOf: (target: Window) => Storage | undefined;
+//# sourceMappingURL=staleModule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"staleModule.d.ts","sourceRoot":"","sources":["../../../src/frame/staleModule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,OACW,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,OAAO,GAAG,SAAS,EAAE,SAAS,MAAM,KAAG,OASzE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,OAAO,GAAG,SAAS,EAAE,SAAS,MAAM,KAAG,IAM1E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,OAAO,GAAG,SAM3D,CAAC"}

package/dist/src/frame/staleModule.js

@@ -0,0 +1,74 @@
+/**
+ * A frame's one retry when its story's module is stale: after the dev server prepared its dependencies again (a new
+ * dependency arrived) or a new build replaced the files, a dynamic import of the old module fails, and reloading the
+ * frame fetches the new one.
+ *
+ * @remarks
+ * The frame reloads once per address; the mark lives in `sessionStorage`, so a second failure shows the error instead
+ * of reloading forever. Where the storage is unavailable (a private window, blocked site data) the frame does not
+ * retry and shows the error.
+ *
+ * @module
+ */
+/** How each engine words a dynamic import that failed to load: Chromium, Firefox, WebKit. */
+const STALE_MODULE_MESSAGES = [
+    "Failed to fetch dynamically imported module",
+    "error loading dynamically imported module",
+    "Importing a module script failed"
+];
+/** The key of a frame address's retry mark. */
+const markKey = (address) => `forgebook:reloaded:${address}`;
+/**
+ * Whether an error message is a dynamic import that failed to load.
+ *
+ * @param message - the error's message.
+ */
+export const isStaleModuleError = (message) => STALE_MODULE_MESSAGES.some((stale) => message.includes(stale));
+/**
+ * Marks an address as retried, unless it already is.
+ *
+ * @param storage - the session storage, or `undefined` where it is unavailable.
+ * @param address - the frame's address.
+ * @returns whether the frame should reload: `false` when it already did, or when there is nowhere to remember it.
+ */
+export const markRetry = (storage, address) => {
+    if (storage === undefined)
+        return false;
+    try {
+        if (storage.getItem(markKey(address)) !== null)
+            return false;
+        storage.setItem(markKey(address), "1");
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Forgets an address's retry once its story rendered, so a later stale module gets its retry too.
+ *
+ * @param storage - the session storage, or `undefined` where it is unavailable.
+ * @param address - the frame's address.
+ */
+export const clearRetry = (storage, address) => {
+    try {
+        storage?.removeItem(markKey(address));
+    }
+    catch {
+        // nothing to forget where the storage refuses access
+    }
+};
+/**
+ * The window's session storage, or `undefined` where reading it throws.
+ *
+ * @param target - the frame's window.
+ */
+export const sessionStorageOf = (target) => {
+    try {
+        return target.sessionStorage;
+    }
+    catch {
+        return undefined;
+    }
+};
+//# sourceMappingURL=staleModule.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"staleModule.js","sourceRoot":"","sources":["../../../src/frame/staleModule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,6FAA6F;AAC7F,MAAM,qBAAqB,GAAG;IAC5B,6CAA6C;IAC7C,2CAA2C;IAC3C,kCAAkC;CACnC,CAAC;AAEF,+CAA+C;AAC/C,MAAM,OAAO,GAAG,CAAC,OAAe,EAAU,EAAE,CAAC,sBAAsB,OAAO,EAAE,CAAC;AAE7E;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAe,EAAW,EAAE,CAC7D,qBAAqB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAA4B,EAAE,OAAe,EAAW,EAAE;IAClF,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC7D,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAA4B,EAAE,OAAe,EAAQ,EAAE;IAChF,IAAI,CAAC;QACH,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,qDAAqD;IACvD,CAAC;AACH,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAc,EAAuB,EAAE;IACtE,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,cAAc,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC,CAAC"}

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

@@ -0,0 +1,21 @@
+/**
+ * The element a story is drawn in, as the frame prepares it for any framework: its layout and the states it forces.
+ *
+ * @module
+ */
+import type { LoadedStory } from "./storyModule.ts";
+/**
+ * A new canvas for the story alone: padded, centred or the whole frame, with its forced states.
+ *
+ * @param document - the frame's document.
+ * @param story - the story.
+ */
+export declare const storyCanvas: (document: Document, story: LoadedStory) => HTMLElement;
+/**
+ * Sets the attribute that forces the story's states on an element, when it forces any.
+ *
+ * @param element - the story's canvas, or a cell of its matrix.
+ * @param story - the story.
+ */
+export declare const forceStates: (element: HTMLElement, story: LoadedStory) => void;
+//# sourceMappingURL=storyCanvas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storyCanvas.d.ts","sourceRoot":"","sources":["../../../src/frame/storyCanvas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,QAAQ,EAAE,OAAO,WAAW,KAAG,WAMpE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,WAAW,EAAE,OAAO,WAAW,KAAG,IAEtE,CAAC"}

package/dist/src/frame/storyCanvas.js

@@ -0,0 +1,30 @@
+/**
+ * The element a story is drawn in, as the frame prepares it for any framework: its layout and the states it forces.
+ *
+ * @module
+ */
+import { FORCE_ATTRIBUTE } from "../vite/forcedStates.js";
+/**
+ * A new canvas for the story alone: padded, centred or the whole frame, with its forced states.
+ *
+ * @param document - the frame's document.
+ * @param story - the story.
+ */
+export const storyCanvas = (document, story) => {
+    const canvas = document.createElement("div");
+    canvas.className = "forgebook-frame";
+    canvas.dataset["layout"] = story.layout;
+    forceStates(canvas, story);
+    return canvas;
+};
+/**
+ * Sets the attribute that forces the story's states on an element, when it forces any.
+ *
+ * @param element - the story's canvas, or a cell of its matrix.
+ * @param story - the story.
+ */
+export const forceStates = (element, story) => {
+    if (story.forceState.length > 0)
+        element.setAttribute(FORCE_ATTRIBUTE, story.forceState.join(" "));
+};
+//# sourceMappingURL=storyCanvas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storyCanvas.js","sourceRoot":"","sources":["../../../src/frame/storyCanvas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAkB,EAAE,KAAkB,EAAe,EAAE;IACjF,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,CAAC,SAAS,GAAG,iBAAiB,CAAC;IACrC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;IACxC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAoB,EAAE,KAAkB,EAAQ,EAAE;IAC5E,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,YAAY,CAAC,eAAe,EAAE,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrG,CAAC,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * What runs before a story is drawn, as CSF orders it: its loaders, then its set-ups (`beforeEach`), each set-up's
+ * cleanup kept to run when the story is mounted again or left. The frame and the server tests prepare a story the same
+ * way.
+ *
+ * @remarks
+ * The loaders run at once and their results merge in their order (the preview's, the meta's, the story's: a later key
+ * wins); the set-ups run one after another, after the loaders, and see what they loaded. A set-up that throws undoes
+ * the ones before it, so a failed story leaves nothing behind.
+ *
+ * @module
+ */
+import type { StoryHookContext } from "@forgebook/story-format/csf";
+import type { LoadedArgs, LoadedStory } from "./storyModule.ts";
+/** A story ready to be drawn: what its loaders returned, and how to undo its set-ups. */
+export type PreparedStory = {
+    /** What the loaders returned, merged: the story's `context.loaded`. */
+    readonly loaded: Readonly<Record<string, unknown>>;
+    /** Runs the set-ups' cleanups, the last set-up's first. */
+    readonly cleanup: () => Promise<void>;
+};
+/**
+ * Runs a story's loaders and set-ups.
+ *
+ * @param story - the story.
+ * @param context - its args and what it is shown with; `loaded` is filled in here.
+ * @returns what it loaded and how to undo its set-ups.
+ * @throws What a loader or a set-up throws, after undoing the set-ups that ran.
+ */
+export declare const prepareStory: (story: Pick<LoadedStory, "loaders" | "beforeEach">, context: Omit<StoryHookContext<LoadedArgs>, "loaded">) => Promise<PreparedStory>;
+//# sourceMappingURL=storyHooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storyHooks.d.ts","sourceRoot":"","sources":["../../../src/frame/storyHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEhE,yFAAyF;AACzF,MAAM,MAAM,aAAa,GAAG;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,CAAC;AAwBF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GACvB,OAAO,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,YAAY,CAAC,EAClD,SAAS,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,KACpD,OAAO,CAAC,aAAa,CAcvB,CAAC"}

package/dist/src/frame/storyHooks.js

@@ -0,0 +1,59 @@
+/**
+ * What runs before a story is drawn, as CSF orders it: its loaders, then its set-ups (`beforeEach`), each set-up's
+ * cleanup kept to run when the story is mounted again or left. The frame and the server tests prepare a story the same
+ * way.
+ *
+ * @remarks
+ * The loaders run at once and their results merge in their order (the preview's, the meta's, the story's: a later key
+ * wins); the set-ups run one after another, after the loaders, and see what they loaded. A set-up that throws undoes
+ * the ones before it, so a failed story leaves nothing behind.
+ *
+ * @module
+ */
+/** Whether a loader's result is an object whose keys reach `context.loaded`. */
+const isLoaded = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Runs cleanups, the last one first; every one runs even when an earlier one throws, and the first error is thrown
+ * after them.
+ *
+ * @param cleanups - the cleanups, in the order their set-ups ran.
+ */
+const runCleanups = async (cleanups) => {
+    const errors = [];
+    for (const cleanup of [...cleanups].reverse()) {
+        try {
+            await cleanup();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length > 0)
+        throw errors[0];
+};
+/**
+ * Runs a story's loaders and set-ups.
+ *
+ * @param story - the story.
+ * @param context - its args and what it is shown with; `loaded` is filled in here.
+ * @returns what it loaded and how to undo its set-ups.
+ * @throws What a loader or a set-up throws, after undoing the set-ups that ran.
+ */
+export const prepareStory = async (story, context) => {
+    const results = await Promise.all(story.loaders.map((loader) => loader({ ...context, loaded: {} })));
+    const loaded = Object.assign({}, ...results.filter(isLoaded));
+    const cleanups = [];
+    try {
+        for (const beforeEach of story.beforeEach) {
+            const cleanup = await beforeEach({ ...context, loaded });
+            if (typeof cleanup === "function")
+                cleanups.push(cleanup);
+        }
+    }
+    catch (error) {
+        await runCleanups(cleanups);
+        throw error;
+    }
+    return { loaded, cleanup: () => runCleanups(cleanups) };
+};
+//# sourceMappingURL=storyHooks.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storyHooks.js","sourceRoot":"","sources":["../../../src/frame/storyHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,gFAAgF;AAChF,MAAM,QAAQ,GAAG,CAAC,KAAc,EAA8C,EAAE,CAC9E,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,WAAW,GAAG,KAAK,EAAE,QAAiD,EAAiB,EAAE;IAC7F,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,OAAO,EAAE,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,KAAkD,EAClD,OAAqD,EAC7B,EAAE;IAC1B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACrG,MAAM,MAAM,GAAsC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjG,MAAM,QAAQ,GAAmC,EAAE,CAAC;IACpD,IAAI,CAAC;QACH,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YAC1C,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YACzD,IAAI,OAAO,OAAO,KAAK,UAAU;gBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC5B,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;AAC1D,CAAC,CAAC"}

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

@@ -0,0 +1,104 @@
+/**
+ * A loaded story file read safely: the module is code the catalogue did not type-check against its own types, so
+ * every part the frame uses is checked before use.
+ *
+ * @remarks
+ * Objects, strings and lists are checked for their shape; a function's parameters cannot be checked at run time, so a
+ * function is taken with the signature CSF gives it (a render, a play function, a decorator). What a render and a
+ * decorator return is the framework's (`unknown` here); its renderer draws it. The meta's component is the framework's
+ * too: a function, or an object some frameworks make one of (React's `memo` and `forwardRef`), so the frame passes on
+ * whatever the meta names and the renderer reads it.
+ *
+ * A story is an object (CSF 3) or a function (CSF 2: the function is its render, its args and parameters are
+ * properties assigned to it). The meta may give the render and the play function every story without its own uses.
+ *
+ * @module
+ */
+import type { ForcedState, ReplayMode, StoryBeforeEach, StoryContext, StoryLoader, StoryParameters, StoryPlayContext } from "@forgebook/story-format/csf";
+import type { StoryControlsSetting } from "@forgebook/story-format/source";
+/** Args as the frame handles them: whatever the story's component takes. */
+export type LoadedArgs = Readonly<Record<string, unknown>>;
+/** A component of the loaded file, as the framework makes one: a function, or an object (React's `memo`). */
+export type LoadedComponent = NonNullable<unknown>;
+/** A decorator of the loaded file. */
+export type LoadedDecorator = (story: () => unknown, context: StoryContext<LoadedArgs>) => unknown;
+/** A loader of the loaded file or the preview. */
+export type LoadedLoader = StoryLoader<LoadedArgs>;
+/** A `beforeEach` of the loaded file or the preview. */
+export type LoadedBeforeEach = StoryBeforeEach<LoadedArgs>;
+/** What the frame renders: the meta and one story, merged. */
+export type LoadedStory = {
+    /** The component, when the meta names one. */
+    readonly component: LoadedComponent | undefined;
+    /** The meta's args, then the story's. */
+    readonly args: LoadedArgs;
+    /** The story's render, or the meta's, when either has one. */
+    readonly render: ((args: LoadedArgs, context: StoryContext<LoadedArgs>) => unknown) | undefined;
+    /** The story's play function, or the meta's. */
+    readonly play: ((context: StoryPlayContext<LoadedArgs>) => Promise<void> | void) | undefined;
+    /** The story's decorators first (innermost), then the meta's. */
+    readonly decorators: readonly LoadedDecorator[];
+    /** The loaders: the preview's, then the meta's, then the story's. */
+    readonly loaders: readonly LoadedLoader[];
+    /** The set-ups, in the order they run: the preview's, then the meta's, then the story's. */
+    readonly beforeEach: readonly LoadedBeforeEach[];
+    /** The states forced on the story's root. */
+    readonly forceState: readonly ForcedState[];
+    /** The replay, when declared. */
+    readonly replay: ReplayMode | undefined;
+    /** The `globals` of the meta and the story, the story's over the meta's: what it fixes of the view. */
+    readonly globals: Readonly<Record<string, unknown>>;
+    /** The `argTypes` of the meta and the story, merged by arg (the story's fields over the meta's). */
+    readonly argTypes: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    /** The props the panel can set: every adjustable one, or only these (none for fixed examples). */
+    readonly controls: StoryControlsSetting;
+    /** The parameters: the preview's, under the meta's, under the story's. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+    /** The layout in the frame. */
+    readonly layout: NonNullable<StoryParameters["layout"]>;
+    /** A Live story's clock start, in ms since the Unix epoch (`parameters.clock`); none for a still (D-504). */
+    readonly clockStart: number | undefined;
+};
+/**
+ * The meta and one story of a loaded module, merged.
+ *
+ * @param module - the module, as `import()` gave it.
+ * @param exportName - the story's named export.
+ * @param preview - the catalogue's preview: its parameters under the meta's and the story's, its loaders and set-ups
+ *   before theirs (its decorators are the renderer's to put outside); none by default.
+ * @returns what the frame renders, or why it cannot.
+ */
+export declare const readStory: (module: unknown, exportName: string, preview?: LoadedPreview) => LoadedStory | string;
+/** A catalogue's preview, read: its decorators, its parameters, its setup, its loaders and set-ups. */
+export type LoadedPreview = {
+    /** Its decorators, innermost first. */
+    readonly decorators: readonly LoadedDecorator[];
+    /** Its loaders, before every story's. */
+    readonly loaders: readonly LoadedLoader[];
+    /** Its set-ups, before every story's. */
+    readonly beforeEach: readonly LoadedBeforeEach[];
+    /** Its args, under every meta's (Storybook's project args). */
+    readonly args: LoadedArgs;
+    /** Its `argTypes`, under every meta's. */
+    readonly argTypes: Readonly<Record<string, unknown>>;
+    /** Its parameters, under every meta's. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+    /** What runs once before any story renders; nothing when it has none. */
+    readonly setup: (() => Promise<void>) | undefined;
+};
+/** The preview of a catalogue that has none. */
+export declare const NO_PREVIEW: LoadedPreview;
+/**
+ * A catalogue's preview read safely, as a story file is: from the default export of its module, or the module itself.
+ *
+ * @param module - the preview's module, as `import()` gave it; none for a catalogue without one.
+ */
+export declare const readPreview: (module: unknown) => LoadedPreview;
+/**
+ * Previews read one after another, as a catalogue's presets and its own: decorators of the later ones outside the
+ * earlier ones', parameters of the later ones over the earlier ones', every setup, loader and set-up in order.
+ *
+ * @param previews - the previews, the catalogue's own last.
+ */
+export declare const mergedPreviews: (previews: readonly LoadedPreview[]) => LoadedPreview;
+//# sourceMappingURL=storyModule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storyModule.d.ts","sourceRoot":"","sources":["../../../src/frame/storyModule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,YAAY,EACZ,WAAW,EACX,eAAe,EACf,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAI3E,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE3D,6GAA6G;AAC7G,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;AAEnD,sCAAsC;AACtC,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;AAEnG,kDAAkD;AAClD,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;AAEnD,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;AAE3D,8DAA8D;AAC9D,MAAM,MAAM,WAAW,GAAG;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,eAAe,GAAG,SAAS,CAAC;IAChD,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAChG,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,gBAAgB,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IAC7F,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;IAC5C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC,uGAAuG;IACvG,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxD,6GAA6G;IAC7G,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAiGF;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,QAAQ,OAAO,EACf,YAAY,MAAM,EAClB,UAAS,aAA0B,KAClC,WAAW,GAAG,MAsChB,CAAC;AAEF,uGAAuG;AACvG,MAAM,MAAM,aAAa,GAAG;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;CACnD,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,UAAU,EAAE,aAQxB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,OAAO,KAAG,aAa7C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,SAAS,aAAa,EAAE,KAAG,aAmBnE,CAAC"}