blume 0.6.7 → 0.8.0

package/src/components/openapi/RequestPanel.astro

@@ -1,4 +1,6 @@
 ---
+import data from "blume:data";
+
 import { highlightCode } from "../../markdown/index.ts";
 import { exampleValue, type SchemaLike, toJson } from "./helpers.ts";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
@@ -22,7 +24,7 @@ interface Props {
 
 const { sample, languages, responses, schemas } = Astro.props;
 
-// A `.prose` wrapper gives Shiki its scoped token colours; the global style at
+// A `.prose` wrapper gives Shiki its scoped token colors; the global style at
 // the foot of this file strips the standalone code block's own box (border,
 // injected copy button, language label) so the code sits flush inside the one
 // panel border.
@@ -35,6 +37,7 @@ const requestSamples = await Promise.all(
   languages.map(async (language) => ({
     html: await highlightCode(language.build(sample), language.lang, {
       icons: false,
+      themes: data.config.codeThemes,
     }),
     id: language.id,
     label: language.label,
@@ -53,7 +56,10 @@ const responseEntries = await Promise.all(
     const html =
       example === undefined || example === null
         ? null
-        : await highlightCode(toJson(example), "json", { icons: false });
+        : await highlightCode(toJson(example), "json", {
+            icons: false,
+            themes: data.config.codeThemes,
+          });
     return { description: response.description ?? "", html, status };
   })
 );

package/src/components/openapi/helpers.ts

@@ -39,8 +39,71 @@ export interface SchemaLike {
   [key: string]: unknown;
 }
 
+/** A permissive view of an operation parameter — only the fields we render. */
+export interface ParameterLike {
+  $ref?: string;
+  name?: string;
+  in?: string;
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
 const REF_PATTERN = /#\/components\/schemas\/(?<name>[^/]+)$/u;
 
+const COMPONENT_REF = /#\/components\/(?<section>[^/]+)\/(?<name>[^/]+)$/u;
+
+/**
+ * Resolve one level of `$ref` against a named `components` section
+ * (`parameters`, `requestBodies`, `responses`). Mirrors {@link resolveSchema}:
+ * an unknown ref — or one pointing into a different section — is returned
+ * as-is.
+ */
+export const resolveComponentRef = <T extends { $ref?: string }>(
+  node: T,
+  components: Record<string, unknown> | undefined,
+  section: string
+): T => {
+  if (typeof node.$ref !== "string") {
+    return node;
+  }
+  const groups = COMPONENT_REF.exec(node.$ref)?.groups;
+  if (groups?.section !== section) {
+    return node;
+  }
+  const table = components?.[section] as Record<string, T> | undefined;
+  return table?.[groups.name ?? ""] ?? node;
+};
+
+/**
+ * Path-level and operation-level parameters merged into one render list.
+ * `$ref`s resolve against `components.parameters` first; then an operation
+ * parameter overrides a path-level one with the same `name` + `in` (the
+ * OpenAPI override rule), so a re-declared parameter appears once.
+ */
+export const mergeParameters = (
+  pathParameters: ParameterLike[] | undefined,
+  operationParameters: ParameterLike[] | undefined,
+  components?: Record<string, unknown>
+): ParameterLike[] => {
+  const merged = new Map<string, ParameterLike>();
+  let position = 0;
+  for (const raw of [
+    ...(pathParameters ?? []),
+    ...(operationParameters ?? []),
+  ]) {
+    const param = resolveComponentRef(raw, components, "parameters");
+    // A nameless parameter is invalid per spec, but key it uniquely so it is
+    // still rendered rather than collapsing with other invalid entries.
+    const key = param.name ? `${param.in ?? ""}:${param.name}` : `#${position}`;
+    merged.set(key, param);
+    position += 1;
+  }
+  return [...merged.values()];
+};
+
 /** 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;
@@ -166,7 +229,7 @@ export const objectProperties = (
 /** 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}. */
+/** The declared example/const/default/enum for a schema, or {@link NO_VALUE}. */
 const explicitExample = (schema: SchemaLike): unknown => {
   if (schema.example !== undefined) {
     return schema.example;
@@ -174,6 +237,11 @@ const explicitExample = (schema: SchemaLike): unknown => {
   if (Array.isArray(schema.examples) && schema.examples.length > 0) {
     return schema.examples[0];
   }
+  // `const` is the schema's only valid value (the 3.1 discriminator idiom), so
+  // it outranks `default`/`enum` — either of those differing would be invalid.
+  if (schema.const !== undefined) {
+    return schema.const;
+  }
   if (schema.default !== undefined) {
     return schema.default;
   }
@@ -202,8 +270,8 @@ const primitiveExample = (
 
 /**
  * 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.
+ * `const` / `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,

package/src/components/openapi/panel.ts

@@ -1,5 +1,5 @@
 /**
- * Client behaviour for the OpenAPI request/response panels. `<blume-panel-tabs>`
+ * Client behavior 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

package/src/components/openapi/snippets.ts

@@ -43,6 +43,26 @@ const jsonContentType = (
   return entries.find(([type]) => type.includes("json")) ?? entries[0];
 };
 
+/** The `?a=1&b=2` query string from an operation's required query params. */
+const queryString = (
+  params: ParamLike[],
+  schemas: Record<string, SchemaLike>
+): string => {
+  const query: string[] = [];
+  for (const param of params) {
+    if (!(param.in === "query" && param.required && param.name)) {
+      continue;
+    }
+    const value = param.example ?? exampleValue(param.schema, schemas);
+    query.push(
+      `${encodeURIComponent(param.name)}=${encodeURIComponent(
+        String(value ?? "")
+      )}`
+    );
+  }
+  return query.length > 0 ? `?${query.join("&")}` : "";
+};
+
 /** Assemble a representative request from an operation and the spec servers. */
 export const buildRequestSample = (
   operation: OperationLike,
@@ -65,15 +85,7 @@ export const buildRequestSample = (
     }
   }
 
-  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 search = queryString(params, schemas);
 
   const headers: Record<string, string> = {};
   for (const param of params) {
@@ -117,7 +129,8 @@ const curlSnippet = (sample: RequestSample): string => {
   if (sample.body) {
     // Close-quote/escaped-quote/reopen: the POSIX way to put a literal ' in a
     // single-quoted string, so an example like "it's" doesn't break the shell.
-    lines.push(`  -d '${sample.body.replaceAll("'", String.raw`'\''`)}'`);
+    const escapedBody = sample.body.replaceAll("'", String.raw`'\''`);
+    lines.push(`  -d '${escapedBody}'`);
   }
   return lines.join(" \\\n");
 };
@@ -200,11 +213,12 @@ const ALIASES: Record<string, string> = {
 /** 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 byId = new Map(LANGUAGES.map((entry) => [entry.id, entry]));
   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);
+    const language = byId.get(id);
     if (language && !seen.has(id)) {
       seen.add(id);
       out.push(language);

package/src/core/base-path.ts

@@ -0,0 +1,94 @@
+/**
+ * The site-wide `basePath` — a mount point that prepends a segment to every
+ * generated route (`/docs/getting-started`) while staying invisible to the
+ * navigation tree (see `core/navigation.ts`, which builds groups from a page's
+ * base-less `navPath` and takes URLs from its based `route`). This is distinct
+ * from a per-source `prefix` (a namespace that *does* create a sidebar group)
+ * and from `deployment.base` (Astro's host-subdirectory base); the two compose,
+ * stacking as `{deployment.base}/{basePath}/page`.
+ *
+ * These helpers run server-side (config, route construction, the link checker,
+ * redirects, the markdown link plugin). The client-side counterpart lives in
+ * `components/islands/base-path.ts` and serves `deployment.base` via `BASE_URL`.
+ */
+
+/**
+ * Canonicalize a configured base path to either `""` (none) or `/seg[/seg…]`
+ * (leading slash, no trailing slash, collapsed inner slashes). A blank value or
+ * bare `/` normalizes to `""`, so an unset/`"/"` base is a clean no-op.
+ */
+export const normalizeBasePath = (input?: string): string => {
+  if (!input) {
+    return "";
+  }
+  const trimmed = input
+    .trim()
+    .replaceAll(/^\/+|\/+$/gu, "")
+    .replaceAll(/\/{2,}/gu, "/");
+  return trimmed === "" ? "" : `/${trimmed}`;
+};
+
+/**
+ * Whether a link target is a root-relative internal path (`/x`) — the only
+ * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,
+ * other schemes (`mailto:`), fragments (`#x`), and relative paths are excluded.
+ */
+export const isInternalPath = (target: string): boolean =>
+  target.startsWith("/") && !target.startsWith("//");
+
+/**
+ * Idempotently prepend `basePath` to a root-relative route. A route already
+ * equal to or nested under the base is returned unchanged, so authors who write
+ * the base by hand (`/docs/x`) aren't double-prefixed to `/docs/docs/x`.
+ */
+export const withBasePath = (basePath: string, route: string): string => {
+  if (!basePath || !isInternalPath(route)) {
+    return route;
+  }
+  if (route === basePath || route.startsWith(`${basePath}/`)) {
+    return route;
+  }
+  return route === "/" ? basePath : `${basePath}${route}`;
+};
+
+/**
+ * {@link withBasePath} for the composed `deployment.base` + `basePath` stack
+ * (`/base` + `/docs` serves pages at `/base/docs/x`). The hand-written-base
+ * promise applies per layer: authors write `basePath` by hand (see
+ * `markdown/base-links.ts`), so a `/docs/x` link gains only the deployment base
+ * (`/base/docs/x`) rather than being double-prefixed to `/base/docs/docs/x`,
+ * and a route already under the full composite is returned unchanged.
+ */
+export const withComposedBasePath = (
+  deployBase: string,
+  basePath: string,
+  route: string
+): string => {
+  const composed = `${deployBase}${basePath}`;
+  if (
+    composed &&
+    isInternalPath(route) &&
+    (route === composed || route.startsWith(`${composed}/`))
+  ) {
+    return route;
+  }
+  return withBasePath(deployBase, withBasePath(basePath, route));
+};
+
+/**
+ * Remove `basePath` from the front of a route (`/docs/guide` -> `/guide`,
+ * `/docs` -> `/`). A route not under the base is returned unchanged. Inverse of
+ * {@link withBasePath}; used to resolve public assets, which live at the site
+ * root regardless of the base.
+ */
+export const stripBasePath = (basePath: string, route: string): string => {
+  if (!basePath) {
+    return route;
+  }
+  if (route === basePath) {
+    return "/";
+  }
+  return route.startsWith(`${basePath}/`)
+    ? route.slice(basePath.length)
+    : route;
+};

package/src/core/builtin-tags.ts

@@ -26,6 +26,8 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Frame",
   "GithubInfo",
   "Icon",
+  // Conditionally imported by the catch-all, but `detectUsesMath` matches any
+  // authored `<Math`, so it is always wired wherever it can appear.
   "Math",
   "Operation",
   "Panel",

package/src/core/component-overrides.ts

@@ -62,6 +62,7 @@ export interface ComponentOverrideAnalysis {
 }
 
 const GROUPS = ["mdx", "layout", "islands"] as const;
+const GROUP_SET = new Set<string>(GROUPS);
 type Group = (typeof GROUPS)[number];
 
 const FRAMEWORK_BY_EXT: Record<string, OverrideFramework> = {
@@ -121,35 +122,43 @@ const emptyAnalysis = (): ComponentOverrideAnalysis => ({
 const propName = (name: ts.PropertyName): string | undefined =>
   ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
 
+/** Record the bindings declared by one import statement into `map`. */
+const addImportBindings = (
+  map: Map<string, ImportBinding>,
+  statement: ts.Statement
+): void => {
+  if (
+    !ts.isImportDeclaration(statement) ||
+    !ts.isStringLiteral(statement.moduleSpecifier)
+  ) {
+    return;
+  }
+  const specifier = statement.moduleSpecifier.text;
+  const clause = statement.importClause;
+  if (!clause) {
+    return;
+  }
+  if (clause.name) {
+    map.set(clause.name.text, { imported: "default", specifier });
+  }
+  const named = clause.namedBindings;
+  if (named && ts.isNamedImports(named)) {
+    for (const element of named.elements) {
+      map.set(element.name.text, {
+        imported: (element.propertyName ?? element.name).text,
+        specifier,
+      });
+    }
+  }
+};
+
 /** Map each local binding name to the module + exported name it came from. */
 const collectImports = (
   sourceFile: ts.SourceFile
 ): Map<string, ImportBinding> => {
   const map = new Map<string, ImportBinding>();
   for (const statement of sourceFile.statements) {
-    if (
-      !ts.isImportDeclaration(statement) ||
-      !ts.isStringLiteral(statement.moduleSpecifier)
-    ) {
-      continue;
-    }
-    const specifier = statement.moduleSpecifier.text;
-    const clause = statement.importClause;
-    if (!clause) {
-      continue;
-    }
-    if (clause.name) {
-      map.set(clause.name.text, { imported: "default", specifier });
-    }
-    const named = clause.namedBindings;
-    if (named && ts.isNamedImports(named)) {
-      for (const element of named.elements) {
-        map.set(element.name.text, {
-          imported: (element.propertyName ?? element.name).text,
-          specifier,
-        });
-      }
-    }
+    addImportBindings(map, statement);
   }
   return map;
 };
@@ -232,6 +241,43 @@ const resolveIdentifier = (
   return binding ? toImport(binding.specifier, binding.imported, dir) : null;
 };
 
+/** Fold one descriptor-object property into the accumulating descriptor. */
+const applyDescriptorProperty = (
+  descriptor: RawDescriptor,
+  property: ts.ObjectLiteralElementLike,
+  imports: Map<string, ImportBinding>,
+  dir: string
+): void => {
+  if (ts.isShorthandPropertyAssignment(property)) {
+    if (property.name.text === "component") {
+      descriptor.hadComponent = true;
+      descriptor.source = resolveIdentifier(property.name.text, imports, dir);
+    }
+    return;
+  }
+  if (!ts.isPropertyAssignment(property)) {
+    return;
+  }
+  const name = propName(property.name);
+  const init = property.initializer;
+  if (name === "component") {
+    descriptor.hadComponent = true;
+    if (ts.isStringLiteral(init)) {
+      descriptor.source = toImport(init.text, "default", dir);
+    } else if (ts.isIdentifier(init)) {
+      descriptor.source = resolveIdentifier(init.text, imports, dir);
+    }
+  } else if (
+    name === "client" &&
+    ts.isStringLiteral(init) &&
+    HYDRATION_MODES.has(init.text as HydrationMode)
+  ) {
+    descriptor.client = init.text as HydrationMode;
+  } else if (name === "media" && ts.isStringLiteral(init)) {
+    descriptor.media = init.text;
+  }
+};
+
 const readDescriptor = (
   object: ts.ObjectLiteralExpression,
   imports: Map<string, ImportBinding>,
@@ -239,34 +285,7 @@ const readDescriptor = (
 ): RawDescriptor => {
   const descriptor: RawDescriptor = { hadComponent: false, source: null };
   for (const property of object.properties) {
-    if (ts.isShorthandPropertyAssignment(property)) {
-      if (property.name.text === "component") {
-        descriptor.hadComponent = true;
-        descriptor.source = resolveIdentifier(property.name.text, imports, dir);
-      }
-      continue;
-    }
-    if (!ts.isPropertyAssignment(property)) {
-      continue;
-    }
-    const name = propName(property.name);
-    const init = property.initializer;
-    if (name === "component") {
-      descriptor.hadComponent = true;
-      if (ts.isStringLiteral(init)) {
-        descriptor.source = toImport(init.text, "default", dir);
-      } else if (ts.isIdentifier(init)) {
-        descriptor.source = resolveIdentifier(init.text, imports, dir);
-      }
-    } else if (
-      name === "client" &&
-      ts.isStringLiteral(init) &&
-      HYDRATION_MODES.has(init.text as HydrationMode)
-    ) {
-      descriptor.client = init.text as HydrationMode;
-    } else if (name === "media" && ts.isStringLiteral(init)) {
-      descriptor.media = init.text;
-    }
+    applyDescriptorProperty(descriptor, property, imports, dir);
   }
   return descriptor;
 };
@@ -422,6 +441,38 @@ const normalizeEntry = (
   return { identifier: false, key, source: null };
 };
 
+/** Normalize one top-level `{ mdx | layout | islands }` group into `result`. */
+const collectGroupOverrides = (
+  property: ts.ObjectLiteralElementLike,
+  imports: Map<string, ImportBinding>,
+  dir: string,
+  result: ComponentOverrideAnalysis
+): void => {
+  if (!ts.isPropertyAssignment(property)) {
+    return;
+  }
+  const name = propName(property.name);
+  if (
+    !(name && GROUP_SET.has(name)) ||
+    !ts.isObjectLiteralExpression(property.initializer)
+  ) {
+    return;
+  }
+  const group = name as Group;
+  for (const entry of property.initializer.properties) {
+    const normalized = normalizeEntry(
+      entry,
+      group,
+      imports,
+      dir,
+      result.warnings
+    );
+    if (normalized) {
+      result[group].push(normalized);
+    }
+  }
+};
+
 /**
  * Parse a user `components.ts`/`.tsx` and return its normalized overrides. Never
  * executes the file. On a parse failure or unrecognized shape, returns empty
@@ -449,29 +500,7 @@ export const analyzeComponentOverrides = (
   const dir = dirname(filePath);
 
   for (const property of object.properties) {
-    if (!ts.isPropertyAssignment(property)) {
-      continue;
-    }
-    const name = propName(property.name);
-    if (
-      !(name && (GROUPS as readonly string[]).includes(name)) ||
-      !ts.isObjectLiteralExpression(property.initializer)
-    ) {
-      continue;
-    }
-    const group = name as Group;
-    for (const entry of property.initializer.properties) {
-      const normalized = normalizeEntry(
-        entry,
-        group,
-        imports,
-        dir,
-        result.warnings
-      );
-      if (normalized) {
-        result[group].push(normalized);
-      }
-    }
+    collectGroupOverrides(property, imports, dir, result);
   }
 
   return result;