blume 0.6.7 → 0.8.0

package/src/components/layout/Search.astro

@@ -19,7 +19,10 @@ interface Props {
 }
 
 const { askEnabled = false, navigation, strings, locale } = Astro.props;
-const s = strings ?? EN_UI.search;
+// Merge over the English baseline per key (rather than `strings ?? …`) so a
+// partial — or empty `{}` — strings object still resolves every label to a
+// default, matching the pattern PageActions uses for its own dictionary.
+const s = { ...EN_UI.search, ...strings };
 
 // Pages shown in the empty state, before the user has typed anything.
 const popular = navigation ? flattenPages(navigation.sidebar).slice(0, 6) : [];
@@ -30,8 +33,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 <blume-search
   class="contents"
   data-ask={askEnabled ? "" : undefined}
+  data-i18n-ask={s.askAi}
+  data-i18n-ask-hint={s.askAiHint}
   data-i18n-dev={s.devOnly}
   data-i18n-empty={s.noResults}
+  data-i18n-error={s.error}
+  data-i18n-popular={s.popular}
+  data-i18n-results={s.results}
   data-locale={locale || undefined}
 >
   <button
@@ -59,7 +67,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       <input
         aria-label={s.label}
         autocomplete="off"
-        class="flex-1 border-0 bg-transparent text-foreground text-sm focus:outline-none [&::-webkit-search-cancel-button]:appearance-none"
+        class="flex-1 border-0 bg-transparent text-foreground text-sm pointer-coarse:text-base focus:outline-none [&::-webkit-search-cancel-button]:appearance-none"
         data-blume-search-input
         placeholder={s.placeholder}
         type="search"
@@ -116,15 +124,17 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         <span class="flex items-center gap-1">
           <kbd class={`${kbd} text-[0.65rem]`}>↑</kbd>
           <kbd class={`${kbd} text-[0.65rem]`}>↓</kbd>
-          navigate
+          {s.navigate}
         </span>
         <span class="flex items-center gap-1">
           <kbd class={`${kbd} text-[0.65rem]`}>↵</kbd>
-          open
+          {s.open}
         </span>
         <span class="flex items-center gap-1 max-md:hidden">
-          <kbd class={`${kbd} text-[0.65rem]`}>⌘J</kbd>
-          preview
+          <kbd class={`${kbd} text-[0.65rem]`} data-blume-search-preview-kbd
+            >⌘J</kbd
+          >
+          {s.preview}
         </span>
       </div>
     </div>
@@ -139,6 +149,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
   <script>
     import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
+    import { prefixBase } from "../islands/base-path.ts";
     import {
       escapeHtml,
       highlight,
@@ -185,6 +196,9 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       preview!: HTMLElement;
       searchFn: SearchFn | null = null;
       loaded = false;
+      loadFailed = false;
+      /** First-open client/index load still in flight. */
+      loading = false;
       askEnabled = false;
       popular: PopularPage[] = [];
       selectables: Selectable[] = [];
@@ -194,6 +208,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       previewOn = true;
       devOnlyMsg = "Search is available in the production build.";
       noResultsMsg = "No results found.";
+      errorMsg = "Something went wrong. Please try again.";
+      askMsg = "Ask AI";
+      askHintMsg = "Get an instant answer from AI";
+      popularMsg = "Popular";
+      resultsMsg = "Results";
       // The active locale to filter to (null when i18n is off), and whether the
       // reader has opted to search across every language instead.
       locale: string | null = null;
@@ -204,6 +223,14 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           this.getAttribute("data-i18n-dev") || this.devOnlyMsg;
         this.noResultsMsg =
           this.getAttribute("data-i18n-empty") || this.noResultsMsg;
+        this.errorMsg = this.getAttribute("data-i18n-error") || this.errorMsg;
+        this.askMsg = this.getAttribute("data-i18n-ask") || this.askMsg;
+        this.askHintMsg =
+          this.getAttribute("data-i18n-ask-hint") || this.askHintMsg;
+        this.popularMsg =
+          this.getAttribute("data-i18n-popular") || this.popularMsg;
+        this.resultsMsg =
+          this.getAttribute("data-i18n-results") || this.resultsMsg;
         this.locale = this.getAttribute("data-locale");
         this.dialog = this.querySelector("[data-blume-search-dialog]")!;
         this.input = this.querySelector("[data-blume-search-input]")!;
@@ -246,12 +273,18 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           });
         }
 
