create-zudo-doc 0.2.21 → 1.0.0

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

@@ -1,119 +1,34 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Host-side MDX wrapper for <CategoryNav category="..." />.
-//
-// Data-resolution steps performed before forwarding to the v2 CategoryNav component:
-//   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,
-  firstRoutedHref,
-} from "@/utils/docs";
-import { defaultLocale, type Locale } from "@/config/i18n";
+// Thin stub — category-nav moved to the package (epic #2344, S8).
+// Calls `createCategoryNavWrapper(deps)` from @takazudo/zudo-doc/category-nav
+// with host singletons injected, then re-exports the resulting component so
+// all existing call sites continue to work unchanged.
+
+import { createCategoryNavWrapper } from "@takazudo/zudo-doc/category-nav";
+import { buildNavTree, findNode, firstRoutedHref } from "@/utils/docs";
+import { defaultLocale } from "@/config/i18n";
 import { resolveNavSource } from "./_nav-source-docs";
 
-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.
-   *
-   * A `category_no_page` category has no route of its own, so its card links to
-   * the first routed descendant page (via firstRoutedHref); categories with no
-   * reachable page are skipped rather than emitting a dead link.
-   */
-  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;
-}
-
-/**
- * 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). A noPage category card
- *   links to its first routed descendant page (it has no route of its own).
- *
- * 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;
-
-  // No defaultLocaleOnly filter — category cards intentionally show all EN
-  // pages even if they match defaultLocaleOnlyPrefixes (the option signature in
-  // resolveNavSource keeps this variant from colliding with the sidebar's).
-  const { navDocs, categoryMeta } = resolveNavSource(locale, undefined, {
-    keepUnlisted: true,
-  });
-  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. A `category_no_page` category has no route of its own
-    // (collectAutoIndexNodes skips noPage nodes), so its card links to the
-    // first routed descendant page; categories with no reachable page are
-    // skipped rather than emitting a dead link.
-    children = categories
-      .map((slug): V2NavNode | null => {
-        const node = findNode(tree, slug);
-        if (!node) return null;
-        const href = node.href ?? firstRoutedHref(node);
-        if (!href) return null;
-        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} />;
-}
+export type { CategoryNavWrapperProps } from "@takazudo/zudo-doc/category-nav";
+
+export const CategoryNavWrapper = createCategoryNavWrapper({
+  defaultLocale,
+  resolveNavSource: resolveNavSource as (
+    lang: string,
+    currentVersion: string | undefined,
+    options?: { applyDefaultLocaleOnlyFilter?: boolean; keepUnlisted?: boolean },
+  ) => import("@takazudo/zudo-doc/category-nav").CategoryNavSource,
+  buildNavTree: buildNavTree as (
+    docs: unknown[],
+    locale: string,
+    categoryMeta: Map<string, unknown>,
+  ) => import("@takazudo/zudo-doc/category-nav").CategoryNavNode[],
+  findNode: findNode as (
+    tree: import("@takazudo/zudo-doc/category-nav").CategoryNavNode[],
+    slug: string,
+  ) => import("@takazudo/zudo-doc/category-nav").CategoryNavNode | undefined,
+  firstRoutedHref: firstRoutedHref as (
+    node: import("@takazudo/zudo-doc/category-nav").CategoryNavNode,
+  ) => string | undefined,
+});

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

@@ -1,72 +1,45 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Host-side MDX wrapper for <CategoryTreeNav category="..." />.
-//
-// Data-resolution steps performed before forwarding to the v2 CategoryTreeNav component:
-//   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.
+// Thin stub — category-tree-nav moved to the package (epic #2344, S8).
+// Calls `createCategoryTreeNavWrapper(deps)` from
+// @takazudo/zudo-doc/category-tree-nav with host singletons injected,
+// then re-exports the resulting component so all existing call sites continue
+// to work unchanged.
 
-import type { JSX } from "preact";
-import { CategoryTreeNav as CategoryTreeNavV2 } from "@takazudo/zudo-doc/nav-indexing";
-import {
-  buildNavTree,
-  groupSatelliteNodes,
-  findNode,
-} from "@/utils/docs";
+import { createCategoryTreeNavWrapper } from "@takazudo/zudo-doc/category-tree-nav";
+import type {
+  CategoryTreeNavNode,
+  CategoryTreeNavSource,
+} from "@takazudo/zudo-doc/category-tree-nav";
+import { buildNavTree, groupSatelliteNodes, findNode, type NavNode } from "@/utils/docs";
 import { defaultLocale, type Locale } from "@/config/i18n";
+import type { DocsEntry } from "@/types/docs-entry";
+import type { CategoryMeta } from "@/utils/docs";
 import { resolveNavSource } from "./_nav-source-docs";
 
-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;
-}
+export type { CategoryTreeNavWrapperProps } from "@takazudo/zudo-doc/category-tree-nav";
 
-/**
- * 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;
-
-  // No defaultLocaleOnly filter — tree nav intentionally shows all EN pages
-  // (same variant as _category-nav.tsx).
-  const { navDocs, categoryMeta } = resolveNavSource(locale, undefined, {
-    keepUnlisted: true,
-  });
-  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} />;
-}
+// The factory describes its injected nav helpers with the minimal
+// CategoryTreeNavNode view (no `slug` / `position`), while the host helpers are
+// typed against the full NavNode. At runtime the nodes are real NavNodes; the
+// wrappers re-view them as the minimal type at the injection boundary (cast via
+// `unknown` because NavNode is a structural supertype of CategoryTreeNavNode,
+// so a direct cast is rejected as non-overlapping).
+export const CategoryTreeNavWrapper = createCategoryTreeNavWrapper({
+  defaultLocale,
+  resolveNavSource: resolveNavSource as (
+    lang: string,
+    currentVersion: string | undefined,
+    options?: { applyDefaultLocaleOnlyFilter?: boolean; keepUnlisted?: boolean },
+  ) => CategoryTreeNavSource,
+  buildNavTree: (docs: unknown[], locale: string, categoryMeta: Map<string, unknown>) =>
+    buildNavTree(
+      docs as DocsEntry[],
+      locale as Locale,
+      categoryMeta as Map<string, CategoryMeta>,
+    ) as unknown as CategoryTreeNavNode[],
+  groupSatelliteNodes: (tree: CategoryTreeNavNode[], prefixes: string[]) =>
+    groupSatelliteNodes(tree as unknown as NavNode[], prefixes) as unknown as CategoryTreeNavNode[],
+  findNode: (tree: CategoryTreeNavNode[], slug: string) =>
+    findNode(tree as unknown as NavNode[], slug) as unknown as CategoryTreeNavNode | undefined,
+});

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

@@ -19,11 +19,7 @@
  *   has it in practice), fall back to the bare title.
  *
  */
