@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/core/PdfWriter.js

@@ -0,0 +1,245 @@
+import { ChartExporter } from "./ChartExporter.js";
+import { ChartExportError, ExportErrorCode } from "./ChartExportError.js";
+import { ExportText } from "./ExportText.js";
+import { PdfOrientation, PdfPageSize } from "./PdfPage.js";
+import { PDFDocument, PageSizes, StandardFonts, rgb } from "pdf-lib";
+// src/core/PdfWriter.ts
+var SIZES = {
+	[PdfPageSize.A4]: PageSizes.A4,
+	[PdfPageSize.Letter]: PageSizes.Letter
+};
+var MARGIN = 36;
+var TITLE = 16;
+var TEXT = 8;
+var FOOTER = 7;
+var ROW = 14;
+var PADDING = 4;
+var [MIN_COLUMN, MAX_COLUMN] = [44, 180];
+/** Column widths come from this many rows, so a long table costs the same to measure. */
+var MEASURED = 500;
+/** Around 500 pages, where a viewer struggles and a spreadsheet does better. */
+var MAX_ROWS = 25e3;
+/** Canvas pixels per point, for text the built-in fonts have no glyph for. */
+var SHARPNESS = 4;
+var [ASCENT, DESCENT] = [1.05, .35];
+var FALLBACK_FONT = "Helvetica, Arial, \"Noto Sans\", sans-serif";
+var INK = rgb(.1, .1, .1);
+var QUIET = rgb(.4, .4, .4);
+var RULE = rgb(.8, .8, .8);
+var BAND = rgb(.94, .94, .94);
+/** Places a chart's PNG on a page and sets `table()` out as real text, one set of pages per block of columns that fits. */
+var PdfWriter = class PdfWriter {
+	#doc;
+	#regular;
+	#bold;
+	#glyphs;
+	#pictures = /* @__PURE__ */ new Map();
+	#ruler = null;
+	#width;
+	#height;
+	constructor(doc, regular, bold, size) {
+		this.#doc = doc;
+		this.#regular = regular;
+		this.#bold = bold;
+		this.#glyphs = new Set(regular.getCharacterSet());
+		[this.#width, this.#height] = size;
+	}
+	static async write(chart, options = {}) {
+		const table = options.table ? ExportText.rows(chart, "A PDF data table") : null;
+		return PdfWriter.file(await chart.toPNG({ scale: options.scale ?? 3 }), table, options);
+	}
+	static async file(png, table, options) {
+		const { pageSize = PdfPageSize.A4, orientation = PdfOrientation.Auto, title } = options;
+		const size = SIZES[pageSize];
+		if (!size) throw new RangeError(`Unknown PDF page size ${pageSize}.`);
+		if (!Object.values(PdfOrientation).includes(orientation)) throw new RangeError(`Unknown PDF orientation ${orientation}.`);
+		if (table && table.rows.length > MAX_ROWS) throw new ChartExportError(ExportErrorCode.Unsupported, `A PDF table holds ${MAX_ROWS} rows and this one has ${table.rows.length}. Use Excel or CSV for the data.`);
+		const doc = await PDFDocument.create();
+		doc.setCreator("@mstone6969/graph");
+		doc.setProducer("pdf-lib");
+		if (title) doc.setTitle(title);
+		const chart = await doc.embedPng(await png.arrayBuffer());
+		const [narrow, wide] = size;
+		const landscape = orientation === PdfOrientation.Landscape || orientation === PdfOrientation.Auto && chart.width >= chart.height;
+		const writer = new PdfWriter(doc, await doc.embedFont(StandardFonts.Helvetica), await doc.embedFont(StandardFonts.HelveticaBold), landscape ? [wide, narrow] : [narrow, wide]);
+		await writer.#chartPage(chart, title);
+		if (table) await writer.#tablePages(table);
+		await writer.#numberPages();
+		return new Blob([await doc.save()], { type: "application/pdf" });
+	}
+	#page() {
+		return this.#doc.addPage([this.#width, this.#height]);
+	}
+	get #room() {
+		return this.#width - 72;
+	}
+	async #chartPage(chart, title) {
+		const page = this.#page();
+		let top = this.#height - MARGIN;
+		if (title) {
+			top -= TITLE;
+			await this.#text(page, title, MARGIN, top, this.#room, {
+				size: TITLE,
+				bold: true
+			});
+			top -= TITLE;
+		}
+		const fit = Math.min(this.#room / chart.width, (top - MARGIN) / chart.height);
+		const [width, height] = [chart.width * fit, chart.height * fit];
+		page.drawImage(chart, {
+			x: (this.#width - width) / 2,
+			y: top - height,
+			width,
+			height
+		});
+	}
+	async #tablePages({ columns, rows }) {
+		const texts = rows.map((row) => columns.map((_, c) => ExportText.of(row[c])));
+		const natural = columns.map((column, c) => {
+			const widest = texts.slice(0, MEASURED).reduce((most, row) => Math.max(most, this.#textWidth(PdfWriter.#clean(row[c]), TEXT)), this.#textWidth(PdfWriter.#clean(column), TEXT, true));
+			return Math.min(MAX_COLUMN, Math.max(MIN_COLUMN, widest + 8));
+		});
+		for (const block of this.#blocks(natural)) {
+			const used = block.reduce((sum, c) => sum + natural[c], 0);
+			const widths = block.map((c) => natural[c] * this.#room / used);
+			let page = null, y = 0;
+			for (const [r, row] of texts.entries()) {
+				if (!page || y < 50) {
+					page = this.#page();
+					y = this.#height - MARGIN - ROW;
+					page.drawRectangle({
+						x: MARGIN,
+						y: y - PADDING,
+						width: this.#room,
+						height: ROW,
+						color: BAND
+					});
+					await this.#row(page, block.map((c) => columns[c]), block.map((c) => typeof rows[0][c] === "number"), widths, y, true);
+					y -= ROW;
+				}
+				await this.#row(page, block.map((c) => row[c]), block.map((c) => typeof rows[r][c] === "number"), widths, y, false);
+				page.drawLine({
+					start: {
+						x: MARGIN,
+						y: y - PADDING
+					},
+					end: {
+						x: MARGIN + this.#room,
+						y: y - PADDING
+					},
+					thickness: .25,
+					color: RULE
+				});
+				y -= ROW;
+			}
+		}
+	}
+	/** Greedy runs of columns that fit a page. Later runs repeat the first column, so their rows can still be told apart. */
+	#blocks(widths) {
+		const blocks = [];
+		let used = Infinity;
+		widths.forEach((width, c) => {
+			if (used + width > this.#room) {
+				blocks.push(c ? [0, c] : [c]);
+				used = (c ? widths[0] : 0) + width;
+			} else {
+				blocks.at(-1).push(c);
+				used += width;
+			}
+		});
+		return blocks;
+	}
+	async #row(page, cells, right, widths, y, bold) {
+		let x = MARGIN;
+		for (const [c, cell] of cells.entries()) {
+			const room = widths[c] - 8;
+			await this.#text(page, cell, right[c] ? x + PADDING + room : x + PADDING, y, room, {
+				size: TEXT,
+				bold,
+				right: right[c]
+			});
+			x += widths[c];
+		}
+	}
+	async #numberPages() {
+		const pages = this.#doc.getPages();
+		if (pages.length < 2) return;
+		for (const [i, page] of pages.entries()) await this.#text(page, `Page ${i + 1} of ${pages.length}`, this.#width - MARGIN, MARGIN / 2, this.#room, {
+			size: FOOTER,
+			color: QUIET,
+			right: true
+		});
+	}
+	static #clean(text) {
+		return text.replace(/\s+/g, " ").trim();
+	}
+	#encodable(text) {
+		for (const char of text) if (!this.#glyphs.has(char.codePointAt(0))) return false;
+		return true;
+	}
+	#font(bold) {
+		return bold ? this.#bold : this.#regular;
+	}
+	#cssFont(px, bold) {
+		return `${bold ? "bold " : ""}${px}px ${FALLBACK_FONT}`;
+	}
+	#textWidth(text, size, bold) {
+		if (this.#encodable(text)) return this.#font(bold).widthOfTextAtSize(text, size);
+		this.#ruler ??= ChartExporter.paint(ChartExporter.canvas(1, 1));
+		this.#ruler.font = this.#cssFont(size * SHARPNESS, bold);
+		return this.#ruler.measureText(text).width / SHARPNESS;
+	}
+	/** Cuts by code point, so an ellipsis never lands inside a surrogate pair. */
+	#fit(text, room, size, bold) {
+		if (this.#textWidth(text, size, bold) <= room) return text;
+		const chars = [...text];
+		let [low, high] = [0, chars.length];
+		while (low < high) {
+			const middle = Math.ceil((low + high) / 2);
+			if (this.#textWidth(`${chars.slice(0, middle).join("")}…`, size, bold) <= room) low = middle;
+			else high = middle - 1;
+		}
+		return `${chars.slice(0, low).join("").trimEnd()}…`;
+	}
+	/** The 14 built-in fonts cover Western European text only. Anything else is drawn as a small picture, so it shows but cannot be selected. */
+	async #text(page, text, x, y, room, style) {
+		const { size, bold, color = INK, right } = style;
+		const clean = PdfWriter.#clean(text);
+		if (!clean) return;
+		const shown = this.#fit(clean, room, size, bold);
+		const width = this.#textWidth(shown, size, bold);
+		const left = right ? x - width : x;
+		if (this.#encodable(shown)) {
+			page.drawText(shown, {
+				x: left,
+				y,
+				size,
+				font: this.#font(bold),
+				color
+			});
+			return;
+		}
+		const picture = await this.#picture(shown, width, size, bold);
+		page.drawImage(picture, {
+			x: left,
+			y: y - size * DESCENT,
+			width: picture.width / SHARPNESS,
+			height: picture.height / SHARPNESS
+		});
+	}
+	async #picture(text, width, size, bold) {
+		const key = `${size}|${bold}|${text}`;
+		const known = this.#pictures.get(key);
+		if (known) return known;
+		const canvas = ChartExporter.canvas(Math.ceil(width * SHARPNESS), Math.ceil(size * (ASCENT + DESCENT) * SHARPNESS));
+		const paint = ChartExporter.paint(canvas);
+		paint.font = this.#cssFont(size * SHARPNESS, bold);
+		paint.fillStyle = "#1a1a1a";
+		paint.textBaseline = "alphabetic";
+		paint.fillText(text, 0, size * ASCENT * SHARPNESS);
+		const picture = await this.#doc.embedPng(await (await ChartExporter.png(canvas)).arrayBuffer());
+		this.#pictures.set(key, picture);
+		return picture;
+	}
+};
+export { PdfWriter };

