blume 0.3.0 → 0.5.0

package/src/components/layout/NavTree.astro

@@ -31,8 +31,24 @@ const {
   root = depth === 0,
 } = Astro.props;
 
-const badgeClass =
-  "shrink-0 rounded-full bg-muted px-1.5 py-0.5 font-medium text-[0.65rem] text-muted-foreground leading-none";
+const badgeBase =
+  "shrink-0 rounded-full px-1.5 py-0.5 font-medium text-[0.65rem] leading-none";
+const badgeClass = `${badgeBase} bg-muted text-muted-foreground`;
+// HTTP-method badges (from an OpenAPI reference's sidebar) are colour-coded;
+// every other badge keeps the neutral style.
+const METHOD_BADGE: Record<string, string> = {
+  DELETE: "bg-red-500/15 text-red-700 dark:text-red-300",
+  GET: "bg-green-500/15 text-green-700 dark:text-green-300",
+  HEAD: "bg-muted text-muted-foreground",
+  OPTIONS: "bg-muted text-muted-foreground",
+  PATCH: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
+  POST: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  PUT: "bg-orange-500/15 text-orange-700 dark:text-orange-300",
+};
+const badgeClassFor = (badge: string): string => {
+  const method = METHOD_BADGE[badge.toUpperCase()];
+  return method ? `${badgeBase} ${method}` : badgeClass;
+};
 const deprecatedClass =
   "shrink-0 rounded-full bg-amber-500/10 px-1.5 py-0.5 font-medium text-[0.65rem] text-amber-700 leading-none dark:text-amber-300";
 
@@ -154,7 +170,7 @@ const initialId =
                     />
                   )}
                   <span class="min-w-0 flex-1 truncate">{item.label}</span>
-                  {item.badge && <span class={badgeClass}>{item.badge}</span>}
+                  {item.badge && <span class={badgeClassFor(item.badge)}>{item.badge}</span>}
                   {item.deprecated && (
                     <span class={deprecatedClass}>deprecated</span>
                   )}
@@ -188,7 +204,7 @@ const initialId =
                   />
                 )}
                 <span class="min-w-0 flex-1 truncate">{item.label}</span>
-                {item.badge && <span class={badgeClass}>{item.badge}</span>}
+                {item.badge && <span class={badgeClassFor(item.badge)}>{item.badge}</span>}
                 <Icon
                   class="shrink-0 text-muted-foreground"
                   name="chevron-right"
@@ -224,7 +240,7 @@ const initialId =
                       )}
                       <span class="min-w-0 flex-1 truncate">{item.label}</span>
                       {item.badge && (
-                        <span class={badgeClass}>{item.badge}</span>
+                        <span class={badgeClassFor(item.badge)}>{item.badge}</span>
                       )}
                     </a>
                   ) : (
@@ -238,7 +254,7 @@ const initialId =
                       )}
                       <span class="min-w-0 flex-1 truncate">{item.label}</span>
                       {item.badge && (
-                        <span class={badgeClass}>{item.badge}</span>
+                        <span class={badgeClassFor(item.badge)}>{item.badge}</span>
                       )}
                     </>
                   )}
@@ -279,7 +295,7 @@ const initialId =
                   )}
                   <span class="min-w-0 truncate">{item.label}</span>
                   {item.badge && (
-                    <span class={`ml-auto ${badgeClass}`}>{item.badge}</span>
+                    <span class={`ml-auto ${badgeClassFor(item.badge)}`}>{item.badge}</span>
                   )}
                 </a>
               ) : (
@@ -293,7 +309,7 @@ const initialId =
                   )}
                   <span class="min-w-0 truncate">{item.label}</span>
                   {item.badge && (
-                    <span class={`ml-auto ${badgeClass}`}>{item.badge}</span>
+                    <span class={`ml-auto ${badgeClassFor(item.badge)}`}>{item.badge}</span>
                   )}
                 </>
               )}

package/src/components/layout/RootLayout.astro

@@ -200,9 +200,19 @@ const searchLocale =
   localeSwitch && localeSwitch.length > 1 ? locale : undefined;
 // TOC entries: the configured heading range, or none when the TOC is disabled
 // (an empty list makes TableOfContents render nothing).
