react-native-screen-transitions 1.0.3 → 1.2.0

package/README.md

@@ -1,23 +1,28 @@
 # react-native-screen-transitions
 
 
-| iOS | Android |
-|---------|---------|
-|<video src="https://github.com/user-attachments/assets/8a7b8006-f165-4a78-b0f9-c94cddd948b9" width="300" controls></video>|<video src="https://github.com/user-attachments/assets/ddebdaa8-a929-43ab-b857-08a00e142343" width="300" controls></video>|
 
 
-**WIP**: This package is a work-in-progress. It provides customizable screen transition animations for React Native apps, primarily designed for use with `expo-router` and `react-navigation`. It supports gestures, predefined presets, and custom animations, making it easy to add polished transitions to your navigation flows.
 
-This library is inspired by the transition system in `@react-navigation/stack` (not the native stack). If you're familiar with how transitions work there (e.g., using interpolators), you'll find this similar.
 
 
 
 
-## Features
-- Predefined animation presets (e.g., SlideFromTop, ZoomIn, DraggableCard).
-- Gesture support for interactive transitions (e.g., drag-to-dismiss).
-- Animations using Reanimated.
-- Easy integration with expo-router and react-navigation.
+
+
+
+
+
+
+
+
+
+| iOS | Android |
+|---|---|
+| <video src="https://github.com/user-attachments/assets/81f39391-80c0-4ce4-b6ff-76de85d2cf03" width="300" height="600" controls></video> | <video src="https://github.com/user-attachments/assets/c2b4c6ca-2b0c-4cf4-a164-f7e68cee0c32" width="300" controls></video> |
+
+
+**WIP**: This package is a work-in-progress. It provides customizable screen transition animations for React Native apps, primarily designed for use with `expo-router` and `react-navigation`. It supports gestures, predefined presets, and custom animations, making it easy to add polished transitions to your navigation flows.
 
 ## Compatibility
 - **Platforms**: Currently tested on iOS and Android. Not tested or intended for web—web support is not a priority and may not work due to gesture and animation differences.
@@ -34,322 +39,312 @@ bun add react-native-screen-transitions
 
 ## Peer Dependencies
 ```bash
-npm install react-native-reanimated react-native-gesture-handler
-```
-
-## Usage
-
-### Integration with expo-router
-In expo-router, you can define transitions in your root layout (`app/_layout.tsx`) using the `listeners` prop on `Stack.Screen`. Wrap your app in `GestureHandlerRootView` for gesture support.
-
-```tsx
-// app/_layout.tsx
-import { Stack } from "expo-router";
-import { GestureHandlerRootView } from "react-native-gesture-handler";
-import Transition from "react-native-screen-transitions";
-
-export default function RootLayout() {
-  return (
-    <GestureHandlerRootView>
-      <Stack>
-        <Stack.Screen
-          name="index"
-          listeners={Transition.createConfig}
-        />
-        <Stack.Screen
-          name="a"
-          options={Transition.defaultScreenOptions()}
-          listeners={(l) =>
-            Transition.createConfig({
-              ...l,
-              ...Transition.presets.SlideFromTop(),
-            })
-          }
-        />
-        {/* Add more screens with presets */}
-      </Stack>
-    </GestureHandlerRootView>
-  );
-}
+npm install react-native-reanimated react-native-gesture-handler @react-navigation/native-stack
 ```
 
-**Note**: `Transition.defaultScreenOptions()` returns the required screen options for animations to work properly. It sets `presentation: "containedTransparentModal"`, `headerShown: false`, and `animation: "none"` to ensure the library can control the transition animations.
-
-For grouped routes with layouts (e.g., `app/group-a/_layout.tsx`), wrap the nested `Stack` in `Transition.View` to enable transitions:
+## Setup
 
