blume 2.0.3 → 2.1.0

package/src/components/layout/Search.astro

@@ -93,23 +93,19 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   data-version={version ?? undefined}
   data-versioned={version === null ? undefined : ""}
 >
-  {/* The label and shortcut hint wait until `lg`: below it the hamburger and
-      inline tab bar share the header row, and a full-width search field would
-      press into the language switcher. */}
+  {/* An icon button like the theme toggle beside it, named with its shortcut
+      by the header's tooltip. The chord reads left to right in every locale
+      ("⌘K", never "K⌘"), and the script swaps in Ctrl off Apple devices. */}
   <button
+    aria-keyshortcuts="Meta+K Control+K"
     aria-label={s.button}
-    class="inline-flex h-9 cursor-pointer items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground lg:min-w-40"
+    class="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"
     data-blume-search-open
+    data-blume-tooltip={`${s.button} (\u2066⌘K\u2069)`}
+    data-label={s.button}
     type="button"
   >
-    <Icon name="search" size={16} />
-    <span class="flex-1 text-start max-lg:hidden">{s.button}</span>
-    {/* A key chord reads left to right in every locale ("⌘K", never "K⌘"). */}
-    <kbd
-      class="font-mono text-[0.7rem] max-lg:hidden"
-      data-blume-search-kbd
-      dir="ltr">⌘K</kbd
-    >
+    <Icon name="search" size={18} />
   </button>
 
   <dialog
@@ -242,6 +238,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
     import { mountBase } from "../islands/base-path.ts";
     import { escape as escapeHtml } from "html-escaper";
 
+    import { track } from "./analytics-client.ts";
+    import { createSearchTracker } from "./search/analytics.ts";
     import { highlight, matchSnippet } from "./search/types.ts";
     import type { SearchFn, SearchHit } from "./search/types.ts";
 
@@ -326,6 +324,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       message!: HTMLElement;
       preview!: HTMLElement;
       searchFn: SearchFn | null = null;
+      /** Records settled queries and picked results (search/analytics.ts). */
+      tracker = createSearchTracker(track);
       loaded = false;
       loadFailed = false;
       /** First-open client/index load still in flight. */
@@ -470,11 +470,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         }
 
         // The handlers accept both ⌘ and Ctrl chords; show the right modifier
-        // per platform on the button hint and the footer's preview hint.
+        // per platform in the button's tooltip and the footer's preview hint.
         const isApple = /mac|iphone|ipad|ipod/iu.test(navigator.platform);
