create-zudo-doc 0.2.21 → 0.2.22

package/templates/base/pages/lib/_doc-route-paths.ts

@@ -1,101 +1,16 @@
-// Shared, pure prop-builder helpers for the 4 doc-route paths() functions.
-//
-// Extracted (#1917) from the near-verbatim paths() bodies of the 4 doc routes.
-// These are version- and i18n-AGNOSTIC: every URL is produced by an injected
-// `urlFor(slug) => string` closure, so the same code serves latest, locale,
-// versioned, and versioned-locale routes without branching on context. The
-// route file owns the closure (docsUrl vs versionedDocsUrl bound to its
-// version/locale), which is what guarantees a latest-page pagination override
-// is resolved + rewritten against the LATEST tree — it can never be rebound to
-// a /v/ URL because a latest route never receives a versioned closure
-// (#1916 correctness; see the behavioral tests).
-
-import { flattenTree, findNode, type NavNode } from "@/utils/docs";
-
-/** The two pagination-override fields read off entry frontmatter. */
-export interface PaginationOverrides {
-  /** `undefined` = no override; `null` = suppress; string = target slug. */
-  pagination_prev?: string | null;
-  pagination_next?: string | null;
-}
-
-/**
- * Resolve prev/next nav nodes for an entry against the route's OWN nav tree.
- *
- * - Sequential prev/next come from the flattened sub-tree (`subtreeFlat`).
- * - Frontmatter `pagination_prev` / `pagination_next` overrides resolve via
- *   `findNode(tree, …)` against the SAME `tree` the route built — never a
- *   foreign tree. The caller passes its own version/locale-scoped tree, so a
- *   `/v/` override resolves to a `/v/` node and a latest override to a latest
- *   node. (#1916 — pagination-override must bind to the correct tree.)
- *
- * Returns the raw NavNodes (hrefs untouched). Callers that need versioned
- * hrefs run the result through `rewriteNavHref` with their `urlFor` closure.
- */
-export function resolveDocPrevNext(
-  tree: NavNode[],
-  subtreeFlat: NavNode[],
-  slug: string,
-  overrides: PaginationOverrides,
-): { prev: NavNode | null; next: NavNode | null } {
-  const idx = subtreeFlat.findIndex((n) => n.slug === slug);
-
-  let prev = idx > 0 ? subtreeFlat[idx - 1] ?? null : null;
-  let next = idx >= 0 && idx < subtreeFlat.length - 1 ? subtreeFlat[idx + 1] ?? null : null;
-
-  if (overrides.pagination_prev !== undefined) {
-    if (overrides.pagination_prev === null) {
-      prev = null;
-    } else {
-      const found = findNode(tree, overrides.pagination_prev);
-      prev = found ?? prev;
-    }
-  }
-  if (overrides.pagination_next !== undefined) {
-    if (overrides.pagination_next === null) {
-      next = null;
-    } else {
-      const found = findNode(tree, overrides.pagination_next);
-      next = found ?? next;
-    }
-  }
-
-  return { prev, next };
-}
-
-/** Flatten the relevant sub-tree for an entry — convenience over flattenTree. */
-export function flattenSubtree(subtree: NavNode[]): NavNode[] {
-  return flattenTree(subtree);
-}
-
-/**
- * Rewrite a single nav node's href via the route's `urlFor` closure.
- *
- * Returns `null` for a `null` node. Latest routes pass `undefined` (leave the
- * href as the latest `docsUrl` already baked into the node); versioned routes
- * pass `urlFor` so prev/next links point at the versioned URL.
- */
-export function rewriteNavHref(
-  node: NavNode | null,
-  urlFor: ((slug: string) => string) | undefined,
-): NavNode | null {
-  if (!node) return null;
-  if (!urlFor) return node;
-  return { ...node, href: urlFor(node.slug) };
-}
-
-/**
- * Remap an auto-index node's child-card hrefs via `urlFor`.
- *
- * #1916 #2: on versioned routes the children carry latest `docsUrl` hrefs
- * (every nav node does — see toNavNodes). They MUST be overridden to the
- * versioned URL ALWAYS, not only when `c.href` is missing. Passing `urlFor`
- * here does exactly that. Latest routes pass `undefined` to keep the original.
- */
-export function remapNavChildHrefs(
-  children: NavNode[],
-  urlFor: ((slug: string) => string) | undefined,
-): NavNode[] {
-  if (!urlFor) return children;
-  return children.map((c) => ({ ...c, href: urlFor(c.slug) }));
-}
+// Thin stub — doc-route-paths moved to the package (epic #2344, S6).
+// Re-exports the pure prop-builder helpers from @takazudo/zudo-doc/doc-route-paths.
+
+export type {
+  DocNavNode,
+  PaginationOverrides,
+} from "@takazudo/zudo-doc/doc-route-paths";
+
+export {
+  flattenTree,
+  findNode,
+  flattenSubtree,
+  resolveDocPrevNext,
+  rewriteNavHref,
+  remapNavChildHrefs,
+} from "@takazudo/zudo-doc/doc-route-paths";

