npm - create-zudo-doc - Versions diffs - 0.2.21 → 1.0.0 - Mend

create-zudo-doc 0.2.21 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (92) hide show

package/dist/compose.d.ts +6 -3
package/dist/compose.js +6 -4
package/dist/features/image-enlarge.d.ts +22 -12
package/dist/features/image-enlarge.js +23 -191
package/dist/scaffold.d.ts +11 -0
package/dist/scaffold.js +51 -24
package/dist/settings-gen.js +4 -0
package/dist/zfb-config-gen.d.ts +16 -10
package/dist/zfb-config-gen.js +34 -239
package/package.json +1 -1
package/templates/base/pages/_mdx-components.ts +64 -185
package/templates/base/pages/index.tsx +1 -1
package/templates/base/pages/lib/_body-end-islands.tsx +6 -13
package/templates/base/pages/lib/_category-nav.tsx +30 -115
package/templates/base/pages/lib/_category-tree-nav.tsx +38 -65
package/templates/base/pages/lib/_compose-meta-title.ts +2 -6
package/templates/base/pages/lib/_doc-body-end.tsx +3 -35
package/templates/base/pages/lib/_doc-content-header.tsx +10 -111
package/templates/base/pages/lib/_doc-history-area.tsx +19 -211
package/templates/base/pages/lib/_doc-metainfo-area.tsx +10 -113
package/templates/base/pages/lib/_doc-page-renderer.tsx +22 -183
package/templates/base/pages/lib/_doc-page-shell.tsx +17 -251
package/templates/base/pages/lib/_doc-pager.tsx +4 -74
package/templates/base/pages/lib/_doc-route-entries.ts +43 -177
package/templates/base/pages/lib/_doc-route-paths.ts +16 -101
package/templates/base/pages/lib/_doc-tags-area.tsx +14 -77
package/templates/base/pages/lib/_extract-headings.ts +21 -295
package/templates/base/pages/lib/_footer-with-defaults.tsx +37 -225
package/templates/base/pages/lib/_frontmatter-preview-data.ts +5 -31
package/templates/base/pages/lib/_head-with-defaults.tsx +13 -138
package/templates/base/pages/lib/_header-with-defaults.tsx +24 -324
package/templates/base/pages/lib/_inline-version-switcher.tsx +16 -78
package/templates/base/pages/lib/_math-block.tsx +4 -63
package/templates/base/pages/lib/_nav-data-prep.ts +32 -51
package/templates/base/pages/lib/_nav-source-cache.ts +12 -57
package/templates/base/pages/lib/_nav-source-docs.ts +33 -233
package/templates/base/pages/lib/_search-widget-script.ts +2 -470
package/templates/base/pages/lib/_search-widget.tsx +9 -195
package/templates/base/pages/lib/_sidebar-prepaint.tsx +6 -59
package/templates/base/pages/lib/_sidebar-with-defaults.tsx +16 -118
package/templates/base/pages/lib/_site-tree-nav.tsx +29 -80
package/templates/base/pages/lib/doc-page-props.ts +26 -44
package/templates/base/pages/lib/locale-merge.ts +32 -145
package/templates/base/pages/lib/route-enumerators.ts +52 -286
package/templates/base/src/components/ai-chat-modal.tsx +9 -8
package/templates/base/src/components/content/code-group.tsx +3 -76
package/templates/base/src/components/content/content-admonition.tsx +4 -56
package/templates/base/src/components/doc-history.tsx +9 -8
package/templates/base/src/components/image-enlarge.tsx +11 -8
package/templates/base/src/components/sidebar-toggle.tsx +6 -170
package/templates/base/src/components/sidebar-tree.tsx +6 -548
package/templates/base/src/config/color-scheme-utils.ts +34 -158
package/templates/base/src/config/i18n.ts +9 -0
package/templates/base/src/config/settings-types.ts +34 -172
package/templates/base/src/config/z-index-tokens.ts +5 -4
package/templates/base/src/styles/global.css +40 -587
package/templates/base/src/utils/base.ts +1 -1
package/templates/base/src/utils/docs.ts +47 -16
package/templates/base/src/utils/github.ts +12 -9
package/templates/base/src/utils/nav-scope.ts +13 -42
package/templates/base/src/utils/sidebar.ts +18 -86
package/templates/base/src/utils/slug.ts +10 -53
package/templates/base/src/utils/smart-break.tsx +12 -120
package/templates/base/src/utils/tags.ts +25 -68
package/templates/features/bodyFootUtil/files/src/utils/github.ts +12 -9
package/templates/features/designTokenPanel/files/src/lib/design-token-panel-bootstrap.ts +13 -39
package/templates/features/docHistory/files/src/components/doc-history.tsx +8 -636
package/templates/features/docHistory/files/src/types/doc-history.ts +7 -23
package/templates/features/docTags/files/pages/lib/_tag-pages.tsx +35 -201
package/templates/features/i18n/files/pages/[locale]/index.tsx +1 -1
package/templates/features/imageEnlarge/files/src/components/image-enlarge.tsx +8 -269
package/templates/features/sidebarToggle/files/src/components/desktop-sidebar-toggle.tsx +6 -99
package/templates/features/tagGovernance/files/scripts/tags-audit.ts +67 -515
package/templates/features/versioning/files/pages/lib/_versions-page.tsx +21 -73
package/templates/base/pages/404.tsx +0 -61
package/templates/base/pages/robots.txt.tsx +0 -29
package/templates/base/pages/sitemap.xml.tsx +0 -59
package/templates/base/plugins/connect-adapter.mjs +0 -169
package/templates/base/plugins/copy-public-plugin.mjs +0 -58
package/templates/base/plugins/search-index-plugin.mjs +0 -66
package/templates/base/scripts/gen-z-index.mjs +0 -157
package/templates/base/src/components/mermaid-enlarge.tsx +0 -490
package/templates/base/src/components/site-tree-nav.tsx +0 -220
package/templates/features/claudeResources/files/plugins/claude-resources-plugin.mjs +0 -47
package/templates/features/docHistory/files/plugins/doc-history-plugin.mjs +0 -111
package/templates/features/docTags/files/pages/[locale]/docs/tags/[tag].tsx +0 -59
package/templates/features/docTags/files/pages/[locale]/docs/tags/index.tsx +0 -39
package/templates/features/docTags/files/pages/docs/tags/[tag].tsx +0 -43
package/templates/features/docTags/files/pages/docs/tags/index.tsx +0 -20
package/templates/features/llmsTxt/files/plugins/llms-txt-plugin.mjs +0 -93
package/templates/features/versioning/files/pages/[locale]/docs/versions.tsx +0 -48
package/templates/features/versioning/files/pages/docs/versions.tsx +0 -20

