create-zudo-doc 0.2.21 → 1.0.0

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

@@ -1,57 +1,6 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Locale-/version-aware Header wrapper for the zfb doc pages.
-//
-// Header data-prep utilities — builds the resolved header config from user
-// settings + page context: header nav, active-path state, mobile SidebarToggle
-// island (hamburger + slide-in panel) with the full sidebar tree for doc routes,
-// and feeds everything into the v2 <Header> shell.
-//
-// Why this wrapper exists: the v2 Header shell is intentionally
-// framework-agnostic — it accepts slot props (sidebarToggle, themeToggle,
-// etc.) but does not import host helpers (@/config/*, @/utils/*) so the
-// package can be published independently. The data prep stays on the host
-// side. Without this wrapper the zfb doc pages fall through to the
-// DocLayoutWithDefaults minimal default (a bare <header> with only
-// <ThemeToggle>) — the full logo + nav + mobile-sidebar markup is absent
-// from the SSG output, breaking crawlers, screen readers, and no-JS users.
-//
-// Mobile sidebar strategy:
-//   - The v2 <Header> accepts a `sidebarToggle` slot that holds the
-//     complete mobile sidebar widget: hamburger button + backdrop overlay +
-//     slide-in <aside> panel (all rendered by <SidebarToggle>).
-//   - This wrapper ALWAYS builds the sidebarToggle (refs #1453:
-//     SidebarToggle is rendered unconditionally on every page; the host CSS
-//     hides it on pages with hide_sidebar). When `navSection` is defined the
-//     panel gets the full section tree; when undefined (home, 404, tags,
-//     versions) nodes=[] so the panel shows only rootMenuItems.
-//   - The bare package ThemeToggle (wrapped in Island below) is always passed
-//     to Header.themeToggle so the ThemeToggle island marker appears in the
-//     header on every page — matching the documented header contract.
-//
-// Locale switcher strategy (refs #1453):
-//   - This wrapper always renders <LanguageSwitcher /> in the right-items row
-//     when multiple locales are configured. Builds locale links from
-//     buildLocaleLinks() and passes a <LanguageSwitcher> as the
-//     languageSwitcher slot prop.
-//   - Header only renders the slot when settings.locales has > 1 entry, so
-//     single-locale projects are unaffected.
-
-import type { VNode, JSX } from "preact";
-import { Island } from "@takazudo/zfb";
-import { Header } from "@takazudo/zudo-doc/header";
-import {
-  LanguageSwitcher,
-  VersionSwitcher,
-  type VersionSwitcherLabels,
-} from "@takazudo/zudo-doc/i18n-version";
-// The bare (non-island-wrapped) package ThemeToggle, imported straight from
-// the npm subpath: zfb >= 0.1.0-next.39 scans "use client" modules under
-// node_modules (zfb#999/#1001), so the marker registers without the former
-// project-source shim (#2048/#2057). This header composes its own Island
-// below, avoiding nesting an island inside an island.
-import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";
-import SidebarToggle from "@/components/sidebar-toggle";
+// Host thin-stub — see @takazudo/zudo-doc/header-with-defaults (epic #2344, S5).
 import { settings } from "@/config/settings";
 import { defaultLocale, locales, t, type Locale } from "@/config/i18n";
 import { buildGitHubRepoUrl } from "@/utils/github";
@@ -62,7 +11,7 @@ import {
   versionedDocsUrl,
   withBase,
 } from "@/utils/base";
