@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/flow/RetentionFlow.js

@@ -0,0 +1,242 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { FlowChart } from "./FlowChart.js";
+import { FlowBaseline, FlowRibbon } from "./flowEnums.js";
+import { FlowGeometry } from "./FlowPathKit.js";
+import { FlowTable } from "./FlowTable.js";
+// src/charts/flow/RetentionFlow.ts
+/** How the churn and joiner streams end: tapering to a point, as a full-width band, or as a short stub. */
+var RetentionExit = /* @__PURE__ */ function(RetentionExit) {
+	RetentionExit["Taper"] = "taper";
+	RetentionExit["Band"] = "band";
+	RetentionExit["Stub"] = "stub";
+	return RetentionExit;
+}({});
+var RetentionScale = /* @__PURE__ */ function(RetentionScale) {
+	RetentionScale["Absolute"] = "absolute";
+	RetentionScale["Share"] = "share";
+	return RetentionScale;
+}({});
+/** Explain growth period by period: what stayed, what left and what arrived. */
+var RetentionFlow = class extends FlowChart {
+	static meta = {
+		id: "retention-flow",
+		name: "Retention flow",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Shows a customer base period by period, with retained, churned and new users as separate streams.",
+		tags: [
+			"retention",
+			"churn",
+			"growth accounting",
+			"users"
+		],
+		sample: (seed) => {
+			const rows = SampleData.categories(seed, 7, 2);
+			let active = 1e3;
+			return Array.from({ length: 7 }, (_, i) => {
+				const churned = i ? Math.round(active * +rows[i * 2].value / 340) : 0, joined = i ? Math.round(+rows[i * 2 + 1].value * 2.2) : 0;
+				active += joined - churned;
+				return {
+					period: `Month ${i + 1}`,
+					active,
+					churned,
+					joined
+				};
+			});
+		},
+		variants: {
+			exit: [
+				"taper",
+				"band",
+				"stub"
+			],
+			ribbon: [
+				FlowRibbon.Curved,
+				FlowRibbon.Angular,
+				FlowRibbon.Shoulder
+			],
+			baseline: [
+				FlowBaseline.Center,
+				FlowBaseline.Top,
+				FlowBaseline.Bottom
+			],
+			scale: ["absolute", "share"],
+			orientation: [Orientation.Horizontal, Orientation.Vertical]
+		},
+		valid: (v) => v.scale === "absolute" || v.baseline === FlowBaseline.Center
+	};
+	defaults() {
+		return {
+			period: "period",
+			active: "active",
+			churned: "churned",
+			joined: "joined",
+			exit: "taper",
+			ribbon: FlowRibbon.Curved,
+			baseline: FlowBaseline.Center,
+			scale: "absolute",
+			orientation: Orientation.Horizontal
+		};
+	}
+	plotMargin() {
+		return this.options.orientation === Orientation.Vertical ? {
+			top: 8,
+			right: 8,
+			bottom: 8,
+			left: 58
+		} : {
+			top: 8,
+			right: 10,
+			bottom: 26,
+			left: 10
+		};
+	}
+	draw(ctx) {
+		const { data, period, active, churned, joined, baseline, scale, orientation, ribbon, exit } = this.options;
+		const vertical = orientation === Orientation.Vertical;
+		const to = FlowGeometry.project(orientation);
+		const [length, breadth] = vertical ? [ctx.plot.height, ctx.plot.width] : [ctx.plot.width, ctx.plot.height];
+		const num = (cell) => {
+			const value = Number(cell);
+			return Number.isFinite(value) && value > 0 ? value : 0;
+		};
+		const rows = (data ?? []).filter((row) => row?.[period] !== null && row?.[period] !== void 0);
+		const pad = Math.max(16, breadth * .14);
+		const room = breadth - pad * 2;
+		const peak = Math.max(1e-9, ...rows.map((row) => num(row[active])));
+		const bar = Math.min(26, length / Math.max(1, rows.length) / 3);
+		const step = rows.length > 1 ? (length - bar) / (rows.length - 1) : 0;
+		const columns = rows.map((row, i) => {
+			const size = num(row[active]);
+			const unit = room / (scale === "share" ? size || 1 : peak), tall = size * unit;
+			const v0 = baseline === FlowBaseline.Top ? pad : baseline === FlowBaseline.Bottom ? breadth - pad - tall : (breadth - tall) / 2;
+			return {
+				label: String(row[period]),
+				active: size,
+				churned: i ? Math.min(num(row[churned]), num(rows[i - 1][active])) : 0,
+				joined: i ? Math.min(num(row[joined]), size) : 0,
+				u: i * step,
+				v0,
+				v1: v0 + tall,
+				unit
+			};
+		});
+		const color = (stream) => ctx.palette.color(stream);
+		const pieces = [];
+		const add = (stream, from, target, value, d) => {
+			if (value > 0) pieces.push({
+				key: `${stream}#${from.label}`,
+				from: color(stream),
+				datum: {
+					stream,
+					from,
+					to: target,
+					value
+				},
+				d
+			});
+		};
+		const reach = (tall) => exit === "stub" ? tall * .4 : tall;
+		columns.slice(1).forEach((next, i) => {
+			const prev = columns[i];
+			const kept = Math.max(0, prev.active - next.churned);
+			const a = {
+				u: prev.u + bar,
+				v0: prev.v0,
+				v1: prev.v0 + kept * prev.unit
+			};
+			const b = {
+				u: next.u,
+				v0: next.v1 - kept * next.unit,
+				v1: next.v1
+			};
+			add("Retained", prev, next, kept, FlowGeometry.ribbon(a, b, ribbon, to));
+			const lost = next.churned * prev.unit;
+			const span = step - bar, fall = Math.min(breadth - prev.v1 - 2, step * 1.1);
+			const tailEnd = prev.u + bar + span * (exit === "band" ? .42 : .5);
+			const tailV = prev.v1 + reach(fall);
+			const tail = {
+				u: tailEnd,
+				v0: exit === "band" ? tailV - Math.min(lost, fall * .8) : tailV - .5,
+				v1: tailV
+			};
+			add("Churned", prev, next, next.churned, FlowGeometry.ribbon({
+				u: prev.u + bar,
+				v0: prev.v1 - lost,
+				v1: prev.v1
+			}, tail, ribbon, to));
+			const gain = next.joined * next.unit;
+			const rise = Math.min(next.v0 - 2, step * 1.1), spring = next.v0 - reach(rise);
+			const head = {
+				u: next.u - span * (exit === "band" ? .42 : .5),
+				v0: spring,
+				v1: exit === "band" ? spring + Math.min(gain, rise * .8) : spring + .5
+			};
+			add("New", prev, next, next.joined, FlowGeometry.ribbon(head, {
+				u: next.u,
+				v0: next.v0,
+				v1: next.v0 + gain
+			}, ribbon, to));
+		});
+		for (const stream of [
+			"Retained",
+			"Churned",
+			"New"
+		]) color(stream);
+		this.bands(ctx, "streams", pieces, (piece) => ({
+			title: piece.stream,
+			color: color(piece.stream),
+			rows: [[`${piece.from.label} → ${piece.to.label}`, piece.value]]
+		}), .5);
+		const shape = (d) => FlowGeometry.polygon([
+			to(d.u, d.v0),
+			to(d.u + bar, d.v0),
+			to(d.u + bar, d.v1),
+			to(d.u, d.v1)
+		]);
+		const blocks = ctx.marks("columns", "path", columns, (d) => d.label).attr("fill", ctx.theme.inkSecondary);
+		ctx.set(blocks, { d: shape }, { d: shape }, 12);
+		const first = columns[0]?.active || 1;
+		ctx.hover(blocks, (d) => ({
+			title: d.label,
+			rows: [
+				["Active", d.active],
+				["Lost", d.churned],
+				["Joined", d.joined],
+				["Of first period", `${Math.round(d.active / first * 100)}%`]
+			]
+		}));
+		this.ticks(ctx, "periods", columns.map((column, i) => {
+			if (vertical) return {
+				key: column.label,
+				x: -6,
+				y: column.u + bar / 2,
+				text: column.label,
+				anchor: "end"
+			};
+			const half = FlowTable.width(column.label, 11) / 2;
+			return {
+				key: column.label,
+				x: Math.max(half - 12, Math.min(ctx.plot.width + 12 - half, column.u + bar / 2)),
+				y: 0,
+				text: column.label,
+				anchor: "middle"
+			};
+		}), vertical ? "left" : "bottom");
+		this.labels(ctx, "totals", columns.flatMap((column) => {
+			const [x, y] = to(column.u + bar / 2, (column.v0 + column.v1) / 2);
+			return vertical || bar < 24 ? [] : [{
+				key: column.label,
+				x,
+				y,
+				text: `${Math.round(column.active / first * 100)}`,
+				anchor: "middle",
+				size: 10,
+				fill: ctx.palette.inkOn(ctx.theme.inkSecondary)
+			}];
+		}));
+	}
+};
+export { RetentionExit, RetentionFlow, RetentionScale };