+import { createComposeMetaTitle } from "@takazudo/zudo-doc/compose-meta-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}`;
-}
+export const composeMetaTitle = createComposeMetaTitle(settings.siteName);

package/templates/base/pages/lib/_doc-body-end.tsx

@@ -1,40 +1,8 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Shared bodyEndComponents block for doc pages.
-//
-// Extracted from the four doc-route render bodies (pages/docs/[...slug].tsx,
-// pages/[locale]/docs/[...slug].tsx, pages/v/[version]/docs/[...slug].tsx,
-// pages/v/[version]/[locale]/docs/[...slug].tsx) where the block was
-// duplicated verbatim across all four routes.
-//
-// Wraps BodyEndIslands + SidebarResizerInit (the latter conditional on
-// settings.sidebarResizer) and forwards the basePath prop that
-// BodyEndIslands requires for API URL construction.
-
-import type { JSX } from "preact";
+// Host thin-stub — see @takazudo/zudo-doc/doc-body-end (epic #2344, S7).
 import { settings } from "@/config/settings";
+import { createDocBodyEnd } from "@takazudo/zudo-doc/doc-body-end";
 import { BodyEndIslands } from "./_body-end-islands";
-import { SidebarResizerInit } from "@takazudo/zudo-doc/sidebar-resizer";
 
-/**
- * The `bodyEndComponents` slot content shared by all four doc-route page
- * components: `BodyEndIslands` (modal overlays, optional client-router
- * bootstrap when `dynamicPageTransition` is on, image-enlarge) and the
- * optional `SidebarResizerInit` drag handle. Whether the client-router
- * bootstrap island is included depends on `settings.dynamicPageTransition`
- * (gated inside `BodyEndIslands`). The SSR `<ClientRouter />` mounted by
- * `DocLayout` self-activates when `enableClientRouter` is `true`; the
- * island here is redundant for that activation path and kept only for the
- * `when="load"` hydration slot.
- */
-export function DocBodyEnd(): JSX.Element {
-  return (
-    <>
-      <BodyEndIslands basePath={settings.base ?? "/"} />
-      {/* SidebarResizerInit: attach drag handle to #desktop-sidebar on load
-          and on AFTER_NAVIGATE_EVENT (zfb:after-swap under the Strategy B
-          SPA navigation model). Idempotent — safe on every page. */}
-      {settings.sidebarResizer && <SidebarResizerInit />}
-    </>
-  );
-}
+export const DocBodyEnd = createDocBodyEnd({ settings, BodyEndIslands });

package/templates/base/pages/lib/_doc-content-header.tsx

@@ -1,118 +1,17 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Shared content header block for entry doc pages.
-//
-// Extracted from the four doc-route render bodies (pages/docs/[...slug].tsx,
-// pages/[locale]/docs/[...slug].tsx, pages/v/[version]/docs/[...slug].tsx,
-// pages/v/[version]/[locale]/docs/[...slug].tsx) where the block was
-// duplicated verbatim across all four entry branches.
-//
-// Covers the block from the <h1> through <FrontmatterPreview> (inclusive).
-// The MDX <Content /> and DocHistoryArea remain inline in each route because
-// they differ per route (e.g. the unlisted guard, contentDir param).
-
-import type { JSX } from "preact";
+// Host thin-stub — see @takazudo/zudo-doc/doc-content-header (epic #2344, S7).
 import { t } from "@/config/i18n";
