react-native-bottom-sheet-stack 1.0.3 → 1.3.0

package/README.md

@@ -1,88 +1,302 @@
-# 🧩 BottomSheet Stack Manager
+# react-native-bottom-sheet-stack
 
-Manage a stack of [@gorhom/bottom-sheet](https://github.com/gorhom/react-native-bottom-sheet) components with `push`, `switch`, and `replace` navigation — without unmounting underlying sheets.
+A stack manager for [@gorhom/bottom-sheet](https://github.com/gorhom/react-native-bottom-sheet) with `push`, `switch`, and `replace` navigation modes, iOS-style scale animations, and React context preservation.
 
-> ⚠️ **Important:** Not Production Ready
-> This library is currently in active development and is not yet considered production-ready.
+**[Documentation](https://arekkubaczkowski.github.io/react-native-bottom-sheet-stack/)**
 
-## Demo:
-https://x.com/tsolfitsmexx/status/1913103288834089056?s=46&t=kx6uESwbDrRgTUOCDr1tMQ
+## Features
 
----
+- **Stack Navigation** — `push`, `switch`, and `replace` modes for managing multiple sheets
+- **Scale Animation** — iOS-style background scaling effect when sheets are stacked
+- **Context Preservation** — Portal-based API that preserves React context in bottom sheets
+- **Underlying Sheets Stay Mounted** — Sheets remain in the stack until explicitly closed
+- **Group Support** — Isolated stacks for different parts of your app
 
-## 🚀 Features
-
-- 🧱 `push` — stack a new sheet above the current one
-- 🔄 `switch` — override current sheet temporarily, restore the previous one when closing
-- 🔁 `replace` — fully swap and remove the current sheet
-- 🧠 Underlying sheets remain mounted
-- 🗂️ Group support for isolated stacks
-
----
-
-## 📦 Installation
+## Installation
 
 ```bash
-yarn add zustand @gorhom/bottom-sheet
+yarn add react-native-bottom-sheet-stack
 ```
 
-## Usage
-
-### 🧠 Important: Use <BottomSheetManaged /> instead of <BottomSheet />
+### Peer Dependencies
 
-To make the stack manager work, you must replace all instances of BottomSheet from @gorhom/bottom-sheet with the provided:
-
-```tsx
-import { BottomSheetManaged } from 'react-native-bottom-sheet-stack';
+```bash
+yarn add @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-teleport zustand
 ```
 
-In your app entry:
+## Quick Start
+
+### 1. Setup Provider and Host
 
 ```tsx
 import {
+  BottomSheetManagerProvider,
   BottomSheetHost,
-  BottomSheetManager,
-  initBottomSheetCoordinator,
+  BottomSheetScaleView,
 } from 'react-native-bottom-sheet-stack';
-
-initBottomSheetCoordinator();
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
 
 export default function App() {
   return (
-    <BottomSheetManager id="default">
-      <BottomSheetHost />
-      {/* your app content */}
-    </BottomSheetManager>
+    <SafeAreaProvider>
+      <GestureHandlerRootView style={{ flex: 1 }}>
+        <BottomSheetManagerProvider id="default">
+          <BottomSheetScaleView>
+            <YourAppContent />
+          </BottomSheetScaleView>
+          <BottomSheetHost />
+        </BottomSheetManagerProvider>
+      </GestureHandlerRootView>
+    </SafeAreaProvider>
   );
 }
 ```
 
-In a component:
+### 2. Create a Bottom Sheet Component
+
+Use `BottomSheetManaged` instead of `BottomSheet` from `@gorhom/bottom-sheet`:
 
 ```tsx
-import { useBottomSheetManager } from 'react-native-bottom-sheet-stack';
+import { forwardRef } from 'react';
+import { View, Text } from 'react-native';
+import { BottomSheetView } from '@gorhom/bottom-sheet';
+import { BottomSheetManaged, useBottomSheetState } from 'react-native-bottom-sheet-stack';
 
-export default function YouComponent() {
-  const { openBottomSheet } = useBottomSheetManager();
+const MySheet = forwardRef((props, ref) => {
+  const { close } = useBottomSheetState();
 
   return (
-    <TouchableOpacity onPress={() => openBottomSheet(<YourBottomSheet />, { mode: 'switch' })}>
-      <Text>Open Bottom Sheet</Text>
-    </TouchableOpacity>
+    <BottomSheetManaged ref={ref} snapPoints={['50%']}>
+      <BottomSheetView>
+        <View style={{ padding: 20 }}>
+          <Text>Hello from Bottom Sheet!</Text>
+          <Button title="Close" onPress={close} />
+        </View>
+      </BottomSheetView>
+    </BottomSheetManaged>
   );
+});
+```
+
+### 3. Open Bottom Sheets
+
+```tsx
+import { useBottomSheetManager } from 'react-native-bottom-sheet-stack';
+
+function MyComponent() {
+  const { openBottomSheet } = useBottomSheetManager();
+
+  const handleOpen = () => {
+    openBottomSheet(<MySheet />, {
+      mode: 'push', // 'push' | 'switch' | 'replace'
+      scaleBackground: true,
+    });
+  };
+
+  return <Button title="Open Sheet" onPress={handleOpen} />;
 }
 ```
 
-Define your bottom sheet:
+## Navigation Modes
+
+| Mode | Description |
+|------|-------------|
+| `push` | Stack a new sheet on top. Previous sheet remains visible underneath. |
+| `switch` | Hide current sheet and show new one. Previous sheet is restored when new one closes. |
+| `replace` | Close current sheet and open new one. Previous sheet is removed from stack. |
+
+## Scale Animation
+
+Wrap your app content in `BottomSheetScaleView` to enable iOS-style scaling:
+
+```tsx
+<BottomSheetManagerProvider
+  id="default"
+  scaleConfig={{ scale: 0.92, translateY: 0, borderRadius: 24 }}
+>
+  <BottomSheetScaleView>
+    <YourAppContent />
+  </BottomSheetScaleView>
+  <BottomSheetHost />
+</BottomSheetManagerProvider>
+```
+
+> **Important:** `BottomSheetHost` must be **outside** of `BottomSheetScaleView`. If you wrap `BottomSheetHost` inside `BottomSheetScaleView`, the bottom sheets themselves will also scale, which is not the desired behavior.
+
+Open sheets with `scaleBackground: true`:
 
 ```tsx
-import { BottomSheetManaged } from 'react-native-bottom-sheet-stack';
+openBottomSheet(<MySheet />, { scaleBackground: true });
+```
+
+## Context Preservation (Portal API)
+
+The imperative `openBottomSheet()` API stores content in a Zustand store and renders it in `BottomSheetHost`. This means **React context from your component tree is lost**.
+
+For cases where you need context (themes, auth, i18n, etc.), use the **portal-based API**:
+
+```tsx
+import {
+  BottomSheetPortal,
+  useBottomSheetControl,
+} from 'react-native-bottom-sheet-stack';
+
+function MyComponent() {
+  const { open, close, isOpen } = useBottomSheetControl('my-sheet');
 
-export default function YourBottomSheet() {
   return (
-    <BottomSheetManaged snapPoints={['50%']}>
-      {/* Sheet content */}
-    </BottomSheetManaged>
+    <View>
+      {/* Declare the portal - content is rendered here in your React tree */}
+      <BottomSheetPortal id="my-sheet">
+        <MySheet />
+      </BottomSheetPortal>
+
+      {/* Control it imperatively */}
+      <Button title="Open" onPress={() => open({ scaleBackground: true })} />
+    </View>
   );
 }
-```
+```
+
+### How It Works
+
+| API | Context | Use Case |
+|-----|---------|----------|
+| `openBottomSheet()` | Lost | Dynamic sheets, simple cases |
+| `BottomSheetPortal` | Preserved | Sheets needing theme, auth, i18n, etc. |
+
+The portal API uses [react-native-teleport](https://github.com/nicklockwood/react-native-teleport) to render content in your component tree while displaying it in `BottomSheetHost`.
+
+### Type-Safe Portal IDs
+
+You can get autocomplete and type checking for portal sheet IDs by augmenting the `BottomSheetPortalRegistry` interface.
+
+**Step 1:** Create a type declaration file in your project (e.g., `src/types/bottom-sheet.d.ts`):
+
+```tsx
+import 'react-native-bottom-sheet-stack';
+
+declare module 'react-native-bottom-sheet-stack' {
+  interface BottomSheetPortalRegistry {
+    'settings-sheet': true;
+    'profile-sheet': true;
+    'confirm-dialog': true;
+  }
+}
+```
+
+**Step 2:** Make sure the file is included in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": [
+    "src/**/*",
+    "src/types/**/*.d.ts"  // include your declaration files
+  ]
+}
+```
+
+**Step 3:** Now TypeScript will autocomplete and validate the `id` prop:
+
+```tsx
+// ✅ Valid - 'settings-sheet' is in registry
+<BottomSheetPortal id="settings-sheet">
+const control = useBottomSheetControl('settings-sheet');
+
+// ❌ Error - 'unknown-sheet' is not in registry
+<BottomSheetPortal id="unknown-sheet">
+const control = useBottomSheetControl('unknown-sheet');
+```
+
+If you don't augment the registry, the `id` accepts any `string` for flexibility.
+
+## API Reference
+
+### Components
+
+#### `BottomSheetManagerProvider`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `string` | Unique identifier for this stack group |
+| `scaleConfig` | `ScaleConfig` | Optional scale animation configuration |
+
+#### `BottomSheetHost`
+
+Renders the bottom sheet stack. Place after your app content inside `BottomSheetManagerProvider`.
+
+#### `BottomSheetScaleView`
+
+Wrapper that applies scale animation to its children when sheets are opened with `scaleBackground: true`.
+
+#### `BottomSheetManaged`
+
+Drop-in replacement for `BottomSheet` from `@gorhom/bottom-sheet`. Accepts all the same props.
+
+#### `BottomSheetPortal`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `BottomSheetPortalId` | Unique identifier for this portal sheet (type-safe if registry is augmented) |
+| `children` | `ReactElement` | The bottom sheet component to render |
+
+### Hooks
+
+#### `useBottomSheetManager()`
+
+```tsx
+const {
+  openBottomSheet,  // (content, options?) => id
+  close,            // (id) => void
+  clearAll,         // () => void
+} = useBottomSheetManager();
+```
+
+#### `useBottomSheetState()`
+
+Use inside a bottom sheet component:
+
+```tsx
+const {
+  bottomSheetState,  // { id, status, groupId, ... }
+  close,             // () => void
+} = useBottomSheetState();
+```
+
+#### `useBottomSheetControl(id: BottomSheetPortalId)`
+
+Control portal-based sheets:
+
+```tsx
+const {
+  open,    // (options?) => void
+  close,   // () => void
+  isOpen,  // boolean
+  status,  // 'opening' | 'open' | 'closing' | 'hidden' | null
+} = useBottomSheetControl('my-sheet');
+```
+
+### Types
+
+#### `BottomSheetPortalRegistry`
+
+Interface to augment for type-safe portal IDs. See [Type-Safe Portal IDs](#type-safe-portal-ids).
+
+#### `BottomSheetPortalId`
+
+Type for portal sheet IDs. If `BottomSheetPortalRegistry` is augmented, this is a union of registered keys. Otherwise, it's `string`.
+
+## Example
+
+See the [example app](./example) for a full demo including:
+- Navigation flow (push, switch, replace)
+- Nested scale animations
+- Context preservation comparison
+
+## License
+
+MIT

package/lib/commonjs/BottomSheetHost.js

@@ -9,6 +9,7 @@ var _react = require("react");
 var _reactNative = require("react-native");
 var _reactNativeReanimated = _interopRequireDefault(require("react-native-reanimated"));
 var _reactNativeSafeAreaContext = require("react-native-safe-area-context");
+var _reactNativeTeleport = require("react-native-teleport");
 var _shallow = require("zustand/shallow");
 var _animatedRegistry = require("./animatedRegistry");
 var _BottomSheetBackdrop = require("./BottomSheetBackdrop");
@@ -19,6 +20,65 @@ var _bottomSheetCoordinator = require("./bottomSheetCoordinator");
 var _useScaleAnimation = require("./useScaleAnimation");
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function PortalHostWrapper(t0) {
+  const $ = (0, _compilerRuntime.c)(12);
+  const {
+    id,
+    width,
+    height
+  } = t0;
+  let t1;
+  if ($[0] !== height || $[1] !== width) {
+    t1 = {
+      flex: 1,
+      width,
+      height
+    };
+    $[0] = height;
+    $[1] = width;
+    $[2] = t1;
+  } else {
+    t1 = $[2];
+  }
+  const t2 = `bottomsheet-${id}`;
+  let t3;
+  if ($[3] !== height || $[4] !== width) {
+    t3 = {
+      width,
+      height
+    };
+    $[3] = height;
+    $[4] = width;
+    $[5] = t3;
+  } else {
+    t3 = $[5];
+  }
+  let t4;
+  if ($[6] !== t2 || $[7] !== t3) {
+    t4 = /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeTeleport.PortalHost, {
+      name: t2,
+      style: t3
+    });
+    $[6] = t2;
+    $[7] = t3;
+    $[8] = t4;
+  } else {
+    t4 = $[8];
+  }
+  let t5;
+  if ($[9] !== t1 || $[10] !== t4) {
+    t5 = /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      style: t1,
+      children: t4
+    });
+    $[9] = t1;
+    $[10] = t4;
+    $[11] = t5;
+  } else {
+    t5 = $[11];
+  }
+  return t5;
+}
 function BottomSheetHostComp() {
   const $ = (0, _compilerRuntime.c)(15);
   const queueIds = useQueueIds();
@@ -64,10 +124,11 @@ function BottomSheetHostComp() {
   if ($[6] !== groupId || $[7] !== queueIds || $[8] !== scaleConfig) {
     let t5;
     if ($[10] !== groupId || $[11] !== scaleConfig) {
-      t5 = id => /*#__PURE__*/(0, _jsxRuntime.jsx)(QueueItem, {
+      t5 = (id, index) => /*#__PURE__*/(0, _jsxRuntime.jsx)(QueueItem, {
         id: id,
         groupId: groupId,
-        scaleConfig: scaleConfig
+        scaleConfig: scaleConfig,
+        stackIndex: index
       }, id);
       $[10] = groupId;
       $[11] = scaleConfig;
@@ -99,21 +160,22 @@ function _temp(store) {
   return store.clearAll;
 }
 function QueueItem(t0) {
-  const $ = (0, _compilerRuntime.c)(23);
+  const $ = (0, _compilerRuntime.c)(34);
   const {
     id,
     groupId,
-    scaleConfig
+    scaleConfig,
+    stackIndex
   } = t0;
   let t1;
   if ($[0] !== id) {
-    t1 = state => state.sheetsById[id]?.content;
+    t1 = state => state.sheetsById[id];
     $[0] = id;
     $[1] = t1;
   } else {
     t1 = $[1];
   }
-  const content = (0, _bottomSheet.useBottomSheetStore)(t1);
+  const sheet = (0, _bottomSheet.useBottomSheetStore)(t1);
   const {
     width,
     height
@@ -146,73 +208,105 @@ function QueueItem(t0) {
     t4 = $[6];
   }
   (0, _react.useEffect)(t3, t4);
+  const backdropZIndex = stackIndex * 2;
+  const contentZIndex = stackIndex * 2 + 1;
   let t5;
-  if ($[7] === Symbol.for("react.memo_cache_sentinel")) {
-    t5 = [_reactNative.StyleSheet.absoluteFillObject, styles.backdropContainer];
-    $[7] = t5;
+  if ($[7] !== backdropZIndex) {
+    t5 = [_reactNative.StyleSheet.absoluteFillObject, {
+      zIndex: backdropZIndex
+    }];
+    $[7] = backdropZIndex;
+    $[8] = t5;
   } else {
-    t5 = $[7];
+    t5 = $[8];
   }
   let t6;
-  if ($[8] !== id) {
-    t6 = /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-      style: t5,
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_BottomSheetBackdrop.BottomSheetBackdrop, {
-        sheetId: id
-      })
+  if ($[9] !== id) {
+    t6 = /*#__PURE__*/(0, _jsxRuntime.jsx)(_BottomSheetBackdrop.BottomSheetBackdrop, {
+      sheetId: id
     });
-    $[8] = id;
-    $[9] = t6;
+    $[9] = id;
+    $[10] = t6;
   } else {
-    t6 = $[9];
+    t6 = $[10];
   }
   let t7;
-  if ($[10] !== height || $[11] !== width) {
-    t7 = {
-      width,
-      height
-    };
-    $[10] = height;
-    $[11] = width;
-    $[12] = t7;
+  if ($[11] !== t5 || $[12] !== t6) {
+    t7 = /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      style: t5,
+      children: t6
+    });
+    $[11] = t5;
+    $[12] = t6;
+    $[13] = t7;
   } else {
-    t7 = $[12];
+    t7 = $[13];
   }
   let t8;
-  if ($[13] !== scaleStyle || $[14] !== t7) {
-    t8 = [_reactNative.StyleSheet.absoluteFillObject, styles.container, t7, scaleStyle];
-    $[13] = scaleStyle;
-    $[14] = t7;
-    $[15] = t8;
+  if ($[14] !== contentZIndex || $[15] !== height || $[16] !== width) {
+    t8 = {
+      width,
+      height,
+      zIndex: contentZIndex
+    };
+    $[14] = contentZIndex;
+    $[15] = height;
+    $[16] = width;
+    $[17] = t8;
   } else {
-    t8 = $[15];
+    t8 = $[17];
   }
   let t9;
-  if ($[16] !== content || $[17] !== t8) {
-    t9 = /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeReanimated.default.View, {
-      style: t8,
-      children: content
-    });
-    $[16] = content;
-    $[17] = t8;
-    $[18] = t9;
+  if ($[18] !== scaleStyle || $[19] !== t8) {
+    t9 = [_reactNative.StyleSheet.absoluteFillObject, styles.container, t8, scaleStyle];
+    $[18] = scaleStyle;
+    $[19] = t8;
+    $[20] = t9;
   } else {
-    t9 = $[18];
+    t9 = $[20];
   }
   let t10;
-  if ($[19] !== t6 || $[20] !== t9 || $[21] !== value) {
-    t10 = /*#__PURE__*/(0, _jsxRuntime.jsxs)(_BottomSheet.BottomSheetContext.Provider, {
+  if ($[21] !== height || $[22] !== id || $[23] !== sheet?.content || $[24] !== sheet?.usePortal || $[25] !== width) {
+    t10 = sheet?.usePortal ? /*#__PURE__*/(0, _jsxRuntime.jsx)(PortalHostWrapper, {
+      id: id,
+      width: width,
+      height: height
+    }) : sheet?.content;
+    $[21] = height;
+    $[22] = id;
+    $[23] = sheet?.content;
+    $[24] = sheet?.usePortal;
+    $[25] = width;
+    $[26] = t10;
+  } else {
+    t10 = $[26];
+  }
+  let t11;
+  if ($[27] !== t10 || $[28] !== t9) {
+    t11 = /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeReanimated.default.View, {
+      style: t9,
+      children: t10
+    });
+    $[27] = t10;
+    $[28] = t9;
+    $[29] = t11;
+  } else {
+    t11 = $[29];
+  }
+  let t12;
+  if ($[30] !== t11 || $[31] !== t7 || $[32] !== value) {
+    t12 = /*#__PURE__*/(0, _jsxRuntime.jsxs)(_BottomSheet.BottomSheetContext.Provider, {
       value: value,
-      children: [t6, t9]
+      children: [t7, t11]
     });
-    $[19] = t6;
-    $[20] = t9;
-    $[21] = value;
-    $[22] = t10;
+    $[30] = t11;
+    $[31] = t7;
+    $[32] = value;
+    $[33] = t12;
   } else {
-    t10 = $[22];
+    t12 = $[33];
   }
-  return t10;
+  return t12;
 }
 const useQueueIds = () => {
   const $ = (0, _compilerRuntime.c)(2);
@@ -231,11 +325,7 @@ const useQueueIds = () => {
 };
 const BottomSheetHost = exports.BottomSheetHost = BottomSheetHostComp;
 const styles = _reactNative.StyleSheet.create({
-  backdropContainer: {
-    zIndex: 99_999_999
-  },
   container: {
-    zIndex: 100_000_000,
     pointerEvents: 'box-none'
   }
 });