@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/threenetwork/Parallel3DCoordinates.js

@@ -0,0 +1,155 @@
+import { Chart3D } from "../../core/Chart3D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { NetworkMarks3D } from "./NetworkMarks3D.js";
+import { Path3D } from "./Path3D.js";
+import { ascending, extent, scaleLinear } from "d3";
+import { CylinderGeometry, Quaternion, SphereGeometry, Vector3 } from "three";
+// src/charts/threenetwork/Parallel3DCoordinates.ts
+/** How the axes stand in space. */
+var ParallelFrame3D = /* @__PURE__ */ function(ParallelFrame3D) {
+	ParallelFrame3D["Lanes"] = "lanes";
+	ParallelFrame3D["Ring"] = "ring";
+	ParallelFrame3D["Radar"] = "radar";
+	ParallelFrame3D["Helix"] = "helix";
+	return ParallelFrame3D;
+}({});
+var ParallelCurve3D = /* @__PURE__ */ function(ParallelCurve3D) {
+	ParallelCurve3D["Smooth"] = "smooth";
+	ParallelCurve3D["Straight"] = "straight";
+	return ParallelCurve3D;
+}({});
+var ParallelScale3D = /* @__PURE__ */ function(ParallelScale3D) {
+	ParallelScale3D["Linear"] = "linear";
+	ParallelScale3D["Rank"] = "rank";
+	return ParallelScale3D;
+}({});
+var UP = new Vector3(0, 1, 0);
+var TAU = Math.PI * 2;
+/** Parallel coordinates with depth: lanes or rings split groups apart, so many-column rows do not overplot. */
+var Parallel3DCoordinates = class extends Chart3D {
+	static meta = {
+		id: "parallel-coordinates-3d",
+		name: "3D parallel coordinates",
+		family: ChartFamily.Relationship,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Runs each row as a line across many numeric axes, using depth to pull groups apart and reduce overplotting.",
+		tags: [
+			"parallel coordinates",
+			"multivariate",
+			"radar"
+		],
+		sample: (seed) => SampleData.points(seed, 36, 3).map(({ x, y, size, group }) => ({
+			group,
+			x,
+			y,
+			size,
+			ratio: +(y / x).toFixed(3),
+			spread: +(y - x).toFixed(2)
+		})),
+		variants: {
+			frame: Object.values(ParallelFrame3D),
+			curve: Object.values(ParallelCurve3D),
+			scale: Object.values(ParallelScale3D),
+			dots: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			group: "group",
+			frame: "lanes",
+			curve: "smooth",
+			scale: "linear",
+			dots: true,
+			distance: 4.5
+		};
+	}
+	columns(rows) {
+		const { dimensions, group } = this.options;
+		return dimensions ?? Object.keys(rows[0] ?? {}).filter((key) => key !== group && typeof rows[0][key] === "number");
+	}
+	/** Normalised 0..1 reading of every row on one column. */
+	reader(rows, column) {
+		if (this.options.scale === "rank") {
+			const sorted = rows.map((row) => +row[column]).sort(ascending);
+			return (row) => sorted.length > 1 ? sorted.indexOf(+row[column]) / (sorted.length - 1) : .5;
+		}
+		const [low = 0, high = 1] = extent(rows, (row) => +row[column]);
+		const scale = scaleLinear([low, high === low ? low + 1 : high], [0, 1]);
+		return (row) => scale(+row[column]);
+	}
+	/** World position of reading `v` on axis `a` of `count`, in lane `lane` of `lanes`. */
+	seat(a, count, v, lane, lanes) {
+		const f = count > 1 ? a / (count - 1) : .5, angle = a / count * TAU;
+		const offset = lanes > 1 ? lane / (lanes - 1) - .5 : 0;
+		switch (this.options.frame) {
+			case "ring": return new Vector3(Math.cos(angle) * .85, v * 1.6 - .8, Math.sin(angle) * .85);
+			case "radar": {
+				const reach = .14 + v * .84;
+				return new Vector3(Math.cos(angle) * reach, offset * 1.5, Math.sin(angle) * reach);
+			}
+			case "helix": {
+				const turn = f * TAU * 1.25, reach = .25 + v * .72;
+				return new Vector3(Math.cos(turn) * reach, f * 1.6 - .8, Math.sin(turn) * reach);
+			}
+			default: return new Vector3(f * 2 - 1, v * 1.2 - .6, offset * 1.5);
+		}
+	}
+	build(ctx) {
+		const { data, group, frame, curve, dots } = this.options;
+		const rows = data ?? [];
+		const columns = this.columns(rows);
+		const clean = rows.filter((row) => columns.every((column) => row[column] != null && Number.isFinite(+row[column])));
+		if (!clean.length || columns.length < 2) return;
+		const marks = new NetworkMarks3D(ctx);
+		const groups = [...new Set(clean.map((row) => String(row[group] ?? "All")))];
+		const readers = columns.map((column) => this.reader(clean, column));
+		const laneOf = (row) => groups.indexOf(String(row[group] ?? "All"));
+		const closed = frame === "ring" || frame === "radar";
+		const separate = frame === "lanes" || frame === "radar";
+		const lanes = separate ? groups.length : 1;
+		const rails = columns.flatMap((_, a) => Array.from({ length: lanes }, (_, lane) => {
+			const from = this.seat(a, columns.length, 0, lane, lanes), to = this.seat(a, columns.length, 1, lane, lanes);
+			const direction = to.clone().sub(from);
+			return {
+				at: from.clone().add(to).multiplyScalar(.5),
+				size: new Vector3(.006, direction.length(), .006),
+				color: ctx.theme.axis,
+				spin: new Quaternion().setFromUnitVectors(UP, direction.normalize())
+			};
+		}));
+		marks.instances(new CylinderGeometry(1, 1, 1, 8), rails, { shadow: false });
+		const seats = clean.map((row) => readers.map((read, a) => this.seat(a, columns.length, read(row), separate ? laneOf(row) : 0, lanes)));
+		marks.batch(clean.map((row, r) => {
+			const points = closed ? [...seats[r], seats[r][0]] : seats[r];
+			const path = curve === "smooth" ? Path3D.smooth(closed ? seats[r] : points, columns.length * 10, closed) : points;
+			return {
+				rings: Path3D.tube(path, .0055, 5),
+				color: marks.faded(ctx.palette.color(String(row[group] ?? "All")), .15)
+			};
+		}), {}, {
+			opacity: .82,
+			roughness: .7
+		});
+		if (dots) marks.instances(new SphereGeometry(1, 12, 8), clean.flatMap((row, r) => columns.map((_, a) => ({
+			at: seats[r][a],
+			size: .017,
+			color: ctx.palette.color(String(row[group] ?? "All")),
+			tip: {
+				title: String(row[group] ?? ""),
+				color: ctx.palette.color(String(row[group] ?? "All")),
+				rows: columns.map((name) => [name, +row[name]])
+			}
+		}))), { roughness: .4 });
+		columns.forEach((column, a) => {
+			const point = this.seat(a, columns.length, 1, 0, lanes);
+			ctx.label(column, [
+				point.x,
+				point.y + .08,
+				point.z
+			], "secondary", 10);
+		});
+	}
+};
+export { Parallel3DCoordinates, ParallelCurve3D, ParallelFrame3D, ParallelScale3D };

