number-flow-react-native 0.1.0

package/src/core/numerals/digits.ts

@@ -0,0 +1,102 @@
+import { HANIDEC_DIGITS, LATIN_ZERO, ZERO_CODEPOINTS } from "./tables";
+
+const digitStringsCache = new Map<string, string[]>();
+
+/**
+ * Returns the numeric value (0-9) of a hanidec character code,
+ * or -1 if the code is not a hanidec digit.
+ *
+ * Uses a switch with literal hex values (not the HANIDEC_CODEPOINTS array)
+ * to guarantee safe serialization in Reanimated worklets.
+ */
+export function hanidecDigitValue(charCode: number): number {
+  "worklet";
+  switch (charCode) {
+    case 0x3007: return 0;  // 〇
+    case 0x4e00: return 1;  // 一
+    case 0x4e8c: return 2;  // 二
+    case 0x4e09: return 3;  // 三
+    case 0x56db: return 4;  // 四
+    case 0x4e94: return 5;  // 五
+    case 0x516d: return 6;  // 六
+    case 0x4e03: return 7;  // 七
+    case 0x516b: return 8;  // 八
+    case 0x4e5d: return 9;  // 九
+    default: return -1;
+  }
+}
+
+/**
+ * Returns the Unicode codepoint of digit zero for a numbering system.
+ * Falls back to Latin (48) for unknown or supplementary-plane systems.
+ * For hanidec, returns 0x3007 as a sentinel (digits are non-contiguous).
+ */
+export function getZeroCodePoint(numberingSystem: string): number {
+  return ZERO_CODEPOINTS[numberingSystem] ?? LATIN_ZERO;
+}
+
+/**
+ * Builds an array of 10 digit strings for a numbering system.
+ * digitStrings[0] = zero character, digitStrings[9] = nine character.
+ */
+export function getDigitStrings(numberingSystem: string): string[] {
+  const cached = digitStringsCache.get(numberingSystem);
+  if (cached) return cached;
+
+  if (numberingSystem === "hanidec") {
+    digitStringsCache.set("hanidec", HANIDEC_DIGITS);
+    return HANIDEC_DIGITS;
+  }
+
+  const zeroCP = getZeroCodePoint(numberingSystem);
+  const strings = Array.from({ length: 10 }, (_, i) => String.fromCharCode(zeroCP + i));
+
+  digitStringsCache.set(numberingSystem, strings);
+  return strings;
+}
+
+/**
+ * Returns the numeric value (0-9) of a character code in the given system,
+ * or -1 if the code is not a digit in that system.
+ *
+ * Worklet-safe. Handles hanidec (non-contiguous) via sentinel zeroCodePoint = 0x3007.
+ */
+export function localeDigitValue(charCode: number, zeroCodePoint: number): number {
+  "worklet";
+  if (zeroCodePoint === 0x3007) return hanidecDigitValue(charCode);
+
+  const value = charCode - zeroCodePoint;
+  return value >= 0 && value <= 9 ? value : -1;
+}
+
+/**
+ * Checks if a character code is a digit in the given numbering system.
+ * Worklet-safe. Handles hanidec via sentinel zeroCodePoint = 0x3007.
+ */
+export function isLocaleDigit(charCode: number, zeroCodePoint: number): boolean {
+  "worklet";
+  return localeDigitValue(charCode, zeroCodePoint) >= 0;
+}
+
+/**
+ * Checks if a single character is a digit in the given numbering system.
+ * Convenience wrapper over localeDigitValue for string-based callers.
+ * Worklet-safe.
+ */
+export function isDigitChar(char: string, zeroCodePoint = 48): boolean {
+  "worklet";
+  return localeDigitValue(char.charCodeAt(0), zeroCodePoint) >= 0;
+}
+
+/**
+ * Counts the number of digit characters in a string for a given numbering system.
+ * Worklet-safe.
+ */
+export function countDigits(text: string, zeroCodePoint: number): number {
+  "worklet";
+  let count = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (localeDigitValue(text.charCodeAt(i), zeroCodePoint) >= 0) count++;
+  }
+  return count;
+}

package/src/core/numerals/index.ts

@@ -0,0 +1,9 @@
+export { detectNumberingSystem, detectOutputZeroCodePoint } from "./detection";
+export {
+  countDigits,
+  getDigitStrings,
+  getZeroCodePoint,
+  isDigitChar,
+  isLocaleDigit,
+  localeDigitValue,
+} from "./digits";

