blume 0.7.0 → 0.8.0

package/src/cli/init/questions.ts

@@ -0,0 +1,158 @@
+import { basename, resolve } from "pathe";
+
+import {
+  detectPackageManager,
+  titleize,
+  validateContentDir,
+} from "./scaffold.ts";
+import type {
+  InitAnswers,
+  PackageManager,
+  SourceKind,
+  Template,
+} from "./scaffold.ts";
+
+/** One prompt option: value plus display label and optional hint. */
+interface PromptOption<Value> {
+  hint?: string;
+  label: string;
+  value: Value;
+}
+
+/**
+ * The prompt surface `collectAnswers` needs — structurally satisfied by the
+ * `@clack/prompts` module itself, and by plain fakes in tests. Every prompt
+ * resolves to a cancel symbol when the user aborts.
+ */
+export interface Prompter {
+  multiselect: (opts: {
+    initialValues?: SourceKind[];
+    message: string;
+    options: PromptOption<SourceKind>[];
+    required?: boolean;
+  }) => Promise<SourceKind[] | symbol>;
+  select: (opts: {
+    message: string;
+    options: PromptOption<Template>[];
+  }) => Promise<Template | symbol>;
+  text: (opts: {
+    defaultValue?: string;
+    initialValue?: string;
+    message: string;
+    placeholder?: string;
+    validate?: (value: string | undefined) => string | undefined;
+  }) => Promise<string | symbol>;
+}
+
+/** Flag values the user passed explicitly; each one skips its question. */
+export interface InitFlags {
+  contentDir?: string;
+  directory?: string;
+  packageManager?: PackageManager;
+  template?: Template;
+}
+
+const cancelled = (value: unknown): value is symbol =>
+  typeof value === "symbol";
+
+/**
+ * Run the interactive init flow, returning the collected answers or `null`
+ * when the user cancels. All questions run before anything is written, so a
+ * cancel never leaves a partial scaffold behind.
+ */
+export const collectAnswers = async (
+  prompter: Prompter,
+  flags: InitFlags,
+  defaults: { cwd: string; userAgent?: string }
+): Promise<InitAnswers | null> => {
+  const directory =
+    flags.directory ??
+    (await prompter.text({
+      defaultValue: ".",
+      message: "Where should we create your project?",
+      placeholder: "./my-docs",
+    }));
+  if (cancelled(directory)) {
+    return null;
+  }
+
+  const root = resolve(defaults.cwd, directory);
+  const title = await prompter.text({
+    initialValue: titleize(basename(root)),
+    message: "What's your docs site called?",
+    validate: (value) =>
+      value?.trim() ? undefined : "Give your docs site a name.",
+  });
+  if (cancelled(title)) {
+    return null;
+  }
+
+  const template =
+    flags.template ??
+    (await prompter.select({
+      message: "Which template?",
+      options: [
+        { hint: "Markdown docs site", label: "docs", value: "docs" },
+        { hint: "OpenAPI reference at /api", label: "api", value: "api" },
+        { hint: "SDK docs with an install page", label: "sdk", value: "sdk" },
+        {
+          hint: "Docs plus a changelog tab",
+          label: "changelog",
+          value: "changelog",
+        },
+      ],
+    }));
+  if (cancelled(template)) {
+    return null;
+  }
+
+  const picked = await prompter.multiselect({
+    initialValues: ["filesystem"],
+    message: "Where does your content live?",
+    options: [
+      { hint: "Local .mdx files", label: "filesystem", value: "filesystem" },
+      {
+        hint: "Changelog from GitHub Releases",
+        label: "github-releases",
+        value: "github-releases",
+      },
+      { hint: "A Notion database", label: "notion", value: "notion" },
+      { hint: "A Sanity dataset", label: "sanity", value: "sanity" },
+      {
+        hint: "MDX fetched from a GitHub repo",
+        label: "mdx-remote",
+        value: "mdx-remote",
+      },
+    ],
+    required: false,
+  });
+  if (cancelled(picked)) {
+    return null;
+  }
+  // No selection desugars to the implicit local source, same as the schema.
+  const sources: SourceKind[] = picked.length === 0 ? ["filesystem"] : picked;
+
+  let contentDir = flags.contentDir ?? "docs";
+  if (flags.contentDir === undefined && sources.includes("filesystem")) {
+    const answer = await prompter.text({
+      defaultValue: "docs",
+      message: "Content directory?",
+      placeholder: "docs",
+      validate: (value) => validateContentDir(root, value || "docs"),
+    });
+    if (cancelled(answer)) {
+      return null;
+    }
+    contentDir = answer;
+  }
+
+  return {
+    contentDir,
+    directory,
+    packageManager:
+      flags.packageManager ?? detectPackageManager(defaults.userAgent),
+    sources,
+    template,
+    title,
+  };
+};