package/dist/charts/threenetwork/Path3D.js

@@ -0,0 +1,45 @@
+import { CatmullRomCurve3, CubicBezierCurve3, QuadraticBezierCurve3, Vector3 } from "three";
+// src/charts/threenetwork/Path3D.ts
+var TAU = Math.PI * 2;
+/** Polyline builders for links, and the tube cross-sections that skin them. */
+var Path3D = class Path3D {
+	static quadratic(a, control, b, segments = 20) {
+		return new QuadraticBezierCurve3(a, control, b).getPoints(segments);
+	}
+	static cubic(a, c1, c2, b, segments = 24) {
+		return new CubicBezierCurve3(a, c1, c2, b).getPoints(segments);
+	}
+	static smooth(points, segments = points.length * 6, closed = false) {
+		return points.length < 3 ? points : new CatmullRomCurve3(points, closed, "centripetal").getPoints(segments);
+	}
+	/** Arc along the sphere through `a` and `b`, centred on the origin, bulging `lift` above its radius mid-way. */
+	static sphereArc(a, b, lift = 0, segments = 24) {
+		const radius = a.length(), from = a.clone().normalize(), to = b.clone().normalize();
+		const angle = from.angleTo(to), sin = Math.sin(angle) || 1;
+		return Array.from({ length: segments + 1 }, (_, i) => {
+			const t = i / segments;
+			return from.clone().multiplyScalar(Math.sin((1 - t) * angle) / sin).addScaledVector(to, Math.sin(t * angle) / sin).multiplyScalar(radius * (1 + lift * Math.sin(Math.PI * t)));
+		});
+	}
+	/** Circular cross-sections carried along `points` with parallel transport, so tubes never twist. */
+	static tube(points, radius, sides = 6) {
+		const tangent = new Vector3(), side = new Vector3();
+		let normal = null;
+		return points.map((point, i) => {
+			tangent.subVectors(points[Math.min(i + 1, points.length - 1)], points[Math.max(i - 1, 0)]).normalize();
+			normal ??= Path3D.perpendicular(tangent);
+			normal.addScaledVector(tangent, -normal.dot(tangent)).normalize();
+			side.crossVectors(tangent, normal);
+			const r = typeof radius === "number" ? radius : radius(i / (points.length - 1));
+			return Array.from({ length: sides }, (_, j) => {
+				const angle = j / sides * TAU;
+				return point.clone().addScaledVector(normal, Math.cos(angle) * r).addScaledVector(side, Math.sin(angle) * r);
+			});
+		});
+	}
+	static perpendicular(direction) {
+		const axis = Math.abs(direction.y) < .9 ? new Vector3(0, 1, 0) : new Vector3(1, 0, 0);
+		return new Vector3().crossVectors(direction, axis).normalize();
+	}
+};
+export { Path3D };

