blume 2.0.3 → 2.1.1

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/algolia.ts

@@ -48,7 +48,16 @@ export const createSearch = (opts: AlgoliaOptions): SearchFn => {
     // shape, so hits returned by that index carry those fields.
     const records =
       first && "hits" in first ? (first.hits as AlgoliaRecord[]) : [];
-    const hits = records.map((record) => ({
+    // The sync splits a long page across records that share its `url`. The
+    // index's `distinct` returns one of them, unless the site set its own
+    // `attributeForDistinct`; either way a page is listed once.
+    const pages = new Set<string>();
+    const unique = records.filter((record) => {
+      const seen = pages.has(record.url);
+      pages.add(record.url);
+      return !seen;
+    });
+    const hits = unique.map((record) => ({
       content: record.content ?? "",
       excerpt: highlight(
         excerptFor(record.description ?? "", record.content ?? "", query),

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

@@ -0,0 +1,126 @@
+/**
+ * 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.
+ *
+ * With `search.analytics.queries: false`, providers get each query's length
+ * (`queryChars`) instead of its text, and the text rides only the
+ * `blume:track` DOM event, the way the assistant reports questions.
+ */
+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; `local` rides only the `blume:track` DOM event
+ * (see `track`).
+ */
+export type SendEvent = (
+  event: string,
+  props: TrackProps,
+  local?: TrackProps
+) => void;
+
+/** The timer a tracker waits on; injectable for tests. */
+export interface SettleTimer {
+  cancel: (handle: number) => void;
+  start: (callback: () => void, ms: number) => number;
+}
+
+/** How a tracker reports. */
+export interface SearchTrackerOptions {
+  /** Whether providers receive each query's text (`search.analytics.queries`). */
+  queries?: boolean;
+  /** The timer a query waits on to settle; injectable for tests. */
+  timer?: SettleTimer;
+}
+
+/** 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,
+  { queries = true, timer = browserTimer }: SearchTrackerOptions = {}
+): SearchTracker => {
+  let pending: PendingSearch | undefined;
+  let handle: number | undefined;
+  let last: string | undefined;
+
+  // Providers get the query's text, or only its length, in which case the
+  // text goes to the `blume:track` DOM event alone.
+  const report = (event: string, props: TrackProps, query: string): void => {
+    if (queries) {
+      send(event, { ...props, query });
+    } else {
+      send(event, { ...props, queryChars: query.length }, { query });
+    }
+  };
+
+  const flush = (): void => {
+    if (handle !== undefined) {
+      timer.cancel(handle);
+      handle = undefined;
+    }
+    if (pending && pending.query !== last) {
+      report(
+        "search",
+        { path: location.pathname, results: pending.results },
+        pending.query
+      );
+      last = pending.query;
+    }
+    pending = undefined;
+  };
+
+  return {
+    closed: () => {
+      flush();
+      last = undefined;
+    },
+    selected: (query, position, url) => {
+      flush();
+      report(
+        "search_select",
+        { path: location.pathname, position, url },
+        query.slice(0, MAX_QUERY_CHARS)
+      );
+    },
+    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/endpoint.ts

@@ -1,22 +1,64 @@
 import { highlight, SEARCH_LIMIT } from "./types.ts";
-import type { SearchFn, SearchHit } from "./types.ts";
+import type { SearchClientOptions, SearchFn, SearchHit } from "./types.ts";
+
+/**
+ * How long a typed query waits for the reader to stop typing before it's
+ * sent, in milliseconds. The dialog searches on every keystroke, and each
+ * request counts toward the endpoint's `rateLimit`.
+ */
+export const SEARCH_DEBOUNCE_MS = 250;
+
+/** Resolve after `ms`, or reject with the abort reason once `signal` aborts. */
+const pause = (ms: number, signal: AbortSignal): Promise<void> =>
+  // oxlint-disable-next-line promise/avoid-new -- adapt setTimeout and the abort event
+  new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true }
+    );
+  });
 
 /**
  * Server-proxied search (Mixedbread): POST the query to a generated endpoint
  * that holds the secret key and talks to the service. The returned hits carry
  * service-derived text and the dialog injects title/excerpt as HTML, so both
  * are escaped (and query matches marked) here, like every other provider.
+ * A failed request rejects, as a hosted provider's does, so the dialog shows
+ * its error rather than an empty "no results".
+ *
+ * With `typing` (the search dialog), a query waits {@link SEARCH_DEBOUNCE_MS}
+ * before it's sent, and a newer one supersedes it: the earlier call's wait or
+ * request is aborted and it rejects with an `AbortError`. Typing a word then
+ * costs one request rather than one per letter, and a slow earlier response
+ * can't land after a later one. Without it, every call is sent at once.
  */
-export const createSearch =
-  (opts: { api: string }): SearchFn =>
-  async (query) => {
+export const createSearch = (
+  opts: { api: string } & SearchClientOptions
+): SearchFn => {
+  let pending: AbortController | undefined;
+  return async (query) => {
+    let signal: AbortSignal | undefined;
+    if (opts.typing) {
+      pending?.abort();
+      pending = new AbortController();
+      ({ signal } = pending);
+      await pause(SEARCH_DEBOUNCE_MS, signal);
+    }
     const response = await fetch(opts.api, {
       body: JSON.stringify({ query }),
       headers: { "Content-Type": "application/json" },
       method: "POST",
+      signal,
     });
     if (!response.ok) {
-      return { hits: [], sections: [] };
+      throw new Error(
+        `Search failed: ${opts.api} answered ${response.status}.`
+      );
     }
     // SAFETY: the endpoint is Blume-generated (`search-endpoint` template) and
     // responds with the SearchHit list it built; title/excerpt are still
@@ -29,3 +71,4 @@ export const createSearch =
     }));
     return { hits, sections: [] };
   };
+};

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: [] };
   };
 };