blume 2.0.2 → 2.1.0

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).
+    }
+  });
+};

package/src/components/layout/nav-utils.ts

@@ -270,6 +270,89 @@ export const getPagination = (flat: FlatPage[], route: string) => {
   };
 };
 
+/** A group node in the sidebar tree. */
+export type NavGroup = Extract<NavNode, { kind: "group" }>;
+
+/**
+ * The group whose own page `route` is, when that page lists the group's
+ * pages: its `directory` (inherited when the group sets none) is `card` or
+ * `accordion`. `null` on every other page.
+ */
+export const directoryGroupForRoute = (
+  nodes: NavNode[],
+  route: string
+): NavGroup | null => {
+  for (const node of nodes) {
+    if (node.kind !== "group") {
+      continue;
+    }
+    if (
+      node.route === route &&
+      (node.directory === "card" || node.directory === "accordion")
+    ) {
+      return node;
+    }
+    const nested = directoryGroupForRoute(node.children, route);
+    if (nested) {
+      return nested;
+    }
+  }
+  return null;
+};
+
+/** One entry in a group page's directory: a page, or a subgroup and its pages. */
+export interface DirectoryEntry {
+  description?: string;
+  /** The page, or the subgroup's own page (its first page when it has none). */
+  href: string;
+  icon?: string;
+  label: string;
+  /** A subgroup's pages in sidebar order, its own page first; absent for a page. */
+  pages?: FlatPage[];
+}
+
+/**
+ * What a group's page lists: the group's pages and subgroups, in sidebar
+ * order, without the page itself or external links. A subgroup is described
+ * by its own page, and one with no page to link to is left out.
+ */
+export const directoryEntries = (group: NavGroup): DirectoryEntry[] =>
+  group.children.flatMap((child): DirectoryEntry[] => {
+    if (child.kind === "page") {
+      return child.pageId && child.route !== group.route
+        ? [
+            {
+              description: child.description,
+              href: child.route,
+              icon: child.icon,
+              label: child.label,
+            },
+          ]
+        : [];
+    }
+    const listed = flattenPages(child.children);
+    const pages =
+      child.route && !listed.some((page) => page.route === child.route)
+        ? [{ label: child.label, route: child.route }, ...listed]
+        : listed;
+    const [first] = pages;
+    if (!first) {
+      return [];
+    }
+    const own = child.children.find(
+      (node) => node.kind === "page" && node.route === child.route
+    );
+    return [
+      {
+        description: own?.kind === "page" ? own.description : undefined,
+        href: child.route ?? first.route,
+        icon: child.icon,
+        label: child.label,
+        pages,
+      },
+    ];
+  });
+
 /**
  * A stable id for every group in a sidebar — `g<n>` by pre-order position in
  * the full tree. The layout hands `NavTree` a scoped view of that tree (a

package/src/components/layout/page-feedback.ts

@@ -0,0 +1,96 @@
+import { track } from "./analytics-client.ts";
+/**
+ * The "Was this page helpful?" rating (`PageFeedback.astro`). A rating is
+ * sent as a `feedback` analytics event, the buttons give way to a thank-you,
+ * and, with `feedback.comments` on, a box below asks the reader to say more.
+ * A comment they send goes out as a `feedback_comment` event with the same
+ * rating, path, and title, so the two line up in a dashboard.
+ *
+ * Both go through analytics, so under a consent layer (`consent`) the widget
+ * renders hidden and only shows once the reader allows analytics: from
+ * anyone else, an answer would go nowhere.
+ *
+ * Runs on the initial load and again after every client-router swap, which
+ * rebuilds the widget from server-rendered markup, so the handlers always
+ * bind to the freshly swapped-in elements.
+ */
+import type { BlumeConsent } from "./consent/types.ts";
+
+/** The longest comment the box takes. */
+export const COMMENT_MAX_LENGTH = 1000;
+
+/**
+ * Whether an answer would reach analytics: the site has no consent layer, or
+ * the reader has allowed analytics.
+ */
+const answersReachAnalytics = (): boolean => {
+  // SAFETY: the consent init script (`consent/init.ts`) is the only writer of
+  // `window.blumeConsent`; without a consent layer it's absent.
+  const { blumeConsent } = window as Window & { blumeConsent?: BlumeConsent };
+  return blumeConsent === undefined || blumeConsent.analytics === true;
+};
+
+/**
+ * Show the page's rating only while its answers would reach analytics. Runs
+ * when the widget is wired and again on every `blume:consent` change, so a
+ * reader who accepts the banner gets the rating right away.
+ */
+export const syncFeedbackVisibility = (): void => {
+  const root = document.querySelector<HTMLElement>(
+    "[data-blume-page-feedback]"
+  );
+  if (root) {
+    root.hidden = !answersReachAnalytics();
+  }
+};
+
+/** Wire the page's rating, when it has one. */
+export const initFeedback = (): void => {
+  const root = document.querySelector("[data-blume-page-feedback]");
+  if (!root) {
+    return;
+  }
+  syncFeedbackVisibility();
+  const actions = root.querySelector("[data-feedback-actions]");
+  const thanks = root.querySelector<HTMLElement>("[data-feedback-thanks]");
+  const form = root.querySelector<HTMLFormElement>("[data-feedback-form]");
+  let helpful = "";
+  const rate = (value: string) => {
+    helpful = value;
+    track("feedback", {
+      helpful,
+      path: location.pathname,
+      title: document.title,
+    });
+    actions?.classList.add("hidden");
+    thanks?.classList.remove("hidden");
+    if (form) {
+      form.hidden = false;
+    }
+    // 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.
+    // The comment box is the next stop from there.
+    thanks?.focus();
+  };
+  for (const button of root.querySelectorAll<HTMLElement>(
+    "[data-feedback-value]"
+  )) {
+    button.addEventListener("click", () =>
+      rate(button.dataset.feedbackValue ?? "")
+    );
+  }
+  form?.addEventListener("submit", (event) => {
+    event.preventDefault();
+    const comment = form.querySelector("textarea")?.value.trim() ?? "";
+    if (comment) {
+      track("feedback_comment", {
+        comment: comment.slice(0, COMMENT_MAX_LENGTH),
+        helpful,
+        path: location.pathname,
+        title: document.title,
+      });
+    }
+    form.hidden = true;
+    thanks?.focus();
+  });
+};

