@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/ProgressCard/ProgressCard.model.js

@@ -0,0 +1,389 @@
+import { formatDate, formatNumber } from "../../lib/vega/formatters.js";
+import { resolveInstant } from "../../lib/vega/time.js";
+//#region src/components/ProgressCard/ProgressCard.model.ts
+const DAY_MS = 864e5;
+const DEFAULT_PROGRESS_LABELS = {
+	complete: "complete",
+	countLine: (value, total) => `${value} of ${total}`,
+	percentLine: (percent, labels) => `${percent} ${labels.complete}`,
+	remainingHeadline: (value) => `${value} left`,
+	finishes: (date) => `Finishes ${date}`,
+	daysLate: (days) => `${days} ${days === 1 ? "day" : "days"} late`,
+	daysEarly: (days) => `${days} ${days === 1 ? "day" : "days"} early`,
+	onDueDate: "on the due date",
+	verdicts: {
+		done: "Complete",
+		"on-time": "On time",
+		"at-risk": "At risk",
+		late: "Late",
+		stalled: "Stalled"
+	},
+	perDay: (value) => `${value}/day`,
+	needsPerDay: (value) => `needs ${value}/day`,
+	markNames: {
+		completed: "Completed",
+		scope: "Scope",
+		ideal: "Required pace",
+		projection: "Projected",
+		due: "Due"
+	},
+	active: "In progress",
+	blocked: "Blocked",
+	remaining: "Not started",
+	total: "Total",
+	scope: "Scope",
+	scopeMoved: (from, to) => `Scope moved from ${from} to ${to}`,
+	tableItem: "Stage",
+	tableValue: "Count",
+	tableShare: "Share",
+	tableDate: "Date",
+	tableCompleted: "Completed",
+	needsHistory: "Not enough history for a trend yet",
+	noData: "No data",
+	noMatch: "No matching data",
+	clearFilters: "Clear filters",
+	error: "Could not load",
+	retry: "Retry",
+	stale: "Stale",
+	asOf: "as of",
+	showTable: (name) => `Show ${name} details`,
+	hideTable: (name) => `Hide ${name} details`,
+	about: (name) => `About ${name}`,
+	loading: (name) => `Loading ${name}`,
+	tableCaption: (name) => `${name} readings`,
+	progressGroup: (name) => `${name} progress`,
+	stageBar: (name, parts) => `${name} by stage: ${parts}`,
+	insightMark: "AI insight",
+	explanation: (run, labels) => {
+		const rows = [
+			[labels.markNames.completed, `${run.completedText} (${run.percentText})`],
+			[labels.remaining, run.remainingText],
+			[labels.scope, run.scopeText]
+		];
+		if (run.rate) {
+			rows.push([labels.markNames.ideal, labels.perDay(run.rate.text)]);
+			if (run.rate.requiredText) rows.push([labels.markNames.due, labels.needsPerDay(run.rate.requiredText)]);
+		}
+		if (run.projection) rows.push([labels.markNames.projection, run.projection.text]);
+		return rows;
+	},
+	chartDescription: (name, run, labels) => {
+		const sentences = [`Burn-up chart: ${name}, ${run.completedText} of ${run.scopeText} ${labels.complete} (${run.percentText}) as of ${run.asOfText}.`];
+		if (run.ideal) sentences.push(`The required pace reaches ${run.scopeText} on ${run.dueText}.`);
+		if (run.scopeChanged) sentences.push(`${labels.scopeMoved(run.openingScopeText, run.scopeText)}.`);
+		if (run.projection) sentences.push(`At ${labels.perDay(run.rate?.text ?? "")} it finishes ${run.projection.dateText}${run.due ? ` — ${run.projection.text}` : ""}.`);
+		else if (run.verdict === "stalled") sentences.push(`${labels.verdicts.stalled}.`);
+		return sentences.join(" ");
+	},
+	description: ({ name, state, run, labels }) => {
+		if (state === "loading") return labels.loading(name);
+		if (state === "error") return `${name}: ${labels.error}.`;
+		if (state === "no-match") return `${name}: ${labels.noMatch}.`;
+		if (state === "empty" || !run) return `${name}: ${labels.noData}.`;
+		const sentences = [`${name}: ${run.percentText} ${labels.complete} — ${labels.countLine(run.completedText, run.scopeText)}, ${labels.asOf} ${run.asOfText}.`];
+		if (state === "insufficient") sentences.push(`${labels.needsHistory}.`);
+		if (run.scopeChanged) sentences.push(`${labels.scopeMoved(run.openingScopeText, run.scopeText)}.`);
+		if (run.rate) sentences.push(`${labels.perDay(run.rate.text)}${run.rate.requiredText ? `, ${labels.needsPerDay(run.rate.requiredText)}` : ""}.`);
+		if (run.projection) sentences.push(`${labels.finishes(run.projection.dateText)}${run.due ? ` — ${run.projection.text}` : ""}.`);
+		if (run.verdict) sentences.push(`${labels.verdicts[run.verdict]}.`);
+		return sentences.join(" ");
+	}
+};
+/** Merges consumer overrides over the English defaults. */
+function resolveProgressLabels(overrides) {
+	return overrides ? {
+		...DEFAULT_PROGRESS_LABELS,
+		...overrides
+	} : DEFAULT_PROGRESS_LABELS;
+}
+function createProgressFormatters({ format = "integer", locale, timeZone, formatValue, percentDigits = 0, dateGranularity = "day", formatDateValue } = {}) {
+	const shareFormat = `percent:${percentDigits}`;
+	const rateFormat = format === "integer" ? "number:1" : format;
+	return {
+		formatValue: (value) => value == null || !Number.isFinite(value) ? "—" : formatValue ? formatValue(value) : formatNumber(value, format, locale),
+		formatShare: (ratio) => formatNumber(Number.isFinite(ratio) ? ratio : 0, shareFormat, locale),
+		formatRate: (value) => Number.isFinite(value) ? formatNumber(value, rateFormat, locale) : "—",
+		formatDay: (ms) => !Number.isFinite(ms) ? "—" : formatDateValue ? formatDateValue(new Date(ms)) : formatDate(new Date(ms), {
+			granularity: dateGranularity,
+			locale,
+			timeZone
+		})
+	};
+}
+const dayKeyCache = /* @__PURE__ */ new Map();
+function dayKeyFormat(timeZone) {
+	const key = timeZone ?? "";
+	let cached = dayKeyCache.get(key);
+	if (!cached) {
+		cached = new Intl.DateTimeFormat("en-CA", {
+			...timeZone ? { timeZone } : {},
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit"
+		});
+		dayKeyCache.set(key, cached);
+	}
+	return cached;
+}
+/** The calendar day an instant falls on in `timeZone`, as a day number. */
+function zonedDayNumber(ms, timeZone) {
+	const [year, month, day] = dayKeyFormat(timeZone).format(new Date(ms)).split("-").map(Number);
+	return Math.floor(Date.UTC(year ?? 1970, (month ?? 1) - 1, day ?? 1) / DAY_MS);
+}
+/**
+* Whole calendar days from `from` to `to` in `timeZone` — counted between
+* calendar dates, so a daylight-saving change never shifts the count and
+* "2 days late" means two dates on the wall calendar.
+*/
+function dayDiff(from, to, timeZone) {
+	return zonedDayNumber(to, timeZone) - zonedDayNumber(from, timeZone);
+}
+/**
+* The state machine: the transport's `status` first, then what the data says.
+* A refresh over existing readings keeps the previous render under the veil
+* rather than swapping to a skeleton, so a dashboard never jumps. One reading
+* is `insufficient`, not `ready`: a completion with no history.
+*/
+function deriveProgressState({ status, hasValues, hasData, hasTrend, filtered }) {
+	if (status === "error") return "error";
+	if (status === "loading") return hasData ? "refreshing" : "loading";
+	if (!hasData || !hasValues) return filtered ? "no-match" : "empty";
+	return hasTrend ? "ready" : "insufficient";
+}
+/** Places the optional breakdown stages over the run's scope. */
+function deriveProgressStages(input, scope, formatters, labels) {
+	if (input.length === 0 || scope <= 0) return [];
+	const counted = input.map((stage) => {
+		const value = stage.value;
+		return {
+			stage,
+			value: value != null && Number.isFinite(value) && value >= 0 ? value : null
+		};
+	});
+	const accounted = counted.reduce((sum, entry) => sum + (entry.value ?? 0), 0);
+	const total = Math.max(scope, accounted);
+	const share = (value) => value / total;
+	const stages = counted.map(({ stage, value }) => ({
+		key: stage.key ?? stage.label,
+		label: stage.label,
+		value: value ?? 0,
+		missing: value == null,
+		tone: stage.tone ?? "active",
+		share: share(value ?? 0),
+		width: `${(share(value ?? 0) * 100).toFixed(4)}%`,
+		valueText: value == null ? "—" : formatters.formatValue(value),
+		shareText: formatters.formatShare(share(value ?? 0)),
+		implicit: false
+	}));
+	const unaccounted = total - accounted;
+	if (unaccounted > 0) stages.push({
+		key: "__remaining__",
+		label: labels.remaining,
+		value: unaccounted,
+		missing: false,
+		tone: "remaining",
+		share: share(unaccounted),
+		width: `${(share(unaccounted) * 100).toFixed(4)}%`,
+		valueText: formatters.formatValue(unaccounted),
+		shareText: formatters.formatShare(share(unaccounted)),
+		implicit: true
+	});
+	return stages;
+}
+/**
+* Normalises the snapshots into a burn-up run: readings in order, the scope as
+* it stood at each of them, the rate the work is actually being finished at,
+* where that rate crosses the scope, and the verdict against the deadline.
+* Returns `null` when there is nothing to divide — no reading carries a count
+* and no `total` was declared.
+*/
+function deriveProgressRun({ snapshots, total: declaredTotal, due: dueInput, rateWindow, projected, tolerance = 2, stages: stageInput = [], formatters, labels, timeZone }) {
+	const declared = declaredTotal != null && Number.isFinite(declaredTotal) && declaredTotal > 0 ? declaredTotal : null;
+	const points = snapshots.map((snapshot) => {
+		return {
+			t: resolveInstant(snapshot.date, timeZone),
+			completed: snapshot.completed != null && Number.isFinite(snapshot.completed) && snapshot.completed >= 0 ? snapshot.completed : null,
+			total: (snapshot.total != null && Number.isFinite(snapshot.total) && snapshot.total > 0 ? snapshot.total : null) ?? declared ?? 0
+		};
+	}).filter((point) => Number.isFinite(point.t)).sort((a, b) => a.t - b.t);
+	const observed = points.filter((point) => point.completed != null);
+	const latest = observed.at(-1) ?? null;
+	const scope = Math.max(latest?.total ?? declared ?? 0, latest?.completed ?? 0);
+	if (scope <= 0 || !latest) return null;
+	const completed = latest.completed;
+	const remaining = Math.max(0, scope - completed);
+	const completeRatio = completed / scope;
+	const done = completed >= scope;
+	const start = points[0]?.t ?? latest.t;
+	const openingScope = points[0]?.total ?? scope;
+	const due = dueInput == null ? null : resolveInstant(dueInput, timeZone);
+	const hasDue = due != null && Number.isFinite(due);
+	const windowStart = rateWindow != null && rateWindow > 0 ? latest.t - rateWindow * DAY_MS : start;
+	const inWindow = observed.filter((point) => point.t >= windowStart);
+	const first = inWindow.length >= 2 ? inWindow[0] : observed[0];
+	const insufficient = observed.length < 2;
+	let rate = null;
+	if (first && first !== latest) {
+		const days = (latest.t - first.t) / DAY_MS;
+		const perDay = days > 0 ? (completed - first.completed) / days : 0;
+		const daysLeft = hasDue ? (due - latest.t) / DAY_MS : null;
+		const requiredPerDay = daysLeft != null && daysLeft > 0 && remaining > 0 ? remaining / daysLeft : null;
+		rate = {
+			perDay,
+			days,
+			requiredPerDay,
+			text: formatters.formatRate(perDay),
+			requiredText: requiredPerDay == null ? null : formatters.formatRate(Math.ceil(requiredPerDay))
+		};
+	}
+	const previous = observed.at(-2) ?? null;
+	const stalled = !done && previous != null && completed - previous.completed <= 0;
+	let projection = null;
+	const explicit = projected == null ? null : resolveInstant(projected, timeZone);
+	const finishAt = done ? latest.t : explicit != null && Number.isFinite(explicit) ? explicit : rate && rate.perDay > 0 && !stalled ? Math.round(latest.t + remaining / rate.perDay * DAY_MS) : null;
+	if (finishAt != null) {
+		const daysLate = hasDue ? dayDiff(due, finishAt, timeZone) : 0;
+		const dateText = formatters.formatDay(finishAt);
+		const text = !hasDue ? dateText : daysLate > 0 ? labels.daysLate(daysLate) : daysLate < 0 ? labels.daysEarly(-daysLate) : labels.onDueDate;
+		projection = {
+			date: finishAt,
+			daysLate,
+			late: hasDue && daysLate > 0,
+			dateText,
+			text,
+			source: explicit != null && Number.isFinite(explicit) ? "explicit" : "observed"
+		};
+	}
+	let verdict = null;
+	if (done) verdict = "done";
+	else if (stalled) verdict = "stalled";
+	else if (projection && hasDue) verdict = projection.daysLate <= 0 ? "on-time" : projection.daysLate <= tolerance ? "at-risk" : "late";
+	const polarity = verdict === "done" || verdict === "on-time" ? "positive" : verdict === "late" || verdict === "stalled" ? "negative" : verdict === "at-risk" ? "negative" : "neutral";
+	const ideal = hasDue ? {
+		from: {
+			t: start,
+			y: 0
+		},
+		to: {
+			t: due,
+			y: scope
+		}
+	} : null;
+	const candidates = [
+		start,
+		latest.t,
+		...hasDue ? [due] : [],
+		...projection ? [projection.date] : []
+	];
+	const bounds = {
+		min: Math.min(...candidates),
+		max: Math.max(...candidates)
+	};
+	return {
+		points,
+		observed,
+		start,
+		asOf: latest.t,
+		due: hasDue ? due : null,
+		scope,
+		openingScope,
+		openingScopeText: formatters.formatValue(openingScope),
+		scopeChanged: openingScope !== scope,
+		completed,
+		remaining,
+		completeRatio,
+		rate,
+		projection,
+		verdict,
+		polarity,
+		ideal,
+		bounds,
+		scopeText: formatters.formatValue(scope),
+		completedText: formatters.formatValue(completed),
+		remainingText: formatters.formatValue(remaining),
+		percentText: formatters.formatShare(completeRatio),
+		dueText: hasDue ? formatters.formatDay(due) : null,
+		asOfText: formatters.formatDay(latest.t),
+		done,
+		insufficient,
+		stalled,
+		stages: deriveProgressStages(stageInput, scope, formatters, labels)
+	};
+}
+/** The headline's big text and the line beneath it, per `headline`. */
+function buildProgressHeadline(run, headline, labels) {
+	switch (headline) {
+		case "date": return {
+			big: run.projection ? run.projection.dateText : "—",
+			sub: labels.percentLine(run.percentText, labels)
+		};
+		case "remaining": return {
+			big: labels.remainingHeadline(run.remainingText),
+			sub: labels.percentLine(run.percentText, labels)
+		};
+		default: return {
+			big: run.percentText,
+			sub: labels.countLine(run.completedText, run.scopeText)
+		};
+	}
+}
+/**
+* The table twin: every reading in order, labelled by its own date, with the
+* count finished by then and the share it made of the scope as it stood — so
+* a reader who cannot use the plot reads the same trajectory — then the run's
+* own figures beneath.
+*/
+function buildProgressReadingRows(run, formatters, labels) {
+	const rows = run.points.map((point, index) => ({
+		key: `reading-${index}`,
+		label: formatters.formatDay(point.t),
+		value: point.completed == null ? "—" : formatters.formatValue(point.completed),
+		share: point.completed == null || point.total <= 0 ? "—" : formatters.formatShare(point.completed / point.total)
+	}));
+	rows.push({
+		key: "__scope__",
+		label: labels.scope,
+		value: run.scopeText,
+		share: run.percentText,
+		summary: true
+	});
+	return rows;
+}
+/** The stage rows for the details table, when the consumer passed a breakdown. */
+function buildProgressStageRows(run, labels) {
+	if (run.stages.length === 0) return [];
+	const rows = run.stages.map((stage) => ({
+		key: stage.key,
+		label: stage.label,
+		value: stage.valueText,
+		share: stage.missing ? "—" : stage.shareText,
+		stage
+	}));
+	rows.push({
+		key: "__total__",
+		label: labels.total,
+		value: run.scopeText,
+		share: run.percentText,
+		summary: true
+	});
+	return rows;
+}
+/** The headline group's explanation rows. */
+function buildProgressExplanation(run, labels) {
+	return labels.explanation(run, labels);
+}
+/** The plot's own accessible label. */
+function buildProgressChartDescription(name, run, labels) {
+	return labels.chartDescription(name, run, labels);
+}
+/** The whole card's accessible description. */
+function buildProgressDescription(input) {
+	return input.labels.description(input);
+}
+/** The composed breakdown bar is one image, so its parts are named in one string. */
+function buildStageBarLabel(name, run, labels) {
+	const parts = run.stages.map((stage) => `${stage.label} ${stage.shareText}`).join(", ");
+	return labels.stageBar(name, parts);
+}
+//#endregion
+export { DEFAULT_PROGRESS_LABELS, buildProgressChartDescription, buildProgressDescription, buildProgressExplanation, buildProgressHeadline, buildProgressReadingRows, buildProgressStageRows, buildStageBarLabel, createProgressFormatters, dayDiff, deriveProgressRun, deriveProgressStages, deriveProgressState, resolveProgressLabels, zonedDayNumber };

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

