@uxfront/layer-docs 0.2.1 → 0.4.0

package/app/utils/storybookEmbed.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildStorybookEmbedUrl,
+  resolveStorybookBaseUrl,
+  STORYBOOK_EMBED_DEFAULT_HEIGHTS,
+  storybookEmbedCssHeight,
+} from "./storybookEmbed";
+
+const TEMPLATE = "https://{framework}.storybook.example.com";
+const STORY = "components-actions-button--default";
+
+describe("resolveStorybookBaseUrl", () => {
+  it("substitutes every occurrence of the framework placeholder", () => {
+    expect(resolveStorybookBaseUrl("https://{framework}.example.com/{framework}", "vue")).toBe(
+      "https://vue.example.com/vue",
+    );
+  });
+
+  it("passes a template without a placeholder through, for a single Storybook", () => {
+    expect(resolveStorybookBaseUrl("https://storybook.example.com", "vue")).toBe(
+      "https://storybook.example.com",
+    );
+  });
+
+  it("trims trailing slashes so the built URL never doubles them", () => {
+    expect(resolveStorybookBaseUrl("https://storybook.example.com//")).toBe(
+      "https://storybook.example.com",
+    );
+  });
+});
+
+describe("buildStorybookEmbedUrl", () => {
+  it("addresses the preview surface by default and marks itself as a direct embed", () => {
+    expect(buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, framework: "vue" })).toBe(
+      `https://vue.storybook.example.com/iframe.html?id=${STORY}&viewMode=story&docsEmbed=1`,
+    );
+  });
+
+  // `full` and `panel` reproduce the manager URLs the migrating docs site
+  // already ships; a changed parameter here is a changed rendering there.
+  it("addresses the manager in full mode", () => {
+    expect(
+      buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, framework: "vue", mode: "full" }),
+    ).toBe(
+      `https://vue.storybook.example.com/?path=/story/${STORY}&full=1&shortcuts=false&singleStory=true`,
+    );
+  });
+
+  it("addresses the manager with its addon panel in panel mode", () => {
+    expect(
+      buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, framework: "vue", mode: "panel" }),
+    ).toBe(
+      `https://vue.storybook.example.com/?path=/story/${STORY}&shortcuts=false&singleStory=true`,
+    );
+  });
+
+  it("only marks the preview surface — a manager embed is relayed, not direct", () => {
+    for (const mode of ["full", "panel"] as const) {
+      expect(buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, mode })).not.toContain(
+        "docsEmbed",
+      );
+    }
+  });
+
+  it("encodes the story id rather than splicing it into the query raw", () => {
+    expect(
+      buildStorybookEmbedUrl({ template: "https://sb.example.com", story: "a&b=c" }),
+    ).toContain("id=a%26b%3Dc&");
+  });
+
+  it("degrades to a same-origin URL when no consumer configured a host", () => {
+    expect(buildStorybookEmbedUrl({ template: "", story: STORY })).toBe(
+      `/iframe.html?id=${STORY}&viewMode=story&docsEmbed=1`,
+    );
+  });
+});
+
+describe("STORYBOOK_EMBED_DEFAULT_HEIGHTS", () => {
+  // Reserved before the story reports anything — the space that keeps the embed
+  // from shifting the page. Panel carries the addon panel on top of the story.
+  it("reserves more room for the panel surface than the bare story", () => {
+    expect(STORYBOOK_EMBED_DEFAULT_HEIGHTS).toEqual({ preview: 320, full: 320, panel: 600 });
+  });
+});
+
+describe("storybookEmbedCssHeight", () => {
+  it("reads a bare number as pixels, in either type markdown may deliver", () => {
+    expect(storybookEmbedCssHeight(420)).toBe("420px");
+    expect(storybookEmbedCssHeight("420")).toBe("420px");
+    expect(storybookEmbedCssHeight(" 420 ")).toBe("420px");
+  });
+
+  it("passes a CSS length through untouched", () => {
+    expect(storybookEmbedCssHeight("30rem")).toBe("30rem");
+    expect(storybookEmbedCssHeight("420px")).toBe("420px");
+    expect(storybookEmbedCssHeight("min(80vh, 600px)")).toBe("min(80vh, 600px)");
+  });
+});

