@delacour/react-native-ui 0.5.0 → 0.6.0-alpha.20261030084745

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.5.0",
+	"version": "0.6.0-alpha.20261030084745",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -175,15 +175,14 @@
 	},
 	"dependencies": {
 		"cn": "^0.5.0",
-		"tailwind-merge": "^3.6.0",
-		"tailwind-variants": "^3.3.1"
+		"tailwind-variants": "^4.0.0"
 	},
 	"peerDependencies": {
 		"expo-blur": ">=15",
 		"@maplibre/maplibre-react-native": "^11.5.0",
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-bottom-sheet": ">=0.3.0",
-		"@delacour/react-native-charts": ">=0.2.0",
+		"@delacour/react-native-bottom-sheet": "0.6.0-alpha.20261030084745",
+		"@delacour/react-native-charts": "0.6.0-alpha.20261030084745",
 		"@legendapp/list": ">=3.3",
 		"react-native-skia": ">=3.7.3",
 		"expo-linear-gradient": ">=15",
@@ -243,6 +242,7 @@
 		"@types/react": "catalog:",
 		"expo-router": "~58.0.24",
 		"react-native-teleport": "^1.2.2",
+		"tailwind-merge": "^3.6.0",
 		"typescript": "~6.0.3"
 	}
 }

package/src/cn.parity.test.ts

@@ -11,8 +11,8 @@ import { type CustomClassGroupId, TW_MERGE_CONFIG } from "./styles/tokens";
  * `cn` promises tailwind-merge's output for every input; this holds it to that
  * on the strings that matter here — every class literal in a `*.variants.ts`,
  * merged pairwise with a caller-style override, through the same
- * `TW_MERGE_CONFIG`. tailwind-merge stays installed as `tailwind-variants`'
- * peer, which is what makes the reference available.
+ * `TW_MERGE_CONFIG`. tailwind-merge is a dev dependency for this alone:
+ * tailwind-variants v4 compiles its own tables and no longer peers on it.
  */
 const reference = extendTailwindMerge<CustomClassGroupId>(TW_MERGE_CONFIG);
 

package/src/components/kpi/kpi-icon.tsx

