@takazudo/zudo-doc 3.2.0 → 3.3.0

package/dist/design-token-panel-config/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `@takazudo/zudo-doc/design-token-panel-config` — the PACKAGE-DEFAULT zdtp
+ * PanelConfig builder (#2658, epic Minimal Scaffold #2651, decision wave
+ * #2653 "Approach (a)").
+ *
+ * Ported from the showcase's `src/config/design-token-panel-config.ts` (441
+ * lines, ~90% mechanical derivation per the decision-wave audit) so
+ * `designTokenPanel: true` works with NO host config file: the Palette tab
+ * comes from `defaultColorSchemes`' shared `ramps`, the Color tab from
+ * `buildSemanticTierItems`, and Font/Spacing/Size from the manifest in
+ * `./manifest.js`. The hand-authored panel-identity constants
+ * (`storagePrefix`, `consoleNamespace`, `modalClassPrefix`, `schemaId`,
+ * `exportFilenameBase`) and the `FONT_ROLE_TO_SCALE` map are carried over
+ * verbatim — `storagePrefix: "zudo-doc-tweak"` in particular MUST NOT change
+ * (existing user-save carry-over guarantee, see `packages/zudo-doc/CLAUDE.md`
+ * and `src/CLAUDE.md`).
+ *
+ * A host that needs a fully custom panel (its own color schemes, its own
+ * token manifest) points `settings.designTokenPanelConfigModule` at a module
+ * exporting a named `buildDesignTokenPanelConfig` — see
+ * `../plugins/routes.ts` (`virtual:zudo-doc-design-token-panel-config`,
+ * mirrors the `chromeBindingsModule` contract). This module is what the
+ * routes plugin re-exports when NO override is configured.
+ *
+ * Unlike the showcase original, this builder does not resolve
+ * `settings.colorMode`/`settings.colorScheme` — the PACKAGE has no settings
+ * singleton to read (the preset's node-free eval-graph rule keeps this
+ * module out of the config eval graph too, so it must stay side-effect-free
+ * on import). It seeds the Color tab straight from `defaultColorSchemes`'
+ * "Default Light" / "Default Dark" entries for the requested `mode` — the
+ * exact pair `@takazudo/zudo-doc/theme.css` ships as the default scheme.
+ */
+import type { PanelConfig } from "@takazudo/zdtp";
+type PanelMode = "light" | "dark";
+/**
+ * Build the full PACKAGE-DEFAULT PanelConfig for a given color-scheme
+ * `mode`. Only the Color tab's semantic tier and `panelSettings.colorMode.
+ * defaultMode` vary by mode; the Palette/Font/Spacing/Size tabs are
+ * mode-independent. `@takazudo/zudo-doc/design-token-panel-bootstrap` calls
+ * this per mode on every `color-scheme-changed` toggle (destroy +
+ * reconfigure) — it is passed as the BUILDER, not a resolved config (#2610).
+ *
+ * `storagePrefix: "zudo-doc-tweak"` is the same value the showcase's own
+ * `design-token-panel-config.ts` has always used — keep it unchanged so a
+ * host migrating from an ejected config to this package default carries its
+ * existing user-saved tweaks over.
+ */
+export declare function buildDesignTokenPanelConfig(mode: PanelMode): PanelConfig;
+export {};

package/dist/design-token-panel-config/index.js

