react-native-screen-transitions 1.1.0 → 2.0.0

package/README.md

@@ -1,24 +1,12 @@
 # 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>|
+|---|---|
+| <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.
 
-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.
-
 ## 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.
 - **Dependencies**: Requires React Native, Reanimated, Gesture Handler, and either expo-router or react-navigation.
@@ -34,236 +22,170 @@ bun add react-native-screen-transitions
 
 ## Peer Dependencies
 ```bash
-npm install react-native-reanimated react-native-gesture-handler
+npm install react-native-reanimated react-native-gesture-handler \
+  @react-navigation/native @react-navigation/native-stack \
+  @react-navigation/elements react-native-screens \
+  react-native-safe-area-context
 ```
 
-## Your First Screen Transition
-
-Getting started with screen transitions is simple. Here's how to add your first animated transition:
+## Setup
 
-### 1. Wrap your app with GestureHandlerRootView
+### 1. Expo Router
 
 ```tsx
-// app/_layout.tsx (expo-router) or App.tsx (react-navigation)
-import { GestureHandlerRootView } from "react-native-gesture-handler";
-import Transition from "react-native-screen-transitions";
-
-export default function RootLayout() {
-  return (
-    <GestureHandlerRootView style={{ flex: 1 }}>
-      {/* Your navigation setup */}
-    </GestureHandlerRootView>
-  );
-}
+import type {
+  ParamListBase,
+  StackNavigationState,
+} from "@react-navigation/native";
+import { withLayoutContext } from "expo-router";
+import {
+  createNativeStackNavigator,
+  type NativeStackNavigationEventMap,
+  type NativeStackNavigationOptions,
+} from "react-native-screen-transitions";
+
+const { Navigator } = createNativeStackNavigator();
+
+export const Stack = withLayoutContext<
+  NativeStackNavigationOptions,
+  typeof Navigator,
+  StackNavigationState<ParamListBase>,
+  NativeStackNavigationEventMap
+>(Navigator);
 ```
 
-### 2. Add transition configuration to your screens
+That’s it — you’re ready to go.
 
-```tsx
-import { Stack } from "expo-router";
-import Transition from "react-native-screen-transitions";
+### 2. React Navigation (bare)
 
-export default function RootLayout() {
-  return (
-    <GestureHandlerRootView>
-      <Stack>
-        <Stack.Screen
-          name="a"
-          options={{ headerShown: false }}
-          {...Transition.createScreenConfig()}
-        />
-        <Stack.Screen
-          name="b"
-          {...Transition.createScreenConfig({
-            ...Transition.presets.SlideFromTop(),
-          })}
-        />
-      </Stack>
-    </GestureHandlerRootView>
-  );
-}
-```
+If you’re using **React Navigation** directly (not Expo Router), the navigator is already configured.
+No extra setup is required—just import and use as usual:
 
-> ⚠️ **Important**: The first screen (like "a" in the example) must include `{...Transition.createScreenConfig()}` for it to be properly controlled by incoming screens.
+```tsx
+import { createNativeStackNavigator } from 'react-native-screen-transitions';
 
-### 3. Use transition-aware components in your screens
+const Stack = createNativeStackNavigator();
 
-```tsx
-// a.tsx
-import Transition from "react-native-screen-transitions";
+// Use Stack.Navigator and Stack.Screen as normal
+```
 
-export default function A() {
-  return (
-    <Transition.View> {/* By default has flex: 1 */}
-      {/* Your content */}
-    </Transition.View>
-  );
-}
+### Extended native-stack options
 
-// b.tsx
-import Transition from "react-native-screen-transitions";
+This package ships an **extended native stack** built on top of React Navigation’s native stack.
+All the usual native-stack options are available, plus the following extras:
 
-export default function B() {
-  return (
-    <Transition.View>
-      {/* Your content */}
-    </Transition.View>
-  );
-}
-```
+| Option | Type | Description |
+|---|---|---|
+| `enableTransitions` | `boolean` | Switches the screen to a transparent modal and disables the header so custom transitions can take over. |
+| `screenStyleInterpolator` | `ScreenStyleInterpolator` | Function that returns animated styles based on transition progress. |
+| `transitionSpec` | `TransitionSpec` | Reanimated timing/spring config for open/close animations. |
+| `gestureEnabled` | `boolean` | Whether swipe-to-dismiss is allowed. |
+| `gestureDirection` | `GestureDirection \| GestureDirection[]` | Allowed swipe directions (`vertical`, `horizontal`, etc.). |
+| `gestureVelocityImpact` | `number` | How much the gesture’s velocity affects dismissal. |
+| `gestureResponseDistance` | `number` | Distance from screen where the gesture is recognized. |
+| `gestureDrivesProgress` | `boolean` | Whether the gesture directly drives the transition progress. |
 
