react-native-transformer-text-input 0.1.0-alpha.0

package/src/formatters/phone-number.ts

@@ -0,0 +1,327 @@
+import { Transformer, type Selection } from '../Transformer';
+
+export type PhoneNumberTransformerOptions = {
+  /**
+   * Country code for phone number formatting.
+   * Currently only 'US' is supported.
+   * @default 'US'
+   */
+  country?: 'US';
+  /**
+   * Enable debug logging for transformer operations.
+   * @default false
+   */
+  debug?: boolean;
+};
+
+// Check if char is a digit
+const isDigit = (char: string | undefined): boolean => {
+  'worklet';
+  return char !== undefined && char >= '0' && char <= '9';
+};
+
+// Count national digits before a position
+// Always skips the first "1" digit when we have/will have +1 prefix
+const countNationalDigitsBefore = (text: string, pos: number): number => {
+  'worklet';
+  let count = 0;
+  let skippedCountryOne = false;
+  for (let i = 0; i < Math.min(pos, text.length); i++) {
+    if (isDigit(text[i])) {
+      // Skip the "1" in "+1" prefix
+      if (
+        !skippedCountryOne &&
+        text[i] === '1' &&
+        i > 0 &&
+        text[i - 1] === '+'
+      ) {
+        skippedCountryOne = true;
+      } else {
+        count++;
+      }
+    }
+  }
+  return count;
+};
+
+// Find position in formatted text after N national digits
+const positionAfterNationalDigit = (
+  text: string,
+  targetCount: number,
+): number => {
+  'worklet';
+  if (targetCount <= 0) {
+    // Position after "+1 " prefix if present, else 0
+    if (text.startsWith('+1 ')) return 3;
+    if (text.startsWith('+1')) return 2;
+    return 0;
+  }
+  let count = 0;
+  let skippedCountryOne = false;
+  for (let i = 0; i < text.length; i++) {
+    if (isDigit(text[i])) {
+      if (
+        !skippedCountryOne &&
+        text[i] === '1' &&
+        i > 0 &&
+        text[i - 1] === '+'
+      ) {
+        skippedCountryOne = true;
+      } else {
+        count++;
+        if (count === targetCount) return i + 1;
+      }
+    }
+  }
+  return text.length;
+};
+
+// Format national digits into US phone format
+const formatUSPhoneNumber = (digits: string): string => {
+  'worklet';
+  const area = digits.slice(0, 3);
+  const exchange = digits.slice(3, 6);
+  const subscriber = digits.slice(6, 10);
+
+  let formatted = '+1 ';
+
+  if (area.length > 0) {
+    formatted += '(' + area;
+    if (area.length === 3) {
+      formatted += ') ';
+    }
+  }
+
+  if (exchange.length > 0) {
+    formatted += exchange;
+    if (exchange.length === 3 && subscriber.length > 0) {
+      formatted += '-';
+    }
+  }
+
+  if (subscriber.length > 0) {
+    formatted += subscriber;
+  }
+
+  return formatted;
+};
+
+export class PhoneNumberTransformer extends Transformer {
+  constructor({
+    country = 'US',
+    debug = false,
+  }: PhoneNumberTransformerOptions = {}) {
+    if (country !== 'US') {
+      throw new Error(
+        `[PhoneNumberTransformer] Country "${country}" is not supported. Only "US" is currently supported.`,
+      );
+    }
+
+    const worklet = (input: {
+      value: string;
+      previousValue: string;
+      selection: Selection;
+      previousSelection: Selection;
+    }) => {
+      'worklet';
+
+      const { value, selection, previousValue, previousSelection } = input;
+
+      // Extract all digits from input
+      const allDigits = value.replace(/\D/g, '');
+
+      // Empty input - clear everything
+      if (allDigits.length === 0) {
+        return { value: '', selection: { start: 0, end: 0 } };
+      }
+
+      // Get national digits - strip leading "1" if enabled since we always add +1 prefix
+      const nationalDigits = (
+        allDigits.startsWith('1') ? allDigits.slice(1) : allDigits
+      ).slice(0, 10);
+
+      // If no national digits left, check if user is deleting
+      if (nationalDigits.length === 0) {
+        // If value got shorter (user is deleting), clear everything
+        if (value.length < previousValue.length) {
+          if (debug) {
+            console.log('[PhoneNumberTransformer] -> case: deleted to empty');
+          }
+          return { value: '', selection: { start: 0, end: 0 } };
+        }
+        // Otherwise user just typed "1", show the prefix
+        return { value: '+1 ', selection: { start: 3, end: 3 } };
+      }
+
+      const formatted = formatUSPhoneNumber(nationalDigits);
+
+      // Calculate cursor position
+      const isCaret = selection.start === selection.end;
+      const cursorAtEnd = selection.end >= value.length;
+      const prevCursorAtEnd = previousSelection.end >= previousValue.length;
+
+      // Count national digits
+      const digitsBeforeCursor = countNationalDigitsBefore(
+        value,
+        selection.start,
+      );
+      const prevDigitsBeforeCursor = countNationalDigitsBefore(
+        previousValue,
+        previousSelection.start,
+      );
+      const totalDigits = countNationalDigitsBefore(value, value.length);
+      const prevTotalDigits = countNationalDigitsBefore(
+        previousValue,
+        previousValue.length,
+      );
+
+      const isDeleting = totalDigits < prevTotalDigits;
+      const isInserting = totalDigits > prevTotalDigits;
+
+      // Detect deletion of formatting character (e.g., deleting space, dash, or paren)
+      // User expects this to delete the digit before cursor
+      const deletedFormattingChar =
+        isCaret &&
+        value.length < previousValue.length &&
+        totalDigits === prevTotalDigits &&
+        totalDigits > 0;
+
+      // Log for debugging
+      if (debug) {
+        console.log('[PhoneNumberTransformer]', {
+          input: { value, selection },
+          prev: { previousValue, previousSelection },
+          digits: { nationalDigits, totalDigits, prevTotalDigits },
+          cursor: { digitsBeforeCursor, prevDigitsBeforeCursor },
+          flags: {
+            isCaret,
+            cursorAtEnd,
+            prevCursorAtEnd,
+            isDeleting,
+            isInserting,
+            deletedFormattingChar,
+          },
+          output: formatted,
+        });
+      }
+
+      // Case 0: Deleted a formatting char - remove the digit before cursor
+      if (deletedFormattingChar) {
+        // Figure out which digit to remove: the one before the cursor
+        const digitToRemove = digitsBeforeCursor;
+
+        if (digitToRemove <= 0) {
+          // Cursor was before all digits, nothing to delete
+          if (debug) {
+            console.log(
+              '[PhoneNumberTransformer] -> case: deleted formatting char but cursor before all digits',
+            );
+          }
+          return { value: formatted, selection: { start: 3, end: 3 } };
+        }
+
+        // Remove the digit at position (digitToRemove - 1) from nationalDigits
+        const trimmedDigits =
+          nationalDigits.slice(0, digitToRemove - 1) +
+          nationalDigits.slice(digitToRemove);
+
+        if (debug) {
+          console.log(
+            '[PhoneNumberTransformer] -> case: deleted formatting char',
+            {
+              digitToRemove,
+              trimmedDigits,
+            },
+          );
+        }
+
+        if (trimmedDigits.length === 0) {
+          return { value: '', selection: { start: 0, end: 0 } };
+        }
+
+        const trimmedFormatted = formatUSPhoneNumber(trimmedDigits);
+
+        // Position cursor where the deleted digit was
+        const newCursorDigits = digitToRemove - 1;
+        const newPos = positionAfterNationalDigit(
+          trimmedFormatted,
+          newCursorDigits,
+        );
+
+        return {
+          value: trimmedFormatted,
+          selection: { start: newPos, end: newPos },
+        };
+      }
+
+      // Case 1: Typing at end (most common)
+      if (isCaret && cursorAtEnd && prevCursorAtEnd) {
+        if (debug) {
+          console.log('[PhoneNumberTransformer] -> case: typing at end');
+        }
+        return {
+          value: formatted,
+          selection: { start: formatted.length, end: formatted.length },
+        };
+      }
+
+      // Case 2: Deletion - use current cursor position (previous is stale if user moved cursor)
+      if (isDeleting && isCaret) {
+        const newPos = positionAfterNationalDigit(
+          formatted,
+          digitsBeforeCursor,
+        );
+        if (debug) {
+          console.log('[PhoneNumberTransformer] -> case: deletion', {
+            digitsBeforeCursor,
+            newPos,
+          });
+        }
+        return {
+          value: formatted,
+          selection: { start: newPos, end: newPos },
+        };
+      }
+
+      // Case 3: Insertion in middle - use current cursor position
+      if (isInserting && isCaret) {
+        const newPos = positionAfterNationalDigit(
+          formatted,
+          digitsBeforeCursor,
+        );
+        if (debug) {
+          console.log('[PhoneNumberTransformer] -> case: insertion', {
+            digitsBeforeCursor,
+            newPos,
+          });
+        }
+        return {
+          value: formatted,
+          selection: { start: newPos, end: newPos },
+        };
+      }
+
+      // Case 4: Default / selection handling
+      const clampedDigits = Math.min(digitsBeforeCursor, nationalDigits.length);
+      const newStart = positionAfterNationalDigit(formatted, clampedDigits);
+      const endDigits = countNationalDigitsBefore(value, selection.end);
+      const clampedEndDigits = Math.min(endDigits, nationalDigits.length);
+      const newEnd = positionAfterNationalDigit(formatted, clampedEndDigits);
+
+      if (debug) {
+        console.log('[PhoneNumberTransformer] -> case: default', {
+          clampedDigits,
+          newStart,
+          clampedEndDigits,
+          newEnd,
+        });
+      }
+      return {
+        value: formatted,
+        selection: { start: newStart, end: newEnd },
+      };
+    };
+
+    super(worklet);
+  }
+}

