@takazudo/zudo-doc 0.2.21 → 0.2.22

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

@@ -9,7 +9,7 @@
  * Frontmatter fields the builder reads off of each entry's `data` object.
  * Callers are free to extend this; unrecognised fields are ignored.
  */
-interface SidebarFrontmatter {
+export interface SidebarFrontmatter {
     title: string;
     description?: string;
     sidebar_position?: number;
@@ -47,7 +47,7 @@ interface SidebarFrontmatter {
  * structural superset of both Astro's `CollectionEntry` and zfb's
  * `CollectionEntry<T>` so callers can pass either through unchanged.
  */
-interface CollectionEntryLike<T extends SidebarFrontmatter = SidebarFrontmatter> {
+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
@@ -69,7 +69,7 @@ interface CollectionEntryLike<T extends SidebarFrontmatter = SidebarFrontmatter>
 /**
  * Metadata supplied by a directory's `_category_.json` file.
  */
-interface CategoryMeta {
+export interface CategoryMeta {
     label?: string;
     position?: number;
     description?: string;
@@ -87,7 +87,7 @@ interface CategoryMeta {
  * because downstream consumers (sidebar config layer, breadcrumb builder)
  * need them. They are all optional from a caller's perspective.
  */
-interface SidebarNode {
+export interface SidebarNode {
     type: "doc" | "category";
     /** Path-style slug, e.g. `getting-started/introduction`. */
     id: string;
@@ -106,8 +106,8 @@ interface SidebarNode {
  * for non-default locales and `/docs/<slug>/` otherwise — but most projects
  * will inject their own to honour `base`, `trailingSlash`, etc.
  */
-type BuildHref = (slug: string, locale: string) => string;
-interface BuildSidebarTreeOptions {
+export type BuildHref = (slug: string, locale: string) => string;
+export interface BuildSidebarTreeOptions {
     /**
      * Map keyed by slash-joined directory path → category meta. Typically
      * produced by {@link CategoryMetaLoader}.
@@ -130,5 +130,3 @@ interface BuildSidebarTreeOptions {
      */
     isNavVisible?: (entry: CollectionEntryLike<SidebarFrontmatter>) => boolean;
 }
-
-export type { BuildHref, BuildSidebarTreeOptions, CategoryMeta, CollectionEntryLike, SidebarFrontmatter, SidebarNode };

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

@@ -0,0 +1,13 @@
+import type { SidebarNavNode, SidebarRootMenuItem, SidebarLocaleLink } from "../sidebar/types.js";
+export interface SidebarTreeProps {
+    nodes: SidebarNavNode[];
+    currentSlug?: string;
+    rootMenuItems?: SidebarRootMenuItem[];
+    backToMenuLabel?: string;
+    localeLinks?: SidebarLocaleLink[];
+    themeDefaultMode?: "light" | "dark";
+}
+export declare function SidebarTree({ nodes, currentSlug, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }: SidebarTreeProps): import("preact").JSX.Element;
+export declare namespace SidebarTree {
+    var displayName: string;
+}

package/dist/sidebar-tree-island/index.js

@@ -0,0 +1,454 @@
+"use client";
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { useState, useCallback, useEffect, useMemo, useRef } from "preact/hooks";
+import { memo } from "preact/compat";
+import { INDENT, BASE_PAD, connectorLeft, ConnectorLines, CategoryLinkIcon } from "../tree-nav-shared/index.js";
+import { ChevronRight, ChevronLeft, Search } from "../icons/index.js";
+import { ThemeToggle } from "../theme-toggle/index.js";
+import { smartBreakToHtml } from "../smart-break/index.js";
+import { AFTER_NAVIGATE_EVENT, BEFORE_NAVIGATE_EVENT } from "../transitions/index.js";
+function ToggleChevron({ isExpanded, className }) {
+  return /* @__PURE__ */ jsx(
+    ChevronRight,
+    {
+      className: `h-[0.625rem] w-[0.625rem] shrink-0 transition-transform duration-150 ${isExpanded ? "rotate-90" : ""} ${className ?? ""}`
+    }
+  );
+}
+const STORAGE_KEY = "zd-sidebar-open";
+function padLeft(depth, forCategory) {
+  if (depth === 0) return `calc(${BASE_PAD} + ${forCategory ? "0.15rem" : "0rem"})`;
+  return `calc(${depth} * ${INDENT} + 1.25rem + 5px)`;
+}
+function getOpenSet() {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    if (!raw) return /* @__PURE__ */ new Set();
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? new Set(parsed.filter((v) => typeof v === "string")) : /* @__PURE__ */ new Set();
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function saveOpenSet(set) {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify([...set]));
+  } catch {
+  }
+}
+function normalizePath(p) {
+  return p.replace(/\/$/, "") || "/";
+}
+function findActiveSlug(nodes, pathname) {
+  for (const node of nodes) {
+    if (node.href && normalizePath(node.href) === pathname) return node.slug;
+    const found = findActiveSlug(node.children, pathname);
+    if (found !== void 0) return found;
+  }
+  return void 0;
+}
+function deriveActiveSlugFromUrl(nodes) {
+  if (typeof window === "undefined") return void 0;
+  const pathname = normalizePath(window.location.pathname);
+  return findActiveSlug(nodes, pathname);
+}
+function useActiveSlug(nodes, initial) {
+  const [slug, setSlug] = useState(
+    () => initial !== void 0 ? initial : deriveActiveSlugFromUrl(nodes)
+  );
+  useEffect(() => {
+    const update = () => {
+      const found = deriveActiveSlugFromUrl(nodes);
+      if (found !== void 0) setSlug(found);
+    };
+    update();
+    document.addEventListener(AFTER_NAVIGATE_EVENT, update);
+    return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, update);
+  }, [nodes]);
+  return slug;
+}
+function useSidebarScrollPreserve() {
+  useEffect(() => {
+    let savedScrollTop = 0;
+    let restoreTimer;
+    const onBefore = () => {
+      if (restoreTimer !== void 0) {
+        clearTimeout(restoreTimer);
+        restoreTimer = void 0;
+      }
+      const aside = document.querySelector("#desktop-sidebar");
+      if (aside) savedScrollTop = aside.scrollTop;
+    };
+    const onAfter = () => {
+      const aside = document.querySelector("#desktop-sidebar");
+      if (!aside) return;
+      restoreTimer = setTimeout(() => {
+        restoreTimer = void 0;
+        aside.scrollTop = savedScrollTop;
+      }, 50);
+    };
+    document.addEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
+    document.addEventListener(AFTER_NAVIGATE_EVENT, onAfter);
+    return () => {
+      document.removeEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
+      document.removeEventListener(AFTER_NAVIGATE_EVENT, onAfter);
+      if (restoreTimer !== void 0) clearTimeout(restoreTimer);
+    };
+  }, []);
+}
+function filterTree(nodes, query) {
+  return nodes.reduce((acc, node) => {
+    const matchesLabel = node.label.toLowerCase().includes(query.toLowerCase());
+    const filteredChildren = node.children.length > 0 ? filterTree(node.children, query) : [];
+    if (matchesLabel || filteredChildren.length > 0) {
+      acc.push({
+        ...node,
+        children: matchesLabel ? node.children : filteredChildren
+      });
+    }
+    return acc;
+  }, []);
+}
+function RootMenuItemEntry({ item }) {
+  const [expanded, setExpanded] = useState(false);
+  const hasChildren = item.children && item.children.length > 0;
+  return /* @__PURE__ */ jsxs("div", { className: "border-t border-muted", children: [
+    /* @__PURE__ */ jsxs("div", { className: "flex items-center", children: [
+      /* @__PURE__ */ jsxs(
+        "a",
+        {
+          href: item.href,
+          className: "flex flex-1 items-center gap-hsp-xs px-hsp-sm py-vsp-xs text-small font-semibold text-fg hover:text-accent hover:underline break-words",
+          children: [
+            /* @__PURE__ */ jsx(CategoryLinkIcon, { className: "w-[14px]" }),
+            /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: smartBreakToHtml(item.label) } })
+          ]
+        }
+      ),
+      hasChildren && /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          onClick: () => setExpanded((prev) => !prev),
+          className: "flex items-center justify-center px-hsp-sm py-vsp-xs text-muted hover:text-fg",
+          "aria-expanded": expanded,
+          "aria-label": expanded ? `Collapse ${item.label}` : `Expand ${item.label}`,
+          children: /* @__PURE__ */ jsx(ToggleChevron, { isExpanded: expanded, className: "text-muted" })
+        }
+      )
+    ] }),
+    hasChildren && expanded && /* @__PURE__ */ jsx("div", { className: "pb-vsp-xs", children: item.children.map((child) => /* @__PURE__ */ jsx(
+      "a",
+      {
+        href: child.href,
+        className: "block pl-hsp-xl pr-hsp-sm py-vsp-2xs text-small text-muted hover:text-accent hover:underline break-words",
+        children: /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: smartBreakToHtml(child.label) } })
+      },
+      child.href
+    )) })
+  ] });
+}
+function SidebarFooter({ links, themeDefaultMode }) {
+  if (!links && !themeDefaultMode) return null;
+  return (
+    // pb-[50vh] provides scroll room so the footer doesn't sit at the very bottom of the viewport
+    /* @__PURE__ */ jsxs("div", { className: "lg:hidden flex items-center gap-hsp-md border-t border-muted px-hsp-sm py-vsp-xs pb-[50vh] text-small", children: [
+      themeDefaultMode && /* @__PURE__ */ jsx(ThemeToggle, { defaultMode: themeDefaultMode }),
+      links && links.map((link, i) => /* @__PURE__ */ jsxs("span", { className: "flex items-center gap-hsp-xs", children: [
+        i > 0 && /* @__PURE__ */ jsx("span", { className: "text-muted", children: "/" }),
+        link.active ? /* @__PURE__ */ jsx("span", { "aria-current": "true", className: "font-medium text-fg", children: link.label }) : /* @__PURE__ */ jsx("a", { href: link.href, lang: link.code, className: "text-muted hover:text-fg", children: link.label })
+      ] }, link.href))
+    ] })
+  );
+}
+function SidebarTree({ nodes, currentSlug, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }) {
+  const activeSlug = useActiveSlug(nodes, currentSlug);
+  useSidebarScrollPreserve();
+  const [query, setQuery] = useState("");
+  const [showingRootMenu, setShowingRootMenu] = useState(false);
+  const filterRef = useRef(null);
+  const [filterPlaceholder, setFilterPlaceholder] = useState("Filter...");
+  useEffect(() => {
+    const platform = navigator.userAgentData?.platform ?? navigator.platform;
+    const isMac = /mac/i.test(platform);
+    setFilterPlaceholder(isMac ? "Filter... (\u2318 + /)" : "Filter... (Ctrl + /)");
+  }, []);
+  useEffect(() => {
+    function handleKeyDown(e) {
+      if (e.isComposing) return;
+      if (e.key === "/" && (e.metaKey || e.ctrlKey)) {
+        const el = filterRef.current;
+        if (!el || el.offsetParent === null) return;
+        e.preventDefault();
+        el.focus();
+        el.select();
+      }
+    }
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, []);
+  const filteredNodes = useMemo(
+    () => query ? filterTree(nodes, query) : nodes,
+    [nodes, query]
+  );
+  const footer = useMemo(
+    () => localeLinks || themeDefaultMode ? /* @__PURE__ */ jsx(SidebarFooter, { links: localeLinks, themeDefaultMode }) : null,
+    [localeLinks, themeDefaultMode]
+  );
+  if (showingRootMenu && rootMenuItems) {
+    return /* @__PURE__ */ jsxs("nav", { children: [
+      /* @__PURE__ */ jsxs(
+        "button",
+        {
+          type: "button",
+          onClick: () => setShowingRootMenu(false),
+          className: "flex w-full items-center gap-hsp-xs px-hsp-sm py-vsp-xs text-left text-small text-muted hover:text-fg border-b border-muted",
+          children: [
+            /* @__PURE__ */ jsx(ChevronRight, { className: "h-icon-sm w-icon-sm shrink-0" }),
+            backToMenuLabel ?? "Back to main menu"
+          ]
+        }
+      ),
+      rootMenuItems.map((item) => /* @__PURE__ */ jsx(RootMenuItemEntry, { item }, item.href)),
+      footer
+    ] });
+  }
+  if (activeSlug === void 0 && rootMenuItems) {
+    return /* @__PURE__ */ jsxs("nav", { children: [
+      rootMenuItems.map((item) => /* @__PURE__ */ jsx(RootMenuItemEntry, { item }, item.href)),
+      footer
+    ] });
+  }
+  return /* @__PURE__ */ jsxs("nav", { children: [
+    rootMenuItems && /* @__PURE__ */ jsxs(
+      "button",
+      {
+        type: "button",
+        onClick: () => setShowingRootMenu(true),
+        className: "lg:hidden flex w-full items-center gap-hsp-xs px-hsp-sm py-vsp-xs text-left text-small text-muted hover:text-fg border-b border-muted",
+        children: [
+          /* @__PURE__ */ jsx(ChevronLeft, { className: "h-icon-sm w-icon-sm shrink-0" }),
+          backToMenuLabel ?? "Back to main menu"
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx("div", { className: "px-hsp-sm py-vsp-xs", children: /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-hsp-xs bg-surface rounded px-hsp-sm py-vsp-2xs", children: [
+      /* @__PURE__ */ jsx(Search, { className: "h-[14px] w-[14px] text-muted shrink-0" }),
+      /* @__PURE__ */ jsx(
+        "input",
+        {
+          ref: filterRef,
+          type: "text",
+          "aria-label": "Filter navigation",
+          placeholder: filterPlaceholder,
+          value: query,
+          onInput: (e) => setQuery(e.currentTarget.value),
+          className: "bg-transparent text-small outline-none w-full text-fg placeholder:text-muted"
+        }
+      )
+    ] }) }),
+    /* @__PURE__ */ jsx(
+      NodeList,
+      {
+        nodes: filteredNodes,
+        currentSlug: activeSlug,
+        depth: 0,
+        forceOpen: !!query
+      }
+    ),
+    footer
+  ] });
+}
+SidebarTree.displayName = "SidebarTree";
+const NodeList = memo(function NodeList2({
+  nodes,
+  currentSlug,
+  depth,
+  forceOpen
+}) {
+  return /* @__PURE__ */ jsx(Fragment, { children: nodes.map((node, index) => {
+    const isLast = index === nodes.length - 1;
+    return node.children.length > 0 ? /* @__PURE__ */ jsx(
+      CategoryNode,
+      {
+        node,
+        currentSlug,
+        depth,
+        isLast,
+        forceOpen
+      },
+      node.slug
+    ) : /* @__PURE__ */ jsx(
+      LeafNode,
+      {
+        node,
+        currentSlug,
+        depth,
+        isLast
+      },
+      node.slug
+    );
+  }) });
+});
+function subtreeContainsSlug(node, slug) {
+  if (!slug) return false;
+  if (node.slug === slug) return true;
+  return node.children.some((child) => subtreeContainsSlug(child, slug));
+}
+const CategoryNode = memo(function CategoryNode2({
+  node,
+  currentSlug,
+  depth,
+  isLast,
+  forceOpen
+}) {
+  const containsCurrent = useMemo(
+    () => subtreeContainsSlug(node, currentSlug),
+    [node, currentSlug]
+  );
+  const isActive = node.slug === currentSlug;
+  const labelHtml = useMemo(() => smartBreakToHtml(node.label), [node.label]);
+  const [open, setOpen] = useState(containsCurrent ? true : !node.collapsed);
+  useEffect(() => {
+    const stored = getOpenSet();
+    if (stored.has(node.slug) && !open) {
+      setOpen(true);
+    }
+  }, []);
+  useEffect(() => {
+    if (subtreeContainsSlug(node, currentSlug) && !open) {
+      setOpen(true);
+      const stored = getOpenSet();
+      stored.add(node.slug);
+      saveOpenSet(stored);
+    }
+  }, [currentSlug]);
+  useEffect(() => {
+    if (open) {
+      const stored = getOpenSet();
+      if (!stored.has(node.slug)) {
+        stored.add(node.slug);
+        saveOpenSet(stored);
+      }
+    }
+  }, [open, node.slug]);
+  const toggle = useCallback(() => {
+    setOpen((prev) => {
+      const next = !prev;
+      const stored = getOpenSet();
+      if (next) {
+        stored.add(node.slug);
+      } else {
+        stored.delete(node.slug);
+      }
+      saveOpenSet(stored);
+      return next;
+    });
+  }, [node.slug]);
+  const isExpanded = forceOpen || open;
+  const paddingLeft = padLeft(depth, true);
+  return /* @__PURE__ */ jsxs("div", { className: `${depth === 0 ? "border-t border-muted" : ""} ${depth >= 1 && !isLast ? "relative" : ""}`, children: [
+    depth >= 1 && !isLast && isExpanded && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "absolute border-l border-solid border-muted z-local-1",
+        style: {
+          left: connectorLeft(depth),
+          top: 0,
+          bottom: 0
+        }
+      }
+    ),
+    /* @__PURE__ */ jsxs("div", { className: "relative", children: [
+      /* @__PURE__ */ jsx(ConnectorLines, { depth, isLast, topPad: "calc(0.15rem + var(--spacing-vsp-xs))" }),
+      node.href ? /* @__PURE__ */ jsxs(
+        "div",
+        {
+          className: `flex w-full items-center text-small font-semibold pt-[0.15rem] ${isActive ? "bg-fg text-bg" : "text-fg"}`,
+          children: [
+            /* @__PURE__ */ jsxs(
+              "a",
+              {
+                href: node.href,
+                "aria-current": isActive ? "page" : void 0,
+                className: `flex-1 flex items-start gap-hsp-xs py-vsp-xs hover:underline focus:underline break-words ${isActive ? "text-bg" : "text-fg"}`,
+                style: { paddingLeft },
+                children: [
+                  depth === 0 && /* @__PURE__ */ jsx("span", { className: "flex h-[1lh] items-center", children: /* @__PURE__ */ jsx(CategoryLinkIcon, { className: `w-[14px] ${isActive ? "text-bg" : ""}` }) }),
+                  /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: labelHtml } })
+                ]
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                onClick: toggle,
+                className: `aspect-square flex items-center justify-center w-[1.5rem] border-y border-l hover:underline focus:underline ${isActive ? "border-bg/30" : "border-muted"}`,
+                "aria-expanded": isExpanded,
+                "aria-label": isExpanded ? `Collapse ${node.label}` : `Expand ${node.label}`,
+                children: /* @__PURE__ */ jsx(ToggleChevron, { isExpanded, className: isActive ? "text-bg" : "text-muted" })
+              }
+            )
+          ]
+        }
+      ) : /* @__PURE__ */ jsxs(
+        "button",
+        {
+          type: "button",
+          onClick: toggle,
+          className: `flex w-full items-center gap-hsp-md text-left text-small font-semibold py-vsp-xs text-fg hover:underline focus:underline break-words`,
+          style: { paddingLeft },
+          "aria-expanded": isExpanded,
+          "aria-label": isExpanded ? `Collapse ${node.label}` : `Expand ${node.label}`,
+          children: [
+            /* @__PURE__ */ jsx("span", { className: "aspect-square flex items-center justify-center w-[1.5rem] shrink-0 border border-muted", children: /* @__PURE__ */ jsx(ToggleChevron, { isExpanded, className: "text-muted" }) }),
+            /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: labelHtml } })
+          ]
+        }
+      )
+    ] }),
+    isExpanded && /* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(
+      NodeList,
+      {
+        nodes: node.children,
+        currentSlug,
+        depth: depth + 1,
+        forceOpen
+      }
+    ) })
+  ] });
+});
+const LeafNode = memo(function LeafNode2({
+  node,
+  currentSlug,
+  depth,
+  isLast
+}) {
+  const labelHtml = useMemo(() => smartBreakToHtml(node.label), [node.label]);
+  if (!node.href) return null;
+  const isActive = node.slug === currentSlug;
+  const isRoot = depth === 0;
+  const paddingLeft = padLeft(depth, isRoot);
+  const outerClass = isRoot ? "border-t border-muted" : !isRoot && isLast ? "pb-vsp-md" : "";
+  const topPad = isRoot ? "calc(var(--spacing-vsp-xs) + 0.15rem)" : "var(--spacing-vsp-2xs)";
+  return /* @__PURE__ */ jsx("div", { className: outerClass, children: /* @__PURE__ */ jsxs("div", { className: "relative", children: [
+    /* @__PURE__ */ jsx(ConnectorLines, { depth, isLast, topPad }),
+    /* @__PURE__ */ jsxs(
+      "a",
+      {
+        href: node.href,
+        "aria-current": isActive ? "page" : void 0,
+        className: isRoot ? `flex items-start gap-hsp-xs py-[calc(var(--spacing-vsp-xs)+0.15rem)] pr-[4px] text-small font-semibold break-words ${isActive ? "bg-fg text-bg" : "text-fg hover:underline focus:underline"}` : `block py-vsp-2xs pr-[4px] text-small break-words ${isActive ? "bg-fg font-medium text-bg" : "text-muted hover:underline focus:underline"}`,
+        style: { paddingLeft },
+        children: [
+          isRoot && /* @__PURE__ */ jsx("span", { className: "flex h-[1lh] items-center", children: /* @__PURE__ */ jsx(CategoryLinkIcon, { className: `w-[14px] ${isActive ? "text-bg" : ""}` }) }),
+          /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: labelHtml } })
+        ]
+      }
+    )
+  ] }) });
+});
+export {
+  SidebarTree
+};

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

