@takazudo/zudo-doc 5.5.3 → 5.7.0

package/routes-src/_design-token-panel-bootstrap.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+// routes/_design-token-panel-bootstrap — the ROUTES-ONLY configured
+// design-token-panel island (#3396, epic #3394).
+//
+// WHY THIS FILE EXISTS: `virtual:zudo-doc-design-token-panel-config` is
+// registered by the routes plugin, so any module that imports it statically
+// drags the plugin along as a hard requirement. Until #3396 that importer was
+// `../design-token-panel-bootstrap.tsx`, which `chrome/derive.tsx` imports —
+// meaning `@takazudo/zudo-doc/chrome` could not be bundled outside a zfb build
+// (or by a `packageOwnedRoutes: false` host) without aliasing the specifier.
+// Moving the import HERE confines it to the routes graph, which zfb always
+// bundles with the plugin active.
+//
+// WHY A COMPONENT AND NOT A SETTER: the route/SSR module graph and the
+// hydrated island bundle are SEPARATE graphs. A `setPanelConfigBuilder(...)`
+// called while `_chrome.tsx` evaluates would configure only the server-side
+// copy of the bootstrap module; the client bundle re-evaluates that module
+// independently and would keep the package default. Passing the builder as an
+// argument from a component that lives INSIDE the island bundle is the only
+// shape that survives the boundary.
+//
+// ISLAND-SCANNER CONTRACT (#2480 lesson): `_chrome.tsx` imports this module
+// STATICALLY and threads the component into `hostBindings`, so the scanner
+// walks route → _chrome → here. The exported binding identifier and the
+// `displayName` must stay IDENTICAL — zfb registers islands by the
+// scanner-visible export name, and a marker whose name has no registry entry
+// silently never hydrates. The name must also stay DISTINCT from
+// `DesignTokenPanelBootstrap`: `chrome/derive.tsx` still statically imports
+// that package default (it is the slot default for bare `createChrome`
+// callers), so both components are in the scanned graph and a shared name
+// would trip zfb's "island marker name collision" warning and drop one of them.
+
+import type { JSX } from "preact";
+import { runDesignTokenPanelBootstrapOnce } from "@takazudo/zudo-doc/design-token-panel-bootstrap";
+// Host-callables channel, third virtual module (#2658, mirrors #2501's
+// chromeBindingsModule): absent `settings.designTokenPanelConfigModule` →
+// re-exports the package default (`@takazudo/zudo-doc/design-token-panel-config`);
+// present → re-exports the host's module. Registered unconditionally by the
+// routes plugin (`../plugins/routes.ts`) whenever `packageOwnedRoutes` is on.
+// Not present on disk; the package ships ambient typings for it
+// (`./_virtual.d.ts`).
+import { buildDesignTokenPanelConfig } from "virtual:zudo-doc-design-token-panel-config";
+
+/**
+ * The design-token-panel island injected routes mount instead of the package
+ * default: identical behavior, except the mode-scoped `PanelConfig` builder is
+ * the one the routes plugin resolved — the host's
+ * `settings.designTokenPanelConfigModule` when set, the package default
+ * otherwise.
+ *
+ * Renders `null` on both SSR and client (the panel self-mounts as a side
+ * effect of `bootstrapDesignTokenPanel`), matching the package default's
+ * non-`ssrFallback` `Island({ when: "load" })` shape.
+ */
+export function ConfiguredDesignTokenPanelBootstrap(): JSX.Element | null {
+  runDesignTokenPanelBootstrapOnce(buildDesignTokenPanelConfig, "configured");
+  return null;
+}
+ConfiguredDesignTokenPanelBootstrap.displayName = "ConfiguredDesignTokenPanelBootstrap";

package/routes-src/_docs-helpers.ts

@@ -1,37 +1,28 @@
-// routes/_docs-helpers — package-side nav-tree helpers for the package-owned
-// route entrypoints (epic Package-First Finale #2356, A1 #2361).
+// routes/_docs-helpers — the content bridge for the package-owned route
+// entrypoints (epic Package-First Finale #2356, A1 #2361).
 //
