number-flow-react-native 0.1.0

package/src/core/useTimeFormatting.ts

@@ -0,0 +1,95 @@
+import { useMemo } from "react";
+import { digitPart, symbolPart, type KeyedPart } from "./types";
+
+/**
+ * Converts 24h hours (0-23) to 12h display value (1-12).
+ * 0 → 12 (12 AM), 1-12 → as-is, 13-23 → subtract 12.
+ */
+export function to12Hour(h: number): number {
+  if (h === 0) return 12;
+  if (h > 12) return h - 12;
+  return h;
+}
+
+/**
+ * Builds a time display into stably-keyed character parts.
+ *
+ * Each digit position gets a fixed semantic key (h10, h1, m10, m1, s10, s1)
+ * regardless of the actual value. This ensures correct enter/exit animation
+ * behavior — e.g. when hours go from 9→10, the h10 key *enters* (fades in)
+ * rather than shifting all existing positions.
+ */
+export function formatTimeToKeyedParts(
+  hours: number | undefined,
+  minutes: number,
+  seconds: number | undefined,
+  is24Hour: boolean,
+  padHours: boolean,
+): KeyedPart[] {
+  const parts: KeyedPart[] = [];
+
+  const hasHours = hours !== undefined;
+  const hasSeconds = seconds !== undefined;
+
+  if (hasHours) {
+    const displayHours = is24Hour ? hours : to12Hour(hours);
+
+    const h10 = Math.floor(displayHours / 10);
+    const h1 = displayHours % 10;
+
+    // Hours tens digit — only shown if >= 10 or padding is on
+    if (h10 > 0 || padHours) {
+      parts.push(digitPart("h10", h10));
+    }
+
+    parts.push(digitPart("h1", h1));
+
+    parts.push(symbolPart("sep", ":"));
+  }
+
+  const m10 = Math.floor(minutes / 10);
+  const m1 = minutes % 10;
+  parts.push(digitPart("m10", m10));
+  parts.push(digitPart("m1", m1));
+
+  if (hasSeconds) {
+    parts.push(symbolPart("sep2", ":"));
+
+    const s10 = Math.floor(seconds / 10);
+    const s1 = seconds % 10;
+    parts.push(digitPart("s10", s10));
+    parts.push(digitPart("s1", s1));
+  }
+
+  /**
+   * Each character gets a value-dependent key so AM→PM triggers exit/enter crossfade.
+   * Characters are emitted individually for correct glyph width measurement.
+   */
+  if (hasHours && !is24Hour) {
+    const label = hours < 12 ? "AM" : "PM";
+    parts.push(symbolPart("ampm-sp", " "));
+    for (let i = 0; i < label.length; i++) {
+      parts.push(symbolPart(`ampm:${label}:${i}`, label[i]));
+    }
+  }
+
+  return parts;
+}
+
+/**
+ * Hook that formats time values into stably-keyed character parts.
+ * Uses fixed positional keys (h10, h1, sep, m10, m1, etc.) instead of
+ * NumberFlow's RTL integer keying.
+ */
+export function useTimeFormatting(
+  hours: number | undefined,
+  minutes: number,
+  seconds: number | undefined,
+  is24Hour: boolean,
+  padHours: boolean,
+): KeyedPart[] {
+  return useMemo(
+    () => formatTimeToKeyedParts(hours, minutes, seconds, is24Hour, padHours),
+    [hours, minutes, seconds, is24Hour, padHours],
+  );
+}

package/src/core/useTimingResolution.ts

