blume 1.6.5 → 1.7.0

package/src/openapi/render-mdx.ts

@@ -3,6 +3,7 @@ import { fromMarkdown } from "mdast-util-from-markdown";
 import { toString as mdastToString } from "mdast-util-to-string";
 import stringWidth from "string-width";
 
+import { apiNamePhrase } from "../core/api-name.ts";
 import { columnsPrefix } from "../core/text-width.ts";
 import type { GraphqlMember } from "./graphql.ts";
 import { isGraphqlOperationKind } from "./graphql.ts";
@@ -158,6 +159,8 @@ const clip = (text: string, max: number): string => {
 };
 
 const apiName = (spec: ApiSpecData): string => spec.title || spec.label;
+/** The spec's name as "the ___" in generated prose (see `apiNamePhrase`). */
+const apiPhrase = (spec: ApiSpecData): string => apiNamePhrase(apiName(spec));
 
 /** Human phrase for each GraphQL page kind, for meta descriptions. */
 const GRAPHQL_MEMBER_PHRASES = {
@@ -194,16 +197,17 @@ const operationDescription = (
   }
   // AsyncAPI operations act on a channel, not an HTTP endpoint; GraphQL pages
   // document a root field or a named type.
-  let suffix: string;
+  let subject: string;
   if (spec.kind === "asyncapi") {
-    suffix = `Reference for the ${operation.method} operation on ${operation.path} in the ${apiName(spec)} API.`;
+    subject = `${operation.method} operation on ${operation.path}`;
   } else if (spec.kind === "graphql") {
     // SAFETY: the GraphQL extractor only ever assigns member kinds as the
     // method (see `extractGraphqlOperations`).
-    suffix = `Reference for the ${operation.path} ${GRAPHQL_MEMBER_PHRASES[operation.method as GraphqlMember]} in the ${apiName(spec)} API.`;
+    subject = `${operation.path} ${GRAPHQL_MEMBER_PHRASES[operation.method as GraphqlMember]}`;
   } else {
-    suffix = `Reference for the ${operation.method.toUpperCase()} ${operation.path} endpoint in the ${apiName(spec)} API.`;
+    subject = `${operation.method.toUpperCase()} ${operation.path} endpoint`;
   }
+  const suffix = `Reference for the ${subject} in the ${apiPhrase(spec)}.`;
   const prose = clip(
     plainProse(operation.description || operation.summary),
     META_DESCRIPTION_MAX - stringWidth(suffix) - 1
@@ -350,7 +354,7 @@ export const overviewMdx = (
   const seo: RenderedPageData["seo"] = {
     description:
       clip(plainProse(spec.description), META_DESCRIPTION_MAX) ||
-      `${apiName(spec)} API reference.`,
+      `${apiPhrase(spec)} reference.`,
   };
   if (reference?.noindex) {
     seo.noindex = true;

package/src/registry/eject.ts

@@ -17,24 +17,26 @@ import {
 } from "../astro/examples.ts";
 import {
   buildRuntimeData,
+  clientFeaturesFor,
   collectStaged,
   detectNeedsReact,
   detectUsesMath,
+  languageIconCssFor,
 } from "../astro/generate.ts";
 import { discoverIslands } from "../astro/islands.ts";
 import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
 import {
-  askEndpointTemplate,
   askComponentTemplate,
+  askEndpointTemplate,
   astroConfigTemplate,
   catchAllPageTemplate,
   changelogIndexTemplate,
   contentConfigTemplate,
-  envTemplate,
   exampleMapTemplate,
-  exampleWrapperTemplate,
-  examplesPageTemplate,
   exampleSlug,
+  examplesPageTemplate,
+  exampleWrapperTemplate,
+  featuresTemplate,
   islandMapTemplate,
   islandWrapperTemplate,
   mcpEndpointTemplate,
@@ -388,6 +390,8 @@ export const eject = async (
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   const stagedDir = "blume-staged";
+  const features = await clientFeaturesFor(project);
+  const languageIcons = await languageIconCssFor(project);
 
   const files: {
     path: string;
@@ -404,6 +408,8 @@ export const eject = async (
         context: relContext,
         examplesPath: "./src/generated/examples.ts",
         examplesThemePath: "./src/generated/examples.css",
+        features,
+        featuresPath: "./src/generated/features.ts",
         // No CLI publishes the runtime data modules in memory after eject, so
         // the config aliases each to the JSON snapshot written below.
         generatedModulesDir: "./src/generated",
@@ -427,7 +433,6 @@ export const eject = async (
       // Never clobber a hand-tuned tsconfig; only write ours if none exists.
       skipIfExists: true,
     },
-    { content: envTemplate(), path: join(srcDir, "env.d.ts") },
     {
       content: contentConfigTemplate({
         config,
@@ -478,6 +483,7 @@ export const eject = async (
     {
       content: tailwindEntryTemplate({
         configTokens: buildThemeCss(config.theme),
+        languageIcons,
         // Relative paths from src/generated/app.css keep the ejected app
         // portable; the blume glob resolves the real install location when
         // the package is hoisted out of the project's own node_modules.
@@ -560,11 +566,18 @@ export const eject = async (
     });
   }
 
-  // The provider-specific client loader behind the `blume:search-client` alias.
-  files.push({
-    content: searchClientTemplate(config),
-    path: join(genDir, "search-client.ts"),
-  });
+  // The client-feature loaders behind the `blume:features` alias, and the
+  // provider-specific client loader behind `blume:search-client`.
+  files.push(
+    {
+      content: featuresTemplate(features),
+      path: join(genDir, "features.ts"),
+    },
+    {
+      content: searchClientTemplate(config),
+      path: join(genDir, "search-client.ts"),
+    }
+  );
 
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);

package/src/theme/entry.ts

@@ -20,6 +20,8 @@ interface TailwindEntryOptions {
   userTheme: string;
   /** Twoslash rich-renderer styles (for fences with the `twoslash` meta). */
   twoslashCss?: string;
+  /** The code-block language icon rules (`languageIconCss`), if any. */
+  languageIcons?: string;
 }
 
 /** Dark mode is driven by `data-theme` on the root element (both sheets). */
@@ -244,6 +246,31 @@ ${THEME_MAPPING}
   unicode-bidi: isolate;
 }
 
+/* The sidebar's rows. A docs site renders every sidebar row on every page,
+   so a large site's HTML is mostly this markup — one utility per row kind
+   instead of the dozen classes each expands to keeps every page (and the
+   build's HTML output) small. Kept in sync with NavTree.astro: a page row,
+   a page-mode group's drill-in button, a collapsible group's summary and
+   the link inside it, and a flat group's heading and the link inside it. */
+@utility blume-nav-link {
+  @apply block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:font-medium aria-[current=page]:text-foreground;
+}
+@utility blume-nav-drill {
+  @apply flex w-full items-center gap-2 rounded-[0.65rem] px-2.5 py-1.5 text-left font-medium text-foreground text-sm transition-colors hover:bg-muted;
+}
+@utility blume-nav-summary {
+  @apply flex cursor-pointer list-none items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden;
+}
+@utility blume-nav-summary-link {
+  @apply -my-1 flex flex-1 items-center gap-1.5 rounded py-1 transition-colors aria-[current=page]:text-foreground aria-[current=page]:font-semibold;
+}
+@utility blume-nav-heading {
+  @apply mb-2 flex items-center gap-1.5 px-2.5 font-medium text-foreground text-sm;
+}
+@utility blume-nav-heading-link {
+  @apply -ml-1 flex flex-1 items-center gap-1.5 rounded-[0.65rem] px-1 py-0.5 text-foreground transition-colors hover:bg-muted aria-[current=page]:bg-muted;
+}
+
 /* Theme Tailwind Typography (prose) with Blume tokens. */
 .prose {
   --tw-prose-body: var(--blume-foreground);
@@ -459,15 +486,17 @@ blume-diff {
    CodeBlock (no title) never gets data-language, so without this gate the
    absolutely-positioned icon would overlap the first code line. Fenced code
    and titled blocks always have a header, so the icon shows there. */
-.blume-lang-icon {
-  display: none;
-}
-
-.prose > :where(pre[data-language][data-icon]) > .blume-lang-icon {
-  color: var(--blume-muted-foreground);
-  display: block;
+.prose > :where(pre[data-language][data-icon])::after {
+  content: "";
   height: 0.875rem;
   left: 1rem;
+  -webkit-mask-position: center;
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-size: contain;
+  mask-position: center;
+  mask-repeat: no-repeat;
+  mask-size: contain;
+  pointer-events: none;
   position: absolute;
   top: 0.875rem;
   width: 0.875rem;
@@ -477,6 +506,11 @@ blume-diff {
   padding-left: 2.5rem;
 }
 
+/* One mask rule per language the site's Markdown uses (see
+   markdown/language-icon.ts); the ::after above only gets a color and a mask
+   from these, so a block whose language has no rule paints nothing. */
+${options.languageIcons ?? ""}
+
 .prose :where(pre code) {
   background: transparent;
   border-radius: 0;

package/src/theme/fonts.ts

@@ -63,7 +63,14 @@ export type FontValue = string | RemoteFontConfig | LocalFontConfig;
 interface FontDef {
   category: FontCategory;
   family: string;
-  weights: number[];
+  /**
+   * Discrete weights, or one `"min..max"` range for a family Google Fonts
+   * serves as a variable font: the range loads the same variable file the
+   * discrete weights did, declared as one `@font-face` per style instead of
+   * one per weight (16 rules down to 4 for Inter on every page). The three
+   * static families in the table keep discrete weights.
+   */
+  weights: (number | string)[];
 }
 
 /** Resolved theme fonts (a validated value per role, all optional). */
@@ -96,22 +103,22 @@ const FALLBACKS = {
 
 /** Slug -> Google family + weights + fallback category. Keep keys alphabetical. */
 export const GOOGLE_FONTS = {
-  "dm-sans": { category: "sans", family: "DM Sans", weights: [400, 500, 700] },
+  "dm-sans": { category: "sans", family: "DM Sans", weights: ["400..700"] },
   figtree: {
     category: "sans",
     family: "Figtree",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
   "fira-code": {
     category: "mono",
     family: "Fira Code",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
-  geist: { category: "sans", family: "Geist", weights: [400, 500, 600, 700] },
+  geist: { category: "sans", family: "Geist", weights: ["400..700"] },
   "geist-mono": {
     category: "mono",
     family: "Geist Mono",
-    weights: [400, 500, 600],
+    weights: ["400..600"],
   },
   "ibm-plex-mono": {
     category: "mono",
@@ -121,81 +128,81 @@ export const GOOGLE_FONTS = {
   "ibm-plex-sans": {
     category: "sans",
     family: "IBM Plex Sans",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
   "ibm-plex-serif": {
     category: "serif",
     family: "IBM Plex Serif",
     weights: [400, 500, 600],
   },
-  inter: { category: "sans", family: "Inter", weights: [400, 500, 600, 700] },
+  inter: { category: "sans", family: "Inter", weights: ["400..700"] },
   "inter-tight": {
     category: "sans",
     family: "Inter Tight",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
   "jetbrains-mono": {
     category: "mono",
     family: "JetBrains Mono",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
-  lora: { category: "serif", family: "Lora", weights: [400, 500, 600, 700] },
+  lora: { category: "serif", family: "Lora", weights: ["400..700"] },
   manrope: {
     category: "sans",
     family: "Manrope",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
   merriweather: {
     category: "serif",
     family: "Merriweather",
-    weights: [400, 700],
+    weights: ["400..700"],
   },
   "open-sans": {
     category: "sans",
     family: "Open Sans",
-    weights: [400, 600, 700],
+    weights: ["400..700"],
   },
   "playfair-display": {
     category: "serif",
     family: "Playfair Display",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
   "plus-jakarta-sans": {
     category: "sans",
     family: "Plus Jakarta Sans",
-    weights: [400, 500, 600, 700],
+    weights: ["400..700"],
   },
-  roboto: { category: "sans", family: "Roboto", weights: [400, 500, 700] },
+  roboto: { category: "sans", family: "Roboto", weights: ["400..700"] },
   "roboto-mono": {
     category: "mono",
     family: "Roboto Mono",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
   "source-code-pro": {
     category: "mono",
     family: "Source Code Pro",
-    weights: [400, 500, 600],
+    weights: ["400..600"],
   },
   "source-sans-3": {
     category: "sans",
     family: "Source Sans 3",
-    weights: [400, 600, 700],
+    weights: ["400..700"],
   },
   "source-serif-4": {
     category: "serif",
     family: "Source Serif 4",
-    weights: [400, 600, 700],
+    weights: ["400..700"],
   },
   "space-grotesk": {
     category: "sans",
     family: "Space Grotesk",
-    weights: [400, 500, 700],
+    weights: ["400..700"],
   },
   "space-mono": { category: "mono", family: "Space Mono", weights: [400, 700] },
   "work-sans": {
     category: "sans",
     family: "Work Sans",
-    weights: [400, 500, 600],
+    weights: ["400..600"],
   },
 } satisfies Record<string, FontDef>;