@@ -0,0 +1,64 @@
+export interface SidebarLink {
+    type: "link";
+    label: string;
+    href: string;
+}
+export interface SidebarDoc {
+    type: "doc";
+    /** Doc slug, e.g. "getting-started/introduction" */
+    id: string;
+    /** Override the doc's title in sidebar */
+    label?: string;
+}
+export interface SidebarCategory {
+    type: "category";
+    label: string;
+    items: SidebarItem[];
+    collapsed?: boolean;
+    sortOrder?: "asc" | "desc";
+}
+export interface SidebarAutogenerated {
+    type: "autogenerated";
+    dirName?: string;
+}
+/**
+ * A sidebar item — string shorthand is equivalent to `{ type: "doc", id: slug }`.
+ */
+export type SidebarItem = SidebarDoc | SidebarLink | SidebarCategory | SidebarAutogenerated | string;
+/** Sidebar config keyed by section (categoryMatch value). */
+export type SidebarsConfig = {
+    [sectionKey: string]: SidebarItem[] | undefined;
+};
+/** Minimal nav node shape required by sidebar-utils functions. */
+export interface SidebarNavNode {
+    slug: string;
+    label: string;
+    description?: string;
+    position: number;
+    href?: string;
+    hasPage: boolean;
+    children: SidebarNavNode[];
+    sortOrder?: "asc" | "desc";
+    collapsed?: boolean;
+}
+/** Category metadata shape (mirrors host's CategoryMeta). */
+export interface SidebarCategoryMeta {
+    label?: string;
+    position?: number;
+    collapsed?: boolean;
+}
+/**
+ * Build sidebar nodes for a given nav section.
+ *
+ * If sidebar config exists for this section, use it. Otherwise fall back to
+ * the auto-generated tree filtered to the section's categoryMatch.
+ *
+ * Parameterized version of the host's `buildSidebarForSection` from
+ * `src/utils/sidebar.ts` — receives `sidebars`, `buildNavTree`, and
+ * `explicitCategoryPrefixes` as arguments instead of importing from
+ * `@/config/sidebars`, `@/utils/docs`, `@/utils/nav-scope`.
+ *
+ * `explicitCategoryPrefixes` is the pre-computed list of non-`"!"` categoryMatch
+ * values from headerNav, used for the `"!"` fallback category filter.
+ */
+export declare function buildSidebarForSection(docs: unknown[], lang: string, categoryMatch: string | undefined, categoryMeta: Map<string, SidebarCategoryMeta> | undefined, sidebars: SidebarsConfig, buildNavTree: (docs: unknown[], lang: string, categoryMeta?: Map<string, SidebarCategoryMeta>) => SidebarNavNode[], explicitCategoryPrefixes: string[]): SidebarNavNode[];