+### 1. React Navigation
 ```tsx
-// app/group-a/_layout.tsx
-import { Stack } from "expo-router";
-import Transition from "react-native-screen-transitions";
-
-export default function GroupLayout() {
-  return (
-    <Transition.View>
-      <Stack>
-        <Stack.Screen name="a" />
-        {/* Nested screens */}
-      </Stack>
-    </Transition.View>
-  );
-}
-```
-
-### Integration with react-navigation
-For react-navigation, use `createNativeStackNavigator` and apply transitions via `listeners` and `options`.
-
-```tsx
-// App.tsx
-import { createStaticNavigation } from "@react-navigation/native";
-import { createNativeStackNavigator } from "@react-navigation/native-stack";
-import { GestureHandlerRootView } from "react-native-gesture-handler";
-import Transition from "react-native-screen-transitions";
-import { Home } from "./screens/Home"; // Your screens
-import { ScreenA } from "./screens/ScreenA";
-
-const RootStack = createNativeStackNavigator({
-  screens: {
-    Home: {
-      screen: Home,
-      listeners: Transition.createConfig,
-    },
-    ScreenA: {
-      screen: ScreenA,
-      options: Transition.defaultScreenOptions(),
-      listeners: (l) =>
-        Transition.createConfig({
-          ...l,
-          ...Transition.presets.SlideFromTop(),
-        }),
-    },
-    // Add more screens
-  },
-});
+import { NavigationContainer } from '@react-navigation/native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import Transition from 'react-native-screen-transitions';
 
-const Navigation = createStaticNavigation(RootStack);
+const Stack = Transition.createTransitionableStackNavigator();
 
 export default function App() {
   return (
     <GestureHandlerRootView>
-      <Navigation />
+      <NavigationContainer>
+        <Stack.Navigator>
+          <Stack.Screen
+            name="Home"
+            component={Home}
+            options={{
+              skipDefaultScreenOptions: true, // prevents transparent-modal default
+            }}
+          />
+          <Stack.Screen
+            name="A"
+            component={ScreenA}
+            options={{
+              ...Transition.presets.SlideFromTop(),
+            }}
+          />
+        </Stack.Navigator>
+      </NavigationContainer>
     </GestureHandlerRootView>
   );
 }
 ```
 
-For nested navigators, wrap them in `Transition.View` similar to expo-router.
-
-### Predefined Presets
-Use these out-of-the-box animations via `Transition.presets`:
+### 2. Expo Router
+Use the withLayoutContext to convert it into an expo router compatible navigator.
 
-- `SlideFromTop()`: Screen slides in from the top.
-- `ZoomIn()`: Screen zooms in from the center.
-- `SlideFromBottom()`: Screen slides in from the bottom.
-- `DraggableCard()`: Interactive card-like drag gesture.
-- `ElasticCard()`: Elastic bounce effect on drag.
-
-Example:
 ```tsx
-listeners={(l) => Transition.createConfig({ ...l, ...Transition.presets.DraggableCard() })}
+import { withLayoutContext } from 'expo-router';
+import Transition, {
+  type TransitionStackNavigatorTypeBag,
+} from 'react-native-screen-transitions';
+
+const TransitionableNativeStack =
+  Transition.createTransitionableStackNavigator();
+
+export const Stack = withLayoutContext<
+  TransitionStackNavigatorTypeBag['ScreenOptions'],
+  typeof TransitionableNativeStack.Navigator,
+  TransitionStackNavigatorTypeBag['State'],
+  TransitionStackNavigatorTypeBag['EventMap']
+>(TransitionableNativeStack.Navigator);
 ```
 
