@takazudo/zudo-doc 0.2.21 → 1.0.0

package/dist/url-helpers/index.js

@@ -0,0 +1,106 @@
+function makeUrlHelpers(settings, i18n) {
+  const { defaultLocale, locales, getLocaleLabel } = i18n;
+  const normalizedBase = settings.base.replace(/\/+$/, "");
+  function applyTrailingSlash(url) {
+    if (!settings.trailingSlash) return url;
+    if (url.endsWith("/")) return url;
+    const suffixIdx = url.search(/[?#]/);
+    const pathPart = suffixIdx >= 0 ? url.slice(0, suffixIdx) : url;
+    const suffix = suffixIdx >= 0 ? url.slice(suffixIdx) : "";
+    if (pathPart.endsWith("/")) return url;
+    const lastSegment = pathPart.split("/").pop() ?? "";
+    if (/\.[a-zA-Z]\w*$/.test(lastSegment)) return url;
+    return pathPart + "/" + suffix;
+  }
+  function withBase(path) {
+    const raw = normalizedBase === "" ? path : `${normalizedBase}${path.startsWith("/") ? path : `/${path}`}`;
+    return applyTrailingSlash(raw);
+  }
+  function stripBase(path) {
+    if (normalizedBase === "") return path;
+    if (path === normalizedBase) return "/";
+    return path.startsWith(`${normalizedBase}/`) ? path.slice(normalizedBase.length) : path;
+  }
+  function absoluteUrl(pageUrl) {
+    return settings.siteUrl ? settings.siteUrl.replace(/\/$/, "") + pageUrl : void 0;
+  }
+  function docsUrl(slug, lang = defaultLocale) {
+    const path = lang === defaultLocale ? `/docs/${slug}` : `/${lang}/docs/${slug}`;
+    return withBase(path);
+  }
+  function isExternal(href) {
+    return href.startsWith("http://") || href.startsWith("https://");
+  }
+  function resolveHref(href) {
+    return isExternal(href) ? href : withBase(href);
+  }
+  function navHref(path, lang, currentVersion) {
+    const isNonDefaultLocale = lang != null && lang !== defaultLocale;
+    const versionPrefix = currentVersion ? `/v/${currentVersion}` : "";
+    return withBase(
+      isNonDefaultLocale ? `${versionPrefix}/${lang}${path}` : `${versionPrefix}${path}`
+    );
+  }
+  function splitVersionPrefix(path) {
+    const m = path.match(/^(\/v\/[^/]+)(\/.*|$)/);
+    return m ? { versionPrefix: m[1] ?? "", rest: m[2] ?? "/" } : { versionPrefix: "", rest: path };
+  }
+  function getPathForLocale(path, currentLang, targetLang) {
+    const { versionPrefix, rest } = splitVersionPrefix(stripBase(path));
+    let relativePath = rest;
+    if (currentLang !== defaultLocale) {
+      relativePath = relativePath.replace(new RegExp(`^/${currentLang}(?:/|$)`), "/");
+    }
+    if (targetLang !== defaultLocale) {
+      relativePath = `/${targetLang}${relativePath}`;
+    }
+    return withBase(`${versionPrefix}${relativePath}`);
+  }
+  function isDefaultLocaleOnlyPath(path) {
+    const stripped = stripBase(path);
+    const normalized = stripped.endsWith("/") ? stripped : `${stripped}/`;
+    return settings.defaultLocaleOnlyPrefixes.some((prefix) => normalized.startsWith(prefix));
+  }
+  function buildLocaleLinks(currentPath, currentLang) {
+    let defaultLocalePath = splitVersionPrefix(stripBase(currentPath)).rest;
+    if (currentLang !== defaultLocale) {
+      defaultLocalePath = defaultLocalePath.replace(new RegExp(`^/${currentLang}(?:/|$)`), "/");
+    }
+    if (isDefaultLocaleOnlyPath(defaultLocalePath)) {
+      return [{
+        code: currentLang,
+        label: getLocaleLabel(currentLang),
+        href: getPathForLocale(currentPath, currentLang, currentLang),
+        active: true
+      }];
+    }
+    return locales.map((code) => ({
+      code,
+      label: getLocaleLabel(code),
+      href: getPathForLocale(currentPath, currentLang, code),
+      active: code === currentLang
+    }));
+  }
+  function versionedDocsUrl(slug, versionSlug, lang = defaultLocale) {
+    const path = lang === defaultLocale ? `/v/${versionSlug}/docs/${slug}` : `/v/${versionSlug}/${lang}/docs/${slug}`;
+    return withBase(path);
+  }
+  return {
+    normalizedBase,
+    applyTrailingSlash,
+    withBase,
+    stripBase,
+    absoluteUrl,
+    docsUrl,
+    isExternal,
+    resolveHref,
+    navHref,
+    getPathForLocale,
+    buildLocaleLinks,
+    isDefaultLocaleOnlyPath,
+    versionedDocsUrl
+  };
+}
+export {
+  makeUrlHelpers
+};

package/dist/url-normalizer/index.d.ts

@@ -1 +1,39 @@
-export { buildUrl, normalizePathname, shouldSkipNormalization } from './normalize.js';
+/**
+ * Public entry for `@takazudo/zudo-doc/url-normalizer`.
+ *
+ * Build-time URL normalizer that ensures every emitted route URL ends with
+ * a trailing slash, matching the `trailingSlash: "always"` policy of the
+ * legacy Astro build.
+ *
+ * ## Why build-time only?
+ *
+ * zfb is a purely static site builder — there is no server or dev middleware.
+ * The Astro `src/middleware-handler.ts` ran at request time; the equivalent
+ * guarantee is now split:
+ *
+ * - **Build time** (this module): `buildUrl()` constructs URLs that always
+ *   end with `/`, and `normalizePathname()` corrects any bare pathname passed
+ *   in from external data.
+ * - **Runtime**: the deployment host (e.g. Cloudflare Pages `_redirects`) is
+ *   responsible for redirecting requests that arrive without a trailing slash.
+ *
+ * See the "Trailing-Slash Policy" concept doc in the showcase docs for the
+ * full design rationale and an example `_redirects` rule.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import {
+ *   buildUrl,
+ *   normalizePathname,
+ *   shouldSkipNormalization,
+ * } from "@takazudo/zudo-doc/url-normalizer";
+ *
+ * // In a paths() implementation:
+ * const url = buildUrl("docs", slug);  // "/docs/my-slug/"
+ *
+ * // In an integration that receives raw pathnames:
+ * const canonical = normalizePathname(rawPathname);
+ * ```
+ */
+export { buildUrl, normalizePathname, shouldSkipNormalization } from "./normalize.js";

package/dist/url-normalizer/normalize.d.ts

@@ -58,7 +58,7 @@
  * buildUrl()                                     // "/"
  * buildUrl("", "docs", "")                       // "/docs/"
  */
-declare function buildUrl(...segments: string[]): string;
+export declare function buildUrl(...segments: string[]): string;
 /**
  * Return `true` when `pathname` should NOT receive a trailing slash.
  *
@@ -78,7 +78,7 @@ declare function buildUrl(...segments: string[]): string;
  * shouldSkipNormalization("/docs/guide")           // false (needs trailing slash)
  * shouldSkipNormalization("/docs/v2.0")            // false (number after dot → not an extension)
  */
-declare function shouldSkipNormalization(pathname: string): boolean;
+export declare function shouldSkipNormalization(pathname: string): boolean;
 /**
  * Return `pathname` with a trailing slash appended if needed.
  *
@@ -99,6 +99,4 @@ declare function shouldSkipNormalization(pathname: string): boolean;
  * normalizePathname("/docs/guide/")  // "/docs/guide/"  (no-op)
  * normalizePathname("/assets/app.js") // "/assets/app.js"  (skipped)
  */
-declare function normalizePathname(pathname: string): string;
-
-export { buildUrl, normalizePathname, shouldSkipNormalization };
+export declare function normalizePathname(pathname: string): string;

package/dist/use-modal-dialog/index.d.ts

@@ -0,0 +1,70 @@
+interface UseModalDialogOptions {
+    /** True when the dialog should be open. */
+    isOpen: boolean;
+    /** Called when the dialog is closed for any reason (Escape, backdrop, navigation). */
+    onClose: () => void;
+    /**
+     * DOM event name that triggers a close-and-reset. Pass the host's SPA
+     * after-navigate event name (e.g. `AFTER_NAVIGATE_EVENT`); pass `undefined`
+     * to skip navigation-close wiring entirely.
+     */
+    navigateEvent?: string;
+    /**
+     * When `true`, enable backdrop-click-to-close. The caller must forward the
+     * click handler returned by this hook to the `<dialog>` element's `onClick`.
+     * Defaults to `false` so opt-in only.
+     */
+    backdropClickClose?: boolean;
+    /**
+     * When `true`, enable focus management:
+     *  - On open: capture `document.activeElement` as the return target (unless
+     *    `returnFocusRef` is provided), then move focus to the first focusable
+     *    element inside the dialog (or the dialog itself as a fallback).
+     *  - On close: restore focus to the captured element.
+     *
+     * When a caller already manages focus internally (e.g. ai-chat-modal focuses
+     * its input in its own effect), pass `restoreFocusOnly: true` instead to get
+     * trigger-capture + restore without the "move into dialog" step.
+     */
+    manageFocus?: boolean;
+    /**
+     * Like `manageFocus` but skips the "focus first element in dialog" step —
+     * use when the caller has its own focus-on-open logic and only needs
+     * trigger-capture + focus restore on close.
+     */
+    restoreFocusOnly?: boolean;
+    /**
+     * Optional ref holding the element to return focus to on close. When
+     * provided and non-null, this takes precedence over the internally captured
+     * `document.activeElement`. Useful when the trigger element is conditionally
+     * rendered and therefore removed from the DOM before the open effect fires
+     * (e.g. the doc-history trigger button, which is unmounted when `isOpen`
+     * is true). The caller should set `returnFocusRef.current` to the trigger
+     * element in its click handler, before calling `setState`.
+     */
+    returnFocusRef?: React.RefObject<HTMLElement | null>;
+}
+interface UseModalDialogResult {
+    dialogRef: React.RefObject<HTMLDialogElement>;
+    /**
+     * Pass this to `<dialog onClick={handleBackdropClick}>`.
+     * Only wired when `backdropClickClose` is true; otherwise a no-op.
+     */
+    handleBackdropClick: (e: React.MouseEvent<HTMLDialogElement>) => void;
+}
+/**
+ * Shared hook for `<dialog>`-based modal components.
+ *
+ * Usage:
+ * ```tsx
+ * const { dialogRef, handleBackdropClick } = useModalDialog({
+ *   isOpen,
+ *   onClose: handleClose,
+ *   navigateEvent: AFTER_NAVIGATE_EVENT,
+ *   backdropClickClose: true,
+ * });
+ * return <dialog ref={dialogRef} onClick={handleBackdropClick} ... />;
+ * ```
+ */
+export declare function useModalDialog({ isOpen, onClose, navigateEvent, backdropClickClose, manageFocus, restoreFocusOnly, returnFocusRef, }: UseModalDialogOptions): UseModalDialogResult;
+export {};

package/dist/use-modal-dialog/index.js

@@ -0,0 +1,73 @@
+"use client";
+import { useEffect, useRef } from "preact/compat";
+function useModalDialog({
+  isOpen,
+  onClose,
+  navigateEvent,
+  backdropClickClose = false,
+  manageFocus = false,
+  restoreFocusOnly = false,
+  returnFocusRef
+}) {
+  const dialogRef = useRef(null);
+  const internalTriggerRef = useRef(null);
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (isOpen && !dialog.open) {
+      if ((manageFocus || restoreFocusOnly) && !returnFocusRef) {
+        internalTriggerRef.current = document.activeElement;
+      }
+      dialog.showModal();
+      if (manageFocus && !restoreFocusOnly) {
+        const FOCUSABLE = 'button:not([disabled]),a[href],[tabindex]:not([tabindex="-1"]),input:not([disabled]),select:not([disabled]),textarea:not([disabled])';
+        const first = dialog.querySelector(FOCUSABLE);
+        if (first) {
+          first.focus();
+        } else {
+          dialog.focus();
+        }
+      }
+    } else if (!isOpen && dialog.open) {
+      dialog.close();
+    }
+  }, [isOpen, manageFocus, restoreFocusOnly, returnFocusRef]);
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    function onDialogClose() {
+      if (manageFocus || restoreFocusOnly) {
+        const trigger = returnFocusRef ? returnFocusRef.current : internalTriggerRef.current;
+        if (trigger instanceof HTMLElement) {
+          trigger.focus();
+        }
+        internalTriggerRef.current = null;
+      }
+      if (isOpen) onClose();
+    }
+    dialog.addEventListener("close", onDialogClose);
+    return () => dialog.removeEventListener("close", onDialogClose);
+  }, [isOpen, onClose, manageFocus, restoreFocusOnly, returnFocusRef]);
+  useEffect(() => {
+    if (!navigateEvent) return;
+    function handleNavigation() {
+      const dialog = dialogRef.current;
+      if (dialog?.open) {
+        dialog.close();
+        onClose();
+      }
+    }
+    document.addEventListener(navigateEvent, handleNavigation);
+    return () => document.removeEventListener(navigateEvent, handleNavigation);
+  }, [navigateEvent, onClose]);
+  function handleBackdropClick(e) {
+    if (!backdropClickClose) return;
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (e.target === dialog) dialog.close();
+  }
+  return { dialogRef, handleBackdropClick };
+}
+export {
+  useModalDialog
+};

