@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/flow/NetworkFlowChart.js

@@ -0,0 +1,204 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { FlowDirection, FlowRouter } from "./flowEnums.js";
+import { FlowGeometry } from "./FlowPathKit.js";
+import { LayeredLayout } from "./LayeredLayout.js";
+import { FlowNodeShape, NodeLinkChart } from "./FlowNodeLinkChart.js";
+import { MaxFlow } from "./MaxFlow.js";
+import { SampleData } from "../../data/SampleData.js";
+// src/charts/flow/NetworkFlowChart.ts
+/** `Pipe` shows capacity with flow inside; `Width` shows flow alone; `Labelled` writes `flow / capacity`. */
+var NetworkFlowEncoding = /* @__PURE__ */ function(NetworkFlowEncoding) {
+	NetworkFlowEncoding["Pipe"] = "pipe";
+	NetworkFlowEncoding["Width"] = "width";
+	NetworkFlowEncoding["Labelled"] = "labelled";
+	return NetworkFlowEncoding;
+}({});
+/** Find the bottleneck of a capacity network: computes maximum flow from links' capacities and marks the minimum cut. */
+var NetworkFlowChart = class extends NodeLinkChart {
+	static meta = {
+		id: "network-flow",
+		name: "Network flow",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Solves maximum flow on a capacity network, drawing utilisation per link and the limiting minimum cut.",
+		tags: [
+			"max flow",
+			"min cut",
+			"capacity",
+			"pipes",
+			"throughput"
+		],
+		sample: (seed) => {
+			const flow = SampleData.flow(seed, 4, 3);
+			const label = (id) => `${"ABCD"[+id[1]]}${+id[3] + 1}`;
+			const nodes = [
+				...flow.nodes.map((node) => ({
+					id: node.id,
+					label: label(node.id)
+				})),
+				{
+					id: "source",
+					label: "Source"
+				},
+				{
+					id: "sink",
+					label: "Sink"
+				}
+			];
+			const edge = flow.nodes.filter((node) => node.id[1] === "0").map((node, i) => ({
+				source: "source",
+				target: node.id,
+				value: 34 + i * 7
+			}));
+			const out = flow.nodes.filter((node) => node.id[1] === "3").map((node, i) => ({
+				source: node.id,
+				target: "sink",
+				value: 26 + i * 9
+			}));
+			return {
+				nodes,
+				links: [
+					...edge,
+					...flow.links,
+					...out
+				]
+			};
+		},
+		variants: {
+			encoding: [
+				"pipe",
+				"width",
+				"labelled"
+			],
+			router: [
+				FlowRouter.Curved,
+				FlowRouter.Straight,
+				FlowRouter.Orthogonal
+			],
+			direction: [FlowDirection.LeftRight, FlowDirection.TopBottom],
+			cut: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			direction: FlowDirection.LeftRight,
+			router: FlowRouter.Curved,
+			encoding: "pipe",
+			cut: true
+		};
+	}
+	plotMargin() {
+		return {
+			top: 8,
+			right: 8,
+			bottom: 8,
+			left: 8
+		};
+	}
+	draw(ctx) {
+		const { encoding, cut, router, entry, exit } = this.options;
+		const vertical = this.vertical;
+		const to = this.toPlot;
+		const graph = this.graph();
+		const [length, breadth] = vertical ? [ctx.plot.height, ctx.plot.width] : [ctx.plot.width, ctx.plot.height];
+		const solved = MaxFlow.solve(graph, entry, exit);
+		const ranked = LayeredLayout.ranks(graph);
+		const count = Math.max(0, ...ranked.values()) + 1;
+		const step = length / count;
+		const widest = Math.max(1, ...Array.from({ length: count }, (_, rank) => [...ranked.values()].filter((value) => value === rank).length));
+		const placed = LayeredLayout.place(graph, {
+			extent: breadth - 18,
+			node: Math.max(vertical ? 80 : 44, (breadth - 18) / widest),
+			lane: 14
+		}, ranked);
+		const u = (rank) => step * (rank + .5);
+		const scale = 12 / Math.max(1, ...graph.arcs.map((arc) => arc.value));
+		const pipes = placed.routes.filter(({ stops }) => stops.length > 1).map(({ arc, stops }) => {
+			const flow = solved.flow.get(arc) ?? 0;
+			const sign = Math.sign(stops[stops.length - 1].rank - stops[0].rank) || 1;
+			const points = stops.map((stop, i) => [u(stop.rank) + (i === 0 ? sign * 9 : i === stops.length - 1 ? -sign * 9 : 0), stop.cross + 9]);
+			const a = points[0], b = points[1];
+			const mid = to((a[0] + b[0]) / 2, (a[1] + b[1]) / 2);
+			return {
+				key: `${arc.source}>${arc.target}`,
+				path: FlowGeometry.route(points, router, to),
+				capacity: arc.value,
+				flow,
+				cut: solved.cut.has(arc),
+				label: `${Math.round(flow)}/${Math.round(arc.value)}`,
+				mid,
+				angle: Math.atan2(to(b[0], b[1])[1] - to(a[0], a[1])[1], to(b[0], b[1])[0] - to(a[0], a[1])[0]),
+				title: `${arc.source} → ${arc.target}`,
+				capWidth: Math.max(2, arc.value * scale),
+				flowWidth: Math.max(flow ? 1.5 : 0, flow * scale)
+			};
+		});
+		const load = (pipe) => ctx.palette.sequential(.3 + .7 * (pipe.flow / (pipe.capacity || 1)));
+		const tip = (pipe) => ({
+			title: pipe.title,
+			color: load(pipe),
+			rows: [
+				["Flow", Math.round(pipe.flow * 100) / 100],
+				["Capacity", pipe.capacity],
+				["Utilisation", `${Math.round(pipe.flow / (pipe.capacity || 1) * 100)}%`]
+			]
+		});
+		const walls = ctx.marks("walls", "path", encoding === "pipe" ? pipes : [], (d) => d.key).attr("fill", "none").attr("stroke", ctx.theme.grid).attr("stroke-linecap", "butt").attr("stroke-width", (d) => d.capWidth);
+		this.stroke(ctx, walls, (d) => d.path);
+		const cores = ctx.marks("cores", "path", pipes, (d) => d.key).attr("fill", "none").attr("stroke", load).attr("stroke-linecap", "butt").attr("stroke-width", (d) => encoding === "labelled" ? 2 : Math.max(.01, d.flowWidth));
+		this.stroke(ctx, cores, (d) => d.path);
+		ctx.hover(cores, tip);
+		const marks = cut ? pipes.filter((pipe) => pipe.cut) : [];
+		const reach = (pipe) => pipe.capWidth / 2 + 5;
+		const tick = (d) => {
+			const normal = d.angle + Math.PI / 2;
+			return FlowGeometry.polyline([[d.mid[0] - reach(d) * Math.cos(normal), d.mid[1] - reach(d) * Math.sin(normal)], [d.mid[0] + reach(d) * Math.cos(normal), d.mid[1] + reach(d) * Math.sin(normal)]]);
+		};
+		const cuts = ctx.marks("cuts", "path", marks, (d) => d.key).attr("fill", "none").attr("stroke", ctx.theme.critical).attr("stroke-width", 3).attr("stroke-linecap", "round");
+		ctx.set(cuts, { d: tick });
+		ctx.hover(cuts, (d) => ({
+			title: "On the minimum cut",
+			color: ctx.theme.critical,
+			rows: [[d.title, d.capacity]]
+		}));
+		this.labels(ctx, "edge-values", encoding === "labelled" ? pipes.map((pipe) => ({
+			key: pipe.key,
+			x: pipe.mid[0],
+			y: pipe.mid[1],
+			text: pipe.label,
+			anchor: "middle",
+			size: 10,
+			halo: true
+		})) : []);
+		const io = /* @__PURE__ */ new Set([...solved.entries, ...solved.exits]);
+		const boxes = graph.vertices.map((vertex) => ({
+			id: vertex.id,
+			label: vertex.label,
+			u: u(placed.rank.get(vertex.id)),
+			v: placed.cross.get(vertex.id) + 9,
+			along: 28,
+			across: 28,
+			shape: FlowNodeShape.Dot,
+			fill: io.has(vertex.id) ? ctx.theme.ink : ctx.theme.inkMuted,
+			tip: {
+				title: vertex.label,
+				rows: [["Through", Math.round(solved.through.get(vertex.id) ?? 0)]]
+			}
+		}));
+		this.drawBoxes(ctx, boxes);
+		this.labels(ctx, "total", graph.arcs.length ? [{
+			key: "max",
+			x: ctx.plot.width,
+			y: 7,
+			text: `Max flow ${Math.round(solved.total).toLocaleString("en")}`,
+			anchor: "end",
+			weight: 600,
+			tone: "ink"
+		}] : []);
+	}
+	legendItems() {
+		return [];
+	}
+};
+export { NetworkFlowChart, NetworkFlowEncoding };

