@fohte/storybook-addon 0.0.0 → 0.1.0

package/README.md

@@ -1,45 +1,85 @@
 # @fohte/storybook-addon
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+@fohte's personal Storybook addons.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+Runs three checks right after each story renders, and fails the story's test when one trips:
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+- **overflow-check** — flags elements whose content is clipped by their container (scrollWidth > clientWidth), 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.
 
-## Purpose
+It also injects CSS that hides the text-input caret and collapses all animations/transitions to their end state, keeping screenshots deterministic.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@fohte/storybook-addon`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Install
 
-## What is OIDC Trusted Publishing?
+```bash
+pnpm add -D @fohte/storybook-addon
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+# Peer dependencies
+pnpm add -D storybook vitest
+```
 
-## Setup Instructions
+## Usage
 
-To properly configure OIDC trusted publishing for this package:
+Add the addon to `.storybook/main.ts`:
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```ts
+import type { StorybookConfig } from '@storybook/react-vite'
 
-## DO NOT USE THIS PACKAGE
+const config: StorybookConfig = {
+  addons: ['@fohte/storybook-addon'],
+}
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+export default config
+```
 
-## More Information
+This wires up `overflow-check` and `external-resource-check` — no further setup needed.
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+### 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`:
 
-**Maintained for OIDC setup purposes only**
+```ts
+import {
+  configureUnhandledApiRequestCheck,
+  reportUnhandledApiRequest,
+} from '@fohte/storybook-addon/preview'
+import { initialize } from 'msw-storybook-addon'
+
+configureUnhandledApiRequestCheck({ pathPrefixes: ['/api/'] })
+
+initialize({
+  onUnhandledRequest: ({ url }, print) => {
+    if (reportUnhandledApiRequest(url)) {
+      print.error()
+    }
+  },
+})
+```
+
+## Addon `afterEach` ordering
+
+Storybook runs multiple addons' `afterEach` hooks serially, in the **reverse** of the order they're listed in `main.ts`'s `addons` array — the addon listed last runs its `afterEach` first. The consuming app's own `preview.ts`/`preview.tsx` `afterEach` runs before every addon's `afterEach`. If one hook throws, the remaining ones are skipped (fail-fast).
+
+This matters once a screenshot-capturing addon is added: to keep "capture first, then let this package's checks fail the test" working, list that addon **after** `@fohte/storybook-addon` in the `addons` array.
+
+## Development
+
+### Setup
+
+```bash
+pnpm install
+pnpm test
+```
+
+### Scripts
+
+- `pnpm test` - Run type checking and unit tests
+- `pnpm test:type` - Type-check without emitting
+- `pnpm test:unit` - Run unit tests (vitest)
+- `pnpm build` - Compile TypeScript to `lib/`
+- `pnpm lint` - Run ESLint
+
+### Release process
+
+This project uses [release-please](https://github.com/googleapis/release-please). Merging a PR whose title follows [Conventional Commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `feat!:`/`fix!:` for breaking changes) into `main` updates a Release PR; merging that Release PR tags a GitHub release and publishes to npm.

package/lib/checks/check.d.ts

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

package/lib/checks/check.js

@@ -0,0 +1,9 @@
+import { assert } from 'vitest';
+export function throwIfNotEmpty(urls, message) {
+    if (urls.length === 0)
+        return;
+    const list = urls.join('\n');
+    urls.length = 0;
+    assert.fail(`${message}:\n${list}`);
+}
+//# sourceMappingURL=check.js.map

package/lib/checks/external-resource-check.d.ts

@@ -0,0 +1,3 @@
+import type { StorybookCheck } from '#checks/check.js';
+export declare const externalResourceCheck: StorybookCheck;
+//# sourceMappingURL=external-resource-check.d.ts.map

package/lib/checks/external-resource-check.js

@@ -0,0 +1,32 @@
+import { throwIfNotEmpty } from '#checks/check.js';
+// A story that loads a non-same-origin http(s) resource (e.g. a remote
+// avatar image) races the capture against that request's completion over the
+// real network, so the same story can rasterize differently between runs.
+// Failing the test surfaces this instead of letting it show up as unstable
+// screenshot diffs; fix stories by inlining the resource as a data URI.
+const externalResourceUrls = [];
+// Entries older than this are from a previous story and must not be
+// attributed to the one currently rendering.
+let resetAt = 0;
+function isExternalResourceUrl(url) {
+    const { protocol, origin } = new URL(url);
+    return ((protocol === 'http:' || protocol === 'https:') &&
+        origin !== window.location.origin);
+}
+new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+        if (entry.startTime >= resetAt && isExternalResourceUrl(entry.name)) {
+            externalResourceUrls.push(entry.name);
+        }
+    }
+}).observe({ type: 'resource', buffered: true });
+export const externalResourceCheck = {
+    reset: () => {
+        resetAt = performance.now();
+        externalResourceUrls.length = 0;
+    },
+    assert: () => {
+        throwIfNotEmpty(externalResourceUrls, 'Story loaded non-same-origin resource(s), which makes VRT captures flaky');
+    },
+};
+//# sourceMappingURL=external-resource-check.js.map

