@dogsbay/docs-layout 0.2.0-beta.46 → 0.2.0-beta.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.46",
+  "version": "0.2.0-beta.48",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -29,8 +29,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.46",
-    "@dogsbay/primitives": "0.2.0-beta.46"
+    "@dogsbay/ui": "0.2.0-beta.48",
+    "@dogsbay/primitives": "0.2.0-beta.48"
   },
   "devDependencies": {
     "vitest": "^3.0.0"

package/src/DocsLayout.astro

@@ -31,6 +31,7 @@ import SidebarMenuItem from "@dogsbay/ui/sidebar/SidebarMenuItem.astro";
 import SidebarMenuButton from "@dogsbay/ui/sidebar/SidebarMenuButton.astro";
 import SidebarSeparator from "@dogsbay/ui/sidebar/SidebarSeparator.astro";
 import SidebarNavTree from "@dogsbay/ui/sidebar/SidebarNavTree.astro";
+import DocsNavClient from "./DocsNavClient.astro";
 import Separator from "@dogsbay/ui/separator/Separator.astro";
 import ThemeToggle from "@dogsbay/ui/theme-toggle/ThemeToggle.astro";
 import DocsToc from "./DocsToc.astro";
@@ -356,6 +357,19 @@ interface Props {
    * (`<basePath>/<version>/`). Defaults to "/docs".
    */
   basePath?: string;
+  /**
+   * Sidebar navigation render mode.
+   *
+   * - `"client"` (default): emit the small `<DocsNavClient />` placeholder;
+   *   the tree is hydrated from `/_dogsbay/nav.json` once per session.
+   *   Page HTML shrinks dramatically at scale (~50 KB vs ~1.2 MB on a
+   *   2k-page site). No-JS users see a sitemap fallback link.
+   * - `"ssr-full"`: render the full nav tree into every page's HTML.
+   *   Best for very small sites or strict no-JS / SEO contexts.
+   *
+   * See plans/client-rendered-nav.md.
+   */
+  navMode?: "client" | "ssr-full";
   /**
    * Per-page LLM action UI. When set and `enabled !== false`, renders
    * the PageActions cluster (Copy markdown + Open in Claude/ChatGPT/
@@ -447,6 +461,7 @@ const {
   multiSource,
   switcherMap,
   basePath,
+  navMode = "client",
   wideLayout = false,
   class: className,
 } = Astro.props;
@@ -692,7 +707,24 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
         <SidebarSeparator />
 
         <SidebarContent>
-          {navGroups ? (
+          {navMode === "client" ? (
+            // Client-render mode: emit one DocsNavClient placeholder
+            // inside a single SidebarGroup, regardless of navGroups.
+            // The group-label shape doesn't apply when the tree is
+            // hydrated by JS — multi-group nav is reconstructed
+            // client-side from the same /_dogsbay/nav.json shape.
+            // See plans/client-rendered-nav.md.
+            <SidebarGroup>
+              <SidebarGroupContent>
+                <DocsNavClient
+                  currentPath={currentPath}
+                  basePath={basePath ?? ""}
+                  version={multiSource?.version}
+                  locale={multiSource?.locale}
+                />
+              </SidebarGroupContent>
+            </SidebarGroup>
+          ) : navGroups ? (
             navGroups.map(group => (
               <SidebarGroup>
                 <SidebarGroupLabel>{group.label}</SidebarGroupLabel>

package/src/DocsNavClient.astro

@@ -0,0 +1,89 @@
+---
+/**
+ * Client-rendered drop-in replacement for SidebarNavTree.
+ *
+ * Emits an empty placeholder with the metadata the hydration script
+ * needs (nav-url to fetch, current-path to highlight, basePath for
+ * version/locale filtering). The actual tree DOM is rendered by
+ * `docs-nav-client.ts` after a single fetch of `nav.json` (cached
+ * once per session — subsequent navigations re-highlight without
+ * re-fetching, courtesy of view transitions).
+ *
+ * The placeholder shows a few skeleton rows so the layout doesn't
+ * shift when the real tree pops in. Skeleton uses the same width as
+ * the sidebar so visual jump is minimal even on a slow connection.
+ *
+ * Trade-offs vs SidebarNavTree:
+ *   - HTML per page: ~200 bytes (this placeholder + a tiny script
+ *     tag) vs ~600 KB+ for the SSR tree at scale.
+ *   - No-JS users see only the skeleton + the `<noscript>` fallback
+ *     link. A `sitemap.xml` link covers no-JS navigation.
+ *   - First paint waits for the JS bundle + the JSON fetch. On a 4G
+ *     connection that's typically <200 ms; the skeleton fills the
+ *     space until then.
+ *
+ * See plans/client-rendered-nav.md.
+ */
+interface Props {
+  /** Current page's URL pathname; the script uses it to mark the active item. */
+  currentPath: string;
+  /**
+   * URL prefix the host serves under (combined `urlBase` + `basePath`).
+   * The script joins this with `/_dogsbay/nav.json` to locate the
+   * fetchable nav tree; also threaded to the version/locale filter
+   * so multi-axis sites work the same as SSR.
+   */
+  basePath?: string;
+  /** Current source's version axis value, if multi-version site. */
+  version?: string;
+  /** Current source's locale axis value, if multi-locale site. */
+  locale?: string;
+}
+
+const { currentPath, basePath = "", version, locale } = Astro.props;
+const navUrl = `${basePath}/_dogsbay/nav.json`;
+---
+
+<div
+  id="docs-nav-root"
+  data-nav-url={navUrl}
+  data-current-path={currentPath}
+  data-base-path={basePath}
+  data-version={version ?? ""}
+  data-locale={locale ?? ""}
+  aria-busy="true"
+  aria-label="Documentation navigation"
+>
+  <ul class="flex min-w-0 flex-col" data-sidebar="nav-tree" data-level="0">
+    {[0, 1, 2, 3, 4, 5].map((i) => (
+      <li>
+        <div
+          class="flex h-8 w-full items-center gap-2 rounded-md px-2"
+          aria-hidden="true"
+        >
+          <div class="h-2 w-2 rounded-full bg-sidebar-foreground/10" />
+          <div
+            class="h-2 rounded bg-sidebar-foreground/10"
+            style={`width: ${50 + ((i * 17) % 35)}%;`}
+          />
+        </div>
+      </li>
+    ))}
+  </ul>
+  <noscript>
+    <p class="px-2 py-1.5 text-sm text-sidebar-foreground/70">
+      JavaScript is required to render the sidebar. Use the
+      <a href={`${basePath}/sitemap.xml`} class="underline">sitemap</a>
+      to browse all pages.
+    </p>
+  </noscript>
+</div>
+
+<script>
+  // Single import — Astro/Vite bundles this into one shared chunk
+  // referenced from every page that uses DocsNavClient. Browsers
+  // cache the chunk, so the nav script ships once per session
+  // regardless of how many pages the user visits.
+  import { hydrateDocsNav } from "./docs-nav-client.ts";
+  hydrateDocsNav();
+</script>

package/src/docs-nav-client.ts

@@ -0,0 +1,265 @@
+/**
+ * Client-side sidebar nav hydration.
+ *
+ * Fetches `/_dogsbay/nav.json` once per session, renders the tree DOM
+ * to mirror `@dogsbay/ui/sidebar/SidebarNavTree.astro`'s structure,
+ * and re-highlights the current page on each Astro view-transition
+ * page-load.
+ *
+ * Design constraints:
+ *   - DOM output matches SidebarNavTree exactly (same tags, classes,
+ *     data-attributes) so Tailwind's compiled CSS styles us correctly
+ *     and any sidebar-system selectors (e.g. `data-sidebar="nav-tree"`
+ *     hooks) keep working.
+ *   - Filter by `version` / `locale` matches `nav-filter.ts`'s SSR
+ *     filter so a multi-axis site renders the same nav as `ssr-full`
+ *     mode (without the multiplicative HTML cost).
+ *   - One fetch per session. The `nav.json` URL is served with
+ *     `Cache-Control: immutable` by Astro's static build (it lives
+ *     under `public/_dogsbay/`), so the browser cache holds it across
+ *     navigations.
+ *
+ * See plans/client-rendered-nav.md.
+ */
+import { filterNavByAxis } from "./nav-filter.js";
+
+interface NavItem {
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavItem[];
+}
+
+/**
+ * Module-level cache so multiple page loads in the same SPA session
+ * share the same fetched nav data. Cleared by re-loads (full page
+ * navigations) but Astro's view transitions re-execute the script
+ * module without reloading the page — so on view-transition the
+ * cached promise is reused and no extra fetch fires.
+ */
+let navPromise: Promise<NavItem[]> | null = null;
+
+function fetchNav(url: string): Promise<NavItem[]> {
+  if (!navPromise) {
+    navPromise = fetch(url, { credentials: "same-origin" }).then((r) => {
+      if (!r.ok) throw new Error(`nav.json fetch failed: ${r.status}`);
+      return r.json() as Promise<NavItem[]>;
+    });
+  }
+  return navPromise;
+}
+
+function normalize(path: string): string {
+  return path.replace(/\/$/, "") || "/";
+}
+
+function hasActiveDescendant(item: NavItem, current: string): boolean {
+  if (item.href && normalize(item.href) === current) return true;
+  return item.children?.some((c) => hasActiveDescendant(c, current)) ?? false;
+}
+
+/**
+ * Render a single nav item into a `<li>` DOM node. Matches
+ * SidebarNavTree's per-level class set exactly so styling stays in
+ * sync. Padding is computed from `level` the same way (`8 + level*12`
+ * pixels) so indentation lines up across the same render.
+ */
+function renderItem(item: NavItem, current: string, level: number): HTMLLIElement {
+  const li = document.createElement("li");
+  li.dataset.sidebar = "nav-tree-item";
+
+  const active = item.href ? normalize(item.href) === current : false;
+  const hasChildren = !!item.children && item.children.length > 0;
+  const padLeft = `${8 + level * 12}px`;
+  const heightClass = level === 0 ? "h-8" : "h-7";
+
+  if (hasChildren) {
+    const details = document.createElement("details");
+    if (active || hasActiveDescendant(item, current)) details.open = true;
+
+    const summary = document.createElement("summary");
+    summary.className = [
+      "flex w-full min-w-0 cursor-pointer items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none [list-style:none] ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&::-webkit-details-marker]:hidden",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    summary.style.paddingLeft = padLeft;
+    if (item.href) summary.dataset.navHref = item.href;
+    if (active) summary.dataset.active = "true";
+
+    // Chevron SVG — matches SidebarNavTree's rotation-on-open via CSS
+    // (`details[open] > summary [data-chevron] { transform: rotate(90deg); }`).
+    summary.innerHTML =
+      '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6"/></svg>';
+
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      summary.appendChild(iconSpan);
+    }
+
+    const label = document.createElement("span");
+    label.className = "truncate";
+    label.textContent = item.label;
+    summary.appendChild(label);
+
+    details.appendChild(summary);
+
+    // Recurse — nested `<ul>` mirrors SidebarNavTree's `<Astro.self>`.
+    const childUl = document.createElement("ul");
+    childUl.className = "flex min-w-0 flex-col";
+    childUl.dataset.sidebar = "nav-tree";
+    childUl.dataset.level = String(level + 1);
+    for (const child of item.children!) {
+      childUl.appendChild(renderItem(child, current, level + 1));
+    }
+    details.appendChild(childUl);
+
+    li.appendChild(details);
+  } else {
+    const a = document.createElement("a");
+    a.href = item.href || "#";
+    a.className = [
+      "flex w-full min-w-0 items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    a.style.paddingLeft = padLeft;
+    if (active) a.dataset.active = "true";
+    if (item.href) a.dataset.navHref = item.href;
+
+    // Spacer to align leaf text with branch text (which has a chevron).
+    const spacer = document.createElement("span");
+    spacer.className = "size-4 shrink-0";
+    a.appendChild(spacer);
+
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      a.appendChild(iconSpan);
+    }
+
+    const label = document.createElement("span");
+    label.className = "truncate";
+    label.textContent = item.label;
+    a.appendChild(label);
+
+    li.appendChild(a);
+  }
+
+  return li;
+}
+
+function renderTree(items: NavItem[], current: string, root: HTMLElement): void {
+  const ul = document.createElement("ul");
+  ul.className =
+    "flex min-w-0 flex-col w-full group-data-[collapsible=icon]:hidden";
+  ul.dataset.sidebar = "nav-tree";
+  ul.dataset.level = "0";
+  for (const item of items) {
+    ul.appendChild(renderItem(item, current, 0));
+  }
+  // Replace skeleton in one DOM op so there's no flash of partial state.
+  root.replaceChildren(ul);
+  root.removeAttribute("aria-busy");
+}
+
+/**
+ * Re-highlight the active item without rebuilding the whole tree.
+ * Used on `astro:page-load` when view transitions land on a new
+ * route — we re-toggle the `data-active` attribute and re-apply the
+ * active classes, then expand the new active branch's ancestors.
+ *
+ * Cheaper than a full re-render (no fetch, no DOM rebuild). For
+ * the wider hydration loop we still re-render when a brand-new nav
+ * structure is needed (e.g. switching versions), but path-only
+ * navigation just re-highlights.
+ */
+function rehighlight(root: HTMLElement, current: string): void {
+  const ACTIVE_CLASSES = [
+    "bg-sidebar-accent",
+    "font-medium",
+    "text-sidebar-accent-foreground",
+  ];
+  const items = root.querySelectorAll<HTMLElement>("[data-nav-href]");
+  for (const el of Array.from(items)) {
+    const href = el.dataset.navHref;
+    const active = !!href && normalize(href) === current;
+    if (active) {
+      el.dataset.active = "true";
+      el.classList.add(...ACTIVE_CLASSES);
+    } else {
+      delete el.dataset.active;
+      el.classList.remove(...ACTIVE_CLASSES);
+    }
+  }
+  // Expand ancestors of the new active item.
+  const active = root.querySelector<HTMLElement>('[data-active="true"]');
+  if (active) {
+    let parent: HTMLElement | null = active.parentElement;
+    while (parent) {
+      if (parent.tagName === "DETAILS") {
+        (parent as HTMLDetailsElement).open = true;
+      }
+      parent = parent.parentElement;
+    }
+  }
+}
+
+/**
+ * Public entry point. Called once from `<DocsNavClient />`'s inline
+ * script tag. Idempotent — subsequent calls (e.g. from view
+ * transitions) are no-ops once the tree has been rendered; they just
+ * re-highlight against the new pathname.
+ */
+export async function hydrateDocsNav(): Promise<void> {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+
+  const navUrl = root.dataset.navUrl;
+  if (!navUrl) {
+    console.warn("docs-nav: missing data-nav-url");
+    return;
+  }
+  const current = normalize(root.dataset.currentPath || location.pathname);
+  const basePath = root.dataset.basePath || "";
+  const version = root.dataset.version || undefined;
+  const locale = root.dataset.locale || undefined;
+
+  try {
+    const nav = await fetchNav(navUrl);
+    const filtered = filterNavByAxis(nav, {
+      basePath: basePath || "/docs",
+      version: version || undefined,
+      locale: locale || undefined,
+    });
+    renderTree(filtered, current, root);
+  } catch (err) {
+    console.error("docs-nav: hydration failed", err);
+    root.setAttribute("aria-busy", "false");
+    // Keep skeleton so layout doesn't collapse on failure; a real
+    // user will reload or follow the noscript link.
+  }
+}
+
+// Re-run on view transitions. astro:page-load fires both on initial
+// load and after each ClientRouter transition; the module-level
+// `navPromise` cache makes the post-transition path a fast
+// highlight-only pass without re-fetching.
+document.addEventListener("astro:page-load", () => {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+  // If tree is already rendered (no aria-busy), just re-highlight.
+  if (root.getAttribute("aria-busy") === null) {
+    const current = normalize(root.dataset.currentPath || location.pathname);
+    rehighlight(root, current);
+  } else {
+    void hydrateDocsNav();
+  }
+});