blume 2.0.2 → 2.1.0

package/src/components/openapi/code-samples.ts

@@ -0,0 +1,97 @@
+import { sampleLanguageInfo } from "./snippets.ts";
+import type { SampleLanguageInfo } from "./snippets.ts";
+
+/**
+ * Hand-written code samples from a spec: the `x-codeSamples` extension on an
+ * operation (Redocly's, which Mintlify, Speakeasy, and Stainless write too),
+ * or its older spelling `x-code-samples`. Each entry names a `lang`, holds
+ * the `source`, and may carry a `label`. They render as their own tabs ahead
+ * of the generated samples and, being fixed text, the playground leaves them
+ * as written.
+ */
+
+/** One hand-written sample, ready to render as a tab. */
+export interface CustomCodeSample {
+  /** A stable, unique tab key. */
+  key: string;
+  /** The tab label: the entry's own, else the language's name. */
+  label: string;
+  /** The Shiki language to highlight `source` with. */
+  lang: string;
+  source: string;
+}
+
+/** The two places an operation keeps them. */
+export interface CodeSamplesCarrier {
+  "x-code-samples"?: unknown;
+  "x-codeSamples"?: unknown;
+}
+
+interface RawSample {
+  label?: string;
+  lang: string;
+  source: string;
+}
+
+const isRawSample = (value: unknown): value is RawSample =>
+  typeof value === "object" &&
+  value !== null &&
+  "lang" in value &&
+  typeof value.lang === "string" &&
+  "source" in value &&
+  typeof value.source === "string" &&
+  (!("label" in value) || typeof value.label === "string");
+
+// Shell tools in an `x-codeSamples` entry are usually an SDK's CLI, not curl,
+// so they're named for the shell rather than "cURL".
+const SHELL_LANGS = new Set(["bash", "sh", "shell", "zsh"]);
+
+/** The display name and highlighter for a sample's `lang`. */
+const describe = (lang: string): SampleLanguageInfo => {
+  const lower = lang.toLowerCase();
+  if (SHELL_LANGS.has(lower)) {
+    return { label: "Shell", lang: "bash" };
+  }
+  // A language Blume doesn't generate keeps its own name, and Shiki tries
+  // it as written (it knows most languages by their common names).
+  return sampleLanguageInfo(lower) ?? { label: lang, lang: lower };
+};
+
+/**
+ * The operation's hand-written samples, with a unique tab label each. A label
+ * two samples share gains its language (`List plants · JavaScript`), and one
+ * that still repeats gains a number. Malformed entries are skipped.
+ */
+export const customCodeSamples = (
+  operation: CodeSamplesCarrier
+): CustomCodeSample[] => {
+  const raw = operation["x-codeSamples"] ?? operation["x-code-samples"];
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const entries = raw.filter(isRawSample).map((entry) => {
+    const language = describe(entry.lang);
+    return {
+      base: entry.label?.trim() || language.label,
+      language,
+      source: entry.source.replace(/\n$/u, ""),
+    };
+  });
+  const counts = new Map<string, number>();
+  for (const { base } of entries) {
+    counts.set(base, (counts.get(base) ?? 0) + 1);
+  }
+  const used = new Set<string>();
+  return entries.map(({ base, language, source }, index) => {
+    const first =
+      (counts.get(base) ?? 0) > 1 && base !== language.label
+        ? `${base} · ${language.label}`
+        : base;
+    let label = first;
+    for (let n = 2; used.has(label); n += 1) {
+      label = `${first} (${n})`;
+    }
+    used.add(label);
+    return { key: `x-${index}`, label, lang: language.lang, source };
+  });
+};

package/src/components/openapi/helpers.ts

@@ -335,12 +335,17 @@ const isRecord = (value: SpecValue): value is Record<string, SpecValue> =>
 
 /**
  * The example a parameter or media type declares: its `example`, else the
- * first inline `value` in its `examples` map. 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.
+ * 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): SpecValue => {
+export const declaredExample = (
+  carrier: ExampleCarrier,
+  components?: ComponentsLike
+): SpecValue => {
   if (carrier.example !== undefined) {
     return carrier.example;
   }
@@ -349,8 +354,11 @@ export const declaredExample = (carrier: ExampleCarrier): SpecValue => {
     return undefined;
   }
   for (const entry of Object.values(examples)) {
-    if (isRecord(entry) && entry.value !== undefined) {
-      return entry.value;
+    const example = isRecord(entry)
+      ? resolveComponentRef(entry, components, "examples")
+      : undefined;
+    if (example?.value !== undefined) {
+      return example.value;
     }
   }
   return undefined;
@@ -363,9 +371,11 @@ export const declaredExample = (carrier: ExampleCarrier): SpecValue => {
  */
 export const responseExample = (
   media: ExampleCarrier & { schema?: SchemaLike },
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  components?: ComponentsLike
 ): SpecValue =>
