@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/flow/ChordFlow.js

@@ -0,0 +1,262 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { RadialChart } from "../../core/RadialChart.js";
+import { FlowNodeMark, FlowSort } from "./flowEnums.js";
+import { FlowGraph } from "./FlowGraph.js";
+import { FlowSamples } from "./FlowSamples.js";
+import { FlowTable } from "./FlowTable.js";
+import { arc, chord, chordDirected, chordTranspose, ribbon, ribbonArrow, sum } from "d3";
+// src/charts/flow/ChordFlow.ts
+/** What the ribbons measure: flow leaving each group, flow arriving, or both directions summed. */
+var ChordDirection = /* @__PURE__ */ function(ChordDirection) {
+	ChordDirection["Outgoing"] = "outgoing";
+	ChordDirection["Incoming"] = "incoming";
+	ChordDirection["Mutual"] = "mutual";
+	return ChordDirection;
+}({});
+var ChordHead = /* @__PURE__ */ function(ChordHead) {
+	ChordHead["Arrow"] = "arrow";
+	ChordHead["Blunt"] = "blunt";
+	return ChordHead;
+}({});
+/** `Bipartite` puts every group on both halves: senders left, receivers right. */
+var ChordLayout = /* @__PURE__ */ function(ChordLayout) {
+	ChordLayout["Circle"] = "circle";
+	ChordLayout["Bipartite"] = "bipartite";
+	return ChordLayout;
+}({});
+var HALF = Math.PI;
+/** Show exchange between a handful of groups: who sends to whom, and how much comes back. */
+var ChordFlow = class extends RadialChart {
+	static meta = {
+		id: "chord-flow",
+		name: "Chord flow",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Shows directed exchange between groups around a circle, with ribbon width proportional to flow.",
+		tags: [
+			"chord",
+			"migration",
+			"exchange",
+			"matrix"
+		],
+		sample: (seed) => {
+			const graph = FlowSamples.network(seed, 80, 6);
+			const group = new Map(graph.nodes.map((node) => [node.id, node.group]));
+			return {
+				nodes: [...new Set(group.values())].map((id) => ({ id })),
+				links: graph.links.map((link, i) => ({
+					source: group.get(link.source),
+					target: i % 3 ? group.get(link.target) : group.get(`n${i * 7 % 80}`),
+					value: link.value
+				}))
+			};
+		},
+		variants: {
+			direction: [
+				"outgoing",
+				"incoming",
+				"mutual"
+			],
+			head: ["arrow", "blunt"],
+			layout: ["circle", "bipartite"],
+			groupOrder: [
+				FlowSort.Input,
+				FlowSort.Descending,
+				FlowSort.Ascending
+			],
+			arcMark: [FlowNodeMark.Bar, FlowNodeMark.Hairline]
+		},
+		valid: (v) => !(v.direction === "mutual" && v.head === "arrow") && !(v.direction === "mutual" && v.layout === "bipartite")
+	};
+	defaults() {
+		return {
+			direction: "outgoing",
+			head: "arrow",
+			layout: "circle",
+			groupOrder: FlowSort.Input,
+			arcMark: FlowNodeMark.Bar,
+			padAngle: .05
+		};
+	}
+	plotMargin() {
+		return {
+			top: 14,
+			right: 16,
+			bottom: 14,
+			left: 16
+		};
+	}
+	get graph() {
+		return FlowGraph.from(this.options.data, this.options);
+	}
+	table() {
+		return {
+			columns: [
+				"source",
+				"target",
+				"value"
+			],
+			rows: this.graph.arcs.map((link) => [
+				link.source,
+				link.target,
+				link.value
+			])
+		};
+	}
+	circle(names, matrix, color) {
+		const { direction, padAngle } = this.options;
+		const layout = direction === "mutual" ? chord() : direction === "incoming" ? chordTranspose() : chordDirected();
+		layout.padAngle(names.length > 1 ? padAngle : 0);
+		const chords = layout(direction === "mutual" ? matrix.map((row, i) => row.map((value, j) => value + matrix[j][i])) : matrix);
+		const slices = chords.groups.map((group) => ({
+			key: names[group.index],
+			name: names[group.index],
+			color: color(names[group.index]),
+			startAngle: group.startAngle,
+			endAngle: group.endAngle,
+			value: group.value
+		}));
+		const at = new Map(chords.groups.map((group, i) => [group.index, slices[i]]));
+		return {
+			slices,
+			bands: chords.map((path, i) => {
+				const [from, to] = direction === "incoming" ? [path.target, path.source] : [path.source, path.target];
+				const a = names[from.index], b = names[to.index];
+				return {
+					key: `${a}>${b}#${i}`,
+					color: color(a),
+					source: at.get(from.index),
+					target: at.get(to.index),
+					label: `${a} → ${b}`,
+					value: from.value,
+					path
+				};
+			})
+		};
+	}
+	bipartite(names, matrix, color) {
+		const { padAngle, direction } = this.options;
+		const flows = direction === "incoming" ? names.map((_, i) => names.map((__, j) => matrix[j][i])) : matrix;
+		const total = sum(flows.flat());
+		if (!total) return {
+			slices: [],
+			bands: []
+		};
+		const out = names.map((_, i) => sum(flows[i])), into = names.map((_, j) => sum(flows, (row) => row[j]));
+		const lay = (sizes, start, end, side) => {
+			const live = names.map((_, i) => i).filter((i) => sizes[i] > 0);
+			const pad = padAngle, unit = (end - start - pad * Math.max(0, live.length - 1)) / total;
+			let angle = start;
+			return live.map((i) => {
+				const slice = {
+					key: `${side}-${names[i]}`,
+					name: names[i],
+					color: color(names[i]),
+					startAngle: angle,
+					endAngle: angle + sizes[i] * unit,
+					value: sizes[i],
+					index: i
+				};
+				angle = slice.endAngle + pad;
+				return slice;
+			});
+		};
+		const left = lay(out, HALF * 1.04, HALF * 1.96, "send");
+		const right = lay(into, HALF * .04, HALF * .96, "recv");
+		const cursor = new Map([...left, ...right].map((slice) => [slice.key, slice.startAngle]));
+		const claim = (slice, value) => {
+			const start = cursor.get(slice.key), end = start + value / slice.value * (slice.endAngle - slice.startAngle);
+			cursor.set(slice.key, end);
+			return {
+				startAngle: start,
+				endAngle: end,
+				value,
+				index: 0
+			};
+		};
+		const bands = [];
+		for (const from of left) for (const dest of right) {
+			const value = flows[from.index][dest.index];
+			if (!value) continue;
+			const source = claim(from, value), target = claim(dest, value);
+			bands.push({
+				key: `${from.name}>${dest.name}`,
+				color: from.color,
+				source: from,
+				target: dest,
+				label: `${from.name} → ${dest.name}`,
+				value,
+				path: {
+					source,
+					target
+				}
+			});
+		}
+		return {
+			slices: [...left, ...right],
+			bands
+		};
+	}
+	drawRadial(ctx, { radius, center }) {
+		const { layout, head, arcMark } = this.options;
+		const graph = this.graph;
+		const moved = (id) => sum(graph.arcs, (link) => link.source === id || link.target === id ? link.value : 0);
+		const names = FlowTable.sorted(graph.vertices.map((node) => node.id), this.options.groupOrder, moved);
+		const index = new Map(names.map((name, i) => [name, i]));
+		const matrix = names.map(() => names.map(() => 0));
+		for (const link of graph.arcs) matrix[index.get(link.source)][index.get(link.target)] = link.value;
+		const color = (name) => ctx.palette.color(name);
+		for (const name of names) color(name);
+		const thick = arcMark === FlowNodeMark.Hairline ? 4 : 13;
+		const longest = Math.max(0, ...names.map((name) => FlowTable.width(name)));
+		const outer = Math.max(30, Math.min(radius - 16, center[0] - longest - 12));
+		const inner = outer - thick - 2;
+		const { slices, bands } = names.length ? layout === "bipartite" ? this.bipartite(names, matrix, color) : this.circle(names, matrix, color) : {
+			slices: [],
+			bands: []
+		};
+		const path = (head === "arrow" && names.length > 0 ? ribbonArrow().headRadius(Math.min(14, inner * .14)) : ribbon()).radius(inner - 1);
+		const shape = (band) => path(band.path);
+		const ribbons = ctx.marks("ribbons", "path", bands, (d) => d.key).attr("fill", (d) => d.color);
+		ctx.set(ribbons, {
+			d: shape,
+			"fill-opacity": .6
+		}, {
+			d: shape,
+			"fill-opacity": 0
+		}, 4);
+		ctx.hover(ribbons, (d) => ({
+			title: d.label,
+			rows: [["Flow", d.value]],
+			color: d.color
+		}));
+		const ring = arc().innerRadius(inner + 1).outerRadius(outer).cornerRadius(thick > 6 ? 2 : 0);
+		const ticks = ctx.marks("arcs", "path", slices, (d) => d.key).attr("fill", (d) => d.color);
+		ctx.set(ticks, { d: (d) => ring(d) }, { d: (d) => ring(d) }, 12);
+		ctx.hover(ticks, (d) => ({
+			title: d.name,
+			rows: [["Total", d.value]],
+			color: d.color
+		}));
+		ticks.on("pointerenter.trace", (_, slice) => {
+			ribbons.style("opacity", (band) => band.source.name === slice.name || band.target.name === slice.name ? null : .15);
+		}).on("pointerleave.trace", () => {
+			ribbons.style("opacity", null);
+		});
+		const legible = slices.map((slice) => {
+			const angle = (slice.startAngle + slice.endAngle) / 2 - HALF / 2;
+			const right = Math.cos(angle) >= 0;
+			const x = (outer + 6) * Math.cos(angle), y = (outer + 8) * Math.sin(angle);
+			return {
+				key: slice.key,
+				x,
+				y,
+				text: FlowTable.fit(slice.name, center[0] - Math.abs(x) - 2),
+				anchor: right ? "start" : "end"
+			};
+		}).filter(({ text, key }, i) => text && key && (slices[i].endAngle - slices[i].startAngle) * outer > 8);
+		ctx.text(ctx.marks("names", "text", legible, (d) => d.key).attr("text-anchor", (d) => d.anchor).attr("dy", "0.35em").attr("pointer-events", "none").attr("x", (d) => d.x).attr("y", (d) => d.y).text((d) => d.text));
+	}
+};
+export { ChordDirection, ChordFlow, ChordHead, ChordLayout };

