@takazudo/zudo-doc 0.1.0

package/dist/page-loading/page-loading-overlay.js

@@ -0,0 +1,50 @@
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import {
+  AFTER_NAVIGATE_EVENT,
+  BEFORE_NAVIGATE_EVENT
+} from "../transitions/page-events.js";
+const PAGE_LOADING_OVERLAY_ID = "page-loading-overlay";
+function buildPageLoadingOverlayBootstrap(overlayId) {
+  const id = JSON.stringify(overlayId);
+  const before = JSON.stringify(BEFORE_NAVIGATE_EVENT);
+  const after = JSON.stringify(AFTER_NAVIGATE_EVENT);
+  return `(function(){
+var id=${id};
+function show(){var el=document.getElementById(id);if(!el)return;el.setAttribute("data-visible","");el.setAttribute("aria-hidden","false");}
+function hide(){var el=document.getElementById(id);if(!el)return;el.removeAttribute("data-visible");el.setAttribute("aria-hidden","true");}
+function setPending(ev){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});var src=ev&&ev.sourceElement;if(src&&src instanceof Element)src.setAttribute("data-zd-nav-pending","");}
+function clearPending(){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});}
+document.addEventListener(${before},show);
+document.addEventListener(${after},hide);
+document.addEventListener(${before},setPending);
+document.addEventListener(${after},clearPending);
+})();`;
+}
+function PageLoadingOverlay({
+  id = PAGE_LOADING_OVERLAY_ID
+} = {}) {
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        id,
+        class: "page-loading-overlay",
+        "aria-hidden": "true",
+        children: /* @__PURE__ */ jsx("span", { class: "page-loading-spinner" })
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      "script",
+      {
+        dangerouslySetInnerHTML: {
+          __html: buildPageLoadingOverlayBootstrap(id)
+        }
+      }
+    )
+  ] });
+}
+export {
+  PAGE_LOADING_OVERLAY_ID,
+  buildPageLoadingOverlayBootstrap,
+  PageLoadingOverlay as default
+};

package/dist/sidebar/index.d.ts

@@ -0,0 +1,3 @@
+export { Sidebar, SidebarProps } from './sidebar.js';
+export { SidebarLocaleLink, SidebarNavNode, SidebarRootMenuItem, SidebarTreeIslandProps } from './types.js';
+import 'preact';

package/dist/sidebar/index.js

@@ -0,0 +1,4 @@
+import { Sidebar } from "./sidebar.js";
+export {
+  Sidebar
+};

package/dist/sidebar/sidebar.d.ts

@@ -0,0 +1,54 @@
+import { FunctionComponent, ComponentChildren, VNode } from 'preact';
+import { SidebarTreeIslandProps } from './types.js';
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+interface SidebarProps extends SidebarTreeIslandProps {
+    /**
+     * The host's SidebarTree component. When present, the shell renders
+     * `<TreeComponent {...islandProps} />` with the typed props below.
+     * Mutually exclusive with `children`: prefer this form so v2 owns the
+     * prop forwarding contract.
+     */
+    treeComponent?: FunctionComponent<SidebarTreeIslandProps>;
+    /**
+     * Pre-rendered tree content — falls back to this when
+     * `treeComponent` is omitted. Useful for tests and for layouts that
+     * compose the tree separately (e.g. inside an Astro `.astro` wrapper
+     * that needs `client:load` on the actual island element).
+     */
+    children?: ComponentChildren;
+}
+/**
+ * Sidebar shell — typed wrapper around the SidebarTree island.
+ *
+ * Two usage shapes (matching the breadcrumb shell's pattern):
+ *
+ *   1. Pass `treeComponent` plus the data props (`nodes`,
+ *      `rootMenuItems`, `localeLinks`, …). The shell forwards them all
+ *      to the supplied component.
+ *
+ *   2. Pass `children` (e.g. a pre-instantiated `<SidebarTree
+ *      client:load … />` from an Astro wrapper). The shell renders
+ *      them as-is — the typed island props are then unused but kept on
+ *      the type signature so call-sites stay self-documenting.
+ *
+ * **The caller is responsible for wrapping this in `<Island when="load">`**
+ * so the SSG output emits the `data-zfb-island="Sidebar"` hydration
+ * marker around the rendered tree. `<DocLayoutWithDefaults>` does this
+ * for you; consumers who render `<Sidebar>` outside the default layout
+ * (e.g. via the `sidebarOverride` prop or in a custom layout) must
+ * apply the wrapper themselves — otherwise no hydration marker is
+ * emitted, and the runtime walks past the SSR'd tree without claiming
+ * it as an island. Either way the actual user-facing interactivity
+ * comes from the `treeComponent`'s own island registration; the
+ * `<Island>` wrapper here exists so the shell can host data-only
+ * variants in the future without losing the marker contract.
+ */
+declare function Sidebar(props: SidebarProps): VNode | null;
+declare namespace Sidebar {
+    var displayName: string;
+}
+
+export { Sidebar, type SidebarProps };

