blume 2.0.3 → 2.1.0

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