blume 0.6.7 → 0.7.0

package/src/registry/eject.ts

@@ -24,6 +24,7 @@ import {
   envTemplate,
   exampleMapTemplate,
   exampleWrapperTemplate,
+  examplesPageTemplate,
   exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
@@ -45,11 +46,14 @@ import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { servesStaticIndex } from "../search/providers.ts";
-import { tailwindEntryTemplate } from "../theme/entry.ts";
+import {
+  examplesEntryTemplate,
+  tailwindEntryTemplate,
+} from "../theme/entry.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 
-const POSIX = (path: string): string => path.split("\\").join("/");
+const toPosix = (path: string): string => path.split("\\").join("/");
 
 /** The `blume:openapi` payload for the ejected app (`{}` when none). */
 const ejectOpenApiData = (project: BlumeProject): unknown => {
@@ -86,6 +90,40 @@ const askFiles = async (
   return files;
 };
 
+/** Contents of the configured `examples.css`, or `""` when unset/absent. */
+const readExamplesCss = (
+  root: string,
+  css: string | undefined
+): Promise<string> =>
+  css && existsSync(join(root, css))
+    ? readFile(join(root, css), "utf-8")
+    : Promise.resolve("");
+
+/**
+ * The per-example preview route `<Component />` iframes embed, nested under
+ * `basePath` so it stays reachable behind a proxy that only forwards the
+ * base. Empty when the project has no examples.
+ */
+const examplesPreviewFiles = (
+  srcDir: string,
+  basePath: string,
+  hasExamples: boolean
+): { content: string; path: string }[] =>
+  hasExamples
+    ? [
+        {
+          content: examplesPageTemplate(),
+          path: join(
+            srcDir,
+            "pages",
+            ...basePath.split("/").filter(Boolean),
+            "blume-examples",
+            "[...path].astro"
+          ),
+        },
+      ]
+    : [];
+
 /**
  * Promote the generated runtime into the project as an owned Astro app. After
  * eject the project has a normal `astro.config.mjs` and `src/`, the `blume` CLI
@@ -108,6 +146,7 @@ export const eject = async (root: string): Promise<string[]> => {
     needsReactRaw,
     usesMath,
     userTheme,
+    userExamplesCss,
     rawMarkdown,
     islands,
     examples,
@@ -118,9 +157,10 @@ export const eject = async (root: string): Promise<string[]> => {
     context.themeFile
       ? readFile(context.themeFile, "utf-8")
       : Promise.resolve(""),
+    readExamplesCss(root, config.examples.css),
     buildRawMarkdown(project),
     discoverIslands(root),
-    discoverExamples(root, config.examples),
+    discoverExamples(root, config.examples.source),
   ]);
   // Island/example frameworks drive which Astro renderers the ejected config
   // wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.
@@ -135,16 +175,16 @@ export const eject = async (root: string): Promise<string[]> => {
   // A project-relative context so generated files use portable paths.
   const relContext: ProjectContext = {
     ...context,
-    contentRoot: POSIX(relative(root, context.contentRoot)),
+    contentRoot: toPosix(relative(root, context.contentRoot)),
     outDir: ".",
     root: ".",
   };
 
   const componentsImport = context.componentsFile
-    ? `../../${POSIX(relative(root, context.componentsFile))}`
+    ? `../../${toPosix(relative(root, context.componentsFile))}`
     : null;
   const relPages = pages.map((page) => ({
-    entrypoint: POSIX(relative(root, page.entrypoint)),
+    entrypoint: toPosix(relative(root, page.entrypoint)),
     pattern: page.pattern,
   }));
 
@@ -168,6 +208,7 @@ export const eject = async (root: string): Promise<string[]> => {
         context: relContext,
         dataPath: "./src/generated/data.json",
         examplesPath: "./src/generated/examples.ts",
+        examplesThemePath: "./src/generated/examples.css",
         needsReact,
         needsSvelte,
         needsVue,
@@ -218,9 +259,19 @@ export const eject = async (root: string): Promise<string[]> => {
       path: join(genDir, "islands.ts"),
     },
     {
-      content: exampleMapTemplate(examples.examples),
+      content: exampleMapTemplate(examples.examples, config.basePath),
       path: join(genDir, "examples.ts"),
     },
+    {
+      // The isolated Tailwind entry for `<Component />` preview frames.
+      // Relative sources keep the ejected app portable.
+      content: examplesEntryTemplate({
+        configTokens: buildThemeCss(config.theme),
+        sources: ["../../**/*.{astro,jsx,svelte,ts,tsx,vue}"],
+        userCss: userExamplesCss,
+      }),
+      path: join(genDir, "examples.css"),
+    },
     {
       content: tailwindEntryTemplate({
         configTokens: buildThemeCss(config.theme),
@@ -345,7 +396,12 @@ export const eject = async (root: string): Promise<string[]> => {
     ...examples.examples.map((example) => ({
       content: exampleWrapperTemplate(example),
       path: join(genDir, "examples", `${exampleSlug(example.path)}.astro`),
-    }))
+    })),
+    ...examplesPreviewFiles(
+      srcDir,
+      config.basePath,
+      examples.examples.length > 0
+    )
   );
 
   // Materialize staged source bodies under `<root>/blume-staged/<source>/<ref>`,

