create-zudo-doc 0.2.0 → 0.2.2

package/templates/base/src/components/sidebar-tree.tsx

@@ -7,7 +7,9 @@ import { useState, useCallback, useEffect, useMemo, useRef } from "preact/hooks"
 import type { NavNode } from "@/utils/docs";
 import type { LocaleLink } from "@/types/locale";
 import { INDENT, BASE_PAD, connectorLeft, ConnectorLines, CategoryLinkIcon } from "./tree-nav-shared";
-import ThemeToggle from "@/components/theme-toggle";
+// BARE ThemeToggle (#2012 E2) — this footer toggle renders inside the
+// SidebarToggle island, so it must NOT bring its own island wrapper.
+import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";
 import { smartBreakToHtml } from "@/utils/smart-break";
 
 function ToggleChevron({ isExpanded, className }: { isExpanded: boolean; className?: string }) {
@@ -61,7 +63,9 @@ function findActiveSlug(nodes: NavNode[], pathname: string): string | undefined
   for (const node of nodes) {
     if (node.href && normalizePath(node.href) === pathname) return node.slug;
     const found = findActiveSlug(node.children, pathname);
-    if (found) return found;
+    // "" is the canonical root-index slug (#1891) — a truthiness check
+    // would discard a legitimate root match.
+    if (found !== undefined) return found;
   }
   return undefined;
 }
