blume 1.4.2 → 1.5.0

package/src/components/layout/overrides.ts

@@ -1,4 +1,21 @@
-import type { ComponentOverride } from "../../core/define-components.ts";
+import type {
+  ComponentOverride,
+  IslandDescriptor,
+} from "../../core/define-components.ts";
+
+/** A leftover path string an override resolved to (see `resolveSlot`). */
+const isPathString = (override: ComponentOverride): override is string =>
+  typeof override === "string";
+
+/** An `IslandDescriptor` whose `component` is actually present. */
+const isResolvedIsland = (
+  override: ComponentOverride
+): override is IslandDescriptor =>
+  typeof override === "object" &&
+  override !== null &&
+  "component" in override &&
+  override.component !== undefined &&
+  override.component !== null;
 
 /**
  * Resolve a layout-slot override to the component Astro should render, falling
@@ -15,20 +32,16 @@ export const resolveSlot = <T>(
   override: ComponentOverride | undefined,
   fallback: T
 ): T => {
-  if (
-    override === undefined ||
-    override === null ||
-    typeof override === "string"
-  ) {
+  if (override === undefined || override === null || isPathString(override)) {
     return fallback;
   }
-  if (
-    typeof override === "object" &&
-    "component" in override &&
-    override.component !== undefined &&
-    override.component !== null
-  ) {
+  if (isResolvedIsland(override)) {
+    // SAFETY: `ComponentReference` is untyped (`unknown`); the generated
+    // components map stores real components for this slot, so the descriptor's
+    // component is renderable as the slot's component type.
     return override.component as T;
   }
+  // SAFETY: same untyped `ComponentReference` — a bare value here is the
+  // imported component the config referenced for this slot.
   return override as T;
 };

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

@@ -1,4 +1,4 @@
-import { highlight, SEARCH_LIMIT } from "./types.ts";
+import { highlight, sanitizeExcerpt, SEARCH_LIMIT } from "./types.ts";
 import type { SearchFn } from "./types.ts";
 
 interface PagefindResult {
@@ -23,21 +23,24 @@ 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 */
     opts.url
   )) as PagefindModule;
-  // Pagefind builds its own marked-up excerpt; we keep that and only highlight
-  // the title. It carries no section/breadcrumb data, so pills stay hidden and
-  // the preview pane falls back to the excerpt.
+  // Pagefind builds its own marked-up excerpt; we keep its `<mark>` highlights
+  // (dropping any other markup — the excerpt is rendered via innerHTML) and
+  // only highlight the title ourselves. It carries no section/breadcrumb data,
+  // so pills stay hidden and the preview pane falls back to the excerpt.
   return async (query) => {
     const response = await pagefind.search(query);
     const docs = await Promise.all(
       response.results.slice(0, SEARCH_LIMIT).map((result) => result.data())
     );
     const hits = docs.map((doc) => ({
-      excerpt: doc.excerpt,
+      excerpt: sanitizeExcerpt(doc.excerpt),
       title: highlight(doc.meta?.title ?? doc.url, query),
       url: doc.url,
     }));

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. */
@@ -84,6 +95,38 @@ export const highlight = (text: string, query: string): string => {
     .join("");
 };
 
+// Either a tag-shaped run — an opening `<` with a letter or `/` after it,
+// through the closing `>` (or end of string for an unterminated tag) — or a
+// lone `<`. A run can't span a later `<` (`[^<>]`), so between the two
+// alternatives every `<` in the input lands inside a captured run.
+const ANGLE_RUN = /(?<run><\/?[a-z][^<>]*>?|<)/iu;
+const BARE_MARK = /^<\/?mark>$/iu;
+
+/**
+ * Reduce provider-supplied excerpt markup to the `<mark>` highlighting the
+ * dialog expects. Remote excerpts (Pagefind's index, hosted engines) are
+ * rendered via `innerHTML`, so the output alphabet is pinned: bare
+ * `<mark>`/`</mark>` tags (attributes make even a mark untrusted), text, and
+ * entities. Tag-shaped runs are dropped; every other `<` is escaped, which
+ * renders identically but can't be parsed as markup (`<!--` would otherwise
+ * open a comment in `innerHTML` and swallow the rest of the excerpt). Split on
+ * runs covering every `<` rather than deleting tags in place: a deletion can
+ * splice the text around it into a fresh tag (`<<b>script>` → `<script>`),
+ * while here no `<` survives outside a run, so the only ones emitted are the
+ * bare mark tags. String-level on purpose: this also runs under DOM-less
+ * tests, where DOMPurify/DOMParser don't exist.
+ */
+export const sanitizeExcerpt = (html: string): string =>
+  html
+    .split(ANGLE_RUN)
+    .map((part, index) => {
+      if (index % 2 === 0 || BARE_MARK.test(part)) {
+        return part;
+      }
+      return part === "<" ? "&lt;" : "";
+    })
+    .join("");
+
 /** First index in `text` where any query token matches (case-insensitive). */
 const matchIndex = (text: string, query: string): number => {
   const tokens = queryTokens(query);
@@ -161,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>
+  )
+}