@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/geomaps/DrillDownMap.js

@@ -0,0 +1,132 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { GeoAtlas, GeoLayer } from "../../data/GeoAtlas.js";
+import { ChoroplethBase } from "./ChoroplethBase.js";
+import { GeoClassification } from "./GeoClasses.js";
+import { GeoProjectionKind } from "./GeoProjection.js";
+import { GeoSamples } from "./GeoSamples.js";
+// src/charts/geomaps/DrillDownMap.ts
+var CHAR = 6.4;
+var SEPARATOR = 14;
+var CRUMB_Y = 12;
+/** Explore nested geography: click a region to zoom in and see what it contains, and use the breadcrumb or Escape to climb back. */
+var DrillDownMap = class extends ChoroplethBase {
+	static meta = {
+		id: "drill-down-map",
+		name: "Drill-down map",
+		family: ChartFamily.Geospatial,
+		dimension: Dimension.Two,
+		shape: DataShape.Geo,
+		description: "Opens each region into the regions inside it, from country to state to county, with a breadcrumb back up.",
+		tags: [
+			"map",
+			"drill",
+			"drilldown",
+			"hierarchy",
+			"interactive",
+			"zoom",
+			"usa",
+			"county"
+		],
+		sample: (seed) => GeoSamples.usStates(seed),
+		prepare: () => GeoAtlas.load(GeoLayer.UsCounties),
+		variants: {
+			projection: [GeoProjectionKind.AlbersUsa, GeoProjectionKind.Albers],
+			classification: [
+				GeoClassification.Continuous,
+				GeoClassification.Quantile,
+				GeoClassification.NaturalBreaks
+			]
+		},
+		valid: (values) => values.projection === GeoProjectionKind.AlbersUsa
+	};
+	#stack = [];
+	#busy = false;
+	defaults() {
+		return {
+			...super.defaults(),
+			projection: GeoProjectionKind.AlbersUsa,
+			graticule: false,
+			join: "fips",
+			zoom: true,
+			rootLabel: "All regions"
+		};
+	}
+	get framed() {
+		return false;
+	}
+	/** The regions drilled through, outermost first. */
+	get path() {
+		return this.#stack.map((level) => level.region);
+	}
+	/** Opens a region. Resolves to false when it has nothing inside it or a change is already under way. */
+	async drill(region) {
+		if (this.#busy) return false;
+		this.#busy = true;
+		try {
+			const { children, data, projection } = this.options;
+			const inside = await (children ?? GeoAtlas.children.bind(GeoAtlas))(region, this.path);
+			if (!inside?.features.length) return false;
+			const frame = this.#lastFrame;
+			if (frame) await this.viewport.fit(frame.path.bounds(region));
+			this.#stack.push({
+				region,
+				data,
+				projection
+			});
+			await this.viewport.reset(false);
+			this.update({
+				data: data?.demo ? GeoSamples.shaded(inside, this.#stack.length) : inside,
+				projection: GeoProjectionKind.Albers
+			});
+			this.options.onDrill?.(this.path);
+			return true;
+		} finally {
+			this.#busy = false;
+		}
+	}
+	/** Climbs to `depth`: 0 is the top. */
+	climb(depth = this.#stack.length - 1) {
+		const level = this.#stack[depth];
+		if (!level || this.#busy) return;
+		this.#stack.length = depth;
+		this.viewport.reset(false);
+		this.update({
+			data: level.data,
+			projection: level.projection
+		});
+		this.options.onDrill?.(this.path);
+	}
+	#lastFrame = null;
+	finishRegions(_ctx, frame, shapes) {
+		this.#lastFrame = frame;
+		shapes.on("click.drill", (_, region) => {
+			this.drill(region.feature);
+		});
+	}
+	drawKey(ctx, frame) {
+		super.drawKey(ctx, frame);
+		const names = [this.options.rootLabel, ...this.path.map((region) => String(region.properties?.[this.options.name] ?? region.id ?? ""))];
+		let x = 0;
+		const crumbs = (this.#stack.length ? names : []).map((text, depth) => {
+			const at = {
+				text,
+				depth,
+				x,
+				last: depth === names.length - 1
+			};
+			x += text.length * CHAR + SEPARATOR;
+			return at;
+		});
+		const labels = ctx.text(ctx.marks("crumbs", "text", crumbs, (d) => d.depth), 12, "ink");
+		this.halo(ctx, labels).attr("x", (d) => d.x).attr("y", CRUMB_Y).attr("font-weight", (d) => d.last ? 600 : 400).text((d) => d.last ? d.text : `${d.text} ›`).attr("role", (d) => d.last ? null : "button").attr("tabindex", (d) => d.last ? null : 0).style("cursor", (d) => d.last ? "default" : "pointer").on("click", (event, d) => {
+			event.stopPropagation();
+			if (!d.last) this.climb(d.depth);
+		}).on("keydown", (event, d) => {
+			if (!d.last && event.key === "Enter") this.climb(d.depth);
+		});
+		this.svg?.attr("tabindex", 0).on("keydown.drill", (event) => {
+			if (event.key === "Escape") this.climb();
+		});
+	}
+};
+export { DrillDownMap };

