@uxfront/layer-docs 0.4.0 → 0.5.0

package/server/routes/raw/[...slug].md.get.ts

@@ -1,74 +0,0 @@
-import { withLeadingSlash } from "ufo";
-import { stringify } from "minimark/stringify";
-import { queryCollection } from "@nuxt/content/nitro";
-import type { Collections } from "@nuxt/content";
-import { DOCS_SECTIONS } from "~/constants/sections";
-
-export default eventHandler(async (event) => {
-  const slug = getRouterParams(event)["slug.md"];
-  if (!slug?.endsWith(".md")) {
-    throw createError({
-      statusCode: 404,
-      statusMessage: "Page not found",
-      fatal: true,
-    });
-  }
-
-  const path = withLeadingSlash(slug.replace(".md", ""));
-  const config = useRuntimeConfig(event).public;
-
-  const pathSegments = path.split("/").filter(Boolean);
-  let localeSegment: string | undefined;
-  let sectionIndex = 1; // expect /docs/<section>/...
-
-  const i18n = config.i18n as
-    | { locales?: (string | { code: string })[]; defaultLocale?: string }
-    | undefined;
-
-  if (i18n?.locales) {
-    const availableLocales = i18n.locales.map((locale) =>
-      typeof locale === "string" ? locale : locale.code,
-    );
-    const firstSegment = pathSegments[0];
-    if (firstSegment && availableLocales.includes(firstSegment)) {
-      localeSegment = firstSegment;
-      sectionIndex = 2;
-    } else if (i18n.defaultLocale) {
-      localeSegment = i18n.defaultLocale;
-    }
-  }
-
-  const sectionSlug = pathSegments[sectionIndex];
-  const section = DOCS_SECTIONS.find((s) => s.slug === sectionSlug);
-  if (!section) {
-    throw createError({
-      statusCode: 404,
-      statusMessage: "Page not found",
-      fatal: true,
-    });
-  }
-
-  const collectionName = localeSegment
-    ? `docs_${section.key}_${localeSegment}`
-    : `docs_${section.key}`;
-
-  const page = await queryCollection(event, collectionName as keyof Collections)
-    .path(path)
-    .first();
-  if (!page) {
-    throw createError({
-      statusCode: 404,
-      statusMessage: "Page not found",
-      fatal: true,
-    });
-  }
-
-  // Add title and description to the top of the page if missing
-  if (page.body.value[0]?.[0] !== "h1") {
-    page.body.value.unshift(["blockquote", {}, page.description]);
-    page.body.value.unshift(["h1", {}, page.title]);
-  }
-
-  setHeader(event, "Content-Type", "text/markdown; charset=utf-8");
-  return stringify({ ...page.body, type: "minimark" }, { format: "markdown/html" });
-});

package/storybook/index.test.ts

