blume 1.5.2 → 1.6.0

package/src/components/colors.ts

@@ -0,0 +1,142 @@
+/**
+ * Color classes shared by every component that draws a label over a tint of
+ * its own hue — method badges, response status chips, `<Badge>`, the sidebar's
+ * method badges — and by the typed callout/card icons. One table so the pairs
+ * can't drift between components.
+ *
+ * Contrast rule (light mode): text over a 15% tint of its hue must clear 4.5:1,
+ * the WCAG AA bar for text this size. `-700` does for most hues; green and
+ * orange need `-800`, the way yellow already does over its 20% tint. Dark mode
+ * clears the bar at `-300` throughout. Check any hue added here.
+ */
+
+export type Hue =
+  | "blue"
+  | "green"
+  | "orange"
+  | "purple"
+  | "red"
+  | "teal"
+  | "violet"
+  | "yellow";
+
+/** Label over a translucent tint of the same hue. */
+export const TINT = {
+  blue: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  green: "bg-green-500/15 text-green-800 dark:text-green-300",
+  orange: "bg-orange-500/15 text-orange-800 dark:text-orange-300",
+  purple: "bg-purple-500/15 text-purple-700 dark:text-purple-300",
+  red: "bg-red-500/15 text-red-700 dark:text-red-300",
+  teal: "bg-teal-500/15 text-teal-700 dark:text-teal-300",
+  violet: "bg-violet-500/15 text-violet-700 dark:text-violet-300",
+  yellow: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
+} satisfies Record<Hue, string>;
+
+/**
+ * Label with a translucent border of the same hue and no fill. The label
+ * inherits whatever surface it sits on (a callout, a card, the muted panel), so
+ * it is held to the same values as `TINT`: green at `-700` is 4.47:1 on the
+ * default muted surface.
+ */
+export const STROKE = {
+  blue: "border-blue-500/40 text-blue-700 dark:text-blue-300",
+  green: "border-green-500/40 text-green-800 dark:text-green-300",
+  orange: "border-orange-500/40 text-orange-800 dark:text-orange-300",
+  purple: "border-purple-500/40 text-purple-700 dark:text-purple-300",
+  red: "border-red-500/40 text-red-700 dark:text-red-300",
+  teal: "border-teal-500/40 text-teal-700 dark:text-teal-300",
+  violet: "border-violet-500/40 text-violet-700 dark:text-violet-300",
+  yellow: "border-yellow-500/40 text-yellow-800 dark:text-yellow-300",
+} satisfies Record<Hue, string>;
+
+/** The neutral fallback every table falls through to. */
+export const MUTED = "bg-muted text-muted-foreground";
+
+/**
+ * HTTP methods, AsyncAPI actions, and GraphQL root-field kinds, as shown on an
+ * operation's badge and in a reference's sidebar. Type-page kinds fall through
+ * to the muted default so operation badges stay the loud ones.
+ */
+export const METHOD_COLORS = {
+  DELETE: TINT.red,
+  GET: TINT.green,
+  HEAD: MUTED,
+  MUTATION: TINT.blue,
+  OPTIONS: MUTED,
+  PATCH: TINT.yellow,
+  POST: TINT.blue,
+  PUT: TINT.orange,
+  QUERY: TINT.green,
+  RECEIVE: TINT.teal,
+  SEND: TINT.violet,
+  SUBSCRIPTION: TINT.violet,
+} satisfies Record<string, string>;
+
+const isMethod = (key: string): key is keyof typeof METHOD_COLORS =>
+  Object.hasOwn(METHOD_COLORS, key);
+
+export const methodColor = (method: string): string => {
+  const key = method.toUpperCase();
+  return isMethod(key) ? METHOD_COLORS[key] : MUTED;
+};
+
+/** Response status chips, by the status code's class. */
+export const statusColor = (status: string): string => {
+  if (status.startsWith("2")) {
+    return TINT.green;
+  }
+  if (status.startsWith("3")) {
+    return TINT.blue;
+  }
+  if (status.startsWith("4")) {
+    return TINT.orange;
+  }
+  if (status.startsWith("5")) {
+    return TINT.red;
+  }
+  return MUTED;
+};
+
+/**
+ * The small `deprecated` label beside an operation's path or field name. It
+ * draws on the page background, where orange needs `-700` for 4.5:1.
+ */
+export const DEPRECATED_LABEL_CLASS =
+  "font-medium text-[0.625rem] text-orange-700 uppercase tracking-wide dark:text-orange-400";
+
+/** The typed admonitions `<Callout>` and `<Card>` render; `check` is an alias of `success`. */
+export type AdmonitionType =
+  | "info"
+  | "note"
+  | "tip"
+  | "success"
+  | "warning"
+  | "danger";
+
+export const admonitionType = (
+  type: AdmonitionType | "check"
+): AdmonitionType => (type === "check" ? "success" : type);
+
+export const ADMONITION_ICON = {
+  danger: "circle-x",
+  info: "info",
+  note: "info",
+  success: "circle-check",
+  tip: "lightbulb",
+  warning: "triangle-alert",
+} satisfies Record<AdmonitionType, string>;
+
+/**
+ * An admonition's icon names its type, so it is meaningful UI held to the 3:1
+ * non-text bar against the tint behind it: green and amber need `-700` over
+ * their 10% tint, and the note icon is full-strength muted-foreground (at 70%
+ * it fell under the bar on the muted surface).
+ */
+export const ADMONITION_ICON_CLASS = {
+  danger: "text-red-600 dark:text-red-400",
+  info: "text-blue-600 dark:text-blue-400",
+  note: "text-muted-foreground",
+  success: "text-green-700 dark:text-green-400",
+  tip: "text-accent",
+  warning: "text-amber-700 dark:text-amber-400",
+} satisfies Record<AdmonitionType, string>;

