blume 2.0.3 → 2.1.1

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

@@ -9,14 +9,63 @@ interface PagefindResult {
   }>;
 }
 
-interface PagefindModule {
+/** One Pagefind instance: a page language's index, plus any merged into it. */
+interface PagefindInstance {
+  mergeIndex: (
+    url: string,
+    options: { baseUrl: string; language: string }
+  ) => Promise<void>;
   search: (query: string) => Promise<{ results: PagefindResult[] }>;
 }
 
+interface PagefindModule {
+  createInstance: (options: {
+    basePath: string;
+    baseUrl: string;
+  }) => PagefindInstance;
+}
+
+/** `pagefind-entry.json`: the bundle's index for each language. */
+interface PagefindEntry {
+  languages: Record<string, { page_count: number }>;
+}
+
+// Pagefind names each page after its built file (`quickstart/index.html`), so
+// its URLs end in a slash. Blume serves pages without one (`trailingSlash:
+// "never"`): hosts redirect the slashed URL, and `blume preview` 404s it.
+const TRAILING_SLASH = /(?<=.)\/(?=[#?]|$)/u;
+
+/**
+ * The language whose index Pagefind loads for a page, picked the way its
+ * `findIndex` does: the page's own, else its base language (`pt` for
+ * `pt-br`), else the language with the most pages (a locale with no
+ * translated pages has no index of its own).
+ */
+const loadedLanguage = (
+  languages: PagefindEntry["languages"],
+  language: string
+): string | undefined => {
+  const [base = language] = language.split("-");
+  if (languages[language]) {
+    return language;
+  }
+  if (languages[base]) {
+    return base;
+  }
+  return Object.entries(languages).toSorted(
+    ([, a], [, b]) => b.page_count - a.page_count
+  )[0]?.[0];
+};
+
 /**
  * Pagefind: load the index emitted into the built site and query it. The bundle
  * lives in the output (not `node_modules`), so it is imported at runtime by URL
  * — which is why this only works in the production build, not `dev`.
+ *
+ * Pagefind keeps an index per language and searches the one for the page's
+ * `<html lang>`, which Blume sets to the locale the dialog scopes to. A
+ * search scoped to a locale is that index alone; a search across every
+ * language (no `locale`) merges every other language's index into it.
  */
 export const createSearch = async (opts: {
   url: string;
@@ -24,25 +73,85 @@ export const createSearch = async (opts: {
   // 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.
+  // whose export contract (`createInstance()`) is fixed by pagefind.
   // oxlint-disable-next-line react-doctor/no-dynamic-import-path
   const pagefind = (await import(
     /* @vite-ignore */
     opts.url
   )) as PagefindModule;
+  // The bundle's folder, which holds the entry file and every language's index.
+  const bundle = new URL("./", new URL(opts.url, document.baseURI));
+  // `baseUrl` "/" keeps result URLs base-less routes, like every other
+  // provider's: by default Pagefind prefixes the folder the bundle is served
+  // under, and the dialog adds the deployment base itself.
+  const create = (): PagefindInstance =>
+    pagefind.createInstance({ basePath: bundle.pathname, baseUrl: "/" });
+
+  // Every language's index: the page's own, and every other one merged in.
+  const everyLanguage = async (language: string): Promise<PagefindInstance> => {
+    const instance = create();
+    const response = await fetch(new URL("pagefind-entry.json", bundle));
+    // SAFETY: the entry file is the one Pagefind wrote into this bundle.
+    const { languages } = (await response.json()) as PagefindEntry;
+    const own = loadedLanguage(languages, language);
+    // Pagefind skips a merge whose path its own `basePath` starts with, as
+    // the same index twice, so the bundle is merged by its full URL.
+    await Promise.all(
+      Object.keys(languages)
+        .filter((code) => code !== own)
+        .map((code) =>
+          instance.mergeIndex(bundle.href, { baseUrl: "/", language: code })
+        )
+    );
+    return instance;
+  };
+
+  // Pagefind reads the page's language once, when an instance is created. A
+  // client-side language switch changes the page's language without a
+  // reload, so each language gets its own instance, created on its first
+  // search: after the switch, search moves to the new page's index. The
+  // every-language instance is one for the whole page load.
+  const instances = new Map<string, Promise<PagefindInstance>>();
+  const cached = (
+    key: string,
+    load: () => Promise<PagefindInstance>
+  ): Promise<PagefindInstance> => {
+    const existing = instances.get(key);
+    if (existing) {
+      return existing;
+    }
+    const loading = (async () => {
+      try {
+        return await load();
+      } catch (error) {
+        // A failed load (the entry file's fetch, say) is forgotten, so the
+        // next search retries it.
+        instances.delete(key);
+        throw error;
+      }
+    })();
+    instances.set(key, loading);
+    return loading;
+  };
+
   // 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);
+  return async (query, options) => {
+    // Lowercased like Pagefind's own reading, which names the entry's indexes.
+    const language = document.documentElement.lang.toLowerCase() || "unknown";
+    const instance = await (options?.locale
+      ? cached(language, () => Promise.resolve(create()))
+      : cached("*", () => everyLanguage(language)));
+    const response = await instance.search(query);
     const docs = await Promise.all(
       response.results.slice(0, SEARCH_LIMIT).map((result) => result.data())
     );
     const hits = docs.map((doc) => ({
       excerpt: sanitizeExcerpt(doc.excerpt),
       title: highlight(doc.meta?.title ?? doc.url, query),
-      url: doc.url,
+      url: doc.url.replace(TRAILING_SLASH, ""),
     }));
     return { hits, sections: [] };
   };

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

@@ -43,6 +43,18 @@ export type SearchFn = (
   }
 ) => Promise<SearchResult>;
 
+/** What a caller tells `createSearch` (`blume:search-client`) about its queries. */
+export interface SearchClientOptions {
+  /**
+   * The queries come from a reader typing, as in the search dialog, so each
+   * one supersedes the last. The server-proxied client (Mixedbread), whose
+   * endpoint is rate-limited, then waits for a pause in typing before it
+   * sends a query and aborts the one a newer query supersedes. Other
+   * providers ignore it.
+   */
+  typing?: boolean;
+}
+
 /** A document in the client-loaded `blume-search.json` index. */
 export interface IndexedDocument {
   route: string;
@@ -53,8 +65,28 @@ export interface IndexedDocument {
   section?: string;
   locale?: string;
   version?: string;
+  /** The page's relevance multiplier (`search.boost`). */
+  boost?: number;
+  /** Extra terms the page is found by (`search.keywords`). */
+  keywords?: string[];
 }
 
+/** Something ranked with a relevance score, and the page it belongs to. */
+export interface ScoredMatch<Match> {
+  boost?: number;
+  match: Match;
+  score: number;
+}
+
+/**
+ * Re-rank matches by score times their page's `search.boost`. The sort is
+ * stable, so equal scores keep the provider's order.
+ */
+export const byBoost = <Match>(scored: ScoredMatch<Match>[]): Match[] =>
+  scored
+    .toSorted((a, b) => b.score * (b.boost ?? 1) - a.score * (a.boost ?? 1))
+    .map(({ match }) => match);
+
 /** Max results surfaced in the dialog. */
 export const SEARCH_LIMIT = 12;
 

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

@@ -17,10 +17,19 @@ interface TypesenseRecord extends Record<string, unknown> {
  * key. Documents are imported at build time by the sync step. Every adapter
  * option Blume doesn't read (`connectionTimeoutSeconds`, `numRetries`, …) is
  * the site's own client option and goes to the `Client` untouched; the named
- * connection options still decide `apiKey` and `nodes`.
+ * connection options still decide `apiKey` and `nodes`. `locale` is the
+ * sync's: Typesense tokenizes a query for the fields it searches.
  */
 export const createSearch = (opts: TypesenseOptions): SearchFn => {
-  const { apiKey, collection, host, port, protocol, ...clientOptions } = opts;
+  const {
+    apiKey,
+    collection,
+    host,
+    locale: _locale,
+    port,
+    protocol,
+    ...clientOptions
+  } = opts;
   const client = new Client({
     ...clientOptions,
     apiKey,
@@ -34,7 +43,14 @@ export const createSearch = (opts: TypesenseOptions): SearchFn => {
         {
           per_page: SEARCH_LIMIT,
           q: query,
-          query_by: "title,description,content",
+          query_by: "title,keywords,description,content",
+          // Relevance first, then each page's `search.boost` among pages that
+          // match equally well: a boost settles a tie without floating a page
+          // over a better match. Bucketing the relevance instead
+          // (`_text_match(buckets: 10)`) ranks by boost alone inside each
+          // bucket, so at equal boosts a bucket falls back to indexing order
+          // and the best match can land behind weaker ones.
+          sort_by: "_text_match:desc,boost:desc",
           // The sync marks `locale` and `version` as facets so hosted results
           // scope to the active language and the viewed docs version (the
           // current docs upload as "current").

package/src/components/openapi/AsyncApiOperation.astro

@@ -7,11 +7,12 @@ import { asyncApiOperationObject } from "../../openapi/asyncapi.ts";
 import { operationOf, specOf } from "../../openapi/model.ts";
 import { highlightCode } from "../../markdown/index.ts";
 import {
-  asyncApiSecurityEntries,
+  asyncApiSecurity,
   bindingGroups,
   channelParameters,
-  channelServers,
+  kafkaTopic,
   messageLabel,
+  namedChannelServers,
   operationMessages,
   payloadSchema,
   protocolOf,
@@ -33,7 +34,6 @@ 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";
 import OperationPanel from "./OperationPanel.astro";
 
 /**
@@ -61,9 +61,11 @@ const schemas = (document.components?.schemas ?? {}) as Record<
   string,
   SchemaLike
 >;
-const servers = channelServers(channel, document);
-const security = resolveAsyncApiSecurity(
-  asyncApiSecurityEntries(operation, servers),
+const namedServers = namedChannelServers(channel, document);
+const servers = namedServers.map(({ server }) => server);
+const security = asyncApiSecurity(
+  operation,
+  namedServers,
   document.components?.securitySchemes as
     | Record<string, SecuritySchemeLike>
     | undefined
@@ -96,10 +98,15 @@ const messagePanels = await Promise.all(
 
 // One derived model feeds the static default sample, the composer form, and
 // (client-side) the live samples + WebSocket frame — they can never drift.
+// A Kafka channel binding's `topic` names the real topic when the address
+// doesn't, so the samples use it.
+const topic =
+  protocol === "kafka" ? kafkaTopic(channel, document.components) : undefined;
 const model = ref
   ? messageModel({
       action: ref.method === "send" ? "send" : "receive",
-      address: ref.path,
+      address: topic ?? ref.path,
+      components: document.components,
       messages,
       parameters,
       protocol,

package/src/components/openapi/Authorization.astro

@@ -28,6 +28,13 @@ const { security } = Astro.props;
           Optional — this operation also accepts unauthenticated requests.
         </p>
       )}
+      {security.unauthenticatedServers &&
+        security.unauthenticatedServers.length > 0 && (
+          <p class="mb-2 text-muted-foreground text-sm">
+            No authorization needed on{" "}
+            {security.unauthenticatedServers.join(", ")}.
+          </p>
+        )}
       {security.alternatives.map((alternative, index) => (
         <>
           {index > 0 && (
@@ -47,6 +54,9 @@ const { security } = Astro.props;
                     <span class="text-muted-foreground text-xs">
                       {schemeLabel(resolved)}
                       {carrier ? ` · ${carrier.in}` : ""}
+                      {resolved.servers
+                        ? ` · on ${resolved.servers.join(", ")}`
+                        : ""}
                     </span>
                     {!security.optional && (
                       <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">

package/src/components/openapi/GraphqlOperation.astro

@@ -19,10 +19,12 @@ import {
   exampleVariables,
   graphqlPlaygroundModel,
   graphqlRoutes,
+  graphqlSecurity,
 } from "./graphql-helpers.ts";
 import { buildRequest, defaultValues } from "./request.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import { sampleLanguages } from "./snippets.ts";
+import Authorization from "./Authorization.astro";
 import Description from "./Description.astro";
 import GraphqlChip from "./GraphqlChip.astro";
 import GraphqlFieldsTable from "./GraphqlFieldsTable.astro";
@@ -107,6 +109,7 @@ const responsePanels =
     : [];
 
 const returnRoute = field ? routes.get(field.type.name) : undefined;
+const security = spec ? graphqlSecurity(spec) : undefined;
 ---
 
 {
@@ -134,6 +137,7 @@ const returnRoute = field ? routes.get(field.type.name) : undefined;
               Deprecated: <span set:text={field.deprecationReason} />
             </p>
           )}
+          {security && <Authorization security={security} />}
           <GraphqlFieldsTable
             routes={routes}
             rows={field.args}
@@ -169,6 +173,7 @@ const returnRoute = field ? routes.get(field.type.name) : undefined;
                 model={model}
                 operation={id}
                 proxy={spec.playground.proxy}
+                proxyConfig="graphql"
                 slug={spec.slug}
               />
             )}

package/src/components/openapi/Operation.astro

@@ -1,6 +1,6 @@
 ---
 import specs from "blume:openapi";
-import { operationOf, specOf } from "../../openapi/model.ts";
+import { HTTP_METHODS, operationOf, specOf } from "../../openapi/model.ts";
 import {
   mergeParameters,
   type ParameterLike,
@@ -21,10 +21,13 @@ import {
   type SecuritySchemeLike,
 } from "./security.ts";
 import { DEPRECATED_LABEL_CLASS } from "../colors.ts";
+import { customCodeSamples } from "./code-samples.ts";
+import type { CodeSamplesCarrier } from "./code-samples.ts";
 import { sampleLanguages } from "./snippets.ts";
 import AsyncApiOperation from "./AsyncApiOperation.astro";
 import GraphqlOperation from "./GraphqlOperation.astro";
 import Authorization from "./Authorization.astro";
+import Description from "./Description.astro";
 import MethodBadge from "./MethodBadge.astro";
 import ParametersTable from "./ParametersTable.astro";
 import Playground from "./Playground.astro";
@@ -57,7 +60,18 @@ interface ResponseLike {
   content?: Record<string, MediaTypeLike>;
 }
 
-interface FullOperation {
+/**
+ * One callback: a map of runtime URL expressions
+ * (`{$request.body#/callbackUrl}`) to the path item the API will call there,
+ * or a `$ref` to one under `components.callbacks`.
+ */
+type CallbackLike = { $ref?: string } & Record<
+  string,
+  Record<string, unknown> | string | undefined
+>;
+
+interface FullOperation extends CodeSamplesCarrier {
+  callbacks?: Record<string, CallbackLike>;
   summary?: string;
   description?: string;
   deprecated?: boolean;
@@ -77,15 +91,17 @@ const ref = spec ? operationOf(spec, id) : undefined;
 const isAsyncApi = spec?.kind === "asyncapi";
 const isGraphql = spec?.kind === "graphql";
 
+type PathItemLike = Record<string, unknown> & {
+  parameters?: ParameterLike[];
+  servers?: ServerLike[];
+};
+
 const doc = (spec?.document ?? {}) as {
-  paths?: Record<
-    string,
-    Record<string, unknown> & {
-      parameters?: ParameterLike[];
-      servers?: ServerLike[];
-    }
-  >;
+  paths?: Record<string, PathItemLike>;
+  // OpenAPI 3.1 webhooks: requests the API sends, keyed by name.
+  webhooks?: Record<string, PathItemLike>;
   components?: {
+    callbacks?: Record<string, CallbackLike>;
     schemas?: Record<string, SchemaLike>;
     parameters?: Record<string, ParameterLike>;
     requestBodies?: Record<string, RequestBodyLike>;
@@ -95,7 +111,12 @@ const doc = (spec?.document ?? {}) as {
   security?: SecurityRequirementLike[];
   servers?: ServerLike[];
 };
-const pathItem = ref ? doc.paths?.[ref.path] : undefined;
+const isWebhook = ref?.webhook === true;
+const pathItem = ref
+  ? isWebhook
+    ? doc.webhooks?.[ref.path]
+    : doc.paths?.[ref.path]
+  : undefined;
 const operation = (
   pathItem && ref ? pathItem[ref.method] : undefined
 ) as FullOperation | undefined;
@@ -110,6 +131,10 @@ const params = mergeParameters(
 const requestBody = operation?.requestBody
   ? resolveComponentRef(operation.requestBody, components, "requestBodies")
   : undefined;
+// A request body table leaves out `readOnly` fields. A webhook's or
+// callback's body is a request the API sends, so it reads like a response
+// (and like its payload example): `readOnly` fields in, `writeOnly` out.
+const bodyDirection = isWebhook ? "response" : "request";
 const responses = Object.fromEntries(
   Object.entries(operation?.responses ?? {}).map(([status, response]) => [
     status,
@@ -118,14 +143,16 @@ const responses = Object.fromEntries(
 );
 
 const security = resolveSecurity(
-  effectiveSecurity(operation?.security, doc.security),
+  effectiveSecurity(operation?.security, doc.security, isWebhook),
   doc.components?.securitySchemes
 );
 
 // One derived model feeds the static default sample, the playground form,
-// and (client-side) the live samples + fetch — they can never drift apart.
+// and (client-side) the live samples + fetch — they can never drift apart. A
+// webhook has none: the API sends it, so there is nothing for a reader to
+// call, and its rail shows the payload instead.
 const model =
-  ref && operation
+  ref && operation && !isWebhook
     ? operationModel({
         components,
         method: ref.method,
@@ -145,6 +172,70 @@ const model =
     : null;
 const sample = model ? buildRequest(model, defaultValues(model)) : null;
 const languages = sampleLanguages(spec?.codeSamples ?? []);
+// The spec's own `x-codeSamples`, shown ahead of the generated ones.
+const customSamples = operation ? customCodeSamples(operation) : [];
+
+/** One request the API makes back to the reader, flattened for rendering. */
+interface CallbackEntry {
+  expression: string;
+  key: string;
+  method: string;
+  name: string;
+  operation: FullOperation;
+  /** The callback path item's own parameters, which each method inherits. */
+  pathParameters?: ParameterLike[];
+}
+
+// Callbacks: for each named callback (resolved through
+// `components.callbacks`), each URL expression, each method it declares.
+const callbacks: CallbackEntry[] = Object.entries(
+  operation?.callbacks ?? {}
+).flatMap(([name, raw]) => {
+  const callback = resolveComponentRef(raw, components, "callbacks");
+  return Object.entries(callback).flatMap(([expression, item]) => {
+    if (expression === "$ref" || typeof item !== "object" || item === null) {
+      return [];
+    }
+    return HTTP_METHODS.flatMap((method) => {
+      const entry = item[method];
+      return typeof entry === "object" && entry !== null
+        ? [
+            {
+              expression,
+              key: `${name}-${expression}-${method}`,
+              method,
+              name,
+              // SAFETY: a path item's method entry is an operation object; the
+              // object check above guards a spec that put a scalar there.
+              operation: entry as FullOperation,
+              // SAFETY: the object check above passed, and a path item's
+              // `parameters` is a parameter list, which `mergeParameters`
+              // reads the way it reads an operation's.
+              pathParameters: (item as PathItemLike).parameters,
+            },
+          ]
+        : [];
+    });
+  });
+});
+
+/** A callback's parameters, request body, and responses, `$ref`s resolved. */
+const callbackParts = (entry: CallbackEntry) => ({
+  parameters: mergeParameters(
+    entry.pathParameters,
+    entry.operation.parameters,
+    components
+  ),
+  requestBody: entry.operation.requestBody
+    ? resolveComponentRef(entry.operation.requestBody, components, "requestBodies")
+    : undefined,
+  responses: Object.fromEntries(
+    Object.entries(entry.operation.responses ?? {}).map(([status, response]) => [
+      status,
+      resolveComponentRef(response, components, "responses"),
+    ])
+  ),
+});
 ---
 {
   isAsyncApi ? (
@@ -160,6 +251,11 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
         <code class="break-all font-mono text-foreground text-sm">
           {ref.path}
         </code>
+        {isWebhook && (
+          <span class="rounded-md border border-border px-1.5 py-0.5 font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide">
+            Webhook
+          </span>
+        )}
         {operation.deprecated && (
           <span class={DEPRECATED_LABEL_CLASS}>
             deprecated
@@ -172,6 +268,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
           <ParametersTable parameters={params} schemas={schemas} />
           {requestBody && (
             <RequestBody
+              direction={bodyDirection}
               expandAll={spec.expandSchemas}
               requestBody={requestBody}
               schemas={schemas}
@@ -184,7 +281,79 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
               schemas={schemas}
             />
           )}
+          {callbacks.length > 0 && (
+            <section class="mt-10">
+              <div
+                aria-level="2"
+                class="mb-3 font-semibold text-foreground text-lg"
+                role="heading"
+              >
+                Callbacks
+              </div>
+              <div class="flex flex-col gap-6">
+                {callbacks.map((entry) => {
+                  const parts = callbackParts(entry);
+                  return (
+                    <div class="rounded-blume border border-border p-4">
+                      <div
+                        aria-level="3"
+                        class="font-semibold text-foreground"
+                        role="heading"
+                      >
+                        {entry.operation.summary || entry.name}
+                      </div>
+                      <div class="mt-2 flex flex-wrap items-center gap-2">
+                        <MethodBadge method={entry.method} />
+                        <code class="break-all font-mono text-muted-foreground text-xs">
+                          {entry.expression}
+                        </code>
+                      </div>
+                      {entry.operation.description && (
+                        <Description
+                          class="mt-2 text-muted-foreground text-sm"
+                          text={entry.operation.description}
+                        />
+                      )}
+                      <ParametersTable
+                        level={4}
+                        parameters={parts.parameters}
+                        schemas={schemas}
+                      />
+                      {parts.requestBody && (
+                        <RequestBody
+                          direction="response"
+                          expandAll={spec.expandSchemas}
+                          level={4}
+                          requestBody={parts.requestBody}
+                          schemas={schemas}
+                        />
+                      )}
+                      {entry.operation.responses && (
+                        <Responses
+                          expandAll={spec.expandSchemas}
+                          level={4}
+                          responses={parts.responses}
+                          schemas={schemas}
+                        />
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            </section>
+          )}
         </div>
+        {isWebhook && (requestBody?.content || operation.responses) && (
+          <OperationPanel>
+            <RequestPanel
+              components={components}
+              customSamples={customSamples}
+              payload={requestBody?.content}
+              responses={responses}
+              schemas={schemas}
+            />
+          </OperationPanel>
+        )}
         {sample && model && (
           <OperationPanel>
             {spec.playground.enabled && (
@@ -192,11 +361,13 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
                 model={model}
                 operation={id}
                 proxy={spec.playground.proxy}
+                proxyConfig="openapi"
                 slug={spec.slug}
               />
             )}
             <RequestPanel
               components={components}
+              customSamples={customSamples}
               languages={languages}
               responses={responses}
               sample={sample}