blume 1.6.5 → 1.7.0

package/src/components/layout/NavTreeScript.astro

@@ -0,0 +1,256 @@
+---
+// The sidebar's client behavior, split out of NavTree so a subtree rendered
+// into the sidebar cache (see nav-cache.ts) never carries a copy of it: Astro
+// emits a component's script where the component renders, and a cached
+// subtree would replay the copy captured on its first render on every later
+// page, next to the live root's own. Rendered by the root NavTree only, when
+// a `page`-mode group gives the panel stack something to do or sections are
+// deferred.
+//
+// Two jobs. The `<blume-nav>` drill-in panel stack; and deferred sections —
+// a collapsed group's children or an inactive panel's contents left out of
+// the page as an empty element with `data-nav-src`, fetched from the
+// prerendered fragment at that URL on first open (and prefetched on hover or
+// focus, so the open is usually instant). Fetched fragments are kept for the
+// session, so a section opened once is free on every later page.
+---
+
+<script>
+  const DURATION = 260;
+  const EASING = "cubic-bezier(0.33, 1, 0.68, 1)";
+
+  /** Fragment URL → its HTML, once fetched (shared across router swaps). */
+  const fragments = new Map<string, Promise<string>>();
+
+  const loadFragment = (src: string): Promise<string> => {
+    let pending = fragments.get(src);
+    if (!pending) {
+      pending = fetch(src, { headers: { Accept: "text/html" } }).then(
+        (response) => {
+          if (!response.ok) {
+            throw new Error(`Sidebar fragment ${src} responded ${response.status}`);
+          }
+          return response.text();
+        }
+      );
+      fragments.set(src, pending);
+      // A failed fetch is retried on the next open rather than cached.
+      pending.catch(() => fragments.delete(src));
+    }
+    return pending;
+  };
+
+  /** Fill a deferred element from its fragment; a no-op once filled. */
+  const fillDeferred = async (slot: HTMLElement): Promise<void> => {
+    const src = slot.dataset.navSrc;
+    if (!src) {
+      return;
+    }
+    slot.setAttribute("aria-busy", "true");
+    try {
+      slot.innerHTML = await loadFragment(src);
+      delete slot.dataset.navSrc;
+    } finally {
+      slot.removeAttribute("aria-busy");
+    }
+  };
+
+  const deferredIn = (element: Element | null): HTMLElement | null =>
+    element instanceof HTMLElement && element.dataset.navSrc ? element : null;
+
+  // Delegated at the document so the handlers survive client-router swaps
+  // (the document persists; only its tree is replaced). Module scripts run
+  // once per real load, and the flag keeps a second copy of this module —
+  // a page that renders two trees — from doubling the listeners.
+  let installed = false;
+  const install = (): void => {
+    if (installed) {
+      return;
+    }
+    installed = true;
+    document.addEventListener(
+      "toggle",
+      (event) => {
+        const details = event.target;
+        if (!(details instanceof HTMLDetailsElement) || !details.open) {
+          return;
+        }
+        const slot = deferredIn(details.querySelector(":scope > [data-nav-src]"));
+        if (slot) {
+          void fillDeferred(slot);
+        }
+      },
+      true
+    );
+    // Prefetch on intent: a hovered or focused summary, or a drill-in row.
+    const prefetch = (event: Event): void => {
+      const target = event.target;
+      if (!(target instanceof Element)) {
+        return;
+      }
+      const summary = target.closest("summary");
+      const slot = summary
+        ? deferredIn(summary.parentElement?.querySelector(":scope > [data-nav-src]") ?? null)
+        : null;
+      if (slot?.dataset.navSrc) {
+        void loadFragment(slot.dataset.navSrc).catch(() => undefined);
+        return;
+      }
+      const drill = target.closest("[data-nav-to]");
+      const nav = drill?.closest("blume-nav");
+      if (drill && nav instanceof BlumeNav) {
+        const panel = deferredIn(nav.panel(drill.getAttribute("data-nav-to") ?? ""));
+        if (panel?.dataset.navSrc) {
+          void loadFragment(panel.dataset.navSrc).catch(() => undefined);
+        }
+      }
+    };
+    document.addEventListener("pointerover", prefetch);
+    document.addEventListener("focusin", prefetch);
+  };
+
+  class BlumeNav extends HTMLElement {
+    active: HTMLElement | null = null;
+    finishSlide: (() => void) | null = null;
+
+    connectedCallback() {
+      if (this.dataset.ready) {
+        return;
+      }
+      this.dataset.ready = "1";
+      this.addEventListener("click", (event) => {
+        const target = event.target;
+        if (!(target instanceof Element)) {
+          return;
+        }
+        const drill = target.closest("[data-nav-to]");
+        if (drill && this.contains(drill)) {
+          const id = drill.getAttribute("data-nav-to");
+          if (id && this.panel(id)) {
+            event.preventDefault();
+            void this.show(id, true);
+          }
+          return;
+        }
+        const back = target.closest("[data-nav-back]");
+        if (back && this.contains(back)) {
+          event.preventDefault();
+          void this.show(back.getAttribute("data-nav-back") || "root", true);
+        }
+      });
+      // Initial panel is route-driven, so it snaps into place without a slide.
+      void this.show(this.dataset.initial || "root", false);
+    }
+
+    panel(id: string): HTMLElement | null {
+      return this.querySelector(`[data-nav-panel="${id}"]`);
+    }
+
+    depth(panel: HTMLElement): number {
+      return Number(panel.dataset.navDepth ?? "0");
+    }
+
+    reduced(): boolean {
+      return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    }
+
+    async show(id: string, animate: boolean): Promise<void> {
+      const next = this.panel(id) || this.panel("root");
+      if (!next) {
+        return;
+      }
+      // A deferred panel loads its contents before it slides in.
+      await fillDeferred(next);
+      const prev = this.active;
+      if (prev === next) {
+        return;
+      }
+      // Settle any in-flight slide before starting the next one.
+      if (this.finishSlide) {
+        this.finishSlide();
+      }
+      this.active = next;
+      this.dataset.active = next.dataset.navPanel;
+
+      if (!(animate && prev) || this.reduced()) {
+        for (const panel of this.querySelectorAll<HTMLElement>("[data-nav-panel]")) {
+          panel.hidden = panel !== next;
+        }
+        return;
+      }
+
+      this.slide(prev, next, this.depth(next) > this.depth(prev));
+    }
+
+    slide(out: HTMLElement, into: HTMLElement, forward: boolean): void {
+      const rtl = getComputedStyle(this).direction === "rtl" ? -1 : 1;
+      const sign = (forward ? -1 : 1) * rtl;
+
+      const fromHeight = out.offsetHeight;
+      this.style.position = "relative";
+      this.style.overflow = "hidden";
+      this.style.height = `${fromHeight}px`;
+      into.hidden = false;
+      for (const panel of [out, into]) {
+        panel.style.position = "absolute";
+        panel.style.top = "0";
+        panel.style.insetInlineStart = "0";
+        panel.style.width = "100%";
+      }
+      const toHeight = into.offsetHeight;
+      this.style.height = `${toHeight}px`;
+
+      const options = { duration: DURATION, easing: EASING };
+      const animations = [
+        out.animate(
+          [
+            { transform: "translateX(0)" },
+            { transform: `translateX(${sign * 100}%)` },
+          ],
+          options
+        ),
+        into.animate(
+          [
+            { transform: `translateX(${-sign * 100}%)` },
+            { transform: "translateX(0)" },
+          ],
+          options
+        ),
+        this.animate(
+          [{ height: `${fromHeight}px` }, { height: `${toHeight}px` }],
+          options
+        ),
+      ];
+
+      let done = false;
+      const finish = () => {
+        if (done) {
+          return;
+        }
+        done = true;
+        for (const animation of animations) {
+          animation.cancel();
+        }
+        out.hidden = true;
+        for (const panel of [out, into]) {
+          panel.style.position = "";
+          panel.style.top = "";
+          panel.style.insetInlineStart = "";
+          panel.style.width = "";
+          panel.style.transform = "";
+        }
+        this.style.position = "";
+        this.style.overflow = "";
+        this.style.height = "";
+        this.finishSlide = null;
+      };
+      this.finishSlide = finish;
+      animations[0]?.finished.then(finish, finish);
+    }
+  }
+
+  install();
+  if (!customElements.get("blume-nav")) {
+    customElements.define("blume-nav", BlumeNav);
+  }
+</script>

