From 0736e547f0823d1dffce8e96ea21de4511a924d2 Mon Sep 17 00:00:00 2001 From: Nayan Date: Thu, 6 Aug 2026 08:45:00 +0530 Subject: [PATCH] feat(overlay): storybook the editor's own chrome MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The inspector's controls and sections, the whole Design panel, the chat timeline, diffs, toasts and the device presets — browsable in isolation, and runnable as tests in real Chromium. Stories sit next to the code they cover (src/**/*.stories.ts), the same convention the .test.ts files already follow. Storybook starts through turbo, because the token package's dist has to exist before its builder runs. --- packages/overlay/.storybook/main.ts | 68 ++ packages/overlay/.storybook/preview.ts | 247 +++++++ packages/overlay/src/stories/captions.ts | 26 + packages/overlay/src/stories/chrome.ts | 464 ++++++++++++ packages/overlay/src/stories/fixtures.ts | 506 +++++++++++++ .../src/stories/foundations.stories.ts | 292 ++++++++ packages/overlay/src/stories/lifecycle.ts | 56 ++ packages/overlay/src/stories/story-panel.ts | 280 +++++++ packages/overlay/src/stories/subjects.test.ts | 124 ++++ packages/overlay/src/stories/subjects.ts | 683 ++++++++++++++++++ packages/overlay/vitest.browser.config.ts | 57 ++ 11 files changed, 2803 insertions(+) create mode 100644 packages/overlay/.storybook/main.ts create mode 100644 packages/overlay/.storybook/preview.ts create mode 100644 packages/overlay/src/stories/captions.ts create mode 100644 packages/overlay/src/stories/chrome.ts create mode 100644 packages/overlay/src/stories/fixtures.ts create mode 100644 packages/overlay/src/stories/foundations.stories.ts create mode 100644 packages/overlay/src/stories/lifecycle.ts create mode 100644 packages/overlay/src/stories/story-panel.ts create mode 100644 packages/overlay/src/stories/subjects.test.ts create mode 100644 packages/overlay/src/stories/subjects.ts create mode 100644 packages/overlay/vitest.browser.config.ts diff --git a/packages/overlay/.storybook/main.ts b/packages/overlay/.storybook/main.ts new file mode 100644 index 0000000..4178902 --- /dev/null +++ b/packages/overlay/.storybook/main.ts @@ -0,0 +1,68 @@ +import type { StorybookConfig } from "@storybook/html-vite"; + +/* + * Storybook for the overlay. + * + * The HTML renderer, and not as a fallback — it is the exact shape this code + * already has. Every seam in the overlay hands back an `HTMLElement` + * (`ControlHandle.element`, `renderFill(ctx, node)`, `DesignPanel.element`, + * `toolRow(item)`), which is precisely what an HTML story returns. A React + * renderer would mean a wrapper around each one and React in the dependency + * graph of a package that has deliberately never had it. + * + * What this buys that the test suite cannot: `vitest.config.ts` runs on + * happy-dom, and its own docstring — plus `inspector/test-support.ts`'s — lists + * what that costs. No layout, no native CSS nesting, `@layer` dropped entirely, + * no `CSSStyleDeclaration` iterator. Those are the four things the inspector + * reads. Here they are real, because this is a real browser. + */ +const config: StorybookConfig = { + addons: [ + // axe on every story. The overlay hand-wires its ARIA — `role="group"` plus + // a label on segmented groups, `aria-pressed` per cell, `aria-haspopup` + // /`aria-expanded` on selects — and `inspector/a11y.test.ts` asserts a + // sample of it. This checks the rest, on every story, for free. + "@storybook/addon-a11y", + /* + * Opt-in since Storybook 9, and not optional here. + * + * The editor is dark-only chrome, and three of its border tokens are + * `rgba(255,255,255,0.06…0.12)` — on Storybook's default white canvas they + * are invisible, so a hairline that is missing looks exactly like a hairline + * that is there. `preview.ts` defines the two grounds this repo has: the + * editor surface, and the white page the docks float over. + */ + "storybook/backgrounds", + /* + * The browser test tier — see `vitest.browser.config.ts`. + * + * Registered here so the runner and the UI agree on what a story is, but + * deliberately *not* wired into `pnpm test`: that runs from + * `.husky/pre-commit`, and a commit hook that launches Chromium fails on any + * machine that has not downloaded it. `make test-browser` opts in. + */ + "@storybook/addon-vitest", + ], + + framework: { name: "@storybook/html-vite", options: {} }, + + /* + * The fonts, which the overlay cannot render honestly without. + * + * `styles/index.ts` declares `@font-face` against `/__airship/fonts/*.woff2`, + * and in production only the proxy serves that path + * (`packages/server/src/proxy.ts`). The files themselves are emitted by + * `@airship/editor-tokens`' postbuild, so this mapping is why the `storybook` + * turbo task depends on that package's `build` — Storybook errors at startup + * on a missing `from`, rather than starting up and rendering everything in + * fallback fonts. Failing loudly is the right trade: the dock is 11px type in + * a 360px column, and it is a different piece of design in Helvetica. + */ + staticDirs: [ + { from: "../../editor-tokens/dist/fonts", to: "/__airship/fonts" }, + ], + + stories: ["../src/**/*.stories.ts"], +}; + +export default config; diff --git a/packages/overlay/.storybook/preview.ts b/packages/overlay/.storybook/preview.ts new file mode 100644 index 0000000..c525b85 --- /dev/null +++ b/packages/overlay/.storybook/preview.ts @@ -0,0 +1,247 @@ +import type { Preview } from "@storybook/html-vite"; +import { PREFIX } from "../src/dom"; +import { closeOpenPopover, mountPopoverHost } from "../src/popover-host"; +import { setCaptionsEnabled } from "../src/stories/captions"; +import { runStoryTeardown } from "../src/stories/lifecycle"; +import { overlayCss } from "../src/styles"; +import { setRuntimeTokens, setStaticTokens } from "../src/tokens/registry"; + +/* + * What every story needs around it before it can be looked at honestly. + * + * Each of the four things below is a *silent* failure if skipped: nothing + * throws, the story renders, and what you are looking at is wrong. That is the + * whole reason they are here rather than in each story. + */ + +/** + * The overlay stylesheet, as one tag, re-written in place. + * + * Deliberately not `injectStyles()`. That function guards on a module-level + * `injected` flag, and Vite resets module state on HMR — so editing any + * `styles/*.css.ts` clears the flag and appends a *second* + * `` + + (wrap === "none" ? body : `
${body}
`); + + const node = page.querySelector("[data-subject]"); + if (!node) { + throw new Error( + `Specimen "${name}" declares no [data-subject] node — the marker is how a ` + + "story says which element it is about. See stories/subjects.ts." + ); + } + return { node, page }; +} + +/** One specimen in the story's own document. */ +export function subject(name: SubjectName): Subject { + return buildSpecimenIn(document, name); +} + +// --------------------------------------------------------------------------- +// The cross-realm case +// --------------------------------------------------------------------------- + +/** A subject in its own document, plus the `Surface` that describes it. */ +export interface FrameSubject extends Subject { + surface: Surface; +} + +/** + * An empty frame, and the function that fills it once it has been mounted. + * + * Two steps rather than one, and the reason is a browser rule with teeth: + * **moving an iframe in the DOM reloads it.** A frame written to while it is + * still detached — or while it sits somewhere other than where the story will + * finally put it — is wiped the moment Storybook appends the story to the + * canvas, and what is left is a blank white pane and a `Surface` pointing at a + * document that no longer exists. Nothing throws; the panel simply reads an + * empty page and reports it accurately. + * + * So `frame` goes into the story's DOM first, and `fill` runs after Storybook + * has mounted it. + */ +export interface PendingFrame { + fill: (name: SubjectName) => FrameSubject; + frame: HTMLIFrameElement; +} + +/** + * The same specimens, in their own document, with a `Surface` pointed at them. + * + * This exists for one specific and non-obvious reason. `stubSurface()` in + * `test-support.ts` returns `doc: document` — which under happy-dom is a clean + * empty document, and in Storybook is the *preview iframe*, carrying Storybook's + * own stylesheets. `matchedRules` walks `doc.styleSheets`, and `isOwnSheet` skips + * the overlay's sheet but knows nothing about Storybook's. So a CSS-pane story on + * a same-document subject would list Storybook's reset as the element's + * provenance, which is worse than useless: it is a plausible wrong answer. + * + * Putting the subject in its own document fixes it exactly, and does so by being + * more faithful rather than less — this is the production topology. In canvas + * mode the app runs in frame iframes while the overlay runs in the shell, which + * is why `realm.ts` exists at all. The panel resolves `getComputedStyle` against + * the node's own window and duck-types its `instanceof` checks, so it handles + * this natively. + */ +export function pendingFrame(): PendingFrame { + const frame = document.createElement("iframe"); + // Named, because the a11y pass checks `frame-title` and an unnamed frame is a + // real finding rather than a harness artefact — the canvas frames want one too. + frame.title = "The page being inspected"; + frame.style.cssText = + "width: 100%; height: 100%; min-height: 420px; border: 0; background: #fff;"; + + const fill = (name: SubjectName): FrameSubject => { + const doc = frame.contentDocument; + const win = frame.contentWindow; + if (!(doc && win)) { + throw new Error("iframe has no document — was it mounted first?"); + } + // `document.write` rather than `srcdoc`: srcdoc loads asynchronously, and + // the caller needs the subject measurable in the same tick it is handed + // back so the panel can seed from a real box. + doc.open(); + doc.write(""); + doc.close(); + + const built = buildSpecimenIn(doc, name); + doc.body.style.margin = "0"; + doc.body.style.padding = "24px"; + doc.body.append(built.page); + + return { ...built, surface: frameSurface(frame, doc, win) }; + }; + + return { fill, frame }; +} + +/** + * A `Surface` over one frame. + * + * Only the members the panel actually reaches for are real; the rest answer + * honestly for a static, unzoomed frame. This mirrors `stubSurface()`'s approach + * and its rationale — implement what is used, and let the type document the + * rest — but differs in the one member that matters here, `doc`. + */ +function frameSurface( + frame: HTMLIFrameElement, + doc: Document, + win: Window +): Surface { + const offset = () => frame.getBoundingClientRect(); + return { + bounds: () => { + const r = offset(); + return { height: r.height, left: r.left, top: r.top, width: r.width }; + }, + doc, + elementAtScreen: (point) => { + const r = offset(); + return doc.elementFromPoint(point.x - r.left, point.y - r.top); + }, + extract: (target: Element) => + Promise.resolve({ + context: contextOf(target) as ElementContext, + source: null, + }), + id: "story-frame", + isLive: true, + // 1:1 — the canvas zoom is a separate concern and none of these stories + // exercise it. A scaled frame would need `toScreen`/`toLocal` to multiply. + scale: 1, + scanTokens: () => ({ framework: "unknown", tokens: [] }), + toLocal: (point) => { + const r = offset(); + return { x: point.x - r.left, y: point.y - r.top }; + }, + toScreen: (rect) => { + const r = offset(); + return { ...rect, left: rect.left + r.left, top: rect.top + r.top }; + }, + win, + }; +} diff --git a/packages/overlay/vitest.browser.config.ts b/packages/overlay/vitest.browser.config.ts new file mode 100644 index 0000000..9170190 --- /dev/null +++ b/packages/overlay/vitest.browser.config.ts @@ -0,0 +1,57 @@ +import { storybookTest } from "@storybook/addon-vitest/vitest-plugin"; +import { playwright } from "@vitest/browser-playwright"; +import { defineConfig } from "vitest/config"; + +/* + * The browser tier: every story, run as a test, in real Chromium. + * + * ## Why this is a second file rather than a `projects` array + * + * The obvious shape is one `vitest.config.ts` with two projects — happy-dom for + * the unit tests, a browser project for the stories. It is the wrong shape here + * for a reason outside vitest entirely: `.husky/pre-commit` runs `pnpm test`, + * which reaches `vitest run` with no project filter, which would run *both*. + * Every commit would launch Chromium, and on a machine that has not downloaded + * it the hook would fail and block the commit. This repo has no CI — `make + * check` is documented in the Makefile as "what CI should run" — so that hook is + * the only gate there is, and making it depend on a browser download is a bad + * trade for a catalogue. + * + * Separate file, separate script, separate turbo task, not wired into `test`. + * `make test-browser` opts in; `make browsers` fetches the browser. + * + * ## What it adds that the unit suite cannot + * + * `vitest.config.ts`'s own docstring, and `inspector/test-support.ts`'s, both + * list what happy-dom cannot do: no layout, no native CSS nesting, `@layer` + * dropped entirely, no `CSSStyleDeclaration` iterator. Those are the four things + * the inspector reads. Here they are real — which makes this the complement to + * the unit suite rather than a second copy of it. + * + * Every story becomes a smoke test that it renders without throwing, every + * `play` function becomes an interaction test, and the `a11y` parameter in + * `preview.ts` makes an axe violation fail the run rather than merely appear in + * a panel. + * + * ## What is deliberately absent + * + * No `test.include`: `main.ts`'s `stories` glob is the single index, and passing + * one here is ignored with a warning. No `setupFiles` either — since Storybook + * 10.3 the plugin applies `preview.ts`'s annotations itself, and a hand-rolled + * `setProjectAnnotations` now conflicts with that rather than enabling it. The + * risk that setup file was guarding against — stories running *without* the + * decorator, rendering unstyled, and passing anyway — is covered instead by the + * `play` assertions on `Foundations/Tokens`, which check the token scope and the + * fonts from inside the run. + */ +export default defineConfig({ + plugins: [storybookTest({ configDir: ".storybook" })], + test: { + browser: { + enabled: true, + headless: true, + instances: [{ browser: "chromium" }], + provider: playwright(), + }, + }, +});