@honeypathkar/react-native-predictive-back-gesture 1.0.4 → 1.0.6

package/Readme.md

@@ -1,485 +1,127 @@
-# Android Predictive Back Gesture — Implementation Guide
+# @honeypathkar/react-native-predictive-back-gesture
 
 <div align="center">
   <img src="https://mintcdn.com/honeypathkar/2crkeqrZKInE-b4M/images/ezgif-154f2a3ceac3de29.gif?s=be7bda13989332cd5d3b93d1c5ced59f" width="280" alt="Predictive Back Gesture Demo" />
 </div>
 
-## What This Feature Does
+A lightweight React Native library providing Android 14+ Predictive Back gesture animations and edge drag-to-close card transitions.
 
-- **Android 14+ (API 34+):** Live gesture progress from the OS → card shrinks 13%, drifts right, reveals the screen underneath while the finger is mid-swipe.
-- **Android < 14:** Only the commit event fires → timed slide-out fallback animation plays instead.
-- **All platforms:** A drag-to-close gesture from the left edge of the screen does the same card animation.
-- **Root screen:** App stands down completely so Android plays its native _back-to-home_ animation (app shrinks into a card over the wallpaper).
-- Haptic feedback on dismiss, proper gesture cancellation, and `beforeRemove` guard support.
+## Features
 
----
-
-## Architecture Overview
-
-```
-Android OS
-  └── OnBackPressedDispatcher
-        └── PredictiveBackModule.kt   (native, intercepts back events)
-              └── NativeEventEmitter
-                    └── PredictiveBack.js  (JS bridge, ownership model)
-                          └── SwipeableScreen.jsx  (consumes events → Reanimated)
-                                └── AppNavigator.jsx  (sets fallback mode per nav state)
-```
+- **Android 14+ (API 34+):** Live OS gesture progress. The card shrinks 13%, tilts dynamically, and reveals the underlying screen during mid-swipe.
+- **Android < 14 / Back Button:** Plays a smooth slide-out card exit animation on back commit.
+- **Cross-Platform Swipe Gesture:** Left-edge drag-to-close gesture on all platforms (iOS & Android).
+- **Root Back-To-Home:** Root screen stands down so Android plays its native *back-to-home* animation (app shrinking over wallpaper).
+- **Zero Config Autolinking:** Native Android module auto-linked seamlessly.
 
 ---
 
-## Files Changed / Created
-
-| File                                                   | Status   | Role                               |
-| ------------------------------------------------------ | -------- | ---------------------------------- |
-| `android/app/build.gradle`                             | Modified | Add `activity-ktx` dependency      |
-| `android/app/src/main/AndroidManifest.xml`             | Modified | Opt-in to predictive back          |
-| `android/app/src/main/java/…/MainApplication.kt`       | Modified | Register `PredictiveBackPackage`   |
-| `android/app/src/main/java/…/PredictiveBackModule.kt`  | **New**  | Native Kotlin bridge               |
-| `android/app/src/main/java/…/PredictiveBackPackage.kt` | **New**  | ReactPackage wrapper               |
-| `src/native/PredictiveBack.js`                         | **New**  | JS ownership model + event routing |
-| `src/components/SwipeableScreen.jsx`                   | Modified | Reanimated card animation          |
-| `src/navigation/AppNavigator.jsx`                      | Modified | Sync fallback back mode            |
-
----
+## Installation
 
-## Step-by-Step Implementation
-
-### 1. `android/app/build.gradle` — Add the Dependency
-
-```diff
- dependencies {
-     // ... existing deps
-
-+    // BackEventCompat / predictive-back callbacks on OnBackPressedDispatcher (1.8.0+)
-+    implementation("androidx.activity:activity-ktx:1.9.3")
- }
+```bash
+npm install @honeypathkar/react-native-predictive-back-gesture
+# or
+yarn add @honeypathkar/react-native-predictive-back-gesture
 ```
 
----
+### Peer Dependencies
 
-### 2. `android/app/src/main/AndroidManifest.xml` — Opt In
+Ensure `react-native-gesture-handler` and `react-native-reanimated` are installed in your project:
 
-Add **`android:enableOnBackInvokedCallback="true"`** to the `<application>` tag.
-Without this the OS never delivers predictive back events to your app.
-
-```diff
-  <application
-    android:allowBackup="false"
-    android:theme="@style/AppTheme"
-    android:usesCleartextTraffic="${usesCleartextTraffic}"
--   android:supportsRtl="true">
-+   android:supportsRtl="true"
-+   android:enableOnBackInvokedCallback="true">
+```bash
+npm install react-native-gesture-handler react-native-reanimated
 ```
 
-> [!IMPORTANT]
-> This flag is the single most common reason the feature silently does nothing. It must be present at the `<application>` level (not `<activity>`).
-
 ---
 
-### 3. `PredictiveBackPackage.kt` — New File
-
-Create at `android/app/src/main/java/com/<yourpackage>/PredictiveBackPackage.kt`
+## Android Setup
 
