blume 0.4.0 → 0.5.1

package/src/components/content/ApiField.astro

@@ -0,0 +1,75 @@
+---
+// Shared field row behind the Mintlify-compat <ParamField>/<ResponseField>/
+// <RequestField> components: a labeled name + type + badges, with the field's
+// description rendered from the slot (which may hold rich MDX, including nested
+// <Expandable> or further fields). Styled to match the native OpenAPI reference
+// rows (src/components/openapi/), so a migrated site reads consistently.
+interface Props {
+  default?: unknown;
+  deprecated?: unknown;
+  location?: string;
+  name?: string;
+  required?: unknown;
+  type?: string;
+}
+
+const {
+  default: defaultValue,
+  deprecated,
+  location,
+  name,
+  required,
+  type,
+} = Astro.props;
+
+// Booleans arrive as MDX shorthand (`required`) or strings (`required="true"`).
+const isTrue = (value: unknown): boolean => value === true || value === "true";
+const hasDefault =
+  defaultValue !== undefined && defaultValue !== null && defaultValue !== "";
+const hasDescription = Astro.slots.has("default");
+---
+
+<div class="not-prose my-2 rounded-blume border border-border px-4 py-3">
+  <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+    {name && <code class="font-mono text-foreground text-sm">{name}</code>}
+    {
+      location && (
+        <span class="rounded bg-muted px-1.5 py-0.5 font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide">
+          {location}
+        </span>
+      )
+    }
+    {type && <span class="text-muted-foreground text-xs">{type}</span>}
+    {
+      isTrue(required) && (
+        <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
+          required
+        </span>
+      )
+    }
+    {
+      isTrue(deprecated) && (
+        <span class="font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide line-through">
+          deprecated
+        </span>
+      )
+    }
+  </div>
+  {
+    hasDefault && (
+      <div class="mt-1 text-muted-foreground text-xs">
+        Default:{" "}
+        <code class="rounded bg-muted px-1 py-0.5 text-foreground">
+          {String(defaultValue)}
+        </code>
+      </div>
+    )
+  }
+  {
+    hasDescription && (
+      <div class="mt-1.5 text-muted-foreground text-sm [&>:first-child]:mt-0 [&>:last-child]:mb-0">
+        <slot />
+      </div>
+    )
+  }
+</div>

package/src/components/content/ParamField.astro

@@ -0,0 +1,39 @@
+---
+// Mintlify-compat <ParamField>. Mintlify encodes the parameter's location in the
+// attribute name (`<ParamField path="id" />`, `query`, `header`, `body`); the
+// attribute's value is the field name. Falls back to a plain `name` prop.
+import ApiField from "./ApiField.astro";
+
+const {
+  body,
+  default: defaultValue,
+  deprecated,
+  header,
+  name,
+  path,
+  query,
+  required,
+  type,
+} = Astro.props;
+
+const locations = [
+  { key: "path", value: path },
+  { key: "query", value: query },
+  { key: "header", value: header },
+  { key: "body", value: body },
+] as const;
+const located = locations.find((entry) => typeof entry.value === "string");
+const fieldName = located ? located.value : name;
+const location = located?.key;
+---
+
+<ApiField
+  default={defaultValue}
+  deprecated={deprecated}
+  location={location}
+  name={fieldName}
+  required={required}
+  type={type}
+>
+  <slot />
+</ApiField>

package/src/components/content/RequestField.astro

@@ -0,0 +1,23 @@
+---
+// Mintlify-compat <RequestField>: same shape as <ResponseField> — a named field
+// (`name`, `type`, `required`, `default`, `deprecated`) with a slotted body.
+import ApiField from "./ApiField.astro";
+
+const {
+  default: defaultValue,
+  deprecated,
+  name,
+  required,
+  type,
+} = Astro.props;
+---
+
+<ApiField
+  default={defaultValue}
+  deprecated={deprecated}
+  name={name}
+  required={required}
+  type={type}
+>
+  <slot />
+</ApiField>

package/src/components/content/ResponseField.astro

@@ -0,0 +1,23 @@
+---
+// Mintlify-compat <ResponseField>: a named field (`name`, `type`, `required`,
+// `default`, `deprecated`) with its description in the slot.
+import ApiField from "./ApiField.astro";
+
+const {
+  default: defaultValue,
+  deprecated,
+  name,
+  required,
+  type,
+} = Astro.props;
+---
+
+<ApiField
+  default={defaultValue}
+  deprecated={deprecated}
+  name={name}
+  required={required}
+  type={type}
+>
+  <slot />
+</ApiField>

package/src/components/content/Step.astro

@@ -18,7 +18,7 @@ const canRenderIcon =
   icon !== undefined &&
   (/^\s*<svg[\s\S]*<\/svg>\s*$/u.test(icon) ||
     isImageIcon(icon) ||
-    hasIcon(icon, iconType));
+    hasIcon(icon, { iconType }));
 ---
 
 <div

package/src/components/layout/Breadcrumbs.astro

@@ -4,9 +4,11 @@ import type { Crumb } from "./nav-utils.ts";
 interface Props {
   /** Full breadcrumb trail from the site root to the current page. */
   crumbs: Crumb[];
+  /** Left-align full width (for the wide API layout) instead of the prose measure. */
+  wide?: boolean;
 }
 
-const { crumbs } = Astro.props;
+const { crumbs, wide = false } = Astro.props;
 
 // The built-in shows a single "eyebrow" crumb — the parent group — rather than
 // the whole trail. An override receives the complete list and can render more.
@@ -17,7 +19,10 @@ const eyebrowCrumb = crumbs.length > 1 ? crumbs[crumbs.length - 2] : null;
   eyebrowCrumb && (
     <nav
       aria-label="Breadcrumb"
-      class="mx-auto mb-2 max-w-[42rem] text-muted-foreground text-sm"
+      class:list={[
+        "mb-2 text-muted-foreground text-sm",
+        wide ? "max-w-none" : "mx-auto max-w-[42rem]",
+      ]}
     >
       {eyebrowCrumb.route ? (
         <a class="hover:text-foreground" href={eyebrowCrumb.route}>

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