create-zudo-doc 0.1.0

package/templates/base/pages/lib/_math-block.tsx

@@ -0,0 +1,63 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// MathBlock — server-rendered KaTeX component for MDX math expressions.
+//
+// Registered in pages/_mdx-components.ts as `MathBlock` so the MDX corpus
+// can reference it as <MathBlock latex="…" block />.
+//
+// Used by the math-equations.mdx content files (both EN and JA) which write
+// `<MathBlock>` JSX directly instead of `$$…$$` fences. The explicit JSX
+// form is required because the zfb Rust MDX→JSX emitter does not understand
+// remark-math `$$…$$` syntax — LaTeX identifiers like `\infty` become invalid
+// JSX expressions `{\infty}` that esbuild rejects (zudo-front-builder #93).
+// Using `<MathBlock>` directly keeps the LaTeX inside a string attribute,
+// which esbuild accepts cleanly.
+//
+// Rendering: katex.renderToString() is called at SSR time — no client JS.
+// `throwOnError: false` keeps a broken formula visible as an error span
+// rather than crashing the page.
+
+import katex from "katex";
+import type { VNode } from "preact";
+
+interface MathBlockProps {
+  /** Raw LaTeX source string. */
+  latex: string;
+  /** When true, renders as a block (display) equation; otherwise inline. */
+  block?: boolean;
+}
+
+/**
+ * Server-rendered KaTeX math component.
+ *
+ * Block mode wraps the output in `<div class="math math-display">`;
+ * inline mode uses `<span class="math math-inline">`. The class names
+ * match the standard rehype-katex output so existing CSS (e.g. the
+ * KaTeX stylesheet) still applies.
+ */
+export function MathBlock({ latex, block = false }: MathBlockProps): VNode {
+  const html = katex.renderToString(latex, {
+    displayMode: block,
+    // Never throw — malformed LaTeX renders a visible error span instead
+    // of crashing the entire page build.
+    throwOnError: false,
+  });
+
+  if (block) {
+    return (
+      <div
+        class="math math-display"
+        // eslint-disable-next-line react/no-danger
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    );
+  }
+
+  return (
+    <span
+      class="math math-inline"
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  );
+}

package/templates/base/pages/lib/_nav-source-docs.ts