package/lib/checks/overflow-check.d.ts

@@ -0,0 +1,3 @@
+import type { StorybookCheck } from '#checks/check.js';
+export declare const overflowCheck: StorybookCheck;
+//# sourceMappingURL=overflow-check.d.ts.map

package/lib/checks/overflow-check.js

@@ -0,0 +1,162 @@
+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');
+    const classes = classAttr !== null && classAttr !== ''
+        ? `.${classAttr.trim().split(/\s+/).join('.')}`
+        : '';
+    return `${el.tagName.toLowerCase()}${id}${classes}`;
+}
+// `text-overflow: ellipsis` is excluded because it's a deliberate "this is
+// cut off, here's more" affordance (e.g. Tailwind's `truncate`), not a
+// silent, undiscoverable clip — exactly the class of intentional truncation
+// this check isn't meant to flag.
+//
+// `overflow-x: visible` elements are NOT excluded, even though such an
+// element doesn't clip its own content: in a real app, some clipping
+// ancestor above it usually reports the same overflow independently, but a
+// story has no such ancestor above its scan root — an `overflow-x: visible`
+// element may be the only place a story's overflow is ever caught.
+function isIntentionalTruncation(cs) {
+    return cs.textOverflow === 'ellipsis';
+}
+// The standard visually-hidden a11y technique (e.g. Tailwind's `sr-only`)
+// shrinks an element to a 1x1px box and clips it on purpose, to keep it
+// readable by screen readers while invisible to sighted users. A 1x1px box
+// can never show meaningfully clipped content to a sighted user either way,
+// so this is a safe, general skip rather than a per-story exclusion.
+function isVisuallyHidden(el) {
+    return el.clientWidth <= 1 && el.clientHeight <= 1;
+}
+// A single overflowing element is picked up again by every clipping
+// ancestor above it, up to the scan root (per
+// https://www.w3.org/TR/cssom-view-1/#scrolling-area, unclipped overflow
+// keeps bubbling upward), so one bug would otherwise read as N separate
+// findings. Group ancestor-descendant reports into the topmost ancestor's
+// group instead of dropping any of them — the chain itself is a hint for
+// where the fix belongs, since the root cause (e.g. a parent flex layout)
+// isn't always the innermost element. `root.querySelectorAll` yields
+// elements in document order, so an element's ancestors are always seen
+// (and can become its group) before it is.
+function groupByAncestor(entries) {
+    const groups = [];
+    for (const { el, description } of entries) {
+        const group = groups.find((g) => g.root.contains(el));
+        if (group) {
+            group.descriptions.push(description);
+        }
+        else {
+            groups.push({ root: el, descriptions: [description] });
+        }
+    }
+    return groups.map((g) => g.descriptions.length === 1
+        ? g.descriptions.join('')
+        : `${String(g.descriptions.length)} chained overflows (same root cause, outermost first):\n  ${g.descriptions.join('\n  ')}`);
+}
+// el.scrollWidth > el.clientWidth means the element's content doesn't fit
+// inside its own padding box (clientWidth) — i.e. some of it is clipped and
+// invisible.
+//
+// This only measures overflow on the inline-end (right, in LTR) side: the
+// CSSOM "scrolling area" a scrollable box exposes never extends past its
+// inline-start edge, so content overflowing to the *left* is invisible to
+// this check (https://www.w3.org/TR/cssom-view-1/#scrolling-area).
+// `position: fixed` elements are invisible to it too — they escape the
+// containing block chain, so an off-screen fixed element never shows up in
+// any ancestor's scrollWidth.
+function findOverflows(root, ignoreSelectors) {
+    const entries = [];
+    for (const el of root.querySelectorAll('*')) {
+        if (el.scrollWidth <= el.clientWidth)
+            continue;
+        if (isVisuallyHidden(el))
+            continue;
+        if (ignoreSelectors.some((selector) => el.matches(selector)))
+            continue;
+        if (isIntentionalTruncation(getComputedStyle(el)))
+            continue;
+        const overflowPx = el.scrollWidth - el.clientWidth;
+        entries.push({
+            el,
+            description: `${describeElement(el)}: scrollWidth=${String(el.scrollWidth)} > clientWidth=${String(el.clientWidth)} (+${String(overflowPx)}px)`,
+        });
+    }
+    return groupByAncestor(entries);
+}
+function overflowCheckParameters(storyParameters) {
+    if (typeof storyParameters !== 'object' || storyParameters === null) {
+        return undefined;
+    }
+    if (!('overflowCheck' in storyParameters))
+        return undefined;
+    const { overflowCheck } = storyParameters;
+    if (typeof overflowCheck !== 'object' || overflowCheck === null) {
+        return undefined;
+    }
+    return overflowCheck;
+}
+function isDisabled(overflowCheck) {
+    return (overflowCheck !== undefined &&
+        'disable' in overflowCheck &&
+        overflowCheck.disable === true);
+}
+// Narrower than `overflowCheck.disable`: exempt one intentionally-overflowing
+// element (e.g. a chip row using `overflow-x-auto`, or a fixed-scrollbar
+// sizing artifact) by CSS selector via the story's own parameters, matching
+// only the element itself — not its descendants — so the rest of the story
+// (including anything nested inside the matched element) still gets checked.
+function ignoreSelectorsOf(overflowCheck) {
+    if (overflowCheck === undefined)
+        return [];
+    if (!('ignoreSelectors' in overflowCheck))
+        return [];
+    const { ignoreSelectors } = overflowCheck;
+    if (!Array.isArray(ignoreSelectors))
+        return [];
+    return ignoreSelectors.filter((s) => typeof s === 'string');
+}
+export const overflowCheck = {
+    reset: watchStoryRoot,
+    assert: (storyParameters) => {
+        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');
+            return;
+        }
+        throwIfNotEmpty(findOverflows(storyRoot, 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

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

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

@@ -0,0 +1,34 @@
+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 = [];
+export function configureUnhandledApiRequestCheck(options) {
+    pathPrefixes = options.pathPrefixes;
+}
+// Returns whether the request was recorded, so the caller can decide whether
+// to also print MSW's own error for it.
+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))) {
+        return false;
+    }
+    unhandledApiRequestUrls.push(parsed.pathname);
+    return true;
+}
+export const unhandledApiRequestCheck = {
+    reset: () => {
+        unhandledApiRequestUrls.length = 0;
+    },
+    assert: () => {
+        throwIfNotEmpty(unhandledApiRequestUrls, 'Story made unhandled API request(s); add an MSW handler for');
+    },
+};
+//# sourceMappingURL=unhandled-api-request-check.js.map