package/templates/base/pages/lib/_sidebar-prepaint.tsx CHANGED Viewed

@@ -1,64 +1,11 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Shared afterSidebar block for doc pages.
-//
-// Extracted from the four doc-route render bodies (pages/docs/[...slug].tsx,
-// pages/[locale]/docs/[...slug].tsx, pages/v/[version]/docs/[...slug].tsx,
-// pages/v/[version]/[locale]/docs/[...slug].tsx) where the block was
-// duplicated verbatim across all four routes.
-//
-// Contains:
-//   1. A pre-paint inline <script> that restores the persisted sidebar
-//      visibility flag from localStorage before first paint (avoids flash).
-//   2. A `DesktopSidebarToggle` Island that mounts on "load".
-//
-// Pattern mirrors `_body-end-islands.tsx`: the file imports the real
-// component so zfb's island scanner walks page → helper → DesktopSidebarToggle
-// and registers the constructor in the manifest. The Island call's return type
-// is widened to `unknown` (JSX shim gap) so call-sites cast through
-// `as unknown as VNode` at the boundary.
-import type { VNode, JSX } from "preact";
-import { Island } from "@takazudo/zfb";
+// Host thin-stub — see @takazudo/zudo-doc/sidebar-prepaint (epic #2344, S5).
 import { settings } from "@/config/settings";
