@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/MetricCard/MetricCard.chart.js

@@ -0,0 +1,435 @@
+import { AXIS_LABEL_LIMIT_EXPR } from "../../lib/vega/axisTicks.js";
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/MetricCard/MetricCard.chart.ts
+/** The trend rows: `{ x, y }` per `MetricTrendRow` (plus `hl` and `tone` in the highlight variant). */
+const METRIC_TREND_DATASET = "table";
+/** Zero or one row `{ value }` — the target reference line. */
+const METRIC_REFERENCE_DATASET = "reference";
+/** Zero or one row — the latest valid reading, marked with a dot. */
+const METRIC_LATEST_DATASET = "latest";
+/** Highlight variant: the readings outside the window with a `seg` of `before` or `after` — the gray context runs. */
+const METRIC_CONTEXT_DATASET = "context";
+/** Highlight variant: the readings inside the window — the coloured segment. */
+const METRIC_HIGHLIGHT_ROWS_DATASET = "highlightRows";
+/** Highlight variant: the window's start and end readings — the two dots. */
+const METRIC_HIGHLIGHT_POINTS_DATASET = "highlightPoints";
+/** Highlight variant: one row `{ start, end, startY, endY, tone }` — the band behind a line and the axis anchors. */
+const METRIC_HIGHLIGHT_DATASET = "highlight";
+/** The nearest-point hover selection. */
+const METRIC_HOVER_PARAM = "hover";
+/** Responsive x tick values, recomputed by Vega when the domain or width changes. */
+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. */
+const METRIC_HIGHLIGHT_START_PARAM = "metric_hl_start";
+const METRIC_HIGHLIGHT_END_PARAM = "metric_hl_end";
+const POINT_SIZE = 64;
+const BAR_WIDTH_EXPR = "min(24, bandwidth('x') * 0.7)";
+const PLOT_PADDING = 6;
+const BAND_OPACITY = .08;
+const DISCRETE_DOMAIN_EXPR = `pluck(data('${METRIC_TREND_DATASET}'), 'x')`;
+const Y_AXIS_TICKS = 3;
+/**
+* A mark colour that follows the window's polarity through the row's `tone`
+* field — the diverging ends when the move means good or bad (lightness-matched,
+* ≥ 3:1 on both surfaces), the emphasis hue when it is neutral — and
+* `fallback` for rows outside the window (`tone: null`). Kept in the spec as
+* three token values, so the spec stays structural while the data decides.
+*/
+function toneColor(tokens, fallback) {
+	return {
+		condition: [
+			{
+				test: "datum.tone === 'positive'",
+				value: tokens.divergingPositive
+			},
+			{
+				test: "datum.tone === 'negative'",
+				value: tokens.divergingNegative
+			},
+			{
+				test: "datum.tone === 'neutral'",
+				value: tokens.emphasis
+			}
+		],
+		value: fallback
+	};
+}
+/**
+* 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.
+*/
+function buildMetricTrendSpec(options, tokens) {
+	const { mark, scale, xType, axes = "x", height, reference, tooltip, highlight = false, xTitle, yTitle, valueFormat, timeFormat, axisTimeFormat } = options;
+	const zero = mark !== "line" || scale === "zero";
+	const showX = axes === "x" || axes === "both";
+	const showY = axes === "y" || axes === "both";
+	const discreteX = mark === "bar" || xType === "ordinal";
+	const xTickFormat = xType === "temporal" ? axisTimeFormat : "compact";
+	const xTickKind = xType === "temporal" ? "time" : xType === "quantitative" ? "number" : "text";
+	const axisArgs = `domain('x'), width, ${discreteX}, ${JSON.stringify(xTickFormat)}, ${JSON.stringify(xTickKind)}`;
+	const anchorsArg = highlight ? `, [${METRIC_HIGHLIGHT_START_PARAM}, ${METRIC_HIGHLIGHT_END_PARAM}]` : "";
+	const xAxisLabels = xType === "temporal" ? {
+		format: axisTimeFormat,
+		formatType: "arcTime"
+	} : xType === "quantitative" ? {
+		format: "compact",
+		formatType: "arcNumber"
+	} : {};
+	const xAxis = showX ? {
+		title: null,
+		orient: "bottom",
+		domain: true,
+		ticks: false,
+		grid: false,
+		values: { expr: METRIC_X_TICKS_PARAM },
+		labelAngle: 0,
+		labelAlign: { expr: highlight ? `arcAxisLabelAlign(datum.value, ${axisArgs}${anchorsArg})` : "scale('x', datum.value) === scale('x', domain('x')[0]) ? 'left' : scale('x', datum.value) === scale('x', peek(domain('x'))) ? 'right' : 'center'" },
+		labelFlush: false,
+		labelOverlap: false,
+		labelLimit: { expr: AXIS_LABEL_LIMIT_EXPR },
+		labelPadding: 4,
+		...xAxisLabels
+	} : null;
+	const yAxis = showY ? {
+		title: null,
+		orient: "left",
+		domain: false,
+		ticks: false,
+		grid: true,
+		tickCount: Y_AXIS_TICKS,
+		labelOverlap: true,
+		labelPadding: 6,
+		format: valueFormat,
+		formatType: "arcNumber"
+	} : null;
+	const discreteScale = highlight ? { scale: { domain: { expr: DISCRETE_DOMAIN_EXPR } } } : {};
+	const xField = mark === "bar" ? {
+		field: "x",
+		type: "ordinal",
+		sort: null,
+		axis: xAxis,
+		...discreteScale
+	} : {
+		field: "x",
+		type: xType,
+		axis: xAxis,
+		...xType === "ordinal" ? {
+			sort: null,
+			...discreteScale
+		} : { scale: {
+			nice: false,
+			...xType === "quantitative" ? { zero: false } : {}
+		} }
+	};
+	const yField = {
+		field: "y",
+		type: "quantitative",
+		axis: yAxis,
+		scale: {
+			zero,
+			nice: showY
+		}
+	};
+	const tooltipChannel = [xType === "temporal" ? {
+		field: "x",
+		type: "temporal",
+		title: xTitle,
+		format: timeFormat,
+		formatType: "arcTime"
+	} : xType === "quantitative" ? {
+		field: "x",
+		type: "quantitative",
+		title: xTitle,
+		format: "number",
+		formatType: "arcNumber"
+	} : {
+		field: "x",
+		type: "nominal",
+		title: xTitle
+	}, {
+		field: "y",
+		type: "quantitative",
+		title: yTitle,
+		format: valueFormat,
+		formatType: "arcNumber"
+	}];
+	const layers = [];
+	if (highlight) layers.push({
+		data: { name: METRIC_HIGHLIGHT_DATASET },
+		mark: {
+			type: "rect",
+			opacity: BAND_OPACITY,
+			aria: false
+		},
+		encoding: {
+			x: {
+				...xField,
+				field: "start",
+				...discreteX ? { bandPosition: 0 } : {}
+			},
+			x2: {
+				field: "end",
+				...discreteX ? { bandPosition: 1 } : {}
+			},
+			fill: toneColor(tokens, tokens.emphasis)
+		}
+	});
+	if (mark === "bar") layers.push({
+		...tooltip ? { params: [{
+			name: METRIC_HOVER_PARAM,
+			select: {
+				type: "point",
+				on: "pointerover",
+				clear: "pointerout",
+				encodings: ["x"]
+			}
+		}] } : {},
+		mark: {
+			type: "bar",
+			...highlight ? {} : { fill: tokens.emphasis },
+			cornerRadiusEnd: 2,
+			width: { expr: BAR_WIDTH_EXPR }
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			...highlight ? { fill: toneColor(tokens, tokens.context) } : {},
+			...tooltip ? {
+				opacity: {
+					condition: {
+						param: METRIC_HOVER_PARAM,
+						empty: false,
+						value: 1
+					},
+					value: .75
+				},
+				tooltip: tooltipChannel
+			} : {}
+		}
+	});
+	else if (highlight) {
+		const contextEncoding = {
+			x: xField,
+			y: yField,
+			detail: {
+				field: "seg",
+				type: "nominal"
+			}
+		};
+		if (mark === "area") layers.push({
+			data: { name: METRIC_CONTEXT_DATASET },
+			mark: {
+				type: "area",
+				fill: tokens.context,
+				fillOpacity: .12,
+				line: false,
+				interpolate: "linear"
+			},
+			encoding: contextEncoding
+		});
+		layers.push({
+			data: { name: METRIC_CONTEXT_DATASET },
+			mark: {
+				type: "line",
+				stroke: tokens.context,
+				strokeWidth: 2,
+				strokeCap: "round",
+				strokeJoin: "round",
+				interpolate: "linear"
+			},
+			encoding: contextEncoding
+		});
+		if (mark === "area") layers.push({
+			data: { name: METRIC_HIGHLIGHT_ROWS_DATASET },
+			mark: {
+				type: "area",
+				fillOpacity: .12,
+				line: false,
+				interpolate: "linear"
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				fill: toneColor(tokens, tokens.emphasis)
+			}
+		});
+		layers.push({
+			data: { name: METRIC_HIGHLIGHT_ROWS_DATASET },
+			mark: {
+				type: "line",
+				strokeWidth: 2,
+				strokeCap: "round",
+				strokeJoin: "round",
+				interpolate: "linear"
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				stroke: toneColor(tokens, tokens.emphasis)
+			}
+		});
+	} else {
+		if (mark === "area") layers.push({
+			mark: {
+				type: "area",
+				fill: tokens.emphasis,
+				fillOpacity: .12,
+				line: false,
+				interpolate: "linear"
+			},
+			encoding: {
+				x: xField,
+				y: yField
+			}
+		});
+		layers.push({
+			mark: {
+				type: "line",
+				stroke: tokens.emphasis,
+				strokeWidth: 2,
+				strokeCap: "round",
+				strokeJoin: "round",
+				interpolate: "linear"
+			},
+			encoding: {
+				x: xField,
+				y: yField
+			}
+		});
+	}
+	if (reference) layers.push({
+		data: { name: METRIC_REFERENCE_DATASET },
+		mark: {
+			type: "rule",
+			stroke: tokens.reference,
+			strokeWidth: 1.5,
+			strokeDash: [0, 4],
+			strokeCap: "round",
+			opacity: .9,
+			aria: false
+		},
+		encoding: {
+			y: {
+				...yField,
+				field: "value"
+			},
+			...tooltip ? { tooltip: [{
+				field: "value",
+				type: "quantitative",
+				title: options.targetTitle ?? "Target",
+				format: valueFormat,
+				formatType: "arcNumber"
+			}] } : {}
+		}
+	});
+	if (mark !== "bar") {
+		const dot = {
+			type: "point",
+			filled: true,
+			size: POINT_SIZE,
+			stroke: tokens.background,
+			strokeWidth: 1.5,
+			opacity: 1,
+			aria: false
+		};
+		if (highlight) layers.push({
+			data: { name: METRIC_HIGHLIGHT_POINTS_DATASET },
+			mark: dot,
+			encoding: {
+				x: xField,
+				y: yField,
+				fill: toneColor(tokens, tokens.emphasis)
+			}
+		});
+		else layers.push({
+			data: { name: METRIC_LATEST_DATASET },
+			mark: {
+				...dot,
+				fill: tokens.emphasis
+			},
+			encoding: {
+				x: xField,
+				y: yField
+			}
+		});
+		if (tooltip) layers.push({
+			params: [{
+				name: METRIC_HOVER_PARAM,
+				select: {
+					type: "point",
+					on: "pointermove",
+					nearest: true,
+					clear: "pointerout",
+					encodings: ["x"]
+				}
+			}],
+			mark: {
+				type: "point",
+				filled: true,
+				size: POINT_SIZE,
+				...highlight ? {} : { fill: tokens.emphasis },
+				stroke: tokens.background,
+				strokeWidth: 1.5,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				...highlight ? { fill: toneColor(tokens, tokens.context) } : {},
+				opacity: {
+					condition: {
+						param: METRIC_HOVER_PARAM,
+						empty: false,
+						value: 1
+					},
+					value: 0
+				},
+				tooltip: tooltipChannel
+			}
+		});
+	}
+	const params = [];
+	if (highlight) params.push({
+		name: METRIC_HIGHLIGHT_START_PARAM,
+		expr: `length(data('${METRIC_HIGHLIGHT_DATASET}')) ? data('${METRIC_HIGHLIGHT_DATASET}')[0].start : null`
+	}, {
+		name: METRIC_HIGHLIGHT_END_PARAM,
+		expr: `length(data('${METRIC_HIGHLIGHT_DATASET}')) ? data('${METRIC_HIGHLIGHT_DATASET}')[0].end : null`
+	});
+	if (showX) params.push({
+		name: METRIC_X_TICKS_PARAM,
+		expr: `arcAxisTicks(${axisArgs}${anchorsArg})`
+	});
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 240,
+		height,
+		autosize: {
+			type: "fit",
+			contains: "padding"
+		},
+		padding: PLOT_PADDING,
+		background: "transparent",
+		data: { name: METRIC_TREND_DATASET },
+		...params.length > 0 ? { params } : {},
+		layer: layers,
+		config: arcVegaConfig(tokens, {
+			locale: options.locale,
+			timeZone: options.timeZone
+		})
+	};
+}
+//#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, buildMetricTrendSpec };

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

