react-native-swipeable-actions 0.1.0

package/README.md

@@ -0,0 +1,250 @@
+# react-native-swipeable-actions
+
+A high-performance native swipeable row component for React Native. Native alternative to `react-native-gesture-handler/Swipeable` - no `react-native-reanimated` required.
+
+## Features
+
+- Pure native gestures - no JS thread blocking
+- 60fps spring animations on both iOS and Android
+- No `react-native-reanimated` dependency
+- Built-in FlashList/virtualized list support via `recyclingKey`
+- AutoClose pattern for chat-style swipe-to-reply
+- Lazy action rendering for optimal performance
+
+## Performance
+
+Benchmark comparison on Android 16, Pixel 8 Pro, GrapheneOS — List Demo with 100 items:
+
+<table>
+<tr>
+<th>react-native-gesture-handler/Swipeable</th>
+<th>react-native-swipeable-actions</th>
+</tr>
+<tr>
+<td><video src="example/assets/rngh.mp4" controls width="300"></video></td>
+<td><video src="example/assets/swipeable.mp4" controls width="300"></video></td>
+</tr>
+<tr>
+<td align="center">Reanimated</td>
+<td align="center">Pure native</td>
+</tr>
+<tr>
+<td align="center"><b>Avg 60.9</b> FPS (Min: 56.7 / Max: 65.7)</td>
+<td align="center"><b>Avg 116.8</b> FPS (Min: 109.9 / Max: 120.3)</td>
+</tr>
+</table>
+
+## Installation
+
+```bash
+npm install react-native-swipeable-actions
+```
+
+### Peer Dependencies
+
+```json
+{
+  "expo": ">=50.0.0",
+  "expo-modules-core": ">=1.0.0",
+  "react": ">=18.0.0",
+  "react-native": ">=0.73.0"
+}
+```
+
+## Basic Usage
+
+```tsx
+import { Swipeable, SwipeableMethods } from 'react-native-swipeable-actions'
+import { useRef } from 'react'
+import { View, Text, TouchableOpacity } from 'react-native'
+
+function DeleteAction({ onPress }: { onPress: () => void }) {
+  return (
+    <TouchableOpacity onPress={onPress} style={styles.deleteAction}>
+      <Text style={styles.actionText}>Delete</Text>
+    </TouchableOpacity>
+  )
+}
+
+function MyRow() {
+  const swipeableRef = useRef<SwipeableMethods>(null)
+
+  return (
+    <Swipeable
+      ref={swipeableRef}
+      actions={<DeleteAction onPress={() => console.log('Delete!')} />}
+      actionsWidth={80}
+      onSwipeEnd={(state) => console.log('Swipe ended:', state)}
+    >
+      <View style={styles.row}>
+        <Text>Swipe me left</Text>
+      </View>
+    </Swipeable>
+  )
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Row content |
+| `actions` | `ReactNode` | required | Action buttons revealed on swipe |
+| `actionsWidth` | `number` | required | Width of actions container in pixels |
+| `actionsPosition` | `'left' \| 'right'` | `'right'` | Position of actions (`'left'` = swipe right to reveal) |
+| `friction` | `number` | `1` | Drag damping factor (0-1). Lower = more resistance |
+| `threshold` | `number` | `0.4` | Snap-to threshold as percentage of actionsWidth (0-1) |
+| `dragOffsetFromEdge` | `number` | `0` | Minimum drag distance before gesture starts |
+| `autoClose` | `boolean` | `false` | Auto-close after swipe release (for swipe-to-reply) |
+| `autoCloseTimeout` | `number` | `0` | Delay in ms before auto-closing |
+| `recyclingKey` | `string \| number` | - | Unique key for FlashList/recycling support |
+| `style` | `StyleProp<ViewStyle>` | - | Container style |
+| `testID` | `string` | - | Test ID for e2e testing |
+
+## Callbacks
+
+| Callback | Type | Description |
+|----------|------|-------------|
+| `onSwipeStart` | `() => void` | Called when swipe gesture begins |
+| `onSwipeStateChange` | `(state: 'open' \| 'closed') => void` | Called when gesture ends (before animation) |
+| `onSwipeEnd` | `(state: 'open' \| 'closed') => void` | Called when animation completes |
+| `onProgress` | `(progress: number) => void` | Called on each frame (0 = closed, 1 = fully open) |
+
+## Ref Methods
+
+Access via ref:
+
+```tsx
+const swipeableRef = useRef<SwipeableMethods>(null)
+
+// Close the row (with optional animation)
+swipeableRef.current?.close()         // animated
+swipeableRef.current?.close(false)    // instant
+
+// Open the row
+swipeableRef.current?.open()
+```
+
+## Static Methods
+
+Control swipeables globally by their `recyclingKey`:
+
+```tsx
+import { Swipeable } from 'react-native-swipeable-actions'
+
+// Open a specific row
+Swipeable.open('row-1')
+
+// Close a specific row
+Swipeable.close('row-1')           // animated
+Swipeable.close('row-1', false)    // instant
+
+// Close all open rows
+Swipeable.closeAll()               // animated
+Swipeable.closeAll(false)          // instant
+```
+
+## AutoClose Pattern (Swipe-to-Reply)
+
+For chat-style swipe-to-reply where the row should automatically close:
+
+```tsx
+<Swipeable
+  actions={<ReplyIndicator />}
+  actionsWidth={60}
+  actionsPosition="right"
+  autoClose={true}
+  threshold={0.6}
+  onSwipeEnd={(state) => {
+    if (state === 'open') {
+      // Trigger reply action
+      onReply(message)
+    }
+  }}
+>
+  <ChatMessage message={message} />
+</Swipeable>
+```
+
+## FlashList Integration
+
+For virtualized lists, use `recyclingKey` to persist swipe state across recycling:
+
+```tsx
+import { FlashList } from '@shopify/flash-list'
+
+function MessageList({ messages }) {
+  return (
+    <FlashList
+      data={messages}
+      renderItem={({ item }) => (
+        <Swipeable
+          recyclingKey={item.id}
+          actions={<DeleteAction />}
+          actionsWidth={80}
+        >
+          <MessageRow message={item} />
+        </Swipeable>
+      )}
+      estimatedItemSize={60}
+    />
+  )
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  JS Layer (React)                                           │
+│  ┌─────────────────┐  ┌──────────────────────────────────┐ │
+│  │ <Swipeable>     │  │ Actions (ReactNode)              │ │
+│  │  - renderActions│──│  - Rendered lazily on first swipe│ │
+│  │  - ref methods  │  │  - Any React components          │ │
+│  └────────┬────────┘  └──────────────────────────────────┘ │
+└───────────│─────────────────────────────────────────────────┘
+            │ Expo Modules Bridge
+┌───────────▼─────────────────────────────────────────────────┐
+│  Native Layer (Kotlin/Swift)                                │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │ SwipeableView                                           ││
+│  │  - UIPanGestureRecognizer (iOS) / OnTouchListener (And) ││
+│  │  - Spring animations (UIView.animate / DynamicAnimation)││
+│  │  - Progress events @ 60fps (CADisplayLink / Choreograph)││
+│  │  - LRU cache for recycling state persistence            ││
+│  └─────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Key design decisions:**
+
+- Gestures handled entirely in native code for 60fps performance
+- Actions rendered lazily on first swipe gesture (performance optimization)
+- Recycling key enables state persistence in virtualized lists
+- No SharedValue dependency - progress synced via native events
+
+## Platform Support
+
+| Platform | Version |
+|----------|---------|
+| iOS | 12.0+ |
+| Android | API 21+ |
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import {
+  Swipeable,
+  SwipeableProps,
+  SwipeableMethods,
+  SwipeableStatic,
+  SwipeProgressEvent,
+  SwipeStateEvent,
+} from 'react-native-swipeable-actions'
+```
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,99 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'maven-publish'
+
+group = 'expo.modules.swipeable'
+version = '0.1.0'
+
+buildscript {
+    def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+    if (expoModulesCorePlugin.exists()) {
+        apply from: expoModulesCorePlugin
+        applyKotlinExpoModulesCorePlugin()
+    }
+
+    repositories {
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.23")
+    }
+}
+
+afterEvaluate {
+    publishing {
+        publications {
+            release(MavenPublication) {
+                from components.release
+            }
+        }
+        repositories {
+            maven {
+                url = mavenLocal().url
+            }
+        }
+    }
+}
+
+android {
+    namespace "expo.modules.swipeable"
+    compileSdkVersion safeExtGet("compileSdkVersion", 34)
+
+    defaultConfig {
+        minSdkVersion safeExtGet("minSdkVersion", 23)
+        targetSdkVersion safeExtGet("targetSdkVersion", 34)
+        versionCode 1
+        versionName "0.1.0"
+    }
+
+    publishing {
+        singleVariant("release") {
+            withSourcesJar()
+        }
+    }
+
+    lintOptions {
+        abortOnError false
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_17.majorVersion
+    }
+
+    testOptions {
+        unitTests {
+            includeAndroidResources = true
+        }
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation project(':expo-modules-core')
+    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${getKotlinVersion()}"
+    implementation "androidx.dynamicanimation:dynamicanimation:1.0.0"
+
+    testImplementation "junit:junit:4.13.2"
+    testImplementation "io.mockk:mockk:1.13.8"
+    testImplementation "org.robolectric:robolectric:4.11.1"
+}
+
+def getKotlinVersion() {
+    def kotlin_version = rootProject.ext.has("kotlinVersion")
+        ? rootProject.ext.get("kotlinVersion")
+        : "1.9.23"
+    return kotlin_version
+}
+
+def safeExtGet(String prop, Integer defaultValue) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : defaultValue
+}

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/expo/modules/swipeable/SwipeConstants.kt

@@ -0,0 +1,29 @@
+package expo.modules.swipeable
+
+/**
+ * Physics and animation constants for swipeable behavior.
+ *
+ * Cross-platform constants (must match iOS SwipeAnimationConfig.swift):
+ * - RUBBER_BAND_DIVISOR, VELOCITY_NORMALIZER, MAX_NORMALIZED_VELOCITY
+ * - VELOCITY_PROJECTION_FACTOR, PROGRESS_CHANGE_THRESHOLD, *_DAMPING_RATIO
+ *
+ * Platform-specific: Android uses spring physics (stiffness), iOS uses duration-based animation.
+ * Both produce similar visual results with critical damping (no oscillation).
+ */
+object SwipeConstants {
+    // Cross-platform constants - must match iOS
+    const val RUBBER_BAND_DIVISOR = 3f
+    const val VELOCITY_NORMALIZER = 500f
+    const val MAX_NORMALIZED_VELOCITY = 2.0f
+    const val VELOCITY_PROJECTION_FACTOR = 0.15f
+    const val PROGRESS_CHANGE_THRESHOLD = 0.001f
+
+    // Android-specific: velocity conversion
+    const val VELOCITY_SCALE = 1000f
+
+    // Android-specific: spring physics (iOS uses duration-based animation)
+    const val OPEN_STIFFNESS = 300f
+    const val OPEN_DAMPING_RATIO = 1.0f  // Critical damping - no oscillation (matches iOS)
+    const val CLOSE_STIFFNESS = 400f
+    const val CLOSE_DAMPING_RATIO = 1.0f  // Critical damping - no oscillation (matches iOS)
+}

package/android/src/main/java/expo/modules/swipeable/SwipePhysics.kt

@@ -0,0 +1,66 @@
+package expo.modules.swipeable
+
+import kotlin.math.abs
+import kotlin.math.min
+import kotlin.math.sign
+
+object SwipePhysics {
+
+    fun applyRubberBand(
+        translation: Float,
+        actionsWidth: Float,
+        isLeading: Boolean
+    ): Float {
+        var result = translation
+        if (isLeading) {
+            when {
+                result > actionsWidth -> {
+                    result = actionsWidth + ((result - actionsWidth) / SwipeConstants.RUBBER_BAND_DIVISOR)
+                }
+                result < 0f -> {
+                    result /= SwipeConstants.RUBBER_BAND_DIVISOR
+                }
+            }
+        } else {
+            when {
+                result < -actionsWidth -> {
+                    result = -actionsWidth - ((abs(result) - actionsWidth) / SwipeConstants.RUBBER_BAND_DIVISOR)
+                }
+                result > 0f -> {
+                    result /= SwipeConstants.RUBBER_BAND_DIVISOR
+                }
+            }
+        }
+        return result
+    }
+
+    fun shouldSnapToOpen(
+        projectedPosition: Float,
+        thresholdDistance: Float,
+        isOpen: Boolean,
+        isLeading: Boolean
+    ): Boolean {
+        return if (isLeading) {
+            if (isOpen) projectedPosition > -thresholdDistance else projectedPosition > thresholdDistance
+        } else {
+            if (isOpen) projectedPosition < thresholdDistance else projectedPosition < -thresholdDistance
+        }
+    }
+
+    fun projectFinalPosition(
+        translation: Float,
+        velocity: Float,
+        friction: Float
+    ): Float {
+        return (translation * friction) + (velocity * friction * SwipeConstants.VELOCITY_PROJECTION_FACTOR)
+    }
+
+    fun calculateSpringVelocity(gestureVelocity: Float): Float {
+        // Preserve the sign of the velocity - critical for correct spring animation direction
+        val magnitude = min(
+            abs(gestureVelocity) / SwipeConstants.VELOCITY_NORMALIZER,
+            SwipeConstants.MAX_NORMALIZED_VELOCITY
+        ) * SwipeConstants.VELOCITY_SCALE
+        return sign(gestureVelocity) * magnitude
+    }
+}

package/android/src/main/java/expo/modules/swipeable/SwipeableModule.kt

@@ -0,0 +1,69 @@
+package expo.modules.swipeable
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class SwipeableModule : Module() {
+    override fun definition() = ModuleDefinition {
+        Name("Swipeable")
+
+        // Module-level functions (by recyclingKey)
+        Function("openByKey") { key: String ->
+            SwipeableView.openByKey(key)
+        }
+
+        Function("closeByKey") { key: String, animated: Boolean? ->
+            SwipeableView.closeByKey(key, animated ?: true)
+        }
+
+        Function("closeAll") { animated: Boolean? ->
+            SwipeableView.closeAll(animated ?: true)
+        }
+
+        View(SwipeableView::class) {
+            Prop("actionsWidth") { view: SwipeableView, width: Float ->
+                view.actionsWidth = width
+            }
+            Prop("actionsPosition") { view: SwipeableView, position: String ->
+                view.actionsPosition = position
+            }
+            Prop("friction") { view: SwipeableView, friction: Float ->
+                view.friction = friction.coerceIn(0f, 1f)
+            }
+            Prop("threshold") { view: SwipeableView, threshold: Float ->
+                view.threshold = threshold.coerceIn(0f, 1f)
+            }
+            Prop("dragOffsetFromEdge") { view: SwipeableView, offset: Float ->
+                view.dragOffsetFromEdge = offset
+            }
+            Prop("recyclingKey") { view: SwipeableView, key: String? ->
+                view.recyclingKey = key
+            }
+            Prop("autoClose") { view: SwipeableView, autoClose: Boolean ->
+                view.autoClose = autoClose
+            }
+            Prop("autoCloseTimeout") { view: SwipeableView, timeout: Float ->
+                view.autoCloseTimeout = timeout
+            }
+
+            Events("onSwipeProgress", "onSwipeStart", "onSwipeStateChange", "onSwipeEnd")
+
+            AsyncFunction("close") { view: SwipeableView, animated: Boolean? ->
+                view.post { view.close(animated ?: true) }
+            }
+            AsyncFunction("open") { view: SwipeableView ->
+                view.post { view.open() }
+            }
+
+            AsyncFunction("handleGestureStart") { view: SwipeableView ->
+                view.handleGestureStart()
+            }
+            AsyncFunction("handleGestureUpdate") { view: SwipeableView, translationX: Float, velocityX: Float ->
+                view.handleGestureUpdate(translationX, velocityX)
+            }
+            AsyncFunction("handleGestureEnd") { view: SwipeableView, translationX: Float, velocityX: Float ->
+                view.handleGestureEnd(translationX, velocityX)
+            }
+        }
+    }
+}