@arcfusionz/arc-analytic-ui 0.0.0

package/dist/lib/vega/config.js

@@ -0,0 +1,113 @@
+//#region src/lib/vega/config.ts
+function withLocale(format, locale) {
+	return locale ? `${format}@${locale}` : format;
+}
+/**
+* The Vega-Lite `config` that makes a chart an Arc chart: transparent
+* background, the brand font stacks (Vega draws its own text, so the Thai
+* fallback rides the stack string), a hairline solid grid on `chart-grid`,
+* quiet axes and labels in the muted text role, ranges drawn from the
+* `chart-*` slots, thin quiet marks, ARIA on, and the Intl-backed
+* `arcNumber` / `arcTime` formatters as the default format types.
+*
+* Rebuild it whenever `tokens` change (a theme flip) — it is part of the spec,
+* so that is the one legitimate re-embed.
+*/
+function arcVegaConfig(tokens, { locale, timeZone, vegaLocale } = {}) {
+	const timeFormat = [
+		"day",
+		locale ?? "",
+		timeZone ?? ""
+	].join("@").replace(/@+$/, "");
+	return {
+		background: "transparent",
+		font: tokens.fontSans,
+		view: { stroke: null },
+		axis: {
+			domainColor: tokens.axis,
+			domainWidth: 1,
+			gridColor: tokens.grid,
+			gridWidth: 1,
+			gridOpacity: 1,
+			tickColor: tokens.axis,
+			tickSize: 4,
+			labelColor: tokens.axisLabel,
+			labelFont: tokens.fontSans,
+			labelFontSize: 11,
+			labelPadding: 6,
+			labelOverlap: true,
+			titleColor: tokens.axisLabel,
+			titleFont: tokens.fontHeading,
+			titleFontSize: 11,
+			titleFontWeight: 500,
+			titlePadding: 8
+		},
+		legend: {
+			orient: "right",
+			labelColor: tokens.foreground,
+			labelFont: tokens.fontSans,
+			labelFontSize: 11,
+			titleColor: tokens.mutedForeground,
+			titleFont: tokens.fontHeading,
+			titleFontSize: 11,
+			titleFontWeight: 500,
+			symbolType: "circle",
+			symbolSize: 64
+		},
+		title: {
+			color: tokens.foreground,
+			font: tokens.fontHeading,
+			fontSize: 14,
+			fontWeight: 600,
+			anchor: "start",
+			subtitleColor: tokens.mutedForeground,
+			subtitleFont: tokens.fontSans,
+			subtitleFontSize: 12
+		},
+		range: {
+			category: tokens.category,
+			ordinal: tokens.sequential,
+			ramp: tokens.sequential,
+			heatmap: tokens.sequential,
+			diverging: [
+				tokens.divergingNegative,
+				tokens.divergingMid,
+				tokens.divergingPositive
+			]
+		},
+		mark: { color: tokens.emphasis },
+		line: {
+			strokeWidth: 2,
+			strokeCap: "round",
+			strokeJoin: "round"
+		},
+		area: {
+			fillOpacity: .12,
+			line: false
+		},
+		bar: { cornerRadiusEnd: 2 },
+		rule: {
+			color: tokens.reference,
+			strokeWidth: 1
+		},
+		point: {
+			size: 64,
+			filled: true
+		},
+		circle: { size: 64 },
+		text: {
+			color: tokens.foreground,
+			font: tokens.fontSans,
+			fontSize: 11
+		},
+		customFormatTypes: true,
+		numberFormatType: "arcNumber",
+		numberFormat: withLocale("compact", locale),
+		timeFormatType: "arcTime",
+		timeFormat,
+		...vegaLocale ? { locale: vegaLocale } : {},
+		aria: true
+	};
+}
+//#endregion
+export { arcVegaConfig };

package/dist/lib/vega/embed.d.ts

