blume 0.6.7 → 0.8.0

package/src/components/content/Component.astro

@@ -5,14 +5,18 @@
 // `<Component path="forms/login" />` for `examples/forms/login.tsx`.
 //
 // Blume discovers `examples/` at build time and generates `blume:examples`: a
-// map of path → { Component (a static hydration wrapper), code, lang }. React,
-// Vue, Svelte, and Astro examples are all supported. The source is highlighted
-// with the same Shiki setup as ordinary code fences.
+// map of path → { Component (a static hydration wrapper), code, lang } plus
+// the route base preview frames live under. React, Vue, Svelte, and Astro
+// examples are all supported. The source is highlighted with the same Shiki
+// setup as ordinary code fences.
+import data from "blume:data";
+
 import { highlightCode } from "../../markdown/index.ts";
+import { withBase } from "../islands/base-path.ts";
 import Tab from "./Tab.astro";
 import Tabs from "./Tabs.astro";
 // Generated per project; resolves to an empty map when there are no examples.
-import { examples } from "blume:examples";
+import { examples, examplesBase } from "blume:examples";
 
 interface Props {
   path: string;
@@ -20,14 +24,27 @@ interface Props {
 
 const { path } = Astro.props;
 const entry = examples[path];
-const Preview = entry?.Component;
+
+// The live preview renders in its own generated route, embedded as an iframe:
+// the frame boundary is what keeps the docs CSS (prose typography, component
+// chrome) out of the example entirely, so users can preview components styled
+// by their own design system (e.g. shadcn, via the configured `examples.css`).
+// The frame syncs its theme with this document before first paint.
+const previewSrc = entry
+  ? withBase(
+      `${examplesBase}/${path.split("/").map(encodeURIComponent).join("/")}`
+    )
+  : undefined;
 
 // Highlight the source with the shared helper so it matches Markdown fences.
 // `blume-source` makes the inner `<code>` (not the `<pre>`) the scroll/height-
 // capped box — see the theme entry — so the copy button, pinned to the `<pre>`,
 // stays put. This pane already lives inside `.prose`, so the theme styles it.
 const codeHtml = entry
-  ? await highlightCode(entry.code, entry.lang, { className: "blume-source" })
+  ? await highlightCode(entry.code, entry.lang, {
+      className: "blume-source",
+      themes: data.config.codeThemes,
+    })
   : undefined;
 
 // Both tabs share one height so toggling them never shifts the layout. Size it
@@ -45,16 +62,13 @@ const paneStyle = `height:${paneHeight}px`;
     // `sync={false}`: each preview's Preview/Code tabs are independent — unlike
     // CodeGroup, switching one Component must not switch the others.
     <Tabs hash={false} sync={false}>
-      <Tab
-        // `not-prose`: the preview lives inside the page's `.prose` wrapper, so
-        // without this the typography styles bleed into the live component
-        // (headings, links, lists, spacing). The Code pane below keeps prose on
-        // purpose — that's what styles the highlighted source.
-        class="not-prose flex items-center justify-center overflow-auto"
-        style={paneStyle}
-        title="Preview"
-      >
-        <Preview />
+      <Tab class="overflow-hidden p-0!" style={paneStyle} title="Preview">
+        <iframe
+          class="h-full w-full"
+          loading="lazy"
+          src={previewSrc}
+          title={`Preview of ${path}`}
+        />
       </Tab>
       <Tab class="overflow-hidden" style={paneStyle} title="Code">
         <Fragment set:html={codeHtml} />

package/src/components/content/Diff.astro

@@ -6,6 +6,8 @@
 //
 // Inputs (one of): `patch`/`src` (unified patch), `before`+`after` (file paths),
 // or `old`+`new` (inline strings, with optional `lang`).
+import data from "blume:data";
+
 import { renderDiff } from "./diff.ts";
 
 interface Props {
@@ -22,7 +24,7 @@ let html: string | undefined;
 let error: string | undefined;
 
 try {
-  html = await renderDiff(Astro.props);
+  html = await renderDiff({ ...Astro.props, theme: data.config.codeThemes });
 } catch (cause) {
   error = cause instanceof Error ? cause.message : String(cause);
 }

package/src/components/content/Step.astro

@@ -26,7 +26,16 @@ const canRenderIcon =
   <span class:list={[markerClass, !canRenderIcon && "before:[content:counter(blume-step)]"]}>
     {canRenderIcon && <Icon name={icon} size={14} />}
   </span>
-  {title && <p class="mb-1.5 font-semibold">{title}</p>}
+  {
+    // Consumes the `titleSize` variables set by <Steps>; the fallbacks match
+    // its "p" default (and the prose-inherited sizing) so a bare <Step>
+    // renders identically.
+    title && (
+      <p class="mb-1.5 font-semibold text-[length:var(--blume-step-title-size,1rem)] leading-[var(--blume-step-title-line-height,1.75rem)]">
+        {title}
+      </p>
+    )
+  }
   <div class="[&>:first-child]:mt-0! [&>:last-child]:mb-0!">
     <slot />
   </div>

package/src/components/content/Tabs.astro

@@ -51,6 +51,10 @@ const hashEnabled = String(hash) !== "false";
     "w-full rounded-blume border border-border bg-background px-3 py-2 font-medium text-foreground text-sm";
   const SYNC_EVENT = "blume-tabs-change";
 
+  // Disambiguates generated trigger/panel ids when the same tab labels appear
+  // in several <Tabs> instances on one page.
+  let instanceCount = 0;
+
   const panelTitle = (panel: HTMLElement, index: number) =>
     panel.dataset.title ?? `Tab ${index + 1}`;
   const panelId = (panel: HTMLElement) => panel.dataset.tabId ?? panel.id;
@@ -119,7 +123,8 @@ const hashEnabled = String(hash) !== "false";
       if (this.dataset.dropdown === "true") {
         this.#select = document.createElement("select");
         this.#select.className = SELECT_CLASS;
-        this.#select.setAttribute("aria-label", "Select code example");
+        // Neutral default: tab sets aren't necessarily code examples.
+        this.#select.setAttribute("aria-label", "Select tab");
         panels.forEach((panel, index) => {
           const option = document.createElement("option");
           option.value = String(index);
@@ -131,6 +136,7 @@ const hashEnabled = String(hash) !== "false";
         });
         list.appendChild(this.#select);
       } else {
+        const instance = ++instanceCount;
         panels.forEach((panel, index) => {
           const trigger = document.createElement("button");
           trigger.type = "button";
@@ -138,9 +144,15 @@ const hashEnabled = String(hash) !== "false";
           trigger.className = TRIGGER_CLASS;
           appendTriggerContent(trigger, panel, index);
           trigger.tabIndex = index === 0 ? 0 : -1;
-          if (panel.id) {
-            trigger.setAttribute("aria-controls", panel.id);
+          // Wire tab and panel both ways. An author-supplied panel id is kept;
+          // otherwise derive unique ids from the label slug per instance.
+          const slug = panelId(panel) || `tab-${index + 1}`;
+          if (!panel.id) {
+            panel.id = `blume-tabpanel-${slug}-${instance}`;
           }
+          trigger.id = `blume-tab-${slug}-${instance}`;
+          trigger.setAttribute("aria-controls", panel.id);
+          panel.setAttribute("aria-labelledby", trigger.id);
           trigger.setAttribute(
             "aria-selected",
             index === 0 ? "true" : "false"

package/src/components/content/Tile.astro

@@ -1,5 +1,6 @@
 ---
 import Icon from "../Icon.astro";
+import { contentHref } from "./base-href.ts";
 
 const { description, href, title } = Astro.props;
 const Tag = href ? "a" : "div";
@@ -11,7 +12,7 @@ const previewPattern =
 <Tag
   class="not-prose block overflow-hidden rounded-blume border border-border bg-background text-inherit no-underline! transition-colors hover:no-underline! hover:[&[href]]:border-accent"
   data-blume-tile
-  href={href}
+  href={href === undefined ? undefined : contentHref(href)}
   rel={external ? "noreferrer" : undefined}
   target={external ? "_blank" : undefined}
 >

package/src/components/content/Tooltip.astro

@@ -1,6 +1,8 @@
 ---
 import { randomUUID } from "node:crypto";
 
+import { contentHref } from "./base-href.ts";
+
 interface Props {
   cta?: string;
   headline?: string;
@@ -43,7 +45,7 @@ const labelHtml = Astro.slots.has("default")
       cta && href && (
         <a
           class="mt-2 inline-flex font-medium text-accent text-xs hover:underline"
-          href={href}
+          href={contentHref(href)}
           rel={external ? "noreferrer" : undefined}
           target={external ? "_blank" : undefined}
         >

package/src/components/content/Update.astro

@@ -1,4 +1,6 @@
 ---
+import { contentHref } from "./base-href.ts";
+
 interface RssMetadata {
   description?: string;
   title?: string;
@@ -6,7 +8,12 @@ interface RssMetadata {
 
 interface Props {
   description?: string;
-  /** Link the heading to a dedicated page; falls back to the in-page anchor. */
+  /**
+   * Link the heading to a dedicated page; falls back to the in-page anchor.
+   * A root-relative route gains the composed `deployment.base` + `basePath`
+   * prefix at emit time (like a markdown link); anchors and external URLs
+   * pass through.
+   */
   href?: string;
   id?: string;
   label?: string;
@@ -47,7 +54,7 @@ const tagList = Array.isArray(tags) ? tags : tags ? [tags] : [];
   <header class="md:border-border md:border-e md:pe-4">
     <a
       class="font-semibold text-foreground text-sm no-underline hover:text-accent"
-      href={href ?? `#${id}`}
+      href={contentHref(href ?? `#${id}`)}
     >
       {updateLabel}
     </a>

package/src/components/content/auto-type-table.ts

@@ -9,7 +9,17 @@
  */
 import nodePath from "node:path";
 
-import type * as TypeScriptApi from "typescript";
+import type {
+  CompilerHost,
+  CompilerOptions,
+  DeclarationStatement,
+  Program,
+} from "typescript";
+
+// `typeof import(...)` is the only way to name the whole lazily-imported
+// `typescript` module without a value import (see components/props.ts).
+// oxlint-disable-next-line typescript/consistent-type-imports
+type TypeScriptApi = typeof import("typescript");
 
 /** A single documented property — one generated row of a type table. */
 export interface TypeTableProperty {
@@ -36,10 +46,10 @@ const VIRTUAL_FILE = "__blume_auto_type_table__.ts";
 
 /** Build a compiler host that serves a single in-memory file plus the real libs. */
 const inMemoryHost = (
-  ts: typeof TypeScriptApi,
-  options: TypeScriptApi.CompilerOptions,
+  ts: TypeScriptApi,
+  options: CompilerOptions,
   source: string
-): TypeScriptApi.CompilerHost => {
+): CompilerHost => {
   const host = ts.createCompilerHost(options, true);
   const getSourceFile = host.getSourceFile.bind(host);
   host.getSourceFile = (requested, languageVersion, onError, shouldCreate) =>
@@ -65,9 +75,9 @@ export const extractTypeTable = async (
 ): Promise<TypeTableProperty[]> => {
   const { name, path, root = process.cwd(), source } = options;
   const tsModule = await import("typescript");
-  const ts = (tsModule.default ?? tsModule) as typeof TypeScriptApi;
+  const ts = (tsModule.default ?? tsModule) as TypeScriptApi;
 
-  const compilerOptions: TypeScriptApi.CompilerOptions = {
+  const compilerOptions: CompilerOptions = {
     allowJs: true,
     module: ts.ModuleKind.ESNext,
     moduleResolution: ts.ModuleResolutionKind.Bundler,
@@ -78,7 +88,7 @@ export const extractTypeTable = async (
   };
 
   let fileName: string;
-  let program: TypeScriptApi.Program;
+  let program: Program;
   if (source === undefined) {
     if (path === undefined) {
       throw new Error("AutoTypeTable needs a `path` or inline `type` source.");
@@ -100,7 +110,7 @@ export const extractTypeTable = async (
   }
 
   const declaration = sourceFile.statements.find(
-    (statement): statement is TypeScriptApi.DeclarationStatement =>
+    (statement): statement is DeclarationStatement =>
       (ts.isInterfaceDeclaration(statement) ||
         ts.isTypeAliasDeclaration(statement)) &&
       statement.name?.text === name
@@ -134,7 +144,13 @@ export const extractTypeTable = async (
       default: defaultValue || undefined,
       description: description || undefined,
       name: symbol.getName(),
-      required: !signature?.questionToken,
+      // Optionality lives on the checker's symbol, not the backing
+      // declaration: mapped/utility types synthesize members whose
+      // declaration has no question token (`Partial<Base>` would read as
+      // all-required), and `Required<Base>` strips optionality while the
+      // declaration keeps its `?` — the token is wrong in both directions.
+      // oxlint-disable-next-line no-bitwise -- SymbolFlags is a bitfield
+      required: (symbol.flags & ts.SymbolFlags.Optional) === 0,
       type: typeText,
     };
   });

package/src/components/content/base-href.ts

@@ -0,0 +1,33 @@
+import data from "blume:data";
+
+import {
+  isInternalPath,
+  normalizeBasePath,
+  withComposedBasePath,
+} from "../../core/base-path.ts";
+
+// Mirrors `markdown/base-links.ts`: a path whose final segment carries a file
+// extension is a `public/` asset, served at the site root and never moved
+// under `basePath`.
+const ASSET_PATH = /\.[a-z0-9]+$/iu;
+
+/** Strip any `#fragment`/`?query` so only the path is extension-tested. */
+const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
+
+/**
+ * Rebase a component-emitted `href` the way `markdown/base-links.ts` rebases
+ * `[x](/guide)`: a root-relative internal page link gains the composed
+ * `deployment.base` + `basePath` prefix, so authors write component links
+ * (`<Card href="/guide">`) under the same "as if mounted at root" contract as
+ * markdown links. Idempotent per layer (a hand-written `/docs/x` isn't
+ * double-prefixed) and inert for external URLs, fragments, relative paths, and
+ * asset links.
+ */
+export const contentHref = (href: string): string =>
+  isInternalPath(href) && !ASSET_PATH.test(pathOf(href))
+    ? withComposedBasePath(
+        normalizeBasePath(import.meta.env.BASE_URL),
+        data.config.basePath,
+        href
+      )
+    : href;

package/src/components/content/changelog-element.ts

@@ -1,5 +1,5 @@
 /**
- * Client behaviour for the `<blume-changelog>` custom element wrapping the
+ * Client behavior for the `<blume-changelog>` custom element wrapping the
  * generated changelog timeline when its releases are semver-versioned. The
  * newest major line stays visible; every older major is collapsed into a group
  * revealed one major at a time by the "Show N.x releases" button at the bottom.
@@ -24,6 +24,10 @@ class BlumeChangelog extends HTMLElement {
       return;
     }
 
+    // Localized button template from the generated page markup (the
+    // data-attribute channel); `{version}` is replaced with the major line.
+    const template = this.dataset.i18nMore || "Show {version} releases";
+
     for (const group of groups) {
       group.hidden = true;
       // Focusable only programmatically, so revealing a group can move focus to
@@ -35,7 +39,10 @@ class BlumeChangelog extends HTMLElement {
     const sync = () => {
       const next = groups[revealed];
       if (next) {
-        button.textContent = `Show ${next.dataset.changelogLabel} releases`;
+        button.textContent = template.replace(
+          "{version}",
+          next.dataset.changelogLabel ?? ""
+        );
         button.hidden = false;
       } else {
         button.hidden = true;

package/src/components/content/diff.ts

@@ -13,6 +13,9 @@ import { readFile } from "node:fs/promises";
 import { preloadDiffHTML, preloadPatchDiff } from "@pierre/diffs/ssr";
 import { isAbsolute, join } from "pathe";
 
+import { DEFAULT_CODE_THEMES } from "../../markdown/themes.ts";
+import type { CodeThemes } from "../../markdown/themes.ts";
+
 export interface DiffOptions {
   /** Path to the "after" file, resolved relative to {@link DiffOptions.root}. */
   after?: string;
@@ -30,11 +33,13 @@ export interface DiffOptions {
   root?: string;
   /** Path to a `.patch`/`.diff` file, resolved relative to {@link DiffOptions.root}. */
   src?: string;
+  /**
+   * Light/dark Shiki themes (`markdown.codeBlocks.theme`). Defaults to the same
+   * github pair Blume's code blocks use, keeping diffs in lockstep.
+   */
+  theme?: CodeThemes;
 }
 
-/** Dual-theme config mirroring Blume's Shiki convention (see `templates.ts`). */
-const THEME = { dark: "github-dark", light: "github-light" } as const;
-
 const resolvePath = (path: string, root: string): string =>
   isAbsolute(path) ? path : join(root, path);
 
@@ -56,12 +61,13 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     patch,
     root = process.cwd(),
     src,
+    theme = DEFAULT_CODE_THEMES,
   } = options;
 
   if (patch !== undefined || src !== undefined) {
     const text = patch ?? (await readText(src as string, root));
     const result = await preloadPatchDiff({
-      options: { theme: THEME },
+      options: { theme },
       patch: text,
     });
     return result.prerenderedHTML;
@@ -74,7 +80,7 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     return await preloadDiffHTML({
       newFile: { contents: await readText(after, root), name: after },
       oldFile: { contents: await readText(before, root), name: before },
-      options: { theme: THEME },
+      options: { theme },
     });
   }
 
@@ -85,7 +91,7 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     return await preloadDiffHTML({
       newFile: { contents: newText, lang, name: "snippet" },
       oldFile: { contents: old, lang, name: "snippet" },
-      options: { disableFileHeader: true, theme: THEME },
+      options: { disableFileHeader: true, theme },
     });
   }
 

package/src/components/content/mermaid-element.ts

@@ -1,5 +1,5 @@
 /**
- * Client behaviour for the `<blume-mermaid>` custom element emitted by the
+ * Client behavior for the `<blume-mermaid>` custom element emitted by the
  * Mermaid markdown plugin. Mermaid is lazy-loaded — it needs a DOM and is large,
  * so the dependency only downloads on pages that actually contain a diagram —
  * and each diagram re-renders when the color theme flips so it tracks light/dark.
@@ -55,10 +55,18 @@ class BlumeMermaid extends HTMLElement {
         // A newer render (rapid theme toggles) superseded this one — dropping
         // the stale result keeps the diagram in the latest theme.
         if (token === this.#renderToken) {
+          // Mermaid's own render output is SVG markup; it must be injected as
+          // HTML, not text. securityLevel "strict" (see initialize) sanitizes it.
+          // oxlint-disable-next-line github/no-inner-html -- Mermaid-generated SVG must be injected as HTML
           output.innerHTML = svg;
         }
       } catch {
-        output.textContent = "Could not render this diagram.";
+        // Localized message stamped on <body> by RootLayout's markup (the
+        // data-attribute channel); English fallback when the attribute is
+        // missing (a stale snapshot or a custom layout).
+        output.textContent =
+          document.body.dataset.i18nDiagramError ||
+          "Could not render this diagram.";
       }
       output.removeAttribute("aria-busy");
     };

package/src/components/index.ts

@@ -11,4 +11,26 @@ export type {
   IslandDescriptor,
 } from "../core/define-components.ts";
 export type { HydrationMode } from "../core/schema.ts";
-export type * from "./props.ts";
+export type {
+  AccordionItemProps,
+  AccordionProps,
+  BadgeProps,
+  CalloutProps,
+  CardGroupProps,
+  CardProps,
+  CodeGroupProps,
+  ColumnProps,
+  ColumnsProps,
+  ExpandableProps,
+  FrameProps,
+  IconProps,
+  PanelProps,
+  PromptProps,
+  StepProps,
+  StepsProps,
+  TabProps,
+  TabsProps,
+  TileProps,
+  TooltipProps,
+  YouTubeProps,
+} from "./props.ts";

package/src/components/islands/AskAI.astro

@@ -63,13 +63,16 @@ const icons = {
   }
 
   /* The table of contents only shows at xl; reclaim its column for the article
-     while the panel is open so the shrunken content still has room to breathe. */
+     while the panel is open so the shrunken content still has room to breathe.
+     Scoped to grids that actually have a TOC column: a "bare" layout (the
+     changelog index) is single-column, and forcing the sidebar tracks onto it
+     would squeeze its only item — <main> — into the 17.5rem track. */
   @media (min-width: 1280px) {
     body[data-blume-ask="open"] [data-blume-toc] {
       display: none;
     }
 
-    body[data-blume-ask="open"] [data-blume-doc-grid] {
+    body[data-blume-ask="open"] [data-blume-doc-grid]:has([data-blume-toc]) {
       grid-template-columns: 17.5rem minmax(0, 1fr);
     }
   }