blume 0.0.0 → 0.1.1

package/src/components/layout/toc-element.ts

@@ -0,0 +1,108 @@
+/**
+ * Client behaviour for the `<blume-toc>` custom element wrapping each "On this
+ * page" list. As the reader scrolls, it marks the link for the section currently
+ * in view with `aria-current="location"` — styled via Tailwind `aria-[current]`
+ * variants in RootLayout — giving the table of contents a live scrollspy.
+ *
+ * The active heading is chosen by rect (the last heading at or above a trigger
+ * line just below the sticky header), so it stays correct for sections taller
+ * than the viewport and at the bottom of the page. An IntersectionObserver is the
+ * cheap primary trigger — it only fires as headings cross the band near the top —
+ * and a passive, rAF-throttled scroll listener covers the one case it can't: a
+ * final section too short to push its heading past the trigger line.
+ *
+ * Imported for its side effect (registers the element) from RootLayout's script.
+ */
+
+interface TocEntry {
+  heading: HTMLElement;
+  link: HTMLAnchorElement;
+}
+
+// Matches the theme's `scroll-padding-top: 4.5rem`, so the highlighted heading
+// agrees with where a clicked anchor lands beneath the sticky header.
+const TRIGGER_OFFSET = 72;
+
+class BlumeToc extends HTMLElement {
+  #entries: TocEntry[] = [];
+  #observer: IntersectionObserver | null = null;
+  #current: HTMLAnchorElement | null = null;
+  #ticking = false;
+
+  connectedCallback() {
+    for (const link of this.querySelectorAll<HTMLAnchorElement>(
+      'a[href^="#"]'
+    )) {
+      const id = decodeURIComponent(link.hash.slice(1));
+      const heading = id
+        ? document.querySelector<HTMLElement>(`#${CSS.escape(id)}`)
+        : null;
+      if (heading) {
+        this.#entries.push({ heading, link });
+      }
+    }
+    if (this.#entries.length === 0) {
+      return;
+    }
+
+    this.#observer = new IntersectionObserver(() => this.#update(), {
+      rootMargin: `-${TRIGGER_OFFSET}px 0px -70% 0px`,
+      threshold: 0,
+    });
+    for (const { heading } of this.#entries) {
+      this.#observer.observe(heading);
+    }
+    window.addEventListener("scroll", this.#onScroll, { passive: true });
+    this.#update();
+  }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    window.removeEventListener("scroll", this.#onScroll);
+  }
+
+  #onScroll = () => {
+    if (this.#ticking) {
+      return;
+    }
+    this.#ticking = true;
+    requestAnimationFrame(() => {
+      this.#ticking = false;
+      this.#update();
+    });
+  };
+
+  #update() {
+    const active = this.#activeLink();
+    if (active === this.#current) {
+      return;
+    }
+    this.#current?.removeAttribute("aria-current");
+    active?.setAttribute("aria-current", "location");
+    this.#current = active;
+  }
+
+  #activeLink(): HTMLAnchorElement | null {
+    const scrolledToBottom =
+      window.innerHeight + window.scrollY >=
+      document.documentElement.scrollHeight - 2;
+    if (scrolledToBottom) {
+      return this.#entries.at(-1)?.link ?? null;
+    }
+
+    // Headings are in document order, so the last one whose top has reached the
+    // trigger line is the section currently being read; default to the first.
+    let active = this.#entries[0]?.link ?? null;
+    for (const { heading, link } of this.#entries) {
+      if (heading.getBoundingClientRect().top <= TRIGGER_OFFSET) {
+        active = link;
+      }
+    }
+    return active;
+  }
+}
+
+if (!customElements.get("blume-toc")) {
+  customElements.define("blume-toc", BlumeToc);
+}

package/src/core/bridge.ts

