blume 0.0.0 → 0.1.0

package/src/markdown/index.ts

@@ -0,0 +1,159 @@
+import { satteri } from "@astrojs/markdown-satteri";
+import {
+  transformerMetaHighlight,
+  transformerNotationDiff,
+  transformerNotationFocus,
+  transformerNotationHighlight,
+  transformerNotationWordHighlight,
+} from "@shikijs/transformers";
+
+import { codeTitleTransformer } from "./code-title.ts";
+import { directiveToCalloutPlugin } from "./directives.ts";
+import { headingAnchorPlugin } from "./heading-anchors.ts";
+import { inlineCodeHighlightPlugin } from "./inline-code.ts";
+import { languageIconTransformer } from "./language-icon.ts";
+import { mathPlugin } from "./math.ts";
+import { mermaidPlugin } from "./mermaid.ts";
+import { packageInstallPlugin } from "./package-install.ts";
+
+/** A Shiki transformer, derived from the upstream factories' return type. */
+type ShikiTransformer = ReturnType<typeof transformerNotationDiff>;
+
+export {
+  PACKAGE_MANAGERS,
+  type PackageManager,
+  toPackageCommands,
+} from "./package-commands.ts";
+export {
+  type CodeTitleTransformer,
+  codeTitleTransformer,
+} from "./code-title.ts";
+export { calloutTypeFor } from "./directives.ts";
+export { headingAnchorPlugin } from "./heading-anchors.ts";
+export { mermaidPlugin } from "./mermaid.ts";
+export { packageInstallPlugin } from "./package-install.ts";
+
+/** Element type of Satteri's `mdastPlugins`, sourced from the (alpha) core. */
+type MdastPlugin = NonNullable<
+  NonNullable<Parameters<typeof satteri>[0]>["mdastPlugins"]
+>[number];
+
+/** Element type of Satteri's `hastPlugins`. */
+type HastPlugin = NonNullable<
+  NonNullable<Parameters<typeof satteri>[0]>["hastPlugins"]
+>[number];
+
+/**
+ * Hast plugins enabled by config. Inline `` `code`{:lang} `` highlighting is
+ * opt-in; self-linking heading anchors (`<h2>`–`<h6>` wrapped in an `<a>` to
+ * their own id) are on unless `markdown.headingAnchors` is `false`. Inline code
+ * runs first so the anchor wrap re-refs already-highlighted code.
+ */
+const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
+  const plugins: HastPlugin[] = [];
+  if (options.inline) {
+    plugins.push(inlineCodeHighlightPlugin() as unknown as HastPlugin);
+  }
+  if (options.headingAnchors !== false) {
+    plugins.push(headingAnchorPlugin() as unknown as HastPlugin);
+  }
+  return plugins;
+};
+
+/**
+ * Shiki transformers enabled by default for every code block. The four upstream
+ * notation transformers read GitHub-style comments and strip them from the
+ * output: `// [!code highlight]`, `// [!code ++]` / `// [!code --]`,
+ * `// [!code word:x]`, and `// [!code focus]`. The v3 match algorithm scopes a
+ * notation to the line it sits on (or the next, for a trailing comment).
+ * `transformerMetaHighlight` adds numeric range highlighting from the fence meta
+ * (` ```ts {1,3-5} `), reusing the same `highlighted` class. Blume's own
+ * {@link languageIconTransformer} prepends a brand icon, and
+ * {@link codeTitleTransformer} runs last to promote fence-meta (title / line
+ * numbers) to `<pre>` attributes. The theme styles the classes these emit
+ * (`highlighted`, `diff add/remove`, `highlighted-word`, `focused`,
+ * `blume-lang-icon`).
+ */
+export interface BlumeShikiOptions {
+  /** Prepend a brand language icon to the header (`markdown.code.icons`). */
+  icons?: boolean;
+}
+
+export const blumeShikiTransformers = (
+  options: BlumeShikiOptions = {}
+): ShikiTransformer[] => {
+  const transformers: ShikiTransformer[] = [
+    transformerNotationHighlight({ matchAlgorithm: "v3" }),
+    transformerNotationDiff({ matchAlgorithm: "v3" }),
+    transformerNotationWordHighlight({ matchAlgorithm: "v3" }),
+    transformerNotationFocus({ matchAlgorithm: "v3" }),
+    transformerMetaHighlight(),
+  ];
+  if (options.icons !== false) {
+    transformers.push(languageIconTransformer() as unknown as ShikiTransformer);
+  }
+  // The fence-meta reader (title / line numbers) always runs last.
+  transformers.push(codeTitleTransformer() as unknown as ShikiTransformer);
+  return transformers;
+};
+
+/**
+ * Sätteri Markdown features Blume enables beyond Astro's defaults. GFM,
+ * frontmatter, and smart punctuation are already on; this adds superscript
+ * (`^text^`) and subscript (`~text~`), which render to native `<sup>`/`<sub>`.
+ */
+const FEATURES = { subscript: true, superscript: true };
+
+/** Options shared by both processors. */
+export interface BlumeMarkdownOptions {
+  /**
+   * Wrap `<h2>`–`<h6>` in self-linking anchors (`markdown.headingAnchors`).
+   * On unless explicitly `false`.
+   */
+  headingAnchors?: boolean;
+  /** Highlight inline `` `code`{:lang} `` snippets (`markdown.code.inline`). */
+  inline?: boolean;
+}
+
+/** Sätteri processor for plain `.md`, with Blume's curated feature set. */
+export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
+  satteri({
+    features: { ...FEATURES },
+    hastPlugins: blumeHastPlugins(options),
+  });
+
+export interface BlumeMdxOptions extends BlumeMarkdownOptions {
+  /** Enable KaTeX math parsing and rendering. */
+  math?: boolean;
+}
+
+/**
+ * Sätteri MDX processor: Blume's feature set plus the MDAST plugins that target
+ * components — `package-install` → package-manager tabs, `:::note` →
+ * `<Callout>`, and ` ```mermaid ` → a `<blume-mermaid>` element. Used as the
+ * `processor` for `@astrojs/mdx` so these apply to
+ * `.mdx` only (plain `.md` uses {@link blumeMarkdownProcessor}). Math is opt-in
+ * via config since `$` is common in prose and code.
+ *
+ * The plugins are modeled with minimal structural types; bridge them to
+ * Satteri's full `MdastPlugin` type at this single boundary.
+ */
+export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) => {
+  const plugins: unknown[] = [
+    packageInstallPlugin(),
+    directiveToCalloutPlugin(),
+    mermaidPlugin(),
+  ];
+  if (options.math) {
+    plugins.push(mathPlugin());
+  }
+  return satteri({
+    features: {
+      ...FEATURES,
+      directive: true,
+      ...(options.math ? { math: true } : {}),
+    },
+    hastPlugins: blumeHastPlugins(options),
+    mdastPlugins: plugins as unknown as MdastPlugin[],
+  });
+};

