create-zudo-doc 0.1.0

package/templates/base/pages/lib/_search-widget.tsx

@@ -0,0 +1,196 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// SSR-friendly search widget for the zfb host header.
+//
+// Mirrors the Astro baseline `src/components/search.astro` (deleted in
+// commit a4d9956) for the zfb host pages. The key SSR requirement is that
+// the placeholder text ("Type to search..." / 「検索したい単語を入力」) and
+// the keyboard-shortcut hint ("to open search from anywhere" /
+// 「いつでも検索バーを開ける」) appear in the static HTML so no-JS users
+// and crawlers can see them.
+//
+// Architecture:
+//   - Pure SSR markup for the dialog structure + placeholder text.
+//   - A `<site-search>` custom element wraps everything; the inline script
+//     at the bottom of this module registers the element and handles:
+//       * Dialog open / close (button click, backdrop click, Escape key)
+//       * Platform keyboard-shortcut label (⌘K / Ctrl+K) written into
+//         `[data-kbd-shortcut]` on first `connectedCallback`
+//       * Search-index loading + MiniSearch query dispatch (lazy-loaded
+//         after the user types the first character)
+//   - Locale-aware strings are passed as props from the caller so the
+//     Japanese placeholder / shortcut-hint copy appears in JA-locale SSR
+//     without JS execution.
+//
+// Coordination note: this file is inserted into the header via
+// `_header-with-defaults.tsx`'s `search` slot prop. It is self-contained
+// so B-10-2 (version-switcher) can touch the header file without conflict.
+
+import type { JSX } from "preact";
+import { withBase } from "@/utils/base";
+import { SEARCH_WIDGET_SCRIPT } from "./_search-widget-script.js";
+
+export interface SearchWidgetProps {
+  /** Locale-aware placeholder: "Type to search..." / 「検索したい単語を入力」 */
+  placeholderText: string;
+  /** Locale-aware shortcut hint: "to open search from anywhere" / 「いつでも検索バーを開ける」 */
+  shortcutHint: string;
+  /** Locale-aware result count template, e.g. "{count} results" */
+  resultCountTemplate: string;
+  /** Accessible label for the search trigger button */
+  searchLabel: string;
+}
+
+/**
+ * Search trigger button + dialog widget.
+ *
+ * Pure SSR — renders the full dialog markup including the placeholder text
+ * so static HTML contains the required copy even before JS runs.
+ * The `<site-search>` custom element registers itself via the inline script
+ * and activates interactive behaviour (open/close/keyboard shortcut/MiniSearch)
+ * only on the client.
+ */
+export function SearchWidget(props: SearchWidgetProps): JSX.Element {
+  const { placeholderText, shortcutHint, resultCountTemplate, searchLabel } = props;
+  const base = withBase("/");
+
+  return (
+    <>
+      {/* @ts-expect-error site-search is a custom element not in JSX intrinsics */}
+      <site-search
+        data-base={base}
+        data-result-count-template={resultCountTemplate}
+      >
+        {/* Header trigger button — search magnifier icon */}
+        <button
+          data-open-search
+          type="button"
+          class="flex items-center justify-center text-muted transition-colors hover:text-fg"
+          aria-label={searchLabel}
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="22"
+            height="22"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            aria-hidden="true"
+          >
+            <circle cx="11" cy="11" r="8" />
+            <path d="m21 21-4.3-4.3" />
+          </svg>
+        </button>
+
+        {/* Search dialog — rendered in SSR so the placeholder text is in
+            static HTML for no-JS users and crawlers. The browser treats
+            it as a closed <dialog> until the custom element calls
+            showModal(). */}
+        <dialog
+          data-search-dialog
+          class="m-0 h-full w-full max-w-none border-none bg-transparent p-0 backdrop:bg-overlay/60 sm:mx-auto sm:my-[10vh] sm:h-auto sm:max-h-[80vh] sm:max-w-[52rem] sm:rounded-lg"
+        >
+          <div class="flex h-full flex-col overflow-hidden bg-surface sm:rounded-lg sm:border sm:border-muted">
+            {/* ── Dialog header (input row) ─────────────────────────── */}
+            <div class="flex items-center gap-hsp-sm border-b border-muted px-hsp-lg py-vsp-sm">
+              {/* Small search icon inside the input area */}
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="16"
+                height="16"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                class="shrink-0 text-muted"
+                aria-hidden="true"
+              >
+                <circle cx="11" cy="11" r="8" />
+                <path d="m21 21-4.3-4.3" />
+              </svg>
+              <input
+                data-search-input
+                type="text"
+                placeholder={placeholderText}
+                class="w-full bg-transparent text-body text-fg outline-none placeholder:text-muted"
+                autocomplete="off"
+                spellcheck={false}
+              />
+              {/* Wide-viewport hit count (hidden until results arrive) */}
+              <span
+                data-search-count
+                class="hidden shrink-0 text-caption text-muted"
+                aria-live="polite"
+              />
+              <button
+                data-close-search
+                type="button"
+                class="shrink-0 text-muted hover:text-fg"
+                aria-label="Close search"
+              >
+                <svg
+                  xmlns="http://www.w3.org/2000/svg"
+                  width="20"
+                  height="20"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                >
+                  <path d="M18 6 6 18" />
+                  <path d="m6 6 12 12" />
+                </svg>
+              </button>
+            </div>
+
+            {/* Narrow-viewport hit count (below header, hidden on sm+) */}
+            <span
+              data-search-count-narrow
+              class="hidden border-b border-muted px-hsp-lg py-vsp-xs text-caption text-muted"
+              aria-live="polite"
+            />
+
+            {/* ── Results area ──────────────────────────────────────── */}
+            {/* aria-live="polite" so screen readers announce result changes */}
+            <div
+              class="flex-1 overflow-y-auto px-hsp-lg pb-vsp-md"
+              data-search-results
+              aria-live="polite"
+            >
+              {/* Placeholder text — always in SSR HTML so no-JS users and
+                  crawlers see the placeholderText and shortcutHint strings
+                  in the static page source. */}
+              <div class="text-small text-muted" data-search-placeholder>
+                <p>{placeholderText}</p>
+                <p class="mt-vsp-md text-caption">
+                  {/* data-kbd-shortcut is populated by the custom element on
+                      connectedCallback() with the platform shortcut string
+                      (⌘K on Mac, Ctrl+K elsewhere). Empty in SSR. */}
+                  <kbd
+                    class="rounded border border-muted bg-bg px-hsp-2xs py-[2px] font-mono text-caption"
+                    data-kbd-shortcut
+                  />{" "}
+                  {shortcutHint}
+                </p>
+              </div>
+            </div>
+          </div>
+        </dialog>
+      {/* @ts-expect-error closing custom element tag */}
+      </site-search>
+
+      {/* Inline script registers the SiteSearch custom element. Emitted once
+          per page — the browser deduplicates same-id custom elements
+          automatically; the `customElements.define` call below guards against
+          double-registration with the `!customElements.get(...)` check. */}
+      <script dangerouslySetInnerHTML={{ __html: SEARCH_WIDGET_SCRIPT }} />
+    </>
+  );
+}

