blume 2.0.2 → 2.1.0

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

@@ -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;
@@ -118,15 +139,18 @@ 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,
         parameters: params,
         path: ref.path,
@@ -144,6 +168,59 @@ 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;
+}
+
+// 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,
+            },
+          ]
+        : [];
+    });
+  });
+});
+
+/** A callback's request body and responses, `$ref`s resolved. */
+const callbackParts = (entry: CallbackEntry) => ({
+  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 ? (
@@ -159,6 +236,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
@@ -183,7 +265,73 @@ 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}
+                        />
+                      )}
+                      {parts.requestBody && (
+                        <RequestBody
+                          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 && (
@@ -195,6 +343,8 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
               />
             )}
             <RequestPanel
+              components={components}
+              customSamples={customSamples}
               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/RequestBody.astro

@@ -17,9 +17,11 @@ interface Props {
   requestBody: RequestBodyLike;
   schemas: Record<string, SchemaLike>;
   expandAll?: boolean;
+  /** The heading's level: 2 on an operation, deeper inside a callback. */
+  level?: number;
 }
 
-const { requestBody, schemas, expandAll = false } = Astro.props;
+const { requestBody, schemas, expandAll = false, level = 2 } = Astro.props;
 
 const entries = Object.entries(requestBody.content ?? {});
 const chosen = entries.find(([type]) => type.includes("json")) ?? entries[0];
@@ -27,11 +29,11 @@ const contentType = chosen?.[0] ?? "application/json";
 const schema = chosen?.[1]?.schema ?? {};
 ---
 
-<section class="mt-8">
+<section class:list={[level > 2 ? "mt-5" : "mt-8"]}>
   <div class="mb-2 flex flex-wrap items-center gap-2">
     <div
-      aria-level="2"
-      class="font-semibold text-foreground text-lg"
+      aria-level={level}
+      class:list={["font-semibold text-foreground", level > 2 ? "text-sm" : "text-lg"]}
       role="heading"
     >
       Request body

package/src/components/openapi/RequestPanel.astro

@@ -3,11 +3,13 @@ import data from "blume:data";
 
 import { highlightCode } from "../../markdown/index.ts";
 import {
+  type ComponentsLike,
   responseExample,
   type SchemaLike,
   type SpecValue,
   toJson,
 } from "./helpers.ts";
+import type { CustomCodeSample } from "./code-samples.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import PanelTabs from "./PanelTabs.astro";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
@@ -24,19 +26,71 @@ interface ResponseLike {
 }
 
 interface Props {
-  sample: RequestSample;
-  languages: SampleLanguage[];
+  /** The document's `components`, which `$ref`'d examples resolve against. */
+  components?: ComponentsLike;
+  /** The spec's hand-written `x-codeSamples`, shown first and never re-rendered live. */
+  customSamples?: CustomCodeSample[];
+  /**
+   * A webhook's body: the rail shows it as a "Payload" example per media
+   * type in place of client code, since the API sends the request.
+   */
+  payload?: Record<string, MediaTypeLike>;
+  sample?: RequestSample;
+  languages?: SampleLanguage[];
   responses: Record<string, ResponseLike>;
   schemas: Record<string, SchemaLike>;
 }
 
-const { sample, languages, responses, schemas } = Astro.props;
-
-const requestPanels = await languageSamplePanels(
-  languages,
+const {
+  components,
+  customSamples = [],
+  payload,
   sample,
-  data.config.codeThemes
+  languages = [],
+  responses,
+  schemas,
+} = Astro.props;
+
+/** A media type's example, highlighted, or null when it has none. */
+const highlightExample = async (media: MediaTypeLike, type: string) => {
+  const example = responseExample(media, schemas, components);
+  if (example === undefined || example === null) {
+    return null;
+  }
+  const json = type.includes("json");
+  return highlightCode(
+    json || typeof example !== "string" ? toJson(example) : example,
+    json ? "json" : "text",
+    { icons: false, themes: data.config.codeThemes }
+  );
+};
+
+// Hand-written samples carry no `lang` key, so the playground leaves them
+// as written when it re-renders the generated ones from the form.
+const customPanels = await Promise.all(
+  customSamples.map(async (custom) => ({
+    html: await highlightCode(custom.source, custom.lang, {
+      icons: false,
+      themes: data.config.codeThemes,
+    }),
+    key: custom.key,
+    label: custom.label,
+  }))
+);
+const payloadPanels = await Promise.all(
+  Object.entries(payload ?? {}).map(async ([type, media]) => ({
+    html: await highlightExample(media, type),
+    key: type,
+    label: type,
+    text: "No example payload.",
+  }))
 );
+const requestPanels = [
+  ...customPanels,
+  ...(sample
+    ? await languageSamplePanels(languages, sample, data.config.codeThemes)
+    : []),
+];
 
 const responsePanels = await Promise.all(
   Object.entries(responses).map(async ([status, response]) => {
@@ -44,7 +98,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
@@ -63,6 +117,7 @@ const responsePanels = await Promise.all(
 ---
 
 <div class="not-prose flex flex-col gap-6">
+  <PanelTabs copy heading="Payload" mono panels={payloadPanels} />
   <PanelTabs copy heading="Request" panels={requestPanels} />
   <PanelTabs heading="Response" mono panels={responsePanels} />
 </div>

package/src/components/openapi/Responses.astro

@@ -17,19 +17,21 @@ interface Props {
   responses: Record<string, ResponseLike>;
   schemas: Record<string, SchemaLike>;
   expandAll?: boolean;
+  /** The heading's level: 2 on an operation, deeper inside a callback. */
+  level?: number;
 }
 
-const { responses, schemas, expandAll = false } = Astro.props;
+const { responses, schemas, expandAll = false, level = 2 } = Astro.props;
 
 const items = Object.entries(responses);
 ---
 
 {
   items.length > 0 && (
-    <section class="mt-8">
+    <section class:list={[level > 2 ? "mt-5" : "mt-8"]}>
       <div
-        aria-level="2"
-        class="mb-3 font-semibold text-foreground text-lg"
+        aria-level={level}
+        class:list={["mb-3 font-semibold text-foreground", level > 2 ? "text-sm" : "text-lg"]}
         role="heading"
       >
         Responses

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-snippets.ts

@@ -157,15 +157,15 @@ const ALIASES = new Map<string, ToolId>([
 /**
  * The sample tools to render for an operation. The protocol picks the
  * candidate set; a non-empty `codeSamples` config filters and orders it
- * (unknown ids are dropped, aliases accepted). No protocol, an unsupported
- * one, or a filter that matches nothing yields no samples.
+ * (unknown ids are dropped, aliases accepted). `false`, no protocol, an
+ * unsupported one, or a filter that matches nothing yields no samples.
  */
 export const asyncSampleLanguages = (
-  ids: string[],
+  ids: string[] | false,
   protocol?: string
 ): AsyncSampleLanguage[] => {
   const candidates = PROTOCOL_TOOLS.get(protocol ?? "") ?? [];
-  if (candidates.length === 0) {
+  if (ids === false || candidates.length === 0) {
     return [];
   }
   if (ids.length === 0) {

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;
     }