number-flow-react-native 0.1.0

package/src/core/types.ts

@@ -0,0 +1,189 @@
+import type { SkFont } from "@shopify/react-native-skia";
+import type { EasingFunction, SharedValue } from "react-native-reanimated";
+
+export interface TimingConfig {
+  /** Duration in milliseconds */
+  duration: number;
+  /** Easing function (t: 0→1) => 0→1 */
+  easing: EasingFunction;
+}
+
+export interface AnimationConfig {
+  /** Timing for layout transforms (position, width changes). Defaults to NumberFlow's 900ms deceleration curve. */
+  transformTiming?: TimingConfig;
+  /** Timing for digit spin/rolling. Falls back to transformTiming if unset. */
+  spinTiming?: TimingConfig;
+  /** Timing for enter/exit opacity. Defaults to 450ms ease-out. */
+  opacityTiming?: TimingConfig;
+}
+
+/**
+ * Controls digit spin direction:
+ * - `1`: always spin upward
+ * - `-1`: always spin downward
+ * - `0`: each digit takes the shortest path
+ */
+export type Trend = -1 | 0 | 1;
+
+/**
+ * Trend prop accepted by components: either a static direction
+ * or a function that receives (prevValue, nextValue) and returns the direction.
+ */
+export type TrendProp = Trend | ((prev: number, next: number) => Trend);
+
+/**
+ * Animation behavior props shared by all Flow components (NumberFlow, TimeFlow,
+ * SkiaNumberFlow, SkiaTimeFlow). Controls how digit transitions behave.
+ */
+export interface AnimationBehaviorProps extends AnimationConfig {
+  /**
+   * Digit spin direction. When omitted, auto-detects from value changes:
+   * increasing values spin up, decreasing spin down.
+   * Pass `0` explicitly for shortest-path per-digit behavior.
+   */
+  trend?: TrendProp;
+
+  /** Set to false to disable animations and update instantly. Defaults to true. */
+  animated?: boolean;
+
+  /** When true (default), disables animations when the device's "Reduce Motion" setting is on. */
+  respectMotionPreference?: boolean;
+
+  /**
+   * When true, unchanged lower-significance digits spin through a full cycle
+   * during transitions, making the number appear to pass through intermediate values.
+   * Defaults to false.
+   */
+  continuous?: boolean;
+
+  /** Enable edge gradient fade masking on digit slots. Defaults to true. */
+  mask?: boolean;
+
+  /** Called when update animations begin */
+  onAnimationsStart?: () => void;
+
+  /** Called when all update animations complete */
+  onAnimationsFinish?: () => void;
+}
+
+/** A single character with a stable key from formatToParts RTL/LTR keying */
+export interface KeyedPart {
+  /** Stable key: "integer:0" (ones), "integer:1" (tens), "fraction:0" (tenths), "decimal:0", etc. */
+  key: string;
+  /** Whether this is a rolling digit or a static symbol */
+  type: "digit" | "symbol";
+  /** The display character */
+  char: string;
+  /** 0-9 for digits, -1 for symbols */
+  digitValue: number;
+}
+
+export function digitPart(key: string, value: number): KeyedPart {
+  return { key, type: "digit", char: String(value), digitValue: value };
+}
+
+export function symbolPart(key: string, char: string): KeyedPart {
+  return { key, type: "symbol", char, digitValue: -1 };
+}
+
+export interface GlyphMetrics {
+  /** Advance width for each measurable character */
+  charWidths: Record<string, number>;
+  /** Maximum width among digits 0-9 (used for uniform digit slot sizing) */
+  maxDigitWidth: number;
+  /** Line height computed from font metrics: ceil(descent - ascent) */
+  lineHeight: number;
+  /** Font ascent (negative value — distance above baseline) */
+  ascent: number;
+  /** Font descent (positive value — distance below baseline) */
+  descent: number;
+  /**
+   * Per-character tight vertical bounds relative to the baseline.
+   * `top` is negative (above baseline), `bottom` is positive (below baseline).
+   * Used by the adaptive mask to avoid fading into visible glyph content.
+   */
+  charBounds: Record<string, { top: number; bottom: number }>;
+}
+
+export type TextAlign = "left" | "right" | "center";
+
+/**
+ * Per-position digit constraint. `max` defines the highest value the
+ * digit can display (inclusive), creating a wheel of (max + 1) values.
+ * Example: { max: 5 } creates a 0-5 wheel (6 elements).
+ */
+export interface DigitConstraint {
+  max: number;
+}
+
+/**
+ * Maps integer positions to their constraints.
+ * Position 0 = ones, 1 = tens, 2 = hundreds, etc.
+ * Positions not listed default to { max: 9 } (standard 0-9 wheel).
+ */
+export type DigitsProp = Record<number, DigitConstraint>;
+
+/** Value props — mutually exclusive: provide `value` (JS-driven) or `sharedValue` (worklet-driven), not both. */
+type SkiaNumberFlowValueProps =
+  | {
+      /** JS-thread numeric value. Mutually exclusive with sharedValue. */
+      value: number;
+      /** Intl.NumberFormatOptions for value formatting */
+      format?: Intl.NumberFormatOptions;
+      /** Locale(s) for Intl.NumberFormat */
+      locales?: Intl.LocalesArgument;
+      sharedValue?: never;
+    }
+  | {
+      value?: never;
+      format?: never;
+      locales?: never;
+      /** Worklet-driven pre-formatted string. Mutually exclusive with value. */
+      sharedValue: SharedValue<string>;
+    };
+
+interface SkiaNumberFlowBaseProps extends AnimationBehaviorProps {
+  /** SkFont instance from useFont(). Required — renders empty until font loads. */
+  font: SkFont | null;
+  /** Text color (Skia color string). Defaults to "#000000". */
+  color?: string;
+  /** X position within the Canvas. Defaults to 0. */
+  x?: number;
+  /** Y position within the Canvas (baseline). Defaults to 0. */
+  y?: number;
+  /** Available width for alignment calculations. Defaults to 0. */
+  width?: number;
+  /** Text alignment within the available width. Defaults to "left". */
+  textAlign?: TextAlign;
+  /** Static string prepended before the number */
+  prefix?: string;
+  /** Static string appended after the number */
+  suffix?: string;
+  /** Parent opacity (SharedValue for animation coordination) */
+  opacity?: SharedValue<number>;
+
+  /**
+   * Per-position digit constraints. Maps integer position (0=ones, 1=tens, ...)
+   * to { max: N } where N is the highest digit value (inclusive).
+   * Example: { 1: { max: 5 } } for a wheel where tens go 0-5.
+   */
+  digits?: DigitsProp;
+
+  /**
+   * Controls digit width during worklet-driven scrubbing (when sharedValue is active).
+   * Value between 0 and 1 representing the percentile between min and max digit width.
+   * - 0: use narrowest digit width (tightest, may clip wide digits)
+   * - 0.5: use average digit width
+   * - 1: use widest digit width (no clipping, but wider spacing)
+   * Defaults to 0.75 (75th percentile) for a good balance.
+   * Only affects digits; symbols like "." keep their natural width.
+   */
+  scrubDigitWidthPercentile?: number;
+}
+
+/**
+ * Props for SkiaNumberFlow.
+ * Value changes are auto-announced for screen reader users.
+ * For VoiceOver/TalkBack focus-based reading, set `accessibilityLabel` on the parent Canvas.
+ */
+export type SkiaNumberFlowProps = SkiaNumberFlowBaseProps & SkiaNumberFlowValueProps;

