blume 2.0.1 → 2.0.3

package/src/components/layout/Search.astro

@@ -1,9 +1,13 @@
 ---
+import data from "blume:data";
+
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
+import { scopesVersions } from "../../search/adapters/version-scope.ts";
 import { resolvePopularIconMarkup } from "../../search/popular-icon.ts";
 import Icon from "../Icon.astro";
+import { withBase, withMountedBase } from "../islands/base-path.ts";
 import { flattenPages } from "./nav-utils.ts";
 
 // The provider-specific loader is generated per project into `blume:search-client`
@@ -21,7 +25,8 @@ interface Props {
   locale?: string;
   /**
    * Docs version to filter results to (`""` = the current docs — a meaningful
-   * value, so `null`/omitted is what disables version filtering).
+   * value, so `null`/omitted is what disables version filtering). Ignored when
+   * the configured provider can't scope by version.
    */
   version?: string | null;
 }
@@ -32,27 +37,41 @@ const {
   popularPages,
   strings,
   locale,
-  version = null,
+  version: viewedVersion = null,
 } = Astro.props;
+// Pagefind, Orama Cloud, and Mixedbread search every version whatever the
+// dialog asks, so on those an "All versions" toggle would change nothing:
+// treat the site as unversioned for search instead.
+const version = scopesVersions(data.config.search.provider)
+  ? viewedVersion
+  : null;
 // Merge over the English baseline per key (rather than `strings ?? …`) so a
 // partial — or empty `{}` — strings object still resolves every label to a
 // default, matching the pattern PageActions uses for its own dictionary.
 const s = { ...EN_UI.search, ...strings };
 
 // Resolve popular icons to markup here (icon set is server-only). Unknown
-// names fall through to the island's file glyph.
+// names fall through to the island's file glyph. Each entry's served href is
+// resolved here too: a configured entry is authored, so a base written by hand
+// is kept (`withBase`); the sidebar fallback links generated routes, which
+// always go under the base (`withMountedBase`).
 const popular =
   popularPages && popularPages.length > 0
     ? popularPages.map((page) => ({
+        href: withBase(page.route),
         icon: resolvePopularIconMarkup(
           page.icon,
           import.meta.env.BASE_URL ?? "/"
         ),
         label: page.label,
-        route: page.route,
       }))
     : navigation
-      ? flattenPages(navigation.sidebar).slice(0, 6)
+      ? flattenPages(navigation.sidebar)
+          .slice(0, 6)
+          .map((page) => ({
+            href: withMountedBase(page.route),
+            label: page.label,
+          }))
       : [];
 
 const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
@@ -67,6 +86,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   data-i18n-dev={s.devOnly}
   data-i18n-empty={s.noResults}
   data-i18n-error={s.error}
+  data-i18n-latest={s.latest}
   data-i18n-popular={s.popular}
   data-i18n-results={s.results}
   data-locale={locale || undefined}
@@ -219,7 +239,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   <script>
     import { navigate } from "astro:transitions/client";
     import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
-    import { prefixBase } from "../islands/base-path.ts";
+    import { mountBase } from "../islands/base-path.ts";
     import { escape as escapeHtml } from "html-escaper";
 
     import { highlight, matchSnippet } from "./search/types.ts";
@@ -233,10 +253,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
     }
 
     interface PopularPage {
+      /** The served URL, base included (resolved server-side). */
+      href: string;
       /** Pre-resolved inline SVG from the server; absent falls back to `file`. */
       icon?: string;
       label: string;
-      route: string;
     }
 
     const GRID_COLS = "md:grid-cols-[22rem_minmax(0,1fr)]";
@@ -328,6 +349,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       allMsg = "All";
       popularMsg = "Popular";
       resultsMsg = "Results";
+      latestMsg = "latest";
       // The active locale to filter to (null when i18n is off), and whether the
       // reader has opted to search across every language instead.
       locale: string | null = null;
