@takazudo/zudo-doc 5.5.3 → 5.7.0

package/dist/doc-route-entries/index.d.ts

@@ -2,100 +2,15 @@ import type { DocPageEntry, DocNavNode, AutoIndexNode, DocPageBaseProps } from "
 import type { NavSourceDocs } from "../nav-source-docs/index.js";
 import type { BreadcrumbItem } from "../breadcrumb/types.js";
 import type { HeadingItem } from "../extract-headings/index.js";
-import type { CategoryMeta } from "../sidebar-tree/index.js";
+import type { BuildDocRouteEntriesArgs as BuildDocRouteEntriesArgsGeneric, DocRouteEntriesAPI as DocRouteEntriesAPIGeneric, DocRouteEntriesContext as DocRouteEntriesContextGeneric, DocRouteEntry as DocRouteEntryGeneric } from "../site-schema/doc-route-entries.js";
+export { createDocRouteEntries } from "../site-schema/doc-route-entries.js";
 export type { DocPageEntry, DocNavNode, AutoIndexNode, DocPageBaseProps, NavSourceDocs };
-/** One enumerated doc route: a content entry or an auto-generated category
- *  index, with all per-page derived data pre-computed. */
-export interface DocRouteEntry {
-    /** Canonical route slug ("" for the docs root index — #1891). */
-    slug: string;
-    /** Optional-catchall params array — `toSlugParams(slug)` ([] for the root). */
-    slugParams: string[];
-    /**
-     * True when the entry came from the base collection rather than the locale
-     * collection (`!localeSlugSet.has(slug)`). Only meaningful on routes whose
-     * nav source performs a locale merge — routes without one (default-locale /
-     * versioned-EN, where `localeSlugSet` is empty) must ignore this field.
-     * Always false for autoIndex items.
-     */
-    isFallback: boolean;
-    /** Shared page props (kind/entry/autoIndex/breadcrumbs/prev/next/headings). */
-    props: DocPageBaseProps;
-}
-export interface BuildDocRouteEntriesArgs {
-    /** Identity-stable nav source for this route's (locale, version) context. */
-    source: NavSourceDocs;
-    /** Active locale for nav-tree labels and breadcrumbs. */
-    locale: string;
-    /**
-     * Unique memo signature for this route context. Each route file passes its
-     * own prefix plus the loop variables (version slug / locale), e.g.
-     * "docs;en", "locale-docs;ja", "v-docs;1.0", "v-locale-docs;1.0;ja" —
-     * call sites that share a docs array identity must never collide on a key.
-     */
-    routeSig: string;
-    /** Versioned URL closure bound to the route's version (+ locale). Presence
-     *  switches the versioned behaviors (breadcrumbs, prev/next, child hrefs). */
-    urlFor?: (slug: string) => string;
-}
 export type { BreadcrumbItem, HeadingItem };