package/src/core/numerals/tables.ts

@@ -0,0 +1,112 @@
+/**
+ * Lookup tables for numeral system support.
+ *
+ * Most Unicode decimal digit systems use 10 contiguous codepoints (0-9),
+ * enabling digit detection via: digitValue = charCode - zeroCodePoint.
+ *
+ * Exception: hanidec (〇一二三四五六七八九) uses non-contiguous ideographs.
+ * Functions that accept a zeroCodePoint use 0x3007 as a sentinel to trigger
+ * the hanidec lookup path.
+ *
+ * Only BMP (Basic Multilingual Plane, U+0000-U+FFFF) systems are supported
+ * because the codebase uses charCodeAt-based indexing in worklets.
+ * Supplementary plane systems (adlm) fall back to Latin digits.
+ */
+
+export const LATIN_ZERO = 0x0030; // 48
+export const HANIDEC_ZERO = 0x3007;
+
+export const HANIDEC_DIGITS = ["〇", "一", "二", "三", "四", "五", "六", "七", "八", "九"];
+
+/**
+ * Map of CLDR numbering system name → Unicode codepoint of digit zero.
+ * Only includes BMP systems (codepoint <= 0xFFFF).
+ * hanidec uses 0x3007 as a sentinel — the remaining digits are non-contiguous.
+ */
+export const ZERO_CODEPOINTS: Record<string, number> = {
+  latn: 0x0030,
+  arab: 0x0660,
+  arabext: 0x06f0,
+  bali: 0x1b50,
+  beng: 0x09e6,
+  cham: 0xaa50,
+  deva: 0x0966,
+  fullwide: 0xff10,
+  gujr: 0x0ae6,
+  guru: 0x0a66,
+  hanidec: 0x3007,
+  java: 0xa9d0,
+  kali: 0xa900,
+  khmr: 0x17e0,
+  knda: 0x0ce6,
+  lana: 0x1a80,
+  lanatham: 0x1a90,
+  laoo: 0x0ed0,
+  lepc: 0x1c40,
+  limb: 0x1946,
+  mlym: 0x0d66,
+  mong: 0x1810,
+  mtei: 0xabf0,
+  mymr: 0x1040,
+  mymrshan: 0x1090,
+  nkoo: 0x07c0,
+  olck: 0x1c50,
+  orya: 0x0b66,
+  saur: 0xa8d0,
+  sinh: 0x0de6,
+  sund: 0x1bb0,
+  talu: 0x19d0,
+  tamldec: 0x0be6,
+  telu: 0x0c66,
+  thai: 0x0e50,
+  tibt: 0x0f20,
+  vaii: 0xa620,
+};
+
+/**
+ * CLDR default numbering systems for locales where the platform (Hermes)
+ * may fall back to "latn" despite the locale specifying a different system.
+ *
+ * Only includes locales whose CLDR default differs from "latn".
+ * Key format: language subtag or language-region (e.g. "ar", "ar-EG").
+ */
+export const CLDR_DEFAULT_NUMBERING: Record<string, string> = {
+  ar: "arab",
+  "ar-AE": "arab",
+  "ar-BH": "arab",
+  "ar-EG": "arab",
+  "ar-IQ": "arab",
+  "ar-JO": "arab",
+  "ar-KW": "arab",
+  "ar-LB": "arab",
+  "ar-OM": "arab",
+  "ar-QA": "arab",
+  "ar-SA": "arab",
+  "ar-SD": "arab",
+  "ar-SY": "arab",
+  "ar-YE": "arab",
+  as: "beng",
+  "as-IN": "beng",
+  bn: "beng",
+  "bn-BD": "beng",
+  "bn-IN": "beng",
+  ckb: "arab",
+  "ckb-IQ": "arab",
+  dz: "tibt",
+  "dz-BT": "tibt",
+  fa: "arabext",
+  "fa-IR": "arabext",
+  ks: "arabext",
+  "ks-IN": "arabext",
+  mr: "deva",
+  "mr-IN": "deva",
+  my: "mymr",
+  "my-MM": "mymr",
+  ne: "deva",
+  "ne-NP": "deva",
+  ps: "arabext",
+  "ps-AF": "arabext",
+  sat: "olck",
+  "sat-IN": "olck",
+  "ur-IN": "arabext",
+};