package/src/search/build.ts

@@ -15,6 +15,9 @@ export const buildSearchIndex = async (outDir: string): Promise<number> => {
     throw new Error("Failed to create Pagefind index.");
   }
 
+  // These awaits are strictly ordered, not independent: the directory must be
+  // indexed before its files are written, and the index closed only after.
+  // oxlint-disable-next-line react-doctor/async-parallel
   const result = await index.addDirectory({ path: outDir });
   await index.writeFiles({ outputPath: join(outDir, "pagefind") });
   await pagefind.close();

package/src/search/documents.ts

@@ -65,9 +65,9 @@ const toPlainText = (markdown: string): string => {
   for (const match of withoutBlocks.matchAll(INLINE_CODE)) {
     const start = match.index ?? 0;
     pieces.push(
-      withoutBlocks.slice(cursor, start).replaceAll(HTML_OR_JSX, " ")
+      withoutBlocks.slice(cursor, start).replaceAll(HTML_OR_JSX, " "),
+      match.groups?.code ?? ""
     );
-    pieces.push(match.groups?.code ?? "");
     cursor = start + match[0].length;
   }
   pieces.push(withoutBlocks.slice(cursor).replaceAll(HTML_OR_JSX, " "));

package/src/search/sync/typesense.ts

@@ -40,10 +40,12 @@ export const syncTypesense = async (
   });
 
   const collection = client.collections(config.collection);
-  const exists = await collection
-    .retrieve()
-    .then(() => true)
-    .catch(() => false);
+  let exists = true;
+  try {
+    await collection.retrieve();
+  } catch {
+    exists = false;
+  }
   if (exists) {
     await collection.delete();
   }

package/src/seo/jsonld.ts