-/**
- * Context slice `createDocRouteEntries` derives its bag from (epic Collapse
- * Wiring Shells #2420, FACTORIES #2424 — breaking signature). STRUCTURAL SUBSET
- * of the unified `RouteContext`/`ChromeContext` — the nav-tree builder is
- * reconstructed by binding the context's 4-arg `buildNavTree` to `docsUrl`, and
- * the breadcrumb trail by binding the package `buildBreadcrumbs` to the
- * locale-prefixed `withBase` base, exactly as the pre-collapse wiring did.
- */
-export interface DocRouteEntriesContext {
-    /** Default locale code (drives the breadcrumb base-prefix selection). */
-    defaultLocale: string;
-    /** Build the nav tree for a locale (4-arg form with an explicit href builder). */
-    buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, CategoryMeta> | undefined, buildHref: (slug: string, locale: string) => string) => DocNavNode[];
-    /** Build a docs URL for the given slug and locale. */
-    docsUrl: (slug: string, locale?: string) => string;
-    /** Prefix a path with the configured base directory. */
-    withBase: (path: string) => string;
-    /** Collect all auto-generated index nodes (categories without index.mdx). */
-    collectAutoIndexNodes: (tree: DocNavNode[]) => AutoIndexNode[];
-    /** Determine the nav section (categoryMatch) for a slug. */
-    getNavSectionForSlug: (slug: string) => string | undefined;
-    /** Filter top-level nav nodes by a categoryMatch value. */
-    getNavSubtree: (tree: DocNavNode[], categoryMatch?: string) => DocNavNode[];
-    /** Convert a content entry slug to a canonical route slug. */
-    toRouteSlug: (entrySlug: string) => string;
-    /** Convert a canonical route slug to an optional-catchall params array. */
-    toSlugParams: (slug: string) => string[];
-    /** Extract headings from a raw MDX body (bound to settings depth/strategy). */
-    extractHeadings: (body: string) => HeadingItem[];
-}
-/**
- * Result of `createDocRouteEntries`. Contains the `buildDocRouteEntries`
- * function bound to the injected context.
- */
-export interface DocRouteEntriesAPI {
-    /**
-     * Enumerate all doc routes for one (locale, version) context, with per-entry
-     * derived data pre-computed. Memoized per build on the identity-stable
-     * `source.docs` array.
-     */
-    buildDocRouteEntries: (args: BuildDocRouteEntriesArgs) => DocRouteEntry[];
-}
-/**
- * Create the `buildDocRouteEntries` function bound to the host's injected
- * context.
- *
- * @example
- * ```ts
- * // pages/lib/_doc-route-entries.ts (thin stub)
- * import { createDocRouteEntries } from "@takazudo/zudo-doc/doc-route-entries";
- * import { buildNavTree, buildBreadcrumbs, collectAutoIndexNodes } from "@/utils/docs";
- * import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
- * import { toRouteSlug, toSlugParams } from "@takazudo/zudo-doc/slug";
- * import { extractHeadings } from "./_extract-headings";
- *
- * export const { buildDocRouteEntries } = createDocRouteEntries(routeContext);
- * export type { DocRouteEntry, BuildDocRouteEntriesArgs };
- * ```
- */
-export declare function createDocRouteEntries(ctx: DocRouteEntriesContext): DocRouteEntriesAPI;
+/** One enumerated doc route, carrying a zfb collection entry. */
+export type DocRouteEntry = DocRouteEntryGeneric<DocPageEntry>;
+/** Arguments to `buildDocRouteEntries` for one (locale, version) context. */
+export type BuildDocRouteEntriesArgs = BuildDocRouteEntriesArgsGeneric<DocPageEntry>;
+/** The context slice `createDocRouteEntries` derives its bag from. */
+export type DocRouteEntriesContext = DocRouteEntriesContextGeneric<DocPageEntry>;
+/** The functions `createDocRouteEntries` returns. */
+export type DocRouteEntriesAPI = DocRouteEntriesAPIGeneric<DocPageEntry>;

package/dist/doc-route-entries/index.js

