@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/core/ChartExporter.js

@@ -0,0 +1,298 @@
+import { ChartExportError, ExportErrorCode } from "./ChartExportError.js";
+// src/core/ChartExporter.ts
+var ExportFormat = /* @__PURE__ */ function(ExportFormat) {
+	ExportFormat["SVG"] = "svg";
+	ExportFormat["PNG"] = "png";
+	ExportFormat["CSV"] = "csv";
+	return ExportFormat;
+}({});
+var SVG_NS = "http://www.w3.org/2000/svg";
+var MIME = {
+	["svg"]: "image/svg+xml;charset=utf-8",
+	["png"]: "image/png",
+	["csv"]: "text/csv;charset=utf-8"
+};
+/** What the page's stylesheets can change about a mark. Dash patterns are left out: only a line's reveal animation styles them. */
+var STYLED = [
+	"fill",
+	"fill-opacity",
+	"fill-rule",
+	"stroke",
+	"stroke-opacity",
+	"stroke-width",
+	"stroke-linecap",
+	"stroke-linejoin",
+	"paint-order",
+	"opacity",
+	"visibility",
+	"font-family",
+	"font-size",
+	"font-style",
+	"font-weight",
+	"letter-spacing",
+	"text-anchor",
+	"dominant-baseline"
+];
+/** Inline styles that only make sense on a live page. Marks style opacity inline only to dim what is not hovered. */
+var LIVE_ONLY = [
+	"cursor",
+	"pointer-events",
+	"touch-action",
+	"transition",
+	"stroke-dasharray",
+	"stroke-dashoffset",
+	"opacity",
+	"scale",
+	"transform-origin",
+	"transform-box",
+	"--geo-unzoom"
+];
+/** The same for the root alone: on a mark, `display: none` is what keeps it hidden. */
+var LIVE_ROOT = [
+	"display",
+	"max-width",
+	"background",
+	"position",
+	"z-index"
+];
+/** On-screen controls, hit areas and the keyboard cursor. None of them belongs in a picture of the chart. */
+var CHROME = "[role=\"button\"], .m-zoom-hit, .g-keyboard";
+var TIMEOUT = 2e4;
+/** Characters XML has no way to write, which would make the whole file unreadable. */
+var UNWRITABLE = /[^\t\n\r\x20-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/gu;
+var FORMULA = /^[=+\-@\t\r]/;
+var quoteless = (name) => name.trim().replace(/^['"]|['"]$/g, "").toLowerCase();
+/**
+* Turns a chart into files. Builds on what every chart already has: its SVG root or a canvas, and `table()`.
+* Use the `Chart` methods (`toSVG`, `toPNG`, `toCSV`, `download`); this class holds the shared steps.
+*/
+var ChartExporter = class ChartExporter {
+	/** Comma-separated values per RFC 4180. Text that a spreadsheet would run as a formula is prefixed with `'`. */
+	static csv({ columns, rows }) {
+		if (!rows.length) throw new ChartExportError(ExportErrorCode.NoData, "CSV export needs rows, and this chart's data has no flat table view.");
+		return [columns, ...rows].map((row) => row.map((cell) => ChartExporter.#cell(cell)).join(",")).join("\r\n");
+	}
+	static #cell(cell) {
+		const text = ChartExporter.#text(cell);
+		return /[",\r\n]/.test(text) ? `"${text.replaceAll("\"", "\"\"")}"` : text;
+	}
+	static #text(cell) {
+		if (cell === null || cell === void 0) return "";
+		if (cell instanceof Date) return Number.isNaN(+cell) ? "" : cell.toISOString();
+		if (typeof cell === "number") return Number.isNaN(cell) ? "" : String(cell);
+		if (typeof cell === "object") return ChartExporter.#json(cell);
+		const text = String(cell);
+		return typeof cell === "string" && FORMULA.test(text) && !Number.isFinite(+text) ? `'${text}` : text;
+	}
+	/** Layouts leave cycles in the objects they are handed, which JSON cannot write. */
+	static #json(cell) {
+		try {
+			return JSON.stringify(cell);
+		} catch {
+			return String(cell);
+		}
+	}
+	/**
+	* A standalone copy of a live chart's SVG: computed styles written onto the marks, zoom state baked
+	* into plain transforms, the theme surface as a real rectangle, and on-screen controls removed.
+	*/
+	static document(svg, theme) {
+		ChartExporter.#finish(svg);
+		const copy = svg.cloneNode(true);
+		ChartExporter.#inline(svg, copy);
+		copy.querySelectorAll(CHROME).forEach((el) => el.remove());
+		copy.querySelectorAll("[tabindex]").forEach((el) => el.removeAttribute("tabindex"));
+		for (const el of [copy, ...copy.querySelectorAll("[style]")]) {
+			for (const name of el === copy ? [...LIVE_ONLY, ...LIVE_ROOT] : LIVE_ONLY) el.style.removeProperty(name);
+			if (!el.style.length) el.removeAttribute("style");
+		}
+		copy.setAttribute("font-family", theme.fontFamily);
+		const surface = copy.ownerDocument.createElementNS(SVG_NS, "rect");
+		for (const [name, value] of Object.entries({
+			x: 0,
+			y: 0,
+			width: svg.getAttribute("width"),
+			height: svg.getAttribute("height"),
+			fill: theme.surface
+		})) surface.setAttribute(name, `${value}`);
+		copy.insertBefore(surface, copy.querySelector(":scope > title")?.nextSibling ?? copy.firstChild);
+		return copy;
+	}
+	/** Web Animations show through computed styles, so fades and line reveals jump to their end first. */
+	static #finish(svg) {
+		for (const motion of svg.getAnimations?.({ subtree: true }) ?? []) if (motion.effect?.getComputedTiming().iterations !== Infinity) motion.finish();
+	}
+	/** Writes only what differs from the parent, so output stays close to the size of the live SVG. */
+	static #inline(live, copy) {
+		const copies = [copy, ...copy.querySelectorAll("*")];
+		const values = /* @__PURE__ */ new Map();
+		[live, ...live.querySelectorAll("*")].forEach((el, index) => {
+			const computed = getComputedStyle(el), own = {}, parent = values.get(el.parentElement), target = copies[index];
+			for (const name of STYLED) {
+				if (name === "opacity" && el.style.opacity) continue;
+				const value = own[name] = computed.getPropertyValue(name);
+				const inherited = name === "opacity" ? "1" : parent?.[name];
+				if (value && value !== inherited && !value.includes("url(")) target.setAttribute(name, value);
+			}
+			values.set(el, own);
+			ChartExporter.#bakeScale(el, target, computed);
+		});
+	}
+	/** Map symbols hold their size with the CSS `scale` property, which SVG tools outside the browser ignore. */
+	static #bakeScale(el, target, computed) {
+		const scale = parseFloat(computed.scale);
+		if (!el.style.scale || !Number.isFinite(scale)) return;
+		const box = computed.transformBox === "fill-box" ? el.getBBox?.() : null;
+		const [x = 0, y = 0] = box ? [box.x + box.width / 2, box.y + box.height / 2] : computed.transformOrigin.split(" ").map(parseFloat);
+		const placed = target.getAttribute("transform");
+		target.setAttribute("transform", `translate(${x} ${y}) scale(${scale})${placed ? ` ${placed}` : ""} translate(${-x} ${-y})`);
+	}
+	/**
+	* Replaces links inside an exported SVG with their bytes: map tiles and any `@font-face` the page
+	* declares for the theme's font. Tiles must be readable across origins, or this rejects. A font
+	* that cannot be fetched stays linked, because the text still draws in the fallback fonts.
+	*/
+	static async embed(svg, theme) {
+		await Promise.all([...svg.querySelectorAll("image")].map(async (image) => {
+			const url = image.getAttribute("href");
+			if (url && !url.startsWith("data:")) image.setAttribute("href", await ChartExporter.#tile(url));
+		}));
+		const fonts = await ChartExporter.#fonts(theme.fontFamily);
+		if (!fonts) return;
+		const style = svg.ownerDocument.createElementNS(SVG_NS, "style");
+		style.textContent = fonts;
+		svg.insertBefore(style, svg.querySelector(":scope > title")?.nextSibling ?? svg.firstChild);
+	}
+	static async #tile(url) {
+		try {
+			const data = await ChartExporter.#fetch(url);
+			if (data.startsWith("data:image/")) return data;
+			throw new Error("the response is not an image");
+		} catch (cause) {
+			throw new ChartExportError(ExportErrorCode.Tainted, `Cannot embed map tile ${url}: ${cause.message}. Pages may only read tiles from servers that send Access-Control-Allow-Origin. Use a tile source with CORS enabled, or drop \`tiles\` for this export. toSVG() still works, and keeps tiles as links.`, { cause });
+		}
+	}
+	static async #fetch(url) {
+		const response = await fetch(url, {
+			mode: "cors",
+			credentials: "omit",
+			signal: AbortSignal.timeout(TIMEOUT)
+		});
+		if (!response.ok) throw new Error(`the server answered ${response.status}`);
+		const blob = await response.blob();
+		return new Promise((resolve, reject) => {
+			const reader = new FileReader();
+			reader.onload = () => resolve(reader.result);
+			reader.onerror = () => reject(reader.error ?? /* @__PURE__ */ new Error("the response could not be read"));
+			reader.readAsDataURL(blob);
+		});
+	}
+	static async #fonts(family) {
+		const wanted = new Set(family.split(",").map(quoteless));
+		const rules = [];
+		for (const sheet of document.styleSheets) {
+			let list;
+			try {
+				list = sheet.cssRules;
+			} catch {
+				continue;
+			}
+			for (const rule of ChartExporter.#rules(list)) if (rule.constructor.name === "CSSFontFaceRule" && wanted.has(quoteless(rule.style.getPropertyValue("font-family")))) rules.push(ChartExporter.#fontFace(rule.cssText, sheet.href ?? document.baseURI));
+		}
+		return (await Promise.all(rules)).join("\n");
+	}
+	/** Every rule, including those nested in `@media` or `@layer`. */
+	static *#rules(list) {
+		for (const rule of list) {
+			yield rule;
+			if ("cssRules" in rule) yield* ChartExporter.#rules(rule.cssRules);
+		}
+	}
+	static async #fontFace(css, base) {
+		let out = css;
+		for (const [link, url] of css.matchAll(/url\(["']?([^"')]+)["']?\)/g)) {
+			if (url.startsWith("data:")) continue;
+			out = out.replace(link, await ChartExporter.#fetch(new URL(url, base).href).then((data) => `url("${data}")`, () => link));
+		}
+		return out;
+	}
+	static serialize(svg) {
+		return new XMLSerializer().serializeToString(svg).replace(UNWRITABLE, "");
+	}
+	/** Draws SVG text onto a canvas filled with `surface`. The SVG must already be embedded: an SVG image cannot load links. */
+	static async raster(svg, { width, height }, scale, surface) {
+		const url = URL.createObjectURL(ChartExporter.blob(svg, "svg"));
+		try {
+			const image = await ChartExporter.#load(url);
+			const canvas = ChartExporter.canvas(width * scale, height * scale);
+			const paint = ChartExporter.paint(canvas);
+			paint.fillStyle = surface;
+			paint.fillRect(0, 0, canvas.width, canvas.height);
+			paint.drawImage(image, 0, 0, canvas.width, canvas.height);
+			return canvas;
+		} finally {
+			URL.revokeObjectURL(url);
+		}
+	}
+	static #load(url) {
+		return new Promise((resolve, reject) => {
+			const image = new Image();
+			image.onload = () => resolve(image);
+			image.onerror = () => reject(new ChartExportError(ExportErrorCode.Encoding, "The browser could not decode the exported SVG."));
+			image.src = url;
+		});
+	}
+	static canvas(width, height) {
+		const canvas = document.createElement("canvas");
+		canvas.width = Math.round(width);
+		canvas.height = Math.round(height);
+		return canvas;
+	}
+	static paint(canvas) {
+		const paint = canvas.getContext("2d");
+		if (!paint) throw new ChartExportError(ExportErrorCode.Encoding, `The browser could not create a ${canvas.width}×${canvas.height} canvas. Try a smaller scale.`);
+		return paint;
+	}
+	/** Encodes a canvas, turning a tainted or oversized canvas into a clear error. */
+	static png(canvas) {
+		return new Promise((resolve, reject) => {
+			const tooLarge = () => new ChartExportError(ExportErrorCode.Encoding, `The browser could not encode a ${canvas.width}×${canvas.height} PNG. Try a smaller scale.`);
+			try {
+				canvas.toBlob((blob) => blob ? resolve(blob) : reject(tooLarge()), MIME["png"]);
+			} catch (cause) {
+				reject(cause.name === "SecurityError" ? new ChartExportError(ExportErrorCode.Tainted, "The chart drew a cross-origin image, so the browser will not let the page read it as a PNG.", { cause }) : cause);
+			}
+		});
+	}
+	static scale(scale = 2) {
+		if (Number.isFinite(scale) && scale > 0) return scale;
+		throw new RangeError(`PNG scale must be a positive number, got ${scale}.`);
+	}
+	/** A file for `content`. CSV carries a byte order mark, which Excel needs to read UTF-8. */
+	static blob(content, format) {
+		return new Blob([format === "csv" ? "" : "", content], { type: MIME[format] });
+	}
+	/** Whether any mark is still moving, in which case the DOM holds in-between geometry. */
+	static animating(svg) {
+		return !!svg.querySelector(".live-marks[transform]") || !!svg.getAnimations?.({ subtree: true }).length || [...svg.querySelectorAll("*")].some((el) => "__transition" in el && el.__transition);
+	}
+	/** An off-screen host, so an unmounted chart still measures text and resolves styles. */
+	static scratch({ width, height }) {
+		const host = document.createElement("div");
+		host.style.cssText = `position:absolute;left:-99999px;top:0;width:${width}px;height:${height}px`;
+		host.setAttribute("aria-hidden", "true");
+		return document.body.appendChild(host);
+	}
+	/** Hands a file to the browser's download flow. Use it directly for a Blob you already hold. */
+	static save(blob, filename) {
+		const url = URL.createObjectURL(blob);
+		const link = document.createElement("a");
+		link.href = url;
+		link.download = filename;
+		link.style.display = "none";
+		document.body.appendChild(link).click();
+		link.remove();
+		setTimeout(() => URL.revokeObjectURL(url), 3e4);
+	}
+};
+export { ChartExporter, ExportFormat };