package/dist/charts/flow/CircularSankey.js

@@ -0,0 +1,239 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { FlowGraphChart } from "./FlowChart.js";
+import { FlowRibbon } from "./flowEnums.js";
+import { FlowGeometry } from "./FlowPathKit.js";
+import { FlowSamples } from "./FlowSamples.js";
+import { FlowTable } from "./FlowTable.js";
+import { sankey, sankeyJustify, sankeyLeft, sankeyRight } from "d3-sankey";
+// src/charts/flow/CircularSankey.ts
+var CircularLoopSide = /* @__PURE__ */ function(CircularLoopSide) {
+	CircularLoopSide["Top"] = "top";
+	CircularLoopSide["Bottom"] = "bottom";
+	CircularLoopSide["Alternate"] = "alternate";
+	return CircularLoopSide;
+}({});
+var CircularColumn = /* @__PURE__ */ function(CircularColumn) {
+	CircularColumn["Justify"] = "justify";
+	CircularColumn["Left"] = "left";
+	CircularColumn["Right"] = "right";
+	return CircularColumn;
+}({});
+var CircularCorner = /* @__PURE__ */ function(CircularCorner) {
+	CircularCorner["Round"] = "round";
+	CircularCorner["Square"] = "square";
+	return CircularCorner;
+}({});
+var COLUMN = {
+	["justify"]: sankeyJustify,
+	["left"]: sankeyLeft,
+	["right"]: sankeyRight
+};
+/** Sankey for systems with feedback: recycling, rework, returning customers. Flows that close a cycle travel round the outside. */
+var CircularSankey = class extends FlowGraphChart {
+	static meta = {
+		id: "circular-sankey",
+		name: "Circular Sankey",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "A Sankey that keeps cycles, routing returning flows around the columns as loops.",
+		tags: [
+			"feedback",
+			"cycle",
+			"recycling",
+			"rework"
+		],
+		sample: (seed) => FlowSamples.cyclic(seed),
+		variants: {
+			loopSide: [
+				"top",
+				"bottom",
+				"alternate"
+			],
+			column: [
+				"justify",
+				"left",
+				"right"
+			],
+			corner: ["round", "square"],
+			ribbon: [
+				FlowRibbon.Curved,
+				FlowRibbon.Angular,
+				FlowRibbon.Shoulder
+			],
+			orientation: [Orientation.Horizontal, Orientation.Vertical]
+		}
+	};
+	defaults() {
+		return {
+			orientation: Orientation.Horizontal,
+			loopSide: "top",
+			column: "justify",
+			corner: "round",
+			ribbon: FlowRibbon.Curved,
+			nodeWidth: 14,
+			nodeGap: 14
+		};
+	}
+	plotMargin() {
+		return {
+			top: 8,
+			right: 8,
+			bottom: 8,
+			left: 8
+		};
+	}
+	draw(ctx) {
+		const { orientation, column, nodeWidth, nodeGap, loopSide, corner, ribbon } = this.options;
+		const vertical = orientation === Orientation.Vertical;
+		const graph = this.graph();
+		const [length, full] = vertical ? [ctx.plot.height, ctx.plot.width] : [ctx.plot.width, ctx.plot.height];
+		const breadth = vertical ? Math.min(full, length * 1.15) : full;
+		const inset = (full - breadth) / 2;
+		const flip = FlowGeometry.project(orientation);
+		const to = (u, v) => flip(u, v + inset);
+		const back = graph.backArcs();
+		const totals = graph.throughput();
+		const arcs = graph.arcs;
+		const forward = arcs.filter((_, i) => !back.has(i));
+		const returning = arcs.filter((_, i) => back.has(i));
+		const sides = returning.map((_, i) => loopSide === "top" ? -1 : loopSide === "bottom" ? 1 : i % 2 === 0 ? -1 : 1);
+		const edge = vertical ? 16 : Math.min(length * .14, 8 + Math.max(0, ...graph.vertices.map((node) => FlowTable.width(node.label))) * .8);
+		const lay = (above, below, reach) => {
+			const nodes = graph.vertices.filter(({ id }) => totals.get(id)).map((vertex) => ({
+				...vertex,
+				fixedValue: totals.get(vertex.id)
+			}));
+			const links = forward.map(({ source, target, value }) => ({
+				source,
+				target,
+				value
+			}));
+			const layout = sankey().nodeId((d) => d.id).nodeAlign(COLUMN[column]).nodeWidth(nodeWidth).nodePadding(nodeGap).extent([[edge + reach, above], [length - edge - reach, breadth - below]]);
+			if (nodes.length) layout({
+				nodes,
+				links
+			});
+			return {
+				nodes,
+				links
+			};
+		};
+		const unitOf = (nodes) => nodes.reduce((best, node) => node.fixedValue ? Math.min(best, (node.y1 - node.y0) / node.fixedValue) : best, Infinity);
+		const room = (unit, side) => returning.reduce((sum, arc, i) => sum + (sides[i] === side ? Math.max(1, arc.value * unit) + 4 : 0), 0);
+		const rough = unitOf(lay(0, 0, 0).nodes);
+		const band = (unit) => [room(unit, -1), room(unit, 1)];
+		const [high, low] = Number.isFinite(rough) ? band(rough) : [0, 0];
+		const sideRoom = Math.min(length * .16, Math.max(0, high, low) * .6 + 8);
+		const { nodes, links } = lay(high + 2, low + 2, returning.length ? sideRoom : 0);
+		const color = (node) => ctx.palette.color(node.group ?? node.label);
+		for (const node of nodes) color(node);
+		const scale = unitOf(nodes);
+		const ribbons = this.bands(ctx, "links", links.map((link) => {
+			const source = link.source, target = link.target, half = link.width / 2;
+			return {
+				key: `${source.id}>${target.id}`,
+				from: color(source),
+				datum: link,
+				d: FlowGeometry.ribbon({
+					u: source.x1,
+					v0: link.y0 - half,
+					v1: link.y0 + half
+				}, {
+					u: target.x0,
+					v0: link.y1 - half,
+					v1: link.y1 + half
+				}, ribbon, to)
+			};
+		}), (link) => ({
+			title: `${link.source.label} → ${link.target.label}`,
+			rows: [["Flow", link.value]],
+			color: color(link.source)
+		}));
+		const byId = new Map(nodes.map((node) => [node.id, node]));
+		const leave = new Map(nodes.map((node) => [node.id, node.y0 + (node.sourceLinks ?? []).reduce((sum, link) => sum + link.width, 0)]));
+		const enter = new Map(nodes.map((node) => [node.id, node.y0 + (node.targetLinks ?? []).reduce((sum, link) => sum + link.width, 0)]));
+		const loops = [];
+		const stacked = {
+			[-1]: 0,
+			1: 0
+		};
+		const distance = (arc) => Math.abs((byId.get(arc.source)?.x0 ?? 0) - (byId.get(arc.target)?.x0 ?? 0));
+		returning.map((arc, i) => ({
+			arc,
+			side: sides[i]
+		})).sort((a, b) => distance(b.arc) - distance(a.arc)).forEach(({ arc, side }, i, all) => {
+			const source = byId.get(arc.source), target = byId.get(arc.target);
+			const width = Math.max(1, arc.value * scale);
+			const ys = leave.get(arc.source) + width / 2, yt = enter.get(arc.target) + width / 2;
+			leave.set(arc.source, ys + width / 2);
+			enter.set(arc.target, yt + width / 2);
+			const lane = side < 0 ? stacked[-1] + width / 2 : breadth - stacked[1] - width / 2;
+			stacked[side] = stacked[side] + width + 4;
+			const nested = (all.length - 1 - i) / Math.max(1, all.length) * (sideRoom - 8);
+			loops.push({
+				arc,
+				source,
+				target,
+				width,
+				ys,
+				yt,
+				lane,
+				side,
+				pad: Math.min(6 + width / 2 + nested, edge + sideRoom - width / 2 - 1)
+			});
+		});
+		const radius = corner === "round" ? 12 : .01;
+		const loopPath = ({ source, target, ys, yt, lane, pad, width }) => {
+			const out = source.x1 + pad, back = target.x0 - pad;
+			const points = [
+				[source.x1, ys],
+				[out, ys],
+				[out, lane],
+				[back, lane],
+				[back, yt],
+				[target.x0, yt]
+			];
+			return FlowGeometry.rounded(points.map(([u, v]) => to(u, v)), corner === "round" ? radius + width / 2 : radius);
+		};
+		const hoops = ctx.marks("loops", "path", loops, (d) => `${d.arc.source}>${d.arc.target}`).attr("fill", "none").attr("stroke", (d) => color(d.source)).attr("stroke-width", (d) => d.width).attr("stroke-opacity", .4);
+		this.stroke(ctx, hoops, loopPath);
+		ctx.hover(hoops, (d) => ({
+			title: `${d.source.label} ⟲ ${d.target.label}`,
+			rows: [["Returning flow", d.arc.value]],
+			color: color(d.source)
+		}));
+		const blocks = ctx.marks("nodes", "path", nodes, (d) => d.id).attr("fill", color);
+		const shape = (d) => FlowGeometry.polygon([
+			to(d.x0, d.y0),
+			to(d.x1, d.y0),
+			to(d.x1, d.y1),
+			to(d.x0, d.y1)
+		]);
+		ctx.set(blocks, { d: shape }, { d: shape }, 8);
+		ctx.hover(blocks, (d) => ({
+			title: d.label,
+			rows: [["Throughput", d.fixedValue]],
+			color: color(d)
+		}));
+		this.trace(blocks, ribbons, ({ datum }, node) => datum.source === node || datum.target === node);
+		this.labels(ctx, "names", nodes.map((node) => {
+			const [x, y] = to(node.x1 + 5, (node.y0 + node.y1) / 2);
+			return vertical ? {
+				key: node.id,
+				x,
+				y: node.x1 + 9,
+				text: node.label,
+				anchor: "middle",
+				halo: true
+			} : {
+				key: node.id,
+				x,
+				y,
+				text: node.label,
+				halo: true
+			};
+		}));
+	}
+};
+export { CircularColumn, CircularCorner, CircularLoopSide, CircularSankey };