@takazudo/zudo-doc 3.2.0 → 4.0.0

package/dist/sidebar-tree/build-tree.d.ts

@@ -14,11 +14,10 @@ import type { BuildSidebarTreeOptions, CollectionEntryLike, SidebarFrontmatter,
  * Build a recursive sidebar tree from `entries`. Visibility filtering is
  * applied first; the resulting structure mirrors the filesystem.
  *
- * - Multi-segment ids (e.g. `getting-started/intro`) walk the tree creating
+ * - Multi-segment slugs (e.g. `getting-started/intro`) walk the tree creating
  *   intermediate category nodes as needed.
- * - Single-segment ids represent category index pages (Astro 5 strips
- *   `/index` from the id, so `getting-started/index.mdx` arrives as the id
- *   `getting-started`).
+ * - A trailing `/index` represents a category index page and is stripped from
+ *   the canonical route slug.
  * - Sibling order is determined by `sidebar_position` then alphabetical
  *   slug, with the parent's `sortOrder` (from `_category_.json`) flipping
  *   the comparator when set to `"desc"`.

package/dist/sidebar-tree/build-tree.js

@@ -1,5 +1,6 @@
-function toRouteSlug(id) {
-  return id.replace(/\/index$/, "");
+function toRouteSlug(slug) {
+  if (slug === "index") return "";
+  return slug.replace(/\/index$/, "");
 }
 function toTitleCase(str) {
   return str.split("-").map((word) => word.length === 0 ? word : word[0].toUpperCase() + word.slice(1)).join(" ");
@@ -24,7 +25,7 @@ function buildSidebarTree(entries, locale, options = {}) {
   };
   for (const entry of entries) {
     if (!isNavVisible(entry)) continue;
-    const slug = entry.data.slug ?? entry.slug ?? toRouteSlug(entry.id);
+    const slug = entry.data.slug ?? toRouteSlug(entry.slug);
     if (!slug) continue;
     const parts = slug.split("/");
     if (parts.length <= 1) {

package/dist/sidebar-tree/index.d.ts

@@ -9,8 +9,8 @@
  *     type SidebarNode,
  *   } from "@takazudo/zudo-doc/sidebar-tree";
  *
- * The builder takes a flat list of content collection entries (in either
- * Astro or zfb shape) plus a locale, and emits a recursive `SidebarNode[]`
+ * The builder takes a flat list of current zfb collection entries plus a
+ * locale, and emits a recursive `SidebarNode[]`
  * suitable for rendering or for further sidebar-config processing.
  */
 export { buildSidebarTree, findSidebarNode, flattenSidebarTree, } from "./build-tree.js";

package/dist/sidebar-tree/types.d.ts

@@ -24,7 +24,7 @@ export interface SidebarFrontmatter {
     standalone?: boolean;
     /**
      * Optional override for the route slug. When omitted, the builder derives
-     * the slug from the entry's id (stripping a trailing `/index`).
+     * the route slug from the entry's zfb slug (stripping a trailing `/index`).
      */
     slug?: string;
     /**
@@ -43,27 +43,16 @@ export interface SidebarFrontmatter {
     category_sort_order?: "asc" | "desc";
 }
 /**
- * Minimum shape required of a content collection entry. Designed to be a
- * structural superset of both Astro's `CollectionEntry` and zfb's
- * `CollectionEntry<T>` so callers can pass either through unchanged.
+ * Minimum current zfb collection-entry shape required by the builder.
  */
 export interface CollectionEntryLike<T extends SidebarFrontmatter = SidebarFrontmatter> {
     /**
-     * Stable identifier. For Astro entries this is the file path without the
-     * extension (e.g. `getting-started/index`). For zfb entries the project
-     * convention is to put the cleaned slug here too — either form is fine
-     * because the builder strips a trailing `/index`.
+     * Filename without the extension. Canonical route identity is derived by
+     * stripping the root or nested `index` suffix.
      */
-    id: string;
-    /**
-     * Optional pre-computed slug. When present it wins over the id-derived
-     * value. zfb entries always populate this field; Astro callers can leave
-     * it undefined.
-     */
-    slug?: string;
+    slug: string;
     data: T;
-    /** Free-form fields kept for forward compatibility — never read here. */
-    collection?: string;
+    /** Other native zfb fields are accepted structurally and never read here. */
     body?: string;
 }
 /**

package/dist/site-tree-nav-island/index.d.ts

@@ -4,8 +4,10 @@ export interface SiteTreeNavProps {
     ariaLabel?: string;
     categoryOrder?: string[];
     categoryIgnore?: string[];
+    /** Root-category slugs that should start collapsed. */
+    initiallyCollapsedCategorySlugs?: string[];
 }
-export declare function SiteTreeNav({ tree, ariaLabel, categoryOrder, categoryIgnore, }: SiteTreeNavProps): import("preact").JSX.Element;
+export declare function SiteTreeNav({ tree, ariaLabel, categoryOrder, categoryIgnore, initiallyCollapsedCategorySlugs, }: SiteTreeNavProps): import("preact").JSX.Element;
 export declare namespace SiteTreeNav {
     var displayName: string;
 }

package/dist/site-tree-nav-island/index.js

@@ -3,6 +3,7 @@ import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
 import { useState } from "preact/hooks";
 import { INDENT, connectorLeft, ConnectorLines, CategoryLinkIcon } from "../tree-nav-shared/index.js";
 import { ChevronRight } from "../icons/index.js";
+import { initialCategoryOpenState, toggleCategoryOpenState } from "./state.js";
 const SITE_BASE_PAD = "clamp(0.5rem, 0.8vw, 1rem)";
 function padLeft(depth) {
   if (depth === 0) return SITE_BASE_PAD;
@@ -27,7 +28,8 @@ function SiteTreeNav({
   tree,
   ariaLabel = "Site index",
   categoryOrder,
-  categoryIgnore
+  categoryIgnore,
+  initiallyCollapsedCategorySlugs
 }) {
   let processedTree = tree;
   if (categoryIgnore) {
@@ -37,6 +39,7 @@ function SiteTreeNav({
   if (categoryOrder) {
     processedTree = reorderTree(processedTree, categoryOrder);
   }
+  const initiallyCollapsed = new Set(initiallyCollapsedCategorySlugs);
   return /* @__PURE__ */ jsx(
     "nav",
     {
@@ -46,7 +49,15 @@ function SiteTreeNav({
       style: {
         gridTemplateColumns: "repeat(auto-fill, minmax(min(18rem, 100%), 1fr))"
       },
-      children: processedTree.map((node) => /* @__PURE__ */ jsx("div", { className: "min-w-0 border border-muted pl-hsp-sm py-vsp-2xs", children: node.children.length > 0 ? /* @__PURE__ */ jsx(CategoryNode, { node, depth: 0, isLast: true }) : /* @__PURE__ */ jsx(LeafNode, { node, depth: 0, isLast: true }) }, node.slug))
+      children: processedTree.map((node) => /* @__PURE__ */ jsx("div", { className: "min-w-0 border border-muted pl-hsp-sm py-vsp-2xs", children: node.children.length > 0 ? /* @__PURE__ */ jsx(
+        CategoryNode,
+        {
+          node,
+          depth: 0,
+          isLast: true,
+          initiallyCollapsed: initiallyCollapsed.has(node.slug)
+        }
+      ) : /* @__PURE__ */ jsx(LeafNode, { node, depth: 0, isLast: true }) }, node.slug))
     }
   );
 }
@@ -76,10 +87,11 @@ function NodeList({ nodes, depth }) {
 function CategoryNode({
   node,
   depth,
-  isLast
+  isLast,
+  initiallyCollapsed = false
 }) {
-  const [open, setOpen] = useState(true);
-  const toggle = () => setOpen((prev) => !prev);
+  const [open, setOpen] = useState(() => initialCategoryOpenState(initiallyCollapsed));
+  const toggle = () => setOpen(toggleCategoryOpenState);
   const paddingLeft = padLeft(depth);
   return /* @__PURE__ */ jsxs("div", { className: `${depth >= 1 && !isLast ? "relative" : ""}`, children: [
     depth >= 1 && !isLast && open && /* @__PURE__ */ jsx(

package/dist/site-tree-nav-island/state.d.ts

@@ -0,0 +1,4 @@
+/** Derive the one-time open state used when a category mounts. */
+export declare function initialCategoryOpenState(initiallyCollapsed: boolean): boolean;
+/** Toggle a mounted category without coupling later state to its initial input. */
+export declare function toggleCategoryOpenState(open: boolean): boolean;

package/dist/site-tree-nav-island/state.js

@@ -0,0 +1,10 @@
+function initialCategoryOpenState(initiallyCollapsed) {
+  return !initiallyCollapsed;
+}
+function toggleCategoryOpenState(open) {
+  return !open;
+}
+export {
+  initialCategoryOpenState,
+  toggleCategoryOpenState
+};

package/dist/tag-helpers/index.d.ts

@@ -2,11 +2,9 @@ import type { TagVocabularyEntry, TagGovernanceMode } from "../settings.js";
 export type { TagVocabularyEntry, TagGovernanceMode };
 /** Result of resolving a raw tag string. */
 export interface ResolvedTag {
-    /** Canonical id after alias/redirect rewrites. Equal to the raw input when unchanged. */
+    /** Exact canonical id, or the raw input when it is unknown/inactive. */
     canonical: string;
-    /** True when the canonical id should be dropped from aggregation (deprecated without redirect). */
-    deprecated: boolean;
-    /** True when the raw input matched a vocabulary entry (as id or alias). */
+    /** True when the raw input exactly matched a vocabulary id. */
     known: boolean;
 }
 /**
@@ -17,20 +15,15 @@ export interface ResolvedTag {
  *
  * When the vocabulary is inactive (`tagVocabulary` is empty/falsy or
  * `tagGovernance` is `"off"`), the raw value passes through unchanged with
- * `known: false, deprecated: false`. Otherwise:
+ * `known: false`. Otherwise:
  *
- * - A direct id match returns that id.
- * - An alias match returns the aliased entry's id.
- * - `deprecated: { redirect: "<id>" }` rewrites to the redirect target.
- * - `deprecated: true` (no redirect) returns `deprecated: true` so callers
- *   can drop the tag from aggregation.
+ * - An exact id match returns that id with `known: true`.
  * - An unknown value returns the raw string with `known: false`.
  */
 export declare function resolveTag(raw: string, tagVocabulary: readonly TagVocabularyEntry[] | false | undefined, tagGovernance: TagGovernanceMode | undefined): ResolvedTag;
 /**
- * Resolve a list of raw tag strings (e.g. from frontmatter) to canonical ids,
- * dropping deprecated-without-redirect entries and preserving order. Duplicates
- * produced by alias collapse are removed.
+ * Resolve a list of raw tag strings (e.g. from frontmatter), preserving order
+ * and removing exact duplicates. Unknown strings pass through unchanged.
  *
  * Builds the vocabulary index once and reuses it for all tags — O(N) index
  * construction instead of O(N×M) when called with M tags.

package/dist/tag-helpers/index.js

@@ -1,29 +1,12 @@
 function buildIndex(tagVocabulary) {
-  const byId = /* @__PURE__ */ new Map();
-  const byAlias = /* @__PURE__ */ new Map();
-  for (const entry of tagVocabulary) {
-    byId.set(entry.id, entry);
-    for (const alias of entry.aliases ?? []) byAlias.set(alias, entry);
-  }
-  return { byId, byAlias };
+  return new Set(tagVocabulary.map((entry) => entry.id));
 }
-function resolveTagWithIndex(raw, index) {
-  const entry = index.byId.get(raw) ?? index.byAlias.get(raw);
-  if (!entry) return { canonical: raw, deprecated: false, known: false };
-  const dep = entry.deprecated;
-  if (dep && typeof dep === "object" && dep.redirect) {
-    const target = index.byId.get(dep.redirect);
-    if (target) return { canonical: target.id, deprecated: false, known: true };
-    return { canonical: entry.id, deprecated: true, known: true };
-  }
-  if (dep === true) {
-    return { canonical: entry.id, deprecated: true, known: true };
-  }
-  return { canonical: entry.id, deprecated: false, known: true };
+function resolveTagWithIndex(raw, ids) {
+  return { canonical: raw, known: ids.has(raw) };
 }
 function resolveTag(raw, tagVocabulary, tagGovernance) {
   if (!tagVocabulary || tagGovernance === "off") {
-    return { canonical: raw, deprecated: false, known: false };
+    return { canonical: raw, known: false };
   }
   return resolveTagWithIndex(raw, buildIndex(tagVocabulary));
 }
@@ -40,8 +23,7 @@ function resolvePageTags(rawTags, tagVocabulary, tagGovernance) {
   }
   const index = buildIndex(tagVocabulary);
   for (const raw of rawTags) {
-    const { canonical, deprecated } = resolveTagWithIndex(raw, index);
-    if (deprecated) continue;
+    const { canonical } = resolveTagWithIndex(raw, index);
     if (seen.has(canonical)) continue;
     seen.add(canonical);
     out.push(canonical);

package/dist/tag-pages/index.d.ts

@@ -3,20 +3,9 @@
 import type { ComponentChildren, JSX } from "preact";
 import type { ChromeContext } from "../factory-context/index.js";
 import type { Settings } from "../settings.js";
-/** Minimal docs entry shape needed by the tag-pages factory. */
-export interface TagPagesDocsEntry {
-    id: string;
-    data: {
-        slug?: string;
-        draft?: boolean;
-        unlisted?: boolean;
-        category_no_page?: boolean;
-        tags?: string[];
-        title: string;
-        description?: string;
-        [key: string]: unknown;
-    };
-}
+import type { DocPageEntry } from "../doc-page-props/index.js";
+/** Current zfb docs entry used by the tag-pages factory. */
+export type TagPagesDocsEntry = DocPageEntry;
 /** Tag info produced and consumed by the tag-pages factory. */
 export interface TagInfo {
     tag: string;
@@ -40,11 +29,11 @@ export interface TagPagesComponents {
         title: string;
     }) => JSX.Element;
     HeaderWithDefaults: (props: {
-        lang?: string;
+        lang: string;
         currentPath?: string;
     }) => JSX.Element;
     FooterWithDefaults: (props: {
-        lang?: string;
+        lang: string;
     }) => JSX.Element;
     BodyEndIslands: (props: {
         basePath: string;
@@ -71,7 +60,7 @@ export interface TagPagesDeps {
      * Collect tags from a docs array, producing a Map<tag, TagInfo>.
      * Host passes `collectTags` from `@/utils/tags`.
      */
-    collectTags: (entries: TagPagesDocsEntry[], slugFn: (id: string, data: {
+    collectTags: (entries: TagPagesDocsEntry[], slugFn: (entrySlug: string, data: {
         slug?: string;
     }) => string) => Map<string, TagInfo>;
     /**
@@ -83,7 +72,7 @@ export interface TagPagesDeps {
      * Returns true for paths that are only shown in the default locale.
      * Host passes `isDefaultLocaleOnlyPath` from `@/utils/base`.
      */
-    isDefaultLocaleOnlyPath?: (path: string) => boolean;
+    isDefaultLocaleOnlyPath: (path: string) => boolean;
     components: TagPagesComponents;
 }
 /** Result of {@link createTagPages}. */
@@ -116,8 +105,6 @@ export interface TagPagesAPI {
  * Reads `settings`/`defaultLocale`/`t`/`withBase`/`docsUrl`/`collectTags`/
  * `stableDocs` off the context, derives `composeMetaTitle`, and rebuilds the
  * Head / Header / Footer / BodyEndIslands / DocHistoryArea chrome from the SAME
- * context. `isDefaultLocaleOnlyPath` is left `undefined` to reproduce the
- * pre-collapse injected wiring (`routes/_chrome.tsx` passed `undefined`) — the
- * frozen baseline's tag pages are rendered through that path BYTE-FOR-BYTE.
+ * context, including the current default-locale-only path predicate.
  */
 export declare function createTagPages<S extends Settings = Settings>(ctx: ChromeContext<S>): TagPagesAPI;

package/dist/tag-pages/index.js

@@ -1,15 +1,14 @@
 import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
 import { DocLayoutWithDefaults } from "../doclayout/index.js";
-import { Breadcrumb } from "../breadcrumb/index.js";
 import { DocCardGrid, TagNav } from "../nav-indexing/index.js";
 import { memoizeDerived } from "../nav-source-cache/index.js";
 import { mergeLocaleDocs } from "../locale-merge/index.js";
 import { toRouteSlug } from "../slug/index.js";
 import { createHeadWithDefaults } from "../head-with-defaults/index.js";
-import { createHeaderWithDefaults } from "../header-with-defaults/index.js";
-import { createFooterWithDefaults } from "../footer-with-defaults/index.js";
+import { resolveThemePackSsrSlug } from "../theme/theme-pack-provider.js";
 import { createDocHistoryArea } from "../doc-history-area/index.js";
 import { deriveComposeMetaTitle, deriveBodyEndIslands } from "../chrome/derive.js";
+import { derivePrimaryChromeSlots } from "../chrome/primary-slots.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createTagPages(ctx) {
   assertChromeContext(ctx, "createTagPages");
@@ -21,16 +20,19 @@ function createTagPages(ctx) {
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const collectTags = ctx.collectTags;
   const stableDocs = ctx.stableDocs;
-  const isDefaultLocaleOnlyPath = void 0;
+  const isDefaultLocaleOnlyPath = ctx.isDefaultLocaleOnlyPath;
   const HeadWithDefaults = createHeadWithDefaults(ctx);
-  const HeaderWithDefaults = createHeaderWithDefaults(
-    ctx
-  );
-  const FooterWithDefaults = createFooterWithDefaults(
-    ctx
-  );
+  const {
+    Header: HeaderWithDefaults,
+    Footer: FooterWithDefaults,
+    Breadcrumb
+  } = derivePrimaryChromeSlots(ctx);
   const BodyEndIslands = deriveBodyEndIslands(ctx);
   const DocHistoryArea = createDocHistoryArea(ctx);
+  const dataThemePack = resolveThemePackSsrSlug(
+    ctx.themePackRegistry,
+    ctx.settings
+  );
   function localePrefix(locale) {
     return locale === defaultLocale ? "" : `/${locale}`;
   }
@@ -82,6 +84,7 @@ function createTagPages(ctx) {
         title: composeMetaTitle(pageTitle),
         head: /* @__PURE__ */ jsx(HeadWithDefaults, { title: pageTitle }),
         lang: isDefault ? void 0 : locale,
+        dataThemePack,
         noindex: settings.noindex,
         hideSidebar: true,
         hideToc: true,
@@ -125,6 +128,7 @@ function createTagPages(ctx) {
         title: composeMetaTitle(pageTitle),
         head: /* @__PURE__ */ jsx(HeadWithDefaults, { title: pageTitle }),
         lang: isDefault ? void 0 : locale,
+        dataThemePack,
         noindex: settings.noindex,
         hideSidebar: true,
         hideToc: true,

package/dist/tags-audit.d.ts

@@ -4,44 +4,22 @@
  * Core library for vocabulary-aware frontmatter tag auditing.
  *
  * Exports pure functions and types consumed by:
- *   - the package bin  (packages/zudo-doc/bin/tags-audit.mjs)
- *   - the project-side tags-suggest script (scripts/tags-suggest.ts)
+ *   - the package bins (packages/zudo-doc/bin/tags-audit.mjs and
+ *     packages/zudo-doc/bin/tags-suggest.mjs)
  *   - custom integrations
  *
  * Does NOT import from project-specific config (settings, tag-vocabulary).
  * The caller passes those in via AuditOptions.
  */
-/** Minimal shape required by this library. Matches src/config/tag-vocabulary-types. */
-export interface TagVocabularyEntry {
-    id: string;
-    label?: string;
-    description?: string;
-    group?: string;
-    aliases?: readonly string[];
-    deprecated?: boolean | {
-        redirect?: string;
-    };
-}
+import type { TagVocabularyEntry } from "./settings.js";
+export type { TagVocabularyEntry } from "./settings.js";
 interface VocabularyIndex {
     byId: Map<string, TagVocabularyEntry>;
-    byAlias: Map<string, TagVocabularyEntry>;
-    aliasToId: Map<string, string>;
 }
 export interface UnknownIssue {
     file: string;
     raw: string;
 }
-export interface DeprecatedIssue {
-    file: string;
-    raw: string;
-    canonical: string;
-    redirect?: string;
-}
-export interface AliasIssue {
-    file: string;
-    raw: string;
-    canonical: string;
-}
 export interface NearDuplicatePair {
     a: string;
     b: string;
@@ -50,12 +28,10 @@ export interface NearDuplicatePair {
 }
 export interface AuditReport {
     unknowns: UnknownIssue[];
-    deprecated: DeprecatedIssue[];
-    aliases: AliasIssue[];
     nearDuplicates: NearDuplicatePair[];
     orphans: string[];
     filesScanned: number;
-    /** Totals keyed by canonical id after alias/deprecation resolution. */
+    /** Totals keyed by exact canonical id, or raw unknown id. */
     frequency: Record<string, number>;
 }
 export interface AuditOptions {
@@ -71,6 +47,17 @@ export interface AuditOptions {
      */
     nearDupHelpers?: NearDupHelpers;
 }
+/**
+ * Explicit project input shared by the package-owned tag audit and suggestion
+ * CLIs. Paths are project-root-relative and are resolved from the CLI's cwd.
+ * A config module passed with `--config` must default-export this shape.
+ */
+export interface TagCliConfig {
+    contentDirs: readonly string[];
+    vocabulary: readonly TagVocabularyEntry[];
+    governance: "off" | "warn" | "strict";
+    vocabularyActive: boolean;
+}
 export interface NearDupHelpers {
     singular: (word: string) => string;
     compareTwoStrings: (a: string, b: string) => number;
@@ -81,19 +68,6 @@ export declare function normalizeTags(value: unknown): string[];
 export declare function findNearDuplicates(tags: string[], helpers: NearDupHelpers): NearDuplicatePair[];
 export declare function audit(opts: AuditOptions): Promise<AuditReport>;
 export declare function hasHardIssues(report: AuditReport): boolean;
-export declare function computeRewrites(vocabulary: readonly TagVocabularyEntry[]): Map<string, string>;
-export declare function applyFixes(contentDirs: string[], rewrites: Map<string, string>, rootDir: string): Promise<string[]>;
-/**
- * Rewrite alias tags to canonical ids within a single MDX file, preserving
- * every other byte of the file verbatim. Returns `{ content, changed }`.
- *
- * Supports block-style (`tags:\n  - foo\n`) and flow-style
- * (`tags: [foo, bar]`) YAML sequences. Quoted string values are handled.
- */
-export declare function rewriteAliasesByteStable(content: string, rewrites: Map<string, string>): {
-    content: string;
-    changed: boolean;
-};
 /** Format a human-readable text report. Requires picocolors for coloring. */
 export declare function formatTextReport(report: AuditReport, governance: AuditOptions["governance"], vocabularyActive: boolean, pc: {
     bold: (s: string) => string;
@@ -101,7 +75,5 @@ export declare function formatTextReport(report: AuditReport, governance: AuditO
     dim: (s: string) => string;
     red: (s: string) => string;
     yellow: (s: string) => string;
-    blue: (s: string) => string;
     green: (s: string) => string;
 }): string;
-export {};