package/dist/charts/threenetwork/RingSegment3D.js

@@ -0,0 +1,17 @@
+// src/charts/threenetwork/RingSegment3D.ts
+/** Rectangular-section loft rings for an annular wedge, shared by the sunburst and chord rims. */
+var RingSegment3D = class {
+	static rings(surface, a0, a1, r0, r1, bottom, top) {
+		const steps = Math.max(2, Math.ceil(Math.abs(a1 - a0) * 16));
+		return Array.from({ length: steps + 1 }, (_, i) => {
+			const angle = a0 + (a1 - a0) * i / steps;
+			return [
+				surface(angle, r0, bottom),
+				surface(angle, r1, bottom),
+				surface(angle, r1, top),
+				surface(angle, r0, top)
+			];
+		});
+	}
+};
+export { RingSegment3D };

package/dist/charts/threenetwork/Sankey3DChart.js

@@ -0,0 +1,182 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { Graph3DBase } from "./Graph3DBase.js";
+import { LabelSpacer3D } from "./LabelSpacer3D.js";
+import { NetworkMarks3D } from "./NetworkMarks3D.js";
+import { Path3D } from "./Path3D.js";
+import { BoxGeometry, Vector3 } from "three";
+import { sankey, sankeyCenter, sankeyJustify, sankeyLeft, sankeyRight } from "d3-sankey";
+// src/charts/threenetwork/Sankey3DChart.ts
+var SankeyAlign3D = /* @__PURE__ */ function(SankeyAlign3D) {
+	SankeyAlign3D["Justify"] = "justify";
+	SankeyAlign3D["Left"] = "left";
+	SankeyAlign3D["Right"] = "right";
+	SankeyAlign3D["Center"] = "center";
+	return SankeyAlign3D;
+}({});
+/** The surface the flow runs on. */
+var SankeyStage3D = /* @__PURE__ */ function(SankeyStage3D) {
+	SankeyStage3D["Wall"] = "wall";
+	SankeyStage3D["Floor"] = "floor";
+	SankeyStage3D["Arch"] = "arch";
+	SankeyStage3D["Cascade"] = "cascade";
+	return SankeyStage3D;
+}({});
+var SankeyLink3D = /* @__PURE__ */ function(SankeyLink3D) {
+	SankeyLink3D["Ribbon"] = "ribbon";
+	SankeyLink3D["Tube"] = "tube";
+	return SankeyLink3D;
+}({});
+var SankeyOrder3D = /* @__PURE__ */ function(SankeyOrder3D) {
+	SankeyOrder3D["Relaxed"] = "relaxed";
+	SankeyOrder3D["Input"] = "input";
+	return SankeyOrder3D;
+}({});
+var ALIGN = {
+	["justify"]: sankeyJustify,
+	["left"]: sankeyLeft,
+	["right"]: sankeyRight,
+	["center"]: sankeyCenter
+};
+var SLAB = .05;
+var RIBBON = .012;
+/** Flow diagram on a surface: stood up as a wall, laid on a floor, arched over it or stepped down a cascade. */
+var Sankey3DChart = class extends Graph3DBase {
+	static meta = {
+		id: "sankey-3d",
+		name: "3D Sankey",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Three,
+		shape: DataShape.Graph,
+		description: "Traces quantities through stages with ribbons as wide as the flow, keeping totals conserved at every node.",
+		tags: [
+			"sankey",
+			"alluvial",
+			"flow"
+		],
+		sample: (seed) => {
+			const { nodes, links } = SampleData.flow(seed, 4, 4);
+			const kept = links.filter((link, i) => i % 5 !== 2 && link.source !== "L1-1" && link.target !== "L2-3");
+			return {
+				nodes: nodes.filter(({ id }) => kept.some((link) => link.source === id || link.target === id)),
+				links: kept
+			};
+		},
+		variants: {
+			stage: Object.values(SankeyStage3D),
+			align: Object.values(SankeyAlign3D),
+			linkShape: Object.values(SankeyLink3D),
+			order: Object.values(SankeyOrder3D)
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			stage: "wall",
+			align: "justify",
+			linkShape: "ribbon",
+			order: "relaxed",
+			azimuth: 26,
+			elevation: 20,
+			distance: 4.2
+		};
+	}
+	/** Stage coordinates: `u` along the flow, `v` across it, `h` lift off the surface. */
+	point(u, v, h = 0) {
+		const x = u * 2 - 1;
+		switch (this.options.stage) {
+			case "wall": return new Vector3(x, .82 - v * 1.64, h);
+			case "cascade": return new Vector3(x, .62 - u * 1.2 + h, v * 1.7 - .85);
+			default: return new Vector3(x, -.4 + h, v * 1.7 - .85);
+		}
+	}
+	flow(link) {
+		const { stage, linkShape } = this.options;
+		const source = link.source, target = link.target;
+		const half = (link.width ?? 0) / 2, steps = 28;
+		const center = Array.from({ length: 29 }, (_, i) => {
+			const t = i / steps, ease = t * t * (3 - 2 * t);
+			return [
+				source.x1 + (target.x0 - source.x1) * t,
+				link.y0 + (link.y1 - link.y0) * ease,
+				stage === "arch" ? Math.sin(Math.PI * t) * .34 : 0
+			];
+		});
+		if (linkShape === "tube") return Path3D.tube(center.map(([u, v, h]) => this.point(u, v, h)), Math.max(.004, Math.sqrt(half / Math.PI) * .24), 8);
+		return center.map(([u, v, h]) => [
+			this.point(u, v - half, h - RIBBON),
+			this.point(u, v + half, h - RIBBON),
+			this.point(u, v + half, h + RIBBON),
+			this.point(u, v - half, h + RIBBON)
+		]);
+	}
+	build(ctx) {
+		const { nodes, links } = this.model();
+		const { align, order, linkShape, stage } = this.options;
+		const kept = this.acyclic(nodes, links);
+		if (!kept.length) return;
+		const marks = new NetworkMarks3D(ctx);
+		const layout = sankey().nodeId((node) => node.id).nodeAlign(ALIGN[align]).nodeWidth(.024).nodePadding(.04).extent([[0, 0], [1, 1]]);
+		if (order === "input") layout.nodeSort(null);
+		const graph = layout({
+			nodes: nodes.map(({ id, group }) => ({
+				id,
+				group
+			})),
+			links: kept.map((link) => ({
+				source: link.source.id,
+				target: link.target.id,
+				value: link.value
+			}))
+		});
+		const paint = (node) => marks.faded(ctx.palette.color(node.group), .25);
+		const flows = graph.links.map((link) => {
+			const source = link.source, target = link.target;
+			return {
+				rings: this.flow(link),
+				color: paint(source),
+				end: paint(target),
+				tip: {
+					title: `${source.id} → ${target.id}`,
+					rows: [["Flow", link.value]]
+				}
+			};
+		});
+		if (flows.length <= 400) marks.lofts(flows, { sharp: linkShape === "ribbon" }, {
+			opacity: .86,
+			shadow: false
+		});
+		else marks.batch(flows, { sharp: linkShape === "ribbon" }, { opacity: .86 });
+		const upright = stage === "wall";
+		marks.instances(new BoxGeometry(1, 1, 1), graph.nodes.map((node) => {
+			const u = (node.x0 + node.x1) / 2, v = (node.y0 + node.y1) / 2, along = (node.x1 - node.x0) * 2, across = Math.max(node.y1 - node.y0, .004) * (upright ? 1.64 : 1.7);
+			return {
+				at: this.point(u, v),
+				size: upright ? new Vector3(along, across, SLAB) : new Vector3(along, SLAB, across),
+				color: ctx.palette.color(node.group),
+				tip: {
+					title: node.id,
+					color: ctx.palette.color(node.group),
+					rows: [["Throughput", node.value ?? 0]]
+				}
+			};
+		}), { roughness: .45 });
+		this.labelEnds(ctx, graph.nodes);
+	}
+	/** Names the sources and sinks; the interior is read by hover. */
+	labelEnds(ctx, nodes) {
+		const spacer = new LabelSpacer3D(this.options, this.size.height);
+		const last = Math.max(...nodes.map((node) => node.x1));
+		for (const node of nodes) {
+			const sink = node.x1 === last;
+			if (!sink && node.x0 !== 0) continue;
+			const point = this.point(sink ? 1.04 : -.04, (node.y0 + node.y1) / 2), anchor = sink ? 0 : 1;
+			if (spacer.keep(point, node.id, 10, anchor)) ctx.label(node.id, [
+				point.x,
+				point.y,
+				point.z
+			], "secondary", 10).center.x = anchor;
+		}
+	}
+};
+export { Sankey3DChart, SankeyAlign3D, SankeyLink3D, SankeyOrder3D, SankeyStage3D };