package/templates/base/pages/lib/_doc-tags-area.tsx

@@ -1,44 +1,15 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Locale-aware DocTags area wrapper for the zfb doc pages.
-//
-// Renders the page-level tag chips (e.g. "Tags: #customization") between
-// the DocMetainfo block and the description paragraph (doc-tags placement
-// — after-title, between the date block and description paragraph).
-//
-// Restoration of a Astro→zfb migration regression: the DocTags component
-// was correctly ported into @takazudo/zudo-doc/metainfo/doc-tags.tsx
-// but no page template wired it up (#1658, closes #1508).
-//
-// tagHref logic: inlined from _footer-with-defaults.tsx (the `tagHref`
-// helper there). Extraction was considered but would cause ripple in the
-// footer file and its callers — per the spec's "no opportunistic refactor"
-// rule, a local copy is used here instead.
-//
-// i18n: both `doc.tags` and `doc.taggedWith` are confirmed present for all
-// project locales (en, ja, de) in src/config/i18n.ts — no fallback needed.
-
-import type { VNode } from "preact";
+// Host thin-stub — see @takazudo/zudo-doc/doc-tags-area (epic #2344, S7).
 import { settings } from "@/config/settings";
 import { defaultLocale, t } from "@/config/i18n";
 import { withBase } from "@/utils/base";
-import { resolvePageTags } from "@/utils/tags";
-import { DocTags } from "@takazudo/zudo-doc/metainfo";
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
+import { tagVocabulary } from "@/config/tag-vocabulary";
+import { createDocTagsArea } from "@takazudo/zudo-doc/doc-tags-area";
 