package/dist/sidebar/sidebar.js

@@ -0,0 +1,35 @@
+"use client";
+import { Fragment, jsx } from "preact/jsx-runtime";
+function Sidebar(props) {
+  const {
+    treeComponent: TreeComponent,
+    children,
+    nodes,
+    currentSlug,
+    rootMenuItems,
+    backToMenuLabel,
+    localeLinks,
+    themeDefaultMode
+  } = props;
+  if (TreeComponent) {
+    return /* @__PURE__ */ jsx(
+      TreeComponent,
+      {
+        nodes,
+        currentSlug,
+        rootMenuItems,
+        backToMenuLabel,
+        localeLinks,
+        themeDefaultMode
+      }
+    );
+  }
+  if (children !== void 0 && children !== null) {
+    return /* @__PURE__ */ jsx(Fragment, { children });
+  }
+  return null;
+}
+Sidebar.displayName = "Sidebar";
+export {
+  Sidebar
+};

package/dist/sidebar/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Public types for the framework-agnostic sidebar shell.
+ *
+ * The original Astro `sidebar.astro` mixed three concerns:
+ *   1. Building `rootMenuItems` from `settings.headerNav` (with i18n
+ *      label resolution and version-aware hrefs).
+ *   2. Building the doc tree via `loadLocaleDocs` +
+ *      `buildSidebarForSection`, then optionally remapping hrefs to
+ *      versioned paths.
+ *   3. Rendering a `<SidebarTree client:load .../>` Preact island.
+ *
+ * Concerns (1) and (2) depend on host-only helpers that v2 must not
+ * reach into. The v2 shell exists to:
+ *   - publish the prop shape so the host's data prep code can be
+ *     typed against a v2-owned interface, and
+ *   - render whatever the host hands in (typically the project's
+ *     `<SidebarTree client:load .../>` island) inside a typed wrapper.
+ *
+ * The structural types here mirror `src/utils/docs.ts` (`NavNode`) and
+ * `src/types/locale.ts` (`LocaleLink`) so the host can keep using its
+ * existing data-prep pipeline without re-mapping fields.
+ */
+/**
+ * One node in the navigation tree the SidebarTree island renders.
+ * Matches `NavNode` in the host project's `src/utils/docs.ts`.
+ */
+interface SidebarNavNode {
+    slug: string;
+    label: string;
+    description?: string;
+    position: number;
+    href?: string;
+    hasPage: boolean;
+    children: SidebarNavNode[];
+    sortOrder?: "asc" | "desc";
+    collapsed?: boolean;
+}
+/**
+ * Item in the root-level "Docusaurus-style" menu shown above the
+ * doc tree on mobile / inside the back-to-menu view.
+ */
+interface SidebarRootMenuItem {
+    label: string;
+    href: string;
+    children?: SidebarRootMenuItem[];
+}
+/**
+ * Locale switcher link rendered inside the mobile sidebar footer.
+ * Matches `LocaleLink` in the host project's `src/types/locale.ts`.
+ */
+interface SidebarLocaleLink {
+    code: string;
+    label: string;
+    href: string;
+    active: boolean;
+}
+/**
+ * Props the SidebarTree island consumes. The shell forwards these
+ * to whichever component the host plugs in via {@link SidebarProps.treeComponent}
+ * (or to nothing, when the host renders its own tree as `children`).
+ */
+interface SidebarTreeIslandProps {
+    nodes: SidebarNavNode[];
+    currentSlug?: string;
+    rootMenuItems?: SidebarRootMenuItem[];
+    backToMenuLabel?: string;
+    localeLinks?: SidebarLocaleLink[];
+    themeDefaultMode?: "light" | "dark";
+}
+
+export type { SidebarLocaleLink, SidebarNavNode, SidebarRootMenuItem, SidebarTreeIslandProps };

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