@@ -0,0 +1,4 @@
+import { CreateProgressFormattersInput, DEFAULT_PROGRESS_LABELS, DeriveProgressRunInput, DeriveProgressStateInput, ProgressCardLabels, ProgressCardSize, ProgressCardState, ProgressCardStatus, ProgressDescriptionInput, ProgressDetailRow, ProgressHeadline, ProgressPoint, ProgressPolarity, ProgressProjection, ProgressRate, ProgressRun, ProgressSnapshot, ProgressStage, ProgressStageInput, ProgressStageTone, ProgressTextFormatters, ProgressVerdict, buildProgressChartDescription, buildProgressDescription, buildProgressExplanation, buildProgressHeadline, buildProgressReadingRows, buildProgressStageRows, buildStageBarLabel, createProgressFormatters, dayDiff, deriveProgressRun, deriveProgressStages, deriveProgressState, resolveProgressLabels } from "./ProgressCard.model.js";
+import { ProgressCard, ProgressCardProps } from "./ProgressCard.js";
+import { PROGRESS_COMPLETED_DATASET, PROGRESS_DUE_DATASET, PROGRESS_FINISH_DATASET, PROGRESS_GAP_DATASET, PROGRESS_HOVER_PARAM, PROGRESS_IDEAL_DATASET, PROGRESS_LATEST_DATASET, PROGRESS_PROJECTION_DATASET, PROGRESS_SCOPE_DATASET, PROGRESS_X_TICKS_PARAM, ProgressBurnUpSpecOptions, buildProgressBurnUpSpec } from "./ProgressCard.chart.js";
+export { type CreateProgressFormattersInput, DEFAULT_PROGRESS_LABELS, type DeriveProgressRunInput, type DeriveProgressStateInput, PROGRESS_COMPLETED_DATASET, PROGRESS_DUE_DATASET, PROGRESS_FINISH_DATASET, PROGRESS_GAP_DATASET, PROGRESS_HOVER_PARAM, PROGRESS_IDEAL_DATASET, PROGRESS_LATEST_DATASET, PROGRESS_PROJECTION_DATASET, PROGRESS_SCOPE_DATASET, PROGRESS_X_TICKS_PARAM, type ProgressBurnUpSpecOptions, ProgressCard, type ProgressCardLabels, type ProgressCardProps, type ProgressCardSize, type ProgressCardState, type ProgressCardStatus, type ProgressDescriptionInput, type ProgressDetailRow, type ProgressHeadline, type ProgressPoint, type ProgressPolarity, type ProgressProjection, type ProgressRate, type ProgressRun, type ProgressSnapshot, type ProgressStage, type ProgressStageInput, type ProgressStageTone, type ProgressTextFormatters, type ProgressVerdict, buildProgressBurnUpSpec, buildProgressChartDescription, buildProgressDescription, buildProgressExplanation, buildProgressHeadline, buildProgressReadingRows, buildProgressStageRows, buildStageBarLabel, createProgressFormatters, dayDiff, deriveProgressRun, deriveProgressStages, deriveProgressState, resolveProgressLabels };

