@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/ReportCard/ReportCard.model.js

@@ -0,0 +1,399 @@
+import { formatNumber } from "../../lib/vega/formatters.js";
+//#region src/components/ReportCard/ReportCard.model.ts
+/**
+* The default ladder: a four-step grade on a 0–100 scale, lettered for the
+* row column and worded for the headline. `Good` is neutral on purpose —
+* meeting the standard is not a celebration; only `Excellent` earns the
+* positive hue and only `Poor` the negative one.
+*/
+const DEFAULT_REPORT_BANDS = [
+	{
+		key: "excellent",
+		label: "Excellent",
+		short: "A",
+		min: 90,
+		tone: "positive"
+	},
+	{
+		key: "good",
+		label: "Good",
+		short: "B",
+		min: 75,
+		tone: "neutral"
+	},
+	{
+		key: "fair",
+		label: "Fair",
+		short: "C",
+		min: 60,
+		tone: "warning"
+	},
+	{
+		key: "poor",
+		label: "Poor",
+		short: "D",
+		min: 0,
+		tone: "negative"
+	}
+];
+/** The key of the row the long tail folds into. Never collides with a consumer key that is a label. */
+const REPORT_OTHER_KEY = "__other__";
+const DEFAULT_DOMAIN = [0, 100];
+const isFinite = (value) => typeof value === "number" && Number.isFinite(value);
+const clamp = (value, min, max) => value < min ? min : value > max ? max : value;
+const DEFAULT_REPORT_LABELS = {
+	criteriaCount: (count) => `across ${count} ${count === 1 ? "criterion" : "criteria"}`,
+	versusPrevious: "vs previous",
+	increase: "Up",
+	decrease: "Down",
+	unchanged: "No change",
+	points: " pts",
+	outOf: (ceiling) => `/${ceiling}`,
+	notMeasured: (unscored, total) => `${unscored} of ${total} not measured`,
+	rowDetail: ({ label, scoreText, gradeLabel, valueText, targetText, targetScoreText, weightText, note }) => {
+		const parts = [`${label} ${scoreText}${gradeLabel ? ` · ${gradeLabel}` : ""}`];
+		if (valueText) parts.push(targetText ? `${valueText} of ${targetText}` : valueText);
+		if (targetScoreText) parts.push(`expected ${targetScoreText}`);
+		if (weightText) parts.push(weightText);
+		if (note) parts.push(note);
+		return parts.join(" · ");
+	},
+	unscored: "Not measured",
+	noData: "No data",
+	noMatch: "No matching data",
+	clearFilters: "Clear filters",
+	error: "Couldn't load this report",
+	retry: "Try again",
+	insufficient: "No criteria scored yet",
+	stale: "Stale",
+	asOf: "As of",
+	tableCriterion: "Criterion",
+	tableValue: "Value",
+	tableTarget: "Target",
+	tableScore: "Score",
+	tableGrade: "Grade",
+	tableWeight: "Weight",
+	tableShortfall: "Points lost",
+	tableOverall: "Overall",
+	other: "Other criteria",
+	bandsLegend: "Grades",
+	bandRange: (from, to) => `${from}–${to}`,
+	expected: "Expected",
+	selected: "selected",
+	weight: "weight",
+	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} report`,
+	criteriaGroup: (name) => `Choose the criterion ${name} details`,
+	overallSentence: ({ scoreText, gradeLabel, scored, unscored, weighted, source }) => {
+		const grade = gradeLabel ? `, ${gradeLabel}` : "";
+		const how = source === "given" ? "" : source === "min" ? " (the weakest criterion)" : weighted ? " (weighted)" : "";
+		const missing = unscored > 0 ? ` ${unscored} not measured.` : "";
+		return `Overall ${scoreText}${grade}${how} from ${scored} scored ${scored === 1 ? "criterion" : "criteria"}.${missing}`;
+	},
+	criteriaSummary: (count, list) => `${count} ${count === 1 ? "criterion" : "criteria"}: ${list}.`,
+	foldedSummary: (count) => `${count} more folded into Other criteria.`,
+	changeSentence: ({ word, points, previous, previousLabel }) => points ? `${word} ${points} ${previousLabel} (${previous}).` : `${word} ${previousLabel} (${previous}).`,
+	chartDescription: ({ name, count, ceiling, best, bestScore, worst, worstScore, bands }) => `Bullet chart of ${name}: ${count} scored ${count === 1 ? "criterion" : "criteria"} out of ${ceiling} against the ${bands} bands, ` + (count === 1 || best === worst ? `${best} ${bestScore}.` : `strongest ${best} ${bestScore}, weakest ${worst} ${worstScore}.`),
+	insightMark: "Insight"
+};
+function resolveReportLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_REPORT_LABELS,
+		...overrides
+	} : DEFAULT_REPORT_LABELS;
+}
+/**
+* The state machine. Error wins; loading over existing criteria is a refresh
+* (the previous render stays under the veil); criteria with no scores at all
+* is `insufficient` — the rows are real, the grade is not; nothing at all is
+* `no-match` when the consumer's filter caused it and `empty` otherwise.
+*/
+function deriveReportState({ status, hasScore, hasData, filtered }) {
+	if (status === "error") return "error";
+	if (status === "loading") return hasData ? "refreshing" : "loading";
+	if (hasScore) return "ready";
+	if (hasData) return "insufficient";
+	return filtered ? "no-match" : "empty";
+}
+/**
+* Resolves the ladder against the scale: bands sorted low to high, each
+* running up to the next one's floor and the last to the ceiling, clipped to
+* the plotted domain so a stripe never paints outside the axis. Bands wholly
+* below the floor or above the ceiling of the plotted domain are dropped.
+*/
+function normalizeBands(bands, domain) {
+	const [min, max] = domain;
+	const source = (bands && bands.length > 0 ? bands : DEFAULT_REPORT_BANDS).filter((band) => isFinite(band.min)).slice().sort((a, b) => a.min - b.min);
+	const spans = [];
+	source.forEach((band, index) => {
+		const next = source[index + 1];
+		const from = clamp(band.min, min, max);
+		const to = clamp(next ? next.min : max, min, max);
+		if (to <= from) return;
+		spans.push({
+			key: band.key ?? band.label,
+			label: band.label,
+			short: band.short ?? band.label,
+			tone: band.tone ?? "neutral",
+			from,
+			to,
+			index: spans.length
+		});
+	});
+	return spans;
+}
+/** The band a score falls in — the highest band whose floor it reaches; the lowest band catches anything under the ladder. */
+function findBand(bands, score) {
+	if (!isFinite(score) || bands.length === 0) return null;
+	for (let index = bands.length - 1; index >= 0; index -= 1) if (score >= bands[index].from) return bands[index];
+	return bands[0];
+}
+/** The score a criterion resolves to, and the route it took. */
+function resolveScore(criterion, { goodDirection = "up", ceiling = 100 } = {}) {
+	if (isFinite(criterion.score)) return {
+		score: criterion.score,
+		source: "score"
+	};
+	if (!isFinite(criterion.value)) return {
+		score: null,
+		source: "none"
+	};
+	const value = criterion.value;
+	const direction = criterion.goodDirection ?? goodDirection;
+	if (isFinite(criterion.target) && criterion.target !== 0) {
+		const ratio = direction === "down" ? criterion.target / value : value / criterion.target;
+		return {
+			score: Number.isFinite(ratio) ? ratio * ceiling : null,
+			source: "target"
+		};
+	}
+	const range = criterion.range;
+	if (range && isFinite(range[0]) && isFinite(range[1]) && range[0] !== range[1]) {
+		const [worst, best] = range;
+		return {
+			score: (value - worst) / (best - worst) * ceiling,
+			source: "range"
+		};
+	}
+	return {
+		score: null,
+		source: "none"
+	};
+}
+/**
+* Normalises `criteria` for the plot, the rows and the table: keys default to
+* labels (a repeated key is suffixed so two rows never share a band), each
+* criterion resolves to one score on the declared scale, the plotted domain
+* widens to hold any score past the ends (a reading at 140% of target extends
+* the axis rather than clipping to a full bar), the ladder is resolved and
+* clipped to it, rows are sorted if asked, the tail past `maxCriteria` folds
+* into one `Other` row whose score is the *weighted mean* of the folded rows
+* (a mean folds honestly where a sum would not), and every row's contribution
+* and weighted shortfall are computed against the total weight. Returns `null`
+* when there are no criteria to speak of.
+*/
+function normalizeCriteria(criteria, { bands, scoreDomain = DEFAULT_DOMAIN, goodDirection = "up", passing, overallMode = "weighted", overall, sort = "none", maxCriteria, otherLabel }) {
+	if (!criteria) return null;
+	const floor = isFinite(scoreDomain[0]) ? scoreDomain[0] : 0;
+	const ceiling = isFinite(scoreDomain[1]) && scoreDomain[1] > floor ? scoreDomain[1] : floor + 100;
+	const fallbackTick = isFinite(passing) ? passing : null;
+	const seen = /* @__PURE__ */ new Map();
+	let drafts = criteria.map((criterion) => {
+		const base = criterion.key ?? criterion.label;
+		const repeats = seen.get(base) ?? 0;
+		seen.set(base, repeats + 1);
+		const { score, source } = resolveScore(criterion, {
+			goodDirection,
+			ceiling
+		});
+		const weight = isFinite(criterion.weight) && criterion.weight > 0 ? criterion.weight : 1;
+		return {
+			key: repeats === 0 ? base : `${base}·${repeats + 1}`,
+			label: criterion.label,
+			role: "criterion",
+			score,
+			source,
+			value: isFinite(criterion.value) ? criterion.value : null,
+			target: isFinite(criterion.target) ? criterion.target : null,
+			targetScore: isFinite(criterion.targetScore) ? criterion.targetScore : fallbackTick,
+			weight,
+			format: criterion.format,
+			note: criterion.note
+		};
+	});
+	if (sort !== "none") {
+		const rank = (draft) => {
+			if (draft.score == null) return null;
+			if (sort === "impact") return (ceiling - draft.score) * draft.weight;
+			return draft.score;
+		};
+		const direction = sort === "best" || sort === "impact" ? -1 : 1;
+		drafts = drafts.map((draft, index) => ({
+			draft,
+			index
+		})).sort((a, b) => {
+			const av = rank(a.draft);
+			const bv = rank(b.draft);
+			if (av == null && bv == null) return a.index - b.index;
+			if (av == null) return 1;
+			if (bv == null) return -1;
+			return av === bv ? a.index - b.index : (av - bv) * direction;
+		}).map(({ draft }) => draft);
+	}
+	let folded = 0;
+	if (maxCriteria != null && maxCriteria >= 1 && drafts.length > maxCriteria) {
+		const keepCount = Math.max(0, maxCriteria - 1);
+		const kept = drafts.slice(0, keepCount);
+		const rest = drafts.slice(keepCount);
+		if (rest.length >= 2) {
+			const scored = rest.filter((draft) => draft.score != null);
+			const weight = rest.reduce((total, draft) => total + draft.weight, 0);
+			const scoredWeight = scored.reduce((total, draft) => total + draft.weight, 0);
+			const score = scored.length > 0 && scoredWeight > 0 ? scored.reduce((total, draft) => total + draft.score * draft.weight, 0) / scoredWeight : null;
+			drafts = [...kept, {
+				key: REPORT_OTHER_KEY,
+				label: otherLabel,
+				role: "other",
+				score,
+				source: score == null ? "none" : "score",
+				value: null,
+				target: null,
+				targetScore: fallbackTick,
+				weight
+			}];
+			folded = rest.length;
+		}
+	}
+	const scores = drafts.map((draft) => draft.score).filter(isFinite);
+	const domain = [Math.min(floor, ...scores), Math.max(ceiling, ...scores)];
+	const spans = normalizeBands(bands, domain);
+	const totalWeight = drafts.filter((draft) => draft.score != null).reduce((total, draft) => total + draft.weight, 0);
+	const rows = drafts.map((draft) => {
+		const band = findBand(spans, draft.score);
+		return {
+			...draft,
+			plotted: draft.score == null ? null : clamp(draft.score, domain[0], domain[1]),
+			band,
+			tone: band?.tone ?? "neutral",
+			contribution: draft.score != null && totalWeight > 0 ? draft.score * draft.weight / totalWeight : null,
+			shortfall: draft.score != null && totalWeight > 0 ? (ceiling - draft.score) * draft.weight / totalWeight : null
+		};
+	});
+	const scoredRows = rows.filter((row) => row.score != null);
+	let best = null;
+	let worst = null;
+	for (const row of scoredRows) {
+		if (!best || row.score > best.score) best = row;
+		if (!worst || row.score < worst.score) worst = row;
+	}
+	let overallScore = null;
+	let source = overallMode;
+	if (isFinite(overall)) {
+		overallScore = overall;
+		source = "given";
+	} else if (overallMode === "weighted" && totalWeight > 0) overallScore = scoredRows.reduce((total, row) => total + row.score * row.weight, 0) / totalWeight;
+	else if (overallMode === "min" && scoredRows.length > 0) overallScore = worst?.score ?? null;
+	const weights = new Set(scoredRows.map((row) => row.weight));
+	return {
+		rows,
+		bands: spans,
+		domain,
+		floor,
+		ceiling,
+		best,
+		worst,
+		folded,
+		overall: {
+			score: overallScore,
+			band: findBand(spans, overallScore),
+			source,
+			scored: scoredRows.length,
+			unscored: rows.length - scoredRows.length,
+			weight: totalWeight,
+			weighted: weights.size > 1
+		}
+	};
+}
+/** The overall score against `previousScore`, in points. A score is always up-is-good, so the polarity follows the direction. */
+function deriveReportDelta(score, previous, { scoreFormat = "number:0", locale } = {}) {
+	if (!isFinite(score) || !isFinite(previous)) return null;
+	const points = score - previous;
+	const direction = points > 0 ? "up" : points < 0 ? "down" : "flat";
+	return {
+		direction,
+		polarity: direction === "up" ? "positive" : direction === "down" ? "negative" : "neutral",
+		points,
+		text: formatNumber(points, scoreFormat, locale, { signDisplay: "exceptZero" })
+	};
+}
+/** The formatters every text surface shares — headline, rows, detail line, table, tooltip, descriptions. */
+function createReportFormatters({ scoreFormat = "number:0", format = "compact", locale, formatScore, formatValue }) {
+	return {
+		formatScore: (score) => isFinite(score) ? formatScore ? formatScore(score) : formatNumber(score, scoreFormat, locale) : "—",
+		formatValue: (value, own) => isFinite(value) ? formatValue ? formatValue(value) : formatNumber(value, own ?? format, locale) : "—",
+		formatWeight: (weight) => weight === 1 ? null : `×${formatNumber(weight, "number:2", locale)}`
+	};
+}
+const stripSign = (text) => text.replace(/^[+\-−]/, "");
+/**
+* The card's text equivalent (Amy Cesal's alt-text formula: what it is, what
+* it shows, why it is here, when it was true) — the figure's accessible
+* description, and the summary a screen reader gets before the parts. Every
+* criterion is listed with its score and grade, so nothing lives only in the
+* bars, and an unmeasured criterion is named as unmeasured rather than
+* silently missing.
+*/
+function buildReportDescription({ name, state, summary, delta, previousScore, previousLabel, 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}.`;
+	const sentences = [`${name}.`];
+	if (state === "insufficient") sentences.push(`${labels.insufficient}.`);
+	else if (summary) {
+		const { overall, ceiling } = summary;
+		const outOf = summary.floor === 0 ? labels.outOf(formatters.formatScore(ceiling)) : "";
+		sentences.push(labels.overallSentence({
+			scoreText: `${formatters.formatScore(overall.score)}${outOf}`,
+			gradeLabel: overall.band?.label ?? null,
+			scored: overall.scored,
+			unscored: overall.unscored,
+			weighted: overall.weighted,
+			source: overall.source
+		}));
+		if (delta && isFinite(previousScore)) {
+			const word = delta.direction === "up" ? labels.increase : delta.direction === "down" ? labels.decrease : labels.unchanged;
+			sentences.push(labels.changeSentence({
+				word,
+				points: delta.direction === "flat" ? "" : `${stripSign(delta.text)}${labels.points}`,
+				previous: formatters.formatScore(previousScore),
+				previousLabel: previousLabel ?? labels.versusPrevious
+			}));
+		}
+	}
+	if (summary && summary.rows.length > 0) {
+		const list = summary.rows.map((row) => row.score == null ? `${row.label} ${labels.unscored}` : `${row.label} ${formatters.formatScore(row.score)}${row.band ? ` ${row.band.label}` : ""}`).join(", ");
+		sentences.push(labels.criteriaSummary(summary.rows.length, list));
+		if (summary.folded > 0) sentences.push(labels.foldedSummary(summary.folded));
+	}
+	if (asOfText) sentences.push(`${labels.asOf} ${asOfText}.`);
+	return sentences.join(" ");
+}
+/** The plot's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+function buildReportChartDescription({ name, summary, formatters, labels }) {
+	return labels.chartDescription({
+		name,
+		count: summary.overall.scored,
+		ceiling: formatters.formatScore(summary.ceiling),
+		best: summary.best?.label ?? "—",
+		bestScore: formatters.formatScore(summary.best?.score),
+		worst: summary.worst?.label ?? "—",
+		worstScore: formatters.formatScore(summary.worst?.score),
+		bands: summary.bands.map((band) => band.label).join(", ")
+	});
+}
+//#endregion
+export { DEFAULT_REPORT_BANDS, DEFAULT_REPORT_LABELS, REPORT_OTHER_KEY, buildReportChartDescription, buildReportDescription, createReportFormatters, deriveReportDelta, deriveReportState, findBand, normalizeBands, normalizeCriteria, resolveReportLabels, resolveScore };

package/dist/components/ReportCard/index.d.ts

@@ -0,0 +1,4 @@
+import { REPORT_BANDS_DATASET, REPORT_BOUNDS_DATASET, REPORT_MAX_BAR_HEIGHT, REPORT_MAX_PARAM, REPORT_MIN_PARAM, REPORT_TABLE_DATASET, ReportBandPaint, ReportBulletSpecOptions, buildReportBulletSpec } from "./ReportCard.chart.js";
+import { BuildReportDescriptionInput, DEFAULT_REPORT_BANDS, DEFAULT_REPORT_LABELS, DeriveReportStateInput, NormalizeCriteriaOptions, REPORT_OTHER_KEY, ReportBand, ReportBandSpan, ReportBandTone, ReportCardLabels, ReportCardSize, ReportCardState, ReportCardStatus, ReportCriterion, ReportDelta, ReportGoodDirection, ReportHeadline, ReportOverall, ReportOverallExplanation, ReportOverallMode, ReportOverallSource, ReportPolarity, ReportRole, ReportRow, ReportScoreDomain, ReportScoreSource, ReportSort, ReportSummary, ReportTextFormatters, buildReportChartDescription, buildReportDescription, createReportFormatters, deriveReportDelta, deriveReportState, findBand, normalizeBands, normalizeCriteria, resolveReportLabels, resolveScore } from "./ReportCard.model.js";
+import { ReportCard, ReportCardProps } from "./ReportCard.js";
+export { type BuildReportDescriptionInput, DEFAULT_REPORT_BANDS, DEFAULT_REPORT_LABELS, type DeriveReportStateInput, type NormalizeCriteriaOptions, REPORT_BANDS_DATASET, REPORT_BOUNDS_DATASET, REPORT_MAX_BAR_HEIGHT, REPORT_MAX_PARAM, REPORT_MIN_PARAM, REPORT_OTHER_KEY, REPORT_TABLE_DATASET, type ReportBand, type ReportBandPaint, type ReportBandSpan, type ReportBandTone, type ReportBulletSpecOptions, ReportCard, type ReportCardLabels, type ReportCardProps, type ReportCardSize, type ReportCardState, type ReportCardStatus, type ReportCriterion, type ReportDelta, type ReportGoodDirection, type ReportHeadline, type ReportOverall, type ReportOverallExplanation, type ReportOverallMode, type ReportOverallSource, type ReportPolarity, type ReportRole, type ReportRow, type ReportScoreDomain, type ReportScoreSource, type ReportSort, type ReportSummary, type ReportTextFormatters, buildReportBulletSpec, buildReportChartDescription, buildReportDescription, createReportFormatters, deriveReportDelta, deriveReportState, findBand, normalizeBands, normalizeCriteria, resolveReportLabels, resolveScore };

package/dist/components/ReportCard/index.js

@@ -0,0 +1,4 @@
+import { REPORT_BANDS_DATASET, REPORT_BOUNDS_DATASET, REPORT_MAX_BAR_HEIGHT, REPORT_MAX_PARAM, REPORT_MIN_PARAM, REPORT_TABLE_DATASET, buildReportBulletSpec } from "./ReportCard.chart.js";
+import { DEFAULT_REPORT_BANDS, DEFAULT_REPORT_LABELS, REPORT_OTHER_KEY, buildReportChartDescription, buildReportDescription, createReportFormatters, deriveReportDelta, deriveReportState, findBand, normalizeBands, normalizeCriteria, resolveReportLabels, resolveScore } from "./ReportCard.model.js";
+import { ReportCard } from "./ReportCard.js";
+export { DEFAULT_REPORT_BANDS, DEFAULT_REPORT_LABELS, REPORT_BANDS_DATASET, REPORT_BOUNDS_DATASET, REPORT_MAX_BAR_HEIGHT, REPORT_MAX_PARAM, REPORT_MIN_PARAM, REPORT_OTHER_KEY, REPORT_TABLE_DATASET, ReportCard, buildReportBulletSpec, buildReportChartDescription, buildReportDescription, createReportFormatters, deriveReportDelta, deriveReportState, findBand, normalizeBands, normalizeCriteria, resolveReportLabels, resolveScore };

package/dist/components/SankeyCard/SankeyCard.chart.d.ts

@@ -0,0 +1,75 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/SankeyCard/SankeyCard.chart.d.ts
+/** Sampled ribbon edges: `RIBBON_SAMPLES` rows per flow (`SankeyRibbonRow`). */
+declare const SANKEY_RIBBONS_DATASET = "ribbons";
+/** One row per node — the rect, the name and the value line (`SankeyNodeRow`). */
+declare const SANKEY_NODES_DATASET = "nodes";
+/** The pointed flow. */
+declare const SANKEY_HOVER_PARAM = "hover";
+/** The pointed node. */
+declare const SANKEY_NODE_HOVER_PARAM = "nodeHover";
+/**
+ * The reader's chosen node, driven from React with `view.signal`. A VARIABLE
+ * param, not a selection: consumer-owned state pushed into a selection would
+ * live in that selection's `_store` dataset and fight the reader's own
+ * pointer, which is the bridge's rule.
+ */
+declare const SANKEY_SELECTED_PARAM = "selectedNode";
+interface SankeyPlotSpecOptions {
+  /** Plot height in pixels. The width rides the View API. */
+  height: number;
+  /** The node rect's width in pixels — a mark property, never data. */
+  nodeWidth: number;
+  /**
+   * Gutters in pixels. The x domain is [0,1] and the end columns sit ON 0 and
+   * 1, so their rects and names are drawn into the padding: the left gutter
+   * holds half a rect (plus the first column's names when they label
+   * outward), the right holds half a rect plus the last column's names.
+   */
+  padLeft: number;
+  padRight: number;
+  padTop: number;
+  padBottom: number;
+  /**
+   * Vega expression for the pixel budget a name may use before it ellipsizes
+   * rather than clipping at the frame edge. An expression rather than a
+   * number because the budget differs per column — an end column has its
+   * whole gutter, an interior one only the gap to the next column, which is a
+   * fraction of a width the spec must not be rebuilt to learn.
+   */
+  labelLimit: string;
+  /** Draw the node names at all. `false` leaves every name to the table. */
+  labels: boolean;
+  /**
+   * Label the first and last columns OUTWARD, into their gutters. The reading
+   * that never puts a name over a ribbon; interior names have nowhere else to
+   * go, so they sit to the right of their node in the foreground text role.
+   */
+  labelEndsOutward: boolean;
+  /** Print each node's total under its name, for nodes tall enough to hold one. */
+  showValues: boolean;
+  /** Wire the hover selections and the tooltip channel. */
+  tooltip: boolean;
+  /** Wire the selected-node param, so picking a node dims the flows that miss it. */
+  selectable: boolean;
+  /** `arcNumber` grammar for the tooltip's volume. */
+  valueFormat: string;
+  /** Tooltip titles. */
+  fromTitle: string;
+  toTitle: string;
+  valueTitle: string;
+  locale?: string;
+}
+/**
+ * Builds the flow diagram: the ribbons, then the node rects over their ends,
+ * then the names.
+ *
+ * Colour rides the data (`c`, with `scale: null`) rather than a scale, so
+ * whichever job the card gave it — one emphasis hue, the declared polarity,
+ * or an identity slot per outcome — the spec stays structural and re-colouring
+ * is a data push that cannot repaint a survivor it did not mean to.
+ */
+declare function buildSankeyPlotSpec(options: SankeyPlotSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { SANKEY_HOVER_PARAM, SANKEY_NODES_DATASET, SANKEY_NODE_HOVER_PARAM, SANKEY_RIBBONS_DATASET, SANKEY_SELECTED_PARAM, SankeyPlotSpecOptions, buildSankeyPlotSpec };