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

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Janic Duplessis
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# react-native-transformer-text-input
+
+TextInput component that allows transforming text synchronously with a worklet.
+
+## Installation
+```sh
+npm install react-native-transformer-text-input
+```
+
+## Usage
+```tsx
+import { useRef } from 'react';
+import {
+  Transformer,
+  TransformerTextInput,
+  type TransformerTextInputInstance,
+} from 'react-native-transformer-text-input';
+
+// Transformer that formats input as a lowercase username with @ prefix
+const usernameTransformer = new Transformer(({ value }) => {
+  'worklet';
+
+  const cleaned = value.replace(/[^0-9a-zA-Z]/g, '').toLowerCase();
+  return { value: cleaned ? '@' + cleaned : '' };
+});
+
+function UsernameTextInput() {
+  const inputRef = useRef<TransformerTextInputInstance>(null);
+
+  const handleSubmit = () => {
+    const username = inputRef.current?.getValue();
+    console.log('Submitted:', username);
+  };
+
+  return (
+    <TransformerTextInput
+      ref={inputRef}
+      transformer={usernameTransformer}
+      placeholder="@username"
+      autoCapitalize="none"
+      autoCorrect={false}
+      onSubmitEditing={handleSubmit}
+    />
+  );
+}
+```
+
+## API
+
+### Transformer
+
+Create a transformer by passing a worklet function:
+
+- **Constructor**: `new Transformer(worklet)`
+- **worklet input**: an object with
+  - `value`: current text value.
+  - `previousValue`: previous text value (falls back to `value` on first call).
+  - `selection`: current selection `{ start, end }`.
+  - `previousSelection`: previous selection `{ start, end }` (falls back to `selection` on first call).
+- **worklet return**:
+  - Return `null` or `undefined` to apply no transform.
+  - Return an object where each field can also be `null` or `undefined` to leave that part unchanged:
+    - `value?: string | null` to update the text.
+    - `selection?: { start: number; end: number } | null` to update the selection.
+
+### TransformerTextInput
+
+`TransformerTextInput` wraps React Native `TextInput` and applies a `Transformer` on the UI thread.
+
+- **Props**: all `TextInput` props (except `value`) plus:
+  - `transformer`: a `Transformer` instance.
+- **Ref**: `TransformerTextInputInstance` with:
+  - `getValue(): string` - Returns the current text value.
+  - `update(options): void` - Programmatically update the input.
+    - `options.value: string` - The new text value.
+    - `options.selection?: { start: number; end: number }` - Optional cursor/selection position.
+    - `options.transform?: boolean` - Whether to run the transformer on the new value (default: `true`).
+  - `clear(): void` - Clear the input value.
+
+## Notes
+
+- The transformer must be a worklet; the `Transformer` constructor will throw if it isn't.
+- Prefer creating `Transformer` instances at module scope to avoid recreating worklets on every render.
+- This library supports the New Architecture only.
+
+## Selection Control
+
+Selection control is needed because transforms can insert or remove characters, which would otherwise move the cursor unpredictably. The transformer can return a `selection` to fully control the caret/selection after a change.
+
+Default behavior when no `selection` is returned:
+- If the cursor was at the end, it stays at the end.
+- If the cursor was in the middle, it moves forward by the number of inserted/removed characters.
+- If the position is ambiguous, it falls back to the end.
+
+## Built-in Transformers (Experimental)
+
+> **Warning**: Built-in transformers are experimental. Breaking changes may occur in minor versions.
+
+The library includes ready-to-use transformers for common use cases.
+
+### PhoneNumberTransformer
+
+Formats phone numbers as the user types.
+
+```tsx
+import { PhoneNumberTransformer } from 'react-native-transformer-text-input/formatters/phone-number';
+
+const phoneTransformer = new PhoneNumberTransformer({
+  country: 'US',           // Only 'US' supported currently
+  debug: false,            // Enable debug logging (default: false)
+});
+
+// Formats as: +1 (555) 123-4567
+<TransformerTextInput
+  transformer={phoneTransformer}
+  keyboardType="phone-pad"
+/>
+```
+
+## AI Disclosure
+
+Code in this repository is thought through and mostly written by humans, with AI used to improve clarity, consistency, and implementation details.
+
+## Acknowledgments
+
+- [react-native-live-markdown](https://github.com/Expensify/react-native-live-markdown) for an example of how to extend TextInput.
+- [react-native-worklets](https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-worklets) for the worklet runtime powering UI-thread execution.
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/RNTransformerTextInput.podspec

@@ -0,0 +1,35 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+pods_root = Pod::Config.instance.project_pods_root
+react_native_worklets_node_modules_dir = ENV['REACT_NATIVE_WORKLETS_NODE_MODULES_DIR'] ||
+ File.dirname(`cd "#{Pod::Config.instance.installation_root.to_s}" && node --print "require.resolve('react-native-worklets/package.json')"`)
+react_native_worklets_node_modules_dir_from_pods_root = Pathname.new(react_native_worklets_node_modules_dir).relative_path_from(pods_root).to_s
+
+Pod::Spec.new do |s|
+  s.name         = "RNTransformerTextInput"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/AppAndFlow/react-native-transformer-text-input.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{h,m,mm,swift}",
+    "cpp/**/*.{h,cpp}"
+  ]
+  s.private_header_files = "ios/**/*.h"
+
+  install_modules_dependencies(s)
+
+  s.xcconfig = {
+    "HEADER_SEARCH_PATHS" => [
+      "\"$(PODS_ROOT)/#{react_native_worklets_node_modules_dir_from_pods_root}/apple\"",
+      "\"$(PODS_ROOT)/#{react_native_worklets_node_modules_dir_from_pods_root}/Common/cpp\"",
+    ].join(' '),
+  }
+end