-        const hint = this.querySelector("[data-blume-search-kbd]");
-        if (hint) {
-          hint.textContent = isApple ? "⌘K" : "Ctrl K";
+        const trigger = this.querySelector<HTMLElement>(
+          "[data-blume-search-open]"
+        );
+        if (trigger && !isApple) {
+          trigger.dataset.blumeTooltip = `${trigger.dataset.label ?? ""} (\u2066Ctrl K\u2069)`;
         }
         const previewHint = this.querySelector(
           "[data-blume-search-preview-kbd]"
@@ -494,7 +496,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.dialog.addEventListener("keydown", (event) =>
           this.onKeydown(event)
         );
-        this.dialog.addEventListener("close", () => this.unlockPageScroll());
+        this.dialog.addEventListener("close", () => {
+          this.unlockPageScroll();
+          this.tracker.closed();
+        });
         this.dialog.addEventListener("click", (event) => {
           if (event.target === this.dialog) {
             this.dialog.close();
@@ -678,6 +683,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           this.setMessage(this.noResultsMsg);
         }
 
+        this.tracker.settled(query, result.hits.length);
         this.finishRender();
       }
 
@@ -901,6 +907,14 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
             new CustomEvent("blume:open-assistant", { detail: { query } })
           );
         } else if (item.url) {
+          if (item.hit) {
+            const hits = this.selectables.filter((row) => row.hit);
+            this.tracker.selected(
+              this.input.value.trim(),
+              hits.indexOf(item) + 1,
+              item.url
+            );
+          }
           // Close first so the dialog isn't left open over the transition;
           // navigate() rides the client router (and falls back to a normal
           // full load on pages without it).

package/src/components/layout/SiteFooter.astro

@@ -0,0 +1,124 @@
+---
+// The site footer, below the content on every page: one row, as tall as the
+// header, with `footer.links` on one side and the social profile icons on the
+// other. The site's repository (`github`, unless `navigation.repo` hides it)
+// is the first icon; the footer is the only place it's linked. With `consent` configured the links end with the
+// Cookie settings link, which reopens the reader's consent choices. Renders
+// nothing when there's none of these; a `components.ts` `Footer` replaces it.
+import data from "blume:data";
+
+import type { BlumeDataConfig } from "../../core/data.ts";
+import type { Navigation } from "../../core/types.ts";
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import { routeSetFor } from "../../core/locale-links.ts";
+import { newTabAttrs } from "../../core/new-tab.ts";
+import Icon from "../Icon.astro";
+import { withBase } from "../islands/base-path.ts";
+import { footerLinks } from "./footer-links.ts";
+import { footerSocialLinks } from "./footer-socials.ts";
+
+interface Props {
+  footer?: BlumeDataConfig["footer"];
+  /**
+   * Active locale of the page: labels written as per-locale maps show its
+   * entry, and internal links move into it (see `footer-links.ts`).
+   */
+  locale?: string;
+  /** The page's navigation: its `repoUrl` is the repository link. */
+  navigation?: Navigation;
+  /** Localized UI strings; the Cookie settings label comes from `consent`. */
+  ui?: UIStrings;
+}
+
+const { footer, locale, navigation, ui } = Astro.props;
+// `github`, as `navigation.repo` leaves it: hidden, or pointed elsewhere.
+const repoUrl = navigation?.repoUrl;
+const socials = footerSocialLinks(
+  footer?.socials ?? {},
+  repoUrl
+    ? { href: repoUrl, label: { ...EN_UI.nav, ...ui?.nav }.githubRepository }
+    : null
+);
+const links = footerLinks(footer?.links ?? [], {
+  basePath: data.config.basePath,
+  i18n: data.config.i18n,
+  locale,
+  routes: routeSetFor(data.routes),
+});
+const consentSettings = data.config.consent
+  ? { ...EN_UI.consent, ...ui?.consent }.settings
+  : null;
+const linkClass =
+  "text-muted-foreground transition-colors hover:text-foreground focus-visible:text-foreground";
+// Round icon buttons, like the header's.
+const iconButton =
+  "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 focus-visible:text-foreground";
+const hasLinks = links.length > 0 || consentSettings !== null;
+---
+
+{
+  (hasLinks || socials.length > 0) && (
+    <footer class="border-border border-t px-4 md:px-6" data-blume-footer>
+      <div class="flex min-h-16 flex-wrap items-center justify-between gap-x-6 gap-y-3 py-3">
+        {hasLinks && (
+          <ul class="flex flex-wrap items-center gap-x-5 gap-y-2 text-sm">
+            {links.map((link) => (
+              <li>
+                <a
+                  class={linkClass}
+                  href={withBase(link.href)}
+                  {...newTabAttrs(link.href)}
+                >
+                  {link.label}
+                </a>
+              </li>
+            ))}
+            {consentSettings && (
+              <li>
+                <button
+                  class:list={[linkClass, "cursor-pointer"]}
+                  data-blume-consent-open
+                  type="button"
+                >
+                  {consentSettings}
+                </button>
+              </li>
+            )}
+          </ul>
+        )}
+        {/* Pulled out by the buttons' padding, so the glyphs line up with the
+            footer's edge, and pushed to the far side even with no links. */}
+        {socials.length > 0 && (
+          <ul class="-me-[9px] -my-[9px] ms-auto flex flex-wrap items-center gap-1">
+            {socials.map((social) => (
+              <li>
+                <a
+                  aria-label={social.label}
+                  class={iconButton}
+                  href={withBase(social.href)}
+                  title={social.label}
+                  {...newTabAttrs(social.href)}
+                >
+                  {social.path ? (
+                    <svg
+                      aria-hidden="true"
+                      fill="currentColor"
+                      height="18"
+                      viewBox="0 0 24 24"
+                      width="18"
+                    >
+                      <path d={social.path} />
+                    </svg>
+                  ) : (
+                    <Icon name={social.icon} size={18} />
+                  )}
+                </a>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </footer>
+  )
+}

package/src/components/layout/SiteMetatags.astro

@@ -0,0 +1,16 @@
+---
+import { metatagAttributes } from "../../seo/metatags.ts";
+
+/**
+ * The site's own `seo.metatags` in a page's head, after the tags Blume
+ * writes (see seo/metatags.ts). Every layout renders it, so a verification
+ * token or `theme-color` reaches every page.
+ */
+interface Props {
+  tags: Record<string, string> | null | undefined;
+}
+
+const { tags } = Astro.props;
+---
+
+{metatagAttributes(tags).map((attributes) => <meta {...attributes} />)}

package/src/components/layout/consent/native.ts

@@ -0,0 +1,79 @@
+/**
+ * `native()`'s browser module: Blume's own banner. The generated
+ * `blume:consent-client` brings it in when `native()` is the configured
+ * consent adapter (see `consent/clients.ts`). It reports the reader's stored
+ * answer, shows the banner (`ConsentBanner.astro`) until they pick one, stores
+ * the pick, and makes the footer's Cookie settings link bring the banner back.
+ */
+import type { NativeOptions } from "../../../consent/native.ts";
+import type { BlumeConsent, ConsentClientStart } from "./types.ts";
+
+/** Where `native()` keeps the reader's answer. */
+export const CONSENT_STORAGE_KEY = "blume-consent";
+
+const BANNER = "[data-blume-consent-banner]";
+const CHOICE = "[data-blume-consent-choice]";
+
+/** The stored answer, or `null` before one (or without storage). */
+export const storedChoice = (): boolean | null => {
+  try {
+    const value = localStorage.getItem(CONSENT_STORAGE_KEY);
+    if (value === "granted" || value === "denied") {
+      return value === "granted";
+    }
+  } catch {
+    // Storage blocked: ask again on every page rather than fail.
+  }
+  return null;
+};
+
+const storeChoice = (granted: boolean): void => {
+  try {
+    localStorage.setItem(CONSENT_STORAGE_KEY, granted ? "granted" : "denied");
+  } catch {
+    // Storage blocked: the answer holds for this page load only.
+  }
+};
+
+const banner = (): HTMLElement | null =>
+  document.querySelector<HTMLElement>(BANNER);
+
+/**
+ * Wire this page's banner: show it while the reader hasn't answered, and
+ * store and report an answer. Runs again after every client-router swap,
+ * which brings a fresh, hidden banner.
+ */
+const syncBanner = (consent: BlumeConsent): void => {
+  const element = banner();
+  if (!element) {
+    return;
+  }
+  element.hidden = storedChoice() !== null;
+  for (const button of element.querySelectorAll<HTMLElement>(CHOICE)) {
+    button.addEventListener("click", () => {
+      const granted = button.dataset.blumeConsentChoice === "accept";
+      storeChoice(granted);
+      element.hidden = true;
+      consent.set({ analytics: granted });
+    });
+  }
+};
+
+/**
+ * Report the stored answer, and wire the banner on this page and every page
+ * the client router swaps in. The options (the banner's privacy link) are
+ * rendered into the banner itself, so there's nothing to read here.
+ */
+export const start: ConsentClientStart<NativeOptions> = (consent) => {
+  consent.open = () => {
+    const element = banner();
+    if (element) {
+      element.hidden = false;
+    }
+  };
+  syncBanner(consent);
+  consent.set({ analytics: storedChoice() === true });
+  document.addEventListener("astro:after-swap", () => {
+    syncBanner(consent);
+  });
+};

package/src/components/layout/consent/types.ts

@@ -0,0 +1,37 @@
+/**
+ * The consent contract every adapter talks to, shared by the consent runtime
+ * (`consent/client.ts`) and each adapter's browser module (like `native.ts`
+ * here). `window.blumeConsent` is created by the inline init script
+ * (`consent/init.ts`) before any adapter loads.
+ */
+
+/** What a consent adapter reports: whether the reader allows analytics. */
+export interface ConsentState {
+  analytics: boolean;
+}
+
+/** `window.blumeConsent`, created by the inline init script. */
+export interface BlumeConsent {
+  /** `null` until an adapter reports, then the reader's choice. */
+  analytics: boolean | null;
+  /** The configured adapter's kind. */
+  kind: string;
+  /** Reopen the reader's consent choices; set by the adapter. */
+  open?: () => void;
+  /** Report the reader's choice; fires `blume:consent` when it changes. */
+  set: (state: ConsentState) => void;
+}
+
+/**
+ * A consent adapter's browser module entry point, which the generated
+ * `blume:consent-client` calls once per real page load, after the runtime is
+ * listening. It gets the consent state and the adapter's options from
+ * `blume.config.ts`, and must report the reader's answer with
+ * `consent.set({ analytics })` (on load, and again whenever it changes) and
+ * set `consent.open` to reopen the adapter's preferences. Anything it does per
+ * page, it redoes on `astro:after-swap`.
+ */
+export type ConsentClientStart<Options> = (
+  consent: BlumeConsent,
+  options: Options
+) => void;

package/src/components/layout/footer-links.ts

@@ -0,0 +1,53 @@
+import type { LocaleRouting } from "../../core/i18n.ts";
+import { localizeHref } from "../../core/locale-links.ts";
+import type { RouteSet } from "../../core/locale-links.ts";
+import { resolveLocalizable } from "../../core/localizable.ts";
+import type { ResolvedConfig } from "../../core/schema.ts";
+
+/** The configured `footer.links`. */
+type FooterLinks = NonNullable<ResolvedConfig["footer"]>["links"];
+
+/** A footer link, ready to render. */
+export interface FooterLinkItem {
+  href: string;
+  label: string;
+}
+
+/** What resolving needs from the site and the page. */
+export interface FooterContext {
+  basePath: string;
+  /** The site's locales, when it has more than one. */
+  i18n: LocaleRouting | null;
+  /** The locale of the page being rendered. */
+  locale?: string;
+  routes: RouteSet;
+}
+
+/**
+ * The footer's links in the page's locale: a label written as a per-locale
+ * map shows that locale's entry (see `core/localizable.ts`), and an internal
+ * link moves into the locale when it serves that page, the way content and
+ * header links do, so a reader on `/fr/…` stays in French.
+ */
+export const footerLinks = (
+  links: FooterLinks,
+  context: FooterContext
+): FooterLinkItem[] => {
+  const { i18n, locale } = context;
+  const defaultLocale = i18n?.defaultLocale;
+  const localize = (href: string): string =>
+    i18n && locale
+      ? localizeHref(href, {
+          basePath: context.basePath,
+          // The layout mounts the deployment base afterwards.
+          deployBase: "",
+          i18n,
+          locale,
+          routes: context.routes,
+        })
+      : href;
+  return links.map((link) => ({
+    href: localize(link.href),
+    label: resolveLocalizable(link.label, locale, defaultLocale),
+  }));
+};

package/src/components/layout/footer-socials.ts

@@ -0,0 +1,87 @@
+import {
+  siBluesky,
+  siDiscord,
+  siFacebook,
+  siGithub,
+  siInstagram,
+  siMedium,
+  siReddit,
+  siTelegram,
+  siThreads,
+  siX,
+  siYcombinator,
+  siYoutube,
+} from "simple-icons";
+
+import type { FooterSocial } from "../../core/footer.ts";
+
+/**
+ * How a `footer.socials` platform is shown: its name, for the link's label,
+ * and either a filled brand mark or a Lucide icon.
+ */
+export interface SocialIcon {
+  label: string;
+  /** A Lucide icon name, where simple-icons carries no mark for the brand. */
+  icon?: string;
+  /** A simple-icons path on a 24×24 viewBox, drawn filled. */
+  path?: string;
+}
+
+/**
+ * Each platform's icon. Brand marks come from simple-icons; LinkedIn and
+ * Slack had theirs removed there at the brands' request, so they take
+ * Lucide's glyphs, as do the generic website and podcast links.
+ */
+export const SOCIAL_ICONS: Record<FooterSocial, SocialIcon> = {
+  bluesky: { label: "Bluesky", path: siBluesky.path },
+  discord: { label: "Discord", path: siDiscord.path },
+  facebook: { label: "Facebook", path: siFacebook.path },
+  github: { label: "GitHub", path: siGithub.path },
+  "hacker-news": { label: "Hacker News", path: siYcombinator.path },
+  instagram: { label: "Instagram", path: siInstagram.path },
+  linkedin: { icon: "linkedin", label: "LinkedIn" },
+  medium: { label: "Medium", path: siMedium.path },
+  podcast: { icon: "podcast", label: "Podcast" },
+  reddit: { label: "Reddit", path: siReddit.path },
+  slack: { icon: "slack", label: "Slack" },
+  telegram: { label: "Telegram", path: siTelegram.path },
+  threads: { label: "Threads", path: siThreads.path },
+  website: { icon: "globe", label: "Website" },
+  x: { label: "X", path: siX.path },
+  youtube: { label: "YouTube", path: siYoutube.path },
+};
+
+/** A configured social link, with the icon it's shown by. */
+export interface FooterSocialLink extends SocialIcon {
+  href: string;
+}
+
+const isFooterSocial = (key: string): key is FooterSocial =>
+  Object.hasOwn(SOCIAL_ICONS, key);
+
+/** The site's repository, as the footer links it. */
+export interface FooterRepoLink {
+  href: string;
+  /** Its accessible name, in the page's language ("GitHub repository"). */
+  label: string;
+}
+
+/**
+ * The footer's social links, in the order written, each with its icon. The
+ * footer is the only place the site links its repository, so `repo` (from
+ * `github` in the config) leads as the GitHub link, unless `socials.github`
+ * names one itself.
+ */
+export const footerSocialLinks = (
+  socials: Partial<Record<FooterSocial, string>>,
+  repo?: FooterRepoLink | null
+): FooterSocialLink[] => {
+  const links = Object.entries(socials).flatMap(([platform, href]) =>
+    isFooterSocial(platform) && href
+      ? [{ ...SOCIAL_ICONS[platform], href }]
+      : []
+  );
+  return repo && !socials.github
+    ? [{ ...SOCIAL_ICONS.github, ...repo }, ...links]
+    : links;
+};

package/src/components/layout/locale-redirect.ts

@@ -0,0 +1,107 @@
+import { withBasePath } from "../../core/base-path.ts";
+import type { BlumeDataI18n } from "../../core/data.ts";
+import { localizeRoute } from "../../core/i18n.ts";
+import type { RouteSet } from "../../core/locale-links.ts";
+
+/**
+ * Routing by browser language (`i18n.routeByBrowserLanguage`): a visitor who
+ * lands on the default language's home page from outside the site goes to
+ * the home page in the first language their browser prefers that the site
+ * has, until they pick a language with the switcher. It runs in the browser,
+ * from the home page's head, so it works on a static host, and the redirect
+ * happens before anything paints.
+ */
+
+/**
+ * Where a language picked with the switcher is remembered. The inline script
+ * below spells it out.
+ */
+export const LOCALE_STORAGE_KEY = "blume-locale";
+
+/** What the home page's routing needs from the site. */
+export interface LocaleRedirectContext {
+  basePath: string;
+  i18n: BlumeDataI18n | null;
+  /** The page being rendered. */
+  route: string;
+  routes: RouteSet;
+}
+
+/**
+ * The other languages' home pages a visitor could be sent to from `route`,
+ * by locale code, or `null` when this page doesn't route: the option is off,
+ * this isn't the default language's home, or no other home is served.
+ */
+export const browserLanguageTargets = (
+  context: LocaleRedirectContext
+): Record<string, string> | null => {
+  const { i18n } = context;
+  if (!i18n?.routeByBrowserLanguage) {
+    return null;
+  }
+  const home = (code: string): string =>
+    withBasePath(context.basePath, localizeRoute("/", code, i18n));
+  if (context.route !== home(i18n.defaultLocale)) {
+    return null;
+  }
+  const targets = i18n.locales
+    .filter(({ code }) => code !== i18n.defaultLocale)
+    .map(({ code }) => [code, home(code)] as const)
+    .filter(([, path]) => context.routes.has(path));
+  return targets.length > 0 ? Object.fromEntries(targets) : null;
+};
+
+/**
+ * The inline script, given the default locale (`data-default`) and the other
+ * homes (`data-targets`). For each language the browser prefers, in order, it
+ * matches a locale by exact code, then by base language (`fr-CA` finds `fr`,
+ * `pt` finds `pt-br`): the default language stays put, another one's home is
+ * where the visitor goes. A visitor who picked a language, arrived from
+ * another page of the site, or whose storage can't be read stays too.
+ */
+export const LOCALE_REDIRECT_SCRIPT = `(()=>{const s=document.currentScript;if(!s)return;try{if(localStorage.getItem("blume-locale")!==null)return}catch{return}if(document.referrer.startsWith(location.origin+"/"))return;let t;try{t=JSON.parse(s.dataset.targets||"")}catch{return}const d=s.dataset.default||"";const c=[d,...Object.keys(t)];const low=(v)=>v.toLowerCase();const base=(v)=>low(v).split("-")[0];for(const l of navigator.languages||[]){const m=c.find((v)=>low(v)===low(l))||c.find((v)=>low(v)===base(l))||c.find((v)=>base(v)===base(l));if(m===d)return;if(m){location.replace(t[m]+location.search+location.hash);return}}})();`;
+
+/** A click target that can look up its ancestors: an element. */
+interface ClosestTarget {
+  closest: (selector: string) => {
+    getAttribute: (name: string) => string | null;
+  } | null;
+}
+
+/** A click, as the listener reads it. */
+interface Click {
+  target: EventTarget | ClosestTarget | null;
+}
+
+/** What {@link rememberLocaleChoice} listens on: the document. */
+export interface ChoiceTarget {
+  addEventListener: (type: "click", listener: (event: Click) => void) => void;
+}
+
+const hasClosest = (target: Click["target"]): target is ClosestTarget =>
+  target !== null && "closest" in target;
+
+/** The code of the switcher link a click landed on, if any. */
+const chosenCode = (target: Click["target"]): string | null | undefined =>
+  hasClosest(target)
+    ? target.closest("a[data-blume-locale-choice]")?.getAttribute("hreflang")
+    : null;
+
+/**
+ * Remember a language picked with the switcher, so routing by browser
+ * language stops sending the reader elsewhere. One listener on the document
+ * covers every switcher, on every page the client router swaps in.
+ */
+export const rememberLocaleChoice = (target: ChoiceTarget): void => {
+  target.addEventListener("click", (event) => {
+    const code = chosenCode(event.target);
+    if (!code) {
+      return;
+    }
+    try {
+      localStorage.setItem(LOCALE_STORAGE_KEY, code);
+    } catch {
+      // Storage can be off; routing then stays off too (see the script).
+    }
+  });
+};