number-flow-react-native 0.1.0

package/src/skia/SkiaTimeFlow.tsx

@@ -0,0 +1,257 @@
+import { Group, LinearGradient, Paint, Rect as SkiaRect, vec } from "@shopify/react-native-skia";
+import { useMemo } from "react";
+import { MASK_WIDTH_RATIO } from "../core/constants";
+import { computeKeyedLayout } from "../core/layout";
+import { computeTimeStringLayout } from "../core/timeLayout";
+import type { SkiaTimeFlowProps } from "../core/timeTypes";
+import { useAccessibilityAnnouncement } from "../core/useAccessibilityAnnouncement";
+import { useFlowPipeline } from "../core/useFlowPipeline";
+import { useTimeFormatting } from "../core/useTimeFormatting";
+import { useWorkletFormatting } from "../core/useWorkletFormatting";
+import { TIME_DIGIT_COUNTS } from "../core/utils";
+import { warnOnce } from "../core/warnings";
+import { renderSlots } from "./renderSlots";
+import { useGlyphMetrics } from "./useGlyphMetrics";
+
+export const SkiaTimeFlow = ({
+  hours,
+  minutes,
+  seconds,
+  timestamp,
+  timezoneOffset,
+  sharedValue,
+  is24Hour = true,
+  padHours = true,
+  font,
+  color = "#000000",
+  x = 0,
+  y = 0,
+  width = 0,
+  textAlign = "left",
+  opacity,
+  spinTiming,
+  opacityTiming,
+  transformTiming,
+  trend,
+  animated,
+  respectMotionPreference,
+  continuous,
+  mask,
+  onAnimationsStart,
+  onAnimationsFinish,
+}: SkiaTimeFlowProps) => {
+  const metrics = useGlyphMetrics(font);
+
+  if (__DEV__) {
+    if (!font) {
+      warnOnce(
+        "skia-tf-font",
+        "font is null — pass a loaded SkFont from useFont(). Component renders empty until font loads.",
+      );
+    }
+  }
+
+  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;
+
+  const hasHours = resolvedHours !== undefined;
+  const hasSeconds = resolvedSeconds !== undefined;
+
+  if (__DEV__) {
+    if (resolvedHours !== undefined && (resolvedHours < 0 || resolvedHours > 23)) {
+      warnOnce("skia-tf-hours", "hours must be 0-23.");
+    }
+    if (resolvedMinutes !== undefined && (resolvedMinutes < 0 || resolvedMinutes > 59)) {
+      warnOnce("skia-tf-minutes", "minutes must be 0-59.");
+    }
+    if (resolvedSeconds !== undefined && (resolvedSeconds < 0 || resolvedSeconds > 59)) {
+      warnOnce("skia-tf-seconds", "seconds must be 0-59.");
+    }
+  }
+
+  const totalSeconds =
+    (resolvedHours ?? 0) * 3600 + (resolvedMinutes ?? 0) * 60 + (resolvedSeconds ?? 0);
+
+  const keyedParts = useTimeFormatting(
+    resolvedHours,
+    // Fallback for sharedValue mode where minutes is undefined (unused — layout comes from string path)
+    resolvedMinutes ?? 0,
+    resolvedSeconds,
+    is24Hour,
+    padHours,
+  );
+
+  const workletDigitValues = useWorkletFormatting(sharedValue, "", "");
+
+  const layout = useMemo(() => {
+    if (!metrics) return [];
+
+    if (sharedValue && resolvedHours === undefined && resolvedMinutes === undefined) {
+      return computeTimeStringLayout(
+        sharedValue.value,
+        metrics,
+        width,
+        textAlign,
+        hasHours,
+        hasSeconds,
+      );
+    }
+
+    if (keyedParts.length === 0) return [];
+    return computeKeyedLayout(keyedParts, metrics, width, textAlign);
+  }, [
+    metrics,
+    keyedParts,
+    width,
+    textAlign,
+    sharedValue,
+    resolvedHours,
+    resolvedMinutes,
+    hasHours,
+    hasSeconds,
+  ]);
+
+  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;
+
+  useAccessibilityAnnouncement(accessibilityLabel);
+
+  if (!font || !metrics) {
+    return <Group />;
+  }
+
+  if (layout.length === 0 && exitingEntries.size === 0) {
+    return <Group />;
+  }
+
+  const baseY = y;
+  const resolvedMask = mask ?? true;
+
+  const maskTopHeight = resolvedMask ? adaptiveMask.top : 0;
+  const maskBottomHeight = resolvedMask ? adaptiveMask.bottom : 0;
+  const maskWidth = resolvedMask ? MASK_WIDTH_RATIO * metrics.lineHeight : 0;
+
+  // Content bounds from layout (in local coordinate space before translateX)
+  const contentLeft = layout.reduce((min, entry) => Math.min(min, entry.x), Infinity);
+  const contentRight = layout.reduce((max, entry) => Math.max(max, entry.x + entry.width), 0);
+  const contentWidth = layout.length > 0 ? contentRight - contentLeft : 0;
+
+  const content = (
+    <Group transform={[{ translateX: x }]}>
+      {renderSlots({
+        layout,
+        exitingEntries,
+        prevMap,
+        isInitialRender,
+        onExitComplete,
+        metrics,
+        font,
+        color,
+        baseY,
+        resolvedTrend,
+        spinTiming: resolvedSpinTiming,
+        opacityTiming: resolvedOpacityTiming,
+        transformTiming: resolvedTransformTiming,
+        spinGenerations,
+        digitCountResolver: (key) => TIME_DIGIT_COUNTS[key],
+        maskTop: maskTopHeight,
+        maskBottom: maskBottomHeight,
+        workletDigitValues,
+      })}
+    </Group>
+  );
+
+  /**
+   * Container-level 2D gradient mask matching web NumberFlow's vignette.
+   * Horizontal: fade extends outside text edges (for enter/exit animations).
+   * Vertical: fade is within the text line height (digits roll through it).
+   * Two DstIn layers compose: final_alpha = content * h_alpha * v_alpha.
+   */
+  const maskLeft = x + contentLeft - maskWidth;
+  const maskRight = x + contentRight + maskWidth;
+  const maskY = baseY + metrics.ascent;
+  const maskTotalWidth = contentWidth + 2 * maskWidth;
+  const maskTotalHeight = metrics.lineHeight;
+  const hRatio = maskTotalWidth > 0 ? maskWidth / maskTotalWidth : 0;
+  const vRatioTop = maskTotalHeight > 0 ? maskTopHeight / maskTotalHeight : 0;
+  const vRatioBottom = maskTotalHeight > 0 ? maskBottomHeight / maskTotalHeight : 0;
+
+  const maskedContent = resolvedMask ? (
+    <Group layer={<Paint />}>
+      {content}
+
+      {/* Horizontal fade */}
+      <Group layer={<Paint blendMode="dstIn" />}>
+        <SkiaRect height={maskTotalHeight} width={maskTotalWidth} x={maskLeft} y={maskY}>
+          <LinearGradient
+            colors={["transparent", "black", "black", "transparent"]}
+            end={vec(maskRight, 0)}
+            positions={[0, hRatio, 1 - hRatio, 1]}
+            start={vec(maskLeft, 0)}
+          />
+        </SkiaRect>
+      </Group>
+
+      {/* Vertical fade */}
+      <Group layer={<Paint blendMode="dstIn" />}>
+        <SkiaRect height={maskTotalHeight} width={maskTotalWidth} x={maskLeft} y={maskY}>
+          <LinearGradient
+            colors={["transparent", "black", "black", "transparent"]}
+            end={vec(0, maskY + maskTotalHeight)}
+            positions={[0, vRatioTop, 1 - vRatioBottom, 1]}
+            start={vec(0, maskY)}
+          />
+        </SkiaRect>
+      </Group>
+    </Group>
+  ) : (
+    content
+  );
+
+  if (opacity) {
+    return <Group layer={<Paint opacity={opacity} />}>{maskedContent}</Group>;
+  }
+
+  return maskedContent;
+};