@@ -0,0 +1,68 @@
+// Shared helper — pick the right loadDocs() collection and category-meta dir
+// for the active (locale, version) pair, applying the locale-first + EN-fallback
+// merge that pages/[locale]/docs/[...slug].tsx uses in its own paths() pass so
+// the sidebar tree mirrors what those pages enumerate.
+//
+// Used by _sidebar-with-defaults.tsx (desktop sidebar) and
+// _header-with-defaults.tsx (mobile SidebarToggle) so both nav surfaces apply
+// the same defaultLocaleOnlyPrefixes filter and stay in sync.
+
+import { defaultLocale, type Locale } from "@/config/i18n";
+import { settings } from "@/config/settings";
+import { docsUrl, isDefaultLocaleOnlyPath } from "@/utils/base";
+import { loadCategoryMeta, type CategoryMeta } from "@/utils/docs";
+import type { DocsEntry } from "@/types/docs-entry";
+import { loadDocs } from "../_data";
+
+export type NavSourceDocs = {
+  docs: DocsEntry[];
+  categoryMeta: Map<string, CategoryMeta>;
+};
+
+/**
+ * Pick the right `loadDocs(...)` collection name and category-meta dir
+ * for the active (locale, version) pair, applying the same locale-first
+ * + EN-fallback merge that `pages/[locale]/docs/[...slug].tsx` performs
+ * in its own `paths()` so the sidebar tree mirrors what those pages
+ * enumerate.
+ */
+export function loadNavSourceDocs(
+  lang: Locale,
+  currentVersion: string | undefined,
+): NavSourceDocs {
+  if (currentVersion) {
+    const collectionName = `docs-v-${currentVersion}`;
+    const versionConfig = settings.versions?.find((v) => v.slug === currentVersion);
+    const docs = loadDocs(collectionName).filter((d) => !d.data.draft);
+    const categoryMeta = loadCategoryMeta(versionConfig?.docsDir ?? settings.docsDir);
+    return { docs, categoryMeta };
+  }
+
+  if (lang === defaultLocale) {
+    const docs = loadDocs("docs").filter((d) => !d.data.draft);
+    const categoryMeta = loadCategoryMeta(settings.docsDir);
+    return { docs, categoryMeta };
+  }
+
+  // Non-default locale: locale-first merge with EN fallback so docs the
+  // active locale has not yet translated still appear in the tree.
+  const localeDocs = loadDocs(`docs-${lang}`).filter((d) => !d.data.draft);
+  const baseDocs = loadDocs("docs").filter((d) => !d.data.draft);
+  const localeSlugSet = new Set(localeDocs.map((d) => d.data.slug ?? d.id));
+  const fallbackDocs = baseDocs
+    .filter((d) => !localeSlugSet.has(d.data.slug ?? d.id))
+    .filter((d) => !isDefaultLocaleOnlyPath(docsUrl(d.data.slug ?? d.id)));
+  const allDocs = [...localeDocs, ...fallbackDocs];
+
+  const localeDir =
+    (settings.locales as Record<string, { dir?: string }>)[lang]?.dir ??
+    settings.docsDir;
+  // Base meta first, locale meta wins on overlapping keys — same merge
+  // order [locale]/docs/[...slug].tsx uses in its paths() pass.
+  const categoryMeta = new Map<string, CategoryMeta>([
+    ...loadCategoryMeta(settings.docsDir),
+    ...loadCategoryMeta(localeDir),
+  ]);
+
+  return { docs: allDocs, categoryMeta };
+}

package/templates/base/pages/lib/_preset-generator.tsx

@@ -0,0 +1,81 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// SSR fallback shell for the <PresetGenerator> interactive form.
+//
+// The real component (src/components/preset-generator.tsx) is a large
+// client-only island. This file is imported transitively from page modules
+// (pages/docs/[...slug].tsx → _mdx-components.ts → here), so zfb's island
+// scanner walks the static import chain and registers PresetGenerator in the
+// manifest. Without this import, the scanner never finds the component and
+// client-side hydration never fires (orphan-component problem; same root
+// cause fixed for body-end islands in _body-end-islands.tsx).
+//
+// The fallback renders all 8 section headings as static SSR HTML so:
+//   1. Screen readers and search engines see the section structure (a11y/SEO).
+//   2. Layout does not collapse to nothing while JS loads (no-JS layout).
+//   3. The scanner traces this file → preset-generator.tsx via the Island child
+//      and registers PresetGenerator in the manifest for client-side mounting.
+//
+// Uses the canonical `<Island ssrFallback>` API (zfb) so the scanner can
+// connect the import to the manifest entry and the hydration runtime can
+// mount the real form into the skip-ssr placeholder on the client.
+
+import type { VNode } from "preact";
+import { HeadingH3 } from "@takazudo/zudo-doc/content";
+import { Island } from "@takazudo/zfb";
+import PresetGenerator from "@/components/preset-generator";
+
+// Pin displayName so zfb's captureComponentName produces a stable marker
+// name even after the SSR pipeline runs through a function-name-rewriting
+// layer. Matches the data-zfb-island-skip-ssr attribute value the runtime
+// queries. Mirrors the pattern in _body-end-islands.tsx.
+(PresetGenerator as { displayName?: string }).displayName = "PresetGenerator";
+
+// Heading text for each of the 8 sections — must match the original
+// SectionHeading calls in src/components/preset-generator.tsx exactly
+// so the SSR fallback and the real component render the same section labels.
+// Order must mirror the JSX source order in preset-generator.tsx — do NOT
+// sort alphabetically. The array drives the SSR fallback heading sequence
+// shown to screen readers and visible before JS hydration.
+const SECTION_HEADINGS = [
+  "Project Name",
+  "Default Language",
+  "Color Scheme Mode",
+  "Color Scheme",
+  "Features",
+  "Header right items",
+  "Markdown Options",
+  "Package Manager",
+] as const;
+
+/**
+ * Static SSR fallback for the interactive PresetGenerator form.
+ *
+ * Renders all 8 section headings as static HTML for a11y/SEO and no-JS
+ * layout stability. Uses Island with ssrFallback so the zfb scanner traces
+ * this file → preset-generator.tsx and registers the real component in the
+ * island manifest for client-side mounting.
+ */
+export function PresetGeneratorFallback(): VNode {
+  const fallback = (
+    <div class="zd-preset-gen-fallback">
+      {SECTION_HEADINGS.map((heading) => (
+        <section key={heading}>
+          <HeadingH3>{heading}</HeadingH3>
+        </section>
+      ))}
+    </div>
+  );
+
+  // Island with ssrFallback:
+  // - SSR emits the section headings as static HTML inside the skip-ssr div.
+  // - The scanner reads children.type = PresetGenerator → registers it in
+  //   the manifest under "PresetGenerator".
+  // - The hydration runtime mounts the real interactive form into the
+  //   skip-ssr placeholder on the client after load.
+  return Island({
+    when: "load",
+    ssrFallback: fallback,
+    children: <PresetGenerator />,
+  }) as unknown as VNode;
+}

