@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/matrix/GridPlot.js

@@ -0,0 +1,211 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MatrixSurface, fitText } from "./MatrixSurface.js";
+import { area, curveMonotoneX, curveStepAfter, extent, group, line, max, mean, min, scaleLinear, scaleTime } from "d3";
+// src/charts/matrix/GridPlot.ts
+var GridPanel = /* @__PURE__ */ function(GridPanel) {
+	GridPanel["Line"] = "line-panels";
+	GridPanel["Area"] = "area-panels";
+	GridPanel["Step"] = "step-panels";
+	GridPanel["Bars"] = "bar-panels";
+	GridPanel["Dots"] = "dot-panels";
+	return GridPanel;
+}({});
+var GridScale = /* @__PURE__ */ function(GridScale) {
+	GridScale["Shared"] = "shared-scale";
+	GridScale["Free"] = "free-scale";
+	GridScale["Indexed"] = "indexed-scale";
+	return GridScale;
+}({});
+var TITLE = 16;
+var GAP = 12;
+var AXIS = 16;
+/** Small multiples: one panel per group on a common layout, so shapes can be compared without overplotting. */
+var GridPlot = class extends MatrixSurface {
+	static meta = {
+		id: "grid-plot",
+		name: "Grid plot",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Repeats a small chart in a grid, one panel per group, to compare many series without overlap.",
+		tags: [
+			"small multiples",
+			"trellis",
+			"facet grid"
+		],
+		sample: (seed) => SampleData.timeSeries(seed, 36, 6),
+		variants: {
+			panel: [
+				"line-panels",
+				"area-panels",
+				"step-panels",
+				"bar-panels",
+				"dot-panels"
+			],
+			scale: [
+				"shared-scale",
+				"free-scale",
+				"indexed-scale"
+			],
+			columns: [
+				3,
+				2,
+				6
+			],
+			reference: [false, true],
+			context: [false, true]
+		},
+		valid: (v) => !(v.context && (v.panel === "bar-panels" || v.panel === "dot-panels" || v.scale === "free-scale"))
+	};
+	defaults() {
+		return {
+			facet: "series",
+			x: "date",
+			y: "value",
+			panel: "line-panels",
+			scale: "shared-scale",
+			columns: 3,
+			reference: false,
+			context: false,
+			trend: false
+		};
+	}
+	get blank() {
+		return !this.options.data?.length;
+	}
+	facets() {
+		const { data, facet, x, y, scale } = this.options;
+		const times = data[0]?.[x] instanceof Date;
+		return {
+			facets: [...group(data, (row) => String(row[facet]))].map(([name, rows]) => {
+				const ordered = rows.flatMap((raw, i) => {
+					const position = raw[x] instanceof Date ? raw[x].getTime() : Number(raw[x] ?? i), value = raw[y];
+					return value === null || value === void 0 || !Number.isFinite(+value) ? [] : [{
+						x: Number.isFinite(position) ? position : i,
+						y: +value,
+						raw
+					}];
+				}).sort((a, b) => a.x - b.x);
+				const start = ordered[0]?.y || 1;
+				return {
+					name,
+					points: scale === "indexed-scale" ? ordered.map((point) => ({
+						...point,
+						y: point.y / start * 100
+					})) : ordered
+				};
+			}),
+			times
+		};
+	}
+	valueScale(values, top) {
+		const bars = this.options.panel === "bar-panels" || this.options.panel === "area-panels";
+		const [low = 0, high = 1] = extent(values);
+		return scaleLinear([bars ? Math.min(0, low) : low, bars ? Math.max(0, high) : high], [top, 0]).nice(3);
+	}
+	pathFor(points, fx, fy, bottom) {
+		const { panel } = this.options;
+		if (panel === "area-panels") return area().x((p) => fx(p.x)).y0(Math.min(bottom, fy(0))).y1((p) => fy(p.y)).curve(curveMonotoneX)(points) ?? "";
+		if (panel === "bar-panels") {
+			const width = Math.max(1, (fx(points[points.length - 1]?.x ?? 0) - fx(points[0]?.x ?? 0)) / Math.max(1, points.length) - 1);
+			const zero = fy(0);
+			return points.map((p) => `M${(fx(p.x) - width / 2).toFixed(2)},${Math.min(zero, fy(p.y)).toFixed(2)}h${width.toFixed(2)}v${Math.abs(zero - fy(p.y)).toFixed(2)}h${(-width).toFixed(2)}Z`).join("");
+		}
+		if (panel === "dot-panels") return points.map((p) => `M${(fx(p.x) - 1.5).toFixed(2)},${fy(p.y).toFixed(2)}a1.5,1.5 0 1,0 3,0a1.5,1.5 0 1,0 -3,0Z`).join("");
+		return line().x((p) => fx(p.x)).y((p) => fy(p.y)).curve(panel === "step-panels" ? curveStepAfter : curveMonotoneX)(points) ?? "";
+	}
+	compose(ctx) {
+		const { panel, scale, reference, context, trend, columns: wanted } = this.options;
+		const { facets, times } = this.facets();
+		const columns = Math.max(1, Math.min(wanted, facets.length)), rows = Math.ceil(facets.length / columns);
+		const every = facets.flatMap((facet) => facet.points);
+		const free = scale === "free-scale";
+		const gutter = 30, gap = free ? gutter : GAP;
+		const panelW = (ctx.plot.width - gutter - gap * (columns - 1)) / columns;
+		const panelH = (ctx.plot.height - AXIS - 28 * rows + GAP) / rows;
+		const span = extent(every, (point) => point.x);
+		const fx = times ? scaleTime([new Date(span[0]), new Date(span[1])], [0, panelW]) : scaleLinear(span, [0, panelW]);
+		const shared = this.valueScale(every.map((point) => point.y), panelH);
+		const fill = ctx.palette.sequential(.62), stroke = panel === "line-panels" || panel === "step-panels";
+		const reach = max(every, (point) => Math.abs(point.y)) ?? 1;
+		const panels = facets.map((facet, i) => ({
+			...facet,
+			column: i % columns,
+			row: Math.floor(i / columns),
+			i,
+			fy: free ? this.valueScale(facet.points.map((p) => p.y), panelH) : shared
+		}));
+		const left = (d) => gutter + d.column * (panelW + gap);
+		const top = (d) => TITLE + d.row * (panelH + GAP + TITLE);
+		ctx.marks("backs", "rect", panels, (d) => d.name).attr("x", left).attr("y", top).attr("width", panelW).attr("height", panelH).attr("fill", "none").attr("stroke", ctx.theme.grid);
+		ctx.text(ctx.marks("titles", "text", panels, (d) => d.name), 11, "ink").attr("x", left).attr("y", (d) => top(d) - 5).attr("font-weight", 600).text((d) => fitText(d.name, panelW));
+		const ghosts = context ? panels.flatMap((d) => facets.filter((other) => other.name !== d.name).map((other) => ({
+			key: `${d.name}/${other.name}`,
+			d: line().x((p) => fx(p.x)).y((p) => d.fy(p.y))(other.points) ?? "",
+			host: d
+		}))) : [];
+		ctx.marks("ghosts", "path", ghosts, (g) => g.key).attr("d", (g) => g.d).attr("transform", (g) => `translate(${left(g.host)},${top(g.host)})`).attr("fill", "none").attr("stroke", ctx.theme.axis).attr("stroke-width", 1);
+		const marks = ctx.marks("series", "path", panels, (d) => d.name).attr("d", (d) => this.pathFor(d.points, fx, d.fy, panelH)).attr("transform", (d) => `translate(${left(d)},${top(d)})`).attr("fill", stroke ? "none" : fill).attr("stroke", stroke ? fill : "none").attr("stroke-width", 2).attr("stroke-linejoin", "round");
+		if (stroke) ctx.drawOn(marks);
+		ctx.hover(marks, (d) => ({
+			title: d.name,
+			color: fill,
+			rows: [
+				["Mean", Scales.format(mean(d.points, (p) => p.y) ?? 0, reach)],
+				["Low", Scales.format(min(d.points, (p) => p.y) ?? 0, reach)],
+				["High", Scales.format(max(d.points, (p) => p.y) ?? 0, reach)]
+			]
+		}));
+		const means = reference ? panels.map((d) => ({
+			...d,
+			level: d.fy(mean(d.points, (p) => p.y) ?? 0)
+		})) : [];
+		ctx.marks("means", "line", means, (d) => d.name).attr("x1", left).attr("x2", (d) => left(d) + panelW).attr("y1", (d) => top(d) + d.level).attr("y2", (d) => top(d) + d.level).attr("stroke", ctx.theme.inkMuted).attr("stroke-dasharray", "3 3");
+		const fits = trend ? panels.flatMap((d) => {
+			const meanX = mean(d.points, (p) => p.x) ?? 0, meanY = mean(d.points, (p) => p.y) ?? 0;
+			const spread = d.points.reduce((sum, p) => sum + (p.x - meanX) ** 2, 0);
+			if (d.points.length < 2 || !spread) return [];
+			const slope = d.points.reduce((sum, p) => sum + (p.x - meanX) * (p.y - meanY), 0) / spread;
+			const at = (x) => d.fy(meanY + slope * (x - meanX));
+			const [from, to] = extent(d.points, (p) => p.x);
+			const [x1, x2, y1, y2] = [
+				fx(from),
+				fx(to),
+				at(from),
+				at(to)
+			];
+			const edge = (y) => Math.max(0, Math.min(panelH, y));
+			const inset = (y, other) => edge(y) === y ? 0 : (edge(y) - y) / (other - y);
+			return [{
+				...d,
+				x1: x1 + (x2 - x1) * inset(y1, y2),
+				x2: x2 - (x2 - x1) * inset(y2, y1),
+				y1: edge(y1),
+				y2: edge(y2)
+			}];
+		}) : [];
+		ctx.marks("trends", "line", fits, (d) => d.name).attr("x1", (d) => left(d) + d.x1).attr("x2", (d) => left(d) + d.x2).attr("y1", (d) => top(d) + d.y1).attr("y2", (d) => top(d) + d.y2).attr("stroke", ctx.theme.ink).attr("stroke-width", 1.5);
+		const ticksY = panels.filter((d) => free || d.column === 0).flatMap((d) => d.fy.ticks(3).map((tick) => ({
+			key: `${d.name}/${tick}`,
+			d,
+			tick
+		})));
+		ctx.text(ctx.marks("y-ticks", "text", ticksY, (t) => t.key), 10, "muted").attr("text-anchor", "end").attr("dy", "0.32em").attr("x", (t) => left(t.d) - 4).attr("y", (t) => top(t.d) + t.d.fy(t.tick)).text((t) => Scales.format(t.tick, reach));
+		const format = (value) => times ? new Date(value).toLocaleDateString("en", {
+			month: "short",
+			day: "numeric",
+			timeZone: "UTC"
+		}) : Scales.format(value, Math.abs(span[1]));
+		const lastRow = panels.filter((d) => d.i + columns >= panels.length);
+		const ticksX = panelW > 90 ? lastRow.flatMap((d) => [span[0], span[1]].map((tick, at) => ({
+			key: `${d.name}/${at}`,
+			d,
+			tick,
+			at
+		}))) : [];
+		ctx.text(ctx.marks("x-ticks", "text", ticksX, (t) => t.key), 10, "muted").attr("text-anchor", (t) => t.at ? "end" : "start").attr("x", (t) => left(t.d) + (t.at ? panelW : 0)).attr("y", (t) => top(t.d) + panelH + 12).text((t) => format(t.tick));
+	}
+};
+export { GridPanel, GridPlot, GridScale };