@@ -382,6 +404,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           this.getAttribute("data-i18n-popular") || this.popularMsg;
         this.resultsMsg =
           this.getAttribute("data-i18n-results") || this.resultsMsg;
+        this.latestMsg =
+          this.getAttribute("data-i18n-latest") || this.latestMsg;
         this.locale = this.getAttribute("data-locale");
         // "" (the current docs) is a real version value, so a presence flag —
         // not the attribute's truthiness — decides whether filtering is on.
@@ -667,7 +691,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         if (this.popular.length > 0) {
           const group = this.addGroup(this.popularMsg);
           for (const page of this.popular) {
-            const item = this.createLinkRow(page.route, page.label, page.icon);
+            const item = this.createLinkRow(page.href, page.label, page.icon);
             group.appendChild(item.el);
             this.selectables.push(item);
           }
@@ -751,9 +775,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
       createHitRow(hit: SearchHit, query: string): Selectable {
         const el = document.createElement("a");
-        // Index URLs are base-less logical routes; prefix the deployment base so
-        // clicking a result lands on the page's real served URL.
-        const href = prefixBase(import.meta.env.BASE_URL, hit.url);
+        // Index URLs are base-less logical routes; mount them under the
+        // deployment base so clicking a result lands on the page's real served
+        // URL, even when the route starts with the base's own name.
+        const href = mountBase(import.meta.env.BASE_URL, hit.url);
         el.href = href;
         el.className = `${ROW_CLASS} ${MARK}`;
         // `line-clamp-2` already sets `display`, so no `block` here (it would
@@ -765,7 +790,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         // reader knows they're about to leave the docs they're viewing.
         const versionTag =
           this.versioned && hit.version !== undefined && hit.version !== this.version
-            ? `<span class="ms-2 inline-block rounded-full bg-muted px-1.5 py-0.5 align-middle text-[0.65rem] text-muted-foreground">${escapeHtml(hit.version || "latest")}</span>`
+            ? `<span class="ms-2 inline-block rounded-full bg-muted px-1.5 py-0.5 align-middle text-[0.65rem] text-muted-foreground">${escapeHtml(hit.version || this.latestMsg)}</span>`
             : "";
         el.innerHTML = `
           <span class="mt-0.5 shrink-0 text-muted-foreground">${svg("file")}</span>
@@ -778,9 +803,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         return item;
       }
 
-      createLinkRow(url: string, label: string, icon?: string): Selectable {
+      createLinkRow(href: string, label: string, icon?: string): Selectable {
         const el = document.createElement("a");
-        const href = prefixBase(import.meta.env.BASE_URL, url);
         el.href = href;
         el.className = ROW_CLASS;
         // `icon` is server-resolved markup (built-in Lucide, `<img>`, or

package/src/components/layout/VersionBanner.astro

@@ -1,5 +1,5 @@
 ---
-import { withBase } from "../islands/base-path.ts";
+import { withMountedBase } from "../islands/base-path.ts";
 import Icon from "../Icon.astro";
 
 // The "you're viewing an old version" notice, shared by RootLayout and
@@ -29,7 +29,7 @@ const { notice } = Astro.props;
       <span>{notice.message}</span>
       <a
         class="inline-flex items-center gap-1 font-medium underline underline-offset-2"
-        href={withBase(notice.latestHref)}
+        href={withMountedBase(notice.latestHref)}
       >
         {notice.latestLabel}
         <Icon name="arrow-right" size={14} />

package/src/components/layout/analytics-client.ts

@@ -29,6 +29,7 @@ interface AnalyticsWindow {
   analytics?: { track?: (event: string, props?: TrackProps) => void };
   clarity?: (command: "event", event: string) => void;
   dataLayer?: DataLayer;
+  databuddy?: { track?: (event: string, props?: TrackProps) => void };
   fathom?: { trackEvent?: (event: string) => void };
   gtag?: (command: "event", event: string, props?: TrackProps) => void;
   heap?: { track?: (event: string, props?: TrackProps) => void };
@@ -39,6 +40,9 @@ interface AnalyticsWindow {
   pirsch?: (event: string, options?: { meta?: TrackProps }) => void;
   plausible?: (event: string, options?: { props?: TrackProps }) => void;
   posthog?: { capture?: (event: string, props?: TrackProps) => void };
+  stonks?: {
+    event?: (event: string, props?: Record<string, string>) => void;
+  };
 }
 
 /** Run one provider call; its failure must not reach the others or the caller. */
@@ -82,7 +86,17 @@ const trackGlobals = (
   attempt(() => (w.__blumeGtmLayer ?? w.dataLayer)?.push({ ...props, event }));
   // Privacy-first counters take a name, some with properties.
   attempt(() => w.plausible?.(event, { props }));
+  attempt(() => w.databuddy?.track?.(event, props));
   attempt(() => w.fathom?.trackEvent?.(event));
+  // OneDollarStats only takes string property values.
+  attempt(() =>
+    w.stonks?.event?.(
+      event,
+      Object.fromEntries(
+        Object.entries(props).map(([key, value]) => [key, String(value)])
+      )
+    )
+  );
   // Pirsch stringifies `meta` values in place, so it gets its own copy and
   // the `blume:track` listeners still see the original types.
   attempt(() => w.pirsch?.(event, { meta: { ...props } }));

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

package/src/components/openapi/AsyncApiOperation.astro

@@ -70,7 +70,7 @@ const security = resolveAsyncApiSecurity(
 );
 const parameters = channelParameters(channel, document);
 const messages = operation ? operationMessages(operation, channel, document) : [];
-const protocol = protocolOf(operation, channel, servers);
+const protocol = protocolOf(operation, channel, servers, document.components);
 
 /** Declared example first, else a sampled value from the payload schema. */
 const exampleOf = (message: (typeof messages)[number]["message"]): unknown =>
@@ -115,8 +115,8 @@ const samplePanels = sample
   ? await languageSamplePanels(languages, sample, data.config.codeThemes)
   : [];
 
-const operationBindings = bindingGroups(operation?.bindings);
-const channelBindings = bindingGroups(channel?.bindings);
+const operationBindings = bindingGroups(operation?.bindings, document.components);
+const channelBindings = bindingGroups(channel?.bindings, document.components);
 ---
 
 {
@@ -144,7 +144,10 @@ const channelBindings = bindingGroups(channel?.bindings);
             // Headers may be multi-format too; undefined with `headers`
             // present means an inline-unrenderable schema format.
             const headers = schemaOf(named.message.headers);
-            const messageBindings = bindingGroups(named.message.bindings);
+            const messageBindings = bindingGroups(
+              named.message.bindings,
+              document.components
+            );
             return (
               <section class="mt-6">
                 <div

package/src/components/openapi/GraphqlChip.astro

@@ -1,5 +1,5 @@
 ---
-import { withBase } from "../islands/base-path.ts";
+import { withMountedBase } from "../islands/base-path.ts";
 
 /**
  * A schema name (or full type display like `[Pet!]!`) rendered as a link when
@@ -21,7 +21,7 @@ const { name, route, class: className } = Astro.props;
   route ? (
     <a
       class:list={["font-mono text-accent hover:underline", className]}
-      href={withBase(route)}
+      href={withMountedBase(route)}
     >
       {name}
     </a>

package/src/components/openapi/GraphqlType.astro

@@ -1,4 +1,5 @@
 ---
+import { isSafeHref } from "../../core/safe-href.ts";
 import type { GraphqlDocument } from "../../openapi/graphql.ts";
 import { graphqlTypeDef } from "../../openapi/graphql.ts";
 import type { ApiOperationRef, ApiSpecData } from "../../openapi/model.ts";
@@ -65,9 +66,16 @@ const SECTION_HEADING = "mb-2 font-semibold text-foreground text-sm";
       {type.specifiedByUrl && (
         <div class="mb-4 text-muted-foreground text-sm">
           Specified by{" "}
-          <a class="text-accent hover:underline" href={type.specifiedByUrl}>
-            {type.specifiedByUrl}
-          </a>
+          {/* The URL comes from the schema, someone else's content: a
+              `javascript:` one would run on the docs origin when clicked, so
+              only a safe destination becomes a link. */}
+          {isSafeHref(type.specifiedByUrl) ? (
+            <a class="text-accent hover:underline" href={type.specifiedByUrl}>
+              {type.specifiedByUrl}
+            </a>
+          ) : (
+            <code class="break-all">{type.specifiedByUrl}</code>
+          )}
         </div>
       )}
       <GraphqlFieldsTable

package/src/components/openapi/MessageComposer.astro

@@ -133,7 +133,7 @@ const BUTTON_QUIET =
           Payload
           {
             model.payload.contentType && (
-              <span class="ml-1.5 font-mono normal-case">
+              <span class="ms-1.5 font-mono normal-case">
                 {model.payload.contentType}
               </span>
             )

package/src/components/openapi/Operation.astro

@@ -6,8 +6,13 @@ import {
   type ParameterLike,
   resolveComponentRef,
   type SchemaLike,
+  type SpecValue,
 } from "./helpers.ts";
-import { operationModel } from "./operation-model.ts";
+import {
+  effectiveServers,
+  operationModel,
+  type ServerLike,
+} from "./operation-model.ts";
 import { buildRequest, defaultValues } from "./request.ts";
 import {
   effectiveSecurity,
@@ -35,7 +40,8 @@ interface Props {
 
 interface MediaTypeLike {
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  examples?: SpecValue;
 }
 
 interface RequestBodyLike {
@@ -59,6 +65,7 @@ interface FullOperation {
   requestBody?: RequestBodyLike;
   responses?: Record<string, ResponseLike>;
   security?: SecurityRequirementLike[];
+  servers?: ServerLike[];
 }
 
 const { source, id } = Astro.props;
@@ -73,7 +80,10 @@ const isGraphql = spec?.kind === "graphql";
 const doc = (spec?.document ?? {}) as {
   paths?: Record<
     string,
-    Record<string, unknown> & { parameters?: ParameterLike[] }
+    Record<string, unknown> & {
+      parameters?: ParameterLike[];
+      servers?: ServerLike[];
+    }
   >;
   components?: {
     schemas?: Record<string, SchemaLike>;
@@ -83,7 +93,7 @@ const doc = (spec?.document ?? {}) as {
     securitySchemes?: Record<string, SecuritySchemeLike>;
   };
   security?: SecurityRequirementLike[];
-  servers?: { url?: string }[];
+  servers?: ServerLike[];
 };
 const pathItem = ref ? doc.paths?.[ref.path] : undefined;
 const operation = (
@@ -117,13 +127,20 @@ const security = resolveSecurity(
 const model =
   ref && operation
     ? operationModel({
+        components,
         method: ref.method,
         parameters: params,
         path: ref.path,
         requestBody,
         schemas,
         security,
-        servers: doc.servers ?? [],
+        // An operation's own `servers` override its path item's, which
+        // override the document's.
+        servers: effectiveServers(
+          operation.servers,
+          pathItem?.servers,
+          doc.servers
+        ),
       })
     : null;
 const sample = model ? buildRequest(model, defaultValues(model)) : null;
@@ -179,6 +196,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
               />
             )}
             <RequestPanel
+              components={components}
               languages={languages}
               responses={responses}
               sample={sample}

package/src/components/openapi/PanelTabs.astro

@@ -62,7 +62,9 @@ const TAB_CLASS =
       </div>
       <blume-panel-tabs class="block overflow-hidden rounded-blume border border-border bg-background">
         <div class="flex items-center justify-between gap-2 border-border border-b px-3">
-          <div class="flex flex-wrap gap-4" role="tablist">
+          <div aria-label={heading} class="flex flex-wrap gap-4" role="tablist">
+            {/* Roving tabindex: only the selected tab is in the Tab order, and
+                the arrow keys, Home, and End move between tabs (panel.ts). */}
             {panels.map((panel, index) => (
               <button
                 aria-controls={idFor("panel", panel.key)}
@@ -71,6 +73,7 @@ const TAB_CLASS =
                 data-panel-tab={panel.key}
                 id={idFor("tab", panel.key)}
                 role="tab"
+                tabindex={index === 0 ? "0" : "-1"}
                 type="button"
               >
                 {panel.label}

package/src/components/openapi/Playground.astro

@@ -1,5 +1,6 @@
 ---
 import { stableId } from "../content/tooltip-id.ts";
+import { withMountedBase } from "../islands/base-path.ts";
 
 import { paramKey, type PlaygroundModel } from "./request.ts";
 
@@ -23,6 +24,11 @@ interface Props {
 
 const { model, proxy, slug, operation } = Astro.props;
 
+// The built-in proxy route carries the site `basePath` but, like every
+// internal URL in the spec data, not `deployment.base`; `withMountedBase`
+// adds it and passes an external proxy URL through untouched.
+const proxyUrl = proxy ? withMountedBase(proxy) : undefined;
+
 // `</script>`-proof embedding: `<` only ever occurs inside JSON strings,
 // where the \u escape is equivalent, so a spec description can never close
 // the model script early and inject markup.
@@ -46,7 +52,7 @@ const CHECKBOX_ROW =
 
 <blume-playground
   class="mb-6 block"
-  data-proxy={proxy || undefined}
+  data-proxy={proxyUrl}
   data-storage-key={`blume-playground:${slug}:${operation}`}
 >
   <script
@@ -194,7 +200,7 @@ const CHECKBOX_ROW =
           <div class={GROUP}>
             <div class={GROUP_HEADING}>
               Body
-              <span class="ml-1.5 font-mono normal-case">
+              <span class="ms-1.5 font-mono normal-case">
                 {model.body.contentType}
               </span>
             </div>

package/src/components/openapi/RequestPanel.astro

@@ -2,14 +2,21 @@
 import data from "blume:data";
 
 import { highlightCode } from "../../markdown/index.ts";
-import { exampleValue, type SchemaLike, toJson } from "./helpers.ts";
+import {
+  type ComponentsLike,
+  responseExample,
+  type SchemaLike,
+  type SpecValue,
+  toJson,
+} from "./helpers.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import PanelTabs from "./PanelTabs.astro";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
 
 interface MediaTypeLike {
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  examples?: SpecValue;
 }
 
 interface ResponseLike {
@@ -18,13 +25,15 @@ interface ResponseLike {
 }
 
 interface Props {
+  /** The document's `components`, which `$ref`'d examples resolve against. */
+  components?: ComponentsLike;
   sample: RequestSample;
   languages: SampleLanguage[];
   responses: Record<string, ResponseLike>;
   schemas: Record<string, SchemaLike>;
 }
 
-const { sample, languages, responses, schemas } = Astro.props;
+const { components, sample, languages, responses, schemas } = Astro.props;
 
 const requestPanels = await languageSamplePanels(
   languages,
@@ -38,9 +47,7 @@ const responsePanels = await Promise.all(
       Object.entries(response.content ?? {}).find(([type]) =>
         type.includes("json")
       )?.[1] ?? Object.values(response.content ?? {})[0];
-    const example = media
-      ? (media.example ?? exampleValue(media.schema, schemas))
-      : undefined;
+    const example = media ? responseExample(media, schemas, components) : undefined;
     const html =
       example === undefined || example === null
         ? null