package/src/skia/SymbolSlot.tsx

@@ -0,0 +1,120 @@
+import { Group, Paint, Text as SkiaText } from "@shopify/react-native-skia";
+import React, { useMemo, useState } from "react";
+import {
+  Easing,
+  makeMutable,
+  type SharedValue,
+  useAnimatedReaction,
+  useDerivedValue,
+  withTiming,
+} from "react-native-reanimated";
+import { getSuperscriptTransform } from "../core/superscript";
+import type { SkiaNumberFlowProps, TimingConfig } from "../core/types";
+import { useAnimatedX } from "../core/useAnimatedX";
+import { useSlotOpacity } from "../core/useSlotOpacity";
+
+// Timing for smooth prefix/suffix animation during scrubbing
+const WORKLET_X_ANIMATION_MS = 150;
+
+interface SymbolSlotProps {
+  char: string;
+  targetX: number;
+  baseY: number;
+  ascent: number;
+  color: string;
+  font: NonNullable<SkiaNumberFlowProps["font"]>;
+  opacityTiming: TimingConfig;
+  transformTiming: TimingConfig;
+  entering: boolean;
+  exiting: boolean;
+  exitKey?: string;
+  onExitComplete?: (key: string) => void;
+  workletLayout?: SharedValue<{ x: number; width: number }[]>;
+  slotIndex?: number;
+  superscript?: boolean;
+}
+
+export const SymbolSlot = React.memo(
+  ({
+    char,
+    targetX,
+    baseY,
+    ascent,
+    color,
+    font,
+    opacityTiming,
+    transformTiming,
+    entering,
+    exiting,
+    exitKey,
+    onExitComplete,
+    workletLayout,
+    slotIndex,
+    superscript,
+  }: SymbolSlotProps) => {
+    const slotOpacity = useSlotOpacity({
+      entering,
+      exiting,
+      opacityTiming,
+      exitKey,
+      onExitComplete,
+    });
+
+    const animatedX = useAnimatedX(targetX, exiting, transformTiming);
+
+    /**
+     * Animated X position (worklet-driven).
+     * Unlike digits (which need instant response for scrubbing),
+     * symbols (prefix/suffix) should animate smoothly when the layout
+     * shifts due to digit count changes. This prevents jarring jumps.
+     */
+    const [workletAnimatedX] = useState(() => makeMutable(targetX));
+
+    useAnimatedReaction(
+      () => {
+        const wl = workletLayout?.value;
+        if (wl && slotIndex !== undefined && slotIndex < wl.length) {
+          return wl[slotIndex].x;
+        }
+        return null;
+      },
+      (newX, prevX) => {
+        if (newX !== null && newX !== prevX) {
+          workletAnimatedX.value = withTiming(newX, {
+            duration: WORKLET_X_ANIMATION_MS,
+            easing: Easing.out(Easing.ease),
+          });
+        }
+      },
+    );
+
+    const groupTransform = useDerivedValue(() => {
+      const wl = workletLayout?.value;
+      if (wl && slotIndex !== undefined && slotIndex < wl.length) {
+        return [{ translateX: workletAnimatedX.value }];
+      }
+      return [{ translateX: animatedX.value }];
+    });
+
+    const superscriptTransform = useMemo(
+      () => (superscript ? getSuperscriptTransform(baseY, ascent) : undefined),
+      [superscript, baseY, ascent],
+    );
+
+    const opacityPaint = useMemo(() => <Paint opacity={slotOpacity} />, [slotOpacity]);
+
+    const textElement = <SkiaText color={color} font={font} text={char} x={0} y={baseY} />;
+
+    return (
+      <Group layer={opacityPaint} transform={groupTransform}>
+        {superscriptTransform ? (
+          <Group transform={superscriptTransform}>{textElement}</Group>
+        ) : (
+          textElement
+        )}
+      </Group>
+    );
+  },
+);
+
+SymbolSlot.displayName = "SymbolSlot";

