blume 2.0.3 → 2.1.0

package/src/components/layout/NavSelector.astro

@@ -19,9 +19,15 @@ interface Props {
    * overflow the viewport — pass `end` there.
    */
   align?: "start" | "end";
+  /**
+   * `bar` (the default) for the header; `drawer` for the top of the nav
+   * drawer, where the trigger spans the drawer, always shows its label, and
+   * opens a panel as wide as itself, so nothing reaches past the drawer edge.
+   */
+  variant?: "bar" | "drawer";
 }
 
-const { selector, route, align = "start" } = Astro.props;
+const { selector, route, align = "start", variant = "bar" } = Astro.props;
 
 // The active item is the deepest path the current route sits under (on a path
 // boundary, so `/api` never claims `/api-reference` routes), falling back to
@@ -37,25 +43,37 @@ const active =
 // version like "v2" or "Latest"): on a phone a bare chevron doesn't say what
 // it switches. Longer product names still collapse to the icon there.
 const label = active?.label ?? selector.label;
-const labelClass = label.length <= 6 ? undefined : "max-sm:hidden";
+let labelClass: string | undefined;
+if (variant === "drawer") {
+  labelClass = "flex-1 text-start";
+} else if (label.length > 6) {
+  labelClass = "max-sm:hidden";
+}
 // The accessible name carries the visible active label too (WCAG 2.5.3,
 // label in name), so a voice-control user can say "v2" to open it — the
 // language switcher's pattern.
 const summaryLabel =
   label === selector.label ? selector.label : `${selector.label}: ${label}`;
 