@@ -0,0 +1,29 @@
+import { TooltipHandler } from "vega";
+import { EmbedOptions } from "vega-embed";
+//#region src/lib/vega/embed.d.ts
+/**
+ * `vega.Warn`. The numeric level is used rather than the constant because the
+ * constant is not in vega's typings and importing vega here would pull the
+ * engine into a module that must stay engine-free.
+ */
+declare const VEGA_WARN = 2;
+interface ArcEmbedOptionsInput {
+  /** The bridge's tooltip handler (`useArcTooltipHandler().handler`), or `false` for none. */
+  tooltip?: TooltipHandler | false;
+  /** `svg` (default) gives an accessibility tree, DPR-crisp output and deterministic snapshots; `canvas` only for a measured case above the budget. */
+  renderer?: "svg" | "canvas";
+  /** Vega log level. Default `VEGA_WARN` — a warning is a spec bug to fix, never to silence. */
+  logLevel?: number;
+}
+/**
+ * vega-embed options for an Arc chart: Vega-Lite mode, no actions menu (an
+ * Arc `Menu` calling `view.toImageURL` replaces it), no injected stylesheet
+ * (consumer packages ship no CSS), vega-tooltip replaced by the bridge's
+ * handler, hover off.
+ *
+ * **Memoize the result** — react-vega deep-compares options on every render
+ * and a fresh object (or a fresh handler function) re-embeds the view.
+ */
+declare function arcEmbedOptions({ tooltip, renderer, logLevel }?: ArcEmbedOptionsInput): EmbedOptions;
+//#endregion
+export { ArcEmbedOptionsInput, VEGA_WARN, arcEmbedOptions };

package/dist/lib/vega/embed.js

@@ -0,0 +1,29 @@
+//#region src/lib/vega/embed.ts
+/**
+* `vega.Warn`. The numeric level is used rather than the constant because the
+* constant is not in vega's typings and importing vega here would pull the
+* engine into a module that must stay engine-free.
+*/
+const VEGA_WARN = 2;
+/**
+* vega-embed options for an Arc chart: Vega-Lite mode, no actions menu (an
+* Arc `Menu` calling `view.toImageURL` replaces it), no injected stylesheet
+* (consumer packages ship no CSS), vega-tooltip replaced by the bridge's
+* handler, hover off.
+*
+* **Memoize the result** — react-vega deep-compares options on every render
+* and a fresh object (or a fresh handler function) re-embeds the view.
+*/
+function arcEmbedOptions({ tooltip = false, renderer = "svg", logLevel = 2 } = {}) {
+	return {
+		mode: "vega-lite",
+		renderer,
+		actions: false,
+		defaultStyle: false,
+		hover: false,
+		tooltip,
+		logLevel
+	};
+}
+//#endregion
+export { VEGA_WARN, arcEmbedOptions };

package/dist/lib/vega/engine.d.ts

@@ -0,0 +1,10 @@
+import { ArcVegaDatasets, UseArcVegaParams, useArcVega } from "./useArcVega.js";
+import { ArcVegaSurface, ArcVegaSurfaceProps } from "./ArcVegaSurface.js";
+import { changeset, expressionFunction as expressionFunction$1 } from "vega";
+import { compile } from "vega-lite";
+import { VegaEmbed, useVegaEmbed as useVegaEmbed$1 } from "react-vega";
+declare namespace engine_d_exports {
+  export { ArcVegaDatasets, ArcVegaSurface, ArcVegaSurfaceProps, UseArcVegaParams, VegaEmbed, changeset, compile, expressionFunction$1 as expressionFunction, useArcVega, useVegaEmbed$1 as useVegaEmbed };
+}
+//#endregion
+export { type ArcVegaDatasets, ArcVegaSurface, type ArcVegaSurfaceProps, type UseArcVegaParams, VegaEmbed, changeset, compile, engine_d_exports, expressionFunction$1 as expressionFunction, useArcVega, useVegaEmbed$1 as useVegaEmbed };

package/dist/lib/vega/engine.js

@@ -0,0 +1,6 @@
+import { useArcVega } from "./useArcVega.js";
+import { ArcVegaSurface } from "./ArcVegaSurface.js";
+import { changeset, expressionFunction } from "vega";
+import { compile } from "vega-lite";
+import { VegaEmbed, useVegaEmbed } from "react-vega";
+export { ArcVegaSurface, VegaEmbed, changeset, compile, expressionFunction, useArcVega, useVegaEmbed };

