@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/TrendCard/TrendCard.model.js

@@ -0,0 +1,623 @@
+import { formatDate, formatDateRange, formatDelta, formatNumber } from "../../lib/vega/formatters.js";
+//#region src/components/TrendCard/TrendCard.model.ts
+const DEFAULT_TREND_LABELS = {
+	increase: "Up",
+	decrease: "Down",
+	unchanged: "No change",
+	percentagePoints: " pp",
+	noData: "No data",
+	noMatch: "No matching data",
+	clearFilters: "Clear filters",
+	error: "Couldn't load this trend",
+	retry: "Try again",
+	insufficient: "Not enough data for a trend",
+	stale: "Stale",
+	asOf: "As of",
+	tablePeriod: "Period",
+	tableValue: "Value",
+	tableActual: "actual",
+	target: "Target",
+	other: "Other",
+	legendGroup: (name) => `Series shown in ${name}`,
+	hideSeries: (series) => `Hide ${series}`,
+	showSeries: (series) => `Show ${series}`,
+	focused: "focused",
+	band: "highlighted period",
+	since: (period) => `vs ${period}`,
+	indexedAt: (period) => `Indexed to 100 at ${period}`,
+	normalized: "Share of period total",
+	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} trend`,
+	changeGroup: (name) => `${name} change`,
+	deltaExplanation: ({ fromLabel, fromText, toLabel, toText, changeText, secondaryText, renderedMode, direction }) => {
+		const rows = [
+			[fromLabel, fromText],
+			[toLabel, toText],
+			[direction === "up" ? "Increase" : direction === "down" ? "Decrease" : "No change", changeText]
+		];
+		if (secondaryText) rows.push([renderedMode === "percent" ? "Change" : "Change %", secondaryText]);
+		return rows;
+	},
+	spanSentence: ({ word, series, primary, secondary, range, from, to }) => primary ? `${series} ${word.toLowerCase()} ${primary}${secondary ? ` (${secondary})` : ""} over ${range}, from ${from} to ${to}.` : `${series} ${word.toLowerCase()} over ${range} (${from}).`,
+	extremesSentence: ({ peak, peakAt, trough, troughAt }) => `Peaked at ${peak} on ${peakAt} and bottomed at ${trough} on ${troughAt}.`,
+	seriesSummary: (count, list) => count === 1 ? `Latest reading: ${list}.` : `${count} series, latest readings: ${list}.`,
+	foldedSummary: (count) => `${count} more folded into Other.`,
+	bandsSummary: (list) => `Highlighted periods: ${list}.`,
+	markNames: {
+		line: "Line",
+		area: "Area",
+		bar: "Bar"
+	},
+	chartDescription: ({ mark, name, seriesCount, periodCount, range, min, max, focus, target, stacked }) => `${mark} chart of ${name}: ${seriesCount} series over ${periodCount} periods, ${range}, ranging ${min} to ${max}.` + (focus ? ` ${focus} emphasised.` : "") + (stacked ? ` ${stacked}.` : "") + (target ? ` Reference line at the ${target} target.` : ""),
+	insightMark: "Insight",
+	insight: ({ series, direction, from, to, change, secondary, range, peak, peakAt }) => {
+		if (direction === "flat") return [
+			`${series} held at `,
+			{ value: from },
+			` across ${range}.`
+		];
+		const segments = [
+			`${series} ${direction === "up" ? "rose" : "fell"} from `,
+			{ value: from },
+			" to ",
+			{ value: to },
+			` across ${range}, a ${direction === "up" ? "rise" : "drop"} of `,
+			{ value: change }
+		];
+		if (secondary) segments.push(" (", { value: secondary }, ")");
+		segments.push(".");
+		if (peak && peakAt) segments.push(` It peaked at `, { value: peak }, ` on ${peakAt}.`);
+		return segments;
+	}
+};
+function resolveTrendLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_TREND_LABELS,
+		...overrides
+	} : DEFAULT_TREND_LABELS;
+}
+/**
+* The state machine. Error wins; loading over existing series is a refresh (the
+* previous render stays under the veil); no readings is `no-match` when the
+* consumer's filter caused it and `empty` otherwise.
+*/
+function deriveTrendState({ status, hasValue, hasData, filtered }) {
+	if (status === "error") return "error";
+	if (status === "loading") return hasData ? "refreshing" : "loading";
+	if (hasValue) return "ready";
+	return filtered ? "no-match" : "empty";
+}
+const isFinite = (value) => typeof value === "number" && Number.isFinite(value);
+const DAY_MS = 864e5;
+const ISO_DATE = /^\d{4}-\d{2}(-\d{2})?([T ].*)?$/;
+/** The key of the series the long tail folds into. Never collides with a consumer key that is a label. */
+const TREND_OTHER_KEY = "__other__";
+function inferXType(series) {
+	for (const entry of series) {
+		const sample = entry.points.find((point) => point.x != null);
+		if (!sample) continue;
+		const { x } = sample;
+		if (x instanceof Date) return "temporal";
+		if (typeof x === "number") return "quantitative";
+		return ISO_DATE.test(x) ? "temporal" : "ordinal";
+	}
+	return "ordinal";
+}
+function inferGranularity(periods) {
+	const xs = periods.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";
+}
+/**
+* The granularity an x axis labels its ticks at: the tooltip and table keep the
+* full form (`Sep 8, 2026`); an axis has room for `Sep 8`. Duplicated per
+* component rather than shared, so a card's text grammar is readable in one
+* file — the same reason each card owns its own state machine.
+*/
+function trendAxisGranularity(granularity) {
+	switch (granularity) {
+		case "day": return "day-short";
+		case "month": return "month-short";
+		case "datetime": return "time";
+		default: return granularity;
+	}
+}
+function normalizeX(x, xType) {
+	if (xType === "temporal") {
+		const time = x instanceof Date ? x.getTime() : new Date(x).getTime();
+		return Number.isNaN(time) ? null : time;
+	}
+	if (xType === "quantitative") return isFinite(x) ? x : null;
+	return String(x);
+}
+/**
+* The colour job, resolved against the theme's own categorical budget.
+*
+* The brand ships six hues and reserves three for status, so `colors.css`
+* defines only a handful of `chart-N` identity slots. Repeating a slot would
+* make two series look like one, so `categorical` past the budget degrades to
+* `emphasis` — the focused series in the hue on a context-gray field, which is
+* the FT/Few reading of a many-line chart anyway. `auto` applies the same
+* budget without being asked.
+*/
+function resolveSeriesColorMode(requested, seriesCount, slots) {
+	if (requested === "sequential") return "sequential";
+	if (requested === "emphasis") return "emphasis";
+	if (requested === "categorical") return seriesCount <= slots ? "categorical" : "emphasis";
+	if (seriesCount <= 1) return "emphasis";
+	return seriesCount <= slots ? "categorical" : "emphasis";
+}
+/**
+* The colour one series paints with. Identity slots are assigned by the
+* series' index in the consumer's order — never by rank or by value — so
+* hiding a series cannot repaint the survivors (rule 6). A sequential ramp
+* spreads the ordered series across the whole ramp so the ends are always the
+* ends, however many series there are.
+*/
+function seriesColorAt(index, seriesCount, mode, focusIndex, tokens) {
+	if (mode === "categorical") return tokens.category[index % tokens.category.length];
+	if (mode === "sequential") {
+		const ramp = tokens.sequential;
+		if (seriesCount <= 1) return ramp[ramp.length - 1];
+		const step = Math.round(index * (ramp.length - 1) / (seriesCount - 1));
+		return ramp[Math.min(ramp.length - 1, Math.max(0, step))];
+	}
+	return index === focusIndex ? tokens.emphasis : tokens.context;
+}
+/**
+* Normalises `series` onto one shared period domain for the plot, the legend
+* and the table: temporal `x` becomes epoch milliseconds, invalid dates are
+* dropped, a period a series has no reading for stays a gap (never a zero),
+* the long tail folds into `Other` when asked, and the visible series are laid
+* out long-form with their colour and stack order baked into each row — so the
+* spec stays structural and a visibility change is a data push, not a re-embed.
+*
+* Returns `null` when there are no series to speak of.
+*/
+function normalizeSeries(series, { granularity, normalize = "none", focus, visible, maxSeries, otherLabel, colorMode, tokens, stack = false }) {
+	if (!series) return null;
+	const xType = inferXType(series);
+	const seen = /* @__PURE__ */ new Map();
+	let entries = series.map((entry) => {
+		const base = entry.key ?? entry.label;
+		const repeats = seen.get(base) ?? 0;
+		seen.set(base, repeats + 1);
+		return {
+			key: repeats === 0 ? base : `${base}·${repeats + 1}`,
+			label: entry.label,
+			points: entry.points
+		};
+	});
+	const focusKey = focus != null && entries.some((entry) => entry.key === focus) ? focus : entries[0]?.key ?? "";
+	let folded = 0;
+	if (maxSeries != null && maxSeries >= 1 && entries.length > maxSeries) {
+		const keepCount = Math.max(0, maxSeries - 1);
+		const kept = [];
+		const rest = [];
+		entries.forEach((entry, index) => {
+			if (index < keepCount || entry.key === focusKey) kept.push(entry);
+			else rest.push(entry);
+		});
+		if (rest.length >= 2) {
+			const totals = /* @__PURE__ */ new Map();
+			for (const entry of rest) for (const point of entry.points) {
+				const x = normalizeX(point.x, xType);
+				if (x == null || !isFinite(point.y)) continue;
+				totals.set(String(x), (totals.get(String(x)) ?? 0) + point.y);
+			}
+			const orderedX = [];
+			const seenX = /* @__PURE__ */ new Set();
+			for (const entry of rest) for (const point of entry.points) {
+				const x = normalizeX(point.x, xType);
+				if (x == null || seenX.has(String(x))) continue;
+				seenX.add(String(x));
+				orderedX.push(x);
+			}
+			const points = orderedX.map((x) => ({
+				x,
+				y: totals.get(String(x)) ?? null
+			}));
+			entries = [...kept, {
+				key: TREND_OTHER_KEY,
+				label: otherLabel,
+				points
+			}];
+			folded = rest.length;
+		}
+	}
+	const periodSet = /* @__PURE__ */ new Map();
+	for (const entry of entries) for (const point of entry.points) {
+		const x = normalizeX(point.x, xType);
+		if (x == null) continue;
+		periodSet.set(String(x), x);
+	}
+	const periods = [...periodSet.values()];
+	if (xType !== "ordinal") periods.sort((a, b) => a - b);
+	const focusIndex = Math.max(0, entries.findIndex((entry) => entry.key === focusKey));
+	const positionOf = new Map(periods.map((x, index) => [String(x), index]));
+	const infos = entries.map((entry, index) => {
+		const values = new Array(periods.length).fill(null);
+		const reported = new Array(periods.length).fill(false);
+		for (const point of entry.points) {
+			const x = normalizeX(point.x, xType);
+			if (x == null) continue;
+			const at = positionOf.get(String(x));
+			if (at == null) continue;
+			values[at] = isFinite(point.y) ? point.y : null;
+			reported[at] = true;
+		}
+		const baseIndex = values.findIndex((value) => value != null);
+		const base = baseIndex < 0 ? null : values[baseIndex];
+		const plotted = normalize === "index" && base != null && base !== 0 ? values.map((value) => value == null ? null : value / base * 100) : values;
+		const finite = values.map((value, at) => ({
+			x: periods[at],
+			y: value
+		})).filter((row) => row.y != null);
+		const finitePlotted = plotted.map((value, at) => ({
+			x: periods[at],
+			y: value
+		})).filter((row) => row.y != null);
+		return {
+			key: entry.key,
+			label: entry.label,
+			index,
+			color: seriesColorAt(index, entries.length, colorMode, focusIndex, tokens),
+			values,
+			plotted,
+			reported,
+			count: finite.length,
+			first: finite[0] ?? null,
+			latest: finite[finite.length - 1] ?? null,
+			latestPlotted: finitePlotted[finitePlotted.length - 1] ?? null,
+			min: finite.length > 0 ? Math.min(...finite.map((row) => row.y)) : null,
+			max: finite.length > 0 ? Math.max(...finite.map((row) => row.y)) : null
+		};
+	});
+	const shown = new Set(visible ?? infos.map((info) => info.key));
+	const visibleInfos = infos.filter((info) => shown.has(info.key));
+	const rows = [];
+	periods.forEach((x, at) => {
+		for (const info of visibleInfos) {
+			if (!info.reported[at]) continue;
+			rows.push({
+				x,
+				s: info.key,
+				y: info.plotted[at],
+				raw: info.values[at],
+				i: info.index,
+				c: info.color,
+				n: info.label,
+				f: info.key === focusKey
+			});
+		}
+	});
+	const plottedValues = rows.map((row) => row.y).filter((y) => y != null);
+	let min = plottedValues.length > 0 ? Math.min(...plottedValues) : null;
+	let max = plottedValues.length > 0 ? Math.max(...plottedValues) : null;
+	if (stack === "zero" && plottedValues.length > 0) {
+		let positive = 0;
+		let negative = 0;
+		periods.forEach((_x, at) => {
+			let up = 0;
+			let down = 0;
+			for (const info of visibleInfos) {
+				const value = info.plotted[at];
+				if (value == null) continue;
+				if (value >= 0) up += value;
+				else down += value;
+			}
+			positive = Math.max(positive, up);
+			negative = Math.min(negative, down);
+		});
+		max = Math.max(max ?? 0, positive);
+		min = Math.min(min ?? 0, negative);
+	}
+	return {
+		xType,
+		granularity: granularity ?? (xType === "temporal" ? inferGranularity(periods) : "day"),
+		periods,
+		series: infos,
+		rows,
+		count: plottedValues.length,
+		min,
+		max,
+		hasNegative: plottedValues.some((value) => value < 0),
+		folded,
+		focusKey
+	};
+}
+/** The periods the crosshair reads — one row each, so it lands on the period rather than on a series. */
+function buildPeriodRows(summary) {
+	return summary.periods.map((x) => ({ x }));
+}
+/** One row per visible series at its last plotted reading — where a direct endpoint label sits. */
+function buildLatestRows(summary, visibleKeys) {
+	const shown = new Set(visibleKeys);
+	return summary.series.filter((info) => shown.has(info.key) && info.latestPlotted != null).map((info) => ({
+		x: info.latestPlotted.x,
+		y: info.latestPlotted.y,
+		n: info.label,
+		c: info.color
+	}));
+}
+/**
+* Snaps every band onto the period domain. Each bound moves inward to the
+* nearest period the data actually has, so a band can never extend the axis;
+* a band that covers no period is dropped rather than drawn as a hairline.
+*/
+function resolveBands(bands, summary) {
+	if (!bands || !summary || summary.periods.length === 0) return [];
+	const { periods, xType } = summary;
+	const rows = [];
+	for (const band of bands) {
+		const lo = normalizeX(band.start, xType);
+		const hi = normalizeX(band.end, xType);
+		if (lo == null || hi == null) continue;
+		if (xType === "ordinal") {
+			let first = periods.findIndex((x) => x === lo);
+			let last = periods.findIndex((x) => x === hi);
+			if (first < 0 || last < 0) continue;
+			if (first > last) [first, last] = [last, first];
+			rows.push({
+				start: periods[first],
+				end: periods[last],
+				label: band.label
+			});
+			continue;
+		}
+		const [from, to] = lo <= hi ? [lo, hi] : [hi, lo];
+		const inside = periods.filter((x) => x >= from && x <= to);
+		if (inside.length === 0) continue;
+		rows.push({
+			start: inside[0],
+			end: inside[inside.length - 1],
+			label: band.label
+		});
+	}
+	return rows;
+}
+/**
+* The band a period falls inside — the tooltip's and the table's band marker.
+* A continuous axis compares the values; an ordinal one compares positions in
+* `periods`, since a category label has no order of its own. The first
+* matching band wins, so overlapping bands are read in the consumer's order.
+*/
+function bandAt(bands, periods, x) {
+	if (bands.length === 0) return null;
+	const positionOf = (value) => typeof value === "number" ? value : periods.findIndex((period) => String(period) === String(value));
+	const at = positionOf(x);
+	if (at < 0) return null;
+	for (const band of bands) {
+		const from = positionOf(band.start);
+		const to = positionOf(band.end);
+		if (from < 0 || to < 0) continue;
+		if (at >= Math.min(from, to) && at <= Math.max(from, to)) return band;
+	}
+	return null;
+}
+/**
+* The change the focused series made across the span it actually covers —
+* first finite reading to last finite reading — with the extremes in between.
+* `null` unless the series holds two distinct readings, so the card never
+* invents a trend from one point.
+*/
+function deriveTrendSpan(summary, focusKey, { deltaMode, goodDirection, format, locale, percentagePoints, formatters }) {
+	if (!summary) return null;
+	const info = summary.series.find((entry) => entry.key === focusKey) ?? summary.series[0];
+	if (!info || !info.first || !info.latest || info.count < 2) return null;
+	if (String(info.first.x) === String(info.latest.x)) return null;
+	const delta = deriveTrendDelta(info.latest.y, info.first.y, {
+		deltaMode,
+		goodDirection,
+		format,
+		locale,
+		percentagePoints
+	});
+	if (!delta) return null;
+	const finite = info.values.map((value, at) => ({
+		x: summary.periods[at],
+		y: value
+	})).filter((row) => row.y != null);
+	let peak = finite[0];
+	let trough = finite[0];
+	for (const row of finite) {
+		if (row.y > peak.y) peak = row;
+		if (row.y < trough.y) trough = row;
+	}
+	const isEnd = (row) => String(row.x) === String(info.first?.x) || String(row.x) === String(info.latest?.x);
+	return {
+		seriesKey: info.key,
+		seriesLabel: info.label,
+		from: info.first,
+		to: info.latest,
+		rangeText: formatters.formatXRange(info.first.x, info.latest.x),
+		delta,
+		peak: isEnd(peak) ? null : peak,
+		trough: isEnd(trough) ? null : trough
+	};
+}
+/** A change between two readings, with polarity resolved through `goodDirection`. */
+function deriveTrendDelta(value, previous, { deltaMode, goodDirection, format, locale, percentagePoints }) {
+	if (!isFinite(value) || !isFinite(previous)) return null;
+	const delta = formatDelta(value, previous, {
+		mode: deltaMode,
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	const other = formatDelta(value, previous, {
+		mode: delta.renderedMode === "percent" ? "absolute" : "percent",
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	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
+	};
+}
+/** The formatters every text surface shares — headline, badge, legend, table, tooltip, descriptions. */
+function createTrendFormatters({ format, locale, timeZone, formatValue, xType, granularity, normalize = "none", stack = false, indexFormat = "number:0" }) {
+	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 value = (input) => isFinite(input) ? formatValue ? formatValue(input) : formatNumber(input, format, locale) : "—";
+	return {
+		formatValue: value,
+		formatPlotted: normalize === "index" ? (input) => formatNumber(input, indexFormat, locale) : stack === "normalize" ? (input) => formatNumber(input, "percent:0", locale) : value,
+		formatX,
+		formatXRange: (start, end) => xType === "temporal" && typeof start === "number" && typeof end === "number" ? formatDateRange(start, end, {
+			granularity,
+			locale,
+			timeZone
+		}) : `${formatX(start)} – ${formatX(end)}`
+	};
+}
+const stripSign = (text) => text.replace(/^[+\-−]/, "");
+/**
+* The generated insight — what the card shows beside the AI mark when the
+* consumer passes no `insight`. The focused series' two ends, its change (in
+* the badge's form, with the other form in brackets) and its peak come back as
+* `{ value }` segments so the card can set them in bold; the words come from
+* `labels.insight`.
+*/
+function buildTrendInsight({ span, formatters, labels }) {
+	const flat = span.delta.direction === "flat";
+	const secondary = span.delta.secondaryText;
+	return labels.insight({
+		series: span.seriesLabel,
+		direction: span.delta.direction,
+		from: formatters.formatValue(span.from.y),
+		to: formatters.formatValue(span.to.y),
+		change: flat ? "" : stripSign(span.delta.text),
+		secondary: flat || !secondary ? null : stripSign(secondary),
+		range: span.rangeText,
+		peak: span.peak ? formatters.formatValue(span.peak.y) : null,
+		peakAt: span.peak ? formatters.formatX(span.peak.x) : null
+	});
+}
+/**
+* The hover chip's contents for one period — pure, so the shared-x reading is
+* unit-tested rather than only reachable through a pointer event (Vega's own
+* hit-testing needs a visible document, which a hidden frame does not give).
+*
+* Ranked descending by the PLOTTED value, so the reader compares by reading
+* down the chip in the order the marks sit on screen. Returns `null` for a
+* period the card does not have.
+*/
+function buildTrendTooltip({ summary, visibleKeys, bands, x, target, formatters, transformed }) {
+	if (x == null || !summary) return null;
+	const at = summary.periods.findIndex((period) => String(period) === String(x));
+	if (at < 0) return null;
+	const shown = new Set(visibleKeys);
+	const band = bandAt(bands, summary.periods, summary.periods[at]);
+	const entries = summary.series.filter((info) => shown.has(info.key) && info.reported[at]).map((info) => ({
+		info,
+		plotted: info.plotted[at],
+		value: info.values[at]
+	})).sort((a, b) => (b.plotted ?? Number.NEGATIVE_INFINITY) - (a.plotted ?? Number.NEGATIVE_INFINITY)).map(({ info, plotted, value }) => ({
+		key: info.key,
+		label: info.label,
+		color: info.color,
+		isFocus: info.key === summary.focusKey,
+		valueText: formatters.formatValue(value),
+		plottedText: transformed ? formatters.formatPlotted(plotted) : null
+	}));
+	return {
+		periodText: formatters.formatX(summary.periods[at]),
+		bandText: band ? band.label ?? formatters.formatXRange(band.start, band.end) : null,
+		entries,
+		targetText: target != null ? formatters.formatValue(target) : null
+	};
+}
+/**
+* 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
+* visible series' latest reading is listed, so nothing lives only in the lines.
+*/
+function buildTrendDescription({ name, state, headline, summary, visibleKeys, span, bands, formatters, targetText, 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 shown = new Set(visibleKeys);
+	const visible = (summary?.series ?? []).filter((info) => shown.has(info.key));
+	const sentences = [];
+	if (headline === "latest" && span) sentences.push(`${name}: ${span.seriesLabel} ${formatters.formatValue(span.to.y)}.`);
+	else if (headline === "change" && span) sentences.push(`${name}: ${span.seriesLabel} ${span.delta.text} over ${span.rangeText}.`);
+	else sentences.push(`${name}.`);
+	if (span) {
+		const flat = span.delta.direction === "flat";
+		const word = span.delta.direction === "up" ? labels.increase : span.delta.direction === "down" ? labels.decrease : labels.unchanged;
+		sentences.push(labels.spanSentence({
+			word,
+			series: span.seriesLabel,
+			primary: flat ? "" : stripSign(span.delta.text),
+			secondary: flat || !span.delta.secondaryText ? null : stripSign(span.delta.secondaryText),
+			range: span.rangeText,
+			from: formatters.formatValue(span.from.y),
+			to: formatters.formatValue(span.to.y)
+		}));
+		if (span.peak && span.trough) sentences.push(labels.extremesSentence({
+			peak: formatters.formatValue(span.peak.y),
+			peakAt: formatters.formatX(span.peak.x),
+			trough: formatters.formatValue(span.trough.y),
+			troughAt: formatters.formatX(span.trough.x)
+		}));
+	}
+	if (visible.length > 0) {
+		const list = visible.map((info) => `${info.label} ${formatters.formatValue(info.latest?.y)}`).join(", ");
+		sentences.push(labels.seriesSummary(visible.length, list));
+	}
+	if (summary && summary.folded > 0) sentences.push(labels.foldedSummary(summary.folded));
+	if (bands.length > 0) {
+		const list = bands.map((band) => band.label ?? formatters.formatXRange(band.start, band.end)).join(", ");
+		sentences.push(labels.bandsSummary(list));
+	}
+	if (targetText) sentences.push(`${labels.target} ${targetText}.`);
+	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 buildTrendChartDescription({ name, mark, summary, visibleKeys, focusLabel, stack, normalize, formatters, targetText, labels }) {
+	const shown = new Set(visibleKeys);
+	const visible = summary.series.filter((info) => shown.has(info.key));
+	const first = summary.periods[0];
+	const last = summary.periods[summary.periods.length - 1];
+	return labels.chartDescription({
+		mark: labels.markNames[mark],
+		name,
+		seriesCount: visible.length,
+		periodCount: summary.periods.length,
+		range: first != null && last != null ? formatters.formatXRange(first, last) : "—",
+		min: formatters.formatPlotted(summary.min),
+		max: formatters.formatPlotted(summary.max),
+		focus: focusLabel,
+		target: targetText ?? null,
+		stacked: stack === "normalize" ? labels.normalized : normalize === "index" && summary.periods.length > 0 ? labels.indexedAt(formatters.formatX(summary.periods[0])) : null
+	});
+}
+//#endregion
+export { DEFAULT_TREND_LABELS, TREND_OTHER_KEY, bandAt, buildLatestRows, buildPeriodRows, buildTrendChartDescription, buildTrendDescription, buildTrendInsight, buildTrendTooltip, createTrendFormatters, deriveTrendDelta, deriveTrendSpan, deriveTrendState, normalizeSeries, resolveBands, resolveSeriesColorMode, resolveTrendLabels, seriesColorAt, trendAxisGranularity };

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

@@ -0,0 +1,4 @@
+import { BuildTrendDescriptionInput, DEFAULT_TREND_LABELS, DeriveTrendDeltaOptions, DeriveTrendSpanOptions, DeriveTrendStateInput, NormalizeSeriesOptions, TREND_OTHER_KEY, TrendBand, TrendBandRow, TrendCardLabels, TrendCardSize, TrendCardState, TrendCardStatus, TrendDelta, TrendDeltaExplanation, TrendDeltaMode, TrendGoodDirection, TrendHeadline, TrendInsightSegment, TrendMark, TrendNormalize, TrendPeriodRow, TrendPoint, TrendPolarity, TrendRow, TrendScale, TrendSeries, TrendSeriesColor, TrendSeriesColorMode, TrendSeriesInfo, TrendSpan, TrendStack, TrendSummary, TrendTextFormatters, TrendTooltipEntry, TrendTooltipModel, TrendXType, bandAt, buildLatestRows, buildPeriodRows, buildTrendChartDescription, buildTrendDescription, buildTrendInsight, buildTrendTooltip, createTrendFormatters, deriveTrendDelta, deriveTrendSpan, deriveTrendState, normalizeSeries, resolveBands, resolveSeriesColorMode, resolveTrendLabels, seriesColorAt, trendAxisGranularity } from "./TrendCard.model.js";
+import { TrendCard, TrendCardProps, TrendLegendMode } from "./TrendCard.js";
+import { TREND_BANDS_DATASET, TREND_HOVER_PARAM, TREND_LATEST_DATASET, TREND_PERIODS_DATASET, TREND_REFERENCE_DATASET, TREND_TABLE_DATASET, TREND_X_TICKS_PARAM, TrendPlotSpecOptions, buildTrendPlotSpec } from "./TrendCard.chart.js";
+export { type BuildTrendDescriptionInput, DEFAULT_TREND_LABELS, type DeriveTrendDeltaOptions, type DeriveTrendSpanOptions, type DeriveTrendStateInput, type NormalizeSeriesOptions, TREND_BANDS_DATASET, TREND_HOVER_PARAM, TREND_LATEST_DATASET, TREND_OTHER_KEY, TREND_PERIODS_DATASET, TREND_REFERENCE_DATASET, TREND_TABLE_DATASET, TREND_X_TICKS_PARAM, type TrendBand, type TrendBandRow, TrendCard, type TrendCardLabels, type TrendCardProps, type TrendCardSize, type TrendCardState, type TrendCardStatus, type TrendDelta, type TrendDeltaExplanation, type TrendDeltaMode, type TrendGoodDirection, type TrendHeadline, type TrendInsightSegment, type TrendLegendMode, type TrendMark, type TrendNormalize, type TrendPeriodRow, type TrendPlotSpecOptions, type TrendPoint, type TrendPolarity, type TrendRow, type TrendScale, type TrendSeries, type TrendSeriesColor, type TrendSeriesColorMode, type TrendSeriesInfo, type TrendSpan, type TrendStack, type TrendSummary, type TrendTextFormatters, type TrendTooltipEntry, type TrendTooltipModel, type TrendXType, bandAt, buildLatestRows, buildPeriodRows, buildTrendChartDescription, buildTrendDescription, buildTrendInsight, buildTrendPlotSpec, buildTrendTooltip, createTrendFormatters, deriveTrendDelta, deriveTrendSpan, deriveTrendState, normalizeSeries, resolveBands, resolveSeriesColorMode, resolveTrendLabels, seriesColorAt, trendAxisGranularity };

package/dist/components/TrendCard/index.js

@@ -0,0 +1,4 @@
+import { TREND_BANDS_DATASET, TREND_HOVER_PARAM, TREND_LATEST_DATASET, TREND_PERIODS_DATASET, TREND_REFERENCE_DATASET, TREND_TABLE_DATASET, TREND_X_TICKS_PARAM, buildTrendPlotSpec } from "./TrendCard.chart.js";
+import { DEFAULT_TREND_LABELS, TREND_OTHER_KEY, bandAt, buildLatestRows, buildPeriodRows, buildTrendChartDescription, buildTrendDescription, buildTrendInsight, buildTrendTooltip, createTrendFormatters, deriveTrendDelta, deriveTrendSpan, deriveTrendState, normalizeSeries, resolveBands, resolveSeriesColorMode, resolveTrendLabels, seriesColorAt, trendAxisGranularity } from "./TrendCard.model.js";
+import { TrendCard } from "./TrendCard.js";
+export { DEFAULT_TREND_LABELS, TREND_BANDS_DATASET, TREND_HOVER_PARAM, TREND_LATEST_DATASET, TREND_OTHER_KEY, TREND_PERIODS_DATASET, TREND_REFERENCE_DATASET, TREND_TABLE_DATASET, TREND_X_TICKS_PARAM, TrendCard, bandAt, buildLatestRows, buildPeriodRows, buildTrendChartDescription, buildTrendDescription, buildTrendInsight, buildTrendPlotSpec, buildTrendTooltip, createTrendFormatters, deriveTrendDelta, deriveTrendSpan, deriveTrendState, normalizeSeries, resolveBands, resolveSeriesColorMode, resolveTrendLabels, seriesColorAt, trendAxisGranularity };