package/app/utils/storybookEmbed.ts

@@ -0,0 +1,93 @@
+import { DOCS_EMBED_PARAM } from "../../storybook";
+
+/**
+ * Which Storybook surface a `StorybookEmbed` addresses.
+ *
+ * The three values are not styling choices — each is a different URL against a
+ * different Storybook surface, and the height signal reaches the page by a
+ * different route in each. See `@uxfront/layer-docs/storybook`.
+ *
+ * - `preview` — `iframe.html`, the story on its own with no Storybook UI.
+ * - `full` — the manager in full-canvas mode: story plus toolbar, no panel.
+ * - `panel` — the manager with its addon panel, for stories documented through
+ *   controls or actions.
+ */
+export type StorybookEmbedMode = "preview" | "full" | "panel";
+
+/**
+ * Height an embed occupies before Storybook reports its own, and the height it
+ * keeps if no bridge is installed on the Storybook side.
+ *
+ * The panel default is taller because the addon panel is a fixed cost on top of
+ * the story. Reserving the space up front is what keeps the embed from shifting
+ * the page when the real height arrives.
+ */
+export const STORYBOOK_EMBED_DEFAULT_HEIGHTS: Record<StorybookEmbedMode, number> = {
+  preview: 320,
+  full: 320,
+  panel: 600,
+};
+
+/**
+ * Resolve a Storybook base URL from a template.
+ *
+ * A `{framework}` placeholder addresses a per-framework Storybook deployment
+ * (`https://{framework}.storybook.example.com`); a template without one is used
+ * as-is, so a single-Storybook site needs no placeholder.
+ */
+export function resolveStorybookBaseUrl(template: string, framework?: string): string {
+  return template.replaceAll("{framework}", framework ?? "").replace(/\/+$/, "");
+}
+
+export interface StorybookEmbedUrlOptions {
+  /** Base URL template, optionally containing `{framework}`. */
+  template: string;
+  /** Storybook story id, e.g. `components-actions-button--default`. */
+  story: string;
+  /** Framework substituted into the template's `{framework}` placeholder. */
+  framework?: string;
+  /** Storybook surface to address. Defaults to `preview`. */
+  mode?: StorybookEmbedMode;
+}
+
+/**
+ * Build the `src` for an embedded story.
+ *
+ * `preview` is marked with `docsEmbed=1`: embedded that way the docs page is
+ * the preview's direct parent, so the preview bridge must post the final height
+ * itself rather than the intermediate one it sends to a manager.
+ *
+ * An empty template yields a root-relative URL rather than a broken absolute
+ * one, which is what an unconfigured consumer gets — a same-origin 404 it can
+ * see, not a silent request to nowhere.
+ */
+export function buildStorybookEmbedUrl(options: StorybookEmbedUrlOptions): string {
+  const { template, story, framework, mode = "preview" } = options;
+
+  const base = resolveStorybookBaseUrl(template, framework);
+  const id = encodeURIComponent(story);
+
+  if (mode === "preview") {
+    return `${base}/iframe.html?id=${id}&viewMode=story&${DOCS_EMBED_PARAM}=1`;
+  }
+
+  // `singleStory` hides the sidebar, `shortcuts` stops the embed from
+  // swallowing keystrokes meant for the page around it, and `full` drops the
+  // addon panel.
+  const full = mode === "full" ? "&full=1" : "";
+
+  return `${base}/?path=/story/${id}${full}&shortcuts=false&singleStory=true`;
+}
+
+/**
+ * Coerce an author-supplied height to a CSS length. A bare number — in either
+ * type, since markdown attributes arrive as strings — means pixels; anything
+ * else is already a CSS length and is passed through.
+ */
+export function storybookEmbedCssHeight(height: number | string): string {
+  if (typeof height === "number") return `${height}px`;
+
+  const trimmed = height.trim();
+
+  return /^\d+(\.\d+)?$/.test(trimmed) ? `${trimmed}px` : trimmed;
+}

