blume 1.5.2 → 1.6.0

package/src/components/openapi/GraphqlType.astro

@@ -0,0 +1,154 @@
+---
+import type { GraphqlDocument } from "../../openapi/graphql.ts";
+import { graphqlTypeDef } from "../../openapi/graphql.ts";
+import type { ApiOperationRef, ApiSpecData } from "../../openapi/model.ts";
+import {
+  graphqlOperationRoutes,
+  graphqlRoutes,
+  graphqlUsage,
+} from "./graphql-helpers.ts";
+import GraphqlChip from "./GraphqlChip.astro";
+import GraphqlFieldsTable from "./GraphqlFieldsTable.astro";
+import MethodBadge from "./MethodBadge.astro";
+
+/**
+ * A named-type reference page: the type's fields (or input fields, enum
+ * values, union members), what it implements or is implemented by, and usage
+ * backlinks — which operations return or accept it and which types reference
+ * it. The description prose is already in the MDX body above this component.
+ */
+interface Props {
+  spec: ApiSpecData;
+  refOp: ApiOperationRef;
+}
+
+const { spec, refOp } = Astro.props;
+const document = spec.document as GraphqlDocument;
+const type = graphqlTypeDef(document, refOp);
+const routes = graphqlRoutes(spec);
+const operationRoutes = graphqlOperationRoutes(spec);
+
+const usage = type ? graphqlUsage(document, type.name) : { operations: [], types: [] };
+
+// The chip sections a kind can render, empty ones dropped: `possibleTypes`
+// carries a union's members or an interface's implementers, so its heading
+// follows the kind.
+const sections = type
+  ? [
+      {
+        names: type.kind === "union" ? (type.possibleTypes ?? []) : [],
+        title: "Member types",
+      },
+      {
+        names: type.kind === "interface" ? (type.possibleTypes ?? []) : [],
+        title: "Implemented by",
+      },
+      { names: type.interfaces ?? [], title: "Implements" },
+    ].filter((section) => section.names.length > 0)
+  : [];
+
+const SECTION_HEADING = "mb-2 font-semibold text-foreground text-sm";
+---
+
+{
+  !(type) ? (
+    <div class="text-muted-foreground">This GraphQL type could not be found.</div>
+  ) : (
+    <div class="not-prose">
+      <div class="mb-6 flex flex-wrap items-center gap-3">
+        <MethodBadge method={refOp.method} />
+        <code class="break-all font-mono text-foreground text-sm">
+          {type.name}
+        </code>
+      </div>
+      {type.specifiedByUrl && (
+        <div class="mb-4 text-muted-foreground text-sm">
+          Specified by{" "}
+          <a class="text-accent hover:underline" href={type.specifiedByUrl}>
+            {type.specifiedByUrl}
+          </a>
+        </div>
+      )}
+      <GraphqlFieldsTable
+        routes={routes}
+        rows={type.fields ?? []}
+        title="Fields"
+      />
+      <GraphqlFieldsTable
+        routes={routes}
+        rows={type.inputFields ?? []}
+        title="Input fields"
+      />
+      {(type.enumValues ?? []).length > 0 && (
+        <section class="mt-6">
+          <div aria-level="2" class={SECTION_HEADING} role="heading">
+            Values
+          </div>
+          <div class="rounded-blume border border-border px-4">
+            {(type.enumValues ?? []).map((value) => (
+              <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">
+                    {value.name}
+                  </code>
+                  {value.deprecationReason !== undefined && (
+                    <span class="font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide line-through">
+                      deprecated
+                    </span>
+                  )}
+                </div>
+                {value.description && (
+                  <div
+                    class="mt-1 text-muted-foreground text-sm"
+                    set:text={value.description}
+                  />
+                )}
+                {value.deprecationReason && (
+                  <div class="mt-1 text-muted-foreground text-xs">
+                    Deprecated: <span set:text={value.deprecationReason} />
+                  </div>
+                )}
+              </div>
+            ))}
+          </div>
+        </section>
+      )}
+      {sections.map((section) => (
+        <section class="mt-6">
+          <div aria-level="2" class={SECTION_HEADING} role="heading">
+            {section.title}
+          </div>
+          <div class="flex flex-wrap gap-2">
+            {section.names.map((name) => (
+              <GraphqlChip class="text-xs" name={name} route={routes.get(name)} />
+            ))}
+          </div>
+        </section>
+      ))}
+      {(usage.operations.length > 0 || usage.types.length > 0) && (
+        <section class="mt-6">
+          <div aria-level="2" class={SECTION_HEADING} role="heading">
+            Used by
+          </div>
+          <div class="flex flex-wrap items-baseline gap-x-3 gap-y-1">
+            {usage.operations.map((operation) => (
+              <span class="inline-flex items-baseline gap-1 text-xs">
+                <GraphqlChip
+                  class="text-xs"
+                  name={operation.name}
+                  route={operationRoutes.get(
+                    `${operation.kind}:${operation.name}`
+                  )}
+                />
+                <span class="text-muted-foreground">{operation.kind}</span>
+              </span>
+            ))}
+            {usage.types.map((name) => (
+              <GraphqlChip class="text-xs" name={name} route={routes.get(name)} />
+            ))}
+          </div>
+        </section>
+      )}
+    </div>
+  )
+}

