blume 1.4.3 → 1.5.1

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

@@ -8,6 +8,7 @@ interface AlgoliaRecord {
   title: string;
   description?: string;
   content?: string;
+  version?: string;
 }
 
 /**
@@ -27,15 +28,24 @@ export const createSearch = (opts: {
           hitsPerPage: SEARCH_LIMIT,
           indexName: opts.indexName,
           query,
-          // The sync uploads `locale` on every record so an i18n site can
-          // scope hosted results to the active language.
-          ...(options?.locale && {
-            facetFilters: [`locale:${options.locale}`],
-          }),
+          // The sync uploads `locale` and `version` on every record so a
+          // site can scope hosted results to the active language and the
+          // viewed docs version (the current docs upload as "current").
+          ...(() => {
+            const facetFilters = [
+              ...(options?.locale ? [`locale:${options.locale}`] : []),
+              ...(options?.version === undefined
+                ? []
+                : [`version:${options.version || "current"}`]),
+            ];
+            return facetFilters.length > 0 ? { facetFilters } : {};
+          })(),
         },
       ],
     });
     const [first] = results;
+    // SAFETY: the build-time sync uploads every record in the AlgoliaRecord
+    // 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) => ({
@@ -46,6 +56,9 @@ export const createSearch = (opts: {
       ),
       title: highlight(record.title, query),
       url: record.url,
+      // Records store the current docs' version as "current" (hosted backends
+      // treat empty facet values unreliably); the hit contract uses "".
+      version: record.version === "current" ? "" : record.version,
     }));
     return { hits, sections: [] };
   };

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

@@ -18,6 +18,9 @@ export const createSearch =
     if (!response.ok) {
       return { hits: [], sections: [] };
     }
+    // SAFETY: the endpoint is Blume-generated (`search-endpoint` template) and
+    // responds with the SearchHit list it built; title/excerpt are still
+    // escaped below before the dialog injects them as HTML.
     const records = (await response.json()) as SearchHit[];
     const hits = records.slice(0, SEARCH_LIMIT).map((hit) => ({
       ...hit,

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

@@ -3,6 +3,16 @@ import { Document } from "flexsearch";
 import { buildResult, RESULT_POOL } from "./types.ts";
 import type { IndexedDocument, SearchFn } from "./types.ts";
 
+/**
+ * The fields FlexSearch indexes. An anonymous alias of the indexed fields:
+ * unlike the `IndexedDocument` interface it satisfies FlexSearch's
+ * index-signature `DocumentData` constraint structurally.
+ */
+type SearchDocument = Pick<
+  IndexedDocument,
+  "content" | "description" | "route" | "title"
+>;
+
 /**
  * FlexSearch: reuse the same static `blume-search.json` Orama ships, but build
  * a FlexSearch document index in the browser. Keyless; works in dev and build.
@@ -13,17 +23,17 @@ export const createSearch = async (opts: {
   indexUrl: string;
 }): Promise<SearchFn> => {
   const response = await fetch(opts.indexUrl);
+  // SAFETY: `blume-search.json` is generated by our own search indexer, which
+  // writes exactly this document shape.
   const documents = (await response.json()) as IndexedDocument[];
   const byRoute = new Map(documents.map((doc) => [doc.route, doc]));
 
-  const index = new Document({
+  const index = new Document<SearchDocument>({
     document: { id: "route", index: ["title", "description", "content"] },
     tokenize: "forward",
   });
   for (const doc of documents) {
-    // FlexSearch's `DocumentData` is an index-signature type; our concrete
-    // record satisfies it structurally but TS needs the cast.
-    index.add(doc as unknown as Record<string, string>);
+    index.add(doc);
   }
 
   // FlexSearch's in-memory search is synchronous, so the SearchFn resolves
@@ -40,9 +50,15 @@ export const createSearch = async (opts: {
         }
         seen.add(route);
         const doc = byRoute.get(route);
-        // Filter to the active locale (when one is requested) before shaping,
-        // so section counts and results stay within the language.
-        if (doc && (!options?.locale || doc.locale === options.locale)) {
+        // Filter to the active locale and version (when requested) before
+        // shaping, so section counts and results stay within scope. `""` is
+        // the current version, so version presence is tested explicitly.
+        if (
+          doc &&
+          (!options?.locale || doc.locale === options.locale) &&
+          (options?.version === undefined ||
+            (doc.version ?? "") === options.version)
+        ) {
           matched.push(doc);
         }
       }

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

@@ -31,7 +31,7 @@ export const createSearch = (opts: {
       ...(options?.locale && { where: { locale: options.locale } }),
     });
     const hits = (results?.hits ?? []).map((hit) => {
-      const doc = hit.document as unknown as OramaCloudRecord;
+      const doc: OramaCloudRecord = hit.document;
       return {
         content: doc.content ?? "",
         excerpt: highlight(

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

@@ -19,13 +19,16 @@ export const createSearch = async (opts: {
   locale?: string;
 }): Promise<SearchFn> => {
   const response = await fetch(opts.indexUrl);
+  // SAFETY: `blume-search.json` is generated by our own indexer
+  // (`buildSearchDocuments`), which writes exactly this document shape.
   const documents = (await response.json()) as IndexedDocument[];
   const db = await buildOramaIndex(documents, opts.locale);
 
   return async (query, options) => {
     const docs = await queryOramaIndex(db, query, RESULT_POOL, {
       locale: options?.locale,
+      version: options?.version,
     });
-    return buildResult(docs as IndexedDocument[], query, options?.section);
+    return buildResult(docs, query, options?.section);
   };
 };

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

@@ -23,6 +23,8 @@ export const createSearch = async (opts: {
 }): Promise<SearchFn> => {
   // The pagefind bundle lives in the built site (not node_modules) and is
   // resolved at runtime by URL — it can't be a static, code-splittable path.
+  // SAFETY: the URL points at the `pagefind.js` module our own build emitted,
+  // whose export contract (`search()`) is fixed by pagefind.
   // oxlint-disable-next-line react-doctor/no-dynamic-import-path
   const pagefind = (await import(
     /* @vite-ignore */

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

