@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/geoflows/DensityFlowMap.js

@@ -0,0 +1,184 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { FlowGeometry } from "./FlowGeometry.js";
+import { GeoFlowProjection } from "./GeoFlowFrame.js";
+import { GeoFlowSample } from "./GeoFlowSample.js";
+import { GeoLinkChart } from "./GeoLinkChart.js";
+import { contourDensity, geoPath, rollups, scaleLinear, sum } from "d3";
+import { hexbin } from "d3-hexbin";
+// src/charts/geoflows/DensityFlowMap.ts
+/** How route density is aggregated. */
+var DensityFlowBin = /* @__PURE__ */ function(DensityFlowBin) {
+	DensityFlowBin["Hex"] = "hexagons";
+	DensityFlowBin["Square"] = "squares";
+	DensityFlowBin["Contour"] = "contours";
+	DensityFlowBin["Streak"] = "streaks";
+	return DensityFlowBin;
+}({});
+/** Transform from traffic to mark size. */
+var DensityFlowScale = /* @__PURE__ */ function(DensityFlowScale) {
+	DensityFlowScale["Linear"] = "linear";
+	DensityFlowScale["Sqrt"] = "sqrt";
+	DensityFlowScale["Log"] = "log";
+	return DensityFlowScale;
+}({});
+var RAMP = {
+	["linear"]: (t) => t,
+	["sqrt"]: Math.sqrt,
+	["log"]: (t) => Math.log10(1 + 9 * t)
+};
+var INVERSE = {
+	["linear"]: (t) => t,
+	["sqrt"]: (t) => t * t,
+	["log"]: (t) => (10 ** t - 1) / 9
+};
+/** Show the corridors in a mass of routes: when individual flows would be a hairball, aggregate them into traffic density. */
+var DensityFlowMap = class extends GeoLinkChart {
+	static meta = {
+		id: "density-flow-map",
+		name: "Density flow map",
+		family: ChartFamily.Geospatial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Samples routes along their great circles and bins the traffic to show corridors and their direction.",
+		tags: [
+			"corridors",
+			"traffic density",
+			"shipping lanes"
+		],
+		sample: (seed) => GeoFlowSample.flows(seed, 90),
+		variants: {
+			projection: [
+				GeoFlowProjection.NaturalEarth,
+				GeoFlowProjection.EqualEarth,
+				GeoFlowProjection.Orthographic,
+				GeoFlowProjection.Mercator
+			],
+			bin: [
+				"hexagons",
+				"squares",
+				"contours",
+				"streaks"
+			],
+			scale: [
+				"sqrt",
+				"linear",
+				"log"
+			],
+			arrows: [false, true]
+		},
+		valid: (v) => !(v.bin === "streaks" && v.arrows)
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			bin: "hexagons",
+			scale: "sqrt",
+			arrows: false,
+			cell: 11
+		};
+	}
+	categorical() {
+		return false;
+	}
+	samples(frame) {
+		return this.links.flatMap((link) => {
+			const steps = Math.max(8, Math.round(FlowGeometry.km(link.from, link.to) / 250));
+			return this.runs(frame, FlowGeometry.geodesic(link.from, link.to, steps)).flatMap((run) => run.slice(1).map((point, i) => {
+				const a = run[i], dx = point[0] - a[0], dy = point[1] - a[1], length = Math.hypot(dx, dy) || 1;
+				return {
+					x: point[0],
+					y: point[1],
+					dx: dx / length,
+					dy: dy / length,
+					weight: link.value
+				};
+			}));
+		});
+	}
+	cells(samples, size, width, height) {
+		const merge = (key, x, y, rows) => ({
+			key,
+			x,
+			y,
+			weight: sum(rows, (row) => row.weight),
+			dx: sum(rows, (row) => row.dx * row.weight),
+			dy: sum(rows, (row) => row.dy * row.weight)
+		});
+		if (this.options.bin === "hexagons") return hexbin().x((d) => d.x).y((d) => d.y).radius(size).extent([[0, 0], [width, height]])(samples).map((rows) => merge(`${rows.x.toFixed(1)}/${rows.y.toFixed(1)}`, rows.x, rows.y, rows));
+		return rollups(samples, (rows) => rows, (row) => Math.floor(row.x / size), (row) => Math.floor(row.y / size)).flatMap(([column, rows]) => rows.map(([line, members]) => merge(`${column}/${line}`, (column + .5) * size, (line + .5) * size, members)));
+	}
+	drawContours(ctx, frame, samples) {
+		const { scale } = this.options;
+		const density = contourDensity().x((d) => d.x).y((d) => d.y).weight((d) => d.weight).size([frame.width, frame.height]).bandwidth(7).cellSize(4);
+		const probe = samples.length ? density.contours(samples) : null;
+		const top = probe?.max ?? 1;
+		const levels = Array.from({ length: 8 }, (_, i) => INVERSE[scale]((i + 1) / 9) * top);
+		const bands = probe ? levels.map((level, i) => ({
+			i,
+			d: geoPath().digits(1)(probe(level)) ?? ""
+		})).filter((band) => band.d) : [];
+		const layer = this.clipped(ctx, "contours", frame.path({ type: "Sphere" }) ?? "");
+		const shapes = ctx.marks("bands", "path", bands, (d) => d.i, layer).attr("fill", (d) => ctx.palette.sequential(.12 + d.i / 7 * .88)).attr("fill-opacity", .82).attr("stroke", ctx.theme.surface).attr("stroke-width", .5);
+		ctx.set(shapes, { d: (d) => d.d }, { d: (d) => d.d });
+		ctx.hover(shapes, (d) => ({
+			title: "Traffic density",
+			rows: [["Band", `${d.i + 1} of 8`], ["Scale", scale]]
+		}));
+	}
+	plotGeo(ctx, frame) {
+		const { bin, scale, arrows, cell } = this.options;
+		const size = cell;
+		const samples = this.samples(frame);
+		const ramp = RAMP[scale];
+		const contour = bin === "contours";
+		if (contour) this.drawContours(ctx, frame, samples);
+		const cells = this.cells(samples, size * (contour ? 1.6 : 1), frame.width, frame.height).filter((d) => d.weight > 0);
+		const top = Math.max(1, ...cells.map((d) => d.weight));
+		const level = (d) => ramp(d.weight / top);
+		const tone = scaleLinear([0, 1], [.2, 1]);
+		const hexes = hexbin().radius(size);
+		const blocks = bin === "hexagons" || bin === "squares" ? cells : [];
+		const inverse = (d) => Math.max(.3, Math.sqrt(level(d)));
+		const layer = this.clipped(ctx, "cells", frame.path({ type: "Sphere" }) ?? "");
+		const shapes = ctx.marks("cells", "path", blocks, (d) => d.key, layer).attr("fill", (d) => ctx.palette.sequential(tone(level(d))));
+		const shape = (d) => {
+			const scaleBy = inverse(d);
+			if (bin === "hexagons") return `M${d.x.toFixed(1)},${d.y.toFixed(1)}${hexes.hexagon(size * scaleBy * .94)}`;
+			const half = size / 2 * scaleBy * .94;
+			return `M${(d.x - half).toFixed(1)},${(d.y - half).toFixed(1)}h${(half * 2).toFixed(1)}v${(half * 2).toFixed(1)}h${(-half * 2).toFixed(1)}Z`;
+		};
+		ctx.set(shapes, { d: shape }, { d: shape });
+		ctx.hover(shapes, (d) => ({
+			title: "Traffic",
+			color: ctx.palette.sequential(tone(level(d))),
+			rows: [["Volume", Math.round(d.weight)]]
+		}));
+		const direct = (d) => Math.hypot(d.dx, d.dy) || 1;
+		const streaks = bin === "streaks" ? cells : [];
+		const lines = ctx.marks("streaks", "path", streaks, (d) => d.key, layer).attr("fill", "none").attr("stroke", (d) => ctx.palette.sequential(tone(level(d)))).attr("stroke-width", 2).attr("stroke-linecap", "round");
+		ctx.set(lines, { d: (d) => {
+			const reach = size * (.2 + level(d) * .75), ux = d.dx / direct(d), uy = d.dy / direct(d);
+			return FlowGeometry.polyline([[d.x - ux * reach, d.y - uy * reach], [d.x + ux * reach, d.y + uy * reach]]);
+		} });
+		ctx.hover(lines, (d) => ({
+			title: "Traffic",
+			rows: [["Volume", Math.round(d.weight)]]
+		}));
+		const onGlobe = (x, y) => {
+			const place = frame.projection.invert?.([x, y]), back = place && frame.projection(place);
+			return !!back && Math.hypot(back[0] - x, back[1] - y) < 1;
+		};
+		const pointers = arrows ? cells.filter((d) => {
+			const ux = d.dx / direct(d), uy = d.dy / direct(d);
+			return d.weight > top * .22 && onGlobe(d.x + ux * 8, d.y + uy * 8) && onGlobe(d.x - ux * 8, d.y - uy * 8);
+		}) : [];
+		const tips = ctx.marks("pointers", "path", pointers, (d) => d.key).attr("fill", ctx.theme.ink).attr("stroke", ctx.theme.surface).attr("stroke-width", .75).attr("pointer-events", "none");
+		ctx.set(tips, { d: (d) => {
+			const ux = d.dx / direct(d), uy = d.dy / direct(d);
+			return FlowGeometry.arrow([d.x + ux * 3.5, d.y + uy * 3.5], [d.x - ux * 3.5, d.y - uy * 3.5], 7);
+		} });
+		this.labels(ctx, this.stopLabels(frame, this.stops, () => 2), "labels", 4);
+		this.keyRamp(ctx, "Traffic", "low", "high", (t) => ctx.palette.sequential(.2 + t * .8));
+	}
+};
+export { DensityFlowBin, DensityFlowMap, DensityFlowScale };