package/dist/core/ChartRegistry.js

@@ -0,0 +1,53 @@
+import { VariantSpace } from "./VariantSpace.js";
+// src/core/ChartRegistry.ts
+/** Catalog of every chart class and every expanded chart type. */
+var ChartRegistry = class {
+	classes = /* @__PURE__ */ new Map();
+	types = /* @__PURE__ */ new Map();
+	register(...charts) {
+		for (const chart of charts) {
+			if (this.classes.has(chart.meta.id)) throw new Error(`Duplicate chart id: ${chart.meta.id}`);
+			this.classes.set(chart.meta.id, chart);
+			for (const type of VariantSpace.expand(chart)) {
+				if (this.types.has(type.id)) throw new Error(`Duplicate chart type: ${type.id}`);
+				this.types.set(type.id, type);
+			}
+		}
+		return this;
+	}
+	get classCount() {
+		return this.classes.size;
+	}
+	get typeCount() {
+		return this.types.size;
+	}
+	allClasses() {
+		return [...this.classes.values()];
+	}
+	allTypes() {
+		return [...this.types.values()];
+	}
+	type(id) {
+		return this.types.get(id);
+	}
+	find({ text, family, dimension } = {}) {
+		const words = text?.toLowerCase().split(/\s+/).filter(Boolean) ?? [];
+		return this.allTypes().filter(({ chart: { meta }, name, id }) => {
+			if (family && meta.family !== family) return false;
+			if (dimension && meta.dimension !== dimension) return false;
+			const haystack = `${id} ${name} ${meta.description} ${meta.tags?.join(" ") ?? ""}`.toLowerCase();
+			return words.every((word) => haystack.includes(word));
+		});
+	}
+	/** Instantiate a chart, or a variant found through `find` or `type`. Options override variant values; sample data is the fallback. */
+	create(chart, options = {}) {
+		const type = typeof chart === "string" ? this.types.get(chart) : chart;
+		if (!type) throw new Error(`Unknown chart type: ${String(chart)}`);
+		return new type.chart({
+			data: type.chart.meta.sample(1),
+			...type.values,
+			...options
+		});
+	}
+};
+export { ChartRegistry };