-const iconButton =
-  "inline-flex h-9 cursor-pointer items-center gap-1.5 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground";
+// Borderless in the header, like the icon buttons and the language switcher;
+// bordered in the drawer, where the trigger spans it.
+const triggerClass =
+  variant === "bar"
+    ? "inline-flex h-9 cursor-pointer items-center gap-1.5 rounded-full px-3 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground group-open:bg-muted group-open:text-foreground"
+    : "inline-flex h-9 w-full cursor-pointer items-center gap-1.5 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground";
 const menuRowClass =
   "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=true]:text-foreground";
 ---
 
 {
   selector.items.length > 0 && (
-    <details class="group relative" data-blume-dropdown>
+    <details
+      class:list={["group relative", variant === "drawer" && "w-full"]}
+      data-blume-dropdown
+    >
       <summary
         aria-label={summaryLabel}
-        class={`${iconButton} list-none [&::-webkit-details-marker]:hidden`}
+        class:list={[triggerClass, "list-none [&::-webkit-details-marker]:hidden"]}
       >
         {active?.icon && <Icon name={active.icon} size={16} />}
         <span class={labelClass}>{label}</span>
@@ -66,7 +84,15 @@ const menuRowClass =
         />
       </summary>
       <div
-        class={`absolute z-50 mt-2 min-w-56 max-w-[calc(100vw-1rem)] rounded-blume border border-border bg-background p-1 shadow-xl ${align === "end" ? "end-0" : "start-0"}`}
+        class:list={[
+          "absolute z-50 mt-2 rounded-blume border border-border bg-background p-1 shadow-xl",
+          variant === "drawer"
+            ? "inset-x-0"
+            : [
+                "min-w-56 max-w-[calc(100vw-1rem)]",
+                align === "end" ? "end-0" : "start-0",
+              ],
+        ]}
         data-blume-dropdown-panel
       >
         {selector.items.map((item) => (

package/src/components/layout/PageFeedback.astro

@@ -1,14 +1,22 @@
 ---
+import data from "blume:data";
+
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import Icon from "../Icon.astro";
+import { COMMENT_MAX_LENGTH } from "./page-feedback.ts";
 
 interface Props {
+  /** Ask for a written comment after the rating (`feedback.comments`). */
+  comments?: boolean;
   /** Localized feedback labels. */
   strings?: UIStrings["feedback"];
 }
 
-const { strings } = Astro.props;
+const { comments = false, strings } = Astro.props;
+// Answers go through analytics, so under a consent layer the rating waits,
+// hidden, until the reader allows analytics (`page-feedback.ts` shows it).
+const waitsForConsent = data.config.consent !== null;
 // Merge over the English baseline per key (rather than `strings ?? …`) so a
 // partial — or empty `{}` — strings object still resolves every label to a
 // default, matching the pattern PageActions and Search use.
@@ -20,61 +28,58 @@ const buttonClass =
 
 <section
   aria-label={f.question}
-  class="mx-auto mt-12 flex max-w-content items-center justify-between gap-4 border-border border-t pt-6"
+  class="mx-auto mt-12 max-w-content border-border border-t pt-6"
   data-blume-page-feedback
+  hidden={waitsForConsent}
 >
-  <p class="text-muted-foreground text-sm">{f.question}</p>
-  <div class="flex items-center gap-2" data-feedback-actions>
-    <button class={buttonClass} data-feedback-value="yes" type="button">
-      <Icon name="thumbs-up" size={16} />
-      {f.yes}
-    </button>
-    <button class={buttonClass} data-feedback-value="no" type="button">
-      <Icon name="thumbs-down" size={16} />
-      {f.no}
-    </button>
+  <div class="flex items-center justify-between gap-4">
+    <p class="text-muted-foreground text-sm">{f.question}</p>
+    <div class="flex items-center gap-2" data-feedback-actions>
+      <button class={buttonClass} data-feedback-value="yes" type="button">
+        <Icon name="thumbs-up" size={16} />
+        {f.yes}
+      </button>
+      <button class={buttonClass} data-feedback-value="no" type="button">
+        <Icon name="thumbs-down" size={16} />
+        {f.no}
+      </button>
+    </div>
+    <p
+      class="hidden text-muted-foreground text-sm focus:outline-none"
+      data-feedback-thanks
+      role="status"
+      tabindex="-1"
+    >
+      {f.thanks}
+    </p>
   </div>
-  <p
-    class="hidden text-muted-foreground text-sm focus:outline-none"
-    data-feedback-thanks
-    role="status"
-    tabindex="-1"
-  >
-    {f.thanks}
-  </p>
+  {
+    comments && (
+      <form class="mt-4 grid gap-2" data-feedback-form hidden>
+        <label class="text-muted-foreground text-sm" for="blume-feedback-comment">
+          {f.comment}
+        </label>
+        <textarea
+          class="w-full resize-y rounded-blume border border-border bg-background px-3 py-2 text-foreground text-sm outline-none transition-colors focus:border-foreground"
+          id="blume-feedback-comment"
+          maxlength={COMMENT_MAX_LENGTH}
+          name="comment"
+          rows="3"
+        ></textarea>
+        <div>
+          <button class={buttonClass} type="submit">
+            {f.send}
+          </button>
+        </div>
+      </form>
+    )
+  }
 </section>
 
 <script>
-  import { track } from "./analytics-client.ts";
-
-  // Run on the initial load and again after every client-router swap, which
-  // rebuilds the rating widget from server-rendered markup — the handlers
-  // below always bind to the freshly swapped-in elements.
-  const initFeedback = () => {
-    const root = document.querySelector("[data-blume-page-feedback]");
-    if (!root) {
-      return;
-    }
-    const actions = root.querySelector("[data-feedback-actions]");
-    const thanks = root.querySelector("[data-feedback-thanks]");
-    for (const button of root.querySelectorAll("[data-feedback-value]")) {
-      button.addEventListener("click", () => {
-        track("feedback", {
-          helpful: button.getAttribute("data-feedback-value") ?? "",
-          path: location.pathname,
-          title: document.title,
-        });
-        actions?.classList.add("hidden");
-        thanks?.classList.remove("hidden");
-        // The clicked button just disappeared under focus; hand focus to the
-        // (live) thanks line so the reader isn't dropped at the top of the page.
-        if (thanks instanceof HTMLElement) {
-          thanks.focus();
-        }
-      });
-    }
-  };
+  import { initFeedback, syncFeedbackVisibility } from "./page-feedback.ts";
 
   initFeedback();
   document.addEventListener("astro:after-swap", initFeedback);
+  addEventListener("blume:consent", syncFeedbackVisibility);
 </script>

package/src/components/layout/PageLayout.astro

@@ -5,8 +5,8 @@ import { createIconSprite } from "../icon-sprite.ts";
 // 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
 // `<head>`, theme/banner pre-paint scripts, banner, and header, then a single
-// full-width `<slot />` for the body (plus an optional `footer` slot rendered
-// after `<main>`). Import it into a custom page and pull props from `blume:data`:
+// full-width `<slot />` for the body, then an optional `footer` slot, or the
+// site footer `footer` configures when the page fills no slot. Import it into a custom page and pull props from `blume:data`:
 //
 //   import PageLayout from "blume/components/layout/PageLayout.astro";
 //   import data from "blume:data";
@@ -40,11 +40,18 @@ import { buildStructuredData } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import Icon from "../Icon.astro";
 import { stripBase, withBase, withMountedBase } from "../islands/base-path.ts";
+import { routeSetFor } from "../../core/locale-links.ts";
+import {
+  browserLanguageTargets,
+  LOCALE_REDIRECT_SCRIPT,
+} from "./locale-redirect.ts";
 import { pageDirection, pageLocale } from "./page-locale.ts";
 import { searchLocaleFor } from "./search-locale.ts";
 import "blume:theme";
 import { ClientRouter } from "astro:transitions";
 import Analytics from "./Analytics.astro";
+import ConsentBanner from "./ConsentBanner.astro";
+import ConsentHead from "./ConsentHead.astro";
 import Banner from "./Banner.astro";
 import DiscoveryLinks from "./DiscoveryLinks.astro";
 import Favicon from "./Favicon.astro";
@@ -57,6 +64,9 @@ import {
 import Header from "./Header.astro";
 import { currentTabForRoute } from "./nav-utils.ts";
 import NavTabMenu from "./NavTabMenu.astro";
+import DrawerSwitchers from "./DrawerSwitchers.astro";
+import SiteFooter from "./SiteFooter.astro";
+import SiteMetatags from "./SiteMetatags.astro";
 import WebMcp from "./WebMcp.astro";
 
 interface Props {
@@ -195,6 +205,8 @@ const clientDataJson = clientData
   : null;
 
 const strings = ui ?? EN_UI;
+// The consent adapter (`consent`), site-wide: analytics waits for the reader.
+const consent = data.config.consent;
 // 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.
@@ -291,6 +303,25 @@ 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);
+
+// A visitor landing on the default language's home page goes to their
+// browser's language (`i18n.routeByBrowserLanguage`, see locale-redirect.ts).
+const localeTargets = browserLanguageTargets({
+  basePath: data.config.basePath,
+  i18n: data.config.i18n,
+  route,
+  routes: routeSetFor(data.routes),
+});
+const localeRedirect = localeTargets
+  ? JSON.stringify(
+      Object.fromEntries(
+        Object.entries(localeTargets).map(([code, path]) => [
+          code,
+          withMountedBase(path),
+        ])
+      )
+    )
+  : null;
 ---
 
 <!doctype html>
@@ -298,6 +329,16 @@ createIconSprite(Astro.locals);
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {
+      localeRedirect && (
+        <script
+          data-default={data.config.i18n?.defaultLocale}
+          data-targets={localeRedirect}
+          is:inline
+          set:html={LOCALE_REDIRECT_SCRIPT}
+        />
+      )
+    }
     {/* Client-side navigation, matching RootLayout: same-origin link clicks
         swap the DOM in place instead of tearing the document down, so no
         browser paints a blank frame between pages. */}
@@ -363,6 +404,7 @@ createIconSprite(Astro.locals);
     {description && <meta content={description} name="twitter:description" />}
     {xSite && <meta content={xSite} name="twitter:site" />}
     {xCreator && <meta content={xCreator} name="twitter:creator" />}
+    <SiteMetatags tags={data.config.metatags} />
     {/* Agent discovery on every page, so a custom page built on PageLayout is
         covered without passing a prop, the same way the docs pages are. */}
     <DiscoveryLinks discovery={discovery} markdownMirror={markdownMirror} />
@@ -381,6 +423,7 @@ createIconSprite(Astro.locals);
       )
     }
     <script data-mode={themeMode} is:inline set:html={THEME_INIT_SCRIPT} />
+    {consent && <ConsentHead consent={consent} />}
     <Analytics analytics={analytics} />
   </head>
   <body class="bg-background font-sans text-foreground antialiased">
@@ -409,8 +452,27 @@ createIconSprite(Astro.locals);
       transparent={transparentHeader}
     />
     <main id="blume-content"><slot /></main>
-    <slot name="footer" />
+    {
+      Astro.slots.has("footer") ? (
+        <slot name="footer" />
+      ) : (
+        <SiteFooter
+          footer={data.config.footer}
+          locale={locale}
+          navigation={navigation}
+          ui={strings}
+        />
+      )
+    }
     <WebMcp />
+    {
+      consent?.kind === "native" && (
+        <ConsentBanner
+          policy={consent.options.policy}
+          strings={strings.consent}
+        />
+      )
+    }
     {
       // Mobile nav for chrome-only pages: the header's inline tab bar is hidden
       // below `lg` and there's no sidebar drawer, so surface the tabs in a
@@ -425,6 +487,12 @@ createIconSprite(Astro.locals);
             data-blume-nav-drawer
             id="blume-nav-drawer"
           >
+            <DrawerSwitchers
+              localeSwitch={localeSwitch}
+              route={route}
+              selectors={navigation.selectors}
+              switcherStrings={strings.languageSwitcher}
+            />
             <nav aria-label={navStrings.sections}>
               <ul class="m-0 list-none p-0">
                 {navigation.tabs.map((tab) => (

package/src/components/layout/ReferenceLayout.astro

@@ -4,6 +4,7 @@ import { createIconSprite } from "../icon-sprite.ts";
 import "blume:theme";
 import data from "blume:data";
 import type {
+  BlumeBanner,
   BlumeDataConfig,
   BlumeFavicon,
   DiscoveryHeadLinks,
@@ -14,6 +15,8 @@ import { NEW_TAB_HINT_ID } from "../../core/new-tab.ts";
 import type { FontHead } from "../../theme/fonts.ts";
 import type { Navigation } from "../../core/types.ts";
 import Analytics from "./Analytics.astro";
+import ConsentBanner from "./ConsentBanner.astro";
+import ConsentHead from "./ConsentHead.astro";
 import WebMcp from "./WebMcp.astro";
 import Banner from "./Banner.astro";
 import DiscoveryLinks from "./DiscoveryLinks.astro";
@@ -27,6 +30,7 @@ import {
 import Header from "./Header.astro";
 import { pageDirection, pageLocale } from "./page-locale.ts";
 import { searchLocaleFor } from "./search-locale.ts";
+import SiteMetatags from "./SiteMetatags.astro";
 
 // A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
 // on top, then a full-height region the reference mounts into. Unlike RootLayout
@@ -50,12 +54,7 @@ interface Props {
   } | null;
   favicon?: BlumeFavicon | null;
   appleIcon?: BlumeFavicon | null;
-  banner?: {
-    content: string;
-    link?: { text: string; href: string };
-    dismissible: boolean;
-    key: string;
-  } | null;
+  banner?: BlumeBanner | null;
   analytics?: BlumeDataConfig["analytics"] | null;
   navigation: Navigation;
   route: string;
@@ -110,6 +109,8 @@ const locale = pageLocale(data.config.i18n, localeProp, Astro.currentLocale);
 const dir = dirProp ?? pageDirection(data.config.i18n, locale);
 
 const strings = ui ?? EN_UI;
+// The consent adapter (`consent`), site-wide: analytics waits for the reader.
+const consent = data.config.consent;
 const navStrings = { ...EN_UI.nav, ...strings.nav };
 // Scope search to the reference page's language on a multi-locale site.
 const searchLocale = searchLocaleFor(data.config.i18n, locale);
@@ -128,6 +129,7 @@ createIconSprite(Astro.locals);
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     {noindex && <meta name="robots" content="noindex" />}
     <title>{pageTitle}</title>
+    <SiteMetatags tags={data.config.metatags} />
     <Favicon favicon={favicon} appleIcon={appleIcon} />
     <Fonts cssVars={fontCssVars ?? []} />
     <DiscoveryLinks discovery={discovery} />
@@ -137,6 +139,7 @@ createIconSprite(Astro.locals);
       )
     }
     <script data-mode={themeMode} is:inline set:html={THEME_INIT_SCRIPT} />
+    {consent && <ConsentHead consent={consent} />}
     <Analytics analytics={analytics} />
   </head>
   <body class="bg-background font-sans text-foreground antialiased">
@@ -170,6 +173,14 @@ createIconSprite(Astro.locals);
       <script is:inline set:html={SCALAR_THEME_INIT_SCRIPT} />
     </div>
     <WebMcp />
+    {
+      consent?.kind === "native" && (
+        <ConsentBanner
+          policy={consent.options.policy}
+          strings={strings.consent}
+        />
+      )
+    }
   <IconSprite />
   </body>
 </html>

package/src/components/layout/RelatedPages.astro

@@ -0,0 +1,42 @@
+---
+import type { RelatedLink } from "../../core/related.ts";
+import Card from "../content/Card.astro";
+import CardGroup from "../content/CardGroup.astro";
+
+/**
+ * A page's `related` links, as cards at its foot: each linked page's title
+ * and description, or a URL's host for a link off the site (see
+ * `core/related.ts`).
+ */
+interface Props {
+  links: RelatedLink[];
+  /** The heading, from the `page.related` UI string. */
+  title: string;
+}
+
+const { links, title } = Astro.props;
+---
+
+{
+  links.length > 0 && (
+    <nav
+      aria-labelledby="blume-related-pages"
+      class="mx-auto mt-10 max-w-content"
+      data-blume-related
+    >
+      <h2
+        class="font-medium text-foreground text-sm"
+        id="blume-related-pages"
+      >
+        {title}
+      </h2>
+      <CardGroup>
+        {links.map((link) => (
+          <Card href={link.href} title={link.title}>
+            {link.description}
+          </Card>
+        ))}
+      </CardGroup>
+    </nav>
+  )
+}