blume 1.6.5 → 1.7.0

package/src/components/Icon.astro

@@ -1,6 +1,7 @@
 ---
 import { isImageIcon, isInlineSvg } from "../theme/icon-kind.ts";
 import { resolveIcon } from "../theme/icons.ts";
+import { iconSpriteFor, registerIconSymbol } from "./icon-sprite.ts";
 import { withBase } from "./islands/base-path.ts";
 
 interface Props {
@@ -32,6 +33,17 @@ const rawSvg = iconName && isInlineSvg(iconName) ? iconName.trim() : null;
 const imageSrc = iconName && !rawSvg && isImageIcon(iconName) ? iconName : null;
 const resolvedIcon =
   iconName && !(imageSrc || rawSvg) ? resolveIcon(iconName) : null;
+// A set icon joins the page's sprite when the shell keeps one (see
+// icon-sprite.ts): the paths render once, in the sprite, and this use is a
+// <use> reference. Without a sprite the icon inlines its paths as before.
+const sprite = resolvedIcon ? iconSpriteFor(Astro.locals) : undefined;
+const symbolId =
+  sprite && resolvedIcon
+    ? registerIconSymbol(sprite, resolvedIcon.name, {
+        body: resolvedIcon.body,
+        viewBox: resolvedIcon.viewBox,
+      })
+    : null;
 const resolvedClass = astroClass ?? className;
 const customStyle = `display:inline-flex;width:${size}px;height:${size}px;${
   color ? `color:${color}` : ""
@@ -68,6 +80,18 @@ const style = color ? `color:${color}` : undefined;
       src={withBase(imageSrc)}
       width={size}
     />
+  ) : symbolId ? (
+    <svg
+      aria-hidden={label ? undefined : "true"}
+      aria-label={label}
+      class={resolvedClass}
+      height={size}
+      role={label ? "img" : undefined}
+      style={style}
+      width={size}
+    >
+      <use href={`#${symbolId}`} />
+    </svg>
   ) : (
     resolvedIcon && (
     <svg

package/src/components/content/GithubInfo.astro

@@ -3,6 +3,7 @@
 // at build time (no client JS). Pass `owner`/`repo`, or omit them to use the
 // repo from blume.config. A `GITHUB_TOKEN` env var lifts the API rate limit.
 // If the API is unreachable the card still renders, just without counts.
+import { getSecret } from "astro:env/server";
 import { apiUrl, PUBLIC_HOST_URL } from "../../core/github.ts";
 import { resolveIcon } from "../../theme/icons.ts";
 import data from "blume:data";
@@ -38,7 +39,9 @@ interface Props {
 const configured = data.config.github;
 const owner = Astro.props.owner ?? configured?.owner;
 const repo = Astro.props.repo ?? configured?.repo;
-const token = Astro.props.token ?? process.env.GITHUB_TOKEN;
+// Read through Astro's `getSecret` so the adapter's secret store is honored
+// (the card renders at build time, where that is the environment).
+const token = Astro.props.token ?? getSecret("GITHUB_TOKEN");
 // A `host` prop is reduced to its origin, as the config field is, so a
 // trailing slash or a path never lands mid-link.
 const host = Astro.props.host

package/src/components/icon-sprite-middleware.ts

@@ -0,0 +1,41 @@
+import type { MiddlewareHandler } from "astro";
+
+import { iconSpriteFor, renderIconSprite } from "./icon-sprite.ts";
+import type { IconSprite } from "./icon-sprite.ts";
+
+/**
+ * The placeholder a shell renders where its icon sprite goes (the end of the
+ * body); {@link onRequest} replaces it once the page has fully rendered.
+ * Rendering the sprite from a component instead wouldn't work: Astro walks a
+ * template's own markup before its nested components render, so a sprite
+ * component at the end of the body runs before the header's search button or
+ * the page content's callouts have registered their icons.
+ */
+export const ICON_SPRITE_SLOT = "<!--blume-icon-sprite-->";
+
+/** The page HTML with its placeholder replaced by the finished sprite. */
+export const spliceIconSprite = (html: string, sprite?: IconSprite): string =>
+  html.includes(ICON_SPRITE_SLOT)
+    ? html.replace(ICON_SPRITE_SLOT, sprite ? renderIconSprite(sprite) : "")
+    : html;
+
+/**
+ * Blume's icon-sprite middleware (wired by the integration). Draining the
+ * response renders the whole page, after which the request's registry holds
+ * every icon it used; the sprite is spliced in where the shell left the slot.
+ * Requests whose shell kept no registry — a user layout override, a partial,
+ * an endpoint — pass through untouched, streaming and all.
+ */
+export const onRequest: MiddlewareHandler = async (context, render) => {
+  const response = await render();
+  const sprite = iconSpriteFor(context.locals);
+  if (!sprite) {
+    return response;
+  }
+  const html = await response.text();
+  return new Response(spliceIconSprite(html, sprite), {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+};

package/src/components/icon-sprite.ts

@@ -0,0 +1,93 @@
+/**
+ * A per-page SVG sprite for the icon sets. A page renders the same handful of
+ * icons many times over (every sidebar chevron, every code-block language
+ * icon, the page-action buttons); inlining each one repeats its paths on every
+ * use, which on a docs page is ~20 kB of the ~60 kB that isn't the sidebar.
+ * With the sprite, each use is a `<use href="#…">` reference and the paths
+ * appear once, in a hidden `<svg>` the layout renders at the end of the body.
+ *
+ * The registry lives on the request's `Astro.locals`, so every component in
+ * one page render — the layout, the MDX content, cached sidebar subtrees —
+ * shares it, and concurrent page renders never see each other's icons. A
+ * shell that creates no registry (a user's layout override, a partial) gets
+ * inline icons, exactly as before.
+ */
+
+/** One symbol in the sprite: an icon set's inner markup and its viewBox. */
+export interface IconSymbol {
+  body: string;
+  viewBox: string;
+}
+
+export interface IconSprite {
+  /** Symbol id → symbol, in first-use order. */
+  symbols: Map<string, IconSymbol>;
+}
+
+/** The request locals (`Astro.locals`) slot the registry lives in. */
+export interface IconSpriteLocals {
+  blumeIconSprite?: IconSprite;
+}
+
+/** The request's sprite registry, when a shell created one. */
+export const iconSpriteFor = (
+  locals: IconSpriteLocals
+): IconSprite | undefined => locals.blumeIconSprite;
+
+/**
+ * The request's sprite registry, created on first call: a shell calls this
+ * up front. Idempotent, so a shell rendered inside another shell's request
+ * joins the existing registry instead of discarding its icons.
+ */
+export const createIconSprite = (locals: IconSpriteLocals): IconSprite => {
+  locals.blumeIconSprite ??= { symbols: new Map() };
+  return locals.blumeIconSprite;
+};
+
+/**
+ * The sprite symbol id for an icon name. Names come from config and content
+ * (`lucide:arrow-right`, `simple-icons:github`), so anything outside the id
+ * charset is folded to a dash.
+ */
+export const iconSymbolId = (name: string): string =>
+  `blume-i-${name.toLowerCase().replaceAll(/[^a-z0-9-]+/gu, "-")}`;
+
+/** Register a symbol (idempotent) and return its id. */
+export const registerIconSymbol = (
+  sprite: IconSprite,
+  name: string,
+  symbol: IconSymbol
+): string => {
+  const id = iconSymbolId(name);
+  if (!sprite.symbols.has(id)) {
+    sprite.symbols.set(id, symbol);
+  }
+  return id;
+};
+
+/** The ids of every sprite symbol a rendered HTML fragment references. */
+export const referencedIconSymbols = (html: string): string[] => [
+  ...new Set(
+    [...html.matchAll(/href="#(?<id>blume-i-[^"]+)"/gu)].map(
+      (match) => match.groups?.id ?? ""
+    )
+  ),
+];
+
+/**
+ * The hidden sprite `<svg>` holding every registered symbol, or an empty
+ * string when the page used no set icon. Symbol bodies are the icon sets'
+ * own markup (already SVG); the viewBox is the only attribute interpolated.
+ */
+export const renderIconSprite = (sprite: IconSprite): string => {
+  if (sprite.symbols.size === 0) {
+    return "";
+  }
+  const symbols = [...sprite.symbols]
+    .map(
+      ([id, symbol]) =>
+        `<symbol id="${id}" viewBox="${symbol.viewBox}">${symbol.body}</symbol>`
+    )
+    .join("");
+  return `<svg aria-hidden="true" hidden xmlns="http://www.w3.org/2000/svg">${symbols}</svg>`;
+};

package/src/components/layout/IconSprite.astro

@@ -0,0 +1,11 @@
+---
+// Where the page's icon sprite goes: every set icon the render registered
+// (see icon-sprite.ts), as one hidden <svg> of <symbol>s the icons' <use>
+// references resolve against. This only leaves a placeholder at the end of
+// the body; the icon-sprite middleware replaces it once the page has fully
+// rendered, since a component here would run before nested components
+// (the header's search button, the content's callouts) register their icons.
+import { ICON_SPRITE_SLOT } from "../icon-sprite-middleware.ts";
+---
+
+<Fragment set:html={ICON_SPRITE_SLOT} />