@@ -0,0 +1,214 @@
+import { SPACING_TOKENS, FONT_TOKENS, SIZE_TOKENS } from "./manifest.js";
+import { STATE_ROLES, buildSemanticTierItems } from "../color-scheme-utils.js";
+import { defaultColorSchemes } from "../color-schemes-defaults/index.js";
+const DEFAULT_SHIKI_THEME = "github-dark";
+function schemeNameForMode(mode) {
+  return mode === "dark" ? "Default Dark" : "Default Light";
+}
+function schemeForMode(mode) {
+  const scheme = defaultColorSchemes[schemeNameForMode(mode)];
+  if (!scheme) {
+    throw new Error(
+      `zudo-doc: defaultColorSchemes is missing "${schemeNameForMode(mode)}" \u2014 this is a package bug.`
+    );
+  }
+  return scheme;
+}
+function toTierItem(t) {
+  let kind;
+  if (t.control === "select") {
+    kind = { kind: "select", options: t.options ?? [] };
+  } else if (t.control === "text") {
+    kind = { kind: "text" };
+  } else {
+    kind = {
+      kind: "length",
+      step: t.step,
+      unit: t.unit
+    };
+  }
+  const item = {
+    id: t.id,
+    cssVar: t.cssVar,
+    label: t.label,
+    default: t.default,
+    type: kind
+  };
+  if (t.pill) item.pill = t.pill;
+  if (t.readonly) item.readonly = true;
+  return item;
+}
+function tierFromGroup(tokens, groupId, label) {
+  return {
+    id: groupId,
+    label,
+    items: tokens.filter((t) => t.group === groupId).map(toTierItem)
+  };
+}
+function buildRampTiers(mode) {
+  const { ramps } = schemeForMode(mode);
+  const baseTier = {
+    id: "base",
+    label: "Base",
+    items: ramps.base.map((color, i) => ({
+      id: `base-${i}`,
+      cssVar: `--palette-base-${i}`,
+      label: String(i),
+      default: color,
+      type: { kind: "color", format: "oklch" }
+    }))
+  };
+  const accentTier = {
+    id: "accent",
+    label: "Accent",
+    items: ramps.accent.map((color, i) => ({
+      id: `accent-${i}`,
+      cssVar: `--palette-accent-${i}`,
+      label: String(i),
+      default: color,
+      type: { kind: "color", format: "oklch" }
+    }))
+  };
+  const stateTier = {
+    id: "state",
+    label: "State",
+    items: STATE_ROLES.map((role) => ({
+      id: `state-${role}`,
+      cssVar: `--palette-state-${role}`,
+      label: role,
+      default: ramps.state[role],
+      type: { kind: "color", format: "oklch" }
+    }))
+  };
+  return [baseTier, accentTier, stateTier];
+}
+function buildPaletteTab(mode) {
+  return {
+    id: "palette",
+    label: "Palette",
+    tiers: buildRampTiers(mode)
+    // No colorExtras: a tab with multiple kind:'color' tiers MUST omit it so
+    // resolveColorClusterFromTab is not invoked and zdtp renders the ramps
+    // with its native curve editor (zdtp palette-tab contract).
+  };
+}
+function buildSemanticTier(mode) {
+  return {
+    id: "semantic",
+    label: "Semantic",
+    semantic: true,
+    referencesRamps: [
+      { tab: "palette", tier: "base" },
+      { tab: "palette", tier: "accent" },
+      { tab: "palette", tier: "state" }
+    ],
+    items: buildSemanticTierItems(schemeForMode(mode))
+  };
+}
+function buildColorExtras(mode) {
+  const lightScheme = schemeNameForMode("light");
+  const darkScheme = schemeNameForMode("dark");
+  return {
+    id: "zudo-doc",
+    label: "Zudo Doc",
+    baseRoles: {},
+    baseDefaults: {},
+    defaultShikiTheme: DEFAULT_SHIKI_THEME,
+    colorSchemes: {},
+    panelSettings: {
+      colorScheme: schemeNameForMode(mode),
+      colorMode: { defaultMode: mode, lightScheme, darkScheme }
+    }
+  };
+}
+function buildColorTab(mode) {
+  return {
+    id: "color",
+    label: "Color",
+    tiers: [buildSemanticTier(mode)],
+    colorExtras: buildColorExtras(mode)
+  };
+}
+const FONT_SCALE_TIER_ID = "font-scale";
+const FONT_ROLE_TO_SCALE = {
+  "text-micro": "text-scale-2xs",
+  "text-caption": "text-scale-xs",
+  "text-small": "text-scale-sm",
+  "text-body": "text-scale-md",
+  "text-title": "text-scale-lg",
+  "text-heading": "text-scale-xl",
+  "text-display": "text-scale-2xl"
+};
+function buildFontRoleTier() {
+  const base = tierFromGroup(FONT_TOKENS, "font-size", "Font size");
+  return {
+    ...base,
+    items: base.items.map((item) => {
+      const scaleId = FONT_ROLE_TO_SCALE[item.id];
+      return scaleId ? { ...item, default: scaleId } : item;
+    }),
+    referencesTier: FONT_SCALE_TIER_ID
+  };
+}
+function buildFontTab() {
+  return {
+    id: "font",
+    label: "Font",
+    tiers: [
+      tierFromGroup(FONT_TOKENS, FONT_SCALE_TIER_ID, "Scale"),
+      buildFontRoleTier(),
+      tierFromGroup(FONT_TOKENS, "line-height", "Line height"),
+      tierFromGroup(FONT_TOKENS, "font-weight", "Font weight"),
+      tierFromGroup(FONT_TOKENS, "font-family", "Font family")
+    ]
+  };
+}
+function buildSpacingTab() {
+  return {
+    id: "spacing",
+    label: "Spacing",
+    tiers: [
+      tierFromGroup(SPACING_TOKENS, "hsp", "Horizontal spacing"),
+      tierFromGroup(SPACING_TOKENS, "vsp", "Vertical spacing"),
+      tierFromGroup(SPACING_TOKENS, "icon", "Icons"),
+      tierFromGroup(SPACING_TOKENS, "layout", "Layout")
+    ]
+  };
+}
+function buildSizeTab() {
+  return {
+    id: "size",
+    label: "Size",
+    tiers: [
+      tierFromGroup(SIZE_TOKENS, "radius", "Radius"),
+      tierFromGroup(SIZE_TOKENS, "transition", "Transition")
+    ]
+  };
+}
+function buildDesignTokenPanelConfig(mode) {
+  return {
+    storagePrefix: "zudo-doc-tweak",
+    consoleNamespace: "zudoDoc",
+    modalClassPrefix: "zudo-doc-design-token-panel-modal",
+    // DISPLAY-ONLY in zdtp 0.4.6: the panel's export hard-codes
+    // `zudo-design-tokens/v2` and auto-upgrades to `.../v3` when object leaves
+    // ({ref}/{literal}/per-mode) are present — which the semantic tier's ramp
+    // refs always are, so real exports carry v3. `schemaId` does NOT gate
+    // import, and (verified against the installed zdtp 0.4.6 bundle) zdtp's
+    // Import/Export modals do not read this field at all — their hint/error
+    // text is hardcoded to zdtp's own internal `SCHEMA_V1`/`SCHEMA_V2`/
+    // `SCHEMA_V3` constants (#498/#505), which are unrelated to this field.
+    // It is thus a purely descriptive config value with no runtime effect;
+    // set to v3 (a literal, not one of those constants) to match what real
+    // exports carry. Distinct from the host serde's `DESIGN_TOKEN_SCHEMA`
+    // (`zudo-doc-design-tokens/v3` — bumped from v2 in #2599 so a stale
+    // pre-5/3-minimize export resets instead of crashing on import), which
+    // governs a separate round-trip.
+    schemaId: "zudo-design-tokens/v3",
+    exportFilenameBase: "zudo-doc-design-tokens",
+    tabs: [buildPaletteTab(mode), buildColorTab(mode), buildFontTab(), buildSpacingTab(), buildSizeTab()]
+  };
+}
+export {
+  buildDesignTokenPanelConfig
+};

