number-flow-react-native 0.1.0

package/src/native/renderSlots.tsx

@@ -0,0 +1,150 @@
+import type { TextStyle } from "react-native";
+import type { CharLayout } from "../core/layout";
+import type { GlyphMetrics, TimingConfig, Trend } from "../core/types";
+import { DigitSlot } from "./DigitSlot";
+import { SymbolSlot } from "./SymbolSlot";
+
+interface RenderSlotsParams {
+  layout: CharLayout[];
+  exitingEntries: Map<string, CharLayout>;
+  prevMap: Map<string, CharLayout>;
+  isInitialRender: boolean;
+  onExitComplete: (key: string) => void;
+  metrics: GlyphMetrics;
+  textStyle: TextStyle;
+  resolvedTrend: Trend;
+  spinTiming: TimingConfig;
+  opacityTiming: TimingConfig;
+  transformTiming: TimingConfig;
+  spinGenerations: Map<string, number> | undefined;
+  digitCountResolver: (key: string) => number;
+  maskTop: number;
+  maskBottom: number;
+  digitStrings?: string[];
+}
+
+/**
+ * Renders the active and exiting digit/symbol slot tree.
+ *
+ * Shared between NumberFlow and TimeFlow — the only behavioral differences
+ * are abstracted via `digitCountResolver` (which digit-count lookup to use)
+ * and the optional `digitStrings` (locale-specific digit characters).
+ */
+export function renderSlots({
+  layout,
+  exitingEntries,
+  prevMap,
+  isInitialRender,
+  onExitComplete,
+  metrics,
+  textStyle,
+  resolvedTrend,
+  spinTiming,
+  opacityTiming,
+  transformTiming,
+  spinGenerations,
+  digitCountResolver,
+  maskTop,
+  maskBottom,
+  digitStrings,
+}: RenderSlotsParams) {
+  return (
+    <>
+      {/* Active entries */}
+      {layout.map((entry) => {
+        const isEntering = !isInitialRender && !prevMap.has(entry.key);
+
+        if (entry.isDigit) {
+          const digitCount = digitCountResolver(entry.key);
+          const spinGeneration = spinGenerations?.get(entry.key);
+
+          return (
+            <DigitSlot
+              charWidth={entry.width}
+              continuousSpinGeneration={spinGeneration}
+              digitCount={digitCount}
+              digitStrings={digitStrings}
+              digitValue={entry.digitValue}
+              entering={isEntering}
+              exiting={false}
+              key={entry.key}
+              maskTop={maskTop}
+              maskBottom={maskBottom}
+              metrics={metrics}
+              opacityTiming={opacityTiming}
+              spinTiming={spinTiming}
+              superscript={entry.superscript}
+              targetX={entry.x}
+              textStyle={textStyle}
+              transformTiming={transformTiming}
+              trend={resolvedTrend}
+            />
+          );
+        }
+
+        return (
+          <SymbolSlot
+            char={entry.char}
+            entering={isEntering}
+            exiting={false}
+            key={entry.key}
+            lineHeight={metrics.lineHeight}
+            opacityTiming={opacityTiming}
+            superscript={entry.superscript}
+            targetX={entry.x}
+            textStyle={textStyle}
+            transformTiming={transformTiming}
+          />
+        );
+      })}
+
+      {/* Exiting entries */}
+      {Array.from(exitingEntries.entries()).map(([key, entry]) => {
+        if (entry.isDigit) {
+          const digitCount = digitCountResolver(key);
+
+          return (
+            <DigitSlot
+              charWidth={entry.width}
+              digitCount={digitCount}
+              digitStrings={digitStrings}
+              digitValue={entry.digitValue}
+              entering={false}
+              exitKey={key}
+              exiting
+              key={key}
+              maskTop={maskTop}
+              maskBottom={maskBottom}
+              metrics={metrics}
+              onExitComplete={onExitComplete}
+              opacityTiming={opacityTiming}
+              spinTiming={spinTiming}
+              superscript={entry.superscript}
+              targetX={entry.x}
+              textStyle={textStyle}
+              transformTiming={transformTiming}
+              trend={resolvedTrend}
+            />
+          );
+        }
+
+        return (
+          <SymbolSlot
+            char={entry.char}
+            entering={false}
+            exitKey={key}
+            exiting
+            key={key}
+            lineHeight={metrics.lineHeight}
+            onExitComplete={onExitComplete}
+            opacityTiming={opacityTiming}
+            superscript={entry.superscript}
+            targetX={entry.x}
+            textStyle={textStyle}
+            transformTiming={transformTiming}
+          />
+        );
+      })}
+    </>
+  );
+}

