blume 0.4.0 → 0.5.0

package/src/components/openapi/RequestPanel.astro

@@ -0,0 +1,169 @@
+---
+import { highlightCode } from "../../markdown/index.ts";
+import { exampleValue, type SchemaLike, toJson } from "./helpers.ts";
+import type { RequestSample, SampleLanguage } from "./snippets.ts";
+
+interface MediaTypeLike {
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+interface ResponseLike {
+  description?: string;
+  content?: Record<string, MediaTypeLike>;
+}
+
+interface Props {
+  sample: RequestSample;
+  languages: SampleLanguage[];
+  responses: Record<string, ResponseLike>;
+  schemas: Record<string, SchemaLike>;
+}
+
+const { sample, languages, responses, schemas } = Astro.props;
+
+// A `.prose` wrapper gives Shiki its scoped token colours; 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.
+const CODE_WRAP = "prose max-w-none text-xs";
+const TAB_CLASS =
+  "-mb-px cursor-pointer border-transparent border-b-2 bg-transparent py-2 font-medium text-muted-foreground text-xs transition-colors hover:text-foreground aria-[selected=true]:border-accent aria-[selected=true]:text-foreground";
+const HEADING = "mb-2 font-semibold text-foreground text-sm";
+
+const requestSamples = await Promise.all(
+  languages.map(async (language) => ({
+    html: await highlightCode(language.build(sample), language.lang, {
+      icons: false,
+    }),
+    id: language.id,
+    label: language.label,
+  }))
+);
+
+const responseEntries = await Promise.all(
+  Object.entries(responses).map(async ([status, response]) => {
+    const media =
+      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 html =
+      example === undefined || example === null
+        ? null
+        : await highlightCode(toJson(example), "json", { icons: false });
+    return { description: response.description ?? "", html, status };
+  })
+);
+---
+
+<div class="not-prose flex flex-col gap-6">
+  {
+    requestSamples.length > 0 && (
+      <div>
+        <div aria-level="3" class={HEADING} role="heading">
+          Request
+        </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 gap-4" role="tablist">
+              {requestSamples.map((entry, index) => (
+                <button
+                  aria-selected={index === 0 ? "true" : "false"}
+                  class={TAB_CLASS}
+                  data-panel-tab={entry.id}
+                  role="tab"
+                  type="button"
+                >
+                  {entry.label}
+                </button>
+              ))}
+            </div>
+            <button
+              aria-label="Copy request"
+              class="group shrink-0 cursor-pointer rounded px-1.5 py-1 text-muted-foreground text-xs hover:text-foreground"
+              data-panel-copy
+              type="button"
+            >
+              <span class="group-data-[copied]:hidden">Copy</span>
+              <span class="hidden group-data-[copied]:inline">Copied</span>
+            </button>
+          </div>
+          {requestSamples.map((entry, index) => (
+            <div
+              class:list={[index === 0 ? "" : "hidden", CODE_WRAP]}
+              data-panel={entry.id}
+            >
+              <Fragment set:html={entry.html} />
+            </div>
+          ))}
+        </blume-panel-tabs>
+      </div>
+    )
+  }
+  {
+    responseEntries.length > 0 && (
+      <div>
+        <div aria-level="3" class={HEADING} role="heading">
+          Response
+        </div>
+        <blume-panel-tabs class="block overflow-hidden rounded-blume border border-border bg-background">
+          <div class="flex flex-wrap gap-4 border-border border-b px-3" role="tablist">
+            {responseEntries.map((entry, index) => (
+              <button
+                aria-selected={index === 0 ? "true" : "false"}
+                class={`${TAB_CLASS} font-mono`}
+                data-panel-tab={entry.status}
+                role="tab"
+                type="button"
+              >
+                {entry.status}
+              </button>
+            ))}
+          </div>
+          {responseEntries.map((entry, index) => (
+            <div
+              class:list={[index === 0 ? "" : "hidden"]}
+              data-panel={entry.status}
+            >
+              {entry.html ? (
+                <div class={CODE_WRAP}>
+                  <Fragment set:html={entry.html} />
+                </div>
+              ) : (
+                <div class="px-3 py-4 text-muted-foreground text-xs">
+                  {entry.description || "No example response."}
+                </div>
+              )}
+            </div>
+          ))}
+        </blume-panel-tabs>
+      </div>
+    )
+  }
+</div>
+
+<script>
+  import "./panel.ts";
+</script>
+
+<style is:global>
+  /* Strip the standalone code block's own chrome inside a panel: the border,
+     margin, radius, and the copy button + language label the prose code theme
+     adds — the panel supplies a single border and its own copy button. */
+  blume-panel-tabs pre.astro-code {
+    margin: 0 !important;
+    border: 0 !important;
+    border-radius: 0 !important;
+    background: transparent !important;
+    padding: 0.75rem 1rem !important;
+  }
+  blume-panel-tabs pre.astro-code::before {
+    content: none !important;
+  }
+  blume-panel-tabs [data-blume-copy] {
+    display: none !important;
+  }
+</style>

package/src/components/openapi/Responses.astro

@@ -0,0 +1,91 @@
+---
+import type { SchemaLike } from "./helpers.ts";
+import SchemaTable from "./SchemaTable.astro";
+
+interface MediaTypeLike {
+  schema?: SchemaLike;
+}
+
+interface ResponseLike {
+  description?: string;
+  content?: Record<string, MediaTypeLike>;
+}
+
+interface Props {
+  responses: Record<string, ResponseLike>;
+  schemas: Record<string, SchemaLike>;
+  expandAll?: boolean;
+}
+
+const { responses, schemas, expandAll = false } = Astro.props;
+
+const statusColor = (status: string): string => {
+  if (status.startsWith("2")) {
+    return "bg-green-500/15 text-green-700 dark:text-green-300";
+  }
+  if (status.startsWith("3")) {
+    return "bg-blue-500/15 text-blue-700 dark:text-blue-300";
+  }
+  if (status.startsWith("4")) {
+    return "bg-orange-500/15 text-orange-700 dark:text-orange-300";
+  }
+  if (status.startsWith("5")) {
+    return "bg-red-500/15 text-red-700 dark:text-red-300";
+  }
+  return "bg-muted text-muted-foreground";
+};
+
+const items = Object.entries(responses);
+---
+
+{
+  items.length > 0 && (
+    <section class="mt-8">
+      <div
+        aria-level="2"
+        class="mb-3 font-semibold text-foreground text-lg"
+        role="heading"
+      >
+        Responses
+      </div>
+      <div class="flex flex-col gap-4">
+        {items.map(([status, response]) => {
+          const schema = (
+            Object.entries(response.content ?? {}).find(([type]) =>
+              type.includes("json")
+            )?.[1] ?? Object.values(response.content ?? {})[0]
+          )?.schema;
+          return (
+            <div class="rounded-blume border border-border p-4">
+              <div class="flex flex-wrap items-center gap-2">
+                <span
+                  class:list={[
+                    "not-prose inline-flex items-center rounded-md px-2 py-0.5 font-mono font-semibold text-xs",
+                    statusColor(status),
+                  ]}
+                >
+                  {status}
+                </span>
+                {response.description && (
+                  <span
+                    class="text-muted-foreground text-sm"
+                    set:text={response.description}
+                  />
+                )}
+              </div>
+              {schema && (
+                <div class="mt-3">
+                  <SchemaTable
+                    expandAll={expandAll}
+                    schema={schema}
+                    schemas={schemas}
+                  />
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </section>
+  )
+}

package/src/components/openapi/SchemaProperty.astro

@@ -0,0 +1,118 @@
+---
+import {
+  constraints,
+  isNullable,
+  refName,
+  resolveSchema,
+  type SchemaLike,
+  typeLabel,
+} from "./helpers.ts";
+import SchemaTable from "./SchemaTable.astro";
+
+interface Props {
+  name: string;
+  schema: SchemaLike;
+  required?: boolean;
+  schemas: Record<string, SchemaLike>;
+  seen?: string[];
+  expandAll?: boolean;
+}
+
+const {
+  name,
+  schema,
+  required = false,
+  schemas,
+  seen = [],
+  expandAll = false,
+} = Astro.props;
+
+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, schemas);
+const description = resolved.description ?? schema.description ?? "";
+const deprecated = resolved.deprecated === true;
+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)));
+---
+
+<div class="border-border border-t py-3 first:border-t-0 last:pb-0">
+  <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+    <code class="font-mono text-foreground text-sm">{name}</code>
+    <span class="text-muted-foreground text-xs"
+      >{type}{nullable ? " | null" : ""}</span
+    >
+    {
+      required && (
+        <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
+          required
+        </span>
+      )
+    }
+    {
+      deprecated && (
+        <span class="font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide line-through">
+          deprecated
+        </span>
+      )
+    }
+  </div>
+  {
+    description && (
+      <div class="mt-1 text-muted-foreground text-sm" set:text={description} />
+    )
+  }
+  {
+    limits.length > 0 && (
+      <div class="mt-1 text-muted-foreground text-xs">{limits.join(" · ")}</div>
+    )
+  }
+  {
+    enumValues && (
+      <div class="mt-1 flex flex-wrap items-center gap-1 text-xs">
+        <span class="text-muted-foreground">Allowed:</span>
+        {enumValues.map((value) => (
+          <code class="rounded bg-muted px-1 py-0.5 text-foreground">
+            {String(value)}
+          </code>
+        ))}
+      </div>
+    )
+  }
+  {
+    expandable && (
+      <details class="group mt-2" open={expandAll}>
+        <summary class="cursor-pointer select-none text-accent text-xs hover:underline">
+          <span class="group-open:hidden">Show properties</span>
+          <span class="hidden group-open:inline">Hide properties</span>
+        </summary>
+        <div class="mt-2 border-border border-l pl-4">
+          <SchemaTable
+            schema={schema}
+            schemas={schemas}
+            seen={seen}
+            expandAll={expandAll}
+          />
+        </div>
+      </details>
+    )
+  }
+</div>

package/src/components/openapi/SchemaTable.astro

@@ -0,0 +1,86 @@
+---
+import {
+  objectProperties,
+  refName,
+  resolveSchema,
+  type SchemaLike,
+  typeLabel,
+} from "./helpers.ts";
+import SchemaProperty from "./SchemaProperty.astro";
+
+interface Props {
+  schema: SchemaLike;
+  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;
+
+// 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);
+---
+
+{
+  circular ? (
+    <div class="text-muted-foreground text-sm">
+      Circular reference to <code class="text-foreground">{refLabel}</code>.
+    </div>
+  ) : isArray ? (
+    <div>
+      <div class="mb-2 text-muted-foreground text-xs">
+        Array of <code class="text-foreground">{typeLabel(items ?? {}, schemas)}</code>
+      </div>
+      {items && (
+        <Astro.self schema={items} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
+      )}
+    </div>
+  ) : 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="rounded-blume border border-border p-3">
+          <div class="mb-2 font-medium text-foreground text-xs">
+            {typeLabel(branch, schemas) || `Option ${index + 1}`}
+          </div>
+          <Astro.self schema={branch} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
+        </div>
+      ))}
+    </div>
+  ) : properties.length > 0 ? (
+    <div class="not-prose">
+      {properties.map(([name, prop]) => (
+        <SchemaProperty
+          name={name}
+          schema={prop}
+          required={required.has(name)}
+          schemas={schemas}
+          seen={nextSeen}
+          expandAll={expandAll}
+        />
+      ))}
+    </div>
+  ) : (
+    <div class="text-muted-foreground text-sm">
+      <code class="text-foreground">{typeLabel(resolved, schemas)}</code>
+    </div>
+  )
+}

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