package/dist/charts/geomaps/GeoChart.js

@@ -0,0 +1,196 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { LegendPosition } from "../../core/enums.js";
+import { GeoFraming, GeoProjectionKind, GeoProjections } from "./GeoProjection.js";
+import { GeoViewport } from "./GeoViewport.js";
+import { color, forceCollide, forceSimulation, forceX, forceY, geoArea, geoBounds, geoGraticule, geoPath, range } from "d3";
+// src/charts/geomaps/GeoChart.ts
+var SPHERE = { type: "Sphere" };
+var USA_BOX = {
+	type: "MultiPoint",
+	coordinates: [[-122, 28], [-69, 48]]
+};
+var ids = 0;
+/**
+* Base of every map: projection, framing, sphere, graticule and key strip.
+* Subclasses say what to fit (`target`) and draw marks in `drawMap`.
+*/
+var GeoChart = class extends Chart2D {
+	clipId = `geo-clip-${++ids}`;
+	/** Programmatic pan and zoom: `zoomIn`, `zoomOut`, `reset`, `fit`. */
+	viewport = new GeoViewport(this);
+	defaults() {
+		return {
+			projection: GeoProjectionKind.NaturalEarth,
+			framing: GeoFraming.Auto,
+			graticule: true,
+			graticuleStep: 30,
+			legend: LegendPosition.None,
+			zoom: false,
+			maxZoom: 16
+		};
+	}
+	plotMargin() {
+		return {
+			top: 6,
+			right: 8,
+			bottom: 6,
+			left: 8
+		};
+	}
+	/** Height of the key strip under the map. */
+	keyHeight() {
+		return 0;
+	}
+	/** Room to keep clear inside the map, for marks that stand taller than their location. */
+	inset(_ctx) {
+		return {};
+	}
+	drawKey(_ctx, _frame) {}
+	/** Whether the globe's outline frames the map; abstract layouts turn it off. */
+	get framed() {
+		return true;
+	}
+	/** Called as the view moves. `settled` is true once a gesture ends. */
+	viewMoved(_transform, settled) {
+		if (settled) this.settled(this.viewport.scale);
+	}
+	/** A gesture ended at this zoom. */
+	settled(_scale) {}
+	/** Under-map layer such as tiles. */
+	drawBackdrop(_ctx, _frame) {}
+	get zoomable() {
+		return !!this.options.zoom;
+	}
+	/** Whether the map redraws from its projection as it moves, rather than scaling what is drawn. */
+	get semanticZoom() {
+		return false;
+	}
+	viewLimits({ width, height }) {
+		return {
+			scale: [1, this.options.maxZoom],
+			pan: [[0, 0], [width, height]]
+		};
+	}
+	draw(outer) {
+		const frame = this.frame(outer);
+		const ctx = this.viewport.attach(outer, {
+			enabled: this.zoomable,
+			width: frame.width,
+			height: frame.height,
+			limits: this.viewLimits(frame),
+			semantic: this.semanticZoom,
+			pinned: this.framed,
+			smooth: this.animated
+		});
+		this.drawBackdrop(ctx, frame);
+		this.drawBase(ctx, frame);
+		this.drawMap(ctx, frame);
+		this.drawKey(outer, frame);
+		this.viewport.finish(outer);
+	}
+	/** Wraps a fitted projection in the frame marks draw against. */
+	frameOf(projection, width, height) {
+		const path = geoPath(projection);
+		return {
+			projection,
+			path,
+			width,
+			height,
+			locate(lon, lat) {
+				const [x, y] = path.centroid({
+					type: "Point",
+					coordinates: [lon, lat]
+				});
+				return Number.isFinite(x) && Number.isFinite(y) ? [x, y] : null;
+			},
+			anchor(feature) {
+				const { geometry } = feature;
+				const parts = geometry?.type === "MultiPolygon" ? geometry.coordinates.map((coordinates) => ({
+					type: "Polygon",
+					coordinates
+				})) : [geometry];
+				const main = parts.reduce((best, part) => geoArea(part) > geoArea(best) ? part : best, parts[0]);
+				const [x, y] = path.centroid(main);
+				return Number.isFinite(x) && Number.isFinite(y) ? [x, y] : null;
+			}
+		};
+	}
+	frame(ctx) {
+		const { projection: kind = GeoProjectionKind.NaturalEarth, rotate, framing } = this.options;
+		const width = ctx.plot.width, height = Math.max(40, ctx.plot.height - this.keyHeight());
+		const { top = 0, right = 0, bottom = 0, left = 0 } = this.inset(ctx);
+		const projection = GeoProjections.create(kind);
+		const target = framing === GeoFraming.Sphere ? null : this.target();
+		const box = target ? geoBounds(target) : null;
+		const bounded = box?.flat().every(Number.isFinite) ? box : null;
+		const span = bounded ? (bounded[1][0] - bounded[0][0] + 360) % 360 || 360 : 360;
+		const zoomed = !!bounded && (framing === GeoFraming.Data || span < 240 && bounded[1][1] - bounded[0][1] < 110);
+		const outline = kind === GeoProjectionKind.AlbersUsa ? target ?? USA_BOX : zoomed && span + (bounded[1][1] - bounded[0][1]) > .01 ? target : zoomed ? this.padded(bounded) : GeoProjections.outline(kind);
+		if (rotate) GeoProjections.rotate(projection, rotate);
+		else if (zoomed) GeoProjections.center(projection, kind, bounded);
+		const extent = [[left + 1, top + 1], [width - right - 1, height - bottom - 1]];
+		projection.fitExtent(extent, outline);
+		if (!projection.translate().every(Number.isFinite)) projection.fitExtent(extent, USA_BOX);
+		if (zoomed || GeoProjections.unbounded(kind)) projection.clipExtent?.([[0, 0], [width, height]]);
+		return this.frameOf(projection, width, height);
+	}
+	/** A single point has no extent to fit: frame the few degrees around it. */
+	padded([[west, south]]) {
+		return {
+			type: "MultiPoint",
+			coordinates: [[west - 4, south - 3], [west + 4, south + 3]]
+		};
+	}
+	drawBase(ctx, { path }) {
+		const { theme } = ctx;
+		ctx.root.attr("clip-path", GeoProjections.lobed(this.options.projection) ? this.clip(ctx, path(SPHERE) ?? "", "lobes") : null);
+		ctx.marks("sphere", "path", this.framed ? [SPHERE] : []).attr("d", (d) => path(d) ?? "").attr("fill", theme.grid).attr("fill-opacity", .28).attr("stroke", theme.axis).attr("stroke-width", 1).attr("stroke-opacity", .8);
+		const step = this.options.graticuleStep;
+		const lines = this.options.graticule ? [geoGraticule().step([step, step])()] : [];
+		ctx.marks("graticule", "path", lines).attr("d", (d) => path(d) ?? "").attr("fill", "none").attr("stroke", theme.grid).attr("stroke-width", .75);
+	}
+	/** Region border: a hairline of surface, thin enough to keep small countries visible. */
+	hairline(ctx) {
+		return Math.max(.35, Math.min(1, ctx.plot.width / 900));
+	}
+	/** Fades filled shapes in, with their geometry in place from the first frame. */
+	fill(ctx, marks, d, opacity = 1, stagger = 0) {
+		return ctx.set(marks, {
+			d,
+			"fill-opacity": opacity
+		}, {
+			d,
+			"fill-opacity": 0
+		}, stagger);
+	}
+	/** Text-legible ink for any colour string a scale can return. */
+	inkOn(ctx, fill) {
+		return ctx.palette.inkOn(color(fill)?.formatHex() ?? fill);
+	}
+	/** Surface-coloured halo so labels stay readable over land and marks. */
+	halo(ctx, labels) {
+		return labels.attr("paint-order", "stroke").attr("stroke", ctx.theme.surface).attr("stroke-width", 3).attr("stroke-linejoin", "round");
+	}
+	/** A `clip-path` reference limited to `d`, regenerated on each paint. */
+	clip(ctx, d, name = "mask") {
+		const id = `${this.clipId}-${name}`, holder = ctx.group(`clip-${name}`);
+		let shape = holder.select("clipPath");
+		if (shape.empty()) shape = holder.append("clipPath").attr("id", id);
+		shape.selectAll("path").data([d]).join("path").attr("d", (value) => value);
+		return `url(#${id})`;
+	}
+	/** Pushes overlapping discs apart while pulling each towards its true position, inside the map. */
+	dodge(discs, frame, gap = 1, ticks = 160) {
+		const keep = (d) => {
+			d.x = Math.max(d.r + 1, Math.min(frame.width - d.r - 1, d.x));
+			d.y = Math.max(d.r + 1, Math.min(frame.height - d.r - 1, d.y));
+		};
+		const simulation = forceSimulation(discs).stop().force("x", forceX((d) => d.homeX).strength(.09)).force("y", forceY((d) => d.homeY).strength(.09)).force("collide", forceCollide((d) => d.r + gap).iterations(3));
+		for (const _ of range(ticks)) {
+			simulation.tick();
+			discs.forEach(keep);
+		}
+		return discs;
+	}
+};
+export { GeoChart };

