@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/chunk-Z3JPIJSC.cjs

@@ -0,0 +1,338 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/core/ChartExportError.ts
+var ExportErrorCode = /* @__PURE__ */ ((ExportErrorCode2) => {
+  ExportErrorCode2["Unsupported"] = "unsupported";
+  ExportErrorCode2["NoData"] = "no-data";
+  ExportErrorCode2["Tainted"] = "tainted";
+  ExportErrorCode2["Encoding"] = "encoding";
+  ExportErrorCode2["Unavailable"] = "unavailable";
+  ExportErrorCode2["Unmounted"] = "unmounted";
+  return ExportErrorCode2;
+})(ExportErrorCode || {});
+var ChartExportError = class extends Error {
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+    this.name = "ChartExportError";
+  }
+  
+};
+
+// src/core/ChartExporter.ts
+var ExportFormat = /* @__PURE__ */ ((ExportFormat2) => {
+  ExportFormat2["SVG"] = "svg";
+  ExportFormat2["PNG"] = "png";
+  ExportFormat2["CSV"] = "csv";
+  ExportFormat2["PDF"] = "pdf";
+  ExportFormat2["Excel"] = "xlsx";
+  return ExportFormat2;
+})(ExportFormat || {});
+var SVG_NS = "http://www.w3.org/2000/svg";
+var MIME = { ["svg" /* SVG */]: "image/svg+xml;charset=utf-8", ["png" /* PNG */]: "image/png", ["csv" /* CSV */]: "text/csv;charset=utf-8" };
+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"
+];
+var LIVE_ONLY = [
+  "cursor",
+  "pointer-events",
+  "touch-action",
+  "transition",
+  "stroke-dasharray",
+  "stroke-dashoffset",
+  "opacity",
+  "scale",
+  "transform-origin",
+  "transform-box",
+  "--geo-unzoom"
+];
+var LIVE_ROOT = ["display", "max-width", "background", "position", "z-index"];
+var CHROME = '[role="button"], .m-zoom-hit, .g-keyboard';
+var TIMEOUT = 2e4;
+var HELD_STROKE = "non-scaling-stroke";
+var UNWRITABLE = /[^\t\n\r\x20-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/gu;
+var FORMULA = /^[=+\-@\t\r]/;
+var SHEET_ROWS = 1048576;
+var quoteless = (name) => name.trim().replace(/^['"]|['"]$/g, "").toLowerCase();
+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("no-data" /* 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");
+  }
+  /** The formats built from rows. A worksheet has a fixed height, and one row of it is the header. */
+  static tabular(rows) {
+    return rows ? ["csv" /* CSV */, ...rows < SHEET_ROWS ? ["xlsx" /* Excel */] : []] : [];
+  }
+  /** Awaits a writer's dynamic import, so a chunk that fails to load rejects like any other export. */
+  static async load(format, load) {
+    try {
+      return await load();
+    } catch (cause) {
+      throw new ChartExportError("unavailable" /* Unavailable */, `The ${format} writer could not be loaded: ${cause.message}`, { cause });
+    }
+  }
+  static #cell(cell) {
+    const text = _ChartExporter.text(cell);
+    const guarded = typeof cell === "string" && FORMULA.test(text) && !Number.isFinite(+text) ? `'${text}` : text;
+    return /[",\r\n]/.test(guarded) ? `"${guarded.replaceAll('"', '""')}"` : guarded;
+  }
+  /** A cell as plain 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);
+    return typeof cell === "object" ? _ChartExporter.#json(cell) : String(cell);
+  }
+  /** Layouts leave cycles in the objects they are handed, which JSON cannot write. */
+  static #json(cell) {
+    try {
+      return JSON.stringify(cell);
+    } catch (e) {
+      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, _nullishCoalesce(_optionalChain([copy, 'access', _ => _.querySelector, 'call', _2 => _2(":scope > title"), 'optionalAccess', _3 => _3.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 _nullishCoalesce(_optionalChain([svg, 'access', _4 => _4.getAnimations, 'optionalCall', _5 => _5({ subtree: true })]), () => ( []))) {
+      if (_optionalChain([motion, 'access', _6 => _6.effect, 'optionalAccess', _7 => _7.getComputedTiming, 'call', _8 => _8(), 'access', _9 => _9.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" : _optionalChain([parent, 'optionalAccess', _10 => _10[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" ? _optionalChain([el, 'access', _11 => _11.getBBox, 'optionalCall', _12 => _12()]) : 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, _nullishCoalesce(_optionalChain([svg, 'access', _13 => _13.querySelector, 'call', _14 => _14(":scope > title"), 'optionalAccess', _15 => _15.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(
+        "tainted" /* 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(_nullishCoalesce(reader.error, () => ( 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 (e2) {
+        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, _nullishCoalesce(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 _ChartExporter.writable(new XMLSerializer().serializeToString(svg));
+  }
+  /** `text` without the characters XML cannot hold. */
+  static writable(text) {
+    return text.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(_ChartExporter.#atScale(svg, { width, height }, scale), "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);
+    }
+  }
+  /**
+   * A held stroke is sized in screen pixels, and engines disagree on what those are in an image drawn larger:
+   * Chromium keeps it thin, WebKit scales it. In an image already at full size they agree, so that is what they get.
+   */
+  static #atScale(svg, { width, height }, scale) {
+    if (scale === 1 || !svg.includes(HELD_STROKE)) return svg;
+    const root = new DOMParser().parseFromString(svg, "image/svg+xml").documentElement;
+    for (const [name, value] of Object.entries({ viewBox: `0 0 ${width} ${height}`, width: width * scale, height: height * scale })) root.setAttribute(name, `${value}`);
+    for (const el of root.querySelectorAll(`[vector-effect="${HELD_STROKE}"]`)) {
+      el.style.setProperty("stroke-width", `${parseFloat(_nullishCoalesce(_optionalChain([el, 'access', _16 => _16.closest, 'call', _17 => _17("[stroke-width]"), 'optionalAccess', _18 => _18.getAttribute, 'call', _19 => _19("stroke-width")]), () => ( "1"))) * scale}px`);
+      const dash = el.getAttribute("stroke-dasharray");
+      if (dash && dash !== "none") el.setAttribute("stroke-dasharray", dash.split(/[\s,]+/).map((length) => parseFloat(length) * scale).join(" "));
+    }
+    return _ChartExporter.serialize(root);
+  }
+  static #load(url) {
+    return new Promise((resolve, reject) => {
+      const image = new Image();
+      image.onload = () => resolve(image);
+      image.onerror = () => reject(new ChartExportError("encoding" /* 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("encoding" /* Encoding */, `The browser could not create a ${canvas.width}\xD7${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("encoding" /* Encoding */, `The browser could not encode a ${canvas.width}\xD7${canvas.height} PNG. Try a smaller scale.`);
+      try {
+        canvas.toBlob((blob) => blob ? resolve(blob) : reject(tooLarge()), MIME["png" /* PNG */]);
+      } catch (cause) {
+        reject(cause.name === "SecurityError" ? new ChartExportError("tainted" /* 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" /* CSV */ ? "\uFEFF" : "", 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]") || !!_optionalChain([svg, 'access', _20 => _20.getAnimations, 'optionalCall', _21 => _21({ subtree: true }), 'access', _22 => _22.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);
+  }
+};
+
+
+
+
+
+
+exports.ExportErrorCode = ExportErrorCode; exports.ChartExportError = ChartExportError; exports.ExportFormat = ExportFormat; exports.ChartExporter = ChartExporter;

package/dist/core/AnnotationLayer.js

@@ -0,0 +1,236 @@
+import { AnnotationPlacer } from "./AnnotationPlacer.js";
+import { AnnotationScale } from "./AnnotationScale.js";
+import { select } from "d3";
+// src/core/AnnotationLayer.ts
+/** Which axis a reference value belongs to: `Y` gives a horizontal line, `X` a vertical one. */
+var AnnotationAxis = /* @__PURE__ */ function(AnnotationAxis) {
+	AnnotationAxis["X"] = "x";
+	AnnotationAxis["Y"] = "y";
+	return AnnotationAxis;
+}({});
+var LINE_HEIGHT = 14;
+var ASCENT = 11;
+var PAD = 4;
+var GAP_ABOVE = 3;
+var MARKER = 4;
+var CLEARANCE = 6;
+var CHAR = 6.2;
+var ABOVE = ":scope > g.m-brush, :scope > g.m-zoom-controls";
+var REACHES = [
+	22,
+	38,
+	56
+];
+var SIDES = [
+	[1, -1],
+	[-1, -1],
+	[1, 1],
+	[-1, 1],
+	[0, -1],
+	[0, 1],
+	[1, 0],
+	[-1, 0]
+];
+var ALONG_END = [
+	1,
+	0,
+	.75,
+	.25,
+	.5
+];
+var ALONG_TOP = [
+	0,
+	1,
+	.25,
+	.75,
+	.5
+];
+var clamp = (value, low, high) => Math.max(low, Math.min(high, value));
+var along = (start, room, size, stops) => stops.map((stop) => start + PAD + stop * (room - size - 8));
+var blank = (text) => !String(text ?? "").trim();
+function measure(node) {
+	const width = node.getComputedTextLength?.() ?? 0;
+	return width > 0 ? width : (node.textContent ?? "").length * CHAR;
+}
+/** Shortens the text to `room` and returns the width it ends up with. */
+function fit(node, room) {
+	const width = measure(node);
+	if (width <= room) return width;
+	const chars = [...node.textContent ?? ""];
+	let keep = Math.floor(chars.length * room / width);
+	do
+		node.textContent = `${chars.slice(0, Math.max(0, --keep)).join("").trimEnd()}…`;
+	while (keep > 0 && measure(node) > room);
+	return measure(node);
+}
+/**
+* Reference lines, shaded bands and point notes for every cartesian chart. Everything goes through
+* the axes of the current draw, so it follows whatever those scales do, including zoom. Values off
+* the domain are skipped, and a label with no free spot in the plot is dropped.
+*/
+var AnnotationLayer = class AnnotationLayer {
+	#ctx;
+	#x;
+	#y;
+	#plot;
+	#kept;
+	constructor(ctx, axes, kept) {
+		this.#ctx = ctx;
+		this.#kept = kept;
+		this.#x = new AnnotationScale(axes.x);
+		this.#y = new AnnotationScale(axes.y);
+		const [left, right] = this.#x.extent(ctx.plot.width), [top, bottom] = this.#y.extent(ctx.plot.height);
+		this.#plot = {
+			x: left,
+			y: top,
+			width: right - left,
+			height: bottom - top
+		};
+	}
+	/** Draws into `ctx`, or clears earlier drawings when no option is set. Labels stay off `kept`. Safe to call on every paint. */
+	static draw(ctx, axes, { referenceLines, referenceBands, annotations }, kept = null) {
+		if (!referenceLines?.length && !referenceBands?.length && !annotations?.length) {
+			ctx.root.selectAll(":scope > g.m-annotations, :scope > g.m-annotation-bands").remove();
+			return;
+		}
+		new AnnotationLayer(ctx, axes, kept).#render(referenceLines ?? [], referenceBands ?? [], annotations ?? []);
+	}
+	#render(lines, bands, notes) {
+		const ctx = this.#ctx, { theme } = ctx, layer = ctx.group("annotations").attr("pointer-events", "none");
+		const root = ctx.root.node();
+		root.insertBefore(layer.node(), root.querySelector(ABOVE));
+		const rules = lines.flatMap((line, index) => this.#rule(line, index));
+		const shades = bands.flatMap((band, index) => this.#shade(band, index));
+		const spots = notes.flatMap((note, index) => this.#spot(note, index));
+		ctx.marks("annotation-bands", "rect", shades.map((shade) => shade.box), (_, index) => index).attr("fill", theme.inkMuted).attr("fill-opacity", .14).attr("pointer-events", "none").attr("x", (d) => d.x).attr("y", (d) => d.y).attr("width", (d) => d.width).attr("height", (d) => d.height);
+		ctx.group("annotation-bands").lower();
+		ctx.marks("annotation-lines", "line", rules.map((rule) => rule.path), (_, index) => index, layer).attr("stroke", theme.inkSecondary).attr("stroke-width", 1.5).attr("stroke-dasharray", "4 3").attr("x1", (d) => d.x1).attr("y1", (d) => d.y1).attr("x2", (d) => d.x2).attr("y2", (d) => d.y2);
+		const labels = [
+			...spots.map((spot) => spot.label),
+			...rules.flatMap((rule) => rule.label ?? []),
+			...shades.flatMap((shade) => shade.label ?? [])
+		];
+		const placed = this.#place(layer, labels, spots.map((spot) => spot.label.anchor));
+		const shown = spots.filter((spot) => placed.has(spot.label.key));
+		ctx.marks("annotation-connectors", "line", shown, (d) => d.label.key, layer).attr("stroke", theme.inkMuted).attr("stroke-width", 1).each(function({ label }) {
+			const { x, y } = label.anchor, end = AnnotationPlacer.nearest(label.anchor, placed.get(label.key));
+			select(this).attr("x1", x).attr("y1", y).attr("x2", end.x).attr("y2", end.y);
+		});
+		ctx.marks("annotation-dots", "circle", shown, (d) => d.label.key, layer).attr("fill", theme.ink).attr("stroke", theme.surface).attr("stroke-width", 2).attr("cx", (d) => d.label.anchor.x).attr("cy", (d) => d.label.anchor.y).attr("r", MARKER);
+		layer.select("g.m-annotation-text").raise();
+	}
+	#place(layer, labels, anchors) {
+		const { theme } = this.#ctx, plot = this.#plot, placer = new AnnotationPlacer(plot), placed = /* @__PURE__ */ new Map();
+		if (this.#kept) placer.reserve(this.#kept);
+		for (const { x, y } of anchors) placer.reserve({
+			x: x - CLEARANCE,
+			y: y - CLEARANCE,
+			width: 12,
+			height: 12
+		});
+		const texts = this.#ctx.marks("annotation-text", "text", labels, (d) => d.key, layer).text((d) => d.text);
+		this.#ctx.text(texts, 11, "ink").attr("stroke", theme.surface).attr("stroke-width", 3).attr("paint-order", "stroke").attr("stroke-linejoin", "round");
+		texts.each(function(label) {
+			const node = this;
+			const box = placer.place(label.spots(fit(node, Math.min(label.room ?? Infinity, plot.width - 8))), label.anchor);
+			if (!box) {
+				node.remove();
+				return;
+			}
+			placed.set(label.key, box);
+			node.setAttribute("x", String(box.x));
+			node.setAttribute("y", String(box.y + ASCENT));
+		});
+		return placed;
+	}
+	#inside(pixel, vertical) {
+		const { x, y, width, height } = this.#plot;
+		const [low, size] = vertical ? [x, width] : [y, height];
+		return pixel >= low - .5 && pixel <= low + size + .5;
+	}
+	#rule({ axis = "y", value, label }, index) {
+		const { x, y, width, height } = this.#plot, vertical = axis === "x";
+		const at = (vertical ? this.#x : this.#y).at(value);
+		if (at === null || !this.#inside(at, vertical)) return [];
+		const path = vertical ? {
+			x1: at,
+			x2: at,
+			y1: y,
+			y2: y + height
+		} : {
+			x1: x,
+			x2: x + width,
+			y1: at,
+			y2: at
+		};
+		const spots = (w) => vertical ? along(y, height, LINE_HEIGHT, ALONG_TOP).flatMap((top) => [at + PAD, at - w - PAD].map((left) => this.#box(left, top, w))) : along(x, width, w, ALONG_END).flatMap((left) => [at - LINE_HEIGHT - GAP_ABOVE, at + GAP_ABOVE].map((top) => this.#box(left, top, w)));
+		const room = vertical ? Math.max(at - x, x + width - at) - PAD : void 0;
+		return [{
+			path,
+			label: blank(label) ? void 0 : {
+				key: `line-${index}`,
+				text: label,
+				spots,
+				room
+			}
+		}];
+	}
+	#shade({ axis = "y", from, to, label }, index) {
+		const { x, y, width, height } = this.#plot, vertical = axis === "x";
+		const span = (vertical ? this.#x : this.#y).span(from, to);
+		if (!span) return [];
+		const [low, size] = vertical ? [x, width] : [y, height];
+		const start = Math.max(span[0], low), end = Math.min(span[1], low + size);
+		if (end <= start) return [];
+		const box = vertical ? {
+			x: start,
+			y,
+			width: end - start,
+			height
+		} : {
+			x,
+			y: start,
+			width,
+			height: end - start
+		};
+		const inward = (length) => end - start >= length + 8 ? [start + PAD, end - length - PAD] : [clamp((start + end - length) / 2, low, low + size - length)];
+		const spots = (w) => vertical ? along(y, height, LINE_HEIGHT, ALONG_TOP).flatMap((top) => inward(w).map((left) => this.#box(left, top, w))) : along(x, width, w, ALONG_END).flatMap((left) => inward(LINE_HEIGHT).map((top) => this.#box(left, top, w)));
+		return [{
+			box,
+			label: blank(label) ? void 0 : {
+				key: `band-${index}`,
+				text: label,
+				spots
+			}
+		}];
+	}
+	#spot({ x, y, text }, index) {
+		const px = this.#x.at(x), py = this.#y.at(y);
+		if (blank(text) || px === null || py === null || !this.#inside(px, true) || !this.#inside(py, false)) return [];
+		const { x: left, width } = this.#plot;
+		const spots = (w) => REACHES.flatMap((reach) => SIDES.map(([dx, dy]) => {
+			const across = dy ? reach * .6 : reach;
+			const start = dx > 0 ? px + across : dx < 0 ? px - across - w : px - w / 2;
+			const top = dy < 0 ? py - reach - LINE_HEIGHT : dy > 0 ? py + reach : py - LINE_HEIGHT / 2;
+			return this.#box(clamp(start, left, left + width - w), top, w);
+		}));
+		return [{ label: {
+			key: `note-${index}`,
+			text,
+			spots,
+			anchor: {
+				x: px,
+				y: py
+			}
+		} }];
+	}
+	#box(x, y, width) {
+		return {
+			x,
+			y,
+			width,
+			height: LINE_HEIGHT
+		};
+	}
+};
+export { AnnotationAxis, AnnotationLayer };

package/dist/core/AnnotationPlacer.js

@@ -0,0 +1,47 @@
+// src/core/AnnotationPlacer.ts
+var GAP = 2;
+var SAMPLES = 12;
+var overlaps = (a, b) => a.x < b.x + b.width + GAP && b.x < a.x + a.width + GAP && a.y < b.y + b.height + GAP && b.y < a.y + a.height + GAP;
+var crosses = (from, to, box) => Array.from({ length: 13 }, (_, i) => i / SAMPLES).some((t) => {
+	const x = from.x + (to.x - from.x) * t, y = from.y + (to.y - from.y) * t;
+	return x >= box.x && x <= box.x + box.width && y >= box.y && y <= box.y + box.height;
+});
+/** Hands out label boxes inside `bounds` that stay clear of each other, of markers and of connectors. */
+var AnnotationPlacer = class AnnotationPlacer {
+	bounds;
+	#labels = [];
+	#markers = [];
+	#wires = [];
+	constructor(bounds) {
+		this.bounds = bounds;
+	}
+	/** Point on `box` nearest to `point`: where a connector ends. */
+	static nearest(point, box) {
+		return {
+			x: Math.min(box.x + box.width, Math.max(box.x, point.x)),
+			y: Math.min(box.y + box.height, Math.max(box.y, point.y))
+		};
+	}
+	/** Keeps labels off an area they may not cover. */
+	reserve(box) {
+		this.#markers.push(box);
+	}
+	/** Takes the first free spot, reserving it and any connector to `anchor`. Null when none is free. */
+	place(spots, anchor) {
+		const spot = spots.find((box) => this.#free(box, anchor));
+		if (!spot) return null;
+		this.#labels.push(spot);
+		if (anchor) this.#wires.push([anchor, AnnotationPlacer.nearest(anchor, spot)]);
+		return spot;
+	}
+	#free(box, anchor) {
+		const { x, y, width, height } = this.bounds;
+		if (box.x < x || box.y < y || box.x + box.width > x + width || box.y + box.height > y + height) return false;
+		if ([...this.#labels, ...this.#markers].some((other) => overlaps(box, other))) return false;
+		if (this.#wires.some(([from, to]) => crosses(from, to, box))) return false;
+		if (!anchor) return true;
+		const end = AnnotationPlacer.nearest(anchor, box);
+		return !this.#labels.some((other) => crosses(anchor, end, other));
+	}
+};
+export { AnnotationPlacer };