package/src/skia/index.ts

@@ -0,0 +1,5 @@
+export { SkiaNumberFlow } from "./SkiaNumberFlow";
+export { SkiaTimeFlow } from "./SkiaTimeFlow";
+export { useSkiaFont } from "./useSkiaFont";
+export type { SkiaNumberFlowProps } from "../core/types";
+export type { SkiaTimeFlowProps } from "../core/timeTypes";

package/src/skia/renderSlots.tsx

@@ -0,0 +1,180 @@
+import type { SkFont } from "@shopify/react-native-skia";
+import type { SharedValue } from "react-native-reanimated";
+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;
+  font: SkFont;
+  color: string;
+  baseY: number;
+  resolvedTrend: Trend;
+  spinTiming: TimingConfig;
+  opacityTiming: TimingConfig;
+  transformTiming: TimingConfig;
+  spinGenerations: Map<string, number> | undefined;
+  digitCountResolver: (key: string) => number;
+  maskTop: number;
+  maskBottom: number;
+  digitStrings?: string[];
+  workletDigitValues?: SharedValue<number>[] | null;
+  workletLayout?: SharedValue<{ x: number; width: number }[]>;
+}
+
+/**
+ * Renders the active and exiting digit/symbol slot tree for Skia.
+ *
+ * Shared between SkiaNumberFlow and SkiaTimeFlow. Behavioral differences:
+ * - `digitCountResolver`: NumberFlow uses getDigitCount, TimeFlow uses TIME_DIGIT_COUNTS
+ * - `digitStrings`: NumberFlow passes locale-specific digits, TimeFlow omits (Latin fallback)
+ * - `workletLayout`: NumberFlow passes for scrubbing positioning, TimeFlow omits
+ */
+export function renderSlots({
+  layout,
+  exitingEntries,
+  prevMap,
+  isInitialRender,
+  onExitComplete,
+  metrics,
+  font,
+  color,
+  baseY,
+  resolvedTrend,
+  spinTiming,
+  opacityTiming,
+  transformTiming,
+  spinGenerations,
+  digitCountResolver,
+  maskTop,
+  maskBottom,
+  digitStrings,
+  workletDigitValues,
+  workletLayout,
+}: RenderSlotsParams) {
+  let digitIndex = 0;
+  let slotIndex = 0;
+
+  return (
+    <>
+      {/* Active entries */}
+      {layout.map((entry) => {
+        const isEntering = !isInitialRender && !prevMap.has(entry.key);
+        const currentSlotIndex = slotIndex++;
+
+        if (entry.isDigit) {
+          const wdv = workletDigitValues?.[digitIndex];
+          const digitCount = digitCountResolver(entry.key);
+          const spinGeneration = spinGenerations?.get(entry.key);
+
+          digitIndex++;
+
+          return (
+            <DigitSlot
+              baseY={baseY}
+              charWidth={entry.width}
+              color={color}
+              continuousSpinGeneration={spinGeneration}
+              digitCount={digitCount}
+              digitStrings={digitStrings}
+              digitValue={entry.digitValue}
+              entering={isEntering}
+              exiting={false}
+              font={font}
+              key={entry.key}
+              maskTop={maskTop}
+              maskBottom={maskBottom}
+              metrics={metrics}
+              opacityTiming={opacityTiming}
+              slotIndex={workletLayout ? currentSlotIndex : undefined}
+              spinTiming={spinTiming}
+              superscript={entry.superscript}
+              targetX={entry.x}
+              transformTiming={transformTiming}
+              trend={resolvedTrend}
+              workletDigitValue={wdv}
+              workletLayout={workletLayout}
+            />
+          );
+        }
+
+        return (
+          <SymbolSlot
+            ascent={metrics.ascent}
+            baseY={baseY}
+            char={entry.char}
+            color={color}
+            entering={isEntering}
+            exiting={false}
+            font={font}
+            key={entry.key}
+            opacityTiming={opacityTiming}
+            slotIndex={workletLayout ? currentSlotIndex : undefined}
+            superscript={entry.superscript}
+            targetX={entry.x}
+            transformTiming={transformTiming}
+            workletLayout={workletLayout}
+          />
+        );
+      })}
+
+      {/* Exiting entries */}
+      {Array.from(exitingEntries.entries()).map(([key, entry]) => {
+        if (entry.isDigit) {
+          const digitCount = digitCountResolver(key);
+
+          return (
+            <DigitSlot
+              baseY={baseY}
+              charWidth={entry.width}
+              color={color}
+              digitCount={digitCount}
+              digitStrings={digitStrings}
+              digitValue={entry.digitValue}
+              entering={false}
+              exitKey={key}
+              exiting
+              font={font}
+              key={key}
+              maskTop={maskTop}
+              maskBottom={maskBottom}
+              metrics={metrics}
+              onExitComplete={onExitComplete}
+              opacityTiming={opacityTiming}
+              spinTiming={spinTiming}
+              superscript={entry.superscript}
+              targetX={entry.x}
+              transformTiming={transformTiming}
+              trend={resolvedTrend}
+            />
+          );
+        }
+
+        return (
+          <SymbolSlot
+            ascent={metrics.ascent}
+            baseY={baseY}
+            char={entry.char}
+            color={color}
+            entering={false}
+            exitKey={key}
+            exiting
+            font={font}
+            key={key}
+            onExitComplete={onExitComplete}
+            opacityTiming={opacityTiming}
+            superscript={entry.superscript}
+            targetX={entry.x}
+            transformTiming={transformTiming}
+          />
+        );
+      })}
+    </>
+  );
+}

