@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,4 @@
+import { BuildChartDescriptionInput, CHART_OTHER_KEY, CHART_TABLE_ROW_CAP, CHART_TYPES, CHART_TYPE_ORDER, ChartAggregate, ChartCardLabels, ChartCardSize, ChartCardState, ChartCardStatus, ChartColorMode, ChartExtent, ChartExtremes, ChartFieldType, ChartIntent, ChartLegendKind, ChartRampBucket, ChartRecord, ChartRow, ChartSeriesColor, ChartSeriesInfo, ChartSort, ChartSummary, ChartTableColumn, ChartTableModel, ChartTextFormatters, ChartType, ChartTypeFields, ChartTypeInfo, ChartWebRow, CreateChartFormattersOptions, DEFAULT_CHART_LABELS, DeriveChartStateInput, NormalizeChartDataOptions, RADAR_RING_FRACTIONS, buildChartDescription, buildChartPlotDescription, buildChartTableModel, buildRadarWebRows, buildRampBuckets, chartSeriesColorAt, createChartFormatters, deriveChartState, hasEnoughData, inferFieldType, inferGranularity, missingChartFields, normalizeChartData, resolveChartColorMode, resolveChartLabels } from "./ChartCard.model.js";
+import { ChartCard, ChartCardProps, ChartLegendPosition, ChartTableToggle } from "./ChartCard.js";
+import { CHART_AXES_DATASET, CHART_HOVER_PARAM, CHART_SERIES_NAMES_PARAM, CHART_TABLE_DATASET, CHART_X_TICKS_PARAM, ChartSpecOptions, buildChartSpec } from "./ChartCard.chart.js";
+export { type BuildChartDescriptionInput, CHART_AXES_DATASET, CHART_HOVER_PARAM, CHART_OTHER_KEY, CHART_SERIES_NAMES_PARAM, CHART_TABLE_DATASET, CHART_TABLE_ROW_CAP, CHART_TYPES, CHART_TYPE_ORDER, CHART_X_TICKS_PARAM, type ChartAggregate, ChartCard, type ChartCardLabels, type ChartCardProps, type ChartCardSize, type ChartCardState, type ChartCardStatus, type ChartColorMode, type ChartExtent, type ChartExtremes, type ChartFieldType, type ChartIntent, type ChartLegendKind, type ChartLegendPosition, type ChartRampBucket, type ChartRecord, type ChartRow, type ChartSeriesColor, type ChartSeriesInfo, type ChartSort, type ChartSpecOptions, type ChartSummary, type ChartTableColumn, type ChartTableModel, type ChartTableToggle, type ChartTextFormatters, type ChartType, type ChartTypeFields, type ChartTypeInfo, type ChartWebRow, type CreateChartFormattersOptions, DEFAULT_CHART_LABELS, type DeriveChartStateInput, type NormalizeChartDataOptions, RADAR_RING_FRACTIONS, buildChartDescription, buildChartPlotDescription, buildChartSpec, buildChartTableModel, buildRadarWebRows, buildRampBuckets, chartSeriesColorAt, createChartFormatters, deriveChartState, hasEnoughData, inferFieldType, inferGranularity, missingChartFields, normalizeChartData, resolveChartColorMode, resolveChartLabels };

package/dist/components/ChartCard/index.js

@@ -0,0 +1,4 @@
+import { 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 } from "./ChartCard.model.js";
+import { CHART_AXES_DATASET, CHART_HOVER_PARAM, CHART_SERIES_NAMES_PARAM, CHART_TABLE_DATASET, CHART_X_TICKS_PARAM, buildChartSpec } from "./ChartCard.chart.js";
+import { ChartCard } from "./ChartCard.js";
+export { CHART_AXES_DATASET, CHART_HOVER_PARAM, CHART_OTHER_KEY, CHART_SERIES_NAMES_PARAM, CHART_TABLE_DATASET, CHART_TABLE_ROW_CAP, CHART_TYPES, CHART_TYPE_ORDER, CHART_X_TICKS_PARAM, ChartCard, DEFAULT_CHART_LABELS, RADAR_RING_FRACTIONS, buildChartDescription, buildChartPlotDescription, buildChartSpec, buildChartTableModel, buildRadarWebRows, buildRampBuckets, chartSeriesColorAt, createChartFormatters, deriveChartState, hasEnoughData, inferFieldType, inferGranularity, missingChartFields, normalizeChartData, resolveChartColorMode, resolveChartLabels };

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