package/dist/versions-page/index.d.ts

@@ -0,0 +1,55 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { ComponentChildren, JSX } from "preact";
+/** Minimal version config entry needed by the versions page. */
+export interface VersionsPageVersionEntry {
+    slug: string;
+    label?: string;
+    banner?: "unmaintained" | "unreleased" | false;
+}
+/** Settings subset read by the versions page factory. */
+export interface VersionsPageSettings {
+    noindex?: boolean;
+    dynamicPageTransition?: boolean;
+    versions: VersionsPageVersionEntry[] | false;
+    base: string;
+}
+/** Host-supplied component bindings injected into the versions page factory. */
+export interface VersionsPageComponents {
+    HeadWithDefaults: (props: {
+        title: string;
+    }) => JSX.Element;
+    HeaderWithDefaults: (props: {
+        lang?: string;
+        currentPath?: string;
+    }) => JSX.Element;
+    FooterWithDefaults: (props: {
+        lang?: string;
+    }) => JSX.Element;
+    BodyEndIslands: (props: {
+        basePath: string;
+    }) => JSX.Element;
+}
+/** Injected dependencies for {@link createVersionsPageView}. */
+export interface VersionsPageDeps {
+    settings: VersionsPageSettings;
+    /** Default locale code (e.g. `"en"`). */
+    defaultLocale: string;
+    /** Translate a UI string key for a locale. */
+    t: (key: string, locale: string) => string;
+    /** Prefix a path with the configured base directory. */
+    withBase: (path: string) => string;
+    /** Compose the meta `<title>` value. */
+    composeMetaTitle: (title: string) => string;
+    components: VersionsPageComponents;
+}
+/** Props for the VersionsPageView component. */
+export interface VersionsPageViewProps {
+    locale: string;
+    children?: ComponentChildren;
+}
+/**
+ * Create a `VersionsPageView` component bound to the host's settings and
+ * component dependencies.
+ */
+export declare function createVersionsPageView(deps: VersionsPageDeps): (props: VersionsPageViewProps) => JSX.Element;

