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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.5.0",
+	"version": "0.6.0-alpha.20261030084636",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -182,8 +182,8 @@
 		"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.20261030084636",
+		"@delacour/react-native-charts": "0.6.0-alpha.20261030084636",
 		"@legendapp/list": ">=3.3",
 		"react-native-skia": ">=3.7.3",
 		"expo-linear-gradient": ">=15",

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;
+}