@@ -0,0 +1,80 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { ComparisonMark, ComparisonScale } from "./ComparisonCard.model.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/ComparisonCard/ComparisonCard.chart.d.ts
+/** The rows: `{ key, label, value, from, role }` per `ComparisonRow`, in display order. */
+declare const COMPARISON_TABLE_DATASET = "table";
+/** Zero or one row `{ value }` — the target reference rule. */
+declare const COMPARISON_REFERENCE_DATASET = "reference";
+/** Zero or one row `{ value: 0 }` — a hairline at zero, pushed only when a value is negative. */
+declare const COMPARISON_ZERO_DATASET = "zero";
+/** The hovered row's point selection. */
+declare const COMPARISON_HOVER_PARAM = "hover";
+declare const MAX_BAR_HEIGHT = 24;
+/** Which axis the value runs along. `slope` and `column` put the category on x. */
+declare function comparisonOrientation(mark: ComparisonMark): "horizontal" | "vertical";
+/** The marks that read two values per item — the `from` field is theirs alone. */
+declare function comparisonUsesFrom(mark: ComparisonMark): boolean;
+/**
+ * Whether length carries the comparison, which forces a zero baseline
+ * whatever `scale` asks for: proportional ink is not negotiable for a bar, a
+ * column or a lollipop's stem. Position marks (`dot`, `dumbbell`, `slope`) may
+ * crop — the card prints every value as text beside the mark, so a cropped
+ * scale is never the only reading.
+ */
+declare function comparisonNeedsZero(mark: ComparisonMark): boolean;
+/** The scale the plot actually draws with, after the marks that force zero. */
+declare function resolveComparisonScale(mark: ComparisonMark, scale: ComparisonScale | undefined): ComparisonScale;
+interface ComparisonPlotSpecOptions {
+  /** Which form the plot draws. */
+  mark: ComparisonMark;
+  /** Bar or column thickness in pixels, capped at 24. Centered in each band. */
+  barHeight: number;
+  /** Dot area in px² for `dot`, `lollipop`, `dumbbell` and the slope's endpoints. */
+  pointSize: number;
+  /** Initial plot height. Horizontal marks pass rows × step; vertical marks pass their own block height. The live value rides the View API. */
+  height: number;
+  /** Include zero in the value scale, or let it crop to the data. Bars, columns and lollipops always include zero — see `comparisonNeedsZero`. */
+  scale: ComparisonScale;
+  /** Draw the target reference rule (the `reference` dataset carries the value). */
+  reference: boolean;
+  /**
+   * Draw a hairline at zero (the `zero` dataset carries the one row) — only
+   * when a value is negative: for all-positive bars the left edge is the
+   * baseline already, and a hairline there would read as a border. Structural
+   * rather than data-driven because Vega warns about the infinite extent of an
+   * empty dataset that feeds a scale.
+   */
+  zeroRule: boolean;
+  /** Wire the hover selection and the tooltip channel. */
+  tooltip: boolean;
+  /** Paint the focus row in the emphasis hue and every other row in the context gray. Without a focus, all marks take the emphasis hue (nominal marks are one color). */
+  emphasize: boolean;
+  /** Tooltip titles. */
+  itemTitle: string;
+  valueTitle: string;
+  /** Names of the two readings a `dumbbell` or a `slope` compares — the axis labels of a slope, the tooltip rows of both. */
+  fromTitle: string;
+  toTitle: string;
+  /** Localised title for the target reference rule's hover value. */
+  targetTitle?: string;
+  /** `arcNumber` grammar for values (`currency:THB:compact@en-US`). */
+  valueFormat: string;
+  locale?: string;
+}
+/**
+ * Builds the plot. One mark per row on a shared value scale — length from
+ * zero for `bar`, `column` and `lollipop` (Cleveland & McGill's second-best
+ * channel, and the honest one for a zero baseline), position alone for `dot`,
+ * `dumbbell` and `slope` (the best channel, and the readable one when the
+ * values cluster far from zero) — the focus row in the emphasis hue and the
+ * rest in the context gray, a hairline at zero once a value is negative, an
+ * optional dotted target rule that joins the value domain, and a hover
+ * selection that keeps the pointed mark solid while its siblings recede.
+ *
+ * Horizontal bands have no padding, so the mark centers line up with the DOM
+ * rows that carry the names and values.
+ */
+declare function buildComparisonPlotSpec(options: ComparisonPlotSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { COMPARISON_HOVER_PARAM, COMPARISON_REFERENCE_DATASET, COMPARISON_TABLE_DATASET, COMPARISON_ZERO_DATASET, ComparisonPlotSpecOptions, MAX_BAR_HEIGHT, buildComparisonPlotSpec, comparisonNeedsZero, comparisonOrientation, comparisonUsesFrom, resolveComparisonScale };

package/dist/components/ComparisonCard/ComparisonCard.chart.js

@@ -0,0 +1,337 @@
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/ComparisonCard/ComparisonCard.chart.ts
+/** The rows: `{ key, label, value, from, role }` per `ComparisonRow`, in display order. */
+const COMPARISON_TABLE_DATASET = "table";
+/** Zero or one row `{ value }` — the target reference rule. */
+const COMPARISON_REFERENCE_DATASET = "reference";
+/** Zero or one row `{ value: 0 }` — a hairline at zero, pushed only when a value is negative. */
+const COMPARISON_ZERO_DATASET = "zero";
+/** The hovered row's point selection. */
+const COMPARISON_HOVER_PARAM = "hover";
+const MAX_BAR_HEIGHT = 24;
+const RESTING_OPACITY = .6;
+const CONNECTOR_WIDTH = 2;
+const SLOPE_WIDTH = 2;
+const CROP_PADDING = 8;
+const ROW_DOMAIN_EXPR = `pluck(data('${COMPARISON_TABLE_DATASET}'), 'key')`;
+const BAND_LABEL_EXPR = `((data('${COMPARISON_TABLE_DATASET}')[indexof(pluck(data('${COMPARISON_TABLE_DATASET}'), 'key'), datum.value)] || {}).label)`;
+/** Which axis the value runs along. `slope` and `column` put the category on x. */
+function comparisonOrientation(mark) {
+	return mark === "column" || mark === "slope" ? "vertical" : "horizontal";
+}
+/** The marks that read two values per item — the `from` field is theirs alone. */
+function comparisonUsesFrom(mark) {
+	return mark === "dumbbell" || mark === "slope";
+}
+/**
+* Whether length carries the comparison, which forces a zero baseline
+* whatever `scale` asks for: proportional ink is not negotiable for a bar, a
+* column or a lollipop's stem. Position marks (`dot`, `dumbbell`, `slope`) may
+* crop — the card prints every value as text beside the mark, so a cropped
+* scale is never the only reading.
+*/
+function comparisonNeedsZero(mark) {
+	return mark === "bar" || mark === "column" || mark === "lollipop";
+}
+/** The scale the plot actually draws with, after the marks that force zero. */
+function resolveComparisonScale(mark, scale) {
+	if (comparisonNeedsZero(mark)) return "zero";
+	return scale ?? "auto";
+}
+const SLOPE_FOLD = ["from", "value"];
+/**
+* Builds the plot. One mark per row on a shared value scale — length from
+* zero for `bar`, `column` and `lollipop` (Cleveland & McGill's second-best
+* channel, and the honest one for a zero baseline), position alone for `dot`,
+* `dumbbell` and `slope` (the best channel, and the readable one when the
+* values cluster far from zero) — the focus row in the emphasis hue and the
+* rest in the context gray, a hairline at zero once a value is negative, an
+* optional dotted target rule that joins the value domain, and a hover
+* selection that keeps the pointed mark solid while its siblings recede.
+*
+* Horizontal bands have no padding, so the mark centers line up with the DOM
+* rows that carry the names and values.
+*/
+function buildComparisonPlotSpec(options, tokens) {
+	const { mark, barHeight, pointSize, height, scale, reference, zeroRule, tooltip, emphasize, itemTitle, valueTitle, fromTitle, toTitle, valueFormat, locale } = options;
+	const vertical = comparisonOrientation(mark) === "vertical";
+	const V = vertical ? "y" : "x";
+	const V2 = vertical ? "y2" : "x2";
+	const C = vertical ? "x" : "y";
+	const valueScale = scale === "auto" ? {
+		zero: false,
+		nice: true,
+		padding: CROP_PADDING
+	} : {
+		zero: true,
+		nice: false
+	};
+	const valueChannel = (field) => ({
+		field,
+		type: "quantitative",
+		axis: null,
+		scale: valueScale
+	});
+	const categoryChannel = {
+		field: "key",
+		type: "nominal",
+		sort: null,
+		axis: vertical ? {
+			title: null,
+			labelAngle: 0,
+			labelPadding: 6,
+			domain: false,
+			ticks: false,
+			grid: false,
+			labelExpr: BAND_LABEL_EXPR,
+			aria: false
+		} : null,
+		scale: vertical ? {
+			type: "band",
+			domain: { expr: ROW_DOMAIN_EXPR },
+			paddingInner: .35,
+			paddingOuter: .2
+		} : {
+			type: "band",
+			domain: { expr: ROW_DOMAIN_EXPR },
+			paddingInner: 0,
+			paddingOuter: 0
+		}
+	};
+	const valueTooltip = (field, title) => ({
+		field,
+		type: "quantitative",
+		title,
+		format: valueFormat,
+		formatType: "arcNumber"
+	});
+	const tooltipChannel = [
+		{
+			field: "label",
+			type: "nominal",
+			title: itemTitle
+		},
+		...comparisonUsesFrom(mark) ? [valueTooltip("from", fromTitle)] : [],
+		valueTooltip("value", comparisonUsesFrom(mark) ? toTitle : valueTitle)
+	];
+	const hue = emphasize ? {
+		condition: {
+			test: "datum.role === 'focus'",
+			value: tokens.emphasis
+		},
+		value: tokens.context
+	} : { value: tokens.emphasis };
+	const hoverOpacity = tooltip ? { opacity: {
+		condition: {
+			param: COMPARISON_HOVER_PARAM,
+			value: 1
+		},
+		value: RESTING_OPACITY
+	} } : {};
+	const hoverParam = tooltip ? { params: [{
+		name: COMPARISON_HOVER_PARAM,
+		select: {
+			type: "point",
+			on: "pointerover",
+			clear: "pointerout",
+			encodings: [C]
+		}
+	}] } : {};
+	const layers = [];
+	if (zeroRule) layers.push({
+		data: { name: COMPARISON_ZERO_DATASET },
+		mark: {
+			type: "rule",
+			stroke: tokens.axis,
+			strokeWidth: 1,
+			aria: false
+		},
+		encoding: { [V]: valueChannel("value") }
+	});
+	if (mark === "bar" || mark === "column") layers.push({
+		...hoverParam,
+		mark: {
+			type: "bar",
+			[vertical ? "width" : "height"]: Math.min(24, barHeight),
+			cornerRadiusEnd: 2,
+			aria: false
+		},
+		encoding: {
+			[C]: categoryChannel,
+			[V]: valueChannel("value"),
+			fill: hue,
+			...hoverOpacity,
+			...tooltip ? { tooltip: tooltipChannel } : {}
+		}
+	});
+	if (mark === "lollipop") layers.push({
+		mark: {
+			type: "rule",
+			strokeWidth: CONNECTOR_WIDTH,
+			strokeCap: "round",
+			aria: false
+		},
+		encoding: {
+			[C]: categoryChannel,
+			[V]: valueChannel("value"),
+			[V2]: { datum: 0 },
+			stroke: hue,
+			...hoverOpacity
+		}
+	});
+	if (mark === "dumbbell") {
+		layers.push({
+			mark: {
+				type: "rule",
+				strokeWidth: CONNECTOR_WIDTH,
+				strokeCap: "round",
+				aria: false
+			},
+			encoding: {
+				[C]: categoryChannel,
+				[V]: valueChannel("value"),
+				[V2]: { field: "from" },
+				stroke: hue,
+				...hoverOpacity
+			}
+		});
+		layers.push({
+			mark: {
+				type: "point",
+				filled: true,
+				size: pointSize,
+				strokeWidth: 2,
+				aria: false
+			},
+			encoding: {
+				[C]: categoryChannel,
+				[V]: valueChannel("from"),
+				fill: { value: tokens.background },
+				stroke: hue,
+				...hoverOpacity
+			}
+		});
+	}
+	if (mark === "slope") {
+		const slopeBase = {
+			data: { name: COMPARISON_TABLE_DATASET },
+			transform: [
+				{
+					fold: SLOPE_FOLD,
+					as: ["end", "reading"]
+				},
+				{
+					calculate: "datum.end === 'from' ? 0 : 1",
+					as: "endIndex"
+				},
+				{ filter: "isValid(datum.reading)" }
+			]
+		};
+		const slopeCategory = {
+			field: "endIndex",
+			type: "ordinal",
+			sort: null,
+			scale: {
+				type: "point",
+				padding: .3
+			},
+			axis: {
+				title: null,
+				labelAngle: 0,
+				labelPadding: 6,
+				domain: false,
+				ticks: false,
+				grid: false,
+				labelExpr: `datum.value === 0 ? ${JSON.stringify(fromTitle)} : ${JSON.stringify(toTitle)}`,
+				aria: false
+			}
+		};
+		layers.push({
+			...slopeBase,
+			mark: {
+				type: "line",
+				strokeWidth: SLOPE_WIDTH,
+				aria: false
+			},
+			encoding: {
+				x: slopeCategory,
+				y: valueChannel("reading"),
+				detail: {
+					field: "key",
+					type: "nominal"
+				},
+				order: {
+					field: "endIndex",
+					type: "quantitative"
+				},
+				stroke: hue,
+				...hoverOpacity
+			}
+		});
+		layers.push({
+			...slopeBase,
+			...hoverParam,
+			mark: {
+				type: "point",
+				filled: true,
+				size: pointSize,
+				aria: false
+			},
+			encoding: {
+				x: slopeCategory,
+				y: valueChannel("reading"),
+				fill: hue,
+				...hoverOpacity,
+				...tooltip ? { tooltip: tooltipChannel } : {}
+			}
+		});
+	}
+	if (mark === "dot" || mark === "lollipop" || mark === "dumbbell") layers.push({
+		...hoverParam,
+		mark: {
+			type: "point",
+			filled: true,
+			size: pointSize,
+			aria: false
+		},
+		encoding: {
+			[C]: categoryChannel,
+			[V]: valueChannel("value"),
+			fill: hue,
+			...hoverOpacity,
+			...tooltip ? { tooltip: tooltipChannel } : {}
+		}
+	});
+	if (reference) layers.push({
+		data: { name: COMPARISON_REFERENCE_DATASET },
+		mark: {
+			type: "rule",
+			stroke: tokens.reference,
+			strokeWidth: 1.5,
+			strokeDash: [0, 4],
+			strokeCap: "round",
+			opacity: .9,
+			aria: false
+		},
+		encoding: {
+			[V]: valueChannel("value"),
+			...tooltip ? { tooltip: [valueTooltip("value", options.targetTitle ?? "Target")] } : {}
+		}
+	});
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 240,
+		height,
+		autosize: vertical ? {
+			type: "fit",
+			contains: "padding"
+		} : { type: "none" },
+		padding: 0,
+		background: "transparent",
+		data: { name: COMPARISON_TABLE_DATASET },
+		layer: layers,
+		config: arcVegaConfig(tokens, { locale })
+	};
+}
+//#endregion
+export { COMPARISON_HOVER_PARAM, COMPARISON_REFERENCE_DATASET, COMPARISON_TABLE_DATASET, COMPARISON_ZERO_DATASET, MAX_BAR_HEIGHT, buildComparisonPlotSpec, comparisonNeedsZero, comparisonOrientation, comparisonUsesFrom, resolveComparisonScale };