package/src/native/types.ts

@@ -0,0 +1,40 @@
+import type { TextStyle, ViewStyle } from "react-native";
+import type { AnimationBehaviorProps, DigitsProp, TextAlign } from "../core/types";
+
+/** Text style for NumberFlow/TimeFlow. Requires fontSize; fontFamily defaults to the system font when omitted. */
+export type NumberFlowStyle = TextStyle & {
+  fontSize: number;
+};
+
+interface NumberFlowValueProps {
+  /** Numeric value to display */
+  value: number;
+  /** Intl.NumberFormatOptions for value formatting */
+  format?: Intl.NumberFormatOptions;
+  /** Locale(s) for Intl.NumberFormat */
+  locales?: Intl.LocalesArgument;
+}
+
+interface NumberFlowBaseProps extends AnimationBehaviorProps {
+  /** Text styling. fontSize is required; fontFamily defaults to the platform system font. */
+  style: NumberFlowStyle;
+  /** Text alignment. Defaults to "left". */
+  textAlign?: TextAlign;
+  /** Static string prepended before the number */
+  prefix?: string;
+  /** Static string appended after the number */
+  suffix?: string;
+
+  /**
+   * 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;
+
+  /** Style applied to the outer container View */
+  containerStyle?: ViewStyle;
+}
+
+/** Props for NumberFlow. Accessibility is built-in: accessibilityRole="text" and accessibilityLabel are set automatically. */
+export type NumberFlowProps = NumberFlowBaseProps & NumberFlowValueProps;

package/src/native/useMeasuredGlyphMetrics.tsx

