react-native-screen-transitions 3.3.0 → 3.4.0-alpha.0

package/README.md

@@ -9,10 +9,13 @@ Customizable screen transitions for React Native. Build gesture-driven, shared e
 ## Features
 
 - **Full Animation Control** – Define exactly how screens enter, exit, and respond to gestures
-- **Shared Elements** – Smooth transitions between screens using the Bounds API
-- **Gesture Support** – Swipe-to-dismiss with edge or full-screen activation
+- **Shared Elements** – Smooth transitions between screens using `Transition.Boundary` and the Bounds API
+- **Navigation Bounds** – SwiftUI-like zoom transitions with masked reveal effects via `bounds().navigation.zoom()`
+- **Gesture Support** – Swipe-to-dismiss with edge or full-screen activation, configurable velocity
+- **Animated Props** – Drive component-specific props (e.g., BlurView `intensity`) alongside styles
+- **Custom Layers** – `surfaceComponent` and `backdropComponent` with animated styles and props
 - **Stack Progress** – Track animation progress across the entire stack
-- **Ready-Made Presets** – Instagram, Apple Music, X (Twitter) style transitions included
+- **Ready-Made Presets** – Instagram, Apple Music, X (Twitter), zoom navigation style transitions included
 
 ## When to Use This Library
 
