create-zudo-doc 0.2.21 → 1.0.0

package/templates/base/src/config/color-scheme-utils.ts

@@ -1,64 +1,39 @@
-import { colorSchemes, type ColorScheme, type ColorRef } from "./color-schemes";
+/**
+ * Project-side color-scheme helpers.
+ *
+ * The MECHANISM (palette→CSS injection logic) now lives in the package:
+ * `@takazudo/zudo-doc/color-scheme-utils`. This file re-exports those
+ * mechanism symbols and adds project-specific thin wrappers that read from
+ * this project's `colorSchemes` map and `settings`. The DATA (palette values,
+ * scheme names) stays in `./color-schemes` and `./settings`.
+ *
+ * S9a package-first migration — zudolab/zudo-doc#2333.
+ */
+
+export {
+  type ColorRef,
+  type ColorScheme,
+  SEMANTIC_DEFAULTS,
+  SEMANTIC_CSS_NAMES,
+  resolveColor,
+  resolveSemanticColors,
+  schemeToCssPairs,
+  generateCssCustomProperties as generateCssCustomPropertiesFromScheme,
+  generateLightDarkCssProperties as generateLightDarkCssPropertiesFromSchemes,
+} from "@takazudo/zudo-doc/color-scheme-utils";
+import {
+  generateCssCustomProperties as _generateCssCustomProperties,
+  generateLightDarkCssProperties as _generateLightDarkCssProperties,
+} from "@takazudo/zudo-doc/color-scheme-utils";
+
+import { colorSchemes } from "./color-schemes";
 import { settings } from "./settings";
 
-/** Default mapping: semantic token name → palette index */
-export const SEMANTIC_DEFAULTS: Record<string, number> = {
-  surface: 0,
-  muted: 8,
-  accent: 5,
-  accentHover: 14,
-  codeBg: 10,
-  codeFg: 11,
-  success: 2,
-  danger: 1,
-  warning: 3,
-  info: 4,
-  mermaidNodeBg: 9,
-  mermaidText: 11,
-  mermaidLine: 8,
-  mermaidLabelBg: 10,
-  mermaidNoteBg: 0,
-  chatUserBg: 5,
-  chatUserText: 9,
-  chatAssistantBg: 9,
-  chatAssistantText: 11,
-  imageOverlayBg: 0,
-  imageOverlayFg: 11,
-  matchedKeywordBg: 3,
-  matchedKeywordFg: 15,
-};
-
-export const SEMANTIC_CSS_NAMES: Record<string, string> = {
-  surface: "--zd-surface",
-  muted: "--zd-muted",
-  accent: "--zd-accent",
-  accentHover: "--zd-accent-hover",
-  codeBg: "--zd-code-bg",
-  codeFg: "--zd-code-fg",
-  success: "--zd-success",
-  danger: "--zd-danger",
-  warning: "--zd-warning",
-  info: "--zd-info",
-  mermaidNodeBg: "--zd-mermaid-node-bg",
-  mermaidText: "--zd-mermaid-text",
-  mermaidLine: "--zd-mermaid-line",
-  mermaidLabelBg: "--zd-mermaid-label-bg",
-  mermaidNoteBg: "--zd-mermaid-note-bg",
-  chatUserBg: "--zd-chat-user-bg",
-  chatUserText: "--zd-chat-user-text",
-  chatAssistantBg: "--zd-chat-assistant-bg",
-  chatAssistantText: "--zd-chat-assistant-text",
-  imageOverlayBg: "--zd-image-overlay-bg",
-  imageOverlayFg: "--zd-image-overlay-fg",
-  matchedKeywordBg: "--zd-matched-keyword-bg",
-  matchedKeywordFg: "--zd-matched-keyword-fg",
-};
-
 export const lightDarkPairings = [
   { light: "Default Light", dark: "Default Dark", label: "Default" },
 ];
 