-import { filterHeaderRightItems } from "@takazudo/zudo-doc/header";
+import { createHeaderWithDefaults } from "@takazudo/zudo-doc/header-with-defaults";
 import { SearchWidget } from "./_search-widget";
 import {
   buildRootMenuItems,
@@ -71,275 +20,26 @@ import {
   getThemeDefaultMode,
 } from "./_nav-data-prep";
 
-// ---------------------------------------------------------------------------
-// Component
-// ---------------------------------------------------------------------------
-
-export interface HeaderWithDefaultsProps {
-  /** Active locale; defaults to the configured defaultLocale. */
-  lang?: Locale | string;
-  /**
-   * Current page URL path (as the layout passes from Astro.url.pathname or
-   * the zfb equivalent). Used by the Header to compute the active nav item
-   * and by the mobile sidebar footer locale-switcher links.
-   */
-  currentPath?: string;
-  /** Active version slug, when rendering inside /v/{version}/... routes. */
-  currentVersion?: string;
-  /**
-   * Slug of the active doc page — forwarded to SidebarTree so it can
-   * highlight the current entry. Required when navSection is set.
-   */
-  currentSlug?: string;
-  /**
-   * Header-nav category matcher used to scope the sidebar tree (e.g.
-   * "guides"). When provided the mobile sidebar toggle is wired with the
-   * full sidebar tree for this section. When omitted (404, index, tags,
-   * versions pages) no mobile sidebar toggle is included in the header.
-   */
-  navSection?: string;
-}
-
-/**
- * Default-bearing host wrapper around v2's <Header> shell.
- *
- * Handles:
- *  1. Logo, main nav with active-path highlight — delegated to <Header>.
- *  2. ThemeToggle island in the right items row — passed as themeToggle slot.
- *  3. Mobile SidebarToggle island (hamburger + slide-in aside + tree) —
- *     built from the same nav data as SidebarWithDefaults and passed as
- *     the sidebarToggle slot when navSection is defined.
- */
-export function HeaderWithDefaults(
-  props: HeaderWithDefaultsProps,
-): JSX.Element {
-  const {
-    lang: langProp = defaultLocale,
-    currentPath = "",
-    currentVersion,
-    currentSlug,
-    navSection,
-  } = props;
-  // Route params arrive as `string`; cast to Locale since keys of settings.locales
-  // are always valid locale codes. The prop accepts `Locale | string` so callers
-  // without a Locale variable don't need to cast (e.g. _tag-pages.tsx).
-  const lang = langProp as Locale;
-
-  // Root-menu items, locale links, sidebar nodes, and theme mode — all
-  // delegated to the shared _nav-data-prep helpers so header and sidebar
-  // wrappers stay in sync without duplicating the logic.
-  const rootMenuItems = buildRootMenuItems(lang, currentVersion);
-
-  // Build the mobile sidebar toggle unconditionally — SidebarToggle is rendered
-  // on every page (refs #1453); the host CSS hides it where unneeded. When navSection is
-  // defined the panel gets the full section tree; when undefined (home, 404,
-  // tags, versions) nodes=[] so the panel shows only rootMenuItems + locale
-  // links (the basic nav menu without a doc tree).
-  const backToMenuLabel = t("nav.backToMenu", lang);
-
-  // Locale-switcher links in the mobile sidebar footer — only when
-  // multiple locales are configured (mirrors _sidebar-with-defaults.tsx).
-  const localeLinks = buildLocaleLinksForNav(currentPath, lang, locales.length);
-
-  const themeDefaultMode = getThemeDefaultMode();
-
-  const sidebarNodes = buildSidebarNodes(lang, navSection, currentVersion);
-
-  // Wrap SidebarToggle (hamburger button + slide-in aside + SidebarTree) in
-  // Island so the SSG output carries the full tree HTML AND the
-  // data-zfb-island="SidebarToggle" marker for client-side hydration.
-  // Island.captureComponentName reads SidebarToggle.name → "SidebarToggle".
-  //
-  // SidebarTree's data props (nodes, currentSlug, rootMenuItems, …) are
-  // passed to SidebarToggle directly rather than as JSX children so they
-  // ride across the SSR → hydrate boundary in the Island marker's
-  // `data-props` attribute. Island only serialises a wrapped child
-  // component's *own* props (excluding `children`); when SidebarTree was
-  // nested as a JSX child its data was dropped during hydration and
-  // SidebarToggle re-rendered with `children=undefined`, wiping the SSR
-  // tree DOM. zudolab/zudo-doc#1355 wave 13.5.
-  //
-  // C4 — media-gated hydration.  zfb only supports load|idle|visible
-  // strategies (no "media" strategy; matchMedia inside the component is too
-  // late — props are already emitted, bundle already downloaded).
-  // Upstream feature request: Takazudo/zudo-front-builder#969.
-  //
-  // Best achievable downstream: when="visible" + all SidebarToggle children
-  // are lg:hidden, so on desktop the Island wrapper div has zero rendered
-  // dimensions.  IntersectionObserver fires isIntersecting=false on desktop
-  // (zero-size element) → Preact hydrate() is never called.  On mobile (and
-  // on desktop→mobile resize) the children become visible, the element gains
-  // size, IO fires isIntersecting=true, and hydration completes normally.
-  //
-  // Residual: data-props JSON (~2.4 KB) is still emitted in the SSR HTML on
-  // every page regardless of viewport, because it is serialised at build time
-  // and not gated by media. Eliminating it requires a zfb "media" hydration
-  // strategy — tracked in Takazudo/zudo-front-builder#969.
-  const sidebarToggle = Island({
-    when: "visible",
-    children: (
-      <SidebarToggle
-        nodes={sidebarNodes}
-        currentSlug={currentSlug}
-        rootMenuItems={rootMenuItems}
-        backToMenuLabel={backToMenuLabel}
-        localeLinks={localeLinks}
-        themeDefaultMode={themeDefaultMode}
-      />
-    ),
-  }) as unknown as VNode;
-
-  // Wrap the bare ThemeToggle in Island({when:"load"}) so the SSG
-  // output emits a data-zfb-island="ThemeToggle" marker the hydration
-  // runtime can find — matching the documented header contract.
-  const themeToggle = Island({
-    when: "load",
-    children: <ThemeToggle defaultMode={themeDefaultMode} />,
-  }) as unknown as VNode;
-
-  // Locale-aware search widget. Renders the full dialog markup in SSR
-  // so the placeholder text ("Type to search..." / 「検索したい単語を入力」)
-  // and keyboard-shortcut hint appear in the static HTML on every page.
-  // Strings are derived from the host's t() helper so locale switching works.
-  const searchWidget = (
-    <SearchWidget
-      placeholderText={t("search.placeholder", lang)}
-      shortcutHint={t("search.shortcutHint", lang)}
-      resultCountTemplate={t("search.resultCount", lang)}
-      searchLabel={t("search.label", lang)}
-    />
-  );
+export type { HeaderWithDefaultsProps } from "@takazudo/zudo-doc/header-with-defaults";
 
-  // Build the version-switcher component when versioning is configured.
-  // The VersionSwitcher is a pure SSR component — it emits the full dropdown
-  // markup (including the "All versions" footer link) directly in the SSG
-  // HTML so crawlers and JS-off users see the version list. The interactive
-  // toggle behavior is wired by VERSION_SWITCHER_INIT_SCRIPT included in
-  // the layout's body-end scripts.
-  //
-  // Gate: only render when settings.versions is a non-empty array. When
-  // versioning is disabled (settings.versions === false) the slot is
-  // undefined and the Header renders nothing for the version-switcher item.
-  let versionSwitcher: VNode | undefined;
-
-  if (settings.versions && settings.versions.length > 0) {
-    const isNonDefaultLocale = lang !== defaultLocale;
-    // "All versions" page URL — locale-prefixed when not on the default locale.
-    const versionsPageUrl = withBase(
-      isNonDefaultLocale ? `/${lang}/docs/versions` : "/docs/versions",
-    );
-    // "Latest" entry links to the current page in the latest (unversioned)
-    // docs when a slug is available, or falls back to the versions index page.
-    // Null check, not truthiness: "" is the canonical root-index slug (#1891)
-    // and must produce real per-version root URLs.
-    const latestUrl = currentSlug != null
-      ? docsUrl(currentSlug, lang)
-      : versionsPageUrl;
-
-    // Per-version URLs for the current page. When there is no slug in scope
-    // (e.g. on the versions page itself) all entries point to the versions
-    // index — matching the documented version-switcher contract.
-    const versionUrls: Record<string, string> = {};
-    for (const v of settings.versions) {
-      versionUrls[v.slug] = currentSlug != null
-        ? versionedDocsUrl(currentSlug, v.slug, lang)
-        : versionsPageUrl;
-    }
-
-    const labels: VersionSwitcherLabels = {
-      latest: t("version.latest", lang),
-      switcher: t("version.switcher.label", lang),
-      unavailable: t("version.switcher.unavailable", lang),
-      allVersions: t("version.switcher.allVersions", lang),
-    };
-
-    versionSwitcher = (
-      <VersionSwitcher
-        versions={settings.versions.map((v) => ({
-          slug: v.slug,
-          label: v.label ?? v.slug,
-        }))}
-        currentVersion={currentVersion}
-        latestUrl={latestUrl}
-        versionsPageUrl={versionsPageUrl}
-        versionUrls={versionUrls}
-        labels={labels}
-        idSuffix="header"
-      />
-    ) as unknown as VNode;
-  }
-
-  // Build locale-switcher for the header right-items row (refs #1453).
-  // Renders <LanguageSwitcher /> when multiple locales are configured.
-  // Reuses the same localeLinks array built above for the mobile sidebar footer
-  // (buildLocaleLinks is pure, but one call is cleaner).
-  const languageSwitcher =
-    localeLinks != null ? (
-      <LanguageSwitcher
-        links={localeLinks}
-      />
-    ) as unknown as VNode : undefined;
-
-  // Locale-keyed persist key: same-locale swaps preserve the header's
-  // DOM-node identity; cross-locale swaps use a different key and the
-  // router replaces the header entirely (re-rendering locale-specific
-  // SSR content such as the LanguageSwitcher anchors). See #1546 + #1549.
-  const persistKey = `header-${lang}`;
-
-  // Compute the right-items flags from the host's settings. The v2
-  // `<Header>` no longer consults `@/config/settings` directly — see
-  // sub-issue #1729 — so the wrapper is responsible for translating
-  // host state into the prop bag the renderer expects. Boolean
-  // coercion mirrors the original filter predicates verbatim.
-  const headerRightItems = filterHeaderRightItems(
-    settings.headerRightItems ?? [],
-    {
-      designTokenPanel: Boolean(settings.designTokenPanel),
-      aiAssistant: Boolean(settings.aiAssistant),
-      colorMode: Boolean(settings.colorMode),
-      hasLocales: Object.keys(settings.locales).length > 0,
-      hasVersions: Boolean(settings.versions),
-      hasGithubUrl: Boolean(settings.githubUrl),
-    },
-  );
-
-  const githubRepoUrl = buildGitHubRepoUrl();
-  const githubLabel = t("header.github", lang);
-
-  return (
-    <Header
-      lang={lang}
-      currentPath={currentPath}
-      currentVersion={currentVersion}
-      activeCategory={navSection}
-      sidebarToggle={sidebarToggle}
-      themeToggle={themeToggle}
-      search={searchWidget}
-      versionSwitcher={versionSwitcher}
-      languageSwitcher={languageSwitcher}
-      persistKey={persistKey}
-      siteName={settings.siteName}
-      headerNav={settings.headerNav}
-      headerRightItems={headerRightItems}
-      colorModeEnabled={Boolean(settings.colorMode)}
-      hasLocales={locales.length > 1}
-      hasVersions={Boolean(settings.versions)}
-      githubRepoUrl={githubRepoUrl}
-      githubLabel={githubLabel}
-      urlHelpers={{
-        withBase,
-        stripBase,
-        // `navHref` from `@/utils/base` types the lang param as the
-        // host's literal-locale union; v2's `Locale` is `string`. Wrap
-        // so strictFunctionTypes accepts the assignment without losing
-        // the runtime call shape (sub-issue #1729 boundary widening).
-        navHref: (path, l, v) => navHref(path, l as Locale | undefined, v),
-      }}
-      i18n={{
-        defaultLocale,
-        locales,
-        t,
-      }}
-    />
-  );
-}
+export const HeaderWithDefaults = createHeaderWithDefaults({
+  settings,
+  defaultLocale,
+  locales,
+  t: (key, lang) => t(key as Parameters<typeof t>[0], lang as Locale),
+  withBase,
+  stripBase,
+  docsUrl: (slug, lang) => docsUrl(slug, lang as Locale),
+  navHref: (path, lang, version) => navHref(path, lang as Locale | undefined, version),
+  versionedDocsUrl: (slug, versionSlug, lang) =>
+    versionedDocsUrl(slug, versionSlug, lang as Locale),
+  buildLocaleLinksForNav: (currentPath, lang, localeCount) =>
+    buildLocaleLinksForNav(currentPath, lang as Locale, localeCount),
+  buildRootMenuItems: (lang, currentVersion) =>
+    buildRootMenuItems(lang as Locale, currentVersion),
+  buildSidebarNodes: (lang, navSection, currentVersion) =>
+    buildSidebarNodes(lang as Locale, navSection, currentVersion),
+  getThemeDefaultMode,
+  buildGitHubRepoUrl,
+  SearchWidget,
+});

package/templates/base/pages/lib/_inline-version-switcher.tsx

@@ -1,85 +1,23 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Inline VersionSwitcher for the breadcrumb rightSlot on doc pages.
-//
-// The reference site (takazudomodular.com) renders the version-switcher
-// pill inline at the right of the breadcrumb row on every doc page:
-//
-//   <div class="mb-vsp-sm flex ... sm:justify-between [&_nav]:mb-0">
-//     <breadcrumb nav>
-//     <VersionSwitcher ... />
-//   </div>
-//
-// (Wave 2 parity sweep, zudolab/zudo-doc#1478; placement fix #1534.)
-// The header already shows a VersionSwitcher via _header-with-defaults.tsx;
-// this helper provides the pill for the breadcrumb's `rightSlot` prop so
-// both the DOM position AND the flex-row layout match the reference.
-//
-// Gate: only returns a non-null element when settings.versions is a
-// non-empty array. When versioning is disabled the caller gets undefined
-// and <Breadcrumb> renders without a rightSlot (no wrapper div emitted).
+// Thin stub — inline-version-switcher moved to the package (epic #2344, S8).
+// Calls `createInlineVersionSwitcher(deps)` from
+// @takazudo/zudo-doc/inline-version-switcher with host singletons injected,
+// then re-exports the resulting builder so all existing call sites continue
+// to work unchanged.
 
-import type { JSX } from "preact";
-import {
-  VersionSwitcher,
-  type VersionSwitcherLabels,
-} from "@takazudo/zudo-doc/i18n-version";
+import { createInlineVersionSwitcher } from "@takazudo/zudo-doc/inline-version-switcher";
 import { settings } from "@/config/settings";
-import { defaultLocale, t, type Locale } from "@/config/i18n";
+import { defaultLocale, t } from "@/config/i18n";
 import { docsUrl, versionedDocsUrl, withBase } from "@/utils/base";
 
-/**
- * Build an inline VersionSwitcher element for the `<Breadcrumb rightSlot>` prop.
- *
- * Returns `undefined` when versioning is not configured (callers can pass
- * the return value directly as `rightSlot` — `<Breadcrumb>` renders the
- * plain nav (no flex wrapper, no version pill) when `rightSlot` is
- * `undefined`).
- *
- * @param slug       - Slug of the current doc page (used to build per-version URLs).
- * @param locale     - Active locale string.
- * @param currentVersion - Active version slug, or `undefined` on the "latest" route.
- */
-export function buildInlineVersionSwitcher(
-  slug: string,
-  locale: Locale,
-  currentVersion?: string,
-): JSX.Element | undefined {
-  if (!settings.versions || settings.versions.length === 0) return undefined;
+export { type InlineVersionSwitcherVersionEntry } from "@takazudo/zudo-doc/inline-version-switcher";
 
-  const isNonDefaultLocale = locale !== defaultLocale;
-  const versionsPageUrl = withBase(
-    isNonDefaultLocale ? `/${locale}/docs/versions` : "/docs/versions",
-  );
-  // The docs root index has the canonical empty slug "" (#1891), and
-  // docsUrl("")/versionedDocsUrl("") resolve to the per-version docs roots —
-  // so an empty slug must NOT fall back to the versions page.
-  const latestUrl = docsUrl(slug, locale);
-
-  const versionUrls: Record<string, string> = {};
-  for (const v of settings.versions) {
-    versionUrls[v.slug] = versionedDocsUrl(slug, v.slug, locale);
-  }
-
-  const labels: VersionSwitcherLabels = {
-    latest: t("version.latest", locale),
-    switcher: t("version.switcher.label", locale),
-    unavailable: t("version.switcher.unavailable", locale),
-    allVersions: t("version.switcher.allVersions", locale),
-  };
-
-  return (
-    <VersionSwitcher
-      versions={settings.versions.map((v) => ({
-        slug: v.slug,
-        label: v.label ?? v.slug,
-      }))}
-      currentVersion={currentVersion}
-      latestUrl={latestUrl}
-      versionsPageUrl={versionsPageUrl}
-      versionUrls={versionUrls}
-      labels={labels}
-      idSuffix="inline"
-    />
-  );
-}
+export const buildInlineVersionSwitcher = createInlineVersionSwitcher({
+  settings,
+  defaultLocale,
+  t,
+  docsUrl,
+  versionedDocsUrl,
+  withBase,
+});

package/templates/base/pages/lib/_math-block.tsx

@@ -1,63 +1,4 @@
-/** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-// MathBlock — server-rendered KaTeX component for MDX math expressions.
-//
-// Registered in pages/_mdx-components.ts as `MathBlock` so the MDX corpus
-// can reference it as <MathBlock latex="…" block />.
-//
-// Used by the math-equations.mdx content files (both EN and JA) which write
-// `<MathBlock>` JSX directly instead of `$$…$$` fences. The explicit JSX
-// form is required because the zfb Rust MDX→JSX emitter does not understand
-// remark-math `$$…$$` syntax — LaTeX identifiers like `\infty` become invalid
-// JSX expressions `{\infty}` that esbuild rejects (zudo-front-builder #93).
-// Using `<MathBlock>` directly keeps the LaTeX inside a string attribute,
-// which esbuild accepts cleanly.
-//
-// Rendering: katex.renderToString() is called at SSR time — no client JS.
-// `throwOnError: false` keeps a broken formula visible as an error span
-// rather than crashing the page.
-
-import katex from "katex";
-import type { VNode } from "preact";
-
-interface MathBlockProps {
-  /** Raw LaTeX source string. */
-  latex: string;
-  /** When true, renders as a block (display) equation; otherwise inline. */
-  block?: boolean;
-}
-
-/**
- * Server-rendered KaTeX math component.
- *
- * Block mode wraps the output in `<div class="math math-display">`;
- * inline mode uses `<span class="math math-inline">`. The class names
- * match the standard rehype-katex output so existing CSS (e.g. the
- * KaTeX stylesheet) still applies.
- */
-export function MathBlock({ latex, block = false }: MathBlockProps): VNode {
-  const html = katex.renderToString(latex, {
-    displayMode: block,
-    // Never throw — malformed LaTeX renders a visible error span instead
-    // of crashing the entire page build.
-    throwOnError: false,
-  });
-
-  if (block) {
-    return (
-      <div
-        class="math math-display"
-        // eslint-disable-next-line react/no-danger
-        dangerouslySetInnerHTML={{ __html: html }}
-      />
-    );
-  }
-
-  return (
-    <span
-      class="math math-inline"
-      // eslint-disable-next-line react/no-danger
-      dangerouslySetInnerHTML={{ __html: html }}
-    />
-  );
-}
+// Re-export from the shared package — moved to @takazudo/zudo-doc/math-block
+// as part of the package-first migration (epic #2321, S4 #2327).
+export type { MathBlockProps } from "@takazudo/zudo-doc/math-block";
+export { MathBlock } from "@takazudo/zudo-doc/math-block";

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);
 }