blume 0.4.0 → 0.5.1

package/src/components/openapi/helpers.ts

@@ -0,0 +1,238 @@
+/**
+ * Runtime helpers for the OpenAPI components. These operate on the parsed spec
+ * behind the `blume:openapi` alias — resolving `$ref`s (kept intact at parse
+ * time to avoid circular graphs), labelling types, and generating request
+ * examples and code samples. Pure and dependency-free so they run in the browser
+ * build with no server-only imports.
+ */
+
+/** A permissive view of an OpenAPI 3.1 schema — only the fields we render. */
+export interface SchemaLike {
+  $ref?: string;
+  type?: string | string[];
+  format?: string;
+  title?: string;
+  description?: string;
+  properties?: Record<string, SchemaLike>;
+  required?: string[];
+  items?: SchemaLike;
+  enum?: unknown[];
+  const?: unknown;
+  default?: unknown;
+  example?: unknown;
+  examples?: unknown[];
+  allOf?: SchemaLike[];
+  oneOf?: SchemaLike[];
+  anyOf?: SchemaLike[];
+  additionalProperties?: boolean | SchemaLike;
+  nullable?: boolean;
+  deprecated?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  minItems?: number;
+  maxItems?: number;
+  pattern?: string;
+  [key: string]: unknown;
+}
+
+const REF_PATTERN = /#\/components\/schemas\/(?<name>[^/]+)$/u;
+
+/** The display name of a `$ref`, e.g. `#/components/schemas/Pet` -> `Pet`. */
+export const refName = (ref: string): string =>
+  REF_PATTERN.exec(ref)?.groups?.name ?? ref.split("/").at(-1) ?? ref;
+
+/** Resolve one level of `$ref` against the document's component schemas. */
+export const resolveSchema = (
+  schemas: Record<string, SchemaLike>,
+  schema?: SchemaLike
+): SchemaLike => {
+  if (!schema) {
+    return {};
+  }
+  if (typeof schema.$ref === "string") {
+    const name = REF_PATTERN.exec(schema.$ref)?.groups?.name;
+    if (name && schemas[name]) {
+      return schemas[name];
+    }
+  }
+  return schema;
+};
+
+const nonNullTypes = (type: string | string[] | undefined): string[] => {
+  if (!type) {
+    return [];
+  }
+  return (Array.isArray(type) ? type : [type]).filter((t) => t !== "null");
+};
+
+/** A short, human-readable type label for a schema row. */
+export const typeLabel = (
+  schema: SchemaLike,
+  schemas: Record<string, SchemaLike>
+): string => {
+  if (typeof schema.$ref === "string") {
+    return refName(schema.$ref);
+  }
+  if (schema.oneOf || schema.anyOf) {
+    const branches = schema.oneOf ?? schema.anyOf ?? [];
+    const labels = branches.map((branch) => typeLabel(branch, schemas));
+    return [...new Set(labels)].join(" | ") || "any";
+  }
+  if (schema.allOf) {
+    return "object";
+  }
+  const types = nonNullTypes(schema.type);
+  if (types.includes("array")) {
+    const item = resolveSchema(schemas, schema.items);
+    return `${typeLabel(item, schemas)}[]`;
+  }
+  const base = types[0] ?? (schema.properties ? "object" : "any");
+  return schema.format ? `${base}<${schema.format}>` : base;
+};
+
+/** Whether this schema is nullable (3.0 `nullable` or a 3.1 `"null"` in `type`). */
+export const isNullable = (schema: SchemaLike): boolean =>
+  schema.nullable === true ||
+  (Array.isArray(schema.type) && schema.type.includes("null"));
+
+/** Human-readable validation constraints for a schema, in display order. */
+export const constraints = (schema: SchemaLike): string[] => {
+  const out: string[] = [];
+  const numeric: [keyof SchemaLike, string][] = [
+    ["minimum", "min"],
+    ["maximum", "max"],
+    ["minLength", "min length"],
+    ["maxLength", "max length"],
+    ["minItems", "min items"],
+    ["maxItems", "max items"],
+  ];
+  for (const [key, label] of numeric) {
+    const value = schema[key];
+    if (typeof value === "number") {
+      out.push(`${label} ${value}`);
+    }
+  }
+  if (typeof schema.pattern === "string") {
+    out.push(`matches ${schema.pattern}`);
+  }
+  if (schema.default !== undefined) {
+    out.push(`default: ${JSON.stringify(schema.default)}`);
+  }
+  return out;
+};
+
+/**
+ * The object properties a schema exposes, merging `allOf` branches so an
+ * `allOf`-composed model still lists every field. Returns the properties plus
+ * the merged required set.
+ */
+export const objectProperties = (
+  schema: SchemaLike,
+  schemas: Record<string, SchemaLike>
+): { properties: [string, SchemaLike][]; required: Set<string> } => {
+  const properties = new Map<string, SchemaLike>();
+  const required = new Set<string>();
+
+  const collect = (node: SchemaLike): void => {
+    const resolved = resolveSchema(schemas, node);
+    for (const name of resolved.required ?? []) {
+      required.add(name);
+    }
+    for (const [name, prop] of Object.entries(resolved.properties ?? {})) {
+      properties.set(name, prop);
+    }
+    for (const branch of resolved.allOf ?? []) {
+      collect(branch);
+    }
+  };
+
+  collect(schema);
+  return { properties: [...properties.entries()], required };
+};
+
+/** Sentinel: no explicit example is declared on a schema. */
+const NO_VALUE = Symbol("no-value");
+
+/** The declared example/default/enum for a schema, or {@link NO_VALUE}. */
+const explicitExample = (schema: SchemaLike): unknown => {
+  if (schema.example !== undefined) {
+    return schema.example;
+  }
+  if (Array.isArray(schema.examples) && schema.examples.length > 0) {
+    return schema.examples[0];
+  }
+  if (schema.default !== undefined) {
+    return schema.default;
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    return schema.enum[0];
+  }
+  return NO_VALUE;
+};
+
+/** A placeholder value for a primitive (leaf) schema. */
+const primitiveExample = (
+  types: string[],
+  format: string | undefined
+): unknown => {
+  if (types.includes("number") || types.includes("integer")) {
+    return 0;
+  }
+  if (types.includes("boolean")) {
+    return true;
+  }
+  if (format === "date-time") {
+    return "2024-01-01T00:00:00Z";
+  }
+  return format ? `<${format}>` : "string";
+};
+
+/**
+ * Build a representative example value for a schema (honoring `example` /
+ * `default` / `enum` first). A `seen` set of `$ref`s guards against the circular
+ * schemas that keeping refs intact allows.
+ */
+export const exampleValue = (
+  schema: SchemaLike | undefined,
+  schemas: Record<string, SchemaLike>,
+  seen = new Set<string>()
+): unknown => {
+  if (!schema) {
+    return null;
+  }
+  if (typeof schema.$ref === "string") {
+    if (seen.has(schema.$ref)) {
+      return null;
+    }
+    seen.add(schema.$ref);
+    return exampleValue(resolveSchema(schemas, schema), schemas, seen);
+  }
+  const explicit = explicitExample(schema);
+  if (explicit !== NO_VALUE) {
+    return explicit;
+  }
+  const branch = schema.oneOf?.[0] ?? schema.anyOf?.[0];
+  if (branch) {
+    return exampleValue(branch, schemas, seen);
+  }
+  const types = nonNullTypes(schema.type);
+  if (types.includes("array")) {
+    return [exampleValue(schema.items, schemas, seen)];
+  }
+  if (types.includes("object") || schema.properties || schema.allOf) {
+    const out: Record<string, unknown> = {};
+    for (const [name, prop] of objectProperties(schema, schemas).properties) {
+      out[name] = exampleValue(prop, schemas, new Set(seen));
+    }
+    return out;
+  }
+  return primitiveExample(types, schema.format);
+};
+
+/** Pretty-print a JSON value for an example/code block. */
+export const toJson = (value: unknown): string =>
+  JSON.stringify(value, null, 2);

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/graph.ts

