blume 2.0.1 → 2.0.3

package/src/components/openapi/SchemaProperty.astro

@@ -3,33 +3,23 @@ import Description from "./Description.astro";
 import {
   constraints,
   isNullable,
-  refName,
   resolveSchema,
   type SchemaLike,
   typeLabel,
 } from "./helpers.ts";
+import { rowExpands, type SchemaRow } from "./schema-tree.ts";
 import SchemaTable from "./SchemaTable.astro";
 
 interface Props {
-  name: string;
-  schema: SchemaLike;
-  required?: boolean;
+  /** One planned row of the parent table (see `schema-tree.ts`). */
+  row: SchemaRow;
   schemas: Record<string, SchemaLike>;
-  seen?: string[];
   expandAll?: boolean;
 }
 
-const {
-  name,
-  schema,
-  required = false,
-  schemas,
-  seen = [],
-  expandAll = false,
-} = Astro.props;
+const { row, schemas, expandAll = false } = Astro.props;
+const { name, schema, required } = row;
 
-const refLabel = typeof schema.$ref === "string" ? refName(schema.$ref) : null;
-const circular = refLabel !== null && seen.includes(refLabel);
 const resolved = resolveSchema(schemas, schema);
 
 const type = typeLabel(schema);
@@ -39,20 +29,9 @@ const nullable = isNullable(resolved);
 const enumValues = Array.isArray(resolved.enum) ? resolved.enum : null;
 const limits = constraints(resolved);
 
-const types = Array.isArray(resolved.type) ? resolved.type : [resolved.type];
-const isArray = types.includes("array");
-const items = isArray ? resolveSchema(schemas, resolved.items) : null;
-
-const hasObjectShape = (candidate: SchemaLike): boolean =>
-  Boolean(
-    candidate.properties ||
-      candidate.allOf ||
-      candidate.oneOf ||
-      candidate.anyOf ||
-      typeof candidate.$ref === "string"
-  );
-const expandable =
-  !circular && (hasObjectShape(resolved) || Boolean(items && hasObjectShape(items)));
+// Circles and schemas expanded elsewhere in the tree have no disclosure; the
+// type label names them.
+const children = rowExpands(row) ? row.children : undefined;
 ---
 
 {/* The row's vertical scale is 8 / 12 / 16px, and every other reference table copies it. A
@@ -103,17 +82,16 @@ const expandable =
     )
   }
   {
-    expandable && (
+    children && (
       <details class="mt-3" open={expandAll}>
         <summary class="cursor-pointer select-none text-accent text-xs hover:underline">
           <span class="[details[open]>summary_&]:hidden">Show properties</span>
           <span class="hidden [details[open]>summary_&]:inline">Hide properties</span>
         </summary>
-        <div class="mt-3 border-border border-l pl-4">
+        <div class="mt-3 border-border border-s ps-4">
           <SchemaTable
-            schema={schema}
+            node={children.node}
             schemas={schemas}
-            seen={seen}
             expandAll={expandAll}
           />
         </div>

package/src/components/openapi/SchemaTable.astro

@@ -1,86 +1,68 @@
 ---
-import {
-  objectProperties,
-  refName,
-  resolveSchema,
-  type SchemaLike,
-  typeLabel,
-} from "./helpers.ts";
+import type { SchemaLike } from "./helpers.ts";
+import { type SchemaNode, schemaTree } from "./schema-tree.ts";
 import SchemaProperty from "./SchemaProperty.astro";
 
 interface Props {
-  schema: SchemaLike;
+  /** The schema to render, planned here when no `node` is given. */
+  schema?: SchemaLike;
+  /** An already-planned subtree: how nested tables render. */
+  node?: SchemaNode;
   schemas: Record<string, SchemaLike>;
-  /** `$ref` names already on the current branch, to break circular schemas. */
-  seen?: string[];
   expandAll?: boolean;
 }
 