package/src/markdown/inline-code.ts

@@ -0,0 +1,108 @@
+/**
+ * Inline syntax highlighting for `` `code{:lang}` ``. A Satteri hast plugin runs
+ * after Markdown is turned into hast and looks at each inline `<code>` for a
+ * trailing `{:lang}` marker. The marker sits *inside* the backticks (Shiki's
+ * "tailing-curly-colon" convention) so it survives MDX, where a `{…}` after a
+ * code span would be parsed as a JSX expression. When found, it strips the
+ * marker and replaces the code's text with Shiki tokens (dual github-light/dark
+ * via CSS variables, like fenced blocks).
+ *
+ * Shiki is imported lazily, so it loads only on pages that actually use inline
+ * highlighting — and never when `markdown.code.inline` is off (the plugin is not
+ * added to the pipeline at all).
+ */
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  children?: HastNode[];
+  properties?: Record<string, unknown>;
+  tagName?: string;
+  type: string;
+  value?: string;
+}
+
+/** The slice of Satteri's hast visitor context this plugin reads. */
+interface HastContext {
+  parent: (node: HastNode) => { tagName?: string } | undefined;
+  textContent: (node: HastNode) => string;
+}
+
+/** A Satteri hast plugin, typed structurally to avoid a Satteri dep. */
+export interface InlineCodePlugin {
+  name: string;
+  element: {
+    filter: string[];
+    visit: (node: HastNode, ctx: HastContext) => Promise<HastNode | undefined>;
+  };
+}
+
+/** Parsed `{:lang}` marker and the code with it removed. */
+export interface InlineLang {
+  code: string;
+  lang: string;
+}
+
+const INLINE_LANG = /\{:(?<lang>[\w+-]+)\}$/u;
+
+/** Parse a trailing `{:lang}` marker from an inline `<code>`'s own text. */
+export const parseInlineLang = (text: string): InlineLang | null => {
+  const match = text.match(INLINE_LANG);
+  if (!match?.groups?.lang || match.index === undefined) {
+    return null;
+  }
+  const code = text.slice(0, match.index);
+  return code ? { code, lang: match.groups.lang } : null;
+};
+
+/** Loosely-typed Shiki entry: just the inline-highlight call this plugin makes. */
+type InlineHighlighter = (
+  code: string,
+  options: {
+    defaultColor: false;
+    lang: string;
+    structure: "inline";
+    themes: { dark: string; light: string };
+  }
+) => Promise<{ children: HastNode[] }>;
+
+// `import()` caches the module, so this dedupes Shiki across calls on its own.
+const loadHighlighter = async (): Promise<InlineHighlighter> => {
+  const mod = await import("shiki");
+  return mod.codeToHast as unknown as InlineHighlighter;
+};
+
+/** Build the plugin. Highlights inline `` `code{:lang}` `` snippets. */
+export const inlineCodeHighlightPlugin = (): InlineCodePlugin => ({
+  element: {
+    filter: ["code"],
+    async visit(node, ctx) {
+      // Only inline code: a <code> inside <pre> is a fenced block — skip it.
+      if (ctx.parent(node)?.tagName === "pre") {
+        return;
+      }
+      const parsed = parseInlineLang(ctx.textContent(node));
+      if (!parsed) {
+        return;
+      }
+      try {
+        const codeToHast = await loadHighlighter();
+        const root = await codeToHast(parsed.code, {
+          defaultColor: false,
+          lang: parsed.lang,
+          structure: "inline",
+          themes: { dark: "github-dark", light: "github-light" },
+        });
+        return {
+          children: root.children,
+          properties: { className: ["blume-inline-code"] },
+          tagName: "code",
+          type: "element",
+        };
+      } catch {
+        // Unknown language or load failure: leave the code unhighlighted
+        // (falling through returns undefined, so the node is left as-is).
+      }
+    },
+  },
+  name: "blume:inline-code",
+});