@@ -15,7 +15,7 @@ import { kpiVariants } from "./kpi.variants";
  */
 export function KpiIcon({ className, children, ...props }: KpiSlotProps): ReactElement {
 	const { size, colorIndex } = useKpiPart("Kpi.Icon");
-	const slots = kpiVariants({ colorIndex, size });
+	const slots = kpiVariants({ colorIndex: `${colorIndex}`, size });
 	const glyph = slots.iconGlyph();
 	const defaults = useMemo(() => ({ className: glyph, color: `chart-${colorIndex}` }), [glyph, colorIndex]);
 

package/src/components/kpi/kpi.variants.test.ts

@@ -25,7 +25,7 @@ function everyCombination(): ReturnType<typeof kpiVariants>[] {
 		KPI_LAYOUTS.flatMap((layout) =>
 			KPI_TONES.flatMap((tone) =>
 				KPI_COLOR_INDEXES.flatMap((colorIndex) =>
-					CARD_PLANES.map((plane) => kpiVariants({ colorIndex, layout, plane, size, tone }))
+					CARD_PLANES.map((plane) => kpiVariants({ colorIndex: `${colorIndex}`, layout, plane, size, tone }))
 				)
 			)
 		)
@@ -344,7 +344,7 @@ describe("kpiVariants trend", () => {
 describe("kpiVariants icon", () => {
 	test("tints the icon square from the series ramp, one token per colour index", () => {
 		for (const colorIndex of KPI_COLOR_INDEXES) {
-			expect(kpiVariants({ colorIndex }).icon()).toContain(`bg-chart-${colorIndex}/15`);
+			expect(kpiVariants({ colorIndex: `${colorIndex}` }).icon()).toContain(`bg-chart-${colorIndex}/15`);
 		}
 	});
 

package/src/components/kpi/kpi.variants.ts

@@ -143,11 +143,11 @@ export const kpiVariants = tv({
 			neutral: { trendText: "text-muted-foreground" },
 		},
 		colorIndex: {
-			1: { icon: "bg-chart-1/15" },
-			2: { icon: "bg-chart-2/15" },
-			3: { icon: "bg-chart-3/15" },
-			4: { icon: "bg-chart-4/15" },
-			5: { icon: "bg-chart-5/15" },
+			"1": { icon: "bg-chart-1/15" },
+			"2": { icon: "bg-chart-2/15" },
+			"3": { icon: "bg-chart-3/15" },
+			"4": { icon: "bg-chart-4/15" },
+			"5": { icon: "bg-chart-5/15" },
 		},
 		layout: {
 			below: { sparkline: "w-full" },
@@ -180,7 +180,7 @@ export const kpiVariants = tv({
 		size: "md",
 		plane: "default",
 		tone: "neutral",
-		colorIndex: 1,
+		colorIndex: "1",
 		layout: "below",
 		orientation: "vertical",
 		separated: false,

package/src/components/leaderboard/leaderboard-podium-place.tsx

@@ -76,7 +76,7 @@ function LeaderboardPodiumBar({
 	}, [delay, grown, height, isReducedMotion]);
 
 	const style = useAnimatedStyle(() => ({ height: grown.value }));
-	const slots = leaderboardVariants({ place });
+	const slots = leaderboardVariants({ place: `${place}` });
 
 	return (
 		<Animated.View className={slots.podiumBar()} style={style}>
@@ -103,7 +103,7 @@ export function LeaderboardPodiumPlace(props: LeaderboardPodiumPlaceProps): Reac
 	const { entry, rank } = ranked;
 	const place = resolvePodiumPlace(rank);
 	const isHighlighted = entry.id === highlightId;
-	const slots = leaderboardVariants({ isHighlighted, place });
+	const slots = leaderboardVariants({ isHighlighted, place: `${place}` });
 	const formattedValue = formatValue(entry.value);
 	const accessibilityLabel = resolveLeaderboardAccessibilityLabel({ formattedValue, ranked, unit });
 	const media = renderMedia?.(entry, rank);

package/src/components/leaderboard/leaderboard.variants.test.ts

@@ -455,10 +455,10 @@ describe("leaderboardVariants", () => {
 	});
 
 	test("the three bar tones are primary at 100 / 70 / 45 percent — never a metal", () => {
-		expect(leaderboardVariants({ place: 1 }).podiumBar()).toMatch(/\bbg-primary(\s|$)/);
-		expect(leaderboardVariants({ place: 2 }).podiumBar()).toContain("bg-primary/70");
-		expect(leaderboardVariants({ place: 3 }).podiumBar()).toContain("bg-primary/45");
-		for (const place of [1, 2, 3] as const) {
+		expect(leaderboardVariants({ place: "1" }).podiumBar()).toMatch(/\bbg-primary(\s|$)/);
+		expect(leaderboardVariants({ place: "2" }).podiumBar()).toContain("bg-primary/70");
+		expect(leaderboardVariants({ place: "3" }).podiumBar()).toContain("bg-primary/45");
+		for (const place of ["1", "2", "3"] as const) {
 			expect(leaderboardVariants({ place }).podiumBar()).not.toMatch(/gold|silver|bronze|amber|yellow|orange/);
 		}
 	});
@@ -478,8 +478,8 @@ describe("leaderboardVariants", () => {
 	});
 
 	test("the cards podium raises the leader by 12pt", () => {
-		expect(leaderboardVariants({ place: 1 }).podiumCard()).toContain("mb-3");
-		expect(leaderboardVariants({ place: 2 }).podiumCard()).not.toContain("mb-3");
+		expect(leaderboardVariants({ place: "1" }).podiumCard()).toContain("mb-3");
+		expect(leaderboardVariants({ place: "2" }).podiumCard()).not.toContain("mb-3");
 	});
 
 	test("no view slot carries a text colour or size (rule 1)", () => {
@@ -499,7 +499,7 @@ describe("leaderboardVariants", () => {
 		] as const;
 		for (const isHighlighted of [true, false]) {
 			for (const place of [1, 2, 3] as const) {
-				const variant = leaderboardVariants({ isHighlighted, place });
+				const variant = leaderboardVariants({ isHighlighted, place: `${place}` });
 				for (const slot of viewSlots) {
 					expect(variant[slot]()).not.toMatch(/\btext-(?!center|left|right)/);
 				}

package/src/components/leaderboard/leaderboard.variants.ts

@@ -80,9 +80,9 @@ export const leaderboardVariants = tv({
 	},
 	variants: {
 		place: {
-			1: { podiumBar: "bg-primary", podiumCard: "mb-3", podiumCardRank: "bg-primary" },
-			2: { podiumBar: "bg-primary/70", podiumCardRank: "bg-primary/70" },
-			3: { podiumBar: "bg-primary/45", podiumCardRank: "bg-primary/45" },
+			"1": { podiumBar: "bg-primary", podiumCard: "mb-3", podiumCardRank: "bg-primary" },
+			"2": { podiumBar: "bg-primary/70", podiumCardRank: "bg-primary/70" },
+			"3": { podiumBar: "bg-primary/45", podiumCardRank: "bg-primary/45" },
 		},
 		isHighlighted: {
 			true: { row: "bg-primary/10", podiumCard: "border-primary" },

package/src/components/planner/planner-day.tsx

@@ -214,13 +214,13 @@ function distinctColors(
 
 /** The class that paints a colour as a fill, or `undefined` for a literal, which is painted by style. */
 function swatchClass(color: PlannerEntryColor): string | undefined {
-	if (color.kind === "chart") return plannerVariants({ colorIndex: color.index }).swatch();
+	if (color.kind === "chart") return plannerVariants({ colorIndex: `${color.index}` }).swatch();
 	return color.kind === "default" ? "bg-primary" : undefined;
 }
 
 /** The same colour at 15%, for a block or tile behind text — `undefined` for a literal. */
 function tintClass(color: PlannerEntryColor): string | undefined {
-	if (color.kind === "chart") return plannerVariants({ colorIndex: color.index }).tint();
+	if (color.kind === "chart") return plannerVariants({ colorIndex: `${color.index}` }).tint();
 	return color.kind === "default" ? "bg-primary/15" : undefined;
 }
 

package/src/components/planner/planner-legend.tsx

@@ -39,7 +39,7 @@ export function PlannerLegend({ counts = false, className, children, ...props }:
 						<View
 							className={cn(
 								slots.legendDot(),
-								color.kind === "chart" ? plannerVariants({ colorIndex: color.index }).swatch() : undefined,
+								color.kind === "chart" ? plannerVariants({ colorIndex: `${color.index}` }).swatch() : undefined,
 								color.kind === "default" ? "bg-primary" : undefined
 							)}
 							style={color.kind === "literal" ? { backgroundColor: color.color } : undefined}

package/src/components/planner/planner.variants.test.ts

@@ -291,7 +291,7 @@ describe("plannerVariants", () => {
 	test("every colour token named by a slot exists in both themes", () => {
 		const used = new Set<string>();
 		for (const colorIndex of PLANNER_COLOR_INDEXES) {
-			for (const slots of [...everyCombination(), plannerVariants({ colorIndex })]) {
+			for (const slots of [...everyCombination(), plannerVariants({ colorIndex: `${colorIndex}` })]) {
 				for (const fn of Object.values(slots)) {
 					for (const match of (fn() ?? "").matchAll(
 						/(?:^|\s)(?:bg|text|border)-([a-z][a-z0-9-]*?)(?:\/\d+)?(?=\s|$)/g
@@ -347,8 +347,8 @@ describe("plannerVariants", () => {
 
 	test("a chart tint class exists for every colour slot", () => {
 		for (const colorIndex of PLANNER_COLOR_INDEXES) {
-			expect(plannerVariants({ colorIndex }).swatch()).toContain(`bg-chart-${colorIndex}`);
-			expect(plannerVariants({ colorIndex }).tint()).toContain(`bg-chart-${colorIndex}/15`);
+			expect(plannerVariants({ colorIndex: `${colorIndex}` }).swatch()).toContain(`bg-chart-${colorIndex}`);
+			expect(plannerVariants({ colorIndex: `${colorIndex}` }).tint()).toContain(`bg-chart-${colorIndex}/15`);
 		}
 	});
 });

package/src/components/planner/planner.variants.ts

@@ -127,11 +127,11 @@ export const plannerVariants = tv({
 			false: {},
 		},
 		colorIndex: {
-			1: { swatch: "bg-chart-1", tint: "bg-chart-1/15" },
-			2: { swatch: "bg-chart-2", tint: "bg-chart-2/15" },
-			3: { swatch: "bg-chart-3", tint: "bg-chart-3/15" },
-			4: { swatch: "bg-chart-4", tint: "bg-chart-4/15" },
-			5: { swatch: "bg-chart-5", tint: "bg-chart-5/15" },
+			"1": { swatch: "bg-chart-1", tint: "bg-chart-1/15" },
+			"2": { swatch: "bg-chart-2", tint: "bg-chart-2/15" },
+			"3": { swatch: "bg-chart-3", tint: "bg-chart-3/15" },
+			"4": { swatch: "bg-chart-4", tint: "bg-chart-4/15" },
+			"5": { swatch: "bg-chart-5", tint: "bg-chart-5/15" },
 		},
 	},
 	compoundVariants: [

package/src/components/text-animation/AGENTS.md

@@ -110,7 +110,12 @@ scope — it is an input, not a text effect.
   `0`, which is what a position of 9.5 shows half of.
 - **Wheels are keyed by their place from the right.** 999 → 1000 keeps three
   wheels and mounts a fourth, which rolls up from 0. Least-significant first,
-  `stagger` ms apart. Separators, sign, prefix and suffix are static cells.
+  `stagger` ms apart. Separators and the sign are static cells.
+- **An affix is one static cell, digits and all.** `resolveNumberCells` splits
+  the reading through `formatNumberParts`, so only the body is cut into wheels —
+  `suffix="/100"` and `prefix="Q3 "` never roll. `prefix` / `suffix` are props on
+  both numeric parts as well as `format` fields; `resolveNumberFormat` folds
+  them in, a prop winning.
 - **The wheel height is measured, never fixed.** One hidden digit reports the line
   height every wheel offsets by, so the odometer follows font scaling. Until it
   has, the strips are hidden.

package/src/components/text-animation/index.ts

@@ -3,10 +3,14 @@ export type { TextAnimationBase } from "./text-animation.types";
 export {
 	buildTypingTimeline,
 	formatNumber,
+	formatNumberParts,
+	type NumberParts,
 	resolveCaretClass,
 	resolveCaretOpacity,
 	resolveEffectFrame,
 	resolveNextPhrase,
+	resolveNumberCells,
+	resolveNumberFormat,
 	resolveRollTarget,
 	resolveStaggerDelay,
 	resolveTotalDuration,

package/src/components/text-animation/text-animation-counting.tsx

@@ -13,6 +13,7 @@ import { cn } from "../../lib/cn";
 import type { TextAnimationBase } from "./text-animation.types";
 import {
 	formatNumber,
+	resolveNumberFormat,
 	TEXT_ANIMATION_COUNT_DURATION_MS,
 	type TextAnimationNumberFormat,
 	textAnimationVariants,
@@ -28,6 +29,10 @@ export type TextAnimationCountingProps = TextAnimationBase & {
 	from?: number;
 	/** Grouping, decimals, prefix and suffix. */
 	format?: TextAnimationNumberFormat;
+	/** Text before the number, after any sign — `−$5`. Never rolls or tweens. Wins over `format.prefix`. */
+	prefix?: string;
+	/** Text after the number — `%`, ` kg`, `/100`. Never rolls or tweens. Wins over `format.suffix`. */
+	suffix?: string;
 	/** The tween, ms. Default 900. */
 	durationMs?: number;
 	/** Default `out`. */
@@ -82,6 +87,8 @@ export function TextAnimationCounting({
 	value,
 	from = 0,
 	format,
+	prefix,
+	suffix,
 	durationMs = TEXT_ANIMATION_COUNT_DURATION_MS,
 	easing = "out",
 	animateOnMount = true,
@@ -104,7 +111,10 @@ export function TextAnimationCounting({
 		"tabular-nums"
 	);
 	// biome-ignore lint/correctness/useExhaustiveDependencies: the format's fields are its identity
-	const stableFormat = useMemo<TextAnimationNumberFormat>(() => format ?? {}, [JSON.stringify(format ?? {})]);
+	const stableFormat = useMemo<TextAnimationNumberFormat>(
+		() => resolveNumberFormat(format, prefix, suffix),
+		[JSON.stringify(format ?? {}), prefix, suffix]
+	);
 	const start = animateOnMount && !isCalm ? from : value;
 	const shown = useSharedValue(start);
 	const target = formatNumber(value, stableFormat);

package/src/components/text-animation/text-animation-rolling.tsx

@@ -14,10 +14,11 @@ import type { TextAnimationBase } from "./text-animation.types";
 import {
 	formatNumber,
 	type RollDirection,
+	resolveNumberCells,
+	resolveNumberFormat,
 	resolveRollDirection,
 	resolveRollTarget,
 	resolveWheelOffset,
-	splitNumberCells,
 	TEXT_ANIMATION_ROLL_DURATION_MS,
 	TEXT_ANIMATION_ROLL_STAGGER,
 	type TextAnimationNumberFormat,
@@ -30,6 +31,10 @@ export type TextAnimationRollingProps = TextAnimationBase & {
 	value: number;
 	/** Grouping, decimals, prefix and suffix. Separators render static; only digits roll. */
 	format?: TextAnimationNumberFormat;
+	/** Text before the number, after any sign — `−$5`. Never rolls or tweens. Wins over `format.prefix`. */
+	prefix?: string;
+	/** Text after the number — `%`, ` kg`, `/100`. Never rolls or tweens. Wins over `format.suffix`. */
+	suffix?: string;
 	/** One wheel's roll, ms. Default 600. */
 	durationMs?: number;
 	/** Delay between wheels, least significant first, ms. Default 40. */
@@ -134,14 +139,17 @@ TextAnimationWheel.displayName = "DelacourUI.TextAnimation.Wheel";
  * An odometer: each digit is a wheel that rolls to its new digit.
  *
  * Wheels are keyed by their place from the right, so 999 → 1000 keeps the
- * three wheels it had and mounts a fourth, which rolls up from 0. Separators,
- * the sign, the prefix and the suffix are static cells. Every glyph is set in
+ * three wheels it had and mounts a fourth, which rolls up from 0. Separators
+ * and the sign are static cells; the prefix and the suffix are one static cell
+ * each, so a digit inside one never rolls. Every glyph is set in
  * tabular figures, so no digit is wider than another and nothing jitters
  * sideways mid-roll. Under calm motion each wheel lands at once.
  */
 export function TextAnimationRolling({
 	value,
 	format,
+	prefix,
+	suffix,
 	durationMs = TEXT_ANIMATION_ROLL_DURATION_MS,
 	stagger = TEXT_ANIMATION_ROLL_STAGGER,
 	variant,
@@ -163,8 +171,12 @@ export function TextAnimationRolling({
 		"tabular-nums"
 	);
 	// biome-ignore lint/correctness/useExhaustiveDependencies: the format's fields are its identity
-	const formatted = useMemo(() => formatNumber(value, format ?? {}), [value, JSON.stringify(format ?? {})]);
-	const cells = useMemo(() => splitNumberCells(formatted), [formatted]);
+	const resolvedFormat = useMemo(
+		() => resolveNumberFormat(format, prefix, suffix),
+		[JSON.stringify(format ?? {}), prefix, suffix]
+	);
+	const formatted = useMemo(() => formatNumber(value, resolvedFormat), [value, resolvedFormat]);
+	const cells = useMemo(() => resolveNumberCells(value, resolvedFormat), [value, resolvedFormat]);
 
 	const [direction, setDirection] = useState<{ value: number; direction: RollDirection }>({
 		value,

package/src/components/text-animation/text-animation.variants.test.ts

@@ -2,11 +2,14 @@ import { describe, expect, test } from "bun:test";
 import {
 	buildTypingTimeline,
 	formatNumber,
+	formatNumberParts,
 	hashText,
 	resolveCaretClass,
 	resolveCaretOpacity,
 	resolveEffectFrame,
 	resolveNextPhrase,
+	resolveNumberCells,
+	resolveNumberFormat,
 	resolveRollDirection,
 	resolveRollTarget,
 	resolveRowJustify,
@@ -478,6 +481,65 @@ describe("splitNumberCells", () => {
 	});
 });
 
+describe("formatNumberParts", () => {
+	test("splits a reading into sign, prefix, body and suffix", () => {
+		expect(formatNumberParts(-1234.5, { decimals: 1, prefix: "$", suffix: " NZD" })).toEqual({
+			sign: "−",
+			prefix: "$",
+			body: "1,234.5",
+			suffix: " NZD",
+		});
+	});
+
+	test("joined, the parts are formatNumber", () => {
+		const format = { decimals: 2, prefix: "~", suffix: "%" };
+		const parts = formatNumberParts(-42.125, format);
+		expect(`${parts.sign}${parts.prefix}${parts.body}${parts.suffix}`).toBe(formatNumber(-42.125, format));
+	});
+
+	test("a value with no number keeps its affixes off the dash", () => {
+		expect(formatNumberParts(Number.NaN, { prefix: "$" })).toEqual({ sign: "", prefix: "", body: "—", suffix: "" });
+	});
+});
+
+describe("resolveNumberFormat", () => {
+	test("a prop affix wins over the format's", () => {
+		expect(resolveNumberFormat({ prefix: "$", suffix: "%", decimals: 1 }, "€", undefined)).toEqual({
+			prefix: "€",
+			suffix: "%",
+			decimals: 1,
+		});
+	});
+
+	test("no format and no affix is an empty format", () => {
+		expect(resolveNumberFormat(undefined, undefined, undefined)).toEqual({});
+	});
+});
+
+describe("resolveNumberCells", () => {
+	// "/100" rolled as three wheels before: an affix is text, not a reading.
+	test("an affix is one static cell, digits and all", () => {
+		expect(resolveNumberCells(72, { prefix: "Q3 ", suffix: "/100" })).toEqual([
+			{ kind: "static", text: "Q3 " },
+			{ kind: "digit", digit: 7 },
+			{ kind: "digit", digit: 2 },
+			{ kind: "static", text: "/100" },
+		]);
+	});
+
+	test("the sign sits ahead of the prefix", () => {
+		expect(resolveNumberCells(-5, { prefix: "$" })).toEqual([
+			{ kind: "static", text: "−" },
+			{ kind: "static", text: "$" },
+			{ kind: "digit", digit: 5 },
+		]);
+	});
+
+	test("no affix is the body's cells alone", () => {
+		expect(resolveNumberCells(1248, {})).toEqual(splitNumberCells("1,248"));
+	});
+});
+
 describe("resolveCaretClass", () => {
 	test("a bar is a thin column, a block a translucent fill, both on the text's own colour", () => {
 		expect(resolveCaretClass("bar")).toContain("bg-foreground");

package/src/components/text-animation/text-animation.variants.ts

@@ -77,6 +77,9 @@ export type TypingSample = { phraseIndex: number; visibleCount: number; phase: T
 
 export type EffectFrame = { opacity: number; translateX: number; translateY: number; scale: number };
 
+/** A formatted reading in its four pieces, so a part can treat the affixes as text rather than digits. */
+export type NumberParts = { sign: string; prefix: string; body: string; suffix: string };
+
 export type NumberCell = { kind: "digit"; digit: number } | { kind: "static"; text: string };
 
 export type RollDirection = "up" | "down";
@@ -511,17 +514,15 @@ function groupDigits(whole: string, separator: string): string {
 }
 
 /**
- * Writes a number with grouping, fixed decimals, a prefix and a suffix.
+ * {@link formatNumber}, unjoined. A value with no number is the dash alone, affixes dropped.
  *
- * A worklet: `Counting` calls it on the UI thread every frame, where Hermes
- * has no `Intl`, so grouping is done by hand. Rounding is `toFixed`'s, half
- * cases included. A negative takes a true minus sign ahead of the prefix
- * (`−$5`); one that rounds to zero takes none. `NaN` and the infinities are
- * written {@link TEXT_ANIMATION_NO_VALUE}.
+ * Declared above `formatNumber` on purpose: the worklets plugin turns a
+ * worklet into a value that captures what it calls when it is defined, so a
+ * worklet declared below its caller is captured as `undefined`.
  */
-export function formatNumber(value: number, format: TextAnimationNumberFormat): string {
+export function formatNumberParts(value: number, format: TextAnimationNumberFormat): NumberParts {
 	"worklet";
-	if (!Number.isFinite(value)) return "\u2014";
+	if (!Number.isFinite(value)) return { sign: "", prefix: "", body: TEXT_ANIMATION_NO_VALUE, suffix: "" };
 	const decimals = Math.max(0, Math.min(20, Math.floor(format.decimals ?? 0)));
 	const groupSeparator = format.groupSeparator ?? ",";
 	const decimalSeparator = format.decimalSeparator ?? ".";
@@ -537,7 +538,34 @@ export function formatNumber(value: number, format: TextAnimationNumberFormat):
 	// U+2212, a true minus — the width of a plus and of a tabular digit — rather than a hyphen.
 	const sign = value < 0 && !isZero ? "\u2212" : "";
 	const body = fraction === "" ? grouped : `${grouped}${decimalSeparator}${fraction}`;
-	return `${sign}${format.prefix ?? ""}${body}${format.suffix ?? ""}`;
+	return { sign, prefix: format.prefix ?? "", body, suffix: format.suffix ?? "" };
+}
+
+/**
+ * Writes a number with grouping, fixed decimals, a prefix and a suffix.
+ *
+ * A worklet: `Counting` calls it on the UI thread every frame, where Hermes
+ * has no `Intl`, so grouping is done by hand. Rounding is `toFixed`'s, half
+ * cases included. A negative takes a true minus sign ahead of the prefix
+ * (`−$5`); one that rounds to zero takes none. `NaN` and the infinities are
+ * written {@link TEXT_ANIMATION_NO_VALUE}.
+ */
+export function formatNumber(value: number, format: TextAnimationNumberFormat): string {
+	"worklet";
+	const parts = formatNumberParts(value, format);
+	return `${parts.sign}${parts.prefix}${parts.body}${parts.suffix}`;
+}
+
+/** The `prefix` / `suffix` props folded into `format` — a prop wins over the format's own. */
+export function resolveNumberFormat(
+	format: TextAnimationNumberFormat | undefined,
+	prefix: string | undefined,
+	suffix: string | undefined
+): TextAnimationNumberFormat {
+	const resolved: TextAnimationNumberFormat = { ...format };
+	if (prefix !== undefined) resolved.prefix = prefix;
+	if (suffix !== undefined) resolved.suffix = suffix;
+	return resolved;
 }
 
 /**
@@ -577,3 +605,17 @@ export function splitNumberCells(formatted: string): readonly NumberCell[] {
 	}
 	return cells;
 }
+
+/**
+ * A reading as `Rolling`'s cells. The sign, the prefix and the suffix are one
+ * static cell each, so a digit in an affix — `/100`, `Q3 ` — never rolls.
+ */
+export function resolveNumberCells(value: number, format: TextAnimationNumberFormat): readonly NumberCell[] {
+	const parts = formatNumberParts(value, format);
+	const cells: NumberCell[] = [];
+	if (parts.sign !== "") cells.push({ kind: "static", text: parts.sign });
+	if (parts.prefix !== "") cells.push({ kind: "static", text: parts.prefix });
+	cells.push(...splitNumberCells(parts.body));
+	if (parts.suffix !== "") cells.push({ kind: "static", text: parts.suffix });
+	return cells;
+}

package/src/lib/tv.ts

@@ -1,4 +1,4 @@
-import { createTV } from "tailwind-variants";
+import { createTV } from "tailwind-variants/config";
 import { TW_MERGE_CONFIG } from "../styles/tokens";
 
 /**
@@ -9,6 +9,9 @@ import { TW_MERGE_CONFIG } from "../styles/tokens";
  * through a tailwind-merge instance it builds itself, entirely separate from
  * the one behind `cn()`, and a bare `tv` does not know what `button-md` is.
  *
+ * `tailwind-variants/config`, not the default entry: since v4 the default
+ * entry ships only the compiled default tables and throws on `twMergeConfig`.
+ *
  * That is not a cosmetic gap. An unrecognised `text-button-md` lands in
  * tailwind-merge's text *colour* group alongside `text-primary-foreground`, the
  * two are judged to conflict, and the label loses its colour — no error, just a