number-flow-react-native 0.1.0

package/src/native/NumberFlow.tsx

@@ -0,0 +1,287 @@
+import MaskedView from "@rednegniw/masked-view";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { type LayoutChangeEvent, Text, View } from "react-native";
+import { computeKeyedLayout } from "../core/layout";
+import { detectNumberingSystem, getDigitStrings } from "../core/numerals";
+import { getFormatCharacters } from "../core/intlHelpers";
+import { useFlowPipeline } from "../core/useFlowPipeline";
+import { useNumberFormatting } from "../core/useNumberFormatting";
+import { getDigitCount } from "../core/utils";
+import { warnOnce } from "../core/warnings";
+import { renderSlots } from "./renderSlots";
+import type { NumberFlowProps } from "./types";
+import { useMeasuredGlyphMetrics } from "./useMeasuredGlyphMetrics";
+
+export const NumberFlow = ({
+  value,
+  format,
+  locales,
+  style: nfStyle,
+  textAlign = "left",
+  prefix = "",
+  suffix = "",
+  spinTiming,
+  opacityTiming,
+  transformTiming,
+  trend,
+  animated,
+  respectMotionPreference,
+  continuous,
+  digits,
+  onAnimationsStart,
+  onAnimationsFinish,
+  containerStyle,
+  mask,
+}: NumberFlowProps) => {
+  const formatChars = useMemo(
+    () => getFormatCharacters(locales, format, prefix, suffix),
+    [locales, format, prefix, suffix]
+  );
+  const numberingSystem = useMemo(
+    () => detectNumberingSystem(locales, format),
+    [locales, format]
+  );
+  const digitStrings = useMemo(
+    () => getDigitStrings(numberingSystem),
+    [numberingSystem]
+  );
+  const { metrics, MeasureElement } = useMeasuredGlyphMetrics(
+    nfStyle,
+    formatChars,
+    digitStrings
+  );
+
+  if (__DEV__) {
+    if (!nfStyle.fontSize) {
+      warnOnce(
+        "nf-fontSize",
+        "style.fontSize is required for NumberFlow to measure glyphs."
+      );
+    }
+    if (digits) {
+      for (const [posStr, constraint] of Object.entries(digits)) {
+        if (constraint.max < 1 || constraint.max > 9) {
+          warnOnce(
+            `nf-digit-max-${posStr}`,
+            `digits[${posStr}].max must be between 1 and 9, got ${constraint.max}.`
+          );
+        }
+      }
+    }
+  }
+
+  const keyedParts = useNumberFormatting(
+    value,
+    format,
+    locales,
+    prefix,
+    suffix
+  );
+
+  const [containerWidth, setContainerWidth] = useState(0);
+  const handleContainerLayout = useCallback((e: LayoutChangeEvent) => {
+    setContainerWidth(e.nativeEvent.layout.width);
+  }, []);
+
+  const layout = useMemo(() => {
+    if (!metrics) return [];
+
+    // Skip layout when container hasn't measured yet and alignment needs width.
+    // Without this guard, center/right alignment computes with width=0,
+    // then re-computes after onLayout — causing a visible slide-in animation.
+    if (containerWidth === 0 && textAlign !== "left") return [];
+
+    if (keyedParts.length === 0) return [];
+    return computeKeyedLayout(
+      keyedParts,
+      metrics,
+      containerWidth,
+      textAlign,
+      digitStrings
+    );
+  }, [metrics, keyedParts, containerWidth, textAlign, digitStrings]);
+
+  const {
+    resolvedSpinTiming,
+    resolvedOpacityTiming,
+    resolvedTransformTiming,
+    resolvedTrend,
+    spinGenerations,
+    prevMap,
+    isInitialRender,
+    exitingEntries,
+    onExitComplete,
+    accessibilityLabel,
+    adaptiveMask,
+  } = useFlowPipeline({
+    keyedParts,
+    trendValue: value,
+    layout,
+    metrics,
+    animated,
+    respectMotionPreference,
+    spinTiming,
+    opacityTiming,
+    transformTiming,
+    trend,
+    continuous,
+    mask,
+    onAnimationsStart,
+    onAnimationsFinish,
+  });
+
+  const textStyle = useMemo(
+    () => ({
+      ...nfStyle,
+      color: nfStyle.color ?? "#000000",
+    }),
+    [nfStyle]
+  );
+
+  const resolvedMask = mask ?? true;
+  const maskTop = adaptiveMask.top;
+  const maskBottom = adaptiveMask.bottom;
+  const { expansionTop, expansionBottom } = adaptiveMask;
+
+  // Step count scales with mask height — each step must be >=1px (sub-pixel Views collapse to 0).
+  const topSteps = Math.max(2, Math.round(maskTop));
+  const bottomSteps = Math.max(2, Math.round(maskBottom));
+
+  const gradientMaskElement = useMemo(() => {
+    if (!resolvedMask || !metrics) return null;
+    return (
+      <View style={{ flex: 1, flexDirection: "column" }}>
+        {/* Top fade: transparent -> opaque */}
+        {Array.from({ length: topSteps }, (_, i) => (
+          <View
+            key={`t${i}`}
+            style={{
+              height: maskTop / topSteps,
+              backgroundColor: `rgba(0,0,0,${i / (topSteps - 1)})`,
+            }}
+          />
+        ))}
+
+        {/* Middle: fully opaque */}
+        <View style={{ flex: 1, backgroundColor: "black" }} />
+
+        {/* Bottom fade: opaque -> transparent */}
+        {Array.from({ length: bottomSteps }, (_, i) => (
+          <View
+            key={`b${i}`}
+            style={{
+              height: maskBottom / bottomSteps,
+              backgroundColor: `rgba(0,0,0,${1 - i / (bottomSteps - 1)})`,
+            }}
+          />
+        ))}
+      </View>
+    );
+  }, [resolvedMask, metrics, maskTop, maskBottom, topSteps, bottomSteps]);
+
+  
+  const [slotsReady, setSlotsReady] = useState(false);
+  const metricsReady = !!metrics;
+
+  useEffect(() => {
+    if (!metricsReady) return;
+    const id = requestAnimationFrame(() => setSlotsReady(true));
+    return () => cancelAnimationFrame(id);
+  }, [metricsReady]);
+
+  if (!metrics || (layout.length === 0 && exitingEntries.size === 0)) {
+    return (
+      <View
+        accessible
+        accessibilityRole="text"
+        accessibilityLabel={accessibilityLabel}
+        onLayout={handleContainerLayout}
+        style={containerStyle}
+      >
+        <Text style={[textStyle, { textAlign }]}>{accessibilityLabel}</Text>
+        {MeasureElement}
+      </View>
+    );
+  }
+
+  // Placeholder branch: show plain Text while slot tree loads
+  if (!slotsReady) {
+    return (
+      <View
+        accessible
+        accessibilityRole="text"
+        accessibilityLabel={accessibilityLabel}
+        onLayout={handleContainerLayout}
+        style={[
+          containerStyle,
+          {
+            height: metrics.lineHeight + expansionTop + expansionBottom,
+            marginTop: -expansionTop,
+            marginBottom: -expansionBottom,
+            position: "relative",
+            overflow: "hidden",
+          },
+        ]}
+      >
+        <Text style={[textStyle, { textAlign }]}>{accessibilityLabel}</Text>
+        {MeasureElement}
+      </View>
+    );
+  }
+
+  const slots = renderSlots({
+    layout,
+    exitingEntries,
+    prevMap,
+    isInitialRender,
+    onExitComplete,
+    metrics,
+    textStyle,
+    resolvedTrend,
+    spinTiming: resolvedSpinTiming,
+    opacityTiming: resolvedOpacityTiming,
+    transformTiming: resolvedTransformTiming,
+    spinGenerations,
+    digitCountResolver: (key) => getDigitCount(digits, key),
+    maskTop,
+    maskBottom,
+    digitStrings,
+  });
+
+  // Optionally wrap in MaskedView for gradient edge fade.
+  const maskedContent =
+    resolvedMask && gradientMaskElement ? (
+      <MaskedView maskElement={gradientMaskElement} style={{ flex: 1 }}>
+        <View style={{ flex: 1, position: "relative", top: expansionTop }}>
+          {MeasureElement}
+          {slots}
+        </View>
+      </MaskedView>
+    ) : (
+      <View style={{ flex: 1, position: "relative", top: expansionTop }}>
+        {MeasureElement}
+        {slots}
+      </View>
+    );
+
+  return (
+    <View
+      accessible
+      accessibilityRole="text"
+      accessibilityLabel={accessibilityLabel}
+      onLayout={handleContainerLayout}
+      style={[
+        containerStyle,
+        {
+          height: metrics.lineHeight + expansionTop + expansionBottom,
+          marginTop: -expansionTop,
+          marginBottom: -expansionBottom,
+          position: "relative",
+          overflow: "hidden",
+        },
+      ]}
+    >
+      {maskedContent}
+    </View>
+  );
+};