@@ -13,6 +13,11 @@ export interface SearchHit {
   section?: string;
   /** Plain-text page content, used to render the preview pane. */
   content?: string;
+  /**
+   * Docs version the hit belongs to (`""` = current). Local indexes and the
+   * hosted Algolia/Typesense adapters set it; other providers leave it unset.
+   */
+  version?: string;
 }
 
 /** A category pill with its result count. */
@@ -30,7 +35,12 @@ export interface SearchResult {
 /** A configured query function — the common contract every provider returns. */
 export type SearchFn = (
   query: string,
-  options?: { section?: string; locale?: string }
+  options?: {
+    section?: string;
+    locale?: string;
+    /** Docs version to scope to (`""` = current); omitted disables it. */
+    version?: string;
+  }
 ) => Promise<SearchResult>;
 
 /** A document in the client-loaded `blume-search.json` index. */
@@ -42,6 +52,7 @@ export interface IndexedDocument {
   breadcrumb?: string[];
   section?: string;
   locale?: string;
+  version?: string;
 }
 
 /** Max results surfaced in the dialog. */
@@ -193,6 +204,7 @@ export const buildResult = (
     section: doc.section ?? "",
     title: highlight(doc.title, query),
     url: doc.route,
+    version: doc.version,
   }));
   return { hits, sections };
 };

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