-import { FrontmatterPreview } from "@takazudo/zudo-doc/metainfo";
 import { frontmatterRenderers } from "@/config/frontmatter-preview-renderers";
+import { createDocContentHeader } from "@takazudo/zudo-doc/doc-content-header";
+import { buildFrontmatterPreviewEntries } from "./_frontmatter-preview-data";
 import { DocMetainfoArea } from "./_doc-metainfo-area";
 import { DocTagsArea } from "./_doc-tags-area";
-import { buildFrontmatterPreviewEntries } from "./_frontmatter-preview-data";
-import type { DocPageEntry } from "./doc-page-props";
-
-interface DocContentHeaderProps {
-  /** The full content entry (title, description, tags, frontmatter data). */
-  entry: DocPageEntry;
-  /** Canonical page slug for DocMetainfoArea / DocTagsArea lookups. */
-  slug: string;
-  /** Active locale string, e.g. "en", "ja". */
-  locale: string;
-  /**
-   * True when this page falls back to the base EN collection for a locale
-   * route. Renders the "not yet translated" notice. Defaults to false.
-   * Only relevant for locale-prefixed and versioned-locale routes.
-   */
-  isFallback?: boolean;
-  /**
-   * Version slug when rendering a versioned route (e.g. "1.0"); undefined =
-   * latest. On versioned pages the date block and tag chips are hidden —
-   * the doc-history-meta manifest is built only from the LATEST content
-   * dirs, so a bare versioned slug would resolve to the latest file's
-   * Created/Updated/Author (wrong data), and tag chips would link to latest
-   * tag routes that may not exist for version-only tags (404). Mirrors the
-   * #1916 reduced-chrome stance that already hides doc history on
-   * versioned pages.
-   */
-  version?: string;
-}
-
-/**
- * Content header block for entry doc pages: h1, doc-metainfo, tag chips,
- * optional locale-fallback notice, description paragraph, and frontmatter
- * preview table.
- *
- * Placement: at the top of the article `<Fragment>`, before
- * `<props.entry.Content />` and the pager. The MDX content and DocHistoryArea
- * remain in the route component so per-route variations (unlisted gate,
- * contentDir) stay co-located with their context.
- */
-export function DocContentHeader({
-  entry,
-  slug,
-  locale,
-  isFallback = false,
-  version,
-}: DocContentHeaderProps): JSX.Element {
-  return (
-    <>
-      <h1 class="text-heading font-bold mb-vsp-xs">{entry.data.title}</h1>
-
-      {/* Build-time date block (Created / Updated / Author).
-          doc-metainfo placement — between <h1> and description.
-          Data from `.zfb/doc-history-meta.json` (esbuild-inlined, no fs).
-          Hidden on versioned pages — the manifest only covers latest
-          content dirs, so a versioned slug would show the LATEST file's
-          dates (see the `version` prop doc above). */}
-      {!version && (
-        <DocMetainfoArea slug={slug} locale={locale} isFallback={isFallback} />
-      )}
-
-      {/* Page-level tag chips — matching doc-tags placement (#1658).
-          Hidden on versioned pages: tag routes are built from latest
-          frontmatter only, so a version-only tag chip would 404 (see the
-          `version` prop doc above). */}
-      {!version && <DocTagsArea slug={slug} locale={locale} tags={entry.data.tags} />}
-
-      {/* Fallback notice for non-translated pages */}
-      {isFallback && !entry.data.generated && (
-        <div
-          class="mb-vsp-md border border-info/30 bg-info/5 px-hsp-lg py-vsp-sm text-small text-muted rounded"
-          role="note"
-        >
-          {t("doc.fallbackNotice", locale)}
-        </div>
-      )}
-
-      {entry.data.description && (
-        <p class="mb-vsp-lg text-title text-muted">
-          {entry.data.description}
-        </p>
-      )}
 
-      {/* Frontmatter preview — non-system, custom keys only. Returns
-          null when the entries array is empty, so pages without
-          custom frontmatter emit nothing. Custom per-key renderers
-          from frontmatter-preview-renderers.tsx produce styled cells
-          (pills, badges, etc.) instead of plain text. */}
-      <FrontmatterPreview
-        entries={buildFrontmatterPreviewEntries(entry.data)}
-        title={t("frontmatter.preview.title", locale)}
-        keyColLabel={t("frontmatter.preview.keyCol", locale)}
-        valueColLabel={t("frontmatter.preview.valueCol", locale)}
-        renderers={frontmatterRenderers}
-        data={entry.data as Record<string, unknown>}
-        locale={locale}
-      />
-    </>
-  );
-}
+export const DocContentHeader = createDocContentHeader({
+  t,
+  buildFrontmatterPreviewEntries,
+  frontmatterRenderers,
+  DocMetainfoArea,
+  DocTagsArea,
+});