package/src/index.tsx

@@ -0,0 +1,10 @@
+export {
+  Transformer,
+  type TransformerWorklet,
+  type Selection,
+} from './Transformer';
+export {
+  TransformerTextInput,
+  type TransformerTextInputInstance,
+  type TransformerTextInputProps,
+} from './TransformerTextInput';

package/src/registry.ts

@@ -0,0 +1,120 @@
+import { runOnUI } from 'react-native-worklets';
+import NativeTransformerTextInputModule from './NativeTransformerTextInputModule';
+import { type Selection, type Transformer } from './Transformer';
+import { computeUncontrolledSelection, validateSelection } from './selection';
+
+type TransformerWrapper = (
+  input: string,
+  selectionStart: number,
+  selectionEnd: number,
+) => { value: string; selection: Selection };
+
+type ReactNativeTextInputTransformerRegistry = {
+  register(id: number, transformer: TransformerWrapper): void;
+  unregister(transformerId: number): void;
+  get(transformerId: number): TransformerWrapper | undefined;
+};
+
+declare global {
+  var __rntti_registerTransformerRegistry:
+    | ReactNativeTextInputTransformerRegistry
+    | undefined;
+}
+
+let initialized = false;
+
+function initializeIfNeeded() {
+  if (initialized) {
+    return;
+  }
+
+  // Important that `runOnUI` is called first to make sure the UI runtime is initialized.
+  runOnUI(() => {
+    'worklet';
+
+    const transformersMap = new Map<number, TransformerWrapper>();
+
+    globalThis.__rntti_registerTransformerRegistry = {
+      register(id, transformer) {
+        transformersMap.set(id, transformer);
+      },
+      unregister(transformerId) {
+        transformersMap.delete(transformerId);
+      },
+      get(transformerId) {
+        return transformersMap.get(transformerId);
+      },
+    };
+  })();
+
+  NativeTransformerTextInputModule.install();
+
+  initialized = true;
+}
+
+// Start counting ids at 1 to avoid using 0 as it is the default int value.
+let currentId = 1;
+
+export function registerTransformer(transformer: Transformer): number {
+  initializeIfNeeded();
+
+  const id = currentId++;
+  const worklet = transformer.worklet;
+
+  runOnUI(() => {
+    'worklet';
+
+    let previousValue: string | null = null;
+    let previousSelection: Selection | null = null;
+
+    const transformerWrapper: TransformerWrapper = (
+      value,
+      selectionStart,
+      selectionEnd,
+    ) => {
+      const result = worklet({
+        value,
+        previousValue: previousValue ?? value,
+        selection: { start: selectionStart, end: selectionEnd },
+        previousSelection: previousSelection ?? {
+          start: selectionStart,
+          end: selectionEnd,
+        },
+      });
+      const newValue = result?.value ?? value;
+      let newSelection: Selection;
+      if (result?.selection != null) {
+        newSelection = result.selection;
+        validateSelection(newSelection, newValue.length);
+      } else {
+        newSelection = computeUncontrolledSelection(
+          value,
+          newValue,
+          selectionStart,
+          selectionEnd,
+        );
+      }
+      previousValue = newValue;
+      previousSelection = newSelection;
+      return {
+        value: newValue,
+        selection: newSelection,
+      };
+    };
+
+    globalThis.__rntti_registerTransformerRegistry?.register(
+      id,
+      transformerWrapper,
+    );
+  })();
+
+  return id;
+}
+
+export function unregisterTransformer(transformerId: number) {
+  runOnUI(() => {
+    'worklet';
+
+    global.__rntti_registerTransformerRegistry?.unregister(transformerId);
+  })();
+}

