blume 1.4.2 → 1.5.0

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) => ({

package/src/components/openapi/RequestPanel.astro

@@ -3,6 +3,7 @@ import data from "blume:data";
 
 import { highlightCode } from "../../markdown/index.ts";
 import { exampleValue, type SchemaLike, toJson } from "./helpers.ts";
+import PanelTabs from "./PanelTabs.astro";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
 
 interface MediaTypeLike {
@@ -24,27 +25,18 @@ interface Props {
 
 const { sample, languages, responses, schemas } = Astro.props;
 
-// 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";
-const HEADING = "mb-2 font-semibold text-foreground text-sm";
-
-const requestSamples = await Promise.all(
+const requestPanels = await Promise.all(
   languages.map(async (language) => ({
     html: await highlightCode(language.build(sample), language.lang, {
       icons: false,
       themes: data.config.codeThemes,
     }),
-    id: language.id,
+    key: language.id,
     label: language.label,
   }))
 );
 
-const responseEntries = await Promise.all(
+const responsePanels = await Promise.all(
   Object.entries(responses).map(async ([status, response]) => {
     const media =
       Object.entries(response.content ?? {}).find(([type]) =>
@@ -60,116 +52,17 @@ const responseEntries = await Promise.all(
             icons: false,
             themes: data.config.codeThemes,
           });
-    return { description: response.description ?? "", html, status };
+    return {
+      html,
+      key: status,
+      label: status,
+      text: response.description || "No example response.",
+    };
   })
 );
 ---
 
 <div class="not-prose flex flex-col gap-6">
-  {
-    requestSamples.length > 0 && (
-      <div>
-        <div aria-level="3" class={HEADING} role="heading">
-          Request
-        </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 gap-4" role="tablist">
-              {requestSamples.map((entry, index) => (
-                <button
-                  aria-selected={index === 0 ? "true" : "false"}
-                  class={TAB_CLASS}
-                  data-panel-tab={entry.id}
-                  role="tab"
-                  type="button"
-                >
-                  {entry.label}
-                </button>
-              ))}
-            </div>
-            <button
-              aria-label="Copy request"
-              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>
-          {requestSamples.map((entry, index) => (
-            <div
-              class:list={[index === 0 ? "" : "hidden", CODE_WRAP]}
-              data-panel={entry.id}
-            >
-              <Fragment set:html={entry.html} />
-            </div>
-          ))}
-        </blume-panel-tabs>
-      </div>
-    )
-  }
-  {
-    responseEntries.length > 0 && (
-      <div>
-        <div aria-level="3" class={HEADING} role="heading">
-          Response
-        </div>
-        <blume-panel-tabs class="block overflow-hidden rounded-blume border border-border bg-background">
-          <div class="flex flex-wrap gap-4 border-border border-b px-3" role="tablist">
-            {responseEntries.map((entry, index) => (
-              <button
-                aria-selected={index === 0 ? "true" : "false"}
-                class={`${TAB_CLASS} font-mono`}
-                data-panel-tab={entry.status}
-                role="tab"
-                type="button"
-              >
-                {entry.status}
-              </button>
-            ))}
-          </div>
-          {responseEntries.map((entry, index) => (
-            <div
-              class:list={[index === 0 ? "" : "hidden"]}
-              data-panel={entry.status}
-            >
-              {entry.html ? (
-                <div class={CODE_WRAP}>
-                  <Fragment set:html={entry.html} />
-                </div>
-              ) : (
-                <div class="px-3 py-4 text-muted-foreground text-xs">
-                  {entry.description || "No example response."}
-                </div>
-              )}
-            </div>
-          ))}
-        </blume-panel-tabs>
-      </div>
-    )
-  }
+  <PanelTabs copy heading="Request" panels={requestPanels} />
+  <PanelTabs heading="Response" mono panels={responsePanels} />
 </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/async-snippets.ts

@@ -0,0 +1,174 @@
+import type {
+  AsyncApiAction,
+  AsyncApiServerObject,
+} from "../../openapi/asyncapi.ts";
+import { toJson } from "./helpers.ts";
+
+/**
+ * Protocol-aware code samples for AsyncAPI operations — the async counterpart
+ * of `snippets.ts`. Samples are written from the reader's side of the wire:
+ * a `receive` operation means the application receives, so the sample shows
+ * how to *produce* a message; a `send` operation shows how to consume one.
+ * Protocols without a supported tool yield no samples at all — the message
+ * example panel already shows the payload, and fabricating a client for an
+ * unknown binding would be worse than nothing.
+ */
+
+/** Everything a snippet builder needs about one operation. */
+export interface MessageSample {
+  action: AsyncApiAction;
+  /** Channel address, `{param}` templates left intact. */
+  address: string;
+  /** Example payload value (undefined when none could be derived). */
+  payload?: unknown;
+  /** First server the channel is available on, if any. */
+  server?: AsyncApiServerObject;
+}
+
+/** `host[:port]` split apart; MQTT tooling wants them as separate flags. */
+const hostParts = (server?: AsyncApiServerObject) => {
+  const raw = server?.host ?? "localhost";
+  const colon = raw.lastIndexOf(":");
+  if (colon > 0 && /^\d+$/u.test(raw.slice(colon + 1))) {
+    return { host: raw.slice(0, colon), port: raw.slice(colon + 1) };
+  }
+  return { host: raw, port: undefined };
+};
+
+/** POSIX single-quote escaping, matching `snippets.ts`. */
+const shellQuote = (text: string): string =>
+  `'${text.replaceAll("'", String.raw`'\''`)}'`;
+
+const payloadJson = (sample: MessageSample): string =>
+  toJson(sample.payload ?? {});
+
+/** Compact single-line payload for shell `-m`/`echo` arguments. */
+const payloadInline = (sample: MessageSample): string =>
+  JSON.stringify(sample.payload ?? {});
+
+/** `wss://host/path` for a WebSocket channel; the address is the path. */
+const wsUrl = (sample: MessageSample): string => {
+  const { server } = sample;
+  const scheme = server?.protocol === "ws" ? "ws" : "wss";
+  const host = server?.host ?? "localhost";
+  const base = `${server?.pathname ?? ""}/${sample.address}`.replaceAll(
+    /\/+/gu,
+    "/"
+  );
+  return `${scheme}://${host}${base === "/" ? "" : base}`;
+};
+
+const wscatSnippet = (sample: MessageSample): string => {
+  const connect = `wscat -c ${shellQuote(wsUrl(sample))}`;
+  return sample.action === "receive"
+    ? `${connect}\n> ${payloadInline(sample)}`
+    : `# Prints each message as it arrives\n${connect}`;
+};
+
+const webSocketSnippet = (sample: MessageSample): string => {
+  const open = `const socket = new WebSocket(${JSON.stringify(wsUrl(sample))});`;
+  if (sample.action === "receive") {
+    return [
+      open,
+      "",
+      'socket.addEventListener("open", () => {',
+      `  socket.send(JSON.stringify(${payloadJson(sample).replaceAll("\n", "\n  ")}));`,
+      "});",
+    ].join("\n");
+  }
+  return [
+    open,
+    "",
+    'socket.addEventListener("message", (event) => {',
+    "  console.log(JSON.parse(event.data));",
+    "});",
+  ].join("\n");
+};
+
+const kcatSnippet = (sample: MessageSample): string => {
+  const broker = sample.server?.host ?? "localhost:9092";
+  const base = `kcat -b ${shellQuote(broker)} -t ${shellQuote(sample.address)}`;
+  return sample.action === "receive"
+    ? `echo ${shellQuote(payloadInline(sample))} | ${base} -P`
+    : `${base} -C`;
+};
+
+const mosquittoSnippet = (sample: MessageSample): string => {
+  const { host, port } = hostParts(sample.server);
+  const target = `-h ${shellQuote(host)}${port ? ` -p ${port}` : ""} -t ${shellQuote(sample.address)}`;
+  return sample.action === "receive"
+    ? `mosquitto_pub ${target} -m ${shellQuote(payloadInline(sample))}`
+    : `mosquitto_sub ${target} -v`;
+};
+
+/** One renderable sample tool: tab id/label, Shiki language, builder. */
+export interface AsyncSampleLanguage {
+  id: string;
+  label: string;
+  lang: string;
+  build: (sample: MessageSample) => string;
+}
+
+const TOOLS = {
+  js: { build: webSocketSnippet, id: "js", label: "JavaScript", lang: "js" },
+  kcat: { build: kcatSnippet, id: "kcat", label: "kcat", lang: "bash" },
+  mosquitto: {
+    build: mosquittoSnippet,
+    id: "mosquitto",
+    label: "mosquitto",
+    lang: "bash",
+  },
+  wscat: { build: wscatSnippet, id: "wscat", label: "wscat", lang: "bash" },
+} satisfies Record<string, AsyncSampleLanguage>;
+
+type ToolId = keyof typeof TOOLS;
+
+/** The tools appropriate to each protocol binding, in display order. */
+const PROTOCOL_TOOLS = new Map<string, readonly ToolId[]>([
+  ["kafka", ["kcat"]],
+  ["mqtt", ["mosquitto"]],
+  ["ws", ["wscat", "js"]],
+]);
+
+/** Accepted spellings for configured `codeSamples` ids. */
+const ALIASES = new Map<string, ToolId>([
+  ["javascript", "js"],
+  ["kafkacat", "kcat"],
+  ["mosquitto_pub", "mosquitto"],
+  ["mosquitto_sub", "mosquitto"],
+  ["node", "js"],
+  ["typescript", "js"],
+  ["websocket", "js"],
+]);
+
+/**
+ * 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.
+ */
+export const asyncSampleLanguages = (
+  ids: string[],
+  protocol?: string
+): AsyncSampleLanguage[] => {
+  const candidates = PROTOCOL_TOOLS.get(protocol ?? "") ?? [];
+  if (candidates.length === 0) {
+    return [];
+  }
+  if (ids.length === 0) {
+    return candidates.map((id) => TOOLS[id]);
+  }
+  const chosen: AsyncSampleLanguage[] = [];
+  const seen = new Set<string>();
+  for (const raw of ids) {
+    // Case-insensitive like `sampleLanguages` — the docs spell the tools
+    // `WebSocket`/`mosquitto_pub`, so configured ids arrive in any casing.
+    const id = ALIASES.get(raw.toLowerCase()) ?? raw.toLowerCase();
+    const match = candidates.find((candidate) => candidate === id);
+    if (match && !seen.has(match)) {
+      seen.add(match);
+      chosen.push(TOOLS[match]);
+    }
+  }
+  return chosen;
+};