blume 2.0.3 → 2.1.1

package/src/components/content/ViewSwitcher.astro

@@ -0,0 +1,168 @@
+---
+import type { PageView } from "../../markdown/views.ts";
+import Icon from "../Icon.astro";
+import { VIEW_INIT_SCRIPT, viewStyle } from "./view-switcher.ts";
+
+/**
+ * The picker for a page written in `<View>` blocks, rendered above the
+ * content with the page's views (collected by `markdown/views.ts`). The
+ * style hides every other view's blocks and table of contents entries, and
+ * the inline script applies a linked or remembered choice before the views
+ * paint (see `view-switcher.ts`).
+ */
+interface Props {
+  /** The select's accessible name (`content.selectView`). */
+  label: string;
+  views: PageView[];
+}
+
+const { label, views } = Astro.props;
+const titles = views.map((view) => view.title);
+---
+
+<blume-view-switcher
+  class="not-prose mt-4 mb-8 flex items-center gap-2"
+  data-views={JSON.stringify(titles)}
+>
+  <style is:inline set:html={viewStyle(titles)} />
+  {
+    views.map(
+      (view) =>
+        view.icon && (
+          <span
+            class="inline-flex shrink-0 text-muted-foreground"
+            data-blume-view={view.title}
+          >
+            <Icon name={view.icon} size={16} />
+          </span>
+        )
+    )
+  }
+  <select
+    aria-label={label}
+    class="cursor-pointer rounded-blume border border-border bg-background px-3 py-1.5 font-medium text-foreground text-sm"
+  >
+    {views.map((view) => <option value={view.title}>{view.title}</option>)}
+  </select>
+  <script is:inline set:html={VIEW_INIT_SCRIPT} />
+</blume-view-switcher>
+
+<script>
+  import {
+    chooseView,
+    VIEW_PARAM,
+    VIEW_STORAGE_KEY,
+  } from "./view-switcher.ts";
+
+  const HEADINGS = "h2[id], h3[id], h4[id], h5[id], h6[id]";
+
+  const stored = (): string | null => {
+    try {
+      return localStorage.getItem(VIEW_STORAGE_KEY);
+    } catch {
+      return null;
+    }
+  };
+
+  /** The view holding the element a `#hash` link points at, if any. */
+  const linkedView = (): string | undefined => {
+    const id = decodeURIComponent(location.hash.slice(1));
+    const target = id ? document.getElementById(id) : null;
+    return (
+      target?.closest<HTMLElement>("article [data-blume-view]")?.dataset
+        .blumeView ?? undefined
+    );
+  };
+
+  /**
+   * Tag each table of contents entry with the view its heading is in, so the
+   * page's view style hides it with the view.
+   */
+  const tagTableOfContents = () => {
+    const views = new Map<string, string>();
+    for (const view of document.querySelectorAll<HTMLElement>(
+      "article [data-blume-view]"
+    )) {
+      for (const heading of view.querySelectorAll(HEADINGS)) {
+        views.set(heading.id, view.dataset.blumeView ?? "");
+      }
+    }
+    for (const link of document.querySelectorAll<HTMLAnchorElement>(
+      'blume-toc a[href^="#"]'
+    )) {
+      const id = decodeURIComponent(link.getAttribute("href")?.slice(1) ?? "");
+      const item = link.closest("li");
+      const title = views.get(id);
+      if (item && title) {
+        item.dataset.blumeView = title;
+      }
+    }
+  };
+
+  class BlumeViewSwitcher extends HTMLElement {
+    #titles: string[] = [];
+
+    connectedCallback() {
+      try {
+        this.#titles = JSON.parse(this.dataset.views ?? "[]");
+      } catch {
+        this.#titles = [];
+      }
+      tagTableOfContents();
+      this.#show(
+        chooseView(this.#titles, [
+          linkedView(),
+          new URL(location.href).searchParams.get(VIEW_PARAM),
+          stored(),
+        ])
+      );
+      this.querySelector("select")?.addEventListener("change", this.#onPick);
+      window.addEventListener("hashchange", this.#onHash);
+    }
+
+    disconnectedCallback() {
+      this.querySelector("select")?.removeEventListener("change", this.#onPick);
+      window.removeEventListener("hashchange", this.#onHash);
+    }
+
+    #show(title: string | undefined) {
+      if (title === undefined) {
+        return;
+      }
+      document.body.dataset.blumeView = title;
+      const select = this.querySelector("select");
+      if (select) {
+        select.value = title;
+      }
+    }
+
+    #onPick = (event: Event) => {
+      // SAFETY: the listener is only added to this picker's <select>.
+      const { value } = event.currentTarget as HTMLSelectElement;
+      this.#show(value);
+      try {
+        localStorage.setItem(VIEW_STORAGE_KEY, value);
+      } catch {
+        // Storage can be off; the choice still holds for this page.
+      }
+      // replaceState: the link stays shareable without a history entry per
+      // pick, and the client router needs the entry's state kept.
+      const url = new URL(location.href);
+      url.searchParams.set(VIEW_PARAM, value);
+      history.replaceState(history.state, "", url);
+    };
+
+    // An in-page link to a heading in another view switches to that view.
+    #onHash = () => {
+      const view = linkedView();
+      if (view && view !== document.body.dataset.blumeView) {
+        this.#show(view);
+        document.getElementById(decodeURIComponent(location.hash.slice(1)))?.scrollIntoView();
+      }
+    };
+  }
+
+  if (!customElements.get("blume-view-switcher")) {
+    customElements.define("blume-view-switcher", BlumeViewSwitcher);
+  }
+</script>