-### Defining your own screen animations
-There are two ways to define custom animations: at the navigator level using `screenStyleInterpolator` (recommended for animating both screens simultaneously), or at the screen level using `useScreenAnimation` hook.
-
-#### Method 1: Navigator-Level Interpolator (Recommended)
-Define a `screenStyleInterpolator` at the navigator level to animate both the entering and exiting screens simultaneously. This approach provides the most control.
+Use it exactly like any other Expo Router layout:
 
 ```tsx
-// app/_layout.tsx
-import { Stack } from "expo-router";
-import { GestureHandlerRootView } from "react-native-gesture-handler";
-import Transition from "react-native-screen-transitions";
-import { interpolate, Easing } from "react-native-reanimated";
+import { Stack } from './layouts/stack.tsx'
 
-export default function RootLayout() {
-  return (
+export default function RootLayout(){
+  return(
     <GestureHandlerRootView>
       <Stack>
         <Stack.Screen
           name="a"
-          listeners={Transition.createConfig} // Add blank config so system knows what to animate
+          options={{
+            // You usually don't want your first screen to be a transparent modal.
+            skipDefaultScreenOptions: true,
+          }}
         />
         <Stack.Screen
           name="b"
-          options={Transition.defaultScreenOptions()}
-          listeners={(l) =>
-            Transition.createConfig({
-              ...l,
-              gestureDirection: "horizontal",
-              gestureEnabled: true,
-              gestureResponseDistance: 50,
-              gestureVelocityImpact: 0.3,
-              screenStyleInterpolator: ({
-                current,
-                next,
-                layouts: { screen: { width } },
-              }) => {
-                "worklet";
-
-                const progress = current.progress.value + (next?.progress.value || 0);
-
-                const translateX = interpolate(
-                  progress,
-                  [0, 1, 2],
-                  [width, 0, width * -0.3],
-                  "clamp"
-                );
-
-                return {
-                  contentStyle: {
-                    transform: [{ translateX }],
-                  },
-                };
-              },
-              transitionSpec: {
-                open: {
-                  easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
-                  duration: 1000,
-                },
-                close: {
-                  damping: 10,
-                  mass: 0.5,
-                  stiffness: 100,
-                },
-              },
-            })
-          }
+          options={{
+            ...Transition.presets.SlideFromTop(),
+          }}
         />
       </Stack>
     </GestureHandlerRootView>
-  );
+  )
 }
 ```
 
-When using `screenStyleInterpolator`, both screens must wrap their content in `Transition.View`:
+> **Note**: `Transition.createTransitionableStackNavigator()` returns a Native Stack Navigator that's been injected with the necessary functionality for screen transitions to work.
+
+
+## Creating your screen animations
+
+### Using presets
+
+Pick a built-in preset and spread it into the screen’s options.
+The incoming screen automatically controls the previous screen.
 
 ```tsx
-// a.tsx
-import Transition from 'react-native-screen-transitions';
+<Stack>
+  <Stack.Screen
+    name="a"
+    options={{
+      // avoids transparent-modal default for first screen
+      skipDefaultScreenOptions: true,
+    }}
+  />
+  <Stack.Screen
+    name="b"
+    options={{
+      ...Transition.presets.SlideFromTop(),
+    }}
+  />
+  <Stack.Screen
+    name="c"
+    options={{
+      ...Transition.presets.SlideFromBottom(),
+    }}
+  />
+</Stack>
+```
 
-export default function A() {
-  return (
-    <Transition.View>
-      {/* Your content */}
-    </Transition.View>
-  );
-}
+> ⚠️ **Important**
+> Any screen that **must** participate in a transition (i.e., be animated) **must** be wrapped in a transition-aware component.
+> For example, if both `a` and `b` are meant to animate, wrap each screen’s root like this:
 
-// b.tsx
-import Transition from 'react-native-screen-transitions';
+```tsx
+// a.tsx
+<Transition.View>
+  ...
+</Transition.View>
 
-export default function B() {
-  return (
-    <Transition.View>
-      {/* Your content */}
-    </Transition.View>
-  );
-}
+// b.tsx
+<Transition.View>
+  ...
+</Transition.View>
 ```
 