package/templates/base/pages/lib/_sidebar-with-defaults.tsx

@@ -0,0 +1,176 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Locale-/version-aware Sidebar wrapper for the zfb doc pages.
+//
+// Mirrors the data-prep that lived in src/components/sidebar.astro
+// (deleted in commit a4d9956): build root-menu items from
+// settings.headerNav, load the locale's docs collection (with EN
+// fallback for non-default locales), build the nav tree for the active
+// section, optionally remap hrefs for versioned routes, and feed the
+// result into the host's <SidebarTree> Preact island.
+//
+// Why this wrapper exists: the data prep is host-only (it imports
+// @/config/* and @/utils/*), so it cannot live in the published v2
+// package. Without this wrapper the zfb doc pages fall through to a
+// <SidebarTree nodes={[]} /> default and the SSG output emits an empty
+// `<div data-zfb-island="SidebarTree" data-when="load"></div>` marker.
+
+import type { JSX } from "preact";
+// `<Island>` wraps `<SidebarTree>` directly here (rather than going through
+// the v2 `<Sidebar>` shell with `treeComponent`) so the zfb island bundle's
+// hydrate pass targets the actual stateful tree component. Mirrors the
+// mobile `<SidebarToggle>` shape in `pages/lib/_header-with-defaults.tsx`:
+// the hydration target owns its own data props directly so they ride the
+// SSR → hydrate boundary inside the Island marker's `data-props` attribute.
+//
+// Background: zfb's `Island.captureSerializableProps` runs `JSON.stringify`
+// on the wrapped component's own props bag, which silently drops function
+// values. With the previous `<Sidebar treeComponent={SidebarTree} ...>`
+// shape the `treeComponent` function was dropped during serialisation, so
+// at hydration the v2 Sidebar shell mounted with `treeComponent=undefined`,
+// returned `null`, and Preact's `hydrate(null, element)` left the SSR-
+// rendered tree DOM in place WITHOUT attaching the input's `onChange`
+// handler — typing into the filter input had no DOM effect.
+// zudolab/zudo-doc#1459 (Wave 1 #1445 wired the input but not the wiring
+// path; this wave routes the hydration target so the wiring actually
+// reaches the rendered tree).
+import { Island } from "@takazudo/zfb";
+import SidebarTree from "@/components/sidebar-tree";
+import { settings } from "@/config/settings";
+import { defaultLocale, locales, t, type Locale } from "@/config/i18n";
+import { buildLocaleLinks, navHref, versionedDocsUrl } from "@/utils/base";
+import {
+  isNavVisible,
+  type NavNode,
+} from "@/utils/docs";
+import { buildSidebarForSection } from "@/utils/sidebar";
+import { loadNavSourceDocs } from "./_nav-source-docs";
+
+export interface SidebarWithDefaultsProps {
+  /** Slug of the active doc page, used to highlight the current entry. */
+  currentSlug?: string;
+  /** Active locale; defaults to the configured defaultLocale. */
+  lang?: Locale;
+  /** Header-nav category matcher used to scope the tree (e.g. "guides"). */
+  navSection?: string;
+  /** Active version slug, when rendering inside `/v/{version}/...`. */
+  currentVersion?: string;
+  /**
+   * Current page URL path used to build the locale-switcher links shown in
+   * the mobile sidebar footer. The Astro template read this from
+   * `Astro.url.pathname`; in zfb the page module passes it explicitly.
+   */
+  currentPath?: string;
+}
+
+/**
+ * Walk the nav tree and rewrite each node's `href` to its versioned form.
+ *
+ * `buildNavTree` always emits hrefs via `docsUrl()`; when the active route
+ * lives under `/v/{version}/...` we need the same nodes pointing at the
+ * versioned URL so internal nav clicks stay inside the version. Skips
+ * nodes without an href (link-only or category placeholders).
+ */
+function remapVersionedHrefs(
+  nodes: NavNode[],
+  version: string,
+  nodeLang: Locale,
+): NavNode[] {
+  return nodes.map((node) => {
+    const children =
+      node.children.length > 0
+        ? remapVersionedHrefs(node.children, version, nodeLang)
+        : node.children;
+
+    if (!node.href || node.slug.startsWith("__link__")) {
+      return children !== node.children ? { ...node, children } : node;
+    }
+
+    const newHref = versionedDocsUrl(node.slug, version, nodeLang);
+    return { ...node, href: newHref, children };
+  });
+}
+
+/**
+ * Default-bearing host wrapper that performs the data prep the deleted
+ * `sidebar.astro` template did, then wraps the project's `<SidebarTree>`
+ * Preact island in `<Island when="load">` so the SSG output ships a
+ * populated `<div data-zfb-island="SidebarTree" data-when="load">…tree…
+ * </div>` marker for the hydration runtime to pick up.
+ *
+ * The v2 `<Sidebar>` shell is intentionally NOT used as the hydration
+ * target here. Its `treeComponent` prop is a function, and zfb's
+ * `Island.captureSerializableProps` drops function values during
+ * `JSON.stringify`, so a `<Sidebar treeComponent={SidebarTree} ...>`
+ * island would hydrate with `treeComponent=undefined` and the shell
+ * would return `null`, silently breaking the filter input's hydration
+ * (zudolab/zudo-doc#1459). Wrapping `<SidebarTree>` directly mirrors the
+ * mobile `<SidebarToggle>` shape (see `_header-with-defaults.tsx`) and
+ * keeps all data props serializable.
+ */
+export function SidebarWithDefaults(
+  props: SidebarWithDefaultsProps,
+): JSX.Element {
+  const {
+    currentSlug,
+    lang = defaultLocale,
+    navSection,
+    currentVersion,
+    currentPath = "",
+  } = props;
+
+  // Root-menu items derived from headerNav (mobile back-to-menu list).
+  // The Astro template fed labelKey through `t(...)` and computed hrefs
+  // with `navHref()`; mirror that exactly so the rendered list stays
+  // identical between the A and B sites.
+  const rootMenuItems = settings.headerNav.map((item) => ({
+    label: item.labelKey
+      ? t(item.labelKey as Parameters<typeof t>[0], lang)
+      : item.label,
+    href: navHref(item.path, lang, currentVersion),
+    children: item.children?.map((child) => ({
+      label: child.labelKey
+        ? t(child.labelKey as Parameters<typeof t>[0], lang)
+        : child.label,
+      href: navHref(child.path, lang, currentVersion),
+    })),
+  }));
+
+  const backToMenuLabel = navSection ? t("nav.backToMenu", lang) : undefined;
+
+  const { docs, categoryMeta } = loadNavSourceDocs(lang, currentVersion);
+  const navDocs = docs.filter(isNavVisible);
+  const rawNodes = buildSidebarForSection(navDocs, lang, navSection, categoryMeta);
+  const nodes = currentVersion
+    ? remapVersionedHrefs(rawNodes, currentVersion, lang)
+    : rawNodes;
+
+  // Locale-switcher links are only meaningful when more than one locale is
+  // configured — matches the Astro template's guard.
+  const localeLinks =
+    locales.length > 1 ? buildLocaleLinks(currentPath, lang) : undefined;
+
+  // Wrap <SidebarTree> directly in <Island when="load">. SSR emits the
+  // `data-zfb-island="SidebarTree"` marker around the rendered tree, with
+  // all data props serialised into `data-props` (every prop is plain data:
+  // arrays of objects + strings). At hydration the runtime finds the
+  // marker, looks up "SidebarTree" in the islands manifest (registered via
+  // the host's `"use client"` directive on `src/components/sidebar-tree.tsx`),
+  // and mounts the real component in-place — re-attaching the filter
+  // input's `onChange` handler to the existing SSR DOM.
+  return Island({
+    when: "load",
+    children: (
+      <SidebarTree
+        nodes={nodes}
+        currentSlug={currentSlug}
+        rootMenuItems={rootMenuItems}
+        backToMenuLabel={backToMenuLabel}
+        localeLinks={localeLinks}
+        themeDefaultMode={
+          settings.colorMode ? settings.colorMode.defaultMode : undefined
+        }
+      />
+    ),
+  }) as unknown as JSX.Element;
+}