-export function getActiveScheme(): ColorScheme {
+export function getActiveScheme() {
   const scheme = colorSchemes[settings.colorScheme];
   if (!scheme) {
     throw new Error(`Unknown color scheme: "${settings.colorScheme}". Available: ${Object.keys(colorSchemes).join(", ")}`);
@@ -66,93 +41,12 @@ export function getActiveScheme(): ColorScheme {
   return scheme;
 }
 
-/** Resolve a ColorRef to a concrete color string.
- *  - number → palette[value]
- *  - string → used as-is
- *  - undefined → fallback */
-export function resolveColor(
-  value: ColorRef | undefined,
-  palette: string[],
-  fallback: string,
-): string {
-  if (value === undefined) return fallback;
-  if (typeof value === "number") return palette[value] ?? fallback;
-  return value;
-}
-
-/** Resolve semantic colors with fallbacks to default palette slots */
-export function resolveSemanticColors(scheme: ColorScheme) {
-  const p = scheme.palette;
-  return {
-    surface: resolveColor(scheme.semantic?.surface, p, p[0]),
-    muted: resolveColor(scheme.semantic?.muted, p, p[8]),
-    accent: resolveColor(scheme.semantic?.accent, p, p[5]),
-    accentHover: resolveColor(scheme.semantic?.accentHover, p, p[14]),
-    codeBg: resolveColor(scheme.semantic?.codeBg, p, p[10]),
-    codeFg: resolveColor(scheme.semantic?.codeFg, p, p[11]),
-    success: resolveColor(scheme.semantic?.success, p, p[2]),
-    danger: resolveColor(scheme.semantic?.danger, p, p[1]),
-    warning: resolveColor(scheme.semantic?.warning, p, p[3]),
-    info: resolveColor(scheme.semantic?.info, p, p[4]),
-    mermaidNodeBg: resolveColor(scheme.semantic?.mermaidNodeBg, p, p[9]),
-    mermaidText: resolveColor(scheme.semantic?.mermaidText, p, p[11]),
-    mermaidLine: resolveColor(scheme.semantic?.mermaidLine, p, p[8]),
-    mermaidLabelBg: resolveColor(scheme.semantic?.mermaidLabelBg, p, p[10]),
-    mermaidNoteBg: resolveColor(scheme.semantic?.mermaidNoteBg, p, p[0]),
-    chatUserBg: resolveColor(scheme.semantic?.chatUserBg, p, p[5]),
-    chatUserText: resolveColor(scheme.semantic?.chatUserText, p, p[9]),
-    chatAssistantBg: resolveColor(scheme.semantic?.chatAssistantBg, p, p[9]),
-    chatAssistantText: resolveColor(scheme.semantic?.chatAssistantText, p, p[11]),
-    imageOverlayBg: resolveColor(scheme.semantic?.imageOverlayBg, p, p[0]),
-    imageOverlayFg: resolveColor(scheme.semantic?.imageOverlayFg, p, p[11]),
-    matchedKeywordBg: resolveColor(scheme.semantic?.matchedKeywordBg, p, p[3]),
-    matchedKeywordFg: resolveColor(scheme.semantic?.matchedKeywordFg, p, p[15]),
-  };
-}
-
-export function schemeToCssPairs(scheme: ColorScheme): [string, string][] {
-  const p = scheme.palette;
-  const sem = resolveSemanticColors(scheme);
-  return [
-    ["--zd-bg", resolveColor(scheme.background, p, p[0])],
-    ["--zd-fg", resolveColor(scheme.foreground, p, p[15])],
-    ["--zd-cursor", resolveColor(scheme.cursor, p, p[6])], // intentionally inert/vestigial: exposed in the design-token panel but no CSS rule consumes it (no caret-color wiring); mirrors shikiTheme's status
-    ["--zd-sel-bg", resolveColor(scheme.selectionBg, p, resolveColor(scheme.background, p, p[0]))],
-    ["--zd-sel-fg", resolveColor(scheme.selectionFg, p, resolveColor(scheme.foreground, p, p[15]))],
-    ...p.map((color, i) => [`--zd-${i}`, color] as [string, string]),
-    ["--zd-surface", sem.surface],
-    ["--zd-muted", sem.muted],
-    ["--zd-accent", sem.accent],
-    ["--zd-accent-hover", sem.accentHover],
-    ["--zd-code-bg", sem.codeBg],
-    ["--zd-code-fg", sem.codeFg],
-    ["--zd-success", sem.success],
-    ["--zd-danger", sem.danger],
-    ["--zd-warning", sem.warning],
-    ["--zd-info", sem.info],
-    ["--zd-mermaid-node-bg", sem.mermaidNodeBg],
-    ["--zd-mermaid-text", sem.mermaidText],
-    ["--zd-mermaid-line", sem.mermaidLine],
-    ["--zd-mermaid-label-bg", sem.mermaidLabelBg],
-    ["--zd-mermaid-note-bg", sem.mermaidNoteBg],
-    ["--zd-chat-user-bg", sem.chatUserBg],
-    ["--zd-chat-user-text", sem.chatUserText],
-    ["--zd-chat-assistant-bg", sem.chatAssistantBg],
-    ["--zd-chat-assistant-text", sem.chatAssistantText],
-    ["--zd-image-overlay-bg", sem.imageOverlayBg],
-    ["--zd-image-overlay-fg", sem.imageOverlayFg],
-    ["--zd-matched-keyword-bg", sem.matchedKeywordBg],
-    ["--zd-matched-keyword-fg", sem.matchedKeywordFg],
-  ];
-}
-
+/** Generate `:root { --zd-* }` CSS for the project's active single scheme. */
 export function generateCssCustomProperties(): string {
-  const scheme = getActiveScheme();
-  const pairs = schemeToCssPairs(scheme);
-  const lines = [":root {", ...pairs.map(([prop, value]) => `  ${prop}: ${value};`), "}"];
-  return lines.join("\n");
+  return _generateCssCustomProperties(getActiveScheme());
 }
 
+/** Generate `:root { --zd-*: light-dark(…) }` CSS for the project's configured light/dark pair. */
 export function generateLightDarkCssProperties(): string {
   if (!settings.colorMode) {
     throw new Error("colorMode is not configured");
@@ -162,23 +56,5 @@ export function generateLightDarkCssProperties(): string {
   const dark = colorSchemes[darkScheme];
   if (!light) throw new Error(`Unknown light scheme: "${lightScheme}"`);
   if (!dark) throw new Error(`Unknown dark scheme: "${darkScheme}"`);
-
-  const lightPairs = schemeToCssPairs(light);
-  const darkPairs = schemeToCssPairs(dark);
-
-  if (lightPairs.length !== darkPairs.length) {
-    throw new Error(`Light scheme has ${lightPairs.length} properties but dark scheme has ${darkPairs.length}`);
-  }
-
-  const lines = [":root {", "  color-scheme: light dark;"];
-  for (let i = 0; i < lightPairs.length; i++) {
-    const lightPair = lightPairs[i];
-    const darkPair = darkPairs[i];
-    if (!lightPair || !darkPair) continue;
-    const [prop, lightVal] = lightPair;
-    const darkVal = darkPair[1];
-    lines.push(`  ${prop}: light-dark(${lightVal}, ${darkVal});`);
-  }
-  lines.push("}");
-  return lines.join("\n");
+  return _generateLightDarkCssProperties(light, dark);
 }

package/templates/base/src/config/i18n.ts

@@ -74,6 +74,9 @@ const translations: Record<string, Record<string, string>> = {
     "search.placeholder": "Type to search...",
     "search.shortcutHint": "to open search from anywhere",
     "search.resultCount": "{count} results",
+    "search.unavailable": "Search unavailable",
+    "search.loadingIndex": "Loading search index…",
+    "search.noResults": "No results found.",
     "code.copy": "Copy code",
     "code.copied": "Copied!",
     "code.wrapToggle": "Toggle word wrap",
@@ -134,6 +137,9 @@ const translations: Record<string, Record<string, string>> = {
     "search.placeholder": "検索したい単語を入力",
     "search.shortcutHint": "いつでも検索バーを開ける",
     "search.resultCount": "{count} 件",
+    "search.unavailable": "検索を利用できません",
+    "search.loadingIndex": "検索インデックスを読み込み中…",
+    "search.noResults": "検索結果が見つかりませんでした。",
     "code.copy": "コードをコピー",
     "code.copied": "コピーしました！",
     "code.wrapToggle": "折り返し切替",
@@ -194,6 +200,9 @@ const translations: Record<string, Record<string, string>> = {
     "search.placeholder": "Suchbegriff eingeben...",
     "search.shortcutHint": "Suche von überall öffnen",
     "search.resultCount": "{count} Ergebnisse",
+    "search.unavailable": "Suche nicht verfügbar",
+    "search.loadingIndex": "Suchindex wird geladen…",
+    "search.noResults": "Keine Ergebnisse gefunden.",
     "code.copy": "Code kopieren",
     "code.copied": "Kopiert!",
     "code.wrapToggle": "Zeilenumbruch umschalten",

package/templates/base/src/config/settings-types.ts

@@ -1,181 +1,43 @@
-export interface HeaderNavChildItem {
-  label: string;
-  labelKey?: string;
-  path: string;
-  categoryMatch?: string;
-}
-
-export interface HeaderNavItem extends HeaderNavChildItem {
-  children?: HeaderNavChildItem[];
-}
-
-export type HeaderRightComponentName =
-  | "theme-toggle"
-  | "language-switcher"
-  | "version-switcher"
-  | "github-link"
-  | "search";
+// Re-export most types from the shared package — moved to @takazudo/zudo-doc/settings
+// as part of the package-first migration (epic #2321, S4 #2327).
+// HeaderRightTriggerName and HeaderRightTriggerItem are defined locally rather than
+// re-exported from the package because the designTokenPanel feature injects its
+// extra trigger-name variant into HeaderRightTriggerName via the @slot anchor; the
+// package unconditionally includes both trigger names but the base template
+// ships only "ai-chat", and the feature overlay adds the panel trigger variant
+// via the compose engine.  HeaderRightTriggerItem references the local
+// HeaderRightTriggerName, so it stays local too.
+export type {
+  TagGovernanceMode,
+  TagVocabularyEntry,
+  HeaderNavChildItem,
+  HeaderNavItem,
+  HeaderRightComponentName,
+  HeaderRightComponentItem,
+  HeaderRightLinkItem,
+  HeaderRightHtmlItem,
+  HeaderRightItem,
+  BodyFootUtilAreaConfig,
+  ColorModeConfig,
+  LocaleConfig,
+  FooterLinkItem,
+  FooterLinkColumn,
+  FooterTaglistLocaleConfig,
+  FooterTaglistConfig,
+  FooterConfig,
+  HtmlPreviewConfig,
+  FrontmatterPreviewConfig,
+  TagPlacement,
+  VersionConfig,
+  MetaTagsConfig,
+  Settings,
+} from "@takazudo/zudo-doc/settings";
 
 // @slot:settings-types:trigger-names:start
 export type HeaderRightTriggerName = "ai-chat";
 // @slot:settings-types:trigger-names:end
 
-export interface HeaderRightComponentItem {
-  type: "component";
-  component: HeaderRightComponentName;
-}
-
 export interface HeaderRightTriggerItem {
   type: "trigger";
   trigger: HeaderRightTriggerName;
 }
-
-export interface HeaderRightLinkItem {
-  type: "link";
-  href: string;
-  label?: string;
-  ariaLabel?: string;
-  icon?: "github";
-}
-
-export interface HeaderRightHtmlItem {
-  type: "html";
-  html: string;
-}
-
-export type HeaderRightItem =
-  | HeaderRightComponentItem
-  | HeaderRightTriggerItem
-  | HeaderRightLinkItem
-  | HeaderRightHtmlItem;
-
-export interface BodyFootUtilAreaConfig {
-  docHistory?: boolean;
-  viewSourceLink?: boolean;
-}
-
-export interface ColorModeConfig {
-  defaultMode: "light" | "dark";
-  lightScheme: string;
-  darkScheme: string;
-  respectPrefersColorScheme: boolean;
-}
-
-export interface LocaleConfig {
-  label: string;
-  dir: string;
-}
-
-export interface FooterLinkItem {
-  label: string;
-  href: string;
-  locales?: Record<string, { label: string }>;
-}
-
-export interface FooterLinkColumn {
-  title: string;
-  items: FooterLinkItem[];
-  locales?: Record<string, { title: string }>;
-}
-
-/**
- * Per-locale overrides for the footer taglist labels.
- *
- * `title`        — overrides `taglist.title` on this locale.
- * `groupTitles`  — per-group title overrides keyed by vocabulary `group`.
- */
-export interface FooterTaglistLocaleConfig {
-  title?: string;
-  groupTitles?: Record<string, string>;
-}
-
-/**
- * Opt-in footer tag index.
- *
- * Renders one or more columns of tag links inside the existing footer grid.
- * Off by default: when `enabled: false` (or the field is omitted entirely),
- * the footer renders unchanged.
- *
- * - `groupBy: "group"` — one column per vocabulary `group`, in the order the
- *   groups first appear in `tag-vocabulary.ts`. Each column's title comes from
- *   `groupTitles[group]`, falling back to a capitalised version of the group
- *   name.
- * - `groupBy: "flat"` — a single column titled `title` listing every tag
- *   alphabetically. This is also the fallback used when the vocabulary is
- *   inactive (`tagVocabulary: false` or `tagGovernance: "off"`).
- */
-export interface FooterTaglistConfig {
-  enabled: boolean;
-  /** Column title used in flat mode (and as fallback for ungrouped tags). */
-  title?: string;
-  /** Default `"group"` when the vocabulary is active, otherwise forced to `"flat"`. */
-  groupBy?: "group" | "flat";
-  /** English (default-locale) group titles, e.g. `{ type: "By type" }`. */
-  groupTitles?: Record<string, string>;
-  /** Locale-specific overrides for `title` and `groupTitles`. */
-  locales?: Record<string, FooterTaglistLocaleConfig>;
-}
-
-export interface FooterConfig {
-  links: FooterLinkColumn[];
-  /** Copyright text displayed at the bottom of the footer. HTML is supported. */
-  copyright?: string;
-  /** Opt-in footer tag index. Off by default. */
-  taglist?: FooterTaglistConfig;
-}
-
-export interface HtmlPreviewConfig {
-  /** Raw HTML injected into <head> (links, meta, fonts) */
-  head?: string;
-  /** CSS injected as <style> after preflight */
-  css?: string;
-  /** JS injected as <script> before </body> */
-  js?: string;
-}
-
-export interface FrontmatterPreviewConfig {
-  /**
-   * Completely replaces the default ignore list.
-   * When set, `extraIgnoreKeys` is ignored.
-   */
-  ignoreKeys?: string[];
-  /**
-   * Additional keys to ignore on top of the defaults.
-   * Has no effect when `ignoreKeys` is also set.
-   */
-  extraIgnoreKeys?: string[];
-}
-
-export type TagPlacement = "after-title" | "before-pager";
-
-export type { TagGovernanceMode, TagVocabularyEntry } from "./tag-vocabulary-types";
-
-export interface VersionConfig {
-  /** Version identifier, used in URL path (e.g., "1.0", "v1") */
-  slug: string;
-  /** Display label (e.g., "1.0.0", "Version 1") */
-  label: string;
-  /** Content directory for this version's English docs */
-  docsDir: string;
-  /** Per-locale content directories for this version */
-  locales?: Record<string, { dir: string }>;
-  /** Banner text shown on versioned pages (e.g., "unmaintained", "unreleased") */
-  banner?: "unmaintained" | "unreleased" | false;
-}
-
-export interface MetaTagsConfig {
-  /** Emit <meta name="description">. Default true. */
-  description: boolean;
-  /** Emit <meta name="keywords"> with a comma-separated string. false = omit. Default false. */
-  keywords: string | false;
-  /** og:image (and twitter:image) path. false = omit. Default false. Showcase: '/img/ogp.png'. */
-  ogImage: string | false;
-  /** Emit og:site_name. Default true (preserves current og:site_name). */
-  ogSiteName: boolean;
-  /** TwitterCard type. false = omit entire twitter:card block. Default false. Showcase: 'summary_large_image'. */
-  twitterCard: "summary" | "summary_large_image" | false;
-  /** twitter:site handle (e.g. '@yourbrand'). Optional. */
-  twitterSite?: string;
-  /** twitter:creator handle. Optional. */
-  twitterCreator?: string;
-}

package/templates/base/src/config/z-index-tokens.ts

@@ -1,10 +1,11 @@
 // z-index design tokens — single source of truth.
 //
 // This file is the ONE place z-index tiers are defined. The CSS `@theme` block
-// in `src/styles/global.css` is GENERATED from this list by
-// `scripts/gen-z-index.mjs` (run `pnpm gen:z-index`); never hand-edit the
-// generated block. `pnpm check:z-index` re-runs the generator into a buffer and
-// fails on drift, so the committed CSS can never silently diverge from this list.
+// in `src/styles/global.css` is GENERATED from this list by the
+// `gen-z-index` bin from `@takazudo/zudo-doc` (run `pnpm gen:z-index`); never
+// hand-edit the generated block. `pnpm check:z-index` re-runs the generator
+// into a buffer and fails on drift, so the committed CSS can never silently
+// diverge from this list.
 //
 // Strategy (from zudolab/zudo-css-wisdom z-index-strategy): semantic single-
 // namespace tokens — names describe ROLES, never magnitudes. One flat ordered