package/dist/sidebar-utils/index.js

@@ -0,0 +1,88 @@
+function findNode(tree, slug) {
+  for (const node of tree) {
+    if (node.slug === slug) return node;
+    if (node.children.length > 0) {
+      const found = findNode(node.children, slug);
+      if (found) return found;
+    }
+  }
+  return void 0;
+}
+function resolveItems(items, tree, lang) {
+  return items.flatMap((item) => resolveItem(item, tree, lang));
+}
+function resolveItem(item, tree, lang) {
+  if (typeof item === "string") {
+    const node = findNode(tree, item);
+    return node ? [{ ...node, children: [] }] : [];
+  }
+  switch (item.type) {
+    case "doc": {
+      const node = findNode(tree, item.id);
+      if (!node) return [];
+      return [{ ...node, children: [], ...item.label ? { label: item.label } : {} }];
+    }
+    case "link": {
+      return [
+        {
+          slug: `__link__${item.href}`,
+          label: item.label,
+          href: item.href,
+          position: 0,
+          hasPage: false,
+          children: []
+        }
+      ];
+    }
+    case "category": {
+      const children = resolveItems(item.items, tree, lang);
+      if (item.sortOrder === "desc") {
+        children.reverse();
+      }
+      return [
+        {
+          slug: `__category__${item.label}`,
+          label: item.label,
+          position: 0,
+          hasPage: false,
+          href: void 0,
+          children,
+          sortOrder: item.sortOrder,
+          collapsed: item.collapsed
+        }
+      ];
+    }
+    case "autogenerated": {
+      if (item.dirName) {
+        const node = findNode(tree, item.dirName);
+        return node ? node.children : [];
+      }
+      return tree;
+    }
+    default: {
+      const _exhaustive = item;
+      throw new Error(`Unhandled sidebar item type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+function filterByCategory(tree, categoryMatch, explicitPrefixes) {
+  if (!categoryMatch) return tree;
+  if (categoryMatch === "!") {
+    return tree.filter(
+      (node) => !explicitPrefixes.some((prefix) => node.slug.startsWith(prefix))
+    );
+  }
+  return tree.filter((node) => node.slug.startsWith(categoryMatch));
+}
+function buildSidebarForSection(docs, lang, categoryMatch, categoryMeta, sidebars, buildNavTree, explicitCategoryPrefixes) {
+  const tree = buildNavTree(docs, lang, categoryMeta);
+  const sectionKey = categoryMatch ?? "default";
+  const config = sidebars[sectionKey];
+  if (!config || config.length === 0) {
+    return filterByCategory(tree, categoryMatch, explicitCategoryPrefixes);
+  }
+  return resolveItems(config, tree, lang);
+}
+export {
+  buildSidebarForSection
+};