blume 1.6.2 → 1.6.4

package/src/components/content/example-pane.ts

@@ -0,0 +1,6 @@
+/**
+ * Floor for a `<Component>` preview pane, in CSS pixels. Shared between the
+ * server-side line-count estimate and the client script that applies the
+ * frame's measured height, so the two can't drift.
+ */
+export const EXAMPLE_PANE_MIN_PX = 288;

package/src/components/layout/LocaleLinks.astro

@@ -0,0 +1,42 @@
+---
+import data from "blume:data";
+
+import { normalizeBasePath } from "../../core/base-path.ts";
+import { localePrefix } from "../../core/i18n.ts";
+import {
+  localizeContentLinks,
+  localizeHref,
+  routeSetFor,
+} from "../../core/locale-links.ts";
+
+/**
+ * Keep a translated page's content links inside the reader's locale. Content
+ * is compiled once per file, so its `<a href>`s point at the default locale's
+ * routes; rendered under `/fr/…` (a real translation, a fallback page, or a
+ * shared `page.$.mdx`), each root-relative page link moves to `/fr/…` when
+ * that route is served, and keeps its authored target otherwise. Default-locale
+ * pages (no prefix) and single-locale sites pass the slot through untouched.
+ */
+interface Props {
+  /** Locale of the route being rendered — a fallback route's own, not its content's. */
+  locale: string;
+}
+
+const { locale } = Astro.props;
+const i18n = data.config.i18n;
+
+const html =
+  i18n && localePrefix(locale, i18n) !== ""
+    ? localizeContentLinks(await Astro.slots.render("default"), (href) =>
+        localizeHref(href, {
+          basePath: data.config.basePath,
+          deployBase: normalizeBasePath(import.meta.env.BASE_URL),
+          i18n,
+          locale,
+          routes: routeSetFor(data.routes),
+        })
+      )
+    : null;
+---
+
+{html === null ? <slot /> : <Fragment set:html={html} />}

package/src/components/layout/PageLayout.astro

