@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/TargetCard/TargetCard.model.js

@@ -0,0 +1,581 @@
+import { formatDate, formatDateRange, formatDelta, formatNumber } from "../../lib/vega/formatters.js";
+import { zonedMidnight, zonedParts } from "../../lib/vega/time.js";
+//#region src/components/TargetCard/TargetCard.model.ts
+const DEFAULT_TARGET_LABELS = {
+	ofTarget: "of target",
+	pairSeparator: "/",
+	readingLine: (value, target) => `${value} of ${target}`,
+	attainmentLine: (percent, target) => `${percent} of ${target}`,
+	target: "Target",
+	reached: "Reached",
+	remaining: "Remaining",
+	overBy: "Over by",
+	expectedByNow: "Expected by now",
+	aheadOfPace: (direction) => direction === "down" ? "under pace" : "ahead of pace",
+	behindPace: (direction) => direction === "down" ? "over pace" : "behind pace",
+	onPace: "on pace",
+	vsTarget: "vs target",
+	aboveTarget: "Above target",
+	belowTarget: "Below target",
+	onTarget: "On target",
+	projected: "Projected",
+	period: "Period",
+	week: (weekNumber) => `Week ${weekNumber}`,
+	quarter: (quarter, year) => `Q${quarter} ${year}`,
+	elapsed: (percent) => `${percent} elapsed`,
+	elapsedRow: "Elapsed",
+	daysRow: "Days elapsed",
+	days: (elapsed, total) => `${elapsed} of ${total}`,
+	trackNames: {
+		achieved: "Target met",
+		"on-track": "On track",
+		"at-risk": "At risk",
+		"off-track": "Off track",
+		missed: "Target missed"
+	},
+	trackRow: "Status",
+	increase: "Up",
+	decrease: "Down",
+	unchanged: "No change",
+	percentagePoints: " pp",
+	noData: "No data",
+	noMatch: "No matching data",
+	clearFilters: "Clear filters",
+	error: "Couldn't load this target",
+	retry: "Try again",
+	noTarget: "No target set",
+	stale: "Stale",
+	asOf: "As of",
+	tableItem: "Item",
+	tableValue: "Value",
+	changePercent: "Change %",
+	changeAmount: "Change",
+	markNames: {
+		actual: "Reached",
+		pace: "Pace",
+		target: "Target",
+		projection: "Projected"
+	},
+	showTable: (name) => `Show the details behind ${name}`,
+	hideTable: (name) => `Hide the details behind ${name}`,
+	about: (name) => `About ${name}`,
+	loading: (name) => `Loading ${name}`,
+	tableCaption: (name) => `Details of ${name} against its target`,
+	progressGroup: (name) => `${name} against its target`,
+	trackGroup: (name) => `${name} status`,
+	insightMark: "Insight",
+	explanation: ({ kind, direction, valueText, percentText, targetText, gapKind, gapText, expectedText, expectedPercentText, delta, paceStatus }) => {
+		const rows = [[DEFAULT_TARGET_LABELS.reached, `${valueText} (${percentText})`]];
+		if (kind === "pace" && expectedText) {
+			rows.push([DEFAULT_TARGET_LABELS.expectedByNow, expectedPercentText ? `${expectedText} (${expectedPercentText})` : expectedText]);
+			const word = paceStatus === "ahead" ? DEFAULT_TARGET_LABELS.aheadOfPace(direction) : paceStatus === "behind" ? DEFAULT_TARGET_LABELS.behindPace(direction) : DEFAULT_TARGET_LABELS.onPace;
+			rows.push([word.charAt(0).toUpperCase() + word.slice(1), delta.text]);
+		} else {
+			rows.push([DEFAULT_TARGET_LABELS.target, targetText]);
+			rows.push([gapKind === "over" ? DEFAULT_TARGET_LABELS.overBy : DEFAULT_TARGET_LABELS.remaining, gapText]);
+			rows.push([delta.direction === "up" ? DEFAULT_TARGET_LABELS.aboveTarget : delta.direction === "down" ? DEFAULT_TARGET_LABELS.belowTarget : DEFAULT_TARGET_LABELS.onTarget, delta.text]);
+		}
+		if (delta.secondaryText) rows.push([delta.renderedMode === "percent" ? DEFAULT_TARGET_LABELS.changeAmount : DEFAULT_TARGET_LABELS.changePercent, delta.secondaryText]);
+		return rows;
+	},
+	attainmentSentence: ({ name, percent, value, target }) => `${name}: ${percent} of target (${value} of ${target}).`,
+	gapSentence: ({ kind, amount }) => kind === "over" ? `Over by ${amount}.` : `Remaining ${amount}.`,
+	paceSentence: ({ word, primary, secondary, expectedPercent, elapsedPercent }) => {
+		const capitalised = word.charAt(0).toUpperCase() + word.slice(1);
+		const context = elapsedPercent ? `${expectedPercent} expected by now, ${elapsedPercent} of the period elapsed` : `${expectedPercent} expected by now`;
+		return primary ? `${capitalised} by ${primary}${secondary ? ` (${secondary})` : ""}: ${context}.` : `${capitalised}: ${context}.`;
+	},
+	projectionSentence: ({ value, percent }) => `Projected ${value} (${percent} of target).`,
+	periodSentence: ({ name, range }) => name === range ? `Period ${range}.` : `Period ${name} (${range}).`,
+	chartDescription: ({ name, value, percent, target, expected, expectedPercent, projected, projectedPercent }) => `Bullet graph of ${name}: reached ${value}, ${percent} of the ${target} target.` + (expected ? ` Pace marker at ${expected}${expectedPercent ? ` (${expectedPercent})` : ""}.` : "") + (projected ? ` Projected ${projected}${projectedPercent ? ` (${projectedPercent})` : ""}.` : "")
+};
+function resolveTargetLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_TARGET_LABELS,
+		...overrides
+	} : DEFAULT_TARGET_LABELS;
+}
+/**
+* The state machine. Error wins; loading over existing data is a refresh (the
+* previous render stays under the veil); a missing reading is `no-match` when
+* the consumer's filter caused it and `empty` otherwise. A reading without a
+* target is `ready` — the card then shows the reading and says no target is
+* set (`data-insufficient`).
+*/
+function deriveTargetState({ 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);
+const DAY_MS = 864e5;
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+function toInstant(value) {
+	return value instanceof Date ? value.getTime() : new Date(value).getTime();
+}
+/**
+* The period as instants in the card's time zone. A date-only bound is a
+* whole calendar day: `start` opens at its midnight and `end` closes at the
+* midnight after it, so `"2026-09-01"` – `"2026-09-30"` is all of September
+* (30 days, not 29). Any other form is the exact instant. `null` when a bound
+* cannot be parsed or the period has no length.
+*/
+function resolvePeriod(period, timeZone) {
+	if (!period) return null;
+	const resolve = (bound, inclusiveEnd) => {
+		if (typeof bound === "string") {
+			const match = DATE_ONLY.exec(bound);
+			if (match) {
+				const [, year, month, day] = match;
+				return zonedMidnight(Number(year), Number(month) - 1, Number(day) + (inclusiveEnd ? 1 : 0), timeZone);
+			}
+		}
+		const time = toInstant(bound);
+		return Number.isNaN(time) ? null : time;
+	};
+	const start = resolve(period.start, false);
+	const end = resolve(period.end, true);
+	if (start == null || end == null || end <= start) return null;
+	const dateOnly = typeof period.start === "string" && DATE_ONLY.test(period.start) && typeof period.end === "string" && DATE_ONLY.test(period.end);
+	return {
+		start,
+		end,
+		label: period.label,
+		dateOnly
+	};
+}
+/**
+* How far the period has run at `asOf`. The fraction is clamped for the
+* plan's expectation (nothing is expected before the start, everything by the
+* end); `rawFraction` keeps the overshoot so a reading after the end knows
+* the period is over. `null` when `asOf` is missing or unparseable.
+*/
+function deriveElapsed(bounds, asOf, locale) {
+	if (!bounds || asOf == null) return null;
+	const now = toInstant(asOf);
+	if (Number.isNaN(now)) return null;
+	const rawFraction = (now - bounds.start) / (bounds.end - bounds.start);
+	const fraction = Math.min(1, Math.max(0, rawFraction));
+	return {
+		fraction,
+		rawFraction,
+		started: rawFraction >= 0,
+		ended: rawFraction >= 1,
+		percentText: formatNumber(fraction, "percent:0", locale)
+	};
+}
+/** The whole days a date-only period spans. */
+function periodDays(bounds) {
+	return Math.round((bounds.end - bounds.start) / DAY_MS);
+}
+/**
+* The period counted in days — `18 of 30` on 19 September. Only for a period
+* whose bounds are whole calendar days: an intraday window has no honest day
+* count, and `null` keeps the row out of the table rather than rounding one
+* into existence. Counted between calendar dates in the card's zone, so a
+* daylight-saving change never shifts the count by a day.
+*/
+function deriveDays(bounds, asOf, timeZone) {
+	if (!bounds || !bounds.dateOnly || asOf == null) return null;
+	const now = toInstant(asOf);
+	if (Number.isNaN(now)) return null;
+	const total = periodDays(bounds);
+	const start = zonedParts(bounds.start, timeZone);
+	const current = zonedParts(now, timeZone);
+	const startDay = Date.UTC(start.year, start.month - 1, start.day);
+	const currentDay = Date.UTC(current.year, current.month - 1, current.day);
+	const elapsed = Math.round((currentDay - startDay) / DAY_MS);
+	return {
+		elapsed: Math.min(total, Math.max(0, elapsed)),
+		total
+	};
+}
+/** The formatters every text surface shares — headline, badge, plot tooltip, table, descriptions. */
+function createTargetFormatters({ format, locale, formatValue }) {
+	return {
+		formatValue: (value) => isFinite(value) ? formatValue ? formatValue(value) : formatNumber(value, format, locale) : "—",
+		formatPercent: (ratio) => isFinite(ratio) ? formatNumber(ratio, "percent:0", locale) : "—"
+	};
+}
+const NUMERIC_CORE = /^[\d.,'\s]+$/;
+/**
+* Joins a reading and its target into one compact pair — `฿2.6M` and `฿4M`
+* become `฿2.6/4M`, `187 ms` and `200 ms` become `187/200 ms`, `2.7%` and `3%`
+* become `2.7/3%` — by lifting out the symbol they both start with and the
+* magnitude they both end with. A leading sign stays on the reading
+* (`-฿120/500K`).
+*
+* Returns `null` whenever the two cannot share their parts — `฿850K` against
+* `฿4M` is not `฿850/4M`, and a locale or formatter this heuristic does not
+* recognise must not be guessed at — so the caller falls back to the full
+* `X of Y` line rather than printing something untrue.
+*/
+function formatValuePair(valueText, targetText, separator = "/") {
+	const sign = /^[-−+]/.exec(valueText)?.[0] ?? "";
+	const value = valueText.slice(sign.length);
+	if (!value || !targetText) return null;
+	const isDigit = (char) => char >= "0" && char <= "9";
+	let prefix = 0;
+	while (prefix < value.length && prefix < targetText.length && value[prefix] === targetText[prefix] && !isDigit(value[prefix])) prefix += 1;
+	let suffix = 0;
+	while (suffix < value.length - prefix && suffix < targetText.length - prefix && value[value.length - 1 - suffix] === targetText[targetText.length - 1 - suffix] && !isDigit(value[value.length - 1 - suffix])) suffix += 1;
+	const head = value.slice(0, prefix);
+	const tail = suffix > 0 ? value.slice(value.length - suffix) : "";
+	const valueCore = value.slice(prefix, value.length - suffix);
+	const targetCore = targetText.slice(prefix, targetText.length - suffix);
+	if (!NUMERIC_CORE.test(valueCore) || !NUMERIC_CORE.test(targetCore)) return null;
+	return `${sign}${head}${valueCore}${separator}${targetCore}${tail}`;
+}
+/** The reading against a reference (the target, or the plan's expectation), with polarity resolved through `goodDirection`. */
+function deriveTargetDelta(value, reference, { deltaMode, goodDirection, format, locale, percentagePoints }) {
+	const delta = formatDelta(value, reference, {
+		mode: deltaMode,
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	const other = formatDelta(value, reference, {
+		mode: delta.renderedMode === "percent" ? "absolute" : "percent",
+		format,
+		locale,
+		pointsSuffix: percentagePoints
+	});
+	let polarity = "neutral";
+	if (delta.direction !== "flat") 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
+	};
+}
+/**
+* Attainment, pace, projection and verdict — `null` without a finite reading
+* and a finite, non-zero target (a zero target has no ratio).
+*
+* Pace is `target × elapsed` unless the product supplies its own `expected`
+* (a seasonal plan curve); the projection is the linear run rate
+* `value / elapsed` unless the product supplies `projected` — both are
+* declared as such in `source`, and a run rate is only projected while the
+* period is still running with some of it elapsed. The verdict: an `up`
+* target is achieved the moment the reading reaches it and missed once the
+* period ends short of it; a `down` target is missed the moment the reading
+* exceeds it and achieved once the period ends within it. While the period
+* runs, the gap to the plan's expectation in points of the target decides
+* between on track, at risk (behind by no more than `tolerance`) and off
+* track. Without a period or an `expected` there is no pace and no verdict
+* short of achieved or missed.
+*/
+function deriveTargetProgress({ value, target, formatters, tolerance, elapsed, expected, projected, ...deltaOptions }) {
+	if (!isFinite(value) || !isFinite(target) || target === 0) return null;
+	const { goodDirection, locale, percentagePoints } = deltaOptions;
+	const ratio = value / target;
+	const good = (reading, reference) => goodDirection === "up" ? reading - reference : reference - reading;
+	const withinTarget = goodDirection === "up" ? value >= target : value <= target;
+	const gapKind = value > target ? "over" : "remaining";
+	const targetDelta = deriveTargetDelta(value, target, deltaOptions);
+	let pace = null;
+	const expectedValue = expected === null ? null : isFinite(expected) ? expected : elapsed ? target * elapsed.fraction : null;
+	if (expectedValue != null) {
+		const expectedRatio = expectedValue / target;
+		const delta = deriveTargetDelta(value, expectedValue, deltaOptions);
+		const points = formatDelta(ratio, expectedRatio, {
+			mode: "absolute",
+			format: "percent:1",
+			locale,
+			pointsSuffix: percentagePoints
+		});
+		const advantage = good(value, expectedValue);
+		pace = {
+			expected: expectedValue,
+			expectedRatio,
+			expectedText: formatters.formatValue(expectedValue),
+			expectedPercentText: formatters.formatPercent(expectedRatio),
+			delta,
+			pointsText: points.text,
+			status: advantage > 0 ? "ahead" : advantage < 0 ? "behind" : "on",
+			source: isFinite(expected) ? "explicit" : "linear"
+		};
+	}
+	let projection = null;
+	const projectedValue = projected === null ? null : isFinite(projected) ? projected : elapsed && elapsed.fraction > 0 && !elapsed.ended ? value / elapsed.fraction : null;
+	if (projectedValue != null) projection = {
+		value: projectedValue,
+		ratio: projectedValue / target,
+		text: formatters.formatValue(projectedValue),
+		percentText: formatters.formatPercent(projectedValue / target),
+		source: isFinite(projected) ? "explicit" : "linear",
+		extends: Math.sign(projectedValue) === Math.sign(value) && Math.abs(projectedValue) > Math.abs(value)
+	};
+	let track = null;
+	const ended = elapsed?.ended ?? false;
+	if (goodDirection === "up") {
+		if (value >= target) track = "achieved";
+		else if (ended) track = "missed";
+	} else if (value > target) track = "missed";
+	else if (ended) track = "achieved";
+	if (track == null && pace) {
+		const gap = good(ratio, pace.expectedRatio);
+		track = gap >= 0 ? "on-track" : gap >= -tolerance ? "at-risk" : "off-track";
+	}
+	const tone = track === "achieved" ? "positive" : track === "missed" ? "negative" : "primary";
+	const markers = [
+		0,
+		target,
+		value,
+		pace?.expected ?? 0,
+		projection?.value ?? 0
+	];
+	return {
+		value,
+		target,
+		ratio,
+		valueText: formatters.formatValue(value),
+		targetText: formatters.formatValue(target),
+		percentText: formatters.formatPercent(ratio),
+		withinTarget,
+		gapKind,
+		gapText: formatters.formatValue(Math.abs(target - value)),
+		targetDelta,
+		elapsed,
+		pace,
+		projection,
+		track,
+		tone,
+		bounds: {
+			min: Math.min(...markers),
+			max: Math.max(...markers)
+		}
+	};
+}
+/** The word the pace badge's comparison line and explanation use for the reading's standing against the plan. */
+function paceWord(pace, direction, labels) {
+	return pace.status === "ahead" ? labels.aheadOfPace(direction) : pace.status === "behind" ? labels.behindPace(direction) : labels.onPace;
+}
+/** The rows behind the badge: the reading against the plan's expectation when there is a pace, else against the target. */
+function buildTargetExplanation(progress, direction, labels) {
+	const { pace } = progress;
+	return labels.explanation({
+		kind: pace ? "pace" : "target",
+		direction,
+		valueText: progress.valueText,
+		percentText: progress.percentText,
+		targetText: progress.targetText,
+		gapKind: progress.gapKind,
+		gapText: progress.gapText,
+		expectedText: pace?.expectedText ?? null,
+		expectedPercentText: pace?.expectedPercentText ?? null,
+		delta: pace ? pace.delta : progress.targetDelta,
+		paceStatus: pace?.status ?? null
+	});
+}
+/**
+* Every value the card shows, as label/value rows: target, reading, the gap,
+* the plan's expectation and the pace against it, the elapsed share, the
+* projection, the period and the verdict — the popover's table, so nothing
+* lives only in the plot or on hover.
+*/
+function buildTargetDetailRows({ progress, direction, periodText, days, labels }) {
+	const rows = [
+		{
+			key: "target",
+			label: labels.target,
+			value: progress.targetText,
+			mark: "target"
+		},
+		{
+			key: "reached",
+			label: labels.reached,
+			value: `${progress.valueText} (${progress.percentText})`,
+			mark: "actual"
+		},
+		{
+			key: "gap",
+			label: progress.gapKind === "over" ? labels.overBy : labels.remaining,
+			value: progress.gapText
+		}
+	];
+	if (progress.pace) {
+		const word = paceWord(progress.pace, direction, labels);
+		rows.push({
+			key: "expected",
+			label: labels.expectedByNow,
+			value: `${progress.pace.expectedText} (${progress.pace.expectedPercentText})`,
+			mark: "pace"
+		}, {
+			key: "pace",
+			label: word.charAt(0).toUpperCase() + word.slice(1),
+			value: progress.pace.delta.secondaryText ? `${progress.pace.delta.text} (${progress.pace.delta.secondaryText})` : progress.pace.delta.text,
+			tone: progress.pace.delta.polarity
+		});
+	}
+	if (progress.projection) rows.push({
+		key: "projected",
+		label: labels.projected,
+		value: `${progress.projection.text} (${progress.projection.percentText})`,
+		mark: "projection"
+	});
+	if (periodText) rows.push({
+		key: "period",
+		label: labels.period,
+		value: periodText
+	});
+	if (progress.elapsed) rows.push({
+		key: "elapsed",
+		label: labels.elapsedRow,
+		value: progress.elapsed.percentText
+	});
+	if (days) rows.push({
+		key: "days",
+		label: labels.daysRow,
+		value: labels.days(days.elapsed, days.total)
+	});
+	if (progress.track) rows.push({
+		key: "track",
+		label: labels.trackRow,
+		value: labels.trackNames[progress.track]
+	});
+	return rows;
+}
+/** The ISO-8601 week number of a Gregorian date (weeks run Monday to Sunday; week 1 holds the first Thursday). */
+function isoWeekNumber(year, month, day) {
+	const date = new Date(Date.UTC(year, month - 1, day));
+	date.setUTCDate(date.getUTCDate() - (date.getUTCDay() + 6) % 7 + 3);
+	const firstThursday = new Date(Date.UTC(date.getUTCFullYear(), 0, 4));
+	firstThursday.setUTCDate(firstThursday.getUTCDate() - (firstThursday.getUTCDay() + 6) % 7 + 3);
+	return 1 + Math.round((date.getTime() - firstThursday.getTime()) / (7 * DAY_MS));
+}
+/**
+* Which calendar unit the bounds describe. A period qualifies only when it
+* opens on a zoned midnight and closes exactly one week, month, quarter or
+* year later in the same zone — so a DST weekend still measures seven days,
+* and a range that merely looks month-sized (`Sep 2` to `Oct 1`) stays
+* `custom` rather than being renamed after a month it is not.
+*/
+function describePeriodShape(bounds, timeZone) {
+	if (!bounds.dateOnly) return "custom";
+	const start = zonedParts(bounds.start, timeZone);
+	if (start.hour !== 0 || start.minute !== 0 || start.second !== 0) return "custom";
+	const closes = (years, months, days) => zonedMidnight(start.year + years, start.month - 1 + months, start.day + days, timeZone) === bounds.end;
+	if (start.day === 1) {
+		if (start.month === 1 && closes(1, 0, 0)) return "year";
+		if ((start.month - 1) % 3 === 0 && closes(0, 3, 0)) return "quarter";
+		if (closes(0, 1, 0)) return "month";
+	}
+	if (closes(0, 0, 7)) return "week";
+	return "custom";
+}
+/**
+* Names the period and spells out its bounds. The name is the consumer's
+* `label` when it gave one; otherwise the period's own shape supplies it
+* (`Week 32`, `Sep 2026`, `Q3 2026`, `2026`), and a shape the calendar has no
+* word for falls back to the range itself. Every part goes through `Intl` in
+* the card's locale and zone, so a Thai card on the Buddhist calendar reads
+* `ก.ย. 2569` while the arithmetic stays Gregorian.
+*/
+function formatPeriod(bounds, { locale, timeZone, labels = DEFAULT_TARGET_LABELS }) {
+	if (!bounds) return null;
+	const lastInstant = bounds.dateOnly ? bounds.end - DAY_MS / 2 : bounds.end;
+	const granularity = bounds.dateOnly ? "day" : "datetime";
+	const range = formatDateRange(bounds.start, lastInstant, {
+		granularity,
+		locale,
+		timeZone
+	});
+	const shape = describePeriodShape(bounds, timeZone);
+	let derived = range;
+	if (shape === "year") derived = formatDate(bounds.start, {
+		granularity: "year",
+		locale,
+		timeZone
+	});
+	else if (shape === "month") derived = formatDate(bounds.start, {
+		granularity: "month",
+		locale,
+		timeZone
+	});
+	else if (shape === "quarter") {
+		const start = zonedParts(bounds.start, timeZone);
+		derived = labels.quarter(Math.floor((start.month - 1) / 3) + 1, formatDate(bounds.start, {
+			granularity: "year",
+			locale,
+			timeZone
+		}));
+	} else if (shape === "week") {
+		const midweek = zonedParts(bounds.start + 3 * DAY_MS, timeZone);
+		derived = labels.week(isoWeekNumber(midweek.year, midweek.month, midweek.day), formatDate(bounds.start, {
+			granularity: "year",
+			locale,
+			timeZone
+		}));
+	}
+	return {
+		name: bounds.label ?? derived,
+		shape,
+		labelled: bounds.label != null,
+		range
+	};
+}
+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.
+*/
+function buildTargetDescription({ name, state, valueText, progress, direction, periodText, asOfText, labels }) {
+	if (state === "loading") return `${labels.loading(name)}.`;
+	if (state === "error") return `${name}: ${labels.error}.`;
+	if (state === "empty") return `${name}: ${labels.noData}.`;
+	if (state === "no-match") return `${name}: ${labels.noMatch}.`;
+	const sentences = [];
+	if (!progress) sentences.push(`${name}: ${valueText}.`, `${labels.noTarget}.`);
+	else {
+		sentences.push(labels.attainmentSentence({
+			name,
+			percent: progress.percentText,
+			value: progress.valueText,
+			target: progress.targetText
+		}), labels.gapSentence({
+			kind: progress.gapKind,
+			amount: progress.gapText
+		}));
+		if (progress.pace) {
+			const flat = progress.pace.delta.direction === "flat";
+			sentences.push(labels.paceSentence({
+				word: paceWord(progress.pace, direction, labels),
+				primary: flat ? "" : stripSign(progress.pace.delta.text),
+				secondary: flat || !progress.pace.delta.secondaryText ? null : stripSign(progress.pace.delta.secondaryText),
+				expectedPercent: progress.pace.expectedPercentText,
+				elapsedPercent: progress.elapsed?.percentText ?? null
+			}));
+		}
+		if (progress.track) sentences.push(`${labels.trackNames[progress.track]}.`);
+		if (progress.projection) sentences.push(labels.projectionSentence({
+			value: progress.projection.text,
+			percent: progress.projection.percentText
+		}));
+	}
+	if (periodText) sentences.push(labels.periodSentence({
+		name: periodText.name,
+		range: periodText.range
+	}));
+	if (asOfText) sentences.push(`${labels.asOf} ${asOfText}.`);
+	return sentences.join(" ");
+}
+/** The bullet graph's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+function buildTargetChartDescription({ name, progress, labels }) {
+	return labels.chartDescription({
+		name,
+		value: progress.valueText,
+		percent: progress.percentText,
+		target: progress.targetText,
+		expected: progress.pace?.expectedText ?? null,
+		expectedPercent: progress.pace?.expectedPercentText ?? null,
+		projected: progress.projection?.text ?? null,
+		projectedPercent: progress.projection?.percentText ?? null
+	});
+}
+//#endregion
+export { DEFAULT_TARGET_LABELS, buildTargetChartDescription, buildTargetDescription, buildTargetDetailRows, buildTargetExplanation, createTargetFormatters, deriveDays, deriveElapsed, deriveTargetDelta, deriveTargetProgress, deriveTargetState, describePeriodShape, formatPeriod, formatValuePair, isoWeekNumber, paceWord, periodDays, resolvePeriod, resolveTargetLabels };

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

@@ -0,0 +1,4 @@
+import { BuildTargetDescriptionInput, BuildTargetDetailRowsInput, DEFAULT_TARGET_LABELS, DeriveTargetDeltaOptions, DeriveTargetProgressInput, DeriveTargetStateInput, TargetBounds, TargetCardLabels, TargetCardSize, TargetCardState, TargetCardStatus, TargetDelta, TargetDeltaMode, TargetDetailRow, TargetElapsed, TargetExplanationInput, TargetGoodDirection, TargetHeadline, TargetPace, TargetPaceStatus, TargetPeriod, TargetPeriodBounds, TargetPolarity, TargetProgress, TargetProjection, TargetTextFormatters, TargetTone, TargetTrack, buildTargetChartDescription, buildTargetDescription, buildTargetDetailRows, buildTargetExplanation, createTargetFormatters, deriveElapsed, deriveTargetDelta, deriveTargetProgress, deriveTargetState, formatPeriod, formatValuePair, paceWord, periodDays, resolvePeriod, resolveTargetLabels } from "./TargetCard.model.js";
+import { TargetCard, TargetCardProps } from "./TargetCard.js";
+import { TARGET_ACTUAL_DATASET, TARGET_BOUNDS_DATASET, TARGET_LABEL_ROW_PX, TARGET_MARKERS_DATASET, TARGET_MARKER_PARAM, TARGET_MAX_PARAM, TARGET_MIN_PARAM, TARGET_PROJECTION_DATASET, TargetBulletSpecOptions, buildTargetBulletSpec } from "./TargetCard.chart.js";
+export { type BuildTargetDescriptionInput, type BuildTargetDetailRowsInput, DEFAULT_TARGET_LABELS, type DeriveTargetDeltaOptions, type DeriveTargetProgressInput, type DeriveTargetStateInput, TARGET_ACTUAL_DATASET, TARGET_BOUNDS_DATASET, TARGET_LABEL_ROW_PX, TARGET_MARKERS_DATASET, TARGET_MARKER_PARAM, TARGET_MAX_PARAM, TARGET_MIN_PARAM, TARGET_PROJECTION_DATASET, type TargetBounds, type TargetBulletSpecOptions, TargetCard, type TargetCardLabels, type TargetCardProps, type TargetCardSize, type TargetCardState, type TargetCardStatus, type TargetDelta, type TargetDeltaMode, type TargetDetailRow, type TargetElapsed, type TargetExplanationInput, type TargetGoodDirection, type TargetHeadline, type TargetPace, type TargetPaceStatus, type TargetPeriod, type TargetPeriodBounds, type TargetPolarity, type TargetProgress, type TargetProjection, type TargetTextFormatters, type TargetTone, type TargetTrack, buildTargetBulletSpec, buildTargetChartDescription, buildTargetDescription, buildTargetDetailRows, buildTargetExplanation, createTargetFormatters, deriveElapsed, deriveTargetDelta, deriveTargetProgress, deriveTargetState, formatPeriod, formatValuePair, paceWord, periodDays, resolvePeriod, resolveTargetLabels };

package/dist/components/TargetCard/index.js

@@ -0,0 +1,4 @@
+import { TARGET_ACTUAL_DATASET, TARGET_BOUNDS_DATASET, TARGET_LABEL_ROW_PX, TARGET_MARKERS_DATASET, TARGET_MARKER_PARAM, TARGET_MAX_PARAM, TARGET_MIN_PARAM, TARGET_PROJECTION_DATASET, buildTargetBulletSpec } from "./TargetCard.chart.js";
+import { DEFAULT_TARGET_LABELS, buildTargetChartDescription, buildTargetDescription, buildTargetDetailRows, buildTargetExplanation, createTargetFormatters, deriveElapsed, deriveTargetDelta, deriveTargetProgress, deriveTargetState, formatPeriod, formatValuePair, paceWord, periodDays, resolvePeriod, resolveTargetLabels } from "./TargetCard.model.js";
+import { TargetCard } from "./TargetCard.js";
+export { DEFAULT_TARGET_LABELS, TARGET_ACTUAL_DATASET, TARGET_BOUNDS_DATASET, TARGET_LABEL_ROW_PX, TARGET_MARKERS_DATASET, TARGET_MARKER_PARAM, TARGET_MAX_PARAM, TARGET_MIN_PARAM, TARGET_PROJECTION_DATASET, TargetCard, buildTargetBulletSpec, buildTargetChartDescription, buildTargetDescription, buildTargetDetailRows, buildTargetExplanation, createTargetFormatters, deriveElapsed, deriveTargetDelta, deriveTargetProgress, deriveTargetState, formatPeriod, formatValuePair, paceWord, periodDays, resolvePeriod, resolveTargetLabels };

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

@@ -0,0 +1,80 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/TreeCard/TreeCard.chart.d.ts
+/** The visible rows: `{ key, label, depth, value, share, role, inFocus }` per `TreeRow`, in display order. */
+declare const TREE_TABLE_DATASET = "table";
+/** Zero or one row `{ value: 0 }` — a hairline at zero, pushed only when a visible value is negative. */
+declare const TREE_ZERO_DATASET = "zero";
+/** The hovered row's point selection. */
+declare const TREE_HOVER_PARAM = "hover";
+/**
+ * The upper bound of the shared value scale — the tree's total, pushed as a
+ * signal.
+ *
+ * Pinning the domain to the whole rather than to the tallest visible bar is
+ * what makes a bar's length read as its share of the total at every depth,
+ * whether or not the total is itself a row. It rides a signal, not the spec,
+ * because the total is data: baking it into the spec would re-embed the view
+ * on every refresh.
+ */
+declare const TREE_TOTAL_PARAM = "treeTotal";
+declare const TREE_MAX_BAR_HEIGHT = 24;
+/**
+ * Depth reads through the sequential ramp's top steps, darkest at the root.
+ *
+ * Only three: the ramp's lighter steps (`chart-sequential-1…4`) do not clear
+ * WCAG 1.4.11's 3:1 against `background` — `primary-400` measures 2.7:1 on
+ * white — so a fourth shade would buy a depth cue by making the deepest bars
+ * unreadable. Depth past the third level therefore repeats the third step;
+ * indentation, the disclosure control and `aria-level` carry the rest, so the
+ * hierarchy never depends on the ramp alone.
+ */
+declare const TREE_DEPTH_STEPS: readonly [6, 5, 4];
+/** The exact hue a row's bar wears — the swatches in the legend, chips and tooltip read from this too. */
+declare function treeBarColor(tokens: ChartTokens, { depth, role, inFocus }: {
+  depth: number;
+  role?: string;
+  inFocus?: boolean;
+}, colorBy: "depth" | "emphasis", emphasize: boolean): string;
+interface TreeBarsSpecOptions {
+  /** Bar thickness in pixels, capped at 24. Centered in each row's band. */
+  barHeight: number;
+  /** Initial plot height — rows × step. The live value rides the View API. */
+  height: number;
+  /**
+   * Draw a hairline at zero (the `zero` dataset carries the one row) — only
+   * when a visible 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;
+  /** `depth` ramps the sequential steps by level; `emphasis` paints the selected branch and grays the rest. */
+  colorBy: "depth" | "emphasis";
+  /** A row is selected, so `emphasis` has a branch to paint. Without one every bar takes the emphasis hue. */
+  emphasize: boolean;
+  /** Tooltip titles. */
+  itemTitle: string;
+  valueTitle: string;
+  shareTitle: string;
+  /** `arcNumber` grammar for values (`currency:THB:compact@en-US`). */
+  valueFormat: string;
+  /** `arcNumber` grammar for shares (`percent:0@en-US`). */
+  shareFormat: string;
+  locale?: string;
+}
+/**
+ * Builds the bars: one horizontal bar per visible row on a shared zero-based
+ * scale (length compares magnitude — Cleveland & McGill's second-best channel
+ * — and, because the whole is on the same scale, reads as share of it), the
+ * fill carrying depth through the sequential ramp or the selected branch
+ * through the emphasis hue, a hairline at zero once a value is negative, and
+ * a hover selection that keeps the pointed bar solid while its siblings
+ * recede. Every band has no padding, so the bar centers line up with the DOM
+ * rows that carry the names, values and shares.
+ */
+declare function buildTreeBarsSpec(options: TreeBarsSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { TREE_DEPTH_STEPS, TREE_HOVER_PARAM, TREE_MAX_BAR_HEIGHT, TREE_TABLE_DATASET, TREE_TOTAL_PARAM, TREE_ZERO_DATASET, TreeBarsSpecOptions, buildTreeBarsSpec, treeBarColor };