@@ -0,0 +1,92 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+import { loadMintlifyConfig } from "../migrate/mintlify/config.ts";
+import { mintlifyI18n } from "../migrate/mintlify/i18n.ts";
+import type { BlumeConfig } from "./schema.ts";
+
+/** A detected docs-tool config that Blume can serve without a migration. */
+export interface BridgeDetection {
+  /** Which foreign docs tool was detected. */
+  tool: "mintlify";
+  /** Absolute path of the detected config file (`docs.json`/`mint.json`). */
+  configFile: string;
+  /** A Blume config synthesized from the foreign config, ready to validate. */
+  raw: BlumeConfig;
+}
+
+const MINTLIFY_CONFIG_FILES = ["docs.json", "mint.json"];
+
+/**
+ * Detect a Mintlify project at `root` and synthesize an equivalent Blume config.
+ *
+ * "Bridge mode" lets a team swap `mintlify dev` for `blume dev` with no file
+ * changes: `docs.json` is translated to Blume config (`loadMintlifyConfig`) and
+ * its content block is rewired to a single `mintlify` content source, which
+ * transforms each MDX page to Blume idiom at scan time. The original
+ * `content.root`/`exclude` and `variables` move onto the source (Blume has no
+ * runtime variable substitution, so globals are inlined into content there).
+ *
+ * Returns `null` when no Mintlify config is present. Only called when no
+ * `blume.config.*` exists, so an explicit Blume config always takes precedence.
+ */
+export const detectMintlifyBridge = async (
+  root: string
+): Promise<BridgeDetection | null> => {
+  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join(root, name)).find(
+    (candidate) => existsSync(candidate)
+  );
+  if (!configFile) {
+    return null;
+  }
+
+  const config = await loadMintlifyConfig(root, configFile);
+
+  // i18n is derived from the raw spec (language dirs), mirroring the migrator.
+  const spec = JSON.parse(await readFile(configFile, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+  const i18n = mintlifyI18n(spec);
+  if (i18n) {
+    config.i18n = i18n;
+    // Language switching is handled by Blume i18n, not a nav selector.
+    if (config.navigation?.selectors) {
+      config.navigation.selectors = config.navigation.selectors.filter(
+        (selector) => selector.kind !== "language"
+      );
+    }
+  }
+
+  const variables = (config.variables as Record<string, string>) ?? {};
+  const root_ = config.content?.root ?? ".";
+  const exclude = config.content?.exclude ?? [];
+
+  return {
+    configFile,
+    raw: {
+      ...config,
+      content: {
+        // Mirror the excludes onto `content.exclude` too: the generated Astro
+        // `docs` collection globs `content.root` (here the project root) and
+        // must skip node_modules/snippets just like the source does.
+        exclude,
+        root: root_,
+        sources: [
+          {
+            configFile,
+            exclude,
+            root: root_,
+            type: "mintlify",
+            variables,
+          },
+        ],
+      },
+      // Globals are inlined into content by the source; drop the top-level copy.
+      variables: undefined,
+    },
+    tool: "mintlify",
+  };
+};

package/src/core/config.ts

@@ -0,0 +1,112 @@
+import { detectMintlifyBridge } from "./bridge.ts";
+import type { BridgeDetection } from "./bridge.ts";
+import { applyDeploymentEnv } from "./deployment-env.ts";
+import { BlumeError, diagnosticsFromZod } from "./diagnostics.ts";
+import { createModuleLoader } from "./load-module.ts";
+import { findConfigFile } from "./project.ts";
+import { blumeConfigSchema } from "./schema.ts";
+import type { BlumeConfig, ResolvedConfig } from "./schema.ts";
+import type { Diagnostic } from "./types.ts";
+
+/**
+ * Identity helper for authoring `blume.config.ts`. Exists for type inference
+ * and a stable future home for plugin hooks; it does not transform input.
+ */
+export const defineConfig = (config: BlumeConfig): BlumeConfig => config;
+
+/** Bridge mode info: a foreign docs tool Blume is serving without migrating. */
+export interface ConfigBridge {
+  tool: "mintlify";
+  /** Absolute path of the foreign config file (`docs.json`/`mint.json`). */
+  configFile: string;
+}
+
+/** Result of loading + validating a project config. */
+export interface ConfigLoadResult {
+  config: ResolvedConfig;
+  /** Absolute path of the config file used, or null when defaults were used. */
+  configFile: string | null;
+  /** Set when a foreign docs config (e.g. Mintlify) is being bridged. */
+  bridge: ConfigBridge | null;
+  diagnostics: Diagnostic[];
+}
+
+const importConfigModule = createModuleLoader();
+
+/**
+ * Load and validate the project config. When no config file exists, schema
+ * defaults produce a fully resolved config so the zero-boilerplate path works.
+ */
+export const loadConfig = async (
+  root: string,
+  /**
+   * Supplied only by `blume dev`: the local dev server URL, used as the
+   * `deployment.site` fallback when none is configured or detected. Builds
+   * never pass it, so production output can't end up pointing at localhost.
+   */
+  options: { devServerUrl?: string } = {}
+): Promise<ConfigLoadResult> => {
+  const configFile = findConfigFile(root);
+
+  // With no Blume config, a Mintlify `docs.json` activates bridge mode: serve
+  // the unconverted project by synthesizing config + a `mintlify` content source.
+  let bridge: BridgeDetection | null = null;
+  let raw: unknown = {};
+  if (configFile) {
+    try {
+      raw = await importConfigModule(configFile);
+    } catch (error) {
+      throw new BlumeError({
+        code: "BLUME_CONFIG_LOAD_FAILED",
+        file: configFile,
+        message: `Failed to load config: ${(error as Error).message}`,
+        severity: "error",
+      });
+    }
+  } else {
+    bridge = await detectMintlifyBridge(root);
+    if (bridge) {
+      ({ raw } = bridge);
+    }
+  }
+
+  const sourceFile = bridge?.configFile ?? configFile;
+  const parsed = blumeConfigSchema.safeParse(raw ?? {});
+  if (!parsed.success) {
+    const diagnostics = diagnosticsFromZod(parsed.error, {
+      code: "BLUME_CONFIG_INVALID",
+      file: sourceFile ?? undefined,
+    });
+    throw new BlumeError(
+      diagnostics[0] ?? {
+        code: "BLUME_CONFIG_INVALID",
+        file: sourceFile ?? undefined,
+        message: "Invalid Blume config.",
+        severity: "error",
+      }
+    );
+  }
+
+  // Resolve the canonical site URL, then SEO defaults that depend on it.
+  // Precedence: explicit config > platform env (Vercel/Netlify/Cloudflare, via
+  // applyDeploymentEnv) > the local dev server URL (dev only).
+  const config = applyDeploymentEnv(parsed.data);
+  const site = config.deployment.site ?? options.devServerUrl;
+
+  // OG images need an absolute `og:image`, so they default on once a site URL
+  // is known and off otherwise. An explicit `seo.og.enabled` always wins.
+  const ogEnabled = config.seo.og.enabled ?? Boolean(site);
+
+  return {
+    bridge: bridge
+      ? { configFile: bridge.configFile, tool: bridge.tool }
+      : null,
+    config: {
+      ...config,
+      deployment: { ...config.deployment, site },
+      seo: { ...config.seo, og: { ...config.seo.og, enabled: ogEnabled } },
+    },
+    configFile: sourceFile,
+    diagnostics: [],
+  };
+};

package/src/core/content.ts

@@ -0,0 +1,50 @@
+import type { ResolvedI18nConfig } from "./schema.ts";
+import { filesystemSource } from "./sources/filesystem.ts";
+import { normalizeEntry } from "./sources/normalize.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+
+// Re-export the shared parsing helpers from their new home so existing importers
+// (and tests) keep resolving them from `core/content.ts`.
+export {
+  extractHeadings,
+  extractLinks,
+  normalizeEntry,
+  slugify,
+} from "./sources/normalize.ts";
+
+/**
+ * Discover and normalize all content pages under a content root. Thin wrapper
+ * around the filesystem `ContentSource` + `normalizeEntry`, kept for callers and
+ * tests that scan a single directory directly.
+ */
+export const discoverContent = async (options: {
+  contentRoot: string;
+  include: string[];
+  exclude: string[];
+  defaultType: string;
+  i18n?: ResolvedI18nConfig;
+}): Promise<{ pages: PageRecord[]; diagnostics: Diagnostic[] }> => {
+  const source = filesystemSource({
+    exclude: options.exclude,
+    include: options.include,
+    name: "filesystem",
+    projectRoot: options.contentRoot,
+    root: options.contentRoot,
+  });
+
+  const { entries, diagnostics: loadDiagnostics } = await source.load();
+  const pages: PageRecord[] = [];
+  const diagnostics: Diagnostic[] = [...loadDiagnostics];
+
+  for (const entry of entries) {
+    const normalized = normalizeEntry(entry, {
+      defaultType: options.defaultType,
+      i18n: options.i18n,
+      source: { name: source.name, prefix: source.prefix, staged: false },
+    });
+    pages.push(...normalized.pages);
+    diagnostics.push(...normalized.diagnostics);
+  }
+
+  return { diagnostics, pages };
+};

package/src/core/data.ts

@@ -0,0 +1,128 @@
+import type { UIStrings } from "./i18n-ui.ts";
+import type { ResolvedConfig, SearchProvider } from "./schema.ts";
+import type { Navigation, RouteAlternate } from "./types.ts";
+
+/**
+ * The shape of the `blume:data` virtual module — the resolved, serializable
+ * snapshot of a site that custom `.astro` pages read with
+ * `import data from "blume:data"`. `buildRuntimeData` (`astro/generate.ts`)
+ * produces exactly this object and annotates it with {@link BlumeData}, so the
+ * documented type and the emitted JSON stay in lockstep.
+ */
+
+/** Resolved site logo: an inlined SVG, or light/dark image URLs. */
+export interface BlumeLogo {
+  svg?: string;
+  light?: string;
+  dark?: string;
+  alt: string;
+  href: string;
+}
+
+/** A favicon or apple-touch-icon: a link href plus an optional MIME type. */
+export interface BlumeFavicon {
+  href: string;
+  type?: string;
+}
+
+/** Announcement banner, normalized from its config (string shorthand or object). */
+export interface BlumeBanner {
+  content: string;
+  link?: { href: string; text: string };
+  dismissible: boolean;
+  /** Dismissal key: the configured id, else the content itself. */
+  key: string;
+}
+
+/** A generated syndication feed surfaced in the UI. */
+export interface BlumeFeed {
+  href: string;
+  title: string;
+}
+
+/** One configured locale, as exposed to the runtime. */
+export interface BlumeDataLocale {
+  code: string;
+  dir: "ltr" | "rtl";
+  label: string;
+}
+
+/** Resolved i18n settings; `null` when the site is single-locale. */
+export interface BlumeDataI18n {
+  defaultLocale: string;
+  /** Locale whose content renders for a missing translation; `null` disables it. */
+  fallbackLocale: string | null;
+  hideDefaultLocalePrefix: boolean;
+  locales: BlumeDataLocale[];
+}
+
+/** A single content route, with the metadata custom pages can read. */
+export interface BlumeRoute {
+  /** Locales this logical page is translated into (excludes fallbacks). */
+  alternates: RouteAlternate[];
+  /** Astro collection the entry renders through (`"docs"` | `"staged"`). */
+  collection: string;
+  draft: boolean;
+  /** "Edit this page" URL, or `null` when no repo/source provides one. */
+  editUrl: string | null;
+  /** Astro collection entry id (for `getEntry`/`getCollection`); matches `id`. */
+  entryId: string;
+  /** True when this route renders fallback content for a missing translation. */
+  fallback: boolean;
+  hidden: boolean;
+  id: string;
+  /** Whether the page is part of the search index. */
+  indexable: boolean;
+  /** ISO "last updated" date when the feature is on, else `null`. */
+  lastModified: string | null;
+  /** Resolved locale code (the default locale when not under i18n). */
+  locale: string;
+  path: string;
+  title: string;
+}
+
+/** Site-wide settings derived from `blume.config` — the `config` field of {@link BlumeData}. */
+export interface BlumeDataConfig {
+  analytics: NonNullable<ResolvedConfig["analytics"]> | null;
+  /** Apple touch icon, or `null` when none is configured/detected. */
+  appleIcon: BlumeFavicon | null;
+  banner: BlumeBanner | null;
+  /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
+  codeWrap: boolean;
+  description: string | undefined;
+  favicon: BlumeFavicon;
+  feedback: boolean;
+  i18n: BlumeDataI18n | null;
+  /** `markdown.imageZoom`: click-to-zoom content images. */
+  imageZoom: boolean;
+  logo: BlumeLogo | null;
+  /** Hosted MCP server, or `null` when MCP is off. */
+  mcp: { name: string; route: string } | null;
+  /** Open Graph image generation. */
+  og: { enabled: boolean };
+  /** Repository URL for header/edit links, or `null`. */
+  repoUrl: string | null;
+  search: { enabled: boolean; provider: SearchProvider };
+  /** Deployment site URL, or `null` when none is configured/detected. */
+  site: string | null;
+  structuredData: boolean;
+  theme: ResolvedConfig["theme"];
+  title: string;
+}
+
+/** The `blume:data` module a Blume site's custom pages import. */
+export interface BlumeData {
+  config: BlumeDataConfig;
+  feeds: BlumeFeed[];
+  /** CSS variable names for the configured fonts (Astro `<Font>` integration). */
+  fontCssVars: string[];
+  /** Sidebar + tab tree for the default locale. */
+  navigation: Navigation;
+  /** Per-locale navigation trees, keyed by locale code (empty without i18n). */
+  navigationByLocale: Record<string, Navigation>;
+  routes: BlumeRoute[];
+  /** Resolved UI strings for the default locale. */
+  ui: UIStrings;
+  /** Per-locale UI strings, keyed by locale code (empty without i18n). */
+  uiByLocale: Record<string, UIStrings>;
+}

package/src/core/define-components.ts

@@ -0,0 +1,34 @@
+import type { HydrationMode } from "./schema.ts";
+
+/**
+ * A reference to a component. Either an imported component (preferred, for type
+ * safety) or a string path resolved relative to the project root.
+ */
+export type ComponentReference = unknown | string;
+
+/** An interactive component plus its hydration strategy. */
+export interface IslandDescriptor {
+  component: ComponentReference;
+  client: HydrationMode;
+  /** Required when `client` is `"media"`. */
+  media?: string;
+}
+
+/** A component override: a static component or a hydrated island. */
+export type ComponentOverride = ComponentReference | IslandDescriptor;
+
+/** User-authored component overrides, grouped by surface. */
+export interface ComponentOverrides {
+  /** MDX component map overrides (`Callout`, `Card`, ...). */
+  mdx?: Record<string, ComponentOverride>;
+  /** Layout slot overrides (`Header`, `Sidebar`, `Search`, ...). */
+  layout?: Record<string, ComponentOverride>;
+}
+
+/**
+ * Identity helper for authoring `components.ts`. Provides type inference and a
+ * stable home for future normalization; it does not transform input.
+ */
+export const defineComponents = (
+  overrides: ComponentOverrides
+): ComponentOverrides => overrides;

package/src/core/define-meta.ts

@@ -0,0 +1,20 @@
+import type { FolderMeta } from "./schema.ts";
+
+/** A function that computes folder meta, optionally asynchronously. */
+export type FolderMetaFactory = () => FolderMeta | Promise<FolderMeta>;
+
+/** What a `meta.ts` may default-export: a plain object or a (async) factory. */
+export type FolderMetaDefinition = FolderMeta | FolderMetaFactory;
+
+/**
+ * Identity helper for authoring a folder's `meta.ts`. Provides type inference;
+ * it does not transform input. Pass an object, or a function (sync or async)
+ * that returns one when you need to compute the meta:
+ *
+ * ```ts
+ * export default defineMeta({ title: "Guides", order: 2 });
+ * export default defineMeta(async () => ({ pages: await orderPages() }));
+ * ```
+ */
+export const defineMeta = (meta: FolderMetaDefinition): FolderMetaDefinition =>
+  meta;

package/src/core/deployment-env.ts

@@ -0,0 +1,73 @@
+import type { ResolvedConfig } from "./schema.ts";
+
+/** The deployment platforms Blume can infer from runtime/CI env vars. */
+type DeploymentAdapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
+
+interface Platform {
+  /** Astro adapter to use when building for server output on this platform. */
+  adapter: DeploymentAdapter;
+  /** True when the env indicates the build is running on this platform. */
+  detect: (env: NodeJS.ProcessEnv) => boolean;
+  /** Resolve the canonical site URL from the platform's env vars, or null. */
+  site: (env: NodeJS.ProcessEnv) => string | null;
+}
+
+/** Prefix a bare host with `https://`; pass values that are already absolute. */
+const toUrl = (value: string | undefined): string | null => {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  return /^https?:\/\//u.test(trimmed) ? trimmed : `https://${trimmed}`;
+};
+
+/**
+ * Platforms checked in order; the first whose `detect` matches wins. Site URLs
+ * prefer the stable production domain over per-deployment preview URLs so the
+ * inferred origin (sitemap, OG, RSS) stays put across deploys.
+ */
+const PLATFORMS: Platform[] = [
+  {
+    adapter: "vercel",
+    detect: (env) => Boolean(env.VERCEL),
+    site: (env) => toUrl(env.VERCEL_PROJECT_PRODUCTION_URL ?? env.VERCEL_URL),
+  },
+  {
+    adapter: "netlify",
+    detect: (env) => Boolean(env.NETLIFY),
+    site: (env) => toUrl(env.URL ?? env.DEPLOY_PRIME_URL ?? env.DEPLOY_URL),
+  },
+  {
+    adapter: "cloudflare",
+    detect: (env) => Boolean(env.CF_PAGES),
+    site: (env) => toUrl(env.CF_PAGES_URL),
+  },
+];
+
+/**
+ * Fill in `deployment.adapter` and `deployment.site` from platform env vars
+ * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit
+ * config always wins, and the adapter is only inferred for server output (it
+ * has no effect on static builds). Mirrors Astro's platform auto-detection so a
+ * project deployed to a known host gets a working canonical origin for free.
+ */
+export const applyDeploymentEnv = (
+  config: ResolvedConfig,
+  env: NodeJS.ProcessEnv = process.env
+): ResolvedConfig => {
+  const platform = PLATFORMS.find((candidate) => candidate.detect(env));
+  if (!platform) {
+    return config;
+  }
+
+  const { deployment } = config;
+  const adapter =
+    deployment.adapter ??
+    (deployment.output === "server" ? platform.adapter : null);
+  const site = deployment.site ?? platform.site(env) ?? undefined;
+
+  if (adapter === deployment.adapter && site === deployment.site) {
+    return config;
+  }
+  return { ...config, deployment: { ...deployment, adapter, site } };
+};