package/dist/charts/geomaps/GeoClasses.js

@@ -0,0 +1,89 @@
+import { extent, quantileSorted, range } from "d3";
+// src/charts/geomaps/GeoClasses.ts
+var GeoClassification = /* @__PURE__ */ function(GeoClassification) {
+	GeoClassification["Continuous"] = "continuous";
+	GeoClassification["Quantile"] = "quantile";
+	GeoClassification["EqualInterval"] = "equal-interval";
+	GeoClassification["NaturalBreaks"] = "natural-breaks";
+	return GeoClassification;
+}({});
+/** Jenks natural breaks by dynamic programming: minimises within-class variance. */
+function naturalBreaks(sorted, bins) {
+	const n = sorted.length;
+	const prefix = [0], squares = [0];
+	for (const value of sorted) {
+		prefix.push(prefix.at(-1) + value);
+		squares.push(squares.at(-1) + value * value);
+	}
+	const cost = (from, to) => {
+		const total = prefix[to + 1] - prefix[from];
+		return squares[to + 1] - squares[from] - total * total / (to - from + 1);
+	};
+	let best = sorted.map((_, i) => cost(0, i));
+	const cuts = [];
+	for (let k = 1; k < bins; k++) {
+		const next = best.slice(), cut = new Array(n).fill(0);
+		for (let i = k; i < n; i++) {
+			next[i] = Infinity;
+			for (let j = k; j <= i; j++) {
+				const trial = best[j - 1] + cost(j, i);
+				if (trial < next[i]) {
+					next[i] = trial;
+					cut[i] = j;
+				}
+			}
+		}
+		best = next;
+		cuts.push(cut);
+	}
+	const breaks = [];
+	let end = n - 1;
+	for (let k = bins - 2; k >= 0; k--) {
+		end = cuts[k][end] - 1;
+		breaks.unshift((sorted[end] + sorted[end + 1]) / 2);
+	}
+	return breaks;
+}
+/** Turns a value column into class breaks and a 0..1 tone. Tolerates empty and constant columns. */
+var GeoClasses = class {
+	/** Ascending class limits, first = minimum, last = maximum. Continuous scales have just the two. */
+	breaks;
+	min;
+	max;
+	classed;
+	constructor(values, method = "continuous", bins = 5) {
+		const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+		const [low = 0, high = 1] = extent(sorted);
+		this.min = low;
+		this.max = high > low ? high : low + 1;
+		this.classed = method !== "continuous";
+		const inner = () => {
+			if (sorted.length <= bins) return [];
+			if (method === "quantile") return range(1, bins).map((i) => quantileSorted(sorted, i / bins));
+			if (method === "natural-breaks") return naturalBreaks(sorted, bins);
+			if (method === "equal-interval") return range(1, bins).map((i) => this.min + (this.max - this.min) * i / bins);
+			return [];
+		};
+		this.breaks = [.../* @__PURE__ */ new Set([
+			this.min,
+			...inner(),
+			this.max
+		])];
+	}
+	get bins() {
+		return this.breaks.length - 1;
+	}
+	bin(value) {
+		const i = this.breaks.findIndex((limit) => value < limit);
+		return Math.min(this.bins - 1, Math.max(0, (i < 0 ? this.bins : i) - 1));
+	}
+	/** Position on a 0..1 colour ramp: the class centre when classed, proportional otherwise. */
+	tone(value) {
+		return this.classed ? (this.bin(value) + .5) / this.bins : (value - this.min) / (this.max - this.min);
+	}
+	/** Representative value of a class. */
+	center(bin) {
+		return (this.breaks[bin] + this.breaks[bin + 1]) / 2;
+	}
+};
+export { GeoClasses, GeoClassification };

