blume 2.0.0 → 2.0.2

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,48 @@ 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 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.
+ */
+export const declaredExample = (carrier: ExampleCarrier): SpecValue => {
+  if (carrier.example !== undefined) {
+    return carrier.example;
+  }
+  const { examples } = carrier;
+  if (!isRecord(examples)) {
+    return undefined;
+  }
+  for (const entry of Object.values(examples)) {
+    if (isRecord(entry) && entry.value !== undefined) {
+      return entry.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>
+): SpecValue =>
+  declaredExample(media) ?? 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

@@ -199,6 +199,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;
 }
 

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

@@ -1,4 +1,6 @@
+import { withServerDefaults } from "../../openapi/model.ts";
 import {
+  declaredExample,
   exampleValue,
   objectProperties,
   resolveSchema,
@@ -30,9 +32,30 @@ import type { OperationSecurity, ResolvedScheme } from "./security.ts";
 
 interface MediaTypeLike {
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  examples?: SpecValue;
 }
 
+/** A server entry: its URL template and the variables that fill it. */
+export interface ServerLike {
+  url?: string;
+  variables?: SpecValue;
+}
+
+/**
+ * The servers an operation is sent to: its own `servers` when it declares
+ * any, else its path item's, else the document's — each level overrides the
+ * one above it, as the OpenAPI spec defines.
+ */
+export const effectiveServers = (
+  operation: ServerLike[] | undefined,
+  pathItem: ServerLike[] | undefined,
+  document: ServerLike[] | undefined
+): ServerLike[] =>
+  [operation, pathItem, document].find(
+    (servers) => Array.isArray(servers) && servers.length > 0
+  ) ?? [];
+
 /** Primitive types the flat-body fields UI can edit directly. */
 const PRIMITIVE_TYPES = {
   boolean: true,
@@ -78,7 +101,9 @@ const modelParams = (
       required,
       type: scalarType(param.schema, schemas),
       value: required
-        ? inputValue(param.example ?? exampleValue(param.schema, schemas))
+        ? inputValue(
+            declaredExample(param) ?? exampleValue(param.schema, schemas)
+          )
         : "",
     });
   }
@@ -127,7 +152,12 @@ const bodyFields = (
       description: propertySchema.description,
       enum: propertySchema.enum?.map(String),
       name,
-      required: required.has(name),
+      // A `readOnly` property's `required` binds responses only: a request
+      // shouldn't send the server-generated field at all.
+      required:
+        required.has(name) &&
+        property.readOnly !== true &&
+        propertySchema.readOnly !== true,
       type,
       value: inputValue(defaults?.[name]),
     });
@@ -145,10 +175,8 @@ const modelBody = (
     return undefined;
   }
   const [contentType, mediaType] = media;
-  // SAFETY: `example` comes from the parsed spec document (YAML/JSON), whose
-  // values are exactly the JSON-shaped tree `SpecValue` models.
   const exampleData =