-import DesktopSidebarToggle from "@/components/desktop-sidebar-toggle";
-/** Props for {@link SidebarPrepaint}. */
-export interface SidebarPrepaintProps {
-  /**
-   * Mirrors the page's `hide_sidebar: true` frontmatter. When true the desktop
-   * toggle is skipped — there is no visible sidebar for it to collapse.
-   */
-  hideSidebar?: boolean;
-}
+import { createSidebarPrepaint } from "@takazudo/zudo-doc/sidebar-prepaint";
-/**
- * The `afterSidebar` slot content shared by all four doc-route page components.
- *
- * Returns the pre-paint localStorage script + `DesktopSidebarToggle` Island
- * when `settings.sidebarToggle` is enabled AND the page actually shows a
- * sidebar; returns `undefined` when the toggle is disabled or the page hides
- * the sidebar (matching the conditional the route files used inline).
- */
-export function SidebarPrepaint({
-  hideSidebar,
-}: SidebarPrepaintProps): JSX.Element | undefined {
-  if (!settings.sidebarToggle || hideSidebar) return undefined;
+export type { SidebarPrepaintProps } from "@takazudo/zudo-doc/sidebar-prepaint";
-  return (
-    <>
-      {/* Pre-paint inline script: restore persisted sidebar visibility to
-          <html data-sidebar-hidden> before first paint to avoid flash.
-          Rendered only when the toggle is enabled and the page shows a
-          sidebar; the attribute is only set when localStorage says "false"
-          so the default (visible) needs no attribute and causes no layout shift. */}
-      <script dangerouslySetInnerHTML={{
-        __html: `(function(){try{if(localStorage.getItem('zudo-doc-sidebar-visible')==='false'){document.documentElement.setAttribute('data-sidebar-hidden','');}}catch(e){}})();`,
-      }} />
-      {Island({
-        when: "load",
-        children: <DesktopSidebarToggle />,
-      }) as unknown as VNode}
-    </>
-  );
-}
+export const SidebarPrepaint = createSidebarPrepaint({
+  sidebarToggle: Boolean(settings.sidebarToggle),
+});

package/templates/base/pages/lib/_sidebar-with-defaults.tsx CHANGED Viewed

@@ -1,41 +1,8 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Locale-/version-aware Sidebar wrapper for the zfb doc pages.
-//
-// Sidebar data-prep utilities — builds root-menu items from
-// settings.headerNav, loads the locale's docs collection (with EN
-// fallback for non-default locales), builds the nav tree for the active
-// section, optionally remaps hrefs for versioned routes, and feeds the
-// result into the host's <SidebarTree> Preact island.
-//
-// Why this wrapper exists: the data prep is host-only (it imports
-// @/config/* and @/utils/*), so it cannot live in the published v2
-// package. Without this wrapper the zfb doc pages fall through to a
-// <SidebarTree nodes={[]} /> default and the SSG output emits an empty
-// `<div data-zfb-island="SidebarTree" data-when="load"></div>` marker.
-import type { JSX } from "preact";
-// `<Island>` wraps `<SidebarTree>` directly here (rather than going through
-// the v2 `<Sidebar>` shell with `treeComponent`) so the zfb island bundle's
-// hydrate pass targets the actual stateful tree component. Mirrors the
-// mobile `<SidebarToggle>` shape in `pages/lib/_header-with-defaults.tsx`:
-// the hydration target owns its own data props directly so they ride the
-// SSR → hydrate boundary inside the Island marker's `data-props` attribute.
-//
-// Background: zfb's `Island.captureSerializableProps` runs `JSON.stringify`
-// on the wrapped component's own props bag, which silently drops function
-// values. With the previous `<Sidebar treeComponent={SidebarTree} ...>`
-// shape the `treeComponent` function was dropped during serialisation, so
-// at hydration the v2 Sidebar shell mounted with `treeComponent=undefined`,
-// returned `null`, and Preact's `hydrate(null, element)` left the SSR-
-// rendered tree DOM in place WITHOUT attaching the input's `onChange`
-// handler — typing into the filter input had no DOM effect.
-// zudolab/zudo-doc#1459 (Wave 1 #1445 wired the input but not the wiring
-// path; this wave routes the hydration target so the wiring actually
-// reaches the rendered tree).
-import { Island } from "@takazudo/zfb";
-import SidebarTree from "@/components/sidebar-tree";
+// Host thin-stub — see @takazudo/zudo-doc/sidebar-with-defaults (epic #2344, S5).
 import { defaultLocale, locales, t, type Locale } from "@/config/i18n";