@@ -246,8 +250,10 @@ export default function SidebarTree({ nodes, currentSlug, rootMenuItems, backToM
   }
 
   // Top page: show only header nav links, no doc tree or filter.
-  // Derived from activeSlug (runtime-synced) so it stays correct across View Transitions.
-  if (!activeSlug && rootMenuItems) {
+  // Derived from activeSlug (runtime-synced) so it stays correct across View
+  // Transitions. Must be an undefined check, not truthiness: "" is the
+  // canonical root-index doc slug (#1891) and gets the full tree.
+  if (activeSlug === undefined && rootMenuItems) {
     return (
       <nav>
         {rootMenuItems.map((item) => (
@@ -282,7 +288,7 @@ export default function SidebarTree({ nodes, currentSlug, rootMenuItems, backToM
             type="text"
             placeholder={filterPlaceholder}
             value={query}
-            onChange={(e) => setQuery(e.target.value)}
+            onChange={(e) => setQuery(e.currentTarget.value)}
             className="bg-transparent text-small outline-none w-full text-fg placeholder:text-muted"
           />
         </div>

package/templates/base/src/components/theme-toggle.tsx

@@ -1,107 +1,23 @@
 "use client";
 
-// Use preact hook entrypoints directly — the "react" → "preact/compat" alias
-// lets us consume React-typed components in this Preact app (configured
-// project-wide). Same pattern as packages/zudo-doc/src/theme/theme-toggle.tsx.
-import { useState, useEffect } from "preact/hooks";
-
-const STORAGE_KEY = "zudo-doc-theme";
-
-function SunIcon() {
-  return (
-    <svg
-      aria-hidden="true"
-      xmlns="http://www.w3.org/2000/svg"
-      width="20"
-      height="20"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <circle cx="12" cy="12" r="5" />
-      <line x1="12" y1="1" x2="12" y2="3" />
-      <line x1="12" y1="21" x2="12" y2="23" />
-      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
-      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
-      <line x1="1" y1="12" x2="3" y2="12" />
-      <line x1="21" y1="12" x2="23" y2="12" />
-      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
-      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
-    </svg>
-  );
-}
-
-function MoonIcon() {
-  return (
-    <svg
-      aria-hidden="true"
-      xmlns="http://www.w3.org/2000/svg"
-      width="20"
-      height="20"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
-    </svg>
-  );
-}
-
-interface ThemeToggleProps {
-  defaultMode?: "light" | "dark";
+// Scanner-visible ThemeToggle shim. zfb's island scanner does not register
+// "use client" modules located under node_modules (Takazudo/zudo-front-builder#999),
+// so importing the package ThemeToggle straight into the server-rendered header
+// emits an island marker with no matching registry entry — the toggle renders
+// but never hydrates, on every page (zudolab/zudo-doc#2048). This thin
+// project-source wrapper gives the scanner a local binding to register; it
+// re-wraps the bare (non-island-wrapped) package component unchanged.
+import type { JSX } from "preact";
+import {
+  ThemeToggle as ZudoDocThemeToggle,
+  type ThemeToggleProps,
+} from "@takazudo/zudo-doc/theme-toggle";
+
+export function ThemeToggle(props: ThemeToggleProps): JSX.Element {
+  return <ZudoDocThemeToggle {...props} />;
 }
+ThemeToggle.displayName = "ThemeToggle";
 
-export default function ThemeToggle({ defaultMode = "dark" }: ThemeToggleProps) {
-  // Initial state must match server render to avoid hydration mismatch.
-  // Actual theme is synced from DOM in useEffect below.
-  const [mode, setMode] = useState<"light" | "dark">(defaultMode);
-
-  useEffect(() => {
-    const actual =
-      (document.documentElement.getAttribute("data-theme") as
-        | "light"
-        | "dark") || defaultMode;
-    if (actual !== mode) {
-      setMode(actual);
-    }
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
-
-  function toggle() {
-    const next = mode === "dark" ? "light" : "dark";
-    setMode(next);
-    document.documentElement.setAttribute("data-theme", next);
-    document.documentElement.style.colorScheme = next;
-    localStorage.setItem(STORAGE_KEY, next);
-    // Clear both v1 and v2 tweak state so the new scheme's palette takes effect.
-    localStorage.removeItem("zudo-doc-tweak-state");
-    localStorage.removeItem("zudo-doc-tweak-state-v2");
-    window.dispatchEvent(new CustomEvent("color-scheme-changed"));
-  }
-
-  const nextMode = mode === "dark" ? "light" : "dark";
+export type { ThemeToggleProps };
 
-  return (
-    <button
-      onClick={toggle}
-      aria-label={`Switch to ${nextMode} mode`}
-      className="text-muted hover:text-fg transition-colors p-hsp-sm focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2"
-    >
-      {mode === "dark" ? <SunIcon /> : <MoonIcon />}
-    </button>
-  );
-}
-// Pin the island marker name to "ThemeToggle" regardless of esbuild's
-// identifier deduplication. Both this host component and the v2 package's
-// ThemeToggleInner share the plain name "ThemeToggle"; when both land in the
-// same SSR bundle esbuild renames one to "ThemeToggle2", making
-// captureComponentName() emit "ThemeToggle2" — a name that has no entry in
-// the island manifest. Setting displayName explicitly ensures Island() reads
-// the attribute-level name (displayName is preferred over .name) and emits
-// the correct data-zfb-island="ThemeToggle" marker. zudolab/zudo-doc#1446.
-ThemeToggle.displayName = "ThemeToggle";
+export default ThemeToggle;

package/templates/base/src/config/color-schemes.ts

@@ -11,6 +11,10 @@ export interface ColorScheme {
     string, string, string, string, string, string, string, string,
     string, string, string, string, string, string, string, string,
   ];
+  /** Optional Shiki theme for the zdtp panel's client-side code-block preview.
+   *  Falls back to the panel config's DEFAULT_SHIKI_THEME when omitted.
+   *  Static highlighting (syntect via zfb's Rust pipeline) is unaffected. */
+  shikiTheme?: string;
   /** Optional semantic overrides — when omitted, defaults are used:
    *  surface=p0, muted=p8, accent=p5, accentHover=p14
    *  codeBg=p10, codeFg=p11, success=p2, danger=p1, warning=p3, info=p4

package/templates/base/src/config/docs-schema.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { settings } from "./settings";
+import { tagVocabulary } from "./tag-vocabulary";
+
+// ---------------------------------------------------------------------------
+// Tags schema builder — governance-aware.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the `tags` schema based on governance mode. `"strict"` tightens to a
+ * `z.enum` of every canonical id plus every alias (content still uses
+ * aliases verbatim — resolution happens at the aggregation layer, after
+ * parsing).
+ */
+function buildTagsSchema() {
+  const vocabularyActive =
+    settings.tagVocabulary && settings.tagGovernance === "strict";
+  if (!vocabularyActive) return z.array(z.string()).optional();
+  const allowed = new Set<string>();
+  for (const entry of tagVocabulary) {
+    allowed.add(entry.id);
+    for (const alias of entry.aliases ?? []) allowed.add(alias);
+  }
+  const allowedList = [...allowed];
+  if (allowedList.length === 0) return z.array(z.string()).optional();
+  const [first, ...rest] = allowedList;
+  return z
+    .array(z.enum([first, ...rest] as [string, ...string[]]))
+    .optional();
+}
+
+// ---------------------------------------------------------------------------
+// Schema builder — single source of truth for the docs frontmatter shape.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the docs frontmatter zod schema.
+ *
+ * Returns a single `z.object(...).passthrough()` that is 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 a restricted `z.enum`
+ * when `tagGovernance: "strict"` + `tagVocabulary` is configured.
+ *
+ * `.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 function buildDocsSchema() {
+  return z
+    .object({
+      title: z.string(),
+      description: z.string().optional(),
+      category: z.string().optional(),
+      sidebar_position: z.number().optional(),
+      sidebar_label: z.string().optional(),
+      tags: buildTagsSchema(),
+      search_exclude: z.boolean().optional(),
+      pagination_next: z.string().nullable().optional(),
+      pagination_prev: z.string().nullable().optional(),
+      draft: z.boolean().optional(),
+      unlisted: z.boolean().optional(),
+      hide_sidebar: z.boolean().optional(),
+      hide_toc: z.boolean().optional(),
+      doc_history: z.boolean().optional(),
+      standalone: z.boolean().optional(),
+      slug: z.string().optional(),
+      generated: z.boolean().optional(),
+      // Category metadata expressed as a directory index.mdx's frontmatter — the
+      // frontmatter form of `_category_.json`. `category_no_page` makes the index
+      // a non-linked sidebar header excluded from routes/sitemap/search;
+      // `category_sort_order` sets the child sort direction. Frontmatter wins
+      // over the sidecar.
+      category_no_page: z.boolean().optional(),
+      category_sort_order: z.enum(["asc", "desc"]).optional(),
+    })
+    .passthrough();
+}
+
+// ---------------------------------------------------------------------------
+// Inferred type — single source of truth for the docs data shape.
+// ---------------------------------------------------------------------------
+
+/**
+ * TypeScript type inferred from the docs frontmatter zod schema.
+ *
+ * Import this type instead of hand-writing the field list in `pages/_data.ts`
+ * (`ZfbDocsData`) or `src/types/docs-entry.ts` (`DocsEntry.data`).
+ *
+ * The `[key: string]: unknown` index signature from `.passthrough()` is
+ * naturally present via `z.infer` — custom frontmatter keys remain accessible
+ * downstream (e.g. frontmatter-preview) without extra casting.
+ */
+export type DocsData = z.infer<ReturnType<typeof buildDocsSchema>>;

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

@@ -1,4 +1,5 @@
 import { settings } from "./settings";
+import type { LocaleConfig } from "./settings-types";
 
 // Collection name string used by zfb's content engine (`getCollection(...)`).
 // Kept as a structural string-literal alias so callers don't have to redeclare
@@ -15,9 +16,9 @@ export const locales = [
 ] as const;
 export type Locale = (typeof locales)[number];
 
-/** Safely look up a locale in settings.locales. */
-function getLocaleConfig(locale: string) {
-  return settings.locales[locale];
+/** Safely look up a locale in settings.locales by string key. */
+export function getLocaleConfig(locale: string): LocaleConfig | undefined {
+  return (settings.locales as Record<string, LocaleConfig | undefined>)[locale];
 }
 
 /** Get the content directory for a locale. */
@@ -70,6 +71,8 @@ const translations: Record<string, Record<string, string>> = {
     "toc.title": "On this page",
     "docs.browseAll": "Browse all documentation sections.",
     "search.label": "Search",
+    "search.placeholder": "Type to search...",
+    "search.shortcutHint": "to open search from anywhere",
     "search.resultCount": "{count} results",
     "code.copy": "Copy code",
     "code.copied": "Copied!",
@@ -128,6 +131,8 @@ const translations: Record<string, Record<string, string>> = {
     "toc.title": "目次",
     "docs.browseAll": "すべてのドキュメントセクションを閲覧",
     "search.label": "検索",
+    "search.placeholder": "検索したい単語を入力",
+    "search.shortcutHint": "いつでも検索バーを開ける",
     "search.resultCount": "{count} 件",
     "code.copy": "コードをコピー",
     "code.copied": "コピーしました！",
@@ -186,6 +191,8 @@ const translations: Record<string, Record<string, string>> = {
     "toc.title": "Auf dieser Seite",
     "docs.browseAll": "Alle Dokumentationsabschnitte durchsuchen.",
     "search.label": "Suche",
+    "search.placeholder": "Suchbegriff eingeben...",
+    "search.shortcutHint": "Suche von überall öffnen",
     "search.resultCount": "{count} Ergebnisse",
     "code.copy": "Code kopieren",
     "code.copied": "Kopiert!",

package/templates/base/src/styles/global.css

@@ -1002,6 +1002,20 @@ pre[class^="syntect-"] .line .highlighted-word {
   html[data-sidebar-hidden] .zd-sidebar-content-wrapper {
     margin-left: 0;
   }
+
+  /* When hidden via the toggle, narrow the content band to the
+   * hide_sidebar frontmatter width so it centers (the flex parent already
+   * applies justify-content: center) instead of leaving a dead gap where
+   * the sidebar was. 80rem must match the `max-w-[80rem]` hide_sidebar
+   * branch in doc-layout.tsx. These rules are unlayered, so they win over
+   * the Tailwind `max-w-[clamp(...)]` utility (utilities layer). (#2002) */
+  .zd-doc-content-band {
+    transition: max-width 200ms ease-in-out;
+  }
+
+  html[data-sidebar-hidden] .zd-doc-content-band {
+    max-width: 80rem;
+  }
 }
 
 /* Sidebar toggle button — left position uses CSS variable, needs global rule */

package/templates/base/src/types/docs-entry.ts

@@ -1,3 +1,5 @@
+import type { DocsData } from "@/config/docs-schema";
+
 /**
  * Concrete entry type for docs collections.
  *
@@ -6,6 +8,9 @@
  * but is defined locally now that the project runs on the zfb content
  * engine — collection-name-specific generics are not exposed by zfb, so
  * pages cast collection entries to this shape via `pages/_data.ts`.
+ *
+ * `data` is typed as `DocsData` — the `z.infer`-derived type from
+ * `src/config/docs-schema.ts` — so the field set is maintained in one place.
  */
 // Structural shape of zfb's optional rendered-content payload for a doc
 // entry (kept loose to stay engine-agnostic — pages do not rely on the
@@ -13,34 +18,11 @@
 type RenderedContent = unknown;
 export interface DocsEntry {
   id: string;
+  /** zfb content engine slug (filename without `.md`/`.mdx`; used by toRouteSlug). */
+  slug: string;
   body?: string;
   collection: string;
-  data: {
-    title: string;
-    description?: string;
-    category?: string;
-    sidebar_position?: number;
-    sidebar_label?: string;
-    tags?: string[];
-    search_exclude?: boolean;
-    pagination_next?: string | null;
-    pagination_prev?: string | null;
-    draft?: boolean;
-    unlisted?: boolean;
-    hide_sidebar?: boolean;
-    hide_toc?: boolean;
-    doc_history?: boolean;
-    standalone?: boolean;
-    slug?: string;
-    generated?: boolean;
-    /** Category metadata on a directory's index.mdx (frontmatter form of
-     *  `_category_.json` `noPage`): non-linked sidebar header + excluded from
-     *  routes/sitemap/search. Frontmatter wins over the sidecar. */
-    category_no_page?: boolean;
-    /** Frontmatter form of `_category_.json` `sortOrder` — child sort
-     *  direction. Frontmatter wins over the sidecar. */
-    category_sort_order?: "asc" | "desc";
-  };
+  data: DocsData;
   rendered?: RenderedContent;
   filePath?: string;
 }

package/templates/base/src/utils/base.ts

@@ -37,8 +37,10 @@ export function withBase(path: string): string {
 /** Strip the base prefix from a URL pathname. */
 export function stripBase(path: string): string {
   if (normalizedBase === "") return path;
-  return path.startsWith(normalizedBase)
-    ? path.slice(normalizedBase.length) || "/"
+  // Require a segment boundary so base "/app" doesn't strip "/application/...".
+  if (path === normalizedBase) return "/";
+  return path.startsWith(`${normalizedBase}/`)
+    ? path.slice(normalizedBase.length)
     : path;
 }
 
@@ -55,7 +57,7 @@ export function absoluteUrl(pageUrl: string): string | undefined {
 }
 
 /** Build a docs URL for the given slug and lang. */
-export function docsUrl(slug: string, lang: Locale = defaultLocale): string {
+export function docsUrl(slug: string, lang: Locale | string = defaultLocale): string {
   const path = lang === defaultLocale ? `/docs/${slug}` : `/${lang}/docs/${slug}`;
   return withBase(path);
 }