-### For Nested Navigators
+### Renamed native options (extended stack)
 
-When using nested navigators, wrap the nested Stack in a transition-aware component:
+To avoid collisions with the new options above, the built-in React Navigation gesture props are renamed:
 
-```tsx
-// app/nested/_layout.tsx
-import Transition from "react-native-screen-transitions";
+| React Navigation prop | Renamed to |
+|---|---|
+| `gestureDirection` | `nativeGestureDirection` |
+| `gestureEnabled` | `nativeGestureEnabled` |
+| `gestureResponseDistance` | `nativeGestureResponseDistance` |
 
-export default function TabLayout() {
-  return (
-    <Transition.View>
-      <Stack>
-        <Stack.Screen name="nested-a" {...Transition.createScreenConfig()} />
-        <Stack.Screen name="nested-b" {...Transition.createScreenConfig()} />
-      </Stack>
-    </Transition.View>
-  );
-}
-```
+All other React Navigation native-stack options keep their original names.
 
-## Advanced Usage
 
-### Method 1: Navigator-Level Interpolator (Recommended)
+## Creating your screen animations
 
-Define a `screenStyleInterpolator` at the navigator level to animate both entering and exiting screens simultaneously. This approach is much cleaner.
+### Using presets
 
-```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";
+Pick a built-in preset and spread it into the screen’s options.
+The incoming screen automatically controls the previous screen.
 
-export default function RootLayout() {
-  return (
-    <GestureHandlerRootView>
-      <Stack>
-        <Stack.Screen
-          name="a"
-          {...Transition.createScreenConfig()} // Initialize
-        />
-        <Stack.Screen
-          name="b"
-          {...Transition.createScreenConfig({
-            gestureDirection: "horizontal",
-            gestureEnabled: true,
-            gestureResponseDistance: 50,
-            gestureVelocityImpact: 0.3,
-            screenStyleInterpolator: ({
-              current,
-              next,
-              layouts: { screen: { width } },
-            }) => {
-              "worklet";
-              // Mimics the iOS stack slide animation
-              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,
-              },
-            },
-          })}
-        />
-      </Stack>
-    </GestureHandlerRootView>
-  );
-}
+```tsx
+<Stack>
+  <Stack.Screen
+    name="a"
+  />
+  <Stack.Screen
+    name="b"
+    options={{
+      ...Transition.presets.SlideFromTop(),
+    }}
+  />
+  <Stack.Screen
+    name="c"
+    options={{
+      ...Transition.presets.SlideFromBottom(),
+    }}
+  />
+</Stack>
 ```
 
-When using `screenStyleInterpolator`, both screens must wrap their content in a transition-aware component.
+### Navigator-level custom animations
 
-### Method 2: Screen-Level Animations
+Instead of presets, you can define a custom transition directly on the screen’s options.
+`screenStyleInterpolator` receives an object with the following useful fields:
+
+- `progress` – overall transition progress (`0 → 2`).
+- `current` – state for the current screen (includes `progress`, `closing`, `gesture`, `route`, etc.).
+- `previous` – state for the previous screen (may be `undefined`).
+- `next` – state for the next screen (may be `undefined`).
+- `layouts.screen` – `{ width, height }` of the container.
+- `insets` – `{ top, right, bottom, left }` safe-area insets.
+- `bounds(id)` – helper to compute shared-element transforms (see IntelliSense for chainable methods).
+- `activeBoundId`	– id of the active bound.
+- `focused` – state of the current screen
 
-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. You CAN combine this with `screenStyleInterpolator` for more advanced animations, but for this example, we'll leave `screenStyleInterpolator` undefined.
 
 ```tsx