-    (mediaType.example as SpecValue) ?? exampleValue(mediaType.schema, schemas);
+    declaredExample(mediaType) ?? exampleValue(mediaType.schema, schemas);
   return {
     contentType,
     example: toJson(exampleData) ?? "",
@@ -241,7 +269,8 @@ export const operationModel = (args: {
   /** Pre-merged/resolved (`mergeParameters` output). */
   parameters: ParameterLike[];
   requestBody?: { content?: Record<string, MediaTypeLike> };
-  servers: { url?: string }[];
+  /** The operation's effective servers (`effectiveServers` output). */
+  servers: ServerLike[];
   schemas: Record<string, SchemaLike>;
   security: OperationSecurity;
 }): PlaygroundModel => ({
@@ -256,5 +285,8 @@ export const operationModel = (args: {
   method: args.method.toUpperCase(),
   params: modelParams(args.parameters, args.schemas),
   path: args.path,
-  servers: args.servers.map((server) => server.url ?? ""),
+  // Variables resolve to their defaults: the samples and Send need a real URL.
+  servers: args.servers.map((server) =>
+    withServerDefaults(server.url ?? "", server.variables)
+  ),
 });

package/src/components/openapi/panel.ts

@@ -18,23 +18,47 @@ class BlumePanelTabs extends HTMLElement {
 
     const activate = (key: string): void => {
       for (const tab of tabs) {
-        tab.setAttribute(
-          "aria-selected",
-          tab.dataset.panelTab === key ? "true" : "false"
-        );
+        const selected = tab.dataset.panelTab === key;
+        tab.setAttribute("aria-selected", selected ? "true" : "false");
+        // Roving tabindex: Tab reaches the selected tab only, the arrow keys
+        // move between the rest.
+        tab.tabIndex = selected ? 0 : -1;
       }
       for (const panel of panels) {
         panel.classList.toggle("hidden", panel.dataset.panel !== key);
       }
     };
 
-    for (const tab of tabs) {
+    for (const [index, tab] of tabs.entries()) {
       tab.addEventListener("click", () => {
         const key = tab.dataset.panelTab;
         if (key) {
           activate(key);
         }
       });
+      // The WAI-ARIA tabs keyboard pattern, matching `<Tabs>`: arrows move and
+      // wrap, Home and End jump to the ends, and focus follows selection.
+      tab.addEventListener("keydown", (event) => {
+        const last = tabs.length - 1;
+        let next: number | undefined;
+        if (event.key === "ArrowRight") {
+          next = index === last ? 0 : index + 1;
+        } else if (event.key === "ArrowLeft") {
+          next = index === 0 ? last : index - 1;
+        } else if (event.key === "Home") {
+          next = 0;
+        } else if (event.key === "End") {
+          next = last;
+        }
+        const target = next === undefined ? undefined : tabs[next];
+        const key = target?.dataset.panelTab;
+        if (!(target && key)) {
+          return;
+        }
+        event.preventDefault();
+        activate(key);
+        target.focus();
+      });
     }
 
     if (copy) {

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

@@ -155,6 +155,36 @@ const prettyBody = (text: string): string => {
   }
 };
 
+/*
+ * Remembered credentials are a convenience, never a requirement. With storage
+ * blocked (Safari's "Block All Cookies", a sandboxed iframe) even reading the
+ * `localStorage` global throws a SecurityError, which would take the whole
+ * panel down during init; each access is guarded so the form simply forgets.
+ */
+const readStored = (key: string): string | null => {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+};
+
+const writeStored = (key: string, value: string): void => {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+    // Blocked or full storage: the credentials stay in the form only.
+  }
+};
+
+const removeStored = (key: string): void => {
+  try {
+    localStorage.removeItem(key);
+  } catch {
+    // Blocked storage never held the entry in the first place.
+  }
+};
+
 /** A one-line text element for the response/error regions. */
 const line = (className: string, text: string): HTMLElement => {
   const el = document.createElement("div");
@@ -316,7 +346,7 @@ export const initPlayground = (root: HTMLElement): void => {
 
   /** Restore remembered credentials into the inputs and re-check the box. */
   const restoreAuth = (): void => {
-    const stored = localStorage.getItem(storageKey);
+    const stored = readStored(storageKey);
     if (!stored) {
       return;
     }
@@ -355,7 +385,7 @@ export const initPlayground = (root: HTMLElement): void => {
       }
     } catch {
       // A corrupt entry (older format, manual edit) must not break init.
-      localStorage.removeItem(storageKey);
+      removeStored(storageKey);
     }
   };
 
@@ -374,12 +404,12 @@ export const initPlayground = (root: HTMLElement): void => {
       )
     );
     const table = document.createElement("table");
-    table.className = "w-full text-left text-xs";
+    table.className = "w-full text-start text-xs";
     for (const [name, value] of res.headers) {
       const row = document.createElement("tr");
       const header = document.createElement("th");
       header.setAttribute("scope", "row");
-      header.className = "pr-3 align-top font-medium text-muted-foreground";
+      header.className = "pe-3 align-top font-medium text-muted-foreground";
       header.textContent = name;
       const cell = document.createElement("td");
       cell.className = "break-all font-mono text-foreground";
@@ -548,9 +578,9 @@ export const initPlayground = (root: HTMLElement): void => {
     }
     if (remember && target === remember) {
       if (remember.checked) {
-        localStorage.setItem(storageKey, JSON.stringify(collectAuth()));
+        writeStored(storageKey, JSON.stringify(collectAuth()));
       } else {
-        localStorage.removeItem(storageKey);
+        removeStored(storageKey);
       }
     } else if (
       remember?.checked &&
@@ -558,7 +588,7 @@ export const initPlayground = (root: HTMLElement): void => {
         target.dataset.authUsername !== undefined ||
         target.dataset.authPassword !== undefined)
     ) {
-      localStorage.setItem(storageKey, JSON.stringify(collectAuth()));
+      writeStored(storageKey, JSON.stringify(collectAuth()));
     }
     syncSamples();
   };

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

@@ -37,6 +37,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;