blume 2.0.0 → 2.0.2

package/src/components/layout/NavTabMenu.astro

@@ -0,0 +1,133 @@
+---
+// A header tab with dropdown `items` (`navigation.tabs[].items`). In the
+// header's tab bar (`variant="bar"`) it is the nav selectors' floating
+// `<details>` dropdown: the `<summary>` is the disclosure button (the browser
+// exposes its expanded state), the panel a list of links, and the shared
+// light-dismiss closes it on an outside press, Escape (focus returns to the
+// tab), or focus leaving it. In a navigation drawer (`variant="drawer"`) the
+// same items expand in place under the tab, like a sidebar group, open from
+// the start on the tab's own section. Both are server-rendered and the scripts
+// delegate from `document`, so client-router swaps need no re-init.
+import type { NavTab } from "../../core/types.ts";
+import Icon from "../Icon.astro";
+import { withBase } from "../islands/base-path.ts";
+
+interface Props {
+  tab: NavTab;
+  /** The page's route, to mark the item it is on. */
+  route: string;
+  /** Whether the current route falls under this tab. */
+  active: boolean;
+  variant: "bar" | "drawer";
+}
+
+const { tab, route, active, variant } = Astro.props;
+const items = tab.items ?? [];
+// The tab itself is a button, not a page, so its "you are here" state is
+// `aria-current="true"` (current item of a set); an item is the page.
+const tabCurrent = active ? "true" : undefined;
+const itemCurrent = (path: string): "page" | undefined =>
+  path === route ? "page" : undefined;
+
+const barRowClass =
+  "flex w-full items-start gap-2.5 rounded-md px-2 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:text-foreground";
+const drawerRowClass =
+  "flex items-center gap-2 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]:text-foreground";
+---
+
+{
+  variant === "bar" ? (
+    <details class="group relative" data-blume-dropdown>
+      <summary
+        aria-current={tabCurrent}
+        class="inline-flex cursor-pointer list-none items-center gap-1 rounded-full px-3 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=true]:text-foreground [&::-webkit-details-marker]:hidden"
+      >
+        {tab.icon && (
+          <Icon class="me-0.5 shrink-0" name={tab.icon} size={14} />
+        )}
+        {tab.label}
+        <Icon
+          class="transition-transform group-open:rotate-180"
+          name="chevron-down"
+          size={14}
+        />
+      </summary>
+      <div
+        class="absolute start-0 z-50 mt-2 min-w-56 max-w-[calc(100vw-1rem)] rounded-blume border border-border bg-background p-1 shadow-xl"
+        data-blume-dropdown-panel
+      >
+        {items.map((item) => (
+          <a
+            aria-current={itemCurrent(item.path)}
+            class={barRowClass}
+            href={withBase(item.path)}
+          >
+            {item.icon && <Icon class="mt-0.5" name={item.icon} size={16} />}
+            <span class="flex-1">
+              <span class="flex items-center gap-2">
+                {item.label}
+                {item.tag && (
+                  <span class="rounded-full bg-muted px-1.5 py-0.5 text-[0.65rem] text-muted-foreground">
+                    {item.tag}
+                  </span>
+                )}
+              </span>
+              {item.description && (
+                <span class="mt-0.5 block text-muted-foreground text-xs">
+                  {item.description}
+                </span>
+              )}
+            </span>
+          </a>
+        ))}
+      </div>
+    </details>
+  ) : (
+    <details class="group" open={active}>
+      <summary
+        aria-current={tabCurrent}
+        class="flex cursor-pointer list-none items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=true]:text-foreground [&::-webkit-details-marker]:hidden"
+      >
+        {tab.icon && <Icon class="shrink-0" name={tab.icon} size={14} />}
+        <span class="flex-1 truncate">{tab.label}</span>
+        <Icon
+          class="shrink-0 transition-transform group-open:rotate-180"
+          name="chevron-down"
+          size={14}
+        />
+      </summary>
+      <ul class="m-0 ms-2.5 list-none space-y-px border-border border-s p-0 ps-2">
+        {items.map((item) => (
+          <li>
+            <a
+              aria-current={itemCurrent(item.path)}
+              class={drawerRowClass}
+              href={withBase(item.path)}
+            >
+              {item.icon && (
+                <Icon class="shrink-0" name={item.icon} size={14} />
+              )}
+              <span class="flex-1 truncate">{item.label}</span>
+              {item.tag && (
+                <span class="shrink-0 rounded-full bg-muted px-1.5 py-0.5 text-[0.65rem] text-muted-foreground">
+                  {item.tag}
+                </span>
+              )}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </details>
+  )
+}
+
+<script>
+  import { installDropdownDismiss } from "../dropdown-dismiss.ts";
+  import { installDropdownClamp } from "./dropdown-clamp.ts";
+
+  // Outside-click / Escape / focus-out dismissal and viewport clamping for
+  // the header dropdown, shared with the nav selectors. The drawer variant
+  // opts into neither: it is an in-place disclosure, not a floating panel.
+  installDropdownDismiss();
+  installDropdownClamp();
+</script>

package/src/components/layout/NavTree.astro

@@ -79,6 +79,9 @@ const fragmentFor = (node: NavNode, id: string): string | undefined =>
 // blank — the PageActions pattern.
 const n = { ...EN_UI.nav, ...strings };
 
+/** The DOM id of a drill-in panel, which its drill button controls. */
+const navPanelId = (id: string): string => `blume-nav-panel-${id}`;
+
 const badgeBase =
   "shrink-0 rounded-full px-1.5 py-0.5 font-medium text-[0.65rem] leading-none";
 // HTTP-method, AsyncAPI-action, and GraphQL operation-kind badges (from a
@@ -165,6 +168,7 @@ const initialId =
             data-nav-panel={panel.id}
             data-nav-src={src}
             hidden={panel.id !== initialId}
+            id={navPanelId(panel.id)}
           >
             {/* 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
@@ -174,7 +178,7 @@ const initialId =
               <div class="mb-3 flex items-center gap-0.5">
                 <button
                   aria-label={n.back}
-                  class="-ml-1 flex shrink-0 items-center justify-center self-stretch rounded-[0.65rem] px-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                  class="-ms-1 flex shrink-0 items-center justify-center self-stretch rounded-[0.65rem] px-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
                   data-nav-back={panel.parentId}
                   type="button"
                 >
@@ -195,7 +199,7 @@ const initialId =
             ) : (
               <button
                 aria-label={`${n.back}: ${panel.label}`}
-                class="-ml-1 mb-3 flex w-full items-center gap-1.5 rounded-[0.65rem] p-1 text-left font-semibold text-foreground text-sm transition-colors hover:bg-muted"
+                class="-ms-1 mb-3 flex w-full items-center gap-1.5 rounded-[0.65rem] p-1 text-start font-semibold text-foreground text-sm transition-colors hover:bg-muted"
                 data-nav-back={panel.parentId}
                 type="button"
               >
@@ -293,11 +297,16 @@ const initialId =
         const spacing =
           index === 0 ? "mt-0" : display === "flat" ? "mt-6" : "mt-0.5";
 
-        // `page`: a single row that drills into this group's panel.
+        // `page`: a single row that drills into this group's panel. It
+        // controls that panel; NavTreeScript keeps `aria-expanded` in step
+        // with the panel shown (static markup, since cached subtrees and
+        // fragments can't carry per-page state).
         if (display === "page") {
           return (
             <li class={spacing}>
               <button
+                aria-controls={navPanelId(id)}
+                aria-expanded="false"
                 class="blume-nav-drill"
                 data-nav-to={id}
                 type="button"
@@ -377,7 +386,7 @@ const initialId =
                   </span>
                 </summary>
                 <div
-                  class="space-y-0.5 border-border border-l pl-3"
+                  class="space-y-0.5 border-border border-s ps-3"
                   data-nav-src={open ? undefined : fragmentFor(item, id)}
                 >
                   {/* A closed group's children are deferred (fetched into this
@@ -434,7 +443,7 @@ const initialId =
                   )}
                   <span class="truncate">{item.label}</span>
                   {item.badge && (
-                    <span class={`ml-auto ${badgeClassFor(item.badge)}`}>{item.badge}</span>
+                    <span class={`ms-auto ${badgeClassFor(item.badge)}`}>{item.badge}</span>
                   )}
                 </a>
               ) : (
@@ -448,7 +457,7 @@ const initialId =
                   )}
                   <span class="truncate">{item.label}</span>
                   {item.badge && (
-                    <span class={`ml-auto ${badgeClassFor(item.badge)}`}>{item.badge}</span>
+                    <span class={`ms-auto ${badgeClassFor(item.badge)}`}>{item.badge}</span>
                   )}
                 </>
               )}

package/src/components/layout/NavTreeCache.astro

@@ -4,7 +4,10 @@
 // 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.
+// registered into whichever page reuses it. A render with no sprite (the
+// `/blume-nav/` fragment route) inlines its icons instead, so it is cached
+// apart: sprite references reused there would point at symbols the page that
+// fetches the fragment may never have rendered.
 import type { NavNode } from "../../core/types.ts";
 import { iconSpriteFor, referencedIconSymbols } from "../icon-sprite.ts";
 import type { IconSymbol } from "../icon-sprite.ts";
@@ -19,7 +22,7 @@ const { node, variant } = Astro.props;
 const sprite = iconSpriteFor(Astro.locals);
 const { html, icons } = await cachedNavSubtree(
   node,
-  variant,
+  `${variant}|${sprite ? "sprite" : "inline"}`,
   async () => {
     const rendered = await Astro.slots.render("default");
     const used: [string, IconSymbol][] = [];

package/src/components/layout/NavTreeScript.astro

@@ -40,7 +40,12 @@
     return pending;
   };
 
-  /** Fill a deferred element from its fragment; a no-op once filled. */
+  /**
+   * Fill a deferred element from its fragment; a no-op once filled. The rows
+   * are appended, not swapped in: a drill-in panel keeps its own back row
+   * (the Back button and the section's title) above the deferred rows, and a
+   * collapsed group's slot is empty anyway.
+   */
   const fillDeferred = async (slot: HTMLElement): Promise<void> => {
     const src = slot.dataset.navSrc;
     if (!src) {
@@ -48,8 +53,12 @@
     }
     slot.setAttribute("aria-busy", "true");
     try {
-      slot.innerHTML = await loadFragment(src);
-      delete slot.dataset.navSrc;
+      const html = await loadFragment(src);
+      // Two opens racing on the same fetch fill it once.
+      if (slot.dataset.navSrc) {
+        slot.insertAdjacentHTML("beforeend", html);
+        delete slot.dataset.navSrc;
+      }
     } finally {
       slot.removeAttribute("aria-busy");
     }
@@ -179,21 +188,52 @@
       if (prev === next) {
         return;
       }
+      // The pressed drill or back button sits in the panel about to hide, so
+      // its focus has to move into the panel replacing it — left behind, the
+      // next Tab would leave the sidebar.
+      const hadFocus = prev?.contains(document.activeElement) ?? false;
       // Settle any in-flight slide before starting the next one.
       if (this.finishSlide) {
         this.finishSlide();
       }
       this.active = next;
       this.dataset.active = next.dataset.navPanel;
+      this.syncExpanded(next);
 
       if (!(animate && prev) || this.reduced()) {
         for (const panel of this.querySelectorAll<HTMLElement>("[data-nav-panel]")) {
           panel.hidden = panel !== next;
         }
-        return;
+      } else {
+        this.slide(prev, next, this.depth(next) > this.depth(prev));
       }
+      if (hadFocus && prev) {
+        this.focusInto(next, prev);
+      }
+    }
+
+    /** Each drill button is expanded exactly while the panel it opens shows. */
+    syncExpanded(shown: HTMLElement): void {
+      for (const drill of this.querySelectorAll("[data-nav-to]")) {
+        drill.setAttribute(
+          "aria-expanded",
+          String(drill.getAttribute("data-nav-to") === shown.dataset.navPanel)
+        );
+      }
+    }
 
-      this.slide(prev, next, this.depth(next) > this.depth(prev));
+    /**
+     * Focus `next` after leaving `prev`: going back, the drill button that
+     * opened `prev`; drilling in, the new panel's back button (its first
+     * control). `preventScroll` keeps the focus from scrolling the clipped
+     * container mid-slide.
+     */
+    focusInto(next: HTMLElement, prev: HTMLElement): void {
+      const target =
+        next.querySelector<HTMLElement>(
+          `[data-nav-to="${prev.dataset.navPanel}"]`
+        ) ?? next.querySelector<HTMLElement>("button, a[href]");
+      target?.focus({ preventScroll: true });
     }
 
     slide(out: HTMLElement, into: HTMLElement, forward: boolean): void {

package/src/components/layout/PageLayout.astro

@@ -38,6 +38,7 @@ import {
 } from "../../og/dimensions.ts";
 import { buildStructuredData } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
+import Icon from "../Icon.astro";
 import { stripBase, withBase } from "../islands/base-path.ts";
 import { pageDirection, pageLocale } from "./page-locale.ts";
 import { searchLocaleFor } from "./search-locale.ts";
@@ -55,6 +56,7 @@ import {
 } from "./head-scripts.ts";
 import Header from "./Header.astro";
 import { currentTabForRoute } from "./nav-utils.ts";
+import NavTabMenu from "./NavTabMenu.astro";
 import WebMcp from "./WebMcp.astro";
 
 interface Props {
@@ -78,11 +80,11 @@ interface Props {
   fontCssVars?: (string | FontHead)[];
   searchEnabled: boolean;
   /**
-   * Opt this page out of the header's Ask AI trigger. Defaults to whether Ask
-   * AI is configured, so a custom page gets the same trigger the docs pages have
+   * Opt this page out of the header's assistant trigger. Defaults to whether the
+   * assistant is configured, so a custom page gets the same trigger the docs pages have
    * without wiring anything up.
    */
-  askEnabled?: boolean;
+  assistantEnabled?: boolean;
   /**
    * Start the header see-through, with its chrome in white, so it can sit over
    * a dark hero at the top of the page; it returns to the frosted bar as soon
@@ -163,7 +165,7 @@ const {
   themeMode,
   fontCssVars,
   searchEnabled,
-  askEnabled,
+  assistantEnabled,
   transparentHeader,
   siteUrl,
   ogEnabled,
@@ -387,10 +389,10 @@ createIconSprite(Astro.locals);
     >
     {/* Every new-tab link's aria-describedby target (see core/new-tab.ts). */}
     <span hidden id={NEW_TAB_HINT_ID}>{navStrings.opensInNewTab}</span>
-    <Banner banner={banner} strings={strings.banner} />
+    <Banner banner={banner} locale={locale} strings={strings.banner} />
     <Header
-      askEnabled={askEnabled}
-      askStrings={strings.ask}
+      assistantEnabled={assistantEnabled}
+      assistantStrings={strings.assistant}
       hasSidebar={false}
       locale={locale}
       localeSwitch={localeSwitch}
@@ -426,13 +428,25 @@ createIconSprite(Astro.locals);
               <ul class="m-0 list-none p-0">
                 {navigation.tabs.map((tab) => (
                   <li>
-                    <a
-                      aria-current={tab === activeTab ? "page" : undefined}
-                      class="block rounded-[0.65rem] px-2.5 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:text-foreground"
-                      href={withBase(tab.href ?? tab.path)}
-                    >
-                      {tab.label}
-                    </a>
+                    {tab.items && tab.items.length > 0 ? (
+                      <NavTabMenu
+                        active={tab === activeTab}
+                        route={route}
+                        tab={tab}
+                        variant="drawer"
+                      />
+                    ) : (
+                      <a
+                        aria-current={tab === activeTab ? "page" : undefined}
+                        class="flex items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:text-foreground"
+                        href={withBase(tab.href ?? tab.path)}
+                      >
+                        {tab.icon && (
+                          <Icon class="shrink-0" name={tab.icon} size={14} />
+                        )}
+                        <span class="flex-1 truncate">{tab.label}</span>
+                      </a>
+                    )}
                   </li>
                 ))}
               </ul>

package/src/components/layout/Pagination.astro

@@ -26,19 +26,19 @@ const s = { ...EN_UI.page, ...strings };
   (prev || next) && (
     <nav
       aria-label={s.pagination}
-      class="mx-auto mt-12 flex max-w-content justify-between gap-4 border-border border-t pt-6 max-md:flex-col"
+      class="mx-auto mt-12 flex max-w-content justify-between gap-4 border-border border-t pt-6"
     >
       {prev ? (
         <a
-          class="flex max-w-[48%] flex-1 items-center gap-2 rounded-blume border border-border px-4 py-3 text-foreground transition-colors hover:border-foreground max-md:max-w-full"
+          class="flex max-w-[48%] flex-1 items-center gap-2 rounded-blume border border-border px-4 py-3 text-foreground transition-colors hover:border-foreground"
           href={withBase(prev.route)}
         >
           <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
           <span class="min-w-0">
-            <span class="block text-muted-foreground text-xs max-md:hidden">
+            <span class="block text-muted-foreground text-xs">
               {s.previous}
             </span>
-            <span class="block truncate font-medium">{prev.label}</span>
+            <span class="block font-medium max-md:line-clamp-2 max-md:wrap-break-word md:truncate">{prev.label}</span>
           </span>
         </a>
       ) : (
@@ -46,14 +46,14 @@ const s = { ...EN_UI.page, ...strings };
       )}
       {next && (
         <a
-          class="ms-auto flex max-w-[48%] flex-1 items-center justify-end gap-2 rounded-blume border border-border px-4 py-3 text-end text-foreground transition-colors hover:border-foreground max-md:max-w-full"
+          class="ms-auto flex max-w-[48%] flex-1 items-center justify-end gap-2 rounded-blume border border-border px-4 py-3 text-end text-foreground transition-colors hover:border-foreground"
           href={withBase(next.route)}
         >
           <span class="min-w-0">
-            <span class="block text-muted-foreground text-xs max-md:hidden">
+            <span class="block text-muted-foreground text-xs">
               {s.next}
             </span>
-            <span class="block truncate font-medium">{next.label}</span>
+            <span class="block font-medium max-md:line-clamp-2 max-md:wrap-break-word md:truncate">{next.label}</span>
           </span>
           <Icon class="rtl:-scale-x-100" name="arrow-right" size={16} />
         </a>

package/src/components/layout/ReferenceLayout.astro

@@ -146,18 +146,21 @@ createIconSprite(Astro.locals);
     >
     {/* Every new-tab link's aria-describedby target (see core/new-tab.ts). */}
     <span hidden id={NEW_TAB_HINT_ID}>{navStrings.opensInNewTab}</span>
-    <Banner banner={banner} strings={strings.banner} />
+    <Banner banner={banner} locale={locale} strings={strings.banner} />
     <Header
-      askStrings={strings.ask}
+      assistantStrings={strings.assistant}
       hasDrawer={false}
       hasSidebar={false}
       locale={locale}
       logo={logo}
+      navStrings={navStrings}
       navigation={navigation}
       route={route}
       searchEnabled={searchEnabled}
       searchLocale={searchLocale}
+      searchStrings={strings.search}
       site={site}
+      switcherStrings={strings.languageSwitcher}
     />
     <div
       class="h-[calc(100dvh-4rem)] overflow-auto border-border border-t [&>[data-scalar-client]]:h-full"

package/src/components/layout/RootLayout.astro

@@ -66,6 +66,7 @@ import {
   navGroupIds,
   sidebarForRoute,
 } from "./nav-utils.ts";
+import NavTabMenu from "./NavTabMenu.astro";
 import NavTree from "./NavTree.astro";
 import { resolveSlot } from "./overrides.ts";
 import { pageDirection, pageLocale } from "./page-locale.ts";
@@ -122,10 +123,10 @@ interface Props {
   canonical?: string | null;
   editUrl?: string | null;
   /**
-   * Opt this page out of the header's Ask AI trigger. Defaults to whether Ask
-   * AI is configured, so pages never wire the trigger up themselves.
+   * Opt this page out of the header's assistant trigger. Defaults to whether the
+   * assistant is configured, so pages never wire the trigger up themselves.
    */
-  askEnabled?: boolean;
+  assistantEnabled?: boolean;
   /** Show the "Was this page helpful?" rating below the content. */
   feedback?: boolean;
   exportPdf?: boolean;
@@ -248,7 +249,7 @@ const {
   x,
   canonical,
   editUrl,
-  askEnabled,
+  assistantEnabled,
   feedback = false,
   exportPdf,
   exportEpub,
@@ -579,11 +580,11 @@ createIconSprite(Astro.locals);
     >
     {/* Every new-tab link's aria-describedby target (see core/new-tab.ts). */}
     <span hidden id={NEW_TAB_HINT_ID}>{navStrings.opensInNewTab}</span>
-    <Banner banner={banner} strings={strings.banner} />
+    <Banner banner={banner} locale={locale} strings={strings.banner} />
     <VersionBanner notice={versionNotice ?? null} />
     <HeaderSlot
-      askEnabled={askEnabled}
-      askStrings={strings.ask}
+      assistantEnabled={assistantEnabled}
+      assistantStrings={strings.assistant}
       layout={layout}
       locale={locale}
       localeSwitch={localeSwitch}
@@ -677,13 +678,25 @@ createIconSprite(Astro.locals);
               <ul class="m-0 list-none p-0">
                 {navigation.tabs.map((tab) => (
                   <li>
-                    <a
-                      aria-current={tab === activeTab ? "page" : undefined}
-                      class="block rounded-[0.65rem] px-2.5 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:text-foreground"
-                      href={withBase(tab.href ?? tab.path)}
-                    >
-                      {tab.label}
-                    </a>
+                    {tab.items && tab.items.length > 0 ? (
+                      <NavTabMenu
+                        active={tab === activeTab}
+                        route={page.route}
+                        tab={tab}
+                        variant="drawer"
+                      />
+                    ) : (
+                      <a
+                        aria-current={tab === activeTab ? "page" : undefined}
+                        class="flex items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:text-foreground"
+                        href={withBase(tab.href ?? tab.path)}
+                      >
+                        {tab.icon && (
+                          <Icon class="shrink-0" name={tab.icon} size={14} />
+                        )}
+                        <span class="flex-1 truncate">{tab.label}</span>
+                      </a>
+                    )}
                   </li>
                 ))}
               </ul>