@mstone6969/graph 0.1.0 → 0.2.0

package/dist/core/ExcelWriter.js

@@ -0,0 +1,152 @@
+import { ChartExporter } from "./ChartExporter.js";
+import { ChartExportError, ExportErrorCode } from "./ChartExportError.js";
+import { ExportText } from "./ExportText.js";
+import { strToU8, zipSync } from "fflate";
+// src/core/ExcelWriter.ts
+var TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+var HEAD = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n";
+var MAIN = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+var PACKAGE = "http://schemas.openxmlformats.org/package/2006";
+var LINKS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+var CONTENT = "application/vnd.openxmlformats-officedocument";
+var MAX_COLUMNS = 16384;
+var MAX_ROWS = 1048576;
+var MAX_TEXT = 32767;
+var MAX_SERIAL = 2958465;
+var DAY = 864e5;
+/** Excel counts days from this date, and believes 1900 was a leap year, so its first 60 days read one too high. */
+var EPOCH = Date.UTC(1899, 11, 30);
+var LEAP_BUG = 61;
+var EMU_PER_PIXEL = 9525;
+var [MIN_WIDTH, MAX_WIDTH] = [8, 60];
+/** Column widths come from this many rows, so a million-row sheet is not measured cell by cell. */
+var MEASURED = 1e3;
+/** Indexes into `cellXfs`. */
+var Style = {
+	Date: 1,
+	DateTime: 2,
+	Header: 3,
+	Guarded: 4
+};
+/** A stored string is never run as a formula. The guarded style also keeps it text when someone edits the cell. */
+var FORMULA = /^[=+\-@\t\r\n]/;
+var STYLES = `${HEAD}<styleSheet xmlns="${MAIN}"><numFmts count="2"><numFmt numFmtId="164" formatCode="yyyy\\-mm\\-dd"/><numFmt numFmtId="165" formatCode="yyyy\\-mm\\-dd\\ hh:mm:ss"/></numFmts><fonts count="2"><font><sz val="11"/><name val="Calibri"/></font><font><b/><sz val="11"/><name val="Calibri"/></font></fonts><fills count="2"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill></fills><borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders><cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs><cellXfs count="5"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/><xf numFmtId="164" fontId="0" fillId="0" borderId="0" xfId="0" applyNumberFormat="1"/><xf numFmtId="165" fontId="0" fillId="0" borderId="0" xfId="0" applyNumberFormat="1"/><xf numFmtId="49" fontId="1" fillId="0" borderId="0" xfId="0" quotePrefix="1" applyNumberFormat="1" applyFont="1"/><xf numFmtId="49" fontId="0" fillId="0" borderId="0" xfId="0" quotePrefix="1" applyNumberFormat="1"/></cellXfs><cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles></styleSheet>`;
+/** Writes an .xlsx file by hand: a workbook is a zip of XML parts. Text goes through the shared string table, and no cell ever holds a formula. */
+var ExcelWriter = class ExcelWriter {
+	#strings = /* @__PURE__ */ new Map();
+	#references = 0;
+	static async write(chart, { image, scale = 2 } = {}) {
+		const table = ExportText.rows(chart, "Excel export");
+		return ExcelWriter.file(table, image ? await chart.toPNG({ scale }) : null, scale);
+	}
+	/** `image` is a PNG drawn at `scale`, placed at the chart's own size on a second sheet. */
+	static async file(table, image, scale) {
+		if (table.rows.length >= MAX_ROWS || table.columns.length > MAX_COLUMNS) throw new ChartExportError(ExportErrorCode.Unsupported, `A worksheet holds ${MAX_ROWS} rows and ${MAX_COLUMNS} columns, and this table has ${table.rows.length} rows and ${table.columns.length} columns. Use CSV.`);
+		return new ExcelWriter().#workbook(table, image && new Uint8Array(await image.arrayBuffer()), scale);
+	}
+	#workbook(table, image, scale) {
+		const sheets = [["Data", this.#sheet(table)], ...image ? [["Chart", ExcelWriter.#pictureSheet()]] : []];
+		const parts = {
+			"[Content_Types].xml": ExcelWriter.#xml(ExcelWriter.#types(sheets.length)),
+			"_rels/.rels": ExcelWriter.#xml(ExcelWriter.#links([`${LINKS}/officeDocument`, "xl/workbook.xml"])),
+			"xl/workbook.xml": ExcelWriter.#xml(ExcelWriter.#book(sheets.map(([name]) => name))),
+			"xl/_rels/workbook.xml.rels": ExcelWriter.#xml(ExcelWriter.#links(...sheets.map((_, i) => [`${LINKS}/worksheet`, `worksheets/sheet${i + 1}.xml`]), [`${LINKS}/styles`, "styles.xml"], [`${LINKS}/sharedStrings`, "sharedStrings.xml"])),
+			"xl/styles.xml": ExcelWriter.#xml(STYLES),
+			"xl/sharedStrings.xml": ExcelWriter.#xml(this.#stringTable())
+		};
+		sheets.forEach(([, xml], i) => {
+			parts[`xl/worksheets/sheet${i + 1}.xml`] = ExcelWriter.#xml(xml);
+		});
+		if (image) {
+			parts["xl/worksheets/_rels/sheet2.xml.rels"] = ExcelWriter.#xml(ExcelWriter.#links([`${LINKS}/drawing`, "../drawings/drawing1.xml"]));
+			parts["xl/drawings/drawing1.xml"] = ExcelWriter.#xml(ExcelWriter.#drawing(image, scale));
+			parts["xl/drawings/_rels/drawing1.xml.rels"] = ExcelWriter.#xml(ExcelWriter.#links([`${LINKS}/image`, "../media/image1.png"]));
+			parts["xl/media/image1.png"] = [image, { level: 0 }];
+		}
+		return new Blob([zipSync(parts)], { type: TYPE });
+	}
+	static #xml(text) {
+		return [strToU8(text), { level: 6 }];
+	}
+	static #types(sheets) {
+		const override = (part, type) => `<Override PartName="/${part}" ContentType="${type}+xml"/>`;
+		const sheetParts = Array.from({ length: sheets }, (_, i) => override(`xl/worksheets/sheet${i + 1}.xml`, `${CONTENT}.spreadsheetml.worksheet`));
+		return `${HEAD}<Types xmlns="${PACKAGE}/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Default Extension="png" ContentType="image/png"/>` + override("xl/workbook.xml", `${CONTENT}.spreadsheetml.sheet.main`) + sheetParts.join("") + override("xl/styles.xml", `${CONTENT}.spreadsheetml.styles`) + override("xl/sharedStrings.xml", `${CONTENT}.spreadsheetml.sharedStrings`) + (sheets > 1 ? override("xl/drawings/drawing1.xml", `${CONTENT}.drawing`) : "") + "</Types>";
+	}
+	static #links(...targets) {
+		return `${HEAD}<Relationships xmlns="${PACKAGE}/relationships">${targets.map(([type, target], i) => `<Relationship Id="rId${i + 1}" Type="${type}" Target="${target}"/>`).join("")}</Relationships>`;
+	}
+	static #book(names) {
+		return `${HEAD}<workbook xmlns="${MAIN}" xmlns:r="${LINKS}"><bookViews><workbookView/></bookViews><sheets>${names.map((name, i) => `<sheet name="${name}" sheetId="${i + 1}" r:id="rId${i + 1}"/>`).join("")}</sheets></workbook>`;
+	}
+	static #pictureSheet() {
+		return `${HEAD}<worksheet xmlns="${MAIN}" xmlns:r="${LINKS}"><sheetData/><drawing r:id="rId1"/></worksheet>`;
+	}
+	/** The element order is fixed by the schema, and Excel calls a file corrupt when it differs. */
+	#sheet({ columns, rows }) {
+		const widths = columns.map((column) => column.length + 1);
+		const lines = [`<row r="1">${columns.map((column, c) => this.#textCell(ExcelWriter.#ref(c, 1), column, Style.Header)).join("")}</row>`];
+		rows.forEach((row, r) => {
+			const number = r + 2;
+			const cells = row.slice(0, MAX_COLUMNS).map((cell, c) => {
+				if (r < MEASURED) widths[c] = Math.max(widths[c] ?? 0, ExportText.of(cell).length);
+				return this.#cell(ExcelWriter.#ref(c, number), cell);
+			});
+			lines.push(`<row r="${number}">${cells.join("")}</row>`);
+		});
+		const pane = "<pane ySplit=\"1\" topLeftCell=\"A2\" activePane=\"bottomLeft\" state=\"frozen\"/><selection pane=\"bottomLeft\" activeCell=\"A2\" sqref=\"A2\"/>";
+		const cols = widths.map((width, c) => `<col min="${c + 1}" max="${c + 1}" width="${Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, width + 2))}" customWidth="1"/>`).join("");
+		return `${HEAD}<worksheet xmlns="${MAIN}"><dimension ref="A1:${ExcelWriter.#ref(Math.max(widths.length, 1) - 1, rows.length + 1)}"/><sheetViews><sheetView tabSelected="1" workbookViewId="0">${pane}</sheetView></sheetViews><sheetFormatPr defaultRowHeight="15"/>${cols && `<cols>${cols}</cols>`}<sheetData>${lines.join("")}</sheetData></worksheet>`;
+	}
+	#cell(ref, cell) {
+		if (typeof cell === "number") return Number.isFinite(cell) ? `<c r="${ref}"><v>${cell}</v></c>` : Number.isNaN(cell) ? "" : this.#textCell(ref, String(cell));
+		if (typeof cell === "boolean") return `<c r="${ref}" t="b"><v>${+cell}</v></c>`;
+		if (cell instanceof Date && !Number.isNaN(+cell)) return ExcelWriter.#dateCell(ref, cell) ?? this.#textCell(ref, ExportText.stamp(cell));
+		const text = ChartExporter.text(cell);
+		return text ? this.#textCell(ref, text) : "";
+	}
+	/** A date outside the range Excel can show has no serial, so it stays text. */
+	static #dateCell(ref, date) {
+		const days = (ExportText.wall(date) - EPOCH) / DAY;
+		const serial = days < LEAP_BUG ? days - 1 : days;
+		if (serial < 1 || serial > MAX_SERIAL) return null;
+		return `<c r="${ref}" s="${Number.isInteger(serial) ? Style.Date : Style.DateTime}"><v>${serial}</v></c>`;
+	}
+	#textCell(ref, text, style) {
+		const shown = style ?? (FORMULA.test(text) ? Style.Guarded : void 0);
+		return `<c r="${ref}"${shown ? ` s="${shown}"` : ""} t="s"><v>${this.#string(text)}</v></c>`;
+	}
+	#string(text) {
+		this.#references++;
+		const known = this.#strings.get(text);
+		if (known !== void 0) return known;
+		const index = this.#strings.size;
+		this.#strings.set(text, index);
+		return index;
+	}
+	#stringTable() {
+		const items = [...this.#strings.keys()].map((text) => `<si><t xml:space="preserve">${ExcelWriter.#escape(text)}</t></si>`);
+		return `${HEAD}<sst xmlns="${MAIN}" count="${this.#references}" uniqueCount="${this.#strings.size}">${items.join("")}</sst>`;
+	}
+	/** Spreadsheets read `_x0041_` in a string as "A", so a literal one has its underscore escaped the same way. */
+	static #escape(text) {
+		return ChartExporter.writable(text.slice(0, MAX_TEXT)).replace(/_(?=x[0-9a-fA-F]{4}_)/g, "_x005F_").replace(/[&<>\r]/g, (char) => ({
+			"&": "&amp;",
+			"<": "&lt;",
+			">": "&gt;",
+			"\r": "&#13;"
+		})[char]);
+	}
+	static #ref(column, row) {
+		let letters = "";
+		for (let left = column + 1; left > 0; left = Math.floor((left - 1) / 26)) letters = String.fromCharCode(65 + (left - 1) % 26) + letters;
+		return `${letters}${row}`;
+	}
+	/** The size comes from the PNG's own header: width and height follow its 16-byte preamble. */
+	static #drawing(image, scale) {
+		const header = new DataView(image.buffer, image.byteOffset);
+		const cx = Math.round(header.getUint32(16) / scale * EMU_PER_PIXEL), cy = Math.round(header.getUint32(20) / scale * EMU_PER_PIXEL);
+		return `${HEAD}<xdr:wsDr xmlns:xdr="http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="${LINKS}"><xdr:oneCellAnchor><xdr:from><xdr:col>0</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>0</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:from><xdr:ext cx="${cx}" cy="${cy}"/><xdr:pic><xdr:nvPicPr><xdr:cNvPr id="2" name="Chart"/><xdr:cNvPicPr><a:picLocks noChangeAspect="1"/></xdr:cNvPicPr></xdr:nvPicPr><xdr:blipFill><a:blip r:embed="rId1"/><a:stretch><a:fillRect/></a:stretch></xdr:blipFill><xdr:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${cx}" cy="${cy}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></xdr:spPr></xdr:pic><xdr:clientData/></xdr:oneCellAnchor></xdr:wsDr>`;
+	}
+};
+export { ExcelWriter };

