number-flow-react-native 0.1.0

package/src/core/useDigitAnimation.ts

@@ -0,0 +1,192 @@
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import {
+  makeMutable,
+  runOnJS,
+  type SharedValue,
+  useAnimatedReaction,
+  withTiming,
+} from "react-native-reanimated";
+import { DIGIT_COUNT } from "./constants";
+import type { TimingConfig, Trend } from "./types";
+import { useSlotOpacity } from "./useSlotOpacity";
+import { computeRollDelta } from "./utils";
+
+/**
+ * We use makeMutable (via useState) instead of useSharedValue because
+ * useSharedValue's cleanup calls cancelAnimation, which kills in-flight
+ * animations when the component re-renders in StrictMode.
+ */
+
+interface UseDigitAnimationParams {
+  digitValue: number;
+  entering: boolean;
+  exiting: boolean;
+  trend: Trend;
+  spinTiming: TimingConfig;
+  opacityTiming: TimingConfig;
+  exitKey?: string;
+  onExitComplete?: (key: string) => void;
+  workletDigitValue?: SharedValue<number>;
+  /** Number of values in this digit's wheel. Defaults to 10 (0-9). */
+  digitCount?: number;
+  /** Incrementing counter from useContinuousSpin; triggers a full-wheel rotation when changed. */
+  continuousSpinGeneration?: number;
+}
+
+interface UseDigitAnimationResult {
+  initialDigit: number;
+  animDelta: SharedValue<number>;
+  currentDigitSV: SharedValue<number>;
+  slotOpacity: SharedValue<number>;
+}
+
+/**
+ * Manages the digit rolling state machine: delta tracking, exit animations,
+ * prop-driven digit changes, and worklet-driven digit updates.
+ *
+ * Each renderer creates its own format-specific Y transforms and position
+ * reaction that reads animDelta + currentDigitSV from this hook.
+ */
+export function useDigitAnimation({
+  digitValue,
+  entering,
+  exiting,
+  trend,
+  spinTiming,
+  opacityTiming,
+  exitKey,
+  onExitComplete,
+  workletDigitValue,
+  digitCount,
+  continuousSpinGeneration,
+}: UseDigitAnimationParams): UseDigitAnimationResult {
+  const resolvedDigitCount = digitCount ?? DIGIT_COUNT;
+  const initialDigit = entering ? 0 : digitValue;
+  const prevDigitRef = useRef(initialDigit);
+
+  /**
+   * animDelta starts at the computed roll distance and animates toward 0.
+   * The per-digit position reaction computes c = currentDigit - animDelta
+   * and uses mod-10 arithmetic to position each digit individually.
+   */
+  const [animDelta] = useState(() => makeMutable(0));
+  const [currentDigitSV] = useState(() => makeMutable(initialDigit));
+
+  const handleExitingStart = useCallback(() => {
+    if (prevDigitRef.current !== 0) {
+      const delta = computeRollDelta(prevDigitRef.current, 0, trend, resolvedDigitCount);
+      prevDigitRef.current = 0;
+      currentDigitSV.value = 0;
+      animDelta.value = delta;
+      animDelta.value = withTiming(0, {
+        duration: spinTiming.duration,
+        easing: spinTiming.easing,
+      });
+    }
+  }, [trend, spinTiming, animDelta, currentDigitSV, resolvedDigitCount]);
+
+  const slotOpacity = useSlotOpacity({
+    entering,
+    exiting,
+    opacityTiming,
+    exitKey,
+    onExitComplete,
+    onExitingStart: handleExitingStart,
+  });
+
+  useLayoutEffect(() => {
+    const workletActive = workletDigitValue !== undefined && workletDigitValue.value >= 0;
+    if (!exiting && !workletActive && prevDigitRef.current !== digitValue) {
+      const delta = computeRollDelta(prevDigitRef.current, digitValue, trend, resolvedDigitCount);
+      prevDigitRef.current = digitValue;
+      currentDigitSV.value = digitValue;
+      animDelta.value = delta;
+      animDelta.value = withTiming(0, {
+        duration: spinTiming.duration,
+        easing: spinTiming.easing,
+      });
+    }
+  }, [
+    digitValue,
+    exiting,
+    workletDigitValue,
+    trend,
+    spinTiming,
+    animDelta,
+    currentDigitSV,
+    resolvedDigitCount,
+  ]);
+
+  /**
+   * Continuous spin: when the generation counter increments, this digit's
+   * value didn't change but a higher-significance digit did. Perform a
+   * full-wheel rotation so the digit appears to "carry" through.
+   *
+   * Example: 100 → 200 with trend=1 — the ones digit (0→0) spins through
+   * all 10 values upward while the hundreds digit rolls 1→2 normally.
+   */
+  const prevSpinGenRef = useRef(continuousSpinGeneration ?? 0);
+
+  useLayoutEffect(() => {
+    const currentGen = continuousSpinGeneration ?? 0;
+
+    // Generation unchanged — no continuous spin needed
+    if (currentGen === prevSpinGenRef.current) return;
+    prevSpinGenRef.current = currentGen;
+
+    // Don't spin digits that are entering or exiting — they animate via opacity
+    if (exiting || entering) return;
+
+    // Full wheel rotation: e.g. 10 * 1 = spin up 10, or 6 * -1 = spin down 6 (for s10)
+    const delta = resolvedDigitCount * trend;
+    if (delta === 0) return;
+
+    // Accumulate onto any in-flight animation, then ease back to 0
+    animDelta.value = animDelta.value + delta;
+    animDelta.value = withTiming(0, {
+      duration: spinTiming.duration,
+      easing: spinTiming.easing,
+    });
+  }, [
+    continuousSpinGeneration,
+    exiting,
+    entering,
+    trend,
+    spinTiming,
+    resolvedDigitCount,
+    animDelta,
+  ]);
+
+  const syncFromWorklet = useCallback((digit: number) => {
+    prevDigitRef.current = digit;
+  }, []);
+
+  useAnimatedReaction(
+    () => workletDigitValue?.value ?? -1,
+    (current, previous) => {
+      if (current < 0 || current === previous) return;
+
+      const prev = currentDigitSV.value;
+      if (prev === current) return;
+
+      const delta = computeRollDelta(prev, current, trend, resolvedDigitCount);
+      currentDigitSV.value = current;
+
+      /**
+       * Accumulate remaining animation delta (composite: 'accumulate').
+       * Safe to read animDelta.value here — we're on the UI thread.
+       */
+      animDelta.value = animDelta.value + delta;
+
+      animDelta.value = withTiming(0, {
+        duration: spinTiming.duration,
+        easing: spinTiming.easing,
+      });
+
+      runOnJS(syncFromWorklet)(current);
+    },
+    [workletDigitValue, spinTiming, trend],
+  );
+
+  return { initialDigit, animDelta, currentDigitSV, slotOpacity };
+}