@@ -8,6 +8,7 @@ interface TypesenseRecord extends Record<string, unknown> {
   title: string;
   description?: string;
   content?: string;
+  version?: string;
 }
 
 /**
@@ -40,9 +41,20 @@ export const createSearch = (opts: {
           per_page: SEARCH_LIMIT,
           q: query,
           query_by: "title,description,content",
-          // The sync marks `locale` as a facet so an i18n site can scope
-          // hosted results to the active language.
-          ...(options?.locale && { filter_by: `locale:=${options.locale}` }),
+          // 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").
+          ...(() => {
+            const clauses = [
+              ...(options?.locale ? [`locale:=${options.locale}`] : []),
+              ...(options?.version === undefined
+                ? []
+                : [`version:=${options.version || "current"}`]),
+            ];
+            return clauses.length > 0
+              ? { filter_by: clauses.join(" && ") }
+              : {};
+          })(),
         },
         {}
       );
@@ -56,6 +68,10 @@ export const createSearch = (opts: {
         ),
         title: highlight(doc.title, query),
         url: doc.url,
+        // Records store the current docs' version as "current" (hosted
+        // backends treat empty facet values unreliably); the hit contract
+        // uses "".
+        version: doc.version === "current" ? "" : doc.version,
       };
     });
     return { hits, sections: [] };

package/src/components/openapi/ApiOverview.astro

@@ -1,6 +1,8 @@
 ---
 import specs from "blume:openapi";
 
+import type { AsyncApiDocument } from "../../openapi/asyncapi.ts";
+
 // The spec-level metadata block (version + base URLs) at the top of an API
 // overview page. The tag sections that follow are emitted by `overviewMdx` as
 // markdown headings plus `<ApiTagOperations>` lists, so they land in the
@@ -11,8 +13,32 @@ interface Props {
 
 const { source } = Astro.props;
 const spec = specs[source];
-const servers =
-  ((spec?.document ?? {}) as { servers?: { url?: string }[] }).servers ?? [];
+
+// OpenAPI declares `servers` as an array of URLs; AsyncAPI as a named map of
+// host/protocol/pathname. Both flatten into one list of address chips.
+const addresses: string[] = [];
+if (spec?.kind === "asyncapi") {
+  const servers = (spec.document as AsyncApiDocument).servers ?? {};
+  for (const server of Object.values(servers)) {
+    if (server?.host) {
+      addresses.push(
+        `${server.protocol ? `${server.protocol}://` : ""}${server.host}${server.pathname ?? ""}`
+      );
+    }
+  }
+} else {
+  // Hand-written specs sometimes declare `servers` as a bare object; degrade
+  // to no address chips instead of throwing mid-build.
+  const declared = ((spec?.document ?? {}) as { servers?: { url?: string }[] })
+    .servers;
+  const servers = Array.isArray(declared) ? declared : [];
+  for (const server of servers) {
+    if (server.url) {
+      addresses.push(server.url);
+    }
+  }
+}
+const addressLabel = spec?.kind === "asyncapi" ? "Servers" : "Base URL";
 ---
 
 {
@@ -23,12 +49,12 @@ const servers =
           Version {spec.version}
         </div>
       )}
-      {servers.length > 0 && (
+      {addresses.length > 0 && (
         <div class="not-prose mb-8 flex flex-wrap items-center gap-2">
-          <span class="text-muted-foreground text-xs">Base URL</span>
-          {servers.map((server) => (
+          <span class="text-muted-foreground text-xs">{addressLabel}</span>
+          {addresses.map((address) => (
             <code class="rounded bg-muted px-2 py-0.5 text-foreground text-xs">
-              {server.url}
+              {address}
             </code>
           ))}
         </div>

package/src/components/openapi/AsyncApiOperation.astro

@@ -0,0 +1,237 @@
+---
+import data from "blume:data";
+import specs from "blume:openapi";
+
+import type { AsyncApiDocument } from "../../openapi/asyncapi.ts";
+import { asyncApiOperationObject } from "../../openapi/asyncapi.ts";
+import { highlightCode } from "../../markdown/index.ts";
+import {
+  asyncApiSecurityEntries,
+  bindingGroups,
+  channelParameters,
+  channelServers,
+  messageLabel,
+  operationMessages,
+  payloadSchema,
+  protocolOf,
+  schemaOf,
+} from "./async.ts";
+import type { MessageSample } from "./async-snippets.ts";
+import { asyncSampleLanguages } from "./async-snippets.ts";
+import Authorization from "./Authorization.astro";
+import Bindings from "./Bindings.astro";
+import { exampleValue, type SchemaLike, toJson } from "./helpers.ts";
+import MethodBadge from "./MethodBadge.astro";
+import PanelTabs from "./PanelTabs.astro";
+import ParametersTable from "./ParametersTable.astro";
+import SchemaTable from "./SchemaTable.astro";
+import type { SecuritySchemeLike } from "./security.ts";
+import { resolveAsyncApiSecurity } from "./security.ts";
+
+/**
+ * The AsyncAPI front-end of the operation page: message payloads instead of
+ * request/response, channel parameters instead of path/query, protocol
+ * bindings, and binding-aware samples in the right rail. Everything below the
+ * dispatch — schema tables, parameter rows, authorization, the tabbed panels —
+ * is the same component set the OpenAPI operation renders.
+ */
+interface Props {
+  source: string;
+  id: string;
+}
+
+const { source, id } = Astro.props;
+const spec = specs[source];
+const ref = spec?.operations[id];
+const document = (spec?.document ?? {}) as AsyncApiDocument;
+const operation = ref ? asyncApiOperationObject(document, ref) : undefined;
+const channel = ref?.channelId
+  ? document.channels?.[ref.channelId]
+  : undefined;
+
+const schemas = (document.components?.schemas ?? {}) as Record<
+  string,
+  SchemaLike
+>;
+const servers = channelServers(channel, document);
+const security = resolveAsyncApiSecurity(
+  asyncApiSecurityEntries(operation, servers),
+  document.components?.securitySchemes as
+    | Record<string, SecuritySchemeLike>
+    | undefined
+);
+const parameters = channelParameters(channel, document);
+const messages = operation ? operationMessages(operation, channel, document) : [];
+const protocol = protocolOf(operation, channel, servers);
+
+/** Declared example first, else a sampled value from the payload schema. */
+const exampleOf = (message: (typeof messages)[number]["message"]): unknown =>
+  message.examples?.[0]?.payload ?? exampleValue(payloadSchema(message), schemas);
+
+const messagePanels = await Promise.all(
+  messages.map(async (named, index) => {
+    const example = exampleOf(named.message);
+    return {
+      html:
+        example === undefined || example === null
+          ? null
+          : await highlightCode(toJson(example), "json", {
+              icons: false,
+              themes: data.config.codeThemes,
+            }),
+      key: `message-${index}`,
+      label: messageLabel(named),
+      text: named.message.summary || "No example payload.",
+    };
+  })
+);
+
+const sample: MessageSample | null = ref
+  ? {
+      action: ref.method === "send" ? "send" : "receive",
+      address: ref.path,
+      payload: messages.length > 0 ? exampleOf(messages[0].message) : undefined,
+      server: servers[0],
+    }
+  : null;
+const languages = asyncSampleLanguages(spec?.codeSamples ?? [], protocol);
+const samplePanels = sample
+  ? await Promise.all(
+      languages.map(async (language) => ({
+        html: await highlightCode(language.build(sample), language.lang, {
+          icons: false,
+          themes: data.config.codeThemes,
+        }),
+        key: language.id,
+        label: language.label,
+      }))
+    )
+  : [];
+
+const operationBindings = bindingGroups(operation?.bindings);
+const channelBindings = bindingGroups(channel?.bindings);
+---
+
+{
+  !(spec && ref && operation) ? (
+    <div class="text-muted-foreground">This API operation could not be found.</div>
+  ) : (
+    <div class="not-prose">
+      <div class="mb-6 flex flex-wrap items-center gap-3">
+        <MethodBadge method={ref.method} />
+        <code class="break-all font-mono text-foreground text-sm">
+          {ref.path}
+        </code>
+        {ref.deprecated && (
+          <span class="font-medium text-[0.625rem] text-orange-600 uppercase tracking-wide dark:text-orange-400">
+            deprecated
+          </span>
+        )}
+      </div>
+      <div class="grid grid-cols-1 items-start gap-x-10 gap-y-8 xl:grid-cols-[minmax(0,1fr)_minmax(0,28rem)]">
+        <div>
+          <Authorization security={security} />
+          <ParametersTable parameters={parameters} schemas={schemas} />
+          {messages.map((named) => {
+            const payload = payloadSchema(named.message);
+            // 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);
+            return (
+              <section class="mt-6">
+                <div
+                  aria-level="2"
+                  class="mb-2 font-semibold text-foreground text-sm"
+                  role="heading"
+                >
+                  {messages.length > 1
+                    ? `Message: ${messageLabel(named)}`
+                    : "Message"}
+                </div>
+                {named.message.description && (
+                  <p class="mb-2 text-muted-foreground text-sm">
+                    {named.message.description}
+                  </p>
+                )}
+                {named.message.contentType && (
+                  <div class="mb-2 text-muted-foreground text-xs">
+                    <code class="rounded bg-muted px-1 py-0.5">
+                      {named.message.contentType}
+                    </code>
+                  </div>
+                )}
+                {payload && (
+                  <div class="not-prose rounded-blume border border-border px-4 py-3">
+                    <SchemaTable
+                      expandAll={spec.expandSchemas}
+                      schema={payload}
+                      schemas={schemas}
+                    />
+                  </div>
+                )}
+                {/* Payload is optional on a message — only a payload that
+                    failed to unwrap earns the can't-render note. */}
+                {named.message.payload !== undefined && !payload && (
+                  <p class="text-muted-foreground text-sm">
+                    The payload uses a schema format this reference can't
+                    render inline.
+                  </p>
+                )}
+                {named.message.headers && (
+                  <div class="mt-3">
+                    <div class="mb-1 font-medium text-muted-foreground text-xs uppercase tracking-wide">
+                      Headers
+                    </div>
+                    {headers ? (
+                      <div class="not-prose rounded-blume border border-border px-4 py-3">
+                        <SchemaTable
+                          expandAll={spec.expandSchemas}
+                          schema={headers}
+                          schemas={schemas}
+                        />
+                      </div>
+                    ) : (
+                      <p class="text-muted-foreground text-sm">
+                        The headers use a schema format this reference can't
+                        render inline.
+                      </p>
+                    )}
+                  </div>
+                )}
+                {messageBindings.length > 0 && (
+                  <Bindings
+                    expandAll={spec.expandSchemas}
+                    groups={messageBindings}
+                    schemas={schemas}
+                    title="Message bindings"
+                  />
+                )}
+              </section>
+            );
+          })}
+          <Bindings
+            expandAll={spec.expandSchemas}
+            groups={operationBindings}
+            schemas={schemas}
+            title="Operation bindings"
+          />
+          <Bindings
+            expandAll={spec.expandSchemas}
+            groups={channelBindings}
+            schemas={schemas}
+            title="Channel bindings"
+          />
+        </div>
+        {(samplePanels.length > 0 || messagePanels.length > 0) && (
+          <div class="xl:sticky xl:top-24 xl:self-start">
+            <div class="not-prose flex flex-col gap-6">
+              <PanelTabs copy heading="Example" panels={samplePanels} />
+              <PanelTabs heading="Message" panels={messagePanels} />
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/components/openapi/Bindings.astro

@@ -0,0 +1,89 @@
+---
+import type { BindingGroup } from "./async.ts";
+import type { SchemaLike } from "./helpers.ts";
+import SchemaTable from "./SchemaTable.astro";
+
+/**
+ * Protocol binding fields as a key/value list, one group per protocol
+ * (`kafka`, `ws`, `mqtt`, …). Schema-shaped values — the ws binding's `query`
+ * and `headers` — render as nested schema tables; everything else as code.
+ */
+interface Props {
+  title: string;
+  groups: BindingGroup[];
+  schemas: Record<string, SchemaLike>;
+  expandAll?: boolean;
+}
+
+const { title, groups, schemas, expandAll = false } = Astro.props;
+
+// A bare `type` key is not enough — binding sub-objects carry protocol enums
+// there (the AMQP exchange's `type: "topic"`), so only a JSON-Schema type
+// value counts.
+const SCHEMA_TYPES = new Set([
+  "array",
+  "boolean",
+  "integer",
+  "null",
+  "number",
+  "object",
+  "string",
+]);
+
+const isSchemaish = (value: unknown): value is SchemaLike => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  if ("properties" in value || "$ref" in value) {
+    return true;
+  }
+  const { type } = value as { type?: unknown };
+  return typeof type === "string" && SCHEMA_TYPES.has(type);
+};
+---
+
+{
+  groups.length > 0 && (
+    <section class="mt-6">
+      <div
+        aria-level="2"
+        class="mb-2 font-semibold text-foreground text-sm"
+        role="heading"
+      >
+        {title}
+      </div>
+      {groups.map((group) => (
+        <div class="not-prose mb-3 rounded-blume border border-border px-4 last:mb-0">
+          <div class="flex items-baseline gap-2 border-border py-3">
+            <code class="font-mono font-semibold text-foreground text-sm">
+              {group.protocol}
+            </code>
+          </div>
+          {group.rows.map((row) => (
+            <div class="border-border border-t py-3">
+              <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+                <code class="font-mono text-foreground text-sm">{row.name}</code>
+                {!isSchemaish(row.value) && (
+                  <code class="rounded bg-muted px-1 py-0.5 text-foreground text-xs">
+                    {typeof row.value === "string"
+                      ? row.value
+                      : JSON.stringify(row.value)}
+                  </code>
+                )}
+              </div>
+              {isSchemaish(row.value) && (
+                <div class="mt-2">
+                  <SchemaTable
+                    expandAll={expandAll}
+                    schema={row.value}
+                    schemas={schemas}
+                  />
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      ))}
+    </section>
+  )
+}

package/src/components/openapi/MethodBadge.astro

@@ -15,6 +15,9 @@ const COLORS: Record<string, string> = {
   PATCH: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
   POST: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
   PUT: "bg-orange-500/15 text-orange-700 dark:text-orange-300",
+  // AsyncAPI actions.
+  RECEIVE: "bg-teal-500/15 text-teal-700 dark:text-teal-300",
+  SEND: "bg-violet-500/15 text-violet-700 dark:text-violet-300",
 };
 const color = COLORS[upper] ?? "bg-muted text-muted-foreground";
 ---

package/src/components/openapi/Operation.astro

@@ -14,6 +14,7 @@ import {
   type SecuritySchemeLike,
 } from "./security.ts";
 import { buildRequestSample, sampleLanguages } from "./snippets.ts";
+import AsyncApiOperation from "./AsyncApiOperation.astro";
 import Authorization from "./Authorization.astro";
 import MethodBadge from "./MethodBadge.astro";
 import ParametersTable from "./ParametersTable.astro";
@@ -57,6 +58,9 @@ interface FullOperation {
 const { source, id } = Astro.props;
 const spec = specs[source];
 const ref = spec?.operations[id];
+// The AsyncAPI front-end renders its own body; the lookups below are
+// OpenAPI-shaped (paths, request/response) and resolve to nothing for it.
+const isAsyncApi = spec?.kind === "asyncapi";
 
 const doc = (spec?.document ?? {}) as {
   paths?: Record<
@@ -113,9 +117,10 @@ const sample =
     : null;
 const languages = sampleLanguages(spec?.codeSamples ?? []);
 ---
-
 {
-  !(spec && ref && operation) ? (
+  isAsyncApi ? (
+    <AsyncApiOperation id={id} source={source} />
+  ) : !(spec && ref && operation) ? (
     <div class="text-muted-foreground">This API operation could not be found.</div>
   ) : (
     <div class="not-prose">