enarratio-astro 0.1.0 → 0.4.2

package/src/markdown.ts

@@ -1,164 +1,171 @@
-import { type ChartSpec, renderChart } from "./chart.js";
-import { chartMarkup } from "./figure.js";
-import { chartStyles, type StyleOptions } from "./styles.js";
-
-/** Options for the Markdown plugins: how charts are styled. */
-export type MarkdownChartOptions = StyleOptions;
-
-const BOOLEAN_KEYS = new Set(["regression", "interactive"]);
-const KEYS = new Set([
-  "type",
-  "alt",
-  "title",
-  "caption",
-  "x",
-  "y",
-  "series",
-  "value",
-  "xLabel",
-  "yLabel",
-  "layout",
-  "orientation",
-  "scale",
-  "regression",
-  "dataTable",
-  "id",
-  "interactive",
-]);
-
-/**
- * Reads a `chart` code block: `key: value` lines, a line of three dashes, then the data.
- *
- * ```chart
- * type: line
- * x: month
- * y: visitors
- * alt: Monthly visitors rise from 820 to 1,190.
- * ---
- * month,visitors
- * 2026-01-01,820
- * ```
- */
-export function parseChartBlock(source: string): ChartSpec & { readonly interactive: boolean } {
-  const lines = source.split(/\r?\n/);
-  const rule = lines.findIndex((line) => line.trim() === "---");
-  if (rule === -1)
-    throw new Error('Put a line of three dashes ("---") between the options and the data.');
-  const spec: Record<string, string | boolean> = {};
-  for (const line of lines.slice(0, rule)) {
-    if (line.trim() === "") continue;
-    const colon = line.indexOf(":");
-    const key = colon === -1 ? "" : line.slice(0, colon).trim();
-    if (!KEYS.has(key)) {
-      throw new Error(`"${line.trim()}" is not an option. Options are: ${[...KEYS].join(", ")}.`);
-    }
-    const raw = line.slice(colon + 1).trim();
-    spec[key] = BOOLEAN_KEYS.has(key) ? raw === "true" || raw === "yes" : raw;
-  }
-  return {
-    ...(spec as Omit<ChartSpec, "data">),
-    data: lines.slice(rule + 1).join("\n"),
-    interactive: spec["interactive"] === true,
-  };
-}
-
-/** The HTML for one chart block, with the chart CSS when it is the document's first chart. */
-async function chartHtml(
-  source: string,
-  first: boolean,
-  options: MarkdownChartOptions,
-): Promise<string> {
-  let markup: string;
-  try {
-    const { interactive, ...spec } = parseChartBlock(source);
-    const result = await renderChart(spec);
-    if (!result.ok) console.warn(`[enarratio-astro] Markdown chart not drawn: ${result.error}`);
-    markup = chartMarkup(result, interactive);
-  } catch (error) {
-    markup = chartMarkup(
-      { ok: false, error: error instanceof Error ? error.message : String(error) },
-      false,
-    );
-  }
-  const css = first ? chartStyles(options) : "";
-  return css ? `<style>${css}</style>\n${markup}` : markup;
-}
-
-/** The parts of a Markdown code node the plugins read. */
-interface CodeNode {
-  readonly type: "code";
-  readonly lang?: string | null | undefined;
-  readonly value: string;
-}
-
-/** The parts of the Sätteri visitor context the plugin uses. */
-interface SatteriContext {
-  replaceNode(node: Readonly<CodeNode>, content: { type: "html"; value: string }): void;
-}
-
-/**
- * Charts in Markdown for Astro's default Markdown processor, Sätteri (Astro 7 and later): every
- * code block whose language is `chart` becomes a chart, drawn when the site builds or renders.
- *
- * @example
- * // astro.config.mjs
- * import { satteri } from "@astrojs/markdown-satteri";
- * import { satteriCharts } from "enarratio-astro/markdown";
- * export default defineConfig({ markdown: { processor: satteri({ mdastPlugins: [satteriCharts()] }) } });
- */
-export function satteriCharts(options: MarkdownChartOptions = {}) {
-  let first = true;
-  return {
-    name: "enarratio-charts",
-    before() {
-      first = true;
-    },
-    async code(node: Readonly<CodeNode>, ctx: SatteriContext) {
-      if (node.lang !== "chart") return;
-      // Visitors run concurrently, so the first block claims the stylesheet before it awaits.
-      const isFirst = first;
-      first = false;
-      const value = await chartHtml(node.value, isFirst, options);
-      ctx.replaceNode(node, { type: "html", value });
-    },
-  };
-}
-
-interface MdastParent {
-  children: Array<{
-    type: string;
-    lang?: string | null | undefined;
-    value?: string | undefined;
-    children?: unknown[] | undefined;
-  }>;
-}
-
-/**
- * Charts in Markdown for the unified (remark) processor, Astro 6's default and an option in
- * Astro 7: every code block whose language is `chart` becomes a chart.
- *
- * @example
- * // astro.config.mjs, Astro 6
- * import { remarkCharts } from "enarratio-astro/markdown";
- * export default defineConfig({ markdown: { remarkPlugins: [remarkCharts] } });
- */
-export function remarkCharts(options: MarkdownChartOptions = {}) {
-  return async (tree: MdastParent): Promise<void> => {
-    const blocks: MdastParent["children"] = [];
-    const walk = (parent: MdastParent) => {
-      for (const child of parent.children) {
-        if (child.type === "code" && child.lang === "chart") blocks.push(child);
-        else if (Array.isArray(child.children)) walk(child as MdastParent);
-      }
-    };
-    walk(tree);
-    let first = true;
-    for (const node of blocks) {
-      const value = await chartHtml(node.value ?? "", first, options);
-      first = false;
-      // Turned into raw HTML in place, as remark plugins do.
-      Object.assign(node, { type: "html", value });
-      delete node.lang;
-    }
-  };
-}
+import { type ChartSpec, renderChart } from "./chart.js";
+import { chartMarkup } from "./figure.js";
+import { chartStyles, type StyleOptions } from "./styles.js";
+
+/** Options for the Markdown plugins: how charts are styled. */
+export type MarkdownChartOptions = StyleOptions;
+
+const BOOLEAN_KEYS = new Set(["regression", "interactive"]);
+const KEYS = new Set([
+  "type",
+  "alt",
+  "title",
+  "subtitle",
+  "caption",
+  "notes",
+  "source",
+  "sourceHref",
+  "byline",
+  "x",
+  "y",
+  "series",
+  "value",
+  "xLabel",
+  "yLabel",
+  "xUnit",
+  "yUnit",
+  "layout",
+  "orientation",
+  "scale",
+  "regression",
+  "dataTable",
+  "id",
+  "interactive",
+]);
+
+/**
+ * Reads a `chart` code block: `key: value` lines, a line of three dashes, then the data.
+ *
+ * ```chart
+ * type: line
+ * x: month
+ * y: visitors
+ * alt: Monthly visitors rise from 820 to 1,190.
+ * ---
+ * month,visitors
+ * 2026-01-01,820
+ * ```
+ */
+export function parseChartBlock(source: string): ChartSpec & { readonly interactive: boolean } {
+  const lines = source.split(/\r?\n/);
+  const rule = lines.findIndex((line) => line.trim() === "---");
+  if (rule === -1)
+    throw new Error('Put a line of three dashes ("---") between the options and the data.');
+  const spec: Record<string, string | boolean> = {};
+  for (const line of lines.slice(0, rule)) {
+    if (line.trim() === "") continue;
+    const colon = line.indexOf(":");
+    const key = colon === -1 ? "" : line.slice(0, colon).trim();
+    if (!KEYS.has(key)) {
+      throw new Error(`"${line.trim()}" is not an option. Options are: ${[...KEYS].join(", ")}.`);
+    }
+    const raw = line.slice(colon + 1).trim();
+    spec[key] = BOOLEAN_KEYS.has(key) ? raw === "true" || raw === "yes" : raw;
+  }
+  return {
+    ...(spec as Omit<ChartSpec, "data">),
+    data: lines.slice(rule + 1).join("\n"),
+    interactive: spec["interactive"] === true,
+  };
+}
+
+/** The HTML for one chart block, with the chart CSS when it is the document's first chart. */
+async function chartHtml(
+  source: string,
+  first: boolean,
+  options: MarkdownChartOptions,
+): Promise<string> {
+  let markup: string;
+  try {
+    const { interactive, ...spec } = parseChartBlock(source);
+    const result = await renderChart(spec, { interactive });
+    if (!result.ok) console.warn(`[enarratio-astro] Markdown chart not drawn: ${result.error}`);
+    markup = chartMarkup(result, interactive);
+  } catch (error) {
+    markup = chartMarkup(
+      { ok: false, error: error instanceof Error ? error.message : String(error) },
+      false,
+    );
+  }
+  const css = first ? chartStyles(options) : "";
+  return css ? `<style>${css}</style>\n${markup}` : markup;
+}
+
+/** The parts of a Markdown code node the plugins read. */
+interface CodeNode {
+  readonly type: "code";
+  readonly lang?: string | null | undefined;
+  readonly value: string;
+}
+
+/** The parts of the Sätteri visitor context the plugin uses. */
+interface SatteriContext {
+  replaceNode(node: Readonly<CodeNode>, content: { type: "html"; value: string }): void;
+}
+
+/**
+ * Charts in Markdown for Astro's default Markdown processor, Sätteri (Astro 7 and later): every
+ * code block whose language is `chart` becomes a chart, drawn when the site builds or renders.
+ *
+ * @example
+ * // astro.config.mjs
+ * import { satteri } from "@astrojs/markdown-satteri";
+ * import { satteriCharts } from "enarratio-astro/markdown";
+ * export default defineConfig({ markdown: { processor: satteri({ mdastPlugins: [satteriCharts()] }) } });
+ */
+export function satteriCharts(options: MarkdownChartOptions = {}) {
+  let first = true;
+  return {
+    name: "enarratio-charts",
+    before() {
+      first = true;
+    },
+    async code(node: Readonly<CodeNode>, ctx: SatteriContext) {
+      if (node.lang !== "chart") return;
+      // Visitors run concurrently, so the first block claims the stylesheet before it awaits.
+      const isFirst = first;
+      first = false;
+      const value = await chartHtml(node.value, isFirst, options);
+      ctx.replaceNode(node, { type: "html", value });
+    },
+  };
+}
+
+interface MdastParent {
+  children: Array<{
+    type: string;
+    lang?: string | null | undefined;
+    value?: string | undefined;
+    children?: unknown[] | undefined;
+  }>;
+}
+
+/**
+ * Charts in Markdown for the unified (remark) processor, Astro 6's default and an option in
+ * Astro 7: every code block whose language is `chart` becomes a chart.
+ *
+ * @example
+ * // astro.config.mjs, Astro 6
+ * import { remarkCharts } from "enarratio-astro/markdown";
+ * export default defineConfig({ markdown: { remarkPlugins: [remarkCharts] } });
+ */
+export function remarkCharts(options: MarkdownChartOptions = {}) {
+  return async (tree: MdastParent): Promise<void> => {
+    const blocks: MdastParent["children"] = [];
+    const walk = (parent: MdastParent) => {
+      for (const child of parent.children) {
+        if (child.type === "code" && child.lang === "chart") blocks.push(child);
+        else if (Array.isArray(child.children)) walk(child as MdastParent);
+      }
+    };
+    walk(tree);
+    let first = true;
+    for (const node of blocks) {
+      const value = await chartHtml(node.value ?? "", first, options);
+      first = false;
+      // Turned into raw HTML in place, as remark plugins do.
+      Object.assign(node, { type: "html", value });
+      delete node.lang;
+    }
+  };
+}