package/src/components/content/api-field.ts

@@ -0,0 +1,103 @@
+/**
+ * The props `<ParamField>` and `<ResponseField>` take, in Mintlify's shape: a
+ * parameter names its location with the attribute that carries its name
+ * (`<ParamField query="limit">`), and both take `type`, `required`,
+ * `deprecated`, and `default`; a response field adds `pre` and `post` labels
+ * around its name. Pure, so the Markdown downlevel and the playground can
+ * read fields the way the components render them.
+ */
+
+/** Where a `<ParamField>` parameter goes, in the order the attributes are checked. */
+export const PARAM_LOCATIONS = ["path", "query", "header", "body"] as const;
+
+/** A parameter's location. */
+export type ParamLocation = (typeof PARAM_LOCATIONS)[number];
+
+/** A literal value as MDX passes it: a string attribute, or an expression's data. */
+export type FieldValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | FieldValue[]
+  | { [key: string]: FieldValue };
+
+/** A boolean prop: MDX shorthand (`required`) is `true`, `required="true"` a string. */
+export type FlagProp = boolean | string;
+
+/** What both field components take. */
+export interface FieldProps {
+  /** The value used when none is given. */
+  default?: FieldValue;
+  deprecated?: FlagProp;
+  required?: FlagProp;
+  /** Free text: `string`, `integer`, `string[]`, `object`. */
+  type?: string;
+}
+
+/** `<ParamField>`: a request parameter, named by its location attribute. */
+export interface ParamFieldProps extends FieldProps {
+  body?: string;
+  header?: string;
+  /** The name, for a field with no location attribute. */
+  name?: string;
+  path?: string;
+  /**
+   * An example value: the one the playground and request samples start
+   * with, not an input's placeholder hint (see `fieldSchema`).
+   */
+  placeholder?: string;
+  query?: string;
+}
+
+/** `<ResponseField>`: a field of the response. */
+export interface ResponseFieldProps extends FieldProps {
+  name: string;
+  /** Labels after the name. */
+  post?: string | string[];
+  /** Labels before the name. */
+  pre?: string | string[];
+}
+
+/** Whether a flag prop is on. */
+export const isOn = (value?: FlagProp): boolean =>
+  value === true || value === "true";
+
+/** Where a parameter goes, and what it's called. */
+export interface ParamFieldName {
+  location?: ParamLocation;
+  name?: string;
+}
+
+/** A parameter's location and name: the first location attribute set, else `name`. */
+export const paramField = (props: ParamFieldProps): ParamFieldName => {
+  for (const location of PARAM_LOCATIONS) {
+    const name = props[location];
+    if (name !== undefined) {
+      return { location, name };
+    }
+  }
+  return { name: props.name };
+};
+
+const isText = (value: FieldValue): value is string =>
+  typeof value === "string";
+
+/** A default value as shown: text as written, anything else as JSON; `null` when there is none. */
+export const defaultLabel = (value?: FieldValue): string | null => {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+  return isText(value) ? value : JSON.stringify(value);
+};
+
+/** `pre`/`post` labels as a list, whether one was written or several. */
+export const fieldLabels = (value?: string | string[]): string[] => {
+  if (value === undefined) {
+    return [];
+  }
+  return (Array.isArray(value) ? value : [value]).filter(
+    (label) => label !== ""
+  );
+};

