@takazudo/zudo-doc 2.0.0 → 2.1.0

package/bin/gen-component-tokens.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// @takazudo/zudo-doc/bin/gen-component-tokens.mjs
+//
+// Package bin: regenerate (or check) the BEGIN/END-marked --zdc-* blocks from
+// the single source of truth in packages/zudo-doc/src/config/component-tokens.ts.
+//
+// Each token declares a `surface`, and the generator ROUTES its backing rule to
+// the matching stylesheet:
+//   - surface "content" → block in packages/zudo-doc/src/content.css
+//   - surface "chrome"  → block in packages/zudo-doc/src/features.css
+// A token missing `surface` is a hard error (the parser throws).
+//
+// Paths are resolved relative to this file's location (the package root),
+// NOT process.cwd() — this tool operates on the package's own source files
+// regardless of the working directory from which it is invoked.
+//
+// Usage (after pnpm install, via scripts in the root package.json):
+//   gen-component-tokens            # rewrite the --zdc-* blocks in both files
+//   gen-component-tokens --check    # verify committed blocks are up to date (exit 1 on drift)
+//
+// CI invokes the file by path from the repo root:
+//   node packages/zudo-doc/bin/gen-component-tokens.mjs --check
+//
+// Each block is a set of --zdc-* CSS custom-property rules grouped by selector,
+// giving consumers a single `:root` override point to rebrand component-level
+// typography/chrome without touching JSX or fighting specificity.
+//
+// Pure Node (fs only — NO npm deps). Idempotent: running twice produces no diff.
+//
+// MAINTENANCE: edit packages/zudo-doc/src/config/component-tokens.ts (the source
+// of truth), then run `pnpm gen:component-tokens` and commit the regenerated
+// content.css / features.css. Never hand-edit the block between the BEGIN/END
+// markers.
+
+import { readFileSync, writeFileSync, realpathSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Paths are relative to this bin file's location so the generator works
+// regardless of cwd (running from the repo root, package dir, or CI).
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "..");
+
+const TOKENS_PATH = resolve(PKG_ROOT, "src/config/component-tokens.ts");
+const CONTENT_CSS_PATH = resolve(PKG_ROOT, "src/content.css");
+const FEATURES_CSS_PATH = resolve(PKG_ROOT, "src/features.css");
+
+// Default marker pair = the content-surface block. Kept under the original
+// names so buildBlock/replaceBlock default to the content block, preserving the
+// byte-identical content.css output (and the existing unit-test call sites).
+const BEGIN_MARKER =
+  "/* BEGIN --zdc-* component tokens (generated by gen-component-tokens; do not edit by hand) */";
+const END_MARKER = "/* END --zdc-* component tokens */";
+
+// Chrome-surface block markers — a DISTINCT pair so the two blocks never
+// collide when both live in files that the generator scans.
+const CHROME_BEGIN_MARKER =
+  "/* BEGIN --zdc-* chrome component tokens (generated by gen-component-tokens; do not edit by hand) */";
+const CHROME_END_MARKER = "/* END --zdc-* chrome component tokens */";
+
+/**
+ * Surface routing table — source order is the file-write order. Each entry maps
+ * a token `surface` to its destination stylesheet, marker pair, and a
+ * repo-relative path used in console/drift messages.
+ */
+const SURFACES = [
+  {
+    surface: "content",
+    cssPath: CONTENT_CSS_PATH,
+    relPath: "packages/zudo-doc/src/content.css",
+    beginMarker: BEGIN_MARKER,
+    endMarker: END_MARKER,
+  },
+  {
+    surface: "chrome",
+    cssPath: FEATURES_CSS_PATH,
+    relPath: "packages/zudo-doc/src/features.css",
+    beginMarker: CHROME_BEGIN_MARKER,
+    endMarker: CHROME_END_MARKER,
+  },
+];
+
+/** The set of valid `surface` values, derived from the routing table. */
+const VALID_SURFACES = new Set(SURFACES.map((s) => s.surface));
+
+/**
+ * Parse the COMPONENT_TOKENS array out of component-tokens.ts WITHOUT importing
+ * it (this bin is a dependency-free .mjs and cannot resolve TypeScript). Reads
+ * each `{ cssVar: "...", selector: "...", property: "...", default: "...",
+ * surface: "...", ... }` object literal. Throws on a malformed source — or a
+ * token missing the required `surface` field — so drift between the parser and
+ * the file surfaces loudly.
+ *
+ * Returns an array of { cssVar, selector, property, default, surface } objects
+ * in source order — iteration order is the CSS rule order.
+ *
+ * Exported for unit testing.
+ */
+export function parseTokens(src) {
+  const arrayMatch = src.match(
+    /export const COMPONENT_TOKENS[^=]*=\s*\[([\s\S]*?)\];/,
+  );
+  if (!arrayMatch) {
+    throw new Error(
+      `Could not locate "export const COMPONENT_TOKENS = [ ... ]" in ${TOKENS_PATH}`,
+    );
+  }
+  const body = arrayMatch[1];
+  const tokens = [];
+
+  // Each token is a `{ ... }` object literal; iterate top-level braces.
+  // Description strings may contain backticks and parentheses but not braces,
+  // so lazy `{...}` matching correctly isolates each object.
+  const objectRe = /\{([\s\S]*?)\}/g;
+  let m;
+  while ((m = objectRe.exec(body)) !== null) {
+    const obj = m[1];
+    const cssVarMatch = obj.match(/cssVar:\s*"([^"]+)"/);
+    const selectorMatch = obj.match(/selector:\s*"([^"]+)"/);
+    const propertyMatch = obj.match(/property:\s*"([^"]+)"/);
+    const defaultMatch = obj.match(/default:\s*"([^"]+)"/);
+
+    if (!cssVarMatch || !selectorMatch || !propertyMatch || !defaultMatch) {
+      throw new Error(
+        `Malformed token object in COMPONENT_TOKENS (missing cssVar/selector/property/default): ${obj.trim()}`,
+      );
+    }
+
+    // `surface` is REQUIRED — it routes the rule to content.css vs features.css.
+    // Fail loudly rather than silently dropping a token from both files.
+    const surfaceMatch = obj.match(/surface:\s*"([^"]+)"/);
+    if (!surfaceMatch) {
+      throw new Error(
+        `Token ${cssVarMatch[1]} in COMPONENT_TOKENS is missing the required "surface" field ` +
+          `(expected surface: "content" | "chrome").`,
+      );
+    }
+
+    tokens.push({
+      cssVar: cssVarMatch[1],
+      selector: selectorMatch[1],
+      property: propertyMatch[1],
+      default: defaultMatch[1],
+      surface: surfaceMatch[1],
+    });
+  }
+
+  if (tokens.length === 0) {
+    throw new Error(
+      `COMPONENT_TOKENS in ${TOKENS_PATH} parsed to an empty list`,
+    );
+  }
+  return tokens;
+}
+
+/**
+ * Group tokens by selector, preserving the first-appearance order of selectors
+ * and the within-selector declaration order. Deterministic (source-order stable).
+ *
+ * Exported for unit testing.
+ */
+export function groupBySelector(tokens) {
+  const map = new Map();
+  for (const token of tokens) {
+    if (!map.has(token.selector)) {
+      map.set(token.selector, []);
+    }
+    map.get(token.selector).push(token);
+  }
+  return map;
+}
+
+/**
+ * Partition tokens by their `surface`, returning a Map keyed by every known
+ * surface (in routing-table order) so callers can emit an EMPTY block for a
+ * surface that currently has no tokens (e.g. the seeded chrome block). Throws
+ * loudly on an unknown surface value — a routing typo must never silently drop
+ * a rule from both files.
+ *
+ * Exported for unit testing.
+ */
+export function routeBySurface(tokens) {
+  const routes = new Map(SURFACES.map((s) => [s.surface, []]));
+  for (const token of tokens) {
+    if (!routes.has(token.surface)) {
+      throw new Error(
+        `Token ${token.cssVar} in COMPONENT_TOKENS has unknown surface "${token.surface}" ` +
+          `(expected one of: ${[...VALID_SURFACES].map((s) => `"${s}"`).join(", ")}).`,
+      );
+    }
+    routes.get(token.surface).push(token);
+  }
+  return routes;
+}
+
+/**
+ * Build the full generated block (markers included). Selectors are emitted in
+ * source-file order; declarations within each selector are in source-file order.
+ * No trailing newline — the caller appends css.slice(lineEnd) which starts with
+ * the \n that follows the END marker line.
+ *
+ * `beginMarker`/`endMarker` default to the CONTENT block markers so existing
+ * call sites keep producing the byte-identical content.css block; the chrome
+ * surface passes its own marker pair. An empty `tokens` array yields just the
+ * marker pair separated by a blank line (the seeded-empty chrome block).
+ *
+ * Exported for unit testing.
+ */
+export function buildBlock(tokens, beginMarker = BEGIN_MARKER, endMarker = END_MARKER) {
+  const groups = groupBySelector(tokens);
+  const lines = [];
+
+  lines.push(beginMarker);
+
+  for (const [selector, entries] of groups) {
+    lines.push("");
+    lines.push(`${selector} {`);
+    for (const entry of entries) {
+      lines.push(`  ${entry.property}: var(${entry.cssVar}, ${entry.default});`);
+    }
+    lines.push("}");
+  }
+
+  lines.push("");
+  lines.push(endMarker);
+
+  return lines.join("\n");
+}
+
+/**
+ * Replace the existing BEGIN…END block in `css` with `block`. Throws if the
+ * markers are missing (the block must be seeded once by hand — see content.css
+ * / features.css). `beginMarker`/`endMarker` default to the content block; the
+ * chrome surface passes its own pair. `cssPath` only feeds the error message.
+ *
+ * Exported for unit testing.
+ */
+export function replaceBlock(
+  css,
+  block,
+  beginMarker = BEGIN_MARKER,
+  endMarker = END_MARKER,
+  cssPath = CONTENT_CSS_PATH,
+) {
+  const beginIdx = css.indexOf(beginMarker);
+  const endIdx = css.indexOf(endMarker);
+  if (beginIdx === -1 || endIdx === -1) {
+    throw new Error(
+      `Could not find BEGIN/END markers in ${cssPath}.\n` +
+        `Seed the marker block once by hand, then re-run the generator.`,
+    );
+  }
+  // Expand to the full line that opens the block and the end of the closing
+  // line so the whole region (including any per-selector comments the hand-
+  // written block may have had) is replaced cleanly.
+  const lineStart = css.lastIndexOf("\n", beginIdx) + 1;
+  const afterEnd = css.indexOf("\n", endIdx);
+  const lineEnd = afterEnd === -1 ? css.length : afterEnd;
+  return css.slice(0, lineStart) + block + css.slice(lineEnd);
+}
+
+function main() {
+  const check = process.argv.includes("--check");
+
+  const tokensSrc = readFileSync(TOKENS_PATH, "utf8");
+  const tokens = parseTokens(tokensSrc);
+  const routes = routeBySurface(tokens);
+
+  let drift = false;
+  let wroteAny = false;
+  const summaries = [];
+
+  for (const target of SURFACES) {
+    const surfaceTokens = routes.get(target.surface);
+    const selectorCount = [...groupBySelector(surfaceTokens).keys()].length;
+    summaries.push(
+      `${target.surface}: ${surfaceTokens.length} token(s), ${selectorCount} selector(s)`,
+    );
+
+    const css = readFileSync(target.cssPath, "utf8");
+    const block = buildBlock(surfaceTokens, target.beginMarker, target.endMarker);
+    const next = replaceBlock(
+      css,
+      block,
+      target.beginMarker,
+      target.endMarker,
+      target.cssPath,
+    );
+
+    if (next === css) continue;
+
+    if (check) {
+      console.error(
+        `component-tokens codegen drift detected: ${target.relPath} (${target.surface} surface) is out of date.`,
+      );
+      drift = true;
+    } else {
+      writeFileSync(target.cssPath, next);
+      wroteAny = true;
+      console.log(
+        `Wrote --zdc-* ${target.surface} component token block to ${target.relPath} ` +
+          `(${surfaceTokens.length} token(s), ${selectorCount} selector(s)).`,
+      );
+    }
+  }
+
+  if (check) {
+    if (drift) {
+      console.error("Run `pnpm gen:component-tokens` and commit the result.");
+      return 1;
+    }
+    console.log(
+      `OK — --zdc-* component token blocks up to date [${summaries.join("; ")}].`,
+    );
+    return 0;
+  }
+
+  if (!wroteAny) {
+    console.log(
+      `--zdc-* component token blocks already up to date [${summaries.join("; ")}]; no change.`,
+    );
+  }
+  return 0;
+}
+
+// Run the CLI only when executed directly, NOT when imported by tests (an
+// import must not rewrite content.css as a side effect — it would break
+// `pnpm test`). Compare REAL paths on both sides: when invoked through the
+// pnpm bin shim (root `pnpm gen:/check:component-tokens`, b4push), argv[1] is
+// the `node_modules/.bin/…` symlink, NOT the real workspace file, so a raw
+// path-equality check is always false and main() would silently no-op — the
+// drift guard would pass even on real drift. realpathSync resolves the shim/
+// symlink to the real file on both sides so direct invocation is detected
+// however the bin is launched.
+function isDirectInvocation() {
+  if (!process.argv[1]) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation()) {
+  process.exit(main());
+}