package/dist/components/ProgressCard/index.js

@@ -0,0 +1,4 @@
+import { PROGRESS_COMPLETED_DATASET, PROGRESS_DUE_DATASET, PROGRESS_FINISH_DATASET, PROGRESS_GAP_DATASET, PROGRESS_HOVER_PARAM, PROGRESS_IDEAL_DATASET, PROGRESS_LATEST_DATASET, PROGRESS_PROJECTION_DATASET, PROGRESS_SCOPE_DATASET, PROGRESS_X_TICKS_PARAM, buildProgressBurnUpSpec } from "./ProgressCard.chart.js";
+import { DEFAULT_PROGRESS_LABELS, buildProgressChartDescription, buildProgressDescription, buildProgressExplanation, buildProgressHeadline, buildProgressReadingRows, buildProgressStageRows, buildStageBarLabel, createProgressFormatters, dayDiff, deriveProgressRun, deriveProgressStages, deriveProgressState, resolveProgressLabels } from "./ProgressCard.model.js";
+import { ProgressCard } from "./ProgressCard.js";
+export { DEFAULT_PROGRESS_LABELS, PROGRESS_COMPLETED_DATASET, PROGRESS_DUE_DATASET, PROGRESS_FINISH_DATASET, PROGRESS_GAP_DATASET, PROGRESS_HOVER_PARAM, PROGRESS_IDEAL_DATASET, PROGRESS_LATEST_DATASET, PROGRESS_PROJECTION_DATASET, PROGRESS_SCOPE_DATASET, PROGRESS_X_TICKS_PARAM, ProgressCard, buildProgressBurnUpSpec, buildProgressChartDescription, buildProgressDescription, buildProgressExplanation, buildProgressHeadline, buildProgressReadingRows, buildProgressStageRows, buildStageBarLabel, createProgressFormatters, dayDiff, deriveProgressRun, deriveProgressStages, deriveProgressState, resolveProgressLabels };

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