package/src/once.ts

@@ -1,11 +1,11 @@
-const styled = new WeakSet<object>();
-
-/**
- * True the first time it is asked about a page render. Astro gives each render its own Request,
- * so the theme's stylesheet is written once per page however many charts the page has.
- */
-export function firstOnPage(request: object): boolean {
-  if (styled.has(request)) return false;
-  styled.add(request);
-  return true;
-}
+const styled = new WeakSet<object>();
+
+/**
+ * True the first time it is asked about a page render. Astro gives each render its own Request,
+ * so the theme's stylesheet is written once per page however many charts the page has.
+ */
+export function firstOnPage(request: object): boolean {
+  if (styled.has(request)) return false;
+  styled.add(request);
+  return true;
+}

package/src/styles.ts

@@ -1,36 +1,36 @@
-import { baseStylesheet, type StylesheetOptions, stylesheet, type Theme } from "enarratio";
-import { defaultTheme } from "enarratio/themes";
-
-/**
- * What a page's charts are styled with:
- * - `"theme"` (default): an Enarratio theme's colors and rules, light and dark.
- * - `"base"`: the rules without colors or fonts, for a site whose own tokens define the
- *   `--enarratio-*` properties (Capsomer's tokens do).
- * - `"none"`: nothing; the site includes Enarratio's stylesheet itself.
- */
-export type Styles = "theme" | "base" | "none";
-
-/** How charts are styled: the {@link Styles} choice, and for `"theme"` which theme and how. */
-export interface StyleOptions {
-  readonly styles?: Styles | undefined;
-  /** The Enarratio theme. Default: Enarratio's default theme. */
-  readonly theme?: Theme | undefined;
-  /** Passed to Enarratio's `stylesheet()`, e.g. `{ colorScheme: { dark: '[data-theme="dark"]' } }`. */
-  readonly stylesheetOptions?: StylesheetOptions | undefined;
-}
-
-/** The note that replaces a chart that cannot be drawn, set apart from the text around it. */
-const NOTE =
-  ".enarratio-chart-error{border-inline-start:3px solid currentColor;padding-inline-start:.75em;font-size:.875em}";
-
-/** The CSS written once per page (or Markdown document) with a chart; empty for `"none"`. */
-export function chartStyles(options: StyleOptions = {}): string {
-  switch (options.styles ?? "theme") {
-    case "none":
-      return "";
-    case "base":
-      return `${baseStylesheet()}\n${NOTE}`;
-    default:
-      return `${stylesheet(options.theme ?? defaultTheme, options.stylesheetOptions)}\n${NOTE}`;
-  }
-}
+import { baseStylesheet, type StylesheetOptions, stylesheet, type Theme } from "enarratio";
+import { defaultTheme } from "enarratio/themes";
+
+/**
+ * What a page's charts are styled with:
+ * - `"theme"` (default): an Enarratio theme's colors and rules, light and dark.
+ * - `"base"`: the rules without colors or fonts, for a site whose own tokens define the
+ *   `--enarratio-*` properties (Capsomer's tokens do).
+ * - `"none"`: nothing; the site includes Enarratio's stylesheet itself.
+ */
+export type Styles = "theme" | "base" | "none";
+
+/** How charts are styled: the {@link Styles} choice, and for `"theme"` which theme and how. */
+export interface StyleOptions {
+  readonly styles?: Styles | undefined;
+  /** The Enarratio theme. Default: Enarratio's default theme. */
+  readonly theme?: Theme | undefined;
+  /** Passed to Enarratio's `stylesheet()`, e.g. `{ colorScheme: { dark: '[data-theme="dark"]' } }`. */
+  readonly stylesheetOptions?: StylesheetOptions | undefined;
+}
+
+/** The note that replaces a chart that cannot be drawn, set apart from the text around it. */
+const NOTE =
+  ".enarratio-chart-error{border-inline-start:3px solid currentColor;padding-inline-start:.75em;font-size:.875em}";
+
+/** The CSS written once per page (or Markdown document) with a chart; empty for `"none"`. */
+export function chartStyles(options: StyleOptions = {}): string {
+  switch (options.styles ?? "theme") {
+    case "none":
+      return "";
+    case "base":
+      return `${baseStylesheet()}\n${NOTE}`;
+    default:
+      return `${stylesheet(options.theme ?? defaultTheme, options.stylesheetOptions)}\n${NOTE}`;
+  }
+}