blume 2.0.1 → 2.0.2

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;

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

@@ -0,0 +1,203 @@
+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 }[];
+    }
+  | { 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" },
+      };
+    }
+    const branches = schema.oneOf ?? schema.anyOf;
+    if (branches) {
+      return {
+        node: {
+          branches: branches.map((branch, index) => ({
+            label: typeLabel(branch) || `Option ${index + 1}`,
+            slot: table(branch, ancestors),
+          })),
+          kind: "branches",
+          label: schema.oneOf ? "One of" : "Any of",
+        },
+      };
+    }
+    // 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);
+    if (properties.length > 0) {
+      return {
+        node: {
+          kind: "properties",
+          rows: properties.map(([name, property]) => ({
+            children: rowChildren(property),
+            name,
+            required: required.has(name),
+            schema: property,
+          })),
+        },
+      };
+    }
+    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");
+};

package/src/components/openapi/snippets.ts

@@ -22,26 +22,42 @@ const headerLines = (
 ): string[] =>
   Object.entries(headers).map(([key, value]) => format(key, value));
 
+/**
+ * A single-quoted POSIX shell word. Nothing expands inside single quotes — no
+ * `$`, backtick, `!`, or `\` — so a value reaches curl byte for byte; a
+ * literal `'` closes the quote, adds an escaped one, and reopens it.
+ */
+const shellQuote = (value: string): string =>
+  `'${value.replaceAll("'", String.raw`'\''`)}'`;
+
+/**
+ * A double-quoted string literal for the JavaScript and Python samples. JSON's
+ * string escapes are a subset of both languages' — a quote in a header value
+ * (`If-Match: "33a64df5"`) or a backslash becomes an escape rather than
+ * ending the literal early.
+ */
+const stringLiteral = (value: string): string => JSON.stringify(value);
+
 const curlSnippet = (sample: RequestSample): string => {
   const lines = [
-    `curl -X ${sample.method} "${sample.url}"`,
-    ...headerLines(sample.headers, (key, value) => `  -H "${key}: ${value}"`),
+    `curl -X ${sample.method} ${shellQuote(sample.url)}`,
+    ...headerLines(
+      sample.headers,
+      (key, value) => `  -H ${shellQuote(`${key}: ${value}`)}`
+    ),
   ];
   if (sample.body) {
-    // Close-quote/escaped-quote/reopen: the POSIX way to put a literal ' in a
-    // single-quoted string, so an example like "it's" doesn't break the shell.
-    const escapedBody = sample.body.replaceAll("'", String.raw`'\''`);
-    lines.push(`  -d '${escapedBody}'`);
+    lines.push(`  -d ${shellQuote(sample.body)}`);
   }
   return lines.join(" \\\n");
 };
 
 const fetchSnippet = (sample: RequestSample): string => {
-  const options = [`  method: "${sample.method}"`];
+  const options = [`  method: ${stringLiteral(sample.method)}`];
   if (Object.keys(sample.headers).length > 0) {
     const headers = headerLines(
       sample.headers,
-      (key, value) => `    "${key}": "${value}"`
+      (key, value) => `    ${stringLiteral(key)}: ${stringLiteral(value)}`
     ).join(",\n");
     options.push(`  headers: {\n${headers}\n  }`);
   }
@@ -53,28 +69,27 @@ const fetchSnippet = (sample: RequestSample): string => {
     // and an id past 2^53 loses digits through a JS number. The string
     // literal also stays syntactically valid while the editor holds mid-edit
     // text that isn't JSON yet.
-    options.push(`  body: ${JSON.stringify(sample.body)}`);
+    options.push(`  body: ${stringLiteral(sample.body)}`);
   }
-  return `const response = await fetch("${sample.url}", {\n${options.join(
+  return `const response = await fetch(${stringLiteral(sample.url)}, {\n${options.join(
     ",\n"
   )}\n});`;
 };
 
 const pythonSnippet = (sample: RequestSample): string => {
-  const args = [`    "${sample.url}"`];
+  const args = [`    ${stringLiteral(sample.url)}`];
   if (Object.keys(sample.headers).length > 0) {
     const headers = headerLines(
       sample.headers,
-      (key, value) => `        "${key}": "${value}"`
+      (key, value) => `        ${stringLiteral(key)}: ${stringLiteral(value)}`
     ).join(",\n");
     args.push(`    headers={\n${headers}\n    }`);
   }
   if (sample.body) {
     // Same rule as the fetch snippet: the raw text travels as a string via
-    // `data=` (JSON string escapes are a subset of Python's, so the literal is
-    // valid) rather than a `json=` dict — a Python literal re-serializes
+    // `data=` rather than a `json=` dict — a Python literal re-serializes
     // `1e400` as `Infinity` and would otherwise diverge from the live send.
-    args.push(`    data=${JSON.stringify(sample.body)}`);
+    args.push(`    data=${stringLiteral(sample.body)}`);
   }
   return `import requests\n\nresponse = requests.${sample.method.toLowerCase()}(\n${args.join(
     ",\n"

package/src/components/openapi/validate-json.ts

@@ -74,7 +74,7 @@ const walk = (
   path: string,
   errors: string[]
 ): void => {
-  if (!schema) {
+  if (!schema || (value === null && schema.nullable === true)) {
     return;
   }
   if (schema.type !== undefined && !matchesType(value, schema.type)) {

package/src/core/base-path.ts

@@ -88,6 +88,21 @@ export const withBasePath = (basePath: string, route: string): string => {
   return route === "/" ? basePath : `${basePath}${route}`;
 };
 
+/**
+ * Mount a route Blume generates from content under `basePath`,
+ * unconditionally. {@link withBasePath} leaves a route that already starts
+ * with the base alone, which is right for a link an author based by hand but
+ * wrong for a content route: with `basePath: "/docs"`, `docs/guide.md` routes
+ * to `/docs/guide` before the base and publishes at `/docs/docs/guide`, not on
+ * top of the root `guide.md`.
+ */
+export const mountBasePath = (basePath: string, route: string): string => {
+  if (!basePath) {
+    return route;
+  }
+  return route === "/" ? basePath : `${basePath}${route}`;
+};
+
 /**
  * {@link withBasePath} for the composed `deployment.base` + `basePath` stack
  * (`/base` + `/docs` serves pages at `/base/docs/x`). The hand-written-base

package/src/core/config-input.ts

@@ -596,14 +596,14 @@ export interface LlmsTxtConfig {
   /**
    * Markdown placed after the title and summary in `llms.txt`, before the
    * page sections — the llms.txt spec's "details" block. Use it to tell
-   * agents when to reach for the product and how to call it (a "When to use"
-   * heading, the install command, the package name). Blank values are
-   * dropped.
+   * agents when to reach for the product and how to call it (the install
+   * command, the package name). The spec allows any Markdown there but
+   * headings. Blank values are dropped.
    *
    * ```ts
    * agents: {
    *   llmsTxt: {
-   *     details: "## When to use Acme\n\nUse Acme when…",
+   *     details: "Use Acme when…",
    *   },
    * }
    * ```