@uxfront/layer-docs 0.3.0 → 0.4.1

package/storybook/index.ts

@@ -0,0 +1,362 @@
+/**
+ * `@uxfront/layer-docs/storybook` — the Storybook-side half of the docs embed
+ * contract.
+ *
+ * The docs page and the Storybook it embeds talk over `postMessage`, and they
+ * deploy independently. That makes the message names a contract between two
+ * repositories, so they live here — imported by both sides — rather than being
+ * retyped as string literals in a manager config, a preview config and a Vue
+ * component that can each drift on their own.
+ *
+ * This module is deliberately framework-free: no Vue, no Nuxt, no Storybook
+ * imports. It runs inside a Storybook manager or preview bundle, where none of
+ * those are guaranteed and the Storybook API surface differs per framework. The
+ * addon-specific work — flipping a dark-mode addon, updating a theme store —
+ * stays in the consumer's config and is reached through the `onTheme` callback.
+ *
+ * ## The two topologies
+ *
+ * A docs page embeds one of two Storybook surfaces, and the height signal takes
+ * a different route through each:
+ *
+ * - **`full` / `panel`** — the page embeds the Storybook *manager*
+ *   (`/?path=/story/…`). The preview iframe measures the story and posts
+ *   {@link DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE} up to the manager, which adds its
+ *   own chrome and padding and posts {@link DOCS_EMBED_HEIGHT_MESSAGE} to the
+ *   docs page.
+ * - **`preview`** — the page embeds `iframe.html` directly. No manager exists
+ *   to relay, so the component marks the URL with `{@link DOCS_EMBED_PARAM}=1`
+ *   and the preview bridge posts {@link DOCS_EMBED_HEIGHT_MESSAGE} straight to
+ *   its parent.
+ *
+ * Either way exactly one signal name reaches the docs page.
+ *
+ * ## The compat window
+ *
+ * A docs site that already ships its own branded message names sets
+ * `legacyNamespace`. Every bridge then **accepts both** names on the messages
+ * it receives and **emits both** on the messages it sends, so a stale deploy on
+ * either side keeps working. Handling is idempotent — the same theme or height
+ * applied twice is the same state — so a peer that understands both names
+ * simply acts on whichever arrives first with no visible difference.
+ *
+ * Drop the option once both sides are on the neutral names.
+ *
+ * @example Storybook manager config
+ * ```ts
+ * // .storybook/manager.ts
+ * import { installDocsEmbedManagerBridge } from "@uxfront/layer-docs/storybook";
+ *
+ * installDocsEmbedManagerBridge({
+ *   legacyNamespace: "acme",
+ *   onTheme: (theme) => applyManagerTheme(theme),
+ * });
+ * ```
+ *
+ * @example Storybook preview config
+ * ```ts
+ * // .storybook/preview.ts
+ * import { installDocsEmbedPreviewBridge } from "@uxfront/layer-docs/storybook";
+ *
+ * installDocsEmbedPreviewBridge({
+ *   legacyNamespace: "acme",
+ *   onTheme: (theme) => channel.emit(DARK_MODE_EVENT_NAME, theme === "dark"),
+ * });
+ * ```
+ */
+
+/** Docs page → Storybook: the colour mode the embedding page is displaying. */
+export const DOCS_EMBED_THEME_MESSAGE = "uxfront:docs-embed:theme";
+
+/** Storybook preview → Storybook manager: the measured height of the story. */
+export const DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE = "uxfront:docs-embed:preview-height";
+
+/** Storybook → docs page: the height the embedding iframe should be given. */
+export const DOCS_EMBED_HEIGHT_MESSAGE = "uxfront:docs-embed:height";
+
+/**
+ * URL flag the docs component appends when it embeds `iframe.html` directly.
+ * Its presence tells the preview bridge that no manager sits between it and the
+ * docs page, so it must post the final height itself.
+ */
+export const DOCS_EMBED_PARAM = "docsEmbed";
+
+/** Storybook's story container element in the preview iframe. */
+const STORYBOOK_ROOT_ID = "storybook-root";
+
+/** Storybook's preview iframe element inside the manager. */
+const STORYBOOK_PREVIEW_IFRAME_ID = "storybook-preview-iframe";
+
+/**
+ * Breathing room the manager adds around the measured story so the embedded
+ * frame does not clip against its own border.
+ */
+const DEFAULT_PADDING = 64;
+
+export type DocsEmbedTheme = "light" | "dark";
+
+/** Every message name accepted and emitted for one leg of the contract. */
+export interface DocsEmbedMessageNames {
+  /** Docs page → Storybook theme message. */
+  theme: readonly string[];
+  /** Preview → manager height message. */
+  previewHeight: readonly string[];
+  /** Storybook → docs page height message. */
+  height: readonly string[];
+}
+
+/**
+ * The message names in play, newest first.
+ *
+ * With no `legacyNamespace` that is one name per leg. With one — say `"acme"` —
+ * each leg also accepts and emits `acme:theme`, `acme:preview-height` and
+ * `acme:height`, which is the compat window described in the module docs.
+ */
+export function docsEmbedMessageNames(legacyNamespace?: string): DocsEmbedMessageNames {
+  const legacy = legacyNamespace?.trim();
+
+  if (!legacy) {
+    return {
+      theme: [DOCS_EMBED_THEME_MESSAGE],
+      previewHeight: [DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE],
+      height: [DOCS_EMBED_HEIGHT_MESSAGE],
+    };
+  }
+
+  return {
+    theme: [DOCS_EMBED_THEME_MESSAGE, `${legacy}:theme`],
+    previewHeight: [DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE, `${legacy}:preview-height`],
+    height: [DOCS_EMBED_HEIGHT_MESSAGE, `${legacy}:height`],
+  };
+}
+
+/**
+ * Read a theme message, or `null` when the payload is not one of `names`.
+ *
+ * Anything that is not the string `"dark"` reads as `"light"`, matching how
+ * every receiver in the contract has always coerced it: a malformed payload
+ * lands on the default theme rather than throwing inside a message listener.
+ */
+export function readDocsEmbedTheme(data: unknown, names: readonly string[]): DocsEmbedTheme | null {
+  const message = asMessage(data);
+  if (!message || !names.includes(message.type)) return null;
+
+  return message.theme === "dark" ? "dark" : "light";
+}
+
+/**
+ * Read a height message, or `null` when the payload is not one of `names` or
+ * carries no usable height. Heights that are not finite positive numbers are
+ * rejected rather than written to a style attribute.
+ */
+export function readDocsEmbedHeight(data: unknown, names: readonly string[]): number | null {
+  const message = asMessage(data);
+  if (!message || !names.includes(message.type)) return null;
+
+  const { height } = message;
+  if (typeof height !== "number" || !Number.isFinite(height) || height <= 0) return null;
+
+  return height;
+}
+
+/**
+ * Height the manager reports for a story of `contentHeight`.
+ *
+ * `chromeHeight` is the manager UI wrapped around the preview — toolbar and
+ * addon panel — and is `0` in `full` mode, where none of it is visible.
+ */
+export function resolveDocsEmbedRelayHeight(options: {
+  contentHeight: number;
+  chromeHeight?: number;
+  padding?: number;
+}): number {
+  const { contentHeight, chromeHeight = 0, padding = DEFAULT_PADDING } = options;
+
+  return Math.max(0, chromeHeight) + contentHeight + padding;
+}
+
+export interface DocsEmbedManagerBridgeOptions {
+  /** Brand namespace to keep accepting and emitting during a migration. */
+  legacyNamespace?: string;
+  /** Padding added around the measured story. Defaults to 64. */
+  padding?: number;
+  /** Called with the theme the docs page is displaying. */
+  onTheme?: (theme: DocsEmbedTheme) => void;
+}
+
+/**
+ * Install the manager half: relay the docs page's theme down to the preview
+ * iframe, and relay the preview's measured height up to the docs page.
+ *
+ * Only relays height when the manager is itself framed — a Storybook opened
+ * directly has no docs page to report to. Returns a teardown function.
+ */
+export function installDocsEmbedManagerBridge(
+  options: DocsEmbedManagerBridgeOptions = {},
+): () => void {
+  const { legacyNamespace, padding = DEFAULT_PADDING, onTheme } = options;
+
+  const names = docsEmbedMessageNames(legacyNamespace);
+  const embedded = window !== window.parent;
+  const isFullMode = new URLSearchParams(window.location.search).has("full");
+
+  const onMessage = (event: MessageEvent) => {
+    const theme = readDocsEmbedTheme(event.data, names.theme);
+    if (theme) {
+      onTheme?.(theme);
+      const preview = previewIframe();
+      if (preview?.contentWindow) {
+        // Same document, so the origin is known — no reason to widen it to "*".
+        postAll(preview.contentWindow, names.theme, { theme }, window.location.origin);
+      }
+      return;
+    }
+
+    if (!embedded) return;
+
+    const contentHeight = readDocsEmbedHeight(event.data, names.previewHeight);
+    if (contentHeight === null) return;
+
+    let chromeHeight = 0;
+    if (!isFullMode) {
+      const preview = previewIframe();
+      // Chrome is measured, not assumed: without the preview element there is
+      // no honest number to send, so send nothing and keep the last height.
+      if (!preview) return;
+      chromeHeight = window.innerHeight - preview.offsetHeight;
+    }
+
+    const height = resolveDocsEmbedRelayHeight({ contentHeight, chromeHeight, padding });
+    postAll(window.parent, names.height, { height }, "*");
+  };
+
+  window.addEventListener("message", onMessage);
+
+  return () => window.removeEventListener("message", onMessage);
+}
+
+export interface DocsEmbedPreviewBridgeOptions {
+  /** Brand namespace to keep accepting and emitting during a migration. */
+  legacyNamespace?: string;
+  /**
+   * Extra height added when the docs page embeds this preview directly. Only
+   * applies to that topology; the manager owns padding in the relayed one.
+   */
+  padding?: number;
+  /** Called with the theme the docs page is displaying. */
+  onTheme?: (theme: DocsEmbedTheme) => void;
+}
+
+/**
+ * Install the preview half: receive the docs page's theme, and report the
+ * story's height to whichever parent is listening.
+ *
+ * Reports to the manager by default, or straight to the docs page when the URL
+ * carries {@link DOCS_EMBED_PARAM}. Returns a teardown function.
+ */
+export function installDocsEmbedPreviewBridge(
+  options: DocsEmbedPreviewBridgeOptions = {},
+): () => void {
+  const { legacyNamespace, padding = 0, onTheme } = options;
+
+  const names = docsEmbedMessageNames(legacyNamespace);
+  const teardown: Array<() => void> = [];
+
+  const onMessage = (event: MessageEvent) => {
+    const theme = readDocsEmbedTheme(event.data, names.theme);
+    if (theme) onTheme?.(theme);
+  };
+  window.addEventListener("message", onMessage);
+  teardown.push(() => window.removeEventListener("message", onMessage));
+
+  if (window !== window.parent) {
+    teardown.push(installHeightReporter(names, padding));
+  }
+
+  return () => {
+    for (const stop of teardown) stop();
+  };
+}
+
+/** Observe the story container and post its height whenever it changes. */
+function installHeightReporter(names: DocsEmbedMessageNames, padding: number): () => void {
+  const direct = new URLSearchParams(window.location.search).has(DOCS_EMBED_PARAM);
+  const target = direct ? names.height : names.previewHeight;
+
+  let lastHeight = 0;
+  const send = () => {
+    const root = document.getElementById(STORYBOOK_ROOT_ID);
+    if (!root) return;
+
+    // Through the manager, the relay re-measures the chrome around this exact
+    // box, so the story box is the right number. Embedded directly, the docs
+    // iframe shows this whole document — body padding included — so measure it.
+    const height = direct
+      ? Math.max(root.offsetHeight, document.documentElement.scrollHeight) + padding
+      : root.offsetHeight;
+
+    if (height === lastHeight) return;
+    lastHeight = height;
+    postAll(window.parent, target, { height }, "*");
+  };
+
+  let frame: number | undefined;
+  let resizeObserver: ResizeObserver | undefined;
+  let mutationObserver: MutationObserver | undefined;
+
+  const observe = () => {
+    const root = document.getElementById(STORYBOOK_ROOT_ID);
+    if (!root) {
+      // Storybook mounts the root asynchronously, and there is no event for it.
+      frame = requestAnimationFrame(observe);
+      return;
+    }
+
+    resizeObserver = new ResizeObserver(send);
+    resizeObserver.observe(root);
+    // A re-render that swaps content of the same height still changes what the
+    // story needs — the resize observer alone misses it.
+    mutationObserver = new MutationObserver(send);
+    mutationObserver.observe(root, { childList: true, subtree: true });
+    send();
+  };
+
+  if (document.readyState === "complete") {
+    observe();
+  } else {
+    window.addEventListener("load", observe);
+  }
+
+  return () => {
+    if (frame !== undefined) cancelAnimationFrame(frame);
+    window.removeEventListener("load", observe);
+    resizeObserver?.disconnect();
+    mutationObserver?.disconnect();
+  };
+}
+
+/** Post the same payload under every accepted name (the compat window). */
+function postAll(
+  target: Window,
+  names: readonly string[],
+  payload: Record<string, unknown>,
+  targetOrigin: string,
+): void {
+  for (const type of names) {
+    target.postMessage({ ...payload, type }, targetOrigin);
+  }
+}
+
+/** Narrow an untrusted `MessageEvent.data` to a typed message, or `null`. */
+function asMessage(data: unknown): { type: string; theme?: unknown; height?: unknown } | null {
+  if (typeof data !== "object" || data === null) return null;
+
+  const message = data as { type?: unknown; theme?: unknown; height?: unknown };
+  if (typeof message.type !== "string") return null;
+
+  return { type: message.type, theme: message.theme, height: message.height };
+}
+
+function previewIframe(): HTMLIFrameElement | null {
+  return document.getElementById(STORYBOOK_PREVIEW_IFRAME_ID) as HTMLIFrameElement | null;
+}

