blume 2.0.3 → 2.1.1

package/src/components/layout/Banner.astro

@@ -1,7 +1,9 @@
 ---
 import data from "blume:data";
+import type { BlumeBanner } from "../../core/data.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { resolveLocalizable } from "../../core/localizable.ts";
 import { withBase } from "../islands/base-path.ts";
 import Icon from "../Icon.astro";
 
@@ -9,14 +11,11 @@ import Icon from "../Icon.astro";
 // every shell shows the same bar. The pre-paint hide for a dismissed banner and
 // the dismiss click handler live in the layout/Header, not here.
 interface Props {
-  banner:
-    | {
-        content: string;
-        link?: { text: string; href: string };
-        dismissible: boolean;
-        key: string;
-      }
-    | null;
+  /**
+   * The banner. Its `content` and link `text` may be per-locale maps, shown
+   * in `locale` (else the default locale, else the map's first entry).
+   */
+  banner: BlumeBanner | null;
   /** Localized banner labels. */
   strings?: UIStrings["banner"];
   /**
@@ -40,6 +39,11 @@ const b = { ...EN_UI.banner, ...strings };
 const navigation =
   (locale === undefined ? undefined : data.navigationByLocale[locale]) ??
   data.navigation;
+const defaultLocale = data.config.i18n?.defaultLocale;
+const content =
+  banner && resolveLocalizable(banner.content, locale, defaultLocale);
+const linkText =
+  banner?.link && resolveLocalizable(banner.link.text, locale, defaultLocale);
 const linkHref =
   banner?.link && banner.link.href === data.config.banner?.link?.href
     ? (navigation.bannerHref ?? banner.link.href)
@@ -55,13 +59,13 @@ const linkHref =
     >
       {/* The message is authored in one language, whatever the page's
           direction: `dir="auto"` keeps its punctuation where it was typed. */}
-      <span dir="auto">{banner.content}</span>
+      <span dir="auto">{content}</span>
       {banner.link && linkHref && (
         <a
           class="inline-flex items-center gap-1 font-medium underline underline-offset-2"
           href={withBase(linkHref)}
         >
-          {banner.link.text}
+          {linkText}
           <Icon class="rtl:-scale-x-100" name="arrow-right" size={14} />
         </a>
       )}

package/src/components/layout/Breadcrumbs.astro

@@ -11,9 +11,11 @@ interface Props {
   strings?: UIStrings["nav"];
   /** Left-align full width (for the wide API layout) instead of the prose measure. */
   wide?: boolean;
+  /** Match a `center` page's wider centered column instead of the prose measure. */
+  centered?: boolean;
 }
 
-const { crumbs, strings, wide = false } = Astro.props;
+const { crumbs, strings, wide = false, centered = false } = Astro.props;
 
 // 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