-const { schema, schemas, seen = [], expandAll = false } = Astro.props;
+const { schema = {}, node: planned, schemas, expandAll = false } = Astro.props;
 
-// Track the ref so a self-referential model stops instead of recursing forever.
-const refLabel =
-  typeof schema.$ref === "string" ? refName(schema.$ref) : null;
-const circular = refLabel !== null && seen.includes(refLabel);
-const nextSeen = refLabel ? [...seen, refLabel] : seen;
-const resolved = circular ? schema : resolveSchema(schemas, schema);
-
-const types = Array.isArray(resolved.type) ? resolved.type : [resolved.type];
-const isArray = types.includes("array");
-// Keep array items unresolved so a self-referential item `$ref` stays trackable
-// via `seen` — resolving here would drop the name and loop forever.
-const items = isArray ? (resolved.items ?? null) : null;
-const branches = resolved.oneOf ?? resolved.anyOf ?? null;
-
-const { properties, required } = circular
-  ? { properties: [] as [string, SchemaLike][], required: new Set<string>() }
-  : objectProperties(resolved, schemas);
+// The whole tree is planned once, at the top-level table, so that which named
+// schemas expand is decided for the tree as a whole (see `schema-tree.ts`).
+const node = planned ?? schemaTree(schema, schemas);
 ---
 
 {
-  circular ? (
+  node.kind === "circular" ? (
     <div class="text-muted-foreground text-sm">
-      Circular reference to <code class="text-foreground">{refLabel}</code>.
+      Circular reference to <code class="text-foreground">{node.name}</code>.
     </div>
-  ) : isArray ? (
+  ) : node.kind === "array" ? (
     <div>
       <div class="mb-2 text-muted-foreground text-xs">
-        Array of <code class="text-foreground">{typeLabel(items ?? {})}</code>
+        Array of <code class="text-foreground">{node.itemsLabel}</code>
       </div>
-      {items && (
-        <Astro.self schema={items} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
+      {node.items && (
+        <Astro.self node={node.items.node} schemas={schemas} expandAll={expandAll} />
       )}
     </div>
-  ) : branches ? (
+  ) : node.kind === "branches" ? (
     <div class="flex flex-col gap-3">
-      <div class="text-muted-foreground text-xs">
-        {resolved.oneOf ? "One of" : "Any of"}:
-      </div>
-      {branches.map((branch, index) => (
+      {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">
           <div class="mb-2 font-medium text-foreground text-xs">
-            {typeLabel(branch) || `Option ${index + 1}`}
+            {branch.label}
           </div>
-          <Astro.self schema={branch} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
+          <Astro.self node={branch.slot.node} schemas={schemas} expandAll={expandAll} />
         </div>
       ))}
     </div>
-  ) : properties.length > 0 ? (
+  ) : node.kind === "properties" ? (
     <div class="not-prose">
-      {properties.map(([name, prop]) => (
-        <SchemaProperty
-          name={name}
-          schema={prop}
-          required={required.has(name)}
-          schemas={schemas}
-          seen={nextSeen}
-          expandAll={expandAll}
-        />
+      {node.rows.map((row) => (
+        <SchemaProperty row={row} schemas={schemas} expandAll={expandAll} />
       ))}
     </div>
   ) : (
     <div class="text-muted-foreground text-sm">
-      <code class="text-foreground">{typeLabel(resolved)}</code>
+      <code class="text-foreground">
+        {node.kind === "named" ? node.name : node.label}
+      </code>
     </div>
   )
 }

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

package/src/components/openapi/helpers.ts

@@ -152,17 +152,31 @@ export const resolveSchema = (
   return schema;
 };
 
-const nonNullTypes = (type: string | string[] | undefined): string[] => {
+const declaredTypeList = (type: string | string[] | undefined): string[] => {
   if (!type) {
     return [];
   }
-  return (Array.isArray(type) ? type : [type]).filter((t) => t !== "null");
+  return Array.isArray(type) ? type : [type];
+};
+
+const nonNullTypes = (type: string | string[] | undefined): string[] =>
+  declaredTypeList(type).filter((t) => t !== "null");
+
+/**
+ * Whether a schema admits only `null`: `{ type: "null" }`, the branch Scalar's
+ * upgrade pairs with a 3.0 `nullable: true` `$ref` (`anyOf: [$ref, { type:
+ * "null" }]`).
+ */
+const isNullType = (schema: SchemaLike): boolean => {
+  const types = declaredTypeList(schema.type);
+  return types.length > 0 && types.every((type) => type === "null");
 };
 
 /**
  * A short, human-readable type label for a schema row. `$ref`s label by name
  * (`Pet`, `Pet[]`) without resolving — which also means circular refs through
- * array items can't recurse forever.
+ * array items can't recurse forever. A `null` member stays out of a union's
+ * label: rows mark it with {@link isNullable}, as they do `type: [T, "null"]`.
  */
 export const typeLabel = (schema: SchemaLike): string => {
   if (isString(schema.$ref)) {
@@ -170,24 +184,42 @@ export const typeLabel = (schema: SchemaLike): string => {
   }
   if (schema.oneOf || schema.anyOf) {
     const branches = schema.oneOf ?? schema.anyOf ?? [];
-    const labels = branches.map((branch) => typeLabel(branch));
+    const members = branches.filter((branch) => !isNullType(branch));
+    if (members.length === 0 && branches.length > 0) {
+      return "null";
+    }
+    const labels = members.map((branch) => typeLabel(branch));
     return [...new Set(labels)].join(" | ") || "any";
   }
   if (schema.allOf) {
     return "object";
   }
   const types = nonNullTypes(schema.type);
+  const arrayLabel = (): string => `${typeLabel(schema.items ?? {})}[]`;
+  if (types.length > 1) {
+    // A 3.1 type array names every type the value may take, not just the first.
+    return types
+      .map((type) => (type === "array" ? arrayLabel() : type))
+      .join(" | ");
+  }
   if (types.includes("array")) {
-    return `${typeLabel(schema.items ?? {})}[]`;
+    return arrayLabel();
+  }
+  if (types.length === 0 && isNullType(schema)) {
+    return "null";
   }
   const base = types[0] ?? (schema.properties ? "object" : "any");
   return schema.format ? `${base}<${schema.format}>` : base;
 };
 
-/** Whether this schema is nullable (3.0 `nullable` or a 3.1 `"null"` in `type`). */
+/**
+ * Whether this schema is nullable: 3.0 `nullable`, a 3.1 `"null"` in `type`,
+ * or a `{ type: "null" }` member of a `oneOf`/`anyOf` union.
+ */
 export const isNullable = (schema: SchemaLike): boolean =>
   schema.nullable === true ||
-  (Array.isArray(schema.type) && schema.type.includes("null"));
+  (Array.isArray(schema.type) && schema.type.includes("null")) ||
+  [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])].some(isNullType);
 
 /** Human-readable validation constraints for a schema, in display order. */
 export const constraints = (schema: SchemaLike): string[] => {
@@ -263,23 +295,26 @@ export const objectProperties = (
  * Build a representative example value for a schema via openapi-sampler
  * (Redoc's generator): declared `example`/`const`/`default`/`enum` values
  * win, formats produce realistic placeholders (`email`, `uuid`, `date-time`),
- * `readOnly` fields are skipped (these samples illustrate *requests*, and a
- * server-generated field has no place in one), and circular `$ref` chains —
- * which keeping refs intact allows — terminate safely.
+ * and circular `$ref` chains — which keeping refs intact allows — terminate
+ * safely. A request sample skips `readOnly` fields (a server-generated field
+ * has no place in one); a response sample skips `writeOnly` fields (a
+ * password the client sends never comes back) and keeps the `readOnly` ones.
  */
 export const exampleValue = (
   schema: SchemaLike | undefined,
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  direction: "request" | "response" = "request"
 ): SpecValue => {
   if (!schema) {
     return null;
   }
+  const response = direction === "response";
   try {
     // SAFETY: SchemaLike structurally covers the JSONSchema7 fields the
     // sampler reads, and the sampler only ever assembles JSON values.
     return sample(
       schema as Parameters<typeof sample>[0],
-      { quiet: true, skipReadOnly: true },
+      { quiet: true, skipReadOnly: !response, skipWriteOnly: response },
       { components: { schemas } }
     ) as SpecValue;
   } catch {
@@ -289,5 +324,58 @@ export const exampleValue = (
   }
 };
 
+/** Where an author can declare an example: a parameter or a media type. */
+export interface ExampleCarrier {
+  example?: SpecValue;
+  examples?: SpecValue;
+}
+
+const isRecord = (value: SpecValue): value is Record<string, SpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * The example a parameter or media type declares: its `example`, else the
+ * first `value` in its `examples` map — inline, or behind a `$ref` to
+ * `#/components/examples`, resolved against `components`. Scalar's upgrade
+ * moves every OpenAPI 3.0 and Swagger 2.0 `example` into
+ * `examples.default.value`, and 3.1 authors write that map directly, so
+ * reading `example` alone would drop them all. `undefined` when nothing is
+ * declared.
+ */
+export const declaredExample = (
+  carrier: ExampleCarrier,
+  components?: ComponentsLike
+): SpecValue => {
+  if (carrier.example !== undefined) {
+    return carrier.example;
+  }
+  const { examples } = carrier;
+  if (!isRecord(examples)) {
+    return undefined;
+  }
+  for (const entry of Object.values(examples)) {
+    const example = isRecord(entry)
+      ? resolveComponentRef(entry, components, "examples")
+      : undefined;
+    if (example?.value !== undefined) {
+      return example.value;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * A response media type's example for the Response panel: the declared one,
+ * else a sample built for the response direction (`readOnly` kept,
+ * `writeOnly` skipped).
+ */
+export const responseExample = (
+  media: ExampleCarrier & { schema?: SchemaLike },
+  schemas: Record<string, SchemaLike>,
+  components?: ComponentsLike
+): SpecValue =>
+  declaredExample(media, components) ??
+  exampleValue(media.schema, schemas, "response");
+
 /** Pretty-print a JSON value for an example/code block. */
 export const toJson = <T>(value: T): string => JSON.stringify(value, null, 2);

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

@@ -171,7 +171,12 @@ export const initComposer = (root: HTMLElement): void => {
       return;
     }
     if (state === "error") {
-      setStatus(ERROR_MESSAGE, ERROR_TEXT);
+      // A detail is the browser refusing the URL before dialing; a failed
+      // handshake carries none.
+      setStatus(
+        detail ? `Couldn't connect: ${detail}` : ERROR_MESSAGE,
+        ERROR_TEXT
+      );
       return;
     }
     setStatus(
@@ -199,6 +204,14 @@ export const initComposer = (root: HTMLElement): void => {
 
   const client = createWsClient({ onFrame: renderFrame, onState: renderState });
 
+  // A ClientRouter navigation swaps this panel out of the document without
+  // unloading the page, so a live socket would stay open behind the next page
+  // — and coming back and connecting again would open a second one. Every
+  // swap replaces the panel, so the first one closes the socket for good.
+  document.addEventListener("astro:before-swap", () => client.disconnect(), {
+    once: true,
+  });
+
   connectButton?.addEventListener("click", () => {
     if (validatePayload().length > 0) {
       return;

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

@@ -2,6 +2,7 @@ import type {
   AsyncApiAction,
   AsyncApiServerObject,
 } from "../../openapi/asyncapi.ts";
+import { withServerDefaults } from "../../openapi/model.ts";
 import type { AsyncApiMessageLike, NamedMessage } from "./async.ts";
 import { payloadSchema } from "./async.ts";
 import { exampleValue, toJson } from "./helpers.ts";
@@ -78,9 +79,18 @@ const messagePayload = (
 /**
  * A server's base URL for the picker. Falls back to the bare host when the
  * spec omits `protocol` — a label is a label, and the snippet builders read
- * the server object itself rather than this string.
+ * the server object itself rather than this string. Server variables in the
+ * host and pathname (`{env}.events.example.com`) resolve to their declared
+ * defaults, in the label and in the object the samples and connect URL read.
  */
-const serverOption = (server: AsyncApiServerObject): MessageServerOption => {
+const serverOption = (spec: AsyncApiServerObject): MessageServerOption => {
+  const server = { ...spec };
+  if (spec.host !== undefined) {
+    server.host = withServerDefaults(spec.host, spec.variables);
+  }
+  if (spec.pathname !== undefined) {
+    server.pathname = withServerDefaults(spec.pathname, spec.variables);
+  }
   const host = `${server.host ?? ""}${server.pathname ?? ""}`;
   return {
     label: server.protocol ? `${server.protocol}://${host}` : host,

package/src/components/openapi/message.ts

@@ -40,7 +40,10 @@ export interface MessagePayload {
 export interface MessageServerOption {
   /** `protocol://host+pathname` — what the reader picks between. */
   label: string;
-  /** The spec server, verbatim; the snippet builders read host/pathname/protocol. */
+  /**
+   * The spec server with its host/pathname variables at their defaults; the
+   * snippet builders read host/pathname/protocol.
+   */
   server: AsyncApiServerObject;
 }
 
@@ -84,6 +87,17 @@ export const defaultMessageValues = (model: MessageModel): MessageValues => ({
 
 const PARAM_TEMPLATE = /\{(?<name>[^{}]+)\}/gu;
 
+/**
+ * Protocols whose channel address is a URL path, where a parameter value must
+ * be percent-encoded. Everywhere else — a Kafka or MQTT topic, an AMQP routing
+ * key — the address is a name the value goes into as written: `sensor 1`,
+ * not `sensor%201`.
+ */
+const URL_PROTOCOLS = { http: true, https: true, ws: true } satisfies Record<
+  string,
+  true
+>;
+
 /**
  * A free-text base URL lowered onto the server shape the snippet builders and
  * the connect URL read. A full URL contributes its scheme, host, and path.
@@ -111,7 +125,8 @@ const customServer = (url: string): AsyncApiServerObject => {
 /**
  * THE one message builder: the composer's samples, its copy buttons, and the
  * live WebSocket frame all consume its output. Parameter values are
- * URL-encoded into the address; a parameter left blank keeps its `{name}`
+ * URL-encoded into the address when the protocol addresses channels by URL
+ * (see {@link URL_PROTOCOLS}); a parameter left blank keeps its `{name}`
  * template so the sample still reads as a template rather than a broken
  * address. Payload text that doesn't parse yields no payload — the editor is
  * showing the reader a validation error at that moment, and neither a sample
@@ -123,6 +138,9 @@ export const buildMessage = (
 ): MessageSample => {
   const custom = values.customUrl.trim();
   const picked = model.servers[values.server] ?? model.servers[0];
+  const encode = Object.hasOwn(URL_PROTOCOLS, model.protocol ?? "")
+    ? encodeURIComponent
+    : (value: string) => value;
   let payload: unknown;
   try {
     // SAFETY: JSON.parse returns `any`; widening it to `unknown` claims
@@ -135,7 +153,7 @@ export const buildMessage = (
     action: model.action,
     address: model.address.replaceAll(PARAM_TEMPLATE, (template, name) => {
       const value = values.params[String(name)] ?? "";
-      return value === "" ? template : encodeURIComponent(value);
+      return value === "" ? template : encode(value);
     }),
     payload,
     server: custom === "" ? picked?.server : customServer(custom),