package/dist/versions-page/index.js

@@ -0,0 +1,73 @@
+import { Fragment, jsx } from "preact/jsx-runtime";
+import { DocLayoutWithDefaults } from "../doclayout/index.js";
+import { VersionsPageContent } from "../nav-indexing/index.js";
+function createVersionsPageView(deps) {
+  const {
+    settings,
+    defaultLocale,
+    t,
+    withBase,
+    composeMetaTitle,
+    components: {
+      HeadWithDefaults,
+      HeaderWithDefaults,
+      FooterWithDefaults,
+      BodyEndIslands
+    }
+  } = deps;
+  function VersionsPageView({ locale }) {
+    const isDefault = locale === defaultLocale;
+    const prefix = isDefault ? "" : `/${locale}`;
+    const pageTitle = t("version.page.title", locale);
+    const labels = {
+      pageTitle,
+      latestTitle: t("version.page.latest.title", locale),
+      latestDescription: t("version.page.latest.description", locale),
+      latestLink: t("version.page.latest.link", locale),
+      pastTitle: t("version.page.past.title", locale),
+      pastDescription: t("version.page.past.description", locale),
+      unmaintained: t("version.page.unmaintained", locale),
+      unreleased: t("version.page.unreleased", locale),
+      versionCol: t("version.switcher.label", locale),
+      statusCol: t("version.page.status", locale),
+      docsCol: t("version.page.docs", locale)
+    };
+    const latestHref = withBase(`${prefix}/docs/getting-started`);
+    const versions = settings.versions ? settings.versions.map((v) => ({
+      slug: v.slug,
+      label: v.label ?? v.slug,
+      // Version prefix comes BEFORE the locale — the only routed shape is
+      // pages/v/[version]/{locale}/docs/...; /{locale}/v/... has no route.
+      docsHref: withBase(`/v/${v.slug}${prefix}/docs/getting-started/`),
+      banner: v.banner
+    })) : [];
+    return /* @__PURE__ */ jsx(
+      DocLayoutWithDefaults,
+      {
+        title: composeMetaTitle(pageTitle),
+        head: /* @__PURE__ */ jsx(HeadWithDefaults, { title: pageTitle }),
+        lang: locale,
+        noindex: settings.noindex,
+        hideSidebar: true,
+        hideToc: true,
+        sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
+        headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: withBase(`${prefix}/docs/versions`) }),
+        footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
+        bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }),
+        enableClientRouter: settings.dynamicPageTransition,
+        children: /* @__PURE__ */ jsx(
+          VersionsPageContent,
+          {
+            latestHref,
+            versions,
+            labels
+          }
+        )
+      }
+    );
+  }
+  return VersionsPageView;
+}
+export {
+  createVersionsPageView
+};

