@fohte/storybook-addon 0.1.0 → 0.1.2

package/README.md

@@ -35,6 +35,18 @@ export default config
 
 This wires up `overflow-check` and `external-resource-check` — no further setup needed.
 
+### overflow-check
+
+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
+import type { Parameters } from 'storybook/internal/types'
+
+export const parameters: Parameters = {
+  overflowCheck: { globalIgnoreSelectors: ['[data-slot="checkbox"]'] },
+}
+```
+
 ### unhandled-api-request-check
 
 This check needs to know which paths count as "API requests" (that's app-specific), and needs to be fed unhandled requests from your MSW setup. Configure it once and call `reportUnhandledApiRequest()` from `onUnhandledRequest` in `.storybook/preview.ts`:

package/lib/checks/check.d.ts

@@ -1,6 +1,6 @@
 export type StorybookCheck = {
     reset: () => void;
-    assert: (storyParameters?: unknown) => void;
+    assert: (storyParameters?: unknown, canvasElement?: Element) => void;
 };
 export declare function throwIfNotEmpty(urls: string[], message: string): void;
 //# sourceMappingURL=check.d.ts.map

package/lib/checks/overflow-check.js

@@ -1,32 +1,4 @@
 import { throwIfNotEmpty } from '#checks/check.js';
-// The consuming app's preview.ts calls reset()/assert() around each story
-// render (see preview.ts's beforeEach/afterEach). The story's container is a
-// bare <div> appended to document.body before anything is mounted into it —
-// reset() never gets `context.canvasElement` itself, so this is the only way
-// to reach the same element. Portal-based components (dialogs, popovers,
-// selects, etc.) append their own <div>s directly to document.body too, but
-// only *after* the story has mounted — so the container is reliably the
-// *first* element appended to body once a story starts, not the last. A
-// MutationObserver set up in reset() (which runs before the story mounts)
-// captures it.
-let storyRoot = null;
-let bodyObserver = null;
-function watchStoryRoot() {
-    storyRoot = null;
-    bodyObserver?.disconnect();
-    bodyObserver = new MutationObserver((mutations) => {
-        for (const mutation of mutations) {
-            for (const node of mutation.addedNodes) {
-                if (node instanceof Element) {
-                    storyRoot = node;
-                    bodyObserver?.disconnect();
-                    return;
-                }
-            }
-        }
-    });
-    bodyObserver.observe(document.body, { childList: true });
-}
 function describeElement(el) {
     const id = el.id ? `#${el.id}` : '';
     const classAttr = el.getAttribute('class');
@@ -143,20 +115,43 @@ function ignoreSelectorsOf(overflowCheck) {
         return [];
     return ignoreSelectors.filter((s) => typeof s === 'string');
 }