package/src/core/useFlowPipeline.ts

@@ -0,0 +1,126 @@
+import { useMemo, useRef } from "react";
+import type { CharLayout } from "./layout";
+import { computeAdaptiveMaskHeights, type MaskHeights } from "./mask";
+import type { GlyphMetrics, KeyedPart, TimingConfig, Trend, TrendProp } from "./types";
+import { useAnimationLifecycle } from "./useAnimationLifecycle";
+import { useContinuousSpin } from "./useContinuousSpin";
+import { useLayoutDiff } from "./useLayoutDiff";
+import { useTimingResolution } from "./useTimingResolution";
+import { resolveTrend } from "./utils";
+
+interface FlowPipelineInput {
+  keyedParts: KeyedPart[];
+
+  // The scalar used for trend detection:
+  //   NumberFlow: the numeric `value`
+  //   TimeFlow: `totalSeconds` (h*3600 + m*60 + s)
+  trendValue: number | undefined;
+
+  // Pre-computed layout — each component handles its own layout computation
+  // because Skia has special sharedValue layout paths
+  layout: CharLayout[];
+
+  // Metrics for adaptive mask computation
+  metrics: GlyphMetrics | null;
+
+  // AnimationBehaviorProps
+  animated?: boolean;
+  respectMotionPreference?: boolean;
+  spinTiming?: TimingConfig;
+  opacityTiming?: TimingConfig;
+  transformTiming?: TimingConfig;
+  trend?: TrendProp;
+  continuous?: boolean;
+  mask?: boolean;
+  onAnimationsStart?: () => void;
+  onAnimationsFinish?: () => void;
+}
+
+interface FlowPipelineOutput {
+  resolvedSpinTiming: TimingConfig;
+  resolvedOpacityTiming: TimingConfig;
+  resolvedTransformTiming: TimingConfig;
+  resolvedTrend: Trend;
+  spinGenerations: Map<string, number> | undefined;
+
+  prevMap: Map<string, CharLayout>;
+  isInitialRender: boolean;
+  exitingEntries: Map<string, CharLayout>;
+  onExitComplete: (key: string) => void;
+
+  accessibilityLabel: string | undefined;
+  adaptiveMask: MaskHeights;
+}
+
+const ZERO_MASK: MaskHeights = { top: 0, bottom: 0, expansionTop: 0, expansionBottom: 0 };
+
+/**
+ * Shared data pipeline for all Flow components (NumberFlow, TimeFlow,
+ * SkiaNumberFlow, SkiaTimeFlow).
+ *
+ * Handles: timing resolution, trend tracking, continuous spin,
+ * animation lifecycle, layout diffing, accessibility label,
+ * and adaptive mask computation.
+ *
+ * Layout computation is left to callers because Skia components
+ * have additional sharedValue-driven layout paths.
+ */
+export function useFlowPipeline(input: FlowPipelineInput): FlowPipelineOutput {
+  // 1. Timing resolution
+  const { resolvedSpinTiming, resolvedOpacityTiming, resolvedTransformTiming } =
+    useTimingResolution(
+      input.animated,
+      input.respectMotionPreference,
+      input.spinTiming,
+      input.opacityTiming,
+      input.transformTiming,
+    );
+
+  // 2. Trend tracking
+  const prevValueRef = useRef<number | undefined>(input.trendValue);
+  const resolvedTrend = resolveTrend(input.trend, prevValueRef.current, input.trendValue);
+  prevValueRef.current = input.trendValue;
+
+  // 3. Continuous spin
+  const spinGenerations = useContinuousSpin(input.keyedParts, input.continuous, resolvedTrend);
+
+  // 4. Animation lifecycle
+  useAnimationLifecycle(
+    input.layout,
+    { spin: resolvedSpinTiming, opacity: resolvedOpacityTiming, transform: resolvedTransformTiming },
+    input.onAnimationsStart,
+    input.onAnimationsFinish,
+  );
+
+  // 5. Layout diff
+  const { prevMap, isInitialRender, exitingEntries, onExitComplete } = useLayoutDiff(input.layout);
+
+  // 6. Accessibility label
+  const accessibilityLabel = useMemo(() => {
+    if (input.keyedParts.length === 0) return undefined;
+    
+    return input.keyedParts.map((p) => p.char).join("");
+  }, [input.keyedParts]);
+
+  // 7. Adaptive mask
+  const resolvedMask = input.mask ?? true;
+  const adaptiveMask = useMemo(() => {
+    if (!input.metrics || !resolvedMask) return ZERO_MASK;
+
+    return computeAdaptiveMaskHeights(input.layout, exitingEntries, input.metrics);
+  }, [input.metrics, resolvedMask, input.layout, exitingEntries]);
+
+  return {
+    resolvedSpinTiming,
+    resolvedOpacityTiming,
+    resolvedTransformTiming,
+    resolvedTrend,
+    spinGenerations,
+    prevMap,
+    isInitialRender,
+    exitingEntries,
+    onExitComplete,
+    accessibilityLabel,
+    adaptiveMask,
+  };
+}