@@ -1,110 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  DOCS_EMBED_HEIGHT_MESSAGE,
-  DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE,
-  DOCS_EMBED_THEME_MESSAGE,
-  docsEmbedMessageNames,
-  readDocsEmbedHeight,
-  readDocsEmbedTheme,
-  resolveDocsEmbedRelayHeight,
-} from "./index.ts";
-
-describe("docsEmbedMessageNames", () => {
-  it("uses the neutral names alone when no legacy namespace is configured", () => {
-    expect(docsEmbedMessageNames()).toEqual({
-      theme: [DOCS_EMBED_THEME_MESSAGE],
-      previewHeight: [DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE],
-      height: [DOCS_EMBED_HEIGHT_MESSAGE],
-    });
-  });
-
-  it("adds the legacy names for the compat window, neutral first", () => {
-    expect(docsEmbedMessageNames("acme")).toEqual({
-      theme: [DOCS_EMBED_THEME_MESSAGE, "acme:theme"],
-      previewHeight: [DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE, "acme:preview-height"],
-      height: [DOCS_EMBED_HEIGHT_MESSAGE, "acme:height"],
-    });
-  });
-
-  // An unset `NUXT_PUBLIC_*` variable arrives as "" rather than undefined, so
-  // the empty cases have to mean "no compat window" and not "`:theme`".
-  it.each(["", "   ", undefined])("treats %o as no legacy namespace", (namespace) => {
-    expect(docsEmbedMessageNames(namespace).theme).toEqual([DOCS_EMBED_THEME_MESSAGE]);
-  });
-});
-
-describe("readDocsEmbedTheme", () => {
-  const names = docsEmbedMessageNames("acme").theme;
-
-  it("reads the neutral name", () => {
-    expect(readDocsEmbedTheme({ type: DOCS_EMBED_THEME_MESSAGE, theme: "dark" }, names)).toBe(
-      "dark",
-    );
-  });
-
-  it("reads the legacy name, so a stale docs deploy still themes the story", () => {
-    expect(readDocsEmbedTheme({ type: "acme:theme", theme: "dark" }, names)).toBe("dark");
-  });
-
-  it("ignores a legacy name once the compat window is closed", () => {
-    const neutralOnly = docsEmbedMessageNames().theme;
-
-    expect(readDocsEmbedTheme({ type: "acme:theme", theme: "dark" }, neutralOnly)).toBeNull();
-  });
-
-  it("ignores unrelated traffic on the same channel", () => {
-    expect(readDocsEmbedTheme({ type: "webpackHotUpdate" }, names)).toBeNull();
-    expect(readDocsEmbedTheme("a string message", names)).toBeNull();
-    expect(readDocsEmbedTheme(null, names)).toBeNull();
-    expect(readDocsEmbedTheme({ theme: "dark" }, names)).toBeNull();
-  });
-
-  it("falls back to light for any theme that is not exactly dark", () => {
-    expect(readDocsEmbedTheme({ type: DOCS_EMBED_THEME_MESSAGE, theme: "sepia" }, names)).toBe(
-      "light",
-    );
-    expect(readDocsEmbedTheme({ type: DOCS_EMBED_THEME_MESSAGE }, names)).toBe("light");
-  });
-});
-
-describe("readDocsEmbedHeight", () => {
-  const names = docsEmbedMessageNames("acme").height;
-
-  it("reads both the neutral and the legacy name", () => {
-    expect(readDocsEmbedHeight({ type: DOCS_EMBED_HEIGHT_MESSAGE, height: 420 }, names)).toBe(420);
-    expect(readDocsEmbedHeight({ type: "acme:height", height: 420 }, names)).toBe(420);
-  });
-
-  it("does not confuse the preview leg with the docs leg", () => {
-    expect(
-      readDocsEmbedHeight({ type: DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE, height: 420 }, names),
-    ).toBeNull();
-  });
-
-  // These reach a style attribute, so a bad one is a collapsed or absurd frame
-  // rather than an exception.
-  it.each([0, -10, Number.NaN, Number.POSITIVE_INFINITY, "420", null, undefined])(
-    "rejects %o as a height",
-    (height) => {
-      expect(readDocsEmbedHeight({ type: DOCS_EMBED_HEIGHT_MESSAGE, height }, names)).toBeNull();
-    },
-  );
-});
-
-describe("resolveDocsEmbedRelayHeight", () => {
-  it("adds only padding in full mode, where no manager chrome is visible", () => {
-    expect(resolveDocsEmbedRelayHeight({ contentHeight: 300 })).toBe(364);
-  });
-
-  it("adds the measured chrome in panel mode", () => {
-    expect(resolveDocsEmbedRelayHeight({ contentHeight: 300, chromeHeight: 120 })).toBe(484);
-  });
-
-  it("ignores negative chrome, which means the preview outgrew its own window", () => {
-    expect(resolveDocsEmbedRelayHeight({ contentHeight: 300, chromeHeight: -50 })).toBe(364);
-  });
-
-  it("takes an explicit padding", () => {
-    expect(resolveDocsEmbedRelayHeight({ contentHeight: 300, padding: 0 })).toBe(300);
-  });
-});

package/storybook/index.ts

@@ -1,362 +0,0 @@
-/**
- * `@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;
-}