package/dist/core/RadialChart.js

@@ -0,0 +1,14 @@
+import { Chart2D } from "./Chart2D.js";
+// src/core/RadialChart.ts
+/** Polar charts: `ctx.root` is translated to the centre of the plot before `drawRadial`. */
+var RadialChart = class extends Chart2D {
+	draw(ctx) {
+		const center = [ctx.plot.width / 2, ctx.plot.height / 2];
+		const radius = Math.min(ctx.plot.width, ctx.plot.height) / 2;
+		this.drawRadial(ctx.nest(`translate(${center[0]},${center[1]})`), {
+			radius,
+			center
+		});
+	}
+};
+export { RadialChart };

package/dist/core/Scales.js

@@ -0,0 +1,101 @@
+import { AxisWindow } from "./AxisWindow.js";
+import { CurveKind, ScaleKind, SymbolKind } from "./enums.js";
+import { curveBasis, curveBumpX, curveCardinal, curveCatmullRom, curveLinear, curveMonotoneX, curveNatural, curveStep, curveStepAfter, curveStepBefore, interpolateNumber, scaleLinear, scaleLog, scalePow, scaleSqrt, scaleSymlog, symbolCircle, symbolCross, symbolDiamond, symbolSquare, symbolStar, symbolTriangle, symbolWye } from "d3";
+// src/core/Scales.ts
+var CURVES = {
+	[CurveKind.Linear]: curveLinear,
+	[CurveKind.Monotone]: curveMonotoneX,
+	[CurveKind.Step]: curveStep,
+	[CurveKind.StepBefore]: curveStepBefore,
+	[CurveKind.StepAfter]: curveStepAfter,
+	[CurveKind.Natural]: curveNatural,
+	[CurveKind.Cardinal]: curveCardinal,
+	[CurveKind.CatmullRom]: curveCatmullRom,
+	[CurveKind.Basis]: curveBasis,
+	[CurveKind.Bump]: curveBumpX
+};
+var SYMBOLS = {
+	[SymbolKind.Circle]: symbolCircle,
+	[SymbolKind.Square]: symbolSquare,
+	[SymbolKind.Diamond]: symbolDiamond,
+	[SymbolKind.Triangle]: symbolTriangle,
+	[SymbolKind.Cross]: symbolCross,
+	[SymbolKind.Star]: symbolStar,
+	[SymbolKind.Wye]: symbolWye
+};
+/** Maps library enums to d3 factories. */
+var Scales = class Scales {
+	static curve(kind = CurveKind.Linear) {
+		return CURVES[kind];
+	}
+	static symbol(kind = SymbolKind.Circle) {
+		return SYMBOLS[kind];
+	}
+	static continuous(kind = ScaleKind.Linear) {
+		switch (kind) {
+			case ScaleKind.Log: return scaleLog();
+			case ScaleKind.Sqrt: return scaleSqrt();
+			case ScaleKind.Pow: return scalePow().exponent(2);
+			case ScaleKind.Symlog: return scaleSymlog();
+			default: return scaleLinear();
+		}
+	}
+	/**
+	* Turns a built continuous scale into `kind` in place, because subclasses close over the scales
+	* they build. Says if it did: dates, bands and piecewise domains stay as they are, and so does `Log`
+	* over a value at or below 0. `floor`, the smallest value plotted, lets `Log` start a zero-based domain.
+	*/
+	static retype(scale, kind, floor = null) {
+		const domain = scale.domain?.();
+		if (AxisWindow.kind(scale) !== "continuous" || !scale.interpolate || domain?.length !== 2 || domain.some((value) => value instanceof Date)) return false;
+		if (kind === ScaleKind.Log) {
+			const ends = domain, low = ends[0] <= ends[1] ? 0 : 1;
+			if (ends[1 - low] <= 0 || ends[low] <= 0 && floor === null) return false;
+			if (ends[low] <= 0) {
+				ends[low] = 10 ** Math.floor(Math.log10(floor));
+				scale.domain(ends);
+			}
+		}
+		Scales.#adopt(scale, kind, scale.copy().interpolate(interpolateNumber).range([0, 1]).clamp(false));
+		return true;
+	}
+	/** `reader` undoes the scale's own normalising. What the scale's new shape cannot place lands on the low end, never on NaN. */
+	static #adopt(scale, kind, reader) {
+		const shape = Scales.continuous(kind).range([0, 1]);
+		const synced = () => shape.domain(scale.domain());
+		const { copy } = scale;
+		scale.interpolate((from, to) => {
+			synced();
+			return (t) => {
+				const at = shape(reader.domain(scale.domain()).invert(t));
+				return from + (to - from) * (Number.isFinite(at) ? at : 0);
+			};
+		});
+		scale.shows = (value) => synced()(value);
+		scale.invert = (at) => {
+			const [from, to] = scale.range();
+			return synced().invert((at - from) / (to - from));
+		};
+		scale.tickFormat = (...args) => synced().tickFormat(...args);
+		scale.ticks = (...args) => kind === ScaleKind.Log ? decades(synced().ticks(...args)) : synced().ticks(...args);
+		scale.copy = () => {
+			const twin = copy.call(scale);
+			Scales.#adopt(twin, kind, reader.copy());
+			return twin;
+		};
+	}
+	/** Clean axis ticks: full below 10,000, compact above. */
+	static format(value, reach) {
+		if (reach >= 1e4) return Intl.NumberFormat("en", {
+			notation: "compact",
+			maximumFractionDigits: 1
+		}).format(value);
+		return value.toLocaleString("en", { maximumFractionDigits: reach < 10 ? 2 : 0 });
+	}
+};
+/** A log scale offers a tick per mantissa, far more than an axis can label: keep powers of ten while there are at least two. */
+function decades(ticks) {
+	const tens = ticks.filter((tick) => Math.abs(Math.log10(tick) % 1) < 1e-9);
+	return tens.length >= 2 ? tens : ticks.filter((_, i) => i % Math.ceil(ticks.length / 6) === 0);
+}
+export { Scales };