package/dist/lib/vega/formatters.d.ts

@@ -0,0 +1,125 @@
+//#region src/lib/vega/formatters.d.ts
+/**
+ * One formatting grammar shared by axes, tooltips, tiles, and tables, so the
+ * same value never rounds two ways (Few's precision pitfall). Everything is
+ * built on `Intl`, so locale and time zone are first-class, and the two Vega
+ * expression functions registered by `registerArcFormatters` call straight
+ * into these helpers.
+ *
+ * Number grammar — `kind[:arg[:arg]][@locale]`:
+ *
+ *   "number"            0–2 fraction digits (Intl decimal)     1,234.5
+ *   "number:0"          fixed maximum fraction digits          1,235
+ *   "integer"           whole numbers                          1,235
+ *   "compact"           short scale, 1 fraction digit          3.8M
+ *   "compact:0"                                                4M
+ *   "percent"           ratio → percent, 1 fraction digit      12.4%
+ *   "percent:0"                                                12%
+ *   "currency:THB"      Intl currency, default digits          ฿3,848,305.93
+ *   "currency:THB:0"    fixed digits                           ฿3,848,306
+ *   "currency:THB:compact"  short scale                        ฿3.8M
+ *   "compact@th-TH"     any kind, with a locale suffix
+ *
+ * Time grammar — `granularity[@locale[@timeZone]]`, granularity one of
+ * `day` (8 Sep 2026), `month` (Sep 2026), `year`, `time` (16:30),
+ * `datetime` (8 Sep 2026, 16:30), plus the axis-length forms `day-short`
+ * (8 Sep), `day-time` (8 Sep, 4 PM) and `month-short` (Sep) for tick labels
+ * that have no room for a year — `day-time` is the one a window shorter than
+ * two days needs, where a bare clock time repeats at both ends. It carries the
+ * hour only: minutes on an axis label are noise, they push the text past the
+ * width an axis label is allowed, and the tooltip has them anyway. Thai products that use the Gregorian calendar pass
+ * `th-TH-u-ca-gregory`; a bare `th-TH` defaults to the Buddhist calendar.
+ */
+/** Rendered for null, undefined, NaN and infinite values — a typographic dash, never "0". */
+declare const MISSING_VALUE = "—";
+type ArcNumberFormatKind = "number" | "integer" | "compact" | "percent" | "currency";
+interface ArcNumberFormatSpec {
+  kind: ArcNumberFormatKind;
+  /** Maximum fraction digits, when the format fixes them. */
+  digits?: number;
+  /** Short-scale notation, for currency formats (`currency:THB:compact`). */
+  compact?: boolean;
+  /** ISO 4217 code for currency formats. */
+  currency?: string;
+  /** BCP 47 tag from the `@locale` suffix. */
+  locale?: string;
+}
+type ArcTimeGranularity = "day" | "month" | "year" | "time" | "datetime" | "day-short" | "day-time" | "month-short";
+interface ArcTimeFormatSpec {
+  granularity: ArcTimeGranularity;
+  locale?: string;
+  timeZone?: string;
+}
+/** Parses the number grammar. Unknown kinds fall back to `number` rather than throwing — a bad format string must not take a chart down. */
+declare function parseArcNumberFormat(format: string | undefined | null): ArcNumberFormatSpec;
+/** Parses the time grammar. */
+declare function parseArcTimeFormat(format: string | undefined | null): ArcTimeFormatSpec;
+/**
+ * Formats a number through the grammar above. `extra` merges Intl options on
+ * top (deltas pass `{ signDisplay: "exceptZero" }`); a missing or non-finite
+ * value renders as `MISSING_VALUE`.
+ */
+declare function formatNumber(value: number | null | undefined, format?: string, locale?: string, extra?: Intl.NumberFormatOptions): string;
+/**
+ * Formats a date at a granularity. `timeZone` defaults to the runtime's; pass
+ * it explicitly wherever output must be deterministic (Chromatic, tests, or a
+ * product that reports in one business time zone).
+ */
+declare function formatDate(value: Date | string | number | null | undefined, { granularity, locale, timeZone }?: Partial<ArcTimeFormatSpec>): string;
+/**
+ * Formats a period between two dates at a granularity, collapsing the parts
+ * they share the way the locale does — `Aug 7 – 9, 2026`, `Aug 28 – Sep 8,
+ * 2026`, `7–9 ส.ค. 2026` — through `Intl.DateTimeFormat.formatRange`, with
+ * `start – end` as the fallback where a runtime lacks it. The bounds may come
+ * in either order; an unparseable bound renders as `MISSING_VALUE`.
+ */
+declare function formatDateRange(start: Date | string | number | null | undefined, end: Date | string | number | null | undefined, { granularity, locale, timeZone }?: Partial<ArcTimeFormatSpec>): string;
+type ArcDeltaMode = "percent" | "absolute";
+type ArcDeltaDirection = "up" | "down" | "flat";
+interface FormatDeltaOptions {
+  /** `percent` (default) is relative change; `absolute` is the difference in the value's own units. */
+  mode?: ArcDeltaMode;
+  /** The value's format — an absolute delta of a `percent` value is expressed in percentage points. */
+  format?: string;
+  locale?: string;
+  /** Fraction digits for a percent delta. Default 1. */
+  digits?: number;
+  /** Unit appended to a percentage-point delta. Default `" pp"`. */
+  pointsSuffix?: string;
+}
+interface FormattedDelta {
+  direction: ArcDeltaDirection;
+  /** Relative change as a ratio, or `null` when the previous value is zero (undefined). */
+  percent: number | null;
+  /** `current - previous`, in the value's units. */
+  absolute: number;
+  /** Signed text, e.g. `+12.4%`, `-0.3 pp`, `+฿120K`. */
+  text: string;
+  /** Which mode actually rendered: a percent delta from zero falls back to absolute. */
+  renderedMode: ArcDeltaMode;
+}
+/**
+ * Formats the change between two readings with the sign always shown. A
+ * relative change from zero is undefined, so `mode: "percent"` renders the
+ * absolute difference instead (and says so in `renderedMode`). An absolute
+ * delta of a percent-formatted value is in percentage points — never "-7%"
+ * for churn going from 4.1% to 3.8%.
+ */
+declare function formatDelta(current: number, previous: number, { mode, format, locale, digits, pointsSuffix }?: FormatDeltaOptions): FormattedDelta;
+type ExpressionFunctionRegistrar = (name: string, fn: (...args: never[]) => unknown) => unknown;
+/**
+ * Registers `arcNumber`, `arcTime` and the responsive axis helpers
+ * `arcAxisTicks` / `arcAxisLabelAlign` as Vega expression functions, once.
+ * Takes `vega.expressionFunction` as an argument so this module never imports
+ * the engine itself; the engine-bound modules call it at load time, before the
+ * first `parse` — Vega requires that. Returns whether this call did the
+ * registering.
+ *
+ * Both axis helpers take `(domain, width, discrete, format, kind, anchors?)`:
+ * `kind` picks the label formatter (`time` → `arcTime`, `number` →
+ * `arcNumber`, else the raw category), and `anchors` — a highlighted window's
+ * `[start, end]` — switches from evenly spaced labels to the window's bounds.
+ */
+declare function registerArcFormatters(expressionFunction: ExpressionFunctionRegistrar): boolean;
+//#endregion
+export { ArcDeltaDirection, ArcDeltaMode, ArcNumberFormatKind, ArcNumberFormatSpec, ArcTimeFormatSpec, ArcTimeGranularity, FormatDeltaOptions, FormattedDelta, MISSING_VALUE, formatDate, formatDateRange, formatDelta, formatNumber, parseArcNumberFormat, parseArcTimeFormat, registerArcFormatters };