@@ -0,0 +1,14 @@
+export { SIDEBAR_RESIZER_INIT_SCRIPT, SidebarResizerInit } from './sidebar-resizer-init.js';
+import 'preact';
+
+/**
+ * Attach the sidebar drag handle to `#desktop-sidebar`. Idempotent —
+ * safe to call repeatedly (e.g. after each route swap). No-op if the
+ * sidebar element is missing or the handle is already in place.
+ *
+ * Designed to be called from the browser only. Guards against `document`
+ * being undefined so accidental SSR invocation does not throw.
+ */
+declare function initSidebarResizer(): void;
+
+export { initSidebarResizer };

package/dist/sidebar-resizer/index.js

@@ -0,0 +1,165 @@
+const SIDEBAR_ID = "desktop-sidebar";
+const HANDLE_MARKER = "data-sidebar-resizer";
+const MIN_W = 192;
+const MAX_W = 448;
+const STEP = 10;
+const LS_KEY = "zudo-doc-sidebar-width";
+const CSS_PROP = "--zd-sidebar-w";
+const ACCENT_BG = "var(--zd-accent, rgba(128,128,128,0.3))";
+const ACCENT_OUTLINE = "2px solid var(--zd-accent, rgba(128,128,128,0.5))";
+const ACCENT_GHOST = "var(--zd-accent, rgba(128,128,128,0.5))";
+function initSidebarResizer() {
+  if (typeof document === "undefined") return;
+  const sidebar = document.getElementById(SIDEBAR_ID);
+  if (!sidebar || sidebar.querySelector(`[${HANDLE_MARKER}]`)) return;
+  function readCurrentWidth() {
+    const raw = getComputedStyle(document.documentElement).getPropertyValue(
+      CSS_PROP
+    );
+    return raw ? parseFloat(raw) || MIN_W : MIN_W;
+  }
+  let cachedWidth = readCurrentWidth();
+  const handle = document.createElement("div");
+  handle.setAttribute(HANDLE_MARKER, "");
+  handle.setAttribute("tabindex", "0");
+  handle.setAttribute("role", "separator");
+  handle.setAttribute("aria-orientation", "vertical");
+  handle.setAttribute("aria-label", "Resize sidebar");
+  handle.setAttribute("aria-valuemin", String(MIN_W));
+  handle.setAttribute("aria-valuemax", String(MAX_W));
+  handle.setAttribute("aria-valuenow", String(Math.round(cachedWidth)));
+  Object.assign(handle.style, {
+    position: "absolute",
+    top: "0",
+    right: "0",
+    width: "20px",
+    height: "100%",
+    cursor: "col-resize",
+    zIndex: "10",
+    transition: "background 0.15s"
+  });
+  let dragging = false;
+  let focused = false;
+  function applyWidth(w) {
+    cachedWidth = Math.max(MIN_W, Math.min(MAX_W, w));
+    document.documentElement.style.setProperty(CSS_PROP, cachedWidth + "px");
+    try {
+      localStorage.setItem(LS_KEY, String(Math.round(cachedWidth)));
+    } catch {
+    }
+    handle.setAttribute("aria-valuenow", String(Math.round(cachedWidth)));
+  }
+  function updateHandleVisual() {
+    if (dragging || focused) {
+      handle.style.background = ACCENT_BG;
+    } else {
+      handle.style.background = "";
+    }
+    handle.style.outline = focused && !dragging ? ACCENT_OUTLINE : "";
+    handle.style.outlineOffset = focused && !dragging ? "1px" : "";
+  }
+  handle.addEventListener("focus", () => {
+    focused = true;
+    updateHandleVisual();
+  });
+  handle.addEventListener("blur", () => {
+    focused = false;
+    updateHandleVisual();
+  });
+  handle.addEventListener("keydown", (e) => {
+    let w = cachedWidth;
+    switch (e.key) {
+      case "ArrowLeft":
+        w = Math.max(MIN_W, w - STEP);
+        break;
+      case "ArrowRight":
+        w = Math.min(MAX_W, w + STEP);
+        break;
+      case "Home":
+        w = MIN_W;
+        break;
+      case "End":
+        w = MAX_W;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    applyWidth(w);
+  });
+  handle.addEventListener("mouseenter", () => {
+    if (!dragging && !focused) handle.style.background = ACCENT_BG;
+  });
+  handle.addEventListener("mouseleave", () => {
+    if (!dragging && !focused) handle.style.background = "";
+  });
+  handle.addEventListener("pointerdown", (e) => {
+    e.preventDefault();
+    handle.setPointerCapture(e.pointerId);
+    dragging = true;
+    updateHandleVisual();
+    document.documentElement.style.cursor = "col-resize";
+    document.documentElement.style.userSelect = "none";
+    const ghost = document.createElement("div");
+    Object.assign(ghost.style, {
+      position: "fixed",
+      top: "0",
+      width: "2px",
+      height: "100vh",
+      background: ACCENT_GHOST,
+      pointerEvents: "none",
+      zIndex: "9999"
+    });
+    const sidebarRect = sidebar.getBoundingClientRect();
+    const sidebarLeft = sidebarRect.left;
+    ghost.style.left = sidebarLeft + sidebarRect.width + "px";
+    document.body.appendChild(ghost);
+    let targetWidth = 0;
+    let cleaned = false;
+    const onMove = (ev) => {
+      targetWidth = Math.max(
+        MIN_W,
+        Math.min(MAX_W, ev.clientX - sidebarLeft)
+      );
+      ghost.style.left = sidebarLeft + targetWidth + "px";
+    };
+    const cleanup = () => {
+      if (cleaned) return;
+      cleaned = true;
+      dragging = false;
+      updateHandleVisual();
+      document.documentElement.style.cursor = "";
+      document.documentElement.style.userSelect = "";
+      ghost.remove();
+      handle.removeEventListener("pointermove", onMove);
+      handle.removeEventListener("pointerup", onUp);
+      handle.removeEventListener("pointercancel", onCancel);
+      handle.removeEventListener("lostpointercapture", onLost);
+    };
+    const commit = () => {
+      if (targetWidth > 0) applyWidth(targetWidth);
+    };
+    const onUp = () => {
+      commit();
+      cleanup();
+    };
+    const onLost = () => {
+      commit();
+      cleanup();
+    };
+    const onCancel = () => {
+      cleanup();
+    };
+    handle.addEventListener("pointermove", onMove);
+    handle.addEventListener("pointerup", onUp);
+    handle.addEventListener("pointercancel", onCancel);
+    handle.addEventListener("lostpointercapture", onLost);
+  });
+  sidebar.appendChild(handle);
+}
+import { SidebarResizerInit, SIDEBAR_RESIZER_INIT_SCRIPT } from "./sidebar-resizer-init.js";
+export {
+  SIDEBAR_RESIZER_INIT_SCRIPT,
+  SidebarResizerInit,
+  initSidebarResizer
+};

package/dist/sidebar-resizer/sidebar-resizer-init.d.ts

@@ -0,0 +1,20 @@
+import { JSX } from 'preact';
+
+/** @jsxImportSource preact */
+
+declare const SIDEBAR_RESIZER_INIT_SCRIPT: string;
+/**
+ * Drop-in JSX body-end script for sidebar resize initialization.
+ *
+ * Include once in the layout (gated on `settings.sidebarResizer`). Emits
+ * the full `initSidebarResizer` implementation as an inline
+ * `dangerouslySetInnerHTML` script so it runs without a module import.
+ *
+ * - Calls `initSidebarResizer()` once on first paint.
+ * - Re-runs on `AFTER_NAVIGATE_EVENT` (`zfb:after-swap`) for
+ *   Strategy B SPA navigation support.
+ * - Idempotent: repeated calls on the same DOM are safe.
+ */
+declare function SidebarResizerInit(): JSX.Element;
+
+export { SIDEBAR_RESIZER_INIT_SCRIPT, SidebarResizerInit, SidebarResizerInit as default };

package/dist/sidebar-resizer/sidebar-resizer-init.js

@@ -0,0 +1,119 @@
+import { jsx } from "preact/jsx-runtime";
+import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
+const SIDEBAR_RESIZER_INIT_SCRIPT = `(function(){
+  var SIDEBAR_ID="desktop-sidebar";
+  var HANDLE_MARKER="data-sidebar-resizer";
+  var MIN_W=192,MAX_W=448,STEP=10;
+  var LS_KEY="zudo-doc-sidebar-width";
+  var CSS_PROP="--zd-sidebar-w";
+  var ACCENT_BG="var(--zd-accent,rgba(128,128,128,0.3))";
+  var ACCENT_OUTLINE="2px solid var(--zd-accent,rgba(128,128,128,0.5))";
+  var ACCENT_GHOST="var(--zd-accent,rgba(128,128,128,0.5))";
+
+  function initSidebarResizer(){
+    if(typeof document==="undefined")return;
+    var sidebar=document.getElementById(SIDEBAR_ID);
+    if(!sidebar||sidebar.querySelector("["+HANDLE_MARKER+"]"))return;
+
+    function readCurrentWidth(){
+      var raw=getComputedStyle(document.documentElement).getPropertyValue(CSS_PROP);
+      return raw?parseFloat(raw)||MIN_W:MIN_W;
+    }
+    var cachedWidth=readCurrentWidth();
+
+    var handle=document.createElement("div");
+    handle.setAttribute(HANDLE_MARKER,"");
+    handle.setAttribute("tabindex","0");
+    handle.setAttribute("role","separator");
+    handle.setAttribute("aria-orientation","vertical");
+    handle.setAttribute("aria-label","Resize sidebar");
+    handle.setAttribute("aria-valuemin",String(MIN_W));
+    handle.setAttribute("aria-valuemax",String(MAX_W));
+    handle.setAttribute("aria-valuenow",String(Math.round(cachedWidth)));
+    // 20px hit area > native y-scrollbar (~12-17px) so a draggable strip stays
+    // visible to the LEFT of the scrollbar when sidebar overflows. zudolab/zudo-doc#1660
+    Object.assign(handle.style,{position:"absolute",top:"0",right:"0",width:"20px",height:"100%",cursor:"col-resize",zIndex:"10",transition:"background 0.15s"});
+
+    var dragging=false,focused=false;
+
+    function applyWidth(w){
+      cachedWidth=Math.max(MIN_W,Math.min(MAX_W,w));
+      document.documentElement.style.setProperty(CSS_PROP,cachedWidth+"px");
+      try{localStorage.setItem(LS_KEY,String(Math.round(cachedWidth)));}catch(e){}
+      handle.setAttribute("aria-valuenow",String(Math.round(cachedWidth)));
+    }
+    function updateHandleVisual(){
+      handle.style.background=(dragging||focused)?ACCENT_BG:"";
+      handle.style.outline=(focused&&!dragging)?ACCENT_OUTLINE:"";
+      handle.style.outlineOffset=(focused&&!dragging)?"1px":"";
+    }
+
+    handle.addEventListener("focus",function(){focused=true;updateHandleVisual();});
+    handle.addEventListener("blur",function(){focused=false;updateHandleVisual();});
+    handle.addEventListener("keydown",function(e){
+      var w=cachedWidth;
+      if(e.key==="ArrowLeft")w=Math.max(MIN_W,w-STEP);
+      else if(e.key==="ArrowRight")w=Math.min(MAX_W,w+STEP);
+      else if(e.key==="Home")w=MIN_W;
+      else if(e.key==="End")w=MAX_W;
+      else return;
+      e.preventDefault();applyWidth(w);
+    });
+    handle.addEventListener("mouseenter",function(){if(!dragging&&!focused)handle.style.background=ACCENT_BG;});
+    handle.addEventListener("mouseleave",function(){if(!dragging&&!focused)handle.style.background="";});
+    handle.addEventListener("pointerdown",function(e){
+      e.preventDefault();handle.setPointerCapture(e.pointerId);
+      dragging=true;updateHandleVisual();
+      document.documentElement.style.cursor="col-resize";
+      document.documentElement.style.userSelect="none";
+      var ghost=document.createElement("div");
+      Object.assign(ghost.style,{position:"fixed",top:"0",width:"2px",height:"100vh",background:ACCENT_GHOST,pointerEvents:"none",zIndex:"9999"});
+      var sidebarRect=sidebar.getBoundingClientRect();
+      var sidebarLeft=sidebarRect.left;
+      ghost.style.left=sidebarLeft+sidebarRect.width+"px";
+      document.body.appendChild(ghost);
+      var targetWidth=0;
+      var cleaned=false;
+      function onMove(ev){targetWidth=Math.max(MIN_W,Math.min(MAX_W,ev.clientX-sidebarLeft));ghost.style.left=sidebarLeft+targetWidth+"px";}
+      function cleanup(){
+        if(cleaned)return;cleaned=true;
+        dragging=false;updateHandleVisual();
+        document.documentElement.style.cursor="";
+        document.documentElement.style.userSelect="";
+        ghost.remove();
+        handle.removeEventListener("pointermove",onMove);
+        handle.removeEventListener("pointerup",onUp);
+        handle.removeEventListener("pointercancel",onCancel);
+        handle.removeEventListener("lostpointercapture",onLost);
+      }
+      function commit(){if(targetWidth>0)applyWidth(targetWidth);}
+      // pointerup: normal end-of-drag. Commit then teardown.
+      function onUp(){commit();cleanup();}
+      // lostpointercapture: per spec fires AFTER pointerup, but browsers reorder
+      // these in edge cases (cursor near y-scrollbar, fast drags, OS handoff).
+      // Commit here too so a real drag still applies if pointerup is dropped.
+      // Idempotent with onUp via the cleaned guard.
+      function onLost(){commit();cleanup();}
+      // pointercancel: actual user/OS cancellation (touch interrupted, etc.).
+      // Do NOT commit \u2014 caller intent was to abort.
+      function onCancel(){cleanup();}
+      handle.addEventListener("pointermove",onMove);
+      handle.addEventListener("pointerup",onUp);
+      handle.addEventListener("pointercancel",onCancel);
+      handle.addEventListener("lostpointercapture",onLost);
+    });
+    sidebar.appendChild(handle);
+  }
+
+  initSidebarResizer();
+  document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)},initSidebarResizer);
+})();`;
+function SidebarResizerInit() {
+  return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: SIDEBAR_RESIZER_INIT_SCRIPT } });
+}
+var sidebar_resizer_init_default = SidebarResizerInit;
+export {
+  SIDEBAR_RESIZER_INIT_SCRIPT,
+  SidebarResizerInit,
+  sidebar_resizer_init_default as default
+};

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