package/dist/charts/geoflows/FlowGeometry.js

@@ -0,0 +1,137 @@
+import { geoDistance, geoInterpolate } from "d3";
+// src/charts/geoflows/FlowGeometry.ts
+var fixed = (value) => +value.toFixed(1);
+var RADIANS = Math.PI / 180;
+var mercatorY = (lat) => Math.log(Math.tan(Math.PI / 4 + Math.max(-89, Math.min(89, lat)) * RADIANS / 2));
+var mercatorLat = (y) => (2 * Math.atan(Math.exp(y)) - Math.PI / 2) / RADIANS;
+/** Pure path geometry for flows: sampling, bowing, tapering and bundling. */
+var FlowGeometry = class {
+	static EARTH_KM = 6371;
+	static km(a, b) {
+		return geoDistance(a, b) * this.EARTH_KM;
+	}
+	static geodesic(a, b, steps = 48) {
+		const along = geoInterpolate(a, b);
+		return Array.from({ length: steps + 1 }, (_, i) => along(i / steps));
+	}
+	/** Line of constant bearing, the shortest way round in longitude. */
+	static rhumb(a, b, steps = 48) {
+		const span = (b[0] - a[0] + 540) % 360 - 180, y0 = mercatorY(a[1]), y1 = mercatorY(b[1]);
+		return Array.from({ length: steps + 1 }, (_, i) => {
+			const t = i / steps;
+			return [a[0] + span * t, mercatorLat(y0 + (y1 - y0) * t)];
+		});
+	}
+	/** Quadratic curve bowing to the right of travel, so counterflows pass side by side. */
+	static arc(a, b, bend = .18, steps = 28) {
+		const c = [(a[0] + b[0]) / 2 + (b[1] - a[1]) * bend, (a[1] + b[1]) / 2 - (b[0] - a[0]) * bend];
+		return Array.from({ length: steps + 1 }, (_, i) => {
+			const t = i / steps, s = 1 - t;
+			return [s * s * a[0] + 2 * s * t * c[0] + t * t * b[0], s * s * a[1] + 2 * s * t * c[1] + t * t * b[1]];
+		});
+	}
+	static straight(a, b, steps = 12) {
+		return Array.from({ length: steps + 1 }, (_, i) => [a[0] + (b[0] - a[0]) * i / steps, a[1] + (b[1] - a[1]) * i / steps]);
+	}
+	static polyline(points) {
+		return points.length < 2 ? "" : `M${points.map(([x, y]) => `${fixed(x)},${fixed(y)}`).join("L")}`;
+	}
+	/** Filled band along `points`; `width(t)` is the full width at fraction `t` of the way along. */
+	static ribbon(points, width) {
+		if (points.length < 2) return "";
+		const left = [], right = [];
+		points.forEach((point, i) => {
+			const a = points[Math.max(0, i - 1)], b = points[Math.min(points.length - 1, i + 1)];
+			const dx = b[0] - a[0], dy = b[1] - a[1], length = Math.hypot(dx, dy) || 1;
+			const half = width(i / (points.length - 1)) / 2, nx = -dy / length, ny = dx / length;
+			left.push([point[0] + nx * half, point[1] + ny * half]);
+			right.push([point[0] - nx * half, point[1] - ny * half]);
+		});
+		return `${this.polyline([...left, ...right.reverse()])}Z`;
+	}
+	/** The same path moved sideways, to the right of travel, so counterflows sit next to each other. */
+	static offset(points, distance) {
+		return points.map((point, i) => {
+			const a = points[Math.max(0, i - 1)], b = points[Math.min(points.length - 1, i + 1)];
+			const dx = b[0] - a[0], dy = b[1] - a[1], length = Math.hypot(dx, dy) || 1;
+			return [point[0] - dy / length * distance, point[1] + dx / length * distance];
+		});
+	}
+	/** Arrowhead whose tip sits on `tip`, pointing away from `from`. */
+	static arrow(tip, from, size) {
+		const angle = Math.atan2(tip[1] - from[1], tip[0] - from[0]);
+		const wing = (turn) => [tip[0] - size * Math.cos(angle + turn), tip[1] - size * Math.sin(angle + turn)];
+		return `${this.polyline([
+			tip,
+			wing(.48),
+			wing(-.48)
+		])}Z`;
+	}
+	/** Trims a sampled path so a head or a dot does not sit on top of it. */
+	static trim(points, start, end) {
+		const within = (point, anchor, reach) => Math.hypot(point[0] - anchor[0], point[1] - anchor[1]) < reach;
+		const head = points[0], tail = points[points.length - 1];
+		const kept = points.filter((point) => !within(point, head, start) && !within(point, tail, end));
+		return kept.length >= 2 ? kept : [...points];
+	}
+	/** Corner cutting: a smooth track that stays near every recorded fix. */
+	static chaikin(points, rounds = 2) {
+		let line = [...points];
+		for (let round = 0; round < rounds && line.length > 2; round++) {
+			const next = [line[0]];
+			for (let i = 0; i < line.length - 1; i++) {
+				const [ax, ay] = line[i], [bx, by] = line[i + 1];
+				next.push([ax * .75 + bx * .25, ay * .75 + by * .25], [ax * .25 + bx * .75, ay * .25 + by * .75]);
+			}
+			next.push(line[line.length - 1]);
+			line = next;
+		}
+		return line;
+	}
+	/** Force-directed edge bundling (Holten & van Wijk): compatible edges pull together into trunks. */
+	static bundle(edges, stiffness = .12, cycles = 26, inner = 8) {
+		const paths = edges.map(([a, b]) => this.straight(a, b, inner + 1));
+		const peers = edges.map((edge, i) => edges.flatMap((other, j) => {
+			if (i === j) return [];
+			const score = this.compatibility(edge, other);
+			if (score.value < .55) return [];
+			return [{
+				j,
+				flip: score.flip
+			}];
+		}));
+		for (let cycle = 0; cycle < cycles; cycle++) {
+			const step = 3.2 * (1 - cycle / cycles);
+			paths.map((path, i) => path.map((point, k) => {
+				if (k === 0 || k === path.length - 1) return point;
+				const [x, y] = point, a = path[k - 1], b = path[k + 1];
+				let fx = (a[0] + b[0] - 2 * x) * stiffness * 6, fy = (a[1] + b[1] - 2 * y) * stiffness * 6;
+				for (const { j, flip } of peers[i]) {
+					const other = paths[j][flip ? path.length - 1 - k : k];
+					const dx = other[0] - x, dy = other[1] - y, d = Math.hypot(dx, dy);
+					if (d > 1) {
+						fx += dx / d;
+						fy += dy / d;
+					}
+				}
+				const pull = Math.hypot(fx, fy) || 1;
+				return [x + fx / pull * Math.min(step, pull), y + fy / pull * Math.min(step, pull)];
+			})).forEach((path, i) => {
+				paths[i] = path;
+			});
+		}
+		return paths.map((path) => this.chaikin(path));
+	}
+	static compatibility([a, b], [c, d]) {
+		const px = b[0] - a[0], py = b[1] - a[1], qx = d[0] - c[0], qy = d[1] - c[1];
+		const lp = Math.hypot(px, py) || 1, lq = Math.hypot(qx, qy) || 1;
+		const dot = (px * qx + py * qy) / (lp * lq), mean = (lp + lq) / 2;
+		const scale = 2 / (mean / Math.min(lp, lq) + Math.max(lp, lq) / mean);
+		const mid = Math.hypot((a[0] + b[0] - c[0] - d[0]) / 2, (a[1] + b[1] - c[1] - d[1]) / 2);
+		return {
+			value: Math.abs(dot) * scale * (mean / (mean + mid)),
+			flip: dot < 0
+		};
+	}
+};
+export { FlowGeometry };