-#### Method 2: Screen-Level Animations
-Alternatively, define animations at the screen level using the `useScreenAnimation` hook. This is useful for screen-specific effects or when you don't need to animate both screens.
+Without this wrapper, the transition system cannot animate the screen and the animation will appear broken or skipped.
+
+
+
+### Navigator-level custom animations
+
+Instead of presets, you can define a custom transition directly on the screen’s options.
+The `screenStyleInterpolator` receives the current and next screen’s progress and lets you animate both at once.
 
 ```tsx
-// app/_layout.tsx
-<Stack.Screen
-  name="a"
-  listeners={Transition.createConfig}
-/>
+import { interpolate } from 'react-native-reanimated'
 <Stack.Screen
   name="b"
-  options={Transition.defaultScreenOptions()}
-  listeners={(l) =>
-    Transition.createConfig({
-      ...l,
-      transitionSpec: {
-        open: {
-          easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
-          duration: 1000,
+  options={{
+    screenStyleInterpolator: ({
+      current,
+      next,
+      layouts: { screen: { width } },
+    }) => {
+      "worklet";
+
+      const progress = current.progress.value + (next?.progress.value ?? 0);
+
+      const x = interpolate(progress, [0, 1, 2], [width, 0, -width]);
+      return {
+        contentStyle: {
+          transform: [{ translateX: x }],
         },
-        close: {
-          damping: 10,
-          mass: 0.5,
-          stiffness: 100,
-        },
-      },
-    })
-  }
+      };
+    },
+    transitionSpec: {
+      close: Transition.specs.DefaultSpec,
+      open: Transition.specs.DefaultSpec,
+    },
+  }}
 />
 ```
 
+In this example the incoming screen slides in from the right while the exiting screen slides out to the left.
+
+### Screen-level custom animations with `useScreenAnimation`
+
+For per-screen control, import the `useScreenAnimation` hook and compose your own animated styles.
+
 ```tsx
-// a.tsx (previous screen)
 import { useScreenAnimation } from 'react-native-screen-transitions';
 import Animated, { useAnimatedStyle, interpolate } from 'react-native-reanimated';
 
-export default function A() {
-  const { next, layouts: { screen: { width } } } = useScreenAnimation();
+export default function BScreen() {
+  const { current } = useScreenAnimation();
 
   const animatedStyle = useAnimatedStyle(() => {
-    // Unfocusing animation - screen slides left when next screen enters
-    const translateX = interpolate(next?.progress.value || 0, [0, 1], [0, width * -0.3]);
     return {
-      transform: [{ translateX }],
+      opacity: current.progress.value
     };
   });
 
   return (
-    <Animated.View style={animatedStyle}>
+    <Animated.View style={[{ flex: 1 }, animatedStyle]}>
       {/* Your content */}
     </Animated.View>
   );
 }
+```
 
-// b.tsx (entering screen)
-import { useScreenAnimation } from 'react-native-screen-transitions';
-import Animated, { useAnimatedStyle, interpolate } from 'react-native-reanimated';
+## Apply screen transitions to nested navigators
 