package/src/core/useFormattedValue.ts

@@ -0,0 +1,32 @@
+import { useMemo } from "react";
+import { getOrCreateFormatter } from "./intlHelpers";
+
+/**
+ * Formats a numeric value to a display string using Intl.NumberFormat, with optional prefix/suffix.
+ * Useful for providing an accessibility label on a parent Canvas for Skia components:
+ *
+ * ```tsx
+ * const label = useFormattedValue(value, { style: "currency", currency: "USD" });
+ *
+ * <Canvas accessible accessibilityLabel={label}>
+ *   <SkiaNumberFlow value={value} font={font} format={{ style: "currency", currency: "USD" }} />
+ * </Canvas>
+ * ```
+ */
+export function useFormattedValue(
+  value: number | undefined,
+  format?: Intl.NumberFormatOptions,
+  locales?: Intl.LocalesArgument,
+  prefix?: string,
+  suffix?: string,
+): string | undefined {
+  // Serialize format/locales to a stable string — avoids re-runs when callers pass inline objects
+  const formatKey = useMemo(() => JSON.stringify([locales, format]), [locales, format]);
+
+  return useMemo(() => {
+    if (value === undefined) return undefined;
+    const formatter = getOrCreateFormatter(locales, format);
+    return `${prefix ?? ""}${formatter.format(value)}${suffix ?? ""}`;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value, prefix, suffix, formatKey]);
+}