package/dist/charts/flow/ParallelSets.js

@@ -0,0 +1,120 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { FlowNodeMark, FlowRibbon, FlowSort } from "./flowEnums.js";
+import { FlowGeometry } from "./FlowPathKit.js";
+import { FlowSamples } from "./FlowSamples.js";
+import { StratumAxisOrder, StratumChart, StratumThreading } from "./StratumChart.js";
+// src/charts/flow/ParallelSets.ts
+/** Explore how categorical dimensions intersect: stacked axes filled edge to edge, with nested bands that split at every axis. */
+var ParallelSets = class extends StratumChart {
+	static meta = {
+		id: "parallel-sets",
+		name: "Parallel sets",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Compares categorical dimensions on parallel axes, with bands nesting each combination of categories.",
+		tags: [
+			"parsets",
+			"categorical",
+			"multivariate"
+		],
+		sample: (seed) => FlowSamples.records(seed),
+		variants: {
+			orientation: [Orientation.Vertical, Orientation.Horizontal],
+			axisOrder: [
+				StratumAxisOrder.Input,
+				StratumAxisOrder.Reversed,
+				StratumAxisOrder.Cardinality
+			],
+			categoryOrder: [
+				FlowSort.Input,
+				FlowSort.Descending,
+				FlowSort.Alpha
+			],
+			ribbon: [
+				FlowRibbon.Curved,
+				FlowRibbon.Angular,
+				FlowRibbon.Shoulder
+			],
+			axisMark: [FlowNodeMark.Bar, FlowNodeMark.Hairline]
+		}
+	};
+	defaults() {
+		return {
+			value: "value",
+			orientation: Orientation.Vertical,
+			threading: StratumThreading.Threaded,
+			ribbon: FlowRibbon.Curved,
+			categoryOrder: FlowSort.Input,
+			axisOrder: StratumAxisOrder.Input,
+			axisMark: FlowNodeMark.Bar,
+			gap: 10
+		};
+	}
+	plotMargin() {
+		return {
+			top: 4,
+			right: 8,
+			bottom: 8,
+			left: 8
+		};
+	}
+	draw(ctx) {
+		const vertical = this.options.orientation === Orientation.Vertical;
+		const to = FlowGeometry.project(this.options.orientation);
+		const [length, breadth] = vertical ? [ctx.plot.height, ctx.plot.width] : [ctx.plot.width, ctx.plot.height];
+		const thick = this.options.axisMark === FlowNodeMark.Hairline ? 2 : 10;
+		const headroom = 18;
+		const layout = this.layout(vertical ? headroom : 0, length, breadth - (vertical ? 0 : headroom), thick);
+		const shift = vertical ? 0 : headroom;
+		const at = (u, v) => to(u, v + shift);
+		const color = (name) => ctx.palette.color(name);
+		for (const stratum of layout.axes[0]?.strata ?? []) color(stratum.name);
+		this.bands(ctx, "bands", this.segmentBands(layout, at, (segment) => color(segment.origin)), (segment) => this.segmentTip(segment, layout.total, color(segment.origin)), .55);
+		const bars = layout.axes.flatMap((axis) => axis.strata.map((stratum) => ({
+			...stratum,
+			field: axis.field,
+			u: axis.u
+		})));
+		const shape = (d) => FlowGeometry.polygon([
+			at(d.u, d.v0),
+			at(d.u + thick, d.v0),
+			at(d.u + thick, d.v1),
+			at(d.u, d.v1)
+		]);
+		const marks = ctx.marks("bars", "path", bars, (d) => `${d.field}/${d.name}`).attr("fill", ctx.theme.inkSecondary);
+		ctx.set(marks, { d: shape }, { d: shape }, 4);
+		ctx.hover(marks, (d) => ({
+			title: d.name,
+			rows: [[d.field, +d.value.toFixed(2)], ["Share", `${(d.value / layout.total * 100).toFixed(1)}%`]]
+		}));
+		this.labels(ctx, "names", bars.map((d) => {
+			const share = `${d.name} ${Math.round(d.value / layout.total * 100)}%`;
+			return vertical ? {
+				key: `${d.field}/${d.name}`,
+				x: d.v0 + 1,
+				y: d.u - 7,
+				text: share,
+				tone: "ink",
+				halo: true
+			} : {
+				key: `${d.field}/${d.name}`,
+				x: d.u >= length - thick - 1 ? d.u - 4 : d.u + thick + 4,
+				y: shift + (d.v0 + d.v1) / 2,
+				text: share,
+				anchor: d.u >= length - thick - 1 ? "end" : "start",
+				tone: "ink",
+				halo: true
+			};
+		}));
+		if (!vertical) this.labels(ctx, "heads", layout.axes.map((axis, i) => ({
+			key: axis.field,
+			x: i === layout.axes.length - 1 ? length : axis.u,
+			y: 7,
+			text: axis.field,
+			weight: 600,
+			anchor: i === 0 ? "start" : i === layout.axes.length - 1 ? "end" : "middle"
+		})));
+	}
+};
+export { ParallelSets };