package/src/selection.ts

@@ -0,0 +1,62 @@
+import { type Selection } from './Transformer';
+
+export const computeUncontrolledSelection = (
+  oldValue: string,
+  newValue: string,
+  selectionStart: number,
+  selectionEnd: number,
+): Selection => {
+  'worklet';
+  const oldLength = oldValue.length;
+  const newLength = newValue.length;
+  const delta = newLength - oldLength;
+  let rawStart: number;
+  let rawEnd: number;
+  if (selectionStart === selectionEnd) {
+    if (selectionEnd >= oldLength) {
+      rawStart = newLength;
+      rawEnd = newLength;
+    } else {
+      const next = selectionEnd + delta;
+      rawStart = next;
+      rawEnd = next;
+    }
+  } else {
+    rawStart = selectionStart + delta;
+    rawEnd = selectionEnd + delta;
+  }
+
+  if (
+    rawStart < 0 ||
+    rawEnd < 0 ||
+    rawStart > newLength ||
+    rawEnd > newLength ||
+    rawStart > rawEnd
+  ) {
+    return { start: newLength, end: newLength };
+  }
+
+  return { start: rawStart, end: rawEnd };
+};
+
+export const validateSelection = (
+  selection: Selection,
+  valueLength: number,
+) => {
+  'worklet';
+  if (selection.start < 0 || selection.end < 0) {
+    throw new Error(
+      `[rntti] Returned selection must be non-negative. Received start=${selection.start}, end=${selection.end}, valueLength=${valueLength}`,
+    );
+  }
+  if (selection.end < selection.start) {
+    throw new Error(
+      `[rntti] Returned selection end must be >= selection start. Received start=${selection.start}, end=${selection.end}, valueLength=${valueLength}`,
+    );
+  }
+  if (selection.start > valueLength || selection.end > valueLength) {
+    throw new Error(
+      `[rntti] Returned selection is out of bounds for the returned value. Received start=${selection.start}, end=${selection.end}, valueLength=${valueLength}`,
+    );
+  }
+};