package/dist/lib/vega/formatters.js

@@ -0,0 +1,277 @@
+import { axisLabelAlign, selectAxisTicks } from "./axisTicks.js";
+//#region src/lib/vega/formatters.ts
+/**
+* One formatting grammar shared by axes, tooltips, tiles, and tables, so the
+* same value never rounds two ways (Few's precision pitfall). Everything is
+* built on `Intl`, so locale and time zone are first-class, and the two Vega
+* expression functions registered by `registerArcFormatters` call straight
+* into these helpers.
+*
+* Number grammar — `kind[:arg[:arg]][@locale]`:
+*
+*   "number"            0–2 fraction digits (Intl decimal)     1,234.5
+*   "number:0"          fixed maximum fraction digits          1,235
+*   "integer"           whole numbers                          1,235
+*   "compact"           short scale, 1 fraction digit          3.8M
+*   "compact:0"                                                4M
+*   "percent"           ratio → percent, 1 fraction digit      12.4%
+*   "percent:0"                                                12%
+*   "currency:THB"      Intl currency, default digits          ฿3,848,305.93
+*   "currency:THB:0"    fixed digits                           ฿3,848,306
+*   "currency:THB:compact"  short scale                        ฿3.8M
+*   "compact@th-TH"     any kind, with a locale suffix
+*
+* Time grammar — `granularity[@locale[@timeZone]]`, granularity one of
+* `day` (8 Sep 2026), `month` (Sep 2026), `year`, `time` (16:30),
+* `datetime` (8 Sep 2026, 16:30), plus the axis-length forms `day-short`
+* (8 Sep), `day-time` (8 Sep, 4 PM) and `month-short` (Sep) for tick labels
+* that have no room for a year — `day-time` is the one a window shorter than
+* two days needs, where a bare clock time repeats at both ends. It carries the
+* hour only: minutes on an axis label are noise, they push the text past the
+* width an axis label is allowed, and the tooltip has them anyway. Thai products that use the Gregorian calendar pass
+* `th-TH-u-ca-gregory`; a bare `th-TH` defaults to the Buddhist calendar.
+*/
+/** Rendered for null, undefined, NaN and infinite values — a typographic dash, never "0". */
+const MISSING_VALUE = "—";
+const NUMBER_KINDS = [
+	"number",
+	"integer",
+	"compact",
+	"percent",
+	"currency"
+];
+const TIME_GRANULARITIES = [
+	"day",
+	"month",
+	"year",
+	"time",
+	"datetime",
+	"day-short",
+	"day-time",
+	"month-short"
+];
+/** Parses the number grammar. Unknown kinds fall back to `number` rather than throwing — a bad format string must not take a chart down. */
+function parseArcNumberFormat(format) {
+	const [body = "", locale] = String(format ?? "number").split("@");
+	const [rawKind = "number", ...args] = body.split(":");
+	const kind = NUMBER_KINDS.includes(rawKind) ? rawKind : "number";
+	const spec = { kind };
+	if (locale) spec.locale = locale;
+	let rest = args;
+	if (kind === "currency") {
+		const [code, ...others] = args;
+		if (code) spec.currency = code.toUpperCase();
+		rest = others;
+	}
+	for (const arg of rest) if (/^\d+$/.test(arg)) spec.digits = Number(arg);
+	else if (arg === "compact") spec.compact = true;
+	return spec;
+}
+/** Parses the time grammar. */
+function parseArcTimeFormat(format) {
+	const [rawGranularity = "day", locale, timeZone] = String(format ?? "day").split("@");
+	const spec = { granularity: TIME_GRANULARITIES.includes(rawGranularity) ? rawGranularity : "day" };
+	if (locale) spec.locale = locale;
+	if (timeZone) spec.timeZone = timeZone;
+	return spec;
+}
+const numberFormatCache = /* @__PURE__ */ new Map();
+const dateFormatCache = /* @__PURE__ */ new Map();
+function numberOptions(spec) {
+	switch (spec.kind) {
+		case "integer": return { maximumFractionDigits: 0 };
+		case "compact": return {
+			notation: "compact",
+			compactDisplay: "short",
+			maximumFractionDigits: spec.digits ?? 1
+		};
+		case "percent": return {
+			style: "percent",
+			maximumFractionDigits: spec.digits ?? 1
+		};
+		case "currency": {
+			const options = {
+				style: "currency",
+				currency: spec.currency ?? "USD",
+				currencyDisplay: "narrowSymbol"
+			};
+			if (spec.compact) {
+				options.notation = "compact";
+				options.compactDisplay = "short";
+			}
+			if (spec.digits != null || spec.compact) {
+				options.minimumFractionDigits = 0;
+				options.maximumFractionDigits = spec.digits ?? (spec.compact ? 1 : 0);
+			}
+			return options;
+		}
+		default: return { maximumFractionDigits: spec.digits ?? 2 };
+	}
+}
+function getNumberFormat(spec, locale, extra) {
+	const resolvedLocale = spec.locale ?? locale;
+	const options = {
+		...numberOptions(spec),
+		...extra
+	};
+	const key = `${resolvedLocale ?? ""}|${JSON.stringify(options)}`;
+	let formatter = numberFormatCache.get(key);
+	if (!formatter) {
+		try {
+			formatter = new Intl.NumberFormat(resolvedLocale, options);
+		} catch {
+			formatter = new Intl.NumberFormat(void 0, { maximumFractionDigits: 2 });
+		}
+		numberFormatCache.set(key, formatter);
+	}
+	return formatter;
+}
+/**
+* Formats a number through the grammar above. `extra` merges Intl options on
+* top (deltas pass `{ signDisplay: "exceptZero" }`); a missing or non-finite
+* value renders as `MISSING_VALUE`.
+*/
+function formatNumber(value, format = "number", locale, extra) {
+	if (value == null || !Number.isFinite(value)) return "—";
+	return getNumberFormat(parseArcNumberFormat(format), locale, extra).format(value);
+}
+function toDate(value) {
+	return value instanceof Date ? value : new Date(value);
+}
+const TIME_OPTIONS = {
+	day: {
+		day: "numeric",
+		month: "short",
+		year: "numeric"
+	},
+	month: {
+		month: "short",
+		year: "numeric"
+	},
+	year: { year: "numeric" },
+	time: {
+		hour: "2-digit",
+		minute: "2-digit"
+	},
+	datetime: {
+		day: "numeric",
+		month: "short",
+		year: "numeric",
+		hour: "2-digit",
+		minute: "2-digit"
+	},
+	"day-short": {
+		day: "numeric",
+		month: "short"
+	},
+	"day-time": {
+		day: "numeric",
+		month: "short",
+		hour: "numeric"
+	},
+	"month-short": { month: "short" }
+};
+/**
+* Formats a date at a granularity. `timeZone` defaults to the runtime's; pass
+* it explicitly wherever output must be deterministic (Chromatic, tests, or a
+* product that reports in one business time zone).
+*/
+function formatDate(value, { granularity = "day", locale, timeZone } = {}) {
+	if (value == null) return "—";
+	const date = toDate(value);
+	if (Number.isNaN(date.getTime())) return "—";
+	return getDateFormat(granularity, locale, timeZone).format(date);
+}
+function getDateFormat(granularity, locale, timeZone) {
+	const key = `${locale ?? ""}|${timeZone ?? ""}|${granularity}`;
+	let formatter = dateFormatCache.get(key);
+	if (!formatter) {
+		try {
+			formatter = new Intl.DateTimeFormat(locale, {
+				...TIME_OPTIONS[granularity],
+				timeZone
+			});
+		} catch {
+			formatter = new Intl.DateTimeFormat(void 0, TIME_OPTIONS[granularity]);
+		}
+		dateFormatCache.set(key, formatter);
+	}
+	return formatter;
+}
+/**
+* Formats a period between two dates at a granularity, collapsing the parts
+* they share the way the locale does — `Aug 7 – 9, 2026`, `Aug 28 – Sep 8,
+* 2026`, `7–9 ส.ค. 2026` — through `Intl.DateTimeFormat.formatRange`, with
+* `start – end` as the fallback where a runtime lacks it. The bounds may come
+* in either order; an unparseable bound renders as `MISSING_VALUE`.
+*/
+function formatDateRange(start, end, { granularity = "day", locale, timeZone } = {}) {
+	if (start == null || end == null) return "—";
+	const a = toDate(start);
+	const b = toDate(end);
+	if (Number.isNaN(a.getTime()) || Number.isNaN(b.getTime())) return "—";
+	const [from, to] = a.getTime() <= b.getTime() ? [a, b] : [b, a];
+	const formatter = getDateFormat(granularity, locale, timeZone);
+	if (typeof formatter.formatRange === "function") try {
+		return formatter.formatRange(from, to);
+	} catch {}
+	return `${formatter.format(from)} – ${formatter.format(to)}`;
+}
+/**
+* Formats the change between two readings with the sign always shown. A
+* relative change from zero is undefined, so `mode: "percent"` renders the
+* absolute difference instead (and says so in `renderedMode`). An absolute
+* delta of a percent-formatted value is in percentage points — never "-7%"
+* for churn going from 4.1% to 3.8%.
+*/
+function formatDelta(current, previous, { mode = "percent", format = "number", locale, digits = 1, pointsSuffix = " pp" } = {}) {
+	const absolute = current - previous;
+	const direction = absolute > 0 ? "up" : absolute < 0 ? "down" : "flat";
+	const percent = previous === 0 ? null : absolute / Math.abs(previous);
+	const signed = { signDisplay: "exceptZero" };
+	if (mode === "percent" && percent != null) return {
+		direction,
+		percent,
+		absolute,
+		renderedMode: "percent",
+		text: formatNumber(percent, `percent:${digits}`, locale, signed)
+	};
+	const valueSpec = parseArcNumberFormat(format);
+	return {
+		direction,
+		percent,
+		absolute,
+		renderedMode: "absolute",
+		text: valueSpec.kind === "percent" ? `${formatNumber(absolute * 100, `number:${valueSpec.digits ?? 1}`, locale, signed)}${pointsSuffix}` : formatNumber(absolute, format, locale, signed)
+	};
+}
+let registered = false;
+/**
+* Registers `arcNumber`, `arcTime` and the responsive axis helpers
+* `arcAxisTicks` / `arcAxisLabelAlign` as Vega expression functions, once.
+* Takes `vega.expressionFunction` as an argument so this module never imports
+* the engine itself; the engine-bound modules call it at load time, before the
+* first `parse` — Vega requires that. Returns whether this call did the
+* registering.
+*
+* Both axis helpers take `(domain, width, discrete, format, kind, anchors?)`:
+* `kind` picks the label formatter (`time` → `arcTime`, `number` →
+* `arcNumber`, else the raw category), and `anchors` — a highlighted window's
+* `[start, end]` — switches from evenly spaced labels to the window's bounds.
+*/
+function registerArcFormatters(expressionFunction) {
+	if (registered) return false;
+	registered = true;
+	const arcNumber = (value, format) => formatNumber(typeof value === "number" ? value : Number(value), String(format ?? "number"));
+	const arcTime = (value, format) => formatDate(value, parseArcTimeFormat(String(format ?? "day")));
+	const labelFormatter = (format, kind) => (value) => kind === "time" ? arcTime(value, format) : kind === "number" ? arcNumber(value, format) : String(value);
+	const arcAxisTicks = (domain, width, discrete, format, kind, anchors) => selectAxisTicks(domain, width, discrete, labelFormatter(format, kind), anchors);
+	const arcAxisLabelAlign = (value, domain, width, discrete, format, kind, anchors) => axisLabelAlign(value, domain, width, discrete, labelFormatter(format, kind), anchors);
+	expressionFunction("arcNumber", arcNumber);
+	expressionFunction("arcTime", arcTime);
+	expressionFunction("arcAxisTicks", arcAxisTicks);
+	expressionFunction("arcAxisLabelAlign", arcAxisLabelAlign);
+	return true;
+}
+//#endregion
+export { MISSING_VALUE, formatDate, formatDateRange, formatDelta, formatNumber, parseArcNumberFormat, parseArcTimeFormat, registerArcFormatters };

