create-zudo-doc 0.2.20 → 0.2.22

package/templates/base/pages/lib/_nav-data-prep.ts

@@ -1,9 +1,10 @@
-// Shared nav data-prep utilities used by both _header-with-defaults.tsx
-// and _sidebar-with-defaults.tsx.
+// Host thin-stub for nav data-prep utilities (epic #2344, S5).
+// Imports core logic from @takazudo/zudo-doc and wires host singletons.
 //
-// Extracted to avoid maintaining four near-identical copies: the two host
-// modules above plus their template mirrors under
-// packages/create-zudo-doc/templates/base/pages/lib/.
+// Package exports the pure parameterized functions; this stub binds
+// them to the host's `settings`, `i18n`, and `base` singletons so
+// existing call sites (_header-with-defaults.tsx, _sidebar-with-defaults.tsx)
+// are unchanged.
 
 import { settings } from "@/config/settings";
 import { t, type Locale } from "@/config/i18n";
@@ -15,6 +16,12 @@ import {
 import { type NavNode } from "@/utils/docs";
 import { buildSidebarForSection } from "@/utils/sidebar";
 import { loadNavSourceDocs } from "./_nav-source-docs";
+import {
+  remapVersionedHrefs as _remapVersionedHrefs,
+  buildRootMenuItems as _buildRootMenuItems,
+  buildLocaleLinksForNav as _buildLocaleLinksForNav,
+  getThemeDefaultMode as _getThemeDefaultMode,
+} from "@takazudo/zudo-doc/nav-data-prep";
 
 // ---------------------------------------------------------------------------
 // remapVersionedHrefs
@@ -22,30 +29,18 @@ import { loadNavSourceDocs } from "./_nav-source-docs";
 
 /**
  * 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).
  */
 export 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 };