package/src/cli/init/scaffold.ts

@@ -0,0 +1,380 @@
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+
+import { basename, dirname, isAbsolute, join, relative } from "pathe";
+
+import { blumePackageJson, toPackageName } from "../../core/package-json.ts";
+
+export const TEMPLATES = ["docs", "api", "sdk", "changelog"] as const;
+export type Template = (typeof TEMPLATES)[number];
+
+export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+
+/** The content-source kinds `init` can scaffold a config block for. */
+export const SOURCE_KINDS = [
+  "filesystem",
+  "github-releases",
+  "notion",
+  "sanity",
+  "mdx-remote",
+] as const;
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+
+/** Everything the scaffolder needs, whether prompted or derived from flags. */
+export interface InitAnswers {
+  contentDir: string;
+  /** Target directory as the user gave it (`.` = current directory). */
+  directory: string;
+  packageManager: PackageManager;
+  sources: SourceKind[];
+  template: Template;
+  title: string;
+}
+
+/** One file the scaffold plan will write; `path` is absolute. */
+export interface ScaffoldFile {
+  content: string;
+  path: string;
+}
+
+/** Log sink for scaffold output — satisfied by both consola and clack's `log`. */
+export interface ScaffoldLog {
+  info: (message: string) => void;
+  success: (message: string) => void;
+}
+
+/** A starter: a config fragment plus seed content files (paths relative to root). */
+interface Starter {
+  configExtra: string;
+  files: (contentDir: string) => { content: string; path: string }[];
+}
+
+const page = (title: string, description: string, body: string): string =>
+  `---\ntitle: ${title}\ndescription: ${description}\n---\n\n${body}\n`;
+
+export const STARTERS: Record<Template, Starter> = {
+  api: {
+    configExtra: `
+  openapi: {
+    enabled: true,
+    route: "/api",
+    sources: [
+      {
+        label: "Petstore",
+        spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+      },
+    ],
+  },`,
+    files: (dir) => [
+      {
+        content: page(
+          "API Reference",
+          "Explore the API.",
+          "# API Reference\n\nYour OpenAPI spec renders at [`/api`](/api). Point `openapi.sources` at your own spec in `blume.config.ts`."
+        ),
+        path: join(dir, "index.mdx"),
+      },
+    ],
+  },
+  changelog: {
+    configExtra: `
+  navigation: {
+    tabs: [
+      { label: "Docs", path: "/" },
+      { label: "Changelog", path: "/changelog" },
+    ],
+  },`,
+    files: (dir) => [
+      {
+        content: page(
+          "Introduction",
+          "Welcome to your new Blume docs.",
+          "# Introduction\n\nWrite your docs here, and log releases under `changelog/`."
+        ),
+        path: join(dir, "index.mdx"),
+      },
+      {
+        content: `---\ntitle: v1.0.0\ntype: changelog\ndate: 2026-01-01\n---\n\nThe first release. Edit \`${dir}/changelog/v1-0-0.mdx\` or add new entries beside it.\n`,
+        path: join(dir, "changelog", "v1-0-0.mdx"),
+      },
+    ],
+  },
+  docs: {
+    configExtra: "",
+    files: (dir) => [
+      {
+        content: page(
+          "Introduction",
+          "Welcome to your new Blume docs.",
+          `# Introduction\n\nWelcome to **Blume** — markdown-first docs powered by Astro and Vite.\n\nEdit \`${dir}/index.mdx\` to get started, then run \`blume dev\`.`
+        ),
+        path: join(dir, "index.mdx"),
+      },
+    ],
+  },
+  sdk: {
+    configExtra: "",
+    files: (dir) => [
+      {
+        content: page(
+          "Introduction",
+          "Get started with the SDK.",
+          "# Introduction\n\nInstall the SDK and make your first call. See [Installation](/installation)."
+        ),
+        path: join(dir, "index.mdx"),
+      },
+      {
+        content: page(
+          "Installation",
+          "Install the SDK.",
+          "# Installation\n\n```package-install\nyour-sdk\n```"
+        ),
+        path: join(dir, "installation.mdx"),
+      },
+    ],
+  },
+};
+
+/**
+ * Install + dev commands to print for the chosen package manager, plus the
+ * prefix that runs a locally installed bin (`exec`, e.g. `npx blume eject`) —
+ * dependency bins aren't on PATH, so a bare `blume …` hint would not run.
+ */
+export const commandsFor = (
+  pm: PackageManager
+): { build: string; dev: string; exec: string; install: string } => ({
+  // `bun build` invokes Bun's bundler, not the package.json `build` script —
+  // unlike `bun dev`, the script name is shadowed by a builtin subcommand.
+  build: pm === "npm" || pm === "bun" ? `${pm} run build` : `${pm} build`,
+  dev: pm === "npm" ? "npm run dev" : `${pm} dev`,
+  exec: { bun: "bunx", npm: "npx", pnpm: "pnpm exec", yarn: "yarn" }[pm],
+  install: `${pm} install`,
+});
+
+/**
+ * Derive the package manager from an npm user-agent string (the first
+ * `name/version` token of `npm_config_user_agent`), falling back to npm.
+ */
+export const detectPackageManager = (userAgent?: string): PackageManager => {
+  const name = userAgent?.split("/")[0] as PackageManager | undefined;
+  return name !== undefined && PACKAGE_MANAGERS.includes(name) ? name : "npm";
+};
+
+/**
+ * The content dir is joined into every scaffolded file path, so an absolute or
+ * `../`-escaping value would write outside the project. Returns an error
+ * message, or `undefined` when the dir is safe.
+ */
+export const validateContentDir = (
+  root: string,
+  dir: string
+): string | undefined =>
+  isAbsolute(dir) || relative(root, join(root, dir)).startsWith("..")
+    ? "Must be a relative path inside the project."
+    : undefined;
+
+/** Turn a directory name into a display title: `my-docs` → `My Docs`. */
+export const titleize = (raw: string): string => {
+  const words = raw
+    .replaceAll(/[-_.]+/gu, " ")
+    .split(/\s+/u)
+    .filter(Boolean);
+  return words.length === 0
+    ? "My Docs"
+    : words
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+};
+
+/** True when any selected source is remote (everything except `filesystem`). */
+const hasRemoteSource = (sources: SourceKind[]): boolean =>
+  sources.some((source) => source !== "filesystem");
+
+/**
+ * Config snippets for each remote source kind, with placeholder values to
+ * replace and comments naming the env var each source authenticates with.
+ */
+const sourceSnippetFor = (kind: Exclude<SourceKind, "filesystem">): string => {
+  switch (kind) {
+    case "github-releases": {
+      return `      // Changelog entries from GitHub Releases. Private repos read
+      // GITHUB_TOKEN from the environment.
+      {
+        type: "github-releases",
+        owner: "your-org",
+        repo: "your-repo",
+        prefix: "changelog",
+      },`;
+    }
+    case "notion": {
+      return `      // Pages from a Notion database. Reads NOTION_TOKEN from the environment.
+      {
+        type: "notion",
+        database: "your-database-id",
+        prefix: "notion",
+      },`;
+    }
+    case "sanity": {
+      return `      // Documents from a Sanity dataset. Private datasets read SANITY_TOKEN
+      // from the environment.
+      {
+        type: "sanity",
+        projectId: "your-project-id",
+        dataset: "production",
+        query: \`*[_type == "doc"]\`,
+        prefix: "sanity",
+      },`;
+    }
+    case "mdx-remote": {
+      return `      // MDX fetched from a GitHub repo. Private repos read GITHUB_TOKEN
+      // from the environment.
+      {
+        type: "mdx-remote",
+        github: { owner: "your-org", repo: "your-repo", path: "docs" },
+        prefix: "remote",
+      },`;
+    }
+    default: {
+      return kind satisfies never;
+    }
+  }
+};
+
+/**
+ * The `content` block for the generated config, or an empty string when the
+ * defaults (filesystem source, `docs` root) apply — keeping the default
+ * scaffold byte-identical to a config with no `content` key at all.
+ */
+const contentBlockFor = (answers: InitAnswers): string => {
+  const sources =
+    answers.sources.length === 0 ? ["filesystem" as const] : answers.sources;
+  if (!hasRemoteSource(sources)) {
+    return answers.contentDir === "docs"
+      ? ""
+      : `
+  content: {
+    root: ${JSON.stringify(answers.contentDir)},
+  },`;
+  }
+  // Explicit sources replace the implicit filesystem desugar, so the local
+  // content dir must be listed alongside the remote sources to stay included.
+  const entries = SOURCE_KINDS.filter((kind) => sources.includes(kind)).map(
+    (kind) =>
+      kind === "filesystem"
+        ? `      { type: "filesystem", root: ${JSON.stringify(answers.contentDir)} },`
+        : sourceSnippetFor(kind)
+  );
+  return `
+  content: {
+    sources: [
+${entries.join("\n")}
+    ],
+  },`;
+};
+
+/** The full `blume.config.ts` text for the chosen answers. */
+export const buildConfig = (
+  answers: InitAnswers
+): string => `import { defineConfig } from "blume";
+
+export default defineConfig({
+  title: ${JSON.stringify(answers.title)},
+  description: "Documentation powered by Blume.",${STARTERS[answers.template].configExtra}${contentBlockFor(answers)}
+});
+`;
+
+/** SDK dependencies required by the selected remote sources. */
+const extraDepsFor = (sources: SourceKind[]): Record<string, string> => ({
+  ...(sources.includes("notion") && { "@notionhq/client": "^2.2.15" }),
+  ...(sources.includes("sanity") && { "@sanity/client": "^6.21.0" }),
+});
+
+/** Every file `init` should write for the given answers, package.json first. */
+export const buildPlan = (
+  root: string,
+  answers: InitAnswers
+): ScaffoldFile[] => {
+  const files: ScaffoldFile[] = [
+    {
+      content: blumePackageJson(
+        toPackageName(basename(root)),
+        extraDepsFor(answers.sources)
+      ),
+      path: join(root, "package.json"),
+    },
+    { content: buildConfig(answers), path: join(root, "blume.config.ts") },
+  ];
+  // Seed pages only make sense when a local filesystem source will read them.
+  if (answers.sources.length === 0 || answers.sources.includes("filesystem")) {
+    files.push(
+      ...STARTERS[answers.template]
+        .files(answers.contentDir)
+        .map((file) => ({ ...file, path: join(root, file.path) }))
+    );
+  }
+  return files;
+};
+
+const writeFileSafe = async (
+  file: ScaffoldFile,
+  log: ScaffoldLog
+): Promise<boolean> => {
+  if (existsSync(file.path)) {
+    log.info(`Skipped existing ${file.path}`);
+    return false;
+  }
+  await mkdir(dirname(file.path), { recursive: true });
+  await writeFile(file.path, file.content, "utf-8");
+  log.success(`Created ${file.path}`);
+  return true;
+};
+
+/**
+ * Write the plan's files, skipping any that already exist. Reports whether a
+ * `package.json` was newly created (it decides the install next-step).
+ */
+export const applyPlan = async (
+  files: ScaffoldFile[],
+  log: ScaffoldLog
+): Promise<{ createdPackage: boolean }> => {
+  const created = await Promise.all(
+    files.map((file) => writeFileSafe(file, log))
+  );
+  const createdPackage = files.some(
+    (file, index) => created[index] && basename(file.path) === "package.json"
+  );
+  return { createdPackage };
+};
+
+/** Env vars the selected sources read, in a stable order. */
+const envVarsFor = (sources: SourceKind[]): string[] =>
+  [
+    ["GITHUB_TOKEN", ["github-releases", "mdx-remote"]] as const,
+    ["NOTION_TOKEN", ["notion"]] as const,
+    ["SANITY_TOKEN", ["sanity"]] as const,
+  ]
+    .filter(([, kinds]) => kinds.some((kind) => sources.includes(kind)))
+    .map(([envVar]) => envVar);
+
+/** The next-steps message: `cd` hint, install/dev commands, and token setup. */
+export const nextSteps = (
+  answers: InitAnswers,
+  createdPackage: boolean
+): string => {
+  const commands = commandsFor(answers.packageManager);
+  const lines: string[] = [];
+  if (answers.directory !== ".") {
+    lines.push(`cd ${answers.directory}`);
+  }
+  if (createdPackage) {
+    lines.push(commands.install);
+  }
+  lines.push(commands.dev);
+  const envVars = envVarsFor(answers.sources);
+  const auth =
+    envVars.length > 0
+      ? `\nSet ${envVars.join(" and ")} in .env.local so your sources can authenticate.\n`
+      : "";
+  return `Next steps:\n\n  ${lines.join("\n  ")}\n${auth}`;
+};

