blume 2.1.0 → 2.1.2

package/src/components/openapi/message.ts

@@ -41,15 +41,19 @@ export interface MessageServerOption {
   /** `protocol://host+pathname` — what the reader picks between. */
   label: string;
   /**
-   * The spec server with its host/pathname variables at their defaults; the
-   * snippet builders read host/pathname/protocol.
+   * The spec server with its host/pathname variables at their defaults and
+   * its `security` refs resolved; the snippet builders read
+   * host/pathname/protocol/security.
    */
   server: AsyncApiServerObject;
 }
 
 export interface MessageModel {
   action: AsyncApiAction;
-  /** Channel address with `{param}` templates intact, e.g. `user/{id}/signedup`. */
+  /**
+   * Channel address with `{param}` templates intact, e.g. `user/{id}/signedup`
+   * — or the Kafka binding's `topic` when the channel names one.
+   */
   address: string;
   /**
    * Whether the panel offers a live connection. Only WebSocket bindings can be
@@ -57,6 +61,8 @@ export interface MessageModel {
    * CLI samples rather than faked connectivity.
    */
   connectable: boolean;
+  /** Example Kafka message key, sampled from the first message's binding. */
+  key?: string;
   params: MessageParam[];
   payload: MessagePayload;
   /** Normalized binding key (`ws`, `kafka`, `mqtt`, …) when the spec implies one. */
@@ -149,7 +155,7 @@ export const buildMessage = (
   } catch {
     payload = undefined;
   }
-  return {
+  const sample: MessageSample = {
     action: model.action,
     address: model.address.replaceAll(PARAM_TEMPLATE, (template, name) => {
       const value = values.params[String(name)] ?? "";
@@ -158,6 +164,10 @@ export const buildMessage = (
     payload,
     server: custom === "" ? picked?.server : customServer(custom),
   };
+  if (model.key !== undefined) {
+    sample.key = model.key;
+  }
+  return sample;
 };
 
 /**

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

@@ -3,6 +3,7 @@ import {
   declaredExample,
   exampleValue,
   objectProperties,
+  parameterDescription,
   resolveSchema,
   toJson,
 } from "./helpers.ts";
@@ -142,7 +143,7 @@ const modelParams = (
     const required = where === "path" ? true : param.required === true;
     const schema = resolveSchema(schemas, param.schema);
     params.push({
-      description: param.description,
+      description: parameterDescription(param, schemas),
       enum: schema.enum?.map(String),
       in: where,
       name: param.name,
@@ -330,6 +331,19 @@ const authInput = (
   }
 };
 
+/**
+ * The playground's credential inputs for an operation's security: the first
+ * alternative only — the spec's preferred way to authorize, matching what the
+ * static samples always showed.
+ */
+export const playgroundAuth = (
+  security: OperationSecurity
+): PlaygroundAuthInput[] =>
+  (security.alternatives[0] ?? []).flatMap((resolved) => {
+    const input = authInput(resolved);
+    return input ? [input] : [];
+  });
+
 /** Derive the playground request model for one operation, at build time. */
 export const operationModel = (args: {
   method: string;
@@ -344,12 +358,7 @@ export const operationModel = (args: {
   components?: ComponentsLike;
   security: OperationSecurity;
 }): PlaygroundModel => ({
-  // First alternative only — the spec's preferred way to authorize, matching
-  // what the static samples always showed.
-  auth: (args.security.alternatives[0] ?? []).flatMap((resolved) => {
-    const input = authInput(resolved);
-    return input ? [input] : [];
-  }),
+  auth: playgroundAuth(args.security),
   authOptional: args.security.optional,
   body: modelBody(args.requestBody, args.schemas, args.components),
   method: args.method.toUpperCase(),

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

@@ -26,16 +26,34 @@ import { fetchRefusesMethod, sampleLanguages } from "./snippets.ts";
 import type { RequestSample } from "./snippets.ts";
 import { validateJson } from "./validate-json.ts";
 
+const OPENAPI_PROXY_SETTING =
+  "`playground: { proxy: true }` on the `openapi()` reference";
+
+/**
+ * The Blume config setting that turns on the proxy for a panel, keyed by the
+ * `data-proxy-config` the rendering surface stamps on it: an `openapi()` or
+ * `graphql()` reference's `playground` option, or `api.playground` for
+ * hand-written API pages.
+ */
+const PROXY_SETTINGS = new Map([
+  ["api", "`api: { playground: { proxy: true } }`"],
+  ["graphql", "`playground: { proxy: true }` on the `graphql()` reference"],
+  ["openapi", OPENAPI_PROXY_SETTING],
+]);
+
 /**
  * A failed fetch surfaces as a TypeError with no status — almost always the
  * browser's CORS wall, not the API being down — so the message explains the
- * one fix docs authors control instead of parroting "failed to fetch".
+ * one fix docs authors control instead of parroting "failed to fetch", naming
+ * the setting for the surface this panel is on and the server output the
+ * built-in proxy needs.
  */
-const CORS_MESSAGE =
+const corsMessage = (config: string): string =>
   "The browser blocked this request before it reached the API — the API " +
   "likely does not allow cross-origin requests from this docs site. Set " +
-  "`playground: { proxy: true }` on the `openapi()` reference in the Blume " +
-  "config to route playground requests through the docs server instead.";
+  `${PROXY_SETTINGS.get(config) ?? OPENAPI_PROXY_SETTING} in the Blume ` +
+  "config to route playground requests through the docs server instead. " +
+  "The proxy needs server output: a host adapter in `deployment`.";
 
 /**
  * `Cookie` is a forbidden header name: a page cannot set it, so a credential
@@ -253,6 +271,59 @@ const line = (className: string, text: string): HTMLElement => {
   return el;
 };
 
+/** Render one settled HTTP exchange: status + time, headers, pretty body. */
+const renderResponse = (
+  region: HTMLElement,
+  res: Response,
+  ms: number,
+  text: string
+): void => {
+  region.textContent = "";
+  region.append(
+    line(
+      "font-mono font-semibold text-foreground text-sm",
+      `${res.status} ${res.statusText} \u00B7 ${ms} ms`.trim()
+    )
+  );
+  const table = document.createElement("table");
+  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 = "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";
+    cell.textContent = value;
+    row.append(header, cell);
+    table.append(row);
+  }
+  region.append(table);
+  const pre = document.createElement("pre");
+  pre.className =
+    "overflow-x-auto rounded-blume border border-border p-3 font-mono text-foreground text-xs";
+  const code = document.createElement("code");
+  code.textContent = prettyBody(text);
+  pre.append(code);
+  region.append(pre);
+  // At xl the panel is its own scroll region capped to the viewport, so a
+  // response appended under a tall form can land below the panel's fold
+  // where nothing brings it into view. Scroll the panel alone — "nearest",
+  // by hand — and never the document: below xl the panel does not scroll,
+  // and a document scroll would carry the form (Send, the body editor, its
+  // errors) off the top on a phone.
+  const panel = region.closest<HTMLElement>("[data-operation-panel]");
+  if (panel && panel.scrollHeight > panel.clientHeight) {
+    const box = panel.getBoundingClientRect();
+    const target = region.getBoundingClientRect();
+    const delta = Math.min(target.bottom - box.bottom, target.top - box.top);
+    if (delta > 0) {
+      panel.scrollBy({ top: delta });
+    }
+  }
+};
+
 /**
  * Wire the playground inside `root` (the `<blume-playground>` element). Reads
  * the server-rendered model JSON, keeps the request samples in sync with the
@@ -294,6 +365,7 @@ export const initPlayground = (root: HTMLElement): void => {
   const response = root.querySelector<HTMLElement>("[data-response]");
   const storageKey = root.dataset.storageKey ?? "";
   const proxy = root.dataset.proxy ?? "";
+  const proxyConfig = root.dataset.proxyConfig ?? "";
 
   /** True while a send is outstanding, so a second click can't race it. */
   let sending = false;
@@ -451,59 +523,6 @@ export const initPlayground = (root: HTMLElement): void => {
     }
   };
 
-  /** Render one settled HTTP exchange: status + time, headers, pretty body. */
-  const renderResponse = (
-    region: HTMLElement,
-    res: Response,
-    ms: number,
-    text: string
-  ): void => {
-    region.textContent = "";
-    region.append(
-      line(
-        "font-mono font-semibold text-foreground text-sm",
-        `${res.status} ${res.statusText} \u00B7 ${ms} ms`.trim()
-      )
-    );
-    const table = document.createElement("table");
-    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 = "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";
-      cell.textContent = value;
-      row.append(header, cell);
-      table.append(row);
-    }
-    region.append(table);
-    const pre = document.createElement("pre");
-    pre.className =
-      "overflow-x-auto rounded-blume border border-border p-3 font-mono text-foreground text-xs";
-    const code = document.createElement("code");
-    code.textContent = prettyBody(text);
-    pre.append(code);
-    region.append(pre);
-    // At xl the panel is its own scroll region capped to the viewport, so a
-    // response appended under a tall form can land below the panel's fold
-    // where nothing brings it into view. Scroll the panel alone — "nearest",
-    // by hand — and never the document: below xl the panel does not scroll,
-    // and a document scroll would carry the form (Send, the body editor, its
-    // errors) off the top on a phone.
-    const panel = region.closest<HTMLElement>("[data-operation-panel]");
-    if (panel && panel.scrollHeight > panel.clientHeight) {
-      const box = panel.getBoundingClientRect();
-      const target = region.getBoundingClientRect();
-      const delta = Math.min(target.bottom - box.bottom, target.top - box.top);
-      if (delta > 0) {
-        panel.scrollBy({ top: delta });
-      }
-    }
-  };
-
   /**
    * Send the real request. HTTP error statuses render like any response; only
    * a rejected fetch (the CORS wall) gets the explanatory message. One request
@@ -607,7 +626,7 @@ export const initPlayground = (root: HTMLElement): void => {
         const crossOrigin = !proxy && !sample.url.startsWith("/");
         message =
           crossOrigin && (await reachable(sample.url))
-            ? CORS_MESSAGE
+            ? corsMessage(proxyConfig)
             : UNREACHABLE_MESSAGE;
       }
       response.textContent = "";

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

@@ -62,7 +62,7 @@ const isReadOnly = (
  * 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
  * a ref reused by siblings still prunes fully), depth capped. Structure beyond
- * the cut simply goes unvalidated — advisory checks, not a gate.
+ * the cut simply goes unvalidated, so it can never block a send.
  */
 const pruneSchema = (
   schema: SchemaLike | undefined,

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

@@ -2,6 +2,7 @@ import {
   objectProperties,
   refName,
   resolveSchema,
+  soleAllOfMember,
   typeLabel,
 } from "./helpers.ts";
 import type { SchemaLike, SpecValue } from "./helpers.ts";
@@ -67,6 +68,15 @@ export type SchemaNode =
 const isString = (value: SpecValue): value is string =>
   typeof value === "string";
 
+/**
+ * The `$ref` a schema stands for: its own, or its member's when it is a
+ * single-member `allOf` wrapper, which plans (and stops at a circle) the same.
+ */
+const refOf = (schema: SchemaLike): string | undefined => {
+  const ref = schema.$ref ?? soleAllOfMember(schema)?.$ref;
+  return isString(ref) ? ref : undefined;
+};
+
 const typesOf = (schema: SchemaLike): (string | undefined)[] =>
   Array.isArray(schema.type) ? schema.type : [schema.type];
 
@@ -88,13 +98,32 @@ interface PendingRef {
   slot: SchemaSlot;
 }
 
-/** Plan the table tree for one schema (a request body, a response, a payload). */
+/**
+ * Which way a schema's data travels, when its table has one: a request body
+ * leaves out the `readOnly` fields the server generates, and a response the
+ * `writeOnly` ones it never returns, as the examples beside them do.
+ */
+export type SchemaDirection = "request" | "response";
+
+/**
+ * Plan the table tree for one schema (a request body, a response, a payload).
+ * With a `direction`, every table in the tree leaves out the fields that
+ * don't travel that way.
+ */
 export const schemaTree = (
   root: SchemaLike,
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  direction?: SchemaDirection
 ): SchemaNode => {
   const queue: PendingRef[] = [];
   const expanded = new Set<string>();
+  const omitted = direction === "request" ? "readOnly" : "writeOnly";
+
+  /** Whether a property stays out of this tree's tables. */
+  const hidden = (property: SchemaLike): boolean =>
+    direction !== undefined &&
+    (property[omitted] === true ||
+      resolveSchema(schemas, property)[omitted] === true);
 
   /**
    * A table for `schema`, where `ancestors` are the named schemas already
@@ -107,8 +136,9 @@ export const schemaTree = (
     ancestors: string[],
     resolved = false
   ): SchemaSlot => {
-    if (!resolved && isString(schema.$ref)) {
-      const name = refName(schema.$ref);
+    const ref = resolved ? undefined : refOf(schema);
+    if (ref) {
+      const name = refName(ref);
       if (ancestors.includes(name)) {
         return { node: { kind: "circular", name } };
       }
@@ -132,10 +162,8 @@ export const schemaTree = (
     }
     // 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))
-      ) {
+      const propertyRef = refOf(property);
+      if (propertyRef && ancestors.includes(refName(propertyRef))) {
         return undefined;
       }
       const target = resolveSchema(schemas, property);
@@ -147,12 +175,14 @@ export const schemaTree = (
         : undefined;
     };
     const { properties, required } = objectProperties(schema, schemas);
-    const rows: SchemaRow[] = properties.map(([name, property]) => ({
-      children: rowChildren(property),
-      name,
-      required: required.has(name),
-      schema: property,
-    }));
+    const rows: SchemaRow[] = properties
+      .filter(([, property]) => !hidden(property))
+      .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.

package/src/components/openapi/security.ts

@@ -32,6 +32,11 @@ export interface ResolvedScheme {
   /** The scheme object; undefined when the requirement names an unknown one. */
   scheme?: SecuritySchemeLike;
   scopes: string[];
+  /**
+   * AsyncAPI: the servers that declare this scheme, set only when the
+   * channel's servers don't all declare the same ones.
+   */
+  servers?: string[];
 }
 
 /** The security state one operation renders. */
@@ -40,6 +45,11 @@ export interface OperationSecurity {
   alternatives: ResolvedScheme[][];
   /** True when an empty requirement also allows unauthenticated calls. */
   optional: boolean;
+  /**
+   * AsyncAPI: the servers that declare no security while others do, so the
+   * schemes apply on the other servers only.
+   */
+  unauthenticatedServers?: string[];
 }
 
 /**

package/src/components/openapi/snippets.ts

@@ -1053,19 +1053,21 @@ export const sampleLanguageInfo = (raw: string): SampleLanguageInfo | null => {
   return language ? { label: language.label, lang: language.lang } : null;
 };
 
+/** `openapi()`'s default `codeSamples`, which hand-written endpoint pages always use. */
+export const DEFAULT_SAMPLE_LANGUAGES = ["curl", "js", "python"];
+
 /**
  * The sample languages to render, resolved from config ids (unknown ids
- * dropped). `false` renders none; an empty list, the defaults.
+ * dropped), in order. `false` and an empty list both render none.
  */
 export const sampleLanguages = (ids: string[] | false): SampleLanguage[] => {
   if (ids === false) {
     return [];
   }
-  const wanted = ids.length > 0 ? ids : ["curl", "js", "python"];
   const byId = new Map(LANGUAGES.map((entry) => [entry.id, entry]));
   const out: SampleLanguage[] = [];
   const seen = new Set<string>();
-  for (const raw of wanted) {
+  for (const raw of ids) {
     const id = sampleLanguageId(raw);
     const language = byId.get(id);
     if (language && !seen.has(id)) {

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

@@ -4,9 +4,10 @@ import type { ValidationSchema } from "./request.ts";
  * Minimal JSON-schema validation for the playground body editor. Client-safe
  * and dependency-free by design: the server prunes the operation's schema into
  * the tiny `ValidationSchema` subset (`operation-model.ts`), so a full
- * draft-2020 validator would be dead weight in the browser bundle. Checks are
- * advisory — they catch the common "typo'd a required field" mistakes, they do
- * not gate the Send button.
+ * draft-2020 validator would be dead weight in the browser bundle. The checks
+ * catch the common "typo'd a required field" mistakes, and any error they
+ * report blocks the Try it send (`playground-client.ts`) and the event
+ * composer's connect and send (`message-composer.ts`).
  */
 
 /** An already-parsed JSON object — string keys, parsed-JSON values. */

package/src/components/powered-by-middleware.ts

@@ -0,0 +1,33 @@
+import type { MiddlewareHandler } from "astro";
+
+import { POWERED_BY_HEADERS } from "../core/powered-by.ts";
+
+/**
+ * Names Blume in the responses Astro renders (wired by the integration unless
+ * `poweredBy` is `false`), the server-rendered ones a host's own header rules
+ * don't reach. Innermost, so a page or the project's own middleware that sets
+ * a header of the same name keeps its value. Headers are set in place; a
+ * response whose headers are immutable (a proxied `fetch()` result) is copied
+ * first.
+ */
+export const onRequest: MiddlewareHandler = async (_context, render) => {
+  const response = await render();
+  const missing = Object.entries(POWERED_BY_HEADERS).filter(
+    ([name]) => !response.headers.has(name)
+  );
+  if (missing.length === 0) {
+    return response;
+  }
+  try {
+    for (const [name, value] of missing) {
+      response.headers.set(name, value);
+    }
+    return response;
+  } catch {
+    const copy = new Response(response.body, response);
+    for (const [name, value] of missing) {
+      copy.headers.set(name, value);
+    }
+    return copy;
+  }
+};

package/src/core/changelog-index.ts

@@ -1,4 +1,6 @@
-import type { ResolvedConfig } from "./schema.ts";
+import type { UIStrings } from "./i18n-ui.ts";
+import { resolveLocalizable } from "./localizable.ts";
+import type { LocalizableLabel, ResolvedConfig } from "./schema.ts";
 import { sourcesOfKind } from "./sources/collection.ts";
 import type { PageRecord } from "./types.ts";
 
@@ -22,3 +24,31 @@ export const hasChangelogIndex = (
       page.contentType === "changelog" &&
       !(page.meta.draft || page.meta.sidebar.hidden)
   ) || sourcesOfKind(config, "github-releases").length > 0;
+
+/**
+ * A locale's UI strings with the index's title and description taken from
+ * the `changelog` config where it sets them (a string, or a per-locale map
+ * resolved like a header label), so every surface that reads the
+ * `changelog` strings (the page, its OG card, its Markdown mirror) agrees.
+ */
+export const withChangelogIndexText = (
+  config: ResolvedConfig,
+  ui: UIStrings,
+  locale?: string
+): UIStrings => {
+  const text = (label: LocalizableLabel | undefined, fallback: string) =>
+    label === undefined
+      ? fallback
+      : resolveLocalizable(label, locale, config.i18n?.defaultLocale);
+  return {
+    ...ui,
+    changelog: {
+      ...ui.changelog,
+      description: text(
+        config.changelog?.description,
+        ui.changelog.description
+      ),
+      title: text(config.changelog?.title, ui.changelog.title),
+    },
+  };
+};

package/src/core/component-diagnostics.ts

@@ -1,3 +1,5 @@
+import { relative } from "pathe";
+
 import { BUILTIN_MDX_TAGS } from "./builtin-tags.ts";
 import type { Diagnostic, PageRecord } from "./types.ts";
 
@@ -42,3 +44,54 @@ export const validateUsedComponents = (
   }
   return diagnostics;
 };
+
+/** What example discovery found: where it looked, and each example's key. */
+export interface ExampleKeys {
+  /** Absolute directory the examples were discovered under. */
+  dir: string;
+  examples: readonly { path: string }[];
+}
+
+/**
+ * Warn about each `<Component path>` in an `.mdx` page that names no
+ * discovered example. The page still renders, with a "No example found" box
+ * where the preview should be, so without this a typo or a moved example
+ * ships silently. Reported at the `path` value, in the partial that holds it
+ * when an `<include>` brought it in; a file shared by several locales is
+ * reported once. `extraTags` are the project's own components (islands +
+ * overrides), as for {@link validateUsedComponents}: one named `Component`
+ * replaces the built-in and resolves `path` its own way, so none is checked.
+ */
+export const missingExampleDiagnostics = (
+  pages: readonly PageRecord[],
+  discovery: ExampleKeys,
+  root: string,
+  extraTags: ReadonlySet<string>
+): Diagnostic[] => {
+  if (extraTags.has("Component")) {
+    return [];
+  }
+  const known = new Set(discovery.examples.map((example) => example.path));
+  const dir = relative(root, discovery.dir) || ".";
+  const diagnostics: Diagnostic[] = [];
+  const seen = new Set<string>();
+  for (const page of pages) {
+    for (const use of page.examplesUsed ?? []) {
+      const file = use.file ?? page.sourcePath ?? page.id;
+      const key = `${file}:${use.line}:${use.column}`;
+      if (!(known.has(use.path) || seen.has(key))) {
+        seen.add(key);
+        diagnostics.push({
+          code: "BLUME_EXAMPLE_NOT_FOUND",
+          column: use.column,
+          file,
+          line: use.line,
+          message: `<Component path="${use.path}"> in ${page.route} names no example, so the page shows "No example found" in its place.`,
+          severity: "warning",
+          suggestion: `Fix the path, or add the example under ${dir}/: \`path\` is its location there, without the extension.`,
+        });
+      }
+    }
+  }
+  return diagnostics;
+};

package/src/core/component-overrides.ts

@@ -69,6 +69,29 @@ type Group = (typeof GROUPS)[number];
 
 const isGroup = (name: string): name is Group => GROUP_SET.has(name);
 
+/**
+ * The `layout` keys the built-in chrome reads (`RootLayout.astro` and
+ * `Header.astro`). Any other key is never rendered, so it's warned about
+ * rather than silently dropped; a typo or wrong case would otherwise leave
+ * the built-in in place with no sign why.
+ */
+const LAYOUT_SLOTS = [
+  "Layout",
+  "Header",
+  "Logo",
+  "Search",
+  "Sidebar",
+  "MobileNav",
+  "Breadcrumbs",
+  "TableOfContents",
+  "Pagination",
+  "Feedback",
+  "PageHeader",
+  "PageFooter",
+  "Footer",
+];
+const LAYOUT_SLOT_SET: ReadonlySet<string> = new Set(LAYOUT_SLOTS);
+
 /** The authoring forms an override accepts; the fix every rejection points at. */
 export const ACCEPTED_OVERRIDE_FORMS =
   "Each override must be an imported identifier, a path string, or a `{ component, client, media }` object literal whose `component` is an imported identifier or a path string.";
@@ -628,6 +651,15 @@ const collectGroupOverrides = (
     if (normalized) {
       result[name].push(normalized);
     }
+    if (
+      name === "layout" &&
+      normalized &&
+      !LAYOUT_SLOT_SET.has(normalized.key)
+    ) {
+      context.warnings.push(
+        `Layout override "${normalized.key}" isn't a layout slot, so nothing renders it. Use one of: ${LAYOUT_SLOTS.join(", ")}.`
+      );
+    }
   }
 };