package/dist/charts/matrix/HeatmapChart.js

@@ -0,0 +1,124 @@
+import { Scales } from "../../core/Scales.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MatrixChart } from "./MatrixChart.js";
+import { MatrixGlyphs } from "./MatrixGlyphs.js";
+import { MatrixGlyph, MatrixMarginal, MatrixNormalize, MatrixOrder } from "./matrixEnums.js";
+import { contours, geoPath, geoTransform } from "d3";
+// src/charts/matrix/HeatmapChart.ts
+var HeatmapLattice = /* @__PURE__ */ function(HeatmapLattice) {
+	HeatmapLattice["Square"] = "square-lattice";
+	HeatmapLattice["Brick"] = "brick";
+	HeatmapLattice["Hexagon"] = "hexagon";
+	HeatmapLattice["Contour"] = "contour";
+	return HeatmapLattice;
+}({});
+var HeatmapAspect = /* @__PURE__ */ function(HeatmapAspect) {
+	HeatmapAspect["Fit"] = "fit";
+	HeatmapAspect["SquareCells"] = "square-cells";
+	return HeatmapAspect;
+}({});
+/** The general-purpose matrix: colour shows magnitude at each row and column crossing. */
+var HeatmapChart = class extends MatrixChart {
+	static meta = {
+		id: "heatmap",
+		name: "Heatmap",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Two,
+		shape: DataShape.Matrix,
+		description: "Shows a value at every crossing of two dimensions using colour, for spotting patterns and hot spots.",
+		tags: [
+			"matrix",
+			"grid",
+			"contour",
+			"hexagon"
+		],
+		sample: (seed) => SampleData.matrix(seed),
+		variants: {
+			lattice: [
+				"square-lattice",
+				"brick",
+				"hexagon",
+				"contour"
+			],
+			marginals: [
+				MatrixMarginal.None,
+				MatrixMarginal.Rows,
+				MatrixMarginal.Columns,
+				MatrixMarginal.Both
+			],
+			order: [
+				MatrixOrder.Input,
+				MatrixOrder.Total,
+				MatrixOrder.Cluster
+			],
+			aspect: ["fit", "square-cells"],
+			cellValues: [false, true]
+		},
+		valid: (v) => !(v.aspect === "square-cells" && (v.lattice === "hexagon" || v.lattice === "contour")) && !(v.cellValues && (v.lattice === "contour" || v.lattice === "hexagon" || v.aspect === "square-cells"))
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			lattice: "square-lattice",
+			aspect: "fit",
+			marginals: MatrixMarginal.None,
+			order: MatrixOrder.Input,
+			normalize: MatrixNormalize.None,
+			cellValues: false
+		};
+	}
+	drawMatrix(ctx, source) {
+		const { lattice, marginals, order, aspect, normalize, cellValues } = this.options;
+		const model = this.ordered(source.normalize(normalize), order);
+		const onRight = marginals === MatrixMarginal.Rows || marginals === MatrixMarginal.Both;
+		const onTop = marginals === MatrixMarginal.Columns || marginals === MatrixMarginal.Both;
+		const frame = this.frame(ctx, model, {
+			right: onRight ? 44 : 0,
+			top: onTop ? 44 : 0,
+			bottom: 22,
+			columnLabels: onTop ? "bottom" : "top",
+			square: aspect === "square-cells",
+			stagger: lattice === "brick",
+			hex: lattice === "hexagon"
+		});
+		const fill = this.heat(ctx, model.domain);
+		this.axisLabels(ctx, model, frame);
+		this.marginals(ctx, model, frame, marginals);
+		this.ramp(ctx, model.domain, frame.x, frame.y + frame.height + (onTop ? 20 : 6));
+		const format = (value) => value === null ? "no data" : Scales.format(value, model.reach);
+		if (lattice === "contour") return this.contours(ctx, model, frame, fill);
+		this.glyphs(ctx, "cells", model.cells, frame, {
+			glyph: MatrixGlyph.Tile,
+			size: () => 1,
+			fill: (cell) => fill(cell.value),
+			tip: (cell) => ({
+				title: `${cell.row} · ${cell.column}`,
+				color: fill(cell.value),
+				rows: [["Value", format(cell.value)]]
+			})
+		});
+		if (lattice === "hexagon") ctx.root.select(".m-cells").selectAll("path").attr("d", MatrixGlyphs.hexagon(frame.radius - 1));
+		this.cellText(ctx, "cell-values", cellValues ? model.cells.filter((cell) => cell.value !== null) : [], frame, (cell) => format(cell.value), (cell) => this.inkOn(ctx, fill(cell.value)));
+	}
+	contours(ctx, model, frame, fill) {
+		const [low] = model.domain, columns = model.columns.length;
+		const flat = model.values.flatMap((row) => row.map((value) => value ?? low));
+		const bands = contours().size([columns, model.rows.length]).smooth(true).thresholds(9)(flat);
+		const bed = ctx.marks("bed", "rect", [low]).attr("fill", fill(low)).attr("rx", 4).attr("x", frame.x).attr("y", frame.y).attr("width", frame.width).attr("height", frame.height);
+		ctx.hover(bed, () => ({
+			title: "Contour band",
+			rows: [["At least", Scales.format(low, model.reach)]]
+		}));
+		const project = geoPath(geoTransform({ point(x, y) {
+			this.stream.point(frame.x + x * frame.cw, frame.y + y * frame.ch);
+		} }));
+		const shapes = ctx.marks("bands", "path", bands, (band) => band.value).attr("d", (band) => project(band)).attr("fill", (band) => fill(band.value));
+		ctx.hover(shapes, (band) => ({
+			title: "Contour band",
+			color: fill(band.value),
+			rows: [["At least", Scales.format(band.value, model.reach)]]
+		}));
+	}
+};
+export { HeatmapAspect, HeatmapChart, HeatmapLattice };