-```kotlin
-package com.<yourpackage>
+### 1. Opt-in to Predictive Back in `AndroidManifest.xml`
 
-import com.facebook.react.ReactPackage
-import com.facebook.react.bridge.NativeModule
-import com.facebook.react.bridge.ReactApplicationContext
-import com.facebook.react.uimanager.ViewManager
+In your `android/app/src/main/AndroidManifest.xml`, add `android:enableOnBackInvokedCallback="true"` to the `<application>` tag:
 
-class PredictiveBackPackage : ReactPackage {
-    override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
-        return listOf(PredictiveBackModule(reactContext))
-    }
-
-    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
-        return emptyList()
-    }
-}
+```xml
+<application
+  android:name=".MainApplication"
+  android:enableOnBackInvokedCallback="true"
+  ... >
 ```
 
 ---
 
-### 4. `PredictiveBackModule.kt` — New File (Core Native Logic)
-
-Create at `android/app/src/main/java/com/<yourpackage>/PredictiveBackModule.kt`
-
-**Key design decisions:**
-
-- Uses `OnBackPressedCallback` (via `androidx.activity:activity-ktx`) NOT `OnBackInvokedCallback`. This is intentional — it lets the `OnBackPressedDispatcher` stack work correctly with React Native's own back handler and react-native-screens.
-- Re-adds the callback on every switch to `app` mode so it stays on top of the dispatcher stack (LIFO order).
-- Finds and manages React Native's own internal `OnBackPressedCallback` via reflection to enable the _back-to-home_ OS animation (the `system` mode).
-
-```kotlin
-package com.<yourpackage>
-
-import android.os.Build
-import android.util.Log
-import androidx.activity.ComponentActivity
-import androidx.activity.OnBackPressedCallback
-import androidx.activity.BackEventCompat
-import com.facebook.react.bridge.*
-import com.facebook.react.modules.core.DeviceEventManagerModule
-
-class PredictiveBackModule(reactContext: ReactApplicationContext) :
-    ReactContextBaseJavaModule(reactContext) {
-
-    private val backCallback = object : OnBackPressedCallback(false) {
-        override fun handleOnBackStarted(backEvent: BackEventCompat) {
-            emit(EVENT_START, backEvent.toEventMap())
-        }
-        override fun handleOnBackProgressed(backEvent: BackEventCompat) {
-            emit(EVENT_PROGRESS, backEvent.toEventMap())
-        }
-        override fun handleOnBackCancelled() {
-            emit(EVENT_CANCEL, Arguments.createMap())
-        }
-        override fun handleOnBackPressed() {
-            emit(EVENT_COMMIT, Arguments.createMap())
-        }
-    }
-
-    private var isRegistered = false
-    private var reactCallback: OnBackPressedCallback? = null
-    private var reactCallbackHost: ComponentActivity? = null
-
-    override fun getName(): String = NAME
-
-    override fun getConstants(): MutableMap<String, Any> =
-        hashMapOf(
-            "progressAvailable" to (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
-        )
-
-    @ReactMethod
-    fun setMode(mode: String) {
-        UiThreadUtil.runOnUiThread {
-            val activity = reactApplicationContext.currentActivity as? ComponentActivity
-            when (mode) {
-                MODE_APP -> {
-                    if (activity != null) {
-                        attachTo(activity)
-                        setReactCallbackEnabled(activity, true)
-                    }
-                    backCallback.isEnabled = true
-                }
-                MODE_SYSTEM -> {
-                    backCallback.isEnabled = false
-                    if (activity != null) setReactCallbackEnabled(activity, false)
-                }
-                MODE_DEFAULT -> {
-                    backCallback.isEnabled = false
-                    if (activity != null) setReactCallbackEnabled(activity, true)
-                }
-                else -> Log.w(NAME, "Unknown back mode: $mode")
-            }
-        }
-    }
-
-    @ReactMethod fun addListener(eventName: String) = Unit
-    @ReactMethod fun removeListeners(count: Int) = Unit
-
-    override fun invalidate() {
-        UiThreadUtil.runOnUiThread {
-            backCallback.isEnabled = false
-            if (isRegistered) { backCallback.remove(); isRegistered = false }
-            reactCallback?.isEnabled = true
-            reactCallback = null
-            reactCallbackHost = null
-        }
-        super.invalidate()
-    }
-
-    private fun attachTo(activity: ComponentActivity) {
-        if (isRegistered) backCallback.remove()
-        activity.onBackPressedDispatcher.addCallback(backCallback)
-        isRegistered = true
-    }
-
-    private fun setReactCallbackEnabled(activity: ComponentActivity, enabled: Boolean) {
-        findReactCallback(activity)?.isEnabled = enabled
-    }
-
-    private fun findReactCallback(activity: ComponentActivity): OnBackPressedCallback? {
-        if (reactCallbackHost === activity) return reactCallback
-        var cls: Class<*>? = activity.javaClass
-        while (cls != null && cls != ComponentActivity::class.java) {
-            for (field in cls.declaredFields) {
-                if (OnBackPressedCallback::class.java.isAssignableFrom(field.type)) {
-                    try {
-                        field.isAccessible = true
-                        val found = field.get(activity) as? OnBackPressedCallback
-                        if (found != null) {
-                            reactCallback = found; reactCallbackHost = activity
-                            return found
-                        }
-                    } catch (e: Exception) {
-                        Log.w(NAME, "Could not read React Native's back callback", e)
-                        return null
-                    }
-                }
-            }
-            cls = cls.superclass
-        }
-        Log.w(NAME, "React Native's back callback not found; system back mode is a no-op")
-        return null
-    }
-
-    private fun emit(event: String, payload: WritableMap) {
-        val context = reactApplicationContext
-        if (!context.hasActiveReactInstance()) return
-        context.emitDeviceEvent(event, payload)
-    }
-
-    private fun BackEventCompat.toEventMap(): WritableMap =
-        Arguments.createMap().apply {
-            putDouble("progress", progress.toDouble())
-            putInt("swipeEdge", swipeEdge)        // 0 = left, 1 = right
-            putDouble("touchX", touchX.toDouble())
-            putDouble("touchY", touchY.toDouble())
-        }
-
-    companion object {
-        const val NAME = "PredictiveBackModule"
-        private const val MODE_APP     = "app"
-        private const val MODE_DEFAULT = "default"
-        private const val MODE_SYSTEM  = "system"
-        private const val EVENT_START    = "predictiveBackStart"
-        private const val EVENT_PROGRESS = "predictiveBackProgress"
-        private const val EVENT_CANCEL   = "predictiveBackCancel"
-        private const val EVENT_COMMIT   = "predictiveBackCommit"
-    }
-}
-```
-
----
+## Usage
 
-### 5. `MainApplication.kt` — Register the Package
+### 1. Wrap Root with `GestureHandlerRootView`
 
-```diff
-+ add(PredictiveBackPackage())
-```
+At the entry point of your app (`App.jsx` or `index.js`), wrap your root layout with `GestureHandlerRootView`:
 
----
-
-### 6. `src/native/PredictiveBack.js` — New File (JS Bridge + Ownership Model)
-
-Create at `src/native/PredictiveBack.js` (adapt path to your project).
-
-```js
-import { NativeEventEmitter, NativeModules, Platform } from "react-native";
-
-const PredictiveBackModule =
-  Platform.OS === "android" ? NativeModules.PredictiveBackModule : null;
-
-/** True when the native back-event bridge is present (Android only). */
-export const PREDICTIVE_BACK_SUPPORTED = PredictiveBackModule != null;
-
-/**
- * True when the OS also reports live gesture progress (Android 14 / API 34+).
- * Below that only the commit arrives — callers should play a timed animation.
- */
-export const PREDICTIVE_BACK_HAS_PROGRESS =
-  PREDICTIVE_BACK_SUPPORTED && PredictiveBackModule.progressAvailable === true;
-
-export const EDGE_LEFT = 0;
-export const EDGE_RIGHT = 1;
-
-/** Back is React Native's to handle (BackHandler + React Navigation). */
-export const BACK_MODE_DEFAULT = "default";
-/**
- * Nothing in the app claims back → Android plays its own back-to-home animation.
- * Set this at the root of the stack (nothing to go back to).
- */
-export const BACK_MODE_SYSTEM = "system";
-
-let owner = null;
-let handlers = null;
-let fallbackMode = BACK_MODE_DEFAULT;
-let appliedMode = null;
-let subscriptions = null;
-
-const apply = () => {
-  const mode = owner ? "app" : fallbackMode;
-  if (mode === appliedMode) return;
-  appliedMode = mode;
-  PredictiveBackModule.setMode(mode);
-};
-
-const dispatch = (name, event) => {
-  const handler = handlers && handlers[name];
-  if (handler) handler(event);
-};
-
-const ensureSubscribed = () => {
-  if (subscriptions || !PredictiveBackModule) return;
-  const emitter = new NativeEventEmitter(PredictiveBackModule);
-  subscriptions = [
-    emitter.addListener("predictiveBackStart", (e) => dispatch("onStart", e)),
-    emitter.addListener("predictiveBackProgress", (e) =>
-      dispatch("onProgress", e),
-    ),
-    emitter.addListener("predictiveBackCancel", () => dispatch("onCancel")),
-    emitter.addListener("predictiveBackCommit", () => dispatch("onCommit")),
-  ];
-};
-
-/**
- * What happens when no screen has claimed back.
- * Call from navigator on state change.
- */
-export const setFallbackBackMode = (mode) => {
-  if (!PredictiveBackModule || fallbackMode === mode) return;
-  fallbackMode = mode;
-  apply();
-};
-
-/**
- * Route back events to `nextHandlers` and enable the native callback.
- * `token` is any stable object (e.g. useRef({}).current) that identifies the caller.
- */
-export const acquirePredictiveBack = (token, nextHandlers) => {
-  if (!PredictiveBackModule) return;
-  ensureSubscribed();
-  owner = token;
-  handlers = nextHandlers;
-  appliedMode = null; // force re-apply even if mode string unchanged
-  apply();
-};
-
-/** Give back control, but only if `token` still holds it. */
-export const releasePredictiveBack = (token) => {
-  if (!PredictiveBackModule || owner !== token) return;
-  owner = null;
-  handlers = null;
-  apply();
-};
-```
-
----
-
-### 7. `src/components/SwipeableScreen.jsx` — Modified
-
-This is the most complex piece. The component wraps any screen and provides both the drag-to-close gesture and the Android predictive-back animation. Full code Available Inside src folder for this file.
-
-**Key constants / parameters (tune to your taste):**
-
-```js
-const ENTER_DURATION = 240; // ms — slide-in
-const EXIT_DURATION = 280; // ms — slide-out
-const SPRING = { damping: 20, stiffness: 200 };
-const EASING = Easing.out(Easing.cubic);
-const EDGE_WIDTH = 60; // px — hit-slop width for drag zone
-const HEADER_INSET = 75; // px — how far up the hit-slop extends above the screen
-const DRAG_RANGE = 200; // px — full-drag distance maps to peek=1
-const PEEK_THRESHOLD = 0.42; // commit if peek > this
-const VELOCITY_THRESHOLD = 500; // px/s
-const MIN_VELOCITY_DISTANCE = 20; // px
-const MAX_PEEK_X = 24; // px drift right at peek=1
-const MAX_PEEK_Y = 18; // px vertical pivot offset at peek=1
-const MAX_SCALE_DOWN = 0.13; // card shrinks by 13% at peek=1
-const CORNER_RADIUS = 20; // border-radius at peek=1
-const MAX_DIM = 0.35; // backdrop opacity at rest
-```
+```jsx
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import SwipeableScreen, {
+  setFallbackBackMode,
+  BACK_MODE_SYSTEM,
+  BACK_MODE_DEFAULT,
+} from '@honeypathkar/react-native-predictive-back-gesture';
+
+import HomeScreen from './screens/HomeScreen';
+import DetailsScreen from './screens/DetailsScreen';
+
+export default function App() {
+  const [currentScreen, setCurrentScreen] = React.useState('home');
+
+  // Synchronize back mode:
+  // When at root -> BACK_MODE_SYSTEM (plays Android native back-to-home wallpaper animation)
+  // When on sub-screen -> BACK_MODE_DEFAULT
+  React.useEffect(() => {
+    setFallbackBackMode(
+      currentScreen === 'home' ? BACK_MODE_SYSTEM : BACK_MODE_DEFAULT,
+    );
+  }, [currentScreen]);
+
+  return (
+    <GestureHandlerRootView style={styles.flex}>
+      <View style={styles.flex}>
+        {/* Root screen stays mounted underneath */}
+        <HomeScreen onOpenDetails={() => setCurrentScreen('details')} />
+
+        {/* Sub-screen wrapped inside SwipeableScreen */}
+        {currentScreen === 'details' ? (
+          <View style={StyleSheet.absoluteFill}>
+            <SwipeableScreen
+              onGoBack={() => setCurrentScreen('home')}
+              backgroundColor="#0A0A0F"
+            >
+              <DetailsScreen onBack={() => setCurrentScreen('home')} />
+            </SwipeableScreen>
+          </View>
+        ) : null}
+      </View>
+    </GestureHandlerRootView>
+  );
+}
 
-**Shared values used:**
-
-| Value          | Purpose                                                                |
-| -------------- | ---------------------------------------------------------------------- |
-| `peek`         | 0→1, how far the card has "peeked" (both gesture sources drive this)   |
-| `exit`         | 0→1, the final slide-out to the right when committing                  |
-| `pivot`        | -1→1, vertical position of the drag (drives Y offset for depth feel)   |
-| `nativeActive` | 0 or 1, blocks the pan gesture while Android system gesture is running |
-
-**The animated style formula:**
-
-```js
-const screenStyle = useAnimatedStyle(() => {
-  const p = peek.value;
-  return {
-    transform: [
-      { translateX: p * MAX_PEEK_X + exit.value * width },
-      { translateY: pivot.value * p * MAX_PEEK_Y },
-      { scale: 1 - MAX_SCALE_DOWN * p },
-    ],
-    borderRadius: interpolate(
-      p,
-      [0, 0.05, 1],
-      [0, CORNER_RADIUS, CORNER_RADIUS],
-      Extrapolation.CLAMP,
-    ),
-    overflow: "hidden",
-  };
+const styles = StyleSheet.create({
+  flex: { flex: 1 },
 });
 ```
 
-**useFocusEffect for Android predictive back:**
-
-```js
-useFocusEffect(
-  useCallback(() => {
-    if (!PREDICTIVE_BACK_SUPPORTED || !isActive) return undefined;
-    const track = (event) => {
-      peek.value = event.progress;
-      pivot.value = (event.touchY / height) * 2 - 1;
-    };
-    acquirePredictiveBack(token, {
-      onStart: (event) => {
-        nativeActive.value = 1;
-        cancelAnimation(peek);
-        track(event);
-      },
-      onProgress: (event) => {
-        if (!isDismissing.current) track(event);
-      },
-      onCancel: cancel,
-      onCommit: () =>
-        commit(PREDICTIVE_BACK_HAS_PROGRESS ? EXIT_DURATION : ENTER_DURATION),
-    });
-    return () => releasePredictiveBack(token);
-  }, [token, isActive, peek, pivot, nativeActive, cancel, commit]),
-);
-```
-
-**Required imports:**
-
-```js
-import Animated, {
-  useSharedValue,
-  useAnimatedStyle,
-  withTiming,
-  withSpring,
-  cancelAnimation,
-  runOnJS,
-  interpolate,
-  Extrapolation,
-} from "react-native-reanimated";
-import { Gesture, GestureDetector } from "react-native-gesture-handler";
-import { useFocusEffect } from "@react-navigation/native";
-import {
-  PREDICTIVE_BACK_SUPPORTED,
-  PREDICTIVE_BACK_HAS_PROGRESS,
-  acquirePredictiveBack,
-  releasePredictiveBack,
-} from "../native/PredictiveBack";
-```
-
 ---
 
-### 8. `src/navigation/AppNavigator.jsx` — Modified
+## React Navigation Integration
 
-Sync the fallback back mode whenever the navigation state changes. In your file where you have managed all the navigation setup or insde App.jsx
+If you use `@react-navigation/native`, synchronize `setFallbackBackMode` directly on `NavigationContainer`:
 
-```js
+```jsx
 import {
+  setFallbackBackMode,
   BACK_MODE_DEFAULT,
   BACK_MODE_SYSTEM,
-  setFallbackBackMode,
-} from '../native/PredictiveBack';
+} from '@honeypathkar/react-native-predictive-back-gesture';
+
+const navigationRef = useNavigationContainerRef();
 