@@ -0,0 +1,205 @@
+import React, { useCallback, useMemo, useReducer, useRef } from "react";
+import { Text } from "react-native";
+import { MEASURABLE_CHARS } from "../core/constants";
+import type { GlyphMetrics } from "../core/types";
+import type { NumberFlowStyle } from "./types";
+
+// Combines MEASURABLE_CHARS with additional chars, deduplicating
+function buildCharSet(additionalChars?: string): string {
+  if (!additionalChars) return MEASURABLE_CHARS;
+  const unique = Array.from(additionalChars).filter((c) => !MEASURABLE_CHARS.includes(c));
+  return unique.length > 0 ? MEASURABLE_CHARS + unique.join("") : MEASURABLE_CHARS;
+}
+
+type TextLayoutEvent = Parameters<
+  NonNullable<React.ComponentProps<typeof Text>["onTextLayout"]>
+>[0];
+
+/**
+ * Key: "fontFamily:fontSize", Value: measured GlyphMetrics.
+ * Once measured for a given font config, subsequent mounts return instantly.
+ */
+const metricsCache = new Map<string, GlyphMetrics>();
+
+function cacheKey(
+  style: { fontFamily?: string; fontSize: number },
+  additionalChars?: string,
+): string {
+  const base = `${style.fontFamily}:${style.fontSize}`;
+  return additionalChars ? `${base}:${additionalChars}` : base;
+}
+
+/**
+ * Renders a single off-screen <Text> with all measurable characters separated
+ * by newlines. onTextLayout fires once with lines[] — one entry per line, each
+ * containing the advance width of that single character.
+ */
+
+// ASCII characters known to have no descender (bottom = 0)
+const NO_DESCENDER = new Set("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ.:%+-~°!^*×/$€£¥₩ \u00A0");
+
+/**
+ * Estimates per-character vertical bounds using font-level metrics.
+ * Top: -capHeight for all chars (precise for digits, safe overestimate for smaller glyphs).
+ * Bottom: 0 for known no-descender chars (+ locale digits), full descent otherwise.
+ */
+function estimateCharBounds(
+  charSet: string,
+  descent: number,
+  capHeight: number,
+  localeDigitStrings?: string[],
+): Record<string, { top: number; bottom: number }> {
+  const noDescender = new Set(NO_DESCENDER);
+  if (localeDigitStrings) {
+    for (const d of localeDigitStrings) noDescender.add(d);
+  }
+
+  const bounds: Record<string, { top: number; bottom: number }> = {};
+  const top = -capHeight;
+
+  for (let i = 0; i < charSet.length; i++) {
+    const bottom = noDescender.has(charSet[i]) ? 0 : descent;
+    bounds[charSet[i]] = { top, bottom };
+  }
+
+  return bounds;
+}
+
+interface MeasureComponentProps {
+  nfStyle: NumberFlowStyle;
+  charSet: string;
+  localeDigitStrings?: string[];
+  onComplete: (metrics: GlyphMetrics) => void;
+}
+
+const MeasureComponent = React.memo(
+  ({ nfStyle, charSet, localeDigitStrings, onComplete }: MeasureComponentProps) => {
+    const completedRef = useRef(false);
+
+    /**
+     * Replace regular space with NBSP for measurement safety — some Android
+     * text layout engines collapse trailing whitespace on a line.
+     */
+    const measureString = useMemo(
+      () =>
+        Array.from(charSet)
+          .map((c) => (c === " " ? "\u00A0" : c))
+          .join("\n"),
+      [charSet],
+    );
+
+    const handleTextLayout = useCallback(
+      (e: TextLayoutEvent) => {
+        if (completedRef.current) return;
+        const lines = e.nativeEvent.lines;
+        if (lines.length < charSet.length) return;
+
+        completedRef.current = true;
+
+        const charWidths: Record<string, number> = {};
+        for (let i = 0; i < charSet.length; i++) {
+          charWidths[charSet[i]] = lines[i].width;
+        }
+
+        let maxDigitWidth = 0;
+        const digitChars = localeDigitStrings ?? Array.from({ length: 10 }, (_, d) => String(d));
+        for (const dc of digitChars) {
+          const w = charWidths[dc] ?? 0;
+          if (w > maxDigitWidth) maxDigitWidth = w;
+        }
+
+        let tallestLine = lines[0];
+        for (let i = 1; i < charSet.length; i++) {
+          if (lines[i].height > tallestLine.height) tallestLine = lines[i];
+        }
+
+        // Negate ascender to match Skia convention (negative = above baseline).
+        const ascent = -tallestLine.ascender;
+        const descent = tallestLine.descender;
+        // Fallback 0.72 × |ascent| matches typical system font cap-height ratio.
+        const capHeight =
+          (tallestLine as unknown as Record<string, number>).capHeight || -ascent * 0.72;
+
+        const charBounds = estimateCharBounds(charSet, descent, capHeight, localeDigitStrings);
+
+        onComplete({
+          charWidths,
+          maxDigitWidth,
+          lineHeight: Math.ceil(tallestLine.height),
+          ascent,
+          descent,
+          charBounds,
+        });
+      },
+      [onComplete, charSet, localeDigitStrings],
+    );
+
+    return (
+      <Text
+        onTextLayout={handleTextLayout}
+        pointerEvents="none"
+        style={{
+          fontFamily: nfStyle.fontFamily,
+          fontSize: nfStyle.fontSize,
+          position: "absolute",
+          opacity: 0,
+        }}
+      >
+        {measureString}
+      </Text>
+    );
+  },
+);
+
+MeasureComponent.displayName = "NumberFlowMeasure";
+
+export function useMeasuredGlyphMetrics(
+  style: NumberFlowStyle,
+  additionalChars?: string,
+  localeDigitStrings?: string[],
+): {
+  metrics: GlyphMetrics | null;
+  MeasureElement: React.ReactElement | null;
+} {
+  const charSet = useMemo(() => buildCharSet(additionalChars), [additionalChars]);
+  const key = cacheKey(style, additionalChars);
+  const cached = metricsCache.get(key);
+  const [, forceUpdate] = useReducer((n: number) => n + 1, 0);
+
+  /**
+   * Track the best available metrics for this font config — prevents
+   * returning null (and unmounting all slots) when additionalChars
+   * changes and triggers an async re-measurement.
+   */
+  const baseKey = cacheKey(style);
+  const prevMetricsRef = useRef<GlyphMetrics | null>(null);
+  if (cached) prevMetricsRef.current = cached;
+
+  const handleComplete = useCallback(
+    (metrics: GlyphMetrics) => {
+      metricsCache.set(key, metrics);
+      forceUpdate();
+    },
+    [key],
+  );
+
+  if (cached) {
+    return { metrics: cached, MeasureElement: null };
+  }
+
+  /**
+   * If we have stale metrics from a previous measurement of this font,
+   * return them while re-measuring — avoids unmounting the slot tree.
+   */
+  const staleMetrics = prevMetricsRef.current ?? metricsCache.get(baseKey) ?? null;
+
+  return {
+    metrics: staleMetrics,
+    MeasureElement: React.createElement(MeasureComponent, {
+      nfStyle: style,
+      charSet,
+      localeDigitStrings,
+      onComplete: handleComplete,
+    }),
+  };
+}