package/templates/base/pages/lib/_search-widget-script.ts

@@ -0,0 +1,388 @@
+// Client-side script for the SiteSearch custom element.
+//
+// Port of the `<script>` block from the deleted
+// `src/components/search.astro` (commit a4d9956). Rewritten as a plain
+// JavaScript IIFE (no ES-module `import` statements) so it can be
+// emitted via `dangerouslySetInnerHTML` without requiring bundler
+// support for inline scripts.
+//
+// Differences from the original Astro script:
+//   - MiniSearch is NOT imported; a lightweight built-in search (fetch
+//     index + simple word-match scoring) is used instead. This avoids the
+//     inline-script bundling limitation. Full MiniSearch integration can be
+//     added in a follow-up topic once the bundle pipeline is in place.
+//   - The post-navigation rebinder pulls its event name from
+//     `AFTER_NAVIGATE_EVENT` in
+//     `@takazudo/zudo-doc/transitions` (today: `zfb:after-swap`)
+//     rather than a hard-coded `astro:*` literal. See
+//     zudolab/zudo-doc#1335 (E2 task 2 half B) for the vocabulary
+//     introduction and zudolab/zudo-doc#1523 for the W6B flip from
+//     `DOMContentLoaded` to the Strategy B SPA event name.
+
+import { AFTER_NAVIGATE_EVENT } from "@takazudo/zudo-doc/transitions";
+
+export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
+  if (customElements.get("site-search")) return; // guard double-registration
+
+  var PAGE_SIZE = 10;
+
+  function escapeHtml(text) {
+    return String(text)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;");
+  }
+
+  function escapeRegExp(text) {
+    return text.replace(/[.*+?^\${}()|[\\]\\\\]/g, "\\\\$&");
+  }
+
+  function parseTerms(query) {
+    return query.trim().split(/\\s+/).filter(Boolean);
+  }
+
+  function scoreEntry(entry, terms) {
+    var score = 0;
+    var titleLower = (entry.title || "").toLowerCase();
+    var bodyLower = (entry.body || "").toLowerCase();
+    var descLower = (entry.description || "").toLowerCase();
+    for (var i = 0; i < terms.length; i++) {
+      var t = terms[i].toLowerCase();
+      if (titleLower.indexOf(t) !== -1) score += 3;
+      if (descLower.indexOf(t) !== -1) score += 2;
+      if (bodyLower.indexOf(t) !== -1) score += 1;
+    }
+    return score;
+  }
+
+  function highlightTerms(text, terms) {
+    if (!terms.length) return escapeHtml(text);
+    var escaped = terms.map(function(t) { return escapeRegExp(t); });
+    var pattern = new RegExp("(" + escaped.join("|") + ")", "gi");
+    return text.split(pattern).map(function(seg, i) {
+      return i % 2 === 1
+        ? "<mark>" + escapeHtml(seg) + "</mark>"
+        : escapeHtml(seg);
+    }).join("");
+  }
+
+  function truncate(text, query, max) {
+    max = max || 200;
+    if (text.length <= max) return text;
+    var terms = parseTerms(query);
+    var lower = text.toLowerCase();
+    var best = -1;
+    for (var i = 0; i < terms.length; i++) {
+      var idx = lower.indexOf(terms[i].toLowerCase());
+      if (idx !== -1 && (best === -1 || idx < best)) best = idx;
+    }
+    if (best === -1) return text.slice(0, max) + "\\u2026";
+    var half = Math.floor(max / 2);
+    var start = Math.max(0, best - half);
+    var end = start + max;
+    if (end > text.length) { end = text.length; start = Math.max(0, end - max); }
+    var result = text.slice(start, end);
+    if (start > 0) result = "\\u2026" + result;
+    if (end < text.length) result += "\\u2026";
+    return result;
+  }
+
+  customElements.define("site-search", class SiteSearch extends HTMLElement {
+    constructor() {
+      super();
+      this._dialog = null;
+      this._openBtn = null;
+      this._closeBtn = null;
+      this._input = null;
+      this._results = null;
+      this._countWide = null;
+      this._countNarrow = null;
+      this._entries = null;
+      this._loading = false;
+      this._debounce = null;
+      this._currentQuery = "";
+      this._allResults = [];
+      this._shownCount = 0;
+      this._shortcut = "";
+      this._resultCountTemplate = "";
+      this._keydownHandler = null;
+      this._observer = null;
+      this._sentinel = null;
+      this._isLoadingBatch = false;
+      // Snapshot of the initial results-area HTML (includes SSR placeholder).
+      // Captured in connectedCallback so we can restore it on input-clear
+      // without re-querying the DOM (the placeholder node is replaced once
+      // search results are rendered).
+      this._placeholderHtml = "";
+      // Held so we can remove the document-level after-navigate listener
+      // in disconnectedCallback. zudolab/zudo-doc#1523 — under Strategy B
+      // SPA navigation a non-persisted <site-search> element would leak
+      // one document listener per nav without this hook.
+      this._afterNavHandler = null;
+    }
+
+    connectedCallback() {
+      this._dialog = this.querySelector("[data-search-dialog]");
+      this._openBtn = this.querySelector("[data-open-search]");
+      this._closeBtn = this.querySelector("[data-close-search]");
+      this._input = this.querySelector("[data-search-input]");
+      this._results = this.querySelector("[data-search-results]");
+      this._countWide = this.querySelector("[data-search-count]");
+      this._countNarrow = this.querySelector("[data-search-count-narrow]");
+      this._resultCountTemplate = this.dataset.resultCountTemplate || "{count} results";
+      // Snapshot the placeholder HTML before any search renders overwrite it.
+      this._placeholderHtml = this._results ? this._results.innerHTML : "";
+
+      // Platform keyboard-shortcut label — injected into [data-kbd-shortcut]
+      var nav = navigator;
+      var isMac = /Mac|iPhone|iPad|iPod/.test(
+        (nav.userAgentData && nav.userAgentData.platform) || nav.userAgent
+      );
+      this._shortcut = isMac ? "\\u2318K" : "Ctrl+K";
+      var kbdEl = this.querySelector("[data-kbd-shortcut]");
+      if (kbdEl) kbdEl.textContent = this._shortcut;
+
+      // Wire open/close handlers
+      var self = this;
+      if (this._openBtn) {
+        this._openBtn.addEventListener("click", function() { self.openDialog(); });
+      }
+      if (this._closeBtn) {
+        this._closeBtn.addEventListener("click", function() { self.closeDialog(); });
+      }
+      if (this._dialog) {
+        this._dialog.addEventListener("close", function() {
+          document.documentElement.style.overflow = "";
+        });
+        this._dialog.addEventListener("click", function(e) {
+          if (e.target === self._dialog) self.closeDialog();
+        });
+      }
+      if (this._input) {
+        this._input.addEventListener("input", function() { self.handleInput(); });
+      }
+
+      // Global keyboard shortcut (⌘K / Ctrl+K to open)
+      this._keydownHandler = function(e) {
+        if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+          e.preventDefault();
+          self.openDialog();
+        }
+      };
+      document.addEventListener("keydown", this._keydownHandler);
+
+      // View-Transitions compat: re-run on the v2 after-navigate event.
+      // Stored on the instance so disconnectedCallback can detach it on
+      // body swap when this element is NOT persisted via
+      // data-zfb-transition-persist (zudolab/zudo-doc#1523).
+      this._afterNavHandler = function() {
+        var kbdEl2 = self.querySelector("[data-kbd-shortcut]");
+        if (kbdEl2) kbdEl2.textContent = self._shortcut;
+      };
+      document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)}, this._afterNavHandler);
+    }
+
+    disconnectedCallback() {
+      if (this._keydownHandler) {
+        document.removeEventListener("keydown", this._keydownHandler);
+        this._keydownHandler = null;
+      }
+      if (this._afterNavHandler) {
+        document.removeEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)}, this._afterNavHandler);
+        this._afterNavHandler = null;
+      }
+      this.teardownSentinel();
+    }
+
+    openDialog() {
+      if (!this._dialog) return;
+      document.documentElement.style.overflow = "hidden";
+      this._dialog.showModal();
+      if (this._input) {
+        this._input.focus();
+        this._input.select();
+      }
+      if (!this._entries && !this._loading) {
+        this.loadIndex();
+      }
+    }
+
+    closeDialog() {
+      if (!this._dialog) return;
+      this._dialog.close();
+      document.documentElement.style.overflow = "";
+    }
+
+    handleInput() {
+      var self = this;
+      if (this._debounce) clearTimeout(this._debounce);
+      this._debounce = setTimeout(function() { self.search(); }, 150);
+    }
+
+    loadIndex() {
+      if (this._loading) return;
+      this._loading = true;
+      var self = this;
+      var base = this.dataset.base || "/";
+      fetch(base + "search-index.json")
+        .then(function(r) {
+          if (!r.ok) throw new Error("HTTP " + r.status);
+          return r.json();
+        })
+        .then(function(data) {
+          self._entries = Array.isArray(data) ? data : (data.entries || []);
+          self._loading = false;
+          // If user already typed, search now
+          if (self._input && self._input.value.trim()) {
+            self.search();
+          }
+        })
+        .catch(function() {
+          self._loading = false;
+          // Index unavailable — silently degrade
+        });
+    }
+
+    search() {
+      var query = this._input ? this._input.value.trim() : "";
+      this._currentQuery = query;
+
+      if (!query) {
+        this.teardownSentinel();
+        this._allResults = [];
+        this._shownCount = 0;
+        if (this._results) this._results.innerHTML = this.placeholderHtml();
+        this.updateCount();
+        return;
+      }
+
+      if (!this._entries) {
+        if (this._results) {
+          this._results.innerHTML = "<p class=\\"text-small text-muted\\">Loading search index\\u2026</p>";
+        }
+        if (!this._loading) this.loadIndex();
+        return;
+      }
+
+      var terms = parseTerms(query);
+      var scored = [];
+      for (var i = 0; i < this._entries.length; i++) {
+        var s = scoreEntry(this._entries[i], terms);
+        if (s > 0) scored.push({ entry: this._entries[i], score: s });
+      }
+      scored.sort(function(a, b) { return b.score - a.score; });
+      this._allResults = scored;
+      this._shownCount = 0;
+      this.teardownSentinel();
+      this.updateCount();
+
+      if (!scored.length) {
+        if (this._results) {
+          this._results.innerHTML = "<p class=\\"text-small text-muted\\">No results found.</p>";
+        }
+        return;
+      }
+
+      if (this._results) this._results.innerHTML = "";
+      this.loadMore();
+      if (this._shownCount < this._allResults.length) {
+        this.setupSentinel();
+      }
+    }
+
+    loadMore() {
+      if (this._isLoadingBatch) return;
+      if (this._shownCount >= this._allResults.length) return;
+      this._isLoadingBatch = true;
+      try {
+        var batch = this._allResults.slice(this._shownCount, this._shownCount + PAGE_SIZE);
+        var self = this;
+        for (var i = 0; i < batch.length; i++) {
+          var article = self.renderResult(batch[i].entry);
+          if (self._sentinel && self._sentinel.parentNode === self._results) {
+            self._results.insertBefore(article, self._sentinel);
+          } else if (self._results) {
+            self._results.appendChild(article);
+          }
+        }
+        this._shownCount += batch.length;
+        if (this._shownCount >= this._allResults.length) {
+          this.teardownSentinel();
+        }
+      } finally {
+        this._isLoadingBatch = false;
+      }
+    }
+
+    setupSentinel() {
+      this.teardownSentinel();
+      if (!this._results) return;
+      var sentinel = document.createElement("div");
+      sentinel.setAttribute("data-search-sentinel", "");
+      sentinel.setAttribute("aria-hidden", "true");
+      sentinel.style.height = "1px";
+      sentinel.style.width = "100%";
+      this._results.appendChild(sentinel);
+      this._sentinel = sentinel;
+      var self = this;
+      this._observer = new IntersectionObserver(function(entries) {
+        for (var i = 0; i < entries.length; i++) {
+          if (entries[i].isIntersecting) self.loadMore();
+        }
+      }, { root: this._results, rootMargin: "200px 0px" });
+      this._observer.observe(sentinel);
+    }
+
+    teardownSentinel() {
+      if (this._observer) { this._observer.disconnect(); this._observer = null; }
+      if (this._sentinel) { this._sentinel.remove(); this._sentinel = null; }
+    }
+
+    updateCount() {
+      var count = this._allResults.length;
+      var template = this._resultCountTemplate;
+      var text = count > 0 ? template.replace("{count}", String(count)) : "";
+      var show = !!text;
+      if (this._countWide) {
+        this._countWide.textContent = text;
+        this._countWide.classList.toggle("hidden", !show);
+      }
+      if (this._countNarrow) {
+        this._countNarrow.textContent = text;
+        this._countNarrow.classList.toggle("hidden", !show);
+      }
+    }
+
+    placeholderHtml() {
+      return this._placeholderHtml;
+    }
+
+    renderResult(entry) {
+      var article = document.createElement("article");
+      article.className = "-mx-hsp-lg border-b border-muted";
+      var link = document.createElement("a");
+      link.href = entry.url || "#";
+      link.className =
+        "group block px-hsp-lg py-vsp-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent";
+      var title = document.createElement("span");
+      title.className =
+        "font-semibold text-fg group-hover:text-accent group-hover:underline group-focus-visible:underline";
+      var terms = parseTerms(this._currentQuery);
+      title.innerHTML = highlightTerms(entry.title || "", terms);
+      link.appendChild(title);
+      var text = entry.description || entry.body;
+      if (text) {
+        var excerpt = document.createElement("p");
+        excerpt.className =
+          "mt-vsp-2xs text-caption text-muted leading-relaxed group-hover:underline group-focus-visible:underline decoration-muted";
+        var truncated = truncate(text, this._currentQuery, 200);
+        excerpt.innerHTML = highlightTerms(truncated, terms);
+        link.appendChild(excerpt);
+      }
+      article.appendChild(link);
+      return article;
+    }
+  });
+})();`;