blume 2.0.1 → 2.0.3

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

@@ -1,4 +1,4 @@
-import { resolveSchema } from "./helpers.ts";
+import { isNullable, resolveSchema } from "./helpers.ts";
 import type { SchemaLike, SpecValue } from "./helpers.ts";
 import type { ValidationSchema } from "./request.ts";
 
@@ -50,6 +50,14 @@ export const inputValue = (value: SpecValue): string => {
 /** Recursion limit for pruned validation schemas — deep enough for real specs. */
 const MAX_SCHEMA_DEPTH = 6;
 
+/** Whether a property is `readOnly`, on the property or the schema it refs. */
+const isReadOnly = (
+  property: SchemaLike | undefined,
+  schemas: Record<string, SchemaLike>
+): boolean =>
+  property?.readOnly === true ||
+  resolveSchema(schemas, property).readOnly === true;
+
 /**
  * Prune a spec schema into the tiny subset `validate-json.ts` understands:
  * `$ref`s resolved inline, cycles cut (the visited set is copied per branch so
@@ -74,15 +82,26 @@ const pruneSchema = (
   }
   const resolved = resolveSchema(schemas, schema);
   const out: ValidationSchema = {};
-  const [type] = declaredTypes(resolved.type);
-  if (type) {
-    out.type = type;
+  // Only a single declared type is checked: a 3.1 type array like
+  // `["string", "integer"]` accepts either, which one `type` can't say.
+  const types = declaredTypes(resolved.type);
+  if (types.length === 1) {
+    [out.type] = types;
+  }
+  if (isNullable(resolved)) {
+    out.nullable = true;
   }
   if (resolved.enum) {
     out.enum = resolved.enum;
   }
-  if (resolved.required && resolved.required.length > 0) {
-    out.required = resolved.required;
+  // A `readOnly` property's `required` binds responses only: the server
+  // generates it, so a request body — which the prefilled example already
+  // leaves it out of — must not be told it is missing.
+  const required = (resolved.required ?? []).filter(
+    (name) => !isReadOnly(resolved.properties?.[name], schemas)
+  );
+  if (required.length > 0) {
+    out.required = required;
   }
   if (resolved.properties) {
     const properties: Record<string, ValidationSchema> = {};

package/src/components/openapi/request.ts

@@ -1,3 +1,14 @@
+import {
+  defaultExplode,
+  defaultStyle,
+  isJsonObject,
+  memberText,
+  parseStyledValue,
+  queryPairs,
+  styledValue,
+  templateValue,
+} from "./param-style.ts";
+import type { JsonValue } from "./param-style.ts";
 import type { RequestSample } from "./snippets.ts";
 
 /**
@@ -10,7 +21,18 @@ import type { RequestSample } from "./snippets.ts";
  * byte-for-byte what gets sent.
  */
 
-export interface PlaygroundParam {
+/**
+ * How a parameter or form-body field serializes, as far as the spec says:
+ * the request builder applies the OpenAPI defaults for what it leaves out.
+ */
+export interface ParamSerialization {
+  /** The spec's `style`; else the location's default. */
+  style?: string;
+  /** The spec's `explode`; else the style's default. */
+  explode?: boolean;
+}
+
+export interface PlaygroundParam extends ParamSerialization {
   name: string;
   in: "path" | "query" | "header";
   required: boolean;
@@ -37,6 +59,8 @@ export interface PlaygroundBodyField {
 /** A pruned, cycle-free JSON-schema subset `validate-json.ts` understands. */
 export interface ValidationSchema {
   type?: string;
+  /** `null` is also accepted: 3.0 `nullable`, or `"null"` in a 3.1 type array. */
+  nullable?: boolean;
   properties?: Record<string, ValidationSchema>;
   required?: string[];
   items?: ValidationSchema;
@@ -47,9 +71,14 @@ export interface PlaygroundBody {
   contentType: string;
   /** Present when the schema is a flat object of primitives -> typed fields UI. */
   fields?: PlaygroundBodyField[];
-  /** Pretty-printed example JSON prefill for the raw editor; "" when none. */
+  /**
+   * Prefill for the raw editor: pretty-printed example JSON, or a raw media
+   * type's (`text/plain`, XML) string example verbatim; "" when none.
+   */
   example: string;
   schema?: ValidationSchema;
+  /** A form-urlencoded body's per-field `encoding` (`style`/`explode`). */
+  encoding?: Record<string, ParamSerialization>;
 }
 
 export type AuthKind = "bearer" | "basic" | "apiKey" | "oauth2";
@@ -101,6 +130,38 @@ export interface RequestValues {
 export const paramKey = (p: { in: string; name: string }): string =>
   `${p.in}:${p.name}`;
 
+/**
+ * The request header a proxied send names the headers the playground set in,
+ * comma-separated. Blume's built-in proxy forwards those and nothing else, so
+ * credentials the browser attaches on its own — HTTP Basic auth for a docs
+ * site behind a password, platform headers added in front of the docs server
+ * — never reach the documented API.
+ */
+export const PROXY_HEADERS_HEADER = "X-Blume-Proxy-Headers";
+
+/**
+ * How a body's media type is put on the wire: JSON as the editor text,
+ * `application/x-www-form-urlencoded` as `name=value` pairs, and
+ * `multipart/form-data` as form parts — both from the editor's JSON object —
+ * and any other type (`text/plain`, XML) as the raw text.
+ */
+export type BodyEncoding = "json" | "form" | "multipart" | "raw";
+
+/** A `+json` suffix or a `json` subtype: `application/json`, `application/vnd.api+json`. */
+const JSON_MEDIA_TYPE = /[+/]json$/u;
+
+/** The {@link BodyEncoding} a body's media type (parameters ignored) takes. */
+export const bodyEncoding = (contentType: string): BodyEncoding => {
+  const type = (contentType.split(";")[0] ?? "").trim().toLowerCase();
+  if (type === "application/x-www-form-urlencoded") {
+    return "form";
+  }
+  if (type === "multipart/form-data") {
+    return "multipart";
+  }
+  return JSON_MEDIA_TYPE.test(type) ? "json" : "raw";
+};
+
 /** Values pre-filled from the model's precomputed examples; auth entries empty. */
 export const defaultValues = (model: PlaygroundModel): RequestValues => ({
   auth: Object.fromEntries(
@@ -195,48 +256,119 @@ const applyAuth = (
   }
 };
 
-/** The raw editor text to send, with a parsed mirror when it is valid JSON. */
+/**
+ * A form-urlencoded body's `name=value` pairs: each field serialized like a
+ * query parameter, under the `encoding` the spec declares for it (`form`,
+ * exploded, by default — so a list repeats its name).
+ */
+const urlencodedBody = (
+  value: { [key: string]: JsonValue },
+  encoding: PlaygroundBody["encoding"]
+): string =>
+  Object.entries(value)
+    .flatMap(([name, member]) => {
+      const style = encoding?.[name]?.style ?? "form";
+      return queryPairs(
+        name,
+        styledValue(member),
+        style,
+        encoding?.[name]?.explode ?? defaultExplode(style)
+      );
+    })
+    .join("&");
+
+/** Multipart form parts in order: a list contributes one part per item. */
+const multipartParts = (value: {
+  [key: string]: JsonValue;
+}): [string, string][] =>
+  Object.entries(value).flatMap(([name, member]) =>
+    Array.isArray(member)
+      ? member.map((item): [string, string] => [name, memberText(item)])
+      : [[name, memberText(member)]]
+  );
+
+/**
+ * The editor text serialized for the body's media type, with a parsed mirror
+ * when it is valid JSON. A form body is built from the editor's JSON object;
+ * text that isn't one (mid-edit, or a raw media type) is sent as written.
+ */
 const bodyFor = (
+  body: PlaygroundBody,
   text: string | undefined
-): Pick<RequestSample, "body" | "bodyValue"> => {
+): Pick<RequestSample, "body" | "bodyValue" | "formData"> => {
   if (text === undefined || text === "") {
     return {};
   }
+  const encoding = bodyEncoding(body.contentType);
+  if (encoding === "raw") {
+    return { body: text };
+  }
+  let value: JsonValue;
   try {
-    return { body: text, bodyValue: JSON.parse(text) };
+    value = JSON.parse(text);
   } catch {
-    // Not valid JSON (mid-edit or intentionally raw): still send it — the
-    // structured mirror is only a nicety for consumers of `bodyValue`.
+    // Not valid JSON (mid-edit): still send it — the structured mirror is
+    // only a nicety for consumers of `bodyValue`.
     return { body: text };
   }
+  if (encoding === "json" || !isJsonObject(value)) {
+    return { body: text, bodyValue: value };
+  }
+  return encoding === "form"
+    ? { body: urlencodedBody(value, body.encoding), bodyValue: value }
+    : { bodyValue: value, formData: multipartParts(value) };
 };
 
-/** THE one request builder: samples, copy buttons, and fetch all consume its output. */
-export const buildRequest = (
-  model: PlaygroundModel,
-  values: RequestValues
-): RequestSample => {
-  const base = values.server.replace(TRAILING_SLASH, "");
+/**
+ * A path or header parameter's value under its `style`: an array or object
+ * parameter's JSON text becomes `dog,cat` (simple), `.dog.cat` (label), or
+ * `;tags=dog;tags=cat` (matrix) rather than its JSON.
+ */
+const styledParam = (
+  param: PlaygroundParam,
+  value: string,
+  encode: (text: string) => string
+): string => {
+  const style = param.style ?? defaultStyle(param.in);
+  return templateValue(
+    param.name,
+    parseStyledValue(value, param.type),
+    style,
+    param.explode ?? defaultExplode(style),
+    encode
+  );
+};
 
-  // Path params: an empty value substitutes the raw param name, so a blank
-  // form still renders a readable templated URL instead of `//`.
-  let resolvedPath = model.path;
+/**
+ * The model's path with each `{param}` filled in. An empty value substitutes
+ * the raw param name, so a blank form still renders a readable templated URL
+ * instead of `//`.
+ */
+const resolvePath = (model: PlaygroundModel, values: RequestValues): string => {
+  let resolved = model.path;
   for (const param of model.params) {
     if (param.in !== "path") {
       continue;
     }
     const value = values.params[paramKey(param)] ?? "";
-    resolvedPath = resolvedPath.replace(
+    resolved = resolved.replace(
       `{${param.name}}`,
-      value === "" ? param.name : encodeURIComponent(value)
+      value === "" ? param.name : styledParam(param, value, encodeURIComponent)
     );
   }
+  return resolved;
+};
 
-  // Query params with a value contribute in model order; a query-borne auth
-  // credential appends after — unless the spec also declares that name as an
-  // explicit query parameter, whose (better) example wins.
+/**
+ * The query parameters' `name=value` pairs in model order, each name added to
+ * `seen` so a query-borne credential can defer to it.
+ */
+const queryParams = (
+  model: PlaygroundModel,
+  values: RequestValues,
+  seen: Set<string>
+): string[] => {
   const query: string[] = [];
-  const seen = new Set<string>();
   for (const param of model.params) {
     if (param.in !== "query") {
       continue;
@@ -249,10 +381,37 @@ export const buildRequest = (
       continue;
     }
     seen.add(param.name);
+    const style = param.style ?? defaultStyle(param.in);
     query.push(
-      `${encodeURIComponent(param.name)}=${encodeURIComponent(value)}`
+      ...queryPairs(
+        param.name,
+        parseStyledValue(value, param.type),
+        style,
+        param.explode ?? defaultExplode(style)
+      )
     );
   }
+  return query;
+};
+
+/** THE one request builder: samples, copy buttons, and fetch all consume its output. */
+export const buildRequest = (
+  model: PlaygroundModel,
+  values: RequestValues
+): RequestSample => {
+  // The server's trailing slash only goes when a path is joined onto it: a
+  // GraphQL endpoint (no path) is sent exactly as configured, and
+  // `https://host/graphql/` is not always the same route as `…/graphql`.
+  const base =
+    model.path === ""
+      ? values.server
+      : values.server.replace(TRAILING_SLASH, "");
+
+  // Query params with a value contribute in model order; a query-borne auth
+  // credential appends after — unless the spec also declares that name as an
+  // explicit query parameter, whose (better) example wins.
+  const seen = new Set<string>();
+  const query = queryParams(model, values, seen);
 
   // Auth first, so a spec that also declares the credential as an explicit
   // header parameter overrides it below with its own (better) example.
@@ -266,12 +425,18 @@ export const buildRequest = (
     // Required headers emit even when blank, mirroring the query rule above —
     // except a blank one never clobbers a credential auth already placed
     // under the same name.
-    if (value !== "" || (param.required && headers[param.name] === undefined)) {
+    if (value !== "") {
+      headers[param.name] = styledParam(param, value, (text) => text);
+    } else if (param.required && headers[param.name] === undefined) {
       headers[param.name] = value;
     }
   }
 
-  const { body, bodyValue } = model.body ? bodyFor(values.body) : {};
+  const { body, bodyValue, formData } = model.body
+    ? bodyFor(model.body, values.body)
+    : {};
+  // Multipart parts carry no Content-Type here: the client (curl, fetch,
+  // requests) writes it along with the boundary that separates the parts.
   if (body !== undefined && model.body) {
     headers["Content-Type"] = model.body.contentType;
   }
@@ -280,8 +445,9 @@ export const buildRequest = (
   return {
     body,
     bodyValue,
+    formData,
     headers,
     method: model.method.toUpperCase(),
-    url: `${base}${resolvedPath}${search}`,
+    url: `${base}${resolvePath(model, values)}${search}`,
   };
 };

package/src/components/openapi/schema-tree.ts

@@ -0,0 +1,209 @@
+import {
+  objectProperties,
+  refName,
+  resolveSchema,
+  typeLabel,
+} from "./helpers.ts";
+import type { SchemaLike, SpecValue } from "./helpers.ts";
+
+/**
+ * The expansion plan behind the schema tables (`SchemaTable.astro` and
+ * `SchemaProperty.astro`). Every nested object is server-rendered in full
+ * inside a collapsed `<details>`, so the plan is the page's weight: expanding
+ * each named schema wherever it appears — stopping only at a model nested in
+ * itself — grows exponentially with cross-references (twelve schemas that
+ * each reference four others render tens of thousands of nested tables for
+ * one request body).
+ *
+ * So a named schema expands wherever it appears in the first
+ * {@link REPEAT_DEPTH} named levels, and deeper than that only where it
+ * appears first in the tree, breadth-first; a later mention shows its name
+ * alone. Beyond the first levels each named schema expands at most once, so
+ * the tree stays proportional to the spec instead of to the number of paths
+ * through it, while the shallow nesting typical specs use — `billing` and
+ * `shipping` both an `Address` — renders exactly as before.
+ */
+
+/**
+ * Named-schema nesting depth (the root being 0) up to which a named schema
+ * expands at every mention, even one already expanded elsewhere in the tree.
+ */
+export const REPEAT_DEPTH = 2;
+
+/** A place in the tree a node is planned into; filled in breadth-first. */
+export interface SchemaSlot {
+  node: SchemaNode;
+}
+
+/** One property row of an object table. */
+export interface SchemaRow {
+  name: string;
+  required: boolean;
+  schema: SchemaLike;
+  /** The row's disclosure contents; absent when the row has nothing to show. */
+  children?: SchemaSlot;
+}
+
+/** What one schema table renders. */
+export type SchemaNode =
+  /** A named schema nested inside itself. */
+  | { kind: "circular"; name: string }
+  /** A named schema expanded elsewhere in this tree: its name only. */
+  | { kind: "named"; name: string }
+  | { kind: "array"; itemsLabel: string; items?: SchemaSlot }
+  | {
+      kind: "branches";
+      label: "One of" | "Any of";
+      branches: { label: string; slot: SchemaSlot }[];
+      /**
+       * Properties the schema declares beside its `oneOf`/`anyOf`, which
+       * every variant shares; absent when it declares none.
+       */
+      rows?: SchemaRow[];
+    }
+  | { kind: "properties"; rows: SchemaRow[] }
+  | { kind: "type"; label: string };
+
+const isString = (value: SpecValue): value is string =>
+  typeof value === "string";
+
+const typesOf = (schema: SchemaLike): (string | undefined)[] =>
+  Array.isArray(schema.type) ? schema.type : [schema.type];
+
+/** Whether a schema has nested fields a row can disclose. */
+const hasNestedFields = (candidate: SchemaLike): boolean =>
+  Boolean(
+    candidate.properties ||
+    candidate.allOf ||
+    candidate.oneOf ||
+    candidate.anyOf ||
+    isString(candidate.$ref)
+  );
+
+/** A named schema waiting for its breadth-first turn. */
+interface PendingRef {
+  ancestors: string[];
+  name: string;
+  schema: SchemaLike;
+  slot: SchemaSlot;
+}
+
+/** Plan the table tree for one schema (a request body, a response, a payload). */
+export const schemaTree = (
+  root: SchemaLike,
+  schemas: Record<string, SchemaLike>
+): SchemaNode => {
+  const queue: PendingRef[] = [];
+  const expanded = new Set<string>();
+
+  /**
+   * A table for `schema`, where `ancestors` are the named schemas already
+   * open above it. A `$ref` waits in the queue, so every mention at one depth
+   * is planned before any deeper one; `resolved` plans a dequeued schema's
+   * own body instead.
+   */
+  const table = (
+    schema: SchemaLike,
+    ancestors: string[],
+    resolved = false
+  ): SchemaSlot => {
+    if (!resolved && isString(schema.$ref)) {
+      const name = refName(schema.$ref);
+      if (ancestors.includes(name)) {
+        return { node: { kind: "circular", name } };
+      }
+      const slot: SchemaSlot = { node: { kind: "named", name } };
+      queue.push({ ancestors, name, schema, slot });
+      return slot;
+    }
+    if (typesOf(schema).includes("array")) {
+      // Items stay unresolved, so a self-referential item `$ref` is still
+      // recognized as the circle it is.
+      const { items } = schema;
+      return {
+        node: items
+          ? {
+              items: table(items, ancestors),
+              itemsLabel: typeLabel(items),
+              kind: "array",
+            }
+          : { itemsLabel: typeLabel({}), kind: "array" },
+      };
+    }
+    // A row discloses nested structure — never a model inside itself.
+    const rowChildren = (property: SchemaLike): SchemaSlot | undefined => {
+      if (
+        isString(property.$ref) &&
+        ancestors.includes(refName(property.$ref))
+      ) {
+        return undefined;
+      }
+      const target = resolveSchema(schemas, property);
+      const items = typesOf(target).includes("array")
+        ? resolveSchema(schemas, target.items)
+        : null;
+      return hasNestedFields(target) || (items && hasNestedFields(items))
+        ? table(property, ancestors)
+        : undefined;
+    };
+    const { properties, required } = objectProperties(schema, schemas);
+    const rows: SchemaRow[] = properties.map(([name, property]) => ({
+      children: rowChildren(property),
+      name,
+      required: required.has(name),
+      schema: property,
+    }));
+    // Shared properties beside a `oneOf`/`anyOf` (`amount` and `currency`
+    // next to `Card | BankAccount`) render above the variants, planned first
+    // as they read first.
+    const branches = schema.oneOf ?? schema.anyOf;
+    if (branches) {
+      const node: Extract<SchemaNode, { kind: "branches" }> = {
+        branches: branches.map((branch, index) => ({
+          label: typeLabel(branch) || `Option ${index + 1}`,
+          slot: table(branch, ancestors),
+        })),
+        kind: "branches",
+        label: schema.oneOf ? "One of" : "Any of",
+      };
+      if (rows.length > 0) {
+        node.rows = rows;
+      }
+      return { node };
+    }
+    if (rows.length > 0) {
+      return { node: { kind: "properties", rows } };
+    }
+    return { node: { kind: "type", label: typeLabel(schema) } };
+  };
+
+  const tree = table(root, []);
+  // The queue grows while it drains, in depth order: every mention at one
+  // named depth is queued before the first one at the next.
+  for (const pending of queue) {
+    const depth = pending.ancestors.length;
+    if (depth > REPEAT_DEPTH && expanded.has(pending.name)) {
+      continue;
+    }
+    expanded.add(pending.name);
+    pending.slot.node = table(
+      resolveSchema(schemas, pending.schema),
+      [...pending.ancestors, pending.name],
+      true
+    ).node;
+  }
+  return tree.node;
+};
+
+/**
+ * Whether a row gets a disclosure: it has nested structure, and that structure
+ * isn't just the name of a schema expanded elsewhere (directly, or as the
+ * items of an array).
+ */
+export const rowExpands = (row: SchemaRow): boolean => {
+  const node = row.children?.node;
+  if (!node || node.kind === "named") {
+    return false;
+  }
+  return !(node.kind === "array" && node.items?.node.kind === "named");
+};