@@ -35,6 +35,7 @@ import {
 import { buildStructuredData } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
+import { searchLocaleFor } from "./search-locale.ts";
 import "blume:theme";
 import { ClientRouter } from "astro:transitions";
 import Analytics from "./Analytics.astro";
@@ -160,9 +161,10 @@ const strings = ui ?? EN_UI;
 // from a not-yet-regenerated snapshot) still renders instead of coming out
 // blank — the PageActions pattern.
 const navStrings = { ...EN_UI.nav, ...strings.nav };
-// Filter search to the active language only when the site is multi-locale.
-const searchLocale =
-  localeSwitch && localeSwitch.length > 1 ? locale : undefined;
+// Scope search to the active language on a multi-locale site. Read from the
+// i18n snapshot, not the switcher list, so pages rendered without one still
+// filter (see `searchLocaleFor`).
+const searchLocale = searchLocaleFor(data.config.i18n, locale);
 const pageTitle = page?.title ?? site.title;
 const description = page?.description ?? site.description;
 const route = page?.route ?? "/";

package/src/components/layout/ReferenceLayout.astro

@@ -1,5 +1,6 @@
 ---
 import "blume:theme";
+import data from "blume:data";
 import type { BlumeFavicon } from "../../core/data.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
@@ -16,6 +17,7 @@ import {
   THEME_INIT_SCRIPT,
 } from "./head-scripts.ts";
 import Header from "./Header.astro";
+import { searchLocaleFor } from "./search-locale.ts";
 
 // A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
 // on top, then a full-height region the reference mounts into. Unlike RootLayout
@@ -91,6 +93,8 @@ const {
 } = Astro.props;
 
 const strings = ui ?? EN_UI;
+// Scope search to the reference page's language on a multi-locale site.
+const searchLocale = searchLocaleFor(data.config.i18n, locale);
 
 const bannerKey = banner?.dismissible ? banner.key : null;
 ---
@@ -126,6 +130,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       navigation={navigation}
       route={route}
       searchEnabled={searchEnabled}
+      searchLocale={searchLocale}
       site={site}
     />
     <div

package/src/components/layout/RootLayout.astro

@@ -58,6 +58,7 @@ import {
 } from "./nav-utils.ts";
 import NavTree from "./NavTree.astro";
 import { resolveSlot } from "./overrides.ts";
+import { searchLocaleFor } from "./search-locale.ts";
 import PageActions from "./PageActions.astro";
 import PageFeedback from "./PageFeedback.astro";
 import Pagination from "./Pagination.astro";
@@ -289,9 +290,10 @@ const strings = ui ?? EN_UI;
 const navStrings = { ...EN_UI.nav, ...strings.nav };
 const actionStrings = { ...EN_UI.actions, ...strings.actions };
 const contentStrings = { ...EN_UI.content, ...strings.content };
-// Filter search to the active language only when the site is multi-locale.
-const searchLocale =
-  localeSwitch && localeSwitch.length > 1 ? locale : undefined;
+// Scope search to the active language on a multi-locale site. Read from the
+// i18n snapshot, not the switcher list, so pages rendered without one still
+// filter (see `searchLocaleFor`).
+const searchLocale = searchLocaleFor(data.config.i18n, locale);
 // TOC entries: the configured heading range, or none when the TOC is disabled
 // (an empty list makes TableOfContents render nothing).
 // API operation pages own a two-column body (docs + request panel) and their own
@@ -798,9 +800,55 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       // Opaque icon chip over the code (in the style of Lina's code block),
       // with the check icon scale-swapping in over the copy icon after a copy.
       const buttonClass =
-        "absolute right-3 z-[2] inline-flex size-[1.875rem] select-none items-center justify-center rounded-md text-muted-foreground bg-background transition-colors [&_svg]:pointer-events-none [&_svg]:shrink-0";
+        "inline-flex size-[1.875rem] select-none items-center justify-center rounded-md text-muted-foreground bg-background transition-colors [&_svg]:pointer-events-none [&_svg]:shrink-0";
+      // Pinned over the block's top-right corner when the button lives in
+      // the pre; a strip-hosted button (see codeGroupActions) is in flow.
+      const overlayClass = "absolute right-3 z-[2]";
       const idleClasses = ["hover:bg-muted", "hover:text-foreground"];
 
+      // A tab panel that is nothing but code: a CodeGroup/ts2js block (the
+      // pre is the panel) or a <Tab> holding only fences and the icon
+      // template — the same predicate Tab.astro's flush-padding selector uses.
+      const isCodePanel = (panel: Element) =>
+        panel.matches("pre, figure") ||
+        (panel.matches("[data-blume-tab-panel]") &&
+          panel.querySelector(":scope > pre") !== null &&
+          Array.from(panel.children).every((child) =>
+            child.matches("pre, template")
+          ));
+
+      // The tab group's actions slot, when the group is a code switcher —
+      // every panel a bare block — so one copy button in the strip serves
+      // whichever panel is showing. A group with prose panels (or none) gets
+      // null and keeps a button in each pre.
+      const codeGroupActions = (pre: Element) => {
+        const tabs = pre.closest("blume-tabs");
+        const content = tabs?.querySelector(":scope > [data-blume-tab-content]");
+        const panels = content ? Array.from(content.children) : [];
+        if (!tabs || panels.length === 0 || !panels.every(isCodePanel)) {
+          return null;
+        }
+        return tabs.querySelector<HTMLElement>(
+          ":scope > * > [data-blume-tab-actions]"
+        );
+      };
+
+      // The block the strip's copy button should read: the visible panel's
+      // pre. Panels toggle a `hidden` class once the tabs element upgrades;
+      // before that only the first is painted, and it is also the first
+      // match here.
+      const activeCodePre = (tabs: Element) => {
+        const content = tabs.querySelector(":scope > [data-blume-tab-content]");
+        const panel =
+          Array.from(content?.children ?? []).find(
+            (child) => !child.classList.contains("hidden")
+          ) ?? content?.firstElementChild;
+        if (!panel) {
+          return null;
+        }
+        return panel.matches("pre") ? panel : panel.querySelector("pre");
+      };
+
       const languageLabels: Record<string, string> = {
         astro: "Astro",
         bash: "Bash",
@@ -836,41 +884,16 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         const copiedLabel =
           document.body.getAttribute("data-i18n-copied") || "Copied!";
 
-        for (const pre of document.querySelectorAll(".prose pre")) {
-          if (pre.querySelector("[data-blume-copy]")) {
-            continue;
-          }
-          // Skip nested <pre>: Twoslash renders each hover popup's type signature
-          // as a <pre> inside the code block, which shouldn't get its own button.
-          if (pre.parentElement?.closest("pre")) {
-            continue;
-          }
-          const language = pre.getAttribute("data-language");
-          if (language) {
-            pre.setAttribute(
-              "data-language",
-              languageLabels[language.toLowerCase()] ?? language
-            );
-          }
-          pre.classList.add("group", "relative");
-          // The code element is the scroll container (see the theme entry), but
-          // Shiki's tab stop lands on the pre, which no longer scrolls. Move the
-          // stop to the code so keyboard users can actually scroll the block
-          // (WCAG 2.1.1 — the same rule the table wrapper handles). Twoslash and
-          // API-panel blocks keep the pre as their scroller, so theirs stays.
-          const scroller = pre.querySelector("code");
-          if (scroller && !pre.matches(".twoslash, blume-panel-tabs *")) {
-            scroller.setAttribute("tabindex", "0");
-            pre.removeAttribute("tabindex");
-          }
+        // `placement` is the extra class set for an overlay button (empty for
+        // one hosted by a tab strip); `readPre` resolves the block to copy at
+        // click time, since a strip button follows the active panel.
+        const createCopyButton = (
+          placement: string,
+          readPre: () => Element | null
+        ) => {
           const button = document.createElement("button");
           button.type = "button";
-          // The language-label bar (prose) vs flush code (tabs) need a different
-          // offset; pick the Tailwind class by context instead of a CSS override.
-          const topClass = pre.closest("blume-tabs, .not-prose")
-            ? "top-2.5"
-            : "top-2";
-          button.className = `${buttonClass} ${idleClasses.join(" ")} ${topClass}`;
+          button.className = `${buttonClass} ${idleClasses.join(" ")} ${placement}`;
           button.setAttribute("data-blume-copy", "");
           button.setAttribute("aria-label", copyCodeLabel);
           button.innerHTML =
@@ -896,7 +919,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
           };
           const flash = createCopyFlash(setChecked, copiedLabel);
           button.addEventListener("click", async () => {
-            const code = pre.querySelector("code");
+            const code = readPre()?.querySelector("code");
             let text = code?.textContent ?? "";
             // Twoslash nests each hover popup's type signature and docs inside
             // the <code>; copying textContent verbatim would interleave them
@@ -914,7 +937,55 @@ const bannerKey = banner?.dismissible ? banner.key : null;
               flash();
             }
           });
-          pre.appendChild(button);
+          return button;
+        };
+
+        for (const pre of document.querySelectorAll(".prose pre")) {
+          if (pre.querySelector("[data-blume-copy]")) {
+            continue;
+          }
+          // Skip nested <pre>: Twoslash renders each hover popup's type signature
+          // as a <pre> inside the code block, which shouldn't get its own button.
+          if (pre.parentElement?.closest("pre")) {
+            continue;
+          }
+          const language = pre.getAttribute("data-language");
+          if (language) {
+            pre.setAttribute(
+              "data-language",
+              languageLabels[language.toLowerCase()] ?? language
+            );
+          }
+          pre.classList.add("group", "relative");
+          // The code element is the scroll container (see the theme entry), but
+          // Shiki's tab stop lands on the pre, which no longer scrolls. Move the
+          // stop to the code so keyboard users can actually scroll the block
+          // (WCAG 2.1.1 — the same rule the table wrapper handles). Twoslash and
+          // API-panel blocks keep the pre as their scroller, so theirs stays.
+          const scroller = pre.querySelector("code");
+          if (scroller && !pre.matches(".twoslash, blume-panel-tabs *")) {
+            scroller.setAttribute("tabindex", "0");
+            pre.removeAttribute("tabindex");
+          }
+          const actions = codeGroupActions(pre);
+          if (actions) {
+            // One button per code switcher, reading whichever panel shows.
+            if (!actions.querySelector("[data-blume-copy]")) {
+              const tabs = actions.closest("blume-tabs");
+              actions.appendChild(
+                createCopyButton("", () => (tabs ? activeCodePre(tabs) : null))
+              );
+            }
+            continue;
+          }
+          // The language-label bar (prose) vs flush code (tabs) need a different
+          // offset; pick the Tailwind class by context instead of a CSS override.
+          const topClass = pre.closest("blume-tabs, .not-prose")
+            ? "top-2.5"
+            : "top-2";
+          pre.appendChild(
+            createCopyButton(`${overlayClass} ${topClass}`, () => pre)
+          );
         }
 
         // Click-to-zoom for content images (gated by `markdown.imageZoom`),

package/src/components/layout/search-locale.ts

@@ -0,0 +1,13 @@
+/**
+ * The locale the search dialog should scope to, or `undefined` when scoping
+ * is pointless. Derived from the resolved i18n settings rather than from the
+ * header's language-switcher entries: the switcher list is only assembled by
+ * the content catch-all, so pages rendered without one (custom pages built on
+ * `PageLayout`, the changelog index, the 404 page, the API reference shell)
+ * would otherwise search every language while showing no "All languages"
+ * toggle. A single-locale site (or one without i18n) has nothing to scope.
+ */
+export const searchLocaleFor = (
+  i18n: { locales: { code: string }[] } | null,
+  locale: string
+): string | undefined => (i18n && i18n.locales.length > 1 ? locale : undefined);

package/src/components/openapi/ApiOverview.astro

@@ -1,54 +1,22 @@
 ---
 import specs from "blume:openapi";
 
-import type { AsyncApiDocument } from "../../openapi/asyncapi.ts";
+import { specAddresses, specOf } from "../../openapi/model.ts";
 
 // The spec-level metadata block (version + base URLs) at the top of an API
 // overview page. The tag sections that follow are emitted by `overviewMdx` as
 // markdown headings plus `<ApiTagOperations>` lists, so they land in the
-// table of contents.
+// table of contents. The agent surfaces downlevel this block from the same
+// `specAddresses`, so the `.md` page lists what this one shows.
 interface Props {
   source: string;
 }
 
 const { source } = Astro.props;
-const spec = specs[source];
-
-// OpenAPI declares `servers` as an array of URLs; AsyncAPI as a named map of
-// host/protocol/pathname; a GraphQL schema names no server, so its configured
-// live endpoint stands in. All flatten into one list of address chips.
-const addresses: string[] = [];
-if (spec?.kind === "graphql") {
-  if (spec.endpoint) {
-    addresses.push(spec.endpoint);
-  }
-} else if (spec?.kind === "asyncapi") {
-  const servers = (spec.document as AsyncApiDocument).servers ?? {};
-  for (const server of Object.values(servers)) {
-    if (server?.host) {
-      addresses.push(
-        `${server.protocol ? `${server.protocol}://` : ""}${server.host}${server.pathname ?? ""}`
-      );
-    }
-  }
-} else {
-  // Hand-written specs sometimes declare `servers` as a bare object; degrade
-  // to no address chips instead of throwing mid-build.
-  const declared = ((spec?.document ?? {}) as { servers?: { url?: string }[] })
-    .servers;
-  const servers = Array.isArray(declared) ? declared : [];
-  for (const server of servers) {
-    if (server.url) {
-      addresses.push(server.url);
-    }
-  }
-}
-let addressLabel = "Base URL";
-if (spec?.kind === "asyncapi") {
-  addressLabel = "Servers";
-} else if (spec?.kind === "graphql") {
-  addressLabel = "Endpoint";
-}
+const spec = specOf(specs, source);
+const { addresses, label: addressLabel } = spec
+  ? specAddresses(spec)
+  : { addresses: [], label: "" };
 ---
 
 {

package/src/components/openapi/ApiTagOperations.astro

@@ -1,5 +1,6 @@
 ---
 import specs from "blume:openapi";
+import { specOf } from "../../openapi/model.ts";
 import { withBase } from "../islands/base-path.ts";
 import MethodBadge from "./MethodBadge.astro";
 
@@ -14,7 +15,7 @@ interface Props {
 }
 
 const { source, tag } = Astro.props;
-const operations = Object.values(specs[source]?.operations ?? {}).filter(
+const operations = Object.values(specOf(specs, source)?.operations ?? {}).filter(
   (operation) => operation.tagSlug === tag
 );
 ---

package/src/components/openapi/AsyncApiOperation.astro

@@ -4,6 +4,7 @@ import specs from "blume:openapi";
 
 import type { AsyncApiDocument } from "../../openapi/asyncapi.ts";
 import { asyncApiOperationObject } from "../../openapi/asyncapi.ts";
+import { operationOf, specOf } from "../../openapi/model.ts";
 import { highlightCode } from "../../markdown/index.ts";
 import {
   asyncApiSecurityEntries,
@@ -47,8 +48,8 @@ interface Props {
 }
 
 const { source, id } = Astro.props;
-const spec = specs[source];
-const ref = spec?.operations[id];
+const spec = specOf(specs, source);
+const ref = spec ? operationOf(spec, id) : undefined;
 const document = (spec?.document ?? {}) as AsyncApiDocument;
 const operation = ref ? asyncApiOperationObject(document, ref) : undefined;
 const channel = ref?.channelId

package/src/components/openapi/GraphqlOperation.astro

@@ -10,6 +10,7 @@ import {
   graphqlRootField,
   isGraphqlOperationKind,
 } from "../../openapi/graphql.ts";
+import { operationOf, specOf } from "../../openapi/model.ts";
 import { highlightCode } from "../../markdown/index.ts";
 import { DEPRECATED_LABEL_CLASS } from "../colors.ts";
 import {
@@ -46,8 +47,8 @@ interface Props {
 }
 
 const { source, id } = Astro.props;
-const spec = specs[source];
-const ref = spec?.operations[id];
+const spec = specOf(specs, source);
+const ref = spec ? operationOf(spec, id) : undefined;
 const document = (spec?.document ?? { roots: {}, types: {} }) as GraphqlDocument;
 const isOperation = ref !== undefined && isGraphqlOperationKind(ref.method);
 const field = ref && isOperation ? graphqlRootField(document, ref) : undefined;

package/src/components/openapi/Operation.astro

@@ -1,5 +1,6 @@
 ---
 import specs from "blume:openapi";
+import { operationOf, specOf } from "../../openapi/model.ts";
 import {
   mergeParameters,
   type ParameterLike,
@@ -61,8 +62,8 @@ interface FullOperation {
 }
 
 const { source, id } = Astro.props;
-const spec = specs[source];
-const ref = spec?.operations[id];
+const spec = specOf(specs, source);
+const ref = spec ? operationOf(spec, id) : undefined;
 // 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.

package/src/core/i18n.ts

@@ -48,8 +48,19 @@ export const resolveFallbackLocale = (
   return i18n.fallbackLocale ?? i18n.defaultLocale;
 };
 
+/**
+ * The slice of the i18n settings URL routing reads. `ResolvedI18nConfig` and
+ * the `blume:data` runtime shape both satisfy it, so route helpers serve the
+ * Node-side graph and the rendered page alike.
+ */
+export interface LocaleRouting {
+  defaultLocale: string;
+  hideDefaultLocalePrefix: boolean;
+  locales: { code: string }[];
+}
+
 /** URL prefix for a locale: `""` for the hidden default, else `/<code>`. */
-export const localePrefix = (code: string, i18n: ResolvedI18nConfig): string =>
+export const localePrefix = (code: string, i18n: LocaleRouting): string =>
   code === i18n.defaultLocale && i18n.hideDefaultLocalePrefix ? "" : `/${code}`;
 
 /**
@@ -59,7 +70,7 @@ export const localePrefix = (code: string, i18n: ResolvedI18nConfig): string =>
 export const localizeRoute = (
   logicalRoute: string,
   code: string,
-  i18n: ResolvedI18nConfig
+  i18n: LocaleRouting
 ): string => {
   const prefix = localePrefix(code, i18n);
   if (!prefix) {

package/src/core/links.ts

@@ -7,6 +7,8 @@ import {
   isRelativeImageTarget,
   resolveRelativeImage,
 } from "./content-assets.ts";
+import type { LocaleRouting } from "./i18n.ts";
+import { localizeLinkPath } from "./locale-links.ts";
 import { gradeExternal, probeAll } from "./probe.ts";
 import type {
   ContentGraph,
@@ -78,6 +80,8 @@ interface LinkContext {
   /** Servable routes outside the graph (custom pages, generated routes); their
    * headings are unknown, so anchors there are accepted unchecked. */
   extraRoutes: Set<string>;
+  /** Locale routing, when the site is multi-locale; drives served-route resolution. */
+  i18n: LocaleRouting | null;
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
@@ -189,6 +193,30 @@ const checkAnchor = (
   };
 };
 
+/**
+ * The route a link on `page` actually lands on. Rendered under a prefixed
+ * locale, a root-relative link moves into that locale when the localized route
+ * is served — a real translation (whose own headings then answer the anchor
+ * check) or a fallback page (accepted unchecked via `extraRoutes`) — exactly as
+ * `LocaleLinks.astro` rewrites it at render time. Otherwise the authored route
+ * stands.
+ */
+const servedRoute = (
+  authored: string,
+  page: PageRecord,
+  ctx: LinkContext
+): string =>
+  ctx.i18n
+    ? localizeLinkPath(authored, {
+        basePath: ctx.basePath,
+        i18n: ctx.i18n,
+        locale: page.locale,
+        routes: {
+          has: (route) => ctx.routes.has(route) || ctx.extraRoutes.has(route),
+        },
+      })
+    : authored;
+
 /** Validate a resolved internal path: asset, route, then optional anchor. */
 const checkPathLink = (
   resolved: string,
@@ -204,7 +232,8 @@ const checkPathLink = (
   // relative link already resolved against the based `page.route`). A real
   // route always wins over the asset-extension heuristic, so a dotted route
   // (e.g. `/releases/v1.0`) isn't misread as a missing asset.
-  const route = toRoute(withBasePath(ctx.basePath, resolved));
+  const authoredRoute = toRoute(withBasePath(ctx.basePath, resolved));
+  const route = servedRoute(authoredRoute, page, ctx);
   if (ctx.routes.has(route)) {
     return fragment ? checkAnchor(route, fragment, site, ctx, via) : null;
   }
@@ -374,6 +403,8 @@ export const validateLinks = async (
      * full-route-set resolution in `nav-diagnostics.ts`/`generateRuntime`.
      */
     extraRoutes?: string[];
+    /** Locale routing when i18n is on; links then resolve into the page's locale. */
+    i18n?: LocaleRouting | null;
     publicDir: string | null;
     checkExternal?: boolean;
     /** Configured redirects; their `from` paths count as valid link targets. */
@@ -385,6 +416,7 @@ export const validateLinks = async (
     anchors: buildAnchorIndex(graph.pages),
     basePath,
     extraRoutes: new Set((options.extraRoutes ?? []).map(toRoute)),
+    i18n: options.i18n ?? null,
     publicDir: options.publicDir,
     redirects: new Set(
       (options.redirects ?? []).map((redirect) =>