-/**
- * Build the base-prefixed tag detail page href for the given locale.
- *
- * Inlined from _footer-with-defaults.tsx `tagHref` — not extracted to avoid
- * ripple (spec rule: no opportunistic refactor on tagHref extraction).
- *
- * The tag segment is URL-encoded at the href site only — route params stay
- * raw, so the built output dir keeps the raw tag name and the server decodes
- * the percent-encoded href back to it (e.g. "type:guide" → "type%3Aguide").
- */
+// Inlined from the original _doc-tags-area.tsx `tagHref` helper.
+// Builds the base-prefixed tag detail page href for the given locale.
+// The tag segment is URL-encoded at the href site only.
 function tagHref(tag: string, locale: string): string {
   const encoded = encodeURIComponent(tag);
   const path =
@@ -48,46 +19,12 @@ function tagHref(tag: string, locale: string): string {
   return withBase(path);
 }
 
-// ---------------------------------------------------------------------------
-// Component
-// ---------------------------------------------------------------------------
-
-interface DocTagsAreaProps {
-  /** Page slug, e.g. "guides/sidebar". */
-  slug: string;
-  /** Active locale string, e.g. "en", "ja". */
-  locale: string;
-  /** Raw tag strings from the page frontmatter (entry.data.tags). */
-  tags: readonly string[] | undefined;
-}
-
-/**
- * Renders the page-level tag chip block when `settings.docTags` is enabled
- * and the page has at least one resolved (non-deprecated) tag.
- *
- * Returns null when `docTags` is disabled, the page has no tags, or all
- * raw tags resolve to deprecated entries.
- *
- * Placement is "after-title" (between the date block and description paragraph).
- */
-export function DocTagsArea({ locale, tags }: DocTagsAreaProps): VNode | null {
-  if (!settings.docTags) return null;
-
-  const rawTags = tags ?? [];
-  const canonicalTags = resolvePageTags(rawTags);
-  if (canonicalTags.length === 0) return null;
+export type { DocTagsAreaProps } from "@takazudo/zudo-doc/doc-tags-area";
 
-  const resolvedTags = canonicalTags.map((tag) => ({
-    tag,
-    href: tagHref(tag, locale),
-  }));
-
-  return (
-    <DocTags
-      placement="after-title"
-      tags={resolvedTags}
-      tagsLabel={t("doc.tags", locale)}
-      taggedWithLabel={t("doc.taggedWith", locale)}
-    />
-  );
-}
+export const DocTagsArea = createDocTagsArea({
+  settings,
+  defaultLocale,
+  tagVocabularyEntries: tagVocabulary,
+  tagHref,
+  t,
+});

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

@@ -1,30 +1,9 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Locale-aware Footer wrapper for the zfb doc pages.
-//
-// Footer data-prep utilities — reads settings.footer, localizes link
-// hrefs and titles, and optionally collects tag columns when taglist is
-// enabled — then feeds the result into the presentational <Footer> shell
-// from @takazudo/zudo-doc/footer.
-//
-// Callers pass a `lang` prop (the active locale string, e.g. "en", "ja").
-// The component returns a fully populated <Footer> when settings.footer is
-// configured, or a bare <Footer /> shell when it is not (the shell still
-// emits the contentinfo ARIA landmark).
-//
-// Data-prep helpers used:
-//   settings.footer            — link columns, copyright, taglist config
-//   isExternal / resolveHref / withBase  — href normalization
-//   defaultLocale              — determines when locale prefix is needed
-//   tagVocabulary              — group-by ordering for grouped taglist mode
-//   collectTags                — builds tag → { count, docs } map
-//   toRouteSlug                — derives route slug from collection id
-//   loadDocs / filterDrafts    — synchronous zfb collection helpers (ADR-004)
-
-import type { VNode } from "preact";
+// Host thin-stub — see @takazudo/zudo-doc/footer-with-defaults (epic #2344, S5).
+// Wires host singletons into the package factory and passes the tag loading
+// function as a dependency so the factory never imports @/ aliases.
 import { settings } from "@/config/settings";
-import { Footer } from "@takazudo/zudo-doc/footer";
-import type { FooterLinkColumn, FooterTagColumn } from "@takazudo/zudo-doc/footer";
 import { isExternal, resolveHref, withBase } from "@/utils/base";
 import { defaultLocale } from "@/config/i18n";
 import { tagVocabulary } from "@/config/tag-vocabulary";
@@ -33,214 +12,47 @@ import { toRouteSlug } from "@/utils/slug";
 import { mergeLocaleDocs } from "./locale-merge";
 import { stableDocs, memoizeDerived } from "./_nav-source-cache";
 import type { DocsEntry } from "@/types/docs-entry";
+import { createFooterWithDefaults } from "@takazudo/zudo-doc/footer-with-defaults";
 
 // ---------------------------------------------------------------------------
-// Internal helpers
+// Tag loading (host-side, reads collections via stableDocs / memoizeDerived)
 // ---------------------------------------------------------------------------
 
-/**
- * Prefix an internal href with the locale path for non-default locales,
- * then apply the configured base prefix. External hrefs pass through.
- */
-function localizeHref(href: string, lang: string): string {
-  if (isExternal(href)) return href;
-  if (lang !== defaultLocale) {
-    const path = href.startsWith("/") ? href : `/${href}`;
-    return resolveHref(`/${lang}${path}`);
+function loadTagsForLocale(lang: string) {
+  if (lang === defaultLocale) {
+    const baseDocs = stableDocs("docs");
+    return memoizeDerived([baseDocs], "footerTaglist;default", () => {
+      const docs: DocsEntry[] = baseDocs.filter(
+        (d) => !d.data.draft && !d.data.unlisted && !d.data.category_no_page,
+      );
+      const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+      return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
+    });
   }
-  return resolveHref(href);
-}
-
-/**
- * Build the base-prefixed tag detail page href for the given locale.
- * The tag segment is URL-encoded at the href site only — route params stay
- * raw, so the built output dir keeps the raw tag name and the server decodes
- * the percent-encoded href back to it (e.g. "type:guide" → "type%3Aguide").
- */
-function tagHref(tag: string, lang: string): string {
-  const encoded = encodeURIComponent(tag);
-  const path =
-    lang === defaultLocale
-      ? `/docs/tags/${encoded}`
-      : `/${lang}/docs/tags/${encoded}`;
-  return withBase(path);
+  const baseDocs = stableDocs("docs");
+  const localeDocs = stableDocs(`docs-${lang}`);
+  return memoizeDerived([baseDocs, localeDocs], `footerTaglist;${lang}`, () => {
+    const result = mergeLocaleDocs({
+      baseDocs: baseDocs.filter((d) => !d.data.draft),
+      localeDocs: localeDocs.filter((d) => !d.data.draft),
+      applyDefaultLocaleOnlyFilter: true,
+    });
+    const docs: DocsEntry[] = result.docs.filter((d) => !d.data.category_no_page);
+    const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+    return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
+  });
 }
 
 // ---------------------------------------------------------------------------
-// Component
+// Thin-stub export
 // ---------------------------------------------------------------------------
 
-interface FooterWithDefaultsProps {
-  /** Active locale string, e.g. "en", "ja". Defaults to defaultLocale. */
-  lang?: string;
-}
-
-/**
- * Locale-aware Footer wrapper.
- *
- * Reads settings.footer and assembles the linkColumns / tagColumns /
- * copyright props expected by the presentational <Footer> shell.  When
- * settings.footer is false, a bare <Footer /> shell is returned (the
- * contentinfo ARIA landmark is still present).
- */
-export function FooterWithDefaults({
-  lang = defaultLocale,
-}: FooterWithDefaultsProps): VNode {
-  const footer = settings.footer;
-
-  // Locale-keyed persist key: same-locale swaps preserve DOM identity;
-  // cross-locale swaps discard the stale footer and re-render. (#1546)
-  const persistKey = `footer-${lang}`;
-
-  // When footer is not configured, return the bare shell so the
-  // contentinfo ARIA landmark is present.
-  if (!footer) {
-    return <Footer persistKey={persistKey} />;
-  }
-
-  const { links, copyright, taglist } = footer;
-
-  // ── Link columns ────────────────────────────────────────────────────────
-
-  const linkColumns: FooterLinkColumn[] = links.map((column) => ({
-    title: (column.locales as Record<string, { title: string }> | undefined)?.[lang]?.title ?? column.title,
-    items: column.items.map((item) => ({
-      label: (item.locales as Record<string, { label: string }> | undefined)?.[lang]?.label ?? item.label,
-      href: localizeHref(item.href, lang),
-      isExternal: isExternal(item.href),
-    })),
-  }));
-
-  // ── Tag columns (optional) ───────────────────────────────────────────────
-
-  let tagColumns: FooterTagColumn[] = [];
-
-  if (taglist?.enabled) {
-    // Memoize docs loading and tag aggregation on the snapshot-anchored stable
-    // docs identity — same pattern as _nav-source-cache — so this block runs
-    // once per locale per build, not once per page render.
-    const allTags = (() => {
-      if (lang === defaultLocale) {
-        const baseDocs = stableDocs("docs");
-        return memoizeDerived([baseDocs], "footerTaglist;default", () => {
-          // category_no_page index files build no route — drop them so the
-          // footer taglist matches the tag-route pages (which all now filter too).
-          const docs: DocsEntry[] = baseDocs.filter(
-            (d) => !d.data.draft && !d.data.unlisted && !d.data.category_no_page,
-          );
-          const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
-          return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
-        });
-      }
-      // Apply the default-locale-only filter so the footer taglist only counts
-      // tags that have a locale-routable tag page — matching the tag-route
-      // pages ([tag].tsx / tags/index.tsx) and enumerateTagsRoutes, which all
-      // now filter. Without this, the footer would link to /{locale}/docs/tags/
-      // pages that are never built for tags living only on default-locale-only
-      // prefix pages. category_no_page is dropped for the same reason — AFTER
-      // the merge, so a locale override carrying the flag first wins the merge
-      // (pre-merge filtering would let the unflagged base doc resurface).
-      const baseDocs = stableDocs("docs");
-      const localeDocs = stableDocs(`docs-${lang}`);
-      return memoizeDerived([baseDocs, localeDocs], `footerTaglist;${lang}`, () => {
-        const result = mergeLocaleDocs({
-          baseDocs: baseDocs.filter((d) => !d.data.draft),
-          localeDocs: localeDocs.filter((d) => !d.data.draft),
-          applyDefaultLocaleOnlyFilter: true,
-        });
-        const docs: DocsEntry[] = result.docs.filter((d) => !d.data.category_no_page);
-        const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
-        return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
-      });
-    })();
-
-    const vocabularyActive =
-      Boolean(settings.tagVocabulary) && settings.tagGovernance !== "off";
-    const requestedGroupBy = taglist.groupBy ?? "group";
-    const effectiveGroupBy = vocabularyActive ? requestedGroupBy : "flat";
-
-    const localeOverrides = (taglist.locales as Record<string, { title?: string; groupTitles?: Record<string, string> }> | undefined)?.[lang];
-    const groupTitles: Record<string, string> = {
-      ...taglist.groupTitles,
-      ...localeOverrides?.groupTitles,
-    };
-    const flatTitle = localeOverrides?.title ?? taglist.title ?? "Tags";
-
-    if (effectiveGroupBy === "flat" || !vocabularyActive) {
-      if (allTags.length > 0) {
-        tagColumns = [
-          {
-            group: "__flat__",
-            title: flatTitle,
-            tags: allTags.map(({ tag, count }) => ({
-              tag,
-              count,
-              href: tagHref(tag, lang),
-            })),
-          },
-        ];
-      }
-    } else {
-      // Grouped mode: one column per vocabulary group, in declaration order.
-      const groupByCanonical = new Map<string, string>();
-      const groupOrder: string[] = [];
-      const seenGroups = new Set<string>();
-      for (const entry of tagVocabulary) {
-        if (!entry.group) continue;
-        groupByCanonical.set(entry.id, entry.group);
-        if (!seenGroups.has(entry.group)) {
-          seenGroups.add(entry.group);
-          groupOrder.push(entry.group);
-        }
-      }
-
-      const buckets = new Map<string, typeof allTags>();
-      for (const group of groupOrder) buckets.set(group, []);
-      const ungrouped: typeof allTags = [];
-
-      for (const info of allTags) {
-        const group = groupByCanonical.get(info.tag);
-        if (group && buckets.has(group)) {
-          buckets.get(group)!.push(info);
-        } else {
-          ungrouped.push(info);
-        }
-      }
-
-      tagColumns = groupOrder
-        .filter((g) => (buckets.get(g)?.length ?? 0) > 0)
-        .map((g) => ({
-          group: g,
-          title:
-            groupTitles[g] ??
-            g.charAt(0).toUpperCase() + g.slice(1),
-          tags: buckets.get(g)!.map(({ tag, count }) => ({
-            tag,
-            count,
-            href: tagHref(tag, lang),
-          })),
-        }));
-
-      if (ungrouped.length > 0) {
-        tagColumns.push({
-          group: "__flat__",
-          title: flatTitle,
-          tags: ungrouped.map(({ tag, count }) => ({
-            tag,
-            count,
-            href: tagHref(tag, lang),
-          })),
-        });
-      }
-    }
-  }
-
-  return (
-    <Footer
-      linkColumns={linkColumns}
-      tagColumns={tagColumns}
-      copyright={copyright}
-      persistKey={persistKey}
-    />
-  );
-}
+export const FooterWithDefaults = createFooterWithDefaults({
+  settings,
+  defaultLocale,
+  tagVocabulary,
+  isExternal,
+  resolveHref,
+  withBase,
+  loadTagsForLocale,
+});

package/templates/base/pages/lib/_frontmatter-preview-data.ts

@@ -17,37 +17,11 @@
 // are wired by the page template directly on the `<FrontmatterPreview>` call site
 // via the `renderers` prop. This helper only produces the filtered entries array.
 
+import { createBuildFrontmatterPreviewEntries } from "@takazudo/zudo-doc/frontmatter-preview-data";
 import { settings } from "@/config/settings";
 import { DEFAULT_FRONTMATTER_IGNORE_KEYS } from "@/config/frontmatter-preview-defaults";
 
-export function buildFrontmatterPreviewEntries(
-  data: Record<string, unknown> | null | undefined,
-): Array<[string, unknown]> {
-  if (!data) return [];
-
-  // `frontmatterPreview` may be absent (undefined) in fixtures that
-  // don't opt into the feature. `false` means the host explicitly
-  // disabled the block. Both should produce an empty entries array.
-  const config = (settings as { frontmatterPreview?: unknown })
-    .frontmatterPreview;
-  if (config === false || config === undefined) return [];
-
-  const cfg = config as {
-    ignoreKeys?: string[];
-    extraIgnoreKeys?: string[];
-  };
-  const ignoreSet = new Set<string>(
-    cfg.ignoreKeys ?? [
-      ...DEFAULT_FRONTMATTER_IGNORE_KEYS,
-      ...(cfg.extraIgnoreKeys ?? []),
-    ],
-  );
-
-  const entries: Array<[string, unknown]> = [];
-  for (const [key, value] of Object.entries(data)) {
-    if (ignoreSet.has(key)) continue;
-    if (value === null || value === undefined) continue;
-    entries.push([key, value]);
-  }
-  return entries;
-}
+export const buildFrontmatterPreviewEntries = createBuildFrontmatterPreviewEntries({
+  frontmatterPreview: settings.frontmatterPreview,
+  defaultIgnoreKeys: DEFAULT_FRONTMATTER_IGNORE_KEYS,
+});