package/src/native/SymbolSlot.tsx

@@ -0,0 +1,68 @@
+import React, { useMemo } from "react";
+import { Text, type TextStyle } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { SUPERSCRIPT_SCALE } from "../core/constants";
+import { getSuperscriptTextStyle } from "../core/superscript";
+import type { TimingConfig } from "../core/types";
+import { useAnimatedX } from "../core/useAnimatedX";
+import { useSlotOpacity } from "../core/useSlotOpacity";
+
+interface SymbolSlotProps {
+  char: string;
+  targetX: number;
+  lineHeight: number;
+  textStyle: TextStyle;
+  opacityTiming: TimingConfig;
+  transformTiming: TimingConfig;
+  entering: boolean;
+  exiting: boolean;
+  exitKey?: string;
+  onExitComplete?: (key: string) => void;
+  superscript?: boolean;
+}
+
+export const SymbolSlot = React.memo(
+  ({
+    char,
+    targetX,
+    lineHeight,
+    textStyle,
+    opacityTiming,
+    transformTiming,
+    entering,
+    exiting,
+    exitKey,
+    onExitComplete,
+    superscript,
+  }: SymbolSlotProps) => {
+    const effectiveHeight = superscript ? lineHeight * SUPERSCRIPT_SCALE : lineHeight;
+
+    const effectiveTextStyle = useMemo(
+      () => (superscript ? getSuperscriptTextStyle(textStyle, effectiveHeight) : textStyle),
+      [textStyle, superscript, effectiveHeight],
+    );
+
+    const slotOpacity = useSlotOpacity({
+      entering,
+      exiting,
+      opacityTiming,
+      exitKey,
+      onExitComplete,
+    });
+
+    const animatedX = useAnimatedX(targetX, exiting, transformTiming);
+
+    const animatedStyle = useAnimatedStyle(() => ({
+      transform: [{ translateX: animatedX.value }],
+      opacity: slotOpacity.value,
+    }));
+
+    return (
+      <Animated.View style={[{ position: "absolute", height: effectiveHeight }, animatedStyle]}>
+        <Text style={effectiveTextStyle}>{char}</Text>
+      </Animated.View>
+    );
+  },
+);
+
+SymbolSlot.displayName = "SymbolSlot";