-// The host's `src/utils/docs.ts` `buildNavTree` / `buildBreadcrumbs` /
-// `collectAutoIndexNodes` / `groupSatelliteNodes` / `findNode` /
-// `firstRoutedHref` are host-only wrappers around the package primitive
-// `buildSidebarTree` (`@takazudo/zudo-doc/sidebar-tree`). The package route
-// entrypoints inject these same helpers into the doc-route / nav-source /
-// nav-wrapper factories, so this module reproduces them WITHOUT the host `@/`
-// alias — the "+ package `docs` helpers" note in the ADR's host-dep table.
+// WHAT IS LEFT HERE: `stableDocs`, and only `stableDocs`. It is the one piece
+// of this module that cannot be browser-safe — it imports `@takazudo/zfb/content`
+// directly (NOT the host `zfb/content` tsconfig alias — Decision 2) to anchor
+// the bridged + draft-filtered array on the build snapshot, so repeat callers
+// within a build get the SAME instance and the nav-tree / doc-route memos
+// short-circuit (the content bridge — Decision 5).
 //
-// Faithful to the host derivation (root-index node synthesis, NavNode shape,
-// satellite grouping, breadcrumb walk) but without the host-only LRU /
-// identity caches: build-time array-identity stability already comes from the
-// snapshot-anchored `stableDocs` (below) + `memoizeDerived` in the factories.
-//
-// `stableDocs` (the content bridge — Decision 5) imports `@takazudo/zfb/content`
-// directly (NOT the host `zfb/content` tsconfig alias — Decision 2), anchoring
-// the bridged + draft-filtered array on the snapshot so repeat callers within a
-// build get the SAME instance and the nav-tree / doc-route memos short-circuit.
+// WHAT MOVED: every pure nav helper this file used to define — `buildNavTree`,
+// `groupSatelliteNodes`, `findNode`, `firstRoutedHref`, `collectAutoIndexNodes`,
+// `buildBreadcrumbs`, `isNavVisible` — now lives in `../site-schema/nav-tree.js`
+// (#3395); import them from there, not from here. Cutting them loose is what
+// lets `createDocRouteEntries` reach `buildBreadcrumbs` without dragging
+// `@takazudo/zfb/content` into an otherwise browser-safe graph. This module
+// deliberately re-exports NOTHING: a second import path for the nav helpers
+// through this file would put them one hop from the `@takazudo/zfb/content`
+// edge this file exists to carry.
 
 import {
   getCollection,
   getContentSnapshot,
 } from "@takazudo/zfb/content";
-import {
-  buildSidebarTree,
-  type CategoryMeta,
-  type SidebarNode,
-} from "@takazudo/zudo-doc/sidebar-tree";
-import { toRouteSlug } from "@takazudo/zudo-doc/slug";
-import type { DocNavNode, DocPageEntry, DocPageFrontmatter } from "@takazudo/zudo-doc/doc-page-props";
-
-export type { CategoryMeta, DocNavNode, DocPageEntry };
+import type { DocPageEntry, DocPageFrontmatter } from "@takazudo/zudo-doc/doc-page-props";
 
 // ---------------------------------------------------------------------------
 // Content bridge — snapshot-anchored stable docs (Decision 5)
@@ -64,201 +55,3 @@ export function stableDocs(collectionName: string): DocPageEntry[] {
   docsByAnchor.set(anchor, built);
   return built;
 }