-  declaredExample(media) ?? exampleValue(media.schema, schemas, "response");
+  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(

package/src/components/openapi/message.ts

@@ -87,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.
@@ -114,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
@@ -126,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
@@ -138,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),

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

@@ -6,14 +6,21 @@ import {
   resolveSchema,
   toJson,
 } from "./helpers.ts";
-import type { ParameterLike, SchemaLike, SpecValue } from "./helpers.ts";
+import type {
+  ComponentsLike,
+  ParameterLike,
+  SchemaLike,
+  SpecValue,
+} from "./helpers.ts";
 import {
   declaredTypes,
   inputValue,
   scalarType,
   validationSchema,
 } from "./playground-schema.ts";
+import { bodyEncoding } from "./request.ts";
 import type {
+  ParamSerialization,
   PlaygroundAuthInput,
   PlaygroundBody,
   PlaygroundBodyField,
@@ -34,6 +41,7 @@ interface MediaTypeLike {
   schema?: SchemaLike;
   example?: SpecValue;
   examples?: SpecValue;
+  encoding?: SpecValue;
 }
 
 /** A server entry: its URL template and the variables that fill it. */
@@ -70,6 +78,45 @@ const isExampleObject = (
 ): value is Record<string, SpecValue> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
 
+const isString = (value: SpecValue): value is string =>
+  typeof value === "string";
+
+const isBoolean = (value: SpecValue): value is boolean =>
+  typeof value === "boolean";
+
+/**
+ * The `style`/`explode` a parameter or form-body encoding declares, kept only
+ * when declared so the embedded model stays small; the request builder
+ * applies the OpenAPI defaults for the rest.
+ */
+const serialization = (node: Record<string, SpecValue>): ParamSerialization => {
+  const rule: ParamSerialization = {};
+  if (isString(node.style)) {
+    rule.style = node.style;
+  }
+  if (isBoolean(node.explode)) {
+    rule.explode = node.explode;
+  }
+  return rule;
+};
+
+/** A form body's declared per-field `encoding`, when it names any style. */
+const formEncoding = (
+  encoding: SpecValue
+): PlaygroundBody["encoding"] | undefined => {
+  if (!isExampleObject(encoding)) {
+    return undefined;
+  }
+  const fields: NonNullable<PlaygroundBody["encoding"]> = {};
+  for (const [name, entry] of Object.entries(encoding)) {
+    const rule = isExampleObject(entry) ? serialization(entry) : {};
+    if (Object.keys(rule).length > 0) {
+      fields[name] = rule;
+    }
+  }
+  return Object.keys(fields).length > 0 ? fields : undefined;
+};
+
 /**
  * Playground inputs for the operation's parameters. Cookie params are skipped
  * (not supported in v1 — browsers won't let a page set arbitrary cookies).
@@ -80,7 +127,8 @@ const isExampleObject = (
  */
 const modelParams = (
   parameters: ParameterLike[],
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  components: ComponentsLike | undefined
 ): PlaygroundParam[] => {
   const params: PlaygroundParam[] = [];
   for (const param of parameters) {
@@ -102,9 +150,11 @@ const modelParams = (
       type: scalarType(param.schema, schemas),
       value: required
         ? inputValue(
-            declaredExample(param) ?? exampleValue(param.schema, schemas)
+            declaredExample(param, components) ??
+              exampleValue(param.schema, schemas)
           )
         : "",
+      ...serialization(param),
     });
   }
   return params;
@@ -165,10 +215,16 @@ const bodyFields = (
   return fields;
 };
 
-/** The playground's body editor state, when the operation takes a request body. */
+/**
+ * The playground's body editor state, when the operation takes a request body.
+ * JSON, form-urlencoded, and multipart bodies are edited as JSON (typed fields
+ * when flat) and serialized for their media type on send; any other media
+ * type is raw text, prefilled with a string example as written.
+ */
 const modelBody = (
   requestBody: { content?: Record<string, MediaTypeLike> } | undefined,
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  components: ComponentsLike | undefined
 ): PlaygroundBody | undefined => {
   const media = jsonContentType(requestBody?.content);
   if (!media) {
@@ -176,13 +232,25 @@ const modelBody = (
   }
   const [contentType, mediaType] = media;
   const exampleData =
-    declaredExample(mediaType) ?? exampleValue(mediaType.schema, schemas);
-  return {
+    declaredExample(mediaType, components) ??
+    exampleValue(mediaType.schema, schemas);
+  const encoding = bodyEncoding(contentType);
+  const raw = encoding === "raw";
+  const body: PlaygroundBody = {
     contentType,
-    example: toJson(exampleData) ?? "",
-    fields: bodyFields(mediaType.schema, schemas, exampleData),
+    example:
+      raw && isString(exampleData) ? exampleData : (toJson(exampleData) ?? ""),
+    fields: raw
+      ? undefined
+      : bodyFields(mediaType.schema, schemas, exampleData),
     schema: validationSchema(mediaType.schema, schemas),
   };
+  const fieldEncoding =
+    encoding === "form" ? formEncoding(mediaType.encoding) : undefined;
+  if (fieldEncoding) {
+    body.encoding = fieldEncoding;
+  }
+  return body;
 };
 
 const AUTHORIZATION_HEADER = { in: "header", name: "Authorization" } as const;
@@ -272,6 +340,8 @@ export const operationModel = (args: {
   /** The operation's effective servers (`effectiveServers` output). */
   servers: ServerLike[];
   schemas: Record<string, SchemaLike>;
+  /** The document's `components`, which `$ref`'d examples resolve against. */
+  components?: ComponentsLike;
   security: OperationSecurity;
 }): PlaygroundModel => ({
   // First alternative only — the spec's preferred way to authorize, matching
@@ -281,9 +351,9 @@ export const operationModel = (args: {
     return input ? [input] : [];
   }),
   authOptional: args.security.optional,
-  body: modelBody(args.requestBody, args.schemas),
+  body: modelBody(args.requestBody, args.schemas, args.components),
   method: args.method.toUpperCase(),
-  params: modelParams(args.parameters, args.schemas),
+  params: modelParams(args.parameters, args.schemas, args.components),
   path: args.path,
   // Variables resolve to their defaults: the samples and Send need a real URL.
   servers: args.servers.map((server) =>

package/src/components/openapi/panel.ts

@@ -40,10 +40,12 @@ class BlumePanelTabs extends HTMLElement {
       // wrap, Home and End jump to the ends, and focus follows selection.
       tab.addEventListener("keydown", (event) => {
         const last = tabs.length - 1;
+        // The strip runs right to left under dir="rtl", so the arrows swap.
+        const rtl = getComputedStyle(this).direction === "rtl";
         let next: number | undefined;
-        if (event.key === "ArrowRight") {
+        if (event.key === (rtl ? "ArrowLeft" : "ArrowRight")) {
           next = index === last ? 0 : index + 1;
-        } else if (event.key === "ArrowLeft") {
+        } else if (event.key === (rtl ? "ArrowRight" : "ArrowLeft")) {
           next = index === 0 ? last : index - 1;
         } else if (event.key === "Home") {
           next = 0;

package/src/components/openapi/param-style.ts

@@ -0,0 +1,181 @@
+/**
+ * OpenAPI 3 parameter serialization — `style` and `explode` — for the
+ * playground's one request builder (`request.ts`). An array or object value
+ * has a different wire shape per style: `tags: ["dog", "cat"]` is
+ * `tags=dog&tags=cat` in a query (form, exploded), `dog,cat` in a path
+ * (simple), and `filter: { color: "red" }` is `filter[color]=red` as a
+ * deepObject. Ships in the client bundle with `request.ts`, so it stays
+ * dependency-free.
+ */
+
+/** Parsed JSON: everything `JSON.parse` can produce. */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** A value lowered for serialization: a scalar, a list's items, or an object's entries. */
+export type StyledValue =
+  | { kind: "scalar"; text: string }
+  | { kind: "list"; items: string[] }
+  | { kind: "object"; entries: [string, string][] };
+
+// `typeof` checks live in named predicates (the form the oxlint anti-slop
+// config sanctions).
+const isString = (value: JsonValue): value is string =>
+  typeof value === "string";
+
+/** Whether a parsed value is a plain JSON object. */
+export const isJsonObject = (
+  value: JsonValue
+): value is { [key: string]: JsonValue } =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** One member as wire text: a string verbatim, anything else as its JSON. */
+export const memberText = (value: JsonValue): string =>
+  isString(value) ? value : JSON.stringify(value);
+
+/** A parsed value, lowered: arrays to items, objects to entries, the rest to text. */
+export const styledValue = (value: JsonValue): StyledValue => {
+  if (Array.isArray(value)) {
+    return { items: value.map(memberText), kind: "list" };
+  }
+  if (isJsonObject(value)) {
+    return {
+      entries: Object.entries(value).map(([key, member]) => [
+        key,
+        memberText(member),
+      ]),
+      kind: "object",
+    };
+  }
+  return { kind: "scalar", text: memberText(value) };
+};
+
+/**
+ * A playground input's text as a styled value. Only an array- or object-typed
+ * parameter reads its text as JSON — its prefill is the example's JSON
+ * (`["dog","cat"]`) — and only when the text parses to that shape; anything
+ * else is sent as the one scalar it reads as.
+ */
+export const parseStyledValue = (text: string, type: string): StyledValue => {
+  if (type === "array" || type === "object") {
+    let parsed: JsonValue;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return { kind: "scalar", text };
+    }
+    if (type === "array" ? Array.isArray(parsed) : isJsonObject(parsed)) {
+      return styledValue(parsed);
+    }
+  }
+  return { kind: "scalar", text };
+};
+
+/** The OpenAPI 3 default style: `form` in a query or cookie, `simple` elsewhere. */
+export const defaultStyle = (location: string): string =>
+  location === "query" || location === "cookie" ? "form" : "simple";
+
+/** `explode` when the spec leaves it out: true for `form`, false for the rest. */
+export const defaultExplode = (style: string): boolean => style === "form";
+
+/**
+ * A list or object joined into one value: exploded object entries as
+ * `key=value` separated by `separator`, exploded items by `separator`, and
+ * the unexploded forms comma-separated (`a,b`, `key,value,key2,value2`).
+ */
+const joined = (
+  value: StyledValue,
+  explode: boolean,
+  encode: (text: string) => string,
+  separator: string
+): string => {
+  if (value.kind === "scalar") {
+    return encode(value.text);
+  }
+  if (value.kind === "list") {
+    return value.items.map(encode).join(explode ? separator : ",");
+  }
+  return explode
+    ? value.entries
+        .map(([key, member]) => `${encode(key)}=${encode(member)}`)
+        .join(separator)
+    : value.entries.flat().map(encode).join(",");
+};
+
+/**
+ * A query parameter, or an `application/x-www-form-urlencoded` body field, as
+ * its percent-encoded `name=value` pairs in order. Exploded lists repeat the
+ * name (`tags=dog&tags=cat`) and exploded objects spread their entries
+ * (`color=red&size=L`) whatever the style; unexploded ones join with the
+ * style's delimiter — `,` for form, `%20` for spaceDelimited, `|` for
+ * pipeDelimited. deepObject nests entries under the name (`filter[color]=red`).
+ */
+export const queryPairs = (
+  name: string,
+  value: StyledValue,
+  style: string,
+  explode: boolean
+): string[] => {
+  const key = encodeURIComponent(name);
+  if (value.kind === "object" && style === "deepObject") {
+    return value.entries.map(
+      ([entry, member]) =>
+        `${key}[${encodeURIComponent(entry)}]=${encodeURIComponent(member)}`
+    );
+  }
+  if (value.kind === "list" && explode) {
+    return value.items.map((item) => `${key}=${encodeURIComponent(item)}`);
+  }
+  if (value.kind === "object" && explode) {
+    return value.entries.map(
+      ([entry, member]) =>
+        `${encodeURIComponent(entry)}=${encodeURIComponent(member)}`
+    );
+  }
+  let delimiter = ",";
+  if (style === "spaceDelimited") {
+    delimiter = "%20";
+  } else if (style === "pipeDelimited") {
+    delimiter = "|";
+  }
+  const text =
+    value.kind === "scalar"
+      ? encodeURIComponent(value.text)
+      : (value.kind === "list" ? value.items : value.entries.flat())
+          .map(encodeURIComponent)
+          .join(delimiter);
+  return [`${key}=${text}`];
+};
+
+/**
+ * A path or header parameter's value: `simple` (`dog,cat`), or one of the
+ * path-only `label` (`.dog.cat`) and `matrix` (`;tags=dog;tags=cat`) styles.
+ * `encode` percent-encodes a path segment; a header passes values through.
+ */
+export const templateValue = (
+  name: string,
+  value: StyledValue,
+  style: string,
+  explode: boolean,
+  encode: (text: string) => string
+): string => {
+  if (style === "label") {
+    return `.${joined(value, explode, encode, ".")}`;
+  }
+  if (style !== "matrix") {
+    return joined(value, explode, encode, ",");
+  }
+  const key = encode(name);
+  if (value.kind === "list" && explode) {
+    return value.items.map((item) => `;${key}=${encode(item)}`).join("");
+  }
+  if (value.kind === "object" && explode) {
+    return `;${joined(value, true, encode, ";")}`;
+  }
+  return `;${key}=${joined(value, false, encode, ",")}`;
+};