package/src/components/content/AccordionItem.astro

@@ -67,6 +67,22 @@ const accordionId = id ?? slugify(title);
   if (!state.__blumeAccordionHash) {
     state.__blumeAccordionHash = true;
 
+    // Repeated titles slug to the same id (e.g. several <Expandable> blocks all
+    // defaulting to "show-more"); suffix the later ones so ids stay unique. The
+    // first keeps the plain slug, so hash deep-links stay stable.
+    const dedupeAccordionIds = () => {
+      const seen = new Map<string, number>();
+      for (const accordion of document.querySelectorAll<HTMLElement>(
+        "[data-blume-accordion][id]"
+      )) {
+        const count = seen.get(accordion.id) ?? 0;
+        seen.set(accordion.id, count + 1);
+        if (count > 0) {
+          accordion.id = `${accordion.id}-${count + 1}`;
+        }
+      }
+    };
+
     const accordionFromHash = () => {
       const id = decodeURIComponent(window.location.hash.slice(1));
       if (!id) {
@@ -106,13 +122,16 @@ const accordionId = id ?? slugify(title);
       true
     );
 
+    const init = () => {
+      dedupeAccordionIds();
+      openHashAccordion();
+    };
+
     window.addEventListener("hashchange", openHashAccordion);
     if (document.readyState === "loading") {
-      document.addEventListener("DOMContentLoaded", openHashAccordion, {
-        once: true,
-      });
+      document.addEventListener("DOMContentLoaded", init, { once: true });
     } else {
-      openHashAccordion();
+      init();
     }
   }
 </script>

package/src/components/content/Badge.astro

@@ -97,10 +97,12 @@ const resolvedClass = astroClass ?? className;
 const colorClass = activeStroke
   ? strokeColorClass[colorName] ?? strokeColorClass.gray
   : filledColorClass[colorName] ?? filledColorClass.gray;
+// `color-mix` instead of appending a hex alpha byte, which breaks shorthand
+// hex (`#f00` + `20` is not a color); 12% matches the old `20` (32/255) alpha.
 const customStyle = customColor
   ? activeStroke
     ? `border-color:${customColor};color:${customColor}`
-    : `background:${customColor}20;color:${customColor}`
+    : `background:color-mix(in srgb, ${customColor} 12%, transparent);color:${customColor}`
   : undefined;
 ---
 

package/src/components/content/Card.astro

@@ -1,5 +1,7 @@
 ---
 import Icon from "../Icon.astro";
+import { withBase } from "../islands/base-path.ts";
+import { contentHref } from "./base-href.ts";
 
 interface Props {
   title?: string;
@@ -54,7 +56,7 @@ const variantClass = {
     isHorizontal ? "sm:flex" : "",
   ]}
   data-blume-card
-  href={href}
+  href={href === undefined ? undefined : contentHref(href)}
   rel={external ? "noreferrer" : undefined}
   target={external ? "_blank" : undefined}
 >
@@ -66,7 +68,7 @@ const variantClass = {
           "w-full object-cover",
           isHorizontal ? "sm:w-40 sm:shrink-0" : "max-h-48",
         ]}