package/dist/lib/vega/index.d.ts

@@ -0,0 +1,11 @@
+import { ArcDeltaDirection, ArcDeltaMode, ArcNumberFormatKind, ArcNumberFormatSpec, ArcTimeFormatSpec, ArcTimeGranularity, FormatDeltaOptions, FormattedDelta, MISSING_VALUE, formatDate, formatDateRange, formatDelta, formatNumber, parseArcNumberFormat, parseArcTimeFormat, registerArcFormatters } from "./formatters.js";
+import { ChartTokens, readChartTokens, useChartTokens } from "./tokens.js";
+import { ArcVegaConfigOptions, arcVegaConfig } from "./config.js";
+import { ZonedParts, resolveInstant, timeZoneOffsetMs, zonedDayStart, zonedMidnight, zonedParts } from "./time.js";
+import { ArcTooltipContext, ArcTooltipHandle, ArcTooltipRows, UseArcTooltipHandlerOptions, useArcTooltipHandler } from "./tooltip.js";
+import { ArcEmbedOptionsInput, VEGA_WARN, arcEmbedOptions } from "./embed.js";
+import { ArcVegaDatasets, UseArcVegaParams } from "./useArcVega.js";
+import { ArcVegaSurfaceProps } from "./ArcVegaSurface.js";
+import { ArcEngine, getLoadedEngine, loadEngine } from "./load.js";
+import { ArcVegaChart, ArcVegaChartProps, useArcEngine } from "./ArcVegaChart.js";
+export { type ArcDeltaDirection, type ArcDeltaMode, type ArcEmbedOptionsInput, type ArcEngine, type ArcNumberFormatKind, type ArcNumberFormatSpec, type ArcTimeFormatSpec, type ArcTimeGranularity, type ArcTooltipContext, type ArcTooltipHandle, ArcTooltipRows, ArcVegaChart, type ArcVegaChartProps, type ArcVegaConfigOptions, type ArcVegaDatasets, type ArcVegaSurfaceProps, type ChartTokens, type FormatDeltaOptions, type FormattedDelta, MISSING_VALUE, type UseArcTooltipHandlerOptions, type UseArcVegaParams, VEGA_WARN, type ZonedParts, arcEmbedOptions, arcVegaConfig, formatDate, formatDateRange, formatDelta, formatNumber, getLoadedEngine, loadEngine, parseArcNumberFormat, parseArcTimeFormat, readChartTokens, registerArcFormatters, resolveInstant, timeZoneOffsetMs, useArcEngine, useArcTooltipHandler, useChartTokens, zonedDayStart, zonedMidnight, zonedParts };

