react-native-nitro-modal 0.1.5 → 0.3.0-rc

package/README.md

@@ -7,17 +7,19 @@
 [![npm version](https://img.shields.io/npm/v/react-native-nitro-modal.svg?style=flat-square)](https://www.npmjs.com/package/react-native-nitro-modal)
 [![npm downloads](https://img.shields.io/npm/dm/react-native-nitro-modal.svg?style=flat-square)](https://www.npmjs.com/package/react-native-nitro-modal)
 [![license](https://img.shields.io/npm/l/react-native-nitro-modal.svg?style=flat-square)](LICENSE)
-![platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20Android-lightgrey.svg?style=flat-square)
+![platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20Android%20%7C%20Web-lightgrey.svg?style=flat-square)
 
 </div>
 
 ---
 
-`react-native-nitro-modal` renders your React content inside native modal presentations — an edge-attached UIKit sheet on iOS and Material `BottomSheetBehavior` on Android — so gestures, detent snapping, keyboard handling and transitions are handled natively, not re-implemented in JavaScript.
+`react-native-nitro-modal` renders your React content inside native modal presentations — an edge-attached UIKit sheet on iOS and Material `BottomSheetBehavior` on Android — so gestures, detent snapping, keyboard handling and transitions are handled natively, not re-implemented in JavaScript. On the web (React Native Web), the same API renders a DOM sheet and popup with matching behavior.
 
 ## Features
 
-- 📄 **Native bottom sheets** with multiple detents (`small`, `medium`, `large`, `fitContent`) and swipe-to-dismiss
+- 📄 **Native bottom sheets** with multiple detents (`small`, `medium`, `large`, `fitContent` or a height) and swipe-to-dismiss
+- 📌 **Inline sheets** — a persistent sheet that is part of your screen, with the views behind it still usable
+- 🔄 **Pull to refresh** — pulling a sheet down past its lowest detent
 - 🪟 **Centered popups** with native `scale` / `fade` transitions
 - 📏 **Content-sized sheets** — `fitContent` measures your React content and grows with it
 - ⌨️ **Keyboard aware** — the sheet or card follows the keyboard animation (`pan` or `resize`)
@@ -35,9 +37,10 @@
 | `react-native-nitro-modules`   | `^0.37.1`                                    |
 | iOS                            | 15.0+ (16.0+ for `small` and `fitContent`)   |
 | Android                        | API 24 (Android 7.0)+                        |
+| Web                            | via `react-native-web` (tested with 0.21)    |
 
 > [!NOTE]
-> Web and other platforms are not supported. On those platforms the component renders nothing and logs a one-time warning.
+> Other platforms (e.g. macOS, Windows) are not supported. There the component renders nothing and logs a one-time warning.
 
 ## Installation
 
@@ -110,6 +113,38 @@ Detents are listed smallest first. `initialDetentIndex` selects where the sheet
 </NitroModal>
 ```
 
+### Inline (persistent) bottom sheet
+
+`presentation="inline"` keeps the sheet inside the component's own frame instead of presenting it over the app — like a sheet that is part of the screen. There is no backdrop, the views behind it stay interactive, it moves with your screen during navigation, and the user can't dismiss it. Position the frame with `style` (it fills its parent by default); the sheet rests against its bottom edge and its largest detent reaches its top edge.
+
+```tsx
+<View style={{ flex: 1 }}>
+  <ScreenContent />
+
+  <NitroModal
+    isOpen
+    presentation="inline"
+    style={{ top: headerHeight }}
+    detents={[320, 'large']}
+    onPullToRefresh={refresh}
+  >
+    <FlatList data={rows} renderItem={renderRow} nestedScrollEnabled />
+  </NitroModal>
+</View>
+```
+
+A number in `detents` is the content height in dp/pt above the bottom safe area.
+
+### Scrolling content and pull to refresh
+
+A sheet hands drags off to the scroll view under the finger:
+
+- Dragging up expands the sheet first, then scrolls the content.
+- Dragging down scrolls the content back to its top. Once the content has scrolled during a drag, that drag never moves the sheet; the next drag collapses it.
+- With `onPullToRefresh` set, a drag that starts with the sheet resting on its lowest detent can pull it further down. Letting go past the threshold calls `onPullToRefresh` (with haptic feedback when it is crossed). This needs a sheet that can't be swiped away: inline, or `dismissOnSwipe={false}`.
+
+On Android, scrollable content takes part through nested scrolling, so set `nestedScrollEnabled` on it.
+
 ### Popup
 
 ```tsx
@@ -167,14 +202,16 @@ const sheet = useRef<NitroModalRef>(null);
 | ------------------------ | ---------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
 | `isOpen`                 | `boolean`                                            | —                  | Controls visibility. Leave undefined to use the [ref API](#nitromodalref) instead.                |
 | `mode`                   | `'bottomSheet' \| 'popup'`                           | `'bottomSheet'`    | How the modal is presented.                                                                       |
-| `detents`                | `SheetDetent[]`                                      | `['fitContent']`   | Sheet heights, smallest first. Android uses at most three.                                        |
+| `presentation`           | `'modal' \| 'inline'`                                | `'modal'`          | `inline` keeps a bottom sheet inside the component's frame, as part of the screen. See [Inline](#inline-persistent-bottom-sheet). |
+| `style`                  | `StyleProp<ViewStyle>`                               | `absoluteFill`     | Inline only: the frame the sheet lives in.                                                        |
+| `detents`                | `SheetDetent[]`                                      | `['fitContent']`   | Sheet heights, smallest first: named sizes or a content height in dp/pt. Android uses at most three. |
 | `initialDetentIndex`     | `number`                                             | `0`                | Index into `detents` the sheet opens at.                                                          |
 | `backdropColor`          | `ColorValue`                                         | `'black'`          | Backdrop color.                                                                                   |
 | `backdropOpacity`        | `number`                                             | `0.4`              | Backdrop opacity, `0`–`1`.                                                                        |
-| `backdropBlur`           | `number`                                             | `0`                | Blur radius (dp/pt) behind the modal. `0` disables it. See [platform notes](#platform-notes).     |
+| `backdropBlur`           | `number`                                             | `0`                | Blur radius (dp/pt/px) behind the modal. `0` disables it. See [platform notes](#platform-notes).  |
 | `dismissOnBackdropPress` | `boolean`                                            | `true`             | Tapping the backdrop closes the modal.                                                            |
 | `dismissOnSwipe`         | `boolean`                                            | `true`             | Swiping down closes a bottom sheet.                                                               |
-| `dismissOnBackButton`    | `boolean`                                            | `true`             | The Android back button/gesture closes the modal.                                                 |
+| `dismissOnBackButton`    | `boolean`                                            | `true`             | The Android back button/gesture (Escape on web) closes the modal.                                 |
 | `showGrabber`            | `boolean`                                            | `false`            | Shows the drag handle on a bottom sheet.                                                          |
 | `cornerRadius`           | `number`                                             | platform default   | Corner radius of the sheet/card.                                                                  |
 | `backgroundColor`        | `ColorValue`                                         | system surface     | Background of the sheet/card.                                                                     |
@@ -192,7 +229,8 @@ const sheet = useRef<NitroModalRef>(null);
 | `onDismiss`         | `(reason: DismissReason) => void`        | The modal is fully gone. Fires exactly once per presentation.                      |
 | `onDetentChange`    | `(index: number) => void`                | A bottom sheet settled on a different detent.                                      |
 | `onBackdropPress`   | `() => void`                             | The backdrop was tapped (fires even when `dismissOnBackdropPress` is `false`).     |
-| `onBackButtonPress` | `() => void`                             | The Android hardware/gesture back was pressed.                                     |
+| `onBackButtonPress` | `() => void`                             | The Android hardware/gesture back (Escape on web) was pressed.                     |
+| `onPullToRefresh`   | `() => void`                             | The sheet was pulled down past its lowest detent and released. See [pull to refresh](#scrolling-content-and-pull-to-refresh). |
 
 ### `NitroModalRef`
 
@@ -207,12 +245,17 @@ const sheet = useRef<NitroModalRef>(null);
 ```ts
 type ModalMode = 'bottomSheet' | 'popup';
 
-type SheetDetent =
+type ModalPresentation = 'modal' | 'inline';
+
+type NamedSheetDetent =
   | 'small'      // ~25% of the available height
   | 'medium'     // ~50% of the available height
   | 'large'      // the full available height
   | 'fitContent'; // the measured height of your content
 
+// A named height, or the content height in dp/pt above the bottom safe area.
+type SheetDetent = NamedSheetDetent | number;
+
 type KeyboardBehavior = 'pan' | 'resize' | 'none';
 
 type PopupAnimation = 'scale' | 'fade' | 'none';
@@ -227,6 +270,8 @@ import type {
   DismissReason,
   KeyboardBehavior,
   ModalMode,
+  ModalPresentation,
+  NamedSheetDetent,
   NitroModalProps,
   NitroModalRef,
   PopupAnimation,
@@ -236,7 +281,7 @@ import type {
 
 ## How it works
 
-`<NitroModal>` mounts a zero-size placeholder in your React tree. When opened, the native side presents a real view controller (iOS) or window (Android) and hosts your React children inside it. Children mount when the modal opens and stay mounted until the native exit animation completes, so content never disappears mid-transition. The native side also reports the exact area available to the content (accounting for rotation, keyboard and sheet size), and the content container is sized accordingly.
+`<NitroModal>` mounts a zero-size placeholder in your React tree. When opened, the native side presents a real view controller (iOS) or window (Android) and hosts your React children inside it. An inline sheet instead lives in a view laid out with `style`, in your screen's own hierarchy: touches that miss the sheet go to the views behind it, and `keyboardBehavior` doesn't apply (the screen's own keyboard handling does). Children mount when the modal opens and stay mounted until the native exit animation completes, so content never disappears mid-transition. The native side also reports the exact area available to the content (accounting for rotation, keyboard and sheet size), and the content container is sized accordingly.
 
 ## Platform notes
 
@@ -253,6 +298,15 @@ import type {
 - Predictive back (Android 14+, when the app opts in or targets SDK 36) previews the exit while the gesture runs: the sheet uses Material's bottom-sheet animation and the popup scales down.
 - Transitions are interruptible: closing during the enter animation turns it around, and reopening during the exit animation brings the same modal back (no extra `onDismiss`/`onPresent`). Once the exit starts, taps and back presses reach the screen below, as with a native dialog.
 
+**Web**
+
+- Renders through React Native Web's `Modal`, so it stacks with your other modals, traps focus while open and returns it on close. Nothing is rendered in place.
+- Bottom sheets can be dragged with touch or mouse, with the same detent snapping, fling-to-dismiss and hand-off to scrollable content as on iOS. A touch that starts on content already scrolled down scrolls it natively instead of moving the sheet.
+- The Escape key acts as the back button: it fires `onBackButtonPress` and, unless `dismissOnBackButton` is `false`, dismisses the topmost modal with reason `'backButton'`. The browser's history back is not intercepted.
+- `backdropBlur` uses CSS `backdrop-filter`. Without `backgroundColor`, the sheet/card uses the CSS `Canvas` system color, which follows your page's `color-scheme`.
+- `keyboardBehavior` follows the on-screen keyboard through the `visualViewport` API (mobile browsers). Safe-area insets are respected when the page uses `viewport-fit=cover`.
+- Sheets are at most 640px wide and centered. Animations are skipped when the user prefers reduced motion.
+
 **Colors**
 
 - `backdropColor` and `backgroundColor` accept any color string or number supported by `processColor`. `PlatformColor` and `DynamicColorIOS` values are not supported yet.
@@ -263,7 +317,7 @@ The repository includes an example app that covers content-sized sheets, multi-d
 
 ```sh
 yarn
-yarn example ios      # or: yarn example android
+yarn example ios      # or: yarn example android / yarn example web
 ```
 
 ## Contributing