package/eject/breadcrumb/breadcrumb.tsx

@@ -0,0 +1,194 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+import type { ComponentChildren, VNode } from "preact";
+import { findPath } from "./find-path.js";
+import type { BreadcrumbItem, SidebarNode } from "./types.js";
+import { ChevronRight } from "../icons/index.js";
+
+/**
+ * Convert a sidebar tree + the current page's id into the ordered list
+ * of crumbs the renderer walks. The first crumb is the home rung
+ * (icon-only, label is the empty string), followed by each ancestor in
+ * the tree, ending with the current page (no `href` so the renderer
+ * paints it as plain text).
+ *
+ * Mirrors the legacy buildBreadcrumbs() behaviour from
+ * src/utils/docs.ts so the rendered output stays parity-equivalent
+ * with the original Astro breadcrumb component.
+ */
+export function buildBreadcrumbItems(
+  tree: SidebarNode[],
+  currentId: string,
+  homeHref: string,
+): BreadcrumbItem[] {
+  const items: BreadcrumbItem[] = [{ label: "", href: homeHref }];
+  const path = findPath(tree, currentId);
+  for (let i = 0; i < path.length; i++) {
+    const node = path[i];
+    if (!node) continue;
+    const isLast = i === path.length - 1;
+    items.push({
+      label: node.label,
+      href: isLast ? undefined : node.href,
+    });
+  }
+  return items;
+}
+
+interface SmartLabelProps {
+  label: string;
+}
+
+/**
+ * Inline replacement for the Astro template's `set:html` /
+ * smartBreakToHtml call. Keeps the breadcrumb self-contained inside the
+ * v2 package — the legacy smart-break util lives in the host project's
+ * src/utils/, which v2 must not reach into.
+ *
+ * Inserts a Preact <wbr/> after each delimiter character when the label
+ * looks "path-like" (URLs, slash-separated paths, etc.). Prose labels
+ * pass through unchanged.
+ */
+function SmartLabel({ label }: SmartLabelProps): VNode | string {
+  if (!isPathLike(label)) return label;
+  const parts = label.split(DELIM_SPLIT);
+  const nodes: (string | VNode)[] = [];
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (!part) continue;
+    nodes.push(part);
+    if (i % 2 === 1) nodes.push(<wbr key={`wbr-${i}`} />);
+  }
+  return <>{nodes}</>;
+}
+
+const DELIM_SPLIT = /([/\\\-_.:?#&=])/;
+
+/** Heuristic copied from src/utils/smart-break.tsx — kept inline so v2
+ *  has no upward dependency. Returns true when delimiter-aware
+ *  line-break hints are useful (paths, URLs), false for prose. */
+function isPathLike(text: string): boolean {
+  if (!text) return false;
+  if (text.includes("://")) return true;
+  if (/^\.{0,2}\//.test(text)) return true;
+  if (/^[A-Za-z]:[\\/]/.test(text)) return true;
+  const forwardMatches = text.match(/[A-Za-z0-9]\/[A-Za-z0-9]/g);
+  if (forwardMatches && forwardMatches.length >= 2) return true;
+  const backMatches = text.match(/[A-Za-z0-9]\\[A-Za-z0-9]/g);
+  if (backMatches && backMatches.length >= 2) return true;
+  const hasDomainDot = /[A-Za-z0-9]\.[A-Za-z0-9]/.test(text);
+  const hasSlash = /[\\/]/.test(text);
+  if (hasDomainDot && hasSlash) return true;
+  return false;
+}
+
+function ChevronIcon(): VNode {
+  return <ChevronRight className="h-icon-xs w-icon-xs text-muted shrink-0" />;
+}
+
+function HomeIcon(): VNode {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      class="h-[1.575rem] w-[1.575rem] shrink-0"
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+      stroke-width="2"
+      aria-hidden="true"
+    >
+      <path
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-4 0a1 1 0 01-1-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 01-1 1h-2z"
+      />
+    </svg>
+  );
+}
+
+export interface BreadcrumbProps {
+  /** Pre-built items, or omit and pass `tree` + `currentId` instead. */
+  items?: BreadcrumbItem[];
+  /** Sidebar tree to derive the trail from. Required when `items` is omitted. */
+  tree?: SidebarNode[];
+  /** Id of the current page (matches SidebarNode.id). Required when `items` is omitted. */
+  currentId?: string;
+  /** Href for the leading home rung. Defaults to "/". */
+  homeHref?: string;
+  /**
+   * Optional slot rendered at the right end of the breadcrumb row.
+   * When provided, the breadcrumb nav and this slot are wrapped in a
+   * flex row that matches the original Astro doc-layout's combined
+   * breadcrumb + version-switcher row:
+   *
+   *   class="mb-vsp-sm flex flex-col items-start gap-vsp-xs
+   *          sm:flex-row sm:items-center sm:justify-between [&_nav]:mb-0"
+   *
+   * The `[&_nav]:mb-0` rule strips the nav's own `mb-vsp-md` so the
+   * wrapper margin controls spacing instead. Use this to place the
+   * VersionSwitcher pill inline at the right of the breadcrumb row,
+   * matching the reference site's layout on category index pages.
+   */
+  rightSlot?: ComponentChildren;
+}
+
+/**
+ * Breadcrumb trail component.
+ *
+ * Two usage shapes:
+ *   1. Pass pre-built `items` (existing call-sites that already
+ *      compute crumbs upstream).
+ *   2. Pass `tree` + `currentId` and the component derives the trail.
+ *
+ * Returns null when no items resolve, matching the documented
+ * `items.length > 0 &&` guard.
+ */
+export function Breadcrumb(props: BreadcrumbProps): VNode | null {
+  const items =
+    props.items ??
+    (props.tree && props.currentId !== undefined
+      ? buildBreadcrumbItems(props.tree, props.currentId, props.homeHref ?? "/")
+      : []);
+
+  if (items.length === 0) return null;
+
+  const nav = (
+    <nav class="mb-vsp-md text-small" aria-label="Breadcrumb">
+      <ol class="flex flex-wrap items-center gap-x-hsp-xs">
+        {items.map((item, i) => (
+          <li key={`crumb-${i}`} class="flex items-center gap-x-hsp-xs">
+            {i > 0 && <ChevronIcon />}
+            {item.href ? (
+              <a
+                href={item.href}
+                class="text-muted underline hover:text-fg flex items-center gap-x-hsp-2xs"
+              >
+                {i === 0 && <HomeIcon />}
+                <SmartLabel label={item.label} />
+              </a>
+            ) : (
+              <span class="text-fg">
+                <SmartLabel label={item.label} />
+              </span>
+            )}
+          </li>
+        ))}
+      </ol>
+    </nav>
+  );
+
+  if (props.rightSlot === undefined) return nav;
+
+  // When a rightSlot is provided, wrap both elements in a flex row that
+  // matches the original Astro doc-layout's breadcrumb + version-switcher
+  // row. The `[&_nav]:mb-0` rule cancels the nav's own bottom margin so
+  // the wrapper margin controls spacing instead (matching the Astro
+  // reference which used `mb-vsp-sm` on the outer div).
+  return (
+    <div class="mb-vsp-sm flex flex-col items-start gap-vsp-xs sm:flex-row sm:items-center sm:justify-between [&_nav]:mb-0">
+      {nav}
+      {props.rightSlot}
+    </div>
+  );
+}

package/eject/breadcrumb/find-path.ts

@@ -0,0 +1,26 @@
+import type { BreadcrumbNode, SidebarNode } from "./types.js";
+
+/**
+ * Walk the sidebar tree and return the chain of nodes from the root
+ * level down to (and including) the node whose `id` matches `targetId`.
+ *
+ * Returns an empty array when no node matches. Pure: never mutates the
+ * input tree, never reads anything outside of it.
+ *
+ * Used by the breadcrumb component to derive the current page's
+ * ancestry. The home/root crumb is the renderer's responsibility — this
+ * helper deals strictly with the tree itself.
+ */
+export function findPath<T extends BreadcrumbNode = SidebarNode>(
+  nodes: readonly T[],
+  targetId: string,
+): T[] {
+  for (const node of nodes) {
+    if (node.id === targetId) return [node];
+    if (node.children && node.children.length > 0) {
+      const sub = findPath(node.children as readonly T[], targetId);
+      if (sub.length > 0) return [node, ...sub];
+    }
+  }
+  return [];
+}

package/eject/breadcrumb/index.ts

@@ -0,0 +1,4 @@
+export { Breadcrumb, buildBreadcrumbItems } from "./breadcrumb.js";
+export type { BreadcrumbProps } from "./breadcrumb.js";
+export { findPath } from "./find-path.js";
+export type { BreadcrumbItem, SidebarNode } from "./types.js";