package/dist/charts/geoflows/FlowMap.js

@@ -0,0 +1,104 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { FlowGeometry } from "./FlowGeometry.js";
+import { GeoFlowProjection } from "./GeoFlowFrame.js";
+import { GeoFlowChart } from "./GeoFlowChart.js";
+import { GeoFlowSample } from "./GeoFlowSample.js";
+import { GeoFlowRoute, GeoLinkChart } from "./GeoLinkChart.js";
+import { scaleSqrt } from "d3";
+// src/charts/geoflows/FlowMap.ts
+/** How a flow's size is drawn: a constant line, or a band that narrows towards its destination. */
+var FlowMapShape = /* @__PURE__ */ function(FlowMapShape) {
+	FlowMapShape["Line"] = "line";
+	FlowMapShape["Tapered"] = "tapered";
+	return FlowMapShape;
+}({});
+/** Show how much moves between places: flow width encodes volume and the taper or head shows direction. */
+var FlowMap = class extends GeoLinkChart {
+	static meta = {
+		id: "flow-map",
+		name: "Flow map",
+		family: ChartFamily.Geospatial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Draws origin-destination volumes on a map, with band width proportional to the amount moved.",
+		tags: [
+			"origin-destination",
+			"trade",
+			"movement"
+		],
+		sample: (seed) => GeoFlowSample.flows(seed, 16),
+		variants: {
+			projection: [
+				GeoFlowProjection.NaturalEarth,
+				GeoFlowProjection.EqualEarth,
+				GeoFlowProjection.Mercator,
+				GeoFlowProjection.Orthographic,
+				GeoFlowProjection.AzimuthalEqualArea
+			],
+			route: [
+				GeoFlowRoute.Arc,
+				GeoFlowRoute.Geodesic,
+				GeoFlowRoute.Straight,
+				GeoFlowRoute.Bundled
+			],
+			shape: ["line", "tapered"],
+			arrows: [false, true]
+		},
+		valid: (v) => !(v.shape === "tapered" && (v.route === GeoFlowRoute.Geodesic || v.arrows))
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			route: GeoFlowRoute.Arc,
+			shape: "line",
+			arrows: false
+		};
+	}
+	track(frame, link, bundles) {
+		const { route } = this.options;
+		if (route === GeoFlowRoute.Bundled) return bundles.get(link.id) ?? null;
+		if (route !== GeoFlowRoute.Geodesic) return this.screenRoute(frame, link, route);
+		return this.runs(frame, FlowGeometry.geodesic(link.from, link.to))[0] ?? null;
+	}
+	plotGeo(ctx, frame) {
+		const { route, shape, arrows } = this.options;
+		const links = [...this.links].sort((a, b) => b.value - a.value);
+		const most = Math.max(4, Math.min(ctx.plot.width, ctx.plot.height) / (shape === "tapered" ? 20 : 32));
+		const width = this.widthScale(links, most);
+		const reach = GeoFlowChart.peakOf(this.stops, (stop) => stop.inflow + stop.outflow);
+		const area = scaleSqrt([0, reach], [0, 7]);
+		const radius = (stop) => Math.max(4, area(stop.inflow + stop.outflow));
+		const bundles = route === GeoFlowRoute.Bundled ? this.bundled(frame, links) : /* @__PURE__ */ new Map();
+		const shown = links.flatMap((link) => {
+			const track = this.track(frame, link, bundles);
+			if (!track || track.length < 2) return [];
+			const w = width(link.value), tapered = shape === "tapered";
+			const trimmed = FlowGeometry.trim(track, 4, arrows ? w * 1.6 + 6 : 4);
+			return [{
+				link,
+				d: route === GeoFlowRoute.Geodesic && !arrows ? frame.line(FlowGeometry.geodesic(link.from, link.to)) : tapered ? FlowGeometry.ribbon(trimmed, (t) => w * (1 - t * .82)) : FlowGeometry.polyline(trimmed),
+				tapered,
+				w,
+				track
+			}];
+		});
+		const flows = ctx.marks("flows", "path", shown, (d) => d.link.id).attr("stroke-linecap", "round").attr("stroke-linejoin", "round").attr("opacity", .82).attr("fill", (d) => d.tapered ? this.tint(ctx, d.link) : "none").attr("stroke", (d) => d.tapered ? ctx.theme.surface : this.tint(ctx, d.link)).attr("stroke-width", (d) => d.tapered ? .75 : d.w);
+		ctx.set(flows, { d: (d) => d.d }, { d: (d) => d.d });
+		if (shape === "line") ctx.drawOn(flows);
+		ctx.hover(flows, (d) => ({
+			title: `${d.link.source} → ${d.link.target}`,
+			color: this.tint(ctx, d.link),
+			rows: [["Flow", d.link.value]]
+		}));
+		const heads = shape === "line" && arrows ? shown : [];
+		const tips = ctx.marks("heads", "path", heads, (d) => d.link.id).attr("fill", (d) => this.tint(ctx, d.link));
+		ctx.set(tips, { d: (d) => {
+			const end = d.track.length - 1;
+			return FlowGeometry.arrow(d.track[Math.max(1, end - 1)], d.track[Math.max(0, end - 3)], d.w * 1.6 + 7);
+		} });
+		this.stopDots(ctx, frame, this.stops, radius);
+		this.labels(ctx, this.stopLabels(frame, this.stops, radius), "labels", 6);
+		this.keyWidths(ctx, "Flow", width, GeoFlowChart.peakOf(links, (link) => link.value));
+	}
+};
+export { FlowMap, FlowMapShape };

