@fohte/storybook-addon 0.1.6 → 0.1.8

package/README.md

@@ -4,7 +4,7 @@
 
 Runs three checks right after each story renders, and fails the story's test when one trips:
 
-- **overflow-check** — flags elements whose content is clipped by their container (scrollWidth > clientWidth), which usually means a silent layout bug.
+- **overflow-check** — flags elements whose content is clipped by their container (scrollWidth > clientWidth), or the story's own root overflowing the viewport itself, which usually means a silent layout bug.
 - **external-resource-check** — flags stories that load a non-same-origin resource (font, image, stylesheet), which makes VRT captures non-deterministic.
 - **unhandled-api-request-check** — flags stories that hit an API endpoint with no MSW handler, which would otherwise render with MSW's error response instead of failing.
 
@@ -42,6 +42,10 @@ This wires up `overflow-check` and `external-resource-check` — no further setu
 
 ### overflow-check
 
+Besides scanning canvasElement's descendants, this check also compares `document.documentElement.scrollWidth` against `window.innerWidth`, catching canvasElement itself (or anything above it) overflowing the viewport — which the descendant scan can never see under `layout: 'centered'`, since a flex item's automatic minimum size keeps a fixed-width story from self-overflowing there. This is on by default alongside the descendant scan; `parameters.overflowCheck.disable` turns off both.
+
+`ignoreSelectors`/`globalIgnoreSelectors` below only filter the descendant scan, not the viewport check — the viewport check has no selector-level exemption and can only be turned off entirely via `disable`.
+
 To exempt a selector across every story (e.g. a component whose oversized hit target never visibly clips anything), set `parameters.overflowCheck.globalIgnoreSelectors` once in `.storybook/preview.ts`. It's additive with a story's own `parameters.overflowCheck.ignoreSelectors` — both apply, since they're separate keys and Storybook deep-merges parameter objects by key (only arrays at the same key replace wholesale, so a story-level `ignoreSelectors` can't drop the global list):
 
 ```ts

package/lib/checks/overflow-check.js

@@ -83,6 +83,18 @@ function findOverflows(root, ignoreSelectors) {
     }
     return groupByAncestor(entries);
 }
+// `findOverflows` never sees canvasElement itself overflowing. Under
+// `layout: 'centered'`, canvasElement is a flex item that never shrinks
+// below its own content width, so the clip only shows up on
+// `document.documentElement`, above canvasElement.
+function findViewportOverflow() {
+    const overflowPx = document.documentElement.scrollWidth - window.innerWidth;
+    if (overflowPx <= 0)
+        return [];
+    return [
+        `document.documentElement.scrollWidth=${String(document.documentElement.scrollWidth)} is ${String(overflowPx)}px wider than window.innerWidth=${String(window.innerWidth)}. This usually means the story's own wrapper uses a fixed width (e.g. Tailwind's \`w-*\`) instead of a max-width (\`max-w-*\`).`,
+    ];
+}
 function overflowCheckParameters(storyParameters) {
     if (typeof storyParameters !== 'object' || storyParameters === null) {
         return undefined;
@@ -152,6 +164,7 @@ export const overflowCheck = {
             ...globalIgnoreSelectorsOf(params),
             ...ignoreSelectorsOf(params),
         ]), 'Story has element(s) overflowing their container (clipped and invisible)');
+        throwIfNotEmpty(findViewportOverflow(), 'Story overflows the viewport itself (not just an inner element)');
     },
 };
 //# sourceMappingURL=overflow-check.js.map

package/lib/checks/unhandled-api-request-check.js

@@ -71,18 +71,23 @@ const PENDING_FETCH_TIMEOUT_MS = 2000;
 // every other check.
 export async function waitForPendingApiRequests() {
     const { pendingFetches } = globalState();
-    const deadline = Date.now() + PENDING_FETCH_TIMEOUT_MS;
+    // performance.now(), not Date.now(): a consuming app's test setup may call
+    // vi.setSystemTime() without vi.useFakeTimers() (e.g. to pin screenshots to
+    // a fixed date), which freezes Date.now() while leaving setTimeout on the
+    // real clock — Date.now() < deadline would then stay true forever and this
+    // loop would never exit on its own.
+    const deadline = performance.now() + PENDING_FETCH_TIMEOUT_MS;
     // A tracked fetch's own resolution can synchronously trigger another
     // tracked fetch (e.g. fetch(user).then(() => fetch(user.posts))) — re-check
     // pendingFetches after each round instead of racing a single snapshot of
     // it, so a same-story follow-up fetch is also waited for, within the same
     // overall deadline.
-    while (pendingFetches.size > 0 && Date.now() < deadline) {
+    while (pendingFetches.size > 0 && performance.now() < deadline) {
         // Each iteration re-reads pendingFetches, which the previous iteration's
         // wait may have grown, so this can't be hoisted out of the loop.
         await Promise.race([
             Promise.all(pendingFetches),
-            new Promise((resolve) => setTimeout(resolve, deadline - Date.now())),
+            new Promise((resolve) => setTimeout(resolve, deadline - performance.now())),
         ]);
     }
     if (pendingFetches.size > 0) {

package/package.json

@@ -56,25 +56,25 @@
     "@eslint/eslintrc": "3.3.6",
     "@fohte/eslint-config": "0.4.1",
     "@ninoseki/eslint-plugin-neverthrow": "0.2.0",
-    "@storybook/addon-vitest": "10.5.8",
-    "@storybook/html-vite": "10.5.8",
+    "@storybook/addon-vitest": "10.5.10",
+    "@storybook/html-vite": "10.5.10",
     "@storycap-testrun/browser": "2.1.1",
     "@tsconfig/node-lts": "24.0.1",
     "@tsconfig/strictest": "2.0.8",
     "@types/jsdom": "30.0.0",
     "@types/node": "24.13.3",
-    "@vitest/browser-playwright": "4.1.10",
+    "@vitest/browser-playwright": "4.1.11",
     "concurrently": "10.0.5",
     "eslint": "10.6.0",
     "jsdom": "30.0.1",
     "playwright": "1.62.1",
     "prettier": "3.9.6",
     "rimraf": "6.1.3",
-    "storybook": "10.5.8",
+    "storybook": "10.5.10",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
-  "version": "0.1.6",
+  "version": "0.1.8",
   "scripts": {
     "clean": "rimraf lib tsconfig.tsbuildinfo",
     "prebuild": "pnpm run clean",