package/dist/charts/flow/RibbonFlow.js

@@ -0,0 +1,187 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { FlowChart } from "./FlowChart.js";
+import { FlowBaseline, FlowRibbon, FlowSort } from "./flowEnums.js";
+import { FlowGeometry } from "./FlowPathKit.js";
+import { FlowTable } from "./FlowTable.js";
+// src/charts/flow/RibbonFlow.ts
+/** `Absolute` keeps column height honest to the total; `Share` fills every column. */
+var RibbonScale = /* @__PURE__ */ function(RibbonScale) {
+	RibbonScale["Absolute"] = "absolute";
+	RibbonScale["Share"] = "share";
+	return RibbonScale;
+}({});
+/** Compare series across periods while showing who overtakes whom: columns re-rank and ribbons trace each series. */
+var RibbonFlow = class extends FlowChart {
+	static meta = {
+		id: "ribbon-flow",
+		name: "Ribbon flow",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Stacks ranked columns and ties each series together with ribbons, revealing changes in rank.",
+		tags: [
+			"ribbon chart",
+			"rank",
+			"overtake"
+		],
+		sample: (seed) => SampleData.categories(seed, 6, 5),
+		variants: {
+			rank: [
+				FlowSort.Descending,
+				FlowSort.Ascending,
+				FlowSort.Input
+			],
+			ribbon: [
+				FlowRibbon.Curved,
+				FlowRibbon.Angular,
+				FlowRibbon.Shoulder
+			],
+			scale: ["absolute", "share"],
+			baseline: [
+				FlowBaseline.Bottom,
+				FlowBaseline.Center,
+				FlowBaseline.Top
+			],
+			orientation: [Orientation.Horizontal, Orientation.Vertical]
+		},
+		valid: (v) => v.scale === "absolute" || v.baseline === FlowBaseline.Bottom
+	};
+	defaults() {
+		return {
+			x: "category",
+			series: "series",
+			y: "value",
+			rank: FlowSort.Descending,
+			ribbon: FlowRibbon.Curved,
+			scale: "absolute",
+			baseline: FlowBaseline.Bottom,
+			orientation: Orientation.Horizontal,
+			bar: .34
+		};
+	}
+	plotMargin() {
+		return this.options.orientation === Orientation.Vertical ? {
+			top: 8,
+			right: 8,
+			bottom: 8,
+			left: 62
+		} : {
+			top: 8,
+			right: 8,
+			bottom: 26,
+			left: 8
+		};
+	}
+	draw(ctx) {
+		const { data, x, series, y, rank, ribbon, scale, baseline, orientation, bar } = this.options;
+		const vertical = orientation === Orientation.Vertical;
+		const to = FlowGeometry.project(orientation);
+		const [length, breadth] = vertical ? [ctx.plot.height, ctx.plot.width] : [ctx.plot.width, ctx.plot.height];
+		const table = FlowTable.pivot(data, x, series, y);
+		const count = table.columns.length;
+		const step = length / Math.max(1, count - 1 + (bar ?? .34));
+		const thick = count > 1 ? step * bar : Math.min(length, 60);
+		const peak = Math.max(1e-9, ...table.columns.map((_, c) => table.series.reduce((total, name) => total + Math.max(0, table.at(c, name)), 0)));
+		const gap = 2;
+		const cells = table.columns.flatMap((_, c) => {
+			const live = table.series.filter((name) => table.at(c, name) > 0);
+			const ordered = FlowTable.sorted(live, rank, (name) => table.at(c, name));
+			const total = ordered.reduce((sum, name) => sum + table.at(c, name), 0);
+			const unit = (breadth - gap * Math.max(0, ordered.length - 1)) / (scale === "share" ? total || 1 : peak);
+			const used = total * unit + gap * Math.max(0, ordered.length - 1);
+			let cursor = baseline === FlowBaseline.Center ? (breadth - used) / 2 : baseline === FlowBaseline.Bottom ? breadth - used : 0;
+			return ordered.map((name, r) => {
+				const v0 = cursor, v1 = cursor + table.at(c, name) * unit;
+				cursor = v1 + gap;
+				return {
+					column: c,
+					label: table.labels[c],
+					series: name,
+					value: table.at(c, name),
+					v0,
+					v1,
+					u: c * step,
+					rank: r + 1
+				};
+			});
+		});
+		const color = (name) => ctx.palette.color(name);
+		for (const name of table.series) color(name);
+		const lookup = new Map(cells.map((cell) => [`${cell.column}/${cell.series}`, cell]));
+		const pairs = cells.flatMap((cell) => {
+			const next = lookup.get(`${cell.column + 1}/${cell.series}`);
+			return next ? [{
+				key: `${cell.series}#${cell.column}`,
+				a: cell,
+				b: next
+			}] : [];
+		});
+		this.bands(ctx, "ribbons", pairs.map((pair) => ({
+			key: pair.key,
+			from: color(pair.a.series),
+			datum: pair,
+			d: FlowGeometry.ribbon({
+				u: pair.a.u + thick,
+				v0: pair.a.v0,
+				v1: pair.a.v1
+			}, {
+				u: pair.b.u,
+				v0: pair.b.v0,
+				v1: pair.b.v1
+			}, ribbon, to)
+		})), ({ a, b }) => ({
+			title: a.series,
+			color: color(a.series),
+			rows: [
+				[a.label, a.value],
+				[b.label, b.value],
+				["Rank", `#${a.rank} → #${b.rank}`]
+			]
+		}), .38);
+		const shape = (d) => FlowGeometry.polygon([
+			to(d.u, d.v0),
+			to(d.u + thick, d.v0),
+			to(d.u + thick, d.v1),
+			to(d.u, d.v1)
+		]);
+		const seed = (d) => FlowGeometry.polygon([
+			to(d.u, d.v0),
+			to(d.u + thick, d.v0),
+			to(d.u + thick, d.v0),
+			to(d.u, d.v0)
+		]);
+		const marks = ctx.marks("cells", "path", cells, (d) => `${d.column}/${d.series}`).attr("fill", (d) => color(d.series));
+		ctx.set(marks, { d: shape }, { d: seed }, 6);
+		ctx.hover(marks, (d) => ({
+			title: d.label,
+			color: color(d.series),
+			rows: [[d.series, d.value], ["Rank", `#${d.rank}`]]
+		}));
+		this.ticks(ctx, "columns", table.columns.map((_, c) => vertical ? {
+			key: `c${c}`,
+			x: -6,
+			y: c * step + thick / 2,
+			text: table.labels[c],
+			anchor: "end"
+		} : {
+			key: `c${c}`,
+			x: c * step + thick / 2,
+			y: 0,
+			text: table.labels[c],
+			anchor: "middle"
+		}), vertical ? "left" : "bottom", 62);
+		this.labels(ctx, "values", cells.filter((cell) => cell.v1 - cell.v0 >= 15 && thick >= 28).map((cell) => {
+			const [cx, cy] = to(cell.u + thick / 2, (cell.v0 + cell.v1) / 2);
+			return {
+				key: `${cell.column}/${cell.series}`,
+				x: cx,
+				y: cy,
+				text: Math.round(cell.value).toLocaleString("en"),
+				anchor: "middle",
+				fill: ctx.palette.inkOn(color(cell.series))
+			};
+		}));
+	}
+};
+export { RibbonFlow, RibbonScale };

