blume 1.5.0 → 1.5.2

package/src/components/openapi/Playground.astro

@@ -0,0 +1,320 @@
+---
+import { randomUUID } from "node:crypto";
+
+import { paramKey, type PlaygroundModel } from "./request.ts";
+
+/**
+ * The interactive "Try it" panel for one operation. Everything is
+ * server-rendered — a native collapsed `<details>` with plain labelled
+ * inputs, keyboard-operable with zero JS — and the client module only loads
+ * when the reader first opens it (see the loader script at the foot of this
+ * file). The request model the client consumes is embedded as JSON so the
+ * lazy chunk needs no data fetch.
+ */
+
+interface Props {
+  model: PlaygroundModel;
+  /** Proxy route for the send, or false to fetch the API directly. */
+  proxy: string | false;
+  /** Spec slug + operation key form the per-operation localStorage key. */
+  slug: string;
+  operation: string;
+}
+
+const { model, proxy, slug, operation } = Astro.props;
+
+// `</script>`-proof embedding: `<` only ever occurs inside JSON strings,
+// where the \u escape is equivalent, so a spec description can never close
+// the model script early and inject markup.
+const modelJson = JSON.stringify(model).replaceAll("<", "\\u003c");
+
+// Unique per rendered panel (a page can hold several), so the textarea's
+// aria-describedby can point at ITS error container and no other.
+const bodyErrorsId = `blume-body-errors-${randomUUID()}`;
+
+const LABEL_ROW =
+  "mb-1 flex flex-wrap items-baseline gap-x-1.5 font-medium text-foreground text-xs";
+const FIELD =
+  "w-full rounded border border-border bg-background px-2 py-1.5 font-mono text-foreground text-xs";
+const HINT = "mt-1 block text-muted-foreground text-xs";
+const GROUP = "flex flex-col gap-3";
+const GROUP_HEADING =
+  "font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide";
+const CHECKBOX_ROW =
+  "flex cursor-pointer items-center gap-2 text-foreground text-xs";
+---
+
+<blume-playground
+  class="mb-6 block"
+  data-proxy={proxy || undefined}
+  data-storage-key={`blume-playground:${slug}:${operation}`}
+>
+  <script
+    data-playground-model
+    is:inline
+    set:html={modelJson}
+    type="application/json"
+  />
+  <details
+    class="not-prose rounded-blume border border-border bg-background"
+    data-playground
+  >
+    <summary class="cursor-pointer px-4 py-3 font-semibold text-foreground text-sm">
+      Try it
+    </summary>
+    <div class="flex flex-col gap-5 border-border border-t px-4 py-4">
+      <div class={GROUP}>
+        <div class={GROUP_HEADING}>Server</div>
+        {
+          model.servers.length > 0 && (
+            <label class="block">
+              <span class={LABEL_ROW}>Base URL</span>
+              <select class={FIELD} data-server>
+                {model.servers.map((server) => (
+                  <option value={server}>{server}</option>
+                ))}
+              </select>
+            </label>
+          )
+        }
+        <label class="block">
+          <span class={LABEL_ROW}>Custom base URL</span>
+          <input
+            class={FIELD}
+            data-server-custom
+            placeholder="https://api.example.com"
+            type="text"
+          />
+          <span class={HINT}>Overrides the selected server when set.</span>
+        </label>
+      </div>
+      {
+        model.auth.length > 0 && (
+          <div class={GROUP}>
+            <div class={GROUP_HEADING}>
+              Authorization{model.authOptional && " (optional)"}
+            </div>
+            {model.auth.map((input) =>
+              input.kind === "basic" ? (
+                <div class={GROUP}>
+                  <label class="block">
+                    <span class={LABEL_ROW}>{input.label} username</span>
+                    <input
+                      autocomplete="off"
+                      class={FIELD}
+                      data-auth-username={input.id}
+                      type="text"
+                    />
+                  </label>
+                  <label class="block">
+                    <span class={LABEL_ROW}>{input.label} password</span>
+                    <input
+                      autocomplete="off"
+                      class={FIELD}
+                      data-auth-password={input.id}
+                      type="password"
+                    />
+                  </label>
+                </div>
+              ) : (
+                <label class="block">
+                  <span class={LABEL_ROW}>{input.label}</span>
+                  <input
+                    autocomplete="off"
+                    class={FIELD}
+                    data-auth-value={input.id}
+                    placeholder={input.placeholder}
+                    type="password"
+                  />
+                </label>
+              )
+            )}
+            <label class={CHECKBOX_ROW}>
+              <input data-auth-remember type="checkbox" />
+              Remember on this device
+            </label>
+            <label class={CHECKBOX_ROW}>
+              <input data-samples-auth type="checkbox" />
+              Include my values in samples
+            </label>
+          </div>
+        )
+      }
+      {
+        model.params.length > 0 && (
+          <div class={GROUP}>
+            <div class={GROUP_HEADING}>Parameters</div>
+            {model.params.map((param) => (
+              <label class="block">
+                <span class={LABEL_ROW}>
+                  <code class="font-mono">{param.name}</code>
+                  <span class="text-muted-foreground">{param.in}</span>
+                  {param.required && (
+                    <span
+                      class="text-red-600 dark:text-red-400"
+                      title="required"
+                    >
+                      *
+                    </span>
+                  )}
+                </span>
+                {param.enum ? (
+                  <select
+                    class={FIELD}
+                    data-param={paramKey(param)}
+                    title={param.description}
+                  >
+                    {!param.required && <option value="">—</option>}
+                    {param.enum.map((value) => (
+                      <option selected={value === param.value} value={value}>
+                        {value}
+                      </option>
+                    ))}
+                  </select>
+                ) : (
+                  <input
+                    class={FIELD}
+                    data-param={paramKey(param)}
+                    placeholder={param.type}
+                    title={param.description}
+                    type="text"
+                    value={param.value}
+                  />
+                )}
+                {param.description && (
+                  <span class={HINT} set:text={param.description} />
+                )}
+              </label>
+            ))}
+          </div>
+        )
+      }
+      {
+        model.body && (
+          <div class={GROUP}>
+            <div class={GROUP_HEADING}>
+              Body
+              <span class="ml-1.5 font-mono normal-case">
+                {model.body.contentType}
+              </span>
+            </div>
+            {model.body.fields ? (
+              model.body.fields.map((bodyField) => (
+                <label class="block">
+                  <span class={LABEL_ROW}>
+                    <code class="font-mono">{bodyField.name}</code>
+                    <span class="text-muted-foreground">{bodyField.type}</span>
+                    {bodyField.required && (
+                      <span
+                        class="text-red-600 dark:text-red-400"
+                        title="required"
+                      >
+                        *
+                      </span>
+                    )}
+                  </span>
+                  {bodyField.enum ? (
+                    <select
+                      class={FIELD}
+                      data-body-field={bodyField.name}
+                      title={bodyField.description}
+                    >
+                      {!bodyField.required && <option value="">—</option>}
+                      {bodyField.enum.map((value) => (
+                        <option
+                          selected={value === bodyField.value}
+                          value={value}
+                        >
+                          {value}
+                        </option>
+                      ))}
+                    </select>
+                  ) : (
+                    <input
+                      class={FIELD}
+                      data-body-field={bodyField.name}
+                      placeholder={bodyField.type}
+                      title={bodyField.description}
+                      type="text"
+                      value={bodyField.value}
+                    />
+                  )}
+                  {bodyField.description && (
+                    <span class={HINT} set:text={bodyField.description} />
+                  )}
+                </label>
+              ))
+            ) : (
+              <>
+                <label class="block">
+                  <span class={LABEL_ROW}>Request body</span>
+                  <textarea
+                    aria-describedby={bodyErrorsId}
+                    class={FIELD}
+                    data-body
+                    rows="8"
+                    spellcheck="false">{model.body.example}</textarea
+                  >
+                </label>
+                <div
+                  aria-live="polite"
+                  class="mt-1 flex flex-col gap-0.5 empty:hidden"
+                  data-body-errors
+                  id={bodyErrorsId}
+                />
+              </>
+            )}
+          </div>
+        )
+      }
+      <div>
+        <button
+          class="cursor-pointer rounded-blume bg-accent px-4 py-2 font-medium text-accent-foreground text-sm transition hover:bg-accent/90"
+          data-send
+          type="button"
+        >
+          Send
+        </button>
+      </div>
+      <div
+        aria-live="polite"
+        class="flex flex-col gap-2 empty:hidden"
+        data-response
+      />
+    </div>
+  </details>
+</blume-playground>
+
+<script>
+  // Hydration waits for intent: a collapsed <details> can only fire its first
+  // `toggle` by opening, so the one-shot listener imports the client module —
+  // a separate chunk readers who never try a request never download — and
+  // wires the form. The custom element lives here, not in the client module,
+  // so that module stays import-safe under the test runner.
+  class BlumePlayground extends HTMLElement {
+    connectedCallback() {
+      const details = this.querySelector<HTMLDetailsElement>(
+        "details[data-playground]"
+      );
+      if (!details) {
+        return;
+      }
+      const init = async () => {
+        const { initPlayground } = await import("./playground-client.ts");
+        initPlayground(this);
+      };
+      // A re-attached element (bfcache restore, DOM moves) can arrive with the
+      // panel already open — its first toggle has fired, so a listener alone
+      // would leave a visible form dead.
+      if (details.open) {
+        void init();
+        return;
+      }
+      details.addEventListener("toggle", init, { once: true });
+    }
+  }
+
+  if (!customElements.get("blume-playground")) {
+    customElements.define("blume-playground", BlumePlayground);
+  }
+</script>