package/src/components/layout/PageActions.astro

@@ -523,11 +523,17 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
         epubLabel.textContent = generatingLabel;
       }
       try {
-        // Browser bundle: avoids Node built-ins and returns a Blob. Lazy-loaded
-        // so it never ships in the main bundle. The browserified UMD nests its
-        // callable under `.default`, which Vite's dev (esbuild) and build
-        // (rollup) interops expose at slightly different depths — unwrap both.
-        const epubModule = await import("epub-gen-memory/bundle");
+        // Browser bundle: avoids Node built-ins and returns a Blob. Loaded
+        // through the generated feature loaders, so it's absent from the
+        // bundle altogether when export.epub is off (this button isn't
+        // rendered then either). The browserified UMD nests its callable
+        // under `.default`, which Vite's dev (esbuild) and build (rollup)
+        // interops expose at slightly different depths — unwrap both.
+        const { loadEpub } = await import("blume:features");
+        if (!loadEpub) {
+          throw new Error("EPUB export is not enabled for this site.");
+        }
+        const epubModule = await loadEpub();
         const epub = epubModule.default?.default ?? epubModule.default;
         // The article HTML already opens with the page's <h1>, so don't let the
         // generator prepend a second chapter-title heading.

package/src/components/layout/PageLayout.astro

@@ -1,4 +1,6 @@
 ---
+import IconSprite from "./IconSprite.astro";
+import { createIconSprite } from "../icon-sprite.ts";
 // A full-width page layout for landing pages, marketing pages, dashboards — any
 // page that wants Blume's chrome (document shell, header, theme, fonts) without
 // the docs sidebar + prose + TOC grid that RootLayout hard-codes. It renders the
@@ -35,6 +37,7 @@ import {
 import { buildStructuredData } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
+import { pageDirection, pageLocale } from "./page-locale.ts";
 import { searchLocaleFor } from "./search-locale.ts";
 import "blume:theme";
 import { ClientRouter } from "astro:transitions";
@@ -108,7 +111,11 @@ interface Props {
    */
   x?: { creator?: string; handle?: string };
   noindex?: boolean;
-  /** Active locale + direction for `<html lang>`/`<html dir>`. */
+  /**
+   * Active locale + direction for `<html lang>`/`<html dir>`. Default to the
+   * locale Astro resolved from the URL (`Astro.currentLocale`), then the site
+   * default, and to that locale's configured direction.
+   */
   locale?: string;
   dir?: "ltr" | "rtl";
   /** Resolved UI dictionary; English baseline when omitted. */
@@ -145,13 +152,19 @@ const {
   structuredDataEnabled,
   x,
   noindex,
-  locale = "en",
-  dir = "ltr",
+  locale: localeProp,
+  dir: dirProp,
   ui,
   localeSwitch,
   clientData,
 } = Astro.props;
 
+// The locale and direction: the page's own values when it passes them (the
+// content catch-all always does), else what Astro's i18n routing resolved for
+// this URL, else the site default (see `page-locale.ts`).
+const locale = pageLocale(data.config.i18n, localeProp, Astro.currentLocale);
+const dir = dirProp ?? pageDirection(data.config.i18n, locale);
+
 const clientDataJson = clientData
   ? JSON.stringify(clientData).replaceAll("<", "\\u003c")
   : null;
@@ -232,6 +245,10 @@ const structuredDataJson = structuredData
   : null;
 
 const bannerKey = banner?.dismissible ? banner.key : null;
+
+// Start the page's icon sprite before anything renders an icon (see
+// icon-sprite.ts); <IconSprite /> at the end of the body emits it.
+createIconSprite(Astro.locals);
 ---
 
 <!doctype html>
@@ -401,5 +418,6 @@ const bannerKey = banner?.dismissible ? banner.key : null;
 
       syncDrawerInert();
     </script>
+  <IconSprite />
   </body>
 </html>

package/src/components/layout/ReferenceLayout.astro

@@ -1,4 +1,6 @@
 ---
+import IconSprite from "./IconSprite.astro";
+import { createIconSprite } from "../icon-sprite.ts";
 import "blume:theme";
 import data from "blume:data";
 import type { BlumeFavicon } from "../../core/data.ts";
@@ -17,6 +19,7 @@ import {
   THEME_INIT_SCRIPT,
 } from "./head-scripts.ts";
 import Header from "./Header.astro";
+import { pageDirection, pageLocale } from "./page-locale.ts";
 import { searchLocaleFor } from "./search-locale.ts";
 
 // A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
@@ -66,9 +69,12 @@ interface Props {
   pageTitle: string;
   /** Keep the reference route out of crawler indexes. */
   noindex?: boolean;
-  /** Active locale code for `<html lang>` (defaults to `en`). */
+  /**
+   * Active locale code for `<html lang>`. Defaults to the locale Astro
+   * resolved from the URL (`Astro.currentLocale`), then the site default.
+   */
   locale?: string;
-  /** Text direction for `<html dir>` (defaults to `ltr`). */
+  /** Text direction for `<html dir>`; defaults to the locale's configured direction. */
   dir?: "ltr" | "rtl";
   /** Resolved UI dictionary; English baseline when omitted. */
   ui?: UIStrings;
@@ -88,16 +94,26 @@ const {
   searchEnabled,
   pageTitle,
   noindex = false,
-  locale = "en",
-  dir = "ltr",
+  locale: localeProp,
+  dir: dirProp,
   ui,
 } = Astro.props;
 
+// The locale and direction: the page's own values when it passes them (the
+// content catch-all always does), else what Astro's i18n routing resolved for
+// this URL, else the site default (see `page-locale.ts`).
+const locale = pageLocale(data.config.i18n, localeProp, Astro.currentLocale);
+const dir = dirProp ?? pageDirection(data.config.i18n, locale);
+
 const strings = ui ?? EN_UI;
 // Scope search to the reference page's language on a multi-locale site.
 const searchLocale = searchLocaleFor(data.config.i18n, locale);
 
 const bannerKey = banner?.dismissible ? banner.key : null;
+
+// Start the page's icon sprite before anything renders an icon (see
+// icon-sprite.ts); <IconSprite /> at the end of the body emits it.
+createIconSprite(Astro.locals);
 ---
 
 <!doctype html>
@@ -142,5 +158,6 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       <script is:inline set:html={SCALAR_THEME_INIT_SCRIPT} />
     </div>
     <WebMcp />
+  <IconSprite />
   </body>
 </html>

package/src/components/layout/RootLayout.astro

@@ -1,4 +1,6 @@
 ---
+import IconSprite from "./IconSprite.astro";
+import { createIconSprite } from "../icon-sprite.ts";
 import data from "blume:data";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
@@ -54,10 +56,12 @@ import {
   findBreadcrumbs,
   flattenPages,
   getPagination,
+  navGroupIds,
   sidebarForRoute,
 } from "./nav-utils.ts";
 import NavTree from "./NavTree.astro";
 import { resolveSlot } from "./overrides.ts";
+import { pageDirection, pageLocale } from "./page-locale.ts";
 import { searchLocaleFor } from "./search-locale.ts";
 import PageActions from "./PageActions.astro";
 import PageFeedback from "./PageFeedback.astro";
@@ -149,9 +153,12 @@ interface Props {
   lastModified?: string | null;
   noindex?: boolean;
   structuredDataEnabled?: boolean;
-  /** Active locale code for `<html lang>` (defaults to `en`). */
+  /**
+   * Active locale code for `<html lang>`. Defaults to the locale Astro
+   * resolved from the URL (`Astro.currentLocale`), then the site default.
+   */
   locale?: string;
-  /** Text direction for `<html dir>` (defaults to `ltr`). */
+  /** Text direction for `<html dir>`; defaults to the locale's configured direction. */
   dir?: "ltr" | "rtl";
   /**
    * Direction of the page content's own language — differs from `dir` on a
@@ -177,6 +184,12 @@ interface Props {
   } | null;
   /** Viewed docs version for search filtering (`""` = current; `null`/absent = off). */
   searchVersion?: string | null;
+  /**
+   * URL prefix of this page's deferred sidebar fragments (`/blume-nav/
+   * <version>/<locale>`), when the sidebar defers collapsed sections; absent,
+   * the sidebar renders every section in full. See NavTree.
+   */
+  navFragmentBase?: string;
   /**
    * User layout-slot overrides from `components.ts` (`defineComponents`). Each
    * key replaces the matching built-in; unknown keys are ignored. Wired slots:
@@ -242,8 +255,8 @@ const {
   lastModified,
   noindex,
   structuredDataEnabled,
-  locale = "en",
-  dir = "ltr",
+  locale: localeProp,
+  dir: dirProp,
   contentDir,
   ui,
   localeAlternates,
@@ -252,6 +265,7 @@ const {
   versionSelector,
   versionNotice,
   searchVersion = null,
+  navFragmentBase,
   layout = {},
   clientData,
   toc = { enabled: true, maxLevel: 3, minLevel: 2 },
@@ -259,6 +273,12 @@ const {
   contentLayout = "default",
 } = Astro.props;
 
+// The locale and direction: the page's own values when it passes them (the
+// content catch-all always does), else what Astro's i18n routing resolved for
+// this URL, else the site default (see `page-locale.ts`).
+const locale = pageLocale(data.config.i18n, localeProp, Astro.currentLocale);
+const dir = dirProp ?? pageDirection(data.config.i18n, locale);
+
 // Serialized once for island hooks; `<` escaped so content can't break the tag.
 const clientDataJson = clientData
   ? JSON.stringify(clientData).replaceAll("<", "\\u003c")
@@ -386,6 +406,9 @@ const sidebar = sidebarForRoute(
   page.route,
   navigation.root
 );
+// Stable group ids over the full tree, so the scoped view above names its
+// panels and deferred fragments the same way every other page does.
+const navIds = navGroupIds(navigation.sidebar);
 const activeTab = currentTabForRoute(
   navigation.tabs,
   page.route,
@@ -419,6 +442,10 @@ const structuredDataJson = structuredData
   : null;
 
 const bannerKey = banner?.dismissible ? banner.key : null;
+
+// Start the page's icon sprite before anything renders an icon (see
+// icon-sprite.ts); <IconSprite /> at the end of the body emits it.
+createIconSprite(Astro.locals);
 ---
 
 <!doctype html>
@@ -670,6 +697,8 @@ const bannerKey = banner?.dismissible ? banner.key : null;
                 <div class="lg:hidden">
                   <MobileNavSlot
                     currentRoute={page.route}
+                    fragmentBase={navFragmentBase}
+                    ids={navIds}
                     items={sidebar}
                     strings={navStrings}
                   />
@@ -677,6 +706,8 @@ const bannerKey = banner?.dismissible ? banner.key : null;
                 <div class="hidden lg:block">
                   <SidebarSlot
                     currentRoute={page.route}
+                    fragmentBase={navFragmentBase}
+                    ids={navIds}
                     items={sidebar}
                     strings={navStrings}
                   />
@@ -685,6 +716,8 @@ const bannerKey = banner?.dismissible ? banner.key : null;
             ) : (
               <SidebarSlot
                 currentRoute={page.route}
+                fragmentBase={navFragmentBase}
+                ids={navIds}
                 items={sidebar}
                 strings={navStrings}
               />
@@ -782,8 +815,10 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       import { syncDrawerInert } from "./drawer-inert.ts";
       import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
       // Registers the <blume-mermaid> custom element (emitted by ```mermaid
-      // fences). Mermaid itself is lazy-loaded only on pages that use a diagram.
-      import "../content/mermaid-element.ts";
+      // fences) when some page has one; Mermaid itself is lazy-loaded only on
+      // pages that use a diagram. The loader is null — and the element and
+      // library absent from the bundle — for a site with no diagrams.
+      import { loadMermaid } from "blume:features";
       // Registers the <blume-toc> custom element: scrollspy for the table of
       // contents, highlighting the section currently in view as you scroll.
       import "./toc-element.ts";
@@ -791,6 +826,8 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       // Tree-shaken out of production builds.
       import "./hydration-hint.ts";
 
+      loadMermaid?.();
+
       // Runs once per real page load; re-syncs itself after client-router
       // swaps (see drawer-inert.ts).
       syncDrawerInert();
@@ -1044,5 +1081,6 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       }
     </style>
     <WebMcp />
+  <IconSprite />
   </body>
 </html>

package/src/components/layout/nav-cache.ts

@@ -0,0 +1,49 @@
+import type { NavNode } from "../../core/types.ts";
+import type { IconSymbol } from "../icon-sprite.ts";
+
+/**
+ * Build-time cache of rendered sidebar subtrees. A group that does not contain
+ * the current page renders identically on every page (no `aria-current`, no
+ * forced-open ancestor), so its HTML is rendered once and reused across the
+ * build — keyed on the group node's identity (a regenerated navigation is a
+ * new object, so a stale tree is never served) and the render variant (the
+ * panel id prefix and localized labels). The in-flight promise is what's
+ * stored, so concurrent page renders share one render of the same subtree.
+ */
+/** A cached subtree: its HTML and the sprite symbols that HTML references. */
+export interface CachedNavSubtree {
+  html: string;
+  /** Symbol id → symbol, so a later page can register them into its sprite. */
+  icons: [string, IconSymbol][];
+}
+
+const cache = new WeakMap<NavNode, Map<string, Promise<CachedNavSubtree>>>();
+
+/**
+ * The cached subtree of `node` for `variant` — its HTML plus the icon sprite
+ * symbols it references, since the HTML is reused on pages that never
+ * rendered those icons themselves — rendering it with `render` on the first
+ * request. `enabled: false` always renders (the dev
+ * server, where an edited component must show its change on the next request).
+ */
+export const cachedNavSubtree = (
+  node: NavNode,
+  variant: string,
+  render: () => Promise<CachedNavSubtree>,
+  enabled = true
+): Promise<CachedNavSubtree> => {
+  if (!enabled) {
+    return render();
+  }
+  let byVariant = cache.get(node);
+  if (!byVariant) {
+    byVariant = new Map();
+    cache.set(node, byVariant);
+  }
+  let html = byVariant.get(variant);
+  if (!html) {
+    html = render();
+    byVariant.set(variant, html);
+  }
+  return html;
+};