@@ -0,0 +1,47 @@
+import type { TimingConfig } from "./types";
+import {
+  DEFAULT_OPACITY_TIMING,
+  DEFAULT_SPIN_TIMING,
+  DEFAULT_TRANSFORM_TIMING,
+  ZERO_TIMING,
+} from "./timing";
+import { useCanAnimate } from "./useCanAnimate";
+
+interface ResolvedTimings {
+  resolvedSpinTiming: TimingConfig;
+  resolvedOpacityTiming: TimingConfig;
+  resolvedTransformTiming: TimingConfig;
+}
+
+/**
+ * Resolves animation timing based on the `animated` prop and reduced-motion preference.
+ * When animations are disabled, all timings collapse to zero-duration.
+ */
+export function useTimingResolution(
+  animated: boolean | undefined,
+  respectMotionPreference: boolean | undefined,
+  spinTiming?: TimingConfig,
+  opacityTiming?: TimingConfig,
+  transformTiming?: TimingConfig,
+): ResolvedTimings {
+  const canAnimate = useCanAnimate(respectMotionPreference);
+  const shouldAnimate = (animated ?? true) && canAnimate;
+
+  const resolvedSpinTiming = shouldAnimate
+    ? (spinTiming ?? DEFAULT_SPIN_TIMING)
+    : ZERO_TIMING;
+
+  const resolvedOpacityTiming = shouldAnimate
+    ? (opacityTiming ?? DEFAULT_OPACITY_TIMING)
+    : ZERO_TIMING;
+
+  const resolvedTransformTiming = shouldAnimate
+    ? (transformTiming ?? DEFAULT_TRANSFORM_TIMING)
+    : ZERO_TIMING;
+
+  return {
+    resolvedSpinTiming,
+    resolvedOpacityTiming,
+    resolvedTransformTiming,
+  };
+}

package/src/core/useWorkletFormatting.ts

@@ -0,0 +1,59 @@
+import { useState } from "react";
+import { makeMutable, type SharedValue, useAnimatedReaction } from "react-native-reanimated";
+import { MAX_SLOTS } from "./constants";
+import { localeDigitValue } from "./numerals";
+
+/**
+ * Watches a SharedValue<string> and extracts per-digit numeric values on the
+ * UI thread. Returns an array of SharedValues indexed by digit position
+ * (0 = first digit, 1 = second digit, etc.), skipping non-digit characters.
+ *
+ * This enables zero-latency digit updates during chart scrubbing — the worklet
+ * writes directly to SharedValues without crossing the JS bridge.
+ *
+ * When sharedValue is empty (e.g., scrubbing ended), all slots are set to
+ * -1, signaling DigitSlots to fall back to prop-driven animated updates.
+ */
+export function useWorkletFormatting(
+  sharedValue: SharedValue<string> | undefined,
+  prefix: string,
+  suffix: string,
+  zeroCodePoint = 48,
+): SharedValue<number>[] | null {
+  const [digitValues] = useState(() => Array.from({ length: MAX_SLOTS }, () => makeMutable(-1)));
+
+  useAnimatedReaction(
+    () => sharedValue?.value ?? "",
+    (current, previous) => {
+      if (current === previous) return;
+
+      if (!current) {
+        for (let i = 0; i < MAX_SLOTS; i++) {
+          digitValues[i].value = -1;
+        }
+        return;
+      }
+
+      const fullText = prefix + current + suffix;
+      const len = fullText.length;
+      let digitIndex = 0;
+
+      for (let i = 0; i < len && digitIndex < MAX_SLOTS; i++) {
+        const code = fullText.charCodeAt(i);
+        const dv = localeDigitValue(code, zeroCodePoint);
+        if (dv >= 0) {
+          digitValues[digitIndex].value = dv;
+          digitIndex++;
+        }
+      }
+
+      for (let i = digitIndex; i < MAX_SLOTS; i++) {
+        digitValues[i].value = -1;
+      }
+    },
+    [prefix, suffix, zeroCodePoint],
+  );
+
+  if (!sharedValue) return null;
+  return digitValues;
+}

package/src/core/utils.ts