package/src/core/superscript.ts

@@ -0,0 +1,27 @@
+import type { TextStyle } from "react-native";
+import { SUPERSCRIPT_SCALE } from "./constants";
+
+/**
+ * Returns the scaled TextStyle for superscript rendering in native slots.
+ * Reduces fontSize and lineHeight by SUPERSCRIPT_SCALE.
+ */
+export function getSuperscriptTextStyle(textStyle: TextStyle, lineHeight: number): TextStyle {
+  return {
+    ...textStyle,
+    fontSize: (textStyle.fontSize ?? 16) * SUPERSCRIPT_SCALE,
+    lineHeight,
+  };
+}
+
+/**
+ * Returns the pivot-scale transform array for superscript rendering in Skia slots.
+ * Pivots around the text top so the digit shrinks downward within the mask region.
+ */
+export function getSuperscriptTransform(
+  baseY: number,
+  ascent: number,
+): ({ translateY: number } | { scale: number })[] {
+  const textTop = baseY + ascent;
+
+  return [{ translateY: textTop }, { scale: SUPERSCRIPT_SCALE }, { translateY: -textTop }];
+}

package/src/core/timeLayout.ts

@@ -0,0 +1,119 @@
+import { assignXPositions, type CharLayout } from "./layout";
+import type { GlyphMetrics, TextAlign } from "./types";
+import { isDigitChar, localeDigitValue } from "./numerals";
+
+/**
+ * Keys for each digit position within a time segment.
+ * Index 0 = tens digit, index 1 = ones digit.
+ */
+const HOUR_KEYS = ["h10", "h1"] as const;
+const MINUTE_KEYS = ["m10", "m1"] as const;
+const SECOND_KEYS = ["s10", "s1"] as const;
+
+function pushChar(
+  chars: CharLayout[],
+  key: string,
+  char: string,
+  metrics: GlyphMetrics,
+  zeroCodePoint = 48,
+): void {
+  const isDigit = isDigitChar(char, zeroCodePoint);
+  const width = metrics.charWidths[char] ?? metrics.maxDigitWidth;
+  chars.push({
+    key,
+    char,
+    isDigit,
+    digitValue: isDigit ? localeDigitValue(char.charCodeAt(0), zeroCodePoint) : -1,
+    x: 0,
+    width,
+  });
+}
+
+/**
+ * Pushes a group of digit characters with the given key array.
+ * If the digit string is shorter than the keys array (e.g. single-digit hour),
+ * only the last N keys are used (matching the useTimeFormatting behavior where
+ * h10 is omitted for single-digit hours).
+ */
+function pushDigitGroup(
+  chars: CharLayout[],
+  digits: string,
+  keys: readonly string[],
+  metrics: GlyphMetrics,
+): void {
+  const offset = keys.length - digits.length;
+  for (let i = 0; i < digits.length; i++) {
+    pushChar(chars, keys[offset + i], digits[i], metrics);
+  }
+}
+
+/**
+ * Computes time-aware string layout with fixed semantic keys.
+ *
+ * Unlike `computeStringLayout` which uses positional keys (`pos:0`, `pos:1`),
+ * this function assigns the same fixed keys (h10, h1, sep, m10, m1, etc.)
+ * that `useTimeFormatting` produces. This ensures worklet-driven updates
+ * produce stable keys that match prop-driven updates.
+ *
+ * @param timeString - Formatted time string like "14:30", "9:30", "2:30 PM", "05:30"
+ * @param metrics - Glyph measurement data
+ * @param totalWidth - Available width for alignment
+ * @param textAlign - Text alignment within totalWidth
+ * @param hasHours - Whether the hours segment is shown (determines how to interpret segments)
+ * @param hasSeconds - Whether the seconds segment is shown
+ */
+export function computeTimeStringLayout(
+  timeString: string,
+  metrics: GlyphMetrics,
+  totalWidth: number,
+  textAlign: TextAlign,
+  hasHours: boolean,
+  hasSeconds: boolean,
+): CharLayout[] {
+  const chars: CharLayout[] = [];
+
+  let ampmLabel: string | null = null;
+  let timePart = timeString;
+  if (timePart.endsWith(" AM")) {
+    ampmLabel = "AM";
+    timePart = timePart.slice(0, -3);
+  } else if (timePart.endsWith(" PM")) {
+    ampmLabel = "PM";
+    timePart = timePart.slice(0, -3);
+  }
+
+  const segments = timePart.split(":");
+
+  if (hasHours && hasSeconds && segments.length === 3) {
+    // HH:MM:SS
+    pushDigitGroup(chars, segments[0], HOUR_KEYS, metrics);
+    pushChar(chars, "sep", ":", metrics);
+    pushDigitGroup(chars, segments[1], MINUTE_KEYS, metrics);
+    pushChar(chars, "sep2", ":", metrics);
+    pushDigitGroup(chars, segments[2], SECOND_KEYS, metrics);
+  } else if (hasHours && !hasSeconds && segments.length >= 2) {
+    // HH:MM
+    pushDigitGroup(chars, segments[0], HOUR_KEYS, metrics);
+    pushChar(chars, "sep", ":", metrics);
+    pushDigitGroup(chars, segments[1], MINUTE_KEYS, metrics);
+  } else if (!hasHours && hasSeconds && segments.length >= 2) {
+    // MM:SS (countdown mode)
+    pushDigitGroup(chars, segments[0], MINUTE_KEYS, metrics);
+    pushChar(chars, "sep2", ":", metrics);
+    pushDigitGroup(chars, segments[1], SECOND_KEYS, metrics);
+  } else {
+    // Fallback: just minutes (shouldn't normally happen)
+    pushDigitGroup(chars, segments[0], MINUTE_KEYS, metrics);
+  }
+
+  // AM/PM suffix — individual characters with value-dependent keys
+  if (ampmLabel) {
+    pushChar(chars, "ampm-sp", " ", metrics);
+    for (let i = 0; i < ampmLabel.length; i++) {
+      pushChar(chars, `ampm:${ampmLabel}:${i}`, ampmLabel[i], metrics);
+    }
+  }
+
+  assignXPositions(chars, totalWidth, textAlign);
+  return chars;
+}

