blume 2.0.0 → 2.0.2

package/src/components/layout/Search.astro

@@ -12,7 +12,7 @@ import { flattenPages } from "./nav-utils.ts";
 // `SearchFn` it returns. Only the configured provider's SDK is bundled.
 
 interface Props {
-  askEnabled?: boolean;
+  assistantEnabled?: boolean;
   navigation?: Navigation;
   /** Curated empty-state pages; falls back to the first sidebar pages when empty or omitted. */
   popularPages?: { icon?: string; label: string; route: string }[];
@@ -27,7 +27,7 @@ interface Props {
 }
 
 const {
-  askEnabled = false,
+  assistantEnabled = false,
   navigation,
   popularPages,
   strings,
@@ -60,13 +60,14 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
 <blume-search
   class="contents"
-  data-ask={askEnabled ? "" : undefined}
+  data-ask={assistantEnabled ? "" : undefined}
   data-i18n-all={s.all}
-  data-i18n-ask={s.askAi}
-  data-i18n-ask-hint={s.askAiHint}
+  data-i18n-ask={s.assistant}
+  data-i18n-ask-hint={s.assistantHint}
   data-i18n-dev={s.devOnly}
   data-i18n-empty={s.noResults}
   data-i18n-error={s.error}
+  data-i18n-latest={s.latest}
   data-i18n-popular={s.popular}
   data-i18n-results={s.results}
   data-locale={locale || undefined}
@@ -309,7 +310,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       loadFailed = false;
       /** First-open client/index load still in flight. */
       loading = false;
-      askEnabled = false;
+      assistantEnabled = false;
       popular: PopularPage[] = [];
       selectables: Selectable[] = [];
       selectedIndex = -1;
@@ -323,11 +324,12 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       devOnlyMsg = "Search is available in the production build.";
       noResultsMsg = "No results found.";
       errorMsg = "Something went wrong. Please try again.";
-      askMsg = "Ask AI";
+      askMsg = "Assistant";
       askHintMsg = "Get an instant answer from AI";
       allMsg = "All";
       popularMsg = "Popular";
       resultsMsg = "Results";
+      latestMsg = "latest";
       // The active locale to filter to (null when i18n is off), and whether the
       // reader has opted to search across every language instead.
       locale: string | null = null;
@@ -351,7 +353,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           !event.shiftKey &&
           !event.altKey
         ) {
-          // ⌘K toggles, mirroring the Ask AI panel's ⌘I: pressing it with
+          // ⌘K toggles, mirroring the assistant panel's ⌘I: pressing it with
           // the dialog open must close it, not re-showModal an open dialog
           // (an InvalidStateError on older engines).
           event.preventDefault();
@@ -382,6 +384,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           this.getAttribute("data-i18n-popular") || this.popularMsg;
         this.resultsMsg =
           this.getAttribute("data-i18n-results") || this.resultsMsg;
+        this.latestMsg =
+          this.getAttribute("data-i18n-latest") || this.latestMsg;
         this.locale = this.getAttribute("data-locale");
         // "" (the current docs) is a real version value, so a presence flag —
         // not the attribute's truthiness — decides whether filtering is on.
@@ -394,7 +398,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.results = this.querySelector("[data-blume-search-results]")!;
         this.message = this.querySelector("[data-blume-search-message]")!;
         this.preview = this.querySelector("[data-blume-search-preview]")!;
-        this.askEnabled = this.hasAttribute("data-ask");
+        this.assistantEnabled = this.hasAttribute("data-ask");
 
         const popularScript = this.querySelector(
           "[data-blume-search-popular]"
@@ -636,7 +640,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
         this.renderFilters(result.sections);
 
-        if (this.askEnabled) {
+        if (this.assistantEnabled) {
           const group = this.addGroup(this.askMsg);
           const ask = this.createAskRow(query);
           group.appendChild(ask.el);
@@ -650,7 +654,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
             group.appendChild(item.el);
             this.selectables.push(item);
           }
-        } else if (!this.askEnabled) {
+        } else if (!this.assistantEnabled) {
           this.setMessage(this.noResultsMsg);
         }
 
@@ -658,7 +662,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       }
 
       renderEmpty() {
-        if (this.askEnabled) {
+        if (this.assistantEnabled) {
           const group = this.addGroup(this.askMsg);
           const ask = this.createAskRow("");
           group.appendChild(ask.el);
@@ -765,7 +769,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         // reader knows they're about to leave the docs they're viewing.
         const versionTag =
           this.versioned && hit.version !== undefined && hit.version !== this.version
-            ? `<span class="ms-2 inline-block rounded-full bg-muted px-1.5 py-0.5 align-middle text-[0.65rem] text-muted-foreground">${escapeHtml(hit.version || "latest")}</span>`
+            ? `<span class="ms-2 inline-block rounded-full bg-muted px-1.5 py-0.5 align-middle text-[0.65rem] text-muted-foreground">${escapeHtml(hit.version || this.latestMsg)}</span>`
             : "";
         el.innerHTML = `
           <span class="mt-0.5 shrink-0 text-muted-foreground">${svg("file")}</span>
@@ -874,7 +878,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           const query = this.input.value.trim();
           this.dialog.close();
           window.dispatchEvent(
-            new CustomEvent("blume:open-ask-ai", { detail: { query } })
+            new CustomEvent("blume:open-assistant", { detail: { query } })
           );
         } else if (item.url) {
           // Close first so the dialog isn't left open over the transition;

package/src/components/layout/analytics-client.ts

@@ -29,6 +29,7 @@ interface AnalyticsWindow {
   analytics?: { track?: (event: string, props?: TrackProps) => void };
   clarity?: (command: "event", event: string) => void;
   dataLayer?: DataLayer;
+  databuddy?: { track?: (event: string, props?: TrackProps) => void };
   fathom?: { trackEvent?: (event: string) => void };
   gtag?: (command: "event", event: string, props?: TrackProps) => void;
   heap?: { track?: (event: string, props?: TrackProps) => void };
@@ -82,6 +83,7 @@ const trackGlobals = (
   attempt(() => (w.__blumeGtmLayer ?? w.dataLayer)?.push({ ...props, event }));
   // Privacy-first counters take a name, some with properties.
   attempt(() => w.plausible?.(event, { props }));
+  attempt(() => w.databuddy?.track?.(event, props));
   attempt(() => w.fathom?.trackEvent?.(event));
   // Pirsch stringifies `meta` values in place, so it gets its own copy and
   // the `blume:track` listeners still see the original types.
@@ -96,7 +98,7 @@ const trackGlobals = (
  * @param props Properties every provider receives.
  * @param local Properties only the `blume:track` CustomEvent carries — free
  *   text a site may bridge to a provider on its own terms, but that must not
- *   reach third parties unasked (a reader's Ask AI question, for instance).
+ *   reach third parties unasked (a reader's question to the assistant, for instance).
  */
 export const track = (
   event: string,

package/src/components/layout/drawer-inert.ts

@@ -119,7 +119,7 @@ export const syncDrawerInert = (): void => {
   });
   document.addEventListener("astro:after-swap", sync);
   document.addEventListener("keydown", (event) => {
-    // An open dialog (search, Ask AI) closes itself on Escape first.
+    // An open dialog (search, the assistant) closes itself on Escape first.
     if (
       event.key !== "Escape" ||
       !isOpen() ||

package/src/components/openapi/GraphqlType.astro

@@ -1,4 +1,5 @@
 ---
+import { isSafeHref } from "../../core/safe-href.ts";
 import type { GraphqlDocument } from "../../openapi/graphql.ts";
 import { graphqlTypeDef } from "../../openapi/graphql.ts";
 import type { ApiOperationRef, ApiSpecData } from "../../openapi/model.ts";
@@ -65,9 +66,16 @@ const SECTION_HEADING = "mb-2 font-semibold text-foreground text-sm";
       {type.specifiedByUrl && (
         <div class="mb-4 text-muted-foreground text-sm">
           Specified by{" "}
-          <a class="text-accent hover:underline" href={type.specifiedByUrl}>
-            {type.specifiedByUrl}
-          </a>
+          {/* The URL comes from the schema, someone else's content: a
+              `javascript:` one would run on the docs origin when clicked, so
+              only a safe destination becomes a link. */}
+          {isSafeHref(type.specifiedByUrl) ? (
+            <a class="text-accent hover:underline" href={type.specifiedByUrl}>
+              {type.specifiedByUrl}
+            </a>
+          ) : (
+            <code class="break-all">{type.specifiedByUrl}</code>
+          )}
         </div>
       )}
       <GraphqlFieldsTable

package/src/components/openapi/MessageComposer.astro

@@ -133,7 +133,7 @@ const BUTTON_QUIET =
           Payload
           {
             model.payload.contentType && (
-              <span class="ml-1.5 font-mono normal-case">
+              <span class="ms-1.5 font-mono normal-case">
                 {model.payload.contentType}
               </span>
             )

package/src/components/openapi/Operation.astro

@@ -6,8 +6,13 @@ import {
   type ParameterLike,
   resolveComponentRef,
   type SchemaLike,
+  type SpecValue,
 } from "./helpers.ts";
-import { operationModel } from "./operation-model.ts";
+import {
+  effectiveServers,
+  operationModel,
+  type ServerLike,
+} from "./operation-model.ts";
 import { buildRequest, defaultValues } from "./request.ts";
 import {
   effectiveSecurity,
@@ -35,7 +40,8 @@ interface Props {
 
 interface MediaTypeLike {
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  examples?: SpecValue;
 }
 
 interface RequestBodyLike {
@@ -59,6 +65,7 @@ interface FullOperation {
   requestBody?: RequestBodyLike;
   responses?: Record<string, ResponseLike>;
   security?: SecurityRequirementLike[];
+  servers?: ServerLike[];
 }
 
 const { source, id } = Astro.props;
@@ -73,7 +80,10 @@ const isGraphql = spec?.kind === "graphql";
 const doc = (spec?.document ?? {}) as {
   paths?: Record<
     string,
-    Record<string, unknown> & { parameters?: ParameterLike[] }
+    Record<string, unknown> & {
+      parameters?: ParameterLike[];
+      servers?: ServerLike[];
+    }
   >;
   components?: {
     schemas?: Record<string, SchemaLike>;
@@ -83,7 +93,7 @@ const doc = (spec?.document ?? {}) as {
     securitySchemes?: Record<string, SecuritySchemeLike>;
   };
   security?: SecurityRequirementLike[];
-  servers?: { url?: string }[];
+  servers?: ServerLike[];
 };
 const pathItem = ref ? doc.paths?.[ref.path] : undefined;
 const operation = (
@@ -123,7 +133,13 @@ const model =
         requestBody,
         schemas,
         security,
-        servers: doc.servers ?? [],
+        // An operation's own `servers` override its path item's, which
+        // override the document's.
+        servers: effectiveServers(
+          operation.servers,
+          pathItem?.servers,
+          doc.servers
+        ),
       })
     : null;
 const sample = model ? buildRequest(model, defaultValues(model)) : null;

package/src/components/openapi/PanelTabs.astro

@@ -62,7 +62,9 @@ const TAB_CLASS =
       </div>
       <blume-panel-tabs class="block overflow-hidden rounded-blume border border-border bg-background">
         <div class="flex items-center justify-between gap-2 border-border border-b px-3">
-          <div class="flex flex-wrap gap-4" role="tablist">
+          <div aria-label={heading} class="flex flex-wrap gap-4" role="tablist">
+            {/* Roving tabindex: only the selected tab is in the Tab order, and
+                the arrow keys, Home, and End move between tabs (panel.ts). */}
             {panels.map((panel, index) => (
               <button
                 aria-controls={idFor("panel", panel.key)}
@@ -71,6 +73,7 @@ const TAB_CLASS =
                 data-panel-tab={panel.key}
                 id={idFor("tab", panel.key)}
                 role="tab"
+                tabindex={index === 0 ? "0" : "-1"}
                 type="button"
               >
                 {panel.label}

package/src/components/openapi/Playground.astro

@@ -1,5 +1,6 @@
 ---
 import { stableId } from "../content/tooltip-id.ts";
+import { withBase } from "../islands/base-path.ts";
 
 import { paramKey, type PlaygroundModel } from "./request.ts";
 
@@ -23,6 +24,11 @@ interface Props {
 
 const { model, proxy, slug, operation } = Astro.props;
 
+// The built-in proxy route carries the site `basePath` but, like every
+// internal URL in the spec data, not `deployment.base`; `withBase` adds it
+// and passes an external proxy URL through untouched.
+const proxyUrl = proxy ? withBase(proxy) : undefined;
+
 // `</script>`-proof embedding: `<` only ever occurs inside JSON strings,
 // where the \u escape is equivalent, so a spec description can never close
 // the model script early and inject markup.
@@ -46,7 +52,7 @@ const CHECKBOX_ROW =
 
 <blume-playground
   class="mb-6 block"
-  data-proxy={proxy || undefined}
+  data-proxy={proxyUrl}
   data-storage-key={`blume-playground:${slug}:${operation}`}
 >
   <script
@@ -194,7 +200,7 @@ const CHECKBOX_ROW =
           <div class={GROUP}>
             <div class={GROUP_HEADING}>
               Body
-              <span class="ml-1.5 font-mono normal-case">
+              <span class="ms-1.5 font-mono normal-case">
                 {model.body.contentType}
               </span>
             </div>

package/src/components/openapi/RequestPanel.astro

@@ -2,14 +2,20 @@
 import data from "blume:data";
 
 import { highlightCode } from "../../markdown/index.ts";
-import { exampleValue, type SchemaLike, toJson } from "./helpers.ts";
+import {
+  responseExample,
+  type SchemaLike,
+  type SpecValue,
+  toJson,
+} from "./helpers.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import PanelTabs from "./PanelTabs.astro";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
 
 interface MediaTypeLike {
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  examples?: SpecValue;
 }
 
 interface ResponseLike {
@@ -38,9 +44,7 @@ const responsePanels = await Promise.all(
       Object.entries(response.content ?? {}).find(([type]) =>
         type.includes("json")
       )?.[1] ?? Object.values(response.content ?? {})[0];
-    const example = media
-      ? (media.example ?? exampleValue(media.schema, schemas))
-      : undefined;
+    const example = media ? responseExample(media, schemas) : undefined;
     const html =
       example === undefined || example === null
         ? null

package/src/components/openapi/SchemaProperty.astro

@@ -3,33 +3,23 @@ import Description from "./Description.astro";
 import {
   constraints,
   isNullable,
-  refName,
   resolveSchema,
   type SchemaLike,
   typeLabel,
 } from "./helpers.ts";
+import { rowExpands, type SchemaRow } from "./schema-tree.ts";
 import SchemaTable from "./SchemaTable.astro";
 
 interface Props {
-  name: string;
-  schema: SchemaLike;
-  required?: boolean;
+  /** One planned row of the parent table (see `schema-tree.ts`). */
+  row: SchemaRow;
   schemas: Record<string, SchemaLike>;
-  seen?: string[];
   expandAll?: boolean;
 }
 
-const {
-  name,
-  schema,
-  required = false,
-  schemas,
-  seen = [],
-  expandAll = false,
-} = Astro.props;
+const { row, schemas, expandAll = false } = Astro.props;
+const { name, schema, required } = row;
 
-const refLabel = typeof schema.$ref === "string" ? refName(schema.$ref) : null;
-const circular = refLabel !== null && seen.includes(refLabel);
 const resolved = resolveSchema(schemas, schema);
 
 const type = typeLabel(schema);
@@ -39,20 +29,9 @@ const nullable = isNullable(resolved);
 const enumValues = Array.isArray(resolved.enum) ? resolved.enum : null;
 const limits = constraints(resolved);
 
-const types = Array.isArray(resolved.type) ? resolved.type : [resolved.type];
-const isArray = types.includes("array");
-const items = isArray ? resolveSchema(schemas, resolved.items) : null;
-
-const hasObjectShape = (candidate: SchemaLike): boolean =>
-  Boolean(
-    candidate.properties ||
-      candidate.allOf ||
-      candidate.oneOf ||
-      candidate.anyOf ||
-      typeof candidate.$ref === "string"
-  );
-const expandable =
-  !circular && (hasObjectShape(resolved) || Boolean(items && hasObjectShape(items)));
+// Circles and schemas expanded elsewhere in the tree have no disclosure; the
+// type label names them.
+const children = rowExpands(row) ? row.children : undefined;
 ---
 
 {/* The row's vertical scale is 8 / 12 / 16px, and every other reference table copies it. A
@@ -103,17 +82,16 @@ const expandable =
     )
   }
   {
-    expandable && (
+    children && (
       <details class="mt-3" open={expandAll}>
         <summary class="cursor-pointer select-none text-accent text-xs hover:underline">
           <span class="[details[open]>summary_&]:hidden">Show properties</span>
           <span class="hidden [details[open]>summary_&]:inline">Hide properties</span>
         </summary>
-        <div class="mt-3 border-border border-l pl-4">
+        <div class="mt-3 border-border border-s ps-4">
           <SchemaTable
-            schema={schema}
+            node={children.node}
             schemas={schemas}
-            seen={seen}
             expandAll={expandAll}
           />
         </div>

package/src/components/openapi/SchemaTable.astro

@@ -1,86 +1,61 @@
 ---
-import {
-  objectProperties,
-  refName,
-  resolveSchema,
-  type SchemaLike,
-  typeLabel,
-} from "./helpers.ts";
+import type { SchemaLike } from "./helpers.ts";
+import { type SchemaNode, schemaTree } from "./schema-tree.ts";
 import SchemaProperty from "./SchemaProperty.astro";
 
 interface Props {
-  schema: SchemaLike;
+  /** The schema to render, planned here when no `node` is given. */
+  schema?: SchemaLike;
+  /** An already-planned subtree: how nested tables render. */
+  node?: SchemaNode;
   schemas: Record<string, SchemaLike>;
-  /** `$ref` names already on the current branch, to break circular schemas. */
-  seen?: string[];
   expandAll?: boolean;
 }
 
-const { schema, schemas, seen = [], expandAll = false } = Astro.props;
+const { schema = {}, node: planned, schemas, expandAll = false } = Astro.props;
 
-// Track the ref so a self-referential model stops instead of recursing forever.
-const refLabel =
-  typeof schema.$ref === "string" ? refName(schema.$ref) : null;
-const circular = refLabel !== null && seen.includes(refLabel);
-const nextSeen = refLabel ? [...seen, refLabel] : seen;
-const resolved = circular ? schema : resolveSchema(schemas, schema);
-
-const types = Array.isArray(resolved.type) ? resolved.type : [resolved.type];
-const isArray = types.includes("array");
-// Keep array items unresolved so a self-referential item `$ref` stays trackable
-// via `seen` — resolving here would drop the name and loop forever.
-const items = isArray ? (resolved.items ?? null) : null;
-const branches = resolved.oneOf ?? resolved.anyOf ?? null;
-
-const { properties, required } = circular
-  ? { properties: [] as [string, SchemaLike][], required: new Set<string>() }
-  : objectProperties(resolved, schemas);
+// The whole tree is planned once, at the top-level table, so that which named
+// schemas expand is decided for the tree as a whole (see `schema-tree.ts`).
+const node = planned ?? schemaTree(schema, schemas);
 ---
 
 {
-  circular ? (
+  node.kind === "circular" ? (
     <div class="text-muted-foreground text-sm">
-      Circular reference to <code class="text-foreground">{refLabel}</code>.
+      Circular reference to <code class="text-foreground">{node.name}</code>.
     </div>
-  ) : isArray ? (
+  ) : node.kind === "array" ? (
     <div>
       <div class="mb-2 text-muted-foreground text-xs">
-        Array of <code class="text-foreground">{typeLabel(items ?? {})}</code>
+        Array of <code class="text-foreground">{node.itemsLabel}</code>
       </div>
-      {items && (
-        <Astro.self schema={items} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
+      {node.items && (
+        <Astro.self node={node.items.node} schemas={schemas} expandAll={expandAll} />
       )}
     </div>
-  ) : branches ? (
+  ) : node.kind === "branches" ? (
     <div class="flex flex-col gap-3">
-      <div class="text-muted-foreground text-xs">
-        {resolved.oneOf ? "One of" : "Any of"}:
-      </div>
-      {branches.map((branch, index) => (
+      <div class="text-muted-foreground text-xs">{node.label}:</div>
+      {node.branches.map((branch) => (
         <div class="rounded-blume border border-border p-3">
           <div class="mb-2 font-medium text-foreground text-xs">
-            {typeLabel(branch) || `Option ${index + 1}`}
+            {branch.label}
           </div>
-          <Astro.self schema={branch} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
+          <Astro.self node={branch.slot.node} schemas={schemas} expandAll={expandAll} />
         </div>
       ))}
     </div>
-  ) : properties.length > 0 ? (
+  ) : node.kind === "properties" ? (
     <div class="not-prose">
-      {properties.map(([name, prop]) => (
-        <SchemaProperty
-          name={name}
-          schema={prop}
-          required={required.has(name)}
-          schemas={schemas}
-          seen={nextSeen}
-          expandAll={expandAll}
-        />
+      {node.rows.map((row) => (
+        <SchemaProperty row={row} schemas={schemas} expandAll={expandAll} />
       ))}
     </div>
   ) : (
     <div class="text-muted-foreground text-sm">
-      <code class="text-foreground">{typeLabel(resolved)}</code>
+      <code class="text-foreground">
+        {node.kind === "named" ? node.name : node.label}
+      </code>
     </div>
   )
 }

package/src/components/openapi/description.ts

@@ -14,7 +14,7 @@ import { Marked } from "marked";
  * `marked` rather than the site's own Markdown pipeline: the pipeline is async, plugin-laden and
  * built for whole documents, while these are thousands of short strings per build — a large
  * reference renders tens of thousands of them. `marked` is synchronous, already a dependency,
- * and already how the Ask AI island renders model Markdown.
+ * and already how the assistant island renders model Markdown.
  */
 const TABLE = /<table>[\s\S]*?<\/table>/gu;
 
@@ -30,7 +30,7 @@ const escapeHtml = (text: string): string =>
   text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 
 const markdown = new Marked({
-  // `breaks` is deliberately NOT set, unlike the Ask AI island. Docstring prose is hard-wrapped at
+  // `breaks` is deliberately NOT set, unlike the assistant island. Docstring prose is hard-wrapped at
   // 72 or 79 columns, so honouring single newlines would break every sentence mid-flow at exactly
   // the width the source file happened to use.
   breaks: false,