package/test/brand-palette.ts

@@ -92,6 +92,17 @@ export function describeBrandPaletteCss(options: BrandPaletteCssOptions): void {
       expect(css).toMatch(new RegExp(`@theme\\s+static\\s*\\{[\\s\\S]*--color-${scale}\\s*:`));
       expect(css).toMatch(new RegExp(`--ui-primary\\s*:\\s*var\\(\\s*--color-${scale}\\s*\\)`));
     });
+
+    // The OG card accent is resolved from this same declaration at build time
+    // (`utils/accent.ts`), because satori has no custom properties. The two
+    // assertions above already pin the declaration's existence; this one pins
+    // that it is *readable as a literal* — a value written as `var(...)` or a
+    // relative colour would parse here and then render as nothing in satori.
+    it(`declares --color-${scale} as a literal colour the OG renderer can use`, () => {
+      const declared = new RegExp(`--color-${scale}\\s*:\\s*([^;}]+)`).exec(css)?.[1]?.trim();
+      expect(declared).toBeDefined();
+      expect(declared).not.toMatch(/var\(|hsl\(\s*from|oklch\(\s*from|rgb\(\s*from/);
+    });
   });
 }
 

package/test/no-brand-leakage.test.ts

@@ -0,0 +1,124 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * The Storybook embed is the layer's most leak-prone surface: it is the only
+ * component whose whole job is to address somebody else's deployment. A default
+ * host "just for now", or a message name copied out of the repo it came from,
+ * breaks no build — it points the *next* consumer's docs at the previous
+ * consumer's Storybook, quietly. So it is a test, not a review habit.
+ *
+ * Three assertions, matching the three shapes the leak takes:
+ *
+ * 1. The embed's own source names no consumer.
+ * 2. Nothing in the package hardcodes a Storybook host.
+ * 3. Nothing in the package speaks a branded message namespace.
+ *
+ * Scopes differ on purpose. (1) is narrow because naming a consumer in a
+ * comment elsewhere is often a receipt — "+26.7 KB gzip on <consumer>,
+ * UXF-118" is evidence, not branding, and a guard that banned it would be
+ * training people to delete their sources. (2) and (3) are package-wide because
+ * a hardcoded host or a branded message name is a defect wherever it appears.
+ */
+
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+/** The embed surface: the files that exist to talk to a consumer's Storybook. */
+const EMBED_SOURCES = [
+  "app/components/content/StorybookEmbed.vue",
+  "app/utils/storybookEmbed.ts",
+  "storybook/index.ts",
+];
+
+/**
+ * Products that extend this layer. A match inside the embed surface means the
+ * neutral component learned something about a specific consumer.
+ */
+const CONSUMER_BRANDS = ["styleframe", "inkline"];
+
+/** Hostnames that exist only to be read, never fetched. */
+const DOCUMENTATION_HOSTS = ["example.com", "example.org", "localhost", "127.0.0.1"];
+
+/** The one namespace the package is allowed to speak. */
+const NEUTRAL_NAMESPACE = "uxfront:docs-embed";
+
+/**
+ * Any `<namespace>:theme` / `:height` / `:preview-height` string literal — the
+ * shape of this contract's message names, whoever coined them.
+ *
+ * Quoted strings only, not backticked ones: backticks here mark prose in doc
+ * comments, and a real message name built as a template literal is
+ * parameterized (`${namespace}:theme`) rather than branded.
+ */
+const MESSAGE_NAME_LITERAL = /["']([\w.-]+):(?:theme|height|preview-height)["']/g;
+
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".nuxt", ".output", "dist"]);
+const SOURCE_EXTENSIONS = [".ts", ".vue", ".css", ".json"];
+
+interface SourceFile {
+  path: string;
+  source: string;
+}
+
+function readSourceFiles(directory: string, collected: SourceFile[] = []): SourceFile[] {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRECTORIES.has(entry.name)) readSourceFiles(path, collected);
+      continue;
+    }
+    if (!SOURCE_EXTENSIONS.some((extension) => entry.name.endsWith(extension))) continue;
+    // Tests quote the literals they exercise — including a legacy namespace,
+    // which is the whole point of the compat-window cases.
+    if (entry.name.endsWith(".test.ts")) continue;
+
+    collected.push({ path: relative(PACKAGE_ROOT, path), source: readFileSync(path, "utf8") });
+  }
+
+  return collected;
+}
+
+describe("no brand leakage in the Storybook embed", () => {
+  const files = readSourceFiles(PACKAGE_ROOT);
+  const embedFiles = files.filter((file) => EMBED_SOURCES.includes(file.path));
+
+  // Guards the guard: a scan that silently matched nothing passes everything.
+  it("finds the embed surface and the rest of the package", () => {
+    expect(embedFiles.map((file) => file.path).sort()).toEqual([...EMBED_SOURCES].sort());
+    expect(files.length).toBeGreaterThan(50);
+  });
+
+  it.each(CONSUMER_BRANDS)("names no consumer (%s) in the embed surface", (brand) => {
+    const pattern = new RegExp(brand, "i");
+    const offenders = embedFiles
+      .filter((file) => pattern.test(file.source))
+      .map((file) => file.path);
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("hardcodes no Storybook host — where one is deployed is consumer config", () => {
+    const offenders = files.flatMap((file) =>
+      [...file.source.matchAll(/https?:\/\/[^\s"'`)]+/g)]
+        .map((match) => match[0])
+        .filter((url) => /storybook/i.test(url))
+        .filter((url) => !DOCUMENTATION_HOSTS.some((host) => url.includes(host)))
+        .map((url) => `${file.path}: ${url}`),
+    );
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("speaks no branded message namespace", () => {
+    const offenders = files.flatMap((file) =>
+      [...file.source.matchAll(MESSAGE_NAME_LITERAL)]
+        .filter((match) => match[1] !== NEUTRAL_NAMESPACE)
+        .map((match) => `${file.path}: ${match[0]}`),
+    );
+
+    expect(offenders).toEqual([]);
+  });
+});

package/utils/accent.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+/** Fallback accent when the brand token cannot be resolved. */
+export const FALLBACK_ACCENT = "#ffffff";
+
+/**
+ * Resolve the brand accent colour as a literal, build-time string.
+ *
+ * OG images are rendered by satori, which has no CSS cascade and no custom
+ * properties: `var(--ui-primary)` resolves to nothing. A dynamic Tailwind class
+ * is worse than useless, because every consumer *shadows* a stock Tailwind
+ * scale name with its own value — `--color-teal: hsl(189 53% 41%)` is not
+ * Tailwind's teal, so `text-teal-500` would render the wrong brand. The colour
+ * therefore has to arrive already resolved.
+ *
+ * It is read out of the consumer's CSS entry by following the same two hops the
+ * browser does, and that `describeBrandPaletteCss` already asserts:
+ *
+ *   `@theme static { --color-teal: hsl(189, 53%, 41%); }`  — the literal
+ *   `:root { --ui-primary: var(--color-teal); }`           — the alias
+ *
+ * Reading the CSS rather than `ui.colors.primary` is deliberate: `app.config.ts`
+ * is not merged into `nuxt.options.appConfig` at module-setup time (that object
+ * holds only `nuxt.config.ts`'s own `appConfig` key), so the scale name is not
+ * available there. The CSS is available, it is the definition rather than a
+ * discriminant, and it needs no configuration from the consumer at all.
+ *
+ * Shade variants are deliberately not followed: they are declared with
+ * relative-colour syntax (`hsl(from var(--color-teal) h s 60%)`), which satori
+ * cannot parse either.
+ */
+export function resolveBrandAccent(options: {
+  /** The consumer's registered CSS entries (`nuxt.options.css`). */
+  cssEntries: string[];
+  /** Consumer root, used to resolve relative CSS entry paths. */
+  rootDir: string;
+}): { accent: string; reason?: string } {
+  const { cssEntries, rootDir } = options;
+
+  for (const entry of cssEntries) {
+    const path = isAbsolute(entry) ? entry : join(rootDir, entry.replace(/^\.\//, ""));
+    if (!existsSync(path)) {
+      continue;
+    }
+    const accent = readAccent(readFileSync(path, "utf8"));
+    if (accent) {
+      return { accent };
+    }
+  }
+
+  return {
+    accent: FALLBACK_ACCENT,
+    reason:
+      "could not resolve `--ui-primary` to a literal colour in the registered " +
+      `CSS entries (${cssEntries.join(", ") || "none"})`,
+  };
+}
+
+/** Follow `--ui-primary` to the literal it aliases, or take it literally. */
+function readAccent(css: string): string | undefined {
+  const uiPrimary = /--ui-primary\s*:\s*([^;}]+)/.exec(css)?.[1]?.trim();
+  if (!uiPrimary) {
+    return undefined;
+  }
+
+  const alias = /^var\(\s*(--[\w-]+)\s*\)$/.exec(uiPrimary)?.[1];
+  if (!alias) {
+    // Already a literal — usable unless it is some other custom-property
+    // expression satori would render as nothing.
+    return uiPrimary.includes("var(") ? undefined : uiPrimary;
+  }
+
+  const declared = new RegExp(`${escapeRegExp(alias)}\\s*:\\s*([^;}]+)`).exec(css)?.[1]?.trim();
+  return declared && !declared.includes("var(") ? declared : undefined;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}