package/dist/charts/threenetwork/Sphere3DGraph.js

@@ -0,0 +1,125 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { NodeSizing3D } from "./enums.js";
+import { ForceLayout3D } from "./ForceLayout3D.js";
+import { Graph3DBase } from "./Graph3DBase.js";
+import { NetworkMarks3D } from "./NetworkMarks3D.js";
+import { Path3D } from "./Path3D.js";
+import { Mesh, MeshStandardMaterial, SphereGeometry, Vector3 } from "three";
+// src/charts/threenetwork/Sphere3DGraph.ts
+var SphereArrangement3D = /* @__PURE__ */ function(SphereArrangement3D) {
+	SphereArrangement3D["Caps"] = "caps";
+	SphereArrangement3D["Even"] = "even";
+	SphereArrangement3D["Bands"] = "bands";
+	SphereArrangement3D["Lunes"] = "lunes";
+	return SphereArrangement3D;
+}({});
+var SphereRoute3D = /* @__PURE__ */ function(SphereRoute3D) {
+	SphereRoute3D["Raised"] = "raised";
+	SphereRoute3D["Surface"] = "surface";
+	SphereRoute3D["Chord"] = "chord";
+	return SphereRoute3D;
+}({});
+var SphereShell3D = /* @__PURE__ */ function(SphereShell3D) {
+	SphereShell3D["Glass"] = "glass";
+	SphereShell3D["Graticule"] = "graticule";
+	SphereShell3D["None"] = "none";
+	return SphereShell3D;
+}({});
+var RADIUS = .84;
+var TAU = Math.PI * 2;
+/** Network on a globe: a circular layout with a second dimension, so more nodes fit without hairballs. */
+var Sphere3DGraph = class extends Graph3DBase {
+	static meta = {
+		id: "sphere-graph-3d",
+		name: "Spherical graph",
+		family: ChartFamily.Network,
+		dimension: Dimension.Three,
+		shape: DataShape.Graph,
+		description: "Seats every node on a sphere and routes links over or through it, keeping clusters in fixed regions.",
+		tags: [
+			"network",
+			"globe",
+			"spherical layout",
+			"great circle"
+		],
+		sample: (seed) => SampleData.graph(seed, 72, 4),
+		variants: {
+			arrangement: Object.values(SphereArrangement3D),
+			route: Object.values(SphereRoute3D),
+			shell: Object.values(SphereShell3D),
+			sizeBy: [NodeSizing3D.Degree, NodeSizing3D.Value]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			arrangement: "caps",
+			route: "raised",
+			shell: "glass",
+			distance: 4.3
+		};
+	}
+	/** Seats a group's members within a latitude and longitude window. */
+	seat(index, count, group, groups) {
+		const fraction = (index + .5) / count, golden = index * Math.PI * (3 - Math.sqrt(5));
+		const spherical = (polar, azimuth) => new Vector3(Math.sin(polar) * Math.cos(azimuth), Math.cos(polar), Math.sin(polar) * Math.sin(azimuth));
+		switch (this.options.arrangement) {
+			case "bands": {
+				const low = Math.acos(1 - 2 * group / groups);
+				return spherical(low + (Math.acos(1 - 2 * (group + 1) / groups) - low) * (.14 + .72 * fraction), golden);
+			}
+			case "lunes": return spherical(.3 + (Math.PI - .6) * fraction, (group + .14 + .72 * (index * .618 % 1)) / groups * TAU);
+			case "caps": {
+				const pole = ForceLayout3D.sphere(group, groups);
+				const side = new Vector3(0, 1, 0).cross(pole).normalize();
+				if (!side.lengthSq()) side.set(1, 0, 0);
+				const across = new Vector3().crossVectors(pole, side), tilt = Math.sqrt(fraction) * Math.min(1.05, 2.3 / Math.sqrt(groups));
+				return pole.multiplyScalar(Math.cos(tilt)).addScaledVector(side, Math.sin(tilt) * Math.cos(golden)).addScaledVector(across, Math.sin(tilt) * Math.sin(golden));
+			}
+			default: return new Vector3();
+		}
+	}
+	drawShell(ctx, marks) {
+		const { shell } = this.options;
+		if (shell === "glass") ctx.root.add(new Mesh(new SphereGeometry(RADIUS * .985, 64, 40), new MeshStandardMaterial({
+			color: ctx.theme.grid,
+			roughness: .9,
+			transparent: true,
+			opacity: .55,
+			depthWrite: true
+		})));
+		if (shell !== "graticule") return;
+		const points = [], steps = 72;
+		const point = (polar, azimuth) => new Vector3(Math.sin(polar) * Math.cos(azimuth), Math.cos(polar), Math.sin(polar) * Math.sin(azimuth)).multiplyScalar(RADIUS);
+		for (let i = 0; i < steps; i++) {
+			const a = i / steps * TAU, b = (i + 1) / steps * TAU;
+			for (let lat = 1; lat < 6; lat++) points.push(point(lat / 6 * Math.PI, a), point(lat / 6 * Math.PI, b));
+			for (let lon = 0; lon < 6; lon++) points.push(point(a / 2, lon / 6 * TAU), point(b / 2, lon / 6 * TAU), point(a / 2, lon / 6 * TAU + Math.PI), point(b / 2, lon / 6 * TAU + Math.PI));
+		}
+		marks.lines(points);
+	}
+	build(ctx) {
+		const { nodes, links, groups } = this.model();
+		if (!nodes.length) return;
+		const { arrangement, route: routing } = this.options;
+		const marks = new NetworkMarks3D(ctx);
+		const seats = /* @__PURE__ */ new Map();
+		if (arrangement === "even") [...nodes].sort((a, b) => a.group.localeCompare(b.group)).forEach((node, i) => seats.set(node, ForceLayout3D.sphere(i, nodes.length).multiplyScalar(RADIUS)));
+		else groups.forEach((group, g) => {
+			const members = nodes.filter((node) => node.group === group);
+			members.forEach((node, i) => seats.set(node, this.seat(i, members.length, g, groups.length).multiplyScalar(RADIUS)));
+		});
+		const at = (node) => seats.get(node);
+		const route = (link) => {
+			const a = at(link.source), b = at(link.target);
+			if (routing === "chord") return [a, b];
+			return Path3D.sphereArc(a, b, routing === "raised" ? .05 + a.angleTo(b) * .055 : .012, 22);
+		};
+		this.drawShell(ctx, marks);
+		this.drawLinks(ctx, marks, links, route);
+		this.drawNodes(ctx, marks, nodes, at);
+		this.labelHubs(ctx, nodes, at, 3);
+	}
+};
+export { Sphere3DGraph, SphereArrangement3D, SphereRoute3D, SphereShell3D };

