@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/MetricCard/MetricCard.model.js

@@ -0,0 +1,627 @@
+import { formatDate, formatDateRange, formatDelta, formatNumber, parseArcNumberFormat } from "../../lib/vega/formatters.js";
+//#region src/components/MetricCard/MetricCard.model.ts
+const DEFAULT_METRIC_LABELS = {
+	previousPeriod: "vs previous period",
+	increase: "Up",
+	decrease: "Down",
+	unchanged: "No change",
+	ofTarget: "of target",
+	vsTarget: "vs target",
+	percentagePoints: " pp",
+	noData: "No data",
+	noMatch: "No matching data",
+	clearFilters: "Clear filters",
+	error: "Couldn't load this metric",
+	retry: "Try again",
+	insufficientTrend: "Not enough data for a trend",
+	stale: "Stale",
+	asOf: "As of",
+	tablePeriod: "Period",
+	tableValue: "Value",
+	target: "Target",
+	highlightStart: "Start",
+	highlightEnd: "End",
+	highlightChange: "Change",
+	highlightChangePercent: "Change %",
+	highlightRange: "Period",
+	highlighted: "highlighted",
+	versus: (baseline) => `vs ${baseline}`,
+	chooseComparison: (name) => `Choose what ${name} is compared with`,
+	compareWith: "Compare with",
+	previous: "Previous",
+	changePercent: "Change %",
+	changeAmount: "Change",
+	highlightDetails: (name) => `Details of the ${name} highlight`,
+	highlightReadings: (name) => `Readings of ${name} inside the highlighted period`,
+	highlightBefore: "Before",
+	highlightSince: "Since",
+	highlightLatest: "Latest",
+	markNames: {
+		line: "Line",
+		area: "Area",
+		bar: "Bar"
+	},
+	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`,
+	targetProgress: (name) => `${name} progress to target`,
+	targetExplanation: ({ percentText, progressAmountText, targetText, varianceText, direction }) => [
+		["Progress toward target", percentText],
+		[`Amount at ${percentText}`, progressAmountText],
+		["Target", targetText],
+		[direction === "down" ? "Below target" : direction === "up" ? "Above target" : "On target", varianceText]
+	],
+	deltaComparison: (name) => `${name} comparison`,
+	deltaExplanation: ({ kind, previousText, previousLabel, currentText, changeText, secondaryText, renderedMode, direction, comparisonText, periodText }) => {
+		const rows = [];
+		if (kind === "window" && periodText && periodText !== comparisonText) rows.push(["Period", periodText]);
+		rows.push([kind === "window" ? "Start" : previousLabel ?? "Previous", previousText], [kind === "window" ? "End" : "Current", currentText], [direction === "up" ? "Increase" : direction === "down" ? "Decrease" : "No change", changeText]);
+		if (secondaryText) rows.push([renderedMode === "percent" ? "Change" : "Change %", secondaryText]);
+		return rows;
+	},
+	trendSummary: (count, first, last, min, max) => `Trend of ${count} points from ${first} to ${last}, ranging ${min} to ${max}.`,
+	chartDescription: ({ mark, name, count, first, last, min, max, latest, target }) => `${mark} sparkline of ${name}: ${count} points from ${first} to ${last}, ranging ${min} to ${max}, latest ${latest}.` + (target ? ` Reference line at the ${target} target.` : ""),
+	highlightSentence: ({ word, primary, secondary, range, label, from, to }) => {
+		const period = label ? `${label} (${range})` : range;
+		return primary ? `${word} ${primary}${secondary ? ` (${secondary})` : ""} over ${period}, from ${from} to ${to}.` : `${word} over ${period} (${from}).`;
+	},
+	highlightDescription: ({ range, label, from, to, direction, primary }) => {
+		return `Highlighted ${label ? `${label}, ${range}` : range}: ${from} to ${to}, ${direction === "flat" ? "unchanged" : `${direction === "up" ? "up" : "down"} ${primary}`}.`;
+	},
+	insightMark: "Insight",
+	highlightInsight: ({ name, direction, from, to, change, secondary, range }) => {
+		if (direction === "flat") return [
+			`${name} held at `,
+			{ value: from },
+			` over ${range}.`
+		];
+		const segments = [
+			`${name} ${direction === "up" ? "rose" : "fell"} from `,
+			{ value: from },
+			" to ",
+			{ value: to },
+			` over ${range}, a ${direction === "up" ? "rise" : "drop"} of `,
+			{ value: change }
+		];
+		if (secondary) segments.push(" (", { value: secondary }, ")");
+		segments.push(".");
+		return segments;
+	}
+};
+function resolveMetricLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_METRIC_LABELS,
+		...overrides
+	} : DEFAULT_METRIC_LABELS;
+}
+/**
+* The state machine. Error wins; loading over existing data is a refresh (the
+* previous render stays under the veil); a missing value is `no-match` when
+* the consumer's filter caused it and `empty` otherwise.
+*/
+function deriveMetricState({ 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 ].*)?$/;
+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 `trend` for Vega and the table: temporal `x` becomes epoch
+* milliseconds (numbers are treated as quantitative; pass a `Date` or an ISO
+* string for time), invalid dates are dropped, `null` readings are kept as
+* gaps, and the range and the latest reading are summarised for the text
+* equivalents. Returns `null` when there is no trend at all.
+*/
+function normalizeTrend(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
+		});
+	}
+	const valid = rows.filter((row) => row.y != null);
+	let latest = null;
+	if (valid.length > 0) latest = xType === "ordinal" ? valid[valid.length - 1] : valid.reduce((best, row) => row.x >= best.x ? row : best);
+	const values = valid.map((row) => row.y);
+	return {
+		rows,
+		xType,
+		count: valid.length,
+		first: rows[0] ?? null,
+		last: rows[rows.length - 1] ?? null,
+		latest,
+		min: values.length > 0 ? Math.min(...values) : null,
+		max: values.length > 0 ? Math.max(...values) : null,
+		granularity: granularity ?? (xType === "temporal" ? inferGranularity(rows) : "day")
+	};
+}
+/** The comparison against the previous reading, with polarity resolved through `goodDirection`. */
+function deriveDelta(value, previousValue, { deltaMode, goodDirection, format, locale, percentagePoints }) {
+	if (!isFinite(value) || !isFinite(previousValue)) return null;
+	const delta = formatDelta(value, previousValue, {
+		mode: deltaMode,
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	const other = formatDelta(value, previousValue, {
+		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
+	};
+}
+/** Progress against the target. `null` without a usable target (a zero target has no ratio). */
+function deriveTarget(value, target, { goodDirection, format, locale, formatValue }) {
+	if (!isFinite(value) || !isFinite(target) || target === 0) return null;
+	const ratio = value / target;
+	const displayedRatio = Math.sign(ratio) * Math.round(Math.abs(ratio) * 100) / 100;
+	const progressAmount = displayedRatio * target;
+	const amountFormat = parseArcNumberFormat(format);
+	const amountPrecision = amountFormat.kind === "compact" || amountFormat.compact ? { maximumFractionDigits: Math.max(2, amountFormat.digits ?? 1) } : void 0;
+	const met = goodDirection === "down" ? value <= target : value >= target;
+	const variant = goodDirection === "none" ? "primary" : met ? "success" : goodDirection === "down" ? "destructive" : "primary";
+	const variance = formatDelta(value, target, {
+		mode: "percent",
+		format,
+		locale
+	});
+	return {
+		ratio,
+		met,
+		variant,
+		percentText: formatNumber(displayedRatio, "percent:0", locale),
+		progressAmountText: formatValue ? formatValue(progressAmount) : formatNumber(progressAmount, format, locale, amountPrecision),
+		targetText: formatValue ? formatValue(target) : formatNumber(target, format, locale),
+		varianceText: variance.text,
+		direction: variance.direction
+	};
+}
+/**
+* The granularity an x axis labels its ticks at: the tooltip and table keep
+* the full form (`Sep 8, 2026`); a 250px axis has room for `Sep 8`.
+*/
+function axisGranularity(granularity) {
+	switch (granularity) {
+		case "day": return "day-short";
+		case "month": return "month-short";
+		case "datetime": return "time";
+		default: return granularity;
+	}
+}
+/** The two formatters every text surface shares — headline, delta, table, tooltip, descriptions. */
+function createMetricFormatters({ format, locale, timeZone, formatValue, xType, granularity }) {
+	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);
+	};
+	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)}`
+	};
+}
+function normalizeHighlightBound(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);
+}
+const stripSign = (text) => text.replace(/^[+\-−]/, "");
+/**
+* Snaps a highlight window onto the trend and measures it. Each bound moves
+* inward to the nearest finite reading (a temporal or quantitative bound need
+* not hit a point 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 card then draws the plain sparkline
+* and stamps `data-highlight="unresolved"` rather than inventing a change.
+*/
+function resolveHighlight(summary, range, { deltaMode, goodDirection, format, locale, percentagePoints, formatters }) {
+	if (!summary || !range) return null;
+	const { rows, xType } = summary;
+	const lo = normalizeHighlightBound(range.start, xType);
+	const hi = normalizeHighlightBound(range.end, xType);
+	if (lo == null || hi == null) return null;
+	let startIndex = -1;
+	let endIndex = -1;
+	if (xType === "ordinal") {
+		let first = rows.findIndex((row) => row.x === lo);
+		let last = -1;
+		for (let index = rows.length - 1; index >= 0; index -= 1) if (rows[index].x === hi) {
+			last = index;
+			break;
+		}
+		if (first < 0 || last < 0) return null;
+		if (first > last) [first, last] = [last, first];
+		while (first <= last && rows[first].y == null) first += 1;
+		while (last >= first && rows[last].y == null) last -= 1;
+		if (first >= last) return null;
+		startIndex = first;
+		endIndex = last;
+	} else {
+		const [min, max] = lo <= hi ? [lo, hi] : [hi, lo];
+		rows.forEach((row, index) => {
+			if (row.y == null || typeof row.x !== "number" || row.x < min || row.x > max) return;
+			if (startIndex < 0 || row.x < rows[startIndex].x) startIndex = index;
+			if (endIndex < 0 || row.x > rows[endIndex].x) endIndex = index;
+		});
+		if (startIndex < 0 || endIndex < 0 || rows[startIndex].x === rows[endIndex].x) return null;
+	}
+	const start = {
+		x: rows[startIndex].x,
+		y: rows[startIndex].y,
+		index: startIndex
+	};
+	const end = {
+		x: rows[endIndex].x,
+		y: rows[endIndex].y,
+		index: endIndex
+	};
+	const delta = deriveDelta(end.y, start.y, {
+		deltaMode,
+		goodDirection,
+		format,
+		locale,
+		percentagePoints
+	});
+	if (!delta) return null;
+	const absolute = formatDelta(end.y, start.y, {
+		mode: "absolute",
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	const percent = formatDelta(end.y, start.y, {
+		mode: "percent",
+		format,
+		locale
+	});
+	return {
+		start,
+		end,
+		label: range.label,
+		rangeText: formatters.formatXRange(start.x, end.x),
+		delta,
+		absoluteText: absolute.text,
+		percentText: percent.percent == null ? "—" : percent.text
+	};
+}
+/**
+* The highlight variant's default insight sentence — what the card shows
+* beside the AI mark when the consumer passes no `insight`. The window's start
+* and end readings and its change (in the badge's form, with the other form
+* in brackets) come back as `{ value }` segments so the card can set them in
+* bold; the words come from `labels.highlightInsight`.
+*/
+function buildHighlightInsight({ name, highlight, formatters, labels }) {
+	const flat = highlight.delta.direction === "flat";
+	const secondary = highlight.delta.renderedMode === "percent" ? highlight.absoluteText : highlight.percentText;
+	return labels.highlightInsight({
+		name,
+		direction: highlight.delta.direction,
+		from: formatters.formatY(highlight.start.y),
+		to: formatters.formatY(highlight.end.y),
+		change: flat ? "" : stripSign(highlight.delta.text),
+		secondary: flat || secondary === "—" ? null : stripSign(secondary),
+		range: highlight.rangeText,
+		label: highlight.label
+	});
+}
+/** The plain-text reading of insight segments — for descriptions and tests. */
+function insightSegmentsToText(segments) {
+	return segments.map((segment) => typeof segment === "string" ? segment : segment.value).join("");
+}
+/**
+* The datasets the highlight sparkline reads, derived once per trend or window
+* change: every row flagged with `hl` (bars colour themselves from it, the
+* hover dot too), the context readings split into a `before` and an `after`
+* run so the gray line stops at the window's edges, the window's own readings
+* for the coloured segment, its two endpoint dots, and the one-row band. A
+* continuous axis decides membership by `x`, an ordinal one by position.
+*/
+function buildHighlightDatasets(summary, info) {
+	const { rows, xType } = summary;
+	const tone = info.delta.polarity;
+	const at = (row, index) => xType === "ordinal" ? index : row.x;
+	const startAt = at(rows[info.start.index], info.start.index);
+	const endAt = at(rows[info.end.index], info.end.index);
+	const table = [];
+	const context = [];
+	const highlightRows = [];
+	rows.forEach((row, index) => {
+		const position = at(row, index);
+		const inside = position >= startAt && position <= endAt;
+		table.push({
+			...row,
+			hl: inside,
+			tone: inside ? tone : null
+		});
+		if (inside) highlightRows.push({
+			...row,
+			hl: true,
+			tone
+		});
+		if (position <= startAt) context.push({
+			...row,
+			seg: "before"
+		});
+		if (position >= endAt) context.push({
+			...row,
+			seg: "after"
+		});
+	});
+	return {
+		table,
+		context,
+		highlightRows,
+		highlightPoints: [{
+			x: info.start.x,
+			y: info.start.y,
+			role: "start",
+			tone
+		}, {
+			x: info.end.x,
+			y: info.end.y,
+			role: "end",
+			tone
+		}],
+		highlight: [{
+			start: info.start.x,
+			end: info.end.x,
+			startY: info.start.y,
+			endY: info.end.y,
+			tone
+		}]
+	};
+}
+/** The key of the one baseline a tile builds from `previousValue` for its compare-with menu. Never collides with a consumer's key. */
+const METRIC_PREVIOUS_KEY = "__previous__";
+/**
+* Normalises the baselines a metric tile offers: keys default to labels (a
+* repeated key is suffixed so two options never collide), non-finite values
+* become `null`. The consumer's order is kept — it is the menu's order.
+*/
+function normalizeComparisons(items) {
+	if (!items) return [];
+	const seen = /* @__PURE__ */ new Map();
+	return items.map((item) => {
+		const base = item.key ?? item.label;
+		const repeats = seen.get(base) ?? 0;
+		seen.set(base, repeats + 1);
+		return {
+			key: repeats === 0 ? base : `${base}·${repeats + 1}`,
+			label: item.label,
+			value: isFinite(item.value) ? item.value : null
+		};
+	});
+}
+/**
+* The selected baseline. `null` designates none; a key names one — an absent
+* key selects none rather than a substitute, so the card never compares
+* against something the app did not ask for; `undefined` takes the first
+* baseline with a value, else the first baseline.
+*/
+function resolveComparison(rows, key) {
+	if (key === null) return null;
+	if (key !== void 0) return rows.find((row) => row.key === key) ?? null;
+	return rows.find((row) => row.value != null) ?? rows[0] ?? null;
+}
+/** The compare-with menu's table: every baseline with the change the headline would show against it, in percent and in the value's units. */
+function describeComparisons(rows, value, { formatters, ...options }) {
+	return rows.map((row) => {
+		const delta = deriveDelta(value, row.value, options);
+		const percentText = delta ? delta.renderedMode === "percent" ? delta.text : delta.secondaryText : null;
+		const amountText = delta ? delta.renderedMode === "absolute" ? delta.text : delta.secondaryText : null;
+		return {
+			row,
+			delta,
+			polarity: delta?.polarity ?? "neutral",
+			valueText: formatters.formatY(row.value),
+			percentText: percentText ?? "—",
+			amountText: amountText ?? "—"
+		};
+	});
+}
+/**
+* The detail behind a resolved window — what the sparkline cannot show at
+* tile scale: the readings inside the window one by one, each with its step
+* from the previous finite reading, and the trend's movement before the
+* window and since it, so the reader can tell a step change from a slide and
+* a recovery from a plateau. A continuous axis decides membership by `x`, an
+* ordinal one by position.
+*/
+function buildHighlightDetails(summary, info, { deltaMode, goodDirection, format, locale, percentagePoints, formatters }) {
+	const { rows, xType } = summary;
+	const deltaOptions = {
+		deltaMode,
+		goodDirection,
+		format,
+		locale,
+		percentagePoints
+	};
+	const at = (row, index) => xType === "ordinal" ? index : row.x;
+	const startAt = at(rows[info.start.index], info.start.index);
+	const endAt = at(rows[info.end.index], info.end.index);
+	const reading = (row) => ({
+		x: row.x,
+		xText: formatters.formatX(row.x),
+		yText: formatters.formatY(row.y)
+	});
+	const inside = [];
+	let first = null;
+	let firstAt = Number.POSITIVE_INFINITY;
+	let latest = null;
+	let latestAt = Number.NEGATIVE_INFINITY;
+	for (let index = 0; index < rows.length; index += 1) {
+		const row = rows[index];
+		const position = at(row, index);
+		if (position >= startAt && position <= endAt) inside.push({
+			row,
+			index,
+			position
+		});
+		if (row.y == null) continue;
+		if (position < startAt && position < firstAt) {
+			first = row;
+			firstAt = position;
+		}
+		if (position > endAt && position > latestAt) {
+			latest = row;
+			latestAt = position;
+		}
+	}
+	inside.sort((a, b) => a.position - b.position);
+	let previous = null;
+	const steps = inside.map(({ row, index }) => {
+		const delta = row.y != null && previous != null ? deriveDelta(row.y, previous, deltaOptions) : null;
+		if (row.y != null) previous = row.y;
+		return {
+			...reading(row),
+			changeText: delta?.text ?? null,
+			polarity: delta?.polarity ?? "neutral",
+			role: index === info.start.index ? "start" : index === info.end.index ? "end" : "inside"
+		};
+	});
+	const stretch = (from, to) => {
+		const delta = deriveDelta(to.y, from.y, deltaOptions);
+		if (!delta) return null;
+		return {
+			from: reading(from),
+			to: reading(to),
+			rangeText: formatters.formatXRange(from.x, to.x),
+			changeText: delta.text,
+			secondaryText: delta.secondaryText,
+			direction: delta.direction,
+			polarity: delta.polarity
+		};
+	};
+	return {
+		steps,
+		before: first ? stretch(first, rows[info.start.index]) : null,
+		since: latest ? stretch(rows[info.end.index], latest) : 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.
+*/
+function buildMetricDescription({ name, state, valueText, unit, delta, comparisonText, target, trend, formatters, asOfText, labels, highlight }) {
+	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 directionWord = (direction) => direction === "up" ? labels.increase : direction === "down" ? labels.decrease : labels.unchanged;
+	const sentences = [`${name}: ${valueText}${unit ? ` ${unit}` : ""}.`];
+	if (highlight) {
+		const flat = highlight.delta.direction === "flat";
+		const secondary = highlight.delta.renderedMode === "percent" ? highlight.absoluteText : highlight.percentText;
+		sentences.push(labels.highlightSentence({
+			word: directionWord(highlight.delta.direction),
+			primary: flat ? "" : stripSign(highlight.delta.text),
+			secondary: flat || secondary === "—" ? null : stripSign(secondary),
+			range: highlight.rangeText,
+			label: highlight.label,
+			from: formatters.formatY(highlight.start.y),
+			to: formatters.formatY(highlight.end.y)
+		}));
+	} else if (delta) {
+		const word = directionWord(delta.direction);
+		const magnitude = stripSign(delta.text);
+		sentences.push(delta.direction === "flat" ? `${word} ${comparisonText}.` : `${word} ${magnitude} ${comparisonText}.`);
+	}
+	if (target) sentences.push(`${target.percentText} ${labels.ofTarget} (${target.targetText}).`);
+	if (trend && trend.count >= 2 && trend.first && trend.last) sentences.push(labels.trendSummary(trend.count, formatters.formatX(trend.first.x), formatters.formatX(trend.last.x), formatters.formatY(trend.min), formatters.formatY(trend.max)));
+	if (asOfText) sentences.push(`${labels.asOf} ${asOfText}.`);
+	return sentences.join(" ");
+}
+/** The sparkline's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+function buildMetricChartDescription({ name, mark, trend, target, formatters, labels, highlight }) {
+	const base = labels.chartDescription({
+		mark: labels.markNames[mark],
+		name,
+		count: trend.count,
+		first: trend.first ? formatters.formatX(trend.first.x) : "—",
+		last: trend.last ? formatters.formatX(trend.last.x) : "—",
+		min: formatters.formatY(trend.min),
+		max: formatters.formatY(trend.max),
+		latest: trend.latest ? formatters.formatY(trend.latest.y) : "—",
+		target: target ? target.targetText : null
+	});
+	if (!highlight) return base;
+	return `${base} ${labels.highlightDescription({
+		range: highlight.rangeText,
+		label: highlight.label,
+		from: formatters.formatY(highlight.start.y),
+		to: formatters.formatY(highlight.end.y),
+		direction: highlight.delta.direction,
+		primary: stripSign(highlight.delta.text)
+	})}`;
+}
+//#endregion
+export { DEFAULT_METRIC_LABELS, METRIC_PREVIOUS_KEY, axisGranularity, buildHighlightDatasets, buildHighlightDetails, buildHighlightInsight, buildMetricChartDescription, buildMetricDescription, createMetricFormatters, deriveDelta, deriveMetricState, deriveTarget, describeComparisons, insightSegmentsToText, normalizeComparisons, normalizeTrend, resolveComparison, resolveHighlight, resolveMetricLabels };

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

@@ -0,0 +1,4 @@
+import { DEFAULT_METRIC_LABELS, DescribeComparisonsOptions, METRIC_PREVIOUS_KEY, MetricCardLabels, MetricCardSize, MetricCardState, MetricCardStatus, MetricCardVariant, MetricComparison, MetricComparisonCandidate, MetricComparisonRow, MetricDelta, MetricDeltaExplanation, MetricDeltaMode, MetricGoodDirection, MetricHighlightBand, MetricHighlightContextRow, MetricHighlightDatasets, MetricHighlightDetails, MetricHighlightInfo, MetricHighlightPoint, MetricHighlightRange, MetricHighlightReading, MetricHighlightReadingText, MetricHighlightStep, MetricHighlightStretch, MetricHighlightTrendRow, MetricInsightSegment, MetricPolarity, MetricTargetInfo, MetricTextFormatters, MetricTrendAxes, MetricTrendMark, MetricTrendPoint, MetricTrendRow, MetricTrendScale, MetricTrendSummary, MetricTrendXType, ResolveHighlightOptions, axisGranularity, buildHighlightDatasets, buildHighlightDetails, buildHighlightInsight, buildMetricChartDescription, buildMetricDescription, createMetricFormatters, deriveDelta, deriveMetricState, deriveTarget, describeComparisons, insightSegmentsToText, normalizeComparisons, normalizeTrend, resolveComparison, resolveHighlight, resolveMetricLabels } from "./MetricCard.model.js";
+import { MetricCard, MetricCardBaseProps, MetricCardComparisonProps, MetricCardProps, MetricCardVariantProps } from "./MetricCard.js";
+import { METRIC_CONTEXT_DATASET, METRIC_HIGHLIGHT_DATASET, METRIC_HIGHLIGHT_END_PARAM, METRIC_HIGHLIGHT_POINTS_DATASET, METRIC_HIGHLIGHT_ROWS_DATASET, METRIC_HIGHLIGHT_START_PARAM, METRIC_HOVER_PARAM, METRIC_LATEST_DATASET, METRIC_REFERENCE_DATASET, METRIC_TREND_DATASET, METRIC_X_TICKS_PARAM, MetricTrendSpecOptions, buildMetricTrendSpec } from "./MetricCard.chart.js";
+export { DEFAULT_METRIC_LABELS, type DescribeComparisonsOptions, METRIC_CONTEXT_DATASET, METRIC_HIGHLIGHT_DATASET, METRIC_HIGHLIGHT_END_PARAM, METRIC_HIGHLIGHT_POINTS_DATASET, METRIC_HIGHLIGHT_ROWS_DATASET, METRIC_HIGHLIGHT_START_PARAM, METRIC_HOVER_PARAM, METRIC_LATEST_DATASET, METRIC_PREVIOUS_KEY, METRIC_REFERENCE_DATASET, METRIC_TREND_DATASET, METRIC_X_TICKS_PARAM, MetricCard, type MetricCardBaseProps, type MetricCardComparisonProps, type MetricCardLabels, type MetricCardProps, type MetricCardSize, type MetricCardState, type MetricCardStatus, type MetricCardVariant, type MetricCardVariantProps, type MetricComparison, type MetricComparisonCandidate, type MetricComparisonRow, type MetricDelta, type MetricDeltaExplanation, type MetricDeltaMode, type MetricGoodDirection, type MetricHighlightBand, type MetricHighlightContextRow, type MetricHighlightDatasets, type MetricHighlightDetails, type MetricHighlightInfo, type MetricHighlightPoint, type MetricHighlightRange, type MetricHighlightReading, type MetricHighlightReadingText, type MetricHighlightStep, type MetricHighlightStretch, type MetricHighlightTrendRow, type MetricInsightSegment, type MetricPolarity, type MetricTargetInfo, type MetricTextFormatters, type MetricTrendAxes, type MetricTrendMark, type MetricTrendPoint, type MetricTrendRow, type MetricTrendScale, type MetricTrendSpecOptions, type MetricTrendSummary, type MetricTrendXType, type ResolveHighlightOptions, axisGranularity, buildHighlightDatasets, buildHighlightDetails, buildHighlightInsight, buildMetricChartDescription, buildMetricDescription, buildMetricTrendSpec, createMetricFormatters, deriveDelta, deriveMetricState, deriveTarget, describeComparisons, insightSegmentsToText, normalizeComparisons, normalizeTrend, resolveComparison, resolveHighlight, resolveMetricLabels };

package/dist/components/MetricCard/index.js

@@ -0,0 +1,4 @@
+import { METRIC_CONTEXT_DATASET, METRIC_HIGHLIGHT_DATASET, METRIC_HIGHLIGHT_END_PARAM, METRIC_HIGHLIGHT_POINTS_DATASET, METRIC_HIGHLIGHT_ROWS_DATASET, METRIC_HIGHLIGHT_START_PARAM, METRIC_HOVER_PARAM, METRIC_LATEST_DATASET, METRIC_REFERENCE_DATASET, METRIC_TREND_DATASET, METRIC_X_TICKS_PARAM, buildMetricTrendSpec } from "./MetricCard.chart.js";
+import { DEFAULT_METRIC_LABELS, METRIC_PREVIOUS_KEY, axisGranularity, buildHighlightDatasets, buildHighlightDetails, buildHighlightInsight, buildMetricChartDescription, buildMetricDescription, createMetricFormatters, deriveDelta, deriveMetricState, deriveTarget, describeComparisons, insightSegmentsToText, normalizeComparisons, normalizeTrend, resolveComparison, resolveHighlight, resolveMetricLabels } from "./MetricCard.model.js";
+import { MetricCard } from "./MetricCard.js";
+export { DEFAULT_METRIC_LABELS, METRIC_CONTEXT_DATASET, METRIC_HIGHLIGHT_DATASET, METRIC_HIGHLIGHT_END_PARAM, METRIC_HIGHLIGHT_POINTS_DATASET, METRIC_HIGHLIGHT_ROWS_DATASET, METRIC_HIGHLIGHT_START_PARAM, METRIC_HOVER_PARAM, METRIC_LATEST_DATASET, METRIC_PREVIOUS_KEY, METRIC_REFERENCE_DATASET, METRIC_TREND_DATASET, METRIC_X_TICKS_PARAM, MetricCard, axisGranularity, buildHighlightDatasets, buildHighlightDetails, buildHighlightInsight, buildMetricChartDescription, buildMetricDescription, buildMetricTrendSpec, createMetricFormatters, deriveDelta, deriveMetricState, deriveTarget, describeComparisons, insightSegmentsToText, normalizeComparisons, normalizeTrend, resolveComparison, resolveHighlight, resolveMetricLabels };