package/src/core/useLayoutDiff.ts

@@ -0,0 +1,71 @@
+import { useCallback, useReducer, useRef } from "react";
+import type { CharLayout } from "./layout";
+
+interface LayoutDiffResult {
+  prevMap: Map<string, CharLayout>;
+  isInitialRender: boolean;
+  exitingEntries: Map<string, CharLayout>;
+  onExitComplete: (key: string) => void;
+}
+
+/**
+ * Manages enter/exit tracking for layout transitions. Diffs the current
+ * layout against the previous one and tracks exiting entries until their
+ * animations complete.
+ *
+ * The diff logic runs during render (not in useEffect) using a ref-based
+ * idempotent pattern for StrictMode safety.
+ */
+export function useLayoutDiff(layout: CharLayout[]): LayoutDiffResult {
+  const prevLayoutRef = useRef<CharLayout[]>([]);
+  const exitingRef = useRef<Map<string, CharLayout>>(new Map());
+  const [, forceUpdate] = useReducer((n: number) => n + 1, 0);
+  const isFirstLayoutRef = useRef(true);
+
+  const lastDiffIdRef = useRef("");
+  const diffResultRef = useRef<{
+    prevMap: Map<string, CharLayout>;
+    isInitialRender: boolean;
+  }>({ prevMap: new Map(), isInitialRender: true });
+
+  const onExitComplete = useCallback((key: string) => {
+    exitingRef.current.delete(key);
+    forceUpdate();
+  }, []);
+
+  // Stable layout identity — fast string concat instead of map+join
+  let layoutId = "";
+  for (const s of layout) {
+    layoutId += `${s.key}:${s.digitValue}|`;
+  }
+
+  if (layoutId !== lastDiffIdRef.current) {
+    lastDiffIdRef.current = layoutId;
+
+    const currentKeys = new Set(layout.map((s) => s.key));
+    const prevMap = new Map(prevLayoutRef.current.map((s) => [s.key, s]));
+
+    for (const prev of prevLayoutRef.current) {
+      if (!currentKeys.has(prev.key) && !exitingRef.current.has(prev.key)) {
+        exitingRef.current.set(prev.key, prev);
+      }
+    }
+
+    for (const key of currentKeys) {
+      exitingRef.current.delete(key);
+    }
+
+    const isInitialRender = isFirstLayoutRef.current;
+    if (layout.length > 0) isFirstLayoutRef.current = false;
+
+    diffResultRef.current = { prevMap, isInitialRender };
+    prevLayoutRef.current = layout;
+  }
+
+  return {
+    prevMap: diffResultRef.current.prevMap,
+    isInitialRender: diffResultRef.current.isInitialRender,
+    exitingEntries: exitingRef.current,
+    onExitComplete,
+  };
+}

package/src/core/useNumberFormatting.ts