package/src/components/content/api-page.ts

@@ -0,0 +1,248 @@
+import { exampleValue } from "../openapi/helpers.ts";
+import type { ParameterLike, SchemaLike } from "../openapi/helpers.ts";
+import { resolveSecurity } from "../openapi/security.ts";
+import type { OperationSecurity } from "../openapi/security.ts";
+import type { FieldValue, ParamLocation } from "./api-field.ts";
+
+/**
+ * A hand-written API page's endpoint, as its `api` frontmatter and its
+ * `<ParamField>`s describe it, turned into the OpenAPI-shaped pieces the
+ * operation playground and code samples are built from: a page with
+ * `api: "POST /v1/users"` gets the same Try it panel and request samples as
+ * a spec'd operation, with no spec. Mintlify's frontmatter, so migrated pages
+ * keep it as written.
+ */
+
+/** How a hand-written endpoint authenticates (`authMethod`, `api.auth.method`). */
+export const AUTH_METHODS = ["bearer", "basic", "key", "none"] as const;
+export type AuthMethod = (typeof AUTH_METHODS)[number];
+
+/** What a page's playground shows: all of it, the samples only, or none. */
+export const PLAYGROUND_MODES = ["interactive", "simple", "none"] as const;
+export type PlaygroundMode = (typeof PLAYGROUND_MODES)[number];
+
+/** `api` frontmatter: an HTTP method, then a path or a full URL. */
+export const API_ENDPOINT =
+  /^(?<method>GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE)\s+(?<target>\S+)$/iu;
+
+/** The site's default auth for hand-written endpoints (`api.auth`). */
+export interface EndpointAuth {
+  method: AuthMethod;
+  /** The header an API key goes in. */
+  name?: string;
+}
+
+/** One `<ParamField>`, as the page's plugin collected it. */
+export interface EndpointField {
+  default?: FieldValue;
+  deprecated?: boolean;
+  /** Body fields nested in this one's `<Expandable>`. */
+  fields?: EndpointField[];
+  location: ParamLocation;
+  name: string;
+  placeholder?: string;
+  required?: boolean;
+  type?: string;
+}
+
+/** What the page's plugin hands the endpoint components. */
+export interface EndpointSpec {
+  authMethod?: AuthMethod;
+  fields: EndpointField[];
+  method: string;
+  playground?: PlaygroundMode;
+  /** The page has a `<RequestExample>`, which stands in for generated samples. */
+  requestExample: boolean;
+  /** The `api` target as written: a path, or a full URL. */
+  target: string;
+}
+
+/** The method and target of an `api` value, or `null` when it isn't one. */
+export const parseApiEndpoint = (
+  value: string
+): { method: string; target: string } | null => {
+  const groups = API_ENDPOINT.exec(value.trim())?.groups;
+  return groups?.method && groups.target
+    ? { method: groups.method.toUpperCase(), target: groups.target }
+    : null;
+};
+
+const ABSOLUTE_URL = /^(?<origin>https?:\/\/[^/?#]+)(?<rest>.*)$/iu;
+
+/** An endpoint's target, split the way the operation model takes it. */
+export interface EndpointTarget {
+  path: string;
+  servers: { url: string }[];
+}
+
+/**
+ * The target split into a server and a path: a full URL is its own server,
+ * and a path joins the site's `api.server`, or stays relative to the docs
+ * when there is none.
+ */
+export const endpointTarget = (
+  target: string,
+  server?: string
+): EndpointTarget => {
+  const absolute = ABSOLUTE_URL.exec(target)?.groups;
+  if (absolute?.origin) {
+    return {
+      path: absolute.rest || "/",
+      servers: [{ url: absolute.origin }],
+    };
+  }
+  return {
+    path: target.startsWith("/") ? target : `/${target}`,
+    servers: server ? [{ url: server.replace(/\/+$/u, "") }] : [],
+  };
+};
+
+const PRIMITIVES = new Set([
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "object",
+]);
+
+/**
+ * A field's JSON schema from its `type`: `string[]` an array of strings, a
+ * field with nested fields an object with those properties, and anything
+ * that isn't a JSON type (`enum<string>`, `Date`) a string, which is what it
+ * goes over the wire as. A default and placeholder carry over, the
+ * placeholder as the example the samples show.
+ */
+export const fieldSchema = (field: EndpointField): SchemaLike => {
+  const type = field.type?.trim().toLowerCase() ?? "";
+  if (type.endsWith("[]")) {
+    return {
+      items: fieldSchema({
+        ...field,
+        default: undefined,
+        type: type.slice(0, -2),
+      }),
+      type: "array",
+    };
+  }
+  const nested = field.fields ?? [];
+  const schema: SchemaLike =
+    nested.length > 0
+      ? {
+          properties: Object.fromEntries(
+            nested.map((child) => [child.name, fieldSchema(child)])
+          ),
+          type: "object",
+        }
+      : { type: PRIMITIVES.has(type) ? type : "string" };
+  const required = nested
+    .filter((child) => child.required)
+    .map((child) => child.name);
+  if (required.length > 0) {
+    schema.required = required;
+  }
+  if (field.default !== undefined) {
+    schema.default = field.default;
+  }
+  if (field.placeholder) {
+    schema.example = field.placeholder;
+  }
+  if (field.deprecated) {
+    schema.deprecated = true;
+  }
+  return schema;
+};
+
+/** The path, query, and header fields as OpenAPI parameters. */
+export const endpointParameters = (fields: EndpointField[]): ParameterLike[] =>
+  fields.flatMap((field) =>
+    field.location === "body"
+      ? []
+      : [
+          {
+            deprecated: field.deprecated === true,
+            in: field.location,
+            name: field.name,
+            // A path parameter is always required.
+            required: field.location === "path" || field.required === true,
+            schema: fieldSchema(field),
+          },
+        ]
+  );
+
+/** Whether a field, or one nested in it, has a `default` or `placeholder`. */
+const hasValue = (field: EndpointField): boolean =>
+  field.default !== undefined ||
+  Boolean(field.placeholder) ||
+  (field.fields ?? []).some(hasValue);
+
+/**
+ * The fields a request starts with: required ones, and ones with a value to
+ * send. An optional field with neither is left for the reader to fill,
+ * rather than sent as the sampler's `"string"`, `0`, or `true`.
+ */
+const sentFields = (fields: EndpointField[]): EndpointField[] =>
+  fields
+    .filter((field) => field.required === true || hasValue(field))
+    .map((field) => ({ ...field, fields: sentFields(field.fields ?? []) }));
+
+/**
+ * The body fields as a JSON request body, or `undefined` when there are none.
+ * Its example, which the playground and samples start from, holds only the
+ * {@link sentFields}.
+ */
+export const endpointBody = (fields: EndpointField[]) => {
+  const body = fields.filter((field) => field.location === "body");
+  const object = (members: EndpointField[]): SchemaLike =>
+    fieldSchema({
+      fields: members,
+      location: "body",
+      name: "",
+      type: "object",
+    });
+  return body.length > 0
+    ? {
+        content: {
+          "application/json": {
+            example: exampleValue(object(sentFields(body)), {}),
+            schema: object(body),
+          },
+        },
+      }
+    : undefined;
+};
+
+/**
+ * The security an endpoint enforces: its page's `authMethod`, else the
+ * site's `api.auth`, else none. An API key goes in the configured header,
+ * `x-api-key` when none is named.
+ */
+export const endpointSecurity = (
+  authMethod?: AuthMethod,
+  siteAuth?: EndpointAuth
+): OperationSecurity => {
+  const method = authMethod ?? siteAuth?.method ?? "none";
+  if (method === "none") {
+    return { alternatives: [], optional: false };
+  }
+  if (method === "key") {
+    return resolveSecurity([{ apiKey: [] }], {
+      apiKey: {
+        in: "header",
+        name: siteAuth?.name ?? "x-api-key",
+        type: "apiKey",
+      },
+    });
+  }
+  return resolveSecurity([{ [method]: [] }], {
+    [method]: { scheme: method, type: "http" },
+  });
+};
+
+/**
+ * The endpoint spec the page's plugin wrote into the `spec` attribute of
+ * `<ApiEndpoint>` and `<ApiPlayground>`.
+ */
+export const readEndpointSpec = (json: string): EndpointSpec =>
+  // SAFETY: the attribute is `JSON.stringify` of an `EndpointSpec`, written
+  // by `markdown/api-rail.ts` at build; authors never write it.
+  JSON.parse(json) as EndpointSpec;

package/src/components/content/mermaid-element.ts

@@ -55,6 +55,9 @@ export class BlumeMermaid extends HTMLElement {
         look: "classic",
         securityLevel: "strict",
         startOnLoad: false,
+        // Without this, a diagram that fails to parse leaves Mermaid's own
+        // "Syntax error in text" graphic appended to <body>, below the page.
+        suppressErrorRendering: true,
         theme: prefersDark() ? "dark" : "default",
       });
       try {
@@ -71,13 +74,24 @@ export class BlumeMermaid extends HTMLElement {
           // oxlint-disable-next-line github/no-inner-html -- Mermaid-generated SVG must be injected as HTML
           output.innerHTML = svg;
         }
-      } catch {
+      } catch (error) {
         // Localized message stamped on <body> by RootLayout's markup (the
         // data-attribute channel); English fallback when the attribute is
         // missing (a stale snapshot or a custom layout).
         output.textContent =
           document.body.dataset.i18nDiagramError ||
           "Could not render this diagram.";
+        // Readers get only the message above; the writer needs Mermaid's
+        // parser error (line and expected token) to fix the source. It goes
+        // to the console, and `blume dev` also shows it under the message.
+        console.error("[blume] Mermaid could not render a diagram:", error);
+        if (import.meta.env.DEV) {
+          const detail = document.createElement("pre");
+          detail.className =
+            "mt-2 overflow-x-auto text-muted-foreground text-xs";
+          detail.textContent = String(error);
+          output.append(detail);
+        }
       }
       output.removeAttribute("aria-busy");
     };