package/src/components/openapi/MethodBadge.astro

@@ -1,4 +1,6 @@
 ---
+import { methodColor } from "../colors.ts";
+
 interface Props {
   method: string;
   class?: string;
@@ -6,20 +8,7 @@ interface Props {
 
 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",
-  // AsyncAPI actions.
-  RECEIVE: "bg-teal-500/15 text-teal-700 dark:text-teal-300",
-  SEND: "bg-violet-500/15 text-violet-700 dark:text-violet-300",
-};
-const color = COLORS[upper] ?? "bg-muted text-muted-foreground";
+const color = methodColor(upper);
 ---
 
 <span

package/src/components/openapi/Operation.astro

@@ -14,8 +14,10 @@ import {
   type SecurityRequirementLike,
   type SecuritySchemeLike,
 } from "./security.ts";
+import { DEPRECATED_LABEL_CLASS } from "../colors.ts";
 import { sampleLanguages } from "./snippets.ts";
 import AsyncApiOperation from "./AsyncApiOperation.astro";
+import GraphqlOperation from "./GraphqlOperation.astro";
 import Authorization from "./Authorization.astro";
 import MethodBadge from "./MethodBadge.astro";
 import ParametersTable from "./ParametersTable.astro";
@@ -23,6 +25,7 @@ import Playground from "./Playground.astro";
 import RequestBody from "./RequestBody.astro";
 import RequestPanel from "./RequestPanel.astro";
 import Responses from "./Responses.astro";
+import OperationPanel from "./OperationPanel.astro";
 
 interface Props {
   source: string;
@@ -60,9 +63,11 @@ interface FullOperation {
 const { source, id } = Astro.props;
 const spec = specs[source];
 const ref = spec?.operations[id];
-// The AsyncAPI front-end renders its own body; the lookups below are
-// OpenAPI-shaped (paths, request/response) and resolve to nothing for it.
+// The AsyncAPI and GraphQL front-ends render their own bodies; the lookups
+// below are OpenAPI-shaped (paths, request/response) and resolve to nothing
+// for them.
 const isAsyncApi = spec?.kind === "asyncapi";
+const isGraphql = spec?.kind === "graphql";
 
 const doc = (spec?.document ?? {}) as {
   paths?: Record<
@@ -126,6 +131,8 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
 {
   isAsyncApi ? (
     <AsyncApiOperation id={id} source={source} />
+  ) : isGraphql ? (
+    <GraphqlOperation id={id} source={source} />
   ) : !(spec && ref && operation) ? (
     <div class="text-muted-foreground">This API operation could not be found.</div>
   ) : (
@@ -136,7 +143,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
           {ref.path}
         </code>
         {operation.deprecated && (
-          <span class="font-medium text-[0.625rem] text-orange-600 uppercase tracking-wide dark:text-orange-400">
+          <span class={DEPRECATED_LABEL_CLASS}>
             deprecated
           </span>
         )}
@@ -161,7 +168,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
           )}
         </div>
         {sample && model && (
-          <div class="xl:sticky xl:top-24 xl:self-start" data-operation-panel>
+          <OperationPanel>
             {spec.playground.enabled && (
               <Playground
                 model={model}
@@ -176,7 +183,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
               sample={sample}
               schemas={schemas}
             />
-          </div>
+          </OperationPanel>
         )}
       </div>
     </div>

package/src/components/openapi/OperationPanel.astro

@@ -0,0 +1,43 @@
+---
+/**
+ * The API reference's sample panel: the right-hand column of an operation
+ * page holding the playground and the request/response examples. OpenAPI,
+ * AsyncAPI and GraphQL operation pages share it, so the layout lives here
+ * once. It stays utility classes rather than a theme rule on purpose: an
+ * ejected site freezes its generated app.css but keeps pulling components from
+ * node_modules through its `@source` glob, so utilities survive a blume
+ * upgrade there and a theme rule would not.
+ *
+ * At xl the panel sits beside the docs column and sticks below the 4rem header
+ * with the same 2rem gap the content keeps. It is bounded to the viewport with
+ * its own scroll region: a grid item's sticky containing block is its row, and
+ * the row is as tall as its tallest item, so a long request schema on the left
+ * would otherwise pin the panel with everything below the fold unreachable
+ * until the left column ended. The tradeoff runs the other way when the left
+ * column is the short one — the row is then only as tall as the capped panel
+ * and the overhang is reached by scrolling the panel, not the page. No
+ * overscroll containment, like the sidebar and table of contents: once the
+ * panel reaches its end, wheel input chains to the page. The scrollbar matches
+ * theirs, the end padding keeps it off the Request card's edge, and the stable
+ * gutter stops a bar appearing at the cap ("Try it" opening, a tab switch)
+ * from narrowing the content on classic-scrollbar platforms.
+ *
+ * The 0.25rem inset (`pt-1 ps-1 pb-1`) keeps the global focus ring — 2px
+ * outline, 2px offset — on the first child, the playground's `<summary>` at
+ * the scroller's origin, inside the padding box where it can paint; the
+ * negative margins pull the box back so the content still aligns with the left
+ * column, and the sticky offset (`top-24` less the inset) and the viewport cap
+ * (`7.5rem` less the inset) are adjusted by the same amount. The end side
+ * uses the same trick at 1rem (`-me-4 pe-4`): the box spills into the page
+ * gutter (`<main>` keeps `xl:px-10`), so the scrollbar and the reserved gutter
+ * live there, off the Request card's edge, and with overlay scrollbars the
+ * cards keep the column's full 28rem; a classic bar costs its own width.
+ */
+---
+
+<div
+  class="xl:-ms-1 xl:-mt-1 xl:-me-4 xl:sticky xl:top-[5.75rem] xl:max-h-[calc(100dvh-7.25rem)] xl:overflow-y-auto xl:scrollbar-thin xl:scrollbar-thumb-border xl:scrollbar-track-transparent xl:[scrollbar-gutter:stable] xl:pt-1 xl:ps-1 xl:pb-1 xl:pe-4"
+  data-operation-panel
+>
+  <slot />
+</div>

package/src/components/openapi/RequestPanel.astro

@@ -3,6 +3,7 @@ import data from "blume:data";
 
 import { highlightCode } from "../../markdown/index.ts";
 import { exampleValue, type SchemaLike, toJson } from "./helpers.ts";
+import { languageSamplePanels } from "./sample-panels.ts";
 import PanelTabs from "./PanelTabs.astro";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
 
@@ -25,16 +26,10 @@ interface Props {
 
 const { sample, languages, responses, schemas } = Astro.props;
 
-const requestPanels = await Promise.all(
-  languages.map(async (language) => ({
-    html: await highlightCode(language.build(sample), language.lang, {
-      icons: false,
-      themes: data.config.codeThemes,
-    }),
-    key: language.id,
-    label: language.label,
-    lang: language.id,
-  }))
+const requestPanels = await languageSamplePanels(
+  languages,
+  sample,
+  data.config.codeThemes
 );
 
 const responsePanels = await Promise.all(

package/src/components/openapi/Responses.astro

@@ -1,4 +1,5 @@
 ---
+import { statusColor } from "../colors.ts";
 import type { SchemaLike } from "./helpers.ts";
 import SchemaTable from "./SchemaTable.astro";
 
@@ -19,22 +20,6 @@ interface Props {
 
 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);
 ---