react-native-bottom-sheet-stack 1.0.2 → 1.1.0

package/README.md

@@ -1,88 +1,300 @@
-# 🧩 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.
+## Features
 
-## Demo:
-https://x.com/tsolfitsmexx/status/1913103288834089056?s=46&t=kx6uESwbDrRgTUOCDr1tMQ
+- **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
+### Peer Dependencies
 
-### 🧠 Important: Use <BottomSheetManaged /> instead of <BottomSheet />
-
-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/BottomSheet.context.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","require","BottomSheetContext","exports","createContext","undefined","useMaybeBottomSheetContext","context","useContext"],"sourceRoot":"../../src","sources":["BottomSheet.context.ts"],"mappings":";;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAMO,MAAMC,kBAAkB,GAAAC,OAAA,CAAAD,kBAAA,gBAAG,IAAAE,oBAAa,EAE7CC,SAAS,CAAC;AAEL,SAASC,0BAA0BA,CAAA,EAAG;EAC3C,MAAMC,OAAO,GAAG,IAAAC,iBAAU,EAACN,kBAAkB,CAAC;EAE9C,OAAOK,OAAO;AAChB","ignoreList":[]}
+{"version":3,"names":["_react","require","BottomSheetContext","exports","createContext","undefined","useMaybeBottomSheetContext","context","useContext"],"sourceRoot":"../../src","sources":["BottomSheet.context.ts"],"mappings":";;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAMO,MAAMC,kBAAkB,GAAAC,OAAA,CAAAD,kBAAA,gBAAG,IAAAE,oBAAa,EAE7CC,SAAS,CAAC;AAEL,SAAAC,2BAAA;EACL,MAAAC,OAAA,GAAgB,IAAAC,iBAAU,EAACN,kBAAkB,CAAC;EAAC,OAExCK,OAAO;AAAA","ignoreList":[]}

package/lib/commonjs/BottomSheetBackdrop.js

@@ -0,0 +1,76 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.BottomSheetBackdrop = BottomSheetBackdrop;
+var _compilerRuntime = require("react/compiler-runtime");
+var _reactNative = require("react-native");
+var _reactNativeReanimated = _interopRequireWildcard(require("react-native-reanimated"));
+var _animatedRegistry = require("./animatedRegistry");
+var _bottomSheet = require("./bottomSheet.store");
+var _jsxRuntime = require("react/jsx-runtime");
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+const AnimatedPressable = _reactNativeReanimated.default.createAnimatedComponent(_reactNative.Pressable);
+
+/**
+ * Custom backdrop component rendered separately from the scaled sheet content.
+ * This ensures the backdrop doesn't scale with the sheet.
+ * Opacity is interpolated from the bottom sheet's animatedIndex for smooth animation.
+ */
+function BottomSheetBackdrop(t0) {
+  const $ = (0, _compilerRuntime.c)(8);
+  const {
+    sheetId,
+    onPress
+  } = t0;
+  let t1;
+  if ($[0] !== sheetId) {
+    t1 = state => state.sheetsById[sheetId]?.status;
+    $[0] = sheetId;
+    $[1] = t1;
+  } else {
+    t1 = $[1];
+  }
+  const status = (0, _bottomSheet.useBottomSheetStore)(t1);
+  const animatedIndex = (0, _animatedRegistry.getAnimatedIndex)(sheetId);
+  const isVisible = status === "opening" || status === "open";
+  const animatedStyle = (0, _reactNativeReanimated.useAnimatedStyle)(() => {
+    const opacity = (0, _reactNativeReanimated.interpolate)(animatedIndex.value, [-1, 0], [0, 1], _reactNativeReanimated.Extrapolation.CLAMP);
+    return {
+      opacity
+    };
+  });
+  let t2;
+  if ($[2] !== animatedStyle) {
+    t2 = [styles.backdrop, animatedStyle];
+    $[2] = animatedStyle;
+    $[3] = t2;
+  } else {
+    t2 = $[3];
+  }
+  const t3 = isVisible ? "auto" : "none";
+  let t4;
+  if ($[4] !== onPress || $[5] !== t2 || $[6] !== t3) {
+    t4 = /*#__PURE__*/(0, _jsxRuntime.jsx)(AnimatedPressable, {
+      style: t2,
+      onPress: onPress,
+      pointerEvents: t3
+    });
+    $[4] = onPress;
+    $[5] = t2;
+    $[6] = t3;
+    $[7] = t4;
+  } else {
+    t4 = $[7];
+  }
+  return t4;
+}
+const styles = _reactNative.StyleSheet.create({
+  backdrop: {
+    ..._reactNative.StyleSheet.absoluteFillObject,
+    backgroundColor: 'rgba(0, 0, 0, 0.5)'
+  }
+});
+//# sourceMappingURL=BottomSheetBackdrop.js.map

package/lib/commonjs/BottomSheetBackdrop.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_reactNative","require","_reactNativeReanimated","_interopRequireWildcard","_animatedRegistry","_bottomSheet","_jsxRuntime","_getRequireWildcardCache","e","WeakMap","r","t","__esModule","default","has","get","n","__proto__","a","Object","defineProperty","getOwnPropertyDescriptor","u","hasOwnProperty","call","i","set","AnimatedPressable","Animated","createAnimatedComponent","Pressable","BottomSheetBackdrop","t0","$","_compilerRuntime","c","sheetId","onPress","t1","state","sheetsById","status","useBottomSheetStore","animatedIndex","getAnimatedIndex","isVisible","animatedStyle","useAnimatedStyle","opacity","interpolate","value","Extrapolation","CLAMP","t2","styles","backdrop","t3","t4","jsx","style","pointerEvents","StyleSheet","create","absoluteFillObject","backgroundColor"],"sourceRoot":"../../src","sources":["BottomSheetBackdrop.tsx"],"mappings":"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","ignoreList":[]}