package/src/components/content/view-switcher.ts

@@ -0,0 +1,71 @@
+/**
+ * The page view picker's logic (see `ViewSwitcher.astro`). A page written in
+ * `<View title>` blocks shows one view at a time. The choice sits on
+ * `<body data-blume-view>`, which each page brings fresh, and a per-page style
+ * hides everything tagged with another view: the `<View>` blocks, the
+ * picker's icons, and the table of contents entries for their headings.
+ */
+
+/**
+ * Where a reader's last-picked view is remembered, across pages. The init
+ * script below spells it out, as it does {@link VIEW_PARAM}.
+ */
+export const VIEW_STORAGE_KEY = "blume-view";
+
+/** The query parameter a shared link picks a view with (`?view=Python`). */
+export const VIEW_PARAM = "view";
+
+/**
+ * The view to show: the first of the candidates the page has, most specific
+ * first (a linked heading's view, the link's `?view=`, the reader's last
+ * pick), else the page's first view.
+ */
+export const chooseView = (
+  titles: readonly string[],
+  candidates: readonly (string | null | undefined)[]
+): string | undefined =>
+  candidates.find(
+    (candidate): candidate is string =>
+      candidate !== null &&
+      candidate !== undefined &&
+      titles.includes(candidate)
+  ) ?? titles[0];
+
+/**
+ * A CSS string for `value`, safe inside a `<style>` element: quotes and
+ * backslashes escaped, `<` as a hex escape so the text can't close the
+ * element, and line breaks (which a CSS string can't hold) as spaces.
+ */
+const cssString = (value: string): string =>
+  `"${value
+    .replaceAll(/["\\]/gu, String.raw`\$&`)
+    .replaceAll("<", String.raw`\3c `)
+    .replaceAll(/[\n\r\f]/gu, " ")}"`;
+
+/**
+ * The page's view CSS: with a view chosen on `<body>`, everything tagged with
+ * another is hidden; before a choice, everything but the first view is.
+ */
+export const viewStyle = (titles: readonly string[]): string => {
+  const [first] = titles;
+  if (first === undefined) {
+    return "";
+  }
+  const other = (title: string): string =>
+    `[data-blume-view]:not([data-blume-view=${cssString(title)}])`;
+  const selectors = [
+    `body:not([data-blume-view]) ${other(first)}`,
+    ...titles.map(
+      (title) => `body[data-blume-view=${cssString(title)}] ${other(title)}`
+    ),
+  ];
+  return `${selectors.join(",")}{display:none!important}`;
+};
+
+/**
+ * Runs inline as the picker is parsed, ahead of the views it controls, so a
+ * link's `?view=` or the reader's last pick applies before anything paints.
+ * Inline scripts run once per session under the client router; after that
+ * the picker element applies the choice as each page swaps in.
+ */
+export const VIEW_INIT_SCRIPT = `(()=>{const s=document.currentScript;const p=s&&s.closest("blume-view-switcher");if(!p)return;let t=[];try{t=JSON.parse(p.getAttribute("data-views")||"[]")}catch{}let r=null;try{r=localStorage.getItem("blume-view")}catch{}const l=new URLSearchParams(location.search).get("view");const v=[l,r].find((c)=>c&&t.includes(c))||t[0];if(!v)return;document.body.setAttribute("data-blume-view",v);const e=p.querySelector("select");if(e)e.value=v;})();`;