-const tocHeadings = toc.enabled
-  ? headings.filter((h) => h.depth >= toc.minLevel && h.depth <= toc.maxLevel)
-  : [];
+// API operation pages own a two-column body (docs + request panel) and their own
+// right rail, so they drop the table of contents and widen the content column.
+const isApiOperation = pageType === "openapi-operation";
+const tocHeadings =
+  toc.enabled && !isApiOperation
+    ? headings.filter((h) => h.depth >= toc.minLevel && h.depth <= toc.maxLevel)
+    : [];
+const gridClass = isApiOperation
+  ? "lg:grid-cols-[17.5rem_minmax(0,1fr)]"
+  : "lg:grid-cols-[17.5rem_minmax(0,1fr)] xl:grid-cols-[17.5rem_minmax(0,1fr)_17.5rem]";
+const articleClass = isApiOperation
+  ? "prose max-w-none"
+  : "prose mx-auto max-w-[42rem]";
 const pageTitle = page.title ? `${page.title} - ${site.title}` : site.title;
 const description = page.description ?? site.description;
 
@@ -331,7 +341,7 @@ const bannerScript = banner?.dismissible
     >
       <slot name="ask" slot="ask" />
     </HeaderSlot>
-    <div class="mx-auto grid grid-cols-1 items-start lg:grid-cols-[17.5rem_minmax(0,1fr)] xl:grid-cols-[17.5rem_minmax(0,1fr)_17.5rem]">
+    <div class:list={["mx-auto grid grid-cols-1 items-start", gridClass]}>
       <aside
         aria-label="Primary"
         class="fixed top-16 start-0 z-[35] h-[calc(100dvh-4rem)] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:z-auto lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4"
@@ -354,47 +364,59 @@ const bannerScript = banner?.dismissible
         </nav>
       </aside>
       <main class="min-w-0 px-6 pt-6 pb-10 lg:px-8 xl:px-10" id="blume-content">
-        <BreadcrumbsSlot crumbs={crumbs} />
+        <BreadcrumbsSlot crumbs={crumbs} wide={isApiOperation} />
         <TableOfContentsSlot
           headings={tocHeadings}
           title={strings.toc.title}
           variant="mobile"
         />
         <PageHeaderSlot headings={tocHeadings} page={page} route={page.route} />
-        <article class="prose mx-auto max-w-[42rem]" dir={contentDir}>
+        <article class:list={[articleClass]} dir={contentDir}>
           <slot />
         </article>