package/dist/charts/geoflows/GeoBeeswarm.js

@@ -0,0 +1,161 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { GeoFlowFit } from "./GeoFlowChart.js";
+import { GeoFlowProjection } from "./GeoFlowFrame.js";
+import { GeoFlowSample } from "./GeoFlowSample.js";
+import { GeoPointChart } from "./GeoPointChart.js";
+import { forceCollide, forceSimulation, forceX, forceY, group, mean, scaleSqrt } from "d3";
+// src/charts/geoflows/GeoBeeswarm.ts
+/** How crowded dots are spread out. */
+var GeoBeeswarmLayout = /* @__PURE__ */ function(GeoBeeswarmLayout) {
+	GeoBeeswarmLayout["Force"] = "force";
+	GeoBeeswarmLayout["Spiral"] = "spiral";
+	GeoBeeswarmLayout["Hex"] = "hex-grid";
+	GeoBeeswarmLayout["Region"] = "region-cluster";
+	return GeoBeeswarmLayout;
+}({});
+/** What a dot's area shows. */
+var GeoBeeswarmSize = /* @__PURE__ */ function(GeoBeeswarmSize) {
+	GeoBeeswarmSize["Value"] = "value";
+	GeoBeeswarmSize["Uniform"] = "uniform";
+	return GeoBeeswarmSize;
+}({});
+/** Show every place even where they crowd: dots move just far enough apart to stop overlapping, like a Dorling map of points. */
+var GeoBeeswarm = class extends GeoPointChart {
+	static meta = {
+		id: "geo-beeswarm",
+		name: "Geographic beeswarm",
+		family: ChartFamily.Geospatial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Nudges point symbols apart so none overlap, keeping each close to its true location on the map.",
+		tags: [
+			"dorling",
+			"collision",
+			"dot map"
+		],
+		sample: (seed) => GeoFlowSample.places(seed),
+		variants: {
+			projection: [
+				GeoFlowProjection.NaturalEarth,
+				GeoFlowProjection.EqualEarth,
+				GeoFlowProjection.Orthographic,
+				GeoFlowProjection.Mercator
+			],
+			layout: [
+				"force",
+				"spiral",
+				"hex-grid",
+				"region-cluster"
+			],
+			size: ["value", "uniform"],
+			leaders: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			fit: GeoFlowFit.World,
+			layout: "force",
+			size: "value",
+			leaders: false
+		};
+	}
+	categorical() {
+		return new Set(this.places.map((place) => place.series)).size > 1;
+	}
+	simulate(bees, target) {
+		forceSimulation(bees).stop().force("x", forceX((bee) => target(bee)[0]).strength(.28)).force("y", forceY((bee) => target(bee)[1]).strength(.28)).force("collide", forceCollide((bee) => bee.r + 1).iterations(2)).tick(100);
+	}
+	spiral(bees) {
+		const placed = [];
+		for (const bee of [...bees].sort((a, b) => b.r - a.r)) {
+			for (let turn = 0; turn < 900; turn += .35) {
+				const reach = turn * .55;
+				bee.x = bee.home[0] + reach * Math.cos(turn);
+				bee.y = bee.home[1] + reach * Math.sin(turn);
+				if (placed.every((other) => Math.hypot(bee.x - other.x, bee.y - other.y) >= bee.r + other.r + 1)) break;
+			}
+			placed.push(bee);
+		}
+	}
+	/** Snaps each dot to the nearest free cell of a hexagonal lattice, largest first. */
+	hex(bees) {
+		const pitch = Math.max(...bees.map((bee) => bee.r)) * 2 + 1.5, rowHeight = pitch * .866;
+		const taken = /* @__PURE__ */ new Set();
+		for (const bee of [...bees].sort((a, b) => b.r - a.r)) {
+			const row = Math.round(bee.home[1] / rowHeight), column = Math.round(bee.home[0] / pitch - row % 2 / 2);
+			let best = null;
+			for (let reach = 0; reach < 30 && !best; reach++) for (let j = row - reach; j <= row + reach; j++) for (let i = column - reach; i <= column + reach; i++) {
+				const key = `${i}/${j}`;
+				if (taken.has(key)) continue;
+				const x = (i + (j & 1) / 2) * pitch, y = j * rowHeight, d = Math.hypot(x - bee.home[0], y - bee.home[1]);
+				if (!best || d < best.d) best = {
+					key,
+					x,
+					y,
+					d
+				};
+			}
+			if (best) {
+				taken.add(best.key);
+				bee.x = best.x;
+				bee.y = best.y;
+			}
+		}
+	}
+	plotGeo(ctx, frame) {
+		const { layout, size, leaders, series } = this.options;
+		const crowd = this.places.length || 1;
+		const unit = Math.sqrt(ctx.plot.width * ctx.plot.height * .2 / (crowd * Math.PI));
+		const top = Math.max(1, ...this.places.map((place) => place.value));
+		const area = scaleSqrt([0, top], [0, unit * 1.5]);
+		const floor = Math.min(4, unit * .7);
+		const bees = this.places.flatMap((place) => {
+			const home = frame.at(place.place);
+			const r = size === "value" ? Math.max(floor, area(Math.max(0, place.value))) : Math.max(floor, unit * .85);
+			return home ? [{
+				place,
+				home,
+				r,
+				x: home[0],
+				y: home[1]
+			}] : [];
+		});
+		if (layout === "force") this.simulate(bees, (bee) => bee.home);
+		if (layout === "spiral") this.spiral(bees);
+		if (layout === "hex-grid") this.hex(bees);
+		if (layout === "region-cluster") {
+			const centres = new Map([...group(bees, (bee) => bee.place.series)].map(([name, rows]) => [name, [mean(rows, (bee) => bee.home[0]), mean(rows, (bee) => bee.home[1])]]));
+			this.simulate(bees, (bee) => centres.get(bee.place.series));
+		}
+		for (const bee of bees) {
+			bee.x = Math.max(bee.r, Math.min(ctx.plot.width - bee.r, bee.x));
+			bee.y = Math.max(bee.r, Math.min(ctx.plot.height - bee.r, bee.y));
+		}
+		const tint = (bee) => ctx.palette.color(bee.place.series || String(series));
+		ctx.marks("leaders", "path", leaders ? bees : [], (d) => d.place.id).attr("d", (d) => `M${d.home[0].toFixed(1)},${d.home[1].toFixed(1)}L${d.x.toFixed(1)},${d.y.toFixed(1)}`).attr("stroke", ctx.theme.inkMuted).attr("stroke-width", .75).attr("fill", "none").attr("pointer-events", "none");
+		const dots = ctx.marks("bees", "circle", bees, (d) => d.place.id).attr("fill", tint).attr("stroke", ctx.theme.surface).attr("stroke-width", 1);
+		ctx.set(dots, {
+			cx: (d) => d.x,
+			cy: (d) => d.y,
+			r: (d) => d.r
+		}, {
+			cx: (d) => d.home[0],
+			cy: (d) => d.home[1],
+			r: 0
+		}, 3);
+		ctx.hover(dots, (d) => ({
+			title: d.place.name,
+			color: tint(d),
+			rows: [["Value", d.place.value]]
+		}));
+		this.labels(ctx, [...bees].sort((a, b) => b.r - a.r).map((bee) => ({
+			text: bee.place.name,
+			x: bee.x,
+			y: bee.y,
+			gap: bee.r
+		})), "labels", 4);
+		if (size === "value") this.keyCircles(ctx, "Value", (value) => area(value), top);
+	}
+};
+export { GeoBeeswarm, GeoBeeswarmLayout, GeoBeeswarmSize };