blume 1.4.3 → 1.5.0

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">

package/src/components/openapi/PanelTabs.astro

@@ -0,0 +1,131 @@
+---
+/**
+ * The tabbed code-panel chrome shared by the request/response rail (OpenAPI)
+ * and the sample/message rail (AsyncAPI): a heading, a tab per panel, an
+ * optional copy button, and one visible panel at a time. Panels carry either
+ * highlighted `html` or plain fallback `text`. Behavior comes from the
+ * `<blume-panel-tabs>` custom element in `panel.ts`.
+ */
+interface Panel {
+  key: string;
+  label: string;
+  /** Highlighted code HTML; null/undefined renders the `text` fallback. */
+  html?: string | null;
+  /** Plain-text fallback when there is nothing to highlight. */
+  text?: string;
+}
+
+interface Props {
+  heading: string;
+  panels: Panel[];
+  /** Show a copy button that copies the active panel's text. */
+  copy?: boolean;
+  /** Render tab labels in a monospace face (status codes). */
+  mono?: boolean;
+}
+
+const { heading, panels, copy = false, mono = false } = Astro.props;
+
+// A stable per-instance id prefix so tab/tabpanel pairs can reference each
+// other without colliding across the multiple PanelTabs on one page (the
+// heading is unique per rail group; panel keys are unique within a group).
+const NON_ID = /[^a-z0-9]+/gu;
+const idFor = (kind: "tab" | "panel", key: string): string =>
+  ["panel-tabs", heading, kind, key]
+    .map((part) => part.toLowerCase().replace(NON_ID, "-"))
+    .join("-");
+
+// A `.prose` wrapper gives Shiki its scoped token colors; the global style at
+// the foot of this file strips the standalone code block's own box (border,
+// injected copy button, language label) so the code sits flush inside the one
+// panel border.
+const CODE_WRAP = "prose max-w-none text-xs";
+const TAB_CLASS =
+  "-mb-px cursor-pointer border-transparent border-b-2 bg-transparent py-2 font-medium text-muted-foreground text-xs transition-colors hover:text-foreground aria-[selected=true]:border-accent aria-[selected=true]:text-foreground";
+---
+
+{
+  panels.length > 0 && (
+    <div>
+      <div
+        aria-level="3"
+        class="mb-2 font-semibold text-foreground text-sm"
+        role="heading"
+      >
+        {heading}
+      </div>
+      <blume-panel-tabs class="block overflow-hidden rounded-blume border border-border bg-background">
+        <div class="flex items-center justify-between gap-2 border-border border-b px-3">
+          <div class="flex flex-wrap gap-4" role="tablist">
+            {panels.map((panel, index) => (
+              <button
+                aria-controls={idFor("panel", panel.key)}
+                aria-selected={index === 0 ? "true" : "false"}
+                class:list={[TAB_CLASS, mono && "font-mono"]}
+                data-panel-tab={panel.key}
+                id={idFor("tab", panel.key)}
+                role="tab"
+                type="button"
+              >
+                {panel.label}
+              </button>
+            ))}
+          </div>
+          {copy && (
+            <button
+              aria-label={`Copy ${heading.toLowerCase()}`}
+              class="group shrink-0 cursor-pointer rounded px-1.5 py-1 text-muted-foreground text-xs hover:text-foreground"
+              data-panel-copy
+              type="button"
+            >
+              <span class="group-data-[copied]:hidden">Copy</span>
+              <span class="hidden group-data-[copied]:inline">Copied</span>
+            </button>
+          )}
+        </div>
+        {panels.map((panel, index) => (
+          <div
+            aria-labelledby={idFor("tab", panel.key)}
+            class:list={[index === 0 ? "" : "hidden"]}
+            data-panel={panel.key}
+            id={idFor("panel", panel.key)}
+            role="tabpanel"
+          >
+            {panel.html ? (
+              <div class={CODE_WRAP}>
+                <Fragment set:html={panel.html} />
+              </div>
+            ) : (
+              <div class="px-3 py-4 text-muted-foreground text-xs">
+                {panel.text ?? ""}
+              </div>
+            )}
+          </div>
+        ))}
+      </blume-panel-tabs>
+    </div>
+  )
+}
+
+<script>
+  import "./panel.ts";
+</script>
+
+<style is:global>
+  /* Strip the standalone code block's own chrome inside a panel: the border,
+     margin, radius, and the copy button + language label the prose code theme
+     adds — the panel supplies a single border and its own copy button. */
+  blume-panel-tabs pre.astro-code {
+    margin: 0 !important;
+    border: 0 !important;
+    border-radius: 0 !important;
+    background: transparent !important;
+    padding: 0.75rem 1rem !important;
+  }
+  blume-panel-tabs pre.astro-code::before {
+    content: none !important;
+  }
+  blume-panel-tabs [data-blume-copy] {
+    display: none !important;
+  }
+</style>

package/src/components/openapi/ParametersTable.astro

@@ -27,6 +27,8 @@ const SECTIONS: { in: string; title: string }[] = [
   { in: "query", title: "Query parameters" },
   { in: "header", title: "Header parameters" },
   { in: "cookie", title: "Cookie parameters" },
+  // AsyncAPI channel address parameters.
+  { in: "channel", title: "Channel parameters" },
 ];
 
 const groups = SECTIONS.map((section) => ({