package/dist/charts/matrix/HintonDiagram.js

@@ -0,0 +1,92 @@
+import { ChartFamily, ColorScale, DataShape, Dimension } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MatrixChart } from "./MatrixChart.js";
+import { MatrixGlyph, MatrixNormalize, MatrixOrder } from "./matrixEnums.js";
+// src/charts/matrix/HintonDiagram.ts
+var HintonGround = /* @__PURE__ */ function(HintonGround) {
+	HintonGround["Plain"] = "plain-ground";
+	HintonGround["Tray"] = "tray-ground";
+	return HintonGround;
+}({});
+/** Hinton's weight diagram: signed values as squares whose area is the magnitude, for model weights and factor loadings. */
+var HintonDiagram = class extends MatrixChart {
+	static meta = {
+		id: "hinton-diagram",
+		name: "Hinton diagram",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Two,
+		shape: DataShape.Matrix,
+		description: "Draws signed matrix values as sized squares, showing the pattern of weights, loadings or coefficients at a glance.",
+		tags: [
+			"weights",
+			"loadings",
+			"neural network"
+		],
+		sample: (seed) => SampleData.matrix(seed, 9, 12),
+		variants: {
+			symbol: [
+				MatrixGlyph.Square,
+				MatrixGlyph.Circle,
+				MatrixGlyph.Diamond,
+				MatrixGlyph.Triangle
+			],
+			ground: ["plain-ground", "tray-ground"],
+			normalize: [
+				MatrixNormalize.None,
+				MatrixNormalize.Row,
+				MatrixNormalize.Column
+			],
+			order: [
+				MatrixOrder.Input,
+				MatrixOrder.Total,
+				MatrixOrder.Cluster
+			]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			symbol: MatrixGlyph.Square,
+			ground: "plain-ground",
+			normalize: MatrixNormalize.None,
+			order: MatrixOrder.Input,
+			colorScale: ColorScale.Diverging
+		};
+	}
+	drawMatrix(ctx, source) {
+		const { symbol, ground, normalize, order } = this.options;
+		const model = this.ordered(source, order).normalize(normalize);
+		const frame = this.frame(ctx, model, {
+			square: true,
+			bottom: 22
+		});
+		const reach = model.reach, domain = [-reach, reach], fill = this.heat(ctx, domain);
+		this.axisLabels(ctx, model, frame);
+		ctx.marks("tray", "rect", ground === "tray-ground" ? [0] : []).attr("fill", ctx.theme.grid).attr("opacity", .5).attr("rx", 4).attr("x", frame.x).attr("y", frame.y).attr("width", frame.width).attr("height", frame.height);
+		this.glyphs(ctx, "cells", model.cells.filter((cell) => cell.value !== null), frame, {
+			glyph: symbol,
+			gap: 2,
+			size: (cell) => Math.abs(cell.value) / reach,
+			fill: (cell) => fill(Math.sign(cell.value) * .85 * reach),
+			tip: (cell) => ({
+				title: `${cell.row} · ${cell.column}`,
+				color: fill(Math.sign(cell.value) * .85 * reach),
+				rows: [["Weight", Scales.format(cell.value, reach)]]
+			})
+		});
+		const label = (value) => Scales.format(value, reach);
+		this.sizeKey(ctx, symbol, frame, frame.y + frame.height + 4, [
+			1,
+			.25,
+			-.25,
+			-1
+		].map((t) => ({
+			t: Math.abs(t),
+			sign: t,
+			fill: fill(Math.sign(t) * .85 * reach),
+			label: label(t * reach)
+		})));
+	}
+};
+export { HintonDiagram, HintonGround };

