create-zudo-doc 0.2.21 → 1.0.0

package/templates/base/pages/lib/route-enumerators.ts

@@ -1,292 +1,58 @@
-// Pure URL-enumeration helpers shared by both page paths() functions and the
-// sitemap. Extracting these prevents the sitemap from drifting out of sync
-// with the actual routes the page modules produce.
-//
-// Each enumerator returns absolute paths (with settings.base prefix and
-// trailing slash applied) as expected by the sitemap and page modules.
-// `enumerateAllRoutes()` composes the others and returns a deduped
-// Map<url, lastmod> that the sitemap renderer wraps directly.
-//
-// Design principles:
-//   - Draft pages are always excluded (never built).
-//   - Unlisted pages ARE included — they have real HTML files and should
-//     appear in the sitemap even though they're hidden from nav.
-//   - toRouteSlug() is applied to all entry ids so category index pages
-//     (e.g. "getting-started/index" → "getting-started") get correct URLs.
-//   - Auto-generated category index pages (categories without index.mdx) are
-//     emitted by building the nav tree and calling collectAutoIndexNodes.
-
-import { loadDocs } from "../_data";
-import { mergeLocaleDocs } from "./locale-merge";
-import { resolveNavSource, resolveVersionedLocaleSource } from "./_nav-source-docs";
+// Thin stub — route-enumerators moved to the package (epic #2344, S6).
+// Calls `createRouteEnumerators(ctx)` from @takazudo/zudo-doc/route-enumerators
+// with the host singletons injected, then re-exports the resulting enumeration
+// functions so all existing call sites continue to work unchanged.
+
+import { createRouteEnumerators } from "@takazudo/zudo-doc/route-enumerators";
+import type {
+  DocsEntryForTags,
+  TagInfoForEnum,
+  DocPageEntry,
+  DocNavNode,
+} from "@takazudo/zudo-doc/route-enumerators";
 import { settings } from "@/config/settings";
 import { defaultLocale, type Locale } from "@/config/i18n";
-import type { VersionConfig } from "@/config/settings";
-import type { DocsEntry } from "@/types/docs-entry";
-import { docsUrl, versionedDocsUrl, withBase } from "@/utils/base";
+import { docsUrl, versionedDocsUrl, withBase, isDefaultLocaleOnlyPath } from "@/utils/base";
+import { buildNavTree, collectAutoIndexNodes, type CategoryMeta } from "@/utils/docs";
 import { collectTags } from "@/utils/tags";
 import { toRouteSlug } from "@/utils/slug";