@@ -96,7 +96,6 @@ export const buildContentGraph = (
         selectors: options.navigation.selectors,
         sharedFolderMeta: options.sharedFolderMeta,
         sidebar: options.navigation.sidebar,
-        sidebarVariants: options.navigation.sidebarVariants,
         tabs,
       });
     }
@@ -104,7 +103,6 @@ export const buildContentGraph = (
       chromeVariants: [],
       selectors: [],
       sidebar: [],
-      sidebarVariants: [],
       tabs: [],
     };
   } else {
@@ -114,7 +112,6 @@ export const buildContentGraph = (
       selectors: options.navigation.selectors,
       sharedFolderMeta: options.sharedFolderMeta,
       sidebar: options.navigation.sidebar,
-      sidebarVariants: options.navigation.sidebarVariants,
       tabs: options.navigation.tabs,
     });
   }

package/src/core/nav-diagnostics.ts

@@ -42,10 +42,7 @@ const collectIcons = (
       push(item.icon, `selector "${item.label}"`);
     }
   }
-  const sidebars = [
-    navigation.sidebar,
-    ...navigation.sidebarVariants.map((variant) => variant.sidebar),
-  ];
+  const sidebars = [navigation.sidebar];
   for (const sidebar of sidebars) {
     for (const node of flattenNodes(sidebar)) {
       push(node.icon, `"${node.label}"`);
@@ -140,10 +137,6 @@ const duplicateLabelDiagnostics = (navigation: Navigation): Diagnostic[] => {
   };
   const sidebars: { nodes: NavNode[]; where: string }[] = [
     { nodes: navigation.sidebar, where: "at the top level" },
-    ...navigation.sidebarVariants.map((variant) => ({
-      nodes: variant.sidebar,
-      where: `in the "${variant.path}" section`,
-    })),
   ];
   for (const { nodes, where } of sidebars) {
     checkLevel(nodes, where);
@@ -162,10 +155,7 @@ const hiddenInSidebarDiagnostics = (
   if (hidden.size === 0) {
     return [];
   }
-  const sidebars = [
-    navigation.sidebar,
-    ...navigation.sidebarVariants.map((variant) => variant.sidebar),
-  ];
+  const sidebars = [navigation.sidebar];
   const diagnostics: Diagnostic[] = [];
   const seen = new Set<string>();
   for (const sidebar of sidebars) {

package/src/core/navigation.ts

@@ -8,7 +8,6 @@ import type {
 import type {
   NavChromeVariant,
   NavNode,
-  NavSidebarVariant,
   Navigation,
   NavSelector,
   NavTab,
@@ -348,7 +347,6 @@ export const buildNavigation = (
     selectors?: NavSelector[];
     tabs?: NavTab[];
     sidebar?: SidebarItemConfig[];
-    sidebarVariants?: { path: string; items: SidebarItemConfig[] }[];
     /** Locale dir prefix for folder-meta lookup (`""` for the default locale). */
     metaPrefix?: string;
     /**
@@ -372,19 +370,12 @@ export const buildNavigation = (
       page,
     ])
   );
-  const sidebarVariants: NavSidebarVariant[] = (
-    options.sidebarVariants ?? []
-  ).map((variant) => ({
-    path: variant.path,
-    sidebar: buildConfigSidebar(variant.items, byRoute),
-  }));
 
   if (options.sidebar) {
     return {
       chromeVariants,
       selectors,
       sidebar: buildConfigSidebar(options.sidebar, byRoute),
-      sidebarVariants,
       tabs,
     };
   }
@@ -398,7 +389,6 @@ export const buildNavigation = (
       sharedFolderMeta,
       metaPrefix
     ),
-    sidebarVariants,
     tabs,
   };
 };

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),