package/dist/core/SceneOverlay.js

@@ -0,0 +1,63 @@
+import { Vector3 } from "three";
+// src/core/SceneOverlay.ts
+var INSET = {
+	x: 14,
+	y: 10
+};
+var SWATCH = 10;
+var LINE_HEIGHT = 1.25;
+/** Draws a 3D chart's HTML text onto a canvas: labels, title and legend live outside the WebGL frame. */
+var SceneOverlay = class SceneOverlay {
+	static paint(paint, scene, camera, size, scale, theme, header) {
+		paint.save();
+		paint.scale(scale, scale);
+		paint.textBaseline = "middle";
+		SceneOverlay.#labels(paint, scene, camera, size);
+		SceneOverlay.#header(paint, size, theme, header);
+		paint.restore();
+	}
+	static #labels(paint, scene, camera, { width, height }) {
+		const at = new Vector3();
+		scene.updateMatrixWorld(true);
+		scene.traverseVisible((object) => {
+			if (!object.isCSS2DObject) return;
+			const { element, center } = object;
+			object.onBeforeRender(null, scene, camera);
+			at.setFromMatrixPosition(object.matrixWorld).project(camera);
+			if (at.z < -1 || at.z > 1 || !element.textContent || element.style.opacity === "0") return;
+			paint.font = element.style.font;
+			paint.fillStyle = element.style.color;
+			const box = paint.measureText(element.textContent);
+			paint.fillText(element.textContent, (at.x + 1) / 2 * width - center.x * box.width, (1 - at.y) / 2 * height + (.5 - center.y) * parseFloat(element.style.fontSize || "11") * LINE_HEIGHT);
+		});
+	}
+	static #header(paint, { width }, theme, { title, subtitle, items, fontScale = 1 }) {
+		let y = INSET.y;
+		const line = (text, font, color, size) => {
+			paint.font = font;
+			paint.fillStyle = color;
+			paint.fillText(text, INSET.x, y + size * LINE_HEIGHT / 2);
+			y += size * LINE_HEIGHT;
+		};
+		if (title) line(title, `600 ${15 * fontScale}px ${theme.fontFamily}`, theme.ink, 15 * fontScale);
+		if (subtitle) line(subtitle, `${12 * fontScale}px ${theme.fontFamily}`, theme.inkSecondary, 12 * fontScale);
+		paint.font = `${12 * fontScale}px ${theme.fontFamily}`;
+		let x = INSET.x;
+		y += items.length ? 13 : 0;
+		for (const { key, label, color } of items) {
+			const text = label ?? key, cost = 15 + paint.measureText(text).width + 12;
+			if (x > INSET.x && x + cost > width - INSET.x) {
+				x = INSET.x;
+				y += 18;
+			}
+			paint.fillStyle = color;
+			paint.beginPath();
+			paint.roundRect(x, y - SWATCH / 2, SWATCH, SWATCH, 3);
+			paint.fill();
+			paint.fillStyle = theme.inkSecondary;
+			paint.fillText(text, x + SWATCH + 5, y);
+			x += cost;
+		}
+	}
+};
+export { SceneOverlay };