@@ -1,4 +1,8 @@
 import type { Crumb } from "../components/layout/nav-utils.ts";
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+
+/** A date-ish value carried through frontmatter (string, YAML Date, or unset). */
+type DateInput = string | Date | null;
 
 /** Inputs for a page's JSON-LD, all known at render time in RootLayout. */
 export interface StructuredDataInput {
@@ -9,12 +13,14 @@ export interface StructuredDataInput {
   description?: string;
   /** Page route, e.g. `/blog/post`. */
   route: string;
+  /** Deployment base (`import.meta.env.BASE_URL`); prefixed onto absolute URLs. */
+  base?: string;
   /** Content type — `blog` and `changelog` map to richer article types. */
   pageType?: string;
   /** Publish date (string or YAML Date); emitted as ISO `datePublished`. */
-  published?: string | Date | null;
+  published?: DateInput;
   /** Last-modified date; emitted as ISO `dateModified`. */
-  modified?: string | Date | null;
+  modified?: DateInput;
   /** BCP-47 language tag for `inLanguage`; defaults to `en`. */
   locale?: string;
   breadcrumbs: Crumb[];
@@ -31,7 +37,7 @@ const trimSlash = (value: string): string => value.replace(/\/$/u, "");
 const absolute = (base: string | null, path: string): string =>
   base ? `${base}${path}` : path;
 
-const toIso = (value: string | Date | null | undefined): string | undefined => {
+const toIso = (value: DateInput | undefined): string | undefined => {
   if (!value) {
     return;
   }
@@ -49,7 +55,11 @@ export const buildStructuredData = (
   input: StructuredDataInput
 ): Record<string, unknown> | null => {
   const base = input.siteUrl ? trimSlash(input.siteUrl) : null;
-  const pageUrl = absolute(base, input.route);
+  // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top
+  // so JSON-LD URLs match the served location.
+  const deployBase = normalizeBasePath(input.base);
+  const pageUrl = absolute(base, withBasePath(deployBase, input.route));
+  const rootUrl = absolute(base, deployBase);
   const graph: Record<string, unknown>[] = [];
 
   if (base) {
@@ -57,7 +67,7 @@ export const buildStructuredData = (
       "@id": `${base}#website`,
       "@type": "WebSite",
       name: input.siteName,
-      url: base,
+      url: rootUrl,
     });
   }
 
@@ -98,7 +108,7 @@ export const buildStructuredData = (
             position: index + 1,
           };
           if (crumb.route) {
-            item.item = absolute(base, crumb.route);
+            item.item = absolute(base, withBasePath(deployBase, crumb.route));
           }
           return item;
         }),

package/src/theme/entry.ts

@@ -12,25 +12,16 @@ interface TailwindEntryOptions {
   twoslashCss?: string;
 }
 
+/** Dark mode is driven by `data-theme` on the root element (both sheets). */
+const DARK_VARIANT = `/* Dark mode is driven by data-theme on the <html> element. */
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));`;
+
 /**
- * Build the single Tailwind v4 entry stylesheet for the generated runtime.
- *
- * Everything flows through one Tailwind-processed file so utilities are
- * generated and design tokens cascade deterministically:
- * base defaults -> config tokens -> user theme.css.
+ * The default `--blume-*` design tokens (light + dark), shared by the app
+ * sheet and the isolated example-preview sheet so previews inherit the site's
+ * palette by default.
  */
-export const tailwindEntryTemplate = (options: TailwindEntryOptions): string =>
-  `/* Generated by Blume. Do not edit. */
-@import "tailwindcss";
-@plugin "@tailwindcss/typography";
-
-/* Scan Blume's components and the user's project for utility classes. */
-${options.sources.map((source) => `@source "${source}";`).join("\n")}
-
-/* Dark mode is driven by data-theme on the <html> element. */
-@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
-
-:root {
+const TOKEN_DEFAULTS = `:root {
   --blume-background: oklch(1 0 0);
   --blume-background-image: none;
   --blume-background-image-repeat: no-repeat;
@@ -108,9 +99,15 @@ ${options.sources.map((source) => `@source "${source}";`).join("\n")}
   --blume-code-remove-border: oklch(0.7 0.2 22 / 0.7);
   --blume-code-word: oklch(0.7 0.14 255 / 0.22);
   --blume-code-word-border: oklch(0.7 0.14 255 / 0.55);
-}
+}`;
 
-@theme inline {
+/**
+ * Tailwind theme mapping from `--blume-*` tokens to utility-facing names
+ * (`bg-background`, `border-border`, `rounded-blume`, the font stacks).
+ * Shared by both sheets so example code written against Blume's utility
+ * vocabulary renders identically inside the isolated preview frame.
+ */
+const THEME_MAPPING = `@theme inline {
   --color-background: var(--blume-background);
   --color-foreground: var(--blume-foreground);
   --color-muted: var(--blume-muted);
@@ -125,7 +122,28 @@ ${options.sources.map((source) => `@source "${source}";`).join("\n")}
   --font-sans: var(--blume-font-body);
   --font-mono: var(--blume-font-mono);
   --font-display: var(--blume-font-display);
-}
+}`;
+
+/**
+ * Build the single Tailwind v4 entry stylesheet for the generated runtime.
+ *
+ * Everything flows through one Tailwind-processed file so utilities are
+ * generated and design tokens cascade deterministically:
+ * base defaults -> config tokens -> user theme.css.
+ */
+export const tailwindEntryTemplate = (options: TailwindEntryOptions): string =>
+  `/* Generated by Blume. Do not edit. */
+@import "tailwindcss";
+@plugin "@tailwindcss/typography";
+
+/* Scan Blume's components and the user's project for utility classes. */
+${options.sources.map((source) => `@source "${source}";`).join("\n")}
+
+${DARK_VARIANT}
+
+${TOKEN_DEFAULTS}
+
+${THEME_MAPPING}
 
 @layer base {
   /* Nothing refuses to shrink below its intrinsic content width. This global
@@ -670,3 +688,50 @@ ${options.twoslashCss ?? ""}
 ${options.configTokens}
 ${options.userTheme}
 `;
+
+interface ExamplesEntryOptions {
+  /** Config-derived token overrides (`:root { --blume-accent: ... }`). */
+  configTokens: string;
+  /** Globs to scan for utility classes (example files and their imports). */
+  sources: string[];
+  /** Raw contents of the configured `examples.css`, if any. */
+  userCss: string;
+}
+
+/**
+ * Build the Tailwind entry for `<Component />` preview frames. Each example
+ * renders in its own iframe so none of the app sheet above — prose typography,
+ * component chrome, base overrides — can reach it. This sheet provides only
+ * what an example needs to look like it does in an app: Tailwind (preflight +
+ * utilities scanned from the example sources), the `--blume-*` tokens and
+ * their utility mapping (so `bg-background`-style classes keep working and
+ * previews follow the site palette by default), and the user's example CSS
+ * (shadcn variables, `@theme` mappings, custom styles) last so it wins.
+ */
+export const examplesEntryTemplate = (options: ExamplesEntryOptions): string =>
+  `/* Generated by Blume. Do not edit. */
+@import "tailwindcss";
+
+/* Scan the example files and the project sources they import. */
+${options.sources.map((source) => `@source "${source}";`).join("\n")}
+
+${DARK_VARIANT}
+
+${TOKEN_DEFAULTS}
+
+${THEME_MAPPING}
+
+/* Frame defaults: readable text in both modes, transparent so the docs pane's
+   surface shows through. Base layer, so any user/example CSS wins. */
+@layer base {
+  body {
+    background: transparent;
+    color: var(--blume-foreground);
+  }
+}
+
+/* Token overrides: config first, then the configured examples css (highest
+   priority) — the place for shadcn variables and other component tokens. */
+${options.configTokens}
+${options.userCss}
+`;