package/dist/charts/geomaps/GeoField.js

@@ -0,0 +1,111 @@
+import { blur2, contours, extent, range } from "d3";
+// src/charts/geomaps/GeoField.ts
+var GeoKernel = /* @__PURE__ */ function(GeoKernel) {
+	GeoKernel["Gaussian"] = "gaussian";
+	GeoKernel["Quartic"] = "quartic";
+	GeoKernel["Uniform"] = "uniform";
+	return GeoKernel;
+}({});
+var GeoInterpolation = /* @__PURE__ */ function(GeoInterpolation) {
+	GeoInterpolation["Kernel"] = "kernel";
+	GeoInterpolation["InverseDistance"] = "inverse-distance";
+	return GeoInterpolation;
+}({});
+var RAD = Math.PI / 180;
+var SHAPE = {
+	["gaussian"]: (u) => u > 1 ? 0 : Math.exp(-4.5 * u * u),
+	["quartic"]: (u) => u > 1 ? 0 : (1 - u * u) ** 2,
+	["uniform"]: (u) => u > 1 ? 0 : 1
+};
+var unit = (lon, lat) => {
+	const c = Math.cos(lat * RAD);
+	return [
+		c * Math.cos(lon * RAD),
+		c * Math.sin(lon * RAD),
+		Math.sin(lat * RAD)
+	];
+};
+/** A continuous surface over the sphere, estimated from scattered samples using great-circle distance. */
+var GeoField = class GeoField {
+	points;
+	at;
+	constructor(samples, { interpolation, kernel = "gaussian", bandwidth = 18 }) {
+		this.points = samples.map(({ lon, lat, value }) => ({
+			at: unit(lon, lat),
+			value
+		}));
+		this.at = interpolation === "kernel" ? this.kernel(SHAPE[kernel], bandwidth * RAD) : this.inverseDistance();
+	}
+	angle(a, b) {
+		return Math.acos(Math.min(1, a[0] * b[0] + a[1] * b[1] + a[2] * b[2]));
+	}
+	kernel(shape, reach) {
+		return (lon, lat) => {
+			const at = unit(lon, lat);
+			let total = 0;
+			for (const point of this.points) total += point.value * shape(this.angle(at, point.at) / reach);
+			return total;
+		};
+	}
+	inverseDistance() {
+		return (lon, lat) => {
+			const at = unit(lon, lat);
+			let weight = 0, total = 0;
+			for (const point of this.points) {
+				const w = 1 / Math.max(1e-4, this.angle(at, point.at)) ** 3;
+				weight += w;
+				total += w * point.value;
+			}
+			return weight ? total / weight : 0;
+		};
+	}
+	/** Iso-bands sampled every `step` degrees: spherical polygons to fill, and lines that stop at the grid edge. */
+	bands(step, thresholds) {
+		const width = Math.round(360 / step) + 1, height = Math.round(180 / step) + 1;
+		const grid = new Float64Array(width * height);
+		for (let j = 0; j < height; j++) for (let i = 0; i < width; i++) grid[i + j * width] = this.at(-180 + i * step, 90 - j * step);
+		blur2({
+			data: grid,
+			width,
+			height
+		}, 1);
+		const [low = 0, top = 1] = extent(grid);
+		const levels = range(1, thresholds + 1).map((i) => low + (top - low) * i / (thresholds + 1));
+		const place = ([x, y]) => [Math.min(180, Math.max(-180, -180 + (x - .5) * step)), Math.min(90, Math.max(-90, 90 - (y - .5) * step))];
+		const edge = ([x, y]) => x <= .5 || x >= width - .5 || y <= .5 || y >= height - .5;
+		return contours().size([width, height]).thresholds(levels)(Array.from(grid)).filter((band) => band.coordinates.length).map((band) => ({
+			value: band.value,
+			geometry: {
+				type: "MultiPolygon",
+				coordinates: band.coordinates.map((polygon) => polygon.map((ring, i) => GeoField.wind(ring.map(place), i === 0)))
+			},
+			lines: {
+				type: "MultiLineString",
+				coordinates: band.coordinates.flat().flatMap((ring) => GeoField.split(ring, edge).map((part) => part.map(place)))
+			}
+		}));
+	}
+	/** d3-geo reads ring direction on the sphere: exteriors run clockwise, holes anticlockwise. */
+	static wind(ring, exterior) {
+		let area = 0;
+		ring.forEach(([x, y], i) => {
+			const [u, v] = ring[(i + 1) % ring.length];
+			area += x * v - u * y;
+		});
+		return area > 0 === exterior ? ring.slice().reverse() : ring;
+	}
+	/** Breaks a closed ring wherever it runs along the grid boundary, which is not an iso-line. */
+	static split(ring, edge) {
+		const parts = [];
+		let part = [];
+		ring.forEach((point) => {
+			if (edge(point)) {
+				if (part.length > 1) parts.push(part);
+				part = [];
+			} else part.push(point);
+		});
+		if (part.length > 1) parts.push(part);
+		return parts;
+	}
+};
+export { GeoField, GeoInterpolation, GeoKernel };