package/lib/errors.d.ts

@@ -0,0 +1,4 @@
+export declare abstract class BoundaryError extends Error {
+    constructor(message: string, cause: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/lib/errors.js

@@ -0,0 +1,30 @@
+// Wrap a caught external error before re-throwing, so it carries a
+// domain-meaningful message while preserving the original via `cause`.
+// Subclass per interop boundary — `name` is derived automatically, so no
+// constructor override is needed. The try and the throw this requires each
+// need their own eslint-disable-next-line comment, since @fohte/eslint-config's
+// errorHandling bans ThrowStatement and TryStatement as separate selectors:
+//
+//   export class TaskStorePersistenceError extends BoundaryError {}
+//
+//   // eslint-disable-next-line no-restricted-syntax -- interop boundary
+//   try {
+//     ...
+//   } catch (caughtErr) {
+//     const wrapped = new TaskStorePersistenceError('failed to save', caughtErr)
+//     // eslint-disable-next-line no-restricted-syntax -- interop boundary
+//     throw wrapped
+//   }
+//
+// To report a wrapped error under a stable fingerprint (for Sentry
+// grouping) without changing control flow, call `captureWithFingerprint`
+// (from `@fohte/service-kit/observability`, see src/bootstrap.ts — only
+// generated when `error_tracking` or `is_web_app` is enabled) right before
+// re-throwing.
+export class BoundaryError extends Error {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = new.target.name;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/lib/preview.d.ts

@@ -0,0 +1,6 @@
+import type { AfterEach, BeforeEach, Parameters, WebRenderer } from 'storybook/internal/types';
+export { configureUnhandledApiRequestCheck, reportUnhandledApiRequest, } from '#checks/unhandled-api-request-check.js';
+export declare const parameters: Parameters;
+export declare const beforeEach: BeforeEach<WebRenderer>;
+export declare const afterEach: AfterEach<WebRenderer>;
+//# sourceMappingURL=preview.d.ts.map

package/lib/preview.js

@@ -0,0 +1,43 @@
+import { externalResourceCheck } from '#checks/external-resource-check.js';
+import { overflowCheck } from '#checks/overflow-check.js';
+import { unhandledApiRequestCheck } from '#checks/unhandled-api-request-check.js';
+export { configureUnhandledApiRequestCheck, reportUnhandledApiRequest, } from '#checks/unhandled-api-request-check.js';
+function injectStyle(css) {
+    const style = document.createElement('style');
+    style.textContent = css;
+    document.head.appendChild(style);
+}
+// The native text-input caret blinks on an OS timer, so a captured frame of a
+// focused input/contenteditable is on or off at random — same content,
+// different pixels between runs. Hiding it keeps captures deterministic
+// without touching application code.
+injectStyle('input, textarea, [contenteditable] { caret-color: transparent !important; }');
+// CSS animations/transitions (popup open/close fades, zooms, spinners, ...)
+// capture at whatever frame happens to be on screen when the screenshot
+// fires, so the same story rasterizes differently between runs even though
+// nothing about it actually changed. Forcing zero duration collapses every
+// animation/transition to its end state instantly, keeping captures
+// deterministic without touching application code.
+injectStyle(`
+  *, *::before, *::after {
+    animation-duration: 0s !important;
+    animation-delay: 0s !important;
+    transition-duration: 0s !important;
+    transition-delay: 0s !important;
+  }
+`);
+const checks = [
+    externalResourceCheck,
+    unhandledApiRequestCheck,
+    overflowCheck,
+];
+export const parameters = {};
+export const beforeEach = () => {
+    for (const check of checks)
+        check.reset();
+};
+export const afterEach = (context) => {
+    for (const check of checks)
+        check.assert(context.parameters);
+};
+//# sourceMappingURL=preview.js.map

package/package.json

@@ -1,10 +1,67 @@
 {
   "name": "@fohte/storybook-addon",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @fohte/storybook-addon",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+  "description": "@fohte's personal Storybook addons",
+  "license": "MIT",
+  "author": "Hayato Kawai <fohte.hk@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fohte/storybook-addon.git"
+  },
+  "type": "module",
+  "exports": {
+    "./preview": {
+      "types": "./lib/preview.d.ts",
+      "default": "./lib/preview.js"
+    }
+  },
+  "imports": {
+    "#*.js": "./lib/*.js"
+  },
+  "files": [
+    "lib",
+    "!lib/**/*.map",
+    "!lib/**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "storybook": "^10.0.0",
+    "vitest": "^4.0.0"
+  },
+  "dependencies": {
+    "neverthrow": "8.2.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "21.2.1",
+    "@eslint/eslintrc": "3.3.6",
+    "@fohte/eslint-config": "0.4.0",
+    "@ninoseki/eslint-plugin-neverthrow": "0.2.0",
+    "@tsconfig/node-lts": "24.0.0",
+    "@tsconfig/strictest": "2.0.8",
+    "@types/jsdom": "30.0.0",
+    "@types/node": "24.13.3",
+    "concurrently": "10.0.4",
+    "eslint": "10.6.0",
+    "jsdom": "30.0.1",
+    "prettier": "3.9.6",
+    "rimraf": "6.1.3",
+    "storybook": "10.5.7",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "version": "0.1.0",
+  "scripts": {
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "prebuild": "pnpm run clean",
+    "build": "tsc --project tsconfig.build.json",
+    "lint": "eslint .",
+    "format:eslint": "eslint --fix .",
+    "format:prettier": "prettier --write .",
+    "format": "conc -m 1 pnpm:format:eslint pnpm:format:prettier",
+    "test": "conc pnpm:test:type pnpm:test:unit",
+    "test:type": "tsc --noEmit",
+    "test:unit": "vitest run"
+  }
+}