package/src/markdown/language-icon.ts

@@ -0,0 +1,172 @@
+/**
+ * A Shiki transformer that prepends a brand icon to a code block's header,
+ * keyed off the fence language. Icons are sourced from `simple-icons` (raw SVG
+ * path data) at build time and emitted as an inline `<svg>` — no client JS and
+ * no React, so it works in the core theme. The icon renders in `currentColor`
+ * (the muted header color) so it stays legible in both light and dark; brand
+ * hex colors are skipped because dark-on-dark logos (Next.js, Rust…) vanish.
+ *
+ * The theme styles `.blume-lang-icon` and shifts the language label
+ * (`pre[data-icon]::before`) to make room.
+ */
+
+import {
+  siAstro,
+  siC,
+  siCplusplus,
+  siCss3,
+  siDart,
+  siDocker,
+  siGnubash,
+  siGo,
+  siGraphql,
+  siHtml5,
+  siJavascript,
+  siJson,
+  siKotlin,
+  siLess,
+  siLua,
+  siMarkdown,
+  siMdx,
+  siMysql,
+  siNextdotjs,
+  siPhp,
+  siPrisma,
+  siPython,
+  siReact,
+  siRuby,
+  siRust,
+  siSass,
+  siScala,
+  siSvelte,
+  siSvg,
+  siSwift,
+  siToml,
+  siTypescript,
+  siVuedotjs,
+  siWebassembly,
+  siYaml,
+} from "simple-icons";
+
+/** The slice of a `simple-icons` icon Blume reads (the SVG path data). */
+interface SimpleIcon {
+  path: string;
+}
+
+/** Fence language (and common aliases) → icon. Unmapped languages get none. */
+const LANGUAGE_ICONS: Record<string, SimpleIcon> = {
+  astro: siAstro,
+  bash: siGnubash,
+  c: siC,
+  "c++": siCplusplus,
+  cjs: siJavascript,
+  cpp: siCplusplus,
+  css: siCss3,
+  cts: siTypescript,
+  dart: siDart,
+  docker: siDocker,
+  dockerfile: siDocker,
+  go: siGo,
+  gql: siGraphql,
+  graphql: siGraphql,
+  html: siHtml5,
+  javascript: siJavascript,
+  js: siJavascript,
+  json: siJson,
+  json5: siJson,
+  jsonc: siJson,
+  jsx: siReact,
+  kotlin: siKotlin,
+  kt: siKotlin,
+  less: siLess,
+  lua: siLua,
+  markdown: siMarkdown,
+  md: siMarkdown,
+  mdx: siMdx,
+  mjs: siJavascript,
+  mts: siTypescript,
+  nextjs: siNextdotjs,
+  php: siPhp,
+  prisma: siPrisma,
+  py: siPython,
+  python: siPython,
+  rb: siRuby,
+  react: siReact,
+  rs: siRust,
+  ruby: siRuby,
+  rust: siRust,
+  sass: siSass,
+  scala: siScala,
+  scss: siSass,
+  sh: siGnubash,
+  shell: siGnubash,
+  sql: siMysql,
+  svelte: siSvelte,
+  svg: siSvg,
+  swift: siSwift,
+  toml: siToml,
+  ts: siTypescript,
+  tsx: siReact,
+  typescript: siTypescript,
+  vue: siVuedotjs,
+  wasm: siWebassembly,
+  yaml: siYaml,
+  yml: siYaml,
+  zsh: siGnubash,
+};
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  children?: HastNode[];
+  properties?: Record<string, unknown>;
+  tagName?: string;
+  type: string;
+  value?: string;
+}
+
+/** The slice of Shiki's transformer `this` context the icon hook reads. */
+interface IconContext {
+  options: { lang?: string };
+}
+
+/** The `<pre>` hast node a Shiki `pre` hook receives. */
+interface IconPreNode {
+  children: HastNode[];
+  properties: Record<string, boolean | number | string | undefined>;
+}
+
+/** A Shiki-compatible transformer, typed structurally to avoid a Shiki dep. */
+export interface LanguageIconTransformer {
+  name: string;
+  pre: (this: IconContext, node: IconPreNode) => void;
+}
+
+/** Build an inline SVG hast node from a simple-icons path. */
+const iconNode = (path: string): HastNode => ({
+  children: [
+    { children: [], properties: { d: path }, tagName: "path", type: "element" },
+  ],
+  properties: {
+    ariaHidden: "true",
+    className: ["blume-lang-icon"],
+    fill: "currentColor",
+    height: 14,
+    viewBox: "0 0 24 24",
+    width: 14,
+  },
+  tagName: "svg",
+  type: "element",
+});
+
+/** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
+export const languageIconTransformer = (): LanguageIconTransformer => ({
+  name: "blume:language-icon",
+  pre(node) {
+    const icon = LANGUAGE_ICONS[(this.options.lang ?? "").toLowerCase()];
+    if (!icon) {
+      return;
+    }
+    node.children.unshift(iconNode(icon.path));
+    node.properties.dataIcon = "";
+  },
+});

package/src/markdown/math.ts

@@ -0,0 +1,32 @@
+import { jsxAttribute, jsxFlowElement, jsxTextElement } from "./mdast.ts";
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+
+interface MathNode extends MdastNode {
+  value: string;
+}
+
+/**
+ * Satteri MDAST plugin that turns math nodes into Blume's `<Math>` component,
+ * which renders them with KaTeX at build time. Block math (`$$…$$`) becomes a
+ * block element; inline math (`$…$`) stays inline. Only active when math is
+ * enabled in config, so `$` is otherwise left as literal text.
+ */
+export const mathPlugin = () => ({
+  inlineMath(node: MathNode, ctx: MdastVisitorContext) {
+    ctx.replaceNode(
+      node,
+      jsxTextElement("Math", [jsxAttribute("code", node.value)])
+    );
+  },
+  math(node: MathNode, ctx: MdastVisitorContext) {
+    ctx.replaceNode(
+      node,
+      jsxFlowElement(
+        "Math",
+        [jsxAttribute("code", node.value), jsxAttribute("display")],
+        []
+      )
+    );
+  },
+  name: "blume-math",
+});