package/dist/charts/flow/SankeyChart.js

@@ -0,0 +1,166 @@
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { FlowGraphChart } from "./FlowChart.js";
+import { FlowNodeMark, FlowPaint, FlowRibbon, FlowSort } from "./flowEnums.js";
+import { FlowGeometry } from "./FlowPathKit.js";
+import { FlowSamples } from "./FlowSamples.js";
+import { FlowTable } from "./FlowTable.js";
+import { sankey, sankeyCenter, sankeyJustify, sankeyLeft, sankeyRight } from "d3-sankey";
+// src/charts/flow/SankeyChart.ts
+var SankeyAlign = /* @__PURE__ */ function(SankeyAlign) {
+	SankeyAlign["Justify"] = "justify";
+	SankeyAlign["Left"] = "left";
+	SankeyAlign["Right"] = "right";
+	SankeyAlign["Center"] = "center";
+	return SankeyAlign;
+}({});
+var ALIGN = {
+	["justify"]: sankeyJustify,
+	["left"]: sankeyLeft,
+	["right"]: sankeyRight,
+	["center"]: sankeyCenter
+};
+/** Follow quantities through stages, where band width is the amount. Edges that close a cycle are ignored: use `CircularSankey` for those. */
+var SankeyChart = class extends FlowGraphChart {
+	static meta = {
+		id: "sankey",
+		name: "Sankey diagram",
+		family: ChartFamily.Flow,
+		dimension: Dimension.Two,
+		shape: DataShape.Graph,
+		description: "Shows how quantities split and merge between stages, with band width proportional to the amount.",
+		tags: [
+			"flow",
+			"energy",
+			"budget",
+			"stages"
+		],
+		sample: (seed) => FlowSamples.layered(seed),
+		variants: {
+			orientation: [Orientation.Horizontal, Orientation.Vertical],
+			align: [
+				"justify",
+				"left",
+				"right",
+				"center"
+			],
+			ribbon: [
+				FlowRibbon.Curved,
+				FlowRibbon.Angular,
+				FlowRibbon.Shoulder
+			],
+			nodeMark: [FlowNodeMark.Bar, FlowNodeMark.Hairline],
+			nodeOrder: [FlowSort.Input, FlowSort.Descending]
+		}
+	};
+	defaults() {
+		return {
+			orientation: Orientation.Horizontal,
+			align: "justify",
+			ribbon: FlowRibbon.Curved,
+			nodeMark: FlowNodeMark.Bar,
+			nodeOrder: FlowSort.Input,
+			nodeWidth: 14,
+			nodeGap: 12,
+			paint: FlowPaint.Source
+		};
+	}
+	plotMargin() {
+		return {
+			top: 8,
+			right: 8,
+			bottom: 8,
+			left: 8
+		};
+	}
+	layout(graph, extent) {
+		const { align, nodeMark, nodeWidth, nodeGap, nodeOrder } = this.options;
+		const nodes = graph.vertices.filter(({ id }) => graph.arcs.some((arc) => arc.source === id || arc.target === id)).map((vertex) => ({ ...vertex }));
+		const layout = sankey().nodeId((d) => d.id).nodeAlign(ALIGN[align]).nodeWidth(nodeMark === FlowNodeMark.Hairline ? 4 : nodeWidth).nodePadding(nodeGap).extent(extent);
+		if (nodeOrder !== FlowSort.Input) layout.nodeSort((a, b) => (b.value ?? 0) - (a.value ?? 0));
+		return nodes.length ? layout({
+			nodes,
+			links: graph.arcs.map((arc) => ({ ...arc }))
+		}) : {
+			nodes: [],
+			links: []
+		};
+	}
+	draw(ctx) {
+		const vertical = this.options.orientation === Orientation.Vertical;
+		const to = FlowGeometry.project(this.options.orientation);
+		const graph = this.graph().acyclic();
+		const [length, breadth] = vertical ? [ctx.plot.height, ctx.plot.width] : [ctx.plot.width, ctx.plot.height];
+		const draft = this.layout(graph, [[0, 0], [length, breadth]]).nodes;
+		const last = Math.max(0, ...draft.map((node) => node.depth ?? 0));
+		const gutter = (depth) => vertical ? 16 : Math.min(length * .2, 10 + Math.max(0, ...draft.filter((node) => node.depth === depth).map((node) => FlowTable.width(node.label))));
+		const { nodes, links } = this.layout(graph, [[gutter(0), 0], [length - gutter(last), breadth]]);
+		const color = (node) => ctx.palette.color(node.group ?? node.label);
+		for (const node of nodes) color(node);
+		const ribbons = this.bands(ctx, "links", links.map((link) => {
+			const source = link.source, target = link.target, half = link.width / 2;
+			const a = {
+				u: source.x1,
+				v0: link.y0 - half,
+				v1: link.y0 + half
+			}, b = {
+				u: target.x0,
+				v0: link.y1 - half,
+				v1: link.y1 + half
+			};
+			const [x0, y0] = to(a.u, 0), [x1, y1] = to(b.u, 0);
+			return {
+				key: `${source.id}>${target.id}`,
+				d: FlowGeometry.ribbon(a, b, this.options.ribbon, to),
+				datum: link,
+				...this.tint(ctx, this.options.paint, color(source), color(target), [
+					x0,
+					y0,
+					x1,
+					y1
+				])
+			};
+		}), (link) => ({
+			title: `${link.source.label} → ${link.target.label}`,
+			rows: [["Flow", link.value]],
+			color: color(link.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, Math.max(d.y1, d.y0 + 1)),
+			to(d.x0, Math.max(d.y1, d.y0 + 1))
+		]);
+		ctx.set(blocks, { d: shape }, { d: shape }, 8);
+		ctx.hover(blocks, (d) => ({
+			title: d.label,
+			rows: [["Total", d.value ?? 0]],
+			color: color(d)
+		}));
+		this.trace(blocks, ribbons, ({ datum }, node) => datum.source === node || datum.target === node);
+		this.labels(ctx, "names", nodes.map((node) => {
+			const middle = (node.y0 + node.y1) / 2, depth = node.depth ?? 0;
+			if (vertical) {
+				const y = depth === last ? length - 7 : depth === 0 ? 7 : node.x1 + 9;
+				return {
+					key: node.id,
+					x: middle,
+					y,
+					text: node.label,
+					anchor: "middle",
+					halo: depth !== 0 && depth !== last
+				};
+			}
+			const before = depth === 0;
+			return {
+				key: node.id,
+				x: before ? node.x0 - 6 : node.x1 + 6,
+				y: middle,
+				text: node.label,
+				anchor: before ? "end" : "start",
+				halo: !before && depth !== last
+			};
+		}));
+	}
+};
+export { SankeyAlign, SankeyChart };