@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/ChartCard/ChartCard.model.js

@@ -0,0 +1,1223 @@
+import { formatDate, formatNumber } from "../../lib/vega/formatters.js";
+//#region src/components/ChartCard/ChartCard.model.ts
+const NO_FIELDS = {
+	x: "none",
+	y: "none",
+	series: "none",
+	value: false,
+	size: false,
+	x2: false
+};
+const fields = (overrides) => ({
+	...NO_FIELDS,
+	...overrides
+});
+const XY = fields({
+	x: "required",
+	y: "required",
+	series: "optional"
+});
+/** Raw observations: a value, optionally grouped — Vega bins or aggregates them. */
+const OBSERVATIONS = fields({
+	x: "optional",
+	y: "required",
+	series: "optional"
+});
+/**
+* The registry every other part of the card reads: field-type inference, the
+* legend, the description, the table twin and the spec builder all branch on
+* this rather than on `type` directly, so adding a form is one entry plus one
+* encoding.
+*/
+const CHART_TYPES = {
+	bar: {
+		intent: "magnitude",
+		mark: "bar",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "single",
+		legend: "series",
+		aggregating: false,
+		minRows: 1,
+		name: "bar chart"
+	},
+	"bar-horizontal": {
+		intent: "ranking",
+		mark: "bar",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: true,
+		stack: false,
+		color: "single",
+		legend: "series",
+		aggregating: false,
+		minRows: 1,
+		name: "horizontal bar chart"
+	},
+	"bar-grouped": {
+		intent: "magnitude",
+		mark: "bar",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "required"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "grouped bar chart"
+	},
+	"bar-stacked": {
+		intent: "part-to-whole",
+		mark: "bar",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "required"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: "zero",
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "stacked bar chart"
+	},
+	"bar-normalized": {
+		intent: "part-to-whole",
+		mark: "bar",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "required"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: "normalize",
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "100% stacked bar chart"
+	},
+	"bar-diverging": {
+		intent: "deviation",
+		mark: "bar",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: true,
+		stack: false,
+		color: "single",
+		legend: "none",
+		aggregating: false,
+		minRows: 1,
+		name: "diverging bar chart"
+	},
+	"bar-range": {
+		intent: "flow",
+		mark: "bar",
+		fields: fields({
+			x: "required",
+			y: "optional",
+			series: "required",
+			x2: true
+		}),
+		polar: false,
+		square: false,
+		horizontal: true,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 1,
+		name: "range bar chart"
+	},
+	lollipop: {
+		intent: "ranking",
+		mark: "rule",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: true,
+		stack: false,
+		color: "single",
+		legend: "none",
+		aggregating: false,
+		minRows: 1,
+		name: "lollipop chart"
+	},
+	waterfall: {
+		intent: "flow",
+		mark: "bar",
+		fields: fields({
+			x: "required",
+			y: "required"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "single",
+		legend: "none",
+		aggregating: false,
+		minRows: 2,
+		name: "waterfall chart"
+	},
+	line: {
+		intent: "change-over-time",
+		mark: "line",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "line chart"
+	},
+	"line-points": {
+		intent: "change-over-time",
+		mark: "line",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "line chart with point markers"
+	},
+	step: {
+		intent: "change-over-time",
+		mark: "line",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "step chart"
+	},
+	trail: {
+		intent: "change-over-time",
+		mark: "line",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "optional",
+			size: true
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "trail chart"
+	},
+	area: {
+		intent: "change-over-time",
+		mark: "area",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "area chart"
+	},
+	"area-stacked": {
+		intent: "part-to-whole",
+		mark: "area",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "required"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: "zero",
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "stacked area chart"
+	},
+	"area-normalized": {
+		intent: "part-to-whole",
+		mark: "area",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "required"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: "normalize",
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "100% stacked area chart"
+	},
+	streamgraph: {
+		intent: "change-over-time",
+		mark: "area",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "required"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: "center",
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "streamgraph"
+	},
+	slope: {
+		intent: "change-over-time",
+		mark: "line",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "required"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "slope graph"
+	},
+	pie: {
+		intent: "part-to-whole",
+		mark: "arc",
+		fields: fields({
+			series: "required",
+			value: true
+		}),
+		polar: true,
+		square: true,
+		horizontal: false,
+		stack: "zero",
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "pie chart"
+	},
+	donut: {
+		intent: "part-to-whole",
+		mark: "arc",
+		fields: fields({
+			series: "required",
+			value: true
+		}),
+		polar: true,
+		square: true,
+		horizontal: false,
+		stack: "zero",
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "donut chart"
+	},
+	radial: {
+		intent: "part-to-whole",
+		mark: "arc",
+		fields: fields({
+			series: "required",
+			value: true
+		}),
+		polar: true,
+		square: true,
+		horizontal: false,
+		stack: "zero",
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "radial plot"
+	},
+	scatter: {
+		intent: "correlation",
+		mark: "point",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "scatter plot"
+	},
+	bubble: {
+		intent: "correlation",
+		mark: "point",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "optional",
+			size: true
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "bubble plot"
+	},
+	"connected-scatter": {
+		intent: "correlation",
+		mark: "line",
+		fields: XY,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 2,
+		name: "connected scatter plot"
+	},
+	"heatmap-binned": {
+		intent: "correlation",
+		mark: "rect",
+		fields: fields({
+			x: "required",
+			y: "required"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "magnitude",
+		legend: "ramp",
+		aggregating: true,
+		minRows: 2,
+		name: "2D histogram heatmap"
+	},
+	histogram: {
+		intent: "distribution",
+		mark: "bar",
+		fields: fields({
+			y: "required",
+			series: "optional"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: "zero",
+		color: "identity",
+		legend: "series",
+		aggregating: true,
+		minRows: 2,
+		name: "histogram"
+	},
+	density: {
+		intent: "distribution",
+		mark: "area",
+		fields: fields({
+			y: "required",
+			series: "optional"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: true,
+		minRows: 3,
+		name: "density plot"
+	},
+	boxplot: {
+		intent: "distribution",
+		mark: "boxplot",
+		fields: OBSERVATIONS,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: true,
+		minRows: 2,
+		name: "box plot"
+	},
+	violin: {
+		intent: "distribution",
+		mark: "area",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "optional"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: "center",
+		color: "identity",
+		legend: "series",
+		aggregating: true,
+		minRows: 3,
+		name: "violin plot"
+	},
+	strip: {
+		intent: "distribution",
+		mark: "tick",
+		fields: OBSERVATIONS,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 1,
+		name: "strip plot"
+	},
+	dot: {
+		intent: "distribution",
+		mark: "point",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "optional"
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 1,
+		name: "dot plot"
+	},
+	errorbar: {
+		intent: "distribution",
+		mark: "rule",
+		fields: OBSERVATIONS,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: true,
+		minRows: 2,
+		name: "error bar chart"
+	},
+	errorband: {
+		intent: "distribution",
+		mark: "band",
+		fields: OBSERVATIONS,
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: true,
+		minRows: 2,
+		name: "line chart with a confidence band"
+	},
+	heatmap: {
+		intent: "magnitude",
+		mark: "rect",
+		fields: fields({
+			x: "required",
+			y: "required",
+			value: true
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "magnitude",
+		legend: "ramp",
+		aggregating: false,
+		minRows: 1,
+		name: "heatmap"
+	},
+	punchcard: {
+		intent: "magnitude",
+		mark: "point",
+		fields: fields({
+			x: "required",
+			y: "required",
+			value: true
+		}),
+		polar: false,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "magnitude",
+		legend: "ramp",
+		aggregating: false,
+		minRows: 1,
+		name: "punch card"
+	},
+	radar: {
+		intent: "correlation",
+		mark: "line",
+		fields: fields({
+			x: "required",
+			y: "required",
+			series: "optional"
+		}),
+		polar: true,
+		square: false,
+		horizontal: false,
+		stack: false,
+		color: "identity",
+		legend: "series",
+		aggregating: false,
+		minRows: 3,
+		name: "radar chart"
+	}
+};
+/** Every form, in the docs' own order — the docs table and the type control read this. */
+const CHART_TYPE_ORDER = Object.keys(CHART_TYPES);
+const DEFAULT_CHART_LABELS = {
+	noData: "No data",
+	noMatch: "No data matches the current filters",
+	clearFilters: "Clear filters",
+	error: "Could not load this chart",
+	retry: "Retry",
+	insufficient: "Not enough data to draw this chart",
+	stale: "Stale",
+	legendGroup: (name) => `Series shown in ${name}`,
+	showSeries: (label) => `Show ${label}`,
+	hideSeries: (label) => `Hide ${label}`,
+	other: "Other",
+	showTable: (name) => `Show the data behind ${name}`,
+	hideTable: (name) => `Hide the data behind ${name}`,
+	tableCaption: (name) => `Every value plotted in ${name}`,
+	tableSeries: "Series",
+	tableValue: "Value",
+	tableShare: "Share",
+	tableTruncated: (shown, total) => `First ${shown} of ${total} rows.`,
+	chartOf: (form, measure, dimension) => `${form} of ${measure} by ${dimension}`,
+	describeSeries: (count, names) => `${count} series: ${names}.`,
+	describeRange: (from, to) => `From ${from} to ${to}.`,
+	describeExtremes: (maxLabel, maxValue, minLabel, minValue) => `Highest ${maxLabel} at ${maxValue}; lowest ${minLabel} at ${minValue}.`,
+	describeTotal: (total) => `Total ${total}.`,
+	describeRamp: (low, high) => `Colour runs from ${low} to ${high}.`,
+	describeAggregate: (op, measure) => `${measure} aggregated by ${op}.`,
+	describeFolded: (count, label) => `${count} smaller series folded into ${label}.`,
+	describeHidden: (count) => `${count} series hidden.`,
+	describeStale: "This data is out of date.",
+	describeLoading: (name) => `${name} is loading.`,
+	describeEmpty: (name) => `${name} has no data.`,
+	describeError: (name) => `${name} could not be loaded.`
+};
+function resolveChartLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_CHART_LABELS,
+		...overrides
+	} : DEFAULT_CHART_LABELS;
+}
+/**
+* The state machine every card in this package shares, plus `insufficient`:
+* rows arrived but the form needs more of them than it got.
+*/
+function deriveChartState({ status, hasChart, hasData, filtered }) {
+	if (status === "error") return "error";
+	if (status === "loading") return hasData ? "refreshing" : "loading";
+	if (hasChart) return "ready";
+	if (hasData) return "insufficient";
+	return filtered ? "no-match" : "empty";
+}
+/**
+* Whether the form has enough to say something. Beyond the row floor in the
+* registry, the forms Vega aggregates need several observations INSIDE a
+* group: a box plot of one reading per category has no interquartile range to
+* draw, and Vega then logs an empty-extent warning rather than a chart.
+*/
+function hasEnoughData(type, summary) {
+	if (!summary) return false;
+	const info = CHART_TYPES[type];
+	if ((summary.hasMeasure ? summary.count : summary.rows.length) < info.minRows) return false;
+	if (!info.aggregating) return true;
+	if (summary.count < 4) return false;
+	const perGroup = /* @__PURE__ */ new Map();
+	for (const row of summary.rows) {
+		if (row.v == null) continue;
+		const key = JSON.stringify([row.s ?? "", row.x ?? ""]);
+		perGroup.set(key, (perGroup.get(key) ?? 0) + 1);
+	}
+	for (const count of perGroup.values()) if (count >= 2) return true;
+	return false;
+}
+/**
+* The field names a form needs but did not get. A card missing one of these
+* cannot draw at all, so it shows the insufficient state and says which field
+* is absent rather than rendering an empty frame.
+*/
+function missingChartFields(type, provided) {
+	const { fields } = CHART_TYPES[type];
+	const missing = [];
+	if (fields.x === "required" && !provided.x) missing.push("x");
+	if (fields.y === "required" && !provided.y) missing.push("y");
+	if (fields.series === "required" && !provided.series) missing.push("series");
+	if (fields.value && !provided.value && !provided.y) missing.push("value");
+	if (fields.x2 && !provided.x2) missing.push("x2");
+	return missing;
+}
+const ISO_DATE = /^\d{4}-\d{2}(-\d{2})?([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+function looksTemporal(value) {
+	if (value instanceof Date) return !Number.isNaN(value.getTime());
+	return typeof value === "string" && ISO_DATE.test(value);
+}
+/**
+* Infers a field's Vega-Lite type from the first rows that actually carry it:
+* `Date` objects and ISO-8601 strings are temporal, numbers quantitative,
+* everything else nominal. Returns `undefined` for a field no row defines, so
+* a caller can tell "not present" from "nominal".
+*/
+function inferFieldType(rows, field) {
+	if (!rows || !field) return void 0;
+	let seen = 0;
+	let temporal = 0;
+	let numeric = 0;
+	for (const row of rows) {
+		const value = row[field];
+		if (value == null) continue;
+		seen += 1;
+		if (looksTemporal(value)) temporal += 1;
+		else if (typeof value === "number") numeric += 1;
+		if (seen >= 50) break;
+	}
+	if (seen === 0) return void 0;
+	if (temporal === seen) return "temporal";
+	if (numeric === seen) return "quantitative";
+	return "nominal";
+}
+/** The key the folded tail takes. Never collides with a consumer key, which is a field value. */
+const CHART_OTHER_KEY = "__other__";
+function toNumber(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	return null;
+}
+/**
+* Coerces a position to what Vega can plot. A temporal field becomes epoch
+* MILLISECONDS, because a spec's `format.parse` runs only for the data the
+* spec itself carries — rows pushed through `view.data()` after the parse
+* arrive verbatim, so an ISO string would reach a temporal scale as text and
+* the marks would silently not draw. The sibling cards coerce the same way.
+*/
+function normalizePosition(value, type) {
+	if (value == null) return value;
+	if (type !== "temporal") return value;
+	const time = value instanceof Date ? value.getTime() : new Date(String(value)).getTime();
+	return Number.isNaN(time) ? null : time;
+}
+function xKey(value) {
+	if (value instanceof Date) return `d:${value.getTime()}`;
+	return `${typeof value}:${String(value)}`;
+}
+/**
+* Picks the paint for series `index` under the resolved colour job. Identity
+* slots are assigned by the series' place in the consumer's order — never by
+* rank — so hiding or re-sorting can never repaint the survivors. Past the
+* theme's identity budget the ramp takes over: repeating a slot would make two
+* series look like one, and a ramp at least stays ordered and separable.
+*/
+function chartSeriesColorAt(mode, index, total, tokens) {
+	if (mode === "single") return tokens.emphasis;
+	if (mode === "emphasis") return index === 0 ? tokens.emphasis : tokens.context;
+	if (mode === "categorical") {
+		const slots = tokens.category.length;
+		return tokens.category[index % slots];
+	}
+	const steps = tokens.sequential.length;
+	if (total <= 1) return tokens.emphasis;
+	const first = total >= steps ? 0 : Math.max(0, steps - total);
+	const span = steps - 1 - first;
+	const at = first + Math.round(index / (total - 1) * span);
+	return tokens.sequential[Math.min(steps - 1, Math.max(0, at))];
+}
+/**
+* Resolves the colour job from the prop, the series count and the theme's own
+* identity budget (`chart-1…N`, three hues on the stock theme). A form whose
+* colour encodes a MEASURE — a heatmap, a punch card — always resolves to
+* `magnitude`, whatever the prop says: colour has one job per chart, and there
+* it is already spoken for.
+*/
+function resolveChartColorMode(requested, type, seriesCount, slots) {
+	if (CHART_TYPES[type].color === "magnitude") return "magnitude";
+	if (seriesCount <= 1) return "single";
+	if (requested === "categorical") return seriesCount <= slots ? "categorical" : "sequential";
+	if (requested === "sequential") return "sequential";
+	if (requested === "emphasis") return "emphasis";
+	return seriesCount <= slots ? "categorical" : "sequential";
+}
+const DAY_MS = 864e5;
+/** Infers the period of a temporal axis from the closest spacing its values show. */
+function inferGranularity(values) {
+	const times = values.map((value) => value instanceof Date ? value.getTime() : typeof value === "number" ? value : Date.parse(String(value))).filter((time) => Number.isFinite(time)).sort((a, b) => a - b);
+	if (times.length < 2) return "day";
+	let smallest = Infinity;
+	for (let at = 1; at < times.length; at += 1) {
+		const gap = times[at] - times[at - 1];
+		if (gap > 0 && gap < smallest) smallest = gap;
+	}
+	if (!Number.isFinite(smallest)) return "day";
+	if (smallest < DAY_MS) return "datetime";
+	if (smallest >= DAY_MS * 300) return "year";
+	if (smallest >= DAY_MS * 27) return "month";
+	return "day";
+}
+/**
+* Turns the consumer's records into the long-form rows the plot draws: series
+* keys and labels resolved (a series is one distinct value of the `series`
+* field, in first-seen order), the measure coerced to a finite number or
+* `null`, a paint baked into every row, the tail folded, the x categories
+* optionally ranked, and the waterfall's running total computed here rather
+* than in Vega so the table twin and the tooltip can show the same feet and
+* heads the bars stand on.
+*
+* Returns `null` when there is nothing to normalise.
+*/
+function normalizeChartData(data, options) {
+	if (!data) return null;
+	const info = CHART_TYPES[options.type];
+	const { x: xField, y: yField, series: seriesField, value: valueField, size: sizeField, x2: x2Field, visible, maxSeries, otherLabel, sort = "none", colorMode, tokens } = options;
+	const measureField = info.fields.value ? valueField ?? yField : yField;
+	const xType = options.xType ?? inferFieldType(data, xField) ?? "nominal";
+	const yType = options.yType ?? inferFieldType(data, yField) ?? "quantitative";
+	const order = [];
+	const seen = /* @__PURE__ */ new Set();
+	if (seriesField) for (const record of data) {
+		const raw = record[seriesField];
+		if (raw == null) continue;
+		const key = String(raw);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		order.push(key);
+	}
+	const singleSeries = order.length === 0;
+	const keys = singleSeries ? [""] : order;
+	const totals = new Map(keys.map((key) => [key, 0]));
+	const counts = new Map(keys.map((key) => [key, 0]));
+	for (const record of data) {
+		const key = singleSeries ? "" : String(record[seriesField] ?? "");
+		if (!totals.has(key)) continue;
+		const measure = toNumber(measureField ? record[measureField] : null);
+		if (measure == null) continue;
+		totals.set(key, (totals.get(key) ?? 0) + measure);
+		counts.set(key, (counts.get(key) ?? 0) + 1);
+	}
+	let kept = keys;
+	let foldedKeys = /* @__PURE__ */ new Set();
+	if (maxSeries != null && maxSeries > 0 && keys.length > maxSeries) {
+		const ranked = [...keys].sort((a, b) => (totals.get(b) ?? 0) - (totals.get(a) ?? 0));
+		const survivors = new Set(ranked.slice(0, Math.max(1, maxSeries - 1)));
+		foldedKeys = new Set(keys.filter((key) => !survivors.has(key)));
+		kept = keys.filter((key) => survivors.has(key));
+		if (foldedKeys.size > 0) kept = [...kept, CHART_OTHER_KEY];
+	}
+	const labelFor = (key) => key === "__other__" ? otherLabel : key === "" ? "" : key;
+	const infos = kept.map((key, index) => ({
+		key,
+		label: labelFor(key),
+		color: chartSeriesColorAt(colorMode, index, kept.length, tokens),
+		index,
+		total: key === "__other__" ? [...foldedKeys].reduce((sum, folded) => sum + (totals.get(folded) ?? 0), 0) : totals.get(key) ?? 0,
+		count: key === "__other__" ? [...foldedKeys].reduce((sum, folded) => sum + (counts.get(folded) ?? 0), 0) : counts.get(key) ?? 0
+	}));
+	const byKey = new Map(infos.map((entry) => [entry.key, entry]));
+	const known = new Set(infos.map((entry) => entry.key));
+	const requested = visible?.filter((key) => known.has(key));
+	const shown = requested && requested.length > 0 ? new Set(requested) : known;
+	const rows = [];
+	const xSeen = /* @__PURE__ */ new Map();
+	let total = 0;
+	let count = 0;
+	let min = null;
+	let max = null;
+	for (const record of data) {
+		const rawKey = singleSeries ? "" : String(record[seriesField] ?? "");
+		const key = foldedKeys.has(rawKey) ? CHART_OTHER_KEY : rawKey;
+		const entry = byKey.get(key);
+		if (!entry) continue;
+		const xValue = xField ? normalizePosition(record[xField], xType) : void 0;
+		if (xField && xValue != null) {
+			const seenKey = xKey(xValue);
+			if (!xSeen.has(seenKey)) xSeen.set(seenKey, xValue);
+		}
+		let measure = toNumber(measureField ? record[measureField] : null);
+		if (measure == null && info.fields.x2 && x2Field && xField) {
+			const from = toNumber(xValue);
+			const to = toNumber(normalizePosition(record[x2Field], xType));
+			if (from != null && to != null) measure = to - from;
+		}
+		const yRaw = yField ? record[yField] : void 0;
+		const yValue = yType === "quantitative" ? toNumber(yRaw) : normalizePosition(yRaw, yType);
+		if (!shown.has(key)) continue;
+		const row = {
+			...xField ? { x: xValue } : {},
+			...x2Field && info.fields.x2 ? { x2: normalizePosition(record[x2Field], xType) } : {},
+			...yField ? { y: yValue ?? null } : {},
+			v: measure,
+			...sizeField && info.fields.size ? { z: toNumber(record[sizeField]) } : {},
+			s: key,
+			n: entry.label,
+			c: entry.color,
+			i: entry.index,
+			o: rows.length
+		};
+		rows.push(row);
+		if (measure != null) {
+			total += measure;
+			count += 1;
+			const label = [entry.label, xField ? String(xValue ?? "") : ""].filter(Boolean).join(" ") || String(xValue ?? "");
+			if (!max || measure > max.value) max = {
+				label,
+				value: measure
+			};
+			if (!min || measure < min.value) min = {
+				label,
+				value: measure
+			};
+		}
+	}
+	if (rows.length === 0 && infos.every((entry) => entry.count === 0) && data.length === 0) return null;
+	let xValues = [...xSeen.values()];
+	if (sort !== "none" && xField && xType !== "quantitative") {
+		const byX = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			if (row.v == null) continue;
+			const seenKey = xKey(row.x);
+			byX.set(seenKey, (byX.get(seenKey) ?? 0) + row.v);
+		}
+		xValues = xValues.sort((a, b) => {
+			const left = byX.get(xKey(a)) ?? 0;
+			const right = byX.get(xKey(b)) ?? 0;
+			return sort === "desc" ? right - left : left - right;
+		});
+	}
+	if (options.type === "waterfall") {
+		let running = 0;
+		for (const row of rows) {
+			const step = row.v ?? 0;
+			row.lo = running;
+			running += step;
+			row.hi = running;
+			row.d = step > 0 ? "up" : step < 0 ? "down" : "total";
+			row.c = step < 0 ? tokens.divergingNegative : tokens.divergingPositive;
+		}
+	}
+	if (options.type === "radar") {
+		const at = new Map(xValues.map((value, index) => [xKey(value), index]));
+		const outer = max && max.value > 0 ? max.value : 1;
+		for (const row of rows) {
+			const index = at.get(xKey(row.x)) ?? 0;
+			const angle = 2 * Math.PI * index / Math.max(1, xValues.length);
+			const unit = Math.max(0, row.v ?? 0) / outer;
+			row.px = Math.sin(angle) * unit;
+			row.py = Math.cos(angle) * unit;
+			row.ai = index;
+		}
+	}
+	const domain = min && max ? [min.value, max.value] : null;
+	return {
+		rows,
+		series: infos,
+		count,
+		hasMeasure: measureField != null || info.fields.x2 === true && x2Field != null,
+		xValues,
+		xType,
+		yType,
+		domain,
+		total,
+		extremes: min && max ? {
+			maxLabel: max.label,
+			maxValue: max.value,
+			minLabel: min.label,
+			minValue: min.value
+		} : null,
+		folded: foldedKeys.size,
+		colorMode,
+		granularity: xType === "temporal" ? inferGranularity(xValues) : "day"
+	};
+}
+/** Fractions of the outer ring a radar's web is drawn at. */
+const RADAR_RING_FRACTIONS = [
+	.25,
+	.5,
+	.75,
+	1
+];
+/** Where a radar's axis labels sit, as a fraction of the outer ring. */
+const RADAR_LABEL_RADIUS = 1.13;
+/**
+* The radar's grid: one row per axis per ring, on the same unit plane the
+* polygons are drawn on. Built here rather than in the spec because the spec
+* must stay structural — and because a ring then stands for a real value the
+* description can name, not just a fraction of the frame.
+*/
+function buildRadarWebRows(summary) {
+	if (!summary || summary.xValues.length === 0) return [];
+	const outer = summary.extremes && summary.extremes.maxValue > 0 ? summary.extremes.maxValue : 1;
+	const count = summary.xValues.length;
+	const web = [];
+	summary.xValues.forEach((x, index) => {
+		const angle = 2 * Math.PI * index / count;
+		const sin = Math.sin(angle);
+		const cos = Math.cos(angle);
+		for (const k of [0, ...RADAR_RING_FRACTIONS]) web.push({
+			x,
+			ai: index,
+			k,
+			px: sin * k,
+			py: cos * k,
+			lx: sin * RADAR_LABEL_RADIUS,
+			ly: cos * RADAR_LABEL_RADIUS,
+			r: outer * k
+		});
+	});
+	return web;
+}
+/**
+* Buckets a magnitude ramp for the legend row. Vega owns the continuous scale
+* on the plot; this is the reader's key to it, and — like the reference
+* heatmap's HIGH / MODERATE / LOW row — it is the only way a colour-encoded
+* measure is legible without hovering.
+*/
+function buildRampBuckets(domain, tokens, format, steps = 4) {
+	if (!domain) return [];
+	const [low, high] = domain;
+	const ramp = tokens.sequential;
+	const count = Math.max(2, Math.min(steps, ramp.length));
+	if (!(high > low)) return [{
+		color: ramp[ramp.length - 1],
+		from: low,
+		to: high,
+		label: format(low)
+	}];
+	const width = (high - low) / count;
+	return Array.from({ length: count }, (_, at) => {
+		const from = low + width * at;
+		const to = at === count - 1 ? high : low + width * (at + 1);
+		return {
+			color: ramp[Math.round(at / (count - 1) * (ramp.length - 1))],
+			from,
+			to,
+			label: `${format(from)}–${format(to)}`
+		};
+	});
+}
+/**
+* One set of formatters for the axis, the tooltip, the legend, the table and
+* the description, so the same value never rounds two ways (Few's precision
+* pitfall).
+*/
+function createChartFormatters({ format = "compact", locale, timeZone, formatValue, xType, yType, granularity }) {
+	const value = (input) => {
+		if (input == null || !Number.isFinite(input)) return "—";
+		return formatValue ? formatValue(input) : formatNumber(input, format, locale);
+	};
+	const position = (type) => (input) => {
+		if (input == null) return "—";
+		if (type === "temporal") {
+			const date = input instanceof Date ? input : new Date(typeof input === "number" ? input : String(input));
+			return Number.isNaN(date.getTime()) ? "—" : formatDate(date, {
+				granularity,
+				locale,
+				timeZone
+			});
+		}
+		if (type === "quantitative") {
+			const numeric = toNumber(input);
+			return numeric == null ? "—" : formatNumber(numeric, "compact", locale);
+		}
+		return String(input);
+	};
+	return {
+		formatValue: value,
+		formatX: position(xType),
+		formatY: position(yType),
+		formatShare: (input) => input == null || !Number.isFinite(input) ? "—" : formatNumber(input, "percent:1", locale)
+	};
+}
+/**
+* The card's own accessible description (the figure's `aria-describedby`
+* text): what the chart is, what it covers, where its extremes are, and what
+* has been folded, hidden or aggregated away. Amy Cesal's alt-text formula —
+* chart type, what data, why it is here — generated from the props, because a
+* card whose face carries no text has nothing else for a screen reader to read.
+*/
+function buildChartDescription({ name, type, state, summary, visibleKeys, formatters, labels, measureName, dimensionName, aggregate, stale }) {
+	if (state === "loading") return labels.describeLoading(name);
+	if (state === "error") return labels.describeError(name);
+	if (state === "empty" || state === "no-match") return labels.describeEmpty(name);
+	const info = CHART_TYPES[type];
+	const parts = [`${name}: ${labels.chartOf(info.name, measureName, dimensionName)}.`];
+	if (state === "insufficient") {
+		parts.push(labels.insufficient + ".");
+		return parts.join(" ");
+	}
+	if (!summary) return parts.join(" ");
+	if (aggregate) parts.push(labels.describeAggregate(aggregate, measureName));
+	const named = summary.series.filter((entry) => entry.label !== "");
+	if (named.length > 1) parts.push(labels.describeSeries(named.length, named.map((entry) => entry.label).join(", ")));
+	if (summary.xValues.length > 1) parts.push(labels.describeRange(formatters.formatX(summary.xValues[0]), formatters.formatX(summary.xValues[summary.xValues.length - 1])));
+	if (info.color === "magnitude" && summary.domain) parts.push(labels.describeRamp(formatters.formatValue(summary.domain[0]), formatters.formatValue(summary.domain[1])));
+	if (summary.extremes) parts.push(labels.describeExtremes(summary.extremes.maxLabel, formatters.formatValue(summary.extremes.maxValue), summary.extremes.minLabel, formatters.formatValue(summary.extremes.minValue)));
+	if (info.intent === "part-to-whole" && summary.count > 0) parts.push(labels.describeTotal(formatters.formatValue(summary.total)));
+	if (summary.folded > 0) parts.push(labels.describeFolded(summary.folded, labels.other));
+	const hidden = summary.series.length - visibleKeys.length;
+	if (hidden > 0) parts.push(labels.describeHidden(hidden));
+	if (stale) parts.push(labels.describeStale);
+	return parts.join(" ");
+}
+/**
+* The plot's own `aria-label` — set live through `view.description`, so Vega
+* stamps it on the `graphics-document` node. Deliberately shorter than the
+* card description: the figure's description already carries the detail, and
+* repeating it makes a screen reader say everything twice.
+*/
+function buildChartPlotDescription({ type, measureName, dimensionName, labels }) {
+	return labels.chartOf(CHART_TYPES[type].name, measureName, dimensionName);
+}
+/** How many rows the table twin renders before it says "first N of M". */
+const CHART_TABLE_ROW_CAP = 200;
+/**
+* Every value the plot draws, as text — the keyboard path to the data, since
+* Vega gives marks none. Columns follow the form: a part-to-whole chart gets a
+* share column, a range bar gets both bounds, a bubble gets its size, a
+* waterfall gets the running total the bars stand on.
+*/
+function buildChartTableModel({ type, summary, formatters, labels, measureName, dimensionName, seriesName, sizeName, cap = 200 }) {
+	if (!summary || summary.rows.length === 0) return null;
+	const info = CHART_TYPES[type];
+	const multiSeries = summary.series.some((entry) => entry.label !== "");
+	const columns = [];
+	if (info.fields.x !== "none") columns.push({
+		key: "x",
+		label: dimensionName,
+		numeric: false
+	});
+	if (info.fields.x2) columns.push({
+		key: "x2",
+		label: `${dimensionName} end`,
+		numeric: false
+	});
+	if (multiSeries) columns.push({
+		key: "s",
+		label: seriesName,
+		numeric: false
+	});
+	if (info.fields.value && info.fields.y !== "none") columns.push({
+		key: "y",
+		label: "Row",
+		numeric: false
+	});
+	columns.push({
+		key: "v",
+		label: measureName,
+		numeric: true
+	});
+	if (info.fields.size && sizeName) columns.push({
+		key: "z",
+		label: sizeName,
+		numeric: true
+	});
+	if (type === "waterfall") columns.push({
+		key: "hi",
+		label: "Running total",
+		numeric: true
+	});
+	if (info.intent === "part-to-whole" && summary.total !== 0) columns.push({
+		key: "share",
+		label: labels.tableShare,
+		numeric: true
+	});
+	const body = summary.rows.slice(0, cap).map((row) => {
+		const cells = [];
+		for (const column of columns) switch (column.key) {
+			case "x":
+				cells.push(formatters.formatX(row.x));
+				break;
+			case "x2":
+				cells.push(formatters.formatX(row.x2));
+				break;
+			case "s":
+				cells.push(row.n ?? "");
+				break;
+			case "y":
+				cells.push(formatters.formatY(row.y));
+				break;
+			case "v":
+				cells.push(formatters.formatValue(row.v));
+				break;
+			case "z":
+				cells.push(formatters.formatValue(row.z));
+				break;
+			case "hi":
+				cells.push(formatters.formatValue(row.hi));
+				break;
+			case "share":
+				cells.push(row.v == null ? "—" : formatters.formatShare(row.v / summary.total));
+				break;
+			default: cells.push("");
+		}
+		return cells;
+	});
+	return {
+		columns,
+		rows: body,
+		shown: body.length,
+		total: summary.rows.length
+	};
+}
+//#endregion
+export { CHART_OTHER_KEY, CHART_TABLE_ROW_CAP, CHART_TYPES, CHART_TYPE_ORDER, DEFAULT_CHART_LABELS, RADAR_RING_FRACTIONS, buildChartDescription, buildChartPlotDescription, buildChartTableModel, buildRadarWebRows, buildRampBuckets, chartSeriesColorAt, createChartFormatters, deriveChartState, hasEnoughData, inferFieldType, inferGranularity, missingChartFields, normalizeChartData, resolveChartColorMode, resolveChartLabels };