-
-// ---------------------------------------------------------------------------
-// Nav-tree helpers — ported from src/utils/docs.ts onto buildSidebarTree
-// ---------------------------------------------------------------------------
-
-/** Filter predicate: true when a doc should appear in navigation. */
-export function isNavVisible(doc: DocPageEntry): boolean {
-  return !doc.data.unlisted && !doc.data.standalone;
-}
-
-/** A docs-href builder: `(slug, locale) => url`. */
-export type BuildHref = (slug: string, locale: string) => string;
-
-export interface BuildNavTreeOptions {
-  buildHref?: BuildHref;
-}
-
-function toNavNode(node: SidebarNode): DocNavNode {
-  return {
-    slug: node.id,
-    label: node.label,
-    description: node.description,
-    position: node.sidebar_position ?? 999,
-    href: node.href,
-    hasPage: node.hasPage,
-    children: node.children.map(toNavNode),
-    sortOrder: node.sortOrder ?? "asc",
-  };
-}
-
-/** Last entry whose package-derived slug is empty ("") — the entry the shared
- *  builder skips. Last one wins (mirrors the host builder's overwrite). */
-function findRootIndexDoc(docs: DocPageEntry[]): DocPageEntry | undefined {
-  let found: DocPageEntry | undefined;
-  for (const d of docs) {
-    const slug = d.data.slug ?? toRouteSlug(d.slug);
-    if (slug === "") found = d;
-  }
-  return found;
-}
-
-function toRootNavNode(
-  doc: DocPageEntry,
-  locale: string,
-  buildHref: BuildHref,
-  categoryMeta?: Map<string, CategoryMeta>,
-): DocNavNode {
-  const meta = categoryMeta?.get("");
-  const noPage = doc.data.category_no_page ?? meta?.noPage;
-  const sortOrder =
-    (doc.data.category_sort_order as "asc" | "desc" | undefined) ?? meta?.sortOrder ?? "asc";
-  return {
-    slug: "",
-    label:
-      (doc.data.sidebar_label as string | undefined) ??
-      doc.data.title ??
-      meta?.label ??
-      "",
-    description: doc.data.description ?? meta?.description,
-    position: (doc.data.sidebar_position as number | undefined) ?? meta?.position ?? 999,
-    href: noPage ? undefined : buildHref("", locale),
-    hasPage: noPage !== true,
-    children: [],
-    sortOrder,
-  };
-}
-
-/**
- * Build a recursive navigation tree from a flat doc collection. Delegates tree
- * construction to the shared `buildSidebarTree`; keeps the host-side concerns
- * (DocNavNode shape, root-index node synthesis). `buildHref` parameterizes the
- * href space (default: the injected `docsUrl`). Unlike the host copy this drops
- * the LRU / identity caches — the snapshot-anchored `stableDocs` already makes
- * the input arrays identity-stable so the factory-level `memoizeDerived` short-
- * circuits per build.
- */
-export function buildNavTree(
-  docs: DocPageEntry[],
-  locale: string,
-  categoryMeta: Map<string, CategoryMeta> | undefined,
-  buildHref: BuildHref,
-  options?: BuildNavTreeOptions,
-): DocNavNode[] {
-  const href: BuildHref = options?.buildHref ?? buildHref;
-  const sidebarTree = buildSidebarTree(
-    docs,
-    locale,
-    {
-      categoryMeta,
-      buildHref: (slug, loc) => href(slug, loc),
-      // Host call sites own visibility; disable the builder's default filter so
-      // breadcrumb (unfiltered) and nav (pre-filtered) paths are unchanged.
-      isNavVisible: () => true,
-    },
-  );
-  const result = sidebarTree.map(toNavNode);
-
-  const rootDoc = findRootIndexDoc(docs);
-  if (rootDoc) {
-    result.push(toRootNavNode(rootDoc, locale, href, categoryMeta));
-    result.sort((a, b) => {
-      const posCompare = a.position - b.position;
-      if (posCompare !== 0) return posCompare;
-      return a.slug.localeCompare(b.slug);
-    });
-  }
-  return result;
-}
-
-/** Group "satellite" nodes (slug-prefix siblings) under their primary node. */
-export function groupSatelliteNodes(tree: DocNavNode[], prefixes: string[]): DocNavNode[] {
-  const result = [...tree];
-  for (const prefix of prefixes) {
-    const primaryIdx = result.findIndex((n) => n.slug === prefix);
-    if (primaryIdx < 0) continue;
-    const primary = result[primaryIdx];
-    if (!primary) continue;
-    const satelliteIdxs: number[] = [];
-    for (let i = 0; i < result.length; i++) {
-      const node = result[i];
-      if (node && i !== primaryIdx && node.slug.startsWith(`${prefix}-`)) {
-        satelliteIdxs.push(i);
-      }
-    }
-    if (satelliteIdxs.length === 0) continue;
-    const extraChildren: DocNavNode[] = [];
-    for (const idx of satelliteIdxs) {
-      const node = result[idx];
-      if (node) extraChildren.push(node);
-    }
-    result[primaryIdx] = { ...primary, children: [...primary.children, ...extraChildren] };
-    for (const idx of satelliteIdxs.reverse()) result.splice(idx, 1);
-  }
-  return result;
-}
-
-/** Find a node by slug anywhere in the tree. */
-export function findNode(nodes: DocNavNode[], slug: string): DocNavNode | undefined {
-  for (const node of nodes) {
-    if (node.slug === slug) return node;
-    const found = findNode(node.children, slug);
-    if (found) return found;
-  }
-  return undefined;
-}
-
-/** Href of the first routed descendant, walking children depth-first. */
-export function firstRoutedHref(node: DocNavNode): string | undefined {
-  for (const child of node.children) {
-    if (child.hasPage && child.href) return child.href;
-    const nested = firstRoutedHref(child);
-    if (nested) return nested;
-  }
-  return undefined;
-}
-
-/** Collect all category nodes that have children but no page (no index.mdx). */
-export function collectAutoIndexNodes(nodes: DocNavNode[]): DocNavNode[] {
-  const result: DocNavNode[] = [];
-  for (const node of nodes) {
-    if (!node.hasPage && node.children.length > 0 && node.href) result.push(node);
-    result.push(...collectAutoIndexNodes(node.children));
-  }
-  return result;
-}
-
-export interface BreadcrumbItem {
-  label: string;
-  href?: string;
-}
-
-/** Build breadcrumb trail by walking the nav tree. `homeHref` is the locale
- *  docs root (injected). `hrefFor` optionally remaps intermediate crumbs into
- *  a versioned URL space. */
-export function buildBreadcrumbs(
-  tree: DocNavNode[],
-  slug: string,
-  homeHref: string,
-  hrefFor?: (slug: string) => string,
-): BreadcrumbItem[] {
-  const parts = slug.split("/");
-  const crumbs: BreadcrumbItem[] = [{ label: "", href: homeHref }];
-  let nodes = tree;
-  for (let i = 0; i < parts.length; i++) {
-    const partialSlug = parts.slice(0, i + 1).join("/");
-    const node = nodes.find((n) => n.slug === partialSlug);
-    if (!node) break;
-    const isLast = i === parts.length - 1;
-    const href = isLast
-      ? undefined
-      : hrefFor && node.href !== undefined
-        ? hrefFor(node.slug)
-        : node.href;
-    crumbs.push({ label: node.label, href });
-    nodes = node.children;
-  }
-  return crumbs;
-}