package/src/native/TimeFlow.tsx

@@ -0,0 +1,287 @@
+import MaskedView from "@rednegniw/masked-view";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { type LayoutChangeEvent, Text, View } from "react-native";
+import { computeKeyedLayout } from "../core/layout";
+import type { TimeFlowProps } from "../core/timeTypes";
+import { useFlowPipeline } from "../core/useFlowPipeline";
+import { useTimeFormatting } from "../core/useTimeFormatting";
+import { TIME_DIGIT_COUNTS } from "../core/utils";
+import { warnOnce } from "../core/warnings";
+import { renderSlots } from "./renderSlots";
+import { useMeasuredGlyphMetrics } from "./useMeasuredGlyphMetrics";
+
+export const TimeFlow = ({
+  hours,
+  minutes,
+  seconds,
+  timestamp,
+  timezoneOffset,
+  is24Hour = true,
+  padHours = true,
+  style: nfStyle,
+  textAlign = "left",
+  spinTiming,
+  opacityTiming,
+  transformTiming,
+  trend,
+  animated,
+  respectMotionPreference,
+  continuous,
+  onAnimationsStart,
+  onAnimationsFinish,
+  containerStyle,
+  mask,
+}: TimeFlowProps) => {
+  const { metrics, MeasureElement } = useMeasuredGlyphMetrics(nfStyle);
+
+  if (__DEV__) {
+    if (!nfStyle.fontSize) {
+      warnOnce("tf-fontSize", "style.fontSize is required for TimeFlow to measure glyphs.");
+    }
+  }
+
+  const resolved = useMemo(() => {
+    if (timestamp !== undefined) {
+      const d = new Date(timestamp + (timezoneOffset ?? 0));
+      return {
+        hours: d.getUTCHours(),
+        minutes: d.getUTCMinutes(),
+        seconds: d.getUTCSeconds(),
+      };
+    }
+    return { hours, minutes, seconds };
+  }, [timestamp, timezoneOffset, hours, minutes, seconds]);
+
+  const resolvedHours = resolved.hours;
+  const resolvedMinutes = resolved.minutes;
+  const resolvedSeconds = resolved.seconds;
+
+  if (__DEV__) {
+    if (resolvedHours !== undefined && (resolvedHours < 0 || resolvedHours > 23)) {
+      warnOnce("tf-hours", "hours must be 0-23.");
+    }
+    if (resolvedMinutes !== undefined && (resolvedMinutes < 0 || resolvedMinutes > 59)) {
+      warnOnce("tf-minutes", "minutes must be 0-59.");
+    }
+    if (resolvedSeconds !== undefined && (resolvedSeconds < 0 || resolvedSeconds > 59)) {
+      warnOnce("tf-seconds", "seconds must be 0-59.");
+    }
+  }
+
+  const totalSeconds =
+    (resolvedHours ?? 0) * 3600 + (resolvedMinutes ?? 0) * 60 + (resolvedSeconds ?? 0);
+
+  const keyedParts = useTimeFormatting(
+    resolvedHours,
+    resolvedMinutes,
+    resolvedSeconds,
+    is24Hour,
+    padHours,
+  );
+
+  const [containerWidth, setContainerWidth] = useState(0);
+  const handleContainerLayout = useCallback((e: LayoutChangeEvent) => {
+    setContainerWidth(e.nativeEvent.layout.width);
+  }, []);
+
+  const layout = useMemo(() => {
+    if (!metrics) return [];
+
+    // Skip layout when container hasn't measured yet and alignment needs width.
+    // Without this guard, center/right alignment computes with width=0,
+    // then re-computes after onLayout — causing a visible slide-in animation.
+    if (containerWidth === 0 && textAlign !== "left") return [];
+
+    if (keyedParts.length === 0) return [];
+    return computeKeyedLayout(keyedParts, metrics, containerWidth, textAlign);
+  }, [metrics, keyedParts, containerWidth, textAlign]);
+
+  const pipeline = useFlowPipeline({
+    keyedParts,
+    trendValue: totalSeconds,
+    layout,
+    metrics,
+    animated,
+    respectMotionPreference,
+    spinTiming,
+    opacityTiming,
+    transformTiming,
+    trend,
+    continuous,
+    mask,
+    onAnimationsStart,
+    onAnimationsFinish,
+  });
+
+  const {
+    resolvedSpinTiming,
+    resolvedOpacityTiming,
+    resolvedTransformTiming,
+    resolvedTrend,
+    spinGenerations,
+    prevMap,
+    isInitialRender,
+    exitingEntries,
+    onExitComplete,
+    accessibilityLabel,
+    adaptiveMask,
+  } = pipeline;
+
+  const textStyle = useMemo(
+    () => ({
+      ...nfStyle,
+      color: nfStyle.color ?? "#000000",
+    }),
+    [nfStyle],
+  );
+
+  const resolvedMask = mask ?? true;
+  const maskTop = adaptiveMask.top;
+  const maskBottom = adaptiveMask.bottom;
+  const { expansionTop, expansionBottom } = adaptiveMask;
+
+  // Step count scales with mask height — each step must be >=1px (sub-pixel Views collapse to 0).
+  const topSteps = Math.max(2, Math.round(maskTop));
+  const bottomSteps = Math.max(2, Math.round(maskBottom));
+
+  const gradientMaskElement = useMemo(() => {
+    if (!resolvedMask || !metrics) return null;
+    return (
+      <View style={{ flex: 1, flexDirection: "column" }}>
+        {/* Top fade: transparent -> opaque */}
+        {Array.from({ length: topSteps }, (_, i) => (
+          <View
+            key={`t${i}`}
+            style={{
+              height: maskTop / topSteps,
+              backgroundColor: `rgba(0,0,0,${i / (topSteps - 1)})`,
+            }}
+          />
+        ))}
+        {/* Middle: fully opaque */}
+        <View style={{ flex: 1, backgroundColor: "black" }} />
+        {/* Bottom fade: opaque -> transparent */}
+        {Array.from({ length: bottomSteps }, (_, i) => (
+          <View
+            key={`b${i}`}
+            style={{
+              height: maskBottom / bottomSteps,
+              backgroundColor: `rgba(0,0,0,${1 - i / (bottomSteps - 1)})`,
+            }}
+          />
+        ))}
+      </View>
+    );
+  }, [resolvedMask, metrics, maskTop, maskBottom, topSteps, bottomSteps]);
+
+  // Progressive mount: render a plain <Text> on the first frame, then swap to
+  // the full animated slot tree on the next frame. At mount time there is never
+  // a value change to animate, so the placeholder is visually identical while
+  // avoiding the ~80ms cost of instantiating dozens of useAnimatedStyle hooks.
+  const [slotsReady, setSlotsReady] = useState(false);
+  const metricsReady = !!metrics;
+
+  useEffect(() => {
+    if (!metricsReady) return;
+    const id = requestAnimationFrame(() => setSlotsReady(true));
+    return () => cancelAnimationFrame(id);
+  }, [metricsReady]);
+
+  if (!metrics || (layout.length === 0 && exitingEntries.size === 0)) {
+    return (
+      <View
+        accessible
+        accessibilityRole="text"
+        accessibilityLabel={accessibilityLabel}
+        onLayout={handleContainerLayout}
+        style={containerStyle}
+      >
+        <Text style={[textStyle, { textAlign }]}>{accessibilityLabel}</Text>
+        {MeasureElement}
+      </View>
+    );
+  }
+
+  {/* Placeholder branch: show plain Text while slot tree loads */}
+  if (!slotsReady) {
+    return (
+      <View
+        accessible
+        accessibilityRole="text"
+        accessibilityLabel={accessibilityLabel}
+        onLayout={handleContainerLayout}
+        style={[
+          containerStyle,
+          {
+            height: metrics.lineHeight + expansionTop + expansionBottom,
+            marginTop: -expansionTop,
+            marginBottom: -expansionBottom,
+            position: "relative",
+            overflow: "hidden",
+          },
+        ]}
+      >
+        <Text style={[textStyle, { textAlign }]}>{accessibilityLabel}</Text>
+        {MeasureElement}
+      </View>
+    );
+  }
+
+  const slots = renderSlots({
+    layout,
+    exitingEntries,
+    prevMap,
+    isInitialRender,
+    onExitComplete,
+    metrics,
+    textStyle,
+    resolvedTrend,
+    spinTiming: resolvedSpinTiming,
+    opacityTiming: resolvedOpacityTiming,
+    transformTiming: resolvedTransformTiming,
+    spinGenerations,
+    digitCountResolver: (key) => TIME_DIGIT_COUNTS[key],
+    maskTop,
+    maskBottom,
+  });
+
+  // Optionally wrap in MaskedView for gradient edge fade.
+  // Content must be inside a single wrapper View so MaskedView's native
+  // didUpdateReactSubviews always sees one stable child — avoids Fabric
+  // "Attempt to recycle a mounted view" crash from dynamic slot churn.
+  const maskedContent =
+    resolvedMask && gradientMaskElement ? (
+      <MaskedView maskElement={gradientMaskElement} style={{ flex: 1 }}>
+        <View style={{ flex: 1, position: "relative", top: expansionTop }}>
+          {MeasureElement}
+          {slots}
+        </View>
+      </MaskedView>
+    ) : (
+      <View style={{ flex: 1, position: "relative", top: expansionTop }}>
+        {MeasureElement}
+        {slots}
+      </View>
+    );
+
+  return (
+    <View
+      accessible
+      accessibilityRole="text"
+      accessibilityLabel={accessibilityLabel}
+      onLayout={handleContainerLayout}
+      style={[
+        containerStyle,
+        {
+          height: metrics.lineHeight + expansionTop + expansionBottom,
+          marginTop: -expansionTop,
+          marginBottom: -expansionBottom,
+          position: "relative",
+          overflow: "hidden",
+        },
+      ]}
+    >
+      {maskedContent}
+    </View>
+  );
+};

package/src/native/index.ts

@@ -0,0 +1,2 @@
+export { NumberFlow } from "./NumberFlow";
+export { TimeFlow } from "./TimeFlow";