-        <PageFooterSlot headings={tocHeadings} page={page} route={page.route} />
         {
-          formattedLastModified && (
-            <p class="mx-auto mt-10 max-w-[42rem] text-muted-foreground text-sm">
-              {strings.page.lastUpdated} {formattedLastModified}
-            </p>
+          !isApiOperation && (
+            <>
+              <PageFooterSlot
+                headings={tocHeadings}
+                page={page}
+                route={page.route}
+              />
+              {formattedLastModified && (
+                <p class="mx-auto mt-10 max-w-[42rem] text-muted-foreground text-sm">
+                  {strings.page.lastUpdated} {formattedLastModified}
+                </p>
+              )}
+              {feedback && <FeedbackSlot strings={strings.feedback} />}
+              <PaginationSlot next={next} prev={prev} strings={strings.page} />
+            </>
           )
         }
-        {feedback && <FeedbackSlot strings={strings.feedback} />}
-        <PaginationSlot next={next} prev={prev} strings={strings.page} />
       </main>
-      <aside
-        aria-label={strings.toc.title}
-        class="sticky top-16 hidden h-[calc(100dvh-4rem)] overflow-y-auto px-4 pt-6 pb-10 text-sm xl:block"
-      >
-        <TableOfContentsSlot
-          headings={tocHeadings}
-          title={strings.toc.title}
-          variant="desktop"
-        />
-        <PageActions
-          askEnabled={askEnabled}
-          editUrl={editUrl}
-          exportEpub={exportEpub}
-          exportPdf={exportPdf}
-          mcpName={mcp?.name}
-          mcpUrl={mcpUrl}
-          route={page.route}
-          strings={strings.actions}
-        />
-      </aside>
+      {
+        !isApiOperation && (
+          <aside
+            aria-label={strings.toc.title}
+            class="sticky top-16 hidden h-[calc(100dvh-4rem)] overflow-y-auto px-4 pt-6 pb-10 text-sm xl:block"
+          >
+            <TableOfContentsSlot
+              headings={tocHeadings}
+              title={strings.toc.title}
+              variant="desktop"
+            />
+            <PageActions
+              askEnabled={askEnabled}
+              editUrl={editUrl}
+              exportEpub={exportEpub}
+              exportPdf={exportPdf}
+              mcpName={mcp?.name}
+              mcpUrl={mcpUrl}
+              route={page.route}
+              strings={strings.actions}
+            />
+          </aside>
+        )
+      }
     </div>
     <FooterSlot navigation={navigation} site={site} ui={strings} />
     {
@@ -414,7 +436,7 @@ const bannerScript = banner?.dismissible
       type="button"
     ></button>
     <script>
-      import { icons } from "../../theme/icons.ts";
+      import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
       // Registers the <blume-mermaid> custom element (emitted by ```mermaid
       // fences). Mermaid itself is lazy-loaded only on pages that use a diagram.
       import "../content/mermaid-element.ts";

package/src/components/layout/Search.astro

@@ -138,7 +138,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   />
 
   <script>
-    import { icons } from "../../theme/icons.ts";
+    import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
     import {
       escapeHtml,
       highlight,

package/src/components/openapi/ApiOverview.astro

@@ -0,0 +1,84 @@
+---
+import specs from "blume:openapi";
+import MethodBadge from "./MethodBadge.astro";
+
+interface Props {
+  source: string;
+}
+
+const { source } = Astro.props;
+const spec = specs[source];
+const operations = Object.values(spec?.operations ?? {});
+const servers =
+  ((spec?.document ?? {}) as { servers?: { url?: string }[] }).servers ?? [];
+
+// Tags in declared order, then any operation tag not listed under `tags`.
+const declaredSlugs = new Set(spec?.tags.map((tag) => tag.slug));
+const extraSlugs = new Set<string>();
+const extraTags: { slug: string; name: string; description: string }[] = [];
+for (const operation of operations) {
+  if (!(declaredSlugs.has(operation.tagSlug) || extraSlugs.has(operation.tagSlug))) {
+    extraSlugs.add(operation.tagSlug);
+    extraTags.push({ description: "", name: operation.tag, slug: operation.tagSlug });
+  }
+}
+const sections = [...(spec?.tags ?? []), ...extraTags];
+---
+
+{
+  spec && (
+    <div>
+      {spec.version && (
+        <div class="not-prose mb-4 text-muted-foreground text-sm">
+          Version {spec.version}
+        </div>
+      )}
+      {servers.length > 0 && (
+        <div class="not-prose mb-8 flex flex-wrap items-center gap-2">
+          <span class="text-muted-foreground text-xs">Base URL</span>
+          {servers.map((server) => (
+            <code class="rounded bg-muted px-2 py-0.5 text-foreground text-xs">
+              {server.url}
+            </code>
+          ))}
+        </div>
+      )}
+      {sections.map((tag) => {
+        const ops = operations.filter(
+          (operation) => operation.tagSlug === tag.slug
+        );
+        if (ops.length === 0) {
+          return null;
+        }
+        return (
+          <section class="mb-8">
+            <h2 class="mb-1 font-semibold text-foreground text-xl">
+              {tag.name}
+            </h2>
+            {tag.description && (
+              <div class="mb-3 text-muted-foreground text-sm" set:text={tag.description} />
+            )}
+            <ul class="not-prose flex list-none flex-col gap-2 p-0">
+              {ops.map((operation) => (
+                <li>
+                  <a
+                    class="flex items-center gap-3 rounded-blume border border-border p-3 text-inherit no-underline! transition-colors hover:border-accent hover:bg-muted hover:no-underline!"
+                    href={operation.route}
+                  >
+                    <MethodBadge method={operation.method} />
+                    <span class="font-medium text-foreground text-sm">
+                      {operation.summary || operation.path}
+                    </span>
+                    <code class="ml-auto hidden text-muted-foreground text-xs sm:inline">
+                      {operation.path}
+                    </code>
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </section>
+        );
+      })}
+    </div>
+  )
+}

package/src/components/openapi/MethodBadge.astro

@@ -0,0 +1,28 @@
+---
+interface Props {
+  method: string;
+  class?: string;
+}
+
+const { method, class: className } = Astro.props;
+const upper = method.toUpperCase();
+
+const COLORS: Record<string, string> = {
+  DELETE: "bg-red-500/15 text-red-700 dark:text-red-300",
+  GET: "bg-green-500/15 text-green-700 dark:text-green-300",
+  HEAD: "bg-muted text-muted-foreground",
+  OPTIONS: "bg-muted text-muted-foreground",
+  PATCH: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
+  POST: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  PUT: "bg-orange-500/15 text-orange-700 dark:text-orange-300",
+};
+const color = COLORS[upper] ?? "bg-muted text-muted-foreground";
+---
+
+<span
+  class:list={[
+    "not-prose inline-flex items-center rounded-md px-2 py-0.5 font-mono font-semibold text-xs uppercase tracking-wide",
+    color,
+    className,
+  ]}>{upper}</span
+>

package/src/components/openapi/Operation.astro

@@ -0,0 +1,140 @@
+---
+import specs from "blume:openapi";
+import type { SchemaLike } from "./helpers.ts";
+import { buildRequestSample, sampleLanguages } from "./snippets.ts";
+import MethodBadge from "./MethodBadge.astro";
+import ParametersTable from "./ParametersTable.astro";
+import RequestBody from "./RequestBody.astro";
+import RequestPanel from "./RequestPanel.astro";
+import Responses from "./Responses.astro";
+
+interface Props {
+  source: string;
+  id: string;
+}
+
+interface ParamLike {
+  $ref?: string;
+  name?: string;
+  in?: string;
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+interface MediaTypeLike {
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+interface FullOperation {
+  summary?: string;
+  description?: string;
+  deprecated?: boolean;
+  parameters?: ParamLike[];
+  requestBody?: {
+    description?: string;
+    required?: boolean;
+    content?: Record<string, MediaTypeLike>;
+  };
+  responses?: Record<
+    string,
+    { description?: string; content?: Record<string, MediaTypeLike> }
+  >;
+}
+
+const { source, id } = Astro.props;
+const spec = specs[source];
+const ref = spec?.operations[id];
+
+const doc = (spec?.document ?? {}) as {
+  paths?: Record<string, Record<string, unknown> & { parameters?: ParamLike[] }>;
+  components?: {
+    schemas?: Record<string, SchemaLike>;
+    parameters?: Record<string, ParamLike>;
+  };
+  servers?: { url?: string }[];
+};
+const pathItem = ref ? doc.paths?.[ref.path] : undefined;
+const operation = (
+  pathItem && ref ? pathItem[ref.method] : undefined
+) as FullOperation | undefined;
+
+const schemas = doc.components?.schemas ?? {};
+const componentParams = doc.components?.parameters ?? {};
+const PARAM_REF = /#\/components\/parameters\/(?<name>[^/]+)$/u;
+const resolveParam = (param: ParamLike): ParamLike => {
+  if (typeof param.$ref === "string") {
+    const name = PARAM_REF.exec(param.$ref)?.groups?.name;
+    return (name && componentParams[name]) || param;
+  }
+  return param;
+};
+const params = [
+  ...(pathItem?.parameters ?? []),
+  ...(operation?.parameters ?? []),
+].map(resolveParam);
+
+const sample =
+  ref && operation
+    ? buildRequestSample(
+        { parameters: params, requestBody: operation.requestBody },
+        ref.method,
+        ref.path,
+        doc.servers ?? [],
+        schemas
+      )
+    : null;
+const languages = sampleLanguages(spec?.codeSamples ?? []);
+---
+
+{
+  !(spec && ref && operation) ? (
+    <div class="text-muted-foreground">This API operation could not be found.</div>
+  ) : (
+    <div class="not-prose">
+      <div class="mb-6 flex flex-wrap items-center gap-3">
+        <MethodBadge method={ref.method} />
+        <code class="break-all font-mono text-foreground text-sm">
+          {ref.path}
+        </code>
+        {operation.deprecated && (
+          <span class="font-medium text-[0.625rem] text-orange-600 uppercase tracking-wide dark:text-orange-400">
+            deprecated
+          </span>
+        )}
+      </div>
+      <div class="grid grid-cols-1 items-start gap-x-10 gap-y-8 xl:grid-cols-[minmax(0,1fr)_minmax(0,28rem)]">
+        <div>
+          <ParametersTable parameters={params} schemas={schemas} />
+          {operation.requestBody && (
+            <RequestBody
+              expandAll={spec.expandSchemas}
+              requestBody={operation.requestBody}
+              schemas={schemas}
+            />
+          )}
+          {operation.responses && (
+            <Responses
+              expandAll={spec.expandSchemas}
+              responses={operation.responses}
+              schemas={schemas}
+            />
+          )}
+        </div>
+        {sample && (
+          <div class="xl:sticky xl:top-24 xl:self-start">
+            <RequestPanel
+              languages={languages}
+              responses={operation.responses ?? {}}
+              sample={sample}
+              schemas={schemas}
+            />
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

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>