@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,309 @@
+import { ArcDeltaDirection, ArcDeltaMode } from "../../lib/vega/formatters.js";
+//#region src/components/ComparisonCard/ComparisonCard.model.d.ts
+/** What the consumer's transport reports. */
+type ComparisonCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the items and
+ * `filtered`. Stamped on the root as `data-state`.
+ */
+type ComparisonCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "error";
+/** Which way is good for the focus item: revenue up, churn down, headcount neutral. */
+type ComparisonGoodDirection = "up" | "down" | "none";
+/** How the focus-vs-baseline delta reads once `goodDirection` is applied. Stamped as `data-polarity`. */
+type ComparisonPolarity = "positive" | "negative" | "neutral";
+type ComparisonDeltaMode = ArcDeltaMode;
+/** Row order: the consumer's order (periods stay chronological) or ranked by value. */
+type ComparisonSort = "none" | "asc" | "desc";
+/**
+ * The form the plot draws. Every one answers the same question — how does
+ * this metric compare across these items — with a different channel, so the
+ * choice is about the data, never about variety (Few's pitfall #6):
+ *
+ * - `bar` (default): length from zero along a row. The safe form, and the one
+ *   a reader compares fastest when the values span their own magnitude.
+ * - `column`: the same length, stood up. For two to five items with short
+ *   names — periods above all, where left-to-right IS the reading order.
+ * - `dot`: position alone, free to crop. When the values cluster far from
+ *   zero (NPS 40 against 47) and bars would be seven identical slabs.
+ * - `lollipop`: a dot on a stem from zero. A bar's honesty at a fraction of
+ *   its ink, so a dense card carries more rows without a wall of color.
+ * - `dumbbell`: two readings per item joined by the gap between them — the
+ *   change is a length, not arithmetic the reader does in their head.
+ * - `slope`: the same two readings as a path across two positions, so a
+ *   crossing line says the ranking changed (Tufte's slopegraph).
+ *
+ * `dumbbell` and `slope` read `ComparisonItem.from`; the rest ignore it.
+ * Stamped as `data-mark`.
+ */
+type ComparisonMark = "bar" | "column" | "dot" | "lollipop" | "dumbbell" | "slope";
+/**
+ * Whether the value scale includes zero. `zero` is the honest floor wherever
+ * LENGTH carries the comparison, so `bar`, `column` and `lollipop` take it
+ * whatever this says; `auto` lets a position mark (`dot`, `dumbbell`,
+ * `slope`) crop to its own range, which is the only way values clustered far
+ * from zero separate at tile width. Stamped as `data-scale`.
+ */
+type ComparisonScale = "auto" | "zero";
+/** What the big number is: the focus item's value, the gap between focus and baseline, or nothing. Stamped as `data-headline`. */
+type ComparisonHeadline = "focus" | "gap" | "none";
+type ComparisonCardSize = "sm" | "md" | "lg";
+/** A row's part in the comparison — the subject, the reference, another item, or the fold of the long tail. */
+type ComparisonRole = "focus" | "baseline" | "item" | "other";
+/**
+ * One thing being compared — a period, a segment, a source, a plan. `key`
+ * identifies it for `focus` and `baseline` (defaults to `label`); `value` is
+ * the reading, or `null` when this item has none (its row stays, with no bar).
+ */
+interface ComparisonItem {
+  key?: string;
+  label: string;
+  value: number | null;
+  /**
+   * The item's OTHER reading — where it started, what it was last period,
+   * what was planned. Read only by `mark="dumbbell"` and `mark="slope"`,
+   * which draw the pair and the gap between them; every other mark ignores
+   * it, and the popover table shows it whenever it is present. `null` when
+   * this item has no earlier reading — the pair collapses to the single
+   * `value` mark rather than drawing a gap to nowhere.
+   */
+  from?: number | null;
+}
+/** An item after normalisation, in display order, with its role resolved. */
+interface ComparisonRow {
+  key: string;
+  label: string;
+  value: number | null;
+  /** The item's earlier reading, or `null`. Only `dumbbell` and `slope` plot it. */
+  from: number | null;
+  role: ComparisonRole;
+}
+interface ComparisonSummary {
+  rows: ComparisonRow[];
+  /** Rows with a finite value. */
+  count: number;
+  focus: ComparisonRow | null;
+  baseline: ComparisonRow | null;
+  /** The highest and lowest finite rows — what the chart description names. */
+  max: ComparisonRow | null;
+  min: ComparisonRow | null;
+  /** Any finite value below zero — the plot then draws a zero rule. */
+  hasNegative: boolean;
+  /** At least one row carries an earlier reading, so the two-value marks and the table's `from` column have something to draw. */
+  hasFrom: boolean;
+  /** Items folded into the "Other" row; 0 when nothing was folded. */
+  folded: number;
+}
+interface ComparisonDelta {
+  direction: ArcDeltaDirection;
+  polarity: ComparisonPolarity;
+  /** Signed, formatted change of the focus against the baseline: `+24.9%`, `-0.3 pp`, `+฿424K`. */
+  text: string;
+  renderedMode: ArcDeltaMode;
+  /**
+   * The same change in the other form — the amount when `text` is a percent,
+   * the relative change when `text` is an amount. `null` when the other form
+   * does not exist (a zero baseline has no percent).
+   */
+  secondaryText: string | null;
+}
+/** What the delta tooltip explains: the two readings behind the badge and the change between them in both forms. */
+interface ComparisonDeltaExplanation {
+  focusLabel: string;
+  focusText: string;
+  baselineLabel: string;
+  baselineText: string;
+  changeText: string;
+  secondaryText: string | null;
+  renderedMode: ArcDeltaMode;
+  direction: ArcDeltaDirection;
+}
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface ComparisonCardLabels {
+  /** Comparison line under the delta badge when `comparisonLabel` is omitted — `vs Retail`. */
+  versus: (baseline: string) => string;
+  /** Comparison line of a `gap` headline — `Online vs Retail`. */
+  gapComparison: (focus: string, baseline: string) => string;
+  increase: string;
+  decrease: string;
+  unchanged: string;
+  /** Suffix for a percentage-point delta. */
+  percentagePoints: string;
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  /** Shown in place of the delta when the focus or the baseline has no value. */
+  insufficient: string;
+  stale: string;
+  asOf: string;
+  tableItem: string;
+  tableValue: string;
+  /** Default names of the two readings a `dumbbell` or a `slope` compares, when `fromLabel` / `toLabel` are not passed. */
+  from: string;
+  to: string;
+  /** Header of the change column the two-value marks add to the popover table. */
+  tableChange: string;
+  /** How each mark names itself at the start of the plot's `aria-label` — `Bar comparison of Revenue by channel: …`. */
+  markNames: Record<ComparisonMark, string>;
+  /** Header of the per-row variance column — `vs Retail`. */
+  tableVersus: (baseline: string) => string;
+  tableVsTarget: string;
+  /** Label for the dotted target reference line in chart details. */
+  target: string;
+  /** Label of the row the long tail folds into. */
+  other: string;
+  /** Legend key for every bar that is not the focus. */
+  otherItems: string;
+  /** Read out after the focus row's label. */
+  highlighted: string;
+  showTable: (name: string) => string;
+  hideTable: (name: string) => string;
+  about: (name: string) => string;
+  loading: (name: string) => string;
+  tableCaption: (name: string) => string;
+  /** Accessible name of the delta group beside the value. */
+  deltaComparison: (name: string) => string;
+  /** Accessible name of the selectable rows (a radio group) — `Choose the item Revenue by channel focuses on`. */
+  focusGroup: (name: string) => string;
+  /** Accessible name of the delta stack when it opens the compare-with menu — `Choose what Revenue by channel is compared with`. */
+  chooseBaseline: (name: string) => string;
+  /** Heading of the compare-with menu's options column. */
+  compareWith: string;
+  /** Column headers of the compare-with menu's changes — the relative move and the amount in the value's units. */
+  changePercent: string;
+  changeAmount: string;
+  /** Compact label/value rows explaining the delta badge — by default the subject's reading and the change in both forms; the baseline's reading is available to add. */
+  deltaExplanation: (delta: ComparisonDeltaExplanation) => readonly (readonly [label: string, value: string])[];
+  /** The comparison sentence in the card description: `word` is the direction word, `primary` the unsigned change (empty when flat), `secondary` the other form or `null`. */
+  comparisonSentence: (input: {
+    word: string;
+    primary: string;
+    secondary: string | null;
+    baseline: string;
+    baselineValue: string;
+  }) => string;
+  /** Lists every row — `list` is `Online ฿2.1M, Retail ฿1.7M, …`. */
+  itemsSummary: (count: number, list: string) => string;
+  /** Appended when items were folded into Other. */
+  foldedSummary: (count: number) => string;
+  /** The plot's own `aria-label`. */
+  chartDescription: (input: {
+    /** The mark's own name from `markNames` — the plot says what form it is, because a screen reader cannot see it. */
+    mark: string;
+    name: string;
+    count: number;
+    top: string;
+    topValue: string;
+    bottom: string;
+    bottomValue: string;
+    focus: string | null;
+    target: string | null;
+    /** The two readings a `dumbbell` or a `slope` spans; `null` for the single-value marks. */
+    span: {
+      from: string;
+      to: string;
+    } | null;
+  }) => string;
+  /** Accessible name of the AI mark beside the insight sentence. */
+  insightMark: string;
+}
+declare const DEFAULT_COMPARISON_LABELS: ComparisonCardLabels;
+declare function resolveComparisonLabels(overrides?: Partial<ComparisonCardLabels>): ComparisonCardLabels;
+interface DeriveComparisonStateInput {
+  status: ComparisonCardStatus;
+  /** At least one item has a finite value. */
+  hasValue: boolean;
+  /** Anything is on screen already — any item at all — so a reload is a refresh, not a first load. */
+  hasData: boolean;
+  filtered: boolean;
+}
+/**
+ * The state machine. Error wins; loading over existing items 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.
+ */
+declare function deriveComparisonState({ status, hasValue, hasData, filtered }: DeriveComparisonStateInput): ComparisonCardState;
+/** The key of the row the long tail folds into. Never collides with a consumer key that is a label. */
+declare const COMPARISON_OTHER_KEY = "__other__";
+interface NormalizeItemsOptions {
+  /** Key of the subject. `undefined` takes the first item; `null` designates none. */
+  focus?: string | null;
+  /** Key of the reference. `undefined` — or the focus itself — takes the first item that is not the focus; `null` designates none. */
+  baseline?: string | null;
+  sort?: ComparisonSort;
+  /** Fold every item past this count (after sorting) into one `Other` row; the focus and the baseline are never folded. */
+  maxItems?: number;
+  otherLabel: string;
+}
+/**
+ * Normalises `items` for the plot, the rows and the table: keys default to
+ * labels (a repeated key is suffixed so two rows never share a band), the
+ * focus and the baseline are resolved in the consumer's order before any
+ * sorting (so "first and second" mean what the consumer sees), non-finite
+ * values become `null`, the rows are sorted if asked, and the long tail past
+ * `maxItems` folds into one `Other` row whose value is the sum of the folded
+ * finite values — honest only for additive measures, which the consumer
+ * decides by passing `maxItems` at all. Returns `null` when there are no
+ * items to speak of.
+ */
+declare function normalizeItems(items: readonly ComparisonItem[] | undefined, { focus, baseline, sort, maxItems, otherLabel }: NormalizeItemsOptions): ComparisonSummary | null;
+interface DeriveComparisonDeltaOptions {
+  deltaMode: ComparisonDeltaMode;
+  goodDirection: ComparisonGoodDirection;
+  format: string;
+  locale?: string;
+  percentagePoints: string;
+}
+/** The focus against the baseline, with polarity resolved through `goodDirection`. `null` unless both have a finite value. */
+declare function deriveComparisonDelta(focus: ComparisonRow | null | undefined, baseline: ComparisonRow | null | undefined, { deltaMode, goodDirection, format, locale, percentagePoints }: DeriveComparisonDeltaOptions): ComparisonDelta | null;
+interface ComparisonTextFormatters {
+  formatValue: (value: number | null | undefined) => string;
+  /** A row's signed variance against a reference value (the baseline or the target) in the card's `deltaMode`; `MISSING_VALUE` without two finite readings. */
+  formatVariance: (value: number | null | undefined, reference: number | null | undefined) => string;
+}
+/** The formatters every text surface shares — headline, rows, delta, table, tooltip, descriptions. */
+declare function createComparisonFormatters({ format, locale, formatValue, deltaMode, percentagePoints }: {
+  format: string;
+  locale?: string;
+  formatValue?: (value: number) => string;
+  /** The form of every row's variance — the badge's own `deltaMode`, so the table and the badge never disagree. */
+  deltaMode?: ComparisonDeltaMode;
+  percentagePoints?: string;
+}): ComparisonTextFormatters;
+interface BuildComparisonDescriptionInput {
+  name: string;
+  state: ComparisonCardState;
+  headline: ComparisonHeadline;
+  summary: ComparisonSummary | null;
+  delta: ComparisonDelta | null;
+  formatters: ComparisonTextFormatters;
+  /** The formatted target, when a reference line is drawn. */
+  targetText?: string | null;
+  asOfText?: string;
+  labels: ComparisonCardLabels;
+}
+/**
+ * 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, and the summary a screen reader gets before the parts. Every
+ * row is listed, so nothing lives only in the bars.
+ */
+declare function buildComparisonDescription({ name, state, headline, summary, delta, formatters, targetText, asOfText, labels }: BuildComparisonDescriptionInput): string;
+/** The plot's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+declare function buildComparisonChartDescription({ mark, name, summary, formatters, targetText, span, labels }: {
+  /** The form the plot draws — named in the label, because a screen reader cannot see it. */
+  mark: ComparisonMark;
+  name: string;
+  summary: ComparisonSummary;
+  formatters: ComparisonTextFormatters;
+  targetText?: string | null;
+  /** The two end names of a `dumbbell` or a `slope`; omit for the single-value marks. */
+  span?: {
+    from: string;
+    to: string;
+  } | null;
+  labels: ComparisonCardLabels;
+}): string;
+//#endregion
+export { BuildComparisonDescriptionInput, COMPARISON_OTHER_KEY, ComparisonCardLabels, ComparisonCardSize, ComparisonCardState, ComparisonCardStatus, ComparisonDelta, ComparisonDeltaExplanation, ComparisonDeltaMode, ComparisonGoodDirection, ComparisonHeadline, ComparisonItem, ComparisonMark, ComparisonPolarity, ComparisonRole, ComparisonRow, ComparisonScale, ComparisonSort, ComparisonSummary, ComparisonTextFormatters, DEFAULT_COMPARISON_LABELS, DeriveComparisonDeltaOptions, DeriveComparisonStateInput, NormalizeItemsOptions, buildComparisonChartDescription, buildComparisonDescription, createComparisonFormatters, deriveComparisonDelta, deriveComparisonState, normalizeItems, resolveComparisonLabels };