@@ -1,81 +1,4 @@
-import { memoizeDerived } from "../nav-source-cache/index.js";
-import { buildBreadcrumbs as buildBreadcrumbsImpl } from "../routes/_docs-helpers.js";
-import {
-  resolveDocPrevNext,
-  flattenSubtree,
-  rewriteNavHref,
-  remapNavChildHrefs
-} from "../doc-route-paths/index.js";
-function createDocRouteEntries(ctx) {
-  const defaultLocale = ctx.defaultLocale;
-  const buildNavTree = (docs, locale, categoryMeta) => ctx.buildNavTree(docs, locale, categoryMeta, (slug, loc) => ctx.docsUrl(slug, loc));
-  const buildBreadcrumbs = (tree, slug, locale, urlFor) => buildBreadcrumbsImpl(
-    tree,
-    slug,
-    locale === defaultLocale ? ctx.withBase("/") : ctx.withBase(`/${locale}/`),
-    urlFor
-  );
-  const collectAutoIndexNodes = ctx.collectAutoIndexNodes;
-  const getNavSectionForSlug = ctx.getNavSectionForSlug;
-  const getNavSubtree = ctx.getNavSubtree;
-  const toRouteSlug = ctx.toRouteSlug;
-  const toSlugParams = ctx.toSlugParams;
-  const extractHeadings = ctx.extractHeadings;
-  function buildDocRouteEntries(args) {
-    const { source, locale, routeSig, urlFor } = args;
-    return memoizeDerived([source.docs], `docRouteEntries;${routeSig}`, () => {
-      const { docs, navDocs, categoryMeta, localeSlugSet } = source;
-      const tree = buildNavTree(navDocs, locale, categoryMeta);
-      const breadcrumbTree = urlFor ? tree : buildNavTree(docs, locale, categoryMeta);
-      const result = [];
-      for (const entry of docs) {
-        if (entry.data.category_no_page === true) continue;
-        const slug = entry.data.slug ?? toRouteSlug(entry.slug);
-        const navSection = getNavSectionForSlug(slug);
-        const subtree = getNavSubtree(tree, navSection);
-        const { prev: prevNode, next: nextNode } = resolveDocPrevNext(
-          tree,
-          flattenSubtree(subtree),
-          slug,
-          entry.data
-        );
-        result.push({
-          slug,
-          slugParams: toSlugParams(slug),
-          isFallback: !localeSlugSet.has(slug),
-          props: {
-            kind: "entry",
-            entry,
-            breadcrumbs: buildBreadcrumbs(breadcrumbTree, slug, locale, urlFor),
-            prev: rewriteNavHref(prevNode, urlFor),
-            next: rewriteNavHref(nextNode, urlFor),
-            headings: extractHeadings(entry.body ?? "")
-          }
-        });
-      }
-      for (const node of collectAutoIndexNodes(tree)) {
-        result.push({
-          slug: node.slug,
-          slugParams: toSlugParams(node.slug),
-          isFallback: false,
-          props: {
-            kind: "autoIndex",
-            autoIndex: urlFor ? {
-              ...node,
-              children: remapNavChildHrefs(node.children, urlFor)
-            } : node,
-            breadcrumbs: buildBreadcrumbs(breadcrumbTree, node.slug, locale, urlFor),
-            prev: null,
-            next: null,
-            headings: []
-          }
-        });
-      }
-      return result;
-    });
-  }
-  return { buildDocRouteEntries };
-}
+import { createDocRouteEntries } from "../site-schema/doc-route-entries.js";
 export {
   createDocRouteEntries
 };

package/dist/doc-route-paths/index.d.ts

@@ -1,4 +1,4 @@
-import type { DocNavNode } from "../doc-page-props/index.js";
+import type { DocNavNode } from "../site-schema/types.js";
 export type { DocNavNode };
 /**
  * Flatten a nav tree into a pre-order traversal array.

package/dist/head-with-defaults/index.d.ts

@@ -4,7 +4,7 @@ import type { JSX } from "preact";
 import type { HeadProps } from "../head/types.js";
 import type { ColorSchemeProviderColorMode } from "../theme/color-scheme-provider.js";
 import type { ChromeContext } from "../factory-context/index.js";
-import type { Settings } from "../settings.js";
+import type { Settings, FaviconConfig } from "../settings.js";
 export interface HeadWithDefaultsProps {
     /** Page title forwarded to og:title. Required. */
     title: string;
