blume 0.4.0 → 0.5.0

package/src/components/openapi/panel.ts

@@ -0,0 +1,59 @@
+/**
+ * Client behaviour for the OpenAPI request/response panels. `<blume-panel-tabs>`
+ * switches the visible `[data-panel="key"]` region when a `[data-panel-tab="key"]`
+ * button is clicked, and an optional `[data-panel-copy]` button copies the active
+ * panel's text. Vanilla custom element — no framework, in keeping with the core
+ * theme.
+ */
+
+class BlumePanelTabs extends HTMLElement {
+  connectedCallback() {
+    const tabs = [
+      ...this.querySelectorAll<HTMLButtonElement>("[data-panel-tab]"),
+    ];
+    const panels = [...this.querySelectorAll<HTMLElement>("[data-panel]")];
+    const copy = this.querySelector<HTMLButtonElement>("[data-panel-copy]");
+
+    const activate = (key: string): void => {
+      for (const tab of tabs) {
+        tab.setAttribute(
+          "aria-selected",
+          tab.dataset.panelTab === key ? "true" : "false"
+        );
+      }
+      for (const panel of panels) {
+        panel.classList.toggle("hidden", panel.dataset.panel !== key);
+      }
+    };
+
+    for (const tab of tabs) {
+      tab.addEventListener("click", () => {
+        const key = tab.dataset.panelTab;
+        if (key) {
+          activate(key);
+        }
+      });
+    }
+
+    if (copy) {
+      copy.addEventListener("click", async () => {
+        const active = panels.find(
+          (panel) => !panel.classList.contains("hidden")
+        );
+        try {
+          await navigator.clipboard.writeText(active?.textContent ?? "");
+          copy.dataset.copied = "true";
+          setTimeout(() => {
+            delete copy.dataset.copied;
+          }, 1500);
+        } catch {
+          // Clipboard unavailable (insecure context); silently ignore.
+        }
+      });
+    }
+  }
+}
+
+if (!customElements.get("blume-panel-tabs")) {
+  customElements.define("blume-panel-tabs", BlumePanelTabs);
+}

package/src/components/openapi/snippets.ts