-        // The handler accepts ⌘K and Ctrl+K; show the right one per platform.
+        // The handlers accept both ⌘ and Ctrl chords; show the right modifier
+        // per platform on the button hint and the footer's preview hint.
+        const isApple = /mac|iphone|ipad|ipod/iu.test(navigator.platform);
         const hint = this.querySelector("[data-blume-search-kbd]");
         if (hint) {
-          hint.textContent = /mac|iphone|ipad|ipod/iu.test(navigator.platform)
-            ? "⌘K"
-            : "Ctrl K";
+          hint.textContent = isApple ? "⌘K" : "Ctrl K";
+        }
+        const previewHint = this.querySelector(
+          "[data-blume-search-preview-kbd]"
+        );
+        if (previewHint) {
+          previewHint.textContent = isApple ? "⌘J" : "Ctrl J";
         }
 
         this.querySelector("[data-blume-search-open]")?.addEventListener(
@@ -297,6 +330,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.input.focus();
         this.input.select();
         if (!this.loaded) {
+          this.loading = true;
           try {
             const { createSearch } = await import("blume:search-client");
             this.searchFn = await createSearch();
@@ -304,8 +338,15 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
             // fetching the index) must retry on the next open, not disable
             // search until a full page reload.
             this.loaded = true;
+            this.loadFailed = false;
           } catch {
             this.searchFn = null;
+            // In dev a client can be missing by design (Pagefind's bundle
+            // only exists in the production build) — that's the "dev only"
+            // hint. The same failure in production is a real error.
+            this.loadFailed = !import.meta.env.DEV;
+          } finally {
+            this.loading = false;
           }
         }
         this.render();
@@ -318,7 +359,9 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         } else if (event.key === "ArrowUp") {
           event.preventDefault();
           this.move(-1);
-        } else if (event.key === "Enter") {
+        } else if (event.key === "Enter" && !event.isComposing) {
+          // `isComposing` guards IME input: Enter confirming a CJK conversion
+          // must commit the text, not activate the selected result.
           const item = this.selectables[this.selectedIndex];
           if (item) {
             event.preventDefault();
@@ -357,16 +400,36 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         if (!this.searchFn) {
           this.renderFilters([]);
           this.clearPreview();
-          this.setMessage(this.devOnlyMsg);
+          if (this.loading) {
+            // Typing while the first-open load (client import + index fetch)
+            // is still in flight: the dev-only hint would be wrong in
+            // production and the error message premature. Show a neutral
+            // placeholder; `open()` re-renders once the load settles.
+            this.setMessage("…");
+          } else {
+            this.setMessage(this.loadFailed ? this.errorMsg : this.devOnlyMsg);
+          }
           return;
         }
 
         const localeFilter =
           this.locale && !this.allLocales ? this.locale : undefined;
-        const result = await this.searchFn(query, {
-          locale: localeFilter,
-          section: this.activeSection ?? undefined,
-        });
+        let result: Awaited<ReturnType<SearchFn>>;
+        try {
+          result = await this.searchFn(query, {
+            locale: localeFilter,
+            section: this.activeSection ?? undefined,
+          });
+        } catch {
+          // A hosted provider can reject (network error, outage); the results
+          // list is already cleared, so show a message instead of a blank pane.
+          if (generation === this.renderGeneration) {
+            this.renderFilters([]);
+            this.clearPreview();
+            this.setMessage(this.errorMsg);
+          }
+          return;
+        }
         // Any newer render — a keystroke, a section pill, a locale toggle —
         // supersedes this one mid-await, even for the same query text;
         // appending the stale hits would duplicate rows and desync selection.
@@ -374,17 +437,30 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           return;
         }
 
+        // A section picked for an earlier query can be missing from the new
+        // pool — and when the pool has fewer than two sections the pills that
+        // would clear it are hidden too, so the stale filter would silently
+        // empty the results. Drop it and search again unfiltered.
+        if (
+          this.activeSection &&
+          !result.sections.some((s) => s.label === this.activeSection)
+        ) {
+          this.activeSection = null;
+          this.render();
+          return;
+        }
+
         this.renderFilters(result.sections);
 
         if (this.askEnabled) {
-          const group = this.addGroup("Ask AI");
+          const group = this.addGroup(this.askMsg);
           const ask = this.createAskRow(query);
           group.appendChild(ask.el);
           this.selectables.push(ask);
         }
 
         if (result.hits.length > 0) {
-          const group = this.addGroup("Results");
+          const group = this.addGroup(this.resultsMsg);
           for (const hit of result.hits) {
             const item = this.createHitRow(hit, query);
             group.appendChild(item.el);
@@ -399,13 +475,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
       renderEmpty() {
         if (this.askEnabled) {
-          const group = this.addGroup("Ask AI");
+          const group = this.addGroup(this.askMsg);
           const ask = this.createAskRow("");
           group.appendChild(ask.el);
           this.selectables.push(ask);
         }
         if (this.popular.length > 0) {
-          const group = this.addGroup("Popular");
+          const group = this.addGroup(this.popularMsg);
           for (const page of this.popular) {
             const item = this.createLinkRow(page.route, page.label);
             group.appendChild(item.el);
@@ -460,13 +536,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         el.type = "button";
         el.className = `${ROW_CLASS} ${MARK}`;
         const title = query
-          ? `Ask AI: <span class="text-muted-foreground">“${escapeHtml(query)}”</span>`
-          : "Ask AI";
+          ? `${escapeHtml(this.askMsg)}: <span class="text-muted-foreground">“${escapeHtml(query)}”</span>`
+          : escapeHtml(this.askMsg);
         el.innerHTML = `
           <span class="mt-0.5 shrink-0 text-accent">${svg("sparkles")}</span>
           <span class="flex-1">
             <span class="block truncate font-normal text-foreground text-sm">${title}</span>
-            <span class="block truncate text-muted-foreground text-sm">Get an instant answer from AI</span>
+            <span class="block truncate text-muted-foreground text-sm">${escapeHtml(this.askHintMsg)}</span>
           </span>`;
         const item: Selectable = { el, kind: "ask" };
         this.bindRow(item);
@@ -475,7 +551,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
       createHitRow(hit: SearchHit, query: string): Selectable {
         const el = document.createElement("a");
-        el.href = hit.url;
+        // Index URLs are base-less logical routes; prefix the deployment base so
+        // clicking a result lands on the page's real served URL.
+        const href = prefixBase(import.meta.env.BASE_URL, hit.url);
+        el.href = href;
         el.className = `${ROW_CLASS} ${MARK}`;
         // `line-clamp-2` already sets `display`, so no `block` here (it would
         // override the clamp and let the excerpt run to full height).
@@ -488,21 +567,22 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
             <span class="block truncate font-normal text-foreground text-sm">${hit.title}</span>
             ${excerpt}
           </span>`;
-        const item: Selectable = { el, hit, kind: "link", url: hit.url };
+        const item: Selectable = { el, hit, kind: "link", url: href };
         this.bindRow(item);
         return item;
       }
 
       createLinkRow(url: string, label: string): Selectable {
         const el = document.createElement("a");
-        el.href = url;
+        const href = prefixBase(import.meta.env.BASE_URL, url);
+        el.href = href;
         el.className = ROW_CLASS;
         el.innerHTML = `
           <span class="mt-0.5 shrink-0 text-muted-foreground">${svg("file")}</span>
           <span class="flex-1">
             <span class="block truncate font-normal text-foreground text-sm">${escapeHtml(label)}</span>
           </span>`;
-        const item: Selectable = { el, kind: "link", url };
+        const item: Selectable = { el, kind: "link", url: href };
         this.bindRow(item);
         return item;
       }

package/src/components/layout/nav-utils.ts

@@ -119,10 +119,14 @@ const sectionChildren = (nodes: NavNode[], base: string): NavNode[] | null => {
 };
 
 /** Whether a group maps to a header tab (matched on its path or link route). */
-const isTabSection = (node: NavNode, tabPaths: Set<string>): boolean =>
-  node.kind === "group" &&
-  ((node.path !== undefined && tabPaths.has(node.path)) ||
-    (node.route !== undefined && tabPaths.has(node.route)));
+const isTabSection = (node: NavNode, tabPaths: Set<string>): boolean => {
+  if (node.kind !== "group") {
+    return false;
+  }
+  const byPath = node.path !== undefined && tabPaths.has(node.path);
+  const byRoute = node.route !== undefined && tabPaths.has(node.route);
+  return byPath || byRoute;
+};
 
 /**
  * Drop the groups that already own a header tab from the tree, at any depth —
@@ -132,9 +136,12 @@ const isTabSection = (node: NavNode, tabPaths: Set<string>): boolean =>
  * (`/`) spans everything, so it never removes anything.
  */
 const withoutTabSections = (nodes: NavNode[], tabs: NavTab[]): NavNode[] => {
-  const tabPaths = new Set(
-    tabs.filter((tab) => tab.path !== "/").map((tab) => tab.path)
-  );
+  const tabPaths = new Set<string>();
+  for (const tab of tabs) {
+    if (tab.path !== "/") {
+      tabPaths.add(tab.path);
+    }
+  }
   if (tabPaths.size === 0) {
     return nodes;
   }
@@ -145,11 +152,12 @@ const withoutTabSections = (nodes: NavNode[], tabs: NavTab[]): NavNode[] => {
         continue;
       }
       if (item.kind === "group") {
+        // A container left empty by pruning is dropped, so no bare heading is
+        // stranded.
         const children = prune(item.children);
-        if (children.length === 0) {
-          continue;
+        if (children.length > 0) {
+          kept.push({ ...item, children });
         }
-        kept.push({ ...item, children });
       } else {
         kept.push(item);
       }

package/src/components/layout/search/algolia.ts

@@ -20,10 +20,19 @@ export const createSearch = (opts: {
   searchApiKey: string;
 }): SearchFn => {
   const client = liteClient(opts.appId, opts.searchApiKey);
-  return async (query) => {
+  return async (query, options) => {
     const { results } = await client.search<AlgoliaRecord>({
       requests: [
-        { hitsPerPage: SEARCH_LIMIT, indexName: opts.indexName, query },
+        {
+          hitsPerPage: SEARCH_LIMIT,
+          indexName: opts.indexName,
+          query,
+          // The sync uploads `locale` on every record so an i18n site can
+          // scope hosted results to the active language.
+          ...(options?.locale && {
+            facetFilters: [`locale:${options.locale}`],
+          }),
+        },
       ],
     });
     const [first] = results;

package/src/components/layout/search/endpoint.ts

@@ -1,10 +1,11 @@
-import { SEARCH_LIMIT } from "./types.ts";
+import { highlight, SEARCH_LIMIT } from "./types.ts";
 import type { SearchFn, SearchHit } from "./types.ts";
 
 /**
  * Server-proxied search (Mixedbread): POST the query to a generated endpoint
- * that holds the secret key and talks to the service, then renders the
- * already-shaped hits it returns.
+ * that holds the secret key and talks to the service. The returned hits carry
+ * service-derived text and the dialog injects title/excerpt as HTML, so both
+ * are escaped (and query matches marked) here, like every other provider.
  */
 export const createSearch =
   (opts: { api: string }): SearchFn =>
@@ -17,6 +18,11 @@ export const createSearch =
     if (!response.ok) {
       return { hits: [], sections: [] };
     }
-    const hits = (await response.json()) as SearchHit[];
-    return { hits: hits.slice(0, SEARCH_LIMIT), sections: [] };
+    const records = (await response.json()) as SearchHit[];
+    const hits = records.slice(0, SEARCH_LIMIT).map((hit) => ({
+      ...hit,
+      excerpt: highlight(hit.excerpt, query),
+      title: highlight(hit.title, query),
+    }));
+    return { hits, sections: [] };
   };

package/src/components/layout/search/orama-cloud.ts

@@ -22,8 +22,14 @@ export const createSearch = (opts: {
     api_key: opts.apiKey,
     endpoint: opts.endpoint,
   });
-  return async (query) => {
-    const results = await client.search({ limit: SEARCH_LIMIT, term: query });
+  return async (query, options) => {
+    const results = await client.search({
+      limit: SEARCH_LIMIT,
+      term: query,
+      // The sync carries `locale` on every record so an i18n site can scope
+      // hosted results to the active language.
+      ...(options?.locale && { where: { locale: options.locale } }),
+    });
     const hits = (results?.hits ?? []).map((hit) => {
       const doc = hit.document as unknown as OramaCloudRecord;
       return {

package/src/components/layout/search/pagefind.ts

@@ -21,6 +21,9 @@ interface PagefindModule {
 export const createSearch = async (opts: {
   url: string;
 }): Promise<SearchFn> => {
+  // The pagefind bundle lives in the built site (not node_modules) and is
+  // resolved at runtime by URL — it can't be a static, code-splittable path.
+  // oxlint-disable-next-line react-doctor/no-dynamic-import-path
   const pagefind = (await import(
     /* @vite-ignore */
     opts.url

package/src/components/layout/search/types.ts

@@ -134,7 +134,11 @@ export const excerptFor = (
   if (query && matchIndex(content, query) >= 0) {
     return matchSnippet(content, query, 160);
   }
-  return description || `${content.slice(0, 140)}…`;
+  if (description) {
+    return description;
+  }
+  const head = content.slice(0, 140);
+  return head.length < content.length ? `${head}…` : head;
 };
 
 /** Tally how many matches fall into each section, in first-seen order. */

package/src/components/layout/search/typesense.ts

@@ -31,7 +31,7 @@ export const createSearch = (opts: {
       },
     ],
   });
-  return async (query) => {
+  return async (query, options) => {
     const response = await client
       .collections<TypesenseRecord>(opts.collection)
       .documents()
@@ -40,6 +40,9 @@ export const createSearch = (opts: {
           per_page: SEARCH_LIMIT,
           q: query,
           query_by: "title,description,content",
+          // The sync marks `locale` as a facet so an i18n site can scope
+          // hosted results to the active language.
+          ...(options?.locale && { filter_by: `locale:=${options.locale}` }),
         },
         {}
       );

package/src/components/layout/toc-element.ts

@@ -1,5 +1,5 @@
 /**
- * Client behaviour for the `<blume-toc>` custom element wrapping each "On this
+ * Client behavior for the `<blume-toc>` custom element wrapping each "On this
  * page" list. As the reader scrolls, it marks the link for the section currently
  * in view with `aria-current="location"` — styled via Tailwind `aria-[current]`
  * variants in RootLayout — giving the table of contents a live scrollspy.
@@ -52,7 +52,13 @@ class BlumeToc extends HTMLElement {
     for (const { heading } of this.#entries) {
       this.#observer.observe(heading);
     }
-    window.addEventListener("scroll", this.#onScroll, { passive: true });
+    // The scroll listener is the intentional fallback for the one case the
+    // IntersectionObserver can't cover (a final section too short to push its
+    // heading past the trigger line), so replacing it with an observer would
+    // change behavior. `scroll` isn't cancelable, so it never preventDefaults
+    // and `{ passive: true }` would be a no-op here.
+    // oxlint-disable-next-line github/prefer-observers, react-doctor/client-passive-event-listeners
+    window.addEventListener("scroll", this.#onScroll);
     this.#update();
   }
 

package/src/components/openapi/ApiTagOperations.astro

@@ -1,5 +1,6 @@
 ---
 import specs from "blume:openapi";
+import { withBase } from "../islands/base-path.ts";
 import MethodBadge from "./MethodBadge.astro";
 
 // The operation-link list for one tag section of an API overview page. The
@@ -25,7 +26,7 @@ const operations = Object.values(specs[source]?.operations ?? {}).filter(
         <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}
+            href={withBase(operation.route)}
           >
             <MethodBadge method={operation.method} />
             <span class="font-medium text-foreground text-sm">

package/src/components/openapi/Operation.astro

@@ -1,6 +1,11 @@
 ---
 import specs from "blume:openapi";
-import type { SchemaLike } from "./helpers.ts";
+import {
+  mergeParameters,
+  type ParameterLike,
+  resolveComponentRef,
+  type SchemaLike,
+} from "./helpers.ts";
 import { buildRequestSample, sampleLanguages } from "./snippets.ts";
 import MethodBadge from "./MethodBadge.astro";
 import ParametersTable from "./ParametersTable.astro";
@@ -13,36 +18,31 @@ interface Props {
   id: string;
 }
 
-interface ParamLike {
+interface MediaTypeLike {
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+interface RequestBodyLike {
   $ref?: string;
-  name?: string;
-  in?: string;
   description?: string;
   required?: boolean;
-  deprecated?: boolean;
-  schema?: SchemaLike;
-  example?: unknown;
+  content?: Record<string, MediaTypeLike>;
 }
 
-interface MediaTypeLike {
-  schema?: SchemaLike;
-  example?: unknown;
+interface ResponseLike {
+  $ref?: string;
+  description?: string;
+  content?: Record<string, MediaTypeLike>;
 }
 
 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> }
-  >;
+  parameters?: ParameterLike[];
+  requestBody?: RequestBodyLike;
+  responses?: Record<string, ResponseLike>;
 }
 
 const { source, id } = Astro.props;
@@ -50,10 +50,15 @@ const spec = specs[source];
 const ref = spec?.operations[id];
 
 const doc = (spec?.document ?? {}) as {
-  paths?: Record<string, Record<string, unknown> & { parameters?: ParamLike[] }>;
+  paths?: Record<
+    string,
+    Record<string, unknown> & { parameters?: ParameterLike[] }
+  >;
   components?: {
     schemas?: Record<string, SchemaLike>;
-    parameters?: Record<string, ParamLike>;
+    parameters?: Record<string, ParameterLike>;
+    requestBodies?: Record<string, RequestBodyLike>;
+    responses?: Record<string, ResponseLike>;
   };
   servers?: { url?: string }[];
 };
@@ -63,24 +68,26 @@ const operation = (
 ) 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 components = doc.components ?? {};
+const params = mergeParameters(
+  pathItem?.parameters,
+  operation?.parameters,
+  components
+);
+const requestBody = operation?.requestBody
+  ? resolveComponentRef(operation.requestBody, components, "requestBodies")
+  : undefined;
+const responses = Object.fromEntries(
+  Object.entries(operation?.responses ?? {}).map(([status, response]) => [
+    status,
+    resolveComponentRef(response, components, "responses"),
+  ])
+);
 
 const sample =
   ref && operation
     ? buildRequestSample(
-        { parameters: params, requestBody: operation.requestBody },
+        { parameters: params, requestBody },
         ref.method,
         ref.path,
         doc.servers ?? [],
@@ -109,17 +116,17 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
       <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 && (
             <RequestBody
               expandAll={spec.expandSchemas}
-              requestBody={operation.requestBody}
+              requestBody={requestBody}
               schemas={schemas}
             />
           )}
           {operation.responses && (
             <Responses
               expandAll={spec.expandSchemas}
-              responses={operation.responses}
+              responses={responses}
               schemas={schemas}
             />
           )}
@@ -128,7 +135,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
           <div class="xl:sticky xl:top-24 xl:self-start">
             <RequestPanel
               languages={languages}
-              responses={operation.responses ?? {}}
+              responses={responses}
               sample={sample}
               schemas={schemas}
             />