package/dist/charts/matrix/MatrixChart.js

@@ -0,0 +1,209 @@
+import { ColorScale } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { CHAR, MatrixSurface, fitText } from "./MatrixSurface.js";
+import { MatrixGlyphs } from "./MatrixGlyphs.js";
+import { MatrixGlyph, MatrixMarginal, MatrixOrder } from "./matrixEnums.js";
+import { MatrixModel } from "./MatrixModel.js";
+import { MatrixSeriation } from "./MatrixSeriation.js";
+// src/charts/matrix/MatrixChart.ts
+var BAND = 13;
+var RAMP_STEPS = 32;
+/** Rows × columns of cells. Owns the data model, grid layout, axis labels, colour ramp and cell glyphs. */
+var MatrixChart = class extends MatrixSurface {
+	defaults() {
+		return {
+			x: "series",
+			y: "category",
+			value: "value"
+		};
+	}
+	get model() {
+		return MatrixModel.from(this.options.data, this.options);
+	}
+	get blank() {
+		return this.model.empty;
+	}
+	compose(ctx) {
+		this.drawMatrix(ctx, this.model);
+	}
+	table() {
+		return {
+			columns: [
+				"row",
+				"column",
+				"value"
+			],
+			rows: this.model.cells.map((cell) => [
+				cell.row,
+				cell.column,
+				cell.value
+			])
+		};
+	}
+	ordered(model, order) {
+		if (order === MatrixOrder.Total) {
+			const rows = model.rowTotals, columns = model.columnTotals;
+			return model.reorder(model.rows.map((_, i) => i).sort((a, b) => rows[b] - rows[a] || a - b), model.columns.map((_, i) => i).sort((a, b) => columns[b] - columns[a] || a - b));
+		}
+		if (order === MatrixOrder.Cluster) return model.reorder(MatrixSeriation.clustered(model.rowVectors), MatrixSeriation.clustered(model.columnVectors));
+		return model;
+	}
+	frame(ctx, model, spec = {}) {
+		const { top = 0, right = 0, bottom = 0, left = 0, square = false, stagger = false, hex = false, rowLabels = true, columnLabels = "top" } = spec;
+		const rows = model.rows.length, columns = model.columns.length + (stagger || hex ? .5 : 0);
+		const gutter = rowLabels ? Math.min(ctx.plot.width * .3, Math.max(...model.rows.map((row) => row.length)) * CHAR + 8) : 0;
+		const areaW = Math.max(10, ctx.plot.width - left - right - gutter);
+		const longest = Math.max(...model.columns.map((column) => column.length)) * CHAR;
+		const flatHeader = longest + 6 <= areaW / columns || longest <= 30;
+		const header = columnLabels === "none" ? 0 : flatHeader ? 16 : Math.min(54, longest * .72 + 10);
+		const areaH = Math.max(10, ctx.plot.height - top - bottom - header);
+		let cw = areaW / columns, ch = areaH / rows, radius = 0;
+		if (hex) {
+			radius = Math.min(cw / Math.sqrt(3), areaH / (1.5 * rows + .5));
+			cw = Math.sqrt(3) * radius;
+			ch = 1.5 * radius;
+		} else if (square) cw = ch = Math.min(cw, ch);
+		const x = left + gutter, y = top + (columnLabels === "top" ? header : 0), inset = hex ? radius : ch / 2;
+		return {
+			x,
+			y,
+			cw,
+			ch,
+			radius,
+			header,
+			flatHeader,
+			stagger: stagger || hex,
+			hex,
+			columnLabels,
+			rowLabels,
+			width: cw * columns,
+			height: ch * rows + (hex ? radius / 2 : 0),
+			cx: (c, r = 0) => x + cw * (c + .5 + ((stagger || hex) && r % 2 ? .5 : 0)),
+			cy: (r) => y + inset + r * ch
+		};
+	}
+	axisLabels(ctx, model, frame) {
+		const rowStep = Math.ceil(BAND / frame.ch);
+		const rows = frame.rowLabels ? model.rows.map((label, r) => ({
+			label,
+			r
+		})).filter(({ r }) => r % rowStep === 0) : [];
+		ctx.text(ctx.marks("row-labels", "text", rows, (d) => d.r).attr("text-anchor", "end").attr("dy", "0.32em").attr("x", frame.x - 6).attr("y", (d) => frame.cy(d.r)).text((d) => fitText(d.label, frame.x - 6)));
+		const longest = Math.max(...model.columns.map((column) => column.length)) * CHAR;
+		const columnStep = Math.ceil((frame.flatHeader ? longest + 6 : BAND) / frame.cw);
+		const y = frame.columnLabels === "top" ? frame.y - 6 : frame.y + frame.height + 13;
+		const columns = frame.columnLabels === "none" ? [] : model.columns.map((label, c) => ({
+			label,
+			c
+		})).filter(({ c }) => c % columnStep === 0);
+		ctx.text(ctx.marks("column-labels", "text", columns, (d) => d.c).attr("text-anchor", frame.flatHeader ? "middle" : frame.columnLabels === "top" ? "start" : "end").attr("transform", (d) => `translate(${frame.cx(d.c)},${y})${frame.flatHeader ? "" : " rotate(-40)"}`).text((d) => fitText(d.label, frame.flatHeader ? 200 : frame.header * 1.3)));
+	}
+	/** Value → fill. Null renders as the recessive grid colour. */
+	heat(ctx, [low, high]) {
+		const reach = Math.max(Math.abs(low), Math.abs(high)) || 1;
+		const diverging = (this.options.colorScale ?? (low < 0 && high > 0 ? ColorScale.Diverging : ColorScale.Sequential)) === ColorScale.Diverging;
+		return (value) => {
+			if (value === null) return ctx.theme.grid;
+			return diverging ? ctx.palette.diverging(value / reach) : ctx.palette.sequential(high > low ? (value - low) / (high - low) : .6);
+		};
+	}
+	/** A stepped colour key with its end values, on one baseline. */
+	ramp(ctx, domain, x, y, format = (value) => Scales.format(value, Math.max(...domain.map(Math.abs)))) {
+		const fill = this.heat(ctx, domain);
+		const [low, high] = domain, start = format(low), end = format(high);
+		const width = Math.min(150, Math.max(60, ctx.plot.width - x - (start.length + end.length) * CHAR - 16));
+		const left = x + start.length * CHAR + 6, step = width / RAMP_STEPS;
+		const steps = Array.from({ length: RAMP_STEPS }, (_, i) => i);
+		ctx.marks("ramp", "rect", steps).attr("x", (i) => left + i * step).attr("y", y + 3).attr("width", step + .4).attr("height", 8).attr("fill", (i) => fill(low + (i + .5) / RAMP_STEPS * (high - low)));
+		ctx.text(ctx.marks("ramp-labels", "text", [{
+			text: start,
+			x,
+			anchor: "start"
+		}, {
+			text: end,
+			x: left + width + 6,
+			anchor: "start"
+		}]), 10.5).attr("x", (d) => d.x).attr("y", y + 11).attr("text-anchor", (d) => d.anchor).text((d) => d.text);
+	}
+	/** Sample glyphs with their values, so sized marks can be read back. */
+	sizeKey(ctx, glyph, frame, y, keys) {
+		const span = Math.min(frame.cw, frame.ch) - 2, scale = Math.min(1, 16 / span);
+		let x = frame.x;
+		const placed = keys.map((key, index) => {
+			const at = {
+				...key,
+				index,
+				x: x + span * scale / 2
+			};
+			x += span * scale + 4 + key.label.length * CHAR + 12;
+			return at;
+		});
+		ctx.marks("size-key", "path", placed, (d) => d.index).attr("fill", (d) => d.fill).attr("d", (d) => MatrixGlyphs.path(glyph, span, span, d.t, d.sign)).attr("transform", (d) => `translate(${d.x},${y + 8}) scale(${scale})`);
+		ctx.text(ctx.marks("size-key-labels", "text", placed, (d) => d.index), 10.5).attr("x", (d) => d.x + span * scale / 2 + 4).attr("y", y + 11.5).text((d) => d.label);
+	}
+	/** Draws cells as keyed glyph paths that pop in from their centres. */
+	glyphs(ctx, name, cells, frame, spec) {
+		const gap = spec.gap ?? Math.min(2, Math.min(frame.cw, frame.ch) * .1);
+		const w = frame.cw - gap, h = frame.ch - gap;
+		const place = spec.place ?? ((cell) => `translate(${frame.cx(cell.c, cell.r)},${frame.cy(cell.r)})`);
+		const marks = ctx.marks(name, "path", cells, (cell) => cell.key).attr("d", (cell) => MatrixGlyphs.path(spec.glyph, w, h, spec.size(cell), Math.sign(cell.value ?? 1))).attr("fill", spec.fill).attr("fill-rule", spec.glyph === MatrixGlyph.Pie ? "evenodd" : null);
+		ctx.set(marks, { transform: place }, { transform: (cell) => `${place(cell)} scale(0)` }, Math.min(1.2, 500 / (cells.length || 1)));
+		ctx.hover(marks, spec.tip);
+	}
+	/** Value text centred in cells, skipped entirely when it would not fit. */
+	cellText(ctx, name, cells, frame, text, fill, size = 10.5) {
+		const fits = Math.max(0, ...cells.map((cell) => text(cell).length)) * (size * .58) + 3 <= frame.cw && frame.ch >= size + 2;
+		ctx.marks(name, "text", fits ? cells : [], (cell) => cell.key).attr("x", (cell) => frame.cx(cell.c, cell.r)).attr("y", (cell) => frame.cy(cell.r)).attr("dy", "0.32em").attr("text-anchor", "middle").attr("font-size", size).attr("font-family", ctx.theme.fontFamily).attr("fill", fill).attr("pointer-events", "none").text(text);
+	}
+	/** Thin total bars beside the grid: rows to the right, columns on top. Bars start at zero. */
+	marginals(ctx, model, frame, which) {
+		const showRows = which === MatrixMarginal.Rows || which === MatrixMarginal.Both;
+		const showColumns = which === MatrixMarginal.Columns || which === MatrixMarginal.Both;
+		const bars = (totals) => {
+			const reach = Math.max(1e-9, ...totals.map(Math.abs));
+			const low = Math.min(0, ...totals), span = Math.max(0, ...totals) - low || reach;
+			return totals.map((total, index) => ({
+				index,
+				total,
+				start: (Math.min(0, total) - low) / span,
+				length: Math.abs(total) / span
+			}));
+		};
+		const fill = ctx.palette.sequential(.62), room = 36;
+		const rowBars = ctx.marks("row-margin", "rect", showRows ? bars(model.rowTotals) : [], (d) => d.index).attr("fill", fill).attr("rx", 2);
+		const atX = frame.x + frame.width + 6, thick = Math.max(1, Math.min(10, frame.ch - 2));
+		ctx.set(rowBars, {
+			x: (d) => atX + d.start * room,
+			y: (d) => frame.cy(d.index) - thick / 2,
+			width: (d) => d.length * room,
+			height: thick
+		}, {
+			x: atX,
+			y: (d) => frame.cy(d.index) - thick / 2,
+			width: 0,
+			height: thick
+		});
+		ctx.hover(rowBars, (d) => ({
+			title: model.rows[d.index],
+			rows: [["Row total", Scales.format(d.total, Math.abs(d.total))]]
+		}));
+		const columnBars = ctx.marks("column-margin", "rect", showColumns ? bars(model.columnTotals) : [], (d) => d.index).attr("fill", fill).attr("rx", 2);
+		const base = frame.y - 6, wide = Math.max(1, Math.min(10, frame.cw - 2));
+		ctx.set(columnBars, {
+			x: (d) => frame.cx(d.index) - wide / 2,
+			y: (d) => base - (d.start + d.length) * room,
+			width: wide,
+			height: (d) => d.length * room
+		}, {
+			x: (d) => frame.cx(d.index) - wide / 2,
+			y: base,
+			width: wide,
+			height: 0
+		});
+		ctx.hover(columnBars, (d) => ({
+			title: model.columns[d.index],
+			rows: [["Column total", Scales.format(d.total, Math.abs(d.total))]]
+		}));
+	}
+};
+export { MatrixChart };