@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/SankeyCard/SankeyCard.model.js

@@ -0,0 +1,789 @@
+import { formatNumber } from "../../lib/vega/formatters.js";
+//#region src/components/SankeyCard/SankeyCard.model.ts
+/**
+* The theme ships three categorical identity slots (`chart-1…3`), because
+* three of the brand's six hues are reserved for status. An identity encoding
+* past that folds its tail to the context gray instead of repeating a slot.
+*/
+const SANKEY_MAX_IDENTITY = 3;
+/** Below two columns there is no flow to draw — one column is a bar chart, and the card says so instead of drawing a sankey of nothing. */
+const SANKEY_MIN_STAGES = 2;
+/**
+* Below two flows there is nothing to compare. A diagram of ONE ribbon is a
+* picture of a single number: it has no sibling to weigh it against, no split
+* to read a share at, and no chain — every reason this card exists is
+* missing. The reader is better served by a number, so the card declines and
+* says so rather than drawing a decoration.
+*/
+const SANKEY_MIN_FLOWS = 2;
+/** Points sampled along each ribbon edge. Fixed, so a Chromatic baseline never drifts on it. */
+const RIBBON_SAMPLES = 20;
+/** Below this many pixels a ribbon is not a shape a reader can see, whatever it means. */
+const HAIRLINE_PX = 1.5;
+const DEFAULT_SANKEY_LABELS = {
+	noData: "No data",
+	noMatch: "No matching data",
+	clearFilters: "Clear filters",
+	error: "Couldn't load this flow",
+	retry: "Try again",
+	stale: "Stale",
+	asOf: "As of",
+	insufficient: "Not enough flows to compare",
+	tableFrom: "From",
+	tableTo: "To",
+	tableValue: "Volume",
+	tableShare: "Share",
+	tableNode: "Node",
+	tableStage: "Stage",
+	tableIn: "In",
+	tableOut: "Out",
+	tableUnaccounted: "Unaccounted",
+	other: "Other",
+	otherMembers: (list) => `Includes ${list}`,
+	flowTitle: "Volume",
+	shareTitle: "Share of source",
+	selectedNode: (label) => `${label} selected. Its paths are highlighted.`,
+	clearSelection: "Clear selection",
+	selectNode: (label) => `Highlight the paths through ${label}`,
+	showTable: (name) => `Show the data behind ${name}`,
+	hideTable: (name) => `Hide the data behind ${name}`,
+	about: (name) => `About ${name}`,
+	loading: (name) => `Loading ${name}`,
+	tableCaption: (name) => `Data behind the ${name} flow`,
+	flowsCaption: (name) => `Every flow in ${name}`,
+	nodesCaption: (name) => `Every node in ${name}`,
+	cyclesNote: (count) => `${count} ${count === 1 ? "flow was" : "flows were"} left out to keep the diagram readable: a sankey cannot show a loop back to an earlier stage.`,
+	imbalanceNote: (count, amount) => `${amount} arrived at ${count} ${count === 1 ? "node" : "nodes"} without leaving through any listed flow.`,
+	foldedNote: (label) => `The smallest nodes in a stage are grouped as ${label}.`,
+	hairlineNote: (count) => `${count} ${count === 1 ? "flow is" : "flows are"} too thin to see at this scale — the proportions are exact, so read those values in the table.`,
+	overIdentityNote: (max) => `Only the ${max} largest get their own colour; the rest are gray.`,
+	rejectedNote: (count) => `${count} ${count === 1 ? "flow" : "flows"} could not be shown.`,
+	flowSentence: ({ value, total, share, from, to }) => `${value} of ${total} left ${from} for ${to} (${share}).`,
+	lossSentence: ({ value, share, to }) => `The largest loss was ${value} to ${to} (${share}).`,
+	stageSummary: (count, list) => `${count} ${count === 1 ? "stage" : "stages"}: ${list}.`,
+	chartDescription: ({ name, stages, nodes, flows, total, stageList }) => `Sankey flow diagram of ${name}: ${total} across ${stages} ${stages === 1 ? "stage" : "stages"}, ${nodes} ${nodes === 1 ? "node" : "nodes"} and ${flows} ${flows === 1 ? "flow" : "flows"} — ${stageList}.`,
+	insightMark: "Insight",
+	insight: ({ total, from, to, value, share, lossTo, lossValue, lossShare }) => {
+		const segments = [
+			"Of ",
+			{ value: total },
+			` leaving ${from}, `,
+			{ value },
+			` (`,
+			{ value: share },
+			`) went to ${to}`
+		];
+		if (lossTo && lossValue && lossShare) segments.push(`, and the largest loss was `, { value: lossValue }, ` (`, { value: lossShare }, `) to ${lossTo}`);
+		segments.push(".");
+		return segments;
+	}
+};
+function resolveSankeyLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_SANKEY_LABELS,
+		...overrides
+	} : DEFAULT_SANKEY_LABELS;
+}
+/**
+* The state machine. Error wins; loading over existing data is a refresh (the
+* previous render stays under the veil); no flow at all is `no-match` when the
+* consumer's filter caused it and `empty` otherwise.
+*
+* `insufficient` is the honest refusal: a single flow is a picture of one
+* number, with no sibling to compare it against and no chain to follow, so
+* the card declines to draw a sankey of it. The column floor is checked
+* alongside it — a valid flow always spans two columns, so that half is a
+* guard rather than a case, and it keeps the rule true if the depth
+* assignment ever changes.
+*/
+function deriveSankeyState({ status, hasFlow, hasData, filtered, stages, count }) {
+	if (status === "error") return "error";
+	if (status === "loading") return hasData ? "refreshing" : "loading";
+	if (!hasFlow) return filtered ? "no-match" : "empty";
+	if (stages < 2 || count < 2) return "insufficient";
+	return "ready";
+}
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/** Suffix a repeated key so two nodes never share a column slot or a colour. */
+function uniqueKeys(entries, read) {
+	const seen = /* @__PURE__ */ new Map();
+	return entries.map((entry) => {
+		const base = read(entry);
+		const repeats = seen.get(base) ?? 0;
+		seen.set(base, repeats + 1);
+		return repeats === 0 ? base : `${base}·${repeats + 1}`;
+	});
+}
+/**
+* Drops the back edges that make the graph cyclic, in declared order so the
+* result is deterministic. A sankey is a drawing of a DAG: a flow back to an
+* earlier stage has no left-to-right geometry, and the honest response is to
+* leave it out and SAY so — never to draw a ribbon that doubles back, and
+* never to reorder the stages until the cycle disappears.
+*
+* Iterative depth-first search, so a long chain cannot overflow the stack.
+*/
+function breakCycles(nodeKeys, edges) {
+	const outgoing = /* @__PURE__ */ new Map();
+	edges.forEach((edge, index) => {
+		const list = outgoing.get(edge.source);
+		if (list) list.push(index);
+		else outgoing.set(edge.source, [index]);
+	});
+	const state = /* @__PURE__ */ new Map();
+	const dropped = /* @__PURE__ */ new Set();
+	for (const start of nodeKeys) {
+		if (state.get(start)) continue;
+		state.set(start, 1);
+		const stack = [{
+			key: start,
+			cursor: 0
+		}];
+		while (stack.length > 0) {
+			const frame = stack[stack.length - 1];
+			const out = outgoing.get(frame.key) ?? [];
+			if (frame.cursor >= out.length) {
+				state.set(frame.key, 2);
+				stack.pop();
+				continue;
+			}
+			const edgeIndex = out[frame.cursor];
+			frame.cursor += 1;
+			if (dropped.has(edgeIndex)) continue;
+			const next = edges[edgeIndex].target;
+			const seen = state.get(next) ?? 0;
+			if (seen === 1) {
+				dropped.add(edgeIndex);
+				continue;
+			}
+			if (seen === 2) continue;
+			state.set(next, 1);
+			stack.push({
+				key: next,
+				cursor: 0
+			});
+		}
+	}
+	return dropped;
+}
+/** Longest path from a source to each node — the `left` alignment's depth. */
+function longestFromSources(nodeKeys, edges) {
+	const indegree = new Map(nodeKeys.map((key) => [key, 0]));
+	const outgoing = /* @__PURE__ */ new Map();
+	for (const edge of edges) {
+		indegree.set(edge.target, (indegree.get(edge.target) ?? 0) + 1);
+		const list = outgoing.get(edge.source);
+		if (list) list.push(edge);
+		else outgoing.set(edge.source, [edge]);
+	}
+	const depth = new Map(nodeKeys.map((key) => [key, 0]));
+	const queue = nodeKeys.filter((key) => (indegree.get(key) ?? 0) === 0);
+	for (let cursor = 0; cursor < queue.length; cursor += 1) {
+		const key = queue[cursor];
+		for (const edge of outgoing.get(key) ?? []) {
+			depth.set(edge.target, Math.max(depth.get(edge.target) ?? 0, (depth.get(key) ?? 0) + 1));
+			const remaining = (indegree.get(edge.target) ?? 0) - 1;
+			indegree.set(edge.target, remaining);
+			if (remaining === 0) queue.push(edge.target);
+		}
+	}
+	return depth;
+}
+/** Longest path from each node to a sink — the `right` alignment's height. */
+function longestToSinks(nodeKeys, edges) {
+	const outdegree = new Map(nodeKeys.map((key) => [key, 0]));
+	const incoming = /* @__PURE__ */ new Map();
+	for (const edge of edges) {
+		outdegree.set(edge.source, (outdegree.get(edge.source) ?? 0) + 1);
+		const list = incoming.get(edge.target);
+		if (list) list.push(edge);
+		else incoming.set(edge.target, [edge]);
+	}
+	const height = new Map(nodeKeys.map((key) => [key, 0]));
+	const queue = nodeKeys.filter((key) => (outdegree.get(key) ?? 0) === 0);
+	for (let cursor = 0; cursor < queue.length; cursor += 1) {
+		const key = queue[cursor];
+		for (const edge of incoming.get(key) ?? []) {
+			height.set(edge.source, Math.max(height.get(edge.source) ?? 0, (height.get(key) ?? 0) + 1));
+			const remaining = (outdegree.get(edge.source) ?? 0) - 1;
+			outdegree.set(edge.source, remaining);
+			if (remaining === 0) queue.push(edge.source);
+		}
+	}
+	return height;
+}
+/**
+* Normalises `nodes` and `links` into a drawable DAG plus everything the text
+* surfaces read.
+*
+* The order of operations matters and each step is a decision:
+* 1. Keys resolve (a repeat is suffixed), and a link naming a node that does
+*    not exist is rejected rather than inventing one.
+* 2. Flows aggregate — two `A→B` rows are one ribbon — and a negative or
+*    self-looping flow is rejected. Each rejection is COUNTED and reported.
+* 3. Cycles break, deterministically, and are reported.
+* 4. Depths resolve through `align`.
+* 5. A column past `maxNodesPerStage` folds its smallest into `Other`, links
+*    re-route onto the fold and aggregate again. The table still names every
+*    member, so the fold is honest rather than a disappearance.
+* 6. Node values are `max(in, out)`, so an imbalance shows as unfilled node
+*    rather than being balanced away.
+* 7. Colours are assigned by the node's declared POSITION, never its rank, so
+*    filtering cannot repaint the survivors.
+*
+* Returns `null` when there is nothing to speak of.
+*/
+function normalizeSankey(nodes, links, { align = "justify", nodeOrder, color = "none", maxNodesPerStage = 8, palette, emphasis, context, positive, negative, otherLabel }) {
+	if (!links) return null;
+	const rejected = [];
+	const declared = nodes ?? [];
+	const declaredKeys = uniqueKeys(declared, (node) => node.key ?? node.label);
+	const labelOf = /* @__PURE__ */ new Map();
+	const orderIndex = /* @__PURE__ */ new Map();
+	declaredKeys.forEach((key, index) => {
+		labelOf.set(key, declared[index].label);
+		orderIndex.set(key, index);
+	});
+	const knownDeclared = nodes != null;
+	const keys = [...declaredKeys];
+	const admit = (key) => {
+		if (labelOf.has(key)) return true;
+		if (knownDeclared) return false;
+		labelOf.set(key, key);
+		orderIndex.set(key, keys.length);
+		keys.push(key);
+		return true;
+	};
+	const merged = /* @__PURE__ */ new Map();
+	for (const link of links) {
+		const source = String(link.source);
+		const target = String(link.target);
+		if (!isFiniteNumber(link.value) || link.value < 0) {
+			rejected.push({
+				source,
+				target,
+				value: link.value,
+				reason: "negative"
+			});
+			continue;
+		}
+		if (source === target) {
+			rejected.push({
+				source,
+				target,
+				value: link.value,
+				reason: "self-loop"
+			});
+			continue;
+		}
+		if (!admit(source) || !admit(target)) {
+			rejected.push({
+				source,
+				target,
+				value: link.value,
+				reason: "unknown-node"
+			});
+			continue;
+		}
+		const id = `${source}→${target}`;
+		const existing = merged.get(id);
+		if (existing) {
+			existing.value += link.value;
+			existing.label ??= link.label;
+		} else merged.set(id, {
+			source,
+			target,
+			value: link.value,
+			label: link.label,
+			tone: link.tone ?? "neutral"
+		});
+	}
+	let edges = [...merged.values()];
+	if (keys.length === 0) return null;
+	const dropped = breakCycles(keys, edges);
+	let cycles = 0;
+	if (dropped.size > 0) {
+		cycles = dropped.size;
+		edges.forEach((edge, index) => {
+			if (dropped.has(index)) rejected.push({
+				source: edge.source,
+				target: edge.target,
+				value: edge.value,
+				reason: "cycle"
+			});
+		});
+		edges = edges.filter((_, index) => !dropped.has(index));
+	}
+	const fromSources = longestFromSources(keys, edges);
+	const hasOutgoing = new Set(edges.map((edge) => edge.source));
+	const maxFromSources = Math.max(0, ...keys.map((key) => fromSources.get(key) ?? 0));
+	let depthOf;
+	if (align === "right") {
+		const toSinks = longestToSinks(keys, edges);
+		const maxHeight = Math.max(0, ...keys.map((key) => toSinks.get(key) ?? 0));
+		depthOf = new Map(keys.map((key) => [key, maxHeight - (toSinks.get(key) ?? 0)]));
+	} else if (align === "justify") depthOf = new Map(keys.map((key) => [key, hasOutgoing.has(key) ? fromSources.get(key) ?? 0 : maxFromSources]));
+	else depthOf = new Map(keys.map((key) => [key, fromSources.get(key) ?? 0]));
+	const stages = Math.max(0, ...keys.map((key) => depthOf.get(key) ?? 0)) + 1;
+	const cap = Math.max(2, maxNodesPerStage);
+	let folded = false;
+	const foldMembers = /* @__PURE__ */ new Map();
+	const foldTarget = /* @__PURE__ */ new Map();
+	if (keys.length > cap) {
+		const provisional = /* @__PURE__ */ new Map();
+		for (const key of keys) provisional.set(key, 0);
+		for (const edge of edges) {
+			provisional.set(edge.source, (provisional.get(edge.source) ?? 0) + edge.value);
+			provisional.set(edge.target, (provisional.get(edge.target) ?? 0) + edge.value);
+		}
+		for (let depth = 0; depth < stages; depth += 1) {
+			const column = keys.filter((key) => (depthOf.get(key) ?? 0) === depth);
+			if (column.length <= cap) continue;
+			const fold = [...column].sort((a, b) => {
+				const gap = (provisional.get(b) ?? 0) - (provisional.get(a) ?? 0);
+				return gap !== 0 ? gap : (orderIndex.get(a) ?? 0) - (orderIndex.get(b) ?? 0);
+			}).slice(cap - 1);
+			if (fold.length < 2) continue;
+			folded = true;
+			const otherKey = `__other-${depth}__`;
+			labelOf.set(otherKey, otherLabel);
+			depthOf.set(otherKey, depth);
+			orderIndex.set(otherKey, Number.MAX_SAFE_INTEGER - (stages - depth));
+			foldMembers.set(otherKey, fold.map((key) => labelOf.get(key) ?? key));
+			for (const key of fold) foldTarget.set(key, otherKey);
+		}
+	}
+	if (foldTarget.size > 0) {
+		const rerouted = /* @__PURE__ */ new Map();
+		for (const edge of edges) {
+			const source = foldTarget.get(edge.source) ?? edge.source;
+			const target = foldTarget.get(edge.target) ?? edge.target;
+			if (source === target) continue;
+			const id = `${source}→${target}`;
+			const existing = rerouted.get(id);
+			if (existing) existing.value += edge.value;
+			else rerouted.set(id, {
+				...edge,
+				source,
+				target,
+				label: void 0
+			});
+		}
+		edges = [...rerouted.values()];
+		for (const key of foldTarget.keys()) {
+			labelOf.delete(key);
+			orderIndex.delete(key);
+			depthOf.delete(key);
+		}
+	}
+	const liveKeys = [...labelOf.keys()].filter((key) => depthOf.has(key));
+	const inValue = new Map(liveKeys.map((key) => [key, 0]));
+	const outValue = new Map(liveKeys.map((key) => [key, 0]));
+	for (const edge of edges) {
+		outValue.set(edge.source, (outValue.get(edge.source) ?? 0) + edge.value);
+		inValue.set(edge.target, (inValue.get(edge.target) ?? 0) + edge.value);
+	}
+	let overIdentity = false;
+	const identityColor = /* @__PURE__ */ new Map();
+	if (color === "terminal" || color === "node") {
+		const ranked = [...liveKeys.filter((key) => color === "terminal" ? (outValue.get(key) ?? 0) === 0 : (inValue.get(key) ?? 0) === 0)].sort((a, b) => {
+			const gap = Math.max(inValue.get(b) ?? 0, outValue.get(b) ?? 0) - Math.max(inValue.get(a) ?? 0, outValue.get(a) ?? 0);
+			return gap !== 0 ? gap : (orderIndex.get(a) ?? 0) - (orderIndex.get(b) ?? 0);
+		});
+		const slots = Math.min(palette.length, 3);
+		ranked.forEach((key, rank) => {
+			if (rank < slots) identityColor.set(key, palette[rank] ?? emphasis);
+			else overIdentity = true;
+		});
+	}
+	const toneColor = (tone) => tone === "positive" ? positive : tone === "negative" ? negative : emphasis;
+	const resolvedOrder = nodeOrder ?? (knownDeclared ? "declared" : "value");
+	const infos = /* @__PURE__ */ new Map();
+	for (const key of liveKeys) {
+		const inTotal = inValue.get(key) ?? 0;
+		const outTotal = outValue.get(key) ?? 0;
+		infos.set(key, {
+			key,
+			label: labelOf.get(key) ?? key,
+			depth: depthOf.get(key) ?? 0,
+			index: orderIndex.get(key) ?? 0,
+			order: 0,
+			value: Math.max(inTotal, outTotal),
+			inValue: inTotal,
+			outValue: outTotal,
+			imbalance: inTotal - outTotal,
+			isSource: inTotal === 0,
+			isSink: outTotal === 0,
+			folded: foldMembers.has(key),
+			members: foldMembers.get(key) ?? [],
+			color: context
+		});
+	}
+	const columns = Array.from({ length: stages }, () => []);
+	for (const info of infos.values()) columns[info.depth]?.push(info);
+	for (const column of columns) {
+		column.sort((a, b) => {
+			if (a.folded !== b.folded) return a.folded ? 1 : -1;
+			if (resolvedOrder === "value") {
+				const gap = b.value - a.value;
+				if (gap !== 0) return gap;
+			}
+			return a.index - b.index;
+		});
+		column.forEach((info, position) => {
+			info.order = position;
+		});
+	}
+	const linkInfos = edges.map((edge) => {
+		const source = infos.get(edge.source);
+		const target = infos.get(edge.target);
+		const share = source.outValue > 0 ? edge.value / source.outValue : null;
+		const paint = color === "polarity" ? toneColor(edge.tone) : color === "terminal" ? identityColor.get(edge.target) ?? reachableColor(edge.target, edges, identityColor, "forward") ?? context : color === "node" ? identityColor.get(edge.source) ?? reachableColor(edge.source, edges, identityColor, "back") ?? context : emphasis;
+		return {
+			id: `${edge.source}→${edge.target}`,
+			source: edge.source,
+			target: edge.target,
+			sourceLabel: source.label,
+			targetLabel: target.label,
+			label: edge.label,
+			value: edge.value,
+			share,
+			tone: edge.tone,
+			color: paint,
+			depth: source.depth,
+			targetDepth: target.depth
+		};
+	}).sort((a, b) => a.depth - b.depth || b.value - a.value);
+	const orderedNodes = columns.flat();
+	const imbalanced = orderedNodes.filter((node) => Math.abs(node.imbalance) > 0 && !node.isSink && !node.isSource);
+	const total = columns[0]?.reduce((sum, node) => sum + node.value, 0) ?? 0;
+	for (const node of orderedNodes) node.color = color === "terminal" || color === "node" ? identityColor.get(node.key) ?? context : context;
+	return {
+		nodes: orderedNodes,
+		links: linkInfos,
+		columns,
+		stages,
+		total,
+		count: linkInfos.filter((link) => link.value > 0).length,
+		rejected,
+		cycles,
+		imbalanced,
+		folded,
+		overIdentity
+	};
+	/**
+	* The hue for a flow whose coloured endpoint is several hops away: walk the
+	* graph and collect EVERY assigned colour reachable that way.
+	*
+	* One colour reachable means the flow really does end in that outcome, so
+	* it may wear it. Several means it does not — an upstream ribbon that later
+	* splits between Paid and Lapsed belongs to neither, and painting it the
+	* larger one's hue would claim a destination the data does not give it. It
+	* takes the context gray instead, which is what gray is for.
+	*
+	* Memo-free: these graphs are small, and a cache would have to be
+	* invalidated by the fold.
+	*/
+	function reachableColor(key, all, assigned, direction) {
+		const seen = /* @__PURE__ */ new Set([key]);
+		const found = /* @__PURE__ */ new Set();
+		let frontier = [key];
+		while (frontier.length > 0) {
+			const next = [];
+			for (const current of frontier) {
+				const hit = assigned.get(current);
+				if (hit) {
+					found.add(hit);
+					continue;
+				}
+				for (const edge of all) {
+					const from = direction === "forward" ? edge.source : edge.target;
+					const to = direction === "forward" ? edge.target : edge.source;
+					if (from === current && !seen.has(to)) {
+						seen.add(to);
+						next.push(to);
+					}
+				}
+			}
+			frontier = next;
+		}
+		return found.size === 1 ? [...found][0] : void 0;
+	}
+}
+/**
+* Turns a summary into normalised geometry.
+*
+* Vertical: one value→pixel scale shared by every column (d3-sankey's `ky`),
+* so a thickness means the same quantity wherever it appears — the whole
+* point of the diagram. Nodes stack from the top with `nodeGap` between them,
+* then a few relaxation passes slide each node toward the weighted centre of
+* what it connects to and push overlaps apart again; that is what stops the
+* ribbons knotting, and it is capped and deterministic so a baseline never
+* drifts. Each node's flows are then stacked in the order of the partner's
+* position, so ribbons run roughly parallel instead of crossing inside a node.
+*
+* Horizontal: a column is a normalised centre LINE. The node rect straddles
+* it with a pixel width and the ribbons run line to line, passing under the
+* opaque rects — so the geometry carries no pixel width at all and the same
+* rows are correct at every panel width.
+*/
+function layoutSankey(summary, { plotHeight, nodeGap, iterations = 6, curvature = .5, labels = "all", minLabelHeight = 10, formatValue, formatShare, missing }) {
+	const empty = {
+		nodes: [],
+		ribbons: [],
+		columnCenters: [],
+		hairlines: 0
+	};
+	if (!summary || summary.stages < 1 || plotHeight <= 0) return empty;
+	const { columns, links, stages } = summary;
+	let scale = Infinity;
+	for (const column of columns) {
+		if (column.length === 0) continue;
+		const gaps = (column.length - 1) * nodeGap;
+		const sum = column.reduce((total, node) => total + node.value, 0);
+		const available = Math.max(1, plotHeight - gaps);
+		scale = Math.min(scale, sum > 0 ? available / sum : Infinity);
+	}
+	if (!Number.isFinite(scale)) scale = 0;
+	const top = /* @__PURE__ */ new Map();
+	const height = /* @__PURE__ */ new Map();
+	for (const column of columns) {
+		let y = 0;
+		for (const node of column) {
+			const h = node.value * scale;
+			top.set(node.key, y);
+			height.set(node.key, h);
+			y += h + nodeGap;
+		}
+	}
+	const incoming = /* @__PURE__ */ new Map();
+	const outgoing = /* @__PURE__ */ new Map();
+	for (const link of links) {
+		const outList = outgoing.get(link.source);
+		if (outList) outList.push(link);
+		else outgoing.set(link.source, [link]);
+		const inList = incoming.get(link.target);
+		if (inList) inList.push(link);
+		else incoming.set(link.target, [link]);
+	}
+	const center = (key) => (top.get(key) ?? 0) + (height.get(key) ?? 0) / 2;
+	const pull = (node, side) => {
+		const list = (side === "in" ? incoming.get(node.key) : outgoing.get(node.key)) ?? [];
+		let weight = 0;
+		let sum = 0;
+		for (const link of list) {
+			if (link.value <= 0) continue;
+			sum += center(side === "in" ? link.source : link.target) * link.value;
+			weight += link.value;
+		}
+		return weight > 0 ? sum / weight : null;
+	};
+	const resolveCollisions = () => {
+		for (const column of columns) {
+			if (column.length === 0) continue;
+			let limit = 0;
+			for (const node of column) {
+				const y = Math.max(top.get(node.key) ?? 0, limit);
+				top.set(node.key, y);
+				limit = y + (height.get(node.key) ?? 0) + nodeGap;
+			}
+			let floor = plotHeight;
+			for (let index = column.length - 1; index >= 0; index -= 1) {
+				const node = column[index];
+				const h = height.get(node.key) ?? 0;
+				const y = Math.min(top.get(node.key) ?? 0, floor - h);
+				top.set(node.key, Math.max(0, y));
+				floor = (top.get(node.key) ?? 0) - nodeGap;
+			}
+		}
+	};
+	resolveCollisions();
+	const passes = Math.max(0, Math.min(24, iterations));
+	let alpha = 1;
+	for (let pass = 0; pass < passes; pass += 1) {
+		alpha *= .99;
+		for (let depth = stages - 2; depth >= 0; depth -= 1) for (const node of columns[depth] ?? []) {
+			const target = pull(node, "out");
+			if (target == null) continue;
+			const shift = (target - center(node.key)) * alpha;
+			top.set(node.key, (top.get(node.key) ?? 0) + shift);
+		}
+		resolveCollisions();
+		for (let depth = 1; depth < stages; depth += 1) for (const node of columns[depth] ?? []) {
+			const target = pull(node, "in");
+			if (target == null) continue;
+			const shift = (target - center(node.key)) * alpha;
+			top.set(node.key, (top.get(node.key) ?? 0) + shift);
+		}
+		resolveCollisions();
+	}
+	const byPartner = (list, side) => [...list].sort((a, b) => {
+		const gap = center(side === "source" ? a.source : a.target) - center(side === "source" ? b.source : b.target);
+		return gap !== 0 ? gap : a.value === b.value ? a.id.localeCompare(b.id) : b.value - a.value;
+	});
+	const sourceTop = /* @__PURE__ */ new Map();
+	const targetTop = /* @__PURE__ */ new Map();
+	for (const node of summary.nodes) {
+		let offset = top.get(node.key) ?? 0;
+		for (const link of byPartner(outgoing.get(node.key) ?? [], "target")) {
+			sourceTop.set(link.id, offset);
+			offset += link.value * scale;
+		}
+		let inset = top.get(node.key) ?? 0;
+		for (const link of byPartner(incoming.get(node.key) ?? [], "source")) {
+			targetTop.set(link.id, inset);
+			inset += link.value * scale;
+		}
+	}
+	const columnX = (depth) => stages > 1 ? depth / (stages - 1) : .5;
+	const norm = (pixels) => pixels / plotHeight;
+	const ease = Math.max(0, Math.min(1, curvature));
+	const nodeRows = summary.nodes.map((node) => {
+		const y = top.get(node.key) ?? 0;
+		const h = height.get(node.key) ?? 0;
+		const first = node.depth === 0;
+		const last = node.depth === stages - 1;
+		return {
+			k: node.key,
+			x: columnX(node.depth),
+			y: norm(y),
+			y2: norm(y + h),
+			mid: norm(y + h / 2),
+			h,
+			label: node.label,
+			vt: formatValue(node.value),
+			c: node.color,
+			first,
+			last,
+			lab: labels === "none" ? false : labels === "ends" ? (first || last) && h >= minLabelHeight : h >= minLabelHeight
+		};
+	});
+	const ribbonRows = [];
+	let hairlines = 0;
+	for (const link of links) {
+		if (link.value <= 0) continue;
+		const thickness = link.value * scale;
+		if (thickness < 1.5) hairlines += 1;
+		const y0 = sourceTop.get(link.id) ?? 0;
+		const y1 = targetTop.get(link.id) ?? 0;
+		const x0 = columnX(link.depth);
+		const x1 = columnX(link.targetDepth);
+		const shareText = link.share == null ? missing : formatShare(link.share);
+		for (let sample = 0; sample < 20; sample += 1) {
+			const t = sample / 19;
+			const w = ease * (t * t * (3 - 2 * t)) + (1 - ease) * t;
+			const topEdge = y0 + (y1 - y0) * w;
+			ribbonRows.push({
+				id: link.id,
+				x: x0 + (x1 - x0) * t,
+				y: norm(topEdge),
+				y2: norm(topEdge + thickness),
+				c: link.color,
+				sl: link.sourceLabel,
+				tl: link.targetLabel,
+				v: link.value,
+				sh: shareText,
+				s: link.source,
+				t: link.target
+			});
+		}
+	}
+	return {
+		nodes: nodeRows,
+		ribbons: ribbonRows,
+		columnCenters: Array.from({ length: stages }, (_, depth) => columnX(depth)),
+		hairlines
+	};
+}
+function createSankeyFormatters({ format, shareFormat, locale, formatValue }) {
+	return {
+		formatValue: (value) => isFiniteNumber(value) ? formatValue ? formatValue(value) : formatNumber(value, format, locale) : "—",
+		formatShare: (share) => isFiniteNumber(share) ? formatNumber(share, shareFormat, locale) : "—"
+	};
+}
+/**
+* What the diagram is about: the largest flow leaving the first stage, and
+* the largest declared loss anywhere. Only a link the consumer TONED as
+* negative counts as a loss — the card never decides on its own that an
+* outcome is bad.
+*/
+function deriveSankeyHighlights(summary) {
+	if (!summary || summary.count === 0) return null;
+	const drawable = summary.links.filter((link) => link.value > 0);
+	const firstStage = drawable.filter((link) => link.depth === 0);
+	const main = (firstStage.length > 0 ? firstStage : drawable).reduce((best, link) => link.value > best.value ? link : best);
+	const losses = drawable.filter((link) => link.tone === "negative");
+	const loss = losses.length > 0 ? losses.reduce((worst, link) => link.value > worst.value ? link : worst) : null;
+	return {
+		main,
+		loss: loss && loss.id !== main.id ? loss : null
+	};
+}
+/** The figure's generated description: the volume, the stages, the main flow, the largest loss, the caveats and the as-of. */
+function buildSankeyDescription({ name, state, summary, formatters, asOfText, labels }) {
+	if (state === "loading") return labels.loading(name);
+	if (state === "error") return `${name}: ${labels.error}`;
+	if (state === "empty") return `${name}: ${labels.noData}`;
+	if (state === "no-match") return `${name}: ${labels.noMatch}`;
+	if (state === "insufficient") return `${name}: ${labels.insufficient}`;
+	if (!summary) return name;
+	const parts = [`${name}.`];
+	const highlights = deriveSankeyHighlights(summary);
+	if (highlights) {
+		parts.push(labels.flowSentence({
+			value: formatters.formatValue(highlights.main.value),
+			total: formatters.formatValue(summary.total),
+			share: formatters.formatShare(highlights.main.share),
+			from: highlights.main.sourceLabel,
+			to: highlights.main.targetLabel
+		}));
+		if (highlights.loss) parts.push(labels.lossSentence({
+			value: formatters.formatValue(highlights.loss.value),
+			share: formatters.formatShare(highlights.loss.share),
+			to: highlights.loss.targetLabel
+		}));
+	}
+	parts.push(labels.stageSummary(summary.stages, summary.columns.map((column) => column.map((node) => node.label).join(" / ")).filter(Boolean).join(" → ") || "—"));
+	if (summary.cycles > 0) parts.push(labels.cyclesNote(summary.cycles));
+	if (summary.imbalanced.length > 0) {
+		const amount = summary.imbalanced.reduce((sum, node) => sum + Math.abs(node.imbalance), 0);
+		parts.push(labels.imbalanceNote(summary.imbalanced.length, formatters.formatValue(amount)));
+	}
+	if (summary.folded) parts.push(labels.foldedNote(labels.other));
+	if (summary.overIdentity) parts.push(labels.overIdentityNote(3));
+	if (asOfText) parts.push(`${labels.asOf} ${asOfText}.`);
+	return parts.join(" ");
+}
+/** The plot's own `aria-label` — the form, the volume, the stages. */
+function buildSankeyChartDescription({ name, summary, formatters, labels }) {
+	return labels.chartDescription({
+		name,
+		stages: summary.stages,
+		nodes: summary.nodes.length,
+		flows: summary.count,
+		total: formatters.formatValue(summary.total),
+		stageList: summary.columns.map((column) => column.map((node) => node.label).join(" / ")).filter(Boolean).join(" → ") || "—"
+	});
+}
+/** The generated insight, as segments so the values render bold and the words stay plain. */
+function buildSankeyInsight({ name, summary, formatters, labels }) {
+	const highlights = deriveSankeyHighlights(summary);
+	if (!summary || !highlights) return null;
+	return labels.insight({
+		name,
+		total: formatters.formatValue(summary.total),
+		from: highlights.main.sourceLabel,
+		to: highlights.main.targetLabel,
+		value: formatters.formatValue(highlights.main.value),
+		share: formatters.formatShare(highlights.main.share),
+		lossTo: highlights.loss?.targetLabel ?? null,
+		lossValue: highlights.loss ? formatters.formatValue(highlights.loss.value) : null,
+		lossShare: highlights.loss ? formatters.formatShare(highlights.loss.share) : null
+	});
+}
+/** The plain-text reading of insight segments — for descriptions and tests. */
+function sankeyInsightToText(segments) {
+	return segments.map((segment) => typeof segment === "string" ? segment : segment.value).join("");
+}
+//#endregion
+export { DEFAULT_SANKEY_LABELS, HAIRLINE_PX, RIBBON_SAMPLES, SANKEY_MAX_IDENTITY, SANKEY_MIN_FLOWS, SANKEY_MIN_STAGES, buildSankeyChartDescription, buildSankeyDescription, buildSankeyInsight, createSankeyFormatters, deriveSankeyHighlights, deriveSankeyState, layoutSankey, normalizeSankey, resolveSankeyLabels, sankeyInsightToText };