@@ -0,0 +1,43 @@
+import { SidebarFrontmatter, CollectionEntryLike, BuildSidebarTreeOptions, SidebarNode } from './types.js';
+
+/**
+ * Framework-agnostic sidebar tree builder.
+ *
+ * Takes a flat list of content collection entries and emits a recursive
+ * `SidebarNode[]` that mirrors the filesystem layout — directories become
+ * category nodes, files become leaves. The shape is deliberately
+ * decoupled from astro:content so the same builder works against zfb's
+ * `getCollection` output, in-memory fixtures, etc.
+ *
+ * Ported from src/utils/docs.ts in the legacy zudo-doc Astro project.
+ */
+
+/**
+ * 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
+ *   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`).
+ * - 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"`.
+ */
+declare function buildSidebarTree<T extends SidebarFrontmatter = SidebarFrontmatter>(entries: CollectionEntryLike<T>[], locale: string, options?: BuildSidebarTreeOptions): SidebarNode[];
+/**
+ * Find a node by id (path slug) anywhere in the tree. Useful for sidebar
+ * config layers that resolve named doc references and for the breadcrumb
+ * builder. Exported alongside `buildSidebarTree` because both downstream
+ * topics (sub-tasks 4 and 5) need it.
+ */
+declare function findSidebarNode(nodes: SidebarNode[], id: string): SidebarNode | undefined;
+/**
+ * Depth-first flatten — only nodes with a backing page are emitted, in
+ * traversal order. Mirrors the legacy `flattenTree` used for prev/next
+ * navigation.
+ */
+declare function flattenSidebarTree(nodes: SidebarNode[]): SidebarNode[];
+
+export { buildSidebarTree, findSidebarNode, flattenSidebarTree };