package/dist/charts/threenetwork/Spiral3DTimeline.js

@@ -0,0 +1,159 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { NetworkMarks3D } from "./NetworkMarks3D.js";
+import { Path3D } from "./Path3D.js";
+import { DAY, Temporal3DBase } from "./Temporal3DBase.js";
+import { rollup, sum } from "d3";
+import { CylinderGeometry, SphereGeometry, Vector3 } from "three";
+// src/charts/threenetwork/Spiral3DTimeline.ts
+/** The shape time winds around. */
+var SpiralForm3D = /* @__PURE__ */ function(SpiralForm3D) {
+	SpiralForm3D["Helix"] = "helix";
+	SpiralForm3D["Cone"] = "cone";
+	SpiralForm3D["Disc"] = "disc";
+	SpiralForm3D["Hourglass"] = "hourglass";
+	return SpiralForm3D;
+}({});
+var SpiralMark3D = /* @__PURE__ */ function(SpiralMark3D) {
+	SpiralMark3D["Ribbon"] = "ribbon";
+	SpiralMark3D["Columns"] = "columns";
+	SpiralMark3D["Tube"] = "tube";
+	SpiralMark3D["Dots"] = "dots";
+	return SpiralMark3D;
+}({});
+var TAU = Math.PI * 2;
+var UP = new Vector3(0, 1, 0);
+var SMOOTH = 6;
+/** Time wound into a spiral: aligning each cycle over the last, so periodic patterns stack up visibly. */
+var Spiral3DTimeline = class extends Temporal3DBase {
+	static meta = {
+		id: "spiral-timeline-3d",
+		name: "3D spiral timeline",
+		family: ChartFamily.Temporal,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Winds a time series around an axis at a chosen period, so cycles line up and drift between them shows.",
+		tags: [
+			"spiral",
+			"helix",
+			"periodic",
+			"time series"
+		],
+		sample: (seed) => SampleData.timeSeries(seed, 150, 1),
+		variants: {
+			form: Object.values(SpiralForm3D),
+			mark: Object.values(SpiralMark3D),
+			period: [
+				14,
+				7,
+				30
+			]
+		}
+	};
+	defaults() {
+		return {
+			date: "date",
+			value: "value",
+			form: "helix",
+			mark: "ribbon",
+			period: 14,
+			elevation: 24,
+			distance: 4.4
+		};
+	}
+	spot(u, angle) {
+		const { form } = this.options;
+		const on = (radius, y) => new Vector3(Math.cos(angle) * radius, y, Math.sin(angle) * radius);
+		if (form === "cone") return on(.14 + u * .82, .72 - u * 1.4);
+		if (form === "disc") return on(.12 + u * .86, -.3);
+		if (form === "hourglass") return on(.16 + Math.abs(u * 2 - 1) * .72, u * 1.6 - .9);
+		return on(.74, u * 1.5 - .9);
+	}
+	build(ctx) {
+		const { date, value, mark, period } = this.options;
+		const days = [...rollup(this.dated(date).filter(({ row }) => Number.isFinite(+row[value]) && row[value] != null), (group) => sum(group, ({ row }) => +row[value]), ({ time }) => Math.floor(time / DAY) * DAY)].sort((a, b) => a[0] - b[0]);
+		if (days.length < 2) return;
+		const marks = new NetworkMarks3D(ctx);
+		const first = days[0][0], span = days.at(-1)[0] - first;
+		const peak = Math.max(...days.map(([, amount]) => Math.abs(amount)), 1e-6);
+		const signed = days.some(([, amount]) => amount < 0);
+		const tint = (amount) => signed ? ctx.palette.diverging(amount / peak) : ctx.palette.sequential(.15 + amount / peak * .85);
+		const turns = span / DAY / period, rise = Math.min(.42, 1.2 / Math.max(turns, 1));
+		const spotAt = (day) => this.spot((day - first) / span, (day - first) / DAY / period * TAU);
+		const seats = days.map(([day, amount]) => {
+			return {
+				day,
+				amount,
+				at: spotAt(day),
+				tall: Math.abs(amount) / peak * rise,
+				tip: {
+					title: new Date(day).toISOString().slice(0, 10),
+					rows: [[String(value), Math.round(amount * 100) / 100]]
+				}
+			};
+		});
+		/** Follows the true curve between two samples, so a short period reads as a spiral and not a polygon. */
+		const between = (i) => Array.from({ length: 7 }, (_, k) => {
+			const f = k / SMOOTH, a = seats[i], b = seats[i + 1];
+			return {
+				at: spotAt(a.day + (b.day - a.day) * f),
+				tall: a.tall + (b.tall - a.tall) * f,
+				amount: a.amount + (b.amount - a.amount) * f
+			};
+		});
+		if (mark === "ribbon") {
+			const edge = (at, tall) => {
+				const out = new Vector3(at.x, 0, at.z).setLength(.007);
+				return [
+					at.clone().sub(out),
+					at.clone().add(out),
+					at.clone().add(out).addScaledVector(UP, tall),
+					at.clone().sub(out).addScaledVector(UP, tall)
+				];
+			};
+			marks.batch(seats.slice(1).map((seat, i) => ({
+				rings: between(i).map(({ at, tall }) => edge(at, tall)),
+				color: tint(seats[i].amount),
+				end: tint(seat.amount)
+			})), { sharp: true }, {
+				roughness: .6,
+				shadow: true
+			});
+		}
+		if (mark === "tube") marks.batch(seats.slice(1).map((seat, i) => ({
+			rings: Path3D.tube(between(i).map(({ at }) => at), (t) => Math.max(.004, Math.sqrt(Math.abs(seats[i].amount + (seat.amount - seats[i].amount) * t) / peak) * .035), 8),
+			color: tint(seats[i].amount),
+			end: tint(seat.amount)
+		})), {}, { shadow: true });
+		if (mark === "tube" || mark === "ribbon") marks.instances(new SphereGeometry(1, 8, 6), seats.map((seat) => ({
+			at: seat.at,
+			size: .016,
+			color: tint(seat.amount),
+			tip: seat.tip
+		})), {
+			opacity: .02,
+			shadow: false
+		});
+		if (mark === "columns") marks.instances(new CylinderGeometry(1, 1, 1, 10), seats.map((seat) => ({
+			at: seat.at.clone().addScaledVector(UP, seat.tall / 2),
+			size: new Vector3(.022, Math.max(seat.tall, .004), .022),
+			color: tint(seat.amount),
+			tip: seat.tip
+		})), { rise: true });
+		if (mark === "dots") marks.instances(new SphereGeometry(1, 14, 10), seats.map((seat) => ({
+			at: seat.at,
+			size: Math.max(.006, Math.cbrt(Math.abs(seat.amount) / peak) * .032),
+			color: tint(seat.amount),
+			tip: seat.tip
+		})), { roughness: .35 });
+		for (const seat of [seats[0], seats.at(-1)]) {
+			const clear = new Vector3(seat.at.x, 0, seat.at.z).setLength(.24).add(seat.at).addScaledVector(UP, seat.tall);
+			ctx.label(new Date(seat.day).toISOString().slice(0, 10), [
+				clear.x,
+				clear.y + (this.options.form === "disc" && seat === seats[0] ? .3 : 0),
+				clear.z
+			], "muted", 10);
+		}
+	}
+};
+export { Spiral3DTimeline, SpiralForm3D, SpiralMark3D };