@shaquillehinds/react-native-bottom-sheet 0.0.6 → 0.0.7

package/README.md

@@ -1,30 +1,31 @@
 # @shaquillehinds/react-native-bottom-sheet
 
-A performant, highly customizable bottom sheet component for React Native that just works. Built with React Native Reanimated and Gesture Handler for smooth 60fps animations and natural gesture interactions.
-
-[![npm version](https://badge.fury.io/js/@shaquillehinds%2Freact-native-bottom-sheet.svg)](https://badge.fury.io/js/@shaquillehinds%2Freact-native-bottom-sheet)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/shaquillehinds/react-native-bottom-sheet/master/assets/bottomsheet.gif" alt="example" height="500"/>
-  <img src="https://raw.githubusercontent.com/shaquillehinds/react-native-bottom-sheet/master/assets/bottomsheet2.gif" alt="example2" height="500"/>
-</p>
-
-## Features
-
-- 🎯 **Multiple Snap Points** - Define custom snap positions as percentages of screen height
-- 📱 **Keyboard Aware** - Intelligent keyboard avoidance with per-input customization
-- 🎨 **Fully Customizable** - Style every aspect from bumper to backdrop
-- 🔄 **Portal System** - Renders at app root level above navigation with `BottomSheetPortalProvider`
-- 🎪 **Advanced Portal APIs** - Manual portal control with `useBottomSheetPortal` and `useBottomSheetPortalComponent`
-- 📜 **Scrollable Content** - Built-in FlatList and ScrollView components with proper gesture handlin
-- ⚡ **High Performance** - Optimized animations using `useImperativeHandle` for render isolation
-- 🎭 **Modal & Inline Modes** - Use as a full modal or inline component
-- 🔒 **Type Safe** - Full TypeScript support with comprehensive type definitions
-- 🌐 **Cross Platform** - iOS and Android support with platform-specific optimizations
-- 🎬 **Flexible Drag Areas** - Configure draggable regions (full, bumper, or none)
-- 💾 **Keep Mounted Option** - Persist component state with partial visibility
-- ⏱️ **Content Loading Strategies** - Delay content rendering for improved performance
+A performant, highly customizable bottom sheet for React Native. Built on
+Reanimated and Gesture Handler, with render isolation baked into the mounting
+model so closed sheets cost nothing.
+
+---
+
+## Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+- [Quick start](#quick-start)
+- [The content component pattern](#the-content-component-pattern)
+- [Components](#components)
+- [Controlling the sheet](#controlling-the-sheet)
+- [Snap points](#snap-points)
+- [Scrollable content](#scrollable-content)
+- [Keyboard handling](#keyboard-handling)
+- [Persistent sheets](#persistent-sheets)
+- [Appearance](#appearance)
+- [Portal system](#portal-system)
+- [API reference](#api-reference)
+- [Recipes](#recipes)
+- [Troubleshooting](#troubleshooting)
+- [AI agent rules](#ai-agent-rules)
+
+---
 
 ## Installation
 
@@ -32,23 +33,31 @@ A performant, highly customizable bottom sheet component for React Native that j
 npm install @shaquillehinds/react-native-bottom-sheet
 ```
 
-or
+Peer dependencies:
 
 ```bash
-yarn add @shaquillehinds/react-native-bottom-sheet
+npm install react-native-reanimated react-native-gesture-handler @shaquillehinds/react-native-essentials
 ```
 
-### Peer Dependencies
+| Package                                   | Version |
+| ----------------------------------------- | ------- |
+| `react-native-reanimated`                 | ^3.0.0  |
+| `react-native-gesture-handler`            | ^2.0.0  |
+| `@shaquillehinds/react-native-essentials` | ^1.8.0  |
 
-This package requires the following peer dependencies:
+Reanimated's Babel plugin must be last in your plugin list:
 
-```bash
-npm install react-native-reanimated react-native-gesture-handler @shaquillehinds/react-native-essentials
+```js
+// babel.config.js
+module.exports = {
+  presets: ['module:metro-react-native-babel-preset'],
+  plugins: ['react-native-reanimated/plugin'],
+};
 ```
 
-### Setup
+## Setup
 
-Wrap your app with `BottomSheetPortalProvider` at the root level:
+Wrap your app root — **above** the navigation container:
 
 ```tsx
 import { BottomSheetPortalProvider } from '@shaquillehinds/react-native-bottom-sheet';
@@ -56,333 +65,335 @@ import { BottomSheetPortalProvider } from '@shaquillehinds/react-native-bottom-s
 export default function App() {
   return (
     <BottomSheetPortalProvider>
-      {/* Your app content */}
+      <NavigationContainer>
+        <RootNavigator />
+      </NavigationContainer>
     </BottomSheetPortalProvider>
   );
 }
 ```
 
-This provider enables bottom sheets to render at the top level of your app, above all other content including navigation.
-
-## Quick Start
-
-First, wrap your app with the portal provider:
-
-```tsx
-// App.tsx
-import { BottomSheetPortalProvider } from '@shaquillehinds/react-native-bottom-sheet';
+Sheets render into this portal by default, which is what puts them above
+navigation, tab bars and headers.
 
-export default function App() {
-  return (
-    <BottomSheetPortalProvider>
-      <YourApp />
-    </BottomSheetPortalProvider>
-  );
-}
-```
+---
 
-### Basic Modal Bottom Sheet
+## Quick start
 
 ```tsx
-import React, { useRef, useState } from 'react';
+import { useState } from 'react';
 import { View, Text, Button } from 'react-native';
-import {
-  BottomSheetModal,
-  useBottomSheetRef,
-} from '@shaquillehinds/react-native-bottom-sheet';
-import type { BottomModalRefObject } from '@shaquillehinds/react-native-bottom-sheet';
+import { BottomSheetModal } from '@shaquillehinds/react-native-bottom-sheet';
 
-export default function MyScreen() {
+export default function Screen() {
   const [showModal, setShowModal] = useState(false);
-  const bottomSheetRef = useRef<BottomModalRefObject>(null);
 
   return (
-    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
-      <Button title="Open Bottom Sheet" onPress={() => setShowModal(true)} />
+    <View style={{ flex: 1 }}>
+      <Button title="Open" onPress={() => setShowModal(true)} />
 
       <BottomSheetModal
-        ref={bottomSheetRef}
         showModal={showModal}
         setShowModal={setShowModal}
-        snapPoints={[50, 75, 90]}
+        snapPoints={[50, 90]}
       >
-        <View style={{ padding: 20 }}>
-          <Text>Bottom Sheet Content</Text>
-        </View>
+        <SheetContent onDone={() => setShowModal(false)} />
       </BottomSheetModal>
     </View>
   );
 }
 ```
 
-### Inline Bottom Sheet
+Note the children are a component, not inline JSX. That is the pattern the whole
+library is built around — the next section explains why.
 
-```tsx
-import { BottomSheet } from '@shaquillehinds/react-native-bottom-sheet';
+---
 
-<BottomSheet
-  showModal={showModal}
-  setShowModal={setShowModal}
-  snapPoints={[30, 60, 90]}
-  keepMounted={true}
-  bottomOffset={50}
->
-  <YourContent />
-</BottomSheet>;
-```
+## The content component pattern
 
-## Core Components
+### The idea
 
-### `BottomSheetModal`
+A closed sheet has its entire subtree unmounted. Anything you put in a **child
+component** therefore does no work until the sheet opens: no state initialises, no
+effects run, no queries fire, no lists build. Anything you put in the **wrapper's
+function body** runs on every render of the screen that owns it, open or closed.
 
-Full-screen modal with backdrop. Ideal for most use cases.
+So: the wrapper is a shell. All state lives one level down.
 
-### `BottomSheet`
+```tsx
+export default function ChooseFlashcards(props: ChooseFlashcardsProps) {
+  const { colors, mode } = useTheme();
 
-Inline bottom sheet without backdrop. Useful for persistent UI elements.
+  return (
+    <SmoothBottomModal
+      showModal={props.toggled}
+      setShowModal={props.setToggled}
+      backgroundColor={colors.background[mode]}
+      showContentDelay={{ timeInMilliSecs: 250, type: 'mount' }}
+      snapPoints={[90]}
+    >
+      <ChooseFlashcardsContent {...props} />
+    </SmoothBottomModal>
+  );
+}
 
-### `BottomSheetFlatlist`
+function ChooseFlashcardsContent(props: ChooseFlashcardsProps) {
+  const { relativeY, orientation } = useDeviceOrientation();
+  const t = useTranslation();
+  // ...everything else
+}
+```
 
-Optimized FlatList with proper gesture handling inside bottom sheets.
+Compare with the version that looks equivalent and is not:
 
-### `BottomSheetScrollView`
+```tsx
+export default function ChooseFlashcards(props: ChooseFlashcardsProps) {
+  // These run whenever the parent screen renders, with the sheet closed.
+  const { data, isLoading } = useFlashcardSets(props.studySetId);
+  const [selected, setSelected] = useState<FlashcardSet[]>([]);
+  const rows = useMemo(() => buildRows(data), [data]);
 
-Optimized ScrollView with proper gesture handling inside bottom sheets.
+  return (
+    <SmoothBottomModal
+      showModal={props.toggled}
+      setShowModal={props.setToggled}
+    >
+      {rows.map((r) => (
+        <Row key={r.id} {...r} />
+      ))}
+    </SmoothBottomModal>
+  );
+}
+```
 
-## Portal System
+Every screen that renders a closed sheet pays for that hook stack. Across a dozen
+sheets on a busy screen it is the difference between an instant navigation and a
+visible stall.
 
-The portal system allows bottom sheets to render at the root level of your app, ensuring they appear above all content including navigation stacks.
+### Why it works
 
-### `BottomSheetPortalProvider`
+`BottomSheetModal` passes its subtree through a `ComponentMounter` keyed on
+`showModal`. While `showModal` is false, that subtree is not mounted. Constructing
+the element `<ChooseFlashcardsContent {...props} />` is cheap — it is a plain
+object. _Calling_ the component is the expensive part, and React only does that on
+mount.
 
-**Required**: Wrap your app root with this provider to enable portal functionality.
+Hooks written directly in the wrapper are part of the parent's render, outside
+the mounter, so they are unconditional.
 
-```tsx
-import { BottomSheetPortalProvider } from '@shaquillehinds/react-native-bottom-sheet';
+### Pairing with `showContentDelay`
 
-export default function App() {
-  return (
-    <BottomSheetPortalProvider>
-      <Navigation />
-    </BottomSheetPortalProvider>
-  );
-}
+The pattern removes work while closed. `showContentDelay` moves the remaining work
+out of the opening animation:
+
+```tsx
+showContentDelay={{ type: 'mount', timeInMilliSecs: 250 }}
 ```
 
-**Props:**
+The sheet animates open first, then mounts content behind a short fade. The user
+sees a 60fps open instead of a stutter.
+
+`type: 'mount'` means there is no content to measure when the sheet opens, so it
+must be told its height. Either set `snapPoints` (preferred) or give
+`contentContainerStyle` a `minHeight`. Without one, the sheet opens collapsed.
 
-| Prop                  | Type     | Default | Description                                                        |
-| --------------------- | -------- | ------- | ------------------------------------------------------------------ |
-| `unMountBufferTimeMS` | `number` | `100`   | Delay before removing portal items (prevents premature unmounting) |
-| `updateBufferTimeMS`  | `number` | -       | Throttle time for portal updates (prevents infinite update loops)  |
+`type: 'opacity'` (the default when `type` is omitted) renders content immediately
+and fades it in. Use it for light content where you only want the visual polish.
 
-### `useBottomSheetPortal`
+### State that must survive closing
 
-Access portal context to manually mount/update/unmount portal items.
+State inside `*Content` is destroyed when the sheet closes — usually what you want.
+When it needs to persist, own it in the screen and pass it down:
 
 ```tsx
-import { useBottomSheetPortal } from '@shaquillehinds/react-native-bottom-sheet';
+// screen
+const [selectedFlashcards, setSelectedFlashcards] = useState<FlashcardSet[]>(
+  []
+);
 
-function MyComponent() {
-  const portal = useBottomSheetPortal();
+<ChooseFlashcards
+  toggled={toggled}
+  setToggled={setToggled}
+  selectedFlashcards={selectedFlashcards}
+  setSelectedFlashcards={setSelectedFlashcards}
+  onFlashcardSelect={handleSelect}
+  studySetId={studySetId}
+/>;
+```
 
-  useEffect(() => {
-    if (portal) {
-      const key = portal.mount('my-portal-key', <MyPortalContent />);
-      return () => portal.unmount(key);
-    }
-  }, []);
+Do not solve this by hoisting the state into the sheet wrapper. That reintroduces
+exactly the cost the pattern removes.
 
-  return <View />;
-}
-```
+---
 
-**Methods:**
+## Components
 
-```typescript
-{
-  mount: (key: string | number, element: ReactNode, onMount?: (key) => void) => PortalKey;
-  update: (key: string | number, element: ReactNode) => void;
-  unmount: (key: string | number, onUnMount?: (key) => void) => void;
-}
-```
+### `BottomSheetModal`
 
-### `useBottomSheetPortalComponent`
+The default. Renders with an animated backdrop, closes on backdrop press, handles
+the Android back button.
 
-Simplified hook for mounting a component to the portal with automatic lifecycle management.
+### `BottomSheet`
 
-```tsx
-import { useBottomSheetPortalComponent } from '@shaquillehinds/react-native-bottom-sheet';
+Inline sheet with no backdrop. Renders with background content press enabled, so
+taps pass through to what is behind it. Use for filter panels, mini players,
+persistent drawers.
 
-function MyComponent() {
-  const [showOverlay, setShowOverlay] = useState(true);
+### `BottomSheetFlatlist` / `BottomSheetScrollView`
 
-  useBottomSheetPortalComponent({
-    name: 'my-overlay',
-    Component: showOverlay ? <OverlayContent /> : null,
-    disable: !showOverlay,
-  });
+Scroll containers that coordinate with the sheet's drag gesture. See
+[Scrollable content](#scrollable-content).
 
-  return <View />;
-}
-```
+---
 
-**Props:**
+## Controlling the sheet
 
-| Prop                  | Type            | Description                                      |
-| --------------------- | --------------- | ------------------------------------------------ |
-| `name`                | `string`        | Unique identifier for the portal component       |
-| `Component`           | `ReactNode`     | The component to render in the portal            |
-| `disable`             | `boolean`       | Disables portal rendering when true              |
-| `CustomPortalContext` | `React.Context` | Use a custom portal context (for scoped portals) |
+Two modes. Pick one.
 
-### Types
+### State-controlled
 
-```typescript
-import type {
-  PortalItem,
-  PortalKey,
-  PortalContextValue,
-} from '@shaquillehinds/react-native-bottom-sheet';
+```tsx
+const [showModal, setShowModal] = useState(false);
 
-type PortalItem = {
-  key: PortalKey;
-  element: ReactNode;
-};
+<BottomSheetModal showModal={showModal} setShowModal={setShowModal}>
+  <Content />
+</BottomSheetModal>;
+```
+
+You can wrap the setter to run side effects on open and close:
 
-type PortalKey = number | string;
+```tsx
+setShowModal={(value: boolean) => {
+  Keyboard.dismiss();
+  props.setShowModal(value);
+}}
 ```
 
-## API Reference
-
-### Props
-
-#### `BottomSheetProps` (Common to both components)
-
-| Prop                            | Type                                | Default        | Description                                                                                                     |
-| ------------------------------- | ----------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
-| `showModal`                     | `boolean`                           | -              | Controls visibility of the bottom sheet                                                                         |
-| `setShowModal`                  | `(bool: boolean) => void`           | -              | Callback to update visibility state                                                                             |
-| `snapPoints`                    | `(number \| string)[]`              | `[25, 50, 75]` | Array of snap positions as percentages of screen height. Accepts numbers or strings (e.g., `[25, "50", "75%"]`) |
-| `dragArea`                      | `'full' \| 'bumper' \| 'none'`      | `'bumper'`     | Defines draggable area of the modal                                                                             |
-| `keepMounted`                   | `boolean`                           | `false`        | Prevents full unmounting when closed. Use with `bottomOffset` to keep visible                                   |
-| `hideBumper`                    | `boolean`                           | `false`        | Hides the draggable bumper at top                                                                               |
-| `avoidKeyboard`                 | `boolean`                           | `false`        | Adds padding when keyboard is visible                                                                           |
-| `allowDragWhileKeyboardVisible` | `boolean`                           | `false`        | Allows dragging when keyboard is open (disabled by default to prevent conflicts)                                |
-| `inputsForKeyboardToAvoid`      | `React.RefObject<TextInput>[]`      | -              | Specific inputs that trigger keyboard avoidance                                                                 |
-| `bottomOffset`                  | `number`                            | `0`            | Pushes modal up from bottom. Useful with `keepMounted`                                                          |
-| `style`                         | `StyleProp<ViewStyle>`              | -              | Style for the modal sheet container                                                                             |
-| `backgroundColor`               | `string`                            | -              | Background color for modal and bumper                                                                           |
-| `contentContainerStyle`         | `StyleProp<ViewStyle>`              | -              | Style for the content container                                                                                 |
-| `bumperStyle`                   | `StyleProp<ViewStyle>`              | -              | Style for the bumper element                                                                                    |
-| `bumperContainerStyle`          | `StyleProp<ViewStyle>`              | -              | Style for the bumper container                                                                                  |
-| `BumperComponent`               | `() => React.ReactNode`             | -              | Custom bumper component                                                                                         |
-| `disablePortal`                 | `boolean`                           | `false`        | Disables portal rendering                                                                                       |
-| `CustomPortalContext`           | `React.Context<PortalContextValue>` | -              | Custom portal context for scoped portals                                                                        |
-
-#### `BottomSheetModalProps` (Extends BottomSheetProps)
-
-| Prop                          | Type              | Default | Description                               |
-| ----------------------------- | ----------------- | ------- | ----------------------------------------- |
-| `BackdropComponent`           | `React.ReactNode` | -       | Custom backdrop component                 |
-| `onBackDropPress`             | `() => void`      | -       | Callback when backdrop is pressed         |
-| `disableCloseOnBackdropPress` | `boolean`         | `false` | Prevents closing on backdrop press        |
-| `useNativeModal`              | `boolean`         | `false` | Use React Native's native Modal component |
-
-#### Callbacks
-
-| Prop               | Type                                                | Description                            |
-| ------------------ | --------------------------------------------------- | -------------------------------------- |
-| `onModalShow`      | `() => void \| Promise<void>`                       | Called when modal finishes mounting    |
-| `onModalClose`     | `() => void \| Promise<void>`                       | Called when modal finishes unmounting  |
-| `onSnapPointReach` | `(snapPointIndex: number) => void \| Promise<void>` | Called when modal reaches a snap point |
-
-#### Performance Optimization
-
-| Prop               | Type                                                       | Description                                                                                                                                                        |
-| ------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `showContentDelay` | `{ type?: 'mount' \| 'opacity', timeInMilliSecs: number }` | Delays content rendering for heavy components. Use `'mount'` for better performance with sluggish animations. Provide appropriate `minHeight` when using `'mount'` |
-
-### Ref Methods
-
-#### `BottomModalRef` (for BottomSheetModal and BottomSheet)
-
-```typescript
-const bottomSheetRef = useRef<BottomModalRefObject>(null);
-
-// Open modal programmatically
-bottomSheetRef.current?.openModal({
-  onOpen: () => console.log('Modal opened'),
-});
+### Ref-controlled
 
-// Close modal with options
-bottomSheetRef.current?.closeModal({
-  skipAnimation: false, // Skip close animation
-  isNavigating: false, // Fast close for navigation
-  duration: 300, // Custom duration
-  easing: Easing.linear, // Custom easing
-  onClose: () => console.log('Modal closed'),
-});
+Omit `showModal` and `setShowModal` entirely. Useful for a sheet mounted once,
+high in the tree, opened from anywhere in the app:
 
-// Close instantly without animation
-bottomSheetRef.current?.closeWithoutAnimation();
+```tsx
+export default function UploadMaterialModal() {
+  const ref = useRef<BottomModalRef>(null);
+  const setUploadModalRef = useApp((state) => state.setUploadModalRef);
 
-// Snap to specific index
-bottomSheetRef.current?.snapToIndex(1);
+  useEffect(() => {
+    setUploadModalRef(ref);
+  }, [ref.current]);
 
-// Snap to percentage
-bottomSheetRef.current?.snapToPercentage(75);
-bottomSheetRef.current?.snapToPercentage('80%');
+  return (
+    <SmoothBottomModal
+      ref={ref}
+      disablePortal
+      dragArea="full"
+      snapPoints={[90]}
+    >
+      <UploadMaterialModalContent />
+    </SmoothBottomModal>
+  );
+}
 
-// Get current state
-const state = bottomSheetRef.current?.getModalState();
-// Returns: ModalState.CLOSED | OPENING | OPEN | CLOSING
+// anywhere
+useApp.getState().uploadModalRef?.current?.openModal();
 ```
 
-#### `BottomSheetRef` (for inline BottomSheet with BottomSheetControl)
+`disablePortal` is right here because the sheet is already mounted at root level —
+there is nothing above it for the portal to lift it past.
+
+### Ref methods
 
-```typescript
-const sheetRef = useRef<BottomSheetRefObject>(null);
+```tsx
+const ref = useRef<BottomModalRef>(null);
 
-// Animate close
-sheetRef.current?.animateCloseModal({
+ref.current?.openModal({ onOpen: () => {} });
+ref.current?.closeModal({
+  skipAnimation: false,
+  isNavigating: false,
   duration: 300,
-  easing: Easing.bezier(0.2, 0.32, 0, 1),
+  easing: Easing.linear,
+  onClose: () => {},
 });
+ref.current?.closeWithoutAnimation();
+ref.current?.snapToIndex(1);
+ref.current?.snapToPercentage(75); // or '75%'
+ref.current?.getModalState(); // ModalState.CLOSED | OPENING | OPEN | CLOSING
+```
+
+Behaviour to be aware of on a **state-controlled** sheet:
 
-// Snap to index
-sheetRef.current?.snapToIndex(2);
+| Call                                  | What actually happens                           |
+| ------------------------------------- | ----------------------------------------------- |
+| `openModal()`                         | `setShowModal(true)`                            |
+| `openModal({ onOpen })`               | routes through the mounter so `onOpen` can fire |
+| `closeModal()`                        | `setShowModal(false)`                           |
+| `closeModal({ duration \| onClose })` | animates, then clears state after the animation |
+| `closeModal({ isNavigating: true })`  | 100ms close — use before navigating             |
+| `closeModal({ skipAnimation: true })` | immediate unmount                               |
 
-// Snap to percentage
-sheetRef.current?.snapToPercentage(50);
+### Ref typing
 
-// Get state
-const state = sheetRef.current?.getModalState();
+```tsx
+const ref = useRef<BottomModalRef>(null); // ✅
 ```
 
-### Hook: `useBottomSheetRef`
+`BottomModalRefObject` is `React.Ref<BottomModalRef>` — it types the `ref` _prop_
+on the component, not the object `useRef` gives you. Using it in `useRef` produces
+a doubly-wrapped type.
 
-Access the modal ref from within the bottom sheet component tree.
+### Closing from inside the sheet
 
 ```tsx
 import { useBottomSheetRef } from '@shaquillehinds/react-native-bottom-sheet';
 
-function ContentComponent() {
+function Footer() {
   const { modalRef } = useBottomSheetRef();
+  return (
+    <Button title="Close" onPress={() => modalRef?.current?.closeModal()} />
+  );
+}
+```
 
-  const handleClose = () => {
-    modalRef?.current?.closeModal();
-  };
+Available anywhere inside the sheet's subtree. Returns `{ modalRef }` where
+`modalRef` may be undefined outside a sheet, so optional-chain it.
 
-  return <Button title="Close" onPress={handleClose} />;
-}
+---
+
+## Snap points
+
+Percentages of screen height. Numbers or strings both work:
+
+```tsx
+snapPoints={[25, 50, 75]}
+snapPoints={['25', '50%', 90]}
 ```
 
-## Advanced Usage
+- The sheet opens at index `0`. Order the array in the direction you want it read;
+  `snapToIndex` uses the array's own indices.
+- `onSnapPointReach(index)` fires when the sheet settles on one. Only active when
+  `snapPoints` is set.
+- Keep the array referentially stable — a module constant or `useMemo`.
+- On orientation change, snap points are recomputed and the sheet re-snaps to
+  index 0.
 
-### Scrollable Content
+### Content-height mode
 
-#### Using BottomSheetFlatlist
+Omitting `snapPoints` is a supported mode, not an oversight. The sheet measures its
+content on layout and opens to exactly that height, capped at roughly 110% of
+screen height. Good for short, content-sized sheets — confirmation dialogs, small
+action lists.
+
+Dragging behaviour differs: with no snap points, a drag past half the content
+height or a fast flick dismisses the sheet.
+
+Content-height mode is incompatible with `showContentDelay: { type: 'mount' }`,
+since there is nothing to measure at open time. Use `snapPoints`, or set a
+`minHeight` on `contentContainerStyle`.
+
+---
+
+## Scrollable content
 
 ```tsx
 import {
@@ -390,1076 +401,522 @@ import {
   BottomSheetFlatlist,
 } from '@shaquillehinds/react-native-bottom-sheet';
 
-<BottomSheetModal
-  showModal={showModal}
-  setShowModal={setShowModal}
-  snapPoints={[50, 90]}
->
+<BottomSheetModal snapPoints={[50, 90]} showModal={show} setShowModal={setShow}>
   <BottomSheetFlatlist
     data={items}
-    renderItem={({ item }) => <ItemComponent item={item} />}
+    renderItem={({ item }) => <Row item={item} />}
     keyExtractor={(item) => item.id}
   />
 </BottomSheetModal>;
 ```
 
-#### Using BottomSheetScrollView
+These wrap the underlying Reanimated list in a drag gesture that coordinates with
+the sheet: the sheet drags when the list sits at a scroll boundary, the list
+scrolls otherwise. A bare `FlatList` or `ScrollView` has no such coordination and
+the two gestures will fight.
 
-```tsx
-import {
-  BottomSheetModal,
-  BottomSheetScrollView,
-} from '@shaquillehinds/react-native-bottom-sheet';
+Notes:
 
-<BottomSheetModal showModal={showModal} setShowModal={setShowModal}>
-  <BottomSheetScrollView>{/* Your scrollable content */}</BottomSheetScrollView>
-</BottomSheetModal>;
-```
+- Props are the full underlying set — `FlatListPropsWithLayout` for the list,
+  `AnimatedScrollViewProps` for the scroll view — with `onScroll` widened to also
+  accept a Reanimated scroll event.
+- Pass a custom ref via `refFlatlist` / `refScrollView`, not `ref`.
+- `inverted` lists are supported; the sheet is told about the inversion.
+- `bounces` is forced to `false` inside a sheet.
+- Used outside a sheet, both fall back to a plain animated list/scroll view.
+- Avoid `dragArea="full"` alongside a scrollable child. Keep the default `"bumper"`.
 
-### Keyboard Handling
+---
 
-#### Global Keyboard Avoidance
+## Keyboard handling
+
+### Whole-sheet avoidance
 
 ```tsx
-<BottomSheetModal
-  avoidKeyboard={true}
-  showModal={showModal}
-  setShowModal={setShowModal}
->
+<BottomSheetModal avoidKeyboard showModal={show} setShowModal={setShow}>
   <TextInput placeholder="Email" />
-  <TextInput placeholder="Password" />
 </BottomSheetModal>
 ```
 
-#### Per-Input Keyboard Avoidance
+### Per-input avoidance
 
-```tsx
-function FormComponent() {
-  const emailRef = useRef<TextInput>(null);
-  const passwordRef = useRef<TextInput>(null);
-
-  return (
-    <BottomSheetModal
-      inputsForKeyboardToAvoid={[emailRef, passwordRef]}
-      showModal={showModal}
-      setShowModal={setShowModal}
-    >
-      <TextInput ref={emailRef} placeholder="Email" />
-      <TextInput ref={passwordRef} placeholder="Password" />
-      <TextInput placeholder="Not tracked" />
-    </BottomSheetModal>
-  );
-}
-```
-
-### Custom Bumper
+Only shift for specific inputs — useful when a search field should move but a
+comment box further down should not:
 
 ```tsx
-function CustomBumper() {
-  return (
-    <View style={{ padding: 20, alignItems: 'center' }}>
-      <View
-        style={{
-          width: 100,
-          height: 5,
-          backgroundColor: 'blue',
-          borderRadius: 3,
-        }}
-      />
-      <Text style={{ marginTop: 10 }}>Drag me</Text>
-    </View>
-  );
-}
+const emailRef = useRef<TextInput>(null);
+const passwordRef = useRef<TextInput>(null);
 
 <BottomSheetModal
-  BumperComponent={CustomBumper}
-  showModal={showModal}
-  setShowModal={setShowModal}
+  inputsForKeyboardToAvoid={[emailRef, passwordRef]}
+  showModal={show}
+  setShowModal={setShow}
 >
-  <YourContent />
+  <TextInput ref={emailRef} />
+  <TextInput ref={passwordRef} />
+  <TextInput placeholder="Not tracked" />
 </BottomSheetModal>;
 ```
 
-### Custom Backdrop
+Dragging is disabled while the keyboard is open, since the two interactions
+conflict. Override with `allowDragWhileKeyboardVisible` if you have a reason.
 
-```tsx
-function CustomBackdrop() {
-  return (
-    <View
-      style={{
-        flex: 1,
-        backgroundColor: 'rgba(255, 0, 0, 0.3)',
-      }}
-    />
-  );
-}
+Do not add `KeyboardAvoidingView` — it will fight the built-in handling.
 
-<BottomSheetModal
-  BackdropComponent={<CustomBackdrop />}
-  showModal={showModal}
-  setShowModal={setShowModal}
->
-  <YourContent />
-</BottomSheetModal>;
-```
+---
 
-### Persistent Bottom Sheet
+## Persistent sheets
 
-Keep the sheet partially visible when "closed":
+`keepMounted` changes what a downward drag does: instead of dismissing, the sheet
+snaps to its lowest snap point.
 
 ```tsx
 <BottomSheet
-  keepMounted={true}
-  bottomOffset={50} // Shows 50px when closed
-  snapPoints={[10, 50, 90]}
-  showModal={showModal}
-  setShowModal={setShowModal}
+  keepMounted
+  snapPoints={[10, 70]}
+  bottomOffset={100}
+  showModal={show}
+  setShowModal={setShow}
 >
-  <YourContent />
+  <FilterPanel />
 </BottomSheet>
 ```
 
-### Performance Optimization for Heavy Content
+Two things to know:
 
-Use `showContentDelay` to improve modal animation performance:
+- **`keepMounted` requires `snapPoints`.** With no snap points it is ignored and
+  a drag down will dismiss as usual.
+- It governs the drag gesture only. `showModal={false}` still unmounts the sheet.
 
-```tsx
-<BottomSheetModal
-  showModal={showModal}
-  setShowModal={setShowModal}
-  contentContainerStyle={{ minHeight: 400 }}
-  showContentDelay={{
-    type: 'mount', // Delays mounting entirely
-    timeInMilliSecs: 100,
-  }}
->
-  <HeavyComponent />
-</BottomSheetModal>
-```
+`bottomOffset` pushes the sheet up from the bottom of the screen, so its "closed"
+position stays visible as a peek.
 
-Or use opacity animation:
+---
 
-```tsx
-<BottomSheetModal
-  showContentDelay={{
-    type: 'opacity', // Fades in content
-    timeInMilliSecs: 200,
-  }}
-  showModal={showModal}
-  setShowModal={setShowModal}
->
-  <YourContent />
-</BottomSheetModal>
-```
+## Appearance
 
-### Snap Point Callbacks
+| Prop                    | Targets                                |
+| ----------------------- | -------------------------------------- |
+| `backgroundColor`       | Sheet surface **and** bumper container |
+| `style`                 | The sheet surface                      |
+| `contentContainerStyle` | The container wrapping your children   |
+| `bumperStyle`           | The grab handle itself                 |
+| `bumperContainerStyle`  | The area around the handle             |
 
-```tsx
-<BottomSheetModal
-  snapPoints={[25, 50, 75]}
-  onSnapPointReach={(index) => {
-    console.log(`Reached snap point: ${index}`);
-    if (index === 2) {
-      // Reached highest snap point
-    }
-  }}
-  showModal={showModal}
-  setShowModal={setShowModal}
->
-  <YourContent />
-</BottomSheetModal>
-```
+Use `backgroundColor` rather than setting a background in `style` — the former
+also colours the bumper container, so the handle area matches.
 
-### Drag Configuration
+### Custom bumper
 
-#### Full Sheet Dragging
+The custom component becomes the drag area when `dragArea` is `"bumper"`.
 
 ```tsx
-<BottomSheetModal
-  dragArea="full"
-  showModal={showModal}
-  setShowModal={setShowModal}
->
-  <YourContent />
-</BottomSheetModal>
-```
-
-#### Disable Dragging
+function Bumper() {
+  return (
+    <View style={{ padding: 20, alignItems: 'center' }}>
+      <View style={{ width: 100, height: 5, backgroundColor: '#888', borderRadius: 3 }} />
+    </View>
+  );
+}
 
-```tsx
-<BottomSheetModal
-  dragArea="none"
-  showModal={showModal}
-  setShowModal={setShowModal}
->
-  <YourContent />
-</BottomSheetModal>
+<BottomSheetModal BumperComponent={Bumper} ... />
 ```
 
-#### Allow Dragging with Keyboard
+### Custom backdrop
 
 ```tsx
 <BottomSheetModal
-  avoidKeyboard={true}
-  allowDragWhileKeyboardVisible={true}
-  showModal={showModal}
-  setShowModal={setShowModal}
->
-  <TextInput />
-</BottomSheetModal>
+  BackdropComponent={<BlurView intensity={40} style={StyleSheet.absoluteFill} />}
+  onBackDropPress={() => track('dismiss')}
+  ...
+/>
 ```
 
-### Portal Management
-
-By default, bottom sheets use the portal system to render at the root level, ensuring they appear above all content.
-
-#### Using Default Portal (Recommended)
+`disableCloseOnBackdropPress` keeps `onBackDropPress` firing without closing.
 
-The bottom sheet automatically uses the portal when `BottomSheetPortalProvider` is set up:
+### Drag area
 
-```tsx
-// App.tsx
-import { BottomSheetPortalProvider } from '@shaquillehinds/react-native-bottom-sheet';
+| Value                | Behaviour                                             |
+| -------------------- | ----------------------------------------------------- |
+| `"bumper"` (default) | Only the handle drags                                 |
+| `"full"`             | The whole sheet drags — avoid with scrollable content |
+| `"none"`             | No dragging; close programmatically or via backdrop   |
 
-export default function App() {
-  return (
-    <BottomSheetPortalProvider>
-      <NavigationContainer>
-        <Stack.Navigator>
-          <Stack.Screen name="Home" component={HomeScreen} />
-        </Stack.Navigator>
-      </NavigationContainer>
-    </BottomSheetPortalProvider>
-  );
-}
+`hideBumper` removes the handle. With `dragArea="bumper"` and `hideBumper`, there
+is nothing left to drag — pair `hideBumper` with `"full"` or `"none"`.
 
-// HomeScreen.tsx - bottom sheet will render above navigation
-<BottomSheetModal showModal={showModal} setShowModal={setShowModal}>
-  <YourContent />
-</BottomSheetModal>;
-```
+---
 
-#### Disable Portal Rendering
+## Portal system
 
-If you want the bottom sheet to render in its natural position in the component tree:
+Sheets render into a portal at app root so they sit above navigation. This is
+automatic once `BottomSheetPortalProvider` is in place.
 
-```tsx
-<BottomSheetModal
-  disablePortal={true}
-  showModal={showModal}
-  setShowModal={setShowModal}
->
-  <YourContent />
-</BottomSheetModal>
-```
+### `BottomSheetPortalProvider`
 
-#### Custom Portal Context (Advanced)
+| Prop                  | Type            | Default | Description                             |
+| --------------------- | --------------- | ------- | --------------------------------------- |
+| `unMountBufferTimeMS` | `number`        | `100`   | Delay before removing portal items      |
+| `updateBufferTimeMS`  | `number`        | –       | Throttle for portal updates             |
+| `CustomPortalContext` | `React.Context` | –       | Scope this provider to a custom context |
 
-Create scoped portals for specific parts of your app:
+### `disablePortal`
 
-```tsx
-import {
-  BottomSheetPortalProvider,
-  useBottomSheetPortal,
-} from '@shaquillehinds/react-native-bottom-sheet';
-import { createContext } from 'react';
-import type { PortalContextValue } from '@shaquillehinds/react-native-bottom-sheet';
+Renders the sheet where it sits in the tree. Correct when the sheet is already
+mounted at root level, or when you want it scoped to a subtree.
 
-// Create a custom portal context
-const MyCustomPortalContext = createContext<PortalContextValue | undefined>(
-  undefined
-);
+### Scoped portals
 
-// Wrap specific section with custom portal provider
-function MySection() {
-  return (
-    <BottomSheetPortalProvider CustomPortalContext={MyCustomPortalContext}>
-      <MySectionContent />
-    </BottomSheetPortalProvider>
-  );
-}
-
-// Use the custom context in your bottom sheet
-<BottomSheetModal
-  CustomPortalContext={MyCustomPortalContext}
-  showModal={showModal}
-  setShowModal={setShowModal}
->
-  <YourContent />
-</BottomSheetModal>;
-```
-
-#### Manual Portal Control
-
-For advanced use cases where you need direct portal control:
+Both provider and sheet must be handed the same context object:
 
 ```tsx
-import { useBottomSheetPortal } from '@shaquillehinds/react-native-bottom-sheet';
-
-function CustomPortalComponent() {
-  const portal = useBottomSheetPortal();
-  const [portalKey, setPortalKey] = useState<string | number | null>(null);
-
-  const mountContent = () => {
-    if (portal) {
-      const key = portal.mount(
-        'custom-content',
-        <View style={{ padding: 20, backgroundColor: 'white' }}>
-          <Text>Portal Content</Text>
-        </View>,
-        (key) => console.log('Mounted:', key)
-      );
-      setPortalKey(key);
-    }
-  };
-
-  const updateContent = () => {
-    if (portal && portalKey) {
-      portal.update(
-        portalKey,
-        <View style={{ padding: 20, backgroundColor: 'blue' }}>
-          <Text>Updated Content</Text>
-        </View>
-      );
-    }
-  };
-
-  const unmountContent = () => {
-    if (portal && portalKey) {
-      portal.unmount(portalKey, (key) => console.log('Unmounted:', key));
-      setPortalKey(null);
-    }
-  };
+const ScreenPortalContext = createContext<PortalContextValue | undefined>(undefined);
 
-  return (
-    <View>
-      <Button title="Mount" onPress={mountContent} />
-      <Button title="Update" onPress={updateContent} />
-      <Button title="Unmount" onPress={unmountContent} />
-    </View>
-  );
-}
+<BottomSheetPortalProvider CustomPortalContext={ScreenPortalContext}>
+  <BottomSheetModal CustomPortalContext={ScreenPortalContext} ...>
+    <Content />
+  </BottomSheetModal>
+</BottomSheetPortalProvider>
 ```
 
-#### Using Portal Component Hook
+### Non-sheet overlays
 
-Simplified component-based portal management with automatic cleanup:
+`useBottomSheetPortalComponent` mounts arbitrary content into the same portal with
+automatic cleanup — toasts, loading overlays, anything that needs to sit above
+everything:
 
 ```tsx
-import { useBottomSheetPortalComponent } from '@shaquillehinds/react-native-bottom-sheet';
-
-function ToastNotification() {
-  const [message, setMessage] = useState('');
-  const [show, setShow] = useState(false);
-
-  // Automatically mounts/unmounts based on show state
-  useBottomSheetPortalComponent({
-    name: 'toast-notification',
-    Component: show ? (
-      <View style={{ position: 'absolute', top: 50, alignSelf: 'center' }}>
-        <Text>{message}</Text>
-      </View>
-    ) : null,
-    disable: !show,
-  });
-
-  const showToast = (msg: string) => {
-    setMessage(msg);
-    setShow(true);
-    setTimeout(() => setShow(false), 3000);
-  };
-
-  return <Button title="Show Toast" onPress={() => showToast('Hello!')} />;
-}
+useBottomSheetPortalComponent({
+  name: 'toast',
+  Component: visible ? <Toast message={message} /> : null,
+  disable: !visible,
+});
 ```
 
-### Navigation Integration
+`useBottomSheetPortal` gives the raw `{ mount, update, unmount }` API for manual
+control.
+
+You do not need either of these for a bottom sheet — the sheet portals itself.
+
+---
+
+## API reference
+
+### `BottomSheetProps`
+
+| Prop                            | Type                                                       | Default    | Description                                                                       |
+| ------------------------------- | ---------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------- |
+| `showModal`                     | `boolean`                                                  | –          | Visibility. Omit for a ref-controlled sheet                                       |
+| `setShowModal`                  | `(bool: boolean) => void`                                  | –          | Visibility setter                                                                 |
+| `snapPoints`                    | `(number \| string)[]`                                     | –          | Percentages of screen height. Omit for content-height mode                        |
+| `dragArea`                      | `'full' \| 'bumper' \| 'none'`                             | `'bumper'` | Draggable region                                                                  |
+| `keepMounted`                   | `boolean`                                                  | `false`    | Drag down snaps to lowest snap point instead of dismissing. Requires `snapPoints` |
+| `hideBumper`                    | `boolean`                                                  | `false`    | Remove the grab handle                                                            |
+| `avoidKeyboard`                 | `boolean`                                                  | `false`    | Pad content when the keyboard is open                                             |
+| `allowDragWhileKeyboardVisible` | `boolean`                                                  | `false`    | Permit dragging with the keyboard open                                            |
+| `inputsForKeyboardToAvoid`      | `React.RefObject<TextInput>[]`                             | –          | Only avoid for these inputs                                                       |
+| `bottomOffset`                  | `number`                                                   | `0`        | Push the sheet up from the bottom                                                 |
+| `showContentDelay`              | `{ type?: 'mount' \| 'opacity'; timeInMilliSecs: number }` | –          | Defer content render past the open animation                                      |
+| `style`                         | `StyleProp<ViewStyle>`                                     | –          | Sheet surface                                                                     |
+| `contentContainerStyle`         | `StyleProp<ViewStyle>`                                     | –          | Content container                                                                 |
+| `bumperStyle`                   | `StyleProp<ViewStyle>`                                     | –          | Grab handle                                                                       |
+| `bumperContainerStyle`          | `StyleProp<ViewStyle>`                                     | –          | Handle container                                                                  |
+| `backgroundColor`               | `string`                                                   | –          | Sheet and bumper container background                                             |
+| `BumperComponent`               | `() => React.ReactNode`                                    | –          | Replace the default handle                                                        |
+| `onModalShow`                   | `() => void \| Promise<void>`                              | –          | Fires when the sheet finishes mounting                                            |
+| `onModalClose`                  | `() => void \| Promise<void>`                              | –          | Fires when the sheet finishes unmounting                                          |
+| `onSnapPointReach`              | `(index: number) => void \| Promise<void>`                 | –          | Fires on settling at a snap point                                                 |
+| `disablePortal`                 | `boolean`                                                  | `false`    | Render in place                                                                   |
+| `CustomPortalContext`           | `React.Context<PortalContextValue>`                        | –          | Scoped portal                                                                     |
+
+### `BottomSheetModalProps`
+
+Extends `BottomSheetProps`.
+
+| Prop                           | Type              | Default | Description                                  |
+| ------------------------------ | ----------------- | ------- | -------------------------------------------- |
+| `BackdropComponent`            | `React.ReactNode` | –       | Custom backdrop                              |
+| `onBackDropPress`              | `() => void`      | –       | Backdrop press callback                      |
+| `disableCloseOnBackdropPress`  | `boolean`         | `false` | Keep open on backdrop press                  |
+| `useNativeModal`               | `boolean`         | `false` | Render inside RN's native `Modal`            |
+| `enableBackgroundContentPress` | `boolean`         | `false` | Drop the backdrop; taps reach content behind |
+| `disableAndroidBackButton`     | `boolean`         | `false` | Ignore the hardware back button              |
+
+### `BottomSheetFlatlistProps<T>`
+
+`Omit<FlatListPropsWithLayout<T>, 'onScroll'>` plus:
+
+| Prop          | Type                                    |
+| ------------- | --------------------------------------- |
+| `onScroll`    | `ReanimatedOnScroll \| DefaultOnScroll` |
+| `refFlatlist` | `React.RefObject<FlatList>`             |
+
+### `BottomSheetScrollViewProps`
+
+`Omit<AnimatedScrollViewProps, 'onScroll'>` plus:
+
+| Prop            | Type                                    |
+| --------------- | --------------------------------------- |
+| `onScroll`      | `ReanimatedOnScroll \| DefaultOnScroll` |
+| `refScrollView` | `React.RefObject<AnimatedScrollView>`   |
+
+### Ref types
+
+```ts
+type BottomModalRef = {
+  getModalState: () => ModalState | undefined;
+  openModal: (props?: OpenModalProps) => void;
+  closeModal: (props?: CloseModalProps) => void;
+  closeWithoutAnimation: () => void;
+  snapToIndex: (index: number) => void;
+  snapToPercentage: (percentage: number | string) => void;
+};
 
-For smooth navigation transitions on Android:
+type OpenModalProps = { onOpen?: () => void };
 
-```tsx
-const handleNavigateAndClose = () => {
-  bottomSheetRef.current?.closeModal({
-    isNavigating: true, // Reduces animation to 100ms
-    onClose: () => {
-      navigation.navigate('NextScreen');
-    },
-  });
+type CloseModalProps = {
+  skipAnimation?: boolean;
+  isNavigating?: boolean;
+  onClose?: () => void;
+  duration?: number;
+  easing?: EasingFunction | EasingFunctionFactory;
 };
+
+enum ModalState {
+  CLOSED = 0,
+  OPENING = 1,
+  OPEN = 2,
+  CLOSING = 3,
+}
 ```
 
-Or skip animation entirely:
+### Exports
 
-```tsx
-bottomSheetRef.current?.closeModal({
-  skipAnimation: true,
-  onClose: () => navigation.navigate('NextScreen'),
-});
-```
+```ts
+// Components
+(BottomSheet, BottomSheetModal, BottomSheetFlatlist, BottomSheetScrollView);
 
-## TypeScript Support
+// Hooks
+(useBottomSheetRef, useBottomSheetPortal, useBottomSheetPortalComponent);
 
-Full TypeScript support with comprehensive type definitions:
+// Provider
+BottomSheetPortalProvider;
 
-```typescript
-// Component Props
-import type {
-  BottomSheetProps,
+// Types
+(BottomSheetProps,
   BottomSheetModalProps,
   BottomSheetFlatlistProps,
   BottomSheetScrollViewProps,
-} from '@shaquillehinds/react-native-bottom-sheet';
-
-// Ref Types
-import type {
-  BottomModalRefObject,
-  BottomSheetRefObject,
   BottomModalRef,
   BottomSheetRef,
-} from '@shaquillehinds/react-native-bottom-sheet';
-
-// State and Config Types
-import type {
+  BottomModalRefObject,
+  BottomSheetRefObject,
   ModalState,
-  AnimateCloseModalProps,
-  CloseModalProps,
   OpenModalProps,
-} from '@shaquillehinds/react-native-bottom-sheet';
-
-// Portal Types
-import type {
+  CloseModalProps,
+  AnimateCloseModalProps,
   PortalItem,
   PortalKey,
-  PortalContextValue,
-} from '@shaquillehinds/react-native-bottom-sheet';
+  PortalContextValue);
 ```
 
-## Examples
+---
 
-### Complete Modal Example
+## Recipes
 
-```tsx
-import React, { useRef, useState } from 'react';
-import { View, Text, Button, TextInput } from 'react-native';
-import {
-  BottomSheetModal,
-  BottomSheetScrollView,
-  useBottomSheetRef,
-} from '@shaquillehinds/react-native-bottom-sheet';
-import type { BottomModalRefObject } from '@shaquillehinds/react-native-bottom-sheet';
-
-export default function CompleteExample() {
-  const [showModal, setShowModal] = useState(false);
-  const bottomSheetRef = useRef<BottomModalRefObject>(null);
-
-  const handleOpen = () => {
-    bottomSheetRef.current?.openModal({
-      onOpen: () => console.log('Modal opened!'),
-    });
-  };
-
-  const handleSnapToTop = () => {
-    bottomSheetRef.current?.snapToIndex(2);
-  };
+### Action list
 
-  return (
-    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
-      <Button title="Open Modal" onPress={() => setShowModal(true)} />
-
-      <BottomSheetModal
-        ref={bottomSheetRef}
-        showModal={showModal}
-        setShowModal={setShowModal}
-        snapPoints={[30, 60, 90]}
-        backgroundColor="#ffffff"
-        avoidKeyboard={true}
-        onModalShow={() => console.log('Modal shown')}
-        onModalClose={() => console.log('Modal closed')}
-        onSnapPointReach={(index) => console.log('Snap point:', index)}
-      >
-        <BottomSheetScrollView>
-          <View style={{ padding: 20 }}>
-            <Text style={{ fontSize: 24, marginBottom: 20 }}>My Modal</Text>
-
-            <TextInput
-              placeholder="Enter text..."
-              style={{
-                borderWidth: 1,
-                borderColor: '#ccc',
-                padding: 10,
-                marginBottom: 20,
-              }}
-            />
-
-            <Button title="Snap to Top" onPress={handleSnapToTop} />
-
-            <InnerComponent />
-          </View>
-        </BottomSheetScrollView>
-      </BottomSheetModal>
-    </View>
-  );
-}
-
-function InnerComponent() {
-  const { modalRef } = useBottomSheetRef();
-
-  return (
-    <Button
-      title="Close from Inside"
-      onPress={() => modalRef?.current?.closeModal()}
-    />
-  );
-}
-```
-
-### Form with Validation Example
-
-```tsx
-import React, { useRef, useState } from 'react';
-import { View, Text, TextInput, Button } from 'react-native';
-import { BottomSheetModal } from '@shaquillehinds/react-native-bottom-sheet';
-import type { BottomModalRefObject } from '@shaquillehinds/react-native-bottom-sheet';
-
-export default function FormExample() {
-  const [showModal, setShowModal] = useState(false);
-  const [email, setEmail] = useState('');
-  const [password, setPassword] = useState('');
-  const emailRef = useRef<TextInput>(null);
-  const passwordRef = useRef<TextInput>(null);
-  const bottomSheetRef = useRef<BottomModalRefObject>(null);
-
-  const handleSubmit = () => {
-    if (email && password) {
-      console.log('Submitting:', { email, password });
-      bottomSheetRef.current?.closeModal({
-        onClose: () => {
-          // Clear form after animation
-          setEmail('');
-          setPassword('');
-        },
-      });
-    }
-  };
-
-  return (
-    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
-      <Button title="Login" onPress={() => setShowModal(true)} />
-
-      <BottomSheetModal
-        ref={bottomSheetRef}
-        showModal={showModal}
-        setShowModal={setShowModal}
-        snapPoints={[60]}
-        inputsForKeyboardToAvoid={[emailRef, passwordRef]}
-        contentContainerStyle={{ padding: 20 }}
-      >
-        <Text style={{ fontSize: 24, marginBottom: 20 }}>Login</Text>
-
-        <TextInput
-          ref={emailRef}
-          value={email}
-          onChangeText={setEmail}
-          placeholder="Email"
-          keyboardType="email-address"
-          autoCapitalize="none"
-          style={{
-            borderWidth: 1,
-            borderColor: '#ccc',
-            padding: 10,
-            marginBottom: 15,
-          }}
-        />
-
-        <TextInput
-          ref={passwordRef}
-          value={password}
-          onChangeText={setPassword}
-          placeholder="Password"
-          secureTextEntry
-          style={{
-            borderWidth: 1,
-            borderColor: '#ccc',
-            padding: 10,
-            marginBottom: 20,
-          }}
-        />
-
-        <Button title="Submit" onPress={handleSubmit} />
-      </BottomSheetModal>
-    </View>
-  );
-}
-```
-
-### Custom Portal Overlay Example
+The wrapper stays thin; the option array — which closes over `router` and the
+setter — is built inside the content component, so it is never constructed while
+the sheet is closed.
 
 ```tsx
-import React, { useState } from 'react';
-import { View, Text, Button, TouchableOpacity, StyleSheet } from 'react-native';
-import {
-  BottomSheetPortalProvider,
-  useBottomSheetPortalComponent,
-} from '@shaquillehinds/react-native-bottom-sheet';
+export default function ChatAppsModal(props: {
+  showModal: boolean;
+  setShowModal: React.Dispatch<React.SetStateAction<boolean>>;
+}) {
+  const { colors, mode } = useTheme();
 
-// App root with provider
-export default function App() {
   return (
-    <BottomSheetPortalProvider>
-      <MyScreen />
-    </BottomSheetPortalProvider>
-  );
-}
-
-// Screen with custom portal overlay
-function MyScreen() {
-  const [showOverlay, setShowOverlay] = useState(false);
-  const [message, setMessage] = useState('');
-
-  // Mount custom overlay to portal
-  useBottomSheetPortalComponent({
-    name: 'custom-overlay',
-    Component: showOverlay ? (
-      <TouchableOpacity
-        style={styles.overlay}
-        activeOpacity={1}
-        onPress={() => setShowOverlay(false)}
-      >
-        <View style={styles.overlayContent}>
-          <Text style={styles.overlayText}>{message}</Text>
-          <Button title="Close" onPress={() => setShowOverlay(false)} />
-        </View>
-      </TouchableOpacity>
-    ) : null,
-    disable: !showOverlay,
-  });
-
-  const showCustomOverlay = (msg: string) => {
-    setMessage(msg);
-    setShowOverlay(true);
-  };
-
-  return (
-    <View style={styles.container}>
-      <Button
-        title="Show Portal Overlay"
-        onPress={() => showCustomOverlay('This is rendered in the portal!')}
-      />
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-  },
-  overlay: {
-    ...StyleSheet.absoluteFillObject,
-    backgroundColor: 'rgba(0, 0, 0, 0.5)',
-    justifyContent: 'center',
-    alignItems: 'center',
-  },
-  overlayContent: {
-    backgroundColor: 'white',
-    padding: 30,
-    borderRadius: 10,
-    alignItems: 'center',
-  },
-  overlayText: {
-    fontSize: 18,
-    marginBottom: 20,
-  },
-});
-```
-
-### Multi-Level Portal Example
-
-```tsx
-import React, { createContext, useState } from 'react';
-import { View, Button } from 'react-native';
-import {
-  BottomSheetPortalProvider,
-  BottomSheetModal,
-} from '@shaquillehinds/react-native-bottom-sheet';
-import type { PortalContextValue } from '@shaquillehinds/react-native-bottom-sheet';
-
-// Create custom portal contexts for different levels
-const ScreenPortalContext = createContext<PortalContextValue | undefined>(
-  undefined
-);
-const DialogPortalContext = createContext<PortalContextValue | undefined>(
-  undefined
-);
-
-export default function App() {
-  return (
-    // Global portal for app-wide modals
-    <BottomSheetPortalProvider>
-      <Navigation />
-    </BottomSheetPortalProvider>
+    <SmoothBottomModal
+      showModal={props.showModal}
+      setShowModal={(value: boolean) => {
+        Keyboard.dismiss();
+        props.setShowModal(value);
+      }}
+      backgroundColor={colors.background[mode]}
+      showContentDelay={{ timeInMilliSecs: 250, type: 'mount' }}
+      snapPoints={[85]}
+    >
+      <ChatAppsModalContent {...props} mode={mode} colors={colors} />
+    </SmoothBottomModal>
   );
 }
 
-function MyScreen() {
-  const [showScreenModal, setShowScreenModal] = useState(false);
-  const [showDialogModal, setShowDialogModal] = useState(false);
+function ChatAppsModalContent({ setShowModal, colors, mode }: ContentProps) {
+  const apps = [
+    {
+      id: 'flashcards',
+      title: 'Flashcards',
+      onPress: () => {
+        setShowModal(false);
+        router.push('/platform/practice/flashcards');
+      },
+    },
+    // ...
+  ];
 
-  return (
-    // Screen-specific portal
-    <BottomSheetPortalProvider CustomPortalContext={ScreenPortalContext}>
-      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
-        <Button
-          title="Open Screen Modal"
-          onPress={() => setShowScreenModal(true)}
-        />
-
-        {/* Modal using screen portal */}
-        <BottomSheetModal
-          CustomPortalContext={ScreenPortalContext}
-          showModal={showScreenModal}
-          setShowModal={setShowScreenModal}
-          snapPoints={[50]}
-        >
-          <View style={{ padding: 20 }}>
-            <Text>Screen-level modal</Text>
-            <Button
-              title="Open Dialog"
-              onPress={() => setShowDialogModal(true)}
-            />
-
-            {/* Nested modal using dialog portal */}
-            <BottomSheetPortalProvider
-              CustomPortalContext={DialogPortalContext}
-            >
-              <BottomSheetModal
-                CustomPortalContext={DialogPortalContext}
-                showModal={showDialogModal}
-                setShowModal={setShowDialogModal}
-                snapPoints={[30]}
-              >
-                <View style={{ padding: 20 }}>
-                  <Text>Dialog-level modal</Text>
-                </View>
-              </BottomSheetModal>
-            </BottomSheetPortalProvider>
-          </View>
-        </BottomSheetModal>
-      </View>
-    </BottomSheetPortalProvider>
-  );
+  return <Layout padding={[2, 4]}>{/* render apps */}</Layout>;
 }
 ```
 
-## Performance Best Practices
-
-1. **Use `useImperativeHandle` pattern**: This package follows the render isolation pattern to prevent parent re-renders when animating
-
-2. **Optimize heavy content**: Use `showContentDelay` with `type: 'mount'` for complex UIs:
-
-   ```tsx
-   <BottomSheetModal
-     showContentDelay={{ type: 'mount', timeInMilliSecs: 100 }}
-     contentContainerStyle={{ minHeight: 400 }}
-   >
-     <ComplexComponent />
-   </BottomSheetModal>
-   ```
-
-3. **Memoize callbacks**: Use `useCallback` for callbacks to prevent unnecessary re-renders:
-
-   ```tsx
-   const handleSnapPoint = useCallback((index: number) => {
-     console.log('Snap point:', index);
-   }, []);
-   ```
-
-4. **Keep snap points stable**: Define snap points outside the component or use `useMemo`:
-   ```tsx
-   const snapPoints = useMemo(() => [30, 60, 90], []);
-   ```
-
-## Common Patterns
-
-### Confirmation Dialog
+### Global sheet driven from a store
 
 ```tsx
-function ConfirmDialog() {
-  const [show, setShow] = useState(false);
+export default function UploadMaterialModal() {
+  const ref = useRef<BottomModalRef>(null);
+  const setUploadModalRef = useApp((state) => state.setUploadModalRef);
+  useEffect(() => {
+    setUploadModalRef(ref);
+  }, [ref.current]);
+  const { colors, mode } = useTheme();
 
   return (
-    <BottomSheetModal
-      showModal={show}
-      setShowModal={setShow}
-      snapPoints={[30]}
-      contentContainerStyle={{ padding: 20 }}
+    <SmoothBottomModal
+      ref={ref}
+      disablePortal
+      dragArea="full"
+      snapPoints={[90]}
+      backgroundColor={colors.background[mode]}
     >
-      <Text style={{ fontSize: 18, marginBottom: 20 }}>Are you sure?</Text>
-      <View style={{ flexDirection: 'row', gap: 10 }}>
-        <Button title="Cancel" onPress={() => setShow(false)} />
-        <Button title="Confirm" onPress={handleConfirm} />
-      </View>
-    </BottomSheetModal>
+      <UploadMaterialModalContent />
+    </SmoothBottomModal>
   );
 }
 ```
 
-### Selection List
+Mount it once near the app root. Anything can open it via the stored ref.
+
+### Selection sheet with state owned by the screen
 
 ```tsx
-function SelectionList() {
-  const [show, setShow] = useState(false);
+function ChooseFlashcardsContent(props: ChooseFlashcardsProps) {
+  const t = useTranslation();
 
   return (
-    <BottomSheetModal
-      showModal={show}
-      setShowModal={setShow}
-      snapPoints={[50, 80]}
-    >
-      <BottomSheetFlatlist
-        data={options}
-        renderItem={({ item }) => (
-          <TouchableOpacity onPress={() => handleSelect(item)}>
-            <Text style={{ padding: 15 }}>{item.label}</Text>
-          </TouchableOpacity>
-        )}
+    <>
+      <SelectFlashcardSetsList
+        selectedFlashcardSets={props.selectedFlashcards}
+        setSelectedFlashcardSets={props.setSelectedFlashcards}
+        searchBar
       />
-    </BottomSheetModal>
+      <PrimaryButton
+        disabled={props.selectedFlashcards.length === 0}
+        onPress={() => {
+          props.onFlashcardSelect(props.selectedFlashcards);
+          props.setToggled(false);
+        }}
+      >
+        {t('confirm')}
+      </PrimaryButton>
+    </>
   );
 }
 ```
 
-### Filter Panel
+Selection survives close and reopen because the screen holds it.
 
-```tsx
-function FilterPanel() {
-  const [show, setShow] = useState(false);
-
-  return (
-    <BottomSheet
-      keepMounted={true}
-      bottomOffset={100}
-      snapPoints={[10, 70]}
-      showModal={show}
-      setShowModal={setShow}
-    >
-      <BottomSheetScrollView>
-        <FilterOptions />
-      </BottomSheetScrollView>
-    </BottomSheet>
-  );
-}
-```
-
-### Toast Notification (Using Portal)
+### Closing before navigating
 
 ```tsx
-import { useBottomSheetPortalComponent } from '@shaquillehinds/react-native-bottom-sheet';
-
-function useToast() {
-  const [message, setMessage] = useState('');
-  const [visible, setVisible] = useState(false);
-
-  useBottomSheetPortalComponent({
-    name: 'toast',
-    Component: visible ? (
-      <Animated.View
-        entering={SlideInDown}
-        exiting={SlideOutUp}
-        style={{
-          position: 'absolute',
-          top: 50,
-          alignSelf: 'center',
-          backgroundColor: '#333',
-          padding: 15,
-          borderRadius: 8,
-        }}
-      >
-        <Text style={{ color: 'white' }}>{message}</Text>
-      </Animated.View>
-    ) : null,
-    disable: !visible,
-  });
-
-  const show = (msg: string) => {
-    setMessage(msg);
-    setVisible(true);
-    setTimeout(() => setVisible(false), 3000);
-  };
-
-  return { show };
-}
-
-// Usage
-function MyComponent() {
-  const toast = useToast();
-
-  return <Button title="Show Toast" onPress={() => toast.show('Hello!')} />;
-}
+ref.current?.closeModal({
+  isNavigating: true,
+  onClose: () => navigation.navigate('NextScreen'),
+});
 ```
 
-### Loading Overlay (Using Portal)
-
-```tsx
-import { useBottomSheetPortalComponent } from '@shaquillehinds/react-native-bottom-sheet';
-
-function useLoadingOverlay() {
-  const [isLoading, setIsLoading] = useState(false);
-
-  useBottomSheetPortalComponent({
-    name: 'loading-overlay',
-    Component: isLoading ? (
-      <View
-        style={{
-          ...StyleSheet.absoluteFillObject,
-          backgroundColor: 'rgba(0, 0, 0, 0.5)',
-          justifyContent: 'center',
-          alignItems: 'center',
-        }}
-      >
-        <ActivityIndicator size="large" color="#fff" />
-      </View>
-    ) : null,
-    disable: !isLoading,
-  });
-
-  return { setIsLoading };
-}
+Or skip the animation entirely with `skipAnimation: true`.
 
-// Usage
-function MyComponent() {
-  const { setIsLoading } = useLoadingOverlay();
-
-  const handleSubmit = async () => {
-    setIsLoading(true);
-    await api.submit();
-    setIsLoading(false);
-  };
-
-  return <Button title="Submit" onPress={handleSubmit} />;
-}
-```
+---
 
 ## Troubleshooting
 
-### Modal doesn't appear
+**Sheet does not appear.** Check the Reanimated Babel plugin is installed and last
+in the list, and that `BottomSheetPortalProvider` is mounted at the app root.
 
-Ensure you've set up React Native Reanimated and Gesture Handler properly:
+**Sheet renders behind navigation.** The provider is too low in the tree. It must
+wrap `NavigationContainer`, not sit inside it.
 
-```tsx
-// babel.config.js
-module.exports = {
-  presets: ['module:metro-react-native-babel-preset'],
-  plugins: ['react-native-reanimated/plugin'],
-};
-```
-
-**Also verify `BottomSheetPortalProvider` is set up at your app root:**
+**Sheet opens collapsed or very short.** Using `showContentDelay: { type: 'mount' }`
+without `snapPoints` or a `minHeight` on `contentContainerStyle`. There is nothing
+to measure at open time.
 
-```tsx
-// App.tsx
-import { BottomSheetPortalProvider } from '@shaquillehinds/react-native-bottom-sheet';
+**Scrolling and dragging fight each other.** Swap the bare `FlatList` / `ScrollView`
+for `BottomSheetFlatlist` / `BottomSheetScrollView`, and drop `dragArea="full"`.
 
-export default function App() {
-  return (
-    <BottomSheetPortalProvider>
-      <YourNavigator />
-    </BottomSheetPortalProvider>
-  );
-}
-```
+**Drag down still dismisses despite `keepMounted`.** `keepMounted` has no effect
+without `snapPoints`.
 
-### Modal appears behind navigation or other elements
+**Sheet cannot be dragged.** Either `dragArea="none"`, or `hideBumper` combined
+with the default `dragArea="bumper"`, or the keyboard is open — dragging is
+disabled while it is, unless `allowDragWhileKeyboardVisible` is set.
 
-This typically means the portal provider is not at a high enough level in your component tree. The provider should wrap your navigation container:
+**Content flickers or unmounts early.** Increase `unMountBufferTimeMS` on the
+provider.
 
-```tsx
-// ✅ Correct - Provider wraps navigation
-<BottomSheetPortalProvider>
-  <NavigationContainer>
-    <Stack.Navigator>
-      {/* screens */}
-    </Stack.Navigator>
-  </NavigationContainer>
-</BottomSheetPortalProvider>
+**Sheet is slow to open.** Move state into a `*Content` component and add
+`showContentDelay={{ type: 'mount', timeInMilliSecs: 250 }}`.
 
-// ❌ Incorrect - Provider inside navigation
-<NavigationContainer>
-  <BottomSheetPortalProvider>
-    <Stack.Navigator>
-      {/* screens */}
-    </Stack.Navigator>
-  </BottomSheetPortalProvider>
-</NavigationContainer>
-```
+**Screen feels sluggish even with sheets closed.** Hooks are sitting in a sheet
+wrapper's function body. Move them into the content component.
 
-### Portal content flickers or unmounts unexpectedly
+---
 
-Adjust the `unMountBufferTimeMS` prop on the provider:
+## AI agent rules
 
-```tsx
-<BottomSheetPortalProvider unMountBufferTimeMS={200}>
-  <YourApp />
-</BottomSheetPortalProvider>
-```
+The package ships a rules file written for AI coding agents (Claude Code, Cursor,
+Codex, Copilot, etc.) at `rules/AGENT_RULES.md`. It tells an agent to keep sheet
+state in a separate content component so nothing loads until the sheet is opened,
+to reach for `BottomSheetFlatlist` / `BottomSheetScrollView` instead of raw
+scrollables, and it lists every prop and ref method so it cannot invent APIs or
+fall back to patterns from a different bottom sheet library. Point your agent at
+it with any of the following.
 
-### Scrolling issues
+**Copy it into your project (recommended)**
 
-Always use `BottomSheetFlatlist` or `BottomSheetScrollView` for scrollable content inside the bottom sheet.
+```sh
+npx rnbs-rules            # writes ./AGENTS.md
+npx rnbs-rules cursor     # writes ./.cursor/rules/react-native-bottom-sheet.mdc (alwaysApply)
+npx rnbs-rules claude     # writes ./.claude/rules/react-native-bottom-sheet.md
+npx rnbs-rules codex      # writes ./.codex/rules/react-native-bottom-sheet.md
+npx rnbs-rules copilot    # writes ./.github/instructions/react-native-bottom-sheet.instructions.md
+npx rnbs-rules windsurf   # writes ./.windsurf/rules/react-native-bottom-sheet.md
+npx rnbs-rules docs/ai/bottom-sheet.md   # custom path
+```
 
-### Keyboard issues
+Add `--force` to overwrite an existing file. `--print` writes the rules to stdout
+instead of to disk. Re-run after upgrading the package to pick up rule changes.
 
-Use `avoidKeyboard` or `inputsForKeyboardToAvoid` props and ensure inputs have proper refs.
+**Reference it without copying (Claude Code)**
 
-### Android navigation glitches
+`CLAUDE.md` supports `@path` imports, so a single line keeps the rules in sync with
+the installed version:
 
-Use `isNavigating` or `skipAnimation` when closing before navigation:
+```md
+# CLAUDE.md
 
-```tsx
-bottomSheetRef.current?.closeModal({
-  isNavigating: true,
-  onClose: () => navigation.navigate('NextScreen'),
-});
+@node_modules/@shaquillehinds/react-native-bottom-sheet/rules/AGENT_RULES.md
 ```
 
-## Dependencies
-
-- `react-native-reanimated` ^3.0.0
-- `react-native-gesture-handler` ^2.0.0
-- `@shaquillehinds/react-native-essentials` ^1.8.0
+**Reference it from a generic `AGENTS.md`**
 
-## Contributing
+```md
+Before writing any bottom sheet, read and follow
+node_modules/@shaquillehinds/react-native-bottom-sheet/rules/AGENT_RULES.md.
+```
 
-Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+---
 
 ## License
 
 MIT © [Shaquille Hinds](https://github.com/shaquillehinds)
-
-## Author
-
-**Shaquille Hinds**
-
-- GitHub: [@shaquillehinds](https://github.com/shaquillehinds)
-- Email: shaqdulove@gmail.com
-
-## Related Packages
-
-- [@shaquillehinds/react-native-essentials](https://www.npmjs.com/package/@shaquillehinds/react-native-essentials) - Essential utilities and components for React Native
-
-## Changelog
-
-See [Releases](https://github.com/shaquillehinds/react-native-bottom-sheet/releases) for version history.
-
-## Support
-
-If you encounter any issues or have questions:
-
-- Open an issue on [GitHub](https://github.com/shaquillehinds/react-native-bottom-sheet/issues)
-- Check existing issues for solutions
-- Review the examples in this README
-
-## Acknowledgments
-
-Built with React Native Reanimated and Gesture Handler for optimal performance and smooth interactions.