package/dist/charts/flow/ProcessFlowChart.js

@@ -0,0 +1,175 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { FlowDirection, FlowRouter } from "./flowEnums.js";
+import { FlowSamples } from "./FlowSamples.js";
+import { LayeredLayout } from "./LayeredLayout.js";
+import { FlowNodeShape, NodeLinkChart } from "./FlowNodeLinkChart.js";
+// src/charts/flow/ProcessFlowChart.ts
+var ProcessNodeStyle = /* @__PURE__ */ function(ProcessNodeStyle) {
+	ProcessNodeStyle["Semantic"] = "semantic";
+	ProcessNodeStyle["Uniform"] = "uniform";
+	ProcessNodeStyle["Dot"] = "dot";
+	return ProcessNodeStyle;
+}({});
+/** How much space ranks take: evenly across the plot, or tight around the centre. */
+var ProcessDensity = /* @__PURE__ */ function(ProcessDensity) {
+	ProcessDensity["Spread"] = "spread";
+	ProcessDensity["Compact"] = "compact";
+	return ProcessDensity;
+}({});
+var SHAPE = {
+	start: FlowNodeShape.Pill,
+	end: FlowNodeShape.Pill,
+	decision: FlowNodeShape.Diamond,
+	data: FlowNodeShape.Data,
+	process: FlowNodeShape.Box
+};
+var NAME = {
+	start: "Terminal",
+	end: "Terminal",
+	decision: "Decision",
+	data: "Data",
+	process: "Step"
+};
+/** Document how work moves through steps and decisions. Node shapes follow flowchart convention and layout is automatic. */
+var ProcessFlowChart = class extends NodeLinkChart {
+	static meta = {
+		id: "process-flow",
+		name: "Process flowchart",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Lays out steps and decisions of a process automatically, with conventional shapes and routed arrows.",
+		tags: [
+			"flowchart",
+			"workflow",
+			"bpmn",
+			"dag"
+		],
+		sample: (seed) => {
+			const graph = FlowSamples.network(seed, 9, 3);
+			const degree = (id) => graph.links.filter((link) => link.source === id).length;
+			const seen = /* @__PURE__ */ new Map();
+			const links = graph.links.map((link) => {
+				const index = seen.get(link.source) ?? 0;
+				seen.set(link.source, index + 1);
+				return degree(link.source) > 1 ? {
+					...link,
+					label: index ? "No" : "Yes"
+				} : link;
+			});
+			const leaves = graph.nodes.filter((node) => !degree(node.id));
+			return {
+				nodes: graph.nodes,
+				links: [...links, ...leaves.slice(1).map((node) => ({
+					source: node.id,
+					target: leaves[0].id,
+					value: 1
+				}))]
+			};
+		},
+		variants: {
+			direction: [FlowDirection.LeftRight, FlowDirection.TopBottom],
+			router: [
+				FlowRouter.Orthogonal,
+				FlowRouter.Curved,
+				FlowRouter.Straight
+			],
+			nodeStyle: [
+				"semantic",
+				"uniform",
+				"dot"
+			],
+			density: ["spread", "compact"]
+		}
+	};
+	defaults() {
+		return {
+			direction: FlowDirection.LeftRight,
+			router: FlowRouter.Orthogonal,
+			kind: "kind",
+			edgeLabel: "label",
+			nodeStyle: "semantic",
+			density: "spread"
+		};
+	}
+	plotMargin() {
+		return {
+			top: 8,
+			right: 8,
+			bottom: 8,
+			left: 8
+		};
+	}
+	draw(ctx) {
+		const { nodeStyle, density, kind, edgeLabel } = this.options;
+		const vertical = this.vertical;
+		const graph = this.graph(false);
+		const [length, breadth] = vertical ? [ctx.plot.height, ctx.plot.width] : [ctx.plot.width, ctx.plot.height];
+		const dot = nodeStyle === "dot";
+		const ranked = LayeredLayout.ranks(graph);
+		const count = Math.max(1, ...ranked.values()) + (graph.vertices.length ? 1 : 0);
+		const compact = density === "compact";
+		const span = compact ? Math.min(length, count * (vertical ? 54 : 104)) : length;
+		const step = span / Math.max(1, count);
+		const offset = (length - span) / 2;
+		const alongSize = dot ? 14 : vertical ? Math.min(36, step * .62) : Math.min(step * .74, 100);
+		const crossSize = dot ? 14 : vertical ? 92 : 36;
+		const placed = LayeredLayout.place(graph, {
+			extent: breadth,
+			node: dot ? vertical ? 84 : 42 : crossSize + (compact ? 8 : 16),
+			lane: compact ? 8 : 12
+		}, ranked);
+		const ranks = /* @__PURE__ */ new Map();
+		for (const vertex of graph.vertices) {
+			const rank = placed.rank.get(vertex.id);
+			ranks.set(rank, [...ranks.get(rank) ?? [], placed.cross.get(vertex.id)]);
+		}
+		const pitch = Math.min(Infinity, ...[...ranks.values()].flatMap((list) => list.sort((a, b) => a - b).slice(1).map((cross, i) => cross - list[i])));
+		const degree = (id, side) => graph.arcs.filter((arc) => arc[side] === id).length;
+		const kindOf = (id, raw) => {
+			const stated = raw?.[kind];
+			if (typeof stated === "string" && SHAPE[stated]) return stated;
+			if (!degree(id, "target")) return "start";
+			if (!degree(id, "source")) return "end";
+			return degree(id, "source") > 1 ? "decision" : "process";
+		};
+		const u = (rank) => offset + step * (rank + .5);
+		const halfU = alongSize / 2;
+		const boxes = graph.vertices.map((vertex) => {
+			const type = kindOf(vertex.id, vertex.raw);
+			const shape = dot ? FlowNodeShape.Dot : nodeStyle === "uniform" ? FlowNodeShape.Box : SHAPE[type];
+			const tall = type === "decision" && !dot && nodeStyle === "semantic" ? 1.25 : 1;
+			const name = NAME[type];
+			return {
+				id: vertex.id,
+				label: vertex.label,
+				u: u(placed.rank.get(vertex.id)),
+				v: placed.cross.get(vertex.id),
+				along: alongSize,
+				across: dot ? crossSize : Math.max(14, Math.min(crossSize * tall, pitch - 6)),
+				shape,
+				fill: ctx.palette.color(name),
+				tip: {
+					title: vertex.label,
+					rows: [["Type", name]]
+				}
+			};
+		});
+		const connectors = placed.routes.filter(({ stops }) => stops.length > 1).map(({ arc, stops }) => {
+			const sign = Math.sign(stops[stops.length - 1].rank - stops[0].rank) || 1;
+			return {
+				key: `${arc.source}>${arc.target}`,
+				label: arc.raw[edgeLabel],
+				tip: { title: `${arc.source} → ${arc.target}` },
+				stops: stops.map((stop, i) => {
+					const edge = i === 0 ? sign : i === stops.length - 1 ? -sign : 0;
+					return [u(stop.rank) + edge * (halfU + (edge !== 0 ? 1 : 0)), stop.cross];
+				})
+			};
+		});
+		this.drawConnectors(ctx, connectors);
+		this.drawBoxes(ctx, boxes);
+		this.drawConnectorLabels(ctx, connectors);
+	}
+};
+export { ProcessDensity, ProcessFlowChart, ProcessNodeStyle };