package/modules/config.ts

@@ -4,6 +4,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { inferSiteURL, getPackageJsonMetadata } from "../utils/meta";
 import { getGitBranch, getGitEnv, getLocalGitInfo } from "../utils/git";
+import { resolveBrandAccent } from "../utils/accent";
 
 export default defineNuxtModule({
   meta: {
@@ -51,6 +52,27 @@ export default defineNuxtModule({
       branch: getGitBranch(),
     });
 
+    /*
+     ** OG IMAGE ACCENT
+     **
+     ** Bind the card accent to the same token the site uses — see
+     ** `utils/accent.ts` for why it has to be a literal by the time satori
+     ** runs. Written as a default: a consumer that sets `ogImage.accent` in its
+     ** own `app.config.ts` still wins on the layer merge, and one that sets
+     ** nothing gets a branded card with no configuration at all.
+     */
+    const { accent, reason } = resolveBrandAccent({
+      cssEntries: nuxt.options.css ?? [],
+      rootDir: dir,
+    });
+    if (reason) {
+      console.warn(
+        `[Docus] OG image accent falls back to ${accent}: ${reason}. ` +
+          `Set \`ogImage.accent\` in app.config.ts to silence this.`,
+      );
+    }
+    nuxt.options.appConfig.ogImage = defu(nuxt.options.appConfig.ogImage, { accent });
+
     /*
      ** I18N
      */

package/nuxt.config.ts

@@ -14,12 +14,31 @@ const { resolve } = createResolver(import.meta.url);
  * locale site "just works". A consumer that wants localisation registers the
  * module itself; `modules/config` + `useDocusI18n` pick it up automatically.
  *
+ * ## Styling: the consumer owns the single Tailwind entry
+ *
+ * This layer deliberately does NOT register `app/assets/css/main.css` in `css`.
+ * Its base is palette-free, so a consumer's brand `@theme` only compiles if it
+ * lives inside the same Tailwind pass — which means the consumer's CSS file has
+ * to *import* this base, not sit beside it. Registering it here as well gave
+ * every consumer two Tailwind entries and a byte-for-byte duplicate of every
+ * base utility in the shipped stylesheet (+26.7 KB gzip on inkline, UXF-118),
+ * and left each consumer to un-register what the layer had just registered.
+ *
+ * Consumers therefore register exactly one CSS entry, their own:
+ *
+ * ```ts
+ * // nuxt.config.ts
+ * css: ["./app/assets/css/main.css"],
+ * ```
+ *
+ * whose first line imports this base, followed by the brand `@theme`. Both
+ * halves are guarded by `@uxfront/layer-docs/test`; see README § Styling.
+ *
  * https://nuxt.com/docs/getting-started/layers
  */
 export default defineNuxtConfig({
   compatibilityDate: "2025-07-22",
   telemetry: false,
-  css: [resolve("./app/assets/css/main.css")],
   // Expose `app/constants/` (DOCS_SECTIONS, findDocsSectionBySlug) as
   // auto-imports. The layer ships a neutral empty default; a consumer's own
   // `app/constants/` overrides it via auto-import dir precedence.
@@ -37,6 +56,7 @@ export default defineNuxtConfig({
     "@nuxtjs/sitemap",
     "@nuxt/content",
     "nuxt-llms",
+    "nuxt-og-image",
   ],
   icon: {
     serverBundle: "local",
@@ -109,6 +129,24 @@ export default defineNuxtConfig({
       nitroConfig.prerender.routes.push(...routes);
     },
   },
+  /**
+   * OG images are on by default — same class of SEO plumbing as sitemap and
+   * robots, which this layer also registers unasked. A consumer opts out with
+   * the module's own `ogImage: { enabled: false }`; no layer-specific key.
+   *
+   * Prerendering bakes every card at build time, so no runtime generation
+   * endpoint is needed (or exposed unsigned).
+   * @docs https://nuxtseo.com/og-image/guides/zero-runtime
+   */
+  ogImage: {
+    zeroRuntime: true,
+    // 1.91:1, the ratio every major crawler crops to. The module's own default
+    // is 1200×600 (2:1), which gets letterboxed or trimmed on most previews.
+    defaults: {
+      width: 1200,
+      height: 630,
+    },
+  },
   // Generic sitemap defaults; brand values (url/name) come from the consumer's
   // `site` config or are inferred in `modules/config`.
   sitemap: {
@@ -126,6 +164,18 @@ export default defineNuxtConfig({
         host: "https://us.i.posthog.com",
         defaults: "2025-05-24",
       },
+      // Where `StorybookEmbed` points. Empty here — the host is a consumer
+      // fact, and where a Storybook is deployed changes without a code change,
+      // so this is runtime config (`NUXT_PUBLIC_STORYBOOK_BASE_URL`) rather
+      // than app config. A `{framework}` placeholder addresses per-framework
+      // deployments; a template without one is used as-is.
+      storybookBaseUrl: "",
+      // Migration-only: a brand namespace whose `<ns>:theme` / `<ns>:height`
+      // messages a consumer's Storybook already speaks. Set it and the embed
+      // emits and accepts both those names and the neutral ones, so the docs
+      // site and the Storybook can deploy in either order. Unset it once both
+      // sides are on `@uxfront/layer-docs/storybook`.
+      storybookLegacyMessageNamespace: "",
     },
   },
 });

package/nuxt.schema.ts

@@ -327,6 +327,21 @@ export default defineNuxtSchema({
         }),
       },
     }),
+    ogImage: group({
+      title: "OG image",
+      description: "Social share card options.",
+      icon: "i-lucide-image",
+      fields: {
+        accent: field({
+          type: "string",
+          title: "Accent",
+          description:
+            "Accent colour for the OG card headline, as a literal CSS colour — satori has no custom properties, so `var(--ui-primary)` cannot be used here. Left unset, it is resolved at build time by following `--ui-primary` to the `--color-<scale>` literal it aliases in the registered CSS, so most consumers never set it.",
+          icon: "i-lucide-palette",
+          default: "",
+        }),
+      },
+    }),
     github: group({
       title: "GitHub",
       description: "GitHub configuration.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxfront/layer-docs",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Neutral, brandable Nuxt-layer documentation theme. Consumers extend it and supply their own branding, content and section topology.",
   "keywords": [
     "docs",
@@ -23,6 +23,8 @@
     "i18n",
     "modules",
     "server",
+    "storybook",
+    "test",
     "utils",
     "nuxt.config.ts",
     "nuxt.schema.ts",
@@ -43,6 +45,14 @@
       "types": "./utils/content.ts",
       "import": "./utils/content.ts"
     },
+    "./storybook": {
+      "types": "./storybook/index.ts",
+      "import": "./storybook/index.ts"
+    },
+    "./test": {
+      "types": "./test/brand-palette.ts",
+      "import": "./test/brand-palette.ts"
+    },
     "./app/assets/css/main.css": "./app/assets/css/main.css",
     "./package.json": "./package.json"
   },
@@ -60,7 +70,8 @@
     "ufo": "^1.6.4"
   },
   "devDependencies": {
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "@nuxt/content": "^3.14.0",
@@ -72,11 +83,15 @@
     "@nuxtjs/mdc": "^0.22.0",
     "@nuxtjs/robots": "^6.1.1",
     "@nuxtjs/sitemap": "^8.2.1",
+    "@resvg/resvg-js": "^2.6.0",
     "nuxt": "^4.4.8",
     "nuxt-llms": "^0.2.0",
+    "nuxt-og-image": "^6.6.0",
     "posthog-js": "^1.386.6",
+    "satori": "^0.26.0",
     "tailwindcss": "^4.3.1",
     "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
     "vue": "^3.5.38"
   },
   "peerDependenciesMeta": {
@@ -91,6 +106,9 @@
     },
     "typescript": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "scripts": {

package/storybook/index.test.ts

@@ -0,0 +1,110 @@
+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);
+  });
+});