blume 2.0.2 → 2.0.3

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, ",")}`;
+};

package/src/components/openapi/playground-client.ts

@@ -16,8 +16,14 @@ import type {
   PlaygroundModel,
   RequestValues,
 } from "./request.ts";
-import { buildRequest, redactAuth } from "./request.ts";
-import { sampleLanguages } from "./snippets.ts";
+import {
+  bodyEncoding,
+  buildRequest,
+  PROXY_HEADERS_HEADER,
+  redactAuth,
+} from "./request.ts";
+import { fetchRefusesMethod, sampleLanguages } from "./snippets.ts";
+import type { RequestSample } from "./snippets.ts";
 import { validateJson } from "./validate-json.ts";
 
 /**
@@ -42,6 +48,16 @@ const COOKIE_MESSAGE =
   "send the cookie credential you entered. Copy the sample above and run it " +
   "from a terminal instead.";
 
+/**
+ * fetch refuses the TRACE method outright, proxied or not: the browser throws
+ * before anything is sent, which the send's catch would misdiagnose as the
+ * CORS wall or an unreachable host. The cURL and Python samples can send it.
+ */
+const TRACE_MESSAGE =
+  "Browsers don't allow a page to send a `TRACE` request, so this panel " +
+  "can't send it. Run the cURL or Python sample above from a terminal " +
+  "instead.";
+
 /**
  * A fetch that fails before any response when the API couldn't be reached at
  * all — a mistyped host, a refused connection, no network — rather than
@@ -185,6 +201,50 @@ const removeStored = (key: string): void => {
   }
 };
 
+/**
+ * The headers a live send carries. A `Cookie` header can still arrive via a
+ * spec-declared header parameter; the browser would silently drop the
+ * forbidden name anyway, so it is stripped rather than earn a console
+ * warning. Blume's own proxy — always a path on this site — forwards only the
+ * headers named in {@link PROXY_HEADERS_HEADER}, never ones the browser or
+ * the platform add on their own; a multipart body's Content-Type is fetch's,
+ * written with the boundary, so it is named without being set. An external
+ * proxy on another origin gets no such header: it would only be one more name
+ * for its preflight to allow.
+ */
+const sendHeaders = (sample: RequestSample, proxy: string) => {
+  const headers = { ...sample.headers };
+  delete headers.Cookie;
+  if (proxy.startsWith("/") && !proxy.startsWith("//")) {
+    const names = Object.keys(headers);
+    if (sample.formData) {
+      names.push("Content-Type");
+    }
+    headers[PROXY_HEADERS_HEADER] = names.join(", ");
+  }
+  return headers;
+};
+
+/**
+ * The body a live send carries: multipart parts as `FormData`, anything else
+ * as its text. fetch throws a synchronous TypeError for a GET/HEAD with a
+ * body — which the send's catch would mislabel as CORS — so a spec that
+ * declares a GET requestBody keeps its samples, but the live send drops it.
+ */
+const sendBody = (sample: RequestSample): string | FormData | undefined => {
+  if (sample.method === "GET" || sample.method === "HEAD") {
+    return undefined;
+  }
+  if (!sample.formData) {
+    return sample.body;
+  }
+  const form = new FormData();
+  for (const [name, value] of sample.formData) {
+    form.append(name, value);
+  }
+  return form;
+};
+
 /** A one-line text element for the response/error regions. */
 const line = (className: string, text: string): HTMLElement => {
   const el = document.createElement("div");
@@ -332,9 +392,11 @@ export const initPlayground = (root: HTMLElement): void => {
     }
     // An emptied editor means "no body" (see `bodyFor`), not invalid JSON —
     // reporting a syntax error there would block a send the request builder is
-    // perfectly happy to make.
+    // perfectly happy to make. A raw media type (`text/plain`, XML) isn't
+    // JSON at all, so it isn't checked as JSON either.
+    const raw = bodyEncoding(model.body?.contentType ?? "") === "raw";
     const errors =
-      bodyArea.value.trim() === ""
+      raw || bodyArea.value.trim() === ""
         ? []
         : validateJson(bodyArea.value, model.body?.schema);
     bodyErrors.textContent = "";
@@ -453,6 +515,11 @@ export const initPlayground = (root: HTMLElement): void => {
     if (!response || sending) {
       return;
     }
+    if (fetchRefusesMethod(model.method)) {
+      response.textContent = "";
+      response.append(line(ERROR_TEXT, TRACE_MESSAGE));
+      return;
+    }
     if (validateBody().length > 0) {
       return;
     }
@@ -494,11 +561,7 @@ export const initPlayground = (root: HTMLElement): void => {
           sample.url
         )}`
       : sample.url;
-    // A `Cookie` header can still arrive via a spec-declared header parameter;
-    // the browser would silently drop the forbidden name anyway, so strip it
-    // rather than earn a console warning.
-    const headers = { ...sample.headers };
-    delete headers.Cookie;
+    const headers = sendHeaders(sample, proxy);
     // fetch surfaces an invalid URL or header value as the same TypeError a
     // CORS rejection produces, and the catch below would misdiagnose it as the
     // CORS wall. Both are validated here, where the real error can be shown,
@@ -526,13 +589,7 @@ export const initPlayground = (root: HTMLElement): void => {
     const start = performance.now();
     try {
       const res = await fetch(url, {
-        // fetch throws a synchronous TypeError for a GET/HEAD with a body —
-        // which the catch below would mislabel as CORS. A spec that declares
-        // a GET requestBody keeps its samples, but the live send drops it.
-        body:
-          sample.method === "GET" || sample.method === "HEAD"
-            ? undefined
-            : sample.body,
+        body: sendBody(sample),
         headers,
         method: sample.method,
         // A `TimeoutError` DOMException is not a TypeError, so it reads as a