package/dist/design-token-panel-config/manifest.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Design-token manifest data arrays — the PACKAGE-DEFAULT source of truth for
+ * the spacing/font/size tabs of `buildDesignTokenPanelConfig` (#2658, epic
+ * Minimal Scaffold #2651).
+ *
+ * Ported verbatim from the showcase's `src/config/design-tokens-manifest.ts`
+ * (values mirror the defaults shipped by `@takazudo/zudo-doc/theme.css`,
+ * #2655) so `designTokenPanel: true` works with no host manifest file. A
+ * project that needs its own token set entirely ejects via
+ * `designTokenPanelConfigModule` (see `../plugins/routes.ts`), not by editing
+ * this file — this module stays the PACKAGE default.
+ *
+ * Type strategy: arrays are typed `readonly TokenDef[]`, matching the
+ * upstream zdtp `TokenDef` shape consumed by `../color-scheme-utils.js` and
+ * `./index.ts` (which partitions them into `TabConfig.tiers` by `group`).
+ */
+import type { TokenDef } from "@takazudo/zdtp";
+/**
+ * Spacing tokens — mirrors every `--spacing-*` declaration shipped by
+ * `@takazudo/zudo-doc/theme.css`, 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 declare const SPACING_TOKENS: readonly TokenDef[];
+/**
+ * Font tokens — mirrors every font-related declaration shipped by
+ * `@takazudo/zudo-doc/theme.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.
+ */
+export declare const FONT_TOKENS: readonly TokenDef[];
+/**
+ * Size tokens — mirrors every non-breakpoint size-category custom property
+ * shipped by `@takazudo/zudo-doc/theme.css`. Breakpoints (`--breakpoint-*`)
+ * are intentionally omitted — live-changing them causes layout thrash
+ * mid-drag and adds no real tweak value.
+ *
+ * Radius defaults use `px` (matches a 0-100 slider), even though
+ * `theme.css` expresses them in `rem` — the browser accepts both.
+ * `--radius-full` carries a `pill` toggle: its design default (`9999px`) is
+ * an intentional sentinel a 0-100 slider can't reach.
+ */
+export declare const SIZE_TOKENS: readonly TokenDef[];

package/dist/design-token-panel-config/manifest.js

@@ -0,0 +1,105 @@
+const FONT_WEIGHT_OPTIONS = [
+  "100",
+  "200",
+  "300",
+  "400",
+  "500",
+  "600",
+  "700",
+  "800",
+  "900"
+];
+const SPACING_TOKENS = [
+  // --- Horizontal spacing ---
+  { id: "hsp-2xs", cssVar: "--spacing-hsp-2xs", label: "hsp-2xs", group: "hsp", default: "0.125rem", step: 0.025, unit: "rem" },
+  { id: "hsp-xs", cssVar: "--spacing-hsp-xs", label: "hsp-xs", group: "hsp", default: "0.375rem", step: 0.025, unit: "rem" },
+  { id: "hsp-sm", cssVar: "--spacing-hsp-sm", label: "hsp-sm", group: "hsp", default: "0.5rem", step: 0.025, unit: "rem" },
+  { id: "hsp-md", cssVar: "--spacing-hsp-md", label: "hsp-md", group: "hsp", default: "0.75rem", step: 0.025, unit: "rem" },
+  { id: "hsp-lg", cssVar: "--spacing-hsp-lg", label: "hsp-lg", group: "hsp", default: "1rem", step: 0.025, unit: "rem" },
+  { id: "hsp-xl", cssVar: "--spacing-hsp-xl", label: "hsp-xl", group: "hsp", default: "1.5rem", step: 0.025, unit: "rem" },
+  { id: "hsp-2xl", cssVar: "--spacing-hsp-2xl", label: "hsp-2xl", group: "hsp", default: "2rem", step: 0.025, unit: "rem" },
+  // --- Vertical spacing ---
+  { id: "vsp-3xs", cssVar: "--spacing-vsp-3xs", label: "vsp-3xs", group: "vsp", default: "0.25rem", step: 0.025, unit: "rem" },
+  { id: "vsp-2xs", cssVar: "--spacing-vsp-2xs", label: "vsp-2xs", group: "vsp", default: "0.4375rem", step: 0.025, unit: "rem" },
+  { id: "vsp-xs", cssVar: "--spacing-vsp-xs", label: "vsp-xs", group: "vsp", default: "0.875rem", step: 0.025, unit: "rem" },
+  { id: "vsp-sm", cssVar: "--spacing-vsp-sm", label: "vsp-sm", group: "vsp", default: "1.25rem", step: 0.025, unit: "rem" },
+  { id: "vsp-md", cssVar: "--spacing-vsp-md", label: "vsp-md", group: "vsp", default: "1.5rem", step: 0.025, unit: "rem" },
+  { id: "vsp-lg", cssVar: "--spacing-vsp-lg", label: "vsp-lg", group: "vsp", default: "1.75rem", step: 0.025, unit: "rem" },
+  { id: "vsp-xl", cssVar: "--spacing-vsp-xl", label: "vsp-xl", group: "vsp", default: "2.5rem", step: 0.025, unit: "rem" },
+  { id: "vsp-2xl", cssVar: "--spacing-vsp-2xl", label: "vsp-2xl", group: "vsp", default: "3.5rem", step: 0.025, unit: "rem" },
+  // --- Icons ---
+  { id: "icon-xs", cssVar: "--spacing-icon-xs", label: "icon-xs", group: "icon", default: "0.75rem", step: 0.05, unit: "rem" },
+  { id: "icon-sm", cssVar: "--spacing-icon-sm", label: "icon-sm", group: "icon", default: "1rem", step: 0.05, unit: "rem" },
+  { id: "icon-md", cssVar: "--spacing-icon-md", label: "icon-md", group: "icon", default: "1.25rem", step: 0.05, unit: "rem" },
+  { id: "icon-lg", cssVar: "--spacing-icon-lg", label: "icon-lg", group: "icon", default: "1.5rem", step: 0.05, unit: "rem" },
+  // --- Layout ---
+  { id: "image-overlay-inset", cssVar: "--spacing-image-overlay-inset", label: "image-overlay-inset", group: "layout", default: "0.5rem", 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", 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", 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)", step: 1, unit: "", readonly: true }
+];
+const FONT_TOKENS = [
+  // --- Font sizes (Tier 2 semantic) ---
+  { id: "text-micro", cssVar: "--text-micro", label: "text-micro", group: "font-size", default: "0.75rem", step: 0.05, unit: "rem" },
+  { id: "text-caption", cssVar: "--text-caption", label: "text-caption", group: "font-size", default: "0.875rem", step: 0.05, unit: "rem" },
+  { id: "text-small", cssVar: "--text-small", label: "text-small", group: "font-size", default: "1rem", step: 0.05, unit: "rem" },
+  { id: "text-body", cssVar: "--text-body", label: "text-body", group: "font-size", default: "1.2rem", step: 0.05, unit: "rem" },
+  { id: "text-title", cssVar: "--text-title", label: "text-title", group: "font-size", default: "1.4rem", step: 0.05, unit: "rem" },
+  { id: "text-heading", cssVar: "--text-heading", label: "text-heading", group: "font-size", default: "3rem", step: 0.05, unit: "rem" },
+  { id: "text-display", cssVar: "--text-display", label: "text-display", group: "font-size", default: "3.75rem", step: 0.05, unit: "rem" },
+  // --- Line heights (unitless) ---
+  { id: "leading-tight", cssVar: "--leading-tight", label: "leading-tight", group: "line-height", default: "1.25", step: 0.05, unit: "" },
+  { id: "leading-snug", cssVar: "--leading-snug", label: "leading-snug", group: "line-height", default: "1.375", step: 0.05, unit: "" },
+  { id: "leading-normal", cssVar: "--leading-normal", label: "leading-normal", group: "line-height", default: "1.5", step: 0.05, unit: "" },
+  { id: "leading-relaxed", cssVar: "--leading-relaxed", label: "leading-relaxed", group: "line-height", default: "1.625", step: 0.05, unit: "" },
+  // --- Font weights (select) ---
+  { id: "font-weight-normal", cssVar: "--font-weight-normal", label: "font-weight-normal", group: "font-weight", default: "400", 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", 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", 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", 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", step: 1, unit: "", control: "text" },
+  { id: "font-mono", cssVar: "--font-mono", label: "font-mono", group: "font-family", default: "ui-monospace, monospace", step: 1, unit: "", control: "text" },
+  // --- Tier 1 abstract scale ---
+  { id: "text-scale-2xs", cssVar: "--text-scale-2xs", label: "text-scale-2xs", group: "font-scale", default: "0.75rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-xs", cssVar: "--text-scale-xs", label: "text-scale-xs", group: "font-scale", default: "0.875rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-sm", cssVar: "--text-scale-sm", label: "text-scale-sm", group: "font-scale", default: "1rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-md", cssVar: "--text-scale-md", label: "text-scale-md", group: "font-scale", default: "1.2rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-lg", cssVar: "--text-scale-lg", label: "text-scale-lg", group: "font-scale", default: "1.4rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-xl", cssVar: "--text-scale-xl", label: "text-scale-xl", group: "font-scale", default: "3rem", step: 0.05, unit: "rem" },
+  { id: "text-scale-2xl", cssVar: "--text-scale-2xl", label: "text-scale-2xl", group: "font-scale", default: "3.75rem", step: 0.05, unit: "rem" }
+];
+const SIZE_TOKENS = [
+  // --- Radius ---
+  { id: "radius-DEFAULT", cssVar: "--radius-DEFAULT", label: "radius-DEFAULT", group: "radius", default: "4px", step: 1, unit: "px" },
+  { id: "radius-lg", cssVar: "--radius-lg", label: "radius-lg", group: "radius", default: "8px", step: 1, unit: "px" },
+  {
+    id: "radius-full",
+    cssVar: "--radius-full",
+    label: "radius-full",
+    group: "radius",
+    default: "9999px",
+    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",
+    step: 10,
+    unit: "ms"
+  }
+];
+export {
+  FONT_TOKENS,
+  SIZE_TOKENS,
+  SPACING_TOKENS
+};

package/dist/directive-vocabulary-defaults/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Default directive vocabulary — the canonical seven.
+ *
+ * Ported from the `directiveVocabulary` object that every
+ * `create-zudo-doc`-generated `zfb.config.ts` previously hardcoded inline
+ * (see `packages/create-zudo-doc/src/zfb-config-gen.ts`'s `generateZfbConfig`
+ * and this repo's own `zfb.config.ts`) into a package default (epic
+ * zudolab/zudo-doc#2651, S4 #2654).
+ *
+ * Keys are directive names; values are the JSX component names the markdown
+ * pipeline's `directives` feature resolves them to (registered in the host's
+ * `pages/_mdx-components.ts`). `details` routes to a collapsible, NOT an
+ * admonition — the other six are admonition variants.
+ */
+import type { DirectiveVocabulary } from "../preset.js";
+export declare const defaultDirectiveVocabulary: DirectiveVocabulary;

package/dist/directive-vocabulary-defaults/index.js

@@ -0,0 +1,12 @@
+const defaultDirectiveVocabulary = {
+  note: "Note",
+  tip: "Tip",
+  info: "Info",
+  warning: "Warning",
+  danger: "Danger",
+  caution: "Caution",
+  details: "Details"
+};
+export {
+  defaultDirectiveVocabulary
+};

package/dist/doc-body-end-islands/index.d.ts

@@ -1,7 +1,8 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
 import type { JSX } from "preact";
-/** The `settings` subset this factory reads — the three package-island flags.
+import type { FactoryComponent } from "../factory-context/index.js";
+/** The `settings` subset this factory reads — the four package-island flags.
  *  A structural subset so the host can pass its full `Settings` object. */
 export interface BodyEndIslandsSettings {
     aiAssistant: boolean;
@@ -14,10 +15,38 @@ export interface BodyEndIslandsSettings {
      *  `undefined` is treated as `false` (no overlay) at the mount site, preserving
      *  pre-#2482 behavior; internal callers always pass the full `Settings`. */
     dynamicPageTransition?: boolean;
+    /** Gates the `DesignTokenPanelBootstrap` island mount (#2658). Optional for
+     *  the same external-caller-compat reason as `dynamicPageTransition` above.
+     *  `undefined` is treated as `false` (no panel island). Even when `true`,
+     *  nothing mounts unless `deps.DesignTokenPanelBootstrap` was also supplied
+     *  — see {@link BodyEndIslandsDeps}. */
+    designTokenPanel?: boolean;
+    /**
+     * Gates the `FindInPageInit` island mount (zudolab/zudo-doc#2689). Optional
+     * for the same external-caller-compat reason as `dynamicPageTransition`/
+     * `designTokenPanel` above. `undefined` is treated as `false` (no island).
+     * Controls the PACKAGE-DEFAULT `BodyEndIslands` slot only — a host that
+     * overrides the `BodyEndIslands` chrome binding must mount `FindInPageInit`
+     * itself.
+     */
+    findInPage?: boolean;
 }
 /** Dependencies injected by `_chrome.tsx` (carries the virtual-module settings). */
 export interface BodyEndIslandsDeps {
     settings: BodyEndIslandsSettings;
+    /**
+     * The real `DesignTokenPanelBootstrap` component (#2658) — see the module
+     * header note above for why it is NOT imported directly here.
+     * `chrome/derive.tsx`'s `deriveBodyEndIslands` supplies
+     * `@takazudo/zudo-doc/design-token-panel-bootstrap`'s
+     * `DesignTokenPanelBootstrap` as the default for every `createChrome`
+     * consumer (#2659 gate-2 fix), so chrome-derived callers always carry it.
+     * Omitted (a bare `createBodyEndIslands({ settings })` call outside the
+     * chrome path, as this factory's own unit tests do) means no panel island
+     * mounts even when `settings.designTokenPanel` is `true` — a safe no-op,
+     * not a crash.
+     */
+    DesignTokenPanelBootstrap?: FactoryComponent;
 }
 /** Props for the produced `BodyEndIslands` component. */
 export interface BodyEndIslandsProps {
@@ -30,10 +59,4 @@ export interface BodyEndIslandsProps {
      */
     aiChatBodyLabel?: string;
 }
-/**
- * Build the package-default `BodyEndIslands` component bound to the host's
- * serializable `settings` flags. The produced component matches the
- * `createDocBodyEnd` `BodyEndIslands` slot contract
- * (`(props: { basePath: string }) => JSX.Element`).
- */
 export declare function createBodyEndIslands(deps: BodyEndIslandsDeps): (props: BodyEndIslandsProps) => JSX.Element;

package/dist/doc-body-end-islands/index.js

@@ -3,10 +3,24 @@ import { Island } from "@takazudo/zfb";
 import { AiChatModal } from "../ai-chat-modal/index.js";
 import { ImageEnlarge, ImageEnlargeSsrFallback } from "../image-enlarge/index.js";
 import { MermaidEnlarge, MermaidEnlargeSsrFallback } from "../mermaid-enlarge/index.js";
+import { FindInPageInit } from "../find-in-page/index.js";
 import { PageLoadingOverlay } from "../page-loading/index.js";
 const DEFAULT_AI_CHAT_BODY_LABEL = "Ask a question about the documentation.";
+const ZDTP_TOGGLE_SHIM_SRC = `(function(){
+if(window.__zdtpToggleShimInstalled)return;
+window.__zdtpToggleShimInstalled=true;
+var pending=false;
+function shim(){pending=true;}
+window.addEventListener('toggle-design-token-panel',shim);
+window.__zdtpReadyClicks=function(){
+window.removeEventListener('toggle-design-token-panel',shim);
+delete window.__zdtpReadyClicks;
+if(pending){pending=false;window.dispatchEvent(new CustomEvent('toggle-design-token-panel'));}
+};
+})();`;
 function createBodyEndIslands(deps) {
   const { settings } = deps;
+  const DesignTokenPanelBootstrap = deps.DesignTokenPanelBootstrap;
   function BodyEndIslands({
     basePath,
     aiChatBodyLabel = DEFAULT_AI_CHAT_BODY_LABEL
@@ -28,8 +42,21 @@ function createBodyEndIslands(deps) {
       ssrFallback: /* @__PURE__ */ jsx(MermaidEnlargeSsrFallback, {}),
       children: /* @__PURE__ */ jsx(MermaidEnlarge, {})
     }) : null;
+    const designTokenPanelBootstrap = settings.designTokenPanel && DesignTokenPanelBootstrap ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: ZDTP_TOGGLE_SHIM_SRC } }),
+      Island({
+        when: "load",
+        children: /* @__PURE__ */ jsx(DesignTokenPanelBootstrap, {})
+      })
+    ] }) : null;
+    const findInPageInit = settings.findInPage ? Island({
+      when: "load",
+      children: /* @__PURE__ */ jsx(FindInPageInit, {})
+    }) : null;
     return /* @__PURE__ */ jsxs(Fragment, { children: [
       settings.dynamicPageTransition ? /* @__PURE__ */ jsx(PageLoadingOverlay, {}) : null,
+      designTokenPanelBootstrap,
+      findInPageInit,
       aiAssistant,
       imageEnlarge,
       mermaidEnlarge

package/dist/docs-schema/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Default docs-frontmatter zod schema builder.
+ *
+ * Ported (and parameterized) from the `create-zudo-doc` base template's
+ * `src/config/docs-schema.ts` `buildDocsSchema` export (epic
+ * zudolab/zudo-doc#2651, S4 #2654).
+ *
+ * Unlike the template original — which read the host `settings` and
+ * `tag-vocabulary` singletons directly — this package default NEVER imports
+ * host singletons: governance mode and the vocabulary entries are passed in
+ * as `opts`. `zudoDoc()` (#2657) calls this with the project's merged
+ * governance config; a project may also override `buildDocsSchema` entirely
+ * via `ZudoDocConfig.buildDocsSchema`.
+ */
+import { z } from "zod";
+import type { PresetTagVocabularyEntry } from "../preset.js";
+export interface BuildDocsSchemaOptions {
+    tagGovernance?: "off" | "warn" | "strict";
+    tagVocabulary?: readonly PresetTagVocabularyEntry[];
+}
+/**
+ * Build the docs frontmatter zod schema.
+ *
+ * Returns a single `z.object(...).passthrough()` reused for every docs
+ * collection (default + per-locale + per-version + per-version-per-locale).
+ * The `tags` field is governance-aware: `buildTagsSchema()` returns a plain
+ * `z.array(z.string())` when governance is off (or `opts` is omitted), or a
+ * restricted `z.enum` when `opts.tagGovernance: "strict"` plus a non-empty
+ * `opts.tagVocabulary` is supplied.
+ *
+ * `.passthrough()` keeps custom frontmatter keys (e.g. `author`, `status`)
+ * available downstream — the frontmatter-preview UI relies on this to
+ * surface arbitrary keys without declaring each one here.
+ */
+export declare function buildDocsSchema(opts?: BuildDocsSchemaOptions): z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    sidebar_position: z.ZodOptional<z.ZodNumber>;
+    sidebar_label: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>> | z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>>;
+    search_exclude: z.ZodOptional<z.ZodBoolean>;
+    pagination_next: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    pagination_prev: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    draft: z.ZodOptional<z.ZodBoolean>;
+    unlisted: z.ZodOptional<z.ZodBoolean>;
+    hide_sidebar: z.ZodOptional<z.ZodBoolean>;
+    hide_toc: z.ZodOptional<z.ZodBoolean>;
+    wide: z.ZodOptional<z.ZodBoolean>;
+    doc_history: z.ZodOptional<z.ZodBoolean>;
+    standalone: z.ZodOptional<z.ZodBoolean>;
+    slug: z.ZodOptional<z.ZodString>;
+    generated: z.ZodOptional<z.ZodBoolean>;
+    category_no_page: z.ZodOptional<z.ZodBoolean>;
+    category_sort_order: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}, z.core.$loose>;
+/**
+ * TypeScript type inferred from the default docs frontmatter zod schema.
+ * A project overriding `buildDocsSchema` via `ZudoDocConfig` should derive
+ * its own `DocsData` type from its own builder instead of this one.
+ */
+export type DocsData = z.infer<ReturnType<typeof buildDocsSchema>>;