-// Inside the AppNavigator component:
 const syncBackMode = React.useCallback(() => {
   setFallbackBackMode(
     navigationRef.isReady() && navigationRef.canGoBack()
@@ -488,76 +130,44 @@ const syncBackMode = React.useCallback(() => {
   );
 }, []);
 
-// On the NavigationContainer:
 <NavigationContainer
   ref={navigationRef}
   onReady={syncBackMode}
   onStateChange={syncBackMode}
 >
+  {/* Stack Navigator */}
+</NavigationContainer>
 ```
 
-> [!IMPORTANT]
-> `BACK_MODE_SYSTEM` (nothing claims back) at the root screen is what unlocks the OS _back-to-home_ animation. Without this call the app permanently claims back and that animation never plays.
-
----
-
-## Dependencies Required
+Wrap individual stack screens or custom modals with `<SwipeableScreen>`:
 
-| Package                          | Version Used | Purpose                                                   |
-| -------------------------------- | ------------ | --------------------------------------------------------- |
-| `react-native-reanimated`        | ≥ 3.x        | Worklet animations (`useSharedValue`, `withSpring`, etc.) |
-| `react-native-gesture-handler`   | ≥ 2.x        | `Gesture.Pan()`, `GestureDetector`                        |
-| `@react-navigation/native`       | ≥ 6.x        | `useFocusEffect`, `navigationRef`                         |
-| `androidx.activity:activity-ktx` | 1.9.3        | `BackEventCompat`, `OnBackPressedCallback`                |
+```jsx
+import SwipeableScreen from '@honeypathkar/react-native-predictive-back-gesture';
 
-No new JS packages required beyond what a standard React Navigation + Reanimated project already has.
-
----
-
-## Three Back Modes Explained
-
-| Mode      | `backCallback.isEnabled` | RN's own callback | Result                                            |
-| --------- | ------------------------ | ----------------- | ------------------------------------------------- |
-| `app`     | ✅                       | ✅                | Your JS `onCommit` fires; you control navigation  |
-| `default` | ❌                       | ✅                | React Navigation / BackHandler handle it as usual |
-| `system`  | ❌                       | ❌                | OS plays back-to-home animation (root screen)     |
-
----
-
-## Ownership Model (Why It's Needed)
-
-Only **one screen at a time** should respond to a back event. The JS-side `PredictiveBack.js` uses a lightweight token-based ownership model:
-
-- `acquirePredictiveBack(token, handlers)` — the focused screen takes ownership.
-- `releasePredictiveBack(token)` — the screen gives it up on blur.
-- The check `owner !== token` inside `release` ensures that if two screens blur/focus in quick succession (the order is unspecified), the wrong screen can never accidentally release ownership.
+function ProfileModal() {
+  return (
+    <SwipeableScreen backgroundColor="#12121A">
+      <ProfileContent />
+    </SwipeableScreen>
+  );
+}
+```
 
 ---
 
-## Checklist for Porting to a New Project
+## Props Reference (`<SwipeableScreen />`)
 
-- [ ] Add `implementation("androidx.activity:activity-ktx:1.9.3")` to `build.gradle`
-- [ ] Add `android:enableOnBackInvokedCallback="true"` to `AndroidManifest.xml`
-- [ ] Create `PredictiveBackPackage.kt` (replace package name)
-- [ ] Create `PredictiveBackModule.kt` (replace package name)
-- [ ] Register `PredictiveBackPackage()` in `MainApplication.kt`
-- [ ] Create `src/native/PredictiveBack.js`
-- [ ] Wrap screens in `SwipeableScreen` component (or adapt the Reanimated logic into your existing wrapper)
-- [ ] Add `syncBackMode` calls to `NavigationContainer` (`onReady` + `onStateChange`)
-- [ ] Ensure `react-native-reanimated` and `react-native-gesture-handler` are set up (Babel plugin, `GestureHandlerRootView`, Reanimated plugin)
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | **Required** | Content inside the swipeable screen card. |
+| `enabled` | `boolean` | `true` | Enables or disables predictive back gesture handling. |
+| `backgroundColor` | `string` | `'#000000'` | Background color of the card container. |
+| `onGoBack` | `function` | `undefined` | Optional callback invoked when the screen pops or is swiped back. |
+| `onHaptic` | `function` | `undefined` | Optional haptic feedback callback when swipe commits. |
+| `style` | `ViewStyle` | `undefined` | Additional styles for the animated screen container. |
 
 ---
 
-## Known Gotchas
-
-> [!WARNING]
-> **Do NOT use `OnBackInvokedCallback`** (the `android.window` API) directly. It has equal-priority LIFO behaviour and silently breaks React Native's own `BackHandler`.
-
-> [!WARNING]
-> **Re-add on every `app` mode switch.** The `OnBackPressedDispatcher` is a stack. `react-native-screens` adds its own callbacks as fragments mount. Re-adding ensures your callback stays on top.
-
-> [!NOTE]
-> **Reflection on RN's internal callback** is used for `system` mode. It's stable across RN 0.72–0.76 but could theoretically break if React Native changes its internal `ReactActivity` implementation. Failure is non-fatal — back still works, the OS animation just won't play.
+## License
 
-> [!NOTE]
-> On **iOS**, the `PredictiveBack.js` APIs are all no-ops (`PredictiveBackModule` is `null`). Only the drag-to-close pan gesture from `SwipeableScreen` applies.
+MIT © [honeypathkar](https://github.com/honeypathkar)

package/lib/commonjs/AppNavigator.js

@@ -9,4 +9,4 @@ const syncBackMode = React.useCallback(() => {
         : PredictiveBack_1.BACK_MODE_SYSTEM);
 }, []);
 // On the NavigationContainer:
-<NavigationContainer ref={navigationRef} onReady={syncBackMode} onStateChange={syncBackMode}></NavigationContainer>;
+React.createElement(NavigationContainer, { ref: navigationRef, onReady: syncBackMode, onStateChange: syncBackMode });

package/lib/commonjs/SwipableScreen.js

@@ -38,7 +38,6 @@ const react_native_1 = require("react-native");
 const react_native_gesture_handler_1 = require("react-native-gesture-handler");
 const react_native_reanimated_1 = __importStar(require("react-native-reanimated"));
 const native_1 = require("@react-navigation/native");
-const react_native_paper_1 = require("react-native-paper");
 const PredectiveBack_1 = require("./PredectiveBack");
 const { width, height } = react_native_1.Dimensions.get("window");
 // Material predictive-back peek: the card shrinks and drifts a little way to the right
@@ -63,9 +62,14 @@ const DRAG_RANGE = width * 0.6;
 const PEEK_THRESHOLD = 0.35;
 const VELOCITY_THRESHOLD = 900;
 const MIN_VELOCITY_DISTANCE = 50;
-const SwipeableScreen = ({ children, enabled = true, style, onHaptic }) => {
-    const navigation = (0, native_1.useNavigation)();
-    const theme = (0, react_native_paper_1.useTheme)();
+const SwipeableScreen = ({ children, enabled = true, style, onHaptic, backgroundColor = '#000000', onGoBack }) => {
+    let navigation = null;
+    try {
+        navigation = (0, native_1.useNavigation)();
+    }
+    catch (e) {
+        // Component rendered outside React Navigation container
+    }
     // Gesture progress (0…1) — drives the peek: shrink, drift right, rounded corners.
     const peek = (0, react_native_reanimated_1.useSharedValue)(0);
     // Dismissal progress (0…1) — slides the card clear to the right. Also runs in
@@ -97,18 +101,22 @@ const SwipeableScreen = ({ children, enabled = true, style, onHaptic }) => {
         exit.value = (0, react_native_reanimated_1.withTiming)(0, { duration: 200, easing: EASING });
     }, [peek, exit, nativeActive]);
     const goBack = (0, react_1.useCallback)(() => {
-        if (!navigation.canGoBack()) {
+        if (onGoBack) {
+            onGoBack();
+            return;
+        }
+        if (!navigation || !navigation.canGoBack()) {
             settle();
             return;
         }
         navigation.goBack();
         // goBack dispatches through `beforeRemove`, so it may not actually pop.
         requestAnimationFrame(() => {
-            if (navigation.isFocused()) {
+            if (navigation && navigation.isFocused && navigation.isFocused()) {
                 settle();
             }
         });
-    }, [navigation, settle]);
+    }, [navigation, settle, onGoBack]);
     // ─── Commit / cancel ─────────────────────────────────────────────────────
     const commit = (0, react_1.useCallback)((duration = EXIT_DURATION) => {
         if (isDismissing.current) {
@@ -131,8 +139,9 @@ const SwipeableScreen = ({ children, enabled = true, style, onHaptic }) => {
     }, [peek, nativeActive]);
     // ─── System back gesture (Android) ───────────────────────────────────────
     const token = (0, react_1.useRef)({}).current;
-    const isActive = enabled && navigation.canGoBack();
-    (0, native_1.useFocusEffect)((0, react_1.useCallback)(() => {
+    const canGoBackInNav = navigation && navigation.canGoBack ? navigation.canGoBack() : false;
+    const isActive = enabled && (canGoBackInNav || !!onGoBack);
+    const focusEffectCallback = (0, react_1.useCallback)(() => {
         if (!PredectiveBack_1.PREDICTIVE_BACK_SUPPORTED || !isActive) {
             return undefined;
         }
@@ -160,7 +169,15 @@ const SwipeableScreen = ({ children, enabled = true, style, onHaptic }) => {
             onCommit: () => commit(PredectiveBack_1.PREDICTIVE_BACK_HAS_PROGRESS ? EXIT_DURATION : ENTER_DURATION),
         });
         return () => (0, PredectiveBack_1.releasePredictiveBack)(token);
-    }, [token, isActive, peek, pivot, nativeActive, cancel, commit]));
+    }, [token, isActive, peek, pivot, nativeActive, cancel, commit]);
+    if (navigation) {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        (0, native_1.useFocusEffect)(focusEffectCallback);
+    }
+    else {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        (0, react_1.useEffect)(focusEffectCallback, [focusEffectCallback]);
+    }
     // ─── Drag-to-close from the left edge ────────────────────────────────────
     // On Android this covers the strip just inside the system gesture zone; on iOS it
     // is the only way back. Both drive the same peek, so the card looks identical
@@ -222,20 +239,15 @@ const SwipeableScreen = ({ children, enabled = true, style, onHaptic }) => {
             opacity: (0, react_native_reanimated_1.interpolate)(revealed, [0, 1], [MAX_DIM, 0], react_native_reanimated_1.Extrapolation.CLAMP),
         };
     });
-    return (<react_native_1.View style={styles.outerWrapper}>
-      <react_native_reanimated_1.default.View pointerEvents="none" style={[styles.backdrop, backdropStyle]}/>
-
-      <react_native_gesture_handler_1.GestureDetector gesture={panGesture}>
-        <react_native_reanimated_1.default.View style={[
-            styles.screen,
-            { backgroundColor: theme.colors.background },
-            screenStyle,
-            style,
-        ]}>
-          {children}
-        </react_native_reanimated_1.default.View>
-      </react_native_gesture_handler_1.GestureDetector>
-    </react_native_1.View>);
+    return (react_1.default.createElement(react_native_1.View, { style: styles.outerWrapper },
+        react_1.default.createElement(react_native_reanimated_1.default.View, { pointerEvents: "none", style: [styles.backdrop, backdropStyle] }),
+        react_1.default.createElement(react_native_gesture_handler_1.GestureDetector, { gesture: panGesture },
+            react_1.default.createElement(react_native_reanimated_1.default.View, { style: [
+                    styles.screen,
+                    { backgroundColor },
+                    screenStyle,
+                    style,
+                ] }, children))));
 };
 exports.default = SwipeableScreen;
 const styles = react_native_1.StyleSheet.create({

package/lib/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/appnavigator.jsx","../src/predectiveback.js","../src/swipablescreen.jsx","../src/index.js"],"version":"5.9.3"}

package/lib/typescript/SwipableScreen.d.ts

@@ -1,8 +1,10 @@
 export default SwipeableScreen;
-declare function SwipeableScreen({ children, enabled, style, onHaptic }: {
+declare function SwipeableScreen({ children, enabled, style, onHaptic, backgroundColor, onGoBack }: {
     children: any;
     enabled?: boolean;
     style: any;
     onHaptic: any;
+    backgroundColor?: string;
+    onGoBack: any;
 }): React.JSX.Element;
 import React from "react";

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@honeypathkar/react-native-predictive-back-gesture",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Android 14+ Predictive Back gesture animations and swipeable screen component for React Native.",
   "publishConfig": {
     "access": "public"
   },
-  "main": "src/index.js",
-  "module": "src/index.js",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
   "types": "lib/typescript/index.d.ts",
   "files": [
     "src",
@@ -34,13 +34,12 @@
     "react": "*",
     "react-native": "*",
     "react-native-gesture-handler": "*",
-    "react-native-reanimated": "*",
-    "react-native-paper": "*"
+    "react-native-reanimated": "*"
   },
   "devDependencies": {
     "@types/react": "^18.3.31",
     "react": "^18.2.0",
-    "react-native": "^0.72.0",
+    "react-native": "^0.72.17",
     "react-native-gesture-handler": "^2.12.0",
     "react-native-reanimated": "^3.3.0",
     "typescript": "^5.9.3"

package/src/SwipableScreen.jsx

@@ -13,7 +13,6 @@ import Animated, {
   cancelAnimation,
 } from "react-native-reanimated";
 import { useNavigation, useFocusEffect } from "@react-navigation/native";
-import { useTheme } from "react-native-paper";
 import {
   PREDICTIVE_BACK_HAS_PROGRESS,
   PREDICTIVE_BACK_SUPPORTED,
@@ -48,9 +47,13 @@ const PEEK_THRESHOLD = 0.35;
 const VELOCITY_THRESHOLD = 900;
 const MIN_VELOCITY_DISTANCE = 50;
 
-const SwipeableScreen = ({ children, enabled = true, style, onHaptic }) => {
-  const navigation = useNavigation();
-  const theme = useTheme();
+const SwipeableScreen = ({ children, enabled = true, style, onHaptic, backgroundColor = '#000000', onGoBack }) => {
+  let navigation = null;
+  try {
+    navigation = useNavigation();
+  } catch (e) {
+    // Component rendered outside React Navigation container
+  }
 
   // Gesture progress (0…1) — drives the peek: shrink, drift right, rounded corners.
   const peek = useSharedValue(0);
@@ -86,18 +89,22 @@ const SwipeableScreen = ({ children, enabled = true, style, onHaptic }) => {
   }, [peek, exit, nativeActive]);
 
   const goBack = useCallback(() => {
-    if (!navigation.canGoBack()) {
+    if (onGoBack) {
+      onGoBack();
+      return;
+    }
+    if (!navigation || !navigation.canGoBack()) {
       settle();
       return;
     }
     navigation.goBack();
     // goBack dispatches through `beforeRemove`, so it may not actually pop.
     requestAnimationFrame(() => {
-      if (navigation.isFocused()) {
+      if (navigation && navigation.isFocused && navigation.isFocused()) {
         settle();
       }
     });
-  }, [navigation, settle]);
+  }, [navigation, settle, onGoBack]);
 
   // ─── Commit / cancel ─────────────────────────────────────────────────────
   const commit = useCallback(
@@ -126,43 +133,50 @@ const SwipeableScreen = ({ children, enabled = true, style, onHaptic }) => {
 
   // ─── System back gesture (Android) ───────────────────────────────────────
   const token = useRef({}).current;
-  const isActive = enabled && navigation.canGoBack();
+  const canGoBackInNav = navigation && navigation.canGoBack ? navigation.canGoBack() : false;
+  const isActive = enabled && (canGoBackInNav || !!onGoBack);
 
-  useFocusEffect(
-    useCallback(() => {
-      if (!PREDICTIVE_BACK_SUPPORTED || !isActive) {
-        return undefined;
-      }
+  const focusEffectCallback = useCallback(() => {
+    if (!PREDICTIVE_BACK_SUPPORTED || !isActive) {
+      return undefined;
+    }
 
-      const track = (event) => {
-        peek.value = event.progress;
-        pivot.value = (event.touchY / height) * 2 - 1;
-      };
+    const track = (event) => {
+      peek.value = event.progress;
+      pivot.value = (event.touchY / height) * 2 - 1;
+    };
 
-      acquirePredictiveBack(token, {
-        onStart: (event) => {
-          if (isDismissing.current) {
-            return;
-          }
-          nativeActive.value = 1;
-          cancelAnimation(peek);
+    acquirePredictiveBack(token, {
+      onStart: (event) => {
+        if (isDismissing.current) {
+          return;
+        }
+        nativeActive.value = 1;
+        cancelAnimation(peek);
+        track(event);
+      },
+      onProgress: (event) => {
+        if (!isDismissing.current) {
           track(event);
-        },
-        onProgress: (event) => {
-          if (!isDismissing.current) {
-            track(event);
-          }
-        },
-        onCancel: cancel,
-        // Without live progress (pre-Android 14, or a 3-button back press) the card
-        // has not moved yet, so give the slide-out a little more room to breathe.
-        onCommit: () =>
-          commit(PREDICTIVE_BACK_HAS_PROGRESS ? EXIT_DURATION : ENTER_DURATION),
-      });
+        }
+      },
+      onCancel: cancel,
+      // Without live progress (pre-Android 14, or a 3-button back press) the card
+      // has not moved yet, so give the slide-out a little more room to breathe.
+      onCommit: () =>
+        commit(PREDICTIVE_BACK_HAS_PROGRESS ? EXIT_DURATION : ENTER_DURATION),
+    });
 
-      return () => releasePredictiveBack(token);
-    }, [token, isActive, peek, pivot, nativeActive, cancel, commit]),
-  );
+    return () => releasePredictiveBack(token);
+  }, [token, isActive, peek, pivot, nativeActive, cancel, commit]);
+
+  if (navigation) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useFocusEffect(focusEffectCallback);
+  } else {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useEffect(focusEffectCallback, [focusEffectCallback]);
+  }
 
   // ─── Drag-to-close from the left edge ────────────────────────────────────
   // On Android this covers the strip just inside the system gesture zone; on iOS it
@@ -246,7 +260,7 @@ const SwipeableScreen = ({ children, enabled = true, style, onHaptic }) => {
         <Animated.View
           style={[
             styles.screen,
-            { backgroundColor: theme.colors.background },
+            { backgroundColor },
             screenStyle,
             style,
           ]}

package/lib/commonjs/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["../../src/appnavigator.jsx","../../src/predectiveback.js","../../src/swipablescreen.jsx","../../src/index.js"],"version":"5.9.3"}