package/src/utils/useMergeRefs.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import useRefEffect from './useRefEffect';
+import { useCallback } from 'react';
+import type { MutableRefObject } from 'react';
+
+/**
+ * Constructs a new ref that forwards new values to each of the given refs. The
+ * given refs will always be invoked in the order that they are supplied.
+ *
+ * WARNING: A known problem of merging refs using this approach is that if any
+ * of the given refs change, the returned callback ref will also be changed. If
+ * the returned callback ref is supplied as a `ref` to a React element, this may
+ * lead to problems with the given refs being invoked more times than desired.
+ */
+type RefWithCleanup<T> =
+  | ((instance: T | null) => void | (() => void))
+  | MutableRefObject<T | null>
+  | null
+  | undefined;
+
+export default function useMergeRefs<Instance>(
+  ...refs: ReadonlyArray<RefWithCleanup<Instance>>
+): (instance: Instance | null) => void {
+  const refEffect = useCallback(
+    (current: Instance) => {
+      const cleanups: Array<void | (() => void)> = refs.map((ref) => {
+        if (ref == null) {
+          return undefined;
+        }
+        if (typeof ref === 'function') {
+          const cleanup = ref(current);
+          return typeof cleanup === 'function'
+            ? cleanup
+            : () => {
+                ref(null);
+              };
+        }
+        ref.current = current;
+        return () => {
+          ref.current = null;
+        };
+      });
+
+      return () => {
+        for (const cleanup of cleanups) {
+          cleanup?.();
+        }
+      };
+    },
+    [...refs], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+  return useRefEffect(refEffect);
+}

package/src/utils/useRefEffect.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { useCallback, useRef } from 'react';
+
+type CallbackRef<T> = (instance: T | null) => void;
+
+/**
+ * Constructs a callback ref that provides similar semantics as `useEffect`. The
+ * supplied `effect` callback will be called with non-null component instances.
+ * The `effect` callback can also optionally return a cleanup function.
+ *
+ * When a component is updated or unmounted, the cleanup function is called. The
+ * `effect` callback will then be called again, if applicable.
+ *
+ * When a new `effect` callback is supplied, the previously returned cleanup
+ * function will be called before the new `effect` callback is called with the
+ * same instance.
+ *
+ * WARNING: The `effect` callback should be stable (e.g. using `useCallback`).
+ */
+export default function useRefEffect<TInstance>(
+  effect: (instance: TInstance) => (() => void) | void,
+): CallbackRef<TInstance> {
+  const cleanupRef = useRef<(() => void) | void>(undefined);
+  return useCallback(
+    (instance: null | TInstance) => {
+      if (cleanupRef.current) {
+        cleanupRef.current();
+        cleanupRef.current = undefined;
+      }
+      if (instance != null) {
+        cleanupRef.current = effect(instance);
+      }
+    },
+    [effect],
+  );
+}