blume 0.4.0 → 0.5.1

package/src/components/openapi/ParametersTable.astro

@@ -0,0 +1,97 @@
+---
+import {
+  constraints,
+  resolveSchema,
+  type SchemaLike,
+  typeLabel,
+} from "./helpers.ts";
+
+interface ParamLike {
+  name?: string;
+  in?: string;
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  schema?: SchemaLike;
+}
+
+interface Props {
+  parameters: ParamLike[];
+  schemas: Record<string, SchemaLike>;
+}
+
+const { parameters, schemas } = Astro.props;
+
+const SECTIONS: { in: string; title: string }[] = [
+  { in: "path", title: "Path parameters" },
+  { in: "query", title: "Query parameters" },
+  { in: "header", title: "Header parameters" },
+  { in: "cookie", title: "Cookie parameters" },
+];
+
+const groups = SECTIONS.map((section) => ({
+  items: parameters.filter((param) => param.in === section.in),
+  title: section.title,
+})).filter((group) => group.items.length > 0);
+---
+
+{
+  groups.map((group) => (
+    <section class="mt-6">
+      <div
+        aria-level="3"
+        class="mb-2 font-semibold text-foreground text-sm"
+        role="heading"
+      >
+        {group.title}
+      </div>
+      <div class="not-prose rounded-blume border border-border px-4">
+        {group.items.map((param) => {
+          const resolved = resolveSchema(schemas, param.schema ?? {});
+          const type = param.schema ? typeLabel(param.schema, schemas) : "string";
+          const limits = constraints(resolved);
+          const enumValues = Array.isArray(resolved.enum) ? resolved.enum : null;
+          return (
+            <div class="border-border border-t py-3 first:border-t-0">
+              <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+                <code class="font-mono text-foreground text-sm">{param.name}</code>
+                <span class="text-muted-foreground text-xs">{type}</span>
+                {param.required && (
+                  <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
+                    required
+                  </span>
+                )}
+                {param.deprecated && (
+                  <span class="font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide line-through">
+                    deprecated
+                  </span>
+                )}
+              </div>
+              {param.description && (
+                <div
+                  class="mt-1 text-muted-foreground text-sm"
+                  set:text={param.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>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </section>
+  ))
+}

package/src/components/openapi/RequestBody.astro

@@ -0,0 +1,58 @@
+---
+import type { SchemaLike } from "./helpers.ts";
+import SchemaTable from "./SchemaTable.astro";
+
+interface MediaTypeLike {
+  schema?: SchemaLike;
+}
+
+interface RequestBodyLike {
+  description?: string;
+  required?: boolean;
+  content?: Record<string, MediaTypeLike>;
+}
+
+interface Props {
+  requestBody: RequestBodyLike;
+  schemas: Record<string, SchemaLike>;
+  expandAll?: boolean;
+}
+
+const { requestBody, schemas, expandAll = false } = Astro.props;
+
+const entries = Object.entries(requestBody.content ?? {});
+const chosen = entries.find(([type]) => type.includes("json")) ?? entries[0];
+const contentType = chosen?.[0] ?? "application/json";
+const schema = chosen?.[1]?.schema ?? {};
+---
+
+<section class="mt-8">
+  <div class="mb-2 flex flex-wrap items-center gap-2">
+    <div
+      aria-level="2"
+      class="font-semibold text-foreground text-lg"
+      role="heading"
+    >
+      Request body
+    </div>
+    {
+      requestBody.required && (
+        <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
+          required
+        </span>
+      )
+    }
+    <code class="text-muted-foreground text-xs">{contentType}</code>
+  </div>
+  {
+    requestBody.description && (
+      <div
+        class="text-muted-foreground text-sm"
+        set:text={requestBody.description}
+      />
+    )
+  }
+  <div class="mt-3">
+    <SchemaTable expandAll={expandAll} schema={schema} schemas={schemas} />
+  </div>
+</section>

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>
+  )
+}