package/src/components/layout/search/analytics.ts

@@ -0,0 +1,98 @@
+/**
+ * Search analytics: what readers search for, what they find, and what they
+ * open, sent through the configured analytics adapters (`track`).
+ *
+ * The dialog searches on every keystroke, so a query is only recorded once it
+ * settles: a second without typing, or the reader picking a result or closing
+ * the dialog. Each settled query is one `search` event with the number of
+ * results, so a dashboard can list the queries that found nothing. Picking a
+ * result is a `search_select` event with its position, for click-through. The
+ * same query settling twice in a row (a filter toggled back and forth) counts
+ * once.
+ */
+import type { TrackProps } from "../analytics-client.ts";
+
+/** The longest query sent: past this it's rarely a search term. */
+export const MAX_QUERY_CHARS = 100;
+
+/** How long a query sits untouched before it counts as settled. */
+export const SETTLE_MS = 1000;
+
+/** Sends one analytics event. */
+export type SendEvent = (event: string, props: TrackProps) => void;
+
+/** The timer a tracker waits on; injectable for tests. */
+export interface SettleTimer {
+  cancel: (handle: number) => void;
+  start: (callback: () => void, ms: number) => number;
+}
+
+/** What the dialog tells the tracker. */
+export interface SearchTracker {
+  /** The dialog closed; record the query it was showing. */
+  closed: () => void;
+  /** The reader picked result `position` (1-based) for `query`. */
+  selected: (query: string, position: number, url: string) => void;
+  /** Results for `query` are on screen. */
+  settled: (query: string, results: number) => void;
+}
+
+/** A query and how many results it found. */
+interface PendingSearch {
+  query: string;
+  results: number;
+}
+
+const browserTimer: SettleTimer = {
+  cancel: (handle) => clearTimeout(handle),
+  start: (callback, ms) => Number(setTimeout(callback, ms)),
+};
+
+/** A tracker for one search dialog. */
+export const createSearchTracker = (
+  send: SendEvent,
+  timer: SettleTimer = browserTimer
+): SearchTracker => {
+  let pending: PendingSearch | undefined;
+  let handle: number | undefined;
+  let last: string | undefined;
+
+  const flush = (): void => {
+    if (handle !== undefined) {
+      timer.cancel(handle);
+      handle = undefined;
+    }
+    if (pending && pending.query !== last) {
+      send("search", {
+        path: location.pathname,
+        query: pending.query,
+        results: pending.results,
+      });
+      last = pending.query;
+    }
+    pending = undefined;
+  };
+
+  return {
+    closed: () => {
+      flush();
+      last = undefined;
+    },
+    selected: (query, position, url) => {
+      flush();
+      send("search_select", {
+        path: location.pathname,
+        position,
+        query: query.slice(0, MAX_QUERY_CHARS),
+        url,
+      });
+    },
+    settled: (query, results) => {
+      if (handle !== undefined) {
+        timer.cancel(handle);
+      }
+      pending = { query: query.slice(0, MAX_QUERY_CHARS), results };
+      handle = timer.start(flush, SETTLE_MS);
+    },
+  };
+};