package/src/components/openapi/RequestPanel.astro

@@ -33,6 +33,7 @@ const requestPanels = await Promise.all(
     }),
     key: language.id,
     label: language.label,
+    lang: language.id,
   }))
 );
 

package/src/components/openapi/async-snippets.ts

@@ -2,7 +2,6 @@ import type {
   AsyncApiAction,
   AsyncApiServerObject,
 } from "../../openapi/asyncapi.ts";
-import { toJson } from "./helpers.ts";
 
 /**
  * Protocol-aware code samples for AsyncAPI operations — the async counterpart
@@ -12,6 +11,11 @@ import { toJson } from "./helpers.ts";
  * 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.
+ *
+ * Dependency-free for the same reason `snippets.ts` is: the event composer
+ * re-renders these samples live in the browser, so importing anything from
+ * `helpers.ts` would drag openapi-sampler into that lazy chunk (~13 kB) to
+ * pretty-print a payload.
  */
 
 /** Everything a snippet builder needs about one operation. */
@@ -39,15 +43,24 @@ const hostParts = (server?: AsyncApiServerObject) => {
 const shellQuote = (text: string): string =>
   `'${text.replaceAll("'", String.raw`'\''`)}'`;
 
+/**
+ * Indented payload for a snippet that spans lines, matching `toJson`. Only an
+ * absent payload (unparseable editor text) becomes `{}`; a payload of `null`
+ * is what the reader typed and travels as written.
+ */
 const payloadJson = (sample: MessageSample): string =>
-  toJson(sample.payload ?? {});
+  JSON.stringify(sample.payload === undefined ? {} : sample.payload, null, 2);
 
 /** Compact single-line payload for shell `-m`/`echo` arguments. */
 const payloadInline = (sample: MessageSample): string =>
-  JSON.stringify(sample.payload ?? {});
+  JSON.stringify(sample.payload === undefined ? {} : sample.payload);
 
-/** `wss://host/path` for a WebSocket channel; the address is the path. */
-const wsUrl = (sample: MessageSample): string => {
+/**
+ * `wss://host/path` for a WebSocket channel; the address is the path. Exported
+ * because the live composer connects to exactly this URL — the samples and the
+ * connection cannot point at different endpoints.
+ */
+export const webSocketUrl = (sample: MessageSample): string => {
   const { server } = sample;
   const scheme = server?.protocol === "ws" ? "ws" : "wss";
   const host = server?.host ?? "localhost";
@@ -59,14 +72,14 @@ const wsUrl = (sample: MessageSample): string => {
 };
 
 const wscatSnippet = (sample: MessageSample): string => {
-  const connect = `wscat -c ${shellQuote(wsUrl(sample))}`;
+  const connect = `wscat -c ${shellQuote(webSocketUrl(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))});`;
+  const open = `const socket = new WebSocket(${JSON.stringify(webSocketUrl(sample))});`;
   if (sample.action === "receive") {
     return [
       open,

package/src/components/openapi/async.ts

@@ -182,6 +182,7 @@ interface AsyncApiParameterLike extends AsyncApiRefLike {
   description?: string;
   default?: AsyncApiSpecValue;
   enum?: AsyncApiSpecValue[];
+  examples?: AsyncApiSpecValue[];
 }
 
 /**
@@ -213,7 +214,7 @@ export const channelParameters = (
     if (parameter.default !== undefined) {
       schema.default = parameter.default;
     }
-    parameters.push({
+    const lowered: ParameterLike = {
       description: isString(parameter.description)
         ? parameter.description
         : undefined,
@@ -221,7 +222,17 @@ export const channelParameters = (
       name,
       required: true,
       schema,
-    });
+    };
+    // AsyncAPI parameters carry `examples` (an array of strings) rather than
+    // OpenAPI's singular; the first usable one lowers into the shared slot so
+    // the composer can prefill from it.
+    const example = Array.isArray(parameter.examples)
+      ? parameter.examples.find(isString)
+      : undefined;
+    if (example !== undefined) {
+      lowered.example = example;
+    }
+    parameters.push(lowered);
   }
   return parameters;
 };

package/src/components/openapi/message-composer.ts

@@ -0,0 +1,242 @@
+/**
+ * Client logic for the event "Try it" composer, loaded lazily on the first open
+ * of the `<details data-composer>` disclosure (see MessageComposer.astro — the
+ * custom-element loader lives there so this module stays import-safe in
+ * tests). One message model drives everything: the same {@link buildMessage}
+ * output feeds the protocol-aware samples, the connect URL, and the frame that
+ * goes on the wire, so what a reader copies is what the panel sends.
+ *
+ * Frames are rendered through `textContent` — a broker echoing HTML back must
+ * never execute in the docs page.
+ */
+
+import { asyncSampleLanguages, webSocketUrl } from "./async-snippets.ts";
+import type { MessageModel, MessageValues } from "./message.ts";
+import { buildMessage, messageFrame } from "./message.ts";
+import { validateJson } from "./validate-json.ts";
+import type { WsFrame, WsState } from "./ws-client.ts";
+import { createWsClient } from "./ws-client.ts";
+
+/** Convention used across the OpenAPI components for error-severity text. */
+const ERROR_TEXT = "text-red-600 text-xs dark:text-red-400";
+
+/** The status line's normal (non-error) styling. */
+const MUTED_TEXT = "text-muted-foreground text-xs";
+
+/**
+ * A failed WebSocket handshake gives the page no reason — the browser withholds
+ * it — so the status line explains the causes a docs author can act on instead
+ * of showing a bare "error".
+ */
+const ERROR_MESSAGE =
+  "The connection failed. The broker may reject requests from this origin, " +
+  "require credentials the URL doesn't carry, or be unreachable from here.";
+
+/** Wall-clock prefix for a logged frame, e.g. `14:03:11`. */
+const stamp = (at: number): string => new Date(at).toLocaleTimeString();
+
+/**
+ * Wire the composer inside `root` (the `<blume-message-composer>` element).
+ * Keeps the samples in sync with the form, validates the payload, and — for
+ * WebSocket bindings only — drives a live connection.
+ */
+export const initComposer = (root: HTMLElement): void => {
+  const modelScript = root.querySelector("script[data-composer-model]");
+  if (!modelScript) {
+    return;
+  }
+  // SAFETY: this script tag is written only by MessageComposer.astro, which
+  // serializes a typed MessageModel into it at build time — the JSON here can
+  // hold nothing else.
+  const model = JSON.parse(modelScript.textContent ?? "") as MessageModel;
+
+  // The sample panes live in the sibling rail, so they are looked up from the
+  // shared operation-panel wrapper rather than this element.
+  const scope = root.closest("[data-operation-panel]") ?? document;
+  const panes = [...scope.querySelectorAll<HTMLElement>("[data-sample-lang]")];
+  const languages = new Map(
+    asyncSampleLanguages(
+      panes.map((pane) => pane.dataset.sampleLang ?? ""),
+      model.protocol
+    ).map((language) => [language.id, language])
+  );
+
+  const serverSelect = root.querySelector<HTMLSelectElement>("[data-server]");
+  const serverCustom = root.querySelector<HTMLInputElement>(
+    "[data-server-custom]"
+  );
+  const paramInputs = [
+    ...root.querySelectorAll<HTMLInputElement>("[data-param]"),
+  ];
+  const payloadArea = root.querySelector<HTMLTextAreaElement>("[data-payload]");
+  const payloadErrors = root.querySelector<HTMLElement>(
+    "[data-payload-errors]"
+  );
+  const connectButton = root.querySelector<HTMLButtonElement>("[data-connect]");
+  const disconnectButton =
+    root.querySelector<HTMLButtonElement>("[data-disconnect]");
+  const sendButton = root.querySelector<HTMLButtonElement>("[data-send]");
+  const status = root.querySelector<HTMLElement>("[data-status]");
+  const log = root.querySelector<HTMLElement>("[data-log]");
+
+  /** The current form state as the shared MessageValues shape. */
+  const collect = (): MessageValues => {
+    const params: Record<string, string> = {};
+    for (const input of paramInputs) {
+      params[input.dataset.param ?? ""] = input.value;
+    }
+    return {
+      customUrl: serverCustom?.value ?? "",
+      params,
+      payload: payloadArea?.value ?? model.payload.example,
+      server: Number(serverSelect?.value ?? "0"),
+    };
+  };
+
+  /** Re-render every sample pane from the live form. */
+  const syncSamples = (): void => {
+    const sample = buildMessage(model, collect());
+    for (const pane of panes) {
+      const language = languages.get(pane.dataset.sampleLang ?? "");
+      if (!language) {
+        continue;
+      }
+      const target = pane.querySelector("code") ?? pane;
+      target.textContent = language.build(sample);
+    }
+  };
+
+  /** Validate the payload editor and list the messages; [] when there is none. */
+  const validatePayload = (): string[] => {
+    if (!(payloadArea && payloadErrors)) {
+      return [];
+    }
+    // An empty editor means "no payload" — `buildMessage` derives none and the
+    // frame degrades to `{}` — not invalid JSON. Reporting a syntax error there
+    // would permanently block Connect on an operation with no message example.
+    const errors =
+      payloadArea.value.trim() === ""
+        ? []
+        : validateJson(payloadArea.value, model.payload.schema, "payload");
+    payloadErrors.textContent = "";
+    for (const error of errors) {
+      const item = document.createElement("span");
+      item.className = ERROR_TEXT;
+      item.textContent = error;
+      payloadErrors.append(item);
+    }
+    return errors;
+  };
+
+  /**
+   * The URL the live socket was dialed with; "" when nothing is connected. The
+   * status line and the send path read this rather than recomputing from the
+   * form, because the form can move on while a socket stays where it was.
+   */
+  let connectedUrl = "";
+
+  /** The connect URL the form currently describes. */
+  const formUrl = (): string => webSocketUrl(buildMessage(model, collect()));
+
+  /** Write one message onto the status line, if the panel rendered one. */
+  const setStatus = (text: string, className: string): void => {
+    if (!status) {
+      return;
+    }
+    status.textContent = text;
+    status.className = className;
+  };
+
+  /** Reflect the connection state onto the status line and the buttons. */
+  const renderState = (state: WsState, detail?: string): void => {
+    const live = state === "connecting" || state === "open";
+    if (!live) {
+      connectedUrl = "";
+    }
+    if (connectButton) {
+      connectButton.disabled = live;
+    }
+    if (disconnectButton) {
+      disconnectButton.disabled = !live;
+    }
+    if (sendButton) {
+      sendButton.disabled = state !== "open";
+    }
+    if (state === "connecting") {
+      setStatus("Connecting\u2026", MUTED_TEXT);
+      return;
+    }
+    if (state === "open") {
+      setStatus(`Connected to ${connectedUrl}.`, MUTED_TEXT);
+      return;
+    }
+    if (state === "error") {
+      setStatus(ERROR_MESSAGE, ERROR_TEXT);
+      return;
+    }
+    setStatus(
+      detail ? `Disconnected (${detail}).` : "Not connected.",
+      MUTED_TEXT
+    );
+  };
+
+  /** Append one frame to the log: timestamp, direction, and the raw text. */
+  const renderFrame = (frame: WsFrame): void => {
+    if (!log) {
+      return;
+    }
+    const row = document.createElement("div");
+    row.className = "flex gap-2 font-mono text-xs";
+    const meta = document.createElement("span");
+    meta.className = "shrink-0 text-muted-foreground";
+    meta.textContent = `${stamp(frame.at)} ${frame.direction === "sent" ? "\u2191" : "\u2193"}`;
+    const text = document.createElement("span");
+    text.className = "break-all text-foreground";
+    text.textContent = frame.text;
+    row.append(meta, text);
+    log.append(row);
+  };
+
+  const client = createWsClient({ onFrame: renderFrame, onState: renderState });
+
+  connectButton?.addEventListener("click", () => {
+    if (validatePayload().length > 0) {
+      return;
+    }
+    // A blank channel parameter leaves its `{name}` template in the address, so
+    // connecting would dial a URL no broker has a channel for.
+    const missing = paramInputs
+      .filter((input) => input.value === "")
+      .map((input) => input.dataset.param ?? "");
+    if (missing.length > 0) {
+      setStatus(
+        `Fill in every channel parameter before connecting: ${missing.join(", ")}.`,
+        ERROR_TEXT
+      );
+      return;
+    }
+    connectedUrl = formUrl();
+    client.connect(connectedUrl);
+  });
+  disconnectButton?.addEventListener("click", () => client.disconnect());
+  sendButton?.addEventListener("click", () => {
+    if (validatePayload().length > 0) {
+      return;
+    }
+    client.send(messageFrame(buildMessage(model, collect())));
+  });
+
+  const onEdit = (): void => {
+    // The socket is bound to the URL it was dialed with: once the server or a
+    // channel parameter moves, the open connection is the wrong endpoint, so it
+    // is dropped rather than left to answer for the form on screen.
+    if (connectedUrl !== "" && formUrl() !== connectedUrl) {
+      client.disconnect();
+      setStatus("The endpoint changed. Connect again to use it.", MUTED_TEXT);
+    }
+    validatePayload();
+    syncSamples();
+  };
+  root.addEventListener("input", onEdit);
+  root.addEventListener("change", onEdit);
+};