-// app/_layout.tsx
-<Stack.Screen
-  name="a"
-  {...Transition.createScreenConfig()}
-/>
+import { interpolate } from 'react-native-reanimated'
+
 <Stack.Screen
   name="b"
-  {...Transition.createScreenConfig({
+  options={{
+    enableTransitions: true,
+    screenStyleInterpolator: ({
+      layouts: { screen: { width } },
+      progress,
+    }) => {
+      "worklet";
+
+      const x = interpolate(progress, [0, 1, 2], [width, 0, -width]);
+      return {
+        contentStyle: {
+          transform: [{ translateX: x }],
+        },
+      };
+    },
     transitionSpec: {
-      open: {
-        easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
-        duration: 1000,
-      },
-      close: {
-        damping: 10,
-        mass: 0.5,
-        stiffness: 100,
-      },
+      close: Transition.specs.DefaultSpec,
+      open: Transition.specs.DefaultSpec,
     },
-  })}
+  }}
 />
 ```
 
-```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();
+In this example the incoming screen slides in from the right while the exiting screen slides out to the left.
 
-  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 }],
-    };
-  });
+### Screen-level custom animations with `useScreenAnimation`
 
-  return (
-    <Animated.View style={[{ flex: 1 }, animatedStyle]}>
-      {/* Your content */}
-    </Animated.View>
-  );
-}
+For per-screen control, import the `useScreenAnimation` hook and compose your own animated styles.
 
-// b.tsx (entering screen)
+```tsx
 import { useScreenAnimation } from 'react-native-screen-transitions';
 import Animated, { useAnimatedStyle, interpolate } from 'react-native-reanimated';
 
-export default function B() {
-  const { current, layouts: { screen: { width } } } = useScreenAnimation();
+export default function BScreen() {
+  const props = useScreenAnimation();
 
   const animatedStyle = useAnimatedStyle(() => {
-    // Focusing animation - screen slides in from right
-    const translateX = interpolate(current.progress.value, [0, 1], [width, 0]);
+    const { current: { progress } } = props.value
     return {
-      transform: [{ translateX }],
+      opacity: progress
     };
   });
 
@@ -275,115 +197,193 @@ export default function B() {
 }
 ```
 
+## Swipe-to-dismiss with scrollables
 
-
-## Dismissible Screens with Scrollables
-
-Screen transitions can be dismissed based on defined gesture directions. Integration with scrollable components is seamless:
-
-### Create Custom Transition-Aware Scrollables
-
-You can use built-in scrollables or create your own
+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";
-import { LegendList } from "@legendapp/list";
-import { FlatList, ScrollView } from "react-native";
-import Transition from "react-native-screen-transitions";
 
-// Built-in transition-aware scrollables
-const MyScrollView = Transition.ScrollView;
-const MyFlatList = Transition.FlatList;
+// Drop-in replacements
+const ScrollView = Transition.ScrollView;
+const FlatList = Transition.FlatList;
 
-// Create custom transition-aware scrollables
-const TransitionFlashList = Transition.createTransitionAwareScrollable(FlashList);
-const TransitionLegendList = Transition.createTransitionAwareScrollable(LegendList);
-```
+// Or wrap any list you like
+const TransitionFlashList =
+  Transition.createTransitionAwareScrollable(FlashList, { isScrollable: true });
 
-These components now integrate seamlessly with your transition system and provide smart gesture handling.
+const TransitionLegendList =
+  Transition.createTransitionAwareScrollable(LegendList, { isScrollable: true} );
+```
 