@@ -0,0 +1,149 @@
+import { DIGIT_COUNT } from "./constants";
+import type { Trend, TrendProp } from "./types";
+
+/**
+ * Computes the signed modular offset for digit n relative to virtual
+ * scroll position c. Returns a value in [-half, half), where 0 means
+ * the digit is centered in the viewport.
+ *
+ * This is the Reanimated equivalent of NumberFlow's CSS:
+ *   offset-raw: mod(length + n - mod(c, length), length)
+ *   offset: offset-raw - length * round(down, offset-raw / (length/2), 1)
+ */
+export function signedDigitOffset(n: number, c: number, digitCount: number = DIGIT_COUNT): number {
+  "worklet";
+
+  const raw = (((n - c) % digitCount) + digitCount) % digitCount;
+  const half = digitCount / 2;
+
+  return raw >= half ? raw - digitCount : raw;
+}
+
+/**
+ * Computes the roll delta for a digit transition, respecting the trend direction.
+ *
+ * For trend > 0 (always up):   8→2 = +4 (through 9,0,1,2), not -6
+ * For trend < 0 (always down): 2→8 = -6 (through 1,0,9,8), not +4
+ * For trend = 0 (auto):        takes the shortest path
+ */
+export function computeRollDelta(
+  prev: number,
+  next: number,
+  trend: number,
+  digitCount: number = DIGIT_COUNT,
+): number {
+  "worklet";
+
+  if (prev === next) return 0;
+
+  // Always roll up (positive delta)
+  if (trend > 0) {
+    return next >= prev ? next - prev : digitCount - prev + next;
+  }
+
+  // Always roll down (negative delta)
+  if (trend < 0) {
+    return next <= prev ? next - prev : -(digitCount - next + prev);
+  }
+
+  // Auto: shortest path
+  const half = digitCount / 2;
+  const diff = next - prev;
+
+  if (Math.abs(diff) <= half) return diff;
+  return diff > 0 ? diff - digitCount : diff + digitCount;
+}
+
+/**
+ * Resolves a TrendProp (static value or function) into a concrete Trend.
+ * When undefined, auto-detects direction from the value change.
+ */
+export function resolveTrend(
+  trendProp: TrendProp | undefined,
+  prevValue: number | undefined,
+  nextValue: number | undefined,
+): Trend {
+  const hasChange = prevValue !== undefined && nextValue !== undefined && prevValue !== nextValue;
+
+  // Static trend value — pass through
+  if (typeof trendProp === "number") {
+    return trendProp;
+  }
+
+  // Function trend — call with prev/next when there's an actual change
+  if (typeof trendProp === "function") {
+    return hasChange ? trendProp(prevValue, nextValue) : 0;
+  }
+
+  // Auto-detect from direction of change
+  return hasChange ? (Math.sign(nextValue - prevValue) as Trend) : 0;
+}
+
+/**
+ * Extracts the significance position from a digit's keyed part key.
+ * "integer:2" → 2 (hundreds), "fraction:0" → -1 (tenths).
+ * Returns undefined for non-digit keys (symbols, decimals, etc.).
+ */
+export function parseDigitPosition(key: string): number | undefined {
+  "worklet";
+
+  // Exponent digits are a separate domain — they don't cascade in continuous spin
+  if (key.startsWith("exponentInteger:")) return undefined;
+
+  if (key.startsWith("integer:")) {
+    return parseInt(key.slice(8), 10);
+  }
+
+  if (key.startsWith("fraction:")) {
+    return -(parseInt(key.slice(9), 10) + 1);
+  }
+
+  // Time digit keys — significance ordered: s1 < s10 < m1 < m10 < h1 < h10
+  switch (key) {
+    case "s1":
+      return 0;
+    case "s10":
+      return 1;
+    case "m1":
+      return 2;
+    case "m10":
+      return 3;
+    case "h1":
+      return 4;
+    case "h10":
+      return 5;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Correct wheel size for each time digit position.
+ * s10/m10 only go 0-5, h10 only goes 0-2.
+ */
+export const TIME_DIGIT_COUNTS: Record<string, number> = {
+  s1: 10,
+  s10: 6,
+  m1: 10,
+  m10: 6,
+  h1: 10,
+  h10: 3,
+};
+
+/**
+ * Resolves the wheel size for a digit at a given key.
+ * Uses the `digits` prop for NumberFlow, or TIME_DIGIT_COUNTS for TimeFlow.
+ * Returns DIGIT_COUNT (10) when no constraint applies.
+ */
+export function getDigitCount(
+  digits: Record<number, { max: number }> | undefined,
+  key: string,
+): number {
+  if (!digits) return DIGIT_COUNT;
+
+  const pos = parseDigitPosition(key);
+  if (pos === undefined || pos < 0) return DIGIT_COUNT;
+
+  const constraint = digits[pos];
+  return constraint ? constraint.max + 1 : DIGIT_COUNT;
+}

package/src/core/warnings.ts

@@ -0,0 +1,8 @@
+const warned = new Set<string>();
+
+export function warnOnce(key: string, message: string): void {
+  if (__DEV__ && !warned.has(key)) {
+    warned.add(key);
+    console.warn(`[NumberFlow] ${message}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { detectNumberingSystem, getDigitStrings, getZeroCodePoint } from "./core/numerals";
+export type { TimeFlowProps } from "./core/timeTypes";
+export type {
+  AnimationConfig,
+  DigitConstraint,
+  DigitsProp,
+  TextAlign,
+  TimingConfig,
+  Trend,
+  TrendProp,
+} from "./core/types";
+export { useCanAnimate } from "./core/useCanAnimate";
+export { useFormattedValue } from "./core/useFormattedValue";
+export { NumberFlow, TimeFlow } from "./native";
+export type { NumberFlowProps, NumberFlowStyle } from "./native/types";

package/src/native/DigitSlot.tsx

@@ -0,0 +1,203 @@
+import React, { useLayoutEffect, useMemo, useRef, useState } from "react";
+import { StyleSheet, Text, type TextStyle } from "react-native";
+import Animated, {
+  makeMutable,
+  type SharedValue,
+  useAnimatedReaction,
+  useAnimatedStyle,
+  withTiming,
+} from "react-native-reanimated";
+import { DIGIT_COUNT, SUPERSCRIPT_SCALE } from "../core/constants";
+import { getSuperscriptTextStyle } from "../core/superscript";
+import type { GlyphMetrics, TimingConfig, Trend } from "../core/types";
+import { useAnimatedX } from "../core/useAnimatedX";
+import { useDigitAnimation } from "../core/useDigitAnimation";
+import { signedDigitOffset } from "../core/utils";
+
+// Extracted as its own component so useAnimatedStyle respects Rules of Hooks
+interface DigitElementProps {
+  digitString: string;
+  yValue: SharedValue<number>;
+  textStyle: DigitSlotProps["textStyle"];
+}
+
+const DigitElement = React.memo(({ digitString, yValue, textStyle }: DigitElementProps) => {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ translateY: yValue.value }],
+  }));
+
+  return (
+    <Animated.View style={[styles.digitView, animatedStyle]}>
+      <Text style={textStyle}>{digitString}</Text>
+    </Animated.View>
+  );
+});
+
+DigitElement.displayName = "DigitElement";
+
+interface DigitSlotProps {
+  metrics: GlyphMetrics;
+  digitValue: number;
+  targetX: number;
+  charWidth: number;
+  textStyle: TextStyle;
+  spinTiming: TimingConfig;
+  opacityTiming: TimingConfig;
+  transformTiming: TimingConfig;
+  trend: Trend;
+  entering: boolean;
+  exiting: boolean;
+  exitKey?: string;
+  onExitComplete?: (key: string) => void;
+  digitCount?: number;
+  continuousSpinGeneration?: number;
+  maskTop?: number;
+  maskBottom?: number;
+  superscript?: boolean;
+  digitStrings?: string[];
+}
+
+export const DigitSlot = React.memo(
+  ({
+    metrics,
+    digitValue,
+    targetX,
+    charWidth,
+    textStyle,
+    spinTiming,
+    opacityTiming,
+    transformTiming,
+    trend,
+    entering,
+    exiting,
+    exitKey,
+    onExitComplete,
+    digitCount,
+    continuousSpinGeneration,
+    maskTop = 0,
+    maskBottom = 0,
+    superscript,
+    digitStrings,
+  }: DigitSlotProps) => {
+    const resolvedDigitCount = digitCount ?? DIGIT_COUNT;
+    const resolvedDigitStrings =
+      digitStrings ?? Array.from({ length: resolvedDigitCount }, (_, i) => String(i));
+
+    // Superscript scaling — exponent digits/signs render smaller at the top of the line.
+    // Mask heights are zeroed for superscript: the container-level gradient doesn't cover
+    // the superscript position, so any buffer would show unmasked neighboring digits.
+    const scale = superscript ? SUPERSCRIPT_SCALE : 1;
+    const effectiveLH = metrics.lineHeight * scale;
+    const effectiveMaskTop = superscript ? 0 : maskTop;
+    const effectiveMaskBottom = superscript ? 0 : maskBottom;
+
+    const effectiveTextStyle = useMemo(
+      () => (superscript ? getSuperscriptTextStyle(textStyle, effectiveLH) : textStyle),
+      [textStyle, superscript, effectiveLH],
+    );
+
+    const { initialDigit, animDelta, currentDigitSV, slotOpacity } = useDigitAnimation({
+      digitValue,
+      entering,
+      exiting,
+      trend,
+      spinTiming,
+      opacityTiming,
+      exitKey,
+      onExitComplete,
+      digitCount: resolvedDigitCount,
+      continuousSpinGeneration,
+    });
+
+    /**
+     * Per-digit Y transforms stored as makeMutable shared values.
+     * Each digit independently positions itself based on its signed
+     * modular distance from the virtual scroll position.
+     */
+    const [digitYValues] = useState(() =>
+      Array.from({ length: resolvedDigitCount }, (_, n) => {
+        const offset = signedDigitOffset(n, initialDigit, resolvedDigitCount);
+        const clamped = Math.max(-1.5, Math.min(1.5, offset));
+        return makeMutable(clamped * effectiveLH + effectiveMaskTop);
+      }),
+    );
+
+    /**
+     * Mirrors NumberFlow's CSS mod(): each digit n computes its signed
+     * offset from virtual position c, clamped to [-1.5, 1.5].
+     * Only the current digit (offset ~ 0) and its neighbors (offset ~ +/-1)
+     * are visible through the clip window. All others park just outside.
+     */
+    useAnimatedReaction(
+      () => currentDigitSV.value - animDelta.value,
+      (c) => {
+        for (let n = 0; n < resolvedDigitCount; n++) {
+          const offset = signedDigitOffset(n, c, resolvedDigitCount);
+          const clamped = Math.max(-1.5, Math.min(1.5, offset));
+          digitYValues[n].value = clamped * effectiveLH + effectiveMaskTop;
+        }
+      },
+      [effectiveLH, resolvedDigitCount, effectiveMaskTop],
+    );
+
+    const animatedX = useAnimatedX(targetX, exiting, transformTiming);
+
+    const [animatedClipWidth] = useState(() => makeMutable(charWidth));
+    const prevWidthRef = useRef(charWidth);
+
+    useLayoutEffect(() => {
+      if (!exiting && prevWidthRef.current !== charWidth) {
+        prevWidthRef.current = charWidth;
+        animatedClipWidth.value = withTiming(charWidth, {
+          duration: transformTiming.duration,
+          easing: transformTiming.easing,
+        });
+      }
+    }, [charWidth, exiting, transformTiming, animatedClipWidth]);
+
+    const animatedStyle = useAnimatedStyle(() => ({
+      transform: [{ translateX: animatedX.value }, { translateY: -effectiveMaskTop }],
+      opacity: slotOpacity.value,
+    }));
+
+    const expandedHeight = effectiveLH + effectiveMaskTop + effectiveMaskBottom;
+
+    const animatedClipStyle = useAnimatedStyle(() => ({
+      overflow: "hidden" as const,
+      height: expandedHeight,
+      width: animatedClipWidth.value,
+    }));
+
+    const digitElements = useMemo(
+      () =>
+        Array.from({ length: resolvedDigitCount }, (_, n) => (
+          <DigitElement
+            digitString={resolvedDigitStrings[n]}
+            key={n}
+            textStyle={effectiveTextStyle}
+            yValue={digitYValues[n]}
+          />
+        )),
+      [resolvedDigitCount, resolvedDigitStrings, digitYValues, effectiveTextStyle],
+    );
+
+    return (
+      <Animated.View style={[styles.absolute, animatedStyle]}>
+        <Animated.View style={animatedClipStyle}>{digitElements}</Animated.View>
+      </Animated.View>
+    );
+  },
+);
+
+DigitSlot.displayName = "DigitSlot";
+
+const styles = StyleSheet.create({
+  absolute: {
+    position: "absolute",
+  },
+  digitView: {
+    position: "absolute",
+    left: 0,
+    top: 0,
+  },
+});