package/dist/lib/vega/load.d.ts

@@ -0,0 +1,13 @@
+import { engine_d_exports } from "./engine.js";
+//#region src/lib/vega/load.d.ts
+type ArcEngine = typeof engine_d_exports;
+/**
+ * Loads the engine chunk once and shares the promise. Components render their
+ * frame, title and `Skeleton` immediately and mount the chart when this
+ * resolves.
+ */
+declare function loadEngine(): Promise<ArcEngine>;
+/** The engine if a previous `loadEngine()` already resolved — lets later mounts skip the fallback frame. */
+declare function getLoadedEngine(): ArcEngine | null;
+//#endregion
+export { ArcEngine, getLoadedEngine, loadEngine };

package/dist/lib/vega/load.js

@@ -0,0 +1,21 @@
+//#region src/lib/vega/load.ts
+let pending = null;
+let resolved = null;
+/**
+* Loads the engine chunk once and shares the promise. Components render their
+* frame, title and `Skeleton` immediately and mount the chart when this
+* resolves.
+*/
+function loadEngine() {
+	pending ??= import("./engine.js").then((engine) => {
+		resolved = engine;
+		return engine;
+	});
+	return pending;
+}
+/** The engine if a previous `loadEngine()` already resolved — lets later mounts skip the fallback frame. */
+function getLoadedEngine() {
+	return resolved;
+}
+//#endregion
+export { getLoadedEngine, loadEngine };