package/android/build.gradle

@@ -0,0 +1,96 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.diffplug.spotless:spotless-plugin-gradle:6.25.0"
+  }
+}
+
+if (project == rootProject) {
+  apply from: "spotless.gradle"
+  return
+}
+
+def reactNativeArchitectures() {
+  def value = project.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "com.facebook.react"
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["TransformerInput_" + name]).toInteger()
+}
+
+def getExtOrDefault(name, defaultValue) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["TransformerInput_" + name] ?: defaultValue)
+}
+
+def kotlinVersion = getExtOrDefault("kotlinVersion", "2.0.21")
+
+android {
+  namespace "com.appandflow.transformertextinput"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+
+    ndk {
+      abiFilters (*reactNativeArchitectures())
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+    textReport true
+    textOutput 'stdout'
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    allWarningsAsErrors = System.getenv("RNTTI_WARNINGS_AS_ERRORS") == "true"
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
+
+  if (rootProject.subprojects.find { it.name == "react-native-worklets" }) {
+    implementation project(":react-native-worklets")
+  } else {
+    throw new GradleException("[rntti] `react-native-worklets` library not found. Please install it as a dependency in your project.")
+  }
+}
+
+evaluationDependsOn(":react-native-worklets")
+
+// afterEvaluate {
+//     tasks.named("externalNativeBuildDebug").configure {
+//         dependsOn(findProject(":react-native-worklets").tasks.named("externalNativeBuildDebug"))
+//     }
+//     tasks.named("externalNativeBuildRelease").configure {
+//         dependsOn(findProject(":react-native-worklets").tasks.named("externalNativeBuildRelease"))
+//     }
+// }

package/android/gradle.properties

@@ -0,0 +1,5 @@
+TransformerInput_kotlinVersion=2.0.21
+TransformerInput_minSdkVersion=24
+TransformerInput_targetSdkVersion=34
+TransformerInput_compileSdkVersion=35
+TransformerInput_ndkVersion=27.1.12297006

package/android/spotless.gradle

@@ -0,0 +1,19 @@
+apply plugin: 'com.diffplug.spotless'
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+
+spotless {
+    kotlin {
+        target 'src/**/*.kt'
+        ktlint("1.5.0").setEditorConfigPath("$projectDir/../.editorconfig")
+        trimTrailingWhitespace()
+        indentWithSpaces()
+        endWithNewline()
+    }
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/appandflow/transformertextinput/TextState.kt

@@ -0,0 +1,15 @@
+package com.appandflow.transformertextinput
+
+import com.facebook.proguard.annotations.DoNotStripAny
+
+@DoNotStripAny
+data class TextSelection(
+  val start: Int,
+  val end: Int,
+)
+
+@DoNotStripAny
+data class TextState(
+  val value: String,
+  val selection: TextSelection,
+)

package/android/src/main/java/com/appandflow/transformertextinput/TransformerTextInputDecoratorView.kt

@@ -0,0 +1,160 @@
+package com.appandflow.transformertextinput
+
+import android.content.Context
+import android.text.Editable
+import android.text.TextWatcher
+import com.facebook.react.views.textinput.ReactEditText
+import com.facebook.react.views.view.ReactViewGroup
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.MainScope
+import kotlinx.coroutines.launch
+
+class TransformerTextInputDecoratorView(
+  context: Context,
+) : ReactViewGroup(context),
+  TextWatcher {
+  private var transformerId: Int = 0
+  private var lastEventValue: String? = null
+  private var resetLastEventValueJob: Job? = null
+  private var reactEditText: ReactEditText? = null
+  private var isUpdating = false
+
+  private fun currentValue(): String = reactEditText?.text?.toString() ?: ""
+
+  private fun currentSelection(): TextSelection {
+    val input = reactEditText
+    return if (input == null) {
+      TextSelection(0, 0)
+    } else {
+      TextSelection(input.selectionStart.coerceAtLeast(0), input.selectionEnd.coerceAtLeast(0))
+    }
+  }
+
+  private fun applyValue(value: String) {
+    reactEditText?.setText(value)
+  }
+
+  private fun applySelection(selection: TextSelection) {
+    reactEditText?.setSelection(selection.start, selection.end)
+  }
+
+  private fun transformTextState(state: TextState) =
+    TransformerTextInputJni.transform(
+      transformerId,
+      state.value,
+      state.selection.start,
+      state.selection.end,
+    ) ?: state
+
+  fun setTransformerId(newTransformerId: Int) {
+    transformerId = newTransformerId
+    lastEventValue = null
+  }
+
+  override fun onAttachedToWindow() {
+    super.onAttachedToWindow()
+
+    val child = getChildAt(0)
+    if (child is ReactEditText) {
+      reactEditText = child
+      reactEditText?.addTextChangedListener(this)
+    }
+  }
+
+  override fun onDetachedFromWindow() {
+    super.onDetachedFromWindow()
+    reactEditText?.removeTextChangedListener(this)
+    reactEditText = null
+  }
+
+  override fun beforeTextChanged(
+    s: CharSequence?,
+    start: Int,
+    count: Int,
+    after: Int,
+  ) {
+    // noop
+  }
+
+  override fun onTextChanged(
+    s: CharSequence?,
+    start: Int,
+    before: Int,
+    count: Int,
+  ) {
+    // noop
+  }
+
+  override fun afterTextChanged(s: Editable?) {
+    if (isUpdating) {
+      return
+    }
+
+    val editValue = s?.toString() ?: ""
+
+    // For some reason, text change events are dispatched multiple times with the same value, which
+    // causes issue with how we track previous values. To avoid this and match iOS behavior we ignore
+    // events in the same frame that have the same text value.
+    if (lastEventValue == editValue) {
+      return
+    }
+    lastEventValue = editValue
+    resetLastEventValueJob?.cancel()
+    resetLastEventValueJob =
+      MainScope().launch(Dispatchers.Main) {
+        lastEventValue = null
+        resetLastEventValueJob = null
+      }
+
+    val currentSelection = currentSelection()
+    val current = TextState(editValue, currentSelection)
+    val next = transformTextState(current)
+    val didTransformValue = next.value != current.value
+    isUpdating = true
+    try {
+      if (didTransformValue) {
+        applyValue(next.value)
+      }
+      if (
+        didTransformValue || next.selection != currentSelection
+      ) {
+        applySelection(next.selection)
+      }
+    } finally {
+      isUpdating = false
+    }
+  }
+
+  fun update(
+    transform: Boolean,
+    value: String?,
+    selectionStart: Int,
+    selectionEnd: Int,
+  ) {
+    if (reactEditText == null) {
+      return
+    }
+    val currentValue = currentValue()
+    val currentSelection = currentSelection()
+    val providedValue = value ?: currentValue
+    val providedSelection = TextSelection(selectionStart, selectionEnd)
+    val provided = TextState(providedValue, providedSelection)
+    val next = if (transform) transformTextState(provided) else provided
+
+    val didTransformValue = next.value != currentValue
+    isUpdating = true
+    try {
+      if (didTransformValue) {
+        applyValue(next.value)
+      }
+      if (
+        didTransformValue || next.selection != currentSelection
+      ) {
+        applySelection(next.selection)
+      }
+    } finally {
+      isUpdating = false
+    }
+  }
+}

package/android/src/main/java/com/appandflow/transformertextinput/TransformerTextInputDecoratorViewManager.kt

@@ -0,0 +1,44 @@
+package com.appandflow.transformertextinput
+
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.ViewGroupManager
+import com.facebook.react.uimanager.ViewManagerDelegate
+import com.facebook.react.viewmanagers.TransformerTextInputDecoratorViewManagerDelegate
+import com.facebook.react.viewmanagers.TransformerTextInputDecoratorViewManagerInterface
+
+@ReactModule(name = TransformerTextInputDecoratorViewManager.NAME)
+class TransformerTextInputDecoratorViewManager :
+  ViewGroupManager<TransformerTextInputDecoratorView>(),
+  TransformerTextInputDecoratorViewManagerInterface<TransformerTextInputDecoratorView> {
+  private val mDelegate: ViewManagerDelegate<TransformerTextInputDecoratorView> =
+    TransformerTextInputDecoratorViewManagerDelegate(this)
+
+  override fun getDelegate(): ViewManagerDelegate<TransformerTextInputDecoratorView>? = mDelegate
+
+  override fun getName(): String = NAME
+
+  public override fun createViewInstance(context: ThemedReactContext): TransformerTextInputDecoratorView =
+    TransformerTextInputDecoratorView(context)
+
+  override fun setTransformerId(
+    view: TransformerTextInputDecoratorView?,
+    transformerId: Int,
+  ) {
+    view?.setTransformerId(transformerId)
+  }
+
+  override fun update(
+    view: TransformerTextInputDecoratorView?,
+    transform: Boolean,
+    value: String?,
+    selectionStart: Int,
+    selectionEnd: Int,
+  ) {
+    view?.update(transform, value, selectionStart, selectionEnd)
+  }
+
+  companion object {
+    const val NAME = "TransformerTextInputDecoratorView"
+  }
+}

package/android/src/main/java/com/appandflow/transformertextinput/TransformerTextInputJni.kt

@@ -0,0 +1,25 @@
+package com.appandflow.transformertextinput
+
+import com.facebook.proguard.annotations.DoNotStrip
+import com.facebook.soloader.SoLoader
+import com.swmansion.worklets.WorkletsModule
+
+@DoNotStrip
+object TransformerTextInputJni {
+  init {
+    SoLoader.loadLibrary("react_codegen_rntti")
+  }
+
+  @DoNotStrip
+  @JvmStatic
+  external fun setWorkletsModule(workletsModule: WorkletsModule)
+
+  @DoNotStrip
+  @JvmStatic
+  external fun transform(
+    transformerId: Int,
+    value: String,
+    selectionStart: Int,
+    selectionEnd: Int,
+  ): TextState?
+}

package/android/src/main/java/com/appandflow/transformertextinput/TransformerTextInputModule.kt

@@ -0,0 +1,22 @@
+package com.appandflow.transformertextinput
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.annotations.ReactModule
+import com.swmansion.worklets.WorkletsModule
+
+@ReactModule(name = TransformerTextInputModule.NAME)
+class TransformerTextInputModule(
+  reactContext: ReactApplicationContext,
+) : NativeTransformerTextInputModuleSpec(reactContext) {
+  override fun install(): Boolean {
+    val workletsModule = reactApplicationContext.getNativeModule(WorkletsModule::class.java)
+    if (workletsModule != null) {
+      TransformerTextInputJni.setWorkletsModule(workletsModule)
+    }
+    return true
+  }
+
+  companion object {
+    const val NAME: String = NativeTransformerTextInputModuleSpec.NAME
+  }
+}

package/android/src/main/java/com/appandflow/transformertextinput/TransformerTextInputPackage.kt

@@ -0,0 +1,53 @@
+package com.appandflow.transformertextinput
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.module.annotations.ReactModuleList
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
+import java.util.ArrayList
+import java.util.HashMap
+
+@ReactModuleList(nativeModules = [TransformerTextInputModule::class])
+class TransformerTextInputPackage :
+  BaseReactPackage(),
+  ReactPackage {
+  override fun getModule(
+    name: String,
+    reactContext: ReactApplicationContext,
+  ): NativeModule? =
+    if (name == TransformerTextInputModule.NAME) {
+      TransformerTextInputModule(reactContext)
+    } else {
+      null
+    }
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+    val moduleList = arrayOf(TransformerTextInputModule::class.java)
+    val reactModuleInfoMap: MutableMap<String, ReactModuleInfo> = HashMap()
+    for (moduleClass in moduleList) {
+      val reactModule = moduleClass.getAnnotation(ReactModule::class.java) ?: continue
+      reactModuleInfoMap[reactModule.name] =
+        ReactModuleInfo(
+          reactModule.name,
+          moduleClass.name,
+          reactModule.canOverrideExistingModule,
+          reactModule.needsEagerInit,
+          reactModule.isCxxModule,
+          true,
+        )
+    }
+
+    return ReactModuleInfoProvider { reactModuleInfoMap }
+  }
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    val viewManagers: MutableList<ViewManager<*, *>> = ArrayList()
+    viewManagers.add(TransformerTextInputDecoratorViewManager())
+    return viewManagers
+  }
+}