-import {
-  buildNavTree,
-  collectAutoIndexNodes,
-} from "@/utils/docs";
-
-// ---------------------------------------------------------------------------
-// enumerateDocsRoutes
-// ---------------------------------------------------------------------------
-
-/**
- * Enumerate all doc page URLs for a locale.
- *
- * For the default locale: loads the "docs" collection directly.
- * For non-default locales: inlines a locale-first merge — locale docs take
- * priority; base EN docs fill in slugs not covered by the locale collection,
- * with default-locale-only paths excluded. A nav-tree pass then adds
- * auto-generated category index pages.
- *
- * Applies toRouteSlug so "category/index" entries become "category/" URLs.
- * Returns deduplicated URL strings with base prefix and trailing slash.
- */
-export function enumerateDocsRoutes(locale: string): string[] {
-  const urls: string[] = [];
-
-  // Identity-stable nav source — same instances the doc routes use, so the
-  // nav-tree fast-path applies here too (#1902).
-  const { docs: allDocs, navDocs, categoryMeta } = resolveNavSource(
-    locale as Locale,
-    undefined,
-    { applyDefaultLocaleOnlyFilter: true, keepUnlisted: true },
-  );
-  const tree = buildNavTree(navDocs, locale as Locale, categoryMeta);
-
-  for (const doc of allDocs) {
-    // A `category_no_page` index.mdx is metadata-only — no route, so no sitemap
-    // URL. Same exclusion the doc-route paths() apply (zfb retains every .mdx
-    // as a collection entry, so the skip must be explicit).
-    if (doc.data.category_no_page === true) continue;
-    // Canonical route slug via the one shared rule (@/utils/slug). `doc.id` is
-    // already `toRouteSlug(doc.slug)` (bridged through stripIndexSuffix in
-    // pages/_data.ts), so a bare root index.mdx is "" here → `/docs/` — the
-    // canonical root URL (#1891). The `toRouteSlug` fallback is a redundant
-    // safety re-application of the same rule (idempotent on the already-
-    // stripped id); kept so this enumerator's slug derivation reads as a
-    // single explicit call to the canonical helper.
-    urls.push(docsUrl(doc.data.slug ?? toRouteSlug(doc.id), locale as Locale));
-  }
-  for (const node of collectAutoIndexNodes(tree)) {
-    urls.push(docsUrl(node.slug, locale as Locale));
-  }
-
-  return [...new Set(urls)];
-}
-
-// ---------------------------------------------------------------------------
-// enumerateTagsRoutes
-// ---------------------------------------------------------------------------
-
-/**
- * Enumerate tag-index and per-tag URLs for a locale.
- *
- * Uses the same tag map as the tag pages (unlisted + draft excluded) so the
- * sitemap lists exactly the same tag pages that get built.
- *
- * Returns:
- *   - /docs/tags/ (or /{locale}/docs/tags/)
- *   - /docs/tags/{tag}/ (or /{locale}/docs/tags/{tag}/) for each unique tag
- */
-export function enumerateTagsRoutes(locale: string): string[] {
-  if (!settings.docTags) return [];
-
-  const urls: string[] = [];
-
-  const tagsBase =
-    locale === defaultLocale ? "/docs/tags" : `/${locale}/docs/tags`;
-  urls.push(withBase(tagsBase));
-
-  // Collect tags from the same merged doc set the tag pages use.
-  // Filter unlisted + draft + category_no_page — mirrors the tag [tag].tsx
-  // pages so the sitemap lists exactly the tag pages that get built (a
-  // category_no_page index has no route, so a tag it carries must not coin a
-  // tag page that links back to it). The category_no_page drop happens AFTER
-  // the locale merge so a locale override carrying the flag first wins the
-  // merge — pre-merge filtering would let the unflagged base doc resurface.
-  let docs: DocsEntry[];
-  if (locale === defaultLocale) {
-    docs = loadDocs("docs").filter(
-      (d) => !d.data.unlisted && !d.data.draft && !d.data.category_no_page,
-    );
-  } else {
-    const result = mergeLocaleDocs({
-      baseDocs: loadDocs("docs").filter((d) => !d.data.draft),
-      localeDocs: loadDocs(`docs-${locale}`).filter((d) => !d.data.draft),
-      applyDefaultLocaleOnlyFilter: true,
-    });
-    docs = result.docs.filter((d) => !d.data.category_no_page);
-  }
-
-  const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
-
-  for (const tag of tagMap.keys()) {
-    // Tag segment URL-encoded — these URLs feed the sitemap, which must
-    // carry well-formed encoded URLs (e.g. "type:guide" → "type%3Aguide").
-    // Route params (the page paths() functions) stay raw.
-    const encoded = encodeURIComponent(tag);
-    const tagPath =
-      locale === defaultLocale
-        ? `/docs/tags/${encoded}`
-        : `/${locale}/docs/tags/${encoded}`;
-    urls.push(withBase(tagPath));
-  }
-
-  return urls;
-}
-
-// ---------------------------------------------------------------------------
-// enumerateVersionedRoutes
-// ---------------------------------------------------------------------------
-
-/**
- * Enumerate doc URLs for a single (version, locale) combination.
- *
- * For the default locale: loads `docs-v-${version.slug}`.
- * For non-default locales: locale-first merge — locale-specific collection
- * takes priority; base EN collection fills in pages not yet translated.
- * If the locale collection doesn't exist for this version, all pages fall
- * back to the EN base (matching the page module's behaviour).
- *
- * Returns versioned URLs like /v/{version}/docs/{slug}/ or
- * /v/{version}/{locale}/docs/{slug}/.
- */
-export function enumerateVersionedRoutes(
-  version: VersionConfig,
-  locale: string,
-): string[] {
-  const urls: string[] = [];
-
-  if (locale === defaultLocale) {
-    // Versioned EN base — identity-stable source (#1902).
-    const { docs: allDocs, navDocs, categoryMeta } = resolveNavSource(
-      "en",
-      version.slug,
-    );
-    const tree = buildNavTree(navDocs, "en", categoryMeta);
-
-    for (const doc of allDocs) {
-      // category_no_page index.mdx → no route, no sitemap URL (see paths()).
-      if (doc.data.category_no_page === true) continue;
-      const slug = doc.data.slug ?? toRouteSlug(doc.id);
-      urls.push(versionedDocsUrl(slug, version.slug));
-    }
-    for (const node of collectAutoIndexNodes(tree)) {
-      urls.push(versionedDocsUrl(node.slug, version.slug));
-    }
-  } else {
-    const localeDir = version.locales?.[locale]?.dir;
+import type { DocsEntry } from "@/types/docs-entry";
+import { loadDocs } from "../_data";
+import { resolveNavSource, resolveVersionedLocaleSource } from "./_nav-source-docs";
+import { mergeLocaleDocs } from "./locale-merge";
 
-    // Versioned locale source — locale-first merge over the version's EN base
-    // (identity-stable; #1902).
-    const { docs: allDocs, navDocs, categoryMeta } = resolveVersionedLocaleSource(
-      version.slug,
-      version.docsDir,
+export const {
+  enumerateDocsRoutes,
+  enumerateTagsRoutes,
+  enumerateVersionedRoutes,
+  enumerateAllRoutes,
+} = createRouteEnumerators({
+  defaultLocale,
+  getLocaleKeys: () => Object.keys(settings.locales),
+  getVersions: () => settings.versions,
+  getDocTags: () => settings.docTags,
+  docsUrl,
+  versionedDocsUrl,
+  withBase,
+  loadDocs,
+  isDefaultLocaleOnlyPath,
+  // The factory describes collectTags / buildNavTree with the package's minimal
+  // structural slots (DocsEntryForTags / DocPageEntry / Map<string, unknown> /
+  // TagInfoForEnum). The host helpers are typed against the concrete project
+  // types (DocsEntry / NavNode / the Locale union / TagInfo) but are runtime-
+  // identical, so the stub adapts them with thin casting wrappers at the
+  // injection boundary where the host owns the type knowledge.
+  collectTags: (docs: DocsEntryForTags[], slugFn): Map<string, TagInfoForEnum> =>
+    collectTags(docs as unknown as DocsEntry[], slugFn),
+  toRouteSlug,
+  buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, unknown>) =>
+    buildNavTree(
+      docs as unknown as DocsEntry[],
       locale as Locale,
-      localeDir,
-      { applyDefaultLocaleOnlyFilter: true, keepUnlisted: true },
-    );
-    const tree = buildNavTree(navDocs, locale as Locale, categoryMeta);
-
-    for (const doc of allDocs) {
-      // category_no_page index.mdx → no route, no sitemap URL (see paths()).
-      if (doc.data.category_no_page === true) continue;
-      const slug = doc.data.slug ?? toRouteSlug(doc.id);
-      urls.push(versionedDocsUrl(slug, version.slug, locale as Locale));
-    }
-    for (const node of collectAutoIndexNodes(tree)) {
-      urls.push(versionedDocsUrl(node.slug, version.slug, locale as Locale));
-    }
-  }
-
-  return [...new Set(urls)];
-}
-
-// ---------------------------------------------------------------------------
-// enumerateAllRoutes
-// ---------------------------------------------------------------------------
-
-/**
- * Compose all route enumerators into a deduped Map<url, lastmod>.
- *
- * Covers:
- *   - Site root
- *   - Default-locale docs + tags
- *   - Per-locale homepages, docs, and tags
- *   - Versioned EN docs (for each version in settings.versions)
- *   - Versioned locale docs (for each locale in settings.locales)
- *
- * The map keys are absolute paths (with settings.base prefix + trailing
- * slash). The sitemap renderer prefixes each with settings.siteUrl.
- */
-export function enumerateAllRoutes(): Map<string, string> {
-  const today = new Date().toISOString().split("T")[0] ?? "";
-  const routes = new Map<string, string>();
-
-  function add(url: string): void {
-    if (!routes.has(url)) {
-      routes.set(url, today);
-    }
-  }
-
-  // Site root
-  add(withBase("/"));
-
-  // Default locale docs
-  for (const url of enumerateDocsRoutes(defaultLocale)) {
-    add(url);
-  }
-
-  // Default locale tags
-  for (const url of enumerateTagsRoutes(defaultLocale)) {
-    add(url);
-  }
-
-  // Non-default locales
-  for (const locale of Object.keys(settings.locales)) {
-    add(withBase(`/${locale}`));
-
-    for (const url of enumerateDocsRoutes(locale)) {
-      add(url);
-    }
-
-    for (const url of enumerateTagsRoutes(locale)) {
-      add(url);
-    }
-  }
-
-  // Versions listing pages — /docs/versions/ and /{locale}/docs/versions/.
-  // These static utility pages are built by pages/docs/versions.tsx and
-  // pages/[locale]/docs/versions.tsx whenever versioning is configured.
-  // They are not part of any content collection so they are added explicitly.
-  if (settings.versions) {
-    add(withBase("/docs/versions"));
-    for (const locale of Object.keys(settings.locales)) {
-      add(withBase(`/${locale}/docs/versions`));
-    }
-  }
-
-  // Versioned docs
-  if (settings.versions) {
-    for (const version of settings.versions as VersionConfig[]) {
-      for (const url of enumerateVersionedRoutes(version, defaultLocale)) {
-        add(url);
-      }
-      // Non-default locales always have versioned pages (they fall back to EN
-      // when a locale-specific collection is not configured).
-      for (const locale of Object.keys(settings.locales)) {
-        for (const url of enumerateVersionedRoutes(version, locale)) {
-          add(url);
-        }
-      }
-    }
-  }
-
-  return routes;
-}
+      categoryMeta as Map<string, CategoryMeta>,
+    ) as DocNavNode[],
+  collectAutoIndexNodes,
+  resolveNavSource,
+  resolveVersionedLocaleSource,
+  mergeLocaleDocs,
+});