package/src/core/timeTypes.ts

@@ -0,0 +1,88 @@
+import type { SkFont } from "@shopify/react-native-skia";
+import type { ViewStyle } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+import type { NumberFlowStyle } from "../native/types";
+import type { AnimationBehaviorProps, TextAlign } from "./types";
+
+interface TimeFlowBaseProps extends AnimationBehaviorProps {
+  /** Use 24-hour format. Default: true. Only applies when hours are shown. */
+  is24Hour?: boolean;
+  /** Pad hours with leading zero. Default: true. "09:30" vs "9:30". */
+  padHours?: boolean;
+
+  /** Text styling. fontSize is required; fontFamily defaults to the platform system font. */
+  style: NumberFlowStyle;
+  /** Text alignment. Defaults to "left". */
+  textAlign?: TextAlign;
+  /** Style applied to the outer container View */
+  containerStyle?: ViewStyle;
+}
+
+interface TimeFlowValueProps {
+  /** Hours value (0-23). Omit to hide the hours segment (countdown MM:SS mode). */
+  hours?: number;
+  /** Minutes value (0-59). Required. */
+  minutes: number;
+  /** Seconds value (0-59). Omit to hide the seconds segment. */
+  seconds?: number;
+  /** Unix timestamp in ms. Extracts hours/minutes/seconds automatically. Takes priority over direct values. */
+  timestamp?: number;
+  /** Timezone offset in ms for timestamp mode. */
+  timezoneOffset?: number;
+}
+
+/** Props for TimeFlow. Accessibility is built-in: accessibilityRole="text" and accessibilityLabel are set automatically. */
+export type TimeFlowProps = TimeFlowBaseProps & TimeFlowValueProps;
+
+interface SkiaTimeFlowBaseProps extends AnimationBehaviorProps {
+  /** Use 24-hour format. Default: true. Only applies when hours are shown. */
+  is24Hour?: boolean;
+  /** Pad hours with leading zero. Default: true. "09:30" vs "9:30". */
+  padHours?: boolean;
+
+  /** 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;
+  /** Parent opacity (SharedValue for animation coordination) */
+  opacity?: SharedValue<number>;
+}
+
+type SkiaTimeFlowValueProps =
+  | {
+      /** Hours value (0-23). Omit to hide the hours segment. */
+      hours?: number;
+      /** Minutes value (0-59). Required when using direct time values. */
+      minutes: number;
+      /** Seconds value (0-59). Omit to hide the seconds segment. */
+      seconds?: number;
+      /** Unix timestamp in ms. Extracts hours/minutes/seconds automatically. */
+      timestamp?: number;
+      /** Timezone offset in ms for timestamp mode. */
+      timezoneOffset?: number;
+      sharedValue?: never;
+    }
+  | {
+      hours?: never;
+      minutes?: never;
+      seconds?: never;
+      timestamp?: never;
+      timezoneOffset?: never;
+      /** Worklet-driven pre-formatted time string (e.g. "14:30", "2:30 PM"). */
+      sharedValue: SharedValue<string>;
+    };
+
+/**
+ * Props for SkiaTimeFlow.
+ * Value changes are auto-announced for screen reader users.
+ * For VoiceOver/TalkBack focus-based reading, set `accessibilityLabel` on the parent Canvas.
+ */
+export type SkiaTimeFlowProps = SkiaTimeFlowBaseProps & SkiaTimeFlowValueProps;