-### Configure Gesture Directions
+Enable the gesture on the screen:
 
 ```tsx
 <Stack.Screen
-  name="scrollable-screen"
-  {...Transition.createScreenConfig({
-    gestureDirection: ["vertical", "vertical-inverted"],
+  name="gallery"
+  options={{
+    enableTransitions: true,
     gestureEnabled: true,
-    // ... other config
-  })}
+    gestureDirection: 'vertical', // or 'horizontal', ['vertical', 'horizontal'], etc.
+  }}
 />
 ```
 
-### Use in Your Screen
+Use it in the screen:
 
 ```tsx
-// scrollable-screen.tsx
-export default function ScrollableScreen() {
+export default function B() {
   return (
     <Transition.ScrollView>
-      {/* Your scrollable content */}
+      {/* content */}
     </Transition.ScrollView>
   );
 }
 ```
 
-**Smart Gesture Handling**: The screen will only start the dismissal process when:
-- `vertical`: ScrollView is at the top (scrollY <= 0)
-- `vertical-inverted`: ScrollView is at the bottom (scrollY >= maxScroll)
-- `horizontal`: ScrollView is at the left edge
-- `horizontal-inverted`: ScrollView is at the right edge
+Gesture rules (handled automatically):
 
-This prevents gesture conflicts and provides intuitive user interaction.
+- **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
 
-## Performance Considerations
+These rules apply **only when the screen contains a scrollable**.
+If no scroll view is present, the gesture can begin from **anywhere on the screen**—not restricted to the edges.
 
-This package is designed for optimal performance, but since underlying screens remain active during transitions, following these guidelines will help maintain smooth 60fps animations:
+## Bounds (measure-driven screen transitions)
 
-### Screen Optimization
-- **Keep screens lightweight**: Minimize heavy computations and complex layouts in screens that will be animated
+Bounds let you animate **any component** between two screens by measuring its start and end positions.
+They are **not shared elements**—they’re just measurements.
+Tag the component you want to animate with `sharedBoundTag`, then describe how it should move when the screen transition starts.
 
-### Animation Properties
-Prioritize transform and opacity properties over layout-affecting properties for the smoothest animations:
+1. Tag the source component
 
-**✅ Performant properties:**
-- `transform` (translateX, translateY, scale, rotate)
-- `opacity`
-- `backgroundColor` (with caution)
+```tsx
+<Transition.View sharedBoundTag="hero" style={{ width: 100, height: 100 }}>
+  <Image source={uri} style={{ width: '100%', height: '100%' }} resizeMode="cover" />
+</Transition.View>
+```
 
-**❌ Avoid when possible:**
-- Layout properties (`width`, `height`, `padding`, `margin`)
-- `borderRadius` on large elements
-- Complex `shadowOffset` or `elevation` changes
-- Frequent `zIndex` modifications
+2. Tag the destination component (same id)
 
-### Easing and Timing Configuration
+```tsx
+<Transition.View sharedBoundTag="hero" style={{ width: 200, height: 200 }}>
+  <Image source={uri} style={{ width: '100%', height: '100%' }} resizeMode="cover" />
+</Transition.View>
+```
 
-Choose balanced easing curves to avoid perceived delays:
+3. Drive the animation in `screenStyleInterpolator`
 
 ```tsx
-// ✅ Good - Smooth and responsive
-transitionSpec: {
-  open: {
-    duration: 300,
-    easing: Easing.bezier(0.25, 0.1, 0.25, 1), // iOS-like easing
-  },
-  close: {
-    duration: 250,
-    easing: Easing.out(Easing.quad),
-  },
-}
+screenStyleInterpolator: ({
+  activeBoundId,
+  bounds,
+  focused,
+  current,
+  next,
+}) => {
+  "worklet";
+
+  const animatedBoundStyles = bounds()
+    .relative()
+    .transform()
+    .build();
+
+  return {
+    [activeBoundId]: animatedBoundStyles,
+  };
+};
+```
 