package/dist/chrome/assert-chrome-context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Assert that `ctx` is a fully-wired 2.0 ChromeContext (i.e. has `hostBindings`).
+ *
+ * Throws an actionable Error when the caller passes a bare pre-2.0 deps-bag
+ * instead of the unified ChromeContext the 2.0 factories require. This catches
+ * runtime crashes (`Cannot read properties of undefined (reading 'tagVocabulary')`)
+ * at the factory boundary instead of deep inside the component render.
+ *
+ * See packages/zudo-doc/API.md — "Migration Notes" for upgrade instructions.
+ */
+export declare function assertChromeContext(ctx: unknown, factoryName: string): void;

package/dist/chrome/assert-chrome-context.js

@@ -0,0 +1,10 @@
+function assertChromeContext(ctx, factoryName) {
+  if (ctx == null || ctx.hostBindings == null) {
+    throw new Error(
+      `\`${factoryName}\` received a context without \`hostBindings\` \u2014 the 2.0 factories take a single ChromeContext, not the pre-2.0 deps-bag. See packages/zudo-doc/API.md.`
+    );
+  }
+}
+export {
+  assertChromeContext
+};

package/dist/config/component-tokens.d.ts

@@ -0,0 +1,56 @@
+/** Grouping category for a component token (drives docs/registry sectioning). */
+export type ComponentTokenCategory = "typography" | "shape" | "layout";
+/**
+ * Which rendering surface a token's backing rule targets — drives WHERE the
+ * generator emits the rule:
+ *   - `content` → the `.zd-content` typography surface; rule lands in the
+ *     BEGIN/END block in `src/content.css` (shipped as `…/content.css`).
+ *   - `chrome`  → the app shell (header/footer/sidebar/toc/cards); rule lands
+ *     in the BEGIN/END block in `src/features.css` (shipped as `…/features.css`).
+ * The two surfaces ship as separate stylesheets, so a token MUST declare its
+ * surface — the generator routes by it and fails loudly when it is absent.
+ */
+export type ComponentTokenSurface = "content" | "chrome";
+/**
+ * Union of every `--zdc-*` CSS custom property name in the registry.
+ * Provides autocomplete when a consumer iterates or references individual tokens.
+ * Must be kept in sync with the `cssVar` values in `COMPONENT_TOKENS` below.
+ */
+export type ComponentTokenName = "--zdc-doc-title-font" | "--zdc-doc-title-weight" | "--zdc-doc-title-tracking" | "--zdc-doc-h2-font" | "--zdc-doc-h2-weight" | "--zdc-doc-h2-tracking" | "--zdc-doc-h3-weight" | "--zdc-doc-h4-weight" | "--zdc-doc-prose-font" | "--zdc-doc-link-decoration" | "--zdc-admonition-radius" | "--zdc-admonition-border-width" | "--zdc-card-radius" | "--zdc-content-max-width" | "--zdc-toc-width" | "--zdc-nav-active-indicator-color" | "--zdc-nav-active-weight";
+export interface ComponentToken {
+    /**
+     * The CSS custom-property name the consumer redefines in `:root`, e.g.
+     * `--zdc-doc-title-font`. Always `--zdc-`-prefixed.
+     */
+    cssVar: `--zdc-${string}`;
+    /**
+     * The already-rendered, component-anchored selector the backing rule targets
+     * (the classes the component already emits — no JSX change). Tokens sharing a
+     * selector are emitted into a single CSS rule by the generator.
+     */
+    selector: string;
+    /** The CSS property this token drives, e.g. `font-family`. */
+    property: string;
+    /**
+     * Default value used as the `var(<cssVar>, <default>)` fallback. SHOULD chain
+     * to an existing design token or `inherit` so consumer `@theme` overrides flow
+     * through. Bare CSS literals (e.g. `4px`, `underline`) are allowed only when
+     * no design token exists for the property — document the exception in the
+     * snapshot test. The rendered default MUST be byte-identical to the pre-token
+     * output in every case.
+     */
+    default: string;
+    /** The component this token rebrands (e.g. `doc-title`). */
+    component: string;
+    /**
+     * Rendering surface the backing rule targets. The generator routes the rule
+     * to `content.css` (`content`) or `features.css` (`chrome`) by this field.
+     * Required — codegen throws if it is missing.
+     */
+    surface: ComponentTokenSurface;
+    /** Grouping category. */
+    category: ComponentTokenCategory;
+    /** Human-readable description for the registry/docs. */
+    description: string;
+}
+export declare const COMPONENT_TOKENS: ComponentToken[];