-        src={img}
+        src={withBase(img)}
       />
     )
   }

package/src/components/content/Step.astro

@@ -26,7 +26,16 @@ const canRenderIcon =
   <span class:list={[markerClass, !canRenderIcon && "before:[content:counter(blume-step)]"]}>
     {canRenderIcon && <Icon name={icon} size={14} />}
   </span>
-  {title && <p class="mb-1.5 font-semibold">{title}</p>}
+  {
+    // Consumes the `titleSize` variables set by <Steps>; the fallbacks match
+    // its "p" default (and the prose-inherited sizing) so a bare <Step>
+    // renders identically.
+    title && (
+      <p class="mb-1.5 font-semibold text-[length:var(--blume-step-title-size,1rem)] leading-[var(--blume-step-title-line-height,1.75rem)]">
+        {title}
+      </p>
+    )
+  }
   <div class="[&>:first-child]:mt-0! [&>:last-child]:mb-0!">
     <slot />
   </div>

package/src/components/content/Tabs.astro

@@ -51,6 +51,10 @@ const hashEnabled = String(hash) !== "false";
     "w-full rounded-blume border border-border bg-background px-3 py-2 font-medium text-foreground text-sm";
   const SYNC_EVENT = "blume-tabs-change";
 
+  // Disambiguates generated trigger/panel ids when the same tab labels appear
+  // in several <Tabs> instances on one page.
+  let instanceCount = 0;
+
   const panelTitle = (panel: HTMLElement, index: number) =>
     panel.dataset.title ?? `Tab ${index + 1}`;
   const panelId = (panel: HTMLElement) => panel.dataset.tabId ?? panel.id;
