blume 2.0.2 → 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";
@@ -220,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";
@@ -234,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)]";
@@ -671,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);
           }
@@ -755,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
@@ -782,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

@@ -40,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. */
@@ -85,6 +88,15 @@ const trackGlobals = (
   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/Operation.astro

@@ -127,6 +127,7 @@ const security = resolveSecurity(
 const model =
   ref && operation
     ? operationModel({
+        components,
         method: ref.method,
         parameters: params,
         path: ref.path,
@@ -195,6 +196,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
               />
             )}
             <RequestPanel
+              components={components}
               languages={languages}
               responses={responses}
               sample={sample}

package/src/components/openapi/Playground.astro

@@ -1,6 +1,6 @@
 ---
 import { stableId } from "../content/tooltip-id.ts";
-import { withBase } from "../islands/base-path.ts";
+import { withMountedBase } from "../islands/base-path.ts";
 
 import { paramKey, type PlaygroundModel } from "./request.ts";
 
@@ -25,9 +25,9 @@ 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`; `withBase` adds it
-// and passes an external proxy URL through untouched.
-const proxyUrl = proxy ? withBase(proxy) : undefined;
+// 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

package/src/components/openapi/RequestPanel.astro

@@ -3,6 +3,7 @@ import data from "blume:data";
 
 import { highlightCode } from "../../markdown/index.ts";
 import {
+  type ComponentsLike,
   responseExample,
   type SchemaLike,
   type SpecValue,
@@ -24,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,
@@ -44,7 +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 ? responseExample(media, schemas) : undefined;
+    const example = media ? responseExample(media, schemas, components) : undefined;
     const html =
       example === undefined || example === null
         ? null

package/src/components/openapi/SchemaTable.astro

@@ -35,6 +35,13 @@ const node = planned ?? schemaTree(schema, schemas);
     </div>
   ) : node.kind === "branches" ? (
     <div class="flex flex-col gap-3">
+      {node.rows && (
+        <div class="not-prose">
+          {node.rows.map((row) => (
+            <SchemaProperty row={row} schemas={schemas} expandAll={expandAll} />
+          ))}
+        </div>
+      )}
       <div class="text-muted-foreground text-xs">{node.label}:</div>
       {node.branches.map((branch) => (
         <div class="rounded-blume border border-border p-3">

package/src/components/openapi/async.ts

@@ -265,6 +265,32 @@ export const channelServers = (
   return servers;
 };
 
+/** A protocol-keyed `bindings` map, whatever object it sits on. */
+type BindingMap = Record<string, AsyncApiSpecValue>;
+
+const BINDINGS_REF =
+  /^#\/components\/(?<section>(?:server|channel|operation|message)Bindings)\/(?<name>[^/]+)$/u;
+
+/**
+ * A `bindings` map as declared: inline, or — which AsyncAPI allows in its
+ * place — a `$ref` to a `#/components/*Bindings` entry, resolved here. Read
+ * as-is, a referenced map's only key is `$ref`, which would pass for the
+ * protocol. `undefined` when a ref resolves to nothing.
+ */
+export const resolveBindings = (
+  bindings: BindingMap | undefined,
+  components?: Components
+): BindingMap | undefined => {
+  const ref = bindings?.$ref;
+  if (!isString(ref)) {
+    return bindings;
+  }
+  const groups = BINDINGS_REF.exec(ref)?.groups;
+  const target =
+    components?.[groups?.section ?? ""]?.[unescapePointer(groups?.name ?? "")];
+  return isObject(target) ? target : undefined;
+};
+
 /** Normalize protocol spellings onto the binding key they document. */
 const PROTOCOL_ALIASES = {
   "kafka-secure": "kafka",
@@ -277,15 +303,17 @@ const PROTOCOL_ALIASES = {
 /**
  * The protocol an operation speaks, for binding-aware code samples: the first
  * operation/channel binding key, else the first relevant server's `protocol`.
+ * `components` resolves bindings given as a `$ref`.
  */
 export const protocolOf = (
   operation: AsyncApiOperationObject | undefined,
   channel: AsyncApiChannelObject | undefined,
-  servers: AsyncApiServerObject[]
+  servers: AsyncApiServerObject[],
+  components?: Components
 ): string | undefined => {
   const declared =
-    Object.keys(operation?.bindings ?? {})[0] ??
-    Object.keys(channel?.bindings ?? {})[0] ??
+    Object.keys(resolveBindings(operation?.bindings, components) ?? {})[0] ??
+    Object.keys(resolveBindings(channel?.bindings, components) ?? {})[0] ??
     servers.find((server) => isString(server.protocol))?.protocol;
   if (!isString(declared) || declared === "") {
     return undefined;
@@ -338,13 +366,17 @@ export interface BindingGroup {
 /**
  * Binding maps flattened for display, `bindingVersion` (metadata, not
  * behavior) dropped. Values stay unformatted — the component renders schema-ish
- * objects as nested schema tables and everything else as code.
+ * objects as nested schema tables and everything else as code. `components`
+ * resolves a map given as a `$ref`.
  */
 export const bindingGroups = (
-  bindings?: AsyncApiChannelObject["bindings"]
+  bindings?: BindingMap,
+  components?: Components
 ): BindingGroup[] => {
   const groups: BindingGroup[] = [];
-  for (const [protocol, fields] of Object.entries(bindings ?? {})) {
+  for (const [protocol, fields] of Object.entries(
+    resolveBindings(bindings, components) ?? {}
+  )) {
     if (!isObject(fields)) {
       continue;
     }

package/src/components/openapi/helpers.ts

@@ -335,12 +335,17 @@ const isRecord = (value: SpecValue): value is Record<string, SpecValue> =>
 
 /**
  * The example a parameter or media type declares: its `example`, else the
- * first inline `value` in its `examples` map. Scalar's upgrade moves every
- * OpenAPI 3.0 and Swagger 2.0 `example` into `examples.default.value`, and
- * 3.1 authors write that map directly, so reading `example` alone would drop
- * them all. `undefined` when nothing is declared.
+ * first `value` in its `examples` map — inline, or behind a `$ref` to
+ * `#/components/examples`, resolved against `components`. Scalar's upgrade
+ * moves every OpenAPI 3.0 and Swagger 2.0 `example` into
+ * `examples.default.value`, and 3.1 authors write that map directly, so
+ * reading `example` alone would drop them all. `undefined` when nothing is
+ * declared.
  */
-export const declaredExample = (carrier: ExampleCarrier): SpecValue => {
+export const declaredExample = (
+  carrier: ExampleCarrier,
+  components?: ComponentsLike
+): SpecValue => {
   if (carrier.example !== undefined) {
     return carrier.example;
   }
@@ -349,8 +354,11 @@ export const declaredExample = (carrier: ExampleCarrier): SpecValue => {
     return undefined;
   }
   for (const entry of Object.values(examples)) {
-    if (isRecord(entry) && entry.value !== undefined) {
-      return entry.value;
+    const example = isRecord(entry)
+      ? resolveComponentRef(entry, components, "examples")
+      : undefined;
+    if (example?.value !== undefined) {
+      return example.value;
     }
   }
   return undefined;
@@ -363,9 +371,11 @@ export const declaredExample = (carrier: ExampleCarrier): SpecValue => {
  */
 export const responseExample = (
   media: ExampleCarrier & { schema?: SchemaLike },
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  components?: ComponentsLike
 ): SpecValue =>
-  declaredExample(media) ?? exampleValue(media.schema, schemas, "response");
+  declaredExample(media, components) ??
+  exampleValue(media.schema, schemas, "response");
 
 /** Pretty-print a JSON value for an example/code block. */
 export const toJson = <T>(value: T): string => JSON.stringify(value, null, 2);

package/src/components/openapi/message-composer.ts

@@ -171,7 +171,12 @@ export const initComposer = (root: HTMLElement): void => {
       return;
     }
     if (state === "error") {
-      setStatus(ERROR_MESSAGE, ERROR_TEXT);
+      // A detail is the browser refusing the URL before dialing; a failed
+      // handshake carries none.
+      setStatus(
+        detail ? `Couldn't connect: ${detail}` : ERROR_MESSAGE,
+        ERROR_TEXT
+      );
       return;
     }
     setStatus(

package/src/components/openapi/message.ts

@@ -87,6 +87,17 @@ export const defaultMessageValues = (model: MessageModel): MessageValues => ({
 
 const PARAM_TEMPLATE = /\{(?<name>[^{}]+)\}/gu;
 
+/**
+ * Protocols whose channel address is a URL path, where a parameter value must
+ * be percent-encoded. Everywhere else — a Kafka or MQTT topic, an AMQP routing
+ * key — the address is a name the value goes into as written: `sensor 1`,
+ * not `sensor%201`.
+ */
+const URL_PROTOCOLS = { http: true, https: true, ws: true } satisfies Record<
+  string,
+  true
+>;
+
 /**
  * A free-text base URL lowered onto the server shape the snippet builders and
  * the connect URL read. A full URL contributes its scheme, host, and path.
@@ -114,7 +125,8 @@ const customServer = (url: string): AsyncApiServerObject => {
 /**
  * THE one message builder: the composer's samples, its copy buttons, and the
  * live WebSocket frame all consume its output. Parameter values are
- * URL-encoded into the address; a parameter left blank keeps its `{name}`
+ * URL-encoded into the address when the protocol addresses channels by URL
+ * (see {@link URL_PROTOCOLS}); a parameter left blank keeps its `{name}`
  * template so the sample still reads as a template rather than a broken
  * address. Payload text that doesn't parse yields no payload — the editor is
  * showing the reader a validation error at that moment, and neither a sample
@@ -126,6 +138,9 @@ export const buildMessage = (
 ): MessageSample => {
   const custom = values.customUrl.trim();
   const picked = model.servers[values.server] ?? model.servers[0];
+  const encode = Object.hasOwn(URL_PROTOCOLS, model.protocol ?? "")
+    ? encodeURIComponent
+    : (value: string) => value;
   let payload: unknown;
   try {
     // SAFETY: JSON.parse returns `any`; widening it to `unknown` claims
@@ -138,7 +153,7 @@ export const buildMessage = (
     action: model.action,
     address: model.address.replaceAll(PARAM_TEMPLATE, (template, name) => {
       const value = values.params[String(name)] ?? "";
-      return value === "" ? template : encodeURIComponent(value);
+      return value === "" ? template : encode(value);
     }),
     payload,
     server: custom === "" ? picked?.server : customServer(custom),