@@ -0,0 +1,201 @@
+import { exampleValue, toJson } from "./helpers.ts";
+import type { SchemaLike } from "./helpers.ts";
+
+/**
+ * Request example + code-sample generation for an operation. Kept separate from
+ * `helpers.ts` so the schema renderers don't pull in the sample builders. Output
+ * is intentionally simple, copy-pasteable starter code — not an exhaustive SDK.
+ */
+
+interface ParamLike {
+  name?: string;
+  in?: string;
+  required?: boolean;
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+interface MediaTypeLike {
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+export interface OperationLike {
+  parameters?: ParamLike[];
+  requestBody?: { content?: Record<string, MediaTypeLike> };
+}
+
+export interface RequestSample {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  /** JSON-stringified request body, when the operation takes one. */
+  body?: string;
+  bodyValue?: unknown;
+}
+
+const TRAILING_SLASH = /\/+$/u;
+
+const jsonContentType = (
+  content: Record<string, MediaTypeLike> | undefined
+): [string, MediaTypeLike] | undefined => {
+  const entries = Object.entries(content ?? {});
+  return entries.find(([type]) => type.includes("json")) ?? entries[0];
+};
+
+/** Assemble a representative request from an operation and the spec servers. */
+export const buildRequestSample = (
+  operation: OperationLike,
+  method: string,
+  path: string,
+  servers: { url?: string }[],
+  schemas: Record<string, SchemaLike>
+): RequestSample => {
+  const base = (servers[0]?.url ?? "").replace(TRAILING_SLASH, "");
+  const params = operation.parameters ?? [];
+
+  let resolvedPath = path;
+  for (const param of params) {
+    if (param.in === "path" && param.name) {
+      const value = param.example ?? exampleValue(param.schema, schemas);
+      resolvedPath = resolvedPath.replace(
+        `{${param.name}}`,
+        encodeURIComponent(String(value ?? param.name))
+      );
+    }
+  }
+
+  const query = params
+    .filter((param) => param.in === "query" && param.required && param.name)
+    .map((param) => {
+      const value = param.example ?? exampleValue(param.schema, schemas);
+      return `${encodeURIComponent(param.name ?? "")}=${encodeURIComponent(
+        String(value ?? "")
+      )}`;
+    });
+  const search = query.length > 0 ? `?${query.join("&")}` : "";
+
+  const headers: Record<string, string> = {};
+  for (const param of params) {
+    if (param.in === "header" && param.required && param.name) {
+      headers[param.name] = String(
+        param.example ?? exampleValue(param.schema, schemas) ?? ""
+      );
+    }
+  }
+
+  const media = jsonContentType(operation.requestBody?.content);
+  let body: string | undefined;
+  let bodyValue: unknown;
+  if (media) {
+    const [type, mediaType] = media;
+    headers["Content-Type"] = type;
+    bodyValue = mediaType.example ?? exampleValue(mediaType.schema, schemas);
+    body = toJson(bodyValue);
+  }
+
+  return {
+    body,
+    bodyValue,
+    headers,
+    method: method.toUpperCase(),
+    url: `${base}${resolvedPath}${search}`,
+  };
+};
+
+const headerLines = (
+  headers: Record<string, string>,
+  format: (key: string, value: string) => string
+): string[] =>
+  Object.entries(headers).map(([key, value]) => format(key, value));
+
+const curlSnippet = (sample: RequestSample): string => {
+  const lines = [
+    `curl -X ${sample.method} "${sample.url}"`,
+    ...headerLines(sample.headers, (key, value) => `  -H "${key}: ${value}"`),
+  ];
+  if (sample.body) {
+    lines.push(`  -d '${sample.body}'`);
+  }
+  return lines.join(" \\\n");
+};
+
+const fetchSnippet = (sample: RequestSample): string => {
+  const options = [`  method: "${sample.method}"`];
+  if (Object.keys(sample.headers).length > 0) {
+    const headers = headerLines(
+      sample.headers,
+      (key, value) => `    "${key}": "${value}"`
+    ).join(",\n");
+    options.push(`  headers: {\n${headers}\n  }`);
+  }
+  if (sample.body) {
+    options.push(`  body: JSON.stringify(${sample.body})`);
+  }
+  return `const response = await fetch("${sample.url}", {\n${options.join(
+    ",\n"
+  )}\n});`;
+};
+
+/** Turn a JSON literal into an equivalent Python literal (`true` -> `True`). */
+const toPython = (json: string): string =>
+  json
+    .replaceAll(/\btrue\b/gu, "True")
+    .replaceAll(/\bfalse\b/gu, "False")
+    .replaceAll(/\bnull\b/gu, "None");
+
+const pythonSnippet = (sample: RequestSample): string => {
+  const args = [`    "${sample.url}"`];
+  if (Object.keys(sample.headers).length > 0) {
+    const headers = headerLines(
+      sample.headers,
+      (key, value) => `        "${key}": "${value}"`
+    ).join(",\n");
+    args.push(`    headers={\n${headers}\n    }`);
+  }
+  if (sample.body) {
+    args.push(`    json=${toPython(sample.body)}`);
+  }
+  return `import requests\n\nresponse = requests.${sample.method.toLowerCase()}(\n${args.join(
+    ",\n"
+  )},\n)`;
+};
+
+/** A code-sample language: config id -> label, Shiki lang, and builder. */
+export interface SampleLanguage {
+  id: string;
+  label: string;
+  lang: string;
+  build: (sample: RequestSample) => string;
+}
+
+const LANGUAGES: SampleLanguage[] = [
+  { build: curlSnippet, id: "curl", label: "cURL", lang: "bash" },
+  { build: fetchSnippet, id: "js", label: "JavaScript", lang: "js" },
+  { build: pythonSnippet, id: "python", label: "Python", lang: "python" },
+];
+
+const ALIASES: Record<string, string> = {
+  bash: "curl",
+  javascript: "js",
+  node: "js",
+  py: "python",
+  shell: "curl",
+  typescript: "js",
+};
+
+/** The sample languages to render, resolved from config ids (unknown ids dropped). */
+export const sampleLanguages = (ids: string[]): SampleLanguage[] => {
+  const wanted = ids.length > 0 ? ids : ["curl", "js", "python"];
+  const out: SampleLanguage[] = [];
+  const seen = new Set<string>();
+  for (const raw of wanted) {
+    const id = ALIASES[raw.toLowerCase()] ?? raw.toLowerCase();
+    const language = LANGUAGES.find((entry) => entry.id === id);
+    if (language && !seen.has(id)) {
+      seen.add(id);
+      out.push(language);
+    }
+  }
+  return out;
+};

package/src/core/builtin-tags.ts

@@ -7,6 +7,7 @@
 export const BUILTIN_MDX_TAGS = new Set<string>([
   "Accordion",
   "AccordionItem",
+  "ApiOverview",
   "AutoTypeTable",
   "Badge",
   "Callout",
@@ -25,8 +26,12 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "GithubInfo",
   "Icon",
   "Math",
+  "Operation",
   "Panel",
+  "ParamField",
   "Prompt",
+  "RequestField",
+  "ResponseField",
   "Step",
   "Steps",
   "Tab",

package/src/core/data.ts

@@ -93,6 +93,8 @@ export interface BlumeDataConfig {
   favicon: BlumeFavicon;
   feedback: boolean;
   i18n: BlumeDataI18n | null;
+  /** Default icon library for bare `icon` names. */
+  icons: ResolvedConfig["icons"];
   /** `markdown.imageZoom`: click-to-zoom content images. */
   imageZoom: boolean;
   logo: BlumeLogo | null;

package/src/core/project-graph.ts

@@ -88,6 +88,8 @@ export const scanProject = async (
     refresh?: boolean;
     /** CLI overrides applied over the loaded config (e.g. `--output`). */
     overrides?: ConfigOverrides;
+    /** Relocate the generated runtime (e.g. `.blume-verify` for isolation). */
+    runtimeDir?: string;
   } = {}
 ): Promise<BlumeProject> => {
   const mode = options.mode ?? "dev";
@@ -97,7 +99,9 @@ export const scanProject = async (
   });
   const { bridge } = configResult;
   const config = applyConfigOverrides(configResult.config, options.overrides);
-  const context = resolveProjectContext(root, config);
+  const context = resolveProjectContext(root, config, {
+    runtimeDir: options.runtimeDir,
+  });
 
   // Each source validates itself (e.g. the filesystem source checks its root
   // exists), replacing the single hard `contentRoot` check.

package/src/core/project.ts

@@ -28,13 +28,27 @@ const firstExisting = (root: string, names: string[]): string | null => {
 export const findConfigFile = (root: string): string | null =>
   firstExisting(root, CONFIG_FILENAMES);
 
+/**
+ * Resolve the generated runtime directory for a project. Defaults to
+ * `<root>/.blume`; an override (e.g. `.blume-verify` for an isolated build that
+ * runs alongside a live `blume dev`) may be relative to the root or absolute.
+ */
+export const resolveRuntimeDir = (
+  root: string,
+  runtimeDir = ".blume"
+): string =>
+  isAbsolute(runtimeDir) ? runtimeDir : join(resolve(root), runtimeDir);
+
 /**
  * Resolve every path Blume needs from a project root and its resolved config.
- * Paths are absolute and normalized.
+ * Paths are absolute and normalized. `options.runtimeDir` relocates the whole
+ * generated runtime (and its build output) so a verify build/check can run
+ * without touching a live dev server's `.blume/` or the real `dist/`.
  */
 export const resolveProjectContext = (
   root: string,
-  config: ResolvedConfig
+  config: ResolvedConfig,
+  options?: { runtimeDir?: string }
 ): ProjectContext => {
   const absoluteRoot = resolve(root);
   const contentRoot = isAbsolute(config.content.root)
@@ -44,11 +58,19 @@ export const resolveProjectContext = (
   const pagesPath = join(absoluteRoot, config.content.pages);
   const pagesRoot = existsSync(pagesPath) ? pagesPath : null;
 
+  const outDir = resolveRuntimeDir(absoluteRoot, options?.runtimeDir);
+  // A relocated runtime keeps its build output self-contained under itself, so a
+  // verify build never empties the user's real `<root>/dist`.
+  const distDir = options?.runtimeDir
+    ? join(outDir, "dist")
+    : join(absoluteRoot, "dist");
+
   return {
     componentsFile: firstExisting(absoluteRoot, COMPONENTS_FILENAMES),
     configFile: findConfigFile(absoluteRoot),
     contentRoot,
-    outDir: join(absoluteRoot, ".blume"),
+    distDir,
+    outDir,
     pagesRoot,
     root: absoluteRoot,
     themeFile: firstExisting(absoluteRoot, THEME_FILENAMES),

package/src/core/schema.ts

@@ -69,9 +69,30 @@ const changelogMetaSchema = z
   })
   .strict();
 
+/**
+ * A post author: a bare name/handle, or an object with a name plus optional
+ * avatar/URL. The object is passthrough so richer author metadata (social
+ * handles, roles) survives untouched — Blume doesn't render authors yet, so
+ * this exists to preserve the field (common on blog/changelog pages) rather
+ * than have a strict scan reject it.
+ */
+const authorSchema = z.union([
+  z.string(),
+  z
+    .object({
+      avatar: z.string().optional(),
+      image: z.string().optional(),
+      name: z.string(),
+      url: z.string().optional(),
+    })
+    .passthrough(),
+]);
+
 /** Frontmatter accepted on any content page. */
 const pageMetaBaseSchema = z
   .object({
+    /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
+    authors: z.union([authorSchema, z.array(authorSchema)]).optional(),
     changelog: changelogMetaSchema.optional(),
     /** Publish date for feed-backed content like blog/changelog. */
     date: dateSchema.optional(),
@@ -903,8 +924,8 @@ const markdownConfigSchema = z
   .strict();
 
 /**
- * A single spec rendered by the API reference (Scalar). `spec` is a local path
- * or an `http(s)` URL; Scalar auto-detects OpenAPI vs AsyncAPI documents.
+ * A single spec rendered by the API reference. `spec` is a local path or an
+ * `http(s)` URL (OpenAPI for the Blume renderer; OpenAPI or AsyncAPI for Scalar).
  */
 const openapiSourceSchema = z
   .object({
@@ -920,20 +941,28 @@ const openapiSourceSchema = z
 export type OpenApiSource = z.infer<typeof openapiSourceSchema>;
 
 /**
- * OpenAPI reference, delegated wholesale to Scalar (`@scalar/astro`). The
- * reference is a self-contained embed on its own route — it does not weave into
- * Blume's sidebar, search, or llms. Set `enabled: true` to opt in.
+ * OpenAPI reference. By default (`renderer: "blume"`) Blume parses the spec with
+ * Scalar's parser and renders its own UI: one real page per operation, grouped
+ * by tag in the sidebar and included in site search, llms.txt, and OG. Set
+ * `renderer: "scalar"` to fall back to the embedded Scalar SPA (a single
+ * self-contained route that doesn't weave into the sidebar or search).
  */
 const openapiConfigSchema = z
   .object({
+    /** Code-sample languages shown per operation (Blume renderer). */
+    codeSamples: z.array(z.string()).default(["curl", "js", "python"]),
     enabled: z.boolean().default(false),
+    /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
+    expandSchemas: z.boolean().default(false),
+    /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
+    renderer: z.enum(["blume", "scalar"]).default("blume"),
     /** Where the reference mounts. */
     route: z.string().default("/reference"),
     /** One or more specs; each renders on its own route by default. */
     sources: z.array(openapiSourceSchema).default([]),
     /** Shorthand for a single source: `sources: [{ spec }]`. */
     spec: z.string().optional(),
-    /** Scalar theme name; defaults to a Blume-derived accent override. */
+    /** Scalar theme name (Scalar renderer only). */
     theme: z.string().optional(),
   })
   .strict();
@@ -980,6 +1009,17 @@ const tocConfigSchema = z
     };
   });
 
+/**
+ * Which icon library bare `icon` names resolve against (mirrors Mintlify's
+ * `icons.library`). Names can always opt into a specific set with an explicit
+ * `prefix:name` (`lucide:rocket`, `fa6-brands:github`) regardless of this.
+ */
+const iconsConfigSchema = z
+  .object({
+    library: z.enum(["lucide", "fontawesome", "tabler"]).default("lucide"),
+  })
+  .strict();
+
 export const blumeConfigSchema = z
   .object({
     ai: aiConfigSchema.default({}),
@@ -1008,6 +1048,7 @@ export const blumeConfigSchema = z
     feedback: z.boolean().default(true),
     github: githubConfigSchema.optional(),
     i18n: i18nConfigSchema.optional(),
+    icons: iconsConfigSchema.default({}),
     lastModified: lastModifiedConfigSchema.default(false),
     logo: logoConfigSchema.optional(),
     markdown: markdownConfigSchema.default({}),

package/src/core/sources/mintlify.ts

@@ -102,7 +102,7 @@ export const mintlifySource = (
         ? [
             {
               code: "BLUME_MINTLIFY_UNSUPPORTED",
-              message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Use the OpenAPI reference for API parameters.`,
+              message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Replace them by hand or provide a matching component.`,
               severity: "warning",
             },
           ]

package/src/core/sources/resolve.ts

@@ -1,5 +1,7 @@
 import { join } from "pathe";
 
+import { blumeReferences } from "../../openapi/references.ts";
+import { openApiSource } from "../../openapi/source.ts";
 import type { ContentSourceConfig, ResolvedConfig } from "../schema.ts";
 import type { ProjectContext } from "../types.ts";
 import { filesystemSource } from "./filesystem.ts";
@@ -144,12 +146,8 @@ const baseName = (def: ContentSourceConfig): string => {
   return def.prefix ?? def.type;
 };
 
-/**
- * Build the ordered list of content sources for a project. With no
- * `content.sources` configured, the top-level `root`/`include`/`exclude` desugar
- * to a single implicit filesystem source, so existing projects are untouched.
- */
-export const resolveSources = (
+/** The content sources declared by config (implicit filesystem when none). */
+const contentSources = (
   config: ResolvedConfig,
   context: ProjectContext,
   runtime: SourceRuntime
@@ -172,3 +170,27 @@ export const resolveSources = (
     buildSource(def, nameFor(baseName(def)), context, runtime)
   );
 };
+
+/**
+ * Build the ordered list of content sources for a project. With no
+ * `content.sources` configured, the top-level `root`/`include`/`exclude` desugar
+ * to a single implicit filesystem source, so existing projects are untouched.
+ * A Blume-rendered OpenAPI reference contributes an internal staged source that
+ * lowers each operation into a real content page (routing/nav/search/OG).
+ */
+export const resolveSources = (
+  config: ResolvedConfig,
+  context: ProjectContext,
+  runtime: SourceRuntime
+): ContentSource[] => {
+  const sources = contentSources(config, context, runtime);
+
+  const references = blumeReferences(config);
+  if (references.length > 0) {
+    sources.push(
+      openApiSource(references, sourceContext(context, "openapi", runtime))
+    );
+  }
+
+  return sources;
+};

package/src/core/types.ts

@@ -54,6 +54,13 @@ export interface ProjectContext {
   pagesRoot: string | null;
   /** Absolute path to the generated runtime (`<root>/.blume`). */
   outDir: string;
+  /**
+   * Absolute path to the Astro build output. `<root>/dist` normally; for a
+   * relocated runtime (isolated verify build) it lives under the runtime dir so
+   * it never empties the real `dist/`. Optional so hand-built test contexts and
+   * older callers still typecheck; `resolveProjectContext` always sets it.
+   */
+  distDir?: string;
   /** Absolute path to the user `theme.css`, if present. */
   themeFile: string | null;
   /** Absolute path to the user `components.ts`/`.tsx`, if present. */