package/dist/components/ComparisonCard/ComparisonCard.d.ts

@@ -0,0 +1,200 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { ComparisonCardLabels, ComparisonCardSize, ComparisonCardStatus, ComparisonDeltaMode, ComparisonGoodDirection, ComparisonHeadline, ComparisonItem, ComparisonMark, ComparisonScale, ComparisonSort } from "./ComparisonCard.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/ComparisonCard/ComparisonCard.d.ts
+interface ComparisonCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** 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 things being compared — periods, segments, sources, plans — as
+   * `{ key?, label, value }` records in the order they should read (periods
+   * chronological, segments as the product lists them). `key` defaults to
+   * `label` and identifies an item for `focus` and `baseline`; `value: null`
+   * keeps the row with no bar. Pass `[]` while loading — `expectedItems` rows
+   * are reserved.
+   */
+  items: readonly ComparisonItem[];
+  /**
+   * Key of the subject, controlled: its bar takes the emphasis hue, its value
+   * is the `focus` headline, and the delta measures it against the baseline.
+   * Pair with `onFocusChange` to follow the reader's selection; omit it for
+   * the uncontrolled card (`defaultFocus`, else the first item). `null`
+   * designates none — every bar then takes the hue, there is no delta, the
+   * rows are not selectable, and a `focus` headline renders nothing.
+   */
+  focus?: string | null;
+  /** The subject on first render when `focus` is uncontrolled. Default: the first item. */
+  defaultFocus?: string | null;
+  /** Called with the selected row's key when the reader chooses another subject — by click, or with the arrow keys inside the rows. */
+  onFocusChange?: (key: string) => void;
+  /**
+   * Let the reader choose the subject and the reference: the rows become a
+   * radio group (click, or arrow keys once a row has focus), rank one selected
+   * by default, and the delta stack opens a compare-with menu to the right
+   * listing every other row. The headline, badge, hue, table and description
+   * follow both choices. A value the app controls without its change handler
+   * (`focus` without `onFocusChange`, `baseline` without `onBaselineChange`)
+   * is pinned and renders no control. Default `true`; `false` for a static
+   * tile. Stamped as `data-selectable`.
+   */
+  selectable?: boolean;
+  /**
+   * Key of the reference the focus is compared against, controlled — last
+   * month, the company average, the forecast. Pair with `onBaselineChange` to
+   * follow the reader's pick from the compare-with menu; omit it for the
+   * uncontrolled card (`defaultBaseline`, else the first item that is not the
+   * focus, so the leader is compared with the runner-up and every other row
+   * with the leader). A named baseline keeps its place until the reader
+   * selects it as the subject, then falls back to that rule. `null` draws the
+   * bars without a delta.
+   */
+  baseline?: string | null;
+  /** The reference on first render when `baseline` is uncontrolled. Default: the first item that is not the focus. */
+  defaultBaseline?: string;
+  /** Called with the chosen row's key when the reader picks another reference from the compare-with menu under the delta badge. */
+  onBaselineChange?: (key: string) => void;
+  /**
+   * What the big number is. `focus` (default) shows the focus item's value —
+   * the KPI-tile convention — with the delta badge beside it. `gap` shows the
+   * change of the focus against the baseline (in `deltaMode`) with the other
+   * form in the badge — for a variance card. `none` leaves the bars and the
+   * badge to carry the card. Stamped as `data-headline`.
+   */
+  headline?: ComparisonHeadline;
+  /**
+   * Name the subject in a chip under the headline value — a soft primary
+   * `Badge` with a swatch in the bar's hue, following the selection — so the
+   * number is never read without knowing whose it is. Default `true`; `false`
+   * when the card's title already names the subject. Not rendered with
+   * `headline="none"`.
+   */
+  focusChip?: boolean;
+  /** What the delta is against, under the badge. Default: `vs {baseline label}` (`labels.versus`), or `{focus} vs {baseline}` for a `gap` headline. */
+  comparisonLabel?: ReactNode;
+  /** `percent` (default) is relative change; `absolute` is the difference in the value's units — percentage points for a `percent` format. Also the form of every row's variance in the popover table and tooltip. */
+  deltaMode?: ComparisonDeltaMode;
+  /**
+   * Which direction is good for the focus item: `up` (revenue), `down`
+   * (churn, latency, cost) or `none` (headcount — the delta stays neutral).
+   * Drives the delta badge's polarity color. Default `up`.
+   */
+  goodDirection?: ComparisonGoodDirection;
+  /**
+   * Number format for the headline, rows, delta, 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 a `focus` headline in the muted role (`ms`, `req/s`). Prefer `format="currency:…"` for money. */
+  unit?: ReactNode;
+  /** A shared goal. Draws a dotted reference rule across every bar and adds a `vs target` column to the popover table; pass `null` while unknown. */
+  target?: number | null;
+  /**
+   * The form the plot draws — the channel the comparison rides, never a
+   * choice of variety. `bar` (default) and `column` put length on a zero
+   * baseline, `column` standing the bars up for two to five short-named
+   * items; `dot` drops the baseline so values clustered far from zero
+   * separate; `lollipop` keeps the baseline at a fraction of the ink;
+   * `dumbbell` and `slope` draw the two readings of each item (`value` and
+   * `from`) as a gap and as a path. `column` and `slope` run vertically, so
+   * the plot becomes a block above the rows instead of overlaying them.
+   * Stamped as `data-mark`.
+   */
+  mark?: ComparisonMark;
+  /**
+   * Whether the value scale includes zero. Ignored by `bar`, `column` and
+   * `lollipop`, where length carries the comparison and a cropped baseline
+   * would lie about the ratios. Default `auto` for the position marks
+   * (`dot`, `dumbbell`, `slope`), which is what lets NPS 40 and 47 read as
+   * different; pass `zero` when the distance from nothing is the point.
+   * Stamped as `data-scale`.
+   */
+  scale?: ComparisonScale;
+  /** Name of the earlier reading a `dumbbell` or a `slope` draws — the slope's left axis label and both marks' tooltip row. Default `labels.from` ("Before"). */
+  fromLabel?: string;
+  /** Name of the current reading a `dumbbell` or a `slope` draws — the slope's right axis label and both marks' tooltip row. Default `labels.to` ("After"). */
+  toLabel?: string;
+  /** Row order: `none` (default) keeps the consumer's order — periods stay chronological — while `desc` and `asc` rank by value with missing values last. The focus keeps its hue wherever it lands. */
+  sort?: ComparisonSort;
+  /**
+   * Fold every item past this count (after sorting) into one `Other` row
+   * whose value is the sum of the folded values — for additive measures
+   * (counts, revenue), never for rates or averages. The focus and the
+   * baseline are never folded. Default: no fold.
+   */
+  maxItems?: number;
+  /** Rows the skeleton reserves before `items` arrive, so the tile is already its final height. Default 2. */
+  expectedItems?: number;
+  /** The takeaway in a sentence, rendered beside the AI mark under the rows. Wrap values in `<strong>` to set them in bold. */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with items already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: ComparisonCardStatus;
+  /** The consumer's filter is active — no values 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 comparison. Scales type, padding, the row height (24 / 28 / 32px) and the bar thickness. */
+  size?: ComparisonCardSize;
+  /** 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 the as-of date. Defaults to the runtime's — pass it for deterministic output. */
+  timeZone?: string;
+  /** Overrides for every rendered or announced string. */
+  labels?: Partial<ComparisonCardLabels>;
+  /** 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 bars mount — for `view` access in advanced compositions. */
+  onEmbed?: (result: Result) => void;
+  /** Escape hatch: transform the bars' spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+/**
+ * A comparison tile for dashboard grids — the second subtype of the KPI card
+ * family beside `MetricCard`: one metric across a few items (periods,
+ * segments, sources, plans) on one shared scale, with every name and value as
+ * text beside the plot, the focus item in the emphasis hue, its delta against
+ * a baseline in a polarity badge, an optional target rule, and every loading,
+ * empty, error and stale state — layout-stable inside one `Box` frame, with a
+ * generated text equivalent and a data table in an info popover.
+ *
+ * `mark` picks the form the data calls for: `bar` (default), `column` and
+ * `lollipop` put length on a zero baseline; `dot` drops the baseline so
+ * values clustered far from zero separate; `dumbbell` and `slope` read a
+ * second reading per item (`ComparisonItem.from`) and draw the gap and the
+ * move between the two.
+ */
+declare const ComparisonCard: import("react").ForwardRefExoticComponent<ComparisonCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { ComparisonCard, ComparisonCardProps };