@forgebook/testing 0.0.0-stage → 0.1.0

package/dist/src/overlays.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The overlays a story leaves open past its frame: what a frame as tall as the story would cut or push to the other
+ * side, so the story needs `parameters.height` (D-469).
+ *
+ * @remarks
+ * The catalogue sizes a story's frame to its document's body, and the window of the frame is the overlays' window;
+ * the tests open the frame in a window taller than that, where an overlay opened near the story's foot still fits. So
+ * after the play an overlay is measured against the frame the shell would give it: the body's height, or the height
+ * the story declares when that is more. Without knowing
+ * the library (D-67), an overlay is any element with `position: fixed` that shows (a box, not hidden, not
+ * transparent) and whose box ends more than a pixel below the body. A fixed element placed against the window rather
+ * than against what opened it (a full-window layer, a toast region pinned to the window's foot, a drawer) is told
+ * apart by covering the window's whole height, or by growing the window: it moves or grows with it, an anchored
+ * overlay stays where it is.
+ *
+ * Limits: an overlay that is not `position: fixed` (an absolute popover inside the story) is not seen; an overlay the
+ * library shrinks to the room there is (a list that scrolls in the frame) fits and is not flagged, though it may be
+ * cramped; only the state after the play is measured, not what opens and closes during it; and an anchored overlay
+ * the library fits to the test's window (a list as tall as the room below it) grows with the window and reads as
+ * pinned to it, which takes a list taller than the test's window.
+ *
+ * @module
+ */
+import type { Page } from "@playwright/test";
+import type { ViewState } from "forgebook/view-state";
+/** A shown fixed element's box, in CSS px from the window's top. */
+export type FixedBox = {
+    /** The element, as a short CSS path (`div.menu`), with its order among the elements of that path (`#0`). */
+    readonly key: string;
+    /** Its top edge. */
+    readonly top: number;
+    /** Its bottom edge. */
+    readonly bottom: number;
+};
+/** The frame's height as the shell gives it, and every shown fixed element. */
+export type FixedLayout = {
+    /** The height the shell gives the story's frame, in CSS px: the body's, or the declared one when more. */
+    readonly frameHeight: number;
+    /** The window's height, in CSS px. */
+    readonly windowHeight: number;
+    /** Every shown `position: fixed` element, in document order. */
+    readonly boxes: readonly FixedBox[];
+};
+/** An overlay that reaches past the frame. */
+export type OverlayPastFrame = {
+    /** The element, as `FixedBox.key` names it. */
+    readonly element: string;
+    /** How far its box ends below the frame's foot, in whole CSS px. */
+    readonly by: number;
+    /** The frame's height, in CSS px. */
+    readonly frameHeight: number;
+};
+/** How much taller the window is made to tell the elements pinned to it, in CSS px. */
+export declare const WINDOW_GROWTH = 120;
+/**
+ * The frame's height and every shown fixed element, measured in the story's page (`page.evaluate`), so it takes no
+ * import.
+ */
+export declare const fixedLayout: () => FixedLayout;
+/**
+ * The overlays past the frame, from the layout after the play and the same layout in a window grown by `growth`.
+ *
+ * @param layout - the layout after the play.
+ * @param grown - the layout once the window is `growth` px taller; none counts every box as anchored.
+ * @param growth - how much taller the grown window is, in CSS px.
+ * @returns the boxes that end past the frame and did not follow the window's foot. Pure.
+ */
+export declare const overlaysPastFrame: (layout: FixedLayout, grown: FixedLayout | undefined, growth: number) => OverlayPastFrame[];
+/**
+ * Whether a view is checked for overlays left past the frame: not with the structure sheets only, where a library's
+ * surfaces are bare by its own rules (sizes are look, so an overlay has no cap and no width there), so no declared
+ * height could hold them.
+ *
+ * @param view - the switches a test variant sets over the defaults.
+ * @returns `false` for a structure-only view, `true` otherwise.
+ */
+export declare const isOverlayChecked: (view: Partial<ViewState>) => boolean;
+/**
+ * The overlays a story's page leaves open past its frame, measured once its play is over.
+ *
+ * @param page - the story's frame page, ready.
+ * @param sceneHeight - the height the story declares (`parameters.height`), in CSS px; none by default.
+ * @returns one entry per overlay that ends below the frame's foot; the window is grown and given back only when a
+ * fixed element ends there.
+ */
+export declare const findOverlaysPastFrame: (page: Page, sceneHeight?: number) => Promise<OverlayPastFrame[]>;
+//# sourceMappingURL=overlays.d.ts.map

package/dist/src/overlays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlays.d.ts","sourceRoot":"","sources":["../../src/overlays.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,oEAAoE;AACpE,MAAM,MAAM,QAAQ,GAAG;IACrB,4GAA4G;IAC5G,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oBAAoB;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG;IACxB,0GAA0G;IAC1G,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;CACrC,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,aAAa,MAAM,CAAC;AAKjC;;;GAGG;AACH,eAAO,MAAM,WAAW,QAAO,WAsB9B,CAAC;AAUF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,WACpB,WAAW,SACZ,WAAW,GAAG,SAAS,UACtB,MAAM,KACb,gBAAgB,EAclB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,SAAU,OAAO,CAAC,SAAS,CAAC,KAAG,OAAsC,CAAC;AAMnG;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,SAAgB,IAAI,2BAAoB,OAAO,CAAC,gBAAgB,EAAE,CAenG,CAAC"}

package/dist/src/overlays.js

@@ -0,0 +1,103 @@
+/** How much taller the window is made to tell the elements pinned to it, in CSS px. */
+export const WINDOW_GROWTH = 120;
+/** How far past the frame's foot a box may end without counting, in CSS px: rounding. */
+const TOLERANCE = 1;
+/**
+ * The frame's height and every shown fixed element, measured in the story's page (`page.evaluate`), so it takes no
+ * import.
+ */
+export const fixedLayout = () => {
+    const pathOf = (element) => {
+        const classes = [...element.classList].slice(0, 2).join(".");
+        return classes === "" ? element.tagName.toLowerCase() : `${element.tagName.toLowerCase()}.${classes}`;
+    };
+    const counts = new Map();
+    const boxes = [];
+    for (const element of document.body.querySelectorAll("*")) {
+        const style = getComputedStyle(element);
+        if (style.position !== "fixed" || style.visibility === "hidden" || style.opacity === "0")
+            continue;
+        const box = element.getBoundingClientRect();
+        if (box.width === 0 || box.height === 0)
+            continue;
+        const path = pathOf(element);
+        const count = counts.get(path) ?? 0;
+        counts.set(path, count + 1);
+        boxes.push({ key: `${path}#${count}`, top: box.top, bottom: box.bottom });
+    }
+    return {
+        frameHeight: Math.ceil(document.body.getBoundingClientRect().height),
+        windowHeight: window.innerHeight,
+        boxes
+    };
+};
+/**
+ * Whether a box ends below the frame's foot.
+ *
+ * @param box - the box.
+ * @param frameHeight - the frame's height.
+ */
+const endsPast = (box, frameHeight) => box.bottom > frameHeight + TOLERANCE;
+/**
+ * The overlays past the frame, from the layout after the play and the same layout in a window grown by `growth`.
+ *
+ * @param layout - the layout after the play.
+ * @param grown - the layout once the window is `growth` px taller; none counts every box as anchored.
+ * @param growth - how much taller the grown window is, in CSS px.
+ * @returns the boxes that end past the frame and did not follow the window's foot. Pure.
+ */
+export const overlaysPastFrame = (layout, grown, growth) => {
+    const grownBoxes = new Map((grown?.boxes ?? []).map((box) => [box.key, box]));
+    return layout.boxes.flatMap((box) => {
+        if (!endsPast(box, layout.frameHeight))
+            return [];
+        const after = grownBoxes.get(box.key);
+        // a layer over the whole window, or a box that moved or grew with the window's foot: placed against the window,
+        // not against what opened it (a layer whose overlay closed on the resize is gone from the grown layout)
+        const isWindowLayer = box.top <= TOLERANCE && box.bottom >= layout.windowHeight - TOLERANCE;
+        const isPinnedToWindow = after !== undefined && after.bottom - box.bottom >= growth / 2;
+        if (isWindowLayer || isPinnedToWindow)
+            return [];
+        return [
+            { element: box.key, by: Math.round(box.bottom - layout.frameHeight), frameHeight: layout.frameHeight }
+        ];
+    });
+};
+/**
+ * Whether a view is checked for overlays left past the frame: not with the structure sheets only, where a library's
+ * surfaces are bare by its own rules (sizes are look, so an overlay has no cap and no width there), so no declared
+ * height could hold them.
+ *
+ * @param view - the switches a test variant sets over the defaults.
+ * @returns `false` for a structure-only view, `true` otherwise.
+ */
+export const isOverlayChecked = (view) => view.sheets !== "structure";
+/** Waits for two frames of the page, so a resize has been laid out and anything that follows it has moved. */
+const twoFrames = () => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+/**
+ * The overlays a story's page leaves open past its frame, measured once its play is over.
+ *
+ * @param page - the story's frame page, ready.
+ * @param sceneHeight - the height the story declares (`parameters.height`), in CSS px; none by default.
+ * @returns one entry per overlay that ends below the frame's foot; the window is grown and given back only when a
+ * fixed element ends there.
+ */
+export const findOverlaysPastFrame = async (page, sceneHeight = 0) => {
+    const measure = async () => {
+        const measured = await page.evaluate(fixedLayout);
+        return { ...measured, frameHeight: Math.max(measured.frameHeight, sceneHeight) };
+    };
+    const layout = await measure();
+    if (!layout.boxes.some((box) => endsPast(box, layout.frameHeight)))
+        return [];
+    const size = page.viewportSize();
+    if (size === null)
+        return overlaysPastFrame(layout, undefined, WINDOW_GROWTH);
+    await page.setViewportSize({ width: size.width, height: size.height + WINDOW_GROWTH });
+    await page.evaluate(twoFrames);
+    const grown = await measure();
+    await page.setViewportSize(size);
+    await page.evaluate(twoFrames);
+    return overlaysPastFrame(layout, grown, WINDOW_GROWTH);
+};
+//# sourceMappingURL=overlays.js.map

package/dist/src/overlays.js.map

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

package/dist/src/playwrightConfig.d.ts

@@ -0,0 +1,26 @@
+import type { PlaywrightTestConfig } from "@playwright/test";
+/** Where a package's story tests live and the ports they use. */
+export type StoryTestServer = {
+    /** The folder of the specs, the frame page, its Vite config and the visual tests' global setup. */
+    readonly dir: string;
+    /** The port the test instance of the frame page listens on. */
+    readonly port: number;
+    /** The port the container's browser listens on, for the visual tests. */
+    readonly browserPort: number;
+    /** How many tests run at once; every core when left out or not a positive number. */
+    readonly workers?: number;
+};
+/**
+ * The browser tests' configuration: `stories.spec.ts` in the host's Chromium.
+ *
+ * @param server - the package's folder and ports.
+ */
+export declare const storyTestConfig: (server: StoryTestServer) => PlaywrightTestConfig;
+/**
+ * The visual tests' configuration: `visual.spec.ts` against the reference images in `__screenshots__`, in the
+ * Playwright container's browser (started by `visualBrowser.ts` on a developer's machine, already there in CI).
+ *
+ * @param server - the package's folder and ports.
+ */
+export declare const visualTestConfig: (server: StoryTestServer) => PlaywrightTestConfig;
+//# sourceMappingURL=playwrightConfig.d.ts.map

package/dist/src/playwrightConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwrightConfig.d.ts","sourceRoot":"","sources":["../../src/playwrightConfig.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG;IAC5B,mGAAmG;IACnG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAaF;;;;GAIG;AACH,eAAO,MAAM,eAAe,WAAY,eAAe,KAAG,oBAQxD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,WAAY,eAAe,KAAG,oBAkB1D,CAAC"}

package/dist/src/playwrightConfig.js

@@ -0,0 +1,62 @@
+/**
+ * The two Playwright configurations of a package's story tests: the browser tests on the host's Chromium, and the
+ * visual tests in the Playwright container's browser, both on the package's own test instance of the frame page.
+ *
+ * @remarks
+ * Published (`forgebook/testing/playwright`; D-167). The package keeps a folder with its specs
+ * (`stories.spec.ts`, `visual.spec.ts`), its frame page (`frame.html`), the Vite config that serves it
+ * (`vite.config.ts`, from `storyTestViteConfig`) and the visual tests' global setup (`visualBrowser.ts`, from
+ * `startVisualBrowser`); each package names its own ports, so two packages' tests run side by side. In CI the visual
+ * tests already run inside the Playwright image (`CI` set), so they use its browser directly.
+ *
+ * @module
+ */
+import { availableParallelism } from "node:os";
+/** The workers to use. */
+const workersOf = ({ workers }) => workers !== undefined && workers > 0 ? workers : availableParallelism();
+/** The test instance of the frame page, started by Playwright and stopped after the run. */
+const webServer = ({ dir, port }) => ({
+    command: `pnpm exec vite --config ${dir}/vite.config.ts --host 127.0.0.1 --port ${port} --strictPort`,
+    url: `http://127.0.0.1:${port}/frame.html`,
+    reuseExistingServer: false
+});
+/**
+ * The browser tests' configuration: `stories.spec.ts` in the host's Chromium.
+ *
+ * @param server - the package's folder and ports.
+ */
+export const storyTestConfig = (server) => ({
+    testDir: server.dir,
+    testMatch: "stories.spec.ts",
+    fullyParallel: true,
+    workers: workersOf(server),
+    reporter: [["list"]],
+    webServer: webServer(server),
+    use: { browserName: "chromium", baseURL: `http://127.0.0.1:${server.port}/` }
+});
+/**
+ * The visual tests' configuration: `visual.spec.ts` against the reference images in `__screenshots__`, in the
+ * Playwright container's browser (started by `visualBrowser.ts` on a developer's machine, already there in CI).
+ *
+ * @param server - the package's folder and ports.
+ */
+export const visualTestConfig = (server) => {
+    const isInContainer = process.env["CI"] !== undefined;
+    return {
+        testDir: server.dir,
+        testMatch: "visual.spec.ts",
+        snapshotPathTemplate: "{testDir}/__screenshots__/{arg}{ext}",
+        fullyParallel: true,
+        workers: workersOf(server),
+        reporter: [["list"]],
+        webServer: webServer(server),
+        ...(isInContainer ? {} : { globalSetup: `${server.dir}/visualBrowser.ts` }),
+        use: {
+            browserName: "chromium",
+            viewport: { width: 1024, height: 768 },
+            baseURL: `http://${isInContainer ? "127.0.0.1" : "host.docker.internal"}:${server.port}/`,
+            ...(isInContainer ? {} : { connectOptions: { wsEndpoint: `ws://127.0.0.1:${server.browserPort}/` } })
+        }
+    };
+};
+//# sourceMappingURL=playwrightConfig.js.map

package/dist/src/playwrightConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwrightConfig.js","sourceRoot":"","sources":["../../src/playwrightConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAgB/C,0BAA0B;AAC1B,MAAM,SAAS,GAAG,CAAC,EAAE,OAAO,EAAmB,EAAU,EAAE,CACzD,OAAO,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,oBAAoB,EAAE,CAAC;AAE1E,4FAA4F;AAC5F,MAAM,SAAS,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAmB,EAAkD,EAAE,CAAC,CAAC;IACrG,OAAO,EAAE,2BAA2B,GAAG,2CAA2C,IAAI,eAAe;IACrG,GAAG,EAAE,oBAAoB,IAAI,aAAa;IAC1C,mBAAmB,EAAE,KAAK;CAC3B,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAuB,EAAwB,EAAE,CAAC,CAAC;IACjF,OAAO,EAAE,MAAM,CAAC,GAAG;IACnB,SAAS,EAAE,iBAAiB;IAC5B,aAAa,EAAE,IAAI;IACnB,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC;IAC1B,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC;IAC5B,GAAG,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,oBAAoB,MAAM,CAAC,IAAI,GAAG,EAAE;CAC9E,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAuB,EAAwB,EAAE;IAChF,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;IACtD,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,GAAG;QACnB,SAAS,EAAE,gBAAgB;QAC3B,oBAAoB,EAAE,sCAAsC;QAC5D,aAAa,EAAE,IAAI;QACnB,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC;QAC1B,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QACpB,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC;QAC5B,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC,GAAG,mBAAmB,EAAE,CAAC;QAC3E,GAAG,EAAE;YACH,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;YACtC,OAAO,EAAE,UAAU,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,IAAI,MAAM,CAAC,IAAI,GAAG;YACzF,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,UAAU,EAAE,kBAAkB,MAAM,CAAC,WAAW,GAAG,EAAE,EAAE,CAAC;SACtG;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/src/serverTests.d.ts

@@ -0,0 +1,44 @@
+/**
+ * One Vitest test per story: the framework renders it to a string without errors (`renderToString` of its renderer),
+ * so no component reads `window` or `document` while rendering (D-71), and its controls tell the truth
+ * (`storyControlsProblem`).
+ *
+ * @remarks
+ * The stories load through the source's own globs, which Vitest understands. `wrap` puts each story inside a
+ * provider (a partial translation catalogue, when the library has one) for a second pass, and can check its HTML. The
+ * source's `setup` runs first.
+ *
+ * @module
+ */
+import type { StorySource } from "@forgebook/story-format/source";
+import type { StoryRenderer } from "forgebook/renderer";
+import { type LoadedDecorator } from "forgebook/story-module";
+/** A second pass: each story inside a decorator, its HTML optionally checked. */
+export type StoryServerPass = {
+    /** The pass's name, in each test's title (`partial catalogue`). */
+    readonly name: string;
+    /**
+     * The decorator the story is drawn in (`(story) => <Provider messages={partial}>{story()}</Provider>`), outside its
+     * own; none draws it alone.
+     */
+    readonly decorator: LoadedDecorator | undefined;
+    /** Checks the story's HTML, with Vitest's `expect` (no message key shown, for a partial catalogue); none by default. */
+    readonly check?: (html: string) => void;
+};
+/** The generated tests' options. */
+export type StoryServerTestsOptions = {
+    /** The framework that draws the stories (`reactRenderer` of `@forgebook/react`). */
+    readonly renderer: StoryRenderer;
+    /** The catalogue's previews' modules (its presets' first), whose decorators and parameters every story gets. */
+    readonly previews?: readonly unknown[];
+    /** A second pass over every story. */
+    readonly wrap?: StoryServerPass;
+};
+/**
+ * Declares the tests, one `describe` per component and one test per story (and per story wrapped).
+ *
+ * @param source - the source, with its globs.
+ * @param options - the framework, and an optional wrapper for a second pass.
+ */
+export declare const storyServerTests: (source: StorySource, options: StoryServerTestsOptions) => void;
+//# sourceMappingURL=serverTests.d.ts.map

package/dist/src/serverTests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverTests.d.ts","sourceRoot":"","sources":["../../src/serverTests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAGlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,EAAE,KAAK,eAAe,EAA0C,MAAM,wBAAwB,CAAC;AAOtG,iFAAiF;AACjF,MAAM,MAAM,eAAe,GAAG;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,GAAG,SAAS,CAAC;IAChD,wHAAwH;IACxH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC,CAAC;AAEF,oCAAoC;AACpC,MAAM,MAAM,uBAAuB,GAAG;IACpC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACvC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;CACjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,WAAY,WAAW,WAAW,uBAAuB,KAAG,IAmExF,CAAC"}

package/dist/src/serverTests.js

@@ -0,0 +1,101 @@
+/**
+ * One Vitest test per story: the framework renders it to a string without errors (`renderToString` of its renderer),
+ * so no component reads `window` or `document` while rendering (D-71), and its controls tell the truth
+ * (`storyControlsProblem`).
+ *
+ * @remarks
+ * The stories load through the source's own globs, which Vitest understands. `wrap` puts each story inside a
+ * provider (a partial translation catalogue, when the library has one) for a second pass, and can check its HTML. The
+ * source's `setup` runs first.
+ *
+ * @module
+ */
+import { storyTextOf } from "@forgebook/story-format/texts";
+import { heldFrameClock } from "forgebook/frame-clock";
+import { sourceFiles } from "forgebook/source-files";
+import { prepareStory } from "forgebook/story-hooks";
+import { mergedPreviews, readPreview, readStory } from "forgebook/story-module";
+import { BASE_LANGUAGE, withStoryTexts } from "forgebook/story-texts";
+import { storyTree, testedStoryLocations } from "forgebook/story-tree";
+import { beforeAll, describe, expect, it } from "vitest";
+import { storyControlsProblem } from "./storyControls.js";
+/**
+ * Declares the tests, one `describe` per component and one test per story (and per story wrapped).
+ *
+ * @param source - the source, with its globs.
+ * @param options - the framework, and an optional wrapper for a second pass.
+ */
+export const storyServerTests = (source, options) => {
+    const passes = [
+        { name: "alone", decorator: undefined },
+        ...(options.wrap === undefined ? [] : [options.wrap])
+    ];
+    const preview = mergedPreviews((options.previews ?? []).map(readPreview));
+    beforeAll(async () => {
+        await source.setup?.();
+        await preview.setup?.();
+    });
+    const locations = testedStoryLocations(storyTree([source]));
+    for (const [title, entries] of Map.groupBy(locations, (location) => location.component.title)) {
+        describe(title, () => {
+            for (const { story, component } of entries) {
+                it.each(passes)(`${story.name} renders on the server ($name)`, async (pass) => {
+                    const load = sourceFiles(source).stories[component.file];
+                    if (load === undefined)
+                        throw new Error(`No loader for ${component.file}`);
+                    const loaded = readStory(await load(), story.exportName, preview);
+                    if (typeof loaded === "string")
+                        throw new Error(loaded);
+                    // the stories' own texts: what the catalogue shows when no language is chosen
+                    const texts = source.texts?.[BASE_LANGUAGE] ?? {};
+                    const args = withStoryTexts(loaded.args, storyTextOf(texts));
+                    // a Live story renders at its start, as the frame's tests picture it (D-504)
+                    const clock = heldFrameClock(loaded.clockStart ?? 0);
+                    // the loaders and set-ups run as in the frame, so a story drawn from what they load renders here too
+                    const identity = { id: story.id, name: story.name, title: component.title };
+                    const prepared = await prepareStory(loaded, {
+                        ...identity,
+                        args,
+                        text: storyTextOf(texts),
+                        clock,
+                        globals: {},
+                        parameters: loaded.parameters
+                    });
+                    let html = "";
+                    try {
+                        // a render error fails the test: the server does not run error boundaries, and none may be swallowed
+                        expect(() => {
+                            html = options.renderer.renderToString({
+                                identity,
+                                story: loaded,
+                                args,
+                                texts,
+                                clock,
+                                decorators: [
+                                    ...preview.decorators,
+                                    ...(pass.decorator === undefined ? [] : [pass.decorator])
+                                ],
+                                globals: {},
+                                loaded: prepared.loaded
+                            });
+                        }).not.toThrow();
+                    }
+                    finally {
+                        await prepared.cleanup();
+                    }
+                    pass.check?.(html);
+                });
+                it(`${story.name} declares the controls it uses`, async () => {
+                    const load = sourceFiles(source).stories[component.file];
+                    if (load === undefined)
+                        throw new Error(`No loader for ${component.file}`);
+                    const loaded = readStory(await load(), story.exportName);
+                    if (typeof loaded === "string")
+                        throw new Error(loaded);
+                    expect(storyControlsProblem(loaded)).toBeUndefined();
+                });
+            }
+        });
+    }
+};
+//# sourceMappingURL=serverTests.js.map

package/dist/src/serverTests.js.map

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

package/dist/src/spills.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The elements of a story that spill out of their parent: what overlaps a neighbour or runs off the frame when the
+ * story is narrower than it was drawn for.
+ *
+ * @remarks
+ * Runs in the story's page (`page.evaluate`), so it takes no import. An element spills when its box reaches past its
+ * parent's box by more than a pixel, sideways, and the parent shows its overflow: a parent that clips or scrolls
+ * (`overflow` other than `visible`) and an element taken out of the flow (`absolute`, `fixed`) are left out, as is
+ * anything inside a frame-level layer (`data-forgebook-allow-spill`, for a story that shows a spill on purpose).
+ *
+ * @module
+ */
+/** One spill: the element, its parent, and by how many pixels it reaches past. */
+export type Spill = {
+    /** The element, as a short CSS path (`div.story-settings`). */
+    readonly element: string;
+    /** Its parent, the same way. */
+    readonly parent: string;
+    /** How far it reaches past the parent, in CSS px. */
+    readonly by: number;
+};
+/**
+ * The spills inside a root, measured in the page.
+ *
+ * @param rootSelector - the story's root (`.forgebook-frame`).
+ */
+export declare const findSpills: (rootSelector: string) => Spill[];
+//# sourceMappingURL=spills.d.ts.map

package/dist/src/spills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spills.d.ts","sourceRoot":"","sources":["../../src/spills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,kFAAkF;AAClF,MAAM,MAAM,KAAK,GAAG;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,iBAAkB,MAAM,KAAG,KAAK,EAgCtD,CAAC"}

package/dist/src/spills.js

@@ -0,0 +1,53 @@
+/**
+ * The elements of a story that spill out of their parent: what overlaps a neighbour or runs off the frame when the
+ * story is narrower than it was drawn for.
+ *
+ * @remarks
+ * Runs in the story's page (`page.evaluate`), so it takes no import. An element spills when its box reaches past its
+ * parent's box by more than a pixel, sideways, and the parent shows its overflow: a parent that clips or scrolls
+ * (`overflow` other than `visible`) and an element taken out of the flow (`absolute`, `fixed`) are left out, as is
+ * anything inside a frame-level layer (`data-forgebook-allow-spill`, for a story that shows a spill on purpose).
+ *
+ * @module
+ */
+/**
+ * The spills inside a root, measured in the page.
+ *
+ * @param rootSelector - the story's root (`.forgebook-frame`).
+ */
+export const findSpills = (rootSelector) => {
+    const pathOf = (element) => {
+        const classes = [...element.classList].slice(0, 2).join(".");
+        return classes === "" ? element.tagName.toLowerCase() : `${element.tagName.toLowerCase()}.${classes}`;
+    };
+    // an element out of the flow, a parent that clips or scrolls, and an allowed spill are not measured
+    const isMeasured = (element, parent) => {
+        if (element.closest("[data-forgebook-allow-spill]") !== null)
+            return false;
+        const style = getComputedStyle(element);
+        const parentStyle = getComputedStyle(parent);
+        return (style.position !== "absolute" &&
+            style.position !== "fixed" &&
+            style.display !== "contents" &&
+            parentStyle.display !== "contents" &&
+            parentStyle.overflowX === "visible");
+    };
+    const overreach = (element, parent) => {
+        const box = element.getBoundingClientRect();
+        const parentBox = parent.getBoundingClientRect();
+        if (box.width === 0 || box.height === 0)
+            return 0;
+        return Math.max(box.right - parentBox.right, parentBox.left - box.left);
+    };
+    const root = document.querySelector(rootSelector);
+    if (root === null)
+        return [];
+    return [...root.querySelectorAll("*")].flatMap((element) => {
+        const parent = element.parentElement;
+        if (parent === null || !isMeasured(element, parent))
+            return [];
+        const by = overreach(element, parent);
+        return by > 1 ? [{ element: pathOf(element), parent: pathOf(parent), by: Math.round(by) }] : [];
+    });
+};
+//# sourceMappingURL=spills.js.map

package/dist/src/spills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spills.js","sourceRoot":"","sources":["../../src/spills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,YAAoB,EAAW,EAAE;IAC1D,MAAM,MAAM,GAAG,CAAC,OAAgB,EAAU,EAAE;QAC1C,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7D,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,OAAO,EAAE,CAAC;IACxG,CAAC,CAAC;IACF,oGAAoG;IACpG,MAAM,UAAU,GAAG,CAAC,OAAgB,EAAE,MAAe,EAAW,EAAE;QAChE,IAAI,OAAO,CAAC,OAAO,CAAC,8BAA8B,CAAC,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC3E,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,WAAW,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC7C,OAAO,CACL,KAAK,CAAC,QAAQ,KAAK,UAAU;YAC7B,KAAK,CAAC,QAAQ,KAAK,OAAO;YAC1B,KAAK,CAAC,OAAO,KAAK,UAAU;YAC5B,WAAW,CAAC,OAAO,KAAK,UAAU;YAClC,WAAW,CAAC,SAAS,KAAK,SAAS,CACpC,CAAC;IACJ,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,CAAC,OAAgB,EAAE,MAAe,EAAU,EAAE;QAC9D,MAAM,GAAG,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;QAC5C,MAAM,SAAS,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC;QACjD,IAAI,GAAG,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1E,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7B,OAAO,CAAC,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QACzD,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;QACrC,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC;YAAE,OAAO,EAAE,CAAC;QAC/D,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACtC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClG,CAAC,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/src/storyControls.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether a story's controls tell the truth: the props panel shows a control only when changing it changes the story.
+ *
+ * @remarks
+ * A render that ignores its args draws fixed examples, so its args reach nothing: it declares
+ * `parameters.controls: false`. A render ignores its args when it takes no parameter, or when its first parameter is
+ * named with a leading underscore, the convention for a parameter left unused: a fixed story that reads its texts
+ * takes the context as its second parameter (`(_args, { text }) => …`). A story that declares no controls must have a
+ * render that ignores its args: without a render the component takes them, and a render that reads them follows them,
+ * unless the only arg it follows is the one its Replay toggles (an arrival replayed on demand), which the panel does
+ * not drive. The parameters are read from the function's `length` and its source, so a render written `(args) => …`
+ * that ignores them is not caught. Pure: story in, problem out.
+ *
+ * @module
+ */
+import type { LoadedStory } from "forgebook/story-module";
+/**
+ * What is wrong with a story's controls, or `undefined` when nothing is.
+ *
+ * @param story - the loaded story.
+ * @returns why the panel would show controls that do nothing, or hide ones that work.
+ */
+export declare const storyControlsProblem: (story: LoadedStory) => string | undefined;
+//# sourceMappingURL=storyControls.d.ts.map

package/dist/src/storyControls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storyControls.d.ts","sourceRoot":"","sources":["../../src/storyControls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAa1D;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,UAAW,WAAW,KAAG,MAAM,GAAG,SAYlE,CAAC"}

package/dist/src/storyControls.js

@@ -0,0 +1,29 @@
+/** A function's source that opens on a first parameter named with a leading underscore: `(_args, …) => …`. */
+const FIRST_PARAMETER_UNUSED = /^(?:async\s*)?(?:function\b[^(]*)?\(\s*_/;
+/**
+ * Whether a render ignores its args: it takes no parameter, or names its first one as unused (`_args`).
+ *
+ * @param render - the story's render.
+ */
+const ignoresArgs = (render) => render.length === 0 || FIRST_PARAMETER_UNUSED.test(render.toString());
+/**
+ * What is wrong with a story's controls, or `undefined` when nothing is.
+ *
+ * @param story - the loaded story.
+ * @returns why the panel would show controls that do nothing, or hide ones that work.
+ */
+export const storyControlsProblem = (story) => {
+    if (story.component === undefined)
+        return undefined;
+    const isFixed = story.render !== undefined && ignoresArgs(story.render);
+    const hasNoControls = story.controls !== "all" && story.controls.length === 0;
+    if (isFixed && !hasNoControls) {
+        return "its render ignores its args, so the panel's controls would change nothing: declare `parameters.controls: false`";
+    }
+    const isReplayDriven = story.render !== undefined && typeof story.replay === "object";
+    if (!isFixed && hasNoControls && !isReplayDriven) {
+        return "it declares `parameters.controls: false` but its args reach the story: remove it, or list the props it reads";
+    }
+    return undefined;
+};
+//# sourceMappingURL=storyControls.js.map

package/dist/src/storyControls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storyControls.js","sourceRoot":"","sources":["../../src/storyControls.ts"],"names":[],"mappings":"AAiBA,8GAA8G;AAC9G,MAAM,sBAAsB,GAAG,0CAA0C,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,GAAG,CAAC,MAA0C,EAAW,EAAE,CAC1E,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;AAExE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAkB,EAAsB,EAAE;IAC7E,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACpD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACxE,MAAM,aAAa,GAAG,KAAK,CAAC,QAAQ,KAAK,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC;IAC9E,IAAI,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC;QAC9B,OAAO,iHAAiH,CAAC;IAC3H,CAAC;IACD,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC;IACtF,IAAI,CAAC,OAAO,IAAI,aAAa,IAAI,CAAC,cAAc,EAAE,CAAC;QACjD,OAAO,8GAA8G,CAAC;IACxH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC"}