package/src/skia/useGlyphMetrics.ts

@@ -0,0 +1,79 @@
+import type { SkFont } from "@shopify/react-native-skia";
+import { useMemo } from "react";
+import { MEASURABLE_CHARS } from "../core/constants";
+import type { GlyphMetrics } from "../core/types";
+
+/**
+ * Pre-computes glyph width lookup table and line metrics from an SkFont.
+ * Runs once on font load. All measurements use advance widths (not bounding boxes)
+ * for correct text layout spacing.
+ *
+ * Digit slots use `maxDigitWidth` (the widest of 0-9) for the clip window
+ * so all 10 digit glyphs fit during rolling. Individual digit positions
+ * within the clip use proportional charWidths for natural spacing.
+ *
+ * @param font - The SkFont to measure
+ * @param additionalChars - Optional additional characters to measure (e.g., from prefix/suffix with diacritics)
+ */
+export function useGlyphMetrics(
+  font: SkFont | null,
+  additionalChars?: string,
+  localeDigitStrings?: string[],
+): GlyphMetrics | null {
+  return useMemo(() => {
+    if (!font) return null;
+
+    /**
+     * Combine base chars with any additional chars from prefix/suffix so
+     * diacritics and special characters get proper width measurements.
+     */
+    let charsToMeasure = MEASURABLE_CHARS;
+    if (additionalChars) {
+      const uniqueAdditional = additionalChars
+        .split("")
+        .filter((c) => !MEASURABLE_CHARS.includes(c))
+        .join("");
+      if (uniqueAdditional) {
+        charsToMeasure = MEASURABLE_CHARS + uniqueAdditional;
+      }
+    }
+
+    const glyphIDs = font.getGlyphIDs(charsToMeasure);
+    const widths = font.getGlyphWidths(glyphIDs);
+
+    const charWidths: Record<string, number> = {};
+    for (let i = 0; i < charsToMeasure.length; i++) {
+      charWidths[charsToMeasure[i]] = widths[i];
+    }
+
+    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;
+    }
+
+    const metrics = font.getMetrics();
+    // ascent is negative (above baseline), descent is positive (below baseline)
+    const lineHeight = Math.ceil(metrics.descent - metrics.ascent);
+
+    // Per-character tight vertical bounds from measureText SkRect.
+    // rect.y = top of glyph (negative = above baseline),
+    // rect.y + rect.height = bottom of glyph (positive = below baseline).
+    const charBounds: Record<string, { top: number; bottom: number }> = {};
+    for (let i = 0; i < charsToMeasure.length; i++) {
+      const char = charsToMeasure[i];
+      const rect = font.measureText(char);
+      charBounds[char] = { top: rect.y, bottom: rect.y + rect.height };
+    }
+
+    return {
+      charWidths,
+      maxDigitWidth,
+      lineHeight,
+      ascent: metrics.ascent,
+      descent: metrics.descent,
+      charBounds,
+    };
+  }, [font, additionalChars, localeDigitStrings]);
+}