create-zudo-doc 0.1.0

package/templates/features/designTokenPanel/files/src/config/design-tokens-manifest.ts

@@ -0,0 +1,177 @@
+/**
+ * Design-token manifest data arrays — canonical source of truth for all
+ * editable design tokens, lifted out of the legacy panel component directory
+ * so they survive the W3-2 deletion of the panel component tree.
+ *
+ * Imported by:
+ *  - src/config/design-token-panel-config.ts  (groups items into TabConfig.tiers)
+ *  - @takazudo/zudo-doc/theme (design-token-serde) — cssVar ↔ id lookup for JSON I/O
+ *
+ * Type strategy: arrays are typed `readonly TokenDef[]` for back-compat with
+ * the consumer serde and tests. `design-token-panel-config.ts` partitions the
+ * flat arrays by the `group` field into the new zdtp `TabConfig.tiers` shape.
+ * `TokenDef.advanced` was dropped upstream (zdtp 8abb1e4) — items previously
+ * gated behind an "Advanced" disclosure now live in their own tier ("Scale —
+ * advanced") so the tier acts as the disclosure container.
+ */
+import type { TokenDef } from "@takazudo/zdtp";
+
+// --- Font weight select options ---
+const FONT_WEIGHT_OPTIONS = [
+  "100", "200", "300", "400", "500", "600", "700", "800", "900",
+] as const;
+
+/**
+ * Spacing tokens from `global.css`.
+ *
+ * Coverage (audit 2026-04): every `--spacing-*` declaration plus the
+ * `--zd-sidebar-w` layout token. Read-only rows surface tokens whose value
+ * can't be expressed on a single-axis slider (`clamp()`, structural `0`).
+ */
+export const SPACING_TOKENS: readonly TokenDef[] = [
+  // --- Horizontal spacing ---
+  { id: "hsp-2xs", cssVar: "--spacing-hsp-2xs", label: "hsp-2xs", group: "hsp", default: "0.125rem", min: 0, max: 3, step: 0.025, unit: "rem" },
+  { id: "hsp-xs",  cssVar: "--spacing-hsp-xs",  label: "hsp-xs",  group: "hsp", default: "0.375rem", min: 0, max: 3, step: 0.025, unit: "rem" },
+  { id: "hsp-sm",  cssVar: "--spacing-hsp-sm",  label: "hsp-sm",  group: "hsp", default: "0.5rem",   min: 0, max: 3, step: 0.025, unit: "rem" },
+  { id: "hsp-md",  cssVar: "--spacing-hsp-md",  label: "hsp-md",  group: "hsp", default: "0.75rem",  min: 0, max: 3, step: 0.025, unit: "rem" },
+  { id: "hsp-lg",  cssVar: "--spacing-hsp-lg",  label: "hsp-lg",  group: "hsp", default: "1rem",     min: 0, max: 3, step: 0.025, unit: "rem" },
+  { id: "hsp-xl",  cssVar: "--spacing-hsp-xl",  label: "hsp-xl",  group: "hsp", default: "1.5rem",   min: 0, max: 3, step: 0.025, unit: "rem" },
+  { id: "hsp-2xl", cssVar: "--spacing-hsp-2xl", label: "hsp-2xl", group: "hsp", default: "2rem",     min: 0, max: 3, step: 0.025, unit: "rem" },
+
+  // --- Vertical spacing ---
+  { id: "vsp-2xs", cssVar: "--spacing-vsp-2xs", label: "vsp-2xs", group: "vsp", default: "0.4375rem", min: 0, max: 4, step: 0.025, unit: "rem" },
+  { id: "vsp-xs",  cssVar: "--spacing-vsp-xs",  label: "vsp-xs",  group: "vsp", default: "0.875rem",  min: 0, max: 4, step: 0.025, unit: "rem" },
+  { id: "vsp-sm",  cssVar: "--spacing-vsp-sm",  label: "vsp-sm",  group: "vsp", default: "1.25rem",   min: 0, max: 4, step: 0.025, unit: "rem" },
+  { id: "vsp-md",  cssVar: "--spacing-vsp-md",  label: "vsp-md",  group: "vsp", default: "1.5rem",    min: 0, max: 4, step: 0.025, unit: "rem" },
+  { id: "vsp-lg",  cssVar: "--spacing-vsp-lg",  label: "vsp-lg",  group: "vsp", default: "1.75rem",   min: 0, max: 4, step: 0.025, unit: "rem" },
+  { id: "vsp-xl",  cssVar: "--spacing-vsp-xl",  label: "vsp-xl",  group: "vsp", default: "2.5rem",    min: 0, max: 4, step: 0.025, unit: "rem" },
+  { id: "vsp-2xl", cssVar: "--spacing-vsp-2xl", label: "vsp-2xl", group: "vsp", default: "3.5rem",    min: 0, max: 4, step: 0.025, unit: "rem" },
+
+  // --- Icons ---
+  { id: "icon-xs", cssVar: "--spacing-icon-xs", label: "icon-xs", group: "icon", default: "0.75rem", min: 0, max: 2, step: 0.05, unit: "rem" },
+  { id: "icon-sm", cssVar: "--spacing-icon-sm", label: "icon-sm", group: "icon", default: "1rem",    min: 0, max: 2, step: 0.05, unit: "rem" },
+  { id: "icon-md", cssVar: "--spacing-icon-md", label: "icon-md", group: "icon", default: "1.25rem", min: 0, max: 2, step: 0.05, unit: "rem" },
+  { id: "icon-lg", cssVar: "--spacing-icon-lg", label: "icon-lg", group: "icon", default: "1.5rem",  min: 0, max: 2, step: 0.05, unit: "rem" },
+
+  // --- Layout ---
+  { id: "image-overlay-inset", cssVar: "--spacing-image-overlay-inset", label: "image-overlay-inset", group: "layout", default: "0.5rem", min: 0, max: 2, step: 0.05, unit: "rem" },
+  // Structural zero — surfaced as read-only so designers see it exists, but
+  // editing it would break every utility that relies on "0 is 0".
+  { id: "spacing-0",  cssVar: "--spacing-0",  label: "spacing-0",  group: "layout", default: "0",   min: 0, max: 0, step: 1, unit: "",   readonly: true },
+  // 1px hairline — also read-only by design.
+  { id: "spacing-px", cssVar: "--spacing-px", label: "spacing-px", group: "layout", default: "1px", min: 0, max: 0, step: 1, unit: "px", readonly: true },
+  // Responsive clamp() expression — can't be expressed on a single slider.
+  { id: "sidebar-w",  cssVar: "--zd-sidebar-w", label: "sidebar-w", group: "layout", default: "clamp(14rem, 20vw, 22rem)", min: 0, max: 0, step: 1, unit: "", readonly: true },
+];
+
+/**
+ * Font tokens from `global.css`.
+ *
+ * Tier 2 semantic tokens (sizes, line-heights, weights, families) are exposed
+ * as primary tiers; Tier 1 abstract scale (`--text-scale-*`) lives in its own
+ * `font-scale` tier so designers who tweak the scale see the tokens that the
+ * semantic sizes resolve from.
+ *
+ * (Note: `TokenDef.advanced` was dropped upstream in zdtp 8abb1e4. The
+ * progressive-disclosure container is now the tier itself; the
+ * panel-config groups by `group` and presents each tier as a separate
+ * section under the Font tab.)
+ *
+ * Defaults here mirror `global.css` resolved rem values (`--text-body` →
+ * `1.2rem`) so serde and the flat-`TokenManifest` generator template have a
+ * concrete number. The tier-based main panel (`design-token-panel-config.ts`)
+ * promotes the `font-size` group to a *reference* tier pointing at
+ * `font-scale`, overriding these defaults to the referenced scale id so the
+ * panel reflects the `var(--text-scale-*)` wiring the CSS already encodes.
+ */
+export const FONT_TOKENS: readonly TokenDef[] = [
+  // --- Font sizes (Tier 2 semantic) ---
+  { id: "text-micro",      cssVar: "--text-micro",      label: "text-micro",      group: "font-size", default: "0.75rem",  min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-caption",    cssVar: "--text-caption",    label: "text-caption",    group: "font-size", default: "0.875rem", min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-small",      cssVar: "--text-small",      label: "text-small",      group: "font-size", default: "1rem",     min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-body",       cssVar: "--text-body",       label: "text-body",       group: "font-size", default: "1.2rem",   min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-title", cssVar: "--text-title", label: "text-title", group: "font-size", default: "1.4rem",   min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-heading",    cssVar: "--text-heading",    label: "text-heading",    group: "font-size", default: "3rem",     min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-display",    cssVar: "--text-display",    label: "text-display",    group: "font-size", default: "3.75rem",  min: 0.5, max: 5, step: 0.05, unit: "rem" },
+
+  // --- Line heights (unitless) ---
+  { id: "leading-tight",   cssVar: "--leading-tight",   label: "leading-tight",   group: "line-height", default: "1.25",  min: 1, max: 3, step: 0.05, unit: "" },
+  { id: "leading-snug",    cssVar: "--leading-snug",    label: "leading-snug",    group: "line-height", default: "1.375", min: 1, max: 3, step: 0.05, unit: "" },
+  { id: "leading-normal",  cssVar: "--leading-normal",  label: "leading-normal",  group: "line-height", default: "1.5",   min: 1, max: 3, step: 0.05, unit: "" },
+  { id: "leading-relaxed", cssVar: "--leading-relaxed", label: "leading-relaxed", group: "line-height", default: "1.625", min: 1, max: 3, step: 0.05, unit: "" },
+
+  // --- Font weights (select) ---
+  { id: "font-weight-normal",   cssVar: "--font-weight-normal",   label: "font-weight-normal",   group: "font-weight", default: "400", min: 0, max: 0, step: 1, unit: "", control: "select", options: FONT_WEIGHT_OPTIONS },
+  { id: "font-weight-medium",   cssVar: "--font-weight-medium",   label: "font-weight-medium",   group: "font-weight", default: "500", min: 0, max: 0, step: 1, unit: "", control: "select", options: FONT_WEIGHT_OPTIONS },
+  { id: "font-weight-semibold", cssVar: "--font-weight-semibold", label: "font-weight-semibold", group: "font-weight", default: "600", min: 0, max: 0, step: 1, unit: "", control: "select", options: FONT_WEIGHT_OPTIONS },
+  { id: "font-weight-bold",     cssVar: "--font-weight-bold",     label: "font-weight-bold",     group: "font-weight", default: "700", min: 0, max: 0, step: 1, unit: "", control: "select", options: FONT_WEIGHT_OPTIONS },
+
+  // --- Font families (text input) ---
+  { id: "font-sans", cssVar: "--font-sans", label: "font-sans", group: "font-family", default: "system-ui, sans-serif",    min: 0, max: 0, step: 1, unit: "", control: "text" },
+  { id: "font-mono", cssVar: "--font-mono", label: "font-mono", group: "font-family", default: "ui-monospace, monospace",  min: 0, max: 0, step: 1, unit: "", control: "text" },
+
+  // --- Tier 1 abstract scale (was "Advanced" disclosure in v1 of the panel;
+  //     now lives in its own font-scale tier). ---
+  { id: "text-scale-2xs", cssVar: "--text-scale-2xs", label: "text-scale-2xs", group: "font-scale", default: "0.75rem",  min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-scale-xs",  cssVar: "--text-scale-xs",  label: "text-scale-xs",  group: "font-scale", default: "0.875rem", min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-scale-sm",  cssVar: "--text-scale-sm",  label: "text-scale-sm",  group: "font-scale", default: "1rem",     min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-scale-md",  cssVar: "--text-scale-md",  label: "text-scale-md",  group: "font-scale", default: "1.2rem",   min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-scale-lg",  cssVar: "--text-scale-lg",  label: "text-scale-lg",  group: "font-scale", default: "1.4rem",   min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-scale-xl",  cssVar: "--text-scale-xl",  label: "text-scale-xl",  group: "font-scale", default: "3rem",     min: 0.5, max: 5, step: 0.05, unit: "rem" },
+  { id: "text-scale-2xl", cssVar: "--text-scale-2xl", label: "text-scale-2xl", group: "font-scale", default: "3.75rem",  min: 0.5, max: 5, step: 0.05, unit: "rem" },
+];
+
+/**
+ * Size tokens from `global.css`.
+ *
+ * Coverage (audit 2026-04): every non-breakpoint size-category custom property.
+ * Breakpoints (`--breakpoint-sm/lg/xl`) are intentionally omitted — live-
+ * changing them causes layout thrash mid-drag and adds no real tweak value.
+ *
+ * Radius defaults use `px` (matches the 0–100 slider in the sub-issue spec),
+ * even though `global.css` expresses them in `rem` — the browser accepts both.
+ *
+ * `--radius-full` is special: its design default (`9999px`) is an intentional
+ * sentinel that a 0–100 slider can't reach, so it carries a `pill` toggle. The
+ * checkbox reapplies the sentinel; unchecking drops back to a slider-editable
+ * custom value.
+ */
+export const SIZE_TOKENS: readonly TokenDef[] = [
+  // --- Radius ---
+  { id: "radius-DEFAULT", cssVar: "--radius-DEFAULT", label: "radius-DEFAULT", group: "radius", default: "4px", min: 0, max: 100, step: 1, unit: "px" },
+  { id: "radius-lg",      cssVar: "--radius-lg",      label: "radius-lg",      group: "radius", default: "8px", min: 0, max: 100, step: 1, unit: "px" },
+  {
+    id: "radius-full",
+    cssVar: "--radius-full",
+    label: "radius-full",
+    group: "radius",
+    default: "9999px",
+    min: 0,
+    max: 100,
+    step: 1,
+    unit: "px",
+    pill: { value: "9999px", customDefault: "16px" },
+  },
+
+  // --- Transitions ---
+  {
+    id: "default-transition-duration",
+    cssVar: "--default-transition-duration",
+    label: "default-transition-duration",
+    group: "transition",
+    default: "150ms",
+    min: 0,
+    max: 1000,
+    step: 10,
+    unit: "ms",
+  },
+];
+
+/**
+ * Color tokens — kept as an empty array for back-compat with the consumer
+ * serde, which historically iterated `COLOR_TOKENS` symmetric with the other
+ * three arrays. Color is cluster-driven in zudo-doc and is constructed in
+ * `design-token-panel-config.ts` from `colorSchemes` + `SEMANTIC_*` —
+ * not from this array.
+ */
+export const COLOR_TOKENS: readonly TokenDef[] = [];

package/templates/features/designTokenPanel/files/src/lib/design-token-panel-bootstrap.ts

@@ -0,0 +1,50 @@
+/**
+ * Production bootstrap for @takazudo/zdtp (zdtp).
+ *
+ * Imported as a side-effect from the body-end islands helper when
+ * settings.designTokenPanel (or the deprecated alias colorTweakPanel) is
+ * truthy. The dynamic import is gated there so this module is only bundled
+ * when the feature is enabled.
+ *
+ * Lifecycle bridge: zdtp hard-codes astro:before-swap / astro:page-load
+ * event names (upstream issue Takazudo/zudo-design-token-panel#50). We
+ * re-dispatch those Astro event names whenever the zfb equivalents fire so
+ * zdtp's internal listeners receive the signal they expect. Replace this
+ * bridge with setLifecycleAdapter() once upstream issue #50 ships.
+ */
+
+import { configurePanel } from "@takazudo/zdtp";
+// CSS is pulled via `@import "@takazudo/zdtp/styles.css"` in
+// src/styles/global.css so the panel chrome lands in the main page CSS bundle
+// (not a deferred chunk). Vite library mode strips the source CSS import from
+// the emitted JS, so the explicit CSS-side import is the required pull point.
+import { designTokenPanelConfig } from "@/config/design-token-panel-config";
+
+configurePanel(designTokenPanelConfig);
+
+// Drain the pre-hydration click queue. If the user clicked the palette button
+// before this module evaluated, a pre-hydration shim captured the event as a
+// single boolean flag. Calling __zdtpReadyClicks() here removes the shim
+// listener and re-dispatches once (at most) so the now-registered zdtp
+// listener picks it up and mounts the panel.
+if (typeof window !== "undefined") {
+  (window as { __zdtpReadyClicks?: () => void }).__zdtpReadyClicks?.();
+}
+
+// Idempotency guard: the two document.addEventListener calls below must be
+// installed at most once per page lifecycle. Module caching usually guarantees
+// this, but a future refactor could re-evaluate the module. The flag makes it
+// provably one-shot.
+// zfb fires "zfb:before-preparation" (before nav) and "zfb:after-swap" (after nav).
+// Adjust these event names if your zfb version uses different names.
+if (typeof document !== "undefined") {
+  if (!(document as Document & { __zdtpAstroBridgeInstalled?: boolean }).__zdtpAstroBridgeInstalled) {
+    (document as Document & { __zdtpAstroBridgeInstalled?: boolean }).__zdtpAstroBridgeInstalled = true;
+    document.addEventListener("zfb:before-preparation", () => {
+      document.dispatchEvent(new Event("astro:before-swap"));
+    });
+    document.addEventListener("zfb:after-swap", () => {
+      document.dispatchEvent(new Event("astro:page-load"));
+    });
+  }
+}

package/templates/features/docHistory/files/plugins/doc-history-plugin.mjs

@@ -0,0 +1,99 @@
+// zfb plugin module: doc-history.
+//
+// Wires three lifecycle hooks for the doc-history integration:
+//
+//   preBuild  — emits `.zfb/doc-history-meta.json` (per-page git metadata
+//               consumed at bundle time). Uses the tsx-e shim because the
+//               runner imports Node-only modules (`fs`, `child_process`) and
+//               TypeScript source that the plain-Node plugin host cannot load
+//               directly. Honours `SKIP_DOC_HISTORY=1` via `env: process.env`.
+//
+//   postBuild — invokes `runDocHistoryPostBuild` to write
+//               `<outDir>/doc-history/<slug>.json` files. Also honours
+//               `SKIP_DOC_HISTORY=1` (the runner returns early when set).
+//
+//   devMiddleware — reverse-proxies `/doc-history/*` requests to the
+//               standalone `@takazudo/zudo-doc-history-server` on port 4322.
+//
+// Inline functions are not supported by zfb's plugin runtime — see
+// `@takazudo/zfb/plugins` source comment. Plugins must be authored as
+// standalone modules and referenced from `zfb.config.ts` by `name`.
+//
+// The legacy `scripts/zfb-{pre,post}build.mjs` npm-script glue and
+// `scripts/dev-sidecar.mjs` stay in place during the merge window;
+// T6 retires them once all lifecycle epics land.
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { runDocHistoryPostBuild } from "@takazudo/zudo-doc/integrations/doc-history";
+import { createDocHistoryDevMiddleware } from "@takazudo/zudo-doc/integrations/doc-history";
+import { connectToZfbHandler } from "./connect-adapter.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// tsx is a workspace dep; resolving the binary explicitly avoids PATH
+// dependency — the plugin host is spawned by zfb without the user's shell profile.
+const TSX_BIN = resolve(HERE, "..", "node_modules", ".bin", "tsx");
+
+export default {
+  name: "doc-history",
+
+  async preBuild(ctx) {
+    const { docsDir, locales } = ctx.options;
+    // Serialize options as JSON for the tsx-e inline script. The runner
+    // (`runDocHistoryMetaStep`) honours SKIP_DOC_HISTORY=1 internally;
+    // passing `env: process.env` propagates the flag to the child process.
+    const optsJson = JSON.stringify({
+      projectRoot: ctx.projectRoot,
+      docsDir: typeof docsDir === "string" ? docsDir : "src/content/docs",
+      locales: locales ?? {},
+    });
+    const script = `
+      (async () => {
+        const { runDocHistoryMetaStep } = await import("@takazudo/zudo-doc/integrations/doc-history");
+        const opts = ${optsJson};
+        await runDocHistoryMetaStep(opts);
+      })().catch((err) => {
+        process.stderr.write(err && err.stack ? err.stack : String(err));
+        process.exit(1);
+      });
+    `;
+    const result = spawnSync(TSX_BIN, ["-e", script], {
+      cwd: ctx.projectRoot,
+      stdio: "inherit",
+      env: process.env,
+    });
+    if (result.status !== 0) {
+      throw new Error(
+        `doc-history-meta preBuild failed (exit ${result.status})`,
+      );
+    }
+  },
+
+  async postBuild(ctx) {
+    const { docsDir, locales } = ctx.options;
+    await runDocHistoryPostBuild(
+      { docsDir, locales },
+      { outDir: ctx.outDir, logger: ctx.logger },
+    );
+  },
+
+  devMiddleware(ctx) {
+    const middleware = createDocHistoryDevMiddleware(ctx.options, ctx.logger);
+    // zfb's `register(path, handler)` matches against the FULL request
+    // URL (no base-stripping). For a non-root base (e.g. "/my-docs/"),
+    // requests arrive as `/my-docs/doc-history/foo.json`, so we register
+    // at the full base-prefixed route. For base="/", the prefix is empty
+    // and the route is `/doc-history` as expected. The v2 middleware
+    // itself is base-tolerant (matches via `url.includes("/doc-history/")`)
+    // and slices from `/doc-history/` onward when proxying upstream.
+    const basePrefix = stripTrailingSlash(ctx.options.base ?? "");
+    ctx.register(`${basePrefix}/doc-history`, connectToZfbHandler(middleware));
+  },
+};
+
+function stripTrailingSlash(s) {
+  if (typeof s !== "string" || s.length === 0) return "";
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}