package/src/components/layout/search/flexsearch.ts

@@ -1,6 +1,6 @@
 import { Document } from "flexsearch";
 
-import { buildResult, RESULT_POOL } from "./types.ts";
+import { buildResult, byBoost, RESULT_POOL } from "./types.ts";
 import type { IndexedDocument, SearchFn } from "./types.ts";
 
 /**
@@ -11,7 +11,7 @@ import type { IndexedDocument, SearchFn } from "./types.ts";
 type SearchDocument = Pick<
   IndexedDocument,
   "content" | "description" | "route" | "title"
->;
+> & { keywords: string };
 
 /**
  * FlexSearch: reuse the same static `blume-search.json` Orama ships, but build
@@ -29,11 +29,14 @@ export const createSearch = async (opts: {
   const byRoute = new Map(documents.map((doc) => [doc.route, doc]));
 
   const index = new Document<SearchDocument>({
-    document: { id: "route", index: ["title", "description", "content"] },
+    document: {
+      id: "route",
+      index: ["title", "keywords", "description", "content"],
+    },
     tokenize: "forward",
   });
   for (const doc of documents) {
-    index.add(doc);
+    index.add({ ...doc, keywords: doc.keywords?.join(" ") ?? "" });
   }
 
   // FlexSearch's in-memory search is synchronous, so the SearchFn resolves
@@ -63,6 +66,15 @@ export const createSearch = async (opts: {
         }
       }
     }
-    return Promise.resolve(buildResult(matched, query, options?.section));
+    // FlexSearch returns an order, not scores: rank by position, then apply
+    // each page's `search.boost` to that.
+    const ranked = byBoost(
+      matched.map((doc, position) => ({
+        boost: doc.boost,
+        match: doc,
+        score: 1 / (position + 1),
+      }))
+    );
+    return Promise.resolve(buildResult(ranked, query, options?.section));
   };
 };

package/src/components/layout/search/orama-cloud.ts

@@ -1,7 +1,13 @@
 import { OramaClient } from "@oramacloud/client";
 
 import type { OramaCloudOptions } from "../../../search/adapters/orama-cloud.ts";
-import { excerptFor, highlight, SEARCH_LIMIT } from "./types.ts";
+import {
+  byBoost,
+  excerptFor,
+  highlight,
+  RESULT_POOL,
+  SEARCH_LIMIT,
+} from "./types.ts";
 import type { SearchFn } from "./types.ts";
 
 interface OramaCloudRecord {
@@ -9,6 +15,7 @@ interface OramaCloudRecord {
   title: string;
   description?: string;
   content?: string;
+  boost?: number;
 }
 
 /**
@@ -25,25 +32,30 @@ export const createSearch = (opts: OramaCloudOptions): SearchFn => {
     endpoint,
   });
   return async (query, options) => {
+    // A pool beyond the visible limit, so each page's `search.boost` can
+    // lift a hit into view before the list is cut.
     const results = await client.search({
-      limit: SEARCH_LIMIT,
+      limit: RESULT_POOL,
       term: query,
       // The sync carries `locale` on every record so an i18n site can scope
       // hosted results to the active language.
       ...(options?.locale && { where: { locale: options.locale } }),
     });
-    const hits = (results?.hits ?? []).map((hit) => {
-      const doc: OramaCloudRecord = hit.document;
-      return {
-        content: doc.content ?? "",
-        excerpt: highlight(
-          excerptFor(doc.description ?? "", doc.content ?? "", query),
-          query
-        ),
-        title: highlight(doc.title, query),
-        url: doc.url,
-      };
-    });
+    const ranked = byBoost(
+      (results?.hits ?? []).map((hit) => {
+        const doc: OramaCloudRecord = hit.document;
+        return { boost: doc.boost, match: doc, score: hit.score };
+      })
+    );
+    const hits = ranked.slice(0, SEARCH_LIMIT).map((doc) => ({
+      content: doc.content ?? "",
+      excerpt: highlight(
+        excerptFor(doc.description ?? "", doc.content ?? "", query),
+        query
+      ),
+      title: highlight(doc.title, query),
+      url: doc.url,
+    }));
     return { hits, sections: [] };
   };
 };

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

@@ -53,8 +53,28 @@ export interface IndexedDocument {
   section?: string;
   locale?: string;
   version?: string;
+  /** The page's relevance multiplier (`search.boost`). */
+  boost?: number;
+  /** Extra terms the page is found by (`search.keywords`). */
+  keywords?: string[];
 }
 