package/templates/base/src/components/ai-chat-modal.tsx

@@ -1,12 +1,11 @@
-"use client";
-
-// W6A stub — no-op default export.
+// W6A stub — no-op default + AiChatModal named exports.
 //
-// The host (zudo-doc showcase) ships a full AI-chat modal island here. In
-// generated downstream projects the AI assistant is gated behind a future
-// settings flag; for now the file exists so unconditional page imports
-// (`pages/lib/_body-end-islands.tsx`) resolve, and the component renders
-// nothing. Wire a real implementation by replacing this file.
+// The AiChatModal island now ships from the package
+// (`@takazudo/zudo-doc/ai-chat-modal`); the unconditional
+// `pages/lib/_body-end-islands.tsx` imports it directly from there. This
+// stub exists only so any project-local code that references the
+// `@/components/ai-chat-modal` path still resolves — it renders nothing.
+// Replace this file to wire a project-specific modal.
 import type { JSX } from "preact";
 
 function AiChatModal(): JSX.Element | null {
@@ -15,3 +14,5 @@ function AiChatModal(): JSX.Element | null {
 AiChatModal.displayName = "AiChatModal";
 
 export default AiChatModal;
+
+export { AiChatModal };

package/templates/base/src/components/content/code-group.tsx

@@ -1,76 +1,3 @@
-import { Tabs } from "@takazudo/zudo-doc/code-syntax";
-import { TabItem } from "@takazudo/zudo-doc/tab-item";
-
-/**
- * Adapter for zfb's `:::code-group` directive (codeTabs Option A).
- *
- * zfb emits:
- *   <CodeGroup tabs={["label1", "label2", ...]}>
- *     <pre data-lang="ts">{RAW code text}</pre>
- *     <pre data-lang="js">{RAW code text}</pre>
- *   </CodeGroup>
- *
- * The existing <Tabs>/<TabItem> UI uses a children-based API, so this
- * component zips the `tabs` label array with the `<pre data-lang>` children
- * by index, wrapping each in a <TabItem> with the matching label.
- *
- * Code inside each <pre> is raw text (NOT syntect-highlighted — the Rust
- * pipeline does not run highlight inside code-group fences). We render
- * the <pre> inside a <TabItem> with explicit styling via Tailwind tokens
- * so it looks like a code block visually.
- *
- * TabsInit (the companion init script) is present in the layout
- * (packages/zudo-doc/src/doclayout/doc-layout-with-defaults.tsx line 433)
- * — we rely on it being there; no duplicate needed here.
- */
-
-type Props = {
-  tabs?: string[];
-  children?: React.ReactNode;
-  [key: string]: unknown;
-};
-
-function toArray(children: React.ReactNode): React.ReactNode[] {
-  if (!children) return [];
-  if (Array.isArray(children)) return children;
-  return [children];
-}
-
-export function CodeGroup({ tabs = [], children, name }: Props) {
-  const childArray = toArray(children);
-
-  // Zip tabs labels with pre children by index. Extra children beyond the
-  // tabs array (shouldn't happen in normal zfb output) are ignored.
-  const items = tabs.map((label, i) => {
-    const child = childArray[i];
-    return { label, child };
-  });
-
-  if (items.length === 0) {
-    // Degenerate: no tabs — render children as-is.
-    return <>{children}</>;
-  }
-
-  // zfb forwards `:::code-group{name="x"}` as the `name` prop; Tabs persists
-  // the active tab per group via `groupId`.
-  const groupId = typeof name === "string" ? name : undefined;
-
-  return (
-    <Tabs groupId={groupId}>
-      {items.map(({ label, child }, i) => (
-        // value is suffixed with the index so two fences sharing a label
-        // (e.g. both titled "ts") get distinct stable tab identities; the
-        // label stays the visible text.
-        <TabItem
-          key={`${label}-${i}`}
-          label={label}
-          value={`${label}-${i}`}
-          default={i === 0 ? true : undefined}
-        >
-          {/* Raw-code <pre> from zfb: apply code-block visual treatment via tokens */}
-          <div class="code-group-panel">{child}</div>
-        </TabItem>
-      ))}
-    </Tabs>
-  );
-}
+// Re-export from the shared package — moved to @takazudo/zudo-doc/code-group
+// as part of the package-first migration (epic #2321, S4 #2327).
+export { CodeGroup } from "@takazudo/zudo-doc/code-group";

package/templates/base/src/components/content/content-admonition.tsx

@@ -1,56 +1,4 @@
-/** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-// Real Preact bindings for the admonition MDX tags (Note/Tip/Info/Warning/
-// Danger/Caution/Important). Replaces the former literal-VNode
-// `makeAdmonitionStub` in pages/_mdx-components.ts with a proper typed
-// component — restoring the first-class admonition components the Astro-era
-// theme shipped (zudolab/zudo-doc#1456), now on the zfb pipeline.
-//
-// These tags arrive from two zfb features: the `directives` map emits them from
-// `:::note` directives, and `githubAlerts` emits Important/Caution from
-// `[!IMPORTANT]`/`[!CAUTION]` blockquotes. The JSX form `<Note title="…">` is
-// also authored directly in MDX. All three paths render through here.
-//
-// Markup contract — KEEP STABLE. The structure below
-//   <div data-admonition="<variant>" class="admonition admonition-<variant>">
-//     <p class="admonition-title">…</p>
-//     <div class="admonition-body">…</div>
-//   </div>
-// is the hook both the design-system CSS (`.admonition-<variant>` rules in
-// src/styles/global.css) and the e2e smoke spec (e2e/smoke-admonitions.spec.ts)
-// target. The per-variant color + icon live in CSS keyed off `data-admonition`,
-// so this component stays presentation-agnostic.
-import type { ComponentChildren, VNode } from "preact";
-
-export type AdmonitionVariant =
-  | "note"
-  | "tip"
-  | "info"
-  | "warning"
-  | "danger"
-  | "caution"
-  | "important";
-
-export interface AdmonitionProps {
-  /** Custom title; falls back to the capitalized variant name (e.g. "Note"). */
-  title?: string;
-  children?: ComponentChildren;
-}
-
-/**
- * Build the admonition component for a single variant. The title row is always
- * rendered — defaulting to the capitalized variant name when the author gives
- * no `title` — matching the Astro reference where every callout shows a title.
- */
-export function makeAdmonition(variant: AdmonitionVariant) {
-  const defaultTitle = variant.charAt(0).toUpperCase() + variant.slice(1);
-  return function Admonition({ title, children }: AdmonitionProps): VNode {
-    const heading = title && title.length > 0 ? title : defaultTitle;
-    return (
-      <div data-admonition={variant} class={`admonition admonition-${variant}`}>
-        <p class="admonition-title">{heading}</p>
-        <div class="admonition-body">{children}</div>
-      </div>
-    );
-  };
-}
+// Re-export from the shared package — moved to @takazudo/zudo-doc/content-admonition
+// as part of the package-first migration (epic #2321, S4 #2327).
+export type { AdmonitionVariant, AdmonitionProps } from "@takazudo/zudo-doc/content-admonition";
+export { makeAdmonition } from "@takazudo/zudo-doc/content-admonition";

package/templates/base/src/components/doc-history.tsx

@@ -1,13 +1,14 @@
-"use client";
-
 // W6A stub — no-op default + DocHistory named exports.
 //
-// When the docHistory feature is enabled, the feature template
-// overwrites this file with the real island. Generated projects
-// without the feature ship the no-op so the unconditional
-// `pages/lib/_doc-history-area` import resolves. The host module also
-// exposes `DocHistory` as a named export, so the stub mirrors both
-// shapes to keep the import surface stable.
+// The real DocHistory island now ships from the package
+// (`@takazudo/zudo-doc/doc-history`); the unconditional
+// `pages/lib/_doc-history-area.tsx` imports it directly from there. When
+// the docHistory feature is enabled the feature template overwrites this
+// file with a re-export shim pointing at the package island. Generated
+// projects without the feature ship this no-op so any project-local code
+// that references the `@/components/doc-history` path still resolves. The
+// host module exposes `DocHistory` as a named export, so the stub mirrors
+// both the default and named shapes to keep the import surface stable.
 import type { JSX } from "preact";
 
 function DocHistoryComponent(): JSX.Element | null {

package/templates/base/src/components/image-enlarge.tsx

@@ -1,12 +1,13 @@
-"use client";
-
-// W6A stub — no-op default + ImageEnlargeSsrFallback named exports.
+// W6A stub — no-op default + ImageEnlarge / ImageEnlargeSsrFallback exports.
 //
-// When the imageEnlarge feature is enabled, the feature template
-// overwrites this file with the real island and SSR fallback. Generated
-// projects without the feature ship the no-op so the unconditional
-// `pages/lib/_body-end-islands` import resolves (the body-end islands
-// renderer references both the default and the SSR fallback).
+// The real ImageEnlarge island and its SSR fallback now ship from the
+// package (`@takazudo/zudo-doc/image-enlarge`); the unconditional
+// `pages/lib/_body-end-islands.tsx` imports them directly from there. When
+// the imageEnlarge feature is enabled the feature template overwrites this
+// file with a re-export shim pointing at the package island. Generated
+// projects without the feature ship this no-op so any project-local code
+// that references the `@/components/image-enlarge` path still resolves (the
+// body-end renderer references both the default and the SSR fallback).
 import type { JSX } from "preact";
 
 function ImageEnlarge(): JSX.Element | null {
@@ -16,6 +17,8 @@ ImageEnlarge.displayName = "ImageEnlarge";
 
 export default ImageEnlarge;
 
+export { ImageEnlarge };
+
 export function ImageEnlargeSsrFallback(): JSX.Element | null {
   return null;
 }