@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/HighlightCard/HighlightCard.model.js

@@ -0,0 +1,875 @@
+import { formatDate, formatDateRange, formatDelta, formatNumber, parseArcNumberFormat } from "../../lib/vega/formatters.js";
+//#region src/components/HighlightCard/HighlightCard.model.ts
+const DEFAULT_SIGMA_THRESHOLDS = {
+	notable: 1,
+	unusual: 2,
+	extreme: 3
+};
+const DEFAULT_PERCENTILE_THRESHOLDS = {
+	notable: 40,
+	unusual: 45,
+	extreme: 49
+};
+const DEFAULT_HIGHLIGHT_LABELS = {
+	severityNames: {
+		typical: "Typical",
+		notable: "Notable",
+		unusual: "Unusual",
+		extreme: "Extreme"
+	},
+	increase: "Up",
+	decrease: "Down",
+	unchanged: "No change",
+	percentagePoints: " pp",
+	contextTitle: "In context",
+	peersTitle: "How unusual",
+	driversTitle: "What drove it",
+	noData: "No data",
+	noMatch: "No matching data",
+	clearFilters: "Clear filters",
+	error: "Couldn't load this highlight",
+	retry: "Try again",
+	unresolved: "The highlighted period has no two readings to compare",
+	insufficientPeers: "Not enough comparable periods to say how unusual this is",
+	stale: "Stale",
+	asOf: "As of",
+	tablePeriod: "Period",
+	tableValue: "Value",
+	tableStep: "Step",
+	tableChange: "Change",
+	tableShare: "Share",
+	tableDriver: "Driver",
+	tableWindow: "Window",
+	windowStart: "Start",
+	windowEnd: "End",
+	windowChange: "Change",
+	windowChangePercent: "Change %",
+	windowPeriod: "Period",
+	windowPeak: "Peak",
+	windowTrough: "Trough",
+	windowSteepest: "Steepest step",
+	highlighted: "highlighted",
+	peerMean: "Typical change",
+	peerSd: "Standard deviation",
+	peerTypical: "Typical range",
+	peerRank: "Rank",
+	peerPercentile: "Percentile",
+	peerZ: "Distance from typical",
+	peerThis: "This period",
+	peerCount: "Compared periods",
+	driverTotal: "Total change",
+	driverExplained: "Explained",
+	driverResidual: "Unexplained",
+	driverOther: "Other",
+	driverContribution: "Contribution",
+	insightMark: "Generated insight",
+	about: (name) => `About ${name}`,
+	loading: (name) => `Loading ${name}`,
+	showTable: (name) => `Show the data behind ${name}`,
+	hideTable: (name) => `Hide the data behind ${name}`,
+	windowDetails: (name) => `Details of the ${name} highlight`,
+	driversGroup: (name) => `What drove the ${name} highlight`,
+	selectDriver: (label) => `Drill into ${label}`,
+	driverSelected: ({ label, contribution, share }) => `${label}: ${contribution}${share ? `, ${share} of the change` : ""}.`,
+	tableCaption: (name) => `Data behind the ${name} highlight`,
+	peersCaption: ({ count, readings, mode }) => `Compared with ${count} ${mode === "rolling" ? "overlapping" : "non-overlapping"} ${readings}-reading period${count === 1 ? "" : "s"} in the same series.`,
+	driversCaption: ({ total, explained, residual, reconciles }) => reconciles ? `Contributions sum to ${explained} of the ${total} change.` : `Contributions sum to ${explained} of the ${total} change; ${residual} is unexplained.`,
+	foldedCaption: (folded, label) => `${folded} smaller contributors folded into ${label}.`,
+	windowLine: ({ range, label }) => label ? `${label} · ${range}` : range,
+	windowExplanation: ({ periodText, startText, endText, changeText, secondaryText, renderedMode, direction, peakText, troughText, steepestText }) => {
+		const rows = [
+			["Period", periodText],
+			["Start", startText],
+			["End", endText]
+		];
+		rows.push([direction === "up" ? "Increase" : direction === "down" ? "Decrease" : "No change", changeText]);
+		if (secondaryText) rows.push([renderedMode === "percent" ? "Change" : "Change %", secondaryText]);
+		if (peakText) rows.push(["Peak", peakText]);
+		if (troughText) rows.push(["Trough", troughText]);
+		if (steepestText) rows.push(["Steepest step", steepestText]);
+		return rows;
+	},
+	peerExplanation: (stats) => {
+		const rows = [
+			["This period", stats.changeText],
+			["Rank", stats.rankText],
+			["Typical range", stats.typicalText]
+		];
+		if (stats.baseline === "sigma") {
+			rows.push(["Typical change", stats.meanText]);
+			if (stats.z != null) rows.push(["Distance from typical", stats.zText]);
+		} else rows.push(["Percentile", stats.percentileText]);
+		rows.push(["Compared periods", String(stats.count)]);
+		return rows;
+	},
+	peerVerdict: ({ severity, rank, total, typical, change, inside }) => {
+		const place = rank === "1st" ? "the largest" : `the ${rank} largest`;
+		const scale = `${total} period${total === 1 ? "" : "s"} this length`;
+		if (severity === "typical" || inside) return `${change} is ${place} of ${scale} — inside the typical range of ${typical}.`;
+		return `${change} is ${place} of ${scale}, outside the typical range of ${typical}.`;
+	},
+	contextDescription: ({ mark, name, count, first, last, min, max, range, label, direction, change }) => `${mark} chart of ${name}: ${count} readings from ${first} to ${last}, ranging ${min} to ${max}. The highlighted period ${label ? `${label} (${range})` : range} is painted in the polarity hue and ${direction === "flat" ? "did not change" : `moved ${change}`}.`,
+	peersDescription: ({ name, count, readings, mode, change, rank, typical, severity }) => `Strip plot of the change in ${name} across ${count} ${mode === "rolling" ? "overlapping" : "non-overlapping"} ${readings}-reading periods. The highlighted period changed ${change}, the ${rank} largest, against a typical range of ${typical} — ${severity}.`,
+	driversDescription: ({ name, count, total, top, topContribution, counter, counterContribution, residual }) => `Bar chart of ${count} contributor${count === 1 ? "" : "s"} to the ${total} change in ${name}.` + (top && topContribution ? ` Largest: ${top} at ${topContribution}.` : "") + (counter && counterContribution ? ` Largest against it: ${counter} at ${counterContribution}.` : "") + (residual ? ` ${residual} is unexplained.` : ""),
+	cardDescription: (input) => {
+		const { name, state, range, label, direction, change, secondary, startText, endText, severity, rank, count, driverCount, topDriver, topContribution, asOf } = input;
+		if (state === "loading") return `Loading the ${name} highlight.`;
+		if (state === "error") return `The ${name} highlight could not be loaded.`;
+		if (state === "empty") return `No data for the ${name} highlight.`;
+		if (state === "no-match") return `No ${name} readings match the current filters.`;
+		let text = `Highlight analysis of ${name} over ${label ? `${label} (${range})` : range}: ${direction === "up" ? "rose" : direction === "down" ? "fell" : "held flat"}${change ? ` ${change}` : ""}${secondary ? ` (${secondary})` : ""}, from ${startText} to ${endText}.`;
+		if (severity && rank && count != null) text += ` That is the ${rank} of ${count + 1} comparable periods — ${severity}.`;
+		if (driverCount > 0 && topDriver && topContribution) text += ` Largest contributor: ${topDriver} at ${topContribution}.`;
+		if (asOf) text += ` As of ${asOf}.`;
+		return text;
+	},
+	insight: (input) => {
+		const { name, direction, change, secondary, range, label, severity, rank, count, topDriver, topContribution, topShare } = input;
+		const period = label ? `${label} (${range})` : range;
+		const segments = [`${name} ${direction === "up" ? "rose" : direction === "down" ? "fell" : "held flat"}`];
+		if (change) {
+			segments.push(" ");
+			segments.push({ value: change });
+			if (secondary) segments.push(` (${secondary})`);
+		}
+		segments.push(` over ${period}`);
+		if (rank && count != null) {
+			segments.push(", the ");
+			segments.push({ value: rank });
+			segments.push(` of ${count + 1} comparable periods (${severity.toLowerCase()})`);
+		}
+		if (topDriver && topContribution) {
+			segments.push(". ");
+			segments.push({ value: topDriver });
+			segments.push(" contributed ");
+			segments.push({ value: topContribution });
+			if (topShare) segments.push(` (${topShare} of the move)`);
+		}
+		segments.push(".");
+		return segments;
+	},
+	markNames: {
+		line: "Line",
+		area: "Area",
+		bar: "Bar"
+	},
+	peerModeNames: {
+		rolling: "overlapping",
+		adjacent: "non-overlapping"
+	}
+};
+function resolveHighlightLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_HIGHLIGHT_LABELS,
+		...overrides
+	} : DEFAULT_HIGHLIGHT_LABELS;
+}
+/**
+* The state the panel renders, from the transport's status and the data.
+* `loading` with data already present is a refresh: the previous render stays
+* under the veil rather than collapsing to a skeleton.
+*/
+function deriveHighlightState({ status, hasData, filtered }) {
+	if (status === "error") return "error";
+	if (status === "loading") return hasData ? "refreshing" : "loading";
+	if (!hasData) return filtered ? "no-match" : "empty";
+	return "ready";
+}
+const isFinite = (value) => typeof value === "number" && Number.isFinite(value);
+const DAY_MS = 864e5;
+const ISO_DATE = /^\d{4}-\d{2}(-\d{2})?([T ].*)?$/;
+function inferXType(points) {
+	const sample = points.find((point) => point.x != null);
+	if (!sample) return "ordinal";
+	const { x } = sample;
+	if (x instanceof Date) return "temporal";
+	if (typeof x === "number") return "quantitative";
+	return ISO_DATE.test(x) ? "temporal" : "ordinal";
+}
+function inferGranularity(rows) {
+	const xs = rows.map((row) => row.x).filter((x) => typeof x === "number");
+	if (xs.length < 2) return "day";
+	const gaps = [];
+	for (let index = 1; index < xs.length; index += 1) gaps.push(Math.abs(xs[index] - xs[index - 1]));
+	gaps.sort((a, b) => a - b);
+	const median = gaps[Math.floor(gaps.length / 2)];
+	if (median < DAY_MS) return "time";
+	if (median >= 360 * DAY_MS) return "year";
+	if (median >= 27 * DAY_MS) return "month";
+	return "day";
+}
+/**
+* Normalises `series` for Vega and the tables: temporal `x` becomes epoch
+* milliseconds (a bare number is quantitative — pass a `Date` or an ISO string
+* for time), invalid dates are dropped, `null` readings stay as gaps, and the
+* range is summarised for the text equivalents. Rows are sorted along the axis
+* for a temporal or quantitative series, so a window can be snapped and peer
+* windows can be walked; an ordinal series keeps the consumer's order, which
+* IS its axis. Returns `null` without a series at all.
+*/
+function normalizeHighlightSeries(points, granularity) {
+	if (!points) return null;
+	const xType = inferXType(points);
+	const rows = [];
+	for (const point of points) {
+		const y = isFinite(point.y) ? point.y : null;
+		if (xType === "temporal") {
+			const time = point.x instanceof Date ? point.x.getTime() : new Date(point.x).getTime();
+			if (Number.isNaN(time)) continue;
+			rows.push({
+				x: time,
+				y
+			});
+		} else if (xType === "quantitative") {
+			if (!isFinite(point.x)) continue;
+			rows.push({
+				x: point.x,
+				y
+			});
+		} else rows.push({
+			x: String(point.x),
+			y
+		});
+	}
+	if (xType !== "ordinal") rows.sort((a, b) => a.x - b.x);
+	const valid = rows.filter((row) => row.y != null);
+	const values = valid.map((row) => row.y);
+	return {
+		rows,
+		xType,
+		count: valid.length,
+		first: rows[0] ?? null,
+		last: rows[rows.length - 1] ?? null,
+		latest: valid.length > 0 ? valid[valid.length - 1] : null,
+		min: values.length > 0 ? Math.min(...values) : null,
+		max: values.length > 0 ? Math.max(...values) : null,
+		granularity: granularity ?? (xType === "temporal" ? inferGranularity(rows) : "day")
+	};
+}
+/** The formatters every text surface shares — headline, badges, strip, bars, tables, tooltips, descriptions. */
+function createHighlightFormatters({ format, locale, timeZone, formatValue, xType, granularity, deltaMode, percentagePoints }) {
+	const signed = { signDisplay: "exceptZero" };
+	const spec = parseArcNumberFormat(format);
+	const formatX = (x) => {
+		if (xType === "temporal" && typeof x === "number") return formatDate(x, {
+			granularity,
+			locale,
+			timeZone
+		});
+		if (xType === "quantitative" && typeof x === "number") return formatNumber(x, "number", locale);
+		return String(x);
+	};
+	const formatAmountChange = (delta) => spec.kind === "percent" ? `${formatNumber(delta * 100, `number:${spec.digits ?? 1}`, locale, signed)}${percentagePoints}` : formatNumber(delta, format, locale, signed);
+	return {
+		formatY: (value) => isFinite(value) ? formatValue ? formatValue(value) : formatNumber(value, format, locale) : "—",
+		formatX,
+		formatXRange: (start, end) => xType === "temporal" && typeof start === "number" && typeof end === "number" ? formatDateRange(start, end, {
+			granularity,
+			locale,
+			timeZone
+		}) : `${formatX(start)} – ${formatX(end)}`,
+		formatAmountChange,
+		formatPeerChange: (change) => deltaMode === "percent" ? formatNumber(change, "percent:1", locale, signed) : formatAmountChange(change),
+		formatShare: (share) => share == null ? "—" : formatNumber(share, "percent:0", locale)
+	};
+}
+/** The change between two readings, with polarity resolved through `goodDirection`. */
+function deriveHighlightDelta(value, previousValue, { deltaMode, goodDirection, format, locale, percentagePoints }) {
+	if (!isFinite(value) || !isFinite(previousValue)) return null;
+	const options = {
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	};
+	const delta = formatDelta(value, previousValue, {
+		...options,
+		mode: deltaMode
+	});
+	const other = formatDelta(value, previousValue, {
+		...options,
+		mode: delta.renderedMode === "percent" ? "absolute" : "percent"
+	});
+	let polarity = "neutral";
+	if (delta.direction !== "flat" && goodDirection !== "none") polarity = delta.direction === "up" === (goodDirection === "up") ? "positive" : "negative";
+	return {
+		direction: delta.direction,
+		polarity,
+		text: delta.text,
+		renderedMode: delta.renderedMode,
+		secondaryText: other.renderedMode === delta.renderedMode ? null : other.text
+	};
+}
+const stripSign = (text) => text.replace(/^[+\-−]/, "");
+function normalizeBound(value, xType) {
+	if (xType === "temporal") {
+		const time = value instanceof Date ? value.getTime() : new Date(value).getTime();
+		return Number.isNaN(time) ? null : time;
+	}
+	if (xType === "quantitative") {
+		const numeric = typeof value === "number" ? value : Number(value);
+		return Number.isFinite(numeric) ? numeric : null;
+	}
+	return String(value);
+}
+/**
+* Snaps the window onto the series and measures it. Each bound moves inward to
+* the nearest finite reading (a temporal or quantitative bound need not hit a
+* reading exactly; an ordinal bound is a category label), the bounds may come
+* in either order, and the result is `null` when the window does not hold two
+* distinct finite readings — the panel then says so and stamps
+* `data-window="unresolved"` rather than inventing a change.
+*
+* Beyond the change it records the window's ANATOMY, which is what makes this
+* a highlight-analysis panel rather than a tile: every reading inside it, the
+* step between each consecutive pair, the peak, the trough and the steepest
+* single step.
+*/
+function resolveHighlightWindow(summary, window, { deltaMode, goodDirection, format, locale, percentagePoints, formatters }) {
+	if (!summary || !window) return null;
+	const { rows, xType } = summary;
+	const lo = normalizeBound(window.start, xType);
+	const hi = normalizeBound(window.end, xType);
+	if (lo == null || hi == null) return null;
+	let startIndex = -1;
+	let endIndex = -1;
+	if (xType === "ordinal") {
+		const first = rows.findIndex((row) => row.x === lo);
+		const second = rows.findIndex((row) => row.x === hi);
+		if (first < 0 || second < 0) return null;
+		const [from, to] = first <= second ? [first, second] : [second, first];
+		for (let index = from; index <= to; index += 1) if (rows[index].y != null) {
+			startIndex = index;
+			break;
+		}
+		for (let index = to; index >= from; index -= 1) if (rows[index].y != null) {
+			endIndex = index;
+			break;
+		}
+	} else {
+		const from = Math.min(lo, hi);
+		const to = Math.max(lo, hi);
+		for (let index = 0; index < rows.length; index += 1) {
+			const row = rows[index];
+			const at = row.x;
+			if (at < from || at > to || row.y == null) continue;
+			if (startIndex < 0) startIndex = index;
+			endIndex = index;
+		}
+	}
+	if (startIndex < 0 || endIndex < 0 || startIndex === endIndex) return null;
+	const startRow = rows[startIndex];
+	const endRow = rows[endIndex];
+	const start = {
+		x: startRow.x,
+		y: startRow.y,
+		index: startIndex
+	};
+	const end = {
+		x: endRow.x,
+		y: endRow.y,
+		index: endIndex
+	};
+	const delta = deriveHighlightDelta(end.y, start.y, {
+		deltaMode,
+		goodDirection,
+		format,
+		locale,
+		percentagePoints
+	});
+	if (!delta) return null;
+	const absoluteDelta = formatDelta(end.y, start.y, {
+		mode: "absolute",
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	const percentDelta = formatDelta(end.y, start.y, {
+		mode: "percent",
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	const readings = [];
+	for (let index = startIndex; index <= endIndex; index += 1) {
+		const row = rows[index];
+		if (row.y == null) continue;
+		readings.push({
+			x: row.x,
+			y: row.y,
+			index
+		});
+	}
+	const legs = [];
+	for (let at = 1; at < readings.length; at += 1) {
+		const from = readings[at - 1];
+		const to = readings[at];
+		const step = deriveHighlightDelta(to.y, from.y, {
+			deltaMode,
+			goodDirection,
+			format,
+			locale,
+			percentagePoints
+		});
+		if (!step) continue;
+		legs.push({
+			from,
+			to,
+			change: to.y - from.y,
+			changeText: step.text,
+			rangeText: formatters.formatXRange(from.x, to.x),
+			direction: step.direction,
+			polarity: step.polarity
+		});
+	}
+	let peak = null;
+	let trough = null;
+	for (const reading of readings) {
+		if (!peak || reading.y > peak.y) peak = reading;
+		if (!trough || reading.y < trough.y) trough = reading;
+	}
+	if (peak && trough && peak.y === trough.y) {
+		peak = null;
+		trough = null;
+	}
+	if (peak && (peak.index === startIndex || peak.index === endIndex)) peak = null;
+	if (trough && (trough.index === startIndex || trough.index === endIndex)) trough = null;
+	const steepest = legs.reduce((best, leg) => best == null || Math.abs(leg.change) > Math.abs(best.change) ? leg : best, null);
+	return {
+		start,
+		end,
+		label: window.label,
+		rangeText: formatters.formatXRange(start.x, end.x),
+		delta,
+		absolute: end.y - start.y,
+		absoluteText: absoluteDelta.text,
+		percentText: percentDelta.renderedMode === "percent" ? percentDelta.text : "—",
+		readings,
+		legs,
+		length: endIndex - startIndex,
+		peak,
+		trough,
+		steepest: steepest && steepest.change !== 0 ? steepest : null
+	};
+}
+function quantile(sorted, fraction) {
+	if (sorted.length === 0) return 0;
+	if (sorted.length === 1) return sorted[0];
+	const position = (sorted.length - 1) * fraction;
+	const low = Math.floor(position);
+	const high = Math.ceil(position);
+	if (low === high) return sorted[low];
+	return sorted[low] + (sorted[high] - sorted[low]) * (position - low);
+}
+function severityFrom(distance, { notable, unusual, extreme }) {
+	if (distance > extreme) return "extreme";
+	if (distance > unusual) return "unusual";
+	if (distance > notable) return "notable";
+	return "typical";
+}
+/**
+* Places the window's change among the changes of every comparable window in
+* the same series — the reading that ESTABLISHES the highlight, and the half
+* MetricCard's tile cannot show. Windows are the same length as the
+* highlight's (in rows), taken at every offset (`rolling`) or tiled
+* non-overlapping from the highlight's own start (`adjacent`), and both bounds
+* must carry a finite reading; a window that cannot produce a change in the
+* compared mode is skipped and counted in `skipped`.
+*
+* Returns `null` when fewer than `minPeers` comparable windows exist — the
+* panel then omits the section and says why, rather than calling one window
+* out of three "extreme".
+*
+* The spread is a COMPARISON, not a significance test: `rolling` windows
+* overlap, so their changes are autocorrelated and the standard deviation is
+* narrower than independent sampling would give. `adjacent` is the honest set.
+* The generated text says "the 2nd largest of 48 comparable periods"; nothing
+* here claims a p-value.
+*/
+function derivePeers(summary, info, { mode, baseline, deltaMode, goodDirection, format, locale, percentagePoints, formatters, minPeers = 4, thresholds }) {
+	if (!summary || !info) return null;
+	const { rows } = summary;
+	const lag = info.length;
+	if (lag < 1) return null;
+	const limits = thresholds ?? (baseline === "sigma" ? DEFAULT_SIGMA_THRESHOLDS : DEFAULT_PERCENTILE_THRESHOLDS);
+	const offsets = [];
+	if (mode === "adjacent") for (let index = info.start.index % lag; index + lag < rows.length; index += lag) offsets.push(index);
+	else for (let index = 0; index + lag < rows.length; index += 1) offsets.push(index);
+	const peers = [];
+	let skipped = 0;
+	let highlightChange = null;
+	for (const index of offsets) {
+		const from = rows[index];
+		const to = rows[index + lag];
+		if (from.y == null || to.y == null) {
+			skipped += 1;
+			continue;
+		}
+		const delta = formatDelta(to.y, from.y, {
+			mode: deltaMode,
+			format,
+			locale,
+			pointsSuffix: percentagePoints
+		});
+		if (deltaMode === "percent" && delta.renderedMode !== "percent") {
+			skipped += 1;
+			continue;
+		}
+		const change = deltaMode === "percent" ? delta.percent : delta.absolute;
+		const isHighlight = index === info.start.index;
+		if (isHighlight) highlightChange = change;
+		let polarity = "neutral";
+		if (delta.direction !== "flat" && goodDirection !== "none") polarity = delta.direction === "up" === (goodDirection === "up") ? "positive" : "negative";
+		peers.push({
+			start: from.x,
+			end: to.x,
+			change,
+			changeText: formatters.formatPeerChange(change),
+			rangeText: formatters.formatXRange(from.x, to.x),
+			isHighlight,
+			polarity
+		});
+	}
+	if (highlightChange == null) return null;
+	const others = peers.filter((peer) => !peer.isHighlight).map((peer) => peer.change);
+	if (others.length < minPeers) return null;
+	const mean = others.reduce((sum, value) => sum + value, 0) / others.length;
+	const variance = others.reduce((sum, value) => sum + (value - mean) ** 2, 0) / others.length;
+	const sd = Math.sqrt(variance);
+	const z = sd > 0 ? (highlightChange - mean) / sd : null;
+	const sorted = [...others].sort((a, b) => a - b);
+	const percentile = sorted.filter((value) => value <= highlightChange).length / sorted.length * 100;
+	const [typicalLow, typicalHigh] = baseline === "sigma" ? [mean - sd, mean + sd] : [quantile(sorted, .1), quantile(sorted, .9)];
+	const typical = highlightChange >= typicalLow && highlightChange <= typicalHigh;
+	const rank = [...peers].sort((a, b) => Math.abs(b.change) - Math.abs(a.change)).findIndex((peer) => peer.isHighlight) + 1;
+	const severity = baseline === "sigma" ? z == null ? highlightChange === mean ? "typical" : "extreme" : severityFrom(Math.abs(z), limits) : severityFrom(Math.abs(percentile - 50), limits);
+	const ordinal = (value) => {
+		const tens = value % 100;
+		if (tens >= 11 && tens <= 13) return `${value}th`;
+		switch (value % 10) {
+			case 1: return `${value}st`;
+			case 2: return `${value}nd`;
+			case 3: return `${value}rd`;
+			default: return `${value}th`;
+		}
+	};
+	return {
+		mode,
+		baseline,
+		peers,
+		count: others.length,
+		total: others.length + 1,
+		skipped,
+		length: lag,
+		change: highlightChange,
+		changeText: formatters.formatPeerChange(highlightChange),
+		mean,
+		sd,
+		meanText: formatters.formatPeerChange(mean),
+		sdText: formatters.formatPeerChange(sd),
+		z,
+		zText: z == null ? "—" : `${formatNumber(z, "number:1", locale, { signDisplay: "exceptZero" })} sd`,
+		percentile,
+		percentileText: formatNumber(percentile / 100, "percent:0", locale),
+		rank,
+		rankText: ordinal(rank),
+		typicalLow,
+		typicalHigh,
+		typicalText: `${formatters.formatPeerChange(typicalLow)} to ${formatters.formatPeerChange(typicalHigh)}`,
+		typical,
+		severity
+	};
+}
+/**
+* Decomposes the window's change into its contributors — the half that
+* EXPLAINS the highlight. Each driver's contribution is the amount it added to
+* the total, either passed directly or derived from its own `from`/`to`
+* readings; rows sort by absolute contribution so the biggest mover reads
+* first, the tail folds into `Other`, and whatever the parts do not account
+* for becomes an explicit `Unexplained` row.
+*
+* Totals reconcile with parts or the panel says they do not: a decomposition
+* that silently misses a third of the move is worse than none.
+*/
+function normalizeDrivers(drivers, info, { goodDirection, formatters, limit, otherLabel, residualLabel, tolerance = .005 }) {
+	if (!drivers || drivers.length === 0 || !info) return null;
+	const total = info.absolute;
+	const polarityOf = (contribution) => {
+		if (contribution === 0 || goodDirection === "none") return "neutral";
+		return contribution > 0 === (goodDirection === "up") ? "positive" : "negative";
+	};
+	const seen = /* @__PURE__ */ new Map();
+	const parsed = drivers.flatMap((driver) => {
+		const from = isFinite(driver.from) ? driver.from : null;
+		const to = isFinite(driver.to) ? driver.to : null;
+		const contribution = isFinite(driver.contribution) ? driver.contribution : from != null && to != null ? to - from : null;
+		if (contribution == null) return [];
+		const base = driver.key ?? driver.label;
+		const repeats = seen.get(base) ?? 0;
+		seen.set(base, repeats + 1);
+		const share = total === 0 ? null : contribution / total;
+		return [{
+			key: repeats === 0 ? base : `${base}·${repeats + 1}`,
+			label: driver.label,
+			contribution,
+			contributionText: formatters.formatAmountChange(contribution),
+			share,
+			shareText: formatters.formatShare(share),
+			from,
+			to,
+			fromText: formatters.formatY(from),
+			toText: formatters.formatY(to),
+			direction: contribution > 0 ? "up" : contribution < 0 ? "down" : "flat",
+			polarity: polarityOf(contribution),
+			role: "driver"
+		}];
+	});
+	if (parsed.length === 0) return null;
+	const explained = parsed.reduce((sum, row) => sum + row.contribution, 0);
+	const residual = total - explained;
+	const ordered = [...parsed].sort((a, b) => Math.abs(b.contribution) - Math.abs(a.contribution));
+	const rows = [];
+	let folded = 0;
+	if (limit != null && limit > 0 && ordered.length > limit) {
+		rows.push(...ordered.slice(0, limit));
+		const tail = ordered.slice(limit);
+		folded = tail.length;
+		const contribution = tail.reduce((sum, row) => sum + row.contribution, 0);
+		const share = total === 0 ? null : contribution / total;
+		rows.push({
+			key: "__other__",
+			label: otherLabel,
+			contribution,
+			contributionText: formatters.formatAmountChange(contribution),
+			share,
+			shareText: formatters.formatShare(share),
+			from: null,
+			to: null,
+			fromText: "—",
+			toText: "—",
+			direction: contribution > 0 ? "up" : contribution < 0 ? "down" : "flat",
+			polarity: polarityOf(contribution),
+			role: "other"
+		});
+	} else rows.push(...ordered);
+	const reconciles = total === 0 ? Math.abs(residual) === 0 : Math.abs(residual / total) <= tolerance;
+	if (!reconciles) {
+		const share = total === 0 ? null : residual / total;
+		rows.push({
+			key: "__residual__",
+			label: residualLabel,
+			contribution: residual,
+			contributionText: formatters.formatAmountChange(residual),
+			share,
+			shareText: formatters.formatShare(share),
+			from: null,
+			to: null,
+			fromText: "—",
+			toText: "—",
+			direction: residual > 0 ? "up" : residual < 0 ? "down" : "flat",
+			polarity: polarityOf(residual),
+			role: "residual"
+		});
+	}
+	const withTotal = total === 0 ? 1 : Math.sign(total);
+	const contributors = rows.filter((row) => row.role !== "residual");
+	const top = contributors.filter((row) => Math.sign(row.contribution) === withTotal).reduce((best, row) => best == null || Math.abs(row.contribution) > Math.abs(best.contribution) ? row : best, null) ?? null;
+	const counter = contributors.filter((row) => Math.sign(row.contribution) === -withTotal).reduce((best, row) => best == null || Math.abs(row.contribution) > Math.abs(best.contribution) ? row : best, null) ?? null;
+	return {
+		rows,
+		total,
+		totalText: formatters.formatAmountChange(total),
+		explained,
+		explainedText: formatters.formatAmountChange(explained),
+		residual,
+		residualText: formatters.formatAmountChange(residual),
+		reconciles,
+		folded,
+		top,
+		counter
+	};
+}
+/**
+* Splits the series around the window for the context plot: every row carries
+* `hl` and the window's `tone`, the readings outside it are split into a
+* `before` and an `after` run so the gray path never runs under the coloured
+* one, and the window's extent rides one band row.
+*/
+function buildHighlightContextDatasets(summary, info) {
+	const tone = info.delta.polarity;
+	const table = [];
+	const outside = [];
+	const inside = [];
+	for (let index = 0; index < summary.rows.length; index += 1) {
+		const row = summary.rows[index];
+		const hl = index >= info.start.index && index <= info.end.index;
+		const entry = {
+			...row,
+			hl,
+			tone: hl ? tone : null
+		};
+		table.push(entry);
+		if (hl) inside.push(entry);
+		if (!hl || index === info.start.index || index === info.end.index) outside.push({
+			...row,
+			seg: index <= info.start.index ? "before" : "after"
+		});
+	}
+	return {
+		table,
+		outside,
+		inside,
+		endpoints: [{
+			x: info.start.x,
+			y: info.start.y,
+			role: "start",
+			tone
+		}, {
+			x: info.end.x,
+			y: info.end.y,
+			role: "end",
+			tone
+		}],
+		band: [{
+			start: info.start.x,
+			end: info.end.x,
+			tone
+		}]
+	};
+}
+/** One row `{ low, high }` — the typical-range band behind the strip. */
+function buildTypicalRows(stats) {
+	return [{
+		low: stats.typicalLow,
+		high: stats.typicalHigh
+	}];
+}
+/** The driver bars, in row order, with the fields the spec encodes. */
+function buildDriverRows(info) {
+	return info.rows.map((row) => ({
+		key: row.key,
+		label: row.label,
+		value: row.contribution,
+		share: row.share,
+		tone: row.polarity,
+		role: row.role
+	}));
+}
+function highlightSegmentsToText(segments) {
+	return segments.map((segment) => typeof segment === "string" ? segment : segment.value).join("");
+}
+/** The takeaway: what moved, how it places among its peers, which driver carried it. */
+function buildHighlightAnalysisInsight({ name, info, peers, drivers, labels }) {
+	const { direction } = info.delta;
+	return labels.insight({
+		name,
+		direction,
+		change: direction === "flat" ? "" : stripSign(info.delta.text),
+		secondary: info.delta.secondaryText ? stripSign(info.delta.secondaryText) : null,
+		range: info.rangeText,
+		label: info.label,
+		severity: peers?.severity ?? "typical",
+		rank: peers?.rankText ?? null,
+		count: peers?.count ?? null,
+		topDriver: drivers?.top?.label ?? null,
+		topContribution: drivers?.top ? stripSign(drivers.top.contributionText) : null,
+		topShare: drivers?.top?.share != null ? drivers.top.shareText : null
+	});
+}
+/**
+* The panel'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.
+*/
+function buildHighlightDescription({ name, state, info, peers, drivers, formatters, asOfText, labels }) {
+	if (!info || state !== "ready") return labels.cardDescription({
+		name,
+		state,
+		range: "",
+		direction: "flat",
+		change: "",
+		secondary: null,
+		startText: "",
+		endText: "",
+		severity: null,
+		rank: null,
+		count: null,
+		driverCount: 0,
+		topDriver: null,
+		topContribution: null,
+		asOf: asOfText ?? null
+	});
+	return labels.cardDescription({
+		name,
+		state,
+		range: info.rangeText,
+		label: info.label,
+		direction: info.delta.direction,
+		change: info.delta.direction === "flat" ? "" : stripSign(info.delta.text),
+		secondary: info.delta.secondaryText ? stripSign(info.delta.secondaryText) : null,
+		startText: formatters.formatY(info.start.y),
+		endText: formatters.formatY(info.end.y),
+		severity: peers ? labels.severityNames[peers.severity].toLowerCase() : null,
+		rank: peers?.rankText ?? null,
+		count: peers?.count ?? null,
+		driverCount: drivers?.rows.length ?? 0,
+		topDriver: drivers?.top?.label ?? null,
+		topContribution: drivers?.top ? stripSign(drivers.top.contributionText) : null,
+		asOf: asOfText ?? null
+	});
+}
+/** Accessible description of the context plot — set live through `view.description`. */
+function buildContextDescription({ name, mark, summary, info, formatters, labels }) {
+	return labels.contextDescription({
+		mark: labels.markNames[mark],
+		name,
+		count: summary.count,
+		first: summary.first ? formatters.formatX(summary.first.x) : "—",
+		last: summary.last ? formatters.formatX(summary.last.x) : "—",
+		min: formatters.formatY(summary.min),
+		max: formatters.formatY(summary.max),
+		range: info.rangeText,
+		label: info.label,
+		direction: info.delta.direction,
+		change: stripSign(info.delta.text)
+	});
+}
+/** Accessible description of the peer strip. */
+function buildPeersDescription({ name, stats, labels }) {
+	return labels.peersDescription({
+		name,
+		count: stats.count,
+		readings: stats.length + 1,
+		mode: stats.mode,
+		change: stats.changeText,
+		rank: stats.rankText,
+		typical: stats.typicalText,
+		severity: labels.severityNames[stats.severity].toLowerCase()
+	});
+}
+/** Accessible description of the drivers bars. */
+function buildDriversDescription({ name, info, labels }) {
+	return labels.driversDescription({
+		name,
+		count: info.rows.filter((row) => row.role !== "residual").length,
+		total: info.totalText,
+		top: info.top?.label ?? null,
+		topContribution: info.top?.contributionText ?? null,
+		counter: info.counter?.label ?? null,
+		counterContribution: info.counter?.contributionText ?? null,
+		residual: info.reconciles ? null : info.residualText
+	});
+}
+/** The verdict sentence under the strip — visible text, never colour alone. */
+function buildPeerVerdict(stats, labels) {
+	return labels.peerVerdict({
+		severity: stats.severity,
+		rank: stats.rankText,
+		total: stats.total,
+		readings: stats.length + 1,
+		typical: stats.typicalText,
+		change: stats.changeText,
+		inside: stats.typical
+	});
+}
+//#endregion
+export { DEFAULT_HIGHLIGHT_LABELS, DEFAULT_PERCENTILE_THRESHOLDS, DEFAULT_SIGMA_THRESHOLDS, buildContextDescription, buildDriverRows, buildDriversDescription, buildHighlightAnalysisInsight, buildHighlightContextDatasets, buildHighlightDescription, buildPeerVerdict, buildPeersDescription, buildTypicalRows, createHighlightFormatters, deriveHighlightDelta, deriveHighlightState, derivePeers, highlightSegmentsToText, normalizeDrivers, normalizeHighlightSeries, resolveHighlightLabels, resolveHighlightWindow };