package/dist/core/ExportText.js

@@ -0,0 +1,28 @@
+import { ChartExporter } from "./ChartExporter.js";
+import { ChartExportError, ExportErrorCode } from "./ChartExportError.js";
+// src/core/ExportText.ts
+/** Cells as people read them. Dates use local time, as chart axes do. */
+var ExportText = class ExportText {
+	/** `table()` with any rows still queued, or an error naming what needed them. A chart holding no data has no rows, whatever its override reads. */
+	static rows(chart, needed) {
+		chart.flush();
+		if (chart.data != null) {
+			const table = chart.table();
+			if (table.rows.length) return table;
+		}
+		throw new ChartExportError(ExportErrorCode.NoData, `${needed} needs rows, and this chart's data has no flat table view.`);
+	}
+	/** The local date and time as milliseconds on a UTC clock. Zone offsets are not whole minutes in old dates, so this reads the fields. */
+	static wall(date) {
+		const wall = /* @__PURE__ */ new Date(0);
+		wall.setUTCFullYear(date.getFullYear(), date.getMonth(), date.getDate());
+		return wall.setUTCHours(date.getHours(), date.getMinutes(), date.getSeconds(), date.getMilliseconds());
+	}
+	static stamp(date) {
+		return new Date(ExportText.wall(date)).toISOString().slice(0, 19).replace("T", " ").replace(/ 00:00:00$/, "");
+	}
+	static of(cell) {
+		return cell instanceof Date && !Number.isNaN(+cell) ? ExportText.stamp(cell) : ChartExporter.text(cell);
+	}
+};
+export { ExportText };