-export default function B() {
-  const { current, layouts: { screen: { width } } } = useScreenAnimation();
+When a screen contains its own stack (e.g., `b` is a nested navigator), wrap the nested `Stack` in a `Transition.View`.
 
-  const animatedStyle = useAnimatedStyle(() => {
-    // Focusing animation - screen slides in from right
-    const translateX = interpolate(current.progress.value, [0, 1], [width, 0]);
-    return {
-      transform: [{ translateX }],
-    };
-  });
+```tsx
+// app/b/_layout.tsx  (nested stack for screen "b")
+import { Stack } from 'expo-router';
+import Transition from 'react-native-screen-transitions';
 
+export default function BLayout() {
   return (
-    <Animated.View style={[{ flex: 1 }, animatedStyle]}>
-      {/* Your content */}
-    </Animated.View>
+    <Transition.View>
+      <Stack>
+        <Stack.Screen name="index" options={{ headerShown: false }} />
+        <Stack.Screen name="details" options={{ headerShown: false }} />
+      </Stack>
+    </Transition.View>
   );
 }
+```
+
+The outer transition now treats the entire nested stack as a single animatable view while each inner screen can still function normally—whether you keep the native stack or swap it for the Transitionable Stack.
+
+## Swipe-to-dismiss with scrollables
+
+You can drag a screen away even when it contains a scroll view.
+Just swap the regular scrollable for a transition-aware one:
+
+```tsx
+import Transition from 'react-native-screen-transitions';
+import { LegendList } from "@legendapp/list"
+import { FlashList } from "@shopify/flash-list";
+
+// Drop-in replacements
+const ScrollView = Transition.ScrollView;
+const FlatList   = Transition.FlatList;
 
+// Or wrap any list you like
+const TransitionFlashList =
+  Transition.createTransitionAwareScrollable(FlashList);
+
+const TransitionLegendList =
+  Transition.createTransitionAwareScrollable(LegendList);
+```
 
+Enable the gesture on the screen:
+
+```tsx
+<Stack.Screen
+  name="gallery"
+  options={{
+    gestureEnabled: true,
+    gestureDirection: 'vertical', // or 'horizontal', ['vertical', 'horizontal'], etc.
+  }}
+/>
 ```
 
+Use it in the screen:
+
+```tsx
+export default function B() {
+  return (
+    <Transition.ScrollView>
+      {/* content */}
+    </Transition.ScrollView>
+  );
+}
+```
+
+Gesture rules (handled automatically):
+
+- **vertical** – only starts when the list is at the very top
+- **vertical-inverted** – only starts when the list is at the very bottom
+- **horizontal** / **horizontal-inverted** – only starts when the list is at the left or right edge
+
+These rules apply **only when the screen contains a nested scrollable**.
+If no scroll view is present, the gesture can begin from **anywhere on the screen**—not restricted to the edges.
+
+## Performance tips
+
+Keep animations smooth and responsive:
+
+- **Optimize screen content** – avoid heavy computations, complex layouts, or expensive renders in screens that animate
+- **Use GPU-friendly properties** – stick to `transform` and `opacity` which are hardware-accelerated; avoid animating `width`, `height`, `padding`, large `borderRadius`, and complex shadows
+- **Choose appropriate timing** – use natural easing curves and durations that feel responsive without being jarring
+
+## Roadmap
+
+- **Shared element transitions** – seamless hand-off of components between screens
+- **Gesture-driven forward navigation** – allow gestures to trigger push navigation events
+- **Performance maximization** – further reduce JS thread work and leverage Reanimated 3’s new APIs for even smoother 60 fps animations
+
+
+## Support and Development
 
-### Known Issues and Roadmap
-This is a WIP package, so expect improvements. Current known issues:
-- **Gestures with ScrollViews**: Gestures can be wonky when combined with scrollable content. For example, if a screen defines vertical dismissal gestures and contains a vertical `ScrollView`, the gesture may not trigger reliably (conflicts with scroll handling).
-- **Gestures Dismisall with Nested Navigators**: When using nested navigators with gesture dismissal enabled, dismissing a nested screen via gesture may cause the transparent modal to appear dismissed while remaining open. This affects the visual state but not the actual navigation state.
-- **Web Support**: Not intended or tested for web—focus is on mobile (iOS/Android). Web may have issues with gestures and animations.
+This package is provided as-is and is developed in my free time. While I strive to maintain and improve it, please understand that:
 
+- **Updates and bug fixes** may take time to implement
+- **Feature requests** will be considered but may not be prioritized immediately
 
-### Note:
+I apologize for any inconvenience this may cause. If you encounter issues or have suggestions, please feel free to open an issue on the repository.
 
-This package is something I'll work on in my freetime. However, you can see the roadmap I plan on following in the coming future.
 
-Roadmap:
-- Fix gesture conflicts with ScrollViews (e.g., better gesture priority handling).
-- Add more presets and customization options.
-- Improve documentation and examples.
-- Potential web support if demand arises.
-- Testing for more edge cases (e.g., modals, tabs).
 
-See the examples in `/examples/expo-router-example` and `/examples/react-nav-example` for full demos.
 
 ## License
 MIT