-  });
+  return _remapVersionedHrefs(
+    nodes,
+    version,
+    nodeLang,
+    (slug, v, lang) => versionedDocsUrl(slug, v, lang as Locale),
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -54,26 +49,18 @@ export function remapVersionedHrefs(
 
 /**
  * Root-menu items derived from settings.headerNav (mobile "back to menu" list).
- *
- * Used by both header and sidebar wrappers — the same nav data feeds both the
- * mobile SidebarToggle (header) and the desktop SidebarTree (sidebar).
  */
 export function buildRootMenuItems(
   lang: Locale,
   currentVersion?: string,
 ) {
-  return 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),
-    })),
-  }));
+  return _buildRootMenuItems(
+    lang,
+    currentVersion,
+    settings.headerNav,
+    (key, l) => t(key as Parameters<typeof t>[0], l as Locale),
+    (path, l, v) => navHref(path, l as Locale | undefined, v),
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -89,7 +76,12 @@ export function buildLocaleLinksForNav(
   lang: Locale,
   localeCount: number,
 ) {
-  return localeCount > 1 ? buildLocaleLinks(currentPath, lang) : undefined;
+  return _buildLocaleLinksForNav(
+    currentPath,
+    lang,
+    localeCount,
+    (path, l) => buildLocaleLinks(path, l as Locale),
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -98,17 +90,6 @@ export function buildLocaleLinksForNav(
 
 /**
  * Build the resolved sidebar node list for a given section + version.
- *
- * Loads the nav source, filters to the active section, then optionally
- * remaps hrefs for versioned routes.
- *
- * `emptyWhenUnsectioned` controls the `navSection === undefined` case —
- * the two legacy call sites deliberately disagreed: the header's mobile
- * drawer returned `[]` (root menu only), while the desktop sidebar fell
- * through to `buildSidebarForSection(..., undefined)` = the FULL tree
- * (pages whose slug matches no headerNav categoryMatch still get a
- * sidebar). Collapsing both to `[]` shipped an empty desktop sidebar for
- * unsectioned pages — keep the divergence explicit here.
  */
 export function buildSidebarNodes(
   lang: Locale,
@@ -133,5 +114,5 @@ export function buildSidebarNodes(
  * Returns `undefined` when color mode is not configured (single-scheme projects).
  */
 export function getThemeDefaultMode() {
-  return settings.colorMode ? settings.colorMode.defaultMode : undefined;
+  return _getThemeDefaultMode(settings.colorMode);
 }

package/templates/base/pages/lib/_nav-source-cache.ts

@@ -32,11 +32,21 @@
 // HMR intent preserved: a content edit produces a NEW snapshot object (new
 // `collections[name]` array identity), so every memo here misses and
 // recomputes — matching the old content-keyed cache's change detection.
+//
+// PACKAGE SPLIT (epic #2344, S6):
+//   `memoizeDerived` — the generic two-level WeakMap memo — is now in the
+//   package at @takazudo/zudo-doc/nav-source-cache (no zfb imports needed).
+//   `stableDocs` stays here because it imports `getCollection` /
+//   `getContentSnapshot` from "zfb/content", which is a virtual module
+//   provided by the zfb SSG build system at compile time — not an npm package.
 
 import { getCollection, getContentSnapshot } from "zfb/content";
 import { bridgeDocsEntries, type ZfbDocsData } from "../_data";
 import type { DocPageEntry } from "./doc-page-props";
 
+// Re-export memoizeDerived from the package (pure, no zfb dep).
+export { memoizeDerived } from "@takazudo/zudo-doc/nav-source-cache";
+
 // ---------------------------------------------------------------------------
 // Snapshot anchor → stable bridged arrays
 // ---------------------------------------------------------------------------
@@ -70,6 +80,8 @@ function buildBridged(collectionName: string): DocPageEntry[] {
  * `buildNavTree` — can rely on reference equality. The entries carry the full
  * `DocPageEntry` shape (Content, body, module_specifier, id, collection) the
  * route `paths()` props need.
+ *
+ * Passed as `stableDocs` to `createNavSourceDocs` in `_nav-source-docs.ts`.
  */
 export function stableDocs(collectionName: string): DocPageEntry[] {
   const anchor = snapshotAnchor(collectionName);
@@ -86,60 +98,3 @@ export function stableDocs(collectionName: string): DocPageEntry[] {
   bridgedByAnchor.set(anchor, built);
   return built;
 }
-
-// ---------------------------------------------------------------------------
-// Generic derived-array memo (merge / filter results)
-// ---------------------------------------------------------------------------
-
-// Two-level memo: a WeakMap on the FIRST stable input array (so a new snapshot
-// drops the whole sub-map), then a string key combining the remaining stable
-// inputs' identities and the option signature.
-const derivedMemo = new WeakMap<object, Map<string, unknown>>();
-// Per-build incrementing ids for stable arrays, so a multi-array key can be a
-// cheap string. Lives in a WeakMap so it does not retain arrays past their
-// snapshot.
-const arrayId = new WeakMap<object, number>();
-let nextArrayId = 1;
-function idOf(arr: object): number {
-  let id = arrayId.get(arr);
-  if (id === undefined) {
-    id = nextArrayId++;
-    arrayId.set(arr, id);
-  }
-  return id;
-}
-
-// Anchor object for the rare case of an empty `inputs` array (e.g. an absent
-// locale collection). Lets the WeakMap still key the derived memo.
-const EMPTY_INPUT_ANCHOR: object = {};
-
-/**
- * Memoize a derived array (e.g. a locale merge or an `isNavVisible` filter)
- * on the identity of its stable inputs plus a caller-supplied option
- * signature.
- *
- * `inputs` MUST be the stable arrays returned by {@link stableDocs} (or arrays
- * derived from them through this same helper) — passing a fresh array defeats
- * the memo. `optionSig` distinguishes call sites that differ only in filter
- * options (e.g. `applyDefaultLocaleOnlyFilter`, `keepUnlisted`), so they never
- * collide on the same key.
- */
-export function memoizeDerived<T>(
-  inputs: readonly object[],
-  optionSig: string,
-  compute: () => T,
-): T {
-  const primary = inputs[0] ?? EMPTY_INPUT_ANCHOR;
-  let sub = derivedMemo.get(primary);
-  if (!sub) {
-    sub = new Map();
-    derivedMemo.set(primary, sub);
-  }
-  const key = `${inputs.map((a) => idOf(a)).join("/")}::${optionSig}`;
-  // Use has(): a legitimately-`undefined` computed result must still register
-  // as a cache hit, otherwise it recomputes every call.
-  if (sub.has(key)) return sub.get(key) as T;
-  const computed = compute();
-  sub.set(key, computed);
-  return computed;
-}

package/templates/base/pages/lib/_nav-source-docs.ts

@@ -1,237 +1,37 @@
-// Shared, identity-stable nav-source resolver.
-//
-// Picks the right collection(s) and category-meta dir for an active
-// (locale, version) pair, applying the locale-first + EN-fallback merge that
-// the doc-route `paths()` passes use, so every nav surface (desktop sidebar,
-// mobile SidebarToggle, route enumeration, MDX nav wrappers) sees the same
-// data the pages enumerate.
-//
-// IDENTITY STABILITY (why this is not a thin wrapper)
-// ---------------------------------------------------
-// Every returned `docs` / `navDocs` array and `categoryMeta` Map is memoized
-// so repeat callers within one build get the SAME instances. That is what lets
-// `buildNavTree`'s identity fast-path (`src/utils/docs.ts`) skip the O(n log n)
-// key computation on the ~900 calls a 251-page build makes. See
-// `_nav-source-cache.ts` for the snapshot-anchored memo and the original-issue
-// trace (zudolab/zudo-doc#1902 / #1882).
-//
-// Used by:
-//   - _sidebar-with-defaults.tsx / _header-with-defaults.tsx (per-page nav)
-//   - the 4 doc-route paths() files (route enumeration + nav tree)
-//   - route-enumerators.ts (sitemap) and the MDX nav wrappers
-// each picking the `NavSourceVariant` matching its filter needs.
-
-import { defaultLocale, getLocaleConfig, type Locale } from "@/config/i18n";
+// Thin stub — nav-source-docs moved to the package (epic #2344, S6).
+// Calls `createNavSourceDocs(ctx)` from @takazudo/zudo-doc/nav-source-docs
+// with the host singletons injected, then re-exports the resulting resolver
+// functions so all existing call sites continue to work unchanged.
+
+import { createNavSourceDocs } from "@takazudo/zudo-doc/nav-source-docs";
+export type { NavSourceDocs, NavSourceOptions } from "@takazudo/zudo-doc/nav-source-docs";
+import { defaultLocale, getLocaleConfig } from "@/config/i18n";
 import { settings } from "@/config/settings";
-import {
+import { loadCategoryMeta, isNavVisible } from "@/utils/docs";
+import { isDefaultLocaleOnlyPath } from "@/utils/base";
+import { stableDocs } from "./_nav-source-cache";
+
+const {
+  resolveNavSource,
+  resolveVersionedLocaleSource,
+  loadNavSourceDocs,
+  stableMergeCategoryMeta,
+  stableNavDocs,
+} = createNavSourceDocs({
+  defaultLocale,
+  docsDir: settings.docsDir,
+  getVersions: () => settings.versions,
+  getLocaleConfig,
   loadCategoryMeta,
   isNavVisible,
-  type CategoryMeta,
-} from "@/utils/docs";
-import type { DocsEntry } from "@/types/docs-entry";
-import type { DocPageEntry } from "./doc-page-props";
-import { stableDocs, memoizeDerived } from "./_nav-source-cache";
-import { mergeLocaleDocs } from "./locale-merge";
-
-// ---------------------------------------------------------------------------
-// Stable category-meta merge
-// ---------------------------------------------------------------------------
-
-// `loadCategoryMeta(dir)` is already memoized by dir (returns the same Map).
-// The locale merge of two such Maps, however, was minted fresh on every call —
-// breaking the `categoryMeta === categoryMeta` identity check in the nav-tree
-// fast-path. Memoize the merge on the (baseDir, localeDir) pair.
-const mergedCategoryMetaCache = new Map<string, Map<string, CategoryMeta>>();
-
-/** Base metadata first, locale overrides win on overlapping keys — same merge
- *  order the locale doc-route paths() use. Returns a STABLE Map per
- *  (baseDir, localeDir) pair. */
-export function stableMergeCategoryMeta(
-  baseDir: string,
-  localeDir: string,
-): Map<string, CategoryMeta> {
-  const key = `${baseDir}\n${localeDir}`;
-  const cached = mergedCategoryMetaCache.get(key);
-  if (cached) return cached;
-  const merged = new Map<string, CategoryMeta>([
-    ...loadCategoryMeta(baseDir),
-    ...loadCategoryMeta(localeDir),
-  ]);
-  mergedCategoryMetaCache.set(key, merged);
-  return merged;
-}
-
-// ---------------------------------------------------------------------------
-// Stable navDocs (isNavVisible filter) derived from a stable docs array
-// ---------------------------------------------------------------------------
-
-/** `docs.filter(isNavVisible)`, memoized on the stable `docs` identity so the
- *  filtered array also has stable identity for the nav-tree fast-path. */
-export function stableNavDocs<T extends DocsEntry>(docs: T[]): T[] {
-  return memoizeDerived([docs], "navVisible", () => docs.filter(isNavVisible));
-}
-
-// ---------------------------------------------------------------------------
-// Resolved nav source
-// ---------------------------------------------------------------------------
-
-export type NavSourceDocs = {
-  /** Full doc list (merged + draft-filtered; unlisted retained per options). */
-  docs: DocPageEntry[];
-  /** `docs.filter(isNavVisible)` — stable instance for buildNavTree. */
-  navDocs: DocPageEntry[];
-  /** Stable category-meta Map for the active (locale, version). */
-  categoryMeta: Map<string, CategoryMeta>;
-  /** Slugs that came from the locale collection (for isFallback). Empty for
-   *  default-locale / single-collection cases. */
-  localeSlugSet: ReadonlySet<string>;
+  isDefaultLocaleOnlyPath,
+  stableDocs,
+});
+
+export {
+  resolveNavSource,
+  resolveVersionedLocaleSource,
+  loadNavSourceDocs,
+  stableMergeCategoryMeta,
+  stableNavDocs,
 };
-
-/**
- * How to filter the merged doc list. The locale merge takes different options
- * at different call sites; the option signature is folded into the memo key so
- * variants never collide on a shared cache entry.
- */
-export interface NavSourceOptions {
-  /** Drop base docs matching `defaultLocaleOnlyPrefixes` (route/sidebar nav). */
-  applyDefaultLocaleOnlyFilter?: boolean;
-  /** Retain `unlisted: true` docs (route enumeration + nav). */
-  keepUnlisted?: boolean;
-}
-
-function optionSig(o: NavSourceOptions): string {
-  return `dlo=${o.applyDefaultLocaleOnlyFilter ? 1 : 0};ku=${o.keepUnlisted ? 1 : 0}`;
-}
-
-const EMPTY_SLUG_SET: ReadonlySet<string> = new Set();
-
-/**
- * Resolve the identity-stable nav source for an EN/locale (optionally
- * versioned) context. Every field is memoized so repeated calls with the same
- * logical inputs return the same instances.
- */
-export function resolveNavSource(
-  lang: Locale,
-  currentVersion: string | undefined,
-  options: NavSourceOptions = {},
-): NavSourceDocs {
-  const sig = optionSig(options);
-
-  // --- Versioned. For a non-default locale the version IS configured for,
-  //     delegate to resolveVersionedLocaleSource so every nav surface uses the
-  //     SAME version-scoped locale-first merge the page body / route
-  //     enumeration use (#1909) — keeping nav labels and locale-only version
-  //     pages in sync. Otherwise (default locale, or the version not configured
-  //     for this locale) fall back to the version's EN base collection.
-  if (currentVersion) {
-    // `versions` is `VersionConfig[] | false` — `false?.find` would throw
-    // (optional chaining only short-circuits on null/undefined).
-    const versionConfig = Array.isArray(settings.versions)
-      ? settings.versions.find((v) => v.slug === currentVersion)
-      : undefined;
-    const localeDir = versionConfig?.locales?.[lang]?.dir;
-    if (lang !== defaultLocale && localeDir) {
-      return resolveVersionedLocaleSource(
-        currentVersion,
-        versionConfig?.docsDir ?? settings.docsDir,
-        lang,
-        localeDir,
-        options,
-      );
-    }
-    const docs = stableDocs(`docs-v-${currentVersion}`);
-    const categoryMeta = loadCategoryMeta(versionConfig?.docsDir ?? settings.docsDir);
-    const navDocs = stableNavDocs(docs);
-    return { docs, navDocs, categoryMeta, localeSlugSet: EMPTY_SLUG_SET };
-  }
-
-  // --- Default locale: the "docs" collection directly.
-  if (lang === defaultLocale) {
-    const docs = stableDocs("docs");
-    const categoryMeta = loadCategoryMeta(settings.docsDir);
-    const navDocs = stableNavDocs(docs);
-    return { docs, navDocs, categoryMeta, localeSlugSet: EMPTY_SLUG_SET };
-  }
-
-  // --- Non-default locale: locale-first merge with EN fallback.
-  const baseDocs = stableDocs("docs");
-  const localeDocs = stableDocs(`docs-${lang}`);
-
-  const merged = memoizeDerived([baseDocs, localeDocs], `merge;${sig}`, () =>
-    mergeLocaleDocs<DocPageEntry>({
-      baseDocs,
-      localeDocs,
-      applyDefaultLocaleOnlyFilter: options.applyDefaultLocaleOnlyFilter,
-      keepUnlisted: options.keepUnlisted,
-    }),
-  );
-  const docs = merged.docs;
-
-  const localeDir = getLocaleConfig(lang)?.dir ?? settings.docsDir;
-  const categoryMeta = stableMergeCategoryMeta(settings.docsDir, localeDir);
-  const navDocs = stableNavDocs(docs);
-
-  return { docs, navDocs, categoryMeta, localeSlugSet: merged.localeSlugSet };
-}
-
-/**
- * Resolve the identity-stable nav source for a versioned non-default-locale
- * context — locale-specific version collection over the version's EN base.
- */
-export function resolveVersionedLocaleSource(
-  versionSlug: string,
-  versionDocsDir: string,
-  lang: Locale,
-  localeDir: string | undefined,
-  options: NavSourceOptions = {},
-): NavSourceDocs {
-  const sig = optionSig(options);
-  const baseDocs = stableDocs(`docs-v-${versionSlug}`);
-  const localeDocs = localeDir ? stableDocs(`docs-v-${versionSlug}-${lang}`) : EMPTY_DOCS;
-
-  const merged = memoizeDerived(
-    localeDir ? [baseDocs, localeDocs] : [baseDocs],
-    `vmerge;${lang};${sig}`,
-    () =>
-      mergeLocaleDocs<DocPageEntry>({
-        baseDocs,
-        localeDocs,
-        applyDefaultLocaleOnlyFilter: options.applyDefaultLocaleOnlyFilter,
-        keepUnlisted: options.keepUnlisted,
-      }),
-  );
-  const docs = merged.docs;
-
-  const categoryMeta = localeDir
-    ? stableMergeCategoryMeta(versionDocsDir, localeDir)
-    : loadCategoryMeta(versionDocsDir);
-  const navDocs = stableNavDocs(docs);
-
-  return { docs, navDocs, categoryMeta, localeSlugSet: merged.localeSlugSet };
-}
-
-// Shared empty array for the "no locale collection" branch — stable identity
-// keeps the merge memo consistent.
-const EMPTY_DOCS: DocPageEntry[] = [];
-
-// ---------------------------------------------------------------------------
-// Back-compat: loadNavSourceDocs (sidebar + header consumers)
-// ---------------------------------------------------------------------------
-
-/**
- * Per-page nav source for the desktop sidebar and mobile SidebarToggle.
- *
- * Thin adapter over {@link resolveNavSource} with the sidebar's filter options
- * (`applyDefaultLocaleOnlyFilter`, `keepUnlisted`). Returns `navDocs` already
- * filtered so callers pass it straight to `buildSidebarForSection` without a
- * fresh `.filter(isNavVisible)` that would defeat the nav-tree fast-path.
- */
-export function loadNavSourceDocs(
-  lang: Locale,
-  currentVersion: string | undefined,
-): NavSourceDocs {
-  return resolveNavSource(lang, currentVersion, {
-    applyDefaultLocaleOnlyFilter: true,
-    keepUnlisted: true,
-  });
-}