package/dist/core/TextFit.js

@@ -0,0 +1,37 @@
+// src/core/TextFit.ts
+var ELLIPSIS = "…";
+/** Weights from glyph widths measured in the theme's system font, where one unit is an average Latin character. */
+var ELLIPSIS_WEIGHT = 1.5;
+var THIN = /^[fijlrt.,:;'|!()[\] ]$/;
+var BROAD = /^[A-Zmw@%]$/;
+/** One grapheme drawn about a full em wide: CJK, kana, hangul, full-width forms and emoji. */
+var WIDE = /\p{Script=Han}|\p{Script=Hiragana}|\p{Script=Katakana}|\p{Script=Hangul}|[　-〿！-｠￠-￦]|\p{Emoji_Presentation}|️/u;
+var ZERO = /^[\p{M}\p{Cf}]+$/u;
+var segmenter = typeof Intl.Segmenter === "function" ? new Intl.Segmenter(void 0, { granularity: "grapheme" }) : null;
+var graphemes = (text) => segmenter ? Array.from(segmenter.segment(text), (part) => part.segment) : Array.from(text);
+var cells = (grapheme) => ZERO.test(grapheme) ? 0 : WIDE.test(grapheme) ? 2 : 1;
+/** A closer estimate for deciding on a cut, so all-caps text stops in time and text of thin letters is left whole. */
+var weight = (grapheme) => THIN.test(grapheme) ? .6 : BROAD.test(grapheme) ? 1.3 : cells(grapheme) === 1 ? 1.05 : cells(grapheme);
+/** Estimated text width and truncation, without measuring. `char` is the px width of an average Latin character. */
+var TextFit = class {
+	/** Width of `text` in px. Wide scripts count double, combining marks count nothing. */
+	static width(text, char) {
+		return graphemes(text).reduce((sum, grapheme) => sum + cells(grapheme), 0) * char;
+	}
+	/** `text` cut to `room` px with an ellipsis. Whole graphemes only, so an emoji or accented letter never splits. */
+	static fit(text, room, char) {
+		const parts = graphemes(text), limit = room / char;
+		if (parts.reduce((sum, part) => sum + weight(part), 0) <= limit) return text;
+		let used = ELLIPSIS_WEIGHT, keep = 0;
+		while (keep < parts.length && used + weight(parts[keep]) <= limit) used += weight(parts[keep++]);
+		return `${parts.slice(0, keep).join("").trimEnd()}${ELLIPSIS}`;
+	}
+	/** Adds a `<title>` child holding the full text, or removes it when `full` gives nothing. */
+	static hint(selection, full) {
+		selection.selectAll("title").data((datum) => {
+			const text = full(datum);
+			return text ? [text] : [];
+		}).join("title").text((text) => text);
+	}
+};
+export { TextFit };

package/dist/core/Theme.js

@@ -0,0 +1,102 @@
+import { ThemeMode } from "./enums.js";
+import { hsl } from "d3";
+// src/core/Theme.ts
+var SEQUENTIAL = [
+	"#cde2fb",
+	"#9ec5f4",
+	"#6da7ec",
+	"#3987e5",
+	"#256abf",
+	"#184f95",
+	"#0d366b"
+];
+var STATUS = {
+	good: "#0ca30c",
+	warning: "#fab219",
+	serious: "#ec835a",
+	critical: "#d03b3b"
+};
+var FONT = "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif";
+/** Colour tokens for both modes. Palette order is CVD-validated: never reorder or cycle it. */
+var Theme = class Theme {
+	static light = {
+		surface: "#fcfcfb",
+		ink: "#0b0b0b",
+		inkSecondary: "#52514e",
+		inkMuted: "#8a8984",
+		grid: "#e8e7e2",
+		axis: "#c3c2b7",
+		categorical: [
+			"#2a78d6",
+			"#eb6834",
+			"#1baf7a",
+			"#eda100",
+			"#e87ba4",
+			"#008300",
+			"#6250d6",
+			"#e34948"
+		],
+		sequential: SEQUENTIAL,
+		divergingLow: "#2a78d6",
+		divergingHigh: "#e34948",
+		divergingMid: "#f0efec",
+		...STATUS,
+		fontFamily: FONT
+	};
+	static dark = {
+		surface: "#1a1a19",
+		ink: "#f0efec",
+		inkSecondary: "#c3c2b7",
+		inkMuted: "#8a8984",
+		grid: "#2e2e2c",
+		axis: "#4a4a46",
+		categorical: [
+			"#3987e5",
+			"#d95926",
+			"#199e70",
+			"#c98500",
+			"#d55181",
+			"#008300",
+			"#9085e9",
+			"#e66767"
+		],
+		sequential: [...SEQUENTIAL].reverse(),
+		divergingLow: "#3987e5",
+		divergingHigh: "#e66767",
+		divergingMid: "#383835",
+		...STATUS,
+		fontFamily: FONT
+	};
+	static resolve(theme = ThemeMode.Auto, style) {
+		const tokens = Theme.#mode(theme);
+		return style ? Theme.#styled(tokens, style) : tokens;
+	}
+	static #mode(theme) {
+		if (typeof theme === "object") return theme;
+		if (theme === ThemeMode.Auto) return globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches ? Theme.dark : Theme.light;
+		return theme === ThemeMode.Dark ? Theme.dark : Theme.light;
+	}
+	/** A style colour as a CSS colour: token names such as `good` follow the theme's mode. */
+	static #paint(tokens, value) {
+		const token = tokens[value];
+		return typeof token === "string" ? token : value;
+	}
+	/** Slots past a short `colors` hold `inkMuted`, the colour `Palette` folds into Other, so nothing reads an empty slot. */
+	static #styled(tokens, { colors, sequential, diverging, fontFamily }) {
+		const paint = (value) => Theme.#paint(tokens, value);
+		const stops = sequential && sequential.length >= 2 ? sequential.map(paint) : null;
+		if (!colors?.length && !stops && !diverging && !fontFamily) return tokens;
+		const styled = { ...tokens };
+		if (colors?.length) styled.categorical = Array.from({ length: Math.max(colors.length, tokens.categorical.length) }, (_, i) => colors[i] === void 0 ? tokens.inkMuted : paint(colors[i]));
+		if (stops) styled.sequential = hsl(tokens.surface).l < .5 ? stops.reverse() : stops;
+		if (diverging) [styled.divergingLow, styled.divergingMid, styled.divergingHigh] = diverging.map(paint);
+		if (fontFamily) styled.fontFamily = fontFamily;
+		return styled;
+	}
+	/** `seriesColors` resolved against `tokens`, for `Palette`. */
+	static pins(tokens, style) {
+		const pinned = style?.seriesColors;
+		return pinned && Object.fromEntries(Object.entries(pinned).map(([key, value]) => [key, Theme.#paint(tokens, value)]));
+	}
+};
+export { Theme };

package/dist/core/Tooltip.js

@@ -0,0 +1,73 @@
+// src/core/Tooltip.ts
+/** One HTML tooltip per chart, positioned inside the chart's host. */
+var Tooltip = class {
+	host;
+	el;
+	constructor(host) {
+		this.host = host;
+		this.el = document.createElement("div");
+		this.el.setAttribute("role", "status");
+		Object.assign(this.el.style, {
+			position: "absolute",
+			pointerEvents: "none",
+			opacity: "0",
+			transition: "opacity 120ms",
+			zIndex: "10",
+			top: "0",
+			left: "0",
+			padding: "8px 10px",
+			borderRadius: "8px",
+			fontSize: "12px",
+			lineHeight: "1.5",
+			minWidth: "96px",
+			whiteSpace: "nowrap",
+			boxShadow: "0 4px 16px rgba(0,0,0,.14)"
+		});
+		host.appendChild(this.el);
+	}
+	show(event, content, theme) {
+		const { el, host } = this;
+		Object.assign(el.style, {
+			background: theme.surface,
+			color: theme.ink,
+			border: `1px solid ${theme.grid}`,
+			fontFamily: theme.fontFamily
+		});
+		el.replaceChildren();
+		if (content.title) {
+			const title = el.appendChild(document.createElement("div"));
+			title.textContent = content.title;
+			title.style.fontWeight = "600";
+			if (content.color) title.style.borderLeft = `3px solid ${content.color}`, title.style.paddingLeft = "6px";
+		}
+		for (const [label, value] of content.rows ?? []) {
+			const row = el.appendChild(document.createElement("div"));
+			Object.assign(row.style, {
+				display: "flex",
+				justifyContent: "space-between",
+				gap: "16px"
+			});
+			const name = row.appendChild(document.createElement("span"));
+			name.textContent = label;
+			name.style.color = theme.inkSecondary;
+			row.appendChild(document.createElement("span")).textContent = typeof value === "number" ? value.toLocaleString() : value;
+		}
+		const box = host.getBoundingClientRect();
+		const x = event.clientX - box.left, y = event.clientY - box.top;
+		const left = Math.min(x + 12, box.width - el.offsetWidth - 4), top = y - el.offsetHeight - 10;
+		el.style.transform = `translate(${Math.max(4, left)}px, ${top < 4 ? y + 14 : top}px)`;
+		el.style.opacity = "1";
+	}
+	hide() {
+		this.el.style.opacity = "0";
+	}
+	/** Stops assistive tech reading the box, for when a separate live region speaks instead. */
+	mute(muted) {
+		if (muted) this.el.setAttribute("aria-hidden", "true");
+		else this.el.removeAttribute("aria-hidden");
+	}
+	destroy() {
+		this.el.remove();
+	}
+};
+export { Tooltip };

package/dist/core/VariantSpace.js

@@ -0,0 +1,30 @@
+// src/core/VariantSpace.ts
+/** Expands a chart class's variant axes into its concrete chart types. */
+var VariantSpace = class VariantSpace {
+	static expand(chart) {
+		const { id, name, variants = {}, valid } = chart.meta;
+		const axes = Object.entries(variants);
+		const shared = new Set(axes.flatMap(([, values]) => values).filter((value, i, all) => all.indexOf(value) !== i));
+		return axes.reduce((all, [key, values]) => all.flatMap((combo) => values.map((value) => ({
+			...combo,
+			[key]: value
+		}))), [{}]).filter((values) => valid?.(values) ?? true).map((values) => {
+			const moved = axes.filter(([key, list]) => values[key] !== list[0]).map(([key]) => {
+				const slug = VariantSpace.slug(key, values[key]);
+				return shared.has(values[key]) && typeof values[key] === "string" ? `${key}-${slug}` : slug;
+			});
+			return {
+				id: [id, ...moved].join("."),
+				chart,
+				values,
+				name: [name, ...moved.map((part) => part.replaceAll("-", " "))].join(" · ")
+			};
+		});
+	}
+	static slug(key, value) {
+		if (value === true) return key;
+		if (value === false) return `no-${key}`;
+		return typeof value === "number" ? `${key}-${value}` : value;
+	}
+};
+export { VariantSpace };