+// A separate key from `ignoreSelectors`, set once by the consuming app in
+// its top-level `preview.ts` `parameters` export (not via a module-level
+// setter — a story's own `parameters.overflowCheck` and the app's global one
+// live in different Storybook parameter scopes, which Storybook deep-merges
+// by object key, so a story setting `ignoreSelectors` can't drop this list).
+// This also sidesteps bundlers that resolve this addon's module twice for
+// one consumer (once from the app's own import, once via Storybook's addon
+// loader) — `context.parameters` comes from Storybook itself, not from
+// either module instance, so it's unaffected either way.
+function globalIgnoreSelectorsOf(overflowCheck) {
+    if (overflowCheck === undefined)
+        return [];
+    if (!('globalIgnoreSelectors' in overflowCheck))
+        return [];
+    const { globalIgnoreSelectors } = overflowCheck;
+    if (!Array.isArray(globalIgnoreSelectors))
+        return [];
+    return globalIgnoreSelectors.filter((s) => typeof s === 'string');
+}
 export const overflowCheck = {
-    reset: watchStoryRoot,
-    assert: (storyParameters) => {
+    reset: () => { },
+    assert: (storyParameters, canvasElement) => {
         const params = overflowCheckParameters(storyParameters);
         if (isDisabled(params))
             return;
-        if (storyRoot == null) {
-            // The MutationObserver in watchStoryRoot() hasn't seen an element
-            // appended to body yet (e.g. the story renders nothing). Skip rather
-            // than fail, since there is no root to scan.
-            console.warn('[overflow-check] story root not detected; skipping overflow scan');
+        if (canvasElement == null) {
+            // Real Storybook runs always pass canvasElement (it's the story's
+            // mount container); this only triggers a caller invoking assert()
+            // directly without one. Skip rather than fail, since there is no root
+            // to scan.
+            console.warn('[overflow-check] no canvasElement in story context; skipping overflow scan');
             return;
         }
-        throwIfNotEmpty(findOverflows(storyRoot, ignoreSelectorsOf(params)), 'Story has element(s) overflowing their container (clipped and invisible)');
+        throwIfNotEmpty(findOverflows(canvasElement, [
+            ...globalIgnoreSelectorsOf(params),
+            ...ignoreSelectorsOf(params),
+        ]), 'Story has element(s) overflowing their container (clipped and invisible)');
     },
 };
 //# sourceMappingURL=overflow-check.js.map

package/lib/checks/unhandled-api-request-check.d.ts

@@ -1,7 +1,15 @@
 import type { StorybookCheck } from '#checks/check.js';
+interface UnhandledApiRequestState {
+    pathPrefixes: string[];
+    unhandledApiRequestUrls: string[];
+}
+declare global {
+    var __fohteStorybookAddonUnhandledApiRequestState__: UnhandledApiRequestState | undefined;
+}
 export declare function configureUnhandledApiRequestCheck(options: {
     pathPrefixes: string[];
 }): void;
 export declare function reportUnhandledApiRequest(url: string): boolean;
 export declare const unhandledApiRequestCheck: StorybookCheck;
+export {};
 //# sourceMappingURL=unhandled-api-request-check.d.ts.map

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

@@ -1,15 +1,13 @@
 import { throwIfNotEmpty } from '#checks/check.js';
-// Populated by reportUnhandledApiRequest(), which the consuming app's MSW
-// `onUnhandledRequest` callback calls — a story hitting an API endpoint with
-// no MSW handler gets MSW's error response instead of real data, so the
-// screenshot captures a broken UI state without failing otherwise.
-const unhandledApiRequestUrls = [];
-// Which paths count as "API requests" is app-specific (tq uses `/api/`, a
-// future app might use a different prefix or none), so it's configured once
-// by the consuming app rather than hardcoded here.
-let pathPrefixes = [];
+function globalState() {
+    globalThis.__fohteStorybookAddonUnhandledApiRequestState__ ??= {
+        pathPrefixes: [],
+        unhandledApiRequestUrls: [],
+    };
+    return globalThis.__fohteStorybookAddonUnhandledApiRequestState__;
+}
 export function configureUnhandledApiRequestCheck(options) {
-    pathPrefixes = options.pathPrefixes;
+    globalState().pathPrefixes = options.pathPrefixes;
 }
 // Returns whether the request was recorded, so the caller can decide whether
 // to also print MSW's own error for it.
@@ -17,18 +15,19 @@ export function reportUnhandledApiRequest(url) {
     const parsed = new URL(url);
     if (parsed.origin !== window.location.origin)
         return false;
-    if (!pathPrefixes.some((prefix) => parsed.pathname.startsWith(prefix))) {
+    const state = globalState();
+    if (!state.pathPrefixes.some((prefix) => parsed.pathname.startsWith(prefix))) {
         return false;
     }
-    unhandledApiRequestUrls.push(parsed.pathname);
+    state.unhandledApiRequestUrls.push(parsed.pathname);
     return true;
 }
 export const unhandledApiRequestCheck = {
     reset: () => {
-        unhandledApiRequestUrls.length = 0;
+        globalState().unhandledApiRequestUrls.length = 0;
     },
     assert: () => {
-        throwIfNotEmpty(unhandledApiRequestUrls, 'Story made unhandled API request(s); add an MSW handler for');
+        throwIfNotEmpty(globalState().unhandledApiRequestUrls, 'Story made unhandled API request(s); add an MSW handler for');
     },
 };
 //# sourceMappingURL=unhandled-api-request-check.js.map

package/lib/preview.js

@@ -37,7 +37,8 @@ export const beforeEach = () => {
         check.reset();
 };
 export const afterEach = (context) => {
-    for (const check of checks)
-        check.assert(context.parameters);
+    for (const check of checks) {
+        check.assert(context.parameters, context.canvasElement);
+    }
 };
 //# sourceMappingURL=preview.js.map

package/package.json

@@ -51,7 +51,7 @@
     "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
-  "version": "0.1.0",
+  "version": "0.1.2",
   "scripts": {
     "clean": "rimraf lib tsconfig.tsbuildinfo",
     "prebuild": "pnpm run clean",