@@ -140,8 +143,10 @@ options={{
   screenStyleInterpolator: ({ progress }) => {
     "worklet";
     return {
-      contentStyle: {
-        opacity: interpolate(progress, [0, 1, 2], [0, 1, 0]),
+      content: {
+        style: {
+          opacity: interpolate(progress, [0, 1, 2], [0, 1, 0]),
+        },
       },
     };
   },
@@ -155,49 +160,87 @@ options={{
   screenStyleInterpolator: ({ progress, layouts: { screen } }) => {
     "worklet";
     return {
-      contentStyle: {
-        transform: [{
-          translateX: interpolate(
-            progress,
-            [0, 1, 2],
-            [screen.width, 0, -screen.width * 0.3]
-          ),
-        }],
+      content: {
+        style: {
+          transform: [{
+            translateX: interpolate(
+              progress,
+              [0, 1, 2],
+              [screen.width, 0, -screen.width * 0.3]
+            ),
+          }],
+        },
       },
     };
   },
 }}
 ```
 
-### Slide from Bottom
+### Slide from Bottom with Backdrop
 
 ```tsx
 options={{
   screenStyleInterpolator: ({ progress, layouts: { screen } }) => {
     "worklet";
     return {
-      contentStyle: {
-        transform: [{
-          translateY: interpolate(progress, [0, 1], [screen.height, 0]),
-        }],
+      content: {
+        style: {
+          transform: [{
+            translateY: interpolate(progress, [0, 1], [screen.height, 0]),
+          }],
+        },
+      },
+      backdrop: {
+        style: {
+          backgroundColor: "black",
+          opacity: interpolate(progress, [0, 1], [0, 0.5]),
+        },
       },
     };
   },
 }}
 ```
 
-### Return Styles
+### Return Format
 
-Your interpolator can return:
+Your interpolator returns a map of **slots**. The canonical format is explicit `{ style, props }`:
 
 ```tsx
 return {
-  contentStyle: { ... },   // Main screen
-  backdropStyle: { ... },  // Semi-transparent backdrop
-  ["my-id"]: { ... },      // Specific element via styleId
+  content: {
+    style: { opacity: 1 },
+  },                          // Main screen content
+  backdrop: {
+    style: { opacity: 0.5 },
+    props: { intensity: 80 }, // for components like BlurView
+  },                          // Backdrop layer between screens
+  surface: {
+    style: { transform: [{ scale: 0.98 }] },
+  },                          // Surface component layer
+  ["hero-image"]: {
+    style: { borderRadius: 24 },
+  },                          // Specific element via styleId
 };
 ```
 
+Shorthand styles are still supported and auto-wrapped as `{ style: value }`:
+
+```tsx
+// Shorthand
+content: {
+  opacity: 0.5,
+  transform: [{ scale: 0.9 }],
+},
+
+// Explicit
+content: {
+  style: { opacity: 0.5, transform: [{ scale: 0.9 }] },
+  props: { intensity: 80 },  // for useAnimatedProps (e.g., BlurView)
+},
+```
+
+> **Legacy format**: The flat `contentStyle`/`backdropStyle` format is still supported but deprecated. It will be auto-converted with a one-time warning in development.
+
 ### Animation Specs
 
 Control timing with spring configs:
@@ -230,19 +273,23 @@ options={{
 
 ### Gesture Options
 
-| Option                    | Description                                                              |
-| ------------------------- | ------------------------------------------------------------------------ |
-| `gestureEnabled`          | Enable swipe-to-dismiss (snap sheets: `false` blocks dismiss-to-0 only) |
-| `gestureDirection`        | Direction(s) for swipe gesture                                           |
-| `gestureActivationArea`   | Where gesture can start                                                  |
-| `gestureResponseDistance` | Pixel threshold for activation                                           |
-| `gestureVelocityImpact`   | How much velocity affects dismissal (default: 0.3)                       |
-| `gestureDrivesProgress`   | Whether gesture controls animation progress (default: true)              |
-| `snapVelocityImpact`      | How much velocity affects snap targeting (default: 0.1, lower = iOS-like)|
-| `expandViaScrollView`     | Allow expansion from ScrollView at boundary (default: true)               |
-| `gestureSnapLocked`       | Lock gesture-based snap movement to current snap point                   |
-| `backdropBehavior`        | Touch handling for backdrop area                                         |
-| `backdropComponent`       | Custom backdrop component (replaces default backdrop + press behavior)   |
+| Option                          | Description                                                              |
+| ------------------------------- | ------------------------------------------------------------------------ |
+| `gestureEnabled`                | Enable swipe-to-dismiss (snap sheets: `false` blocks dismiss-to-0 only) |
+| `gestureDirection`              | Direction(s) for swipe gesture                                           |
+| `gestureActivationArea`         | Where gesture can start                                                  |
+| `gestureResponseDistance`       | Pixel threshold for activation                                           |
+| `gestureVelocityImpact`        | How much velocity affects dismissal (default: 0.3)                       |
+| `gestureDrivesProgress`        | Whether gesture controls animation progress (default: true)              |
+| `snapVelocityImpact`           | How much velocity affects snap targeting (default: 0.1, lower = iOS-like)|
+| `gestureReleaseVelocityScale`  | Multiplier for post-release spring velocity (default: 1)                 |
+| `gestureReleaseVelocityMax`    | Cap on post-release spring velocity (default: 3.2)                       |
+| `expandViaScrollView`          | Allow expansion from ScrollView at boundary (default: true)              |
+| `gestureSnapLocked`            | Lock gesture-based snap movement to current snap point                   |
+| `backdropBehavior`             | Touch handling for backdrop area                                         |
+| `backdropComponent`            | Custom backdrop component, driven by interpolator `backdrop` slot        |
+| `surfaceComponent`             | Custom surface component, driven by interpolator `surface` slot          |
+| `maskEnabled`                  | Pre-mount masked view wrapper for navigation bounds masking              |
 
 ### Gesture Direction
 
@@ -290,6 +337,8 @@ Gesture rules with scrollables:
 - **vertical-inverted** – only activates when scrolled to bottom
 - **horizontal** – only activates at left/right scroll edges
 
+`Transition.ScrollView` and `Transition.FlatList` also emit a settled signal (on momentum end, or drag end with no momentum). Grouped boundaries listen for that signal and re-measure source bounds while idle, which keeps list/detail shared transitions accurate after focus-change auto-scrolling.
+
 ---
 
 ## Snap Points
@@ -333,7 +382,7 @@ Create multi-stop sheets that snap to defined positions. Works with any gesture
 | `initialSnapIndex` | Index of initial snap point (default: 0)                             |
 | `gestureSnapLocked` | Locks gesture snapping to current point (programmatic `snapTo` still works) |
 | `backdropBehavior` | Touch handling: `"block"`, `"passthrough"`, `"dismiss"`, `"collapse"`|
-| `backdropComponent` | Custom backdrop component; replaces default backdrop + tap handling    |
+| `backdropComponent` | Custom backdrop component, driven by interpolator `backdrop` slot     |
 
 #### backdropBehavior Values
 
@@ -346,39 +395,69 @@ Create multi-stop sheets that snap to defined positions. Works with any gesture
 
 #### Custom Backdrop Component
 
-Use `backdropComponent` when you want full control over backdrop visuals and interactions.
+Use `backdropComponent` to provide a custom component for the backdrop layer between screens (e.g., a `BlurView`).
 
-- When provided, it replaces the default backdrop entirely (including default tap behavior)
-- You are responsible for dismiss/collapse actions inside the custom component
-- `backdropBehavior` still controls container-level pointer event behavior
+- The library wraps your component with `Animated.createAnimatedComponent` internally
+- Animated styles and props are driven by the `backdrop` slot in your interpolator
+- `backdropBehavior` still controls the wrapping `Pressable` for dismiss/collapse handling
 
 ```tsx
-import { router } from "expo-router";
-import { Pressable } from "react-native";
-import Animated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
-import { useScreenAnimation } from "react-native-screen-transitions";
-
-function SheetBackdrop() {
-  const animation = useScreenAnimation();
-
-  const style = useAnimatedStyle(() => ({
-    opacity: interpolate(animation.value.current.progress, [0, 1], [0, 0.4]),
-    backgroundColor: "#000",
-  }));
-
-  return (
-    <Pressable style={{ flex: 1 }} onPress={() => router.back()}>
-      <Animated.View style={[{ flex: 1 }, style]} />
-    </Pressable>
-  );
-}
+import { BlurView } from "expo-blur";
 
 <Stack.Screen
   name="Sheet"
   options={{
     snapPoints: [0.5, 1],
     backdropBehavior: "dismiss",
-    backdropComponent: SheetBackdrop,
+    backdropComponent: BlurView,
+    screenStyleInterpolator: ({ progress }) => {
+      "worklet";
+      return {
+        backdrop: {
+          style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
+          props: { intensity: interpolate(progress, [0, 1], [0, 80]) },
+        },
+        content: {
+          style: {
+            transform: [{ translateY: interpolate(progress, [0, 1], [800, 0]) }],
+          },
+        },
+      };
+    },
+  }}
+/>
+```
+
+The `props` bucket is applied via `useAnimatedProps`, letting you animate component-specific properties like `BlurView`'s `intensity` or `SquircleView`'s `cornerRadius`.
+
+#### Custom Surface Component
+
+Use `surfaceComponent` to render a custom surface inside the animated content wrapper (e.g., a `SquircleView` for smooth rounded corners).
+
+- `content` drives container-level transitions (position/scale/opacity)
+- `surface` drives custom surface styles/props
+- Animated props are driven by the `surface` slot in your interpolator
+
+```tsx
+import { SquircleView } from "react-native-figma-squircle";
+
+<Stack.Screen
+  name="Card"
+  options={{
+    surfaceComponent: SquircleView,
+    screenStyleInterpolator: ({ progress }) => {
+      "worklet";
+      return {
+        content: {
+          style: {
+            transform: [{ scale: interpolate(progress, [0, 1], [0.8, 1]) }],
+          },
+        },
+        surface: {
+          props: { cornerRadius: 24, cornerSmoothing: 0.7 },
+        },
+      };
+    },
   }}
 />
 ```
@@ -413,8 +492,10 @@ screenStyleInterpolator: ({ snapIndex }) => {
   // snapIndex interpolates between snap point indices
   // e.g., 0.5 means halfway between snap point 0 and 1
   return {
-    contentStyle: {
-      opacity: interpolate(snapIndex, [0, 1], [0.5, 1]),
+    content: {
+      style: {
+        opacity: interpolate(snapIndex, [0, 1], [0.5, 1]),
+      },
     },
   };
 }
@@ -444,46 +525,153 @@ transitionSpec: {
 
 ## Shared Elements (Bounds API)
 
-Animate elements between screens by tagging them.
+Animate elements between screens by tagging them. There are two approaches: the `Transition.Boundary` namespace for declarative shared element transitions, and `sharedBoundTag` on `Transition.View`/`Transition.Pressable` for inline usage.
+
+### Transition.Boundary
+
+The recommended setup. `Transition.Boundary` is a namespace with prebuilt variants:
+- `Transition.Boundary.Pressable` for source elements that trigger navigation
+- `Transition.Boundary.View` for passive source/destination elements
+
+```tsx
+// Source screen — list item
+<Transition.Boundary.Pressable
+  id="album-art"
+  group="albums"           // Optional: list/collection grouping
+  onPress={() => router.push("/details")}
+>
+  <Image source={album} style={{ width: 100, height: 100 }} />
+</Transition.Boundary.Pressable>
+
+// Destination screen
+<Transition.Boundary.View id="album-art">
+  <Image source={album} style={{ width: 300, height: 300 }} />
+</Transition.Boundary.View>
+```
+
+#### Boundary Props
+
+| Prop        | Description                                                        |
+| ----------- | ------------------------------------------------------------------ |
+| `id`        | Unique identifier for matching across screens                      |
+| `group`     | Group name for list/collection scenarios (tag becomes `group:id`)  |
+| `enabled`   | Whether this boundary participates in matching (default: true)     |
+| `method`    | `"transform"` `"size"` `"content"` — how to animate               |
+| `anchor`    | Alignment anchor point                                             |
+| `scaleMode` | `"match"` `"none"` `"uniform"` — aspect ratio handling             |
+| `target`    | Target for size calculations (for example `"fullscreen"`)          |
+
+#### Groups
+
+For list/collection scenarios where multiple items share the same transition:
+
+```tsx
+{items.map((item) => (
+  <Transition.Boundary.Pressable
+    key={item.id}
+    id={item.id}
+    group="photos"
+    onPress={() => router.push(`/photo/${item.id}`)}
+  >
+    <Image source={item.src} />
+  </Transition.Boundary.Pressable>
+))}
+```
+
+Only the tapped item transitions. The library tracks the active member for each group, and transition-aware scrollables emit settled signals so grouped boundaries can re-measure after focus-change auto-scrolling.
+
+### Custom Boundary Components
+
+Use the boundary factory when you want a custom wrapped component (for example `Image`, `BlurView`, or design-system primitives):
+
+```tsx
+import { Image } from "react-native";
+import Transition from "react-native-screen-transitions";
+
+const BoundaryImage = Transition.createBoundaryComponent(Image);
+
+<BoundaryImage id="cover-art" group="albums" source={cover} />
+```
+
+### Inline Shared Elements
 
-### 1. Tag the Source
+For simpler legacy cases, use `sharedBoundTag` directly on `Transition.View` or `Transition.Pressable`:
 
 ```tsx
+// Source
 <Transition.Pressable
   sharedBoundTag="avatar"
   onPress={() => navigation.navigate("Profile")}
 >
   <Image source={avatar} style={{ width: 50, height: 50 }} />
 </Transition.Pressable>
-```
-
-### 2. Tag the Destination
 
-```tsx
+// Destination
 <Transition.View sharedBoundTag="avatar">
   <Image source={avatar} style={{ width: 200, height: 200 }} />
 </Transition.View>
 ```
 
-### 3. Use in Interpolator
+> `sharedBoundTag` on `Transition.Pressable` is planned for deprecation in the next major version. Prefer `Transition.Boundary.Pressable` and `Transition.Boundary.View`.
+
+### Using Bounds in Interpolators
 
 ```tsx
 screenStyleInterpolator: ({ bounds }) => {
   "worklet";
   return {
-    avatar: bounds({ id: "avatar", method: "transform" }),
+    "avatar": bounds({ id: "avatar", method: "transform" }),
   };
 };
 ```
 
+### Navigation Bounds (Zoom Transitions)
+
+For SwiftUI-like navigation zoom transitions where content expands from a source element with a masked reveal:
+
+```tsx
+<Stack.Screen
+  name="Detail"
+  options={{
+    maskEnabled: true,  // Required for masked reveal
+    screenStyleInterpolator: ({ bounds, progress, focused }) => {
+      "worklet";
+      if (!focused) return {};
+
+      return bounds({
+        id: "album-art",
+      }).navigation.zoom();
+    },
+    transitionSpec: {
+      open: { stiffness: 1000, damping: 500, mass: 3, overshootClamping: true },
+      close: { stiffness: 1000, damping: 500, mass: 3, overshootClamping: true },
+    },
+  }}
+/>
+```
+
+`bounds().navigation.zoom()` returns a complete interpolator result with content, mask, and container styles. Set `maskEnabled: true` to pre-mount the masked view wrapper so it's ready from the first frame.
+
+`navigation.zoom()` does not accept options.
+
+Configuration guidance:
+- Preferred: define transition configuration on boundary components (`anchor`, `scaleMode`, `target`, `method`) via `Transition.Boundary.View` / `Transition.Boundary.Pressable`.
+- Supported but secondary: pass options through `bounds({ ... })` when needed.
+
+> **Note**: Navigation bounds masking requires `@react-native-masked-view/masked-view` to be installed.
+
 ### Bounds Options
 
+`bounds({ ... })` options are supported. For shared boundary flows, prefer setting configuration on boundary components and keep `bounds({ id })` minimal.
+
 | Option      | Values                             | Description                   |
 | ----------- | ---------------------------------- | ----------------------------- |
-| `id`        | string                             | The `sharedBoundTag` to match |
+| `id`        | string                             | The boundary id to match      |
 | `method`    | `"transform"` `"size"` `"content"` | How to animate                |
 | `space`     | `"relative"` `"absolute"`          | Coordinate space              |
 | `scaleMode` | `"match"` `"none"` `"uniform"`     | Aspect ratio handling         |
+| `anchor`    | string                             | Alignment anchor point        |
+| `target`    | `"fullscreen"` etc.                | Target for size calculations  |
 | `raw`       | boolean                            | Return raw values             |
 
 ---
@@ -524,13 +712,17 @@ const TabBar = ({ focusedIndex, progress }) => {
 
 ## Transition Components
 
-| Component               | Description                            |
-| ----------------------- | -------------------------------------- |
-| `Transition.View`       | Animated view with `sharedBoundTag`    |
-| `Transition.Pressable`  | Pressable that measures bounds         |
-| `Transition.ScrollView` | ScrollView with gesture coordination   |
-| `Transition.FlatList`   | FlatList with gesture coordination     |
-| `Transition.MaskedView` | For reveal effects (requires native)   |
+| Component                                   | Description                                                                    |
+| ------------------------------------------- | ------------------------------------------------------------------------------ |
+| `Transition.Boundary`                       | Namespace for shared-boundary helpers                                          |
+| `Transition.Boundary.View`                  | Passive boundary wrapper for shared elements                                   |
+| `Transition.Boundary.Pressable`             | Pressable boundary wrapper with press-priority source measurement              |
+| `Transition.createBoundaryComponent`        | Factory for building boundary wrappers around custom components                |
+| `Transition.View`                           | Animated view with `sharedBoundTag` or `styleId`                               |
+| `Transition.Pressable`                      | Pressable wrapper. `sharedBoundTag` usage is legacy and planned for next-major deprecation |
+| `Transition.ScrollView`                     | ScrollView with gesture coordination + scroll-settled signaling                |
+| `Transition.FlatList`                       | FlatList with gesture coordination + scroll-settled signaling                  |
+| `Transition.MaskedView`                     | Deprecated legacy masking wrapper. Prefer `maskEnabled` on screen options      |
 
 ---
 
@@ -669,7 +861,10 @@ screenStyleInterpolator: ({ progress }) => {
   "worklet";
   return {
     "hero-image": {
-      opacity: interpolate(progress, [0, 1], [0, 1]),
+      style: {
+        opacity: interpolate(progress, [0, 1], [0, 1]),
+        transform: [{ scale: interpolate(progress, [0, 1], [0.8, 1]) }],
+      },
     },
   };
 };
@@ -769,9 +964,9 @@ options={{
 
 ---
 
-## Masked View Setup
+## Masked View Setup (`maskEnabled` Recommended)
 
-Required for `SharedIGImage` and `SharedAppleMusic` presets. The masked view creates the "reveal" effect where content expands from the shared element.
+Required for `SharedIGImage`, `SharedAppleMusic` presets, and `bounds().navigation.zoom()` transitions. For new code, prefer `maskEnabled: true` on screen options.
 
 > **Note**: Requires native code. Will not work in Expo Go.
 
@@ -786,72 +981,57 @@ npm install @react-native-masked-view/masked-view
 cd ios && pod install
 ```
 
-### Full Example
+### Recommended Flow (`maskEnabled`)
 
-**1. Source Screen** – Tag pressable elements:
+**1. Source Screen** – use a boundary pressable:
 
 ```tsx
 // app/index.tsx
 import { router } from "expo-router";
-import { View } from "react-native";
 import Transition from "react-native-screen-transitions";
 
 export default function HomeScreen() {
   return (
-    <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
-      <Transition.Pressable
-        sharedBoundTag="album-art"
-        style={{
-          width: 200,
-          height: 200,
-          backgroundColor: "#1DB954",
-          borderRadius: 12,
-        }}
-        onPress={() => {
-          router.push({
-            pathname: "/details",
-            params: { sharedBoundTag: "album-art" },
-          });
-        }}
-      />
-    </View>
+    <Transition.Boundary.Pressable
+      id="album-art"
+      style={{
+        width: 200,
+        height: 200,
+        backgroundColor: "#1DB954",
+        borderRadius: 12,
+      }}
+      onPress={() => router.push("/details")}
+    />
   );
 }
 ```
 
-**2. Destination Screen** – Wrap with MaskedView and match the tag:
+**2. Destination Screen** – render the matching boundary:
 
 ```tsx
 // app/details.tsx
-import { useLocalSearchParams } from "expo-router";
 import Transition from "react-native-screen-transitions";
 
 export default function DetailsScreen() {
-  const { sharedBoundTag } = useLocalSearchParams<{ sharedBoundTag: string }>();
-
   return (
-    <Transition.MaskedView style={{ flex: 1, backgroundColor: "#121212" }}>
-      <Transition.View
-        sharedBoundTag={sharedBoundTag}
-        style={{
-          backgroundColor: "#1DB954",
-          width: 400,
-          height: 400,
-          alignSelf: "center",
-          borderRadius: 12,
-        }}
-      />
-      {/* Additional screen content */}
-    </Transition.MaskedView>
+    <Transition.Boundary.View
+      id="album-art"
+      style={{
+        backgroundColor: "#1DB954",
+        width: 400,
+        height: 400,
+        alignSelf: "center",
+        borderRadius: 12,
+      }}
+    />
   );
 }
 ```
 
-**3. Layout** – Apply the preset with dynamic tag:
+**3. Layout** – enable `maskEnabled` and use `bounds().navigation.zoom()`:
 
 ```tsx
 // app/_layout.tsx
-import Transition from "react-native-screen-transitions";
 import { Stack } from "./stack";
 
 export default function RootLayout() {
@@ -860,23 +1040,36 @@ export default function RootLayout() {
       <Stack.Screen name="index" />
       <Stack.Screen
         name="details"
-        options={({ route }) => ({
-          ...Transition.Presets.SharedAppleMusic({
-            sharedBoundTag: route.params?.sharedBoundTag ?? "",
-          }),
-        })}
+        options={{
+          maskEnabled: true,
+          screenStyleInterpolator: ({ bounds, focused }) => {
+            "worklet";
+            if (!focused) return {};
+            return bounds({ id: "album-art" }).navigation.zoom();
+          },
+        }}
       />
     </Stack>
   );
 }
 ```
 
+### Legacy Fallback (Deprecated): `Transition.MaskedView`
+
+`Transition.MaskedView` remains available for legacy/manual masking flows, but new implementations should use `maskEnabled`.
+
+```tsx
+<Transition.MaskedView style={{ flex: 1 }}>
+  <Transition.View sharedBoundTag="album-art" />
+</Transition.MaskedView>
+```
+
 ### How It Works
 
-1. `Transition.Pressable` measures its bounds on press and stores them with the tag
-2. `Transition.View` on the destination registers as the target for that tag
-3. `Transition.MaskedView` clips content to the animating shared element bounds
-4. The preset interpolates position, size, and mask for a seamless expand/collapse effect
+1. `Transition.Boundary.Pressable` measures and stores source bounds (legacy fallback: `Transition.Pressable` with `sharedBoundTag`, planned for next-major deprecation).
+2. `Transition.Boundary.View` (or `Transition.View`) on the destination registers the matching target.
+3. `maskEnabled: true` pre-mounts the masked wrapper for zoom/reveal transitions (legacy fallback: `Transition.MaskedView`).
+4. The zoom preset interpolates position, size, and mask for a seamless expand/collapse effect.
 
 ---