-// ❌ Avoid - Too snappy, may cause perceived delays
-transitionSpec: {
-  close: {
-    duration: 400,
-    easing: Easing.bezierFn(0, 0.98, 0, 1), // Too abrupt
-  },
-}
+That’s it—the bounds helper works alongside focused and unfocused screens.
+For further customization, separate logic by the `focused` prop:
+
+```tsx
+screenStyleInterpolator: ({
+  activeBoundId,
+  bounds,
+  focused,
+  current,
+  next,
+}) => {
+  "worklet";
+
+
+  if (focused) {
+    const focusedBoundStyles = bounds()
+      .relative()
+      .transform()
+      .build();
+
+    return {
+      [activeBoundId]: focusedBoundStyles,
+    };
+  }
+
+  return {}
+};
 ```
 
-**Why timing matters**: Screen dismissal callbacks execute when animations complete. Overly snappy configurations can create a perceived delay between gesture end and actual screen dismissal. Find the sweet spot that matches your app's personality while feeling responsive.
+
+### Choosing the right modifier
+
+| Modifier | When to use |
+|---|---|
+| `gestures({x,y})` | Sync the bound with live gesture deltas (drag, swipe). |
+| `toFullscreen()` | Destination has no `sharedBoundTag`; animate to full-screen size. |
+| `absolute()` | Element is not constrained by parent layout (uses pageX/pageY). |
+| `relative()` | Element is inside layout constraints (default). |
+| `transform()` | Animate with `translateX/Y` + `scaleX/Y` (default). |
+| `size()` | Animate `translateX/Y` + `width/height` (no scale). |
+| `content()` | Center the container so its bound aligns with the source at progress start. |
+| `contentFill()` / `contentFit()` | Control how the content scales inside the container. |
+| `build()` | Finalize the animated style object. |
+
+### Quick access: `bounds.get()`
+
+Need the raw measurements or styles for a specific bound?
+Call `bounds.get(boundId, phase)` to retrieve the exact dimensions and style object for any bound tag and screen phase (`current`, `next`, or `previous`).
+
+```tsx
+const heroMetrics = bounds.get('hero', 'current');
+// heroMetrics = { bounds: { x, y, width, height, pageX, pageY }, styles: { ... } }
+```
+
+Use this when you want explicit control over which bound’s data you animate, regardless of the current screen focus.
+
+### Animating individual components with `styleId`
+
+Use `styleId` to animate a single view inside a screen.
+
+1. Tag the element:
+
+```tsx
+<Transition.View styleId="fade-box" style={{ width: 100, height: 100, backgroundColor: 'crimson' }} />
+```
+
+2. Drive it from the interpolator:
+
+```tsx
+screenStyleInterpolator: ({ progress }) => {
+  "worklet";
+
+  return {
+    'fade-box': {
+      opacity: interpolate(progress, [0, 1, 2],[0, 1, 0])
+    }
+  };
+};
+```
+
+The red square fades in as the screen opens.
+
+## Known Issues
+
+- **Delayed Touch Events** – There’s a noticeable delay in touch events, likely caused by the `beforeRemove` listener in the native stack. If this affects your app, please hold off on using this package until a fix is available.
+- **Deeply nested navigators with scrollables** – Behavior is currently unstable. We recommend using programmatic dismissal for deeply nested navigators that contain scrollables, as the gesture-driven dismissal logic needs an overhaul.
 
 
 ## Support and Development
@@ -395,6 +395,10 @@ This package is provided as-is and is developed in my free time. While I strive
 
 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.
 
+### Support the project
+I’ve estimated I downed around 60 cups of coffee while building this.
+If you’d like to fuel the next release, [buy me a coffee](https://buymeacoffee.com/trpfsu)
+
 
 
 ## License