@@ -0,0 +1,45 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/ReportCard/ReportCard.chart.d.ts
+/** The rows: `{ key, label, plotted, targetScore, tone, … }` per `ReportRow`, in display order. */
+declare const REPORT_TABLE_DATASET = "table";
+/** The grade ladder: `{ key, label, from, to, tone }` per `ReportBandSpan`, low to high. */
+declare const REPORT_BANDS_DATASET = "bands";
+/** One row `{ min, max }` — the plotted score domain, widened to hold every score. */
+declare const REPORT_BOUNDS_DATASET = "bounds";
+/** The plotted domain's ends, read from the `bounds` dataset. */
+declare const REPORT_MIN_PARAM = "report_x_min";
+declare const REPORT_MAX_PARAM = "report_x_max";
+declare const REPORT_MAX_BAR_HEIGHT = 24;
+/** How the grade bands behind the bars are painted. */
+type ReportBandPaint = "neutral" | "status";
+interface ReportBulletSpecOptions {
+  /** 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;
+  /** `neutral` (default) paints the ladder in one gray at four intensities; `status` paints each band in its own tone. */
+  bandPaint: ReportBandPaint;
+  /** Draw the per-row comparative tick where a criterion is expected to score. */
+  ticks: boolean;
+  /** Wire the tooltip channel on a transparent full-row target — a 12px bar is no pointer target. */
+  tooltip: boolean;
+  /** Tooltip titles. */
+  criterionTitle: string;
+  scoreTitle: string;
+  /** `arcNumber` grammar for scores (`number:0@en-US`). */
+  scoreFormat: string;
+  locale?: string;
+}
+/**
+ * Builds the bullet rows: the grade ladder as quiet full-height stripes, one
+ * bar per criterion from the scale's floor to its score (length on a shared
+ * position scale — Cleveland & McGill's channel for magnitude, Wilke's
+ * proportional ink), the bar painted with its grade's tone, a comparative
+ * tick where the criterion is expected to score, and a transparent full-row
+ * target carrying the tooltip. Every band has no padding, so the bar centers
+ * line up with the DOM rows that carry the names, scores and grades.
+ */
+declare function buildReportBulletSpec(options: ReportBulletSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { REPORT_BANDS_DATASET, REPORT_BOUNDS_DATASET, REPORT_MAX_BAR_HEIGHT, REPORT_MAX_PARAM, REPORT_MIN_PARAM, REPORT_TABLE_DATASET, ReportBandPaint, ReportBulletSpecOptions, buildReportBulletSpec };

package/dist/components/ReportCard/ReportCard.chart.js

@@ -0,0 +1,231 @@
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/ReportCard/ReportCard.chart.ts
+/** The rows: `{ key, label, plotted, targetScore, tone, … }` per `ReportRow`, in display order. */
+const REPORT_TABLE_DATASET = "table";
+/** The grade ladder: `{ key, label, from, to, tone }` per `ReportBandSpan`, low to high. */
+const REPORT_BANDS_DATASET = "bands";
+/** One row `{ min, max }` — the plotted score domain, widened to hold every score. */
+const REPORT_BOUNDS_DATASET = "bounds";
+/** The plotted domain's ends, read from the `bounds` dataset. */
+const REPORT_MIN_PARAM = "report_x_min";
+const REPORT_MAX_PARAM = "report_x_max";
+const REPORT_MAX_BAR_HEIGHT = 24;
+const TICK_OVERSHOOT_PX = 8;
+const NEUTRAL_BAND_OPACITY = {
+	positive: .05,
+	neutral: .07,
+	warning: .12,
+	negative: .18
+};
+const STATUS_BAND_OPACITY = .14;
+const ROW_DOMAIN_EXPR = `pluck(data('${REPORT_TABLE_DATASET}'), 'key')`;
+/**
+* A fill that follows the row's grade through its `tone`: the diverging ends
+* for a passing and a failing grade, the degraded status hue for the band
+* between them, the emphasis hue for a neutral grade and for anything
+* ungraded — four token values in the spec, so the spec stays structural
+* while the data decides. This is the one place status hues belong on a mark:
+* the encoded value *is* the judgement.
+*/
+function toneColor(tokens) {
+	return {
+		condition: [
+			{
+				test: "datum.tone === 'positive'",
+				value: tokens.divergingPositive
+			},
+			{
+				test: "datum.tone === 'warning'",
+				value: tokens.status.degraded
+			},
+			{
+				test: "datum.tone === 'negative'",
+				value: tokens.divergingNegative
+			}
+		],
+		value: tokens.emphasis
+	};
+}
+/** The neutral ladder's intensity, worst band darkest. */
+function neutralOpacity() {
+	return {
+		condition: [
+			{
+				test: "datum.tone === 'negative'",
+				value: NEUTRAL_BAND_OPACITY.negative
+			},
+			{
+				test: "datum.tone === 'warning'",
+				value: NEUTRAL_BAND_OPACITY.warning
+			},
+			{
+				test: "datum.tone === 'positive'",
+				value: NEUTRAL_BAND_OPACITY.positive
+			}
+		],
+		value: NEUTRAL_BAND_OPACITY.neutral
+	};
+}
+/**
+* Builds the bullet rows: the grade ladder as quiet full-height stripes, one
+* bar per criterion from the scale's floor to its score (length on a shared
+* position scale — Cleveland & McGill's channel for magnitude, Wilke's
+* proportional ink), the bar painted with its grade's tone, a comparative
+* tick where the criterion is expected to score, and a transparent full-row
+* target carrying the tooltip. Every band has no padding, so the bar centers
+* line up with the DOM rows that carry the names, scores and grades.
+*/
+function buildReportBulletSpec(options, tokens) {
+	const { barHeight, height, bandPaint, ticks, tooltip, criterionTitle, scoreTitle, scoreFormat, locale } = options;
+	const thickness = Math.min(24, barHeight);
+	const xScale = {
+		domain: { expr: `[${REPORT_MIN_PARAM}, ${REPORT_MAX_PARAM}]` },
+		nice: false
+	};
+	const yField = {
+		field: "key",
+		type: "nominal",
+		sort: null,
+		axis: null,
+		scale: {
+			domain: { expr: ROW_DOMAIN_EXPR },
+			paddingInner: 0,
+			paddingOuter: 0
+		}
+	};
+	const scoreTooltip = { tooltip: [{
+		field: "label",
+		type: "nominal",
+		title: criterionTitle
+	}, {
+		field: "score",
+		type: "quantitative",
+		title: scoreTitle,
+		format: scoreFormat,
+		formatType: "arcNumber"
+	}] };
+	const layers = [
+		{
+			data: { name: REPORT_BOUNDS_DATASET },
+			mark: {
+				type: "rect",
+				fill: tokens.muted,
+				aria: false
+			},
+			encoding: {
+				x: {
+					field: "min",
+					type: "quantitative",
+					axis: null,
+					scale: xScale
+				},
+				x2: { field: "max" },
+				y: { value: 0 },
+				y2: { value: "height" }
+			}
+		},
+		{
+			data: { name: REPORT_BANDS_DATASET },
+			mark: {
+				type: "rect",
+				...bandPaint === "status" ? { fillOpacity: STATUS_BAND_OPACITY } : { fill: tokens.context },
+				aria: false
+			},
+			encoding: {
+				x: {
+					field: "from",
+					type: "quantitative",
+					axis: null,
+					scale: xScale
+				},
+				x2: { field: "to" },
+				y: { value: 0 },
+				y2: { value: "height" },
+				...bandPaint === "status" ? { fill: toneColor(tokens) } : { fillOpacity: neutralOpacity() }
+			}
+		},
+		{
+			data: { name: REPORT_TABLE_DATASET },
+			mark: {
+				type: "bar",
+				height: thickness,
+				cornerRadiusEnd: 0,
+				cornerRadiusTopRight: 2,
+				cornerRadiusBottomRight: 2,
+				aria: false
+			},
+			encoding: {
+				y: yField,
+				x: {
+					field: "plotted",
+					type: "quantitative",
+					axis: null,
+					scale: xScale
+				},
+				x2: { datum: { expr: REPORT_MIN_PARAM } },
+				fill: toneColor(tokens)
+			}
+		}
+	];
+	if (ticks) layers.push({
+		data: { name: REPORT_TABLE_DATASET },
+		transform: [{ filter: "isValid(datum.targetScore)" }],
+		mark: {
+			type: "tick",
+			thickness: 2,
+			size: thickness + TICK_OVERSHOOT_PX,
+			color: tokens.foreground,
+			opacity: .75,
+			aria: false
+		},
+		encoding: {
+			y: yField,
+			x: {
+				field: "targetScore",
+				type: "quantitative",
+				axis: null,
+				scale: xScale
+			}
+		}
+	});
+	if (tooltip) layers.push({
+		data: { name: REPORT_TABLE_DATASET },
+		mark: {
+			type: "rect",
+			fill: "transparent",
+			aria: false
+		},
+		encoding: {
+			y: yField,
+			x: {
+				datum: { expr: REPORT_MIN_PARAM },
+				type: "quantitative",
+				axis: null,
+				scale: xScale
+			},
+			x2: { datum: { expr: REPORT_MAX_PARAM } },
+			...scoreTooltip
+		}
+	});
+	const bounds = (field, fallback) => `length(data('${REPORT_BOUNDS_DATASET}')) ? data('${REPORT_BOUNDS_DATASET}')[0].${field} : ${fallback}`;
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 240,
+		height,
+		autosize: { type: "none" },
+		padding: 0,
+		background: "transparent",
+		params: [{
+			name: REPORT_MIN_PARAM,
+			expr: bounds("min", 0)
+		}, {
+			name: REPORT_MAX_PARAM,
+			expr: bounds("max", 100)
+		}],
+		data: { name: REPORT_TABLE_DATASET },
+		layer: layers,
+		config: arcVegaConfig(tokens, { locale })
+	};
+}
+//#endregion
+export { REPORT_BANDS_DATASET, REPORT_BOUNDS_DATASET, REPORT_MAX_BAR_HEIGHT, REPORT_MAX_PARAM, REPORT_MIN_PARAM, REPORT_TABLE_DATASET, buildReportBulletSpec };