+/** Something ranked with a relevance score, and the page it belongs to. */
+export interface ScoredMatch<Match> {
+  boost?: number;
+  match: Match;
+  score: number;
+}
+
+/**
+ * Re-rank matches by score times their page's `search.boost`. The sort is
+ * stable, so equal scores keep the provider's order.
+ */
+export const byBoost = <Match>(scored: ScoredMatch<Match>[]): Match[] =>
+  scored
+    .toSorted((a, b) => b.score * (b.boost ?? 1) - a.score * (a.boost ?? 1))
+    .map(({ match }) => match);
+
 /** Max results surfaced in the dialog. */
 export const SEARCH_LIMIT = 12;
 

package/src/components/layout/search/typesense.ts

@@ -34,7 +34,11 @@ export const createSearch = (opts: TypesenseOptions): SearchFn => {
         {
           per_page: SEARCH_LIMIT,
           q: query,
-          query_by: "title,description,content",
+          query_by: "title,keywords,description,content",
+          // Relevance first, in ten bands, then each page's `search.boost`
+          // within a band: a boost lifts a page past similar matches without
+          // floating it over clearly better ones.
+          sort_by: "_text_match(buckets: 10):desc,boost:desc",
           // The sync marks `locale` and `version` as facets so hosted results
           // scope to the active language and the viewed docs version (the
           // current docs upload as "current").

package/src/components/layout/toc-active.ts

@@ -0,0 +1,41 @@
+/**
+ * The scrollspy's choice of the active "On this page" entry, kept apart from
+ * the `<blume-toc>` element (toc-element.ts) so it runs without a DOM.
+ */
+
+/** The two measurements the scrollspy takes of a heading. */
+export interface MeasuredHeading {
+  getBoundingClientRect: () => { top: number };
+  getClientRects: () => { length: number };
+}
+
+/**
+ * The entry for the section being read: the last heading at or above the
+ * trigger line (the first heading before any has reached it), or the last
+ * heading once the page is scrolled to the bottom.
+ *
+ * Only rendered headings compete. A heading inside a hidden tab panel
+ * (`display: none`) has no boxes and measures `top: 0`, so it would always
+ * read as scrolled past and hold the highlight from the top of the page.
+ */
+export const activeTocEntry = <Entry extends { heading: MeasuredHeading }>(
+  entries: readonly Entry[],
+  triggerOffset: number,
+  scrolledToBottom: boolean
+): Entry | null => {
+  const rendered = entries.filter(
+    ({ heading }) => heading.getClientRects().length > 0
+  );
+  if (scrolledToBottom) {
+    return rendered.at(-1) ?? null;
+  }
+  // Headings are in document order, so the last one whose top has reached the
+  // trigger line is the section currently being read; default to the first.
+  let active = rendered[0] ?? null;
+  for (const entry of rendered) {
+    if (entry.heading.getBoundingClientRect().top <= triggerOffset) {
+      active = entry;
+    }
+  }
+  return active;
+};

package/src/components/layout/toc-element.ts

@@ -6,7 +6,8 @@
  *
  * The active heading is chosen by rect (the last heading at or above a trigger
  * line just below the sticky header), so it stays correct for sections taller
- * than the viewport and at the bottom of the page. An IntersectionObserver is the
+ * than the viewport and at the bottom of the page; headings that aren't rendered
+ * (inside a hidden tab panel) are skipped (see toc-active.ts). An IntersectionObserver is the
  * cheap primary trigger — it only fires as headings cross the band near the top —
  * and a passive, rAF-throttled scroll listener covers the one case it can't: a
  * final section too short to push its heading past the trigger line.
@@ -14,6 +15,8 @@
  * Imported for its side effect (registers the element) from RootLayout's script.
  */
 
+import { activeTocEntry } from "./toc-active.ts";
+
 interface TocEntry {
   heading: HTMLElement;
   link: HTMLAnchorElement;
@@ -93,19 +96,10 @@ class BlumeToc extends HTMLElement {
     const scrolledToBottom =
       window.innerHeight + window.scrollY >=
       document.documentElement.scrollHeight - 2;
-    if (scrolledToBottom) {
-      return this.#entries.at(-1)?.link ?? null;
-    }
-
-    // Headings are in document order, so the last one whose top has reached the
-    // trigger line is the section currently being read; default to the first.
-    let active = this.#entries[0]?.link ?? null;
-    for (const { heading, link } of this.#entries) {
-      if (heading.getBoundingClientRect().top <= TRIGGER_OFFSET) {
-        active = link;
-      }
-    }
-    return active;
+    return (
+      activeTocEntry(this.#entries, TRIGGER_OFFSET, scrolledToBottom)?.link ??
+      null
+    );
   }
 }
 

package/src/components/openapi/ApiTagOperations.astro

@@ -1,7 +1,7 @@
 ---
 import specs from "blume:openapi";
 import { specOf } from "../../openapi/model.ts";
-import { withBase } from "../islands/base-path.ts";
+import { withMountedBase } from "../islands/base-path.ts";
 import MethodBadge from "./MethodBadge.astro";
 
 // The operation-link list for one tag section of an API overview page. The
@@ -27,7 +27,7 @@ const operations = Object.values(specOf(specs, source)?.operations ?? {}).filter
         <li>
           <a
             class="flex items-start gap-3 rounded-blume border border-border p-3 text-inherit no-underline! transition-colors hover:border-accent hover:bg-muted hover:no-underline!"
-            href={withBase(operation.route)}
+            href={withMountedBase(operation.route)}
           >
             <MethodBadge class="mt-0.5 shrink-0" method={operation.method} />
             {/* Title over path, stacked, so a long summary and a long route each