@@ -0,0 +1,227 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { MetricCardLabels, MetricCardSize, MetricCardStatus, MetricCardVariant, MetricComparison, MetricDeltaMode, MetricGoodDirection, MetricHighlightRange, MetricTrendAxes, MetricTrendMark, MetricTrendPoint, MetricTrendScale } from "./MetricCard.model.js";
+import { ReactNode } from "react";
+import { BoxProps } from "@arcfusionz/arc-primitive-ui";
+import { TopLevelSpec } from "vega-lite";
+import { Result } from "vega-embed";
+//#region src/components/MetricCard/MetricCard.d.ts
+interface MetricCardBaseProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /**
+   * `default` (the metric tile) or `highlight` — a card about one window of
+   * the trend. A highlight card requires `highlight` and `trend` and derives
+   * its headline from them: the value is the reading at the window's end, the
+   * badge is the change across the window, the comparison line is the window's
+   * label or period. `value`, `previousValue` and `comparisonLabel` are not
+   * accepted with it. The sparkline paints the window in the polarity hue on a
+   * gray context, dots its start and end, washes a band behind it and labels
+   * its bounds on the x axis; hovering inside it adds the window's start, end
+   * and change to the tooltip. Default `default`. Stamped as `data-variant`.
+   */
+  variant?: MetricCardVariant;
+  /**
+   * The window a `highlight` card is about: `{ start, end, label? }` in the
+   * trend's own `x` type (Dates or ISO strings, numbers, or category labels).
+   * Each bound snaps inward to the nearest finite reading. A window without
+   * two distinct readings is unresolved — plain sparkline, no badge,
+   * `data-highlight="unresolved"`. Pass stable values (ISO strings or memoized
+   * Dates): the window is re-resolved when they change.
+   */
+  highlight?: MetricHighlightRange;
+  /**
+   * `highlight` variant: clicking the delta stack opens a popover detailing
+   * the window — its start and end readings, the change in both forms, every
+   * reading inside it with its step from the previous one, and how the trend
+   * moved before the window and since it. Default `true`; `false` keeps the
+   * hover tooltip, for a static tile.
+   */
+  highlightDetails?: boolean;
+  /** Open the highlight details popover on first render. */
+  defaultHighlightDetailsOpen?: boolean;
+  /** The metric's name — the tile's heading. Pass `name` too when this is not plain text. */
+  label: ReactNode;
+  /** Plain-text name used in the generated descriptions and control labels. Defaults to `label` when it is a string. */
+  name?: string;
+  /** Definition of the metric, shown in a tooltip behind an info control beside the label and exposed to assistive technology as the control's description. */
+  hint?: string;
+  /** The headline reading. `null`/`undefined` renders the empty (or no-match) state. Not accepted by the `highlight` variant, which reads the window's end value from `trend`. */
+  value?: number | null;
+  /**
+   * Number format for the value, delta, target, table and tooltip — one
+   * grammar so nothing rounds two ways: `number[:digits]`, `integer`,
+   * `compact[:digits]`, `percent[:digits]`, `currency:CODE[:digits|compact]`.
+   * Default `compact` (`3.8M`); pass `percent` for ratio metrics.
+   */
+  format?: string;
+  /** Custom formatter for values. Takes precedence over `format` everywhere a value is rendered. */
+  formatValue?: (value: number) => string;
+  /** Unit shown after the value in the muted role (`ms`, `req/s`). Prefer `format="currency:…"` for money. */
+  unit?: ReactNode;
+  /** The reading one period ago. Renders the delta above its label to the right of the value; pass `null` while unknown to reserve the stack's height. Not accepted by the `highlight` variant, whose delta is the change across the window. */
+  previousValue?: number | null;
+  /** What the delta is against — `vs last month`. Default: `labels.previousPeriod`. Not accepted by the `highlight` variant, which shows `highlight.label` or the window's period, nor with `comparisons`, whose selected baseline names the line. */
+  comparisonLabel?: ReactNode;
+  /**
+   * The baselines the headline can be compared with — yesterday, last week,
+   * last month, last year — as `{ key?, label, value }` records in the order
+   * they should be offered. The selected one supplies the delta and the
+   * comparison line (`vs last month`, through `labels.versus`), and the delta
+   * stack becomes a compare-with menu listing every baseline with its reading
+   * and the change the headline would show against it. Replaces
+   * `previousValue` and `comparisonLabel`; a baseline with `value: null` is
+   * listed but cannot be chosen. Pass `[]` while loading to reserve the
+   * stack's height. Not accepted by the `highlight` variant.
+   */
+  comparisons?: readonly MetricComparison[];
+  /**
+   * Key of the selected baseline, controlled. Pair with `onComparisonChange`
+   * to follow the reader's pick; omit it for the uncontrolled card
+   * (`defaultComparison`, else the first baseline with a value). `null`
+   * selects none — no delta, and the line invites a choice. A controlled key
+   * without its change handler is pinned: the stack renders no menu.
+   */
+  comparison?: string | null;
+  /** The selected baseline on first render when `comparison` is uncontrolled. Default: the first baseline with a value. */
+  defaultComparison?: string;
+  /** Called with the chosen baseline's key when the reader picks another one from the compare-with menu. */
+  onComparisonChange?: (key: string) => void;
+  /**
+   * The delta stack is a menu button: click, Enter, Space or an arrow key
+   * opens the compare-with menu listing every baseline — the `comparisons`,
+   * or the one `previousValue` as a single row — with its reading and the
+   * change against it in both forms. Default `true`; `false` for a static
+   * tile, where the stack is a focusable group with the hover tooltip.
+   * Stamped as `data-selectable` while the menu exists. Not accepted by the
+   * `highlight` variant, whose switch is `highlightDetails`.
+   */
+  selectable?: boolean;
+  /** `percent` (default) is relative change; `absolute` is the difference in the value's units — percentage points for a `percent` format. */
+  deltaMode?: MetricDeltaMode;
+  /**
+   * Which direction is good. Drives the delta's polarity color and the
+   * target meter's status: `up` (revenue), `down` (churn, latency, cost) or
+   * `none` (headcount — the delta stays neutral). Default `up`.
+   */
+  goodDirection?: MetricGoodDirection;
+  /** The goal. Renders a `Meter` of progress and the variance against it; pass `null` while unknown to reserve the block's height. */
+  target?: number | null;
+  /**
+   * Recent readings as `{ x, y }` points: `x` a `Date`, ISO string, number or
+   * category label; `y` the value or `null` for a gap. Two or more finite
+   * readings draw the sparkline; fewer show the insufficient-data caption in
+   * the same space. Pass `[]` while loading to reserve the sparkline's height.
+   * Required by the `highlight` variant.
+   */
+  trend?: readonly MetricTrendPoint[];
+  /** `line` (default, may crop to the data range), `area` (zero baseline, filled to it) or `bar` (zero baseline, for a few periods). */
+  trendMark?: MetricTrendMark;
+  /** Y-scale baseline for a `line` sparkline: `auto` (default) fits the data range and reads for shape; `zero` includes zero. Areas and bars always start at zero. */
+  trendScale?: MetricTrendScale;
+  /**
+   * Which axes the sparkline draws: `x` (default — period labels under the plot,
+   * always including the first and last values), `none` (no axes), `y` (value labels with hairline grid
+   * lines, ticks rounded to readable numbers) or `both`. Labels use the card's
+   * `format`, `locale` and `timeZone`. Interior x labels adapt to the plot width;
+   * a `highlight` card labels the window's bounds instead.
+   * An x axis adds 24px to the default
+   * `trendHeight` so the plot keeps its size.
+   */
+  trendAxes?: MetricTrendAxes;
+  /** Sparkline height in pixels, axes included. Defaults per `size` (32 / 40 / 56), plus 24 when `trendAxes` shows the x axis. */
+  trendHeight?: number;
+  /** Period granularity of temporal `x` values for tooltips and the table. Inferred from the spacing when omitted. */
+  trendGranularity?: ArcTimeGranularity;
+  /**
+   * The takeaway in a sentence, rendered beside the AI mark under the chart —
+   * the insight slot. Wrap values in `<strong>` to set them in bold. A
+   * `highlight` card with no `insight` generates one from the window, with the
+   * start and end readings and the change in bold; pass `null` or `false` to
+   * render no insight.
+   */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with data already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: MetricCardStatus;
+  /** The consumer's filter is active — a missing value then reads as no-match rather than empty, with a clear-filters action when `onClearFilters` is set. */
+  filtered?: boolean;
+  /** The data is older than the product's freshness rule (TanStack Query's `isStale`). Shows a badge and stamps `data-stale`. */
+  stale?: boolean;
+  /** When the data was last true. Rendered as an "as of" line (the date by default — see `updatedAtFormat`) and included in the description. */
+  updatedAt?: Date | string | number;
+  /**
+   * How `updatedAt` is written, as a time-grammar granularity — `day`
+   * (default, `Sep 8, 2026`), `datetime` (`Sep 8, 2026, 04:30 PM`), `time`
+   * (`04:30 PM`), `month` (`Sep 2026`), `year` — or a formatter for a custom
+   * form. Applies to the as-of line and the description alike, in the card's
+   * `locale` and `timeZone`.
+   */
+  updatedAtFormat?: ArcTimeGranularity | ((date: Date) => string);
+  /** Recovery action for the error state; renders a retry button when set. */
+  onRetry?: () => void;
+  /** Recovery action for the no-match state; renders a clear-filters button when set. */
+  onClearFilters?: () => void;
+  /** Density: `sm` for dense grids, `md` (default), `lg` for a hero metric. Scales type, padding and the default sparkline height. */
+  size?: MetricCardSize;
+  /** Heading level of the label for the document outline. Default 3 — tiles usually sit under a page's h2. */
+  titleLevel?: 2 | 3 | 4 | 5 | 6;
+  /** BCP 47 locale for every number and date. Defaults to the runtime's. Thai products on the Gregorian calendar pass `th-TH-u-ca-gregory`. */
+  locale?: string;
+  /** IANA time zone for dates. Defaults to the runtime's — pass it for deterministic output and single-business-zone reporting. */
+  timeZone?: string;
+  /** Overrides for every rendered or announced string. */
+  labels?: Partial<MetricCardLabels>;
+  /** Replaces the generated accessible description of the whole card (the figure's `aria-describedby` text). */
+  description?: string;
+  /** Trailing header slot — a ghost `Button` or `Menu` for drill-through, export, or settings. */
+  action?: ReactNode;
+  /** Open the data popover on first render, anchored to the card. */
+  defaultTableOpen?: boolean;
+  /** Hide the header info button for the data popover. Only when another surface exposes the same values to keyboard and screen-reader users. */
+  hideTableToggle?: boolean;
+  /** Called with vega-embed's result once the sparkline mounts — for `view` access in advanced compositions. */
+  onEmbed?: (result: Result) => void;
+  /** Escape hatch: transform the sparkline spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+type MetricCardComparisonProps = {
+  comparisons?: never;
+  comparison?: never;
+  defaultComparison?: never;
+  onComparisonChange?: never;
+} | {
+  comparisons: readonly MetricComparison[];
+  comparison?: string | null;
+  defaultComparison?: string;
+  onComparisonChange?: (key: string) => void;
+  previousValue?: never;
+  comparisonLabel?: never;
+};
+type MetricCardVariantProps = ({
+  variant?: "default";
+  highlight?: never;
+  highlightDetails?: never;
+  defaultHighlightDetailsOpen?: never;
+} & MetricCardComparisonProps) | {
+  variant: "highlight";
+  highlight: MetricHighlightRange;
+  trend: readonly MetricTrendPoint[];
+  value?: never;
+  previousValue?: never;
+  comparisonLabel?: never;
+  comparisons?: never;
+  comparison?: never;
+  defaultComparison?: never;
+  onComparisonChange?: never;
+  selectable?: never;
+};
+type MetricCardProps = MetricCardBaseProps & MetricCardVariantProps;
+/**
+ * A metric tile for dashboard grids: the headline value, its comparison
+ * against the previous period and/or a target, a sparkline of the recent
+ * readings, and every loading, empty, error and stale state — layout-stable,
+ * with a generated text equivalent and a data table in an info popover. The
+ * `highlight` variant makes one window of the trend the subject: the headline
+ * and delta derive from the window's readings and the sparkline paints it in
+ * the polarity hue on a gray context.
+ */
+declare const MetricCard: import("react").ForwardRefExoticComponent<MetricCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { MetricCard, MetricCardBaseProps, MetricCardComparisonProps, MetricCardProps, MetricCardVariantProps };