package/dist/core/MarkOrigin.js

@@ -0,0 +1,88 @@
+// src/core/MarkOrigin.ts
+/** Where derived marks keep the record they were drawn from, most direct first. */
+var POINTERS = [
+	"row",
+	"record",
+	"datum",
+	"data",
+	"raw",
+	"source",
+	"node",
+	"link",
+	"feature",
+	"region",
+	"sample"
+];
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Text form of a cell. Charts often turn dates into timestamps. */
+var cell = (value) => String(value instanceof Date ? value.getTime() : value);
+/** A graph layout works on copies, so its nodes and links are known by id and by their two ends. */
+var nameOf = (record) => {
+	const end = (value) => isRecord(value) ? value.id : value;
+	return "source" in record && "target" in record ? `${end(record.source)}>${end(record.target)}` : record.id;
+};
+var held = /* @__PURE__ */ new WeakMap();
+/** Finds the record a mark stands for, so `onSelect` hands back what the user passed in rather than layout state. */
+var MarkOrigin = class {
+	/** The row, node or feature behind `mark`, or `mark` when it has no single source. */
+	static of(mark, { data, ...options }) {
+		if (typeof mark !== "object" || mark === null || typeof data !== "object" || data === null) return mark;
+		const known = this.#held(data), derived = mark;
+		return this.#known(derived, known) ?? this.#pointedAt(derived, known, 2) ?? (Array.isArray(data) ? this.#matched(derived, data, options) : void 0) ?? mark;
+	}
+	static #held(data) {
+		let known = held.get(data);
+		if (!known) {
+			known = {
+				records: /* @__PURE__ */ new Set(),
+				named: /* @__PURE__ */ new Map()
+			};
+			held.set(data, known);
+			this.#collect(data, known.records);
+			if (!Array.isArray(data)) for (const record of known.records) known.named.set(nameOf(record), record);
+			known.named.delete(void 0);
+		}
+		return known;
+	}
+	static #known(candidate, { records, named }) {
+		return records.has(candidate) ? candidate : named.get(nameOf(candidate));
+	}
+	/** Rows, tree nodes, graph nodes and links, and map features. Arrays of numbers or coordinates hold no records. */
+	static #collect(value, into) {
+		if (Array.isArray(value)) {
+			if (isRecord(value.find((item) => item !== null && item !== void 0))) for (const item of value) this.#collect(item, into);
+		} else if (isRecord(value) && !into.has(value)) {
+			into.add(value);
+			for (const child of Object.values(value)) if (Array.isArray(child)) this.#collect(child, into);
+		}
+	}
+	static #pointedAt(mark, known, depth) {
+		const links = POINTERS.filter((key) => key !== "source" || !("target" in mark)).map((key) => mark[key]).filter(isRecord);
+		for (const link of links) {
+			const found = this.#known(link, known);
+			if (found) return found;
+		}
+		if (depth === 1) return void 0;
+		for (const link of links) {
+			const deeper = this.#pointedAt(link, known, depth - 1);
+			if (deeper) return deeper;
+		}
+	}
+	/**
+	* For marks built by pivoting rows: the one row whose named columns all appear on the mark. Summed
+	* rows fail on the value, so a second pass ignores numbers. More than one match means a real aggregate.
+	*/
+	static #matched(mark, rows, options) {
+		const table = rows.filter(isRecord);
+		const first = table[0];
+		if (!first) return void 0;
+		const columns = Object.values(options).flat().filter((name) => typeof name === "string" && name in first);
+		const shown = new Set(Object.values(mark).flatMap((value) => isRecord(value) ? Object.values(value) : [value]).map(cell));
+		const unique = (names) => {
+			const hits = names.length ? table.filter((row) => names.every((name) => shown.has(cell(row[name])))) : [];
+			return hits.length === 1 ? hits[0] : void 0;
+		};
+		return unique(columns) ?? unique(columns.filter((name) => typeof first[name] !== "number"));
+	}
+};
+export { MarkOrigin };