package/templates/base/pages/lib/_site-tree-nav.tsx

@@ -0,0 +1,128 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Host-side MDX wrapper for <SiteTreeNav /> and <SiteTreeNavDemo />.
+//
+// The original Astro project had two files:
+//   - src/components/site-tree-nav.astro — interactive Preact island
+//   - src/components/site-tree-nav-demo.astro — Astro wrapper that loaded
+//     collection data and rendered the island
+//
+// Restored to use the interactive SiteTreeNav island (refs #1453):
+// Both <SiteTreeNav> and <SiteTreeNavDemo> MDX tags are mapped to this
+// wrapper which does the same data loading that site-tree-nav-demo.astro did:
+//
+//   1. Load the full docs collection for the active locale.
+//   2. Build nav tree via buildNavTree().
+//   3. Group satellite nodes via groupSatelliteNodes().
+//   4. Wrap the interactive SiteTreeNav in Island({when:"idle"}) so the MDX
+//      page gets the same collapsible grid the reference renders at
+//      /docs/components/site-tree-nav/ (refs #1453/#1442).
+//
+// All data access is synchronous (ADR-004 zfb content snapshot contract).
+// The `lang` prop is injected by createMdxComponents() in
+// pages/_mdx-components.ts so locale routes get locale-aware nav data.
+//
+// categoryIgnore defaults to ["inbox", "develop"] — same as the original index page
+// and site-tree-nav-demo.astro.
+
+import type { JSX } from "preact";
+import { Island } from "@takazudo/zfb";
+import SiteTreeNav from "@/components/site-tree-nav";
+import {
+  buildNavTree,
+  groupSatelliteNodes,
+  loadCategoryMeta,
+  isNavVisible,
+} from "@/utils/docs";
+import { settings } from "@/config/settings";
+import { defaultLocale, type Locale } from "@/config/i18n";
+import { isDefaultLocaleOnlyPath } from "@/utils/base";
+import { getCategoryOrder } from "@/utils/nav-scope";
+import { loadDocs } from "../_data";
+
+export interface SiteTreeNavWrapperProps {
+  /**
+   * Active locale. Injected via createMdxComponents() closure.
+   * Defaults to defaultLocale when not provided.
+   */
+  lang?: Locale | string;
+  /**
+   * Optional aria-label for the wrapping <nav> element.
+   * Forwarded to the v2 SiteTreeNavDemo component.
+   */
+  ariaLabel?: string;
+}
+
+/**
+ * Load merged docs + categoryMeta for the given locale.
+ * Matches the locale-merge strategy used by _category-nav.tsx.
+ */
+function loadNavSource(
+  locale: string,
+): { docs: ReturnType<typeof loadDocs>; categoryMeta: Map<string, import("@/utils/docs").CategoryMeta> } {
+  if (locale === defaultLocale) {
+    return {
+      docs: loadDocs("docs").filter((d) => !d.data.draft),
+      categoryMeta: loadCategoryMeta(settings.docsDir),
+    };
+  }
+
+  const localeDocs = loadDocs(`docs-${locale}`).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) => {
+      const slug = d.data.slug ?? d.id;
+      return !isDefaultLocaleOnlyPath(`/docs/${slug}/`);
+    });
+
+  const localeDir =
+    (settings.locales as Record<string, { dir?: string }>)[locale]?.dir ??
+    settings.docsDir;
+  const categoryMeta = new Map([
+    ...loadCategoryMeta(settings.docsDir),
+    ...loadCategoryMeta(localeDir),
+  ]);
+
+  return { docs: [...localeDocs, ...fallbackDocs], categoryMeta };
+}
+
+/**
+ * MDX wrapper shared by both <SiteTreeNav> and <SiteTreeNavDemo> tags.
+ *
+ * Builds the full site nav tree and renders it via the interactive SiteTreeNav
+ * island (wrapped in Island({when:"idle"})) — restoring byte-parity with the
+ * Astro reference at /docs/components/site-tree-nav/ (refs #1453/#1442).
+ *
+ * The island renders the collapsible multi-column grid the reference shows.
+ * SiteTreeNavDemo (static <details> list) is no longer used for MDX content.
+ *
+ * Returns null when the tree is empty after filtering.
+ */
+export function SiteTreeNavWrapper({
+  lang = defaultLocale,
+  ariaLabel,
+}: SiteTreeNavWrapperProps): JSX.Element | null {
+  const locale = lang as Locale;
+
+  const { docs, categoryMeta } = loadNavSource(locale);
+  const navDocs = docs.filter(isNavVisible);
+  const tree = buildNavTree(navDocs, locale, categoryMeta);
+  const categoryOrder = getCategoryOrder();
+  const groupedTree = groupSatelliteNodes(tree, categoryOrder);
+
+  if (groupedTree.length === 0) return null;
+
+  return Island({
+    when: "idle",
+    children: (
+      <SiteTreeNav
+        tree={groupedTree}
+        categoryOrder={categoryOrder}
+        categoryIgnore={["inbox", "develop"]}
+        ariaLabel={ariaLabel}
+      />
+    ),
+  }) as unknown as JSX.Element;
+}

