blume 1.4.2 → 1.5.0

package/src/components/openapi/async.ts

@@ -0,0 +1,348 @@
+import type {
+  AsyncApiChannelObject,
+  AsyncApiDocument,
+  AsyncApiOperationObject,
+  AsyncApiRefLike,
+  AsyncApiServerObject,
+  AsyncApiSpecValue,
+} from "../../openapi/asyncapi.ts";
+import type { ParameterLike, SchemaLike } from "./helpers.ts";
+import { resolveComponentRef } from "./helpers.ts";
+
+/**
+ * Runtime helpers for the AsyncAPI components — the async counterpart of
+ * `helpers.ts`. These operate on the normalized 3.x document behind the
+ * `blume:openapi` alias, resolving the ref shapes AsyncAPI adds on top of
+ * `#/components/*`: operations point at channels, channel messages may `$ref`
+ * `#/components/messages`, and operation messages point *into* a channel
+ * (`#/channels/<id>/messages/<name>`). Browser-safe like the rest of the set.
+ */
+
+/** A permissive view of an AsyncAPI message — only the fields we render. */
+export interface AsyncApiMessageLike extends AsyncApiRefLike {
+  name?: string;
+  title?: string;
+  summary?: string;
+  description?: string;
+  contentType?: string;
+  payload?: AsyncApiSpecValue;
+  headers?: AsyncApiSpecValue;
+  examples?: {
+    name?: string;
+    summary?: string;
+    payload?: AsyncApiSpecValue;
+    headers?: AsyncApiSpecValue;
+  }[];
+  bindings?: AsyncApiChannelObject["bindings"];
+}
+
+/** A message paired with its channel-map key (the fallback display name). */
+export interface NamedMessage {
+  key: string;
+  message: AsyncApiMessageLike;
+}
+
+const isObject = (
+  value: AsyncApiSpecValue
+): value is Record<string, AsyncApiSpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Permissive spec nodes may lie about declared string fields; verify first. */
+const isString = (value: AsyncApiSpecValue): value is string =>
+  typeof value === "string";
+
+/** Decode a JSON-pointer token: `user~1signedup` -> `user/signedup`. */
+const unescapePointer = (token: string): string =>
+  token.replaceAll("~1", "/").replaceAll("~0", "~");
+
+const CHANNEL_MESSAGE_REF =
+  /^#\/channels\/(?<channel>.+)\/messages\/(?<name>[^/]+)$/u;
+
+type Components = AsyncApiDocument["components"];
+
+/** Resolve a channel-map message (possibly a components `$ref`) to its object. */
+const channelMessage = (
+  raw: AsyncApiRefLike | undefined,
+  components: Components
+): AsyncApiMessageLike | undefined => {
+  if (!isObject(raw)) {
+    return undefined;
+  }
+  const resolved = resolveComponentRef(raw, components, "messages");
+  // Still a bare `$ref` after resolution means it pointed nowhere useful.
+  if (isString(resolved.$ref)) {
+    return undefined;
+  }
+  // SAFETY: `resolved` is a plain message object; the permissive message view
+  // only narrows the fields the components render, all of them optional.
+  return resolved as AsyncApiMessageLike;
+};
+
+/**
+ * The messages one operation carries: its own `messages` refs when declared
+ * (each pointing into the channel's message map or at a components message),
+ * else every message the channel declares. Unresolvable refs are dropped —
+ * the schema tables can only render an actual message object.
+ */
+export const operationMessages = (
+  operation: AsyncApiOperationObject | undefined,
+  channel: AsyncApiChannelObject | undefined,
+  document: AsyncApiDocument
+): NamedMessage[] => {
+  const { components } = document;
+  const messageMap: Record<string, AsyncApiRefLike> = isObject(
+    channel?.messages
+  )
+    ? channel.messages
+    : {};
+  const refs = operation?.messages;
+  if (!Array.isArray(refs) || refs.length === 0) {
+    const all: NamedMessage[] = [];
+    for (const [key, raw] of Object.entries(messageMap)) {
+      const message = channelMessage(raw, components);
+      if (message) {
+        all.push({ key, message });
+      }
+    }
+    return all;
+  }
+  const named: NamedMessage[] = [];
+  for (const ref of refs) {
+    if (!isObject(ref)) {
+      continue;
+    }
+    const pointer = isString(ref.$ref)
+      ? CHANNEL_MESSAGE_REF.exec(ref.$ref)?.groups?.name
+      : undefined;
+    const key = pointer === undefined ? undefined : unescapePointer(pointer);
+    // A channel-message pointer resolves through the channel map; anything
+    // else (a components ref, an inline message) resolves directly.
+    const message =
+      key === undefined
+        ? channelMessage(ref, components)
+        : channelMessage(messageMap[key], components);
+    if (message) {
+      named.push({ key: key ?? message.name ?? "message", message });
+    }
+  }
+  return named;
+};
+
+/** A message's display name: its `name`/`title`, else its channel-map key. */
+export const messageLabel = (named: NamedMessage): string =>
+  named.message.title ?? named.message.name ?? named.key;
+
+/**
+ * The `schemaFormat` media types whose schemas render as JSON Schema: the
+ * AsyncAPI Schema Object (a JSON Schema superset), OpenAPI Schema Objects,
+ * and JSON Schema itself, in their bare and `+json`/`+yaml` spellings.
+ */
+const JSON_SCHEMA_FORMAT =
+  /^application\/(?:vnd\.aai\.asyncapi|vnd\.oai\.openapi|schema)(?:\+(?:json|yaml))?$/u;
+
+/**
+ * The JSON-schema view of a possibly multi-format schema value
+ * (`{ schemaFormat, schema }`, allowed on both message payloads and headers).
+ * Unwraps when the format is JSON-schema compatible and yields nothing
+ * otherwise (an Avro or Protobuf schema can't render as a schema table —
+ * callers fall back to a note).
+ */
+export const schemaOf = (value: AsyncApiSpecValue): SchemaLike | undefined => {
+  if (!isObject(value)) {
+    return undefined;
+  }
+  if (isString(value.schemaFormat) && "schema" in value) {
+    // Match the media type proper (parameters like `;version=…` stripped)
+    // against the JSON-Schema-compatible formats AsyncAPI registers. A
+    // substring test would misclassify e.g. Avro's `+json` encoding, whose
+    // schema is JSON but not JSON Schema.
+    const format = (value.schemaFormat.split(";")[0] ?? "")
+      .trim()
+      .toLowerCase();
+    const jsonish = JSON_SCHEMA_FORMAT.test(format);
+    if (jsonish && isObject(value.schema)) {
+      // SAFETY: a JSON-Schema-format schema object; the permissive SchemaLike
+      // view only narrows the fields the schema tables render, all optional.
+      return value.schema as SchemaLike;
+    }
+    return undefined;
+  }
+  // SAFETY: a bare schema object; the permissive SchemaLike view only narrows
+  // the fields the schema tables render, all of them optional.
+  return value as SchemaLike;
+};
+
+/** The JSON-schema view of a message payload; see {@link schemaOf}. */
+export const payloadSchema = (
+  message: AsyncApiMessageLike
+): SchemaLike | undefined => schemaOf(message.payload);
+
+/** The channel-parameter fields {@link channelParameters} lowers. */
+interface AsyncApiParameterLike extends AsyncApiRefLike {
+  description?: string;
+  default?: AsyncApiSpecValue;
+  enum?: AsyncApiSpecValue[];
+}
+
+/**
+ * Channel parameters lowered into the shared parameter-table shape. AsyncAPI
+ * 3.x parameters are always strings (`enum`/`default`/`examples`, no schema),
+ * and every one is required — an address template can't resolve without it.
+ */
+export const channelParameters = (
+  channel: AsyncApiChannelObject | undefined,
+  document: AsyncApiDocument
+): ParameterLike[] => {
+  const parameters: ParameterLike[] = [];
+  const declared: Record<string, AsyncApiRefLike> = channel?.parameters ?? {};
+  for (const [name, raw] of Object.entries(declared)) {
+    if (!isObject(raw)) {
+      continue;
+    }
+    // SAFETY: the permissive parameter view only narrows the fields lowered
+    // below; each one is runtime-checked before use.
+    const parameter = resolveComponentRef(
+      raw as AsyncApiParameterLike,
+      document.components,
+      "parameters"
+    );
+    const schema: SchemaLike = { type: "string" };
+    if (Array.isArray(parameter.enum)) {
+      schema.enum = parameter.enum;
+    }
+    if (parameter.default !== undefined) {
+      schema.default = parameter.default;
+    }
+    parameters.push({
+      description: isString(parameter.description)
+        ? parameter.description
+        : undefined,
+      in: "channel",
+      name,
+      required: true,
+      schema,
+    });
+  }
+  return parameters;
+};
+
+const SERVER_REF = /^#\/servers\/(?<name>[^/]+)$/u;
+
+/**
+ * The servers a channel is available on: its `servers` refs when declared,
+ * else every server the document declares (the spec's default).
+ */
+export const channelServers = (
+  channel: AsyncApiChannelObject | undefined,
+  document: AsyncApiDocument
+): AsyncApiServerObject[] => {
+  const all = document.servers ?? {};
+  const refs = channel?.servers;
+  if (!Array.isArray(refs) || refs.length === 0) {
+    return Object.values(all).filter(isObject);
+  }
+  const servers: AsyncApiServerObject[] = [];
+  for (const ref of refs) {
+    const name = SERVER_REF.exec(
+      isObject(ref) && isString(ref.$ref) ? ref.$ref : ""
+    )?.groups?.name;
+    const server = name === undefined ? undefined : all[unescapePointer(name)];
+    if (isObject(server)) {
+      servers.push(server);
+    }
+  }
+  return servers;
+};
+
+/** Normalize protocol spellings onto the binding key they document. */
+const PROTOCOL_ALIASES = {
+  "kafka-secure": "kafka",
+  mqtt5: "mqtt",
+  mqtts: "mqtt",
+  "secure-mqtt": "mqtt",
+  wss: "ws",
+};
+
+/**
+ * The protocol an operation speaks, for binding-aware code samples: the first
+ * operation/channel binding key, else the first relevant server's `protocol`.
+ */
+export const protocolOf = (
+  operation: AsyncApiOperationObject | undefined,
+  channel: AsyncApiChannelObject | undefined,
+  servers: AsyncApiServerObject[]
+): string | undefined => {
+  const declared =
+    Object.keys(operation?.bindings ?? {})[0] ??
+    Object.keys(channel?.bindings ?? {})[0] ??
+    servers.find((server) => isString(server.protocol))?.protocol;
+  if (!isString(declared) || declared === "") {
+    return undefined;
+  }
+  const lower = declared.toLowerCase();
+  // SAFETY: guarded by the `in` check, `lower` is one of the alias keys.
+  return lower in PROTOCOL_ALIASES
+    ? PROTOCOL_ALIASES[lower as keyof typeof PROTOCOL_ALIASES]
+    : lower;
+};
+
+/**
+ * The security list an operation actually enforces: its own `security` when
+ * declared, else the union of its servers' — connecting already requires the
+ * server's schemes. Server entries dedupe by `$ref`, so two servers sharing a
+ * scheme render it once.
+ */
+export const asyncApiSecurityEntries = (
+  operation: AsyncApiOperationObject | undefined,
+  servers: AsyncApiServerObject[]
+): AsyncApiRefLike[] => {
+  if (Array.isArray(operation?.security)) {
+    return operation.security;
+  }
+  const entries: AsyncApiRefLike[] = [];
+  const seen = new Set<string>();
+  for (const server of servers) {
+    for (const entry of server.security ?? []) {
+      if (!isObject(entry)) {
+        continue;
+      }
+      if (isString(entry.$ref)) {
+        if (seen.has(entry.$ref)) {
+          continue;
+        }
+        seen.add(entry.$ref);
+      }
+      entries.push(entry);
+    }
+  }
+  return entries;
+};
+
+/** One protocol's binding fields, ready for a key/value table. */
+export interface BindingGroup {
+  protocol: string;
+  rows: { name: string; value: unknown }[];
+}
+
+/**
+ * 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.
+ */
+export const bindingGroups = (
+  bindings?: AsyncApiChannelObject["bindings"]
+): BindingGroup[] => {
+  const groups: BindingGroup[] = [];
+  for (const [protocol, fields] of Object.entries(bindings ?? {})) {
+    if (!isObject(fields)) {
+      continue;
+    }
+    const rows = Object.entries(fields)
+      .filter(([name]) => name !== "bindingVersion")
+      .map(([name, value]) => ({ name, value }));
+    if (rows.length > 0) {
+      groups.push({ protocol, rows });
+    }
+  }
+  return groups;
+};

