@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/core/Chart.js

@@ -0,0 +1,250 @@
+import { ChartExportError, ExportErrorCode } from "./ChartExportError.js";
+import { ChartExporter, ExportFormat } from "./ChartExporter.js";
+import { LegendPosition, ThemeMode } from "./enums.js";
+import { LiveStream } from "./LiveStream.js";
+import { Palette } from "./Palette.js";
+import { Theme } from "./Theme.js";
+import { Tooltip } from "./Tooltip.js";
+// src/core/Chart.ts
+var prefersStill = () => globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+/**
+* Root of every chart. Owns options, host lifecycle, sizing, theme, palette and tooltip.
+* `Chart2D` renders with d3 into SVG; `Chart3D` renders with three.js into WebGL.
+*/
+var Chart = class {
+	options;
+	host = null;
+	tooltipBox = null;
+	palette;
+	theme;
+	observer = null;
+	media = null;
+	onScheme = () => this.render();
+	#stream = null;
+	#seats = /* @__PURE__ */ new Map();
+	#liveFrame = false;
+	#scratch = false;
+	constructor(options) {
+		this.options = {
+			...this.defaults(),
+			...options
+		};
+	}
+	/** Per-class option defaults; override and spread `super.defaults()`. */
+	defaults() {
+		return {};
+	}
+	get meta() {
+		return this.constructor.meta;
+	}
+	get data() {
+		return this.options.data;
+	}
+	mount(host) {
+		this.#stream?.start();
+		this.host = host;
+		if (getComputedStyle(host).position === "static") host.style.position = "relative";
+		this.tooltipBox = new Tooltip(host);
+		this.render();
+		if (typeof ResizeObserver !== "undefined" && !(this.options.width && this.options.height)) {
+			let last = "";
+			this.observer = new ResizeObserver(([entry]) => {
+				const key = `${entry.contentRect.width}x${entry.contentRect.height}`;
+				if (key !== last) {
+					const first = !last;
+					last = key;
+					if (!first) this.render();
+				}
+			});
+			this.observer.observe(host);
+		}
+		if ((this.options.theme ?? ThemeMode.Auto) === ThemeMode.Auto && typeof matchMedia === "function") {
+			this.media = matchMedia("(prefers-color-scheme: dark)");
+			this.media.addEventListener("change", this.onScheme);
+		}
+		return this;
+	}
+	update(patch) {
+		this.options = {
+			...this.options,
+			...patch
+		};
+		if ("data" in patch && this.#stream) {
+			this.#stream.reset(patch.data);
+			this.#seats.clear();
+		}
+		return this.render();
+	}
+	/**
+	* Adds rows without replacing the data, repainting at most once per animation frame. Takes flat
+	* rows or long-form series rows, on 2D table charts; other charts throw. `window` and `keep`
+	* bound what is held and stick for later calls; with neither, rows accumulate without limit.
+	*/
+	append(rows, options) {
+		this.#liveStream.push(rows, options);
+		return this;
+	}
+	/** Paints appended rows now instead of on the next frame. */
+	flush() {
+		this.#stream?.flush();
+		return this;
+	}
+	/** Freezes the picture while rows keep arriving; `resume` catches up. */
+	pause() {
+		this.#liveStream.pause();
+		return this;
+	}
+	resume() {
+		this.#stream?.resume();
+		return this;
+	}
+	get paused() {
+		return this.#stream?.paused ?? false;
+	}
+	/** True once rows have been appended, when `options.data` holds more than the data passed in. */
+	get streaming() {
+		return !!this.#stream;
+	}
+	get #liveStream() {
+		LiveStream.assert(this.meta, this.options.data);
+		if (!this.#stream) for (const { key } of this.palette?.items() ?? []) this.#seats.set(key, this.#seats.size);
+		return this.#stream ??= new LiveStream(this.options.data, () => this.#liveColumns, () => !!this.host, (held) => this.#commit(held));
+	}
+	/** Mounts for one measurement or export. The `destroy` that ends it leaves the stream open. */
+	mountScratch(host) {
+		this.#scratch = !this.#stream?.stopped;
+		return this.mount(host);
+	}
+	get #liveColumns() {
+		const { x, series, group } = this.options;
+		const split = [series, group].find((column) => typeof column === "string");
+		return {
+			x: typeof x === "string" ? x : void 0,
+			series: split
+		};
+	}
+	#commit(rows) {
+		this.options = {
+			...this.options,
+			data: rows
+		};
+		this.#liveFrame = true;
+		try {
+			this.render();
+		} finally {
+			this.#liveFrame = false;
+		}
+	}
+	destroy() {
+		this.#stream?.stop(this.#scratch);
+		this.#scratch = false;
+		this.observer?.disconnect();
+		this.media?.removeEventListener("change", this.onScheme);
+		this.teardown();
+		this.tooltipBox?.destroy();
+		this.tooltipBox = null;
+		this.host = null;
+	}
+	/** Tabular view of the data for accessibility and export. Override for non-row data. */
+	table() {
+		const data = this.options.data;
+		if (!Array.isArray(data)) return {
+			columns: [],
+			rows: []
+		};
+		const rows = data.filter((row) => row !== null && typeof row === "object");
+		const columns = /* @__PURE__ */ new Set();
+		for (const row of rows) for (const column in row) columns.add(column);
+		return {
+			columns: [...columns],
+			rows: rows.map((row) => [...columns].map((column) => row[column]))
+		};
+	}
+	/** What this chart can export right now. Check this before offering a format. */
+	get exportFormats() {
+		return [ExportFormat.PNG, ...this.#rows.rows.length ? [ExportFormat.CSV] : []];
+	}
+	/** The chart as SVG text. Map tiles stay links here: use `toStandaloneSVG` to embed them. 3D charts have no SVG and throw. */
+	toSVG() {
+		throw new ChartExportError(ExportErrorCode.Unsupported, `SVG export is unavailable for ${this.meta.name}: 3D charts render to WebGL. Use toPNG() or toCSV().`);
+	}
+	/** `toSVG` with map tiles and page fonts embedded, so the file needs nothing else. Rejects if a tile cannot be read. */
+	async toStandaloneSVG() {
+		return this.toSVG();
+	}
+	/** The chart as a PNG. 2D charts rasterize their SVG; 3D charts draw the current camera view from their renderer. */
+	async toPNG({ scale } = {}) {
+		const multiple = ChartExporter.scale(scale);
+		return ChartExporter.png(await this.rasterize(multiple));
+	}
+	/** `table()` as CSV text. Throws when the chart has no rows; see `exportFormats`. */
+	toCSV() {
+		this.flush();
+		return ChartExporter.csv(this.#rows);
+	}
+	/** `table()` for exports. Overrides read their own data shape, so a chart holding none has no rows. */
+	get #rows() {
+		return this.options.data == null ? {
+			columns: [],
+			rows: []
+		} : this.table();
+	}
+	/** Saves the chart through the browser's download flow. */
+	async download(format = ExportFormat.PNG, { filename, scale } = {}) {
+		ChartExporter.save(await this.#file(format, scale), filename ?? `${this.meta.id}.${format}`);
+	}
+	async #file(format, scale) {
+		if (format === ExportFormat.PNG) return this.toPNG({ scale });
+		return format === ExportFormat.SVG ? ChartExporter.blob(await this.toStandaloneSVG(), format) : ChartExporter.blob(this.toCSV(), format);
+	}
+	/** Settles once anything the chart loads by itself has arrived. Exports wait for it, so they never picture a chart still loading. */
+	async ready() {
+		await this.meta.prepare?.();
+	}
+	render() {
+		this.theme = Theme.resolve(this.options.theme);
+		this.palette = new Palette(this.theme, this.#stream ? this.#seats : void 0);
+		if (this.host) this.paint();
+		return this;
+	}
+	get size() {
+		const box = this.host?.getBoundingClientRect();
+		return {
+			width: this.options.width ?? (box?.width || 640),
+			height: this.options.height ?? (box?.height || 400)
+		};
+	}
+	get animated() {
+		return this.motionAllowed && !this.liveSliding;
+	}
+	get motionAllowed() {
+		return (this.options.animate ?? true) && !prefersStill();
+	}
+	/** True during a paint caused by appended rows. */
+	get liveFrame() {
+		return this.#liveFrame;
+	}
+	/** True when this live paint draws final geometry and the marks slide as one instead. */
+	get liveSliding() {
+		return false;
+	}
+	get legendPosition() {
+		return this.options.legend ?? LegendPosition.Top;
+	}
+	get label() {
+		return this.options.ariaLabel ?? this.options.title ?? this.meta.name;
+	}
+	tip(event, content) {
+		if (this.options.tooltip !== false) this.tooltipBox?.show(event, content, this.theme);
+	}
+	untip() {
+		this.tooltipBox?.hide();
+	}
+	margin(base) {
+		return {
+			...base,
+			...this.options.margin
+		};
+	}
+};
+export { Chart };

package/dist/core/Chart2D.js

@@ -0,0 +1,249 @@
+import { Chart } from "./Chart.js";
+import { ChartExporter, ExportFormat } from "./ChartExporter.js";
+import { Context2D } from "./Context2D.js";
+import { LegendPosition } from "./enums.js";
+import { KeyboardNav } from "./KeyboardNav.js";
+import { select } from "d3";
+// src/core/Chart2D.ts
+var ROW = 22;
+var CHAR = 6.4;
+/** Layout, title, legend and SVG root for all d3 charts. Subclasses implement `draw`. */
+var Chart2D = class extends Chart {
+	svg = null;
+	#legendRows = 1;
+	#keyboard = null;
+	/** Room the marks need around the plot, excluding title and legend. */
+	plotMargin() {
+		return {
+			top: 12,
+			right: 16,
+			bottom: 16,
+			left: 16
+		};
+	}
+	/** True while marks move by the chart's own clock, which an export stops with a paint and restarts with another. */
+	get looping() {
+		return false;
+	}
+	/** Adds what the SVG alone cannot show to an export. Runs while the chart is still drawn. */
+	finishCopy(_copy) {}
+	/** Legend entries. Defaults to every key given to `palette.color` during `draw`. */
+	legendItems() {
+		return this.palette.items();
+	}
+	/** The legend's size depends on what `draw` colours, so a change of row count lays out once more. */
+	paint() {
+		this.#layoutOnce();
+		const rows = this.#fitLegend();
+		if (rows !== this.#legendRows) {
+			this.#legendRows = rows;
+			this.#layoutOnce();
+		}
+		if (this.liveFrame) Context2D.releaseHover(this.svg.node());
+	}
+	#shownLegend() {
+		if (this.legendPosition === LegendPosition.None) return [];
+		const items = this.legendItems();
+		return items.length >= 2 ? items : [];
+	}
+	#fitLegend() {
+		const items = this.#shownLegend();
+		if (this.legendPosition === LegendPosition.Right) return items.length ? 1 : 0;
+		const room = this.size.width - 24;
+		let rows = items.length ? 1 : 0, x = 0;
+		for (const item of items) {
+			const cost = legendCost(item);
+			if (x && x + cost > room) {
+				rows++;
+				x = 0;
+			}
+			x += cost;
+		}
+		return rows;
+	}
+	#layoutOnce() {
+		const { width, height } = this.size;
+		const { title, subtitle } = this.options;
+		if (!this.svg) {
+			this.svg = select(this.host).append("svg").attr("role", "img").style("display", "block").style("max-width", "100%");
+			this.svg.append("title");
+			this.svg.append("g").attr("class", "g-header");
+			this.svg.append("g").attr("class", "g-plot");
+			this.svg.append("g").attr("class", "g-legend");
+		}
+		const svg = this.svg;
+		svg.attr("viewBox", `0 0 ${width} ${height}`).attr("width", width).attr("height", height).attr("aria-label", this.label).style("background", this.theme.surface).style("font-family", this.theme.fontFamily);
+		svg.select("title").text(this.label);
+		const headerHeight = (title ? 24 : 0) + (subtitle ? 18 : 0);
+		const margin = this.margin(this.plotMargin());
+		const position = this.legendPosition;
+		const reserve = position === LegendPosition.Top || position === LegendPosition.Bottom ? ROW * this.#legendRows : 0;
+		const rail = position === LegendPosition.Right && this.#legendRows ? 120 : 0;
+		const top = headerHeight + margin.top + (position === LegendPosition.Top ? reserve : 0);
+		const plot = {
+			x: 0,
+			y: 0,
+			width: Math.max(10, width - margin.left - margin.right - rail),
+			height: Math.max(10, height - top - margin.bottom - (position === LegendPosition.Bottom ? reserve : 0))
+		};
+		const root = svg.select("g.g-plot").attr("transform", `translate(${margin.left},${top})`);
+		const ctx = new Context2D(svg, root, plot, this.theme, this.palette, this.animated, (event, content) => this.tip(event, content), () => this.untip(), (datum) => this.options.onSelect?.(datum), this.#readyKeyboard({
+			...plot,
+			x: margin.left,
+			y: top
+		})?.register);
+		ctx.live = this.liveFrame;
+		this.drawHeader(svg, width);
+		if (this.options.data != null) this.draw(ctx);
+		else root.selectAll("*").remove();
+		this.drawLegend(svg, width, height, headerHeight, plot.height, top, margin);
+		this.#keyboard?.settle();
+	}
+	#readyKeyboard(area) {
+		if (!this.options.keyboard) {
+			this.#keyboard?.destroy();
+			return this.#keyboard = null;
+		}
+		this.#keyboard ??= new KeyboardNav(this.svg.node(), this.host, this.tooltipBox, (point, content) => this.tip(point, content));
+		if (this.options.tooltip === false) this.untip();
+		this.#keyboard.reset(this.theme, this.palette, this.options.series, area);
+		return this.#keyboard;
+	}
+	teardown() {
+		this.#keyboard?.destroy();
+		this.#keyboard = null;
+		this.svg?.remove();
+		this.svg = null;
+	}
+	signature() {
+		const detached = !this.host;
+		if (detached) this.mountScratch(document.createElement("div"));
+		const parts = [];
+		this.svg.select("g.g-plot").selectAll("*").each(function() {
+			const el = this;
+			const geometry = GEOMETRY.map((name) => el.getAttribute(name)).filter((value) => value !== null).join(",");
+			if (geometry) parts.push(`${el.tagName}:${geometry}`);
+		});
+		if (detached) this.destroy();
+		return parts.join("|");
+	}
+	get exportFormats() {
+		return [ExportFormat.SVG, ...super.exportFormats];
+	}
+	toSVG() {
+		return ChartExporter.serialize(this.#snapshot());
+	}
+	async toStandaloneSVG() {
+		return ChartExporter.serialize((await this.#embedded()).copy);
+	}
+	/** Size and surface come from the copy: a resize, theme change or destroy may land while the image loads. */
+	async rasterize(scale) {
+		const { copy, surface } = await this.#embedded();
+		return ChartExporter.raster(ChartExporter.serialize(copy), {
+			width: +copy.getAttribute("width"),
+			height: +copy.getAttribute("height")
+		}, scale, surface);
+	}
+	async #embedded() {
+		await this.ready();
+		const copy = this.#snapshot(), { theme } = this;
+		await ChartExporter.embed(copy, theme);
+		return {
+			copy,
+			surface: theme.surface
+		};
+	}
+	/** A finished copy of the chart. Marks still moving, or an unmounted chart, are drawn once with animation off. */
+	#snapshot() {
+		this.flush();
+		const { animate } = this.options, { looping } = this;
+		const scratch = this.host ? null : ChartExporter.scratch(this.size);
+		this.options.animate = false;
+		try {
+			if (scratch) this.mountScratch(scratch);
+			else if (looping || ChartExporter.animating(this.svg.node())) this.render();
+			const copy = ChartExporter.document(this.svg.node(), this.theme);
+			this.#keyboard?.scrub(copy);
+			this.finishCopy(copy);
+			return copy;
+		} finally {
+			this.options.animate = animate;
+			if (scratch) {
+				this.destroy();
+				scratch.remove();
+			} else if (looping) this.render();
+		}
+	}
+	drawHeader(svg, width) {
+		const lines = [this.options.title && {
+			text: this.options.title,
+			size: 15,
+			weight: 600,
+			fill: this.theme.ink,
+			y: 18
+		}, this.options.subtitle && {
+			text: this.options.subtitle,
+			size: 12,
+			weight: 400,
+			fill: this.theme.inkSecondary,
+			y: this.options.title ? 37 : 14
+		}].filter(Boolean);
+		svg.select("g.g-header").selectAll("text").data(lines).join("text").attr("x", 16).attr("y", (d) => d.y).attr("font-size", (d) => d.size).attr("font-weight", (d) => d.weight).attr("fill", (d) => d.fill).attr("textLength", (d) => d.text.length * d.size * .6 > width - 32 ? width - 32 : null).text((d) => d.text);
+	}
+	drawLegend(svg, width, height, headerHeight, plotHeight, top, margin) {
+		const position = this.legendPosition;
+		const shown = this.#shownLegend();
+		let x = 16, y = headerHeight + 15;
+		if (position === LegendPosition.Bottom) y = top + plotHeight + margin.bottom + 14;
+		if (position === LegendPosition.Right) {
+			x = width - 112;
+			y = top + 10;
+		}
+		const left = x;
+		const placed = shown.map((item) => {
+			const name = item.label ?? item.key, cost = legendCost(item);
+			if (position !== LegendPosition.Right && x > left && x + cost > width - 8) {
+				x = left;
+				y += ROW;
+			}
+			const at = {
+				...item,
+				name,
+				x,
+				y
+			};
+			if (position === LegendPosition.Right) y += 18;
+			else x += cost;
+			return at;
+		});
+		const legend = svg.select("g.g-legend").selectAll("g").data(placed, (d) => d.key).join((enter) => {
+			const g = enter.append("g");
+			g.append("rect").attr("width", 10).attr("height", 10).attr("rx", 3).attr("y", -9);
+			g.append("text").attr("x", 15).attr("font-size", 11.5);
+			return g;
+		});
+		legend.attr("transform", (d) => `translate(${d.x},${d.y})`);
+		legend.select("rect").attr("fill", (d) => d.color);
+		legend.select("text").attr("fill", this.theme.inkSecondary).text((d) => d.name);
+	}
+};
+var legendCost = (item) => 32 + (item.label ?? item.key).length * CHAR;
+var GEOMETRY = [
+	"d",
+	"x",
+	"y",
+	"width",
+	"height",
+	"cx",
+	"cy",
+	"r",
+	"rx",
+	"ry",
+	"x1",
+	"x2",
+	"y1",
+	"y2",
+	"points",
+	"transform"
+];
+export { Chart2D };