package/routes-src/_virtual.d.ts

@@ -57,8 +57,11 @@ declare module "virtual:zudo-doc-chrome-bindings" {
 // …)`, #2658). No on-disk source — materialised at build, either as a
 // re-export of the host's `settings.designTokenPanelConfigModule` file or as
 // a re-export of the package default (`@takazudo/zudo-doc/design-token-panel-config`)
-// when the setting is absent. See `plugins/routes.ts` and this package's
-// `design-token-panel-bootstrap.tsx` for the full contract.
+// when the setting is absent. Since #3396 its SOLE importer is the
+// routes-only wrapper `./_design-token-panel-bootstrap.tsx` — the generic
+// `design-token-panel-bootstrap.tsx` binds the package default directly, so
+// `@takazudo/zudo-doc/chrome` bundles without the routes plugin. See
+// `plugins/routes.ts` and that bootstrap module for the full contract.
 //
 // Typed via an inline `import(...)` type (not a top-level import, for the
 // same ambient-module-declaration reason as `chromeBindings` above) — see

package/virtual-modules.d.ts

@@ -70,8 +70,11 @@ declare module "virtual:zudo-doc-chrome-bindings" {
 // …)`, #2658). No on-disk source — materialised at build, either as a
 // re-export of the host's `settings.designTokenPanelConfigModule` file or as
 // a re-export of the package default (`@takazudo/zudo-doc/design-token-panel-config`)
-// when the setting is absent. See `plugins/routes.ts` and this package's
-// `design-token-panel-bootstrap.tsx` for the full contract.
+// when the setting is absent. Since #3396 its SOLE importer is the
+// routes-only wrapper `./_design-token-panel-bootstrap.tsx` — the generic
+// `design-token-panel-bootstrap.tsx` binds the package default directly, so
+// `@takazudo/zudo-doc/chrome` bundles without the routes plugin. See
+// `plugins/routes.ts` and that bootstrap module for the full contract.
 //
 // Typed via an inline `import(...)` type (not a top-level import, for the
 // same ambient-module-declaration reason as `chromeBindings` above) — see