@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/InsightCard/InsightCard.model.js

@@ -0,0 +1,421 @@
+import { formatDate, formatDelta, formatNumber, parseArcNumberFormat } from "../../lib/vega/formatters.js";
+//#region src/components/InsightCard/InsightCard.model.ts
+const isFinite = (value) => typeof value === "number" && Number.isFinite(value);
+/** Default severity ladders, per scale. Sigma takes the conventional 2σ / 3σ; a band counts half-widths, so 1 is the edge. */
+const DEFAULT_SEVERITY_THRESHOLDS = {
+	sigma: {
+		notable: 2,
+		critical: 3
+	},
+	band: {
+		notable: 1,
+		critical: 2
+	},
+	relative: {
+		notable: .1,
+		critical: .25
+	}
+};
+/** Confidence at or above these reads as high, then moderate; below, low. */
+const CONFIDENCE_BOUNDS = {
+	high: .9,
+	moderate: .7
+};
+/** Buckets a 0–1 confidence for the provenance line. `null` for anything outside the range. */
+function insightConfidenceLevel(confidence) {
+	if (!isFinite(confidence) || confidence < 0 || confidence > 1) return null;
+	if (confidence >= CONFIDENCE_BOUNDS.high) return "high";
+	if (confidence >= CONFIDENCE_BOUNDS.moderate) return "moderate";
+	return "low";
+}
+/** Guesses the axis kind from the first reading that has an `x`. */
+function inferInsightXType(points) {
+	const first = (points ?? []).find((point) => point.x != null);
+	if (!first) return "temporal";
+	if (first.x instanceof Date) return "temporal";
+	if (typeof first.x === "number") return Number.isFinite(first.x) ? "quantitative" : "temporal";
+	return Number.isNaN(new Date(first.x).getTime()) ? "ordinal" : "temporal";
+}
+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);
+}
+/** How the deviation is measured, given what the detector actually reported. */
+function resolveStrength(value, expected, lower, upper, sd) {
+	if (value == null || expected == null) return {
+		strength: null,
+		kind: null
+	};
+	const deviation = Math.abs(value - expected);
+	if (isFinite(sd) && sd > 0) return {
+		strength: deviation / sd,
+		kind: "sigma"
+	};
+	if (isFinite(lower) && isFinite(upper) && upper > lower) return {
+		strength: deviation / ((upper - lower) / 2),
+		kind: "band"
+	};
+	if (expected !== 0) return {
+		strength: deviation / Math.abs(expected),
+		kind: "relative"
+	};
+	return {
+		strength: null,
+		kind: null
+	};
+}
+/** The severity the strength supports. Never guesses from a scale the data does not establish. */
+function deriveInsightSeverity(strength, kind, overrides) {
+	if (strength == null || kind == null) return "info";
+	const base = DEFAULT_SEVERITY_THRESHOLDS[kind];
+	const critical = overrides?.critical ?? base.critical;
+	const notable = overrides?.notable ?? base.notable;
+	if (strength >= critical) return "critical";
+	if (strength >= notable) return "notable";
+	return "info";
+}
+/** How a deviation reads once the measure's good direction is applied. */
+function deriveInsightPolarity(direction, goodDirection) {
+	if (goodDirection === "none" || direction === "flat") return "neutral";
+	return direction === (goodDirection === "up" ? "up" : "down") ? "positive" : "negative";
+}
+const STRIP_PADDING = .1;
+/**
+* Resolves the finding: which reading is flagged, what was expected of it,
+* how far off it is and on which scale, how that reads as severity and
+* polarity, which evidence form the data can carry, and the rows each form
+* draws. Returns `null` when there is neither a reading nor a history to
+* speak of.
+*/
+function normalizeInsight({ observation, points, xType: xTypeProp, goodDirection = "none", evidence = "auto", severity: severityOverride, severityThresholds, tokens }) {
+	const source = points ?? [];
+	const xType = xTypeProp ?? inferInsightXType(source);
+	const atX = observation?.at != null ? normalizeX(observation.at, xType) : null;
+	const rows = [];
+	const flags = [];
+	source.forEach((point) => {
+		const x = normalizeX(point.x, xType);
+		if (x == null) return;
+		rows.push({
+			x,
+			y: isFinite(point.y) ? point.y : null,
+			e: isFinite(point.expected) ? point.expected : null,
+			lo: isFinite(point.lower) ? point.lower : null,
+			hi: isFinite(point.upper) ? point.upper : null
+		});
+		flags.push(point.flagged === true);
+	});
+	if (xType !== "ordinal") {
+		const order = rows.map((_, index) => index).sort((a, b) => rows[a].x - rows[b].x);
+		const sortedRows = order.map((index) => rows[index]);
+		const sortedFlags = order.map((index) => flags[index]);
+		rows.length = 0;
+		rows.push(...sortedRows);
+		flags.length = 0;
+		flags.push(...sortedFlags);
+	}
+	let flaggedIndex = flags.findIndex(Boolean);
+	if (flaggedIndex < 0 && atX != null) flaggedIndex = rows.findIndex((row) => row.x === atX);
+	if (flaggedIndex < 0) {
+		for (let index = rows.length - 1; index >= 0; index -= 1) if (rows[index].y != null) {
+			flaggedIndex = index;
+			break;
+		}
+	}
+	const flaggedRow = flaggedIndex >= 0 ? rows[flaggedIndex] : void 0;
+	const value = isFinite(observation?.value) ? observation.value : flaggedRow?.y ?? null;
+	if (value == null && rows.length === 0) return null;
+	const lower = isFinite(observation?.lower) ? observation.lower : flaggedRow?.lo ?? null;
+	const upper = isFinite(observation?.upper) ? observation.upper : flaggedRow?.hi ?? null;
+	const midpoint = isFinite(lower) && isFinite(upper) ? (lower + upper) / 2 : null;
+	const expected = isFinite(observation?.expected) ? observation.expected : flaggedRow?.e ?? midpoint;
+	const sd = isFinite(observation?.sd) ? observation.sd : null;
+	const deviation = value != null && expected != null ? value - expected : null;
+	const relative = deviation != null && expected != null && expected !== 0 ? deviation / Math.abs(expected) : null;
+	const outside = value != null && (isFinite(lower) && value < lower || isFinite(upper) && value > upper);
+	const direction = deviation == null || deviation === 0 ? "flat" : deviation > 0 ? "up" : "down";
+	const polarity = deriveInsightPolarity(direction, goodDirection);
+	const { strength, kind } = resolveStrength(value, expected, lower, upper, sd);
+	const severity = severityOverride ?? deriveInsightSeverity(strength, kind, severityThresholds);
+	const color = polarity === "positive" ? tokens?.positive ?? "" : polarity === "negative" ? tokens?.negative ?? "" : tokens?.emphasis ?? "";
+	const finite = rows.filter((row) => row.y != null).length;
+	const insufficient = finite < 2;
+	const hasBand = rows.filter((row) => row.lo != null && row.hi != null).length >= 2;
+	const hasExpectedLine = rows.filter((row) => row.e != null).length >= 2;
+	const canSpark = finite >= 2;
+	const canRange = value != null && (isFinite(lower) || isFinite(upper) || isFinite(expected));
+	const resolvedEvidence = evidence === "none" ? "none" : evidence === "spark" ? canSpark ? "spark" : canRange ? "range" : "none" : evidence === "range" ? canRange ? "range" : "none" : canSpark ? "spark" : canRange ? "range" : "none";
+	const pointRows = rows.map((row, index) => ({
+		...row,
+		f: index === flaggedIndex,
+		c: color
+	}));
+	const interval = resolvedEvidence === "spark" && !hasBand && flaggedRow && isFinite(lower) && isFinite(upper) ? [{
+		x: flaggedRow.x,
+		lo: lower,
+		hi: upper
+	}] : [];
+	const strip = [];
+	if (resolvedEvidence === "range" && value != null) {
+		const marks = [
+			value,
+			expected,
+			lower,
+			upper
+		].filter(isFinite);
+		let d0 = Math.min(...marks);
+		let d1 = Math.max(...marks);
+		if (d1 === d0) {
+			const pad = Math.max(Math.abs(d0) * STRIP_PADDING, 1);
+			d0 -= pad;
+			d1 += pad;
+		} else {
+			const pad = (d1 - d0) * STRIP_PADDING;
+			d0 -= pad;
+			d1 += pad;
+		}
+		strip.push({
+			lo: lower,
+			hi: upper,
+			e: expected,
+			v: value,
+			d0,
+			d1,
+			c: color
+		});
+	}
+	return {
+		value,
+		expected,
+		lower,
+		upper,
+		sd,
+		deviation,
+		relative,
+		outside,
+		strength,
+		strengthKind: kind,
+		direction,
+		polarity,
+		severity,
+		color,
+		evidence: resolvedEvidence,
+		xType,
+		points: resolvedEvidence === "spark" ? pointRows : [],
+		interval,
+		strip,
+		flaggedX: flaggedRow?.x ?? null,
+		at: observation?.at ?? null,
+		count: finite,
+		hasBand,
+		hasExpectedLine,
+		insufficient
+	};
+}
+function createInsightFormatters({ format, locale, deltaMode, formatValue, labels }) {
+	const value = (input) => isFinite(input) ? formatValue ? formatValue(input) : formatNumber(input, format, locale) : "—";
+	return {
+		formatValue: value,
+		formatRange: (lower, upper) => isFinite(lower) && isFinite(upper) ? labels.rangeText(value(lower), value(upper)) : null,
+		formatDeviation: (current, expected) => formatDelta(current, expected, {
+			mode: deltaMode,
+			format,
+			locale
+		}).text,
+		formatStrength: (strength, kind) => {
+			if (strength == null || kind == null) return null;
+			if (kind === "sigma") return labels.sigmaText(formatNumber(strength, "number:1", locale));
+			if (kind === "band") return labels.bandText(formatNumber(strength, "number:1", locale));
+			return labels.relativeText(formatNumber(strength, "percent:0", locale));
+		}
+	};
+}
+const DEFAULT_INSIGHT_LABELS = {
+	noData: "No insight",
+	noMatch: "No matching insight",
+	clearFilters: "Clear filters",
+	error: "Couldn't load this insight",
+	retry: "Try again",
+	stale: "Stale",
+	asOf: "As of",
+	observed: "Observed",
+	expected: "Expected",
+	deviation: "vs expected",
+	rangeText: (lower, upper) => `${lower} – ${upper}`,
+	outsideRange: (range) => `Outside the expected ${range}.`,
+	insideRange: (range) => `Within the expected ${range}.`,
+	sigmaText: (value) => `${value}σ from expected`,
+	bandText: (value) => `${value}× the expected range`,
+	relativeText: (value) => `${value} from expected`,
+	detected: (when) => `Detected ${when}`,
+	sample: (count) => `${count} readings`,
+	confidence: (level, percent) => `${level} confidence (${percent})`,
+	confidenceNames: {
+		high: "High",
+		moderate: "Moderate",
+		low: "Low"
+	},
+	kindNames: {
+		anomaly: "Anomaly",
+		trend: "Trend",
+		threshold: "Threshold",
+		outlier: "Outlier",
+		correlation: "Correlation",
+		forecast: "Forecast",
+		milestone: "Milestone",
+		note: "Note"
+	},
+	severityNames: {
+		info: "Info",
+		notable: "Notable",
+		critical: "Critical"
+	},
+	badge: (severity, kind, key) => key === "info" ? kind : `${severity} ${kind.toLowerCase()}`,
+	directionWords: {
+		up: "up",
+		down: "down",
+		flat: "unchanged"
+	},
+	dismiss: (name) => `Dismiss ${name}`,
+	helpful: "Helpful",
+	notHelpful: "Not helpful",
+	feedbackGroup: (name) => `Was ${name} helpful?`,
+	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 ${name}`,
+	tablePeriod: "Period",
+	tableValue: "Reading",
+	tableExpected: "Expected",
+	tableRange: "Expected range",
+	tableFlagged: "Flagged",
+	flagged: "flagged",
+	needsHistory: "Not enough history to plot a trend.",
+	evidenceNames: {
+		spark: "Sparkline",
+		range: "Range strip"
+	},
+	chartDescription: ({ evidence, name, readings, observed, expected, range, at }) => `${evidence} of ${name}${readings > 0 ? `, ${readings} ${readings === 1 ? "reading" : "readings"}` : ""}. Flagged reading ${observed}${at ? ` at ${at}` : ""}.` + (expected ? ` Expected ${expected}.` : "") + (range ? ` Expected range ${range}.` : ""),
+	claim: ({ kind, name, observed, expected, deviation }) => `${kind} in ${name}: ${observed}` + (expected ? ` against an expected ${expected}` : "") + (deviation ? ` (${deviation})` : "") + ".",
+	insightMark: "Insight"
+};
+function resolveInsightLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_INSIGHT_LABELS,
+		...overrides
+	} : DEFAULT_INSIGHT_LABELS;
+}
+/**
+* The state machine. Error wins; loading over an existing finding is a
+* refresh (the previous render stays under the veil); a finding with too
+* little history to plot is `insufficient`, not `ready` — the claim still
+* reads, only the time plot degrades; nothing to say is `no-match` when the
+* consumer's filter caused it and `empty` otherwise.
+*/
+function deriveInsightState({ status, hasFinding, hasData, insufficient, filtered }) {
+	if (status === "error") return "error";
+	if (status === "loading") return hasData ? "refreshing" : "loading";
+	if (!hasFinding) return filtered ? "no-match" : "empty";
+	return insufficient ? "insufficient" : "ready";
+}
+/**
+* The figure's generated description: what kind of finding this is, how much
+* it matters, the claim, the evidence that supports it, where the reading sits
+* against the expected range, and the provenance — because a machine claim
+* without provenance is not honest data.
+*/
+function buildInsightDescription({ name, state, statement, kind, severity, summary, formatters, provenance, 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 parts = [`${labels.badge(labels.severityNames[severity], labels.kindNames[kind], severity)}. ${name}.`];
+	const observed = summary?.value != null ? formatters.formatValue(summary.value) : null;
+	const expected = summary?.expected != null ? formatters.formatValue(summary.expected) : null;
+	const deviation = summary?.value != null && summary.expected != null ? formatters.formatDeviation(summary.value, summary.expected) : null;
+	if (statement) parts.push(statement.endsWith(".") ? statement : `${statement}.`);
+	else if (observed) parts.push(labels.claim({
+		kind: labels.kindNames[kind],
+		name,
+		observed,
+		expected,
+		deviation
+	}));
+	const range = summary ? formatters.formatRange(summary.lower, summary.upper) : null;
+	if (range) parts.push(summary?.outside ? labels.outsideRange(range) : labels.insideRange(range));
+	const strength = summary ? formatters.formatStrength(summary.strength, summary.strengthKind) : null;
+	if (strength && !range) parts.push(`${strength}.`);
+	if (state === "insufficient") parts.push(labels.needsHistory);
+	if (provenance && provenance.length > 0) parts.push(`${provenance.join(" · ")}.`);
+	if (asOfText) parts.push(`${labels.asOf} ${asOfText}.`);
+	return parts.join(" ");
+}
+/** The plot's own `aria-label` — the form, what is on it, and where the flagged reading sits. */
+function buildInsightChartDescription({ name, summary, formatters, atText, labels }) {
+	const evidence = summary.evidence === "none" ? labels.evidenceNames.range : labels.evidenceNames[summary.evidence];
+	return labels.chartDescription({
+		evidence,
+		name,
+		readings: summary.evidence === "spark" ? summary.count : 0,
+		observed: formatters.formatValue(summary.value),
+		expected: summary.expected != null ? formatters.formatValue(summary.expected) : null,
+		range: formatters.formatRange(summary.lower, summary.upper),
+		at: atText ?? null
+	});
+}
+/**
+* The provenance parts, in reading order — method, confidence, sample size,
+* detection time. Empty when the consumer reported none, which is itself
+* worth seeing: an unattributed claim looks unattributed.
+*/
+function buildInsightProvenance({ method, confidence, sampleSize, detectedAtText, locale, labels }) {
+	const parts = [];
+	if (method) parts.push(method);
+	const level = insightConfidenceLevel(confidence);
+	if (level && confidence != null) parts.push(labels.confidence(labels.confidenceNames[level], formatNumber(confidence, "percent:0", locale)));
+	if (isFinite(sampleSize) && sampleSize > 0) parts.push(labels.sample(formatNumber(sampleSize, "integer", locale)));
+	if (detectedAtText) parts.push(labels.detected(detectedAtText));
+	return parts;
+}
+/** Writes a row's period the way the axis and the tooltip write it, so the table never disagrees with the plot. */
+function formatInsightX(x, { xType, granularity = "day", locale, timeZone }) {
+	if (x == null) return "—";
+	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);
+}
+/** Whether a measure's own format is a percentage, so an absolute delta is written in points rather than percent. */
+function insightFormatIsPercent(format) {
+	return parseArcNumberFormat(format).kind === "percent";
+}
+const DAY_MS = 864e5;
+/**
+* The granularity an axis tick may use, given the one the card reads dates at
+* and how long the plotted window is. An axis label has a pixel budget and
+* ellipsizes past it, so the tooltip's full form is never the axis's form: a
+* date drops its year, a month drops its year, and a datetime drops its clock
+* — except across a window shorter than two days, where a bare date would
+* print the same label at both ends and the hour is the part that separates
+* them. The hour is in the tooltip and the table either way.
+*/
+function insightAxisGranularity(granularity, spanMs) {
+	switch (granularity) {
+		case "day": return "day-short";
+		case "month": return "month-short";
+		case "datetime":
+		case "day-time": return spanMs != null && spanMs < 2 * DAY_MS ? "day-time" : "day-short";
+		case "time": return spanMs != null && spanMs >= 2 * DAY_MS ? "day-short" : "time";
+		default: return granularity;
+	}
+}
+//#endregion
+export { CONFIDENCE_BOUNDS, DEFAULT_INSIGHT_LABELS, DEFAULT_SEVERITY_THRESHOLDS, buildInsightChartDescription, buildInsightDescription, buildInsightProvenance, createInsightFormatters, deriveInsightPolarity, deriveInsightSeverity, deriveInsightState, formatInsightX, inferInsightXType, insightAxisGranularity, insightConfidenceLevel, insightFormatIsPercent, normalizeInsight, resolveInsightLabels };

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

@@ -0,0 +1,4 @@
+import { BuildInsightDescriptionInput, CONFIDENCE_BOUNDS, DEFAULT_INSIGHT_LABELS, DEFAULT_SEVERITY_THRESHOLDS, DeriveInsightStateInput, InsightCardLabels, InsightCardSize, InsightCardState, InsightCardStatus, InsightConfidenceLevel, InsightDeltaMode, InsightEvidence, InsightFeedback, InsightGoodDirection, InsightIntervalRow, InsightKind, InsightObservation, InsightPoint, InsightPolarity, InsightRow, InsightSeverity, InsightSeverityThresholds, InsightStrengthKind, InsightStripRow, InsightSummary, InsightTextFormatters, InsightXType, NormalizeInsightOptions, buildInsightChartDescription, buildInsightDescription, buildInsightProvenance, createInsightFormatters, deriveInsightPolarity, deriveInsightSeverity, deriveInsightState, formatInsightX, inferInsightXType, insightAxisGranularity, insightConfidenceLevel, insightFormatIsPercent, normalizeInsight, resolveInsightLabels } from "./InsightCard.model.js";
+import { INSIGHT_FLAG_PARAM, INSIGHT_HOVER_PARAM, INSIGHT_INTERVAL_DATASET, INSIGHT_POINTS_DATASET, INSIGHT_STRIP_DATASET, INSIGHT_X_TICKS_PARAM, InsightAxes, InsightSparkSpecOptions, InsightStripSpecOptions, buildInsightSparkSpec, buildInsightStripSpec } from "./InsightCard.chart.js";
+import { InsightCard, InsightCardProps } from "./InsightCard.js";
+export { type BuildInsightDescriptionInput, CONFIDENCE_BOUNDS, DEFAULT_INSIGHT_LABELS, DEFAULT_SEVERITY_THRESHOLDS, type DeriveInsightStateInput, INSIGHT_FLAG_PARAM, INSIGHT_HOVER_PARAM, INSIGHT_INTERVAL_DATASET, INSIGHT_POINTS_DATASET, INSIGHT_STRIP_DATASET, INSIGHT_X_TICKS_PARAM, type InsightAxes, InsightCard, type InsightCardLabels, type InsightCardProps, type InsightCardSize, type InsightCardState, type InsightCardStatus, type InsightConfidenceLevel, type InsightDeltaMode, type InsightEvidence, type InsightFeedback, type InsightGoodDirection, type InsightIntervalRow, type InsightKind, type InsightObservation, type InsightPoint, type InsightPolarity, type InsightRow, type InsightSeverity, type InsightSeverityThresholds, type InsightSparkSpecOptions, type InsightStrengthKind, type InsightStripRow, type InsightStripSpecOptions, type InsightSummary, type InsightTextFormatters, type InsightXType, type NormalizeInsightOptions, buildInsightChartDescription, buildInsightDescription, buildInsightProvenance, buildInsightSparkSpec, buildInsightStripSpec, createInsightFormatters, deriveInsightPolarity, deriveInsightSeverity, deriveInsightState, formatInsightX, inferInsightXType, insightAxisGranularity, insightConfidenceLevel, insightFormatIsPercent, normalizeInsight, resolveInsightLabels };

package/dist/components/InsightCard/index.js

@@ -0,0 +1,4 @@
+import { INSIGHT_FLAG_PARAM, INSIGHT_HOVER_PARAM, INSIGHT_INTERVAL_DATASET, INSIGHT_POINTS_DATASET, INSIGHT_STRIP_DATASET, INSIGHT_X_TICKS_PARAM, buildInsightSparkSpec, buildInsightStripSpec } from "./InsightCard.chart.js";
+import { CONFIDENCE_BOUNDS, DEFAULT_INSIGHT_LABELS, DEFAULT_SEVERITY_THRESHOLDS, buildInsightChartDescription, buildInsightDescription, buildInsightProvenance, createInsightFormatters, deriveInsightPolarity, deriveInsightSeverity, deriveInsightState, formatInsightX, inferInsightXType, insightAxisGranularity, insightConfidenceLevel, insightFormatIsPercent, normalizeInsight, resolveInsightLabels } from "./InsightCard.model.js";
+import { InsightCard } from "./InsightCard.js";
+export { CONFIDENCE_BOUNDS, DEFAULT_INSIGHT_LABELS, DEFAULT_SEVERITY_THRESHOLDS, INSIGHT_FLAG_PARAM, INSIGHT_HOVER_PARAM, INSIGHT_INTERVAL_DATASET, INSIGHT_POINTS_DATASET, INSIGHT_STRIP_DATASET, INSIGHT_X_TICKS_PARAM, InsightCard, buildInsightChartDescription, buildInsightDescription, buildInsightProvenance, buildInsightSparkSpec, buildInsightStripSpec, createInsightFormatters, deriveInsightPolarity, deriveInsightSeverity, deriveInsightState, formatInsightX, inferInsightXType, insightAxisGranularity, insightConfidenceLevel, insightFormatIsPercent, normalizeInsight, resolveInsightLabels };

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

@@ -0,0 +1,79 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { MetricTrendAxes, MetricTrendMark, MetricTrendScale, MetricTrendXType } from "./MetricCard.model.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/MetricCard/MetricCard.chart.d.ts
+/** The trend rows: `{ x, y }` per `MetricTrendRow` (plus `hl` and `tone` in the highlight variant). */
+declare const METRIC_TREND_DATASET = "table";
+/** Zero or one row `{ value }` — the target reference line. */
+declare const METRIC_REFERENCE_DATASET = "reference";
+/** Zero or one row — the latest valid reading, marked with a dot. */
+declare const METRIC_LATEST_DATASET = "latest";
+/** Highlight variant: the readings outside the window with a `seg` of `before` or `after` — the gray context runs. */
+declare const METRIC_CONTEXT_DATASET = "context";
+/** Highlight variant: the readings inside the window — the coloured segment. */
+declare const METRIC_HIGHLIGHT_ROWS_DATASET = "highlightRows";
+/** Highlight variant: the window's start and end readings — the two dots. */
+declare const METRIC_HIGHLIGHT_POINTS_DATASET = "highlightPoints";
+/** Highlight variant: one row `{ start, end, startY, endY, tone }` — the band behind a line and the axis anchors. */
+declare const METRIC_HIGHLIGHT_DATASET = "highlight";
+/** The nearest-point hover selection. */
+declare const METRIC_HOVER_PARAM = "hover";
+/** Responsive x tick values, recomputed by Vega when the domain or width changes. */
+declare const METRIC_X_TICKS_PARAM = "metric_x_ticks";
+/** Highlight variant: the window's snapped bounds, read from the `highlight` dataset — the x axis labels them. */
+declare const METRIC_HIGHLIGHT_START_PARAM = "metric_hl_start";
+declare const METRIC_HIGHLIGHT_END_PARAM = "metric_hl_end";
+interface MetricTrendSpecOptions {
+  mark: MetricTrendMark;
+  scale: MetricTrendScale;
+  xType: MetricTrendXType;
+  /** Which axes to draw, default `x`. Axes share the plot's box (`autosize: fit`), so the caller reserves height for the x labels. */
+  axes?: MetricTrendAxes;
+  height: number;
+  /** Draw the target reference rule (the `reference` dataset carries the value). */
+  reference: boolean;
+  /** Wire the nearest-point hover selection and tooltip channel. */
+  tooltip: boolean;
+  /**
+   * The highlight variant: wash a band behind the window, paint the readings
+   * outside it in the context gray and the window in its polarity hue (each
+   * row's `tone`), dot its start and end, and label the window's bounds on the
+   * x axis. Reads the `context`, `highlightRows`, `highlightPoints` and
+   * `highlight` datasets and skips the `latest` dot. Pair it with `tooltip`:
+   * the hover layer is what keeps the `table` dataset in the compiled spec for
+   * a line or an area.
+   */
+  highlight?: boolean;
+  /** Tooltip titles. */
+  xTitle: string;
+  yTitle: string;
+  /** Localised title for the target reference line's hover value. */
+  targetTitle?: string;
+  /** `arcNumber` grammar for values (`compact@en-US`). */
+  valueFormat: string;
+  /** `arcTime` grammar for temporal x in tooltips (`day@en-US@Asia/Bangkok`). */
+  timeFormat: string;
+  /** `arcTime` grammar for x-axis tick labels — the axis-length form (`day-short@en-US@Asia/Bangkok`). */
+  axisTimeFormat: string;
+  locale?: string;
+  timeZone?: string;
+}
+/**
+ * Builds the sparkline: a line (or an area with a crisp line on top, or bars),
+ * an optional hairline target rule that joins the y-domain, the latest reading
+ * as a dot, a nearest-point hover layer carrying the tooltip, and — when
+ * `axes` asks for them — quiet x and/or y axes labelled through the card's own
+ * formats. Lines may crop (`scale: "auto"`); areas and bars keep a zero
+ * baseline whatever `scale` says — proportional ink is not negotiable. Gaps
+ * stay gaps: Vega-Lite's default `invalid` handling breaks the path at a null
+ * reading.
+ *
+ * With `highlight`, the series recedes to the context gray and the window is
+ * the subject: a quiet band washes its extent, its readings draw in the
+ * polarity hue (bars inside it take the hue), its start and end are dotted,
+ * and the x axis labels the window's bounds (flanking the band) before the
+ * domain ends.
+ */
+declare function buildMetricTrendSpec(options: MetricTrendSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { 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 };