package/src/skia/DigitSlot.tsx

@@ -0,0 +1,221 @@
+import { Group, Paint, rect, Text as SkiaText } from "@shopify/react-native-skia";
+import React, { useMemo, useState } from "react";
+import {
+  makeMutable,
+  type SharedValue,
+  useAnimatedReaction,
+  useDerivedValue,
+} from "react-native-reanimated";
+import { DIGIT_COUNT, SUPERSCRIPT_SCALE } from "../core/constants";
+import { getSuperscriptTransform } from "../core/superscript";
+import type { GlyphMetrics, SkiaNumberFlowProps, TimingConfig, Trend } from "../core/types";
+import { useAnimatedX } from "../core/useAnimatedX";
+import { useDigitAnimation } from "../core/useDigitAnimation";
+import { signedDigitOffset } from "../core/utils";
+
+interface DigitSlotProps {
+  metrics: GlyphMetrics;
+  digitValue: number;
+  targetX: number;
+  charWidth: number;
+  baseY: number;
+  color: string;
+  font: NonNullable<SkiaNumberFlowProps["font"]>;
+  spinTiming: TimingConfig;
+  opacityTiming: TimingConfig;
+  transformTiming: TimingConfig;
+  trend: Trend;
+  entering: boolean;
+  exiting: boolean;
+  exitKey?: string;
+  onExitComplete?: (key: string) => void;
+  workletDigitValue?: SharedValue<number>;
+  workletLayout?: SharedValue<{ x: number; width: number }[]>;
+  slotIndex?: number;
+  digitCount?: number;
+  continuousSpinGeneration?: number;
+  maskTop?: number;
+  maskBottom?: number;
+  superscript?: boolean;
+  digitStrings?: string[];
+}
+
+export const DigitSlot = React.memo(
+  ({
+    metrics,
+    digitValue,
+    targetX,
+    charWidth,
+    baseY,
+    color,
+    font,
+    spinTiming,
+    opacityTiming,
+    transformTiming,
+    trend,
+    entering,
+    exiting,
+    exitKey,
+    onExitComplete,
+    workletDigitValue,
+    workletLayout,
+    slotIndex,
+    digitCount,
+    continuousSpinGeneration,
+    maskTop = 0,
+    maskBottom = 0,
+    superscript,
+    digitStrings,
+  }: DigitSlotProps) => {
+    const resolvedDigitCount = digitCount ?? DIGIT_COUNT;
+    const resolvedDigitStrings =
+      digitStrings ?? Array.from({ length: resolvedDigitCount }, (_, i) => String(i));
+
+    const { initialDigit, animDelta, currentDigitSV, slotOpacity } = useDigitAnimation({
+      digitValue,
+      entering,
+      exiting,
+      trend,
+      spinTiming,
+      opacityTiming,
+      exitKey,
+      onExitComplete,
+      workletDigitValue,
+      digitCount: resolvedDigitCount,
+      continuousSpinGeneration,
+    });
+
+    /**
+     * Per-digit Y transforms: each digit independently positions itself
+     * based on its signed modular distance from the virtual scroll position.
+     * Initialized with correct positions so the first frame is accurate.
+     */
+    const [digitYTransforms] = useState(() => {
+      const lh = metrics.lineHeight;
+      return Array.from({ length: resolvedDigitCount }, (_, n) => {
+        const offset = signedDigitOffset(n, initialDigit, resolvedDigitCount);
+        const clamped = Math.max(-1.5, Math.min(1.5, offset));
+        return makeMutable([{ translateY: clamped * lh }]);
+      });
+    });
+
+    /**
+     * 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.
+     * Runs every frame via Reanimated's mapper system (animDelta changes →
+     * marks mapper dirty → microtask recalculates).
+     */
+    useAnimatedReaction(
+      () => currentDigitSV.value - animDelta.value,
+      (c) => {
+        const lh = metrics.lineHeight;
+        for (let n = 0; n < resolvedDigitCount; n++) {
+          const offset = signedDigitOffset(n, c, resolvedDigitCount);
+          const clamped = Math.max(-1.5, Math.min(1.5, offset));
+          digitYTransforms[n].value = [{ translateY: clamped * lh }];
+        }
+      },
+      [metrics.lineHeight, resolvedDigitCount],
+    );
+
+    const animatedX = useAnimatedX(targetX, exiting, transformTiming);
+
+    /**
+     * Group transform absorbs clipX (centering offset within slot width).
+     * This makes clipRect and digitXOffsets static (font-metric only).
+     * For superscript slots the visual clip is scaled, so cx accounts for that.
+     */
+    const visualClipWidth = superscript
+      ? metrics.maxDigitWidth * SUPERSCRIPT_SCALE
+      : metrics.maxDigitWidth;
+
+    const groupTransform = useDerivedValue(() => {
+      const wl = workletLayout?.value;
+      if (wl && slotIndex !== undefined && slotIndex < wl.length) {
+        const slotWidth = wl[slotIndex].width;
+        const cx = slotWidth / 2 - visualClipWidth / 2;
+        return [{ translateX: wl[slotIndex].x + cx }];
+      }
+      const cx = charWidth / 2 - visualClipWidth / 2;
+      return [{ translateX: animatedX.value + cx }];
+    });
+
+    // Digit centering within the maxDigitWidth clip (font-metric only, static)
+    const digitXOffsets = useMemo(() => {
+      const offsets: number[] = [];
+      for (let d = 0; d < resolvedDigitCount; d++) {
+        const w = metrics.charWidths[resolvedDigitStrings[d]] ?? metrics.maxDigitWidth;
+        offsets.push((metrics.maxDigitWidth - w) / 2);
+      }
+      return offsets;
+    }, [metrics, resolvedDigitCount, resolvedDigitStrings]);
+
+    // Superscript digits use a tight clip (no mask buffer) — the container-level
+    // gradient doesn't cover the superscript position, so buffer would leak neighbors.
+    const effectiveMaskTop = superscript ? 0 : maskTop;
+    const effectiveMaskBottom = superscript ? 0 : maskBottom;
+
+    const clipRect = useMemo(
+      () =>
+        rect(
+          0,
+          baseY + metrics.ascent - effectiveMaskTop,
+          metrics.maxDigitWidth,
+          metrics.lineHeight + effectiveMaskTop + effectiveMaskBottom,
+        ),
+      [baseY, metrics, effectiveMaskTop, effectiveMaskBottom],
+    );
+
+    const opacityPaint = useMemo(() => <Paint opacity={slotOpacity} />, [slotOpacity]);
+
+    /**
+     * Each digit gets its own Group transform driven by the position
+     * reaction. Only 10 elements needed (vs 30 with the copy approach).
+     * useMemo creates stable JSX — shared values drive the animation.
+     */
+    const digitElements = useMemo(
+      () =>
+        Array.from({ length: resolvedDigitCount }, (_, n) => (
+          <Group key={n} transform={digitYTransforms[n]}>
+            <SkiaText
+              color={color}
+              font={font}
+              text={resolvedDigitStrings[n]}
+              x={digitXOffsets[n]}
+              y={baseY}
+            />
+          </Group>
+        )),
+      [
+        resolvedDigitCount,
+        resolvedDigitStrings,
+        baseY,
+        color,
+        font,
+        digitXOffsets,
+        digitYTransforms,
+      ],
+    );
+
+    const superscriptTransform = useMemo(
+      () => (superscript ? getSuperscriptTransform(baseY, metrics.ascent) : undefined),
+      [superscript, baseY, metrics],
+    );
+
+    const clipContent = <Group clip={clipRect}>{digitElements}</Group>;
+
+    return (
+      <Group layer={opacityPaint} transform={groupTransform}>
+        {superscriptTransform ? (
+          <Group transform={superscriptTransform}>{clipContent}</Group>
+        ) : (
+          clipContent
+        )}
+      </Group>
+    );
+  },
+);
+
+DigitSlot.displayName = "DigitSlot";