@@ -0,0 +1,164 @@
+import { useMemo } from "react";
+import { getOrCreateFormatter, safeFormatToParts } from "./intlHelpers";
+import { detectOutputZeroCodePoint, localeDigitValue } from "./numerals";
+import type { KeyedPart } from "./types";
+
+/**
+ * Transforms `Intl.NumberFormat.formatToParts()` output into a flat array of
+ * stably-keyed single-character parts. Integer digits are keyed right-to-left
+ * (ones = `integer:0`, tens = `integer:1`, etc.) so that the ones place always
+ * maps to the same React key regardless of digit count. Fraction digits are
+ * keyed left-to-right from the decimal point (`fraction:0` = tenths, etc.).
+ *
+ * This keying ensures correct animation behavior when digits are added/removed
+ * (e.g., 9→10: ones place spins 9→0, tens place enters as new digit).
+ */
+export function formatToKeyedParts(
+  value: number,
+  formatter: Intl.NumberFormat,
+  locales: Intl.LocalesArgument | undefined,
+  prefix = "",
+  suffix = "",
+): KeyedPart[] {
+  const rawParts = safeFormatToParts(formatter, value, locales);
+
+  /**
+   * Detect the actual zero codepoint from the formatted output rather than
+   * trusting resolvedOptions().numberingSystem. Hermes may report "arab" but
+   * output Latin digits, or vice versa. Output-based detection is always correct.
+   */
+  const rawString = rawParts.map((p) => p.value).join("");
+  const zeroCP = detectOutputZeroCodePoint(rawString);
+
+  // Step 1: Flatten all parts into single characters with their source type
+  interface FlatChar {
+    sourceType: string;
+    char: string;
+  }
+
+  const flatChars: FlatChar[] = [];
+
+  for (const char of prefix) {
+    flatChars.push({ sourceType: "prefix", char });
+  }
+
+  for (const part of rawParts) {
+    // Merge signs into unified types.
+    // The fallback parser emits extended types (exponentMinusSign, etc.)
+    // that aren't in Intl.NumberFormatPart["type"], so we widen to string.
+    const partType = part.type as string;
+    const type =
+      partType === "minusSign" || partType === "plusSign"
+        ? "sign"
+        : partType === "exponentMinusSign" || partType === "exponentPlusSign"
+          ? "exponentSign"
+          : partType;
+
+    // Replace exponentSeparator "E" with ×10 display
+    if (type === "exponentSeparator") {
+      flatChars.push({ sourceType: "exponentSeparator", char: "\u00D7" });
+      flatChars.push({ sourceType: "exponentSeparator", char: "1" });
+      flatChars.push({ sourceType: "exponentSeparator", char: "0" });
+      continue;
+    }
+
+    // Flatten digit sequences into individual characters
+    if (type === "integer" || type === "fraction" || type === "exponentInteger") {
+      for (const char of part.value) {
+        flatChars.push({ sourceType: type, char });
+      }
+    } else {
+      flatChars.push({ sourceType: type, char: part.value });
+    }
+  }
+
+  for (const char of suffix) {
+    flatChars.push({ sourceType: "suffix", char });
+  }
+
+  // Step 2: Key characters — integers+groups RTL, everything else LTR
+  const result: KeyedPart[] = new Array(flatChars.length);
+  const counts: Record<string, number> = {};
+
+  const nextKey = (type: string) => `${type}:${(counts[type] = (counts[type] ?? -1) + 1)}`;
+
+  // Find all integer + group indices (they form one contiguous block to key RTL)
+  const integerGroupIndices: number[] = [];
+  for (let i = 0; i < flatChars.length; i++) {
+    if (flatChars[i].sourceType === "integer" || flatChars[i].sourceType === "group") {
+      integerGroupIndices.push(i);
+    }
+  }
+
+  /**
+   * Key integer digits and group separators RTL — rightmost integer digit
+   * gets "integer:0" (ones place), next gets "integer:1" (tens), etc.
+   */
+  for (let i = integerGroupIndices.length - 1; i >= 0; i--) {
+    const idx = integerGroupIndices[i];
+    const fc = flatChars[idx];
+    const isDigit = fc.sourceType === "integer";
+    result[idx] = {
+      key: nextKey(fc.sourceType),
+      type: isDigit ? "digit" : "symbol",
+      char: fc.char,
+      digitValue: isDigit ? localeDigitValue(fc.char.charCodeAt(0), zeroCP) : -1,
+    };
+  }
+
+  // Find all exponent integer indices (key RTL, same logic as mantissa integers)
+  const exponentIntegerIndices: number[] = [];
+  for (let i = 0; i < flatChars.length; i++) {
+    if (flatChars[i].sourceType === "exponentInteger") {
+      exponentIntegerIndices.push(i);
+    }
+  }
+
+  for (let i = exponentIntegerIndices.length - 1; i >= 0; i--) {
+    const idx = exponentIntegerIndices[i];
+    const fc = flatChars[idx];
+    result[idx] = {
+      key: nextKey("exponentInteger"),
+      type: "digit",
+      char: fc.char,
+      digitValue: localeDigitValue(fc.char.charCodeAt(0), zeroCP),
+    };
+  }
+
+  // Key everything else LTR (fraction, decimal, prefix, suffix, exponentSeparator, exponentSign, etc.)
+  for (let i = 0; i < flatChars.length; i++) {
+    if (result[i]) continue; // already keyed (integer, group, or exponentInteger)
+    const fc = flatChars[i];
+    const isDigit = fc.sourceType === "fraction";
+    result[i] = {
+      key: nextKey(fc.sourceType),
+      type: isDigit ? "digit" : "symbol",
+      char: fc.char,
+      digitValue: isDigit ? localeDigitValue(fc.char.charCodeAt(0), zeroCP) : -1,
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Hook that formats a numeric value into stably-keyed character parts.
+ * Uses Intl.NumberFormat.formatToParts() with RTL integer keying.
+ */
+export function useNumberFormatting(
+  value: number | undefined,
+  format: Intl.NumberFormatOptions | undefined,
+  locales: Intl.LocalesArgument | undefined,
+  prefix: string,
+  suffix: string,
+): KeyedPart[] {
+  // Serialize format/locales to a stable string — avoids re-runs when callers pass inline objects
+  const formatKey = useMemo(() => JSON.stringify([locales, format]), [locales, format]);
+
+  return useMemo(() => {
+    if (value === undefined) return [];
+    const formatter = getOrCreateFormatter(locales, format);
+    return formatToKeyedParts(value, formatter, locales, prefix, suffix);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value, prefix, suffix, formatKey]);
+}

package/src/core/useSlotOpacity.ts

@@ -0,0 +1,66 @@
+import { useLayoutEffect, useRef, useState } from "react";
+import { makeMutable, runOnJS, type SharedValue, withTiming } from "react-native-reanimated";
+import type { TimingConfig } from "./types";
+
+/**
+ * We use makeMutable (via useState) instead of useSharedValue because
+ * useSharedValue's cleanup calls cancelAnimation, which kills in-flight
+ * animations when the component re-renders in StrictMode.
+ */
+
+interface UseSlotOpacityParams {
+  entering: boolean;
+  exiting: boolean;
+  opacityTiming: TimingConfig;
+  exitKey?: string;
+  onExitComplete?: (key: string) => void;
+  onExitingStart?: () => void;
+}
+
+export function useSlotOpacity({
+  entering,
+  exiting,
+  opacityTiming,
+  exitKey,
+  onExitComplete,
+  onExitingStart,
+}: UseSlotOpacityParams): SharedValue<number> {
+  const [slotOpacity] = useState(() => makeMutable(entering ? 0 : 1));
+  const prevStateRef = useRef<"entering" | "exiting" | "active" | null>(null);
+  const currentState = entering ? "entering" : exiting ? "exiting" : "active";
+
+  useLayoutEffect(() => {
+    if (currentState === prevStateRef.current) return;
+    const wasInitial = prevStateRef.current === null;
+    prevStateRef.current = currentState;
+
+    if (currentState === "entering") {
+      slotOpacity.value = withTiming(1, {
+        duration: opacityTiming.duration,
+        easing: opacityTiming.easing,
+      });
+    } else if (currentState === "exiting") {
+      slotOpacity.value = withTiming(
+        0,
+        {
+          duration: opacityTiming.duration,
+          easing: opacityTiming.easing,
+        },
+        (finished) => {
+          "worklet";
+          if (finished && onExitComplete && exitKey) {
+            runOnJS(onExitComplete)(exitKey);
+          }
+        },
+      );
+      onExitingStart?.();
+    } else if (!wasInitial) {
+      slotOpacity.value = withTiming(1, {
+        duration: opacityTiming.duration,
+        easing: opacityTiming.easing,
+      });
+    }
+  }, [currentState, opacityTiming, exitKey, onExitComplete, onExitingStart, slotOpacity]);
+
+  return slotOpacity;
+}