@@ -31,7 +33,9 @@ const eyebrowCrumb = crumbs.length > 1 ? crumbs[crumbs.length - 2] : null;
       aria-label={n.breadcrumb}
       class:list={[
         "mb-2 text-muted-foreground text-sm",
-        wide ? "max-w-none" : "mx-auto max-w-content",
+        wide
+          ? "max-w-none"
+          : ["mx-auto", centered ? "max-w-[54rem]" : "max-w-content"],
       ]}
     >
       {eyebrowCrumb.route ? (

package/src/components/layout/ConsentBanner.astro

@@ -0,0 +1,62 @@
+---
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import { newTabAttrs } from "../../core/new-tab.ts";
+import { withBase } from "../islands/base-path.ts";
+
+// The `native()` consent banner: a card at the foot of the viewport asking to
+// use analytics cookies. It renders hidden, and the consent runtime
+// (`consent/client.ts`) shows it until the reader answers, stores the answer,
+// and shows it again from the footer's Cookie settings link. Accept and
+// Decline carry the same weight, so declining is as easy as accepting.
+interface Props {
+  /** The privacy policy link: a page route or a URL. */
+  policy?: string;
+  /** Localized banner labels. */
+  strings?: UIStrings["consent"];
+}
+
+const { policy, strings } = Astro.props;
+const c = { ...EN_UI.consent, ...strings };
+const buttonClass =
+  "flex-1 rounded-blume border border-border px-4 py-2 text-foreground text-sm transition-colors hover:border-foreground";
+---
+
+<div
+  aria-label={c.label}
+  class="fixed inset-x-4 bottom-4 z-50 rounded-blume border border-border bg-background p-4 shadow-lg sm:start-auto sm:end-4 sm:w-96"
+  data-blume-consent-banner
+  hidden
+  role="region"
+>
+  <p class="text-foreground text-sm">
+    {c.message}{" "}
+    {
+      policy && (
+        <a
+          class="text-muted-foreground underline underline-offset-2 transition-colors hover:text-foreground"
+          href={withBase(policy)}
+          {...newTabAttrs(policy)}
+        >
+          {c.policy}
+        </a>
+      )
+    }
+  </p>
+  <div class="mt-3 flex gap-2">
+    <button
+      class={buttonClass}
+      data-blume-consent-choice="decline"
+      type="button"
+    >
+      {c.decline}
+    </button>
+    <button
+      class={buttonClass}
+      data-blume-consent-choice="accept"
+      type="button"
+    >
+      {c.accept}
+    </button>
+  </div>
+</div>

package/src/components/layout/ConsentHead.astro

@@ -0,0 +1,38 @@
+---
+import { consentHead } from "../../consent/head.ts";
+import { CONSENT_INIT_SCRIPT } from "../../consent/init.ts";
+import type { BlumeDataConfig } from "../../core/data.ts";
+
+// The consent layer's <head> output, rendered ahead of `Analytics.astro` by
+// every layout when `consent` is configured: the inline script that creates
+// `window.blumeConsent` (`consent/init.ts`), the adapter's own tags — a
+// hosted consent manager's loader and the bridge that reports its answers —
+// and the runtime that runs the held analytics (`consent/client.ts`), which
+// starts the adapter's browser module, if it has one (`blume:consent-client`,
+// see `consent/clients.ts`). Like analytics, a hosted manager loads in
+// production builds only; a browser module (`native()`'s banner) works in
+// `blume dev` too.
+interface Props {
+  consent: NonNullable<BlumeDataConfig["consent"]>;
+}
+
+const { consent } = Astro.props;
+const tags = import.meta.env.PROD ? consentHead(consent) : [];
+---
+
+<script data-kind={consent.kind} is:inline set:html={CONSENT_INIT_SCRIPT} />
+{
+  tags.map((tag) =>
+    tag.content === null ? (
+      <script is:inline {...tag.attributes} />
+    ) : (
+      <script is:inline set:html={tag.content} {...tag.attributes} />
+    )
+  )
+}
+<script>
+  import { startConsentClient } from "blume:consent-client";
+  import { startConsent } from "../../consent/client.ts";
+
+  startConsent(startConsentClient);
+</script>

package/src/components/layout/Directory.astro

@@ -0,0 +1,94 @@
+---
+import AccordionItem from "../content/AccordionItem.astro";
+import Card from "../content/Card.astro";
+import CardGroup from "../content/CardGroup.astro";
+import Icon from "../Icon.astro";
+import { directoryEntries } from "./nav-utils.ts";
+import type { NavGroup } from "./nav-utils.ts";
+
+/**
+ * A group page's directory: the group's other pages listed below the page's
+ * content, as cards or as an accordion whose subgroups open to their pages
+ * (the group's `directory`, see `core/schema.ts`).
+ */
+interface Props {
+  group: NavGroup;
+}
+
+const { group } = Astro.props;
+const entries = directoryEntries(group);
+---
+
+{
+  entries.length > 0 && (
+    <nav
+      aria-label={group.label}
+      class="mx-auto mt-6 max-w-content"
+      data-blume-directory={group.directory}
+    >
+      {group.directory === "card" ? (
+        <CardGroup>
+          {entries.map((entry) => (
+            <Card href={entry.href} icon={entry.icon} title={entry.label}>
+              {entry.description}
+            </Card>
+          ))}
+        </CardGroup>
+      ) : (
+        <div class="not-prose my-6 divide-y divide-border overflow-hidden rounded-blume border border-border">
+          {entries.map((entry, index) =>
+            entry.pages ? (
+              <AccordionItem
+                description={entry.description}
+                icon={entry.icon}
+                id={`blume-directory-${index + 1}`}
+                title={entry.label}
+              >
+                <ul class="grid gap-2 text-sm">
+                  {entry.pages.map((page) => (
+                    <li>
+                      <a
+                        class="text-muted-foreground no-underline transition-colors hover:text-foreground"
+                        href={page.route}
+                      >
+                        {page.label}
+                      </a>
+                    </li>
+                  ))}
+                </ul>
+              </AccordionItem>
+            ) : (
+              <a
+                class="flex items-center justify-between gap-4 p-4 font-medium text-foreground no-underline transition-colors hover:bg-muted/40"
+                href={entry.href}
+              >
+                <span class="flex items-start gap-2">
+                  {entry.icon && (
+                    <Icon
+                      class="mt-0.5 shrink-0 text-muted-foreground"
+                      name={entry.icon}
+                      size={16}
+                    />
+                  )}
+                  <span>
+                    <span class="block">{entry.label}</span>
+                    {entry.description && (
+                      <span class="block font-normal text-muted-foreground text-sm">
+                        {entry.description}
+                      </span>
+                    )}
+                  </span>
+                </span>
+                <Icon
+                  class="shrink-0 text-muted-foreground rtl:-scale-x-100"
+                  name="arrow-right"
+                  size={16}
+                />
+              </a>
+            )
+          )}
+        </div>
+      )}
+    </nav>
+  )
+}

package/src/components/layout/DrawerSwitchers.astro

@@ -0,0 +1,51 @@
+---
+// The header's selectors, version selector, and language switcher, as a row
+// at the top of the nav drawer. Below `lg` the sidebar is this drawer, and the
+// header has no room for them beside the logo, tabs, search, and icon
+// buttons, so it hides them whenever there's a drawer to open and this row
+// takes over; from `lg` up the row hides and the header shows them again.
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import type {
+  LocaleSwitchOption,
+  NavSelector as NavSelectorConfig,
+} from "../../core/types.ts";
+import LanguageSwitcher from "./LanguageSwitcher.astro";
+import NavSelector from "./NavSelector.astro";
+
+interface Props {
+  selectors: NavSelectorConfig[];
+  versionSelector?: NavSelectorConfig | null;
+  localeSwitch?: LocaleSwitchOption[];
+  route: string;
+  switcherStrings?: UIStrings["languageSwitcher"];
+}
+
+const { selectors, versionSelector, localeSwitch, route, switcherStrings } =
+  Astro.props;
+const hasLocales = (localeSwitch?.length ?? 0) > 1;
+---
+
+{
+  (selectors.length > 0 || versionSelector || hasLocales) && (
+    <div class="mb-4 flex flex-col gap-2 border-border border-b pb-4 lg:hidden">
+      {selectors.map((selector) => (
+        <NavSelector route={route} selector={selector} variant="drawer" />
+      ))}
+      {versionSelector && (
+        <NavSelector
+          route={route}
+          selector={versionSelector}
+          variant="drawer"
+        />
+      )}
+      {localeSwitch && hasLocales && (
+        <LanguageSwitcher
+          label={switcherStrings?.label ?? "Language"}
+          options={localeSwitch}
+          untranslatedLabel={switcherStrings?.untranslated ?? "Not translated"}
+          variant="drawer"
+        />
+      )}
+    </div>
+  )
+}

package/src/components/layout/Empty.astro

@@ -1,6 +1,6 @@
 ---
 // A no-op layout slot: renders nothing regardless of props. Used as the built-in
-// fallback for the content-injection slots (Footer, PageHeader, PageFooter) that
-// have no default, so an unconfigured slot renders empty while `resolveSlot`
+// fallback for the content-injection slots (PageHeader, PageFooter) that have
+// no default, so an unconfigured slot renders empty while `resolveSlot`
 // still returns a valid component and the generated pages stay type-safe.
 ---

package/src/components/layout/Header.astro

@@ -2,7 +2,7 @@
 import Ask from "blume:ask";
 import data from "blume:data";
 import { withBase, withMountedBase } from "../islands/base-path.ts";
-import { NEW_TAB_ATTRS, newTabAttrs } from "../../core/new-tab.ts";
+import { newTabAttrs } from "../../core/new-tab.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
@@ -11,7 +11,6 @@ import type {
   Navigation,
   NavSelector as NavSelectorConfig,
 } from "../../core/types.ts";
-import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
 import LanguageSwitcher from "./LanguageSwitcher.astro";
 import Logo from "./Logo.astro";
@@ -129,11 +128,19 @@ const activeTab = currentTabForRoute(navigation.tabs, route, navigation.root);
 // mobile nav below `lg`, so the inline tabs wait until `lg` to avoid duplicating
 // the drawer's links between `md` and `lg`.
 const tabsNavClass = hasSidebar
-  ? "hidden gap-1 md:flex"
-  : "hidden gap-1 lg:flex";
+  ? "hidden shrink-0 gap-1 md:flex"
+  : "hidden shrink-0 gap-1 lg:flex";
 
 const iconButton =
-  "inline-flex size-9 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground";
+  "inline-flex size-9 shrink-0 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground";
+
+// Below `lg`, where the sidebar is a drawer, the selectors, version selector,
+// and language switcher move into a row at the top of it (see
+// DrawerSwitchers.astro): they scope what the sidebar lists, and beside the
+// logo, tabs, search, and icon buttons they'd overflow a phone or tablet
+// header. With no drawer to open they have nowhere else to go, so they stay.
+// Nothing in the header shrinks except the logo, whose title truncates.
+const switcherClass = showNavToggle ? "hidden shrink-0 lg:block" : "shrink-0";
 
 // Header links: plain actions are secondary and hide below `sm`, where the
 // header has room for the logo and the drawer toggle and nothing else. The one
@@ -186,37 +193,44 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
 ---
 
 <header
-  class="sticky top-0 z-40 flex h-16 items-center gap-3 bg-background/90 px-4 backdrop-blur md:px-6"
+  class="sticky top-0 z-40 flex h-16 items-center gap-2 bg-background/90 px-4 backdrop-blur sm:gap-3 md:px-6 lg:grid lg:grid-cols-[minmax(0,1fr)_auto_minmax(max-content,1fr)]"
   data-blume-header
   data-blume-header-transparent={transparent ? "" : undefined}
 >
-  {
-    showNavToggle && (
-      <button
-        aria-controls="blume-nav-drawer"
-        aria-expanded="false"
-        aria-label={n.toggleNavigation}
-        class={`${iconButton} lg:hidden`}
-        data-blume-nav-toggle
-        type="button"
-      >
-        <Icon name="menu" size={20} />
-      </button>
-    )
-  }
-  <LogoSlot locale={locale} logo={logo} site={site} />
-  {
-    navigation.selectors.length > 0 && (
-      <div class="flex items-center gap-1.5">
-        {navigation.selectors.map((selector) => (
-          <NavSelector route={route} selector={selector} />
-        ))}
-      </div>
-    )
-  }
+  {/* From `lg` the header is three columns, so the tabs sit at its center:
+      the logo side and the controls side share the rest equally. The logo
+      side may shrink to nothing (its title truncates, as on phones); the
+      controls never shrink, so when they need more than half, the tabs move
+      over rather than overlap. Below `lg` it's one row, tabs after the logo. */}
+  <div class="flex min-w-0 items-center gap-2 sm:gap-3 lg:col-start-1">
+    {
+      showNavToggle && (
+        <button
+          aria-controls="blume-nav-drawer"
+          aria-expanded="false"
+          aria-label={n.toggleNavigation}
+          class={`${iconButton} lg:hidden`}
+          data-blume-nav-toggle
+          type="button"
+        >
+          <Icon name="menu" size={20} />
+        </button>
+      )
+    }
+    <LogoSlot locale={locale} logo={logo} site={site} />
+    {
+      navigation.selectors.length > 0 && (
+        <div class:list={["flex items-center gap-1.5", switcherClass]}>
+          {navigation.selectors.map((selector) => (
+            <NavSelector route={route} selector={selector} />
+          ))}
+        </div>
+      )
+    }
+  </div>
   {
     navigation.tabs.length > 0 && (
-      <nav aria-label={n.sections} class={tabsNavClass}>
+      <nav aria-label={n.sections} class:list={[tabsNavClass, "lg:col-start-2"]}>
         {navigation.tabs.map((tab) =>
           tab.items && tab.items.length > 0 ? (
             <NavTabMenu
@@ -241,38 +255,31 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
       </nav>
     )
   }
-  <div class="flex-1"></div>
-  {
-    /* Right-aligned next to the language switcher: the spacer absorbs its
-       width, so pages without a version selector (blog, generated references)
-       keep the logo, tabs, and the rest of this cluster in place — no layout
-       shift when crossing into the docs. */
-    versionSelector && (
-      <NavSelector align="end" route={route} selector={versionSelector} />
-    )
-  }
-  {
-    localeSwitch && localeSwitch.length > 1 && (
-      <LanguageSwitcher
-        label={switcherStrings?.label ?? "Language"}
-        options={localeSwitch}
-        untranslatedLabel={switcherStrings?.untranslated ?? "Not translated"}
-      />
-    )
-  }
-  {
-    searchEnabled && (
-      <SearchSlot
-        assistantEnabled={assistantEnabled}
-        locale={searchLocale}
-        navigation={navigation}
-        popularPages={data.config.search.popular}
-        strings={searchStrings}
-        version={searchVersion}
-      />
-    )
-  }
-  <div class="flex items-center gap-2">
+  <div class="flex-1 lg:hidden"></div>
+  {/* Everything on the right sits in one group with a tight gap: the version
+      and language pickers, the header links, and the icon buttons. Below `lg`
+      the spacer absorbs its width, so pages without a version selector (blog,
+      generated references) keep the logo and tabs in place — no layout shift
+      when crossing into the docs. */}
+  <div class="flex shrink-0 items-center gap-1 lg:col-start-3 lg:justify-self-end">
+    {
+      versionSelector && (
+        <div class={switcherClass}>
+          <NavSelector align="end" route={route} selector={versionSelector} />
+        </div>
+      )
+    }
+    {
+      localeSwitch && localeSwitch.length > 1 && (
+        <div class={switcherClass}>
+          <LanguageSwitcher
+            label={switcherStrings?.label ?? "Language"}
+            options={localeSwitch}
+            untranslatedLabel={switcherStrings?.untranslated ?? "Not translated"}
+          />
+        </div>
+      )
+    }
     {
       /* Plain links first, then the one filled button: the reader's eye lands
          on the button because nothing beside it competes. */
@@ -299,29 +306,24 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
       )
     }
     {
-      navigation.repoUrl && (
-        <a
-          aria-label={n.githubRepository}
-          class={iconButton}
-          href={navigation.repoUrl}
-          {...NEW_TAB_ATTRS}
-        >
-          <svg
-            aria-hidden="true"
-            fill="currentColor"
-            height="18"
-            set:html={GITHUB_MARK}
-            viewBox="0 0 16 16"
-            width="18"
-            xmlns="http://www.w3.org/2000/svg"
-          />
-        </a>
+      /* The icon buttons, each named by a tooltip. The site's repository and
+         social profiles live in the footer. */
+      searchEnabled && (
+        <SearchSlot
+          assistantEnabled={assistantEnabled}
+          locale={searchLocale}
+          navigation={navigation}
+          popularPages={data.config.search.popular}
+          strings={searchStrings}
+          version={searchVersion}
+        />
       )
     }
     <button
       aria-label={n.toggleTheme}
       class={iconButton}
       data-blume-theme-toggle
+      data-blume-tooltip={n.toggleTheme}
       type="button"
     >
       <span class="inline-flex dark:hidden"><Icon name="sun" size={18} /></span>
@@ -334,6 +336,46 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
 {transparent && <script is:inline set:html={transparentScript} />}
 
 <style is:global>
+  /* The header's icon buttons are named by a tooltip below them, shown on hover
+     (where there is one) and on keyboard focus. It hangs from the button's end
+     edge, so the last button's tooltip never runs past the viewport, and it
+     keeps the page's own colors under a transparent header. */
+  [data-blume-tooltip] {
+    position: relative;
+  }
+  [data-blume-tooltip]::after {
+    content: attr(data-blume-tooltip);
+    position: absolute;
+    top: calc(100% + 0.375rem);
+    inset-inline-end: 0;
+    z-index: 50;
+    padding: 0.25rem 0.5rem;
+    border-radius: 0.375rem;
+    background-color: var(--blume-header-foreground);
+    color: var(--blume-header-background);
+    font-size: 0.75rem;
+    font-weight: 500;
+    line-height: 1rem;
+    white-space: nowrap;
+    pointer-events: none;
+    opacity: 0;
+    visibility: hidden;
+    transition:
+      opacity 120ms ease,
+      visibility 0s linear 120ms;
+  }
+  [data-blume-tooltip]:focus-visible::after {
+    opacity: 1;
+    visibility: visible;
+    transition: opacity 120ms ease;
+  }
+  @media (hover: hover) {
+    [data-blume-tooltip]:hover::after {
+      opacity: 1;
+      visibility: visible;
+      transition: opacity 120ms ease 400ms;
+    }
+  }
   /* Transparent header (PageLayout `transparentHeader`): at the top of the
      page the bar has no background and its chrome renders in white so it can
      sit over a dark hero; once scrolled it is the frosted bar again. The color