create-zudo-doc 0.1.0

package/templates/base/pages/lib/_body-end-islands.tsx

@@ -0,0 +1,201 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Host-side body-end islands helper.
+//
+// Wave 8 (Path A — super-epic #1333 / child epic #1355) drops the local
+// SSR-skip wrapper functions in `@takazudo/zudo-doc/ssr-skip` and uses
+// zfb's native `<Island ssrFallback={...}>` API directly with the real
+// component constructors imported by the host.
+//
+// The previous indirection (page → wrapper → placeholder div) created an
+// orphan-component bug: the real components were `"use client"` modules
+// that no page module ever imported transitively, so zfb's island scanner
+// never walked page → real-component, the manifest never bound the marker
+// to the real constructor, and the bundle never contained the real
+// component body. PR #150 to zfb fixed the marker-name alignment but the
+// orphan problem stayed — see issue zudolab/zudo-doc#1355 Wave 7 report.
+//
+// This helper is the page → real-component import chain the scanner
+// needs. Each island below is composed with zfb's `<Island>` wrapper,
+// which emits `<div data-zfb-island-skip-ssr="<ComponentName>">…</div>`
+// at SSR (zfb's `captureComponentName` derives the marker from
+// `child.displayName ?? child.name`). Because the page imports this
+// file, and this file imports the real components, the scanner walks
+// page → helper → real component and registers the constructor under
+// the SSR marker name.
+//
+// Pattern mirrors `_header-with-defaults.tsx`: the JSX-shim widens
+// `Island`'s return type to `unknown`, so call-sites cast through
+// `as unknown as VNode` at the boundary.
+
+import type { VNode, JSX } from "preact";
+import { Island } from "@takazudo/zfb";
+import { settings } from "@/config/settings";
+
+import AiChatModal from "@/components/ai-chat-modal";
+import ClientRouterBootstrap from "@/components/client-router-bootstrap";
+import DesignTokenPanelBootstrap from "@/components/design-token-panel-bootstrap";
+import ImageEnlarge, { ImageEnlargeSsrFallback } from "@/components/image-enlarge";
+import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";
+
+// Set explicit `displayName` on each default-exported island so zfb's
+// `captureComponentName` produces a stable marker even after the SSR
+// pipeline runs the components through a function-name-rewriting layer.
+// The marker must match the third-arg literal that zfb's scanner records
+// for the same source-level identifier (zfb PR #150). esbuild preserves
+// function names by default, but the explicit assignment is a
+// belt-and-braces guard for production minification regressions.
+(AiChatModal as { displayName?: string }).displayName = "AiChatModal";
+(ClientRouterBootstrap as { displayName?: string }).displayName =
+  "ClientRouterBootstrap";
+(DesignTokenPanelBootstrap as { displayName?: string }).displayName =
+  "DesignTokenPanelBootstrap";
+(ImageEnlarge as { displayName?: string }).displayName = "ImageEnlarge";
+
+/**
+ * Default sr-only label rendered as the AiChatModal SSR fallback. This
+ * mirrors the body-label string the deleted `AiChatModalIsland` wrapper
+ * produced verbatim so assistive tech can discover the chat entrypoint
+ * in the static HTML before JS hydration. English-only for now — the
+ * previous default was also English-only; pass `aiChatBodyLabel` to
+ * localise.
+ */
+const DEFAULT_AI_CHAT_BODY_LABEL = "Ask a question about the documentation.";
+
+/**
+ * SSR-emitted inline script that acts as a pre-hydration shim for the
+ * `toggle-design-token-panel` window event. Because the
+ * DesignTokenPanelBootstrap Island is deferred, zdtp's real
+ * `toggle-design-token-panel` listener (registered in index.tsx at
+ * module init) is not yet installed when the user clicks the header
+ * palette button. This shim:
+ *
+ *  1. Records the first (and only meaningful) click as a boolean flag.
+ *  2. Exposes `window.__zdtpReadyClicks` so the bootstrap Island can
+ *     drain the queue and re-dispatch a single event once the real
+ *     listener is live.
+ *  3. Guards against double-installation across any re-evaluation path
+ *     (SPA body swap, HMR, etc.) via `__zdtpToggleShimInstalled`.
+ *
+ * A single boolean (not an array) is used because the panel is a toggle —
+ * any number of pre-hydration clicks should result in at most one open.
+ */
+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'));}
+};
+})();`;
+
+/** Props for {@link BodyEndIslands}. */
+export interface BodyEndIslandsProps {
+  /** Base path the AI chat modal uses to construct API URLs. */
+  basePath: string;
+  /**
+   * Sr-only label rendered as the AiChatModal SSR fallback. Defaults to
+   * the English string. Pass a locale-translated string for non-default
+   * locales so screen readers announce the chat entrypoint correctly
+   * before hydration.
+   */
+  aiChatBodyLabel?: string;
+}
+
+/**
+ * The three default body-end islands every doc page mounts: the
+ * design-token tweak panel (overlay, fixed-position), the AI chat
+ * modal (`<dialog>` overlay), and the image-enlarge dialog (mounted
+ * lazily based on viewport scan).
+ *
+ * Each island is wrapped in `<Island ssrFallback>` so the heavy
+ * component is NOT evaluated server-side — they depend on
+ * `dialog.showModal()`, `localStorage`, `ResizeObserver`, runtime
+ * fetch, etc. The hydration runtime swaps each placeholder on the
+ * client.
+ *
+ * The `<h2 class="sr-only">AI Assistant</h2>` heading is emitted in
+ * the SSG output so screen readers and crawlers can discover the chat
+ * section landmark before JS hydration.
+ */
+export function BodyEndIslands({
+  basePath,
+  aiChatBodyLabel = DEFAULT_AI_CHAT_BODY_LABEL,
+}: BodyEndIslandsProps): JSX.Element {
+  // Hydrates first (when="load") so the SPA-router click intercept is
+  // registered as soon as the islands runtime mounts the marker. The
+  // component renders nothing visually — the island bundle's top-level
+  // `import "@takazudo/zfb-runtime/client-router"` is what actually
+  // wires up the router (zudolab/zudo-doc#1524 W7A fix).
+  const clientRouterBootstrap = Island({
+    when: "load",
+    children: <ClientRouterBootstrap />,
+  }) as unknown as VNode;
+
+  // Hydrates on load so configurePanel() runs as early as possible and
+  // the `toggle-design-token-panel` window listener is registered before
+  // the user can click the header trigger. Renders nothing visually —
+  // the zdtp panel self-mounts as a side-effect (zudolab/zudo-doc#1623).
+  //
+  // The inline <script> emitted alongside the Island is the pre-hydration
+  // toggle shim (zudolab/zudo-doc#1627 Part B). It captures the first
+  // click as a boolean flag and exposes window.__zdtpReadyClicks so the
+  // bootstrap module can drain and re-dispatch once the real zdtp listener
+  // is registered. Mirrors the PageLoadingOverlay SSR-script pattern.
+  const designTokenPanelBootstrap =
+    settings.designTokenPanel || settings.colorTweakPanel
+      ? (
+          <>
+            <script
+              dangerouslySetInnerHTML={{ __html: ZDTP_TOGGLE_SHIM_SRC }}
+            />
+            {Island({
+              when: "load",
+              children: <DesignTokenPanelBootstrap />,
+            }) as unknown as VNode}
+          </>
+        )
+      : null;
+
+  // Use a visually-hidden paragraph as the AiChatModal SSR fallback so
+  // the body label is present in static HTML for screen readers before
+  // JS hydration. sr-only keeps it invisible to sighted users.
+  const aiChat = Island({
+    ssrFallback: <p class="sr-only">{aiChatBodyLabel}</p>,
+    children: <AiChatModal basePath={basePath} />,
+  }) as unknown as VNode;
+
+  // Wave 11 (zudolab/zudo-doc#1355): the SSR fallback is the empty,
+  // closed `<dialog class="zd-enlarge-dialog ...">` shell so the dist
+  // HTML carries one dialog from the start. Without this the smoke
+  // "exactly one zd-enlarge-dialog element" assertion sees zero
+  // (skip-ssr placeholders are empty divs) and the no-JS path has no
+  // dialog at all. Hydration replaces this shell with the real
+  // ImageEnlarge component when the page goes idle.
+  const imageEnlarge = Island({
+    when: "idle",
+    ssrFallback: <ImageEnlargeSsrFallback />,
+    children: <ImageEnlarge />,
+  }) as unknown as VNode;
+
+  return (
+    <>
+      {/* Pure SSR — no Island wrap. The component emits its overlay div,
+          inline styles, and a small inline script that self-wires
+          zfb:before-preparation / zfb:after-swap listeners at runtime. */}
+      <PageLoadingOverlay />
+      {clientRouterBootstrap}
+      {designTokenPanelBootstrap}
+      {/* Emits the "AI Assistant" heading in the SSG output so screen
+          readers can discover the chat section landmark before JS
+          hydration. */}
+      <h2 class="sr-only">AI Assistant</h2>
+      {aiChat}
+      {imageEnlarge}
+    </>
+  );
+}

package/templates/base/pages/lib/_category-nav.tsx

@@ -0,0 +1,148 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Host-side MDX wrapper for <CategoryNav category="..." />.
+//
+// Mirrors the data-resolution shape of src/components/category-nav.astro:
+//   1. Load docs for the active locale (or defaultLocale when not passed).
+//   2. Build the nav tree with buildNavTree().
+//   3. Find the target category node via findNode().
+//   4. Filter to children with hasPage === true.
+//   5. Forward the resolved children to the v2 CategoryNav component.
+//
+// All data access is synchronous (ADR-004 zfb content snapshot contract)
+// via loadDocs() from pages/_data.ts.
+//
+// The `lang` prop is injected by createMdxComponents() in
+// pages/_mdx-components.ts so locale routes get locale-aware nav data.
+
+import type { JSX } from "preact";
+import { CategoryNav as CategoryNavV2 } from "@takazudo/zudo-doc/nav-indexing";
+import type { NavNode as V2NavNode } from "@takazudo/zudo-doc/nav-indexing/types";
+import {
+  buildNavTree,
+  findNode,
+  loadCategoryMeta,
+  isNavVisible,
+} from "@/utils/docs";
+import { settings } from "@/config/settings";
+import { defaultLocale, type Locale } from "@/config/i18n";
+import { docsUrl } from "@/utils/base";
+import { loadDocs } from "../_data";
+
+export interface CategoryNavWrapperProps {
+  /**
+   * Slug of the category whose immediate children should be listed, e.g.
+   * "getting-started" or "guides/layout-demos".
+   */
+  category?: string;
+  /**
+   * Explicit list of top-level category slugs to render as cards. Use this
+   * when the target categories are not children of a single parent node in
+   * the nav tree (e.g. "claude-md", "claude-skills" are top-level siblings
+   * of "claude", not children). Each slug is resolved to its nav node; nodes
+   * not found in the tree are silently skipped.
+   *
+   * For nodes with noPage=true (no index.mdx), the href falls back to the
+   * auto-generated category index URL via docsUrl(slug, lang).
+   */
+  categories?: string[];
+  /**
+   * Active locale. Injected via createMdxComponents() closure.
+   * Defaults to defaultLocale when not provided.
+   */
+  lang?: Locale | string;
+  /** Optional extra CSS classes forwarded to the <nav> element. */
+  class?: string;
+}
+
+/**
+ * Load merged docs + categoryMeta for the given locale.
+ * Mirrors the locale-merge strategy from _header-with-defaults.tsx:
+ * default locale → "docs"; non-default → locale-first + EN fallback.
+ */
+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),
+    };
+  }
+
+  // Non-default locale: locale-first merge with EN fallback.
+  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),
+  );
+
+  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 for CategoryNav. Resolves nav tree data host-side and forwards
+ * the resolved category children into the v2 CategoryNav component.
+ *
+ * Supports two modes:
+ * - `category`: resolves immediate children of a single category node.
+ * - `categories`: resolves an explicit list of top-level slugs as cards.
+ *   Use this when the target categories are siblings in the nav tree rather
+ *   than children of a common parent (e.g. claude-md / claude-skills are
+ *   top-level peers of claude, not children of it). Nodes with noPage=true
+ *   get their href computed via docsUrl() since auto-index pages exist.
+ *
+ * Returns null when no visible children are resolved.
+ */
+export function CategoryNavWrapper({
+  category,
+  categories,
+  lang = defaultLocale,
+  class: className,
+}: CategoryNavWrapperProps): JSX.Element | null {
+  const locale = lang as Locale;
+
+  const { docs, categoryMeta } = loadNavSource(locale);
+  const navDocs = docs.filter(isNavVisible);
+  const tree = buildNavTree(navDocs, locale, categoryMeta);
+
+  let children: V2NavNode[];
+
+  if (categories !== undefined) {
+    // Explicit slug list mode: resolve each slug to its nav node and build
+    // a card for it. noPage nodes have no href in the tree but their
+    // auto-generated category index page is reachable via docsUrl().
+    children = categories
+      .map((slug): V2NavNode | null => {
+        const node = findNode(tree, slug);
+        if (!node) return null;
+        const href = node.href ?? docsUrl(slug, locale);
+        return {
+          label: node.label,
+          description: node.description,
+          href,
+          hasPage: true,
+          children: [],
+        };
+      })
+      .filter((n): n is V2NavNode => n !== null);
+  } else if (category !== undefined) {
+    const categoryNode = findNode(tree, category);
+    children = (categoryNode?.children.filter((c) => c.hasPage) ?? []) as V2NavNode[];
+  } else {
+    return null;
+  }
+
+  if (children.length === 0) return null;
+
+  return <CategoryNavV2 children={children} class={className} />;
+}

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

@@ -0,0 +1,104 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Host-side MDX wrapper for <CategoryTreeNav category="..." />.
+//
+// Mirrors the data-resolution shape of src/components/category-tree-nav.astro:
+//   1. Load docs for the active locale (defaultLocale when not passed).
+//   2. Build the full nav tree with buildNavTree() + groupSatelliteNodes()
+//      (category slug is passed as the grouping prefix list).
+//   3. Find the target category node via findNode().
+//   4. Filter to children with hasPage === true or children.length > 0.
+//   5. Forward the resolved children to the v2 CategoryTreeNav component.
+//
+// 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.
+
+import type { JSX } from "preact";
+import { CategoryTreeNav as CategoryTreeNavV2 } from "@takazudo/zudo-doc/nav-indexing";
+import {
+  buildNavTree,
+  groupSatelliteNodes,
+  findNode,
+  loadCategoryMeta,
+  isNavVisible,
+} from "@/utils/docs";
+import { settings } from "@/config/settings";
+import { defaultLocale, type Locale } from "@/config/i18n";
+import { loadDocs } from "../_data";
+
+export interface CategoryTreeNavWrapperProps {
+  /**
+   * Slug of the category whose children should be rendered as a tree,
+   * e.g. "guides" or "getting-started".
+   */
+  category: string;
+  /**
+   * Active locale. Injected via createMdxComponents() closure.
+   * Defaults to defaultLocale when not provided.
+   */
+  lang?: Locale | 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),
+  );
+
+  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 for CategoryTreeNav. Resolves nav tree data host-side and
+ * forwards the resolved category children into the v2 CategoryTreeNav
+ * component.
+ *
+ * Returns null when the category is not found or has no renderable children —
+ * matching the original Astro component's guard.
+ */
+export function CategoryTreeNavWrapper({
+  category,
+  lang = defaultLocale,
+}: CategoryTreeNavWrapperProps): JSX.Element | null {
+  const locale = lang as Locale;
+
+  const { docs, categoryMeta } = loadNavSource(locale);
+  const navDocs = docs.filter(isNavVisible);
+  const rawTree = buildNavTree(navDocs, locale, categoryMeta);
+  // groupSatelliteNodes with [category] groups satellite nodes under the
+  // target category — matching the original Astro component.
+  const tree = groupSatelliteNodes(rawTree, [category]);
+
+  const categoryNode = findNode(tree, category);
+  const children =
+    categoryNode?.children.filter((c) => c.hasPage || c.children.length > 0) ??
+    [];
+
+  if (children.length === 0) return null;
+
+  return <CategoryTreeNavV2 children={children} />;
+}

package/templates/base/pages/lib/_compose-meta-title.ts

@@ -0,0 +1,29 @@
+/**
+ * Compose the canonical "<title> | <siteName>" page-title shape used by
+ * both <title> (emitted by DocLayout) and og:title (emitted by
+ * HeadWithDefaults).
+ *
+ * Why this exists: the legacy Astro layout synthesised this suffix
+ * inline. The zfb DocLayout shell intentionally renders only what the
+ * host passes as `title`, so the host has to compose the suffix itself.
+ * Centralising the composition in one helper keeps every host call
+ * site in sync and matches the SEO/UX-recognised shape the original
+ * site shipped (also asserted by smoke-seo.spec.ts).
+ *
+ * Edge cases:
+ * - When `title` is identical to `settings.siteName` (e.g. the home
+ *   page already passes `settings.siteName` as the title), do NOT
+ *   duplicate — return just the bare site name. Mirrors the legacy
+ *   Astro behaviour.
+ * - When `siteName` is missing/empty (defensive — settings.ts always
+ *   has it in practice), fall back to the bare title.
+ *
+ */
+import { settings } from "@/config/settings";
+
+export function composeMetaTitle(title: string): string {
+  const siteName = settings.siteName;
+  if (!siteName) return title;
+  if (title === siteName) return siteName;
+  return `${title} | ${siteName}`;
+}

package/templates/base/pages/lib/_details.tsx

@@ -0,0 +1,30 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Host-side MDX wrapper for <Details> — trivial passthrough to the v2
+// Details component.
+//
+// The legacy src/components/details.astro used Astro's <slot /> for children;
+// v2's Details accepts standard Preact children. MDX passes slot content as
+// `children`, so the mapping is direct. The title prop (default "Details")
+// is forwarded unchanged.
+
+import type { ComponentChildren, VNode } from "preact";
+import { Details as DetailsV2 } from "@takazudo/zudo-doc/details";
+
+export interface DetailsWrapperProps {
+  /** Summary label shown in the <summary> element. Defaults to "Details". */
+  title?: string;
+  /** MDX slot content rendered inside the collapsed body. */
+  children?: ComponentChildren;
+}
+
+/**
+ * Passthrough wrapper for the v2 Details component.
+ *
+ * Used in pages/_mdx-components.ts as the Details binding so that MDX
+ * content using `<Details title="...">...</Details>` renders correctly
+ * on zfb routes.
+ */
+export function DetailsWrapper({ title, children }: DetailsWrapperProps): VNode {
+  return <DetailsV2 title={title}>{children}</DetailsV2>;
+}