package/dist/charts/geomaps/GeoLand.js

@@ -0,0 +1,29 @@
+import { SampleData } from "../../data/SampleData.js";
+import { geoBounds, geoContains } from "d3";
+// src/charts/geomaps/GeoLand.ts
+var hits = /* @__PURE__ */ new WeakMap();
+/** Shared land geometry: the bundled world outline and fast point-in-land tests. */
+var GeoLand = class {
+	static bundled = null;
+	/** Natural Earth 110m countries, shared by every map that needs a backdrop. */
+	static get world() {
+		return this.bundled ??= SampleData.world();
+	}
+	static boxes(collection) {
+		let boxes = hits.get(collection);
+		if (!boxes) hits.set(collection, boxes = collection.features.map((feature) => ({
+			feature,
+			box: geoBounds(feature)
+		})));
+		return boxes;
+	}
+	static boxContains([[west, south], [east, north]], lon, lat) {
+		if (lat < south || lat > north) return false;
+		return west <= east ? lon >= west && lon <= east : lon >= west || lon <= east;
+	}
+	/** The feature under a point, or undefined over water. */
+	static at(collection, lon, lat) {
+		return this.boxes(collection).find(({ feature, box }) => this.boxContains(box, lon, lat) && geoContains(feature, [lon, lat]))?.feature;
+	}
+};
+export { GeoLand };

