blume 2.0.3 → 2.1.0

package/src/components/islands/support-link.ts

@@ -0,0 +1,68 @@
+/**
+ * The assistant's handoff to your support channel (`ai.assistant.support`).
+ * A `mailto:` link starts an email with the conversation as its body, so the
+ * reader doesn't have to repeat themselves; any other link gets the
+ * conversation's `thread` id in its query, the same id the assistant's
+ * analytics events carry, so a support team can find the conversation.
+ */
+
+/** One turn of the conversation. */
+export interface SupportMessage {
+  content: string;
+  role: "assistant" | "user";
+}
+
+/** What the link is built from. */
+export interface SupportContext {
+  /** The label the transcript gives the assistant's turns. */
+  ai: string;
+  messages: readonly SupportMessage[];
+  /** The email's subject. */
+  subject: string;
+  thread: string;
+  /** The label the transcript gives the reader's turns. */
+  you: string;
+}
+
+/**
+ * How much conversation an email carries: mail clients cut long `mailto:`
+ * links, so a long conversation is trimmed from the start, keeping the
+ * latest turns.
+ */
+export const MAX_TRANSCRIPT_CHARS = 1500;
+
+const transcriptOf = (context: SupportContext): string => {
+  const full = context.messages
+    .map(
+      (message) =>
+        `${message.role === "user" ? context.you : context.ai}: ${message.content}`
+    )
+    .join("\n\n");
+  return full.length > MAX_TRANSCRIPT_CHARS
+    ? `…${full.slice(-MAX_TRANSCRIPT_CHARS)}`
+    : full;
+};
+
+/** The support link for this conversation. */
+export const supportHref = (
+  support: string,
+  context: SupportContext
+): string => {
+  if (support.startsWith("mailto:")) {
+    // `mailto:` wants %20, not the `+` URLSearchParams writes for a space.
+    const body = `${transcriptOf(context)}\n\n(${context.thread})`;
+    const separator = support.includes("?") ? "&" : "?";
+    return `${support}${separator}subject=${encodeURIComponent(context.subject)}&body=${encodeURIComponent(body)}`;
+  }
+  const url = new URL(support, "https://blume.invalid");
+  url.searchParams.set("thread", context.thread);
+  return url.origin === "https://blume.invalid"
+    ? `${url.pathname}${url.search}${url.hash}`
+    : url.href;
+};
+
+/** A fresh conversation id: 16 hex characters. */
+export const newThreadId = (): string =>
+  Array.from(crypto.getRandomValues(new Uint8Array(8)), (byte) =>
+    byte.toString(16).padStart(2, "0")
+  ).join("");

package/src/components/layout/Analytics.astro

@@ -1,5 +1,6 @@
 ---
 import VercelAnalytics from "@vercel/analytics/astro";
+import data from "blume:data";
 
 import { analyticsHead } from "../../analytics/head.ts";
 import type { BlumeDataConfig } from "../../core/data.ts";
@@ -10,12 +11,20 @@ import type { BlumeDataConfig } from "../../core/data.ts";
 // component for `vercel()`, one <script> for every other adapter. Loads ONLY
 // in production builds so `blume dev` stays clean and local traffic never
 // reaches your analytics.
+//
+// With `consent` configured, every tag is held as inert `text/plain` until
+// the reader allows analytics, when the consent runtime runs it
+// (`consent/client.ts`); Vercel's component sends nothing until then instead
+// (`consent/init.ts`).
 interface Props {
   analytics?: BlumeDataConfig["analytics"] | null;
 }
 
 const { analytics } = Astro.props;
 const nodes = analyticsHead(import.meta.env.PROD ? (analytics ?? []) : []);
+const held = data.config.consent
+  ? { "data-blume-consent": "analytics", type: "text/plain" }
+  : {};
 ---
 
 {
@@ -24,9 +33,9 @@ const nodes = analyticsHead(import.meta.env.PROD ? (analytics ?? []) : []);
       return <VercelAnalytics {...node.props} />;
     }
     return node.content === null ? (
-      <script is:inline {...node.attributes} />
+      <script is:inline {...node.attributes} {...held} />
     ) : (
-      <script is:inline set:html={node.content} {...node.attributes} />
+      <script is:inline set:html={node.content} {...node.attributes} {...held} />
     );
   })
 }

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.
 ---