@uxfront/layer-docs 0.3.0 → 0.4.0

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

@@ -56,6 +56,7 @@ export default defineNuxtConfig({
     "@nuxtjs/sitemap",
     "@nuxt/content",
     "nuxt-llms",
+    "nuxt-og-image",
   ],
   icon: {
     serverBundle: "local",
@@ -128,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: {
@@ -145,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.3.0",
+  "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,7 @@
     "i18n",
     "modules",
     "server",
+    "storybook",
     "test",
     "utils",
     "nuxt.config.ts",
@@ -44,6 +45,10 @@
       "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"
@@ -78,9 +83,12 @@
     "@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",

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);
+  });
+});