package/src/core/timing.ts

@@ -0,0 +1,60 @@
+import { Easing } from "react-native-reanimated";
+import type { TimingConfig } from "./types";
+
+/**
+ * NumberFlow's CSS linear() easing function — exact reproduction.
+ * A smooth deceleration curve defined by 90 evenly-spaced control points.
+ */
+const NUMBER_FLOW_EASING_POINTS = [
+  0, 0.005, 0.019, 0.039, 0.066, 0.096, 0.129, 0.165, 0.202, 0.24, 0.278, 0.316, 0.354, 0.39, 0.426,
+  0.461, 0.494, 0.526, 0.557, 0.586, 0.614, 0.64, 0.665, 0.689, 0.711, 0.731, 0.751, 0.769, 0.786,
+  0.802, 0.817, 0.831, 0.844, 0.856, 0.867, 0.877, 0.887, 0.896, 0.904, 0.912, 0.919, 0.925, 0.931,
+  0.937, 0.942, 0.947, 0.951, 0.955, 0.959, 0.962, 0.965, 0.968, 0.971, 0.973, 0.976, 0.978, 0.98,
+  0.981, 0.983, 0.984, 0.986, 0.987, 0.988, 0.989, 0.99, 0.991, 0.992, 0.992, 0.993, 0.994, 0.994,
+  0.995, 0.995, 0.996, 0.996, 0.9963, 0.9967, 0.9969, 0.9972, 0.9975, 0.9977, 0.9979, 0.9981,
+  0.9982, 0.9984, 0.9985, 0.9987, 0.9988, 0.9989, 1,
+] as const;
+
+/**
+ * NumberFlow's default transform easing — smooth deceleration curve.
+ * Piecewise linear interpolation over the control points above,
+ * recreating CSS linear() easing from the Web Animations API.
+ */
+const numberFlowEasing = (t: number) => {
+  "worklet";
+
+  const lastIndex = NUMBER_FLOW_EASING_POINTS.length - 1;
+
+  if (t <= 0) return NUMBER_FLOW_EASING_POINTS[0];
+  if (t >= 1) return NUMBER_FLOW_EASING_POINTS[lastIndex];
+
+  const scaledT = t * lastIndex;
+  const index = Math.floor(scaledT);
+  const fraction = scaledT - index;
+
+  return (
+    NUMBER_FLOW_EASING_POINTS[index] +
+    (NUMBER_FLOW_EASING_POINTS[index + 1] - NUMBER_FLOW_EASING_POINTS[index]) * fraction
+  );
+};
+
+export const DEFAULT_TRANSFORM_TIMING: TimingConfig = {
+  duration: 900,
+  easing: numberFlowEasing,
+};
+
+// How long a digit spins before settling into its final position
+export const DEFAULT_SPIN_TIMING: TimingConfig = DEFAULT_TRANSFORM_TIMING;
+
+export const DEFAULT_OPACITY_TIMING: TimingConfig = {
+  duration: 450,
+  easing: Easing.out(Easing.ease),
+};
+
+export const ZERO_TIMING: TimingConfig = {
+  duration: 0,
+  easing: (t: number) => {
+    "worklet";
+    return t;
+  },
+};