@@ -33,6 +33,8 @@ export interface HeadWithDefaultsSettings {
     sidebarResizer?: boolean;
     /** Configured theme-pack slug (ADR `docs/adr/theme-packs.md`, #2822). */
     themePack?: string;
+    /** Favicon link set — see {@link resolveFaviconLinks} for the emission table. */
+    favicon?: string | FaviconConfig | false;
 }
 /**
  * Create a `HeadWithDefaults` component from the unified {@link ChromeContext}

package/dist/head-with-defaults/index.js

@@ -6,8 +6,82 @@ import ThemePackProvider, {
   themePackVersionMap
 } from "../theme/theme-pack-provider.js";
 import { DEFAULT_THEME_PACK_SLUG } from "../theme-pack-switcher/theme-pack-sync.js";
+import { renderAutoLogoIconSvg } from "../auto-logo/icon.js";
 import { deriveComposeMetaTitle, deriveColorSchemeGenerators } from "../chrome/derive.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
+const FAVICON_AUTO = "auto";
+const DEFAULT_FAVICON = {
+  svg: "/favicon.svg",
+  ico: "/favicon.ico",
+  png32: "/favicon-32x32.png",
+  png16: "/favicon-16x16.png"
+};
+const FAVICON_TYPE_BY_EXT = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  ico: "image/x-icon",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif"
+};
+function faviconType(value) {
+  const path = value.split(/[?#]/)[0] ?? "";
+  const file = path.slice(path.lastIndexOf("/") + 1);
+  const dot = file.lastIndexOf(".");
+  if (dot < 0) return void 0;
+  return FAVICON_TYPE_BY_EXT[file.slice(dot + 1).toLowerCase()];
+}
+function faviconHref(value, withBase) {
+  return value.startsWith("/") ? withBase(value) : value;
+}
+function resolveFaviconLinks(favicon, siteName, withBase) {
+  if (favicon === false) return [];
+  if (typeof favicon === "string") {
+    if (favicon === FAVICON_AUTO) {
+      const svg = encodeURIComponent(renderAutoLogoIconSvg(siteName));
+      return [{ rel: "icon", type: "image/svg+xml", href: `data:image/svg+xml,${svg}` }];
+    }
+    const type = faviconType(favicon);
+    return [
+      {
+        rel: "icon",
+        ...type !== void 0 ? { type } : {},
+        href: faviconHref(favicon, withBase)
+      }
+    ];
+  }
+  const slots = favicon ?? DEFAULT_FAVICON;
+  const links = [];
+  if (slots.svg !== void 0) {
+    links.push({
+      rel: "icon",
+      type: faviconType(slots.svg) ?? "image/svg+xml",
+      href: faviconHref(slots.svg, withBase)
+    });
+  }
+  if (slots.ico !== void 0) {
+    links.push({ rel: "icon", href: faviconHref(slots.ico, withBase), sizes: "any" });
+  }
+  if (slots.png32 !== void 0) {
+    links.push({
+      rel: "icon",
+      type: faviconType(slots.png32) ?? "image/png",
+      sizes: "32x32",
+      href: faviconHref(slots.png32, withBase)
+    });
+  }
+  if (slots.png16 !== void 0) {
+    links.push({
+      rel: "icon",
+      type: faviconType(slots.png16) ?? "image/png",
+      sizes: "16x16",
+      href: faviconHref(slots.png16, withBase)
+    });
+  }
+  return links;
+}
 function createHeadWithDefaults(ctx) {
   assertChromeContext(ctx, "createHeadWithDefaults");
   const settings = ctx.settings;
@@ -19,6 +93,7 @@ function createHeadWithDefaults(ctx) {
   const themePackEnabled = themePackRegistry !== null ? themePackVersionMap(themePackRegistry) : null;
   const themePackConfigured = settings.themePack ?? DEFAULT_THEME_PACK_SLUG;
   const themePackBase = withBase("/");
+  const faviconLinks = resolveFaviconLinks(settings.favicon, settings.siteName, withBase);
   function HeadWithDefaults({
     title,
     description,
@@ -65,10 +140,7 @@ function createHeadWithDefaults(ctx) {
         }
       ),
       settings.sidebarResizer && /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: SIDEBAR_RESIZER_RESTORE_SCRIPT } }),
-      /* @__PURE__ */ jsx("link", { rel: "icon", type: "image/svg+xml", href: withBase("/favicon.svg") }),
-      /* @__PURE__ */ jsx("link", { rel: "icon", href: withBase("/favicon.ico"), sizes: "any" }),
-      /* @__PURE__ */ jsx("link", { rel: "icon", type: "image/png", sizes: "32x32", href: withBase("/favicon-32x32.png") }),
-      /* @__PURE__ */ jsx("link", { rel: "icon", type: "image/png", sizes: "16x16", href: withBase("/favicon-16x16.png") }),
+      faviconLinks.map((attrs, i) => /* @__PURE__ */ jsx("link", { ...attrs }, i)),
       canonical !== void 0 && /* @__PURE__ */ jsx("link", { rel: "canonical", href: canonical }),
       ctx.settings.head && /* @__PURE__ */ jsxs(Fragment, { children: [
         ctx.settings.head.preconnect?.map((p, i) => /* @__PURE__ */ jsx(

package/dist/header/nav-active.d.ts

@@ -25,6 +25,37 @@ export interface NavItemLike {
  *   pathForMatch(null,            "ja", "en") === ""
  */
 export declare function pathForMatch(pathWithoutBase: string, lang: string | undefined, defaultLocale: string): string;
+/**
+ * Pick the deepest header-nav path that the current page lives under.
+ *
+ * The legacy template flattens parent + child paths, filters by
+ * `pathForMatch.startsWith(p)`, and picks the longest match — this keeps
+ * a child link active even when its parent's path is also a prefix of
+ * the current page.
+ *
+ * Returns `undefined` when no nav entry matches; callers should treat
+ * that as "no active link."
+ */
+/**
+ * Segment-aware prefix test: nav path `/docs/guides` matches `/docs/guides`
+ * and `/docs/guides/...` but NOT `/docs/guideship`.
+ *
+ * Exported (not just module-private) so `scripts/gen-nav-overflow-script.mjs`
+ * can embed it verbatim via `.toString()` alongside `computeActiveNavPath` —
+ * that function closes over this one, so a bare `computeActiveNavPath.toString()`
+ * embed would reference an undefined `pathMatchesNavPath` in the browser (see
+ * the caution note on `computeActiveNavPath` below). Kept self-contained (no
+ * outer references) for the same reason. The generator freezes both into the
+ * committed `nav-overflow-generated-script.ts` literal at package build time
+ * (zudolab/zudo-doc#3534) — this is no longer a live per-module-eval embed.
+ */
+export declare function pathMatchesNavPath(currentPath: string, navPath: string): boolean;
+/**
+ * CAUTION (zudolab/zudo-doc#3398): this closes over `pathMatchesNavPath`
+ * above. `scripts/gen-nav-overflow-script.mjs` embeds both via `.toString()`
+ * (never this one alone) so the frozen browser script (`./nav-overflow-generated-script.ts`,
+ * zudolab/zudo-doc#3534) is self-contained.
+ */
 export declare function computeActiveNavPath(navItems: readonly NavItemLike[], pathForMatchValue: string): string | undefined;
 /**
  * Active-state predicate for a top-level nav item: the item itself, or

package/dist/header/nav-active.js

@@ -34,5 +34,6 @@ export {
   computeActiveNavPath,
   isNavItemActive,
   isNavItemActiveByCategory,
-  pathForMatch
+  pathForMatch,
+  pathMatchesNavPath
 };

package/dist/header/nav-overflow-generated-script.d.ts

@@ -0,0 +1,11 @@
+/** Returns the frozen desktop-nav overflow controller IIFE script. NOTE: the
+ * vitest drift guard imports buildNavOverflowScript from
+ * scripts/gen-nav-overflow-script.mjs (a fresh re-generation) — NEVER from
+ * this module: comparing NAV_OVERFLOW_SCRIPT below against this same file's
+ * function would be a vacuous self-comparison. */
+export declare function buildNavOverflowScript(): string;
+/** Client-side script string for the desktop header nav overflow controller.
+ * See the module header of this generator for the embedding contract; see
+ * current-path/index.ts / header/nav-active.ts / header/nav-class-tokens.ts /
+ * transitions/page-events.ts for the frozen sources. */
+export declare const NAV_OVERFLOW_SCRIPT: string;