@@ -119,7 +123,8 @@ const hashEnabled = String(hash) !== "false";
       if (this.dataset.dropdown === "true") {
         this.#select = document.createElement("select");
         this.#select.className = SELECT_CLASS;
-        this.#select.setAttribute("aria-label", "Select code example");
+        // Neutral default: tab sets aren't necessarily code examples.
+        this.#select.setAttribute("aria-label", "Select tab");
         panels.forEach((panel, index) => {
           const option = document.createElement("option");
           option.value = String(index);
@@ -131,6 +136,7 @@ const hashEnabled = String(hash) !== "false";
         });
         list.appendChild(this.#select);
       } else {
+        const instance = ++instanceCount;
         panels.forEach((panel, index) => {
           const trigger = document.createElement("button");
           trigger.type = "button";
@@ -138,9 +144,15 @@ const hashEnabled = String(hash) !== "false";
           trigger.className = TRIGGER_CLASS;
           appendTriggerContent(trigger, panel, index);
           trigger.tabIndex = index === 0 ? 0 : -1;
-          if (panel.id) {
-            trigger.setAttribute("aria-controls", panel.id);
+          // Wire tab and panel both ways. An author-supplied panel id is kept;
+          // otherwise derive unique ids from the label slug per instance.
+          const slug = panelId(panel) || `tab-${index + 1}`;
+          if (!panel.id) {
+            panel.id = `blume-tabpanel-${slug}-${instance}`;
           }
+          trigger.id = `blume-tab-${slug}-${instance}`;
+          trigger.setAttribute("aria-controls", panel.id);
+          panel.setAttribute("aria-labelledby", trigger.id);
           trigger.setAttribute(
             "aria-selected",
             index === 0 ? "true" : "false"