package/src/components/index.ts

@@ -25,7 +25,9 @@ export type {
   FrameProps,
   IconProps,
   PanelProps,
+  ParamFieldProps,
   PromptProps,
+  ResponseFieldProps,
   StepProps,
   StepsProps,
   TabProps,

package/src/components/islands/Assistant.astro

@@ -1,4 +1,5 @@
 ---
+import type { CaptchaSettings } from "../../captcha/schema.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import { resolveIcon } from "../../theme/icons.ts";
 import Assistant from "./assistant.tsx";
@@ -9,12 +10,17 @@ interface Suggestion {
 }
 
 interface Props {
+  /** The bot check's public settings (`ai.assistant.captcha`). */
+  captcha?: CaptchaSettings;
   endpoint?: string;
   strings?: UIStrings["assistant"];
   suggestions?: Suggestion[];
+  /** The Contact support link (`ai.assistant.support`). */
+  support?: string;
 }
 
-const { endpoint, strings, suggestions = [] } = Astro.props;
+const { captcha, endpoint, strings, suggestions = [], support } =
+  Astro.props;
 
 // Icons resolve to inline SVG here (server-only module), so the client island
 // gets ready-to-render markup rather than a name it can't resolve. Bare Lucide
@@ -41,6 +47,7 @@ const icons = {
   clear: bodyFor("trash-2"),
   close: bodyFor("chevrons-right"),
   copy: bodyFor("copy"),
+  remove: bodyFor("x"),
 };
 ---
 
@@ -50,11 +57,13 @@ const icons = {
     panel and re-stamps the body push attribute itself on astro:after-swap
     (see assistant.tsx), since the swap replaces <body> wholesale. */}
 <Assistant
+  captcha={captcha}
   client:load
   endpoint={endpoint}
   icons={icons}
   strings={strings}
   suggestions={items}
+  support={support}
   transition:persist="blume-assistant"
 />