package/src/markdown/mdast.ts

@@ -0,0 +1,48 @@
+/**
+ * Minimal structural types and node builders for the (alpha) Satteri MDAST
+ * plugin API. We model only what Blume's plugins read and construct; the full
+ * types live in `satteri`, a transitive dependency. Plugins are bridged to
+ * Satteri's real `MdastPlugin` type at a single boundary in `index.ts`.
+ */
+
+/** The visitor context Blume's plugins use to mutate the tree. */
+export interface MdastVisitorContext {
+  replaceNode: (node: unknown, replacement: unknown) => void;
+}
+
+/** Any MDAST node, keyed loosely since we build a small subset by hand. */
+export interface MdastNode {
+  type: string;
+  [key: string]: unknown;
+}
+
+/** Build an MDX JSX attribute. A `null` value renders as a boolean attribute. */
+export const jsxAttribute = (name: string, value: string | null = null) => ({
+  name,
+  type: "mdxJsxAttribute",
+  value,
+});
+
+type JsxAttribute = ReturnType<typeof jsxAttribute>;
+
+/** Build a block-level MDX JSX element (`<Name>…</Name>`). */
+export const jsxFlowElement = (
+  name: string,
+  attributes: JsxAttribute[],
+  children: unknown[]
+) => ({ attributes, children, name, type: "mdxJsxFlowElement" });
+
+/** Build an inline MDX JSX element (phrasing context). */
+export const jsxTextElement = (
+  name: string,
+  attributes: JsxAttribute[],
+  children: unknown[] = []
+) => ({ attributes, children, name, type: "mdxJsxTextElement" });
+
+/** Build a fenced code block node. */
+export const codeBlock = (lang: string, value: string) => ({
+  lang,
+  meta: null,
+  type: "code",
+  value,
+});

package/src/markdown/mermaid.ts

@@ -0,0 +1,37 @@
+import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+
+interface CodeNode extends MdastNode {
+  lang?: string | null;
+  value: string;
+}
+
+/**
+ * Satteri MDAST plugin that turns a ` ```mermaid ` code block into a
+ * `<blume-mermaid>` custom element carrying the raw diagram source. There is no
+ * importable component — the fence is the whole interface. The element is
+ * rendered on the client (Mermaid needs a DOM), so the source rides on a string
+ * attribute rather than as child text (which MDX would try to parse).
+ */
+export const mermaidPlugin = () => ({
+  code(node: CodeNode, ctx: MdastVisitorContext) {
+    if (node.lang !== "mermaid") {
+      return;
+    }
+    ctx.replaceNode(
+      node,
+      jsxFlowElement(
+        "blume-mermaid",
+        [
+          jsxAttribute(
+            "class",
+            "not-prose my-6 flex justify-center overflow-x-auto"
+          ),
+          jsxAttribute("data-source", node.value),
+        ],
+        []
+      )
+    );
+  },
+  name: "blume-mermaid",
+});