package/src/core/useAccessibilityAnnouncement.ts

@@ -0,0 +1,27 @@
+import { useEffect, useRef } from "react";
+import { AccessibilityInfo } from "react-native";
+
+/**
+ * Announces label changes to screen readers for Skia components.
+ *
+ * Skia renders inside <Canvas>, which is opaque to the accessibility tree.
+ * This hook auto-announces value changes when a screen reader is active
+ * so users get audio feedback. The first render is skipped to avoid
+ * announcing the initial value.
+ */
+export function useAccessibilityAnnouncement(label: string | undefined): void {
+  const isFirstRender = useRef(true);
+
+  useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      return;
+    }
+
+    if (!label) return;
+
+    AccessibilityInfo.isScreenReaderEnabled().then((enabled) => {
+      if (enabled) AccessibilityInfo.announceForAccessibility(label);
+    });
+  }, [label]);
+}

package/src/core/useAnimatedX.ts

@@ -0,0 +1,30 @@
+import { useLayoutEffect, useRef, useState } from "react";
+import { makeMutable, 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.
+ */
+
+export function useAnimatedX(
+  targetX: number,
+  exiting: boolean,
+  transformTiming: TimingConfig,
+): SharedValue<number> {
+  const [animatedX] = useState(() => makeMutable(targetX));
+  const prevXRef = useRef(targetX);
+
+  useLayoutEffect(() => {
+    if (!exiting && prevXRef.current !== targetX) {
+      prevXRef.current = targetX;
+      animatedX.value = withTiming(targetX, {
+        duration: transformTiming.duration,
+        easing: transformTiming.easing,
+      });
+    }
+  }, [targetX, exiting, transformTiming, animatedX]);
+
+  return animatedX;
+}

package/src/core/useAnimationLifecycle.ts

@@ -0,0 +1,54 @@
+import { useEffect, useRef } from "react";
+import type { CharLayout } from "./layout";
+import type { TimingConfig } from "./types";
+
+/**
+ * Fires animation lifecycle callbacks (start/finish) when the layout changes.
+ *
+ * Uses refs for callbacks to avoid stale closures in the setTimeout,
+ * and tracks previous layout to detect actual changes (not initial mount).
+ */
+export function useAnimationLifecycle(
+  layout: CharLayout[],
+  timings: { spin: TimingConfig; opacity: TimingConfig; transform: TimingConfig },
+  onAnimationsStart?: () => void,
+  onAnimationsFinish?: () => void,
+): void {
+  // Keep callback refs fresh so the setTimeout always calls the latest version
+  const onStartRef = useRef(onAnimationsStart);
+  onStartRef.current = onAnimationsStart;
+
+  const onFinishRef = useRef(onAnimationsFinish);
+  onFinishRef.current = onAnimationsFinish;
+
+  // Track previous layout to distinguish real changes from initial mount
+  const prevLayoutRef = useRef(layout);
+  const prevLayoutLenRef = useRef(layout.length);
+  const animTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  useEffect(() => {
+    const layoutChanged = layout !== prevLayoutRef.current;
+    const bothNonEmpty = layout.length > 0 && prevLayoutLenRef.current > 0;
+
+    if (layoutChanged && bothNonEmpty) {
+      onStartRef.current?.();
+
+      if (animTimerRef.current) clearTimeout(animTimerRef.current);
+
+      const maxDur = Math.max(
+        timings.spin.duration,
+        timings.opacity.duration,
+        timings.transform.duration,
+      );
+
+      animTimerRef.current = setTimeout(() => onFinishRef.current?.(), maxDur);
+    }
+
+    prevLayoutRef.current = layout;
+    prevLayoutLenRef.current = layout.length;
+
+    return () => {
+      if (animTimerRef.current) clearTimeout(animTimerRef.current);
+    };
+  }, [layout, timings.spin, timings.opacity, timings.transform]);
+}

package/src/core/useCanAnimate.ts

@@ -0,0 +1,21 @@
+import { useReducedMotion } from "react-native-reanimated";
+
+/**
+ * Returns whether NumberFlow animations are currently enabled.
+ *
+ * Use this to conditionally render UI based on animation support:
+ * ```tsx
+ * const canAnimate = useCanAnimate();
+ * return canAnimate ? <NumberFlow value={42} /> : <Text>42</Text>;
+ * ```
+ *
+ * When `respectMotionPreference` is true (default), returns false
+ * if the device's "Reduce Motion" accessibility setting is on.
+ */
+export function useCanAnimate(respectMotionPreference = true): boolean {
+  const reducedMotion = useReducedMotion();
+
+  if (!respectMotionPreference) return true;
+
+  return !reducedMotion;
+}

package/src/core/useContinuousSpin.ts

@@ -0,0 +1,112 @@
+import { useRef } from "react";
+import type { KeyedPart, Trend } from "./types";
+import { parseDigitPosition } from "./utils";
+
+/**
+ * Pure algorithm: given previous and current keyed parts, determines which
+ * unchanged lower-significance digits should do a full-wheel continuous spin.
+ *
+ * Returns a new Map with incremented generation counters for those digits.
+ * The generation counter is what triggers the spin animation in useDigitAnimation.
+ */
+export function computeContinuousGenerations(
+  prevParts: KeyedPart[],
+  currentParts: KeyedPart[],
+  prevGenerations: Map<string, number>,
+): Map<string, number> {
+  // Build lookup of previous digit values by key
+  const prevDigits = new Map<string, number>();
+  for (const part of prevParts) {
+    if (part.type === "digit") {
+      prevDigits.set(part.key, part.digitValue);
+    }
+  }
+
+  // Find the highest-significance position where the digit value changed
+  let maxChangedPos = -Infinity;
+
+  for (const part of currentParts) {
+    if (part.type !== "digit") continue;
+
+    const pos = parseDigitPosition(part.key);
+    if (pos === undefined) continue;
+
+    const prevValue = prevDigits.get(part.key);
+    const changed = prevValue !== undefined && prevValue !== part.digitValue;
+
+    if (changed && pos > maxChangedPos) {
+      maxChangedPos = pos;
+    }
+  }
+
+  // No digit changed — nothing to spin
+  if (maxChangedPos === -Infinity) return prevGenerations;
+
+  /**
+   * Increment the generation counter for each unchanged digit whose
+   * significance is lower than the most-significant changed digit.
+   * Only digits that existed in the previous render qualify — entering
+   * digits have no previous value and can't be "unchanged".
+   */
+  const nextGenerations = new Map(prevGenerations);
+
+  for (const part of currentParts) {
+    if (part.type !== "digit") continue;
+
+    const pos = parseDigitPosition(part.key);
+    if (pos === undefined || pos >= maxChangedPos) continue;
+
+    const prevValue = prevDigits.get(part.key);
+    const unchanged = prevValue !== undefined && prevValue === part.digitValue;
+
+    if (unchanged) {
+      const prev = nextGenerations.get(part.key) ?? 0;
+      nextGenerations.set(part.key, prev + 1);
+    }
+  }
+
+  return nextGenerations;
+}
+
+/**
+ * Tracks which digits need a full-wheel continuous spin.
+ *
+ * When `continuous` is enabled, unchanged lower-significance digits spin
+ * through a complete cycle alongside higher-significance digits that changed.
+ * For example, 100 -> 200 with trend=1 makes ones and tens both do a
+ * full upward rotation even though their values didn't change.
+ *
+ * Returns a Map<key, generation> where generation increments each time
+ * a digit should perform a continuous spin. Returns undefined when
+ * continuous is disabled (zero overhead path).
+ */
+export function useContinuousSpin(
+  keyedParts: KeyedPart[],
+  continuous: boolean | undefined,
+  trend: Trend,
+): Map<string, number> | undefined {
+  const prevPartsRef = useRef<KeyedPart[]>([]);
+  const generationsRef = useRef<Map<string, number>>(new Map());
+
+  if (!continuous) {
+    prevPartsRef.current = keyedParts;
+    return undefined;
+  }
+
+  const prevParts = prevPartsRef.current;
+  prevPartsRef.current = keyedParts;
+
+  // First render — nothing to compare against
+  if (prevParts.length === 0) return generationsRef.current;
+
+  // Shortest-path trend defeats the purpose of continuous spin
+  if (trend === 0) return generationsRef.current;
+
+  generationsRef.current = computeContinuousGenerations(
+    prevParts,
+    keyedParts,
+    generationsRef.current,
+  );
+
+  return generationsRef.current;
+}

package/src/core/useDebouncedWidths.ts

@@ -0,0 +1,93 @@
+import { useState } from "react";
+import {
+  makeMutable,
+  type SharedValue,
+  useAnimatedReaction,
+  withTiming,
+} from "react-native-reanimated";
+import { MAX_SLOTS } from "./constants";
+import { localeDigitValue } from "./numerals";
+
+const WIDTH_ANIM_MS = 200;
+
+/**
+ * Creates a pool of SharedValue<number> that hold digit widths for worklet layout.
+ *
+ * **Tabular mode during scrubbing**: While sharedValue is active (scrubbing),
+ * all digits use a fixed width (scrubDigitWidth) — this eliminates jitter entirely
+ * because all digits occupy the same width regardless of which digit (0-9) is displayed.
+ * Only digits are affected; symbols (like `.`) keep their natural width.
+ *
+ * **Proportional mode when idle**: When scrubbing ends (sharedValue becomes
+ * empty), widths animate to proportional values for natural typography.
+ *
+ * This approach gives the best of both worlds: stable layout during rapid
+ * scrubbing, and beautiful proportional spacing for static display.
+ */
+export function useDebouncedWidths(
+  digitWidths: number[] | null,
+  scrubDigitWidth: number,
+  sharedValue: SharedValue<string> | undefined,
+  prefix: string,
+  suffix: string,
+  zeroCodePoint = 48,
+): SharedValue<number>[] {
+  const [debouncedWidths] = useState(() =>
+    Array.from({ length: MAX_SLOTS }, () => makeMutable(-1)),
+  );
+  const [prevDigits] = useState(() => Array.from({ length: MAX_SLOTS }, () => makeMutable(-1)));
+  const [wasActive] = useState(() => makeMutable(false));
+
+  useAnimatedReaction(
+    () => sharedValue?.value ?? "",
+    (current, previous) => {
+      if (current === previous) return;
+      if (!digitWidths) return;
+
+      if (!current) {
+        // Scrubbing ended — animate to proportional widths
+        if (wasActive.value) {
+          wasActive.value = false;
+          for (let i = 0; i < MAX_SLOTS; i++) {
+            const prevDv = prevDigits[i].value;
+            if (prevDv >= 0) {
+              const proportionalWidth = digitWidths[prevDv];
+              debouncedWidths[i].value = withTiming(proportionalWidth, {
+                duration: WIDTH_ANIM_MS,
+              });
+            } else {
+              debouncedWidths[i].value = -1;
+            }
+            prevDigits[i].value = -1;
+          }
+        }
+        return;
+      }
+
+      const isFirstActivation = !wasActive.value;
+      if (isFirstActivation) wasActive.value = true;
+
+      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) {
+          prevDigits[digitIndex].value = dv;
+          debouncedWidths[digitIndex].value = scrubDigitWidth;
+          digitIndex++;
+        }
+      }
+
+      for (let i = digitIndex; i < MAX_SLOTS; i++) {
+        if (debouncedWidths[i].value !== -1) debouncedWidths[i].value = -1;
+        prevDigits[i].value = -1;
+      }
+    },
+    [prefix, suffix, digitWidths, scrubDigitWidth, zeroCodePoint],
+  );
+
+  return debouncedWidths;
+}