+import { createSidebarWithDefaults } from "@takazudo/zudo-doc/sidebar-with-defaults";
 import {
   buildRootMenuItems,
   buildLocaleLinksForNav,
@@ -43,86 +10,17 @@ import {
   getThemeDefaultMode,
 } from "./_nav-data-prep";
-export interface SidebarWithDefaultsProps {
-  /** Slug of the active doc page, used to highlight the current entry. */
-  currentSlug?: string;
-  /** Active locale; defaults to the configured defaultLocale. */
-  lang?: Locale;
-  /** Header-nav category matcher used to scope the tree (e.g. "guides"). */
-  navSection?: string;
-  /** Active version slug, when rendering inside `/v/{version}/...`. */
-  currentVersion?: string;
-  /**
-   * Current page URL path used to build the locale-switcher links shown in
-   * the mobile sidebar footer. The Astro template read this from
-   * `Astro.url.pathname`; in zfb the page module passes it explicitly.
-   */
-  currentPath?: string;
-}
-/**
- * Default-bearing host wrapper that performs sidebar data prep, then wraps
- * the project's `<SidebarTree>`
- * Preact island in `<Island when="load">` so the SSG output ships a
- * populated `<div data-zfb-island="SidebarTree" data-when="load">…tree…
- * </div>` marker for the hydration runtime to pick up.
- *
- * The v2 `<Sidebar>` shell is intentionally NOT used as the hydration
- * target here. Its `treeComponent` prop is a function, and zfb's
- * `Island.captureSerializableProps` drops function values during
- * `JSON.stringify`, so a `<Sidebar treeComponent={SidebarTree} ...>`
- * island would hydrate with `treeComponent=undefined` and the shell
- * would return `null`, silently breaking the filter input's hydration
- * (zudolab/zudo-doc#1459). Wrapping `<SidebarTree>` directly mirrors the
- * mobile `<SidebarToggle>` shape (see `_header-with-defaults.tsx`) and
- * keeps all data props serializable.
- */
-export function SidebarWithDefaults(
-  props: SidebarWithDefaultsProps,
-): JSX.Element {
-  const {
-    currentSlug,
-    lang = defaultLocale,
-    navSection,
-    currentVersion,
-    currentPath = "",
-  } = props;
-  // Root-menu items, sidebar nodes, locale links, 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);
-  const backToMenuLabel = navSection ? t("nav.backToMenu", lang) : undefined;
-  // emptyWhenUnsectioned=false: the desktop sidebar falls back to the FULL
-  // tree for pages whose slug matches no headerNav categoryMatch (legacy
-  // behavior) — only the header's mobile drawer collapses to root menu.
-  const nodes = buildSidebarNodes(lang, navSection, currentVersion, false);
-  // Locale-switcher links are only meaningful when more than one locale is
-  // configured — matches the Astro template's guard.
-  const localeLinks = buildLocaleLinksForNav(currentPath, lang, locales.length);
-  // Wrap <SidebarTree> directly in <Island when="load">. SSR emits the
-  // `data-zfb-island="SidebarTree"` marker around the rendered tree, with
-  // all data props serialised into `data-props` (every prop is plain data:
-  // arrays of objects + strings). At hydration the runtime finds the
-  // marker, looks up "SidebarTree" in the islands manifest (registered via
-  // the host's `"use client"` directive on `src/components/sidebar-tree.tsx`),
-  // and mounts the real component in-place — re-attaching the filter
-  // input's `onChange` handler to the existing SSR DOM.
-  return Island({
-    when: "load",
-    children: (
-      <SidebarTree
-        nodes={nodes}
-        currentSlug={currentSlug}
-        rootMenuItems={rootMenuItems}
-        backToMenuLabel={backToMenuLabel}
-        localeLinks={localeLinks}
-        themeDefaultMode={getThemeDefaultMode()}
-      />
-    ),
-  }) as unknown as JSX.Element;
-}
+export type { SidebarWithDefaultsProps } from "@takazudo/zudo-doc/sidebar-with-defaults";
+export const SidebarWithDefaults = createSidebarWithDefaults({
+  defaultLocale,
+  localeCount: locales.length,
+  buildRootMenuItems: (lang, currentVersion) =>
+    buildRootMenuItems(lang as Locale, currentVersion),
+  buildLocaleLinksForNav: (currentPath, lang, localeCount) =>
+    buildLocaleLinksForNav(currentPath, lang as Locale, localeCount),
+  buildSidebarNodes: (lang, navSection, currentVersion, emptyWhenUnsectioned) =>
+    buildSidebarNodes(lang as Locale, navSection, currentVersion, emptyWhenUnsectioned),
+  getThemeDefaultMode,
+  t: (key, lang) => t(key as Parameters<typeof t>[0], lang as Locale),
+});

package/templates/base/pages/lib/_site-tree-nav.tsx CHANGED Viewed

@@ -1,88 +1,37 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Host-side MDX wrapper for <SiteTreeNav /> and <SiteTreeNavDemo />.
+// Thin stub — site-tree-nav moved to the package (epic #2344, S8).
+// Calls `createSiteTreeNavWrapper(deps)` from @takazudo/zudo-doc/site-tree-nav
+// with host singletons injected, then re-exports the resulting component so
+// all existing call sites continue to work unchanged.
 //
-// Both <SiteTreeNav> and <SiteTreeNavDemo> MDX tags are mapped to this
-// wrapper, which loads the full site nav tree and renders the interactive
-// SiteTreeNav island (refs #1453):
-//
-//   1. Load the full docs collection for the active locale.
-//   2. Build nav tree via buildNavTree().
-//   3. Group satellite nodes via groupSatelliteNodes().
-//   4. Wrap the interactive SiteTreeNav in Island({when:"idle"}) so the MDX
-//      page gets the collapsible grid rendered at
-//      /docs/components/site-tree-nav/ (refs #1453/#1442).
-//
-// All data access is synchronous (ADR-004 zfb content snapshot contract).
-// The `lang` prop is injected by createMdxComponents() in
-// pages/_mdx-components.ts so locale routes get locale-aware nav data.
-//
-// categoryIgnore defaults to ["inbox", "develop"] — matching the index page
-// and SiteTreeNavDemo defaults.
+// IMPORTANT: Island({when:"idle"}) is PRESERVED in the package factory —
+// the island mounts after the page is idle for performance (refs #1453).
-import type { JSX } from "preact";
-import { Island } from "@takazudo/zfb";
-import SiteTreeNav from "@/components/site-tree-nav";
-import {
-  buildNavTree,
-  groupSatelliteNodes,
-} from "@/utils/docs";
-import { defaultLocale, type Locale } from "@/config/i18n";
+import { createSiteTreeNavWrapper } from "@takazudo/zudo-doc/site-tree-nav";
+import type { SidebarNavNode } from "@takazudo/zudo-doc/sidebar/types";
+import { buildNavTree, groupSatelliteNodes } from "@/utils/docs";
+import { defaultLocale } from "@/config/i18n";
 import { getCategoryOrder } from "@/utils/nav-scope";
 import { resolveNavSource } from "./_nav-source-docs";
-export interface SiteTreeNavWrapperProps {
-  /**
-   * Active locale. Injected via createMdxComponents() closure.
-   * Defaults to defaultLocale when not provided.
-   */
-  lang?: Locale | string;
-  /**
-   * Optional aria-label for the wrapping <nav> element.
-   * Forwarded to the v2 SiteTreeNavDemo component.
-   */
-  ariaLabel?: string;
-}
-/**
- * MDX wrapper shared by both <SiteTreeNav> and <SiteTreeNavDemo> tags.
- *
- * Builds the full site nav tree and renders it via the interactive SiteTreeNav
- * island (wrapped in Island({when:"idle"})) — restoring byte-parity with the
- * Astro reference at /docs/components/site-tree-nav/ (refs #1453/#1442).
- *
- * The island renders the collapsible multi-column grid the reference shows.
- * SiteTreeNavDemo (static <details> list) is no longer used for MDX content.
- *
- * Returns null when the tree is empty after filtering.
- */
-export function SiteTreeNavWrapper({
-  lang = defaultLocale,
-  ariaLabel,
-}: SiteTreeNavWrapperProps): JSX.Element | null {
-  const locale = lang as Locale;
-  // SiteTreeNav mirrors the route nav: applies the defaultLocaleOnly filter for
-  // non-default locales (same options the sidebar/route enumeration use).
-  const { navDocs, categoryMeta } = resolveNavSource(locale, undefined, {
-    applyDefaultLocaleOnlyFilter: true,
-    keepUnlisted: true,
-  });
-  const tree = buildNavTree(navDocs, locale, categoryMeta);
-  const categoryOrder = getCategoryOrder();
-  const groupedTree = groupSatelliteNodes(tree, categoryOrder);
-  if (groupedTree.length === 0) return null;
+export type { SiteTreeNavWrapperProps } from "@takazudo/zudo-doc/site-tree-nav";
-  return Island({
-    when: "idle",
-    children: (
-      <SiteTreeNav
-        tree={groupedTree}
-        categoryOrder={categoryOrder}
-        categoryIgnore={["inbox", "develop"]}
-        ariaLabel={ariaLabel}
-      />
-    ),
-  }) as unknown as JSX.Element;
-}
+export const SiteTreeNavWrapper = createSiteTreeNavWrapper({
+  defaultLocale,
+  resolveNavSource: resolveNavSource as (
+    lang: string,
+    currentVersion: string | undefined,
+    options?: { applyDefaultLocaleOnlyFilter?: boolean; keepUnlisted?: boolean },
+  ) => import("@takazudo/zudo-doc/site-tree-nav").SiteTreeNavSource,
+  buildNavTree: buildNavTree as (
+    docs: unknown[],
+    locale: string,
+    categoryMeta: Map<string, unknown>,
+  ) => SidebarNavNode[],
+  groupSatelliteNodes: groupSatelliteNodes as (
+    tree: SidebarNavNode[],
+    prefixes: string[],
+  ) => SidebarNavNode[],
+  getCategoryOrder,
+});

package/templates/base/pages/lib/doc-page-props.ts CHANGED Viewed

@@ -1,48 +1,30 @@
-// Shared discriminated-union props types for all 4 doc-route pages.
+// Thin stub — types moved to the package (epic #2344, S6).
+// Re-exports the shared discriminated-union props types for all 4 doc-route
+// pages from @takazudo/zudo-doc/doc-page-props.
 //
-// Each route file has its own DocPageProps interface that extends one of these
-// two branches by merging in route-specific fields (locale, version, etc.).
-// Discriminating on `kind` lets TypeScript narrow `entry` / `autoIndex` to
-// non-null inside each branch — eliminating all `entry!` assertions.
+// S5 and downstream (S7) consumers import `DocPageBaseProps`, `DocPageEntry`,
+// `AutoIndexNode`, `DocPageEntryProps`, `DocPageAutoIndexProps` from this path
+// unchanged — all are re-exported below.
-import type { CollectionEntry } from "zfb/content";
-import type { DocsEntry } from "@/types/docs-entry";
-import type { NavNode, BreadcrumbItem } from "@/utils/docs";
-import type { extractHeadings } from "./_extract-headings";
+export type {
+  DocNavNode,
+  DocPageEntry,
+  DocPageFrontmatter,
+  AutoIndexNode,
+  DocPageEntryProps,
+  DocPageAutoIndexProps,
+  DocPageBaseProps,
+  HeadingItem,
+} from "@takazudo/zudo-doc/doc-page-props";
-export interface DocPageEntry extends DocsEntry {
-  /** zfb content renderer. */
-  Content: CollectionEntry<unknown>["Content"];
-  /** zfb module specifier (for Content bridge). */
-  module_specifier: string;
-}
+// Backward-compatible alias: downstream callers that import `NavNode` from
+// this path (e.g. _doc-route-entries.ts, route-enumerators.ts) continue to
+// resolve. `DocNavNode` is structurally identical to the host's `NavNode` from
+// src/utils/docs.ts (same required fields, same optional fields).
+export type { DocNavNode as NavNode } from "@takazudo/zudo-doc/doc-page-props";
-export interface AutoIndexNode extends NavNode {
-  children: NavNode[];
-}
-/** Shared fields present in every doc-page route. */
-interface DocPagePropsBase {
-  breadcrumbs: BreadcrumbItem[];
-  prev: NavNode | null;
-  next: NavNode | null;
-  /** Depth-2/3/4 headings extracted from the MDX body, for SSG TOC links. */
-  headings: ReturnType<typeof extractHeadings>;
-}
-/** Branch: a real content entry. `autoIndex` is absent. */
-export interface DocPageEntryProps extends DocPagePropsBase {
-  kind: "entry";
-  entry: DocPageEntry;
-  autoIndex?: undefined;
-}
-/** Branch: an auto-generated category index. `entry` is absent. */
-export interface DocPageAutoIndexProps extends DocPagePropsBase {
-  kind: "autoIndex";
-  autoIndex: AutoIndexNode;
-  entry?: undefined;
-}
-/** Discriminated union for the `kind` prop. Narrow via `props.kind === "entry"`. */
-export type DocPageBaseProps = DocPageEntryProps | DocPageAutoIndexProps;
+// Backward-compatible alias: `BreadcrumbItem` was previously imported from
+// @/utils/docs in some files. The package's `DocPageBaseProps` uses
+// `BreadcrumbItem` from @takazudo/zudo-doc/breadcrumb/types — re-export it
+// here so callers importing from this path still resolve.
+export type { BreadcrumbItem } from "@takazudo/zudo-doc/breadcrumb";

package/templates/base/pages/lib/locale-merge.ts CHANGED Viewed

@@ -1,159 +1,46 @@
-// Shared utility for merging locale docs with base-locale fallbacks.
+// Thin stub — locale-merge moved to the package (epic #2344, S6).
+// Re-exports the pure merge functions from @takazudo/zudo-doc/locale-merge
+// and provides backward-compatible wrappers that inject the host singletons.
 //
-// Used by route enumerators, nav helpers, and locale page modules to implement
-// the locale-first + base-fallback merge strategy.
+// `mergeLocaleDocs` is the main export: now the package function accepts an
+// optional `isDefaultLocaleOnlyPath` injection in its options object. The host
+// wrapper below injects the host's `isDefaultLocaleOnlyPath` automatically
+// so all existing call sites — which pass `applyDefaultLocaleOnlyFilter: true`
+// without explicitly passing the predicate — continue to work unchanged.
 //
-// Strategy:
-//   1. Caller loads the locale and base doc arrays (via loadDocs / bridgeEntries).
-//   2. mergeLocaleDocs({ baseDocs, localeDocs, ... }) builds the merged list.
-//   3. Locale docs take priority; base docs fill in slugs not present in locale.
-//   4. Optionally excludes base docs that are default-locale-only paths.
-//   5. Optionally filters out unlisted pages (for tag enumeration).
-//
-// WHY caller loads, helper merges:
-//   Collection naming varies per context (regular docs, versioned, locale-versioned),
-//   and the bridging (loadDocs vs. bridgeEntries) also varies per call site. Keeping
-//   the helper as a pure merge over pre-loaded arrays avoids encoding that logic here
-//   and lets each call site retain its own load pattern.
-//
-// This is a zfb-only module (synchronous, uses pre-loaded collections).
+// `mergeCategoryMeta` is kept as a host-only helper (it wraps `loadCategoryMeta`
+// from @/utils/docs which is a host import). The package's `nav-source-docs`
+// factory now owns the merged-category-meta caching; this re-export is kept
+// for any remaining host call sites.
+export type {
+  MergeDocsEntry,
+  MergeLocaleDocsOptions,
+  MergeLocaleDocsResult,
+} from "@takazudo/zudo-doc/locale-merge";
+import { mergeLocaleDocs as _mergeLocaleDocs } from "@takazudo/zudo-doc/locale-merge";
+import type { MergeLocaleDocsOptions, MergeLocaleDocsResult, MergeDocsEntry } from "@takazudo/zudo-doc/locale-merge";
 import { isDefaultLocaleOnlyPath } from "@/utils/base";
-import type { DocsEntry } from "@/types/docs-entry";
-// ---------------------------------------------------------------------------
-// mergeLocaleDocs
-// ---------------------------------------------------------------------------
-/**
- * Options for mergeLocaleDocs.
- *
- * The generic parameter `T` allows callers to pass arrays of a DocsEntry
- * subtype (e.g. `DocPageEntry[]`) and get back results of the same subtype,
- * eliminating the need for `as unknown as` casts at call sites.
- */
-export interface MergeLocaleDocsOptions<T extends DocsEntry = DocsEntry> {
-  /** Pre-loaded base (EN/default-locale) docs array, already draft-filtered. */
-  baseDocs: T[];
-  /** Pre-loaded locale-specific docs array, already draft-filtered. */
-  localeDocs: T[];
-  /**
-   * When true, base docs whose path matches a `defaultLocaleOnlyPrefixes`
-   * entry are excluded from the merge result. This matches the behavior of the
-   * inline copies in route-enumerators, nav helpers, and page paths() sections.
-   *
-   * Pass true for any call site that enumerates routes or builds nav trees for
-   * non-default locales (where showing a default-locale-only page to a locale
-   * user would be incorrect). Pass false (or omit) for call sites where the
-   * filtered paths are harmless — e.g. category nav cards, taglist columns.
-   *
-   * @default false
-   */
-  applyDefaultLocaleOnlyFilter?: boolean;
-  /**
-   * Controls whether `unlisted: true` docs survive the merge.
-   *
-   * - `true`  — unlisted docs are RETAINED (locale + base). Route/sitemap
-   *             enumeration uses this: unlisted pages have real HTML files, so
-   *             they must be built; nav callers rely on `isNavVisible`
-   *             downstream to hide them from the tree.
-   * - `false` (default) — unlisted docs are DROPPED from both locale and base.
-   *             Tag aggregation uses this so hidden pages don't contribute tags.
-   *
-   * @default false
-   */
-  keepUnlisted?: boolean;
-}
-/**
- * Result of mergeLocaleDocs.
- *
- * **Array identity:** Each call returns a fresh array — no module-level
- * memoization is applied. If a caller keys a cache on the docs array identity
- * (e.g. a nav-tree cache), it should memoize the result itself rather than
- * relying on reference stability from this helper.
- *
- * This contract is intentionally unchanged. The identity-stable layer for
- * nav-source arrays lives ABOVE this helper: `pages/lib/_nav-source-docs.ts`
- * (`resolveNavSource` / `resolveVersionedLocaleSource`) memoizes the merge
- * result on the snapshot-anchored input arrays + option signature (see
- * `pages/lib/_nav-source-cache.ts`), so `mergeLocaleDocs` itself stays a pure,
- * memo-free function (#1902).
- *
- * The generic `T` mirrors the parameter on {@link MergeLocaleDocsOptions} so
- * the returned `docs` array preserves the subtype of the input arrays.
- */
-export interface MergeLocaleDocsResult<T extends DocsEntry = DocsEntry> {
-  /**
-   * Merged doc array: locale docs first, followed by base docs for slugs not
-   * present in the locale collection (and not excluded by filter options).
-   */
-  docs: T[];
-  /**
-   * Set of slugs that came from the locale collection.
-   * Useful for callers that need to determine whether a page is a fallback
-   * (i.e. `isFallback = !localeSlugSet.has(slug)`).
-   */
-  localeSlugSet: ReadonlySet<string>;
-}
+import { loadCategoryMeta } from "@/utils/docs";
+import type { CategoryMeta } from "@/utils/docs";
 /**
  * Merge locale docs with base-locale fallbacks.
  *
- * Locale docs take priority; base docs fill in slugs not covered by the locale
- * collection. Optionally excludes default-locale-only paths and/or unlisted pages.
- *
- * **Slug keying**: slug identity uses `d.data.slug ?? d.id`. Since `loadDocs`
- * already strips the `/index` suffix (via `stripIndexSuffix` in `_data.ts`),
- * this key is consistent across all call sites regardless of whether they
- * loaded docs via `loadDocs` or `bridgeEntries`.
- *
- * **Array identity**: returns a fresh array on each call — see
- * {@link MergeLocaleDocsResult} for caching guidance.
+ * Thin host wrapper around the package's `mergeLocaleDocs` that injects
+ * `isDefaultLocaleOnlyPath` from `@/utils/base` automatically. Existing call
+ * sites that pass `applyDefaultLocaleOnlyFilter: true` continue to work
+ * without change — the predicate is now injected rather than module-imported.
  */
-export function mergeLocaleDocs<T extends DocsEntry = DocsEntry>(
-  options: MergeLocaleDocsOptions<T>,
+export function mergeLocaleDocs<T extends MergeDocsEntry = MergeDocsEntry>(
+  options: Omit<MergeLocaleDocsOptions<T>, "isDefaultLocaleOnlyPath">,
 ): MergeLocaleDocsResult<T> {
-  const {
-    baseDocs,
-    localeDocs,
-    applyDefaultLocaleOnlyFilter = false,
-    keepUnlisted = false,
-  } = options;
-  const filteredLocale = keepUnlisted
-    ? localeDocs
-    : localeDocs.filter((d) => !d.data.unlisted);
-  const filteredBase = keepUnlisted
-    ? baseDocs
-    : baseDocs.filter((d) => !d.data.unlisted);
-  const localeSlugSet = new Set(filteredLocale.map((d) => d.data.slug ?? d.id));
-  let fallbackDocs = filteredBase.filter(
-    (d) => !localeSlugSet.has(d.data.slug ?? d.id),
-  );
-  if (applyDefaultLocaleOnlyFilter) {
-    fallbackDocs = fallbackDocs.filter(
-      (d) => !isDefaultLocaleOnlyPath(`/docs/${d.data.slug ?? d.id}`),
-    );
-  }
-  return {
-    docs: [...filteredLocale, ...fallbackDocs],
-    localeSlugSet,
-  };
+  return _mergeLocaleDocs({
+    ...options,
+    isDefaultLocaleOnlyPath,
+  });
 }
-// ---------------------------------------------------------------------------
-// mergeCategoryMeta
-// ---------------------------------------------------------------------------
-import { loadCategoryMeta } from "@/utils/docs";
-import type { CategoryMeta } from "@/utils/docs";
 /**
  * Merge category metadata for a locale: base metadata first, locale overrides
  * win on overlapping keys.