@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/TreeCard/TreeCard.model.js

@@ -0,0 +1,401 @@
+import { formatDelta, formatNumber } from "../../lib/vega/formatters.js";
+//#region src/components/TreeCard/TreeCard.model.ts
+const DEFAULT_TREE_LABELS = {
+	total: "Total",
+	versusPrevious: "vs previous period",
+	increase: "Up",
+	decrease: "Down",
+	unchanged: "No change",
+	percentagePoints: " pp",
+	noData: "No data",
+	noMatch: "No matching data",
+	clearFilters: "Clear filters",
+	error: "Couldn't load this breakdown",
+	retry: "Try again",
+	stale: "Stale",
+	asOf: "As of",
+	other: "Other",
+	unallocated: "Unallocated",
+	expand: (label) => `Expand ${label}`,
+	collapse: (label) => `Collapse ${label}`,
+	expandAll: "Expand all",
+	collapseAll: "Collapse all",
+	tableItem: "Item",
+	tableValue: "Value",
+	tableShare: "Share of parent",
+	tableShareOfTotal: "Share of total",
+	tableLevel: "Level",
+	tableChange: "Change",
+	selected: "selected",
+	foldedItems: (count) => `${count} items`,
+	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} breakdown`,
+	treeLabel: (name) => `Breakdown of ${name}`,
+	deltaComparison: (name) => `${name} comparison`,
+	deltaExplanation: ({ label, valueText, changeText, secondaryText, renderedMode, direction }) => {
+		const rows = [[label, valueText], [direction === "up" ? "Increase" : direction === "down" ? "Decrease" : "No change", changeText]];
+		if (secondaryText) rows.push([renderedMode === "percent" ? "Change" : "Change %", secondaryText]);
+		return rows;
+	},
+	comparisonSentence: ({ word, primary, secondary, previousText }) => primary ? `${word} ${primary}${secondary ? ` (${secondary})` : ""} from ${previousText}.` : `${word} from ${previousText}.`,
+	moverSentence: ({ label, changeText }) => `${label} moved furthest, ${changeText}.`,
+	shapeSummary: ({ nodes, levels }) => `${nodes} ${nodes === 1 ? "part" : "parts"} across ${levels} ${levels === 1 ? "level" : "levels"}.`,
+	partsSummary: (count, list) => `${count === 1 ? "One part" : `${count} parts`}: ${list}.`,
+	foldedSummary: (count) => `${count} smaller parts folded into Other.`,
+	residualSummary: "Some parents report more than their parts account for; the remainder is shown as Unallocated.",
+	chartDescription: ({ name, count, levels, total, top, topValue }) => `Indented bar breakdown of ${name}: ${count} ${count === 1 ? "row" : "rows"} across ${levels} ${levels === 1 ? "level" : "levels"}, total ${total}, largest part ${top} ${topValue}. Bars share one zero-based scale, so each length reads as its share of the total.`,
+	insightMark: "Insight"
+};
+function resolveTreeLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_TREE_LABELS,
+		...overrides
+	} : DEFAULT_TREE_LABELS;
+}
+/**
+* The state machine. Error wins; loading over existing nodes is a refresh (the
+* previous render stays under the veil); no values is `no-match` when the
+* consumer's filter caused it and `empty` otherwise.
+*/
+function deriveTreeState({ 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);
+/** Local key segment of the row a parent's long tail folds into. */
+const TREE_OTHER_KEY = "__other__";
+/** Local key segment of the row carrying what a parent's children do not account for. */
+const TREE_RESIDUAL_KEY = "__residual__";
+/** Default share of a parent's own reading below which a mismatch with its children is rounding, not a gap. */
+const DEFAULT_RESIDUAL_TOLERANCE = 5e-4;
+function sumFinite(values) {
+	let total = 0;
+	let any = false;
+	for (const value of values) if (isFinite(value)) {
+		total += value;
+		any = true;
+	}
+	return any ? total : null;
+}
+/**
+* Walks the source nodes into work nodes with keys unique across the whole
+* tree: a node's key is its parent's key, a slash and its own key (defaulting
+* to its label), and a collision anywhere is suffixed — so two siblings named
+* the same never share a band, and neither do two cousins.
+*/
+function walk(nodes, parentKey, depth, seen) {
+	return nodes.map((node) => {
+		const local = node.key ?? node.label;
+		const base = parentKey == null ? local : `${parentKey}/${local}`;
+		const repeats = seen.get(base) ?? 0;
+		seen.set(base, repeats + 1);
+		const key = repeats === 0 ? base : `${base}·${repeats + 1}`;
+		return {
+			key,
+			label: node.label,
+			depth,
+			ownValue: isFinite(node.value) ? node.value : null,
+			ownPrevious: isFinite(node.previous) ? node.previous : null,
+			value: null,
+			previous: null,
+			children: node.children?.length ? walk(node.children, key, depth + 1, seen) : [],
+			role: "node",
+			folded: 0
+		};
+	});
+}
+/** Bottom-up rollup over the full tree, before any pruning, so a capped parent still totals everything beneath it. */
+function rollupTree(nodes, rollup) {
+	for (const node of nodes) {
+		rollupTree(node.children, rollup);
+		if (node.children.length === 0) {
+			node.value = node.ownValue;
+			node.previous = node.ownPrevious;
+			continue;
+		}
+		const childValue = sumFinite(node.children.map((child) => child.value));
+		const childPrevious = sumFinite(node.children.map((child) => child.previous));
+		node.value = rollup === "own" ? node.ownValue ?? childValue : childValue ?? node.ownValue;
+		node.previous = rollup === "own" ? node.ownPrevious ?? childPrevious : childPrevious ?? node.ownPrevious;
+	}
+}
+function prune(nodes, maxDepth) {
+	for (const node of nodes) if (node.depth >= maxDepth) node.children = [];
+	else prune(node.children, maxDepth);
+}
+function sortSiblings(nodes, sort) {
+	if (sort === "none") return nodes;
+	const direction = sort === "asc" ? 1 : -1;
+	return nodes.map((node, index) => ({
+		node,
+		index
+	})).sort((a, b) => {
+		const av = a.node.value;
+		const bv = b.node.value;
+		if (av == null && bv == null) return a.index - b.index;
+		if (av == null) return 1;
+		if (bv == null) return -1;
+		return av === bv ? a.index - b.index : (av - bv) * direction;
+	}).map(({ node }) => node);
+}
+/** Sorts, folds the tail and appends the residual, recursively. Reports what it changed so the card can say so. */
+function shape(nodes, parentKey, parent, options) {
+	const { rollup, sort, maxChildren, showResidual, residualTolerance, otherLabel, residualLabel } = options;
+	let folded = 0;
+	let residual = false;
+	let ordered = sortSiblings(nodes, sort);
+	if (maxChildren != null && maxChildren >= 1 && ordered.length > maxChildren) {
+		const keep = ordered.slice(0, Math.max(0, maxChildren - 1));
+		const rest = ordered.slice(Math.max(0, maxChildren - 1));
+		ordered = [...keep, {
+			key: parentKey == null ? TREE_OTHER_KEY : `${parentKey}/${TREE_OTHER_KEY}`,
+			label: otherLabel,
+			depth: rest[0].depth,
+			ownValue: null,
+			ownPrevious: null,
+			value: sumFinite(rest.map((node) => node.value)),
+			previous: sumFinite(rest.map((node) => node.previous)),
+			children: [],
+			role: "other",
+			folded: rest.length
+		}];
+		folded += rest.length;
+	}
+	for (const node of ordered) {
+		if (node.children.length === 0) continue;
+		const inner = shape(node.children, node.key, node, options);
+		node.children = inner.nodes;
+		folded += inner.folded;
+		residual ||= inner.residual;
+	}
+	if (showResidual && rollup === "own" && parent != null && isFinite(parent.ownValue) && ordered.length > 0 && !ordered.some((node) => node.role === "residual")) {
+		const childTotal = sumFinite(ordered.map((node) => node.value));
+		if (isFinite(childTotal)) {
+			const gap = parent.ownValue - childTotal;
+			const floor = Math.abs(parent.ownValue) * residualTolerance;
+			if (Math.abs(gap) > floor && gap !== 0) {
+				const childPrevious = sumFinite(ordered.map((node) => node.previous));
+				ordered = [...ordered, {
+					key: `${parent.key}/${TREE_RESIDUAL_KEY}`,
+					label: residualLabel,
+					depth: ordered[0].depth,
+					ownValue: gap,
+					ownPrevious: null,
+					value: gap,
+					previous: isFinite(parent.ownPrevious) && isFinite(childPrevious) ? parent.ownPrevious - childPrevious : null,
+					children: [],
+					role: "residual",
+					folded: 0
+				}];
+				residual = true;
+			}
+		}
+	}
+	return {
+		nodes: ordered,
+		folded,
+		residual
+	};
+}
+/**
+* Normalises the hierarchy into the rows the plot, the tree and the table all
+* read from: unique path keys, a bottom-up rollup, the depth cap, each
+* parent's long tail folded into `Other`, the unallocated remainder made
+* explicit, shares against the parent and against the total, and the ARIA
+* bookkeeping every `treeitem` needs. Returns `null` when there is nothing to
+* speak of.
+*/
+function buildTree(nodes, options) {
+	if (!nodes) return null;
+	const { rollup = "sum", sort = "none", maxChildren, maxDepth, expanded = null, expandDepth = 1, showResidual = true, residualTolerance = DEFAULT_RESIDUAL_TOLERANCE, otherLabel, residualLabel } = options;
+	const tree = walk(nodes, null, 0, /* @__PURE__ */ new Map());
+	rollupTree(tree, rollup);
+	if (maxDepth != null && maxDepth >= 0) prune(tree, maxDepth);
+	const shaped = shape(tree, null, null, {
+		sort,
+		maxChildren,
+		showResidual,
+		residualTolerance,
+		otherLabel,
+		residualLabel,
+		rollup
+	});
+	const total = sumFinite(shaped.nodes.map((node) => node.value));
+	const previousTotal = sumFinite(shaped.nodes.map((node) => node.previous));
+	const partsDepth = shaped.nodes.length >= 2 ? 0 : 1;
+	const allRows = [];
+	const rows = [];
+	const expandedKeys = [];
+	let levels = 0;
+	let hasPrevious = false;
+	let expandable = false;
+	const isOpen = (node) => node.children.length > 0 && (expanded ? expanded.has(node.key) : node.depth < expandDepth);
+	const visit = (siblings, parent, parentVisible) => {
+		siblings.forEach((node, index) => {
+			const parentValue = parent ? parent.value : total;
+			const open = isOpen(node);
+			const row = {
+				key: node.key,
+				label: node.label,
+				depth: node.depth,
+				value: node.value,
+				previous: node.previous,
+				parentKey: parent?.key ?? null,
+				parentValue,
+				share: isFinite(node.value) && isFinite(parentValue) && parentValue !== 0 ? node.value / parentValue : null,
+				shareOfTotal: isFinite(node.value) && isFinite(total) && total !== 0 ? node.value / total : null,
+				hasChildren: node.children.length > 0,
+				expanded: open,
+				posInSet: index + 1,
+				setSize: siblings.length,
+				role: node.role,
+				folded: node.folded
+			};
+			allRows.push(row);
+			if (parentVisible) rows.push(row);
+			if (node.children.length > 0) expandable = true;
+			if (open) expandedKeys.push(node.key);
+			if (isFinite(node.previous)) hasPrevious = true;
+			levels = Math.max(levels, node.depth + 1);
+			if (node.children.length > 0) visit(node.children, node, parentVisible && open);
+		});
+	};
+	visit(shaped.nodes, null, true);
+	if (allRows.length === 0) return null;
+	const parts = allRows.filter((row) => row.depth === partsDepth);
+	let largest = null;
+	let topMover = null;
+	for (const row of parts) {
+		if (isFinite(row.value) && (!largest || row.value > largest.value)) largest = row;
+		if (isFinite(row.value) && isFinite(row.previous)) {
+			if (Math.abs(row.value - row.previous) > (topMover ? Math.abs(topMover.value - topMover.previous) : -1)) topMover = row;
+		}
+	}
+	return {
+		rows,
+		allRows,
+		expandedKeys,
+		total,
+		previousTotal,
+		count: rows.filter((row) => row.value != null).length,
+		nodeCount: allRows.length,
+		levels,
+		partsDepth,
+		largest,
+		topMover,
+		hasNegative: rows.some((row) => isFinite(row.value) && row.value < 0),
+		hasPrevious,
+		hasResidual: shaped.residual,
+		folded: shaped.folded,
+		expandable
+	};
+}
+/** A reading against its comparison period, with polarity resolved through `goodDirection`. `null` unless both are finite. */
+function deriveTreeDelta(value, previous, { deltaMode, goodDirection, format, locale, percentagePoints }) {
+	if (!isFinite(value) || !isFinite(previous)) return null;
+	const delta = formatDelta(value, previous, {
+		mode: deltaMode,
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	const other = formatDelta(value, previous, {
+		mode: delta.renderedMode === "percent" ? "absolute" : "percent",
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	let polarity = "neutral";
+	if (delta.direction !== "flat" && goodDirection !== "none") polarity = delta.direction === "up" === (goodDirection === "up") ? "positive" : "negative";
+	return {
+		direction: delta.direction,
+		polarity,
+		text: delta.text,
+		renderedMode: delta.renderedMode,
+		secondaryText: other.renderedMode === delta.renderedMode ? null : other.text
+	};
+}
+/** The formatters every text surface shares — headline, rows, delta, table, tooltip, descriptions. */
+function createTreeFormatters({ format, locale, formatValue, deltaMode = "percent", shareFormat = "percent:0", percentagePoints = DEFAULT_TREE_LABELS.percentagePoints }) {
+	return {
+		formatValue: (value) => isFinite(value) ? formatValue ? formatValue(value) : formatNumber(value, format, locale) : "—",
+		formatShare: (share) => isFinite(share) ? formatNumber(share, shareFormat, locale) : "—",
+		formatChange: (value, previous) => isFinite(value) && isFinite(previous) ? formatDelta(value, previous, {
+			mode: deltaMode,
+			format,
+			locale,
+			pointsSuffix: percentagePoints
+		}).text : "—"
+	};
+}
+const stripSign = (text) => text.replace(/^[+\-−]/, "");
+/**
+* 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.
+*
+* It names the shape, the total's direct parts with their values and shares,
+* and the branch that moved furthest — rather than enumerating every visible
+* row the way a flat card must. The rows here are real `treeitem`s carrying
+* their own label, value, share and `aria-level`, so a screen reader already
+* reaches each one in place; repeating all of them in one sentence would bury
+* the answer this description exists to give.
+*/
+function buildTreeDescription({ name, state, headline, summary, focus, delta, formatters, 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 sentences = [];
+	if (headline === "focus" && focus) sentences.push(`${name}: ${focus.label} ${formatters.formatValue(focus.value)}.`);
+	else if (headline !== "none" && summary) sentences.push(`${name}: ${labels.total} ${formatters.formatValue(summary.total)}.`);
+	else sentences.push(`${name}.`);
+	if (delta) {
+		const word = delta.direction === "up" ? labels.increase : delta.direction === "down" ? labels.decrease : labels.unchanged;
+		const flat = delta.direction === "flat";
+		const previous = headline === "focus" && focus ? focus.previous : summary?.previousTotal;
+		sentences.push(labels.comparisonSentence({
+			word,
+			primary: flat ? "" : stripSign(delta.text),
+			secondary: flat || !delta.secondaryText ? null : stripSign(delta.secondaryText),
+			previousText: formatters.formatValue(previous)
+		}));
+	}
+	if (summary) {
+		sentences.push(labels.shapeSummary({
+			nodes: summary.nodeCount,
+			levels: summary.levels
+		}));
+		const parts = summary.allRows.filter((row) => row.depth === summary.partsDepth);
+		if (parts.length > 0) {
+			const list = parts.map((row) => `${row.label} ${formatters.formatValue(row.value)} (${formatters.formatShare(row.shareOfTotal)})`).join(", ");
+			sentences.push(labels.partsSummary(parts.length, list));
+		}
+		if (summary.topMover && summary.topMover.key !== focus?.key) sentences.push(labels.moverSentence({
+			label: summary.topMover.label,
+			changeText: formatters.formatChange(summary.topMover.value, summary.topMover.previous)
+		}));
+		if (summary.folded > 0) sentences.push(labels.foldedSummary(summary.folded));
+		if (summary.hasResidual) sentences.push(labels.residualSummary);
+	}
+	if (asOfText) sentences.push(`${labels.asOf} ${asOfText}.`);
+	return sentences.join(" ");
+}
+/** The plot's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+function buildTreeChartDescription({ name, summary, formatters, labels }) {
+	return labels.chartDescription({
+		name,
+		count: summary.rows.length,
+		levels: summary.levels,
+		total: formatters.formatValue(summary.total),
+		top: summary.largest?.label ?? "—",
+		topValue: formatters.formatValue(summary.largest?.value)
+	});
+}
+//#endregion
+export { DEFAULT_RESIDUAL_TOLERANCE, DEFAULT_TREE_LABELS, TREE_OTHER_KEY, TREE_RESIDUAL_KEY, buildTree, buildTreeChartDescription, buildTreeDescription, createTreeFormatters, deriveTreeDelta, deriveTreeState, resolveTreeLabels };

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

@@ -0,0 +1,4 @@
+import { BuildTreeDescriptionInput, BuildTreeOptions, DEFAULT_RESIDUAL_TOLERANCE, DEFAULT_TREE_LABELS, DeriveTreeDeltaOptions, DeriveTreeStateInput, TREE_OTHER_KEY, TREE_RESIDUAL_KEY, TreeCardLabels, TreeCardSize, TreeCardState, TreeCardStatus, TreeColorBy, TreeDelta, TreeDeltaMode, TreeGoodDirection, TreeHeadline, TreeNode, TreeNodeRole, TreePolarity, TreeRollup, TreeRow, TreeRowSecondary, TreeSort, TreeSummary, TreeTextFormatters, buildTree, buildTreeChartDescription, buildTreeDescription, createTreeFormatters, deriveTreeDelta, deriveTreeState, resolveTreeLabels } from "./TreeCard.model.js";
+import { TreeCard, TreeCardProps } from "./TreeCard.js";
+import { TREE_DEPTH_STEPS, TREE_HOVER_PARAM, TREE_MAX_BAR_HEIGHT, TREE_TABLE_DATASET, TREE_TOTAL_PARAM, TREE_ZERO_DATASET, TreeBarsSpecOptions, buildTreeBarsSpec, treeBarColor } from "./TreeCard.chart.js";
+export { type BuildTreeDescriptionInput, type BuildTreeOptions, DEFAULT_RESIDUAL_TOLERANCE, DEFAULT_TREE_LABELS, type DeriveTreeDeltaOptions, type DeriveTreeStateInput, TREE_DEPTH_STEPS, TREE_HOVER_PARAM, TREE_MAX_BAR_HEIGHT, TREE_OTHER_KEY, TREE_RESIDUAL_KEY, TREE_TABLE_DATASET, TREE_TOTAL_PARAM, TREE_ZERO_DATASET, type TreeBarsSpecOptions, TreeCard, type TreeCardLabels, type TreeCardProps, type TreeCardSize, type TreeCardState, type TreeCardStatus, type TreeColorBy, type TreeDelta, type TreeDeltaMode, type TreeGoodDirection, type TreeHeadline, type TreeNode, type TreeNodeRole, type TreePolarity, type TreeRollup, type TreeRow, type TreeRowSecondary, type TreeSort, type TreeSummary, type TreeTextFormatters, buildTree, buildTreeBarsSpec, buildTreeChartDescription, buildTreeDescription, createTreeFormatters, deriveTreeDelta, deriveTreeState, resolveTreeLabels, treeBarColor };

package/dist/components/TreeCard/index.js

@@ -0,0 +1,4 @@
+import { TREE_DEPTH_STEPS, TREE_HOVER_PARAM, TREE_MAX_BAR_HEIGHT, TREE_TABLE_DATASET, TREE_TOTAL_PARAM, TREE_ZERO_DATASET, buildTreeBarsSpec, treeBarColor } from "./TreeCard.chart.js";
+import { DEFAULT_RESIDUAL_TOLERANCE, DEFAULT_TREE_LABELS, TREE_OTHER_KEY, TREE_RESIDUAL_KEY, buildTree, buildTreeChartDescription, buildTreeDescription, createTreeFormatters, deriveTreeDelta, deriveTreeState, resolveTreeLabels } from "./TreeCard.model.js";
+import { TreeCard } from "./TreeCard.js";
+export { DEFAULT_RESIDUAL_TOLERANCE, DEFAULT_TREE_LABELS, TREE_DEPTH_STEPS, TREE_HOVER_PARAM, TREE_MAX_BAR_HEIGHT, TREE_OTHER_KEY, TREE_RESIDUAL_KEY, TREE_TABLE_DATASET, TREE_TOTAL_PARAM, TREE_ZERO_DATASET, TreeCard, buildTree, buildTreeBarsSpec, buildTreeChartDescription, buildTreeDescription, createTreeFormatters, deriveTreeDelta, deriveTreeState, resolveTreeLabels, treeBarColor };

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

@@ -0,0 +1,75 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { TrendMark, TrendScale, TrendStack, TrendXType } from "./TrendCard.model.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/TrendCard/TrendCard.chart.d.ts
+/** Long-form readings: `{ x, s, y, raw, i, c, n }` per `TrendRow`, for the visible series only. */
+declare const TREND_TABLE_DATASET = "table";
+/** One row per period, `{ x }` — the crosshair, filtered by the hover selection. */
+declare const TREND_PERIODS_DATASET = "periods";
+/** Zero or one row `{ value }` — the target reference rule. */
+declare const TREND_REFERENCE_DATASET = "reference";
+/** Resolved bands `{ start, end, label? }` — the washed period annotations. */
+declare const TREND_BANDS_DATASET = "bands";
+/** One row per visible series — its last finite reading, for the endpoint labels. */
+declare const TREND_LATEST_DATASET = "latest";
+/** The shared-x hover selection: projected onto `x`, so every series lights up at the pointed period. */
+declare const TREND_HOVER_PARAM = "hover";
+/** Responsive x tick values, recomputed by Vega when the domain or the width changes. */
+declare const TREND_X_TICKS_PARAM = "trend_x_ticks";
+interface TrendPlotSpecOptions {
+  mark: TrendMark;
+  /** `auto` lets a line crop to its data range; `zero` includes zero. Areas and bars always include zero. */
+  scale: TrendScale;
+  xType: TrendXType;
+  /** How several area or bar series sit together. Lines never stack. */
+  stack: TrendStack;
+  /** Plot height in pixels, axes included. */
+  height: number;
+  /** Draw both axes. `false` shrinks the plot toward a sparkline; the table still carries every value. */
+  axes: boolean;
+  /** Number of y ticks — the caller scales it to the plot's height. */
+  yTicks: number;
+  /** Draw the target reference rule (the `reference` dataset carries the value). */
+  reference: boolean;
+  /** Wash the `bands` dataset behind the marks. */
+  bands: boolean;
+  /** Wire the shared-x hover selection, the crosshair and the tooltip channel. */
+  tooltip: boolean;
+  /** Label each series' last reading in a right-hand gutter, so a reader need not travel to the legend. */
+  labelSeries: boolean;
+  /**
+   * Dim every series but the focused one. Only meaningful while colour is doing
+   * emphasis — with identity slots or a ramp, dimming would fight the hue.
+   * The focused rows carry `f: true`.
+   */
+  emphasize: boolean;
+  /** Tooltip titles. */
+  xTitle: string;
+  yTitle: string;
+  /** Localised title for the target reference rule's hover value. */
+  targetTitle?: string;
+  /** `arcNumber` grammar for the y axis and the tooltip — the PLOTTED units (index points or a share when the card transforms them). */
+  plotFormat: 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 plot: one mark per series on a SHARED y scale (never a second
+ * axis — series in different units are indexed to a common base instead, which
+ * the card does before it gets here), quiet labelled axes, an optional dotted
+ * target rule, washed period bands behind everything, and the documented
+ * multi-series hover: a transparent `point` layer carrying a `nearest`
+ * selection projected onto `x`, a crosshair rule filtered by that selection,
+ * and dots on every series at the pointed period.
+ *
+ * Gaps stay gaps — a `null` reading breaks the path rather than dropping it to
+ * zero. Lines may crop (`scale: "auto"`); areas and bars keep a zero baseline
+ * whatever `scale` says, because proportional ink is not negotiable.
+ */
+declare function buildTrendPlotSpec(options: TrendPlotSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { TREND_BANDS_DATASET, TREND_HOVER_PARAM, TREND_LATEST_DATASET, TREND_PERIODS_DATASET, TREND_REFERENCE_DATASET, TREND_TABLE_DATASET, TREND_X_TICKS_PARAM, TrendPlotSpecOptions, buildTrendPlotSpec };