package/src/components/content/Badge.astro

@@ -1,4 +1,5 @@
 ---
+import { STROKE, TINT } from "../colors.ts";
 import Icon from "../Icon.astro";
 
 type BadgeVariant = "default" | "accent" | "success" | "warning" | "danger";
@@ -44,34 +45,26 @@ const colorName =
   }[variant];
 const customColor = colorName.startsWith("#") ? colorName : null;
 
+// The hue rows come from the shared table (see colors.ts for the contrast
+// rule); the neutral and surface rows are Badge's own.
 const filledColorClass: Record<string, string> = {
-  blue: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  ...TINT,
   gray: "bg-muted text-muted-foreground",
-  green: "bg-green-500/15 text-green-700 dark:text-green-300",
-  orange: "bg-orange-500/15 text-orange-700 dark:text-orange-300",
-  purple: "bg-purple-500/15 text-purple-700 dark:text-purple-300",
-  red: "bg-red-500/15 text-red-700 dark:text-red-300",
   surface: "bg-background text-muted-foreground ring-1 ring-border",
   "surface-destructive":
     "bg-background text-red-700 ring-1 ring-red-500/30 dark:text-red-300",
   white: "bg-white text-muted-foreground ring-1 ring-border dark:bg-white/10",
   "white-destructive":
     "bg-white text-red-700 ring-1 ring-red-500/30 dark:bg-white/10 dark:text-red-300",
-  yellow: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
 };
 
 const strokeColorClass: Record<string, string> = {
-  blue: "border-blue-500/40 text-blue-700 dark:text-blue-300",
+  ...STROKE,
   gray: "border-border text-muted-foreground",
-  green: "border-green-500/40 text-green-700 dark:text-green-300",
-  orange: "border-orange-500/40 text-orange-700 dark:text-orange-300",
-  purple: "border-purple-500/40 text-purple-700 dark:text-purple-300",
-  red: "border-red-500/40 text-red-700 dark:text-red-300",
   surface: "border-border text-muted-foreground",
   "surface-destructive": "border-red-500/40 text-red-700 dark:text-red-300",
   white: "border-border text-muted-foreground",
   "white-destructive": "border-red-500/40 text-red-700 dark:text-red-300",
-  yellow: "border-yellow-500/40 text-yellow-800 dark:text-yellow-300",
 };
 
 const sizeClass: Record<BadgeSize, string> = {

package/src/components/content/Callout.astro

@@ -1,64 +1,47 @@
 ---
+import {
+  ADMONITION_ICON,
+  ADMONITION_ICON_CLASS,
+  type AdmonitionType,
+  admonitionType,
+} from "../colors.ts";
 import Icon from "../Icon.astro";
 
-type CalloutType =
-  | "info"
-  | "note"
-  | "tip"
-  | "success"
-  | "check"
-  | "warning"
-  | "danger";
-
 interface Props {
-  type?: CalloutType;
+  type?: AdmonitionType | "check";
   title?: string;
   icon?: unknown;
   color?: string;
 }
 
 const { color, icon, type = "info", title } = Astro.props;
+// `check` is an alias of `success`; fold it once so the tables need one row.
+const kind = admonitionType(type);
 
-const iconByType: Record<CalloutType, string> = {
-  check: "circle-check",
-  danger: "circle-x",
-  info: "info",
-  note: "info",
-  success: "circle-check",
-  tip: "lightbulb",
-  warning: "triangle-alert",
-};
-
-const variantClass: Record<CalloutType, string> = {
-  check: "border-green-500/25 bg-green-500/10",
+const variantClass: Record<AdmonitionType, string> = {
   danger: "border-red-500/25 bg-red-500/10",
   info: "border-blue-500/25 bg-blue-500/10",
   note: "border-border bg-muted",
   success: "border-green-500/25 bg-green-500/10",
-  tip: "border-accent/25 bg-accent/10",
+  // 6% rather than the 10% the other variants use: this tint comes from the
+  // user-configurable accent, whose default is near black, and muted body
+  // text on a 10% black tint sits at 4.25:1. 6% clears WCAG AA (4.5:1)
+  // against any accent — 4.62:1 worst case on pure black.
+  tip: "border-accent/25 bg-accent/6",
   warning: "border-amber-500/25 bg-amber-500/10",
 };
-
-const iconClass: Record<CalloutType, string> = {
-  check: "text-green-600 dark:text-green-400",
-  danger: "text-red-600 dark:text-red-400",
-  info: "text-blue-600 dark:text-blue-400",
-  note: "text-muted-foreground/70",
-  success: "text-green-600 dark:text-green-400",
-  tip: "text-accent",
-  warning: "text-amber-600 dark:text-amber-400",
-};
 ---
 
 <aside
   class:list={[
     "not-prose my-5 flex flex-row items-start gap-2 rounded-blume border px-4 py-3 font-sans text-muted-foreground text-sm leading-6 [&_a]:underline [&_a]:decoration-current/50 [&_code]:font-mono",
-    color ? "bg-background" : variantClass[type],
+    color ? "bg-background" : variantClass[kind],
   ]}
+  data-blume-callout={kind}
   style={color ? `border:1px solid ${color};color:${color}` : undefined}
 >
-  <span class:list={["mt-0.5 shrink-0", color ? "" : iconClass[type]]}>
-    <Icon color={color} icon={icon ?? iconByType[type]} size={16} />
+  <span class:list={["mt-0.5 shrink-0", color ? "" : ADMONITION_ICON_CLASS[kind]]}>
+    <Icon color={color} icon={icon ?? ADMONITION_ICON[kind]} size={16} />
   </span>
   {/* The global prose rule leaks a 1rem margin onto these paragraphs/lists even
       though the callout is not-prose; with a title the body isn't the first

package/src/components/content/Card.astro

@@ -1,4 +1,9 @@
 ---
+import {
+  ADMONITION_ICON,
+  ADMONITION_ICON_CLASS,
+  admonitionType,
+} from "../colors.ts";
 import Icon from "../Icon.astro";
 import { withBase } from "../islands/base-path.ts";
 import { contentHref } from "./base-href.ts";
@@ -22,31 +27,20 @@ const external = href?.startsWith("http");
 const isHorizontal = horizontal === true || horizontal === "true";
 const showArrow =
   href && arrow === undefined ? external : arrow === true || arrow === "true";
-const iconByType = {
-  check: "circle-check",
-  danger: "circle-x",
-  info: "info",
-  note: "info",
-  tip: "lightbulb",
-  warning: "triangle-alert",
-};
-const iconClass = {
-  check: "text-green-600 dark:text-green-400",
-  danger: "text-red-600 dark:text-red-400",
-  info: "text-blue-600 dark:text-blue-400",
-  note: "text-muted-foreground/70",
-  tip: "text-accent",
-  warning: "text-amber-600 dark:text-amber-400",
-};
-const iconName = icon ?? (type ? iconByType[type] : undefined);
+// The typed icon shares Callout's table (and its contrast rule); the surface
+// tints are Card's own, a shade lighter than a callout's.
+const kind = type ? admonitionType(type) : undefined;
+const iconName = icon ?? (kind ? ADMONITION_ICON[kind] : undefined);
 const variantClass = {
-  check: "border-green-500/30 bg-green-500/10",
   danger: "border-red-500/30 bg-red-500/10",
   info: "border-blue-500/30 bg-blue-500/10",
   note: "border-border bg-muted/40",
-  tip: "border-accent/30 bg-accent/10",
+  success: "border-green-500/30 bg-green-500/10",
+  // 6% for the same reason as Callout: the accent defaults to near black, and
+  // muted body text on a 10% black tint misses WCAG AA.
+  tip: "border-accent/30 bg-accent/6",
   warning: "border-amber-500/30 bg-amber-500/10",
-}[type ?? "note"];
+}[kind ?? "note"];
 ---
 
 <Tag
@@ -75,7 +69,7 @@ const variantClass = {
   <div class="p-5">
   {
     iconName && (
-      <div class:list={["mb-2.5", color ? "" : type ? iconClass[type] : "text-accent"]}>
+      <div class:list={["mb-2.5", color ? "" : kind ? ADMONITION_ICON_CLASS[kind] : "text-accent"]}>
         <Icon color={color} name={iconName} size={20} />
       </div>
     )

package/src/components/content/Component.astro

@@ -10,6 +10,10 @@
 // examples are all supported. The source is highlighted with the same Shiki
 // setup as ordinary code fences.
 import data from "blume:data";
+import {
+  CODE_PADDING_BLOCK_REM,
+  FLUSH_CODE_PADDING_TOP_REM,
+} from "../../theme/code-block-padding.ts";
 
 import { highlightCode } from "../../markdown/index.ts";
 import { withBase } from "../islands/base-path.ts";
@@ -58,7 +62,12 @@ const codeHtml = entry
 // whose collapse to the measured height no transition could hide. No-JS
 // readers aren't hurt by the cap, since the source scrolls at any height.
 const LINE_PX = 21;
-const PADDING_PX = 36;
+const REM_PX = 16;
+// The pre's vertical padding, from the same constants the theme emits: the
+// copy-button strip on top (the pane is a flush block inside tabs) and the
+// plain inset below. The tab panel and the pre carry no border of their own.
+const PADDING_PX =
+  (FLUSH_CODE_PADDING_TOP_REM + CODE_PADDING_BLOCK_REM) * REM_PX;
 const ESTIMATE_MAX_PX = 400;
 // The floor also clamps the measured height client-side; it rides along on the
 // iframe as `data-blume-min-pane` so the script and this estimate can't drift.

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 { apiUrl, PUBLIC_HOST_URL } from "../../core/github.ts";
 import { resolveIcon } from "../../theme/icons.ts";
 import data from "blume:data";
 import { GITHUB_MARK } from "../github-mark.ts";
@@ -15,22 +16,40 @@ const starIcon = resolveIcon("star")?.body ?? "";
 const forkIcon = resolveIcon("git-fork")?.body ?? "";
 
 interface Props {
+  /**
+   * Origin of the GitHub instance the card's repo lives on. Defaults to the
+   * configured `github.host`, so a card on an Enterprise site reads that
+   * instance; set it to point one card elsewhere — `https://github.com` for a
+   * public project from an Enterprise-hosted docs site, say. The REST base is
+   * derived from it the same way `github.api` is derived from `github.host`.
+   */
+  host?: string;
   owner?: string;
   repo?: string;
   token?: string;
 }
 
-// The resolved config exposes the repo as `repoUrl`, not `github`; parse the
-// owner/repo back out so <GithubInfo /> can default to the configured repo.
-const repoMatch = data.config.repoUrl?.match(
-  /github\.com\/(?<owner>[^/]+)\/(?<repo>[^/]+)/u
-);
-const owner = Astro.props.owner ?? repoMatch?.groups?.owner;
-const repo = Astro.props.repo ?? repoMatch?.groups?.repo;
+// `data.config.github` carries the configured repo's coordinates, so the card
+// defaults to it and addresses the right instance — an Enterprise host serves
+// both the link and the API from somewhere other than github.com. Explicit
+// `owner`/`repo` props are read against that same instance unless `host`
+// points them somewhere else; with no `github` configured at all, they fall
+// back to the public one.
+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;
+// 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
+  ? new URL(Astro.props.host).origin
+  : (configured?.host ?? PUBLIC_HOST_URL);
+const baseUrl = Astro.props.host ? apiUrl({ host }) : configured?.api;
 
 const info =
-  owner && repo ? await fetchRepositoryInfo({ owner, repo, token }) : null;
+  owner && repo
+    ? await fetchRepositoryInfo({ baseUrl, owner, repo, token })
+    : null;
 
 // Compact notation matches GitHub's own counts (e.g. 1.2k, 34.5k).
 const numbers = new Intl.NumberFormat("en", {
@@ -46,7 +65,7 @@ const statIcon =
   owner && repo && (
     <a
       class="not-prose my-6 flex flex-col gap-2 rounded-blume border border-border p-4 no-underline! transition-colors hover:border-foreground/30 hover:bg-muted/40"
-      href={`https://github.com/${owner}/${repo}`}
+      href={`${host}/${owner}/${repo}`}
       rel="noreferrer"
       target="_blank"
     >

package/src/components/content/Tabs.astro

@@ -19,6 +19,13 @@ interface Props {
    */
   param?: string;
   sync?: boolean;
+  /**
+   * Sync tab selection only with other groups sharing the same key. Groups
+   * without a key form one page-wide pool (the default); keyed groups — like
+   * the generated ts2js dialect pairs — sync among themselves, so picking a
+   * tab there can't drag along an authored group with a same-titled tab.
+   */
+  syncKey?: string;
 }
 
 const {
@@ -29,6 +36,7 @@ const {
   inline = false,
   param,
   sync = true,
+  syncKey,
 } = Astro.props;
 
 // MDX string attributes (`hash="false"` from generated markup) must read as
@@ -52,6 +60,7 @@ const useDropdown = dropdown && !inline;
   data-hash={hashEnabled ? "true" : "false"}
   data-param={param}
   data-sync={sync ? "true" : "false"}
+  data-sync-key={syncKey}
 >
   <div
     class:list={[
@@ -116,9 +125,12 @@ const useDropdown = dropdown && !inline;
 
     connectedCallback() {
       const list = this.querySelector<HTMLElement>("[data-blume-tablist]");
+      // Nested groups (a generated ts2js pair inside a CodeGroup, say) own
+      // their panels; adopting a descendant group's panels here would leave
+      // both groups toggling the same elements.
       let panels = Array.from(
         this.querySelectorAll<HTMLElement>("[data-blume-tab-panel]")
-      );
+      ).filter((panel) => panel.closest("blume-tabs") === this);
       // CodeGroup passes raw code fences instead of <Tab> elements, so adopt
       // the content wrapper's direct code blocks as panels. The tab label comes
       // from each block's title (the text after the language in the fence).
@@ -251,7 +263,10 @@ const useDropdown = dropdown && !inline;
       if (sync && this.#syncEnabled()) {
         document.dispatchEvent(
           new CustomEvent(SYNC_EVENT, {
-            detail: { title: panelTitle(activePanel, index) },
+            detail: {
+              key: this.#syncKey(),
+              title: panelTitle(activePanel, index),
+            },
           })
         );
       }
@@ -339,6 +354,10 @@ const useDropdown = dropdown && !inline;
       return this.dataset.sync !== "false";
     }
 
+    #syncKey() {
+      return this.dataset.syncKey ?? "";
+    }
+
     #hashEnabled() {
       return this.dataset.hash !== "false";
     }
@@ -358,9 +377,12 @@ const useDropdown = dropdown && !inline;
     }
 
     #sync = (event: Event) => {
-      const title = (event as CustomEvent<{ title?: string }>).detail?.title;
-      if (title) {
-        this.activateByTitle(title, false);
+      const detail = (event as CustomEvent<{ key?: string; title?: string }>)
+        .detail;
+      // Only same-key groups sync: keyless groups form one page-wide pool,
+      // keyed groups (generated dialect pairs) their own.
+      if (detail?.title && (detail.key ?? "") === this.#syncKey()) {
+        this.activateByTitle(detail.title, false);
       }
     };
 

package/src/components/content/github-info.ts

@@ -7,6 +7,8 @@
  * than throwing, so a card never breaks the build when the API is unreachable.
  */
 
+import { PUBLIC_API_URL } from "../../core/github.ts";
+
 export interface RepositoryInfo {
   description: string | null;
   forks: number;
@@ -20,18 +22,31 @@ export interface FetchRepositoryOptions {
   token?: string;
 }
 
-const DEFAULT_BASE_URL = "https://api.github.com";
-
 /** In-process dedupe so the same repo is fetched once per build. */
 const cache = new Map<string, Promise<RepositoryInfo | null>>();
 
+/** Cleartext bases already warned about, so a site of cards logs once. */
+const warnedCleartext = new Set<string>();
+
 const load = async (
   options: FetchRepositoryOptions
 ): Promise<RepositoryInfo | null> => {
-  const { baseUrl = DEFAULT_BASE_URL, owner, repo, token } = options;
+  const { baseUrl = PUBLIC_API_URL, owner, repo, token } = options;
   const headers = new Headers({ Accept: "application/vnd.github+json" });
+  // An Enterprise instance can be configured on plain HTTP; a bearer token is
+  // never worth putting on the wire in cleartext, so it is dropped rather than
+  // sent. The request still goes out — a public repo's counts render either way
+  // — but a private repo's card comes back bare, which looks exactly like a
+  // network failure, so say why once per base.
   if (token) {
-    headers.set("Authorization", `Bearer ${token}`);
+    if (new URL(baseUrl).protocol === "https:") {
+      headers.set("Authorization", `Bearer ${token}`);
+    } else if (!warnedCleartext.has(baseUrl)) {
+      warnedCleartext.add(baseUrl);
+      console.warn(
+        `[blume] <GithubInfo> is not sending its token to ${baseUrl}: the API base is plain HTTP, so the bearer token would travel in cleartext. Counts for a private repository will be missing; serve the API over https to authenticate.`
+      );
+    }
   }
 
   const response = await fetch(`${baseUrl}/repos/${owner}/${repo}`, {
@@ -69,7 +84,7 @@ const loadSafe = async (
 export const fetchRepositoryInfo = (
   options: FetchRepositoryOptions
 ): Promise<RepositoryInfo | null> => {
-  const key = `${options.baseUrl ?? DEFAULT_BASE_URL}/${options.owner}/${options.repo}`;
+  const key = `${options.baseUrl ?? PUBLIC_API_URL}/${options.owner}/${options.repo}`;
   const existing = cache.get(key);
   if (existing) {
     return existing;