package/templates/base/pages/lib/locale-merge.ts

@@ -0,0 +1,58 @@
+// Shared utility for merging locale docs with base-locale fallbacks.
+//
+// Used by the locale tag pages to replicate the locale-first + base-fallback
+// strategy from the Astro src/components/tag-nav.astro non-default-locale
+// branch. Extracted here to avoid duplicating the logic across multiple
+// [locale] page modules.
+//
+// Strategy:
+//   1. Load `docs-${locale}` collection.
+//   2. Load base "docs" collection.
+//   3. Merge: locale docs take priority; base docs fill in slugs not present
+//      in the locale collection.
+//   4. Filter out drafts and unlisted pages.
+//
+// This is a zfb-only module (uses synchronous getCollection from zfb/content).
+// Do not import from Astro page code.
+
+import { loadDocs } from "../_data";
+import type { DocsEntry } from "@/types/docs-entry";
+
+/**
+ * Merge locale docs with base-locale fallbacks.
+ *
+ * Locale docs take priority; base docs fill in slugs not covered by the
+ * locale collection. Drafts and unlisted docs are filtered out.
+ */
+export function mergeLocaleDocs(locale: string): DocsEntry[] {
+  // zfb's CollectionEntry uses `slug`/`collection` only; @/utils/docs
+  // utilities expect Astro-style `id` and `collection` fields. Map them
+  // here so the rest of this module (and its callers) get the
+  // DocsEntry-shaped objects they assume. Bridging on read keeps the
+  // schema discrepancy contained to the I/O boundary.
+  // Use `loadDocs` so the Astro-compat `id`/`collection` augmentation
+  // (and the `index` slug stripping) stays in one place — the inline
+  // `id: e.slug` map dropped the `/index` suffix that
+  // `buildNavTree`/`buildBreadcrumbs` etc. assume Astro 5 strips, which
+  // produced ambiguous-URL collisions at paths()-expansion time.
+  const localeDocs = loadDocs(`docs-${locale}`);
+  const baseDocs = loadDocs("docs");
+
+  const filteredLocale = localeDocs.filter(
+    (d) => !d.data.draft && !d.data.unlisted,
+  );
+  const filteredBase = baseDocs.filter(
+    (d) => !d.data.draft && !d.data.unlisted,
+  );
+
+  const localeSlugSet = new Set(
+    filteredLocale.map((d) => d.data.slug ?? d.id),
+  );
+
+  return [
+    ...filteredLocale,
+    ...filteredBase.filter(
+      (d) => !localeSlugSet.has(d.data.slug ?? d.id),
+    ),
+  ];
+}