blume 1.6.5 → 1.7.0

package/src/components/layout/NavTree.astro

@@ -6,15 +6,20 @@ import { methodColor } from "../colors.ts";
 import Icon from "../Icon.astro";
 import { withBase } from "../islands/base-path.ts";
 import Self from "./NavTree.astro";
+import NavTreeCache from "./NavTreeCache.astro";
+import NavTreeScript from "./NavTreeScript.astro";
 
 interface PagePanel {
   id: string;
   parentId: string;
+  /** Nesting level in the panel stack (a root-level page group is 1). */
+  depth: number;
   label: string;
   route?: string;
   icon?: string;
   children: NavNode[];
   active: boolean;
+  node: NavNode;
 }
 
 interface Props {
@@ -27,6 +32,20 @@ interface Props {
   root?: boolean;
   /** Localized labels ("Back", the deprecated badge); English when omitted. */
   strings?: UIStrings["nav"];
+  /**
+   * Stable ids for the full sidebar's groups (`navGroupIds`), so panel and
+   * fragment ids match across the scoped views the layout renders. Absent,
+   * ids fall back to positions within this render.
+   */
+  ids?: Map<NavNode, string>;
+  /**
+   * URL prefix of the deferred-section fragments (`/blume-nav/<version>/
+   * <locale>`). When set, a collapsed group's children and an inactive
+   * drill-in panel's contents are left out of the page and fetched from
+   * `<fragmentBase>/<id>` on first open (see NavTreeScript); absent, every
+   * section renders in full.
+   */
+  fragmentBase?: string;
 }
 
 const {
@@ -36,8 +55,18 @@ const {
   idPrefix = "n",
   root = depth === 0,
   strings,
+  ids,
+  fragmentBase,
 } = Astro.props;
 
+/** A group's id: its stable full-tree id, else its position in this render. */
+const idOf = (node: NavNode, positional: string): string =>
+  ids?.get(node) ?? positional;
+
+/** The fragment a deferred section loads from, when sections are deferred. */
+const fragmentFor = (id: string): string | undefined =>
+  fragmentBase ? `${fragmentBase}/${id}` : undefined;
+
 // Merge over the English defaults so a label missing from a translation (or
 // from a not-yet-regenerated snapshot) still renders instead of coming out
 // blank — the PageActions pattern.
@@ -66,27 +95,30 @@ const hasActivePage = (item: NavNode): boolean =>
 const collectPanels = (
   nodes: NavNode[],
   prefix: string,
-  parentId: string
+  parentId: string,
+  level = 1
 ): PagePanel[] => {
   const out: PagePanel[] = [];
   nodes.forEach((node, index) => {
     if (node.kind !== "group") {
       return;
     }
-    const id = `${prefix}.${index}`;
+    const id = idOf(node, `${prefix}.${index}`);
     if ((node.display ?? "flat") === "page") {
       out.push({
         active: hasActivePage(node),
         children: node.children,
+        depth: level,
         icon: node.icon,
         id,
         label: node.label,
+        node,
         parentId,
         route: node.route,
       });
-      out.push(...collectPanels(node.children, id, id));
+      out.push(...collectPanels(node.children, id, id, level + 1));
     } else {
-      out.push(...collectPanels(node.children, id, parentId));
+      out.push(...collectPanels(node.children, id, parentId, level));
     }
   });
   return out;
@@ -98,27 +130,33 @@ const panels = root ? collectPanels(items, idPrefix, "root") : [];
 const activePanels = panels.filter((panel) => panel.active);
 const initialId =
   activePanels.length > 0
-    ? activePanels.reduce((a, b) =>
-        b.id.split(".").length > a.id.split(".").length ? b : a
-      ).id
+    ? activePanels.reduce((a, b) => (b.depth > a.depth ? b : a)).id
     : "root";
 ---
 
+{root && (panels.length > 0 || fragmentBase) && <NavTreeScript />}
 {
   root && panels.length > 0 ? (
     <blume-nav class="block" data-initial={initialId}>
-      <div data-nav-panel="root" hidden={initialId !== "root"}>
+      <div data-nav-depth="0" data-nav-panel="root" hidden={initialId !== "root"}>
         <Self
           currentRoute={currentRoute}
           depth={0}
+          fragmentBase={fragmentBase}
           idPrefix={idPrefix}
+          ids={ids}
           items={items}
           root={false}
           strings={n}
         />
       </div>
       {panels.map((panel) => (
-        <div data-nav-panel={panel.id} hidden={panel.id !== initialId}>
+        <div
+          data-nav-depth={panel.depth}
+          data-nav-panel={panel.id}
+          data-nav-src={panel.active ? undefined : fragmentFor(panel.id)}
+          hidden={panel.id !== initialId}
+        >
           {/* The title is the only sidebar link to the section's own page, so
               a routed panel keeps it as a link; without a route the whole row
               becomes the back button. Either way every part of the row is
@@ -156,14 +194,34 @@ const initialId =
               <span class="flex-1 truncate">{panel.label}</span>
             </button>
           )}
-          <Self
-            currentRoute={currentRoute}
-            depth={1}
-            idPrefix={panel.id}
-            items={panel.children}
-            root={false}
-            strings={n}
-          />
+          {/* An inactive panel's contents are deferred (fetched into this
+              element on drill-in) when fragments are on; otherwise the
+              build-time cache renders them once. */}
+          {panel.active ? (
+            <Self
+              currentRoute={currentRoute}
+              depth={1}
+              fragmentBase={fragmentBase}
+              idPrefix={panel.id}
+              ids={ids}
+              items={panel.children}
+              root={false}
+              strings={n}
+            />
+          ) : fragmentBase ? null : (
+            <NavTreeCache node={panel.node} variant={`${panel.id}|${n.back}|${n.deprecated}`}>
+              <Self
+                currentRoute={currentRoute}
+                depth={1}
+                fragmentBase={fragmentBase}
+                idPrefix={panel.id}
+                ids={ids}
+                items={panel.children}
+                root={false}
+                strings={n}
+              />
+            </NavTreeCache>
+          )}
         </div>
       ))}
     </blume-nav>
@@ -171,11 +229,28 @@ const initialId =
     <ul class="m-0 list-none space-y-px p-0">
       {items.map((item, index) => {
         if (item.kind === "page") {
+          const current = item.route === currentRoute ? "page" : undefined;
+          // A bare row (no icon, badge, or deprecation) is the common case and
+          // the bulk of every page's HTML on a large site, so it renders as a
+          // single truncating link with no inner row markup.
+          if (!(item.icon || item.badge || item.deprecated)) {
+            return (
+              <li>
+                <a
+                  aria-current={current}
+                  class="blume-nav-link truncate"
+                  href={withBase(item.route)}
+                >
+                  {item.label}
+                </a>
+              </li>
+            );
+          }
           return (
             <li>
               <a
-                aria-current={item.route === currentRoute ? "page" : undefined}
-                class="block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:font-medium aria-[current=page]:text-foreground"
+                aria-current={current}
+                class="blume-nav-link"
                 href={withBase(item.route)}
               >
                 <span class="flex items-center gap-2">
@@ -198,7 +273,7 @@ const initialId =
         }
 
         const display = item.display ?? "flat";
-        const id = `${idPrefix}.${index}`;
+        const id = idOf(item, `${idPrefix}.${index}`);
         // Flat groups are section headers and want breathing room; collapsible
         // `group`/`page` rows are single rows and should stack tightly.
         const spacing =
@@ -209,7 +284,7 @@ const initialId =
           return (
             <li class={spacing}>
               <button
-                class="flex w-full items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-left font-medium text-foreground text-sm transition-colors hover:bg-muted"
+                class="blume-nav-drill"
                 data-nav-to={id}
                 type="button"
               >
@@ -241,13 +316,13 @@ const initialId =
           return (
             <li class={spacing}>
               <details open={open}>
-                <summary class="flex cursor-pointer list-none items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden">
+                <summary class="blume-nav-summary">
                   {item.route ? (
                     <a
                       aria-current={
                         item.route === currentRoute ? "page" : undefined
                       }
-                      class="-my-1 flex flex-1 items-center gap-1.5 rounded py-1 transition-colors aria-[current=page]:text-foreground aria-[current=page]:font-semibold"
+                      class="blume-nav-summary-link"
                       href={withBase(item.route)}
                     >
                       {item.icon && (
@@ -285,15 +360,37 @@ const initialId =
                     <Icon name="chevron-right" size={13} />
                   </span>
                 </summary>
-                <div class="space-y-0.5 border-border border-l pl-3">
-                  <Self
-                    currentRoute={currentRoute}
-                    depth={depth + 1}
-                    idPrefix={id}
-                    items={item.children}
-                    root={false}
-                    strings={n}
-                  />
+                <div
+                  class="space-y-0.5 border-border border-l pl-3"
+                  data-nav-src={open ? undefined : fragmentFor(id)}
+                >
+                  {/* A closed group's children are deferred (fetched into this
+                      element on first open) when fragments are on. */}
+                  {!open && fragmentBase ? null : active ? (
+                    <Self
+                      currentRoute={currentRoute}
+                      depth={depth + 1}
+                      fragmentBase={fragmentBase}
+                      idPrefix={id}
+                      ids={ids}
+                      items={item.children}
+                      root={false}
+                      strings={n}
+                    />
+                  ) : (
+                    <NavTreeCache node={item} variant={`${id}|${n.back}|${n.deprecated}`}>
+                      <Self
+                        currentRoute={currentRoute}
+                        depth={depth + 1}
+                        fragmentBase={fragmentBase}
+                        idPrefix={id}
+                        ids={ids}
+                        items={item.children}
+                        root={false}
+                        strings={n}
+                      />
+                    </NavTreeCache>
+                  )}
                 </div>
               </details>
             </li>
@@ -303,11 +400,11 @@ const initialId =
         // `flat` (default): a non-collapsible header with its items beneath.
         return (
           <li class={spacing}>
-            <p class="mb-2 flex items-center gap-1.5 px-2.5 font-medium text-foreground text-sm">
+            <p class="blume-nav-heading">
               {item.route ? (
                 <a
                   aria-current={item.route === currentRoute ? "page" : undefined}
-                  class="-ml-1 flex flex-1 items-center gap-1.5 rounded-[0.65rem] px-1 py-0.5 text-foreground transition-colors hover:bg-muted aria-[current=page]:bg-muted"
+                  class="blume-nav-heading-link"
                   href={withBase(item.route)}
                 >
                   {item.icon && (
@@ -339,14 +436,31 @@ const initialId =
               )}
             </p>
             <div class="space-y-0.5">
-              <Self
-                currentRoute={currentRoute}
-                depth={depth + 1}
-                idPrefix={id}
-                items={item.children}
-                root={false}
-                strings={n}
-              />
+              {hasActivePage(item) ? (
+                <Self
+                  currentRoute={currentRoute}
+                  depth={depth + 1}
+                  fragmentBase={fragmentBase}
+                  idPrefix={id}
+                  ids={ids}
+                  items={item.children}
+                  root={false}
+                  strings={n}
+                />
+              ) : (
+                <NavTreeCache node={item} variant={`${id}|${n.back}|${n.deprecated}`}>
+                  <Self
+                    currentRoute={currentRoute}
+                    depth={depth + 1}
+                    fragmentBase={fragmentBase}
+                    idPrefix={id}
+                    ids={ids}
+                    items={item.children}
+                    root={false}
+                    strings={n}
+                  />
+                </NavTreeCache>
+              )}
             </div>
           </li>
         );
@@ -355,149 +469,3 @@ const initialId =
   )
 }
 
-<script>
-  const DURATION = 260;
-  const EASING = "cubic-bezier(0.33, 1, 0.68, 1)";
-
-  class BlumeNav extends HTMLElement {
-    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();
-            this.show(id, true);
-          }
-          return;
-        }
-        const back = target.closest("[data-nav-back]");
-        if (back && this.contains(back)) {
-          event.preventDefault();
-          this.show(back.getAttribute("data-nav-back") || "root", true);
-        }
-      });
-      // Initial panel is route-driven, so it snaps into place without a slide.
-      this.show(this.dataset.initial || "root", false);
-    }
-
-    panel(id) {
-      return this.querySelector(`[data-nav-panel="${id}"]`);
-    }
-
-    depth(id) {
-      return id === "root" ? 0 : id.split(".").length;
-    }
-
-    reduced() {
-      return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-    }
-
-    show(id, animate) {
-      const next = this.panel(id) || this.panel("root");
-      if (!next) {
-        return;
-      }
-      const resolved = next.getAttribute("data-nav-panel");
-      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 = resolved;
-
-      if (!(animate && prev) || this.reduced()) {
-        for (const panel of this.querySelectorAll("[data-nav-panel]")) {
-          panel.hidden = panel !== next;
-        }
-        return;
-      }
-
-      const forward =
-        this.depth(resolved) > this.depth(prev.getAttribute("data-nav-panel"));
-      this.slide(prev, next, forward);
-    }
-
-    slide(out, into, forward) {
-      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);
-    }
-  }
-
-  if (!customElements.get("blume-nav")) {
-    customElements.define("blume-nav", BlumeNav);
-  }
-</script>

package/src/components/layout/NavTreeCache.astro

@@ -0,0 +1,45 @@
+---
+// Renders its slot — a sidebar subtree with no active page in it — through the
+// build-time subtree cache (see nav-cache.ts), so a large sidebar is rendered
+// once per group instead of once per page. Off in dev, where component edits
+// must show on the next request. The cached HTML references the page's icon
+// sprite (see icon-sprite.ts), so the symbols it used ride along and are
+// registered into whichever page reuses it.
+import type { NavNode } from "../../core/types.ts";
+import { iconSpriteFor, referencedIconSymbols } from "../icon-sprite.ts";
+import type { IconSymbol } from "../icon-sprite.ts";
+import { cachedNavSubtree } from "./nav-cache.ts";
+
+interface Props {
+  node: NavNode;
+  variant: string;
+}
+
+const { node, variant } = Astro.props;
+const sprite = iconSpriteFor(Astro.locals);
+const { html, icons } = await cachedNavSubtree(
+  node,
+  variant,
+  async () => {
+    const rendered = await Astro.slots.render("default");
+    const used: [string, IconSymbol][] = [];
+    for (const id of referencedIconSymbols(rendered)) {
+      const symbol = sprite?.symbols.get(id);
+      if (symbol) {
+        used.push([id, symbol]);
+      }
+    }
+    return { html: rendered, icons: used };
+  },
+  !import.meta.env.DEV
+);
+if (sprite) {
+  for (const [id, symbol] of icons) {
+    if (!sprite.symbols.has(id)) {
+      sprite.symbols.set(id, symbol);
+    }
+  }
+}
+---
+
+<Fragment set:html={html} />