package/src/components/openapi/helpers.ts

@@ -8,6 +8,22 @@ import { sample } from "openapi-sampler";
  * values come from openapi-sampler, which is likewise browser-safe.
  */
 
+/** Any value a parsed OpenAPI document can hold: JSON, nested schemas included. */
+export type SpecValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | SpecValue[]
+  | { [key: string]: SpecValue };
+
+const isString = (value: SpecValue): value is string =>
+  typeof value === "string";
+
+const isNumber = (value: SpecValue): value is number =>
+  typeof value === "number";
+
 /** A permissive view of an OpenAPI 3.1 schema — only the fields we render. */
 export interface SchemaLike {
   $ref?: string;
@@ -18,11 +34,11 @@ export interface SchemaLike {
   properties?: Record<string, SchemaLike>;
   required?: string[];
   items?: SchemaLike;
-  enum?: unknown[];
-  const?: unknown;
-  default?: unknown;
-  example?: unknown;
-  examples?: unknown[];
+  enum?: SpecValue[];
+  const?: SpecValue;
+  default?: SpecValue;
+  example?: SpecValue;
+  examples?: SpecValue[];
   allOf?: SchemaLike[];
   oneOf?: SchemaLike[];
   anyOf?: SchemaLike[];
@@ -38,7 +54,7 @@ export interface SchemaLike {
   minItems?: number;
   maxItems?: number;
   pattern?: string;
-  [key: string]: unknown;
+  [key: string]: SpecValue;
 }
 
 /** A permissive view of an operation parameter — only the fields we render. */
@@ -50,9 +66,16 @@ export interface ParameterLike {
   required?: boolean;
   deprecated?: boolean;
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  [key: string]: SpecValue;
 }
 
+/** The `components` object of a parsed spec: section name → named-node table. */
+export type ComponentsLike = Record<
+  string,
+  Record<string, SpecValue> | undefined
+>;
+
 const REF_PATTERN = /#\/components\/schemas\/(?<name>[^/]+)$/u;
 
 const COMPONENT_REF = /#\/components\/(?<section>[^/]+)\/(?<name>[^/]+)$/u;
@@ -65,16 +88,18 @@ const COMPONENT_REF = /#\/components\/(?<section>[^/]+)\/(?<name>[^/]+)$/u;
  */
 export const resolveComponentRef = <T extends { $ref?: string }>(
   node: T,
-  components: Record<string, unknown> | undefined,
+  components: ComponentsLike | undefined,
   section: string
 ): T => {
-  if (typeof node.$ref !== "string") {
+  if (!isString(node.$ref)) {
     return node;
   }
   const groups = COMPONENT_REF.exec(node.$ref)?.groups;
   if (groups?.section !== section) {
     return node;
   }
+  // SAFETY: a components section table stores nodes of that section's type,
+  // and callers always pair `section` with the matching `T`.
   const table = components?.[section] as Record<string, T> | undefined;
   return table?.[groups.name ?? ""] ?? node;
 };
@@ -88,7 +113,7 @@ export const resolveComponentRef = <T extends { $ref?: string }>(
 export const mergeParameters = (
   pathParameters: ParameterLike[] | undefined,
   operationParameters: ParameterLike[] | undefined,
-  components?: Record<string, unknown>
+  components?: ComponentsLike
 ): ParameterLike[] => {
   const merged = new Map<string, ParameterLike>();
   let position = 0;
@@ -118,7 +143,7 @@ export const resolveSchema = (
   if (!schema) {
     return {};
   }
-  if (typeof schema.$ref === "string") {
+  if (isString(schema.$ref)) {
     const name = REF_PATTERN.exec(schema.$ref)?.groups?.name;
     if (name && schemas[name]) {
       return schemas[name];
@@ -140,7 +165,7 @@ const nonNullTypes = (type: string | string[] | undefined): string[] => {
  * array items can't recurse forever.
  */
 export const typeLabel = (schema: SchemaLike): string => {
-  if (typeof schema.$ref === "string") {
+  if (isString(schema.$ref)) {
     return refName(schema.$ref);
   }
   if (schema.oneOf || schema.anyOf) {
@@ -177,11 +202,11 @@ export const constraints = (schema: SchemaLike): string[] => {
   ];
   for (const [key, label] of numeric) {
     const value = schema[key];
-    if (typeof value === "number") {
+    if (isNumber(value)) {
       out.push(`${label} ${value}`);
     }
   }
-  if (typeof schema.pattern === "string") {
+  if (isString(schema.pattern)) {
     out.push(`matches ${schema.pattern}`);
   }
   if (schema.default !== undefined) {
@@ -190,6 +215,12 @@ export const constraints = (schema: SchemaLike): string[] => {
   return out;
 };
 
+/** The merged property list and required set a schema exposes. */
+export interface ObjectPropertySet {
+  properties: [string, SchemaLike][];
+  required: Set<string>;
+}
+
 /**
  * The object properties a schema exposes, merging `allOf` branches so an
  * `allOf`-composed model still lists every field. Returns the properties plus
@@ -198,7 +229,7 @@ export const constraints = (schema: SchemaLike): string[] => {
 export const objectProperties = (
   schema: SchemaLike,
   schemas: Record<string, SchemaLike>
-): { properties: [string, SchemaLike][]; required: Set<string> } => {
+): ObjectPropertySet => {
   const properties = new Map<string, SchemaLike>();
   const required = new Set<string>();
   // Cycles can only enter through `$ref`s (inline JSON can't self-nest), so
@@ -206,7 +237,7 @@ export const objectProperties = (
   const seen = new Set<string>();
 
   const collect = (node: SchemaLike): void => {
-    if (typeof node.$ref === "string") {
+    if (isString(node.$ref)) {
       if (seen.has(node.$ref)) {
         return;
       }
@@ -239,16 +270,18 @@ export const objectProperties = (
 export const exampleValue = (
   schema: SchemaLike | undefined,
   schemas: Record<string, SchemaLike>
-): unknown => {
+): SpecValue => {
   if (!schema) {
     return null;
   }
   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 },
       { components: { schemas } }
-    );
+    ) as SpecValue;
   } catch {
     // An unresolvable $ref or malformed schema is a spec problem the schema
     // tables already surface; a sample is best-effort.
@@ -257,5 +290,4 @@ export const exampleValue = (
 };
 
 /** Pretty-print a JSON value for an example/code block. */
-export const toJson = (value: unknown): string =>
-  JSON.stringify(value, null, 2);
+export const toJson = <T>(value: T): string => JSON.stringify(value, null, 2);

package/src/components/openapi/panel.ts

@@ -6,6 +6,8 @@
  * theme.
  */
 
+import { copyText, createCopyFlash } from "../copy-feedback.ts";
+
 class BlumePanelTabs extends HTMLElement {
   connectedCallback() {
     const tabs = [
@@ -36,18 +38,19 @@ class BlumePanelTabs extends HTMLElement {
     }
 
     if (copy) {
+      const flash = createCopyFlash((copied) => {
+        if (copied) {
+          copy.dataset.copied = "true";
+        } else {
+          delete copy.dataset.copied;
+        }
+      }, "Copied");
       copy.addEventListener("click", async () => {
         const active = panels.find(
           (panel) => !panel.classList.contains("hidden")
         );
-        try {
-          await navigator.clipboard.writeText(active?.textContent ?? "");
-          copy.dataset.copied = "true";
-          setTimeout(() => {
-            delete copy.dataset.copied;
-          }, 1500);
-        } catch {
-          // Clipboard unavailable (insecure context); silently ignore.
+        if (await copyText(active?.textContent ?? "")) {
+          flash();
         }
       });
     }