package/dist/core/MarkStyle.js

@@ -0,0 +1,294 @@
+import { FRAMING } from "./Context2D.js";
+import { EdgeRendering, StrokeDash } from "./enums.js";
+import { color } from "d3";
+// src/core/MarkStyle.ts
+var SHAPES = "path,line,polyline,polygon,rect,circle,ellipse";
+var UNDRAWN = "defs,clipPath,mask,pattern,marker,symbol,.tick,.domain";
+/** Mark-less groups that the shared layer and chart modules name, past what `FRAME` and `FRAMING` list. */
+var FRAMED = /(^|-)(axis|grid|clip|brush(es)?|zoom|annotations?|crosshair|hair)(-|$)/;
+/** Path groups that fill their layout, however small each shape is: cells, tiles, and the keys read against them. */
+var TILED = /^(cells(-\d+)?|tiles|nonzeros|before|after|size-key)$/;
+var MEASURED = [
+	"strokeWidth",
+	"strokeDash",
+	"strokeCap",
+	"strokeJoin",
+	"opacity",
+	"markSize",
+	"edges",
+	"fontSize"
+];
+/** Past this radius a circle is layout, such as a packed node or a dial, not a marker. */
+var MARKER_RADIUS = 24;
+/** The longest `d` a d3 symbol writes. */
+var SYMBOL_PATH = 300;
+var SYMBOL_REACH = 30;
+var SCALE = /scale\(\s*([-\d.e]+)\s*\)/;
+var NUMBER = /-?\d*\.?\d+(?:e-?\d+)?/gi;
+var DASHES = {
+	[StrokeDash.Dashed]: [6, 4],
+	[StrokeDash.Dotted]: [2, 3]
+};
+var EDGES = {
+	[EdgeRendering.Crisp]: "crispEdges",
+	[EdgeRendering.Precise]: "geometricPrecision"
+};
+var round = (value) => String(+value.toFixed(4));
+var positive = (value) => value !== void 0 && value > 0 && Number.isFinite(value) ? value : void 0;
+var write = (el, name, value) => {
+	if (value === null) el.removeAttribute(name);
+	else el.setAttribute(name, value);
+};
+var inFlight = (el) => !!el.__transition;
+var groupNames = (group) => [...group.classList].filter((name) => name.startsWith("m-")).map((name) => name.slice(2));
+/** `base` times `by`, reading `fallback` when the element has no value of its own. A value that is no number stays. */
+var times = (by, fallback) => (base) => {
+	const value = parseFloat(base ?? fallback ?? "");
+	return Number.isFinite(value) ? round(value * by) : base;
+};
+/** True for a path drawn around the origin and small enough to be a glyph, which is how d3 symbols come. */
+var glyph = (d) => {
+	if (!d || d.length > SYMBOL_PATH) return false;
+	const numbers = (d.match(NUMBER) ?? []).map(Number);
+	return numbers.length > 0 && Math.max(...numbers) <= SYMBOL_REACH && Math.min(...numbers) >= -30 && numbers.some((value) => value < 0) && numbers.some((value) => value > 0);
+};
+/** Adds to a glyph's own `scale()`, which entry animations use, or starts one after its `translate()`. */
+var scaled = (by) => (base) => {
+	if (base === null) return `scale(${by})`;
+	return SCALE.test(base) ? base.replace(SCALE, (_, own) => `scale(${round(parseFloat(own) * by)})`) : `${base} scale(${by})`;
+};
+/**
+* The `chartStyle` options that attributes carry. Attributes go back to what the chart drew before each
+* paint, so a chart always draws from clean values, and take the style again after it. A transition
+* owns the attributes it moves: `ends` gives it styled targets, and they count as held until it lands.
+*/
+var MarkStyle = class {
+	#held = /* @__PURE__ */ new Map();
+	/** What running transitions are heading for, since a mark is classed by how it will end up. */
+	#planned = /* @__PURE__ */ new Map();
+	#framed = /* @__PURE__ */ new WeakMap();
+	/** Whether a group's shapes of one tag can size, which holds for all of them or none. */
+	#sizing = /* @__PURE__ */ new Map();
+	#style = {};
+	#theme = null;
+	#key = "";
+	#bare = /* @__PURE__ */ new Set();
+	/** True when `style` has anything this pass does. Colour and the 3D options do not need it. */
+	static wanted(style) {
+		return !!style && MEASURED.some((key) => style[key] !== void 0);
+	}
+	/** Sets what the next paint draws and puts back what the last one styled. A new style also takes back what is moving. */
+	begin(style, theme) {
+		const key = JSON.stringify([
+			style,
+			theme.surface,
+			theme.grid,
+			theme.axis
+		]);
+		this.end(key !== this.#key);
+		this.#sizing.clear();
+		this.#key = key;
+		this.#style = style;
+		this.#theme = theme;
+		this.#bare = new Set([
+			theme.surface,
+			theme.grid,
+			theme.axis
+		].map(hex));
+	}
+	/** Puts back every styled attribute, leaving those a transition is still moving unless `all`. */
+	end(all = true) {
+		for (const [el, held] of this.#held) {
+			for (const [name, { value, moving }] of held) {
+				if (moving && !all && inFlight(el)) continue;
+				write(el, name, value);
+				held.delete(name);
+			}
+			if (!held.size) this.#held.delete(el);
+		}
+		for (const el of this.#planned.keys()) if (all || !inFlight(el)) this.#planned.delete(el);
+	}
+	/** Styles the finished drawing. Marks only under `g-plot`; text anywhere in the chart. */
+	apply(svg) {
+		const plot = svg.querySelector("g.g-plot");
+		if (plot) {
+			for (const el of plot.querySelectorAll(SHAPES)) if (this.#isMark(el)) this.#restyle(el);
+		}
+		if (positive(this.#style.fontSize)) for (const el of svg.querySelectorAll("text")) this.#restyle(el);
+	}
+	/** The values a transition should land on, for the attributes this style changes. Call before the transition exists. */
+	ends(selection, attrs) {
+		const names = Object.keys(attrs), landing = /* @__PURE__ */ new Map(), targets = /* @__PURE__ */ new Map(), claimed = /* @__PURE__ */ new Set();
+		const land = (el, datum, index) => {
+			const raw = {};
+			for (const name of names) {
+				const value = attrs[name];
+				const end = typeof value === "function" ? value.call(el, datum, index) : value;
+				raw[name] = end === null ? null : String(end);
+			}
+			landing.set(el, raw);
+			this.#planned.set(el, {
+				...this.#planned.get(el),
+				...raw
+			});
+		};
+		selection.each(function(datum, index) {
+			land(this, datum, index);
+		});
+		this.#sizing.clear();
+		for (const [el, raw] of landing) {
+			const styled = this.#claim(el, raw);
+			for (const name in styled) claimed.add(name);
+			targets.set(el, {
+				...raw,
+				...styled
+			});
+		}
+		const ends = {};
+		for (const name of claimed) ends[name] = function() {
+			return targets.get(this)[name];
+		};
+		return ends;
+	}
+	/** `names` were just written without a transition, so whatever was moving them no longer speaks for them. */
+	placed(selection, names) {
+		selection.each((_, index, nodes) => {
+			const el = nodes[index], held = this.#held.get(el), planned = this.#planned.get(el);
+			for (const name of names) {
+				if (held?.get(name)?.moving) held.delete(name);
+				if (planned) delete planned[name];
+			}
+		});
+	}
+	#claim(el, raw) {
+		const target = {};
+		if (el.tagName !== "text" && !(el.matches(SHAPES) && this.#isMark(el))) return target;
+		const rules = this.#rules(el);
+		let held = this.#held.get(el);
+		for (const name of Object.keys(raw)) {
+			const rule = rules[name];
+			if (!rule) continue;
+			held ??= /* @__PURE__ */ new Map();
+			this.#held.set(el, held);
+			if (!held.get(name)?.moving) write(el, name, rule(el.getAttribute(name)));
+			held.set(name, {
+				value: raw[name],
+				moving: true
+			});
+			target[name] = rule(raw[name]);
+		}
+		return target;
+	}
+	#restyle(el) {
+		for (const [name, rule] of Object.entries(this.#rules(el))) {
+			const held = this.#held.get(el);
+			if (held?.has(name)) continue;
+			const base = el.getAttribute(name), next = rule(base);
+			if (next === base) continue;
+			if (!held) this.#held.set(el, /* @__PURE__ */ new Map([[name, {
+				value: base,
+				moving: false
+			}]]));
+			else held.set(name, {
+				value: base,
+				moving: false
+			});
+			write(el, name, next);
+		}
+	}
+	#rules(el) {
+		if (el.tagName === "text") {
+			const by = positive(this.#style.fontSize);
+			return by ? { "font-size": times(by, this.#inherited(el, "font-size") ?? "16") } : {};
+		}
+		const { strokeDash, strokeCap, strokeJoin, edges } = this.#style;
+		const strokeWidth = positive(this.#style.strokeWidth), markSize = positive(this.#style.markSize);
+		const opacity = this.#style.opacity === void 0 || Number.isNaN(this.#style.opacity) ? void 0 : Math.max(0, Math.min(1, this.#style.opacity));
+		const paint = this.#inherited(el, "stroke") ?? "none";
+		const stroke = this.#ink(paint), fill = el.tagName === "line" ? 0 : this.#ink(this.#inherited(el, "fill") ?? "#000");
+		const rules = {};
+		if (stroke === 0 && fill === 0) return rules;
+		if (stroke === 2) {
+			if (strokeWidth) rules["stroke-width"] = times(strokeWidth, this.#inherited(el, "stroke-width") ?? "1");
+			const dash = strokeDash && DASHES[strokeDash];
+			if (dash && !this.#painted(this.#inherited(el, "stroke-dasharray"))) {
+				const pattern = dash.map((step) => round(step * (strokeWidth ?? 1))).join(" ");
+				rules["stroke-dasharray"] = () => pattern;
+			}
+			if (strokeCap) rules["stroke-linecap"] = () => strokeCap;
+			if (strokeJoin) rules["stroke-linejoin"] = () => strokeJoin;
+			if (opacity !== void 0) rules["stroke-opacity"] = times(opacity, this.#inherited(el, "stroke-opacity") ?? "1");
+		}
+		if (fill === 2 && opacity !== void 0) rules["fill-opacity"] = times(opacity, this.#inherited(el, "fill-opacity") ?? "1");
+		const guide = fill === 0 && hex(paint) === hex(this.#theme.grid);
+		if (markSize && !guide) this.#size(el, markSize, stroke, rules);
+		const rendering = edges && EDGES[edges];
+		if (rendering && (stroke === 2 || fill === 2)) rules["shape-rendering"] = () => rendering;
+		return rules;
+	}
+	#size(el, by, stroke, rules) {
+		if (el.tagName === "circle") {
+			if (this.#sizes(el)) rules.r = times(by, null);
+		} else if (el.tagName === "path") {
+			if (!(this.#planned.get(el) && "d" in this.#planned.get(el))) this.#whenLanded(el);
+			if (!this.#sizes(el)) return;
+			const transform = this.#read(el, "transform");
+			if (transform !== null && !transform.startsWith("translate(")) return;
+			rules.transform = scaled(by);
+			if (stroke !== 0) rules["vector-effect"] = () => "non-scaling-stroke";
+		}
+	}
+	/** One shape past the limit makes its whole group layout: sizing only the small ones would stop size reading as value. */
+	#sizes(el) {
+		const group = el.parentElement;
+		if (!group) return false;
+		let tags = this.#sizing.get(group);
+		if (!tags) this.#sizing.set(group, tags = /* @__PURE__ */ new Map());
+		let sizes = tags.get(el.tagName);
+		if (sizes === void 0) {
+			const peers = [...group.children].filter((peer) => peer.tagName === el.tagName);
+			sizes = el.tagName === "circle" ? peers.every((peer) => !(parseFloat(this.#read(peer, "r") ?? "") > MARKER_RADIUS)) : !groupNames(group).some((name) => TILED.test(name)) && peers.every((peer) => glyph(this.#read(peer, "d")));
+			tags.set(el.tagName, sizes);
+		}
+		return sizes;
+	}
+	/** A chart's own transition keeps its end to itself, so the shape it lands on is only known then. */
+	#whenLanded(el) {
+		for (const schedule of Object.values(el.__transition ?? {})) schedule.on = schedule.on.copy().on("end.mark-style", () => {
+			this.#sizing.delete(el.parentElement);
+			this.#restyle(el);
+		});
+	}
+	#read(el, name) {
+		const planned = this.#planned.get(el);
+		if (planned && name in planned) return planned[name];
+		return this.#held.get(el)?.get(name)?.value ?? el.getAttribute(name);
+	}
+	#inherited(el, name) {
+		return this.#read(el, name) ?? el.parentElement?.closest(`[${name}]`)?.getAttribute(name) ?? null;
+	}
+	#painted(dash) {
+		return !!dash && dash !== "none" && dash !== "0";
+	}
+	#ink(paint) {
+		if (paint === "none" || paint === "transparent") return 0;
+		return this.#bare.has(hex(paint)) ? 1 : 2;
+	}
+	#isMark(el) {
+		return !el.closest(UNDRAWN) && !this.#inFrame(el.parentElement);
+	}
+	#inFrame(group) {
+		if (!group || group.classList.contains("g-plot")) return false;
+		let framed = this.#framed.get(group);
+		if (framed === void 0) {
+			const names = groupNames(group);
+			framed = group.matches(".m-axis-x,.m-axis-y,.m-axis-title,.m-grid,.m-zoom-hit,.m-view-clip,.m-domain-clip,.m-brush,.m-zoom-controls") || names.some((name) => FRAMING.test(name) || FRAMED.test(name)) || this.#inFrame(group.parentElement);
+			this.#framed.set(group, framed);
+		}
+		return framed;
+	}
+};
+function hex(paint) {
+	return color(paint)?.formatHex() ?? paint;
+}
+export { MarkStyle };

package/dist/core/Palette.js

@@ -1,28 +1,37 @@
 import { color, interpolateRgb, interpolateRgbBasis } from "d3";
 // src/core/Palette.ts
-/** Assigns colours by job. Categorical colour follows the entity in first-seen order, folding past 8 into "Other". */
+/** Assigns colours by job. Categorical colour follows the entity in first-seen order and never cycles: series past the validated list share `inkMuted`, and the legend folds them into "Other". */
 var Palette = class {
 	tokens;
 	seats;
+	pins;
+	opacity;
 	keys = /* @__PURE__ */ new Map();
 	ramp;
-	/** `seats` holds each key's place across palettes, for a stream whose series come and go. */
-	constructor(tokens, seats) {
+	ranked = 0;
+	/**
+	* `seats` holds each key's place across palettes, for a stream whose series come and go. `pins`
+	* gives series their own colour: a pinned series takes no place in the order, so the others keep theirs.
+	* `opacity` is `chartStyle.opacity`: `inkOn` picks ink for the colour a mark ends up on the surface.
+	*/
+	constructor(tokens, seats, pins = {}, opacity = 1) {
 		this.tokens = tokens;
 		this.seats = seats;
+		this.pins = pins;
+		this.opacity = opacity;
 		this.ramp = interpolateRgbBasis([...tokens.sequential]);
 	}
 	color = (key) => {
 		let hit = this.keys.get(key);
 		if (!hit) {
-			hit = this.tokens.categorical[this.seat(key)] ?? this.tokens.inkMuted;
+			hit = Object.hasOwn(this.pins, key) ? this.pins[key] : this.tokens.categorical[this.seat(key)] ?? this.tokens.inkMuted;
 			this.keys.set(key, hit);
 		}
 		return hit;
 	};
 	seat(key) {
 		const { seats, tokens: { categorical: { length } } } = this;
-		if (!seats) return this.keys.size;
+		if (!seats) return this.ranked++;
 		if (!seats.has(key) && seats.size < length) seats.set(key, seats.size);
 		return seats.get(key) ?? length;
 	}
@@ -37,13 +46,24 @@ var Palette = class {
 	inkOn = (fill) => {
 		const rgb = color(fill)?.rgb();
 		if (!rgb) return "#ffffff";
-		return .299 * rgb.r + .587 * rgb.g + .114 * rgb.b > 150 ? "#0b0b0b" : "#ffffff";
+		const share = Number.isNaN(this.opacity) ? 1 : Math.max(0, Math.min(1, this.opacity)), surface = color(this.tokens.surface)?.rgb() ?? rgb;
+		const seen = (channel) => rgb[channel] * share + surface[channel] * (1 - share);
+		return .299 * seen("r") + .587 * seen("g") + .114 * seen("b") > 150 ? "#0b0b0b" : "#ffffff";
 	};
+	/** Series that look the same get one entry, naming them in `title`. A lone muted series is still told apart, so it keeps its name. */
 	items() {
-		return [...this.keys].map(([key, color]) => ({
+		const items = [...this.keys].map(([key, color]) => ({
 			key,
 			color
 		}));
+		const folded = (item) => item.color === this.tokens.inkMuted && !Object.hasOwn(this.pins, item.key);
+		const muted = items.filter(folded);
+		if (muted.length < 2) return items;
+		return [...items.filter((item) => !folded(item)), {
+			key: `Other (${muted.length})`,
+			color: this.tokens.inkMuted,
+			title: muted.map((item) => item.key).join(", ")
+		}];
 	}
 };
 export { Palette };

package/dist/core/PdfPage.js

@@ -0,0 +1,13 @@
+// src/core/PdfPage.ts
+var PdfPageSize = /* @__PURE__ */ function(PdfPageSize) {
+	PdfPageSize["A4"] = "a4";
+	PdfPageSize["Letter"] = "letter";
+	return PdfPageSize;
+}({});
+var PdfOrientation = /* @__PURE__ */ function(PdfOrientation) {
+	PdfOrientation["Auto"] = "auto";
+	PdfOrientation["Portrait"] = "portrait";
+	PdfOrientation["Landscape"] = "landscape";
+	return PdfOrientation;
+}({});
+export { PdfOrientation, PdfPageSize };