package/dist/components/ComparisonCard/ComparisonCard.model.js

@@ -0,0 +1,263 @@
+import { formatDelta, formatNumber } from "../../lib/vega/formatters.js";
+//#region src/components/ComparisonCard/ComparisonCard.model.ts
+const DEFAULT_COMPARISON_LABELS = {
+	versus: (baseline) => `vs ${baseline}`,
+	gapComparison: (focus, baseline) => `${focus} vs ${baseline}`,
+	increase: "Up",
+	decrease: "Down",
+	unchanged: "No change",
+	percentagePoints: " pp",
+	noData: "No data",
+	noMatch: "No matching data",
+	clearFilters: "Clear filters",
+	error: "Couldn't load this comparison",
+	retry: "Try again",
+	insufficient: "Not enough data to compare",
+	stale: "Stale",
+	asOf: "As of",
+	tableItem: "Item",
+	tableValue: "Value",
+	from: "Before",
+	to: "After",
+	tableChange: "Change",
+	markNames: {
+		bar: "Bar",
+		column: "Column",
+		dot: "Dot",
+		lollipop: "Lollipop",
+		dumbbell: "Dumbbell",
+		slope: "Slope"
+	},
+	tableVersus: (baseline) => `vs ${baseline}`,
+	tableVsTarget: "vs target",
+	target: "Target",
+	other: "Other",
+	otherItems: "Other items",
+	highlighted: "highlighted",
+	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} comparison`,
+	deltaComparison: (name) => `${name} comparison`,
+	focusGroup: (name) => `Choose the item ${name} focuses on`,
+	chooseBaseline: (name) => `Choose what ${name} is compared with`,
+	compareWith: "Compare with",
+	changePercent: "Change %",
+	changeAmount: "Change",
+	deltaExplanation: ({ focusLabel, focusText, changeText, secondaryText, renderedMode, direction }) => {
+		const rows = [[focusLabel, focusText], [direction === "up" ? "Increase" : direction === "down" ? "Decrease" : "No change", changeText]];
+		if (secondaryText) rows.push([renderedMode === "percent" ? "Change" : "Change %", secondaryText]);
+		return rows;
+	},
+	comparisonSentence: ({ word, primary, secondary, baseline, baselineValue }) => primary ? `${word} ${primary}${secondary ? ` (${secondary})` : ""} vs ${baseline} (${baselineValue}).` : `${word} vs ${baseline} (${baselineValue}).`,
+	itemsSummary: (count, list) => `Comparison of ${count} ${count === 1 ? "item" : "items"}: ${list}.`,
+	foldedSummary: (count) => `${count} more folded into Other.`,
+	chartDescription: ({ mark, name, count, top, topValue, bottom, bottomValue, focus, target, span }) => {
+		return `${mark} comparison of ${name}: ${count === 1 || top === bottom ? `${count} ${count === 1 ? "item" : "items"}, ${top} ${topValue}.` : `${count} items, highest ${top} ${topValue}, lowest ${bottom} ${bottomValue}.`}` + (span ? ` Each item spans ${span.from} to ${span.to}.` : "") + (focus ? ` ${focus} highlighted.` : "") + (target ? ` Reference line at the ${target} target.` : "");
+	},
+	insightMark: "Insight"
+};
+function resolveComparisonLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_COMPARISON_LABELS,
+		...overrides
+	} : DEFAULT_COMPARISON_LABELS;
+}
+/**
+* The state machine. Error wins; loading over existing items 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 deriveComparisonState({ 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);
+/** The key of the row the long tail folds into. Never collides with a consumer key that is a label. */
+const COMPARISON_OTHER_KEY = "__other__";
+/**
+* Normalises `items` for the plot, the rows and the table: keys default to
+* labels (a repeated key is suffixed so two rows never share a band), the
+* focus and the baseline are resolved in the consumer's order before any
+* sorting (so "first and second" mean what the consumer sees), non-finite
+* values become `null`, the rows are sorted if asked, and the long tail past
+* `maxItems` folds into one `Other` row whose value is the sum of the folded
+* finite values — honest only for additive measures, which the consumer
+* decides by passing `maxItems` at all. Returns `null` when there are no
+* items to speak of.
+*/
+function normalizeItems(items, { focus, baseline, sort = "none", maxItems, otherLabel }) {
+	if (!items) return null;
+	const seen = /* @__PURE__ */ new Map();
+	let rows = items.map((item) => {
+		const base = item.key ?? item.label;
+		const repeats = seen.get(base) ?? 0;
+		seen.set(base, repeats + 1);
+		return {
+			key: repeats === 0 ? base : `${base}·${repeats + 1}`,
+			label: item.label,
+			value: isFinite(item.value) ? item.value : null,
+			from: isFinite(item.from) ? item.from : null,
+			role: "item"
+		};
+	});
+	const has = (key) => key != null && rows.some((row) => row.key === key);
+	const focusKey = focus === null ? null : focus === void 0 ? rows[0]?.key ?? null : has(focus) ? focus : null;
+	const firstOther = focusKey == null ? null : rows.find((row) => row.key !== focusKey)?.key ?? null;
+	const baselineKey = focusKey == null || baseline === null ? null : baseline === void 0 || baseline === focusKey ? firstOther : has(baseline) ? baseline : null;
+	if (sort !== "none") {
+		const direction = sort === "asc" ? 1 : -1;
+		rows = rows.map((row, index) => ({
+			row,
+			index
+		})).sort((a, b) => {
+			const av = a.row.value;
+			const bv = b.row.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(({ row }) => row);
+	}
+	let folded = 0;
+	if (maxItems != null && maxItems >= 1 && rows.length > maxItems) {
+		const keepCount = Math.max(0, maxItems - 1);
+		const kept = [];
+		const rest = [];
+		rows.forEach((row, index) => {
+			if (index < keepCount || row.key === focusKey || row.key === baselineKey) kept.push(row);
+			else rest.push(row);
+		});
+		if (rest.length >= 2) {
+			const finite = rest.filter((row) => row.value != null);
+			const sum = finite.length > 0 ? finite.reduce((total, row) => total + row.value, 0) : null;
+			const fromRows = rest.filter((row) => row.from != null);
+			const fromSum = rest.length > 0 && fromRows.length === rest.length ? fromRows.reduce((total, row) => total + row.from, 0) : null;
+			rows = [...kept, {
+				key: COMPARISON_OTHER_KEY,
+				label: otherLabel,
+				value: sum,
+				from: fromSum,
+				role: "other"
+			}];
+			folded = rest.length;
+		} else rows = [...kept, ...rest];
+	}
+	rows = rows.map((row) => ({
+		...row,
+		role: row.role === "other" ? "other" : row.key === focusKey ? "focus" : row.key === baselineKey ? "baseline" : "item"
+	}));
+	const finiteRows = rows.filter((row) => row.value != null);
+	let max = null;
+	let min = null;
+	for (const row of finiteRows) {
+		if (!max || row.value > max.value) max = row;
+		if (!min || row.value < min.value) min = row;
+	}
+	return {
+		rows,
+		count: finiteRows.length,
+		focus: rows.find((row) => row.role === "focus") ?? null,
+		baseline: rows.find((row) => row.role === "baseline") ?? null,
+		max,
+		min,
+		hasNegative: finiteRows.some((row) => row.value < 0) || rows.some((row) => row.from != null && row.from < 0),
+		hasFrom: rows.some((row) => row.from != null),
+		folded
+	};
+}
+/** The focus against the baseline, with polarity resolved through `goodDirection`. `null` unless both have a finite value. */
+function deriveComparisonDelta(focus, baseline, { deltaMode, goodDirection, format, locale, percentagePoints }) {
+	if (!focus || !baseline || !isFinite(focus.value) || !isFinite(baseline.value)) return null;
+	const delta = formatDelta(focus.value, baseline.value, {
+		mode: deltaMode,
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	const other = formatDelta(focus.value, baseline.value, {
+		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 createComparisonFormatters({ format, locale, formatValue, deltaMode = "percent", percentagePoints = DEFAULT_COMPARISON_LABELS.percentagePoints }) {
+	return {
+		formatValue: (value) => isFinite(value) ? formatValue ? formatValue(value) : formatNumber(value, format, locale) : "—",
+		formatVariance: (value, reference) => isFinite(value) && isFinite(reference) ? formatDelta(value, reference, {
+			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, and the summary a screen reader gets before the parts. Every
+* row is listed, so nothing lives only in the bars.
+*/
+function buildComparisonDescription({ name, state, headline, summary, delta, formatters, targetText, 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 focus = summary?.focus ?? null;
+	const baseline = summary?.baseline ?? null;
+	const sentences = [];
+	if (headline === "focus" && focus) sentences.push(`${name}: ${focus.label} ${formatters.formatValue(focus.value)}.`);
+	else if (headline === "gap" && focus && baseline) sentences.push(`${name}: ${labels.gapComparison(focus.label, baseline.label)}.`);
+	else sentences.push(`${name}.`);
+	if (delta && baseline) {
+		const word = delta.direction === "up" ? labels.increase : delta.direction === "down" ? labels.decrease : labels.unchanged;
+		const flat = delta.direction === "flat";
+		sentences.push(labels.comparisonSentence({
+			word,
+			primary: flat ? "" : stripSign(delta.text),
+			secondary: flat || !delta.secondaryText ? null : stripSign(delta.secondaryText),
+			baseline: baseline.label,
+			baselineValue: formatters.formatValue(baseline.value)
+		}));
+	}
+	if (summary && summary.rows.length > 0) {
+		const list = summary.rows.map((row) => `${row.label} ${formatters.formatValue(row.value)}`).join(", ");
+		sentences.push(labels.itemsSummary(summary.rows.length, list));
+		if (summary.folded > 0) sentences.push(labels.foldedSummary(summary.folded));
+	}
+	if (targetText) sentences.push(`${labels.target} ${targetText}.`);
+	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 buildComparisonChartDescription({ mark, name, summary, formatters, targetText, span, labels }) {
+	return labels.chartDescription({
+		mark: labels.markNames[mark],
+		name,
+		count: summary.count,
+		top: summary.max?.label ?? "—",
+		topValue: formatters.formatValue(summary.max?.value),
+		bottom: summary.min?.label ?? "—",
+		bottomValue: formatters.formatValue(summary.min?.value),
+		focus: summary.focus?.label ?? null,
+		target: targetText ?? null,
+		span: span ?? null
+	});
+}
+//#endregion
+export { COMPARISON_OTHER_KEY, DEFAULT_COMPARISON_LABELS, buildComparisonChartDescription, buildComparisonDescription, createComparisonFormatters, deriveComparisonDelta, deriveComparisonState, normalizeItems, resolveComparisonLabels };

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

@@ -0,0 +1,4 @@
+import { BuildComparisonDescriptionInput, COMPARISON_OTHER_KEY, ComparisonCardLabels, ComparisonCardSize, ComparisonCardState, ComparisonCardStatus, ComparisonDelta, ComparisonDeltaExplanation, ComparisonDeltaMode, ComparisonGoodDirection, ComparisonHeadline, ComparisonItem, ComparisonMark, ComparisonPolarity, ComparisonRole, ComparisonRow, ComparisonScale, ComparisonSort, ComparisonSummary, ComparisonTextFormatters, DEFAULT_COMPARISON_LABELS, DeriveComparisonDeltaOptions, DeriveComparisonStateInput, NormalizeItemsOptions, buildComparisonChartDescription, buildComparisonDescription, createComparisonFormatters, deriveComparisonDelta, deriveComparisonState, normalizeItems, resolveComparisonLabels } from "./ComparisonCard.model.js";
+import { ComparisonCard, ComparisonCardProps } from "./ComparisonCard.js";
+import { COMPARISON_HOVER_PARAM, COMPARISON_REFERENCE_DATASET, COMPARISON_TABLE_DATASET, COMPARISON_ZERO_DATASET, ComparisonPlotSpecOptions, MAX_BAR_HEIGHT, buildComparisonPlotSpec, comparisonNeedsZero, comparisonOrientation, comparisonUsesFrom, resolveComparisonScale } from "./ComparisonCard.chart.js";
+export { type BuildComparisonDescriptionInput, COMPARISON_HOVER_PARAM, COMPARISON_OTHER_KEY, COMPARISON_REFERENCE_DATASET, COMPARISON_TABLE_DATASET, COMPARISON_ZERO_DATASET, ComparisonCard, type ComparisonCardLabels, type ComparisonCardProps, type ComparisonCardSize, type ComparisonCardState, type ComparisonCardStatus, type ComparisonDelta, type ComparisonDeltaExplanation, type ComparisonDeltaMode, type ComparisonGoodDirection, type ComparisonHeadline, type ComparisonItem, type ComparisonMark, type ComparisonPlotSpecOptions, type ComparisonPolarity, type ComparisonRole, type ComparisonRow, type ComparisonScale, type ComparisonSort, type ComparisonSummary, type ComparisonTextFormatters, DEFAULT_COMPARISON_LABELS, type DeriveComparisonDeltaOptions, type DeriveComparisonStateInput, MAX_BAR_HEIGHT, type NormalizeItemsOptions, buildComparisonChartDescription, buildComparisonDescription, buildComparisonPlotSpec, comparisonNeedsZero, comparisonOrientation, comparisonUsesFrom, createComparisonFormatters, deriveComparisonDelta, deriveComparisonState, normalizeItems, resolveComparisonLabels, resolveComparisonScale };

package/dist/components/ComparisonCard/index.js

@@ -0,0 +1,4 @@
+import { COMPARISON_HOVER_PARAM, COMPARISON_REFERENCE_DATASET, COMPARISON_TABLE_DATASET, COMPARISON_ZERO_DATASET, MAX_BAR_HEIGHT, buildComparisonPlotSpec, comparisonNeedsZero, comparisonOrientation, comparisonUsesFrom, resolveComparisonScale } from "./ComparisonCard.chart.js";
+import { COMPARISON_OTHER_KEY, DEFAULT_COMPARISON_LABELS, buildComparisonChartDescription, buildComparisonDescription, createComparisonFormatters, deriveComparisonDelta, deriveComparisonState, normalizeItems, resolveComparisonLabels } from "./ComparisonCard.model.js";
+import { ComparisonCard } from "./ComparisonCard.js";
+export { COMPARISON_HOVER_PARAM, COMPARISON_OTHER_KEY, COMPARISON_REFERENCE_DATASET, COMPARISON_TABLE_DATASET, COMPARISON_ZERO_DATASET, ComparisonCard, DEFAULT_COMPARISON_LABELS, MAX_BAR_HEIGHT, buildComparisonChartDescription, buildComparisonDescription, buildComparisonPlotSpec, comparisonNeedsZero, comparisonOrientation, comparisonUsesFrom, createComparisonFormatters, deriveComparisonDelta, deriveComparisonState, normalizeItems, resolveComparisonLabels, resolveComparisonScale };

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

@@ -0,0 +1,82 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { ForecastMark, ForecastScale, ForecastXType } from "./ForecastCard.model.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/ForecastCard/ForecastCard.chart.d.ts
+/** Every plotted period `{ x, y, lo, hi, k, c, n }`, measured then projected, with the anchor repeated. */
+declare const FORECAST_TABLE_DATASET = "table";
+/** The interval band `{ x, lo, hi }` — the anchor at zero width, then every projected period with bounds. */
+declare const FORECAST_INTERVAL_DATASET = "interval";
+/** One row per period, `{ x }` — the crosshair, filtered by the hover selection. */
+declare const FORECAST_PERIODS_DATASET = "periods";
+/** Zero or one row `{ start, end }` — the projected stretch: the wash, and the x axis's anchors. */
+declare const FORECAST_REGION_DATASET = "region";
+/** Zero or one row `{ x }` — the rule at the last measured period. */
+declare const FORECAST_BOUNDARY_DATASET = "boundary";
+/** Zero or one row `{ value }` — the target reference rule. */
+declare const FORECAST_REFERENCE_DATASET = "reference";
+/** Zero or one row `{ x, y, n, c }` — the landing dot and its direct label. */
+declare const FORECAST_LANDING_DATASET = "landing";
+/** The shared-x hover selection: projected onto `x`, so pointing anywhere in a column reads that period. */
+declare const FORECAST_HOVER_PARAM = "hover";
+/** Responsive x tick values, recomputed by Vega when the domain or the width changes. */
+declare const FORECAST_X_TICKS_PARAM = "forecast_x_ticks";
+/** The projected window's bounds, read from the `region` dataset — the x axis labels them. */
+declare const FORECAST_REGION_START_PARAM = "forecast_region_start";
+declare const FORECAST_REGION_END_PARAM = "forecast_region_end";
+interface ForecastPlotSpecOptions {
+  /** `line` reads shape; `area` fills the MEASURED half from zero. */
+  mark: ForecastMark;
+  /** `auto` lets a line crop to its data range; `zero` includes zero. An area always includes zero. */
+  scale: ForecastScale;
+  xType: ForecastXType;
+  /** 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 interval band (the `interval` dataset carries its rows). */
+  interval: boolean;
+  /** Wash the projected stretch and anchor the x axis on its bounds. */
+  region: boolean;
+  /** Draw the rule at the last measured period. */
+  boundary: boolean;
+  /** Draw the target reference rule. */
+  reference: boolean;
+  /** Dot the landing, and label it when `landingLabel` is true. */
+  landing: boolean;
+  /** Hang the landing's value in the right-hand gutter. */
+  landingLabel: boolean;
+  /** Wire the shared-x hover selection, the crosshair and the tooltip channel. */
+  tooltip: boolean;
+  /** Tooltip titles. */
+  xTitle: string;
+  yTitle: string;
+  kindTitle: string;
+  /** Localised title for the target reference rule's hover value. */
+  targetTitle?: string;
+  /** `arcNumber` grammar for the y axis and the tooltip. */
+  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: the measured readings as a solid path, the projection as the
+ * same path dashed, the prediction interval as a band that opens from the last
+ * reading, a wash and a rule marking where measurement stops, an optional
+ * target rule, a dotted landing, and the documented shared-x hover (a
+ * transparent `point` layer carrying a `nearest` selection projected onto `x`,
+ * with a crosshair rule read from the period dataset).
+ *
+ * Gaps stay gaps — a `null` reading breaks the path rather than dropping it to
+ * zero. An `area` keeps its zero baseline whatever `scale` says, because
+ * proportional ink is not negotiable; a line may crop, and since both axes are
+ * drawn the crop is always visible in the axis.
+ */
+declare function buildForecastPlotSpec(options: ForecastPlotSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { FORECAST_BOUNDARY_DATASET, FORECAST_HOVER_PARAM, FORECAST_INTERVAL_DATASET, FORECAST_LANDING_DATASET, FORECAST_PERIODS_DATASET, FORECAST_REFERENCE_DATASET, FORECAST_REGION_DATASET, FORECAST_REGION_END_PARAM, FORECAST_REGION_START_PARAM, FORECAST_TABLE_DATASET, FORECAST_X_TICKS_PARAM, ForecastPlotSpecOptions, buildForecastPlotSpec };