package/dist/charts/geomaps/GeoLegend.js

@@ -0,0 +1,56 @@
+import { Scales } from "../../core/Scales.js";
+import { range, scaleLinear } from "d3";
+// src/charts/geomaps/GeoLegend.ts
+var WIDTH = 190;
+var SWATCH = 8;
+var CHAR = 6.2;
+var fmt = (value, reach) => Scales.format(value, reach);
+/** Keys drawn inside the plot, in the strip `GeoChart.keyHeight` reserves below the map. */
+var GeoLegend = class {
+	static height = 30;
+	/** A value-positioned ramp: class widths show the data's breaks, so the key differs by method. */
+	static classes(ctx, frame, classes, color, format) {
+		const width = Math.min(WIDTH, ctx.plot.width * .6), y = frame.height + 8;
+		const x = scaleLinear([classes.min, classes.max], [0, width]);
+		const reach = Math.max(Math.abs(classes.min), Math.abs(classes.max));
+		const label = format ?? ((value) => fmt(value, reach));
+		const swatches = classes.classed ? range(classes.bins).map((i) => ({
+			x: x(classes.breaks[i]),
+			w: x(classes.breaks[i + 1]) - x(classes.breaks[i]) - 1,
+			fill: color(classes.center(i))
+		})) : range(20).map((i) => {
+			const value = classes.min + (classes.max - classes.min) * (i + .5) / 20;
+			return {
+				x: width * i / 20,
+				w: width / 20,
+				fill: color(value)
+			};
+		});
+		ctx.marks("key-swatches", "rect", swatches).attr("x", (d) => d.x).attr("y", y).attr("width", (d) => Math.max(.5, d.w)).attr("height", SWATCH).attr("fill", (d) => d.fill);
+		const ticks = classes.classed ? classes.breaks : scaleLinear([classes.min, classes.max], [0, 1]).ticks(4);
+		let edge = -Infinity;
+		const shown = ticks.filter((tick, i) => {
+			const at = x(tick), half = label(tick).length * CHAR / 2;
+			if (at - half < edge && i !== ticks.length - 1) return false;
+			edge = at + half + 4;
+			return true;
+		});
+		ctx.text(ctx.marks("key-ticks", "text", shown, (d) => d).attr("x", (d) => x(d)).attr("y", y + SWATCH + 12).attr("text-anchor", "middle").text(label), 10, "muted");
+	}
+	/** Nested symbols in the map's lower left corner, sharing a baseline: real sizes, labelled by value. */
+	static nested(ctx, frame, entries, shape, { up = 1, down = 1, side = 1 } = {}) {
+		const big = Math.max(0, ...entries.map((entry) => entry.radius)) * side;
+		const base = frame.height - 2, reach = Math.max(0, ...entries.map((entry) => entry.value));
+		ctx.marks("key-sizes", "path", entries, (d) => d.value).attr("d", (d) => shape(d.radius)).attr("transform", (d) => `translate(${big + 1},${base - d.radius * down})`).attr("fill", "none").attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 1);
+		let above = base + 11;
+		const rows = [...entries].reverse().map((entry) => {
+			above = Math.min(base - entry.radius * (up + down) + 4, above - 11);
+			return {
+				...entry,
+				y: above
+			};
+		});
+		ctx.text(ctx.marks("key-size-labels", "text", rows, (d) => d.value).attr("x", big * 2 + 6).attr("y", (d) => d.y).text((d) => fmt(d.value, reach)), 10, "muted");
+	}
+};
+export { GeoLegend };