react-native-snap-sheet 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anthony
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# react-native-snap-sheet

package/index.js

@@ -0,0 +1,9 @@
+import { SnapSheetProvider } from "./src/provider";
+import SnapSheet from "./src/snapsheet";
+import { SnapSheetModal } from "./src/snapsheet_modal";
+
+export {
+    SnapSheet,
+    SnapSheetModal,
+    SnapSheetProvider
+};

package/index.ts

@@ -0,0 +1,256 @@
+import * as React from "react";
+import { StyleProp, ViewStyle } from "react-native";
+
+export interface SnapSheetBaseProps {
+    /**
+     * Child content inside the snap sheet
+     */
+    children?: React.ReactNode;
+
+    /**
+     * Called when snapping begins or index changes
+     */
+    onSnapIndex?: (index: number) => void;
+
+    /**
+     * Called when snapping animation fully finishes
+     */
+    onSnapFinish?: (index: number) => void;
+
+    /**
+     * If enabled, the sheet will snap to the nearest previous snap point
+     * (instead of jumping directly to index 0) while the gesture is decelerating.
+     * 
+     * @default false
+     */
+    snapWhileDecelerating?: boolean;
+
+    /**
+     * Style applied to the sheet
+     */
+    style?: StyleProp<ViewStyle>;
+
+    /**
+     * Whether the sheet should transfer its remaining downward drag velocity to a child scroll view when expanding.
+     * 
+     * @default false
+     */
+    inheritScrollVelocityOnExpand?: boolean;
+
+    /**
+     * Whether the sheet should inherit the remaining upward scroll velocity from a child scroll view when collapsing.
+     * 
+     * @default false
+     */
+    inheritScrollVelocityOnCollapse?: boolean;
+
+    /**
+     * Function to render the sheet handle (top drag indicator)
+     * 
+     * this is not used if `centered` is true
+     */
+    renderHandle?: React.ReactNode | (() => React.ReactNode);
+
+    /**
+     * Color of the sheet handle
+     */
+    handleColor?: string | undefined;
+
+    /**
+     * Behaviour for avoiding keyboard overlap
+     * - "off" → disables keyboard dodging
+     * - "optimum" → intelligently lift only needed amount
+     * - "whole" → move entire sheet above keyboard
+     * 
+     * `react-native-dodge-keyboard` is used for keyboard dodging and automatic tag detection for scrollable and input components.
+     *
+     * By default, the known scrollable tags are:
+     *  - "ScrollView"
+     *  - "FlatList"
+     *  - "SectionList"
+     *  - "VirtualizedList"
+     *
+     * If you want a custom scrollable element to support dodging,
+     * add the prop: `dodge_keyboard_scrollable={true}`.
+     *
+     * By default, "TextInput" is the only known input tag.
+     * To enable dodging for a custom input element,
+     * add the prop: `dodge_keyboard_input={true}`.
+     * 
+     * Input elements or views with dodge_keyboard_input={true} that are not inside a scrollable view must be manually lifted by responding to the `onHandleDodging` callback.
+     * 
+     * @default 'optimum'
+     */
+    keyboardDodgingBehaviour?: "off" | "optimum" | "whole";
+
+    /**
+     * Additional offset to add when dodging keyboard
+     * 
+     * @default 10
+     */
+    keyboardDodgingOffset?: number;
+}
+
+export interface SnapSheetProps extends SnapSheetBaseProps {
+    /**
+     * List of snap point heights (e.g. [0, 300, 600])
+     */
+    snapPoints?: number[];
+
+    /**
+     * The snap index to start from on initial mount
+     * 
+     * @default 0
+     */
+    initialSnapIndex?: number;
+
+    /**
+     * Disable user interactions on the snap sheet
+     * 
+     * @default false
+     */
+    disabled?: boolean;
+}
+
+export interface SnapSheetRef {
+    /**
+     * snap to an index
+     * @param index index to snap to
+     */
+    snap(index: number): void;
+}
+
+export declare const SnapSheet: React.ForwardRefExoticComponent<
+    React.PropsWithoutRef<SnapSheetProps> &
+    React.RefAttributes<SnapSheetRef | undefined>
+>;
+
+
+// <------- SnapSheetModal ------>
+
+export type SnapSheetModalState = "closed" | "middle" | "opened";
+
+export interface SnapSheetModalProps extends SnapSheetBaseProps {
+    /**
+     * Called when the sheet fully opens
+     */
+    onOpened?: () => void;
+
+    /**
+     * Called when the sheet fully closes
+     */
+    onClosed?: () => void;
+
+    /**
+     * Height when fully opened
+     * 
+     * this is not needed if `centered` is true
+     */
+    modalHeight: number;
+
+    /**
+     * Height of "middle" snap point
+     * 
+     * this is not used if `centered` is true
+     */
+    middleHeight: number;
+
+    /**
+     * Initial state of the modal
+     * 
+     * @default 'closed'
+     */
+    initialState?: SnapSheetModalState;
+
+    /**
+     * Called when the sheet transitions to a new state
+     */
+    onStateChanged?: (state: SnapSheetModalState) => void;
+
+    /**
+     * Optional backdrop renderer (e.g. dim overlay)
+     */
+    renderBackDrop?: React.ReactNode | (() => React.ReactNode);
+
+    /**
+     * Disable backdrop press
+     * 
+     * @default false
+     */
+    disableBackdrop?: boolean;
+
+    /**
+     * If true, modal can cover the whole screen area.
+     * 
+     * setting this to `true` requires you to add `<SafeAreaProvider>` at the top of your App.js file
+     * 
+     * @default false
+     */
+    fillScreen?: boolean;
+
+    /**
+     * When true, the children are unmounted when sheet is closed
+     * 
+     * @default true
+     */
+    unMountChildrenWhenClosed?: boolean;
+
+    /**
+     * Style applied to the modal container (not the snap sheet)
+     */
+    containerStyle?: StyleProp<ViewStyle>;
+
+    /**
+     * Enable back button press handler when the modal is opened
+     * 
+     * @default false
+     */
+    disableBackHandler?: boolean;
+
+    /**
+     * Disable user interactions on the snap sheet including indirect actions such as backdrop press and back button press.
+     * 
+     * You can still control snap sheet programmatically via `ref.open()`, `ref.close()` or `ref.middleSnap()`
+     * 
+     * @default false
+     */
+    disabled?: boolean;
+
+    /**
+     * Disable pan gesture on the snap sheet while still retaining indirect actions such as backdrop press and back button press.
+     * 
+     * @default false
+     */
+    disablePanGesture?: boolean;
+
+    /**
+     * True to render children content at the center of the modal instead of the bottom
+     * 
+     * @default false
+     */
+    centered?: boolean;
+}
+
+export interface SnapSheetModalRef {
+    /**
+     * fully open the modal
+     */
+    open(): void;
+
+    /**
+     * close the modal
+     */
+    close(): void;
+
+    /**
+     * partially open the modal and snap to `middleHeight`
+     */
+    middleSnap(): void;
+}
+
+export declare const SnapSheetModal: React.ForwardRefExoticComponent<
+    React.PropsWithoutRef<SnapSheetModalProps> &
+    React.RefAttributes<SnapSheetModalRef | undefined>
+>;
+
+export declare const SnapSheetProvider: React.Component;

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "react-native-snap-sheet",
+  "version": "1.0.0",
+  "description": "",
+  "homepage": "https://github.com/deflexable/react-native-snap-sheet#readme",
+  "bugs": {
+    "url": "https://github.com/deflexable/react-native-snap-sheet/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deflexable/react-native-snap-sheet.git"
+  },
+  "license": "MIT",
+  "author": "Anthony",
+  "type": "module",
+  "types": "./index.d.ts",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "react-native-dodge-keyboard": "^1.0.1",
+    "react-native-push-back": "^1.0.0"
+  }
+}

package/src/provider.js

@@ -0,0 +1,83 @@
+import { createContext, useEffect, useMemo, useReducer, useRef, useState } from "react";
+import { SnapSheetModalBase } from "./snapsheet_modal";
+
+export const PortalContext = createContext();
+
+export const SnapSheetProvider = ({ children }) => {
+    const doUpdating = useRef();
+
+    return (
+        <PortalContext.Provider
+            value={{
+                updateModal: (...args) => doUpdating.current(...args)
+            }}>
+            <ModalShell doUpdating={doUpdating} />
+            {children}
+        </PortalContext.Provider>
+    );
+};
+
+const ModalShell = ({ doUpdating }) => {
+    const [portals, setPortals] = useReducer((prev, [key, shouldAdd]) => {
+        if (shouldAdd) {
+            if (prev.includes(key)) return prev;
+            return [...prev, key];
+        }
+        return prev.filter(v => v !== key);
+    }, []);
+
+    const callerMap = useRef({});
+    const hasMounted = useRef();
+    const pendingEvent = useRef([]);
+
+    useMemo(() => {
+        doUpdating.current = (...args) => {
+            if (hasMounted.current) {
+                const [key, props, ref] = args;
+                if (props) {
+                    if (callerMap.current[key]?.doUpdate) {
+                        callerMap.current[key].doUpdate({ props, ref });
+                    } else {
+                        const willMount = !!callerMap.current[key];
+
+                        callerMap.current[key] = {
+                            initState: { props, ref },
+                            onMounted: () => {
+                                callerMap.current[key].onMounted = undefined;
+                                callerMap.current[key].initState = undefined;
+                                if (willMount) callerMap.current[key].doUpdate({ props, ref });
+                            }
+                        };
+                        if (!willMount) setPortals([key, true]);
+                    }
+                } else {
+                    if (callerMap.current[key]) delete callerMap.current[key];
+                    setPortals([key]);
+                }
+            } else pendingEvent.current.push(args);
+        };
+    }, []);
+
+    useEffect(() => {
+        hasMounted.current = true;
+        pendingEvent.current.forEach(v => doUpdating.current(...v));
+        pendingEvent.current = [];
+    }, []);
+
+    return portals.map(p =>
+        <ModalShellItem
+            key={p}
+            caller={callerMap.current[p]} />
+    );
+}
+
+const ModalShellItem = ({ caller }) => {
+    const [state, setState] = useState(caller.initState);
+
+    useEffect(() => {
+        caller.doUpdate = setState;
+        caller.onMounted();
+    }, []);
+
+    return <SnapSheetModalBase ref={state.ref} {...state.props} />;
+}

package/src/snapsheet.js

@@ -0,0 +1,398 @@
+import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
+import { Animated, Keyboard, PanResponder, StyleSheet, useAnimatedValue, View } from "react-native";
+import DodgeKeyboard, { ReactHijacker } from "react-native-dodge-keyboard";
+import { doRendable, isNumber } from "./utils";
+import { styling } from "./styling";
+
+const PixelRate = 70 / 100; // 70ms to 100 pixels
+
+const SnapSheet = forwardRef(function SnapSheet({
+    snapPoints = [],
+    initialSnapIndex = 0,
+    onSnapIndex,
+    onSnapFinish,
+    snapWhileDecelerating = false,
+    style,
+    inheritScrollVelocityOnExpand,
+    inheritScrollVelocityOnCollapse,
+    renderHandle,
+    handleColor,
+    keyboardDodgingBehaviour = 'optimum', // off, whole
+    keyboardDodgingOffset = 10,
+    children,
+    disabled,
+    currentAnchorId,
+    __shaky_sheet
+}, ref) {
+    const isLift = keyboardDodgingBehaviour === 'whole';
+    const isOptimum = keyboardDodgingBehaviour === 'optimum';
+
+    if (!['optimum', 'whole', 'off'].includes(keyboardDodgingBehaviour))
+        throw `keyboardDodgingBehaviour must be any of ${['optimum', 'whole', 'off']} but got ${keyboardDodgingBehaviour}`;
+
+    useMemo(() => {
+        if (snapPoints.length < 2) throw new Error('snapPoints must have at least two items');
+        snapPoints.forEach((v, i, a) => {
+            if (typeof v !== 'number' || !isNumber(v))
+                throw new Error(`snapPoints must have a valid number but got ${v} at position ${i}`);
+            if (i !== a.length - 1 && v >= a[i + 1])
+                throw new Error(`snapPoints must be in accending order but got ${v} before ${a[i + 1]}`);
+        });
+        if (!Number.isInteger(initialSnapIndex) || initialSnapIndex < 0)
+            throw new Error(`initialSnapIndex should be a positive integer but got:${initialSnapIndex}`);
+        if (initialSnapIndex >= snapPoints.length) throw new Error(`initialSnapIndex is out of range`);
+    }, snapPoints);
+    const initSnapPoints = snapPoints;
+
+    const [scrollEnabled, setScrollEnabled] = useState(false);
+    const [dodgeOffset, setDodgeOffset] = useState(0);
+    const [requiredLift, setRequiredLift] = useState(0);
+    const [currentIndex, setCurrentIndex] = useState(initialSnapIndex);
+    const [finishedIndex, setFinishedIndex] = useState(initialSnapIndex);
+    const [prefferedAnchor, setPrefferedAnchor] = useState();
+
+    const extraLift = dodgeOffset && ((isOptimum ? dodgeOffset : isLift ? requiredLift : 0) || 0);
+
+    snapPoints = snapPoints.map(v => v + extraLift);
+    // console.log('sheetLifing:', { extraLift, dodgeOffset, requiredLift, initSnapPoints: `${initSnapPoints}`, snapPoints: `${snapPoints}` });
+    const MAX_HEIGHT = snapPoints.slice(-1)[0];
+
+    const snapTranslateValues = useMemo(() => snapPoints.map(h => MAX_HEIGHT - h), snapPoints);
+
+    const translateY = useAnimatedValue(snapTranslateValues[initialSnapIndex]);
+
+    /**
+     * @type {import("react").RefObject<{[key: string]: { ref: import('react-native').ScrollView, scrollY: 0, location: number[], anchorId: boolean }}>}
+     */
+    const scrollRefObj = useRef({});
+    const lastOffset = useRef(translateY._value);
+    const lastSnapIndex = useRef(initialSnapIndex);
+    const bottomFakePlaceholderRef = useRef();
+    const instantPrefferAnchor = useRef();
+    instantPrefferAnchor.current = prefferedAnchor;
+
+    const prevScrollY = useRef(0);
+    const prevTime = useRef(0);
+
+    const instantScrollEnabled = useRef(scrollEnabled);
+    instantScrollEnabled.current = scrollEnabled;
+
+    const updateKeyboardOffset = () => {
+        if (!isLift) {
+            setRequiredLift(0);
+            return;
+        }
+        const keyboardInfo = Keyboard.metrics();
+        if (keyboardInfo?.height && keyboardInfo.screenY) {
+            bottomFakePlaceholderRef.current.measureInWindow((x, y) => {
+                const remains = y - keyboardInfo.screenY;
+                setRequiredLift(Math.max(0, remains));
+            });
+        } else setRequiredLift(0);
+    }
+
+    useEffect(updateKeyboardOffset, [dodgeOffset, ...initSnapPoints]);
+
+    const getCurrentSnap = (draggingUpward) => {
+        const shownHeight = MAX_HEIGHT - translateY._value;
+        const currentSnapIndex = draggingUpward ? snapPoints.findIndex((v, i, a) => v <= shownHeight && (i === a.length - 1 || shownHeight < a[i + 1]))
+            : snapPoints.findIndex((v, i, a) => v >= shownHeight && (!i || shownHeight > a[i - 1]));
+
+        return currentSnapIndex;
+    }
+
+    const snapToIndex = (index, force, velocity, onFinish) => {
+        if (disabled && !force) return;
+
+        if (!Number.isInteger(index) || index < 0 || index > snapPoints.length - 1)
+            throw new Error(`invalid snap index:${index}, index must be within range 0 - ${snapPoints.length - 1}`);
+
+        const newY = snapTranslateValues[index];
+
+        if (__shaky_sheet && lastOffset.current !== newY)
+            translateY.setValue(lastOffset.current);
+
+        const prevY = translateY._value;
+        setScrollEnabled(index === snapPoints.length - 1);
+        setCurrentIndex(index);
+
+        // console.log('snapping:', index);
+        let wasFinished;
+        const guessFinish = () => {
+            if (wasFinished) return;
+            wasFinished = true;
+            onFinish?.();
+            onSnapFinish?.(index);
+        }
+        const pixel = Math.abs(prevY - newY);
+        const timeout = pixel * PixelRate;
+
+        const timer = setTimeout(guessFinish, Math.max(300, timeout));
+
+        // console.log('snapTimer:', { timeout, pixel });
+
+        Animated.spring(translateY, {
+            velocity,
+            toValue: newY,
+            useNativeDriver: true
+        }).start(() => {
+            clearTimeout(timer);
+            setFinishedIndex(index);
+            guessFinish();
+        });
+
+        lastOffset.current = newY;
+        lastSnapIndex.current = index;
+        onSnapIndex?.(index);
+    }
+
+    useImperativeHandle(ref, () => ({
+        snap: index => {
+            snapToIndex(index, true);
+        }
+    }), snapPoints);
+
+    useEffect(() => {
+        snapToIndex(Math.min(lastSnapIndex.current, snapPoints.length - 1), true);
+    }, snapPoints);
+
+    const panResponder = useMemo(() => {
+
+        return PanResponder.create({
+            onMoveShouldSetPanResponderCapture: (_, gesture) => {
+                const { scrollY } = scrollRefObj.current[instantPrefferAnchor.current] || {};
+
+                const shouldCapture = !disabled && (
+                    !instantScrollEnabled.current ||
+                    (scrollY <= 0 && gesture.dy > 1) // If sheet is expanded & ScrollView is at top → capture downward drags
+                );
+                // console.log('onMoveShouldSetPanResponderCapture shouldCapture:', shouldCapture, ' stats:', { gesture, scrollOffset: scrollY, instantScrollEnabled: instantScrollEnabled.current }, ' gesture.dy > 0:', gesture.dy > 1);
+                return shouldCapture;
+            },
+            onPanResponderMove: (_, gesture) => {
+                const newY = gesture.dy + lastOffset.current;
+
+                if (newY < 0) return; // prevent overscrolling upward
+                if (newY > MAX_HEIGHT) return;
+
+                translateY.setValue(newY);
+            },
+            onPanResponderRelease: (_, gesture) => {
+                const { dy, vy } = gesture; // when vy is lesser, it is scroll up
+                // console.log('onPanResponderRelease:', gesture);
+
+                const draggingUpward = vy <= 0;
+                const currentSnapIndex = getCurrentSnap(draggingUpward);
+
+                const newSnapIndex = Math.abs(dy) <= 30 ? currentSnapIndex :
+                    draggingUpward ? Math.min(snapPoints.length - 1, currentSnapIndex + 1) :
+                        snapWhileDecelerating ? Math.max(0, currentSnapIndex - 1) :
+                            vy > 0.3 ? 0 : currentSnapIndex;
+                const willFullyShow = newSnapIndex === snapPoints.length - 1;
+
+                snapToIndex(newSnapIndex, true, draggingUpward ? vy : undefined);
+
+                // Only scroll if there was a fling velocity upward
+                if (inheritScrollVelocityOnExpand && willFullyShow && vy < -0.1) {
+                    const newScrollY = Math.min(100, Math.max(0, -vy * 70)); // velocity → scroll inertia
+                    const ref = scrollRefObj.current[instantPrefferAnchor.current]?.ref;
+                    if (ref) {
+                        if (ref.scrollTo) {
+                            ref.scrollTo?.({ y: newScrollY, animated: true });
+                        } else if (ref.scrollToOffset) {
+                            ref.scrollToOffset?.({ offset: newScrollY, animated: true });
+                        } else {
+                            ref.getScrollResponder?.()?.scrollTo?.({ y: newScrollY, animated: true });
+                        }
+                    }
+                }
+            }
+        });
+    }, [!disabled, ...snapPoints]);
+
+    const conStyle = useMemo(() => ({
+        position: "absolute",
+        width: "100%",
+        backgroundColor: "#fff",
+        borderTopLeftRadius: 25,
+        borderTopRightRadius: 25,
+        zIndex: 1,
+        ...StyleSheet.flatten(style),
+        bottom: 0,
+        height: MAX_HEIGHT,
+        transform: [{ translateY }]
+    }), [MAX_HEIGHT, style]);
+
+    useEffect(() => updatePrefferAnchor, [currentAnchorId]);
+    const updateAnchorReducer = useRef();
+
+    const scheduleAnchorUpdate = (timeout = 100) => {
+        clearTimeout(updateAnchorReducer.current);
+        updateAnchorReducer.current = setTimeout(updatePrefferAnchor, timeout);
+    }
+
+    const updatePrefferAnchor = () => {
+        const rankedAnchors = Object.entries(scrollRefObj.current).sort((a, b) => compareReactPaths(a[1].location, b[1].location));
+        const directAnchor = rankedAnchors.find(v => v[1].anchorId === currentAnchorId);
+        if (directAnchor) return setPrefferedAnchor(directAnchor[0]);
+
+        const normalAnchor = rankedAnchors.find(v => !!v[1].anchorId);
+        if (normalAnchor) return setPrefferedAnchor(normalAnchor[0]);
+        setPrefferedAnchor(rankedAnchors[0]?.[0]);
+    }
+
+    const onAnchorScroll = (e, instanceId) => {
+        const scrollY = e.nativeEvent.contentOffset.y;
+        if (scrollRefObj.current[instanceId])
+            scrollRefObj.current[instanceId].scrollY = scrollY;
+
+        // console.log('onAnchorScroll scrollOffset:', scrollY);
+        if (!inheritScrollVelocityOnCollapse) {
+            prevScrollY.current = 0;
+            prevTime.current = 0;
+            return;
+        }
+        const now = Date.now();
+        let scrollVelocity = 0;
+
+        if (prevTime.current) {
+            const dy = scrollY - prevScrollY.current;
+            const dt = now - prevTime.current;
+
+            scrollVelocity = dt > 0 ? dy / dt : 0;
+        }
+
+        prevScrollY.current = scrollY;
+        prevTime.current = now;
+
+        // Handoff: ScrollView tries to overscroll upward
+        if (instantScrollEnabled.current && scrollY <= 0 && scrollVelocity < 0) {
+            instantScrollEnabled.current = false;
+
+            const currentSnapIndex = getCurrentSnap(false);
+            const newSnapIndex = snapWhileDecelerating ? Math.max(0, currentSnapIndex - 1) : 0;
+            snapToIndex(newSnapIndex, false, -scrollVelocity);
+        }
+    }
+
+    const handleDotStyle = useMemo(() => ({
+        ...styling.modalHandleItem,
+        ...handleColor ? { backgroundColor: handleColor } : {}
+    }), [handleColor]);
+
+    const disableDodging = keyboardDodgingBehaviour === 'off';
+    const sameIndex = currentIndex === finishedIndex;
+
+    return (
+        <View style={styling.absoluteFill}>
+            <Animated.View
+                style={conStyle}
+                {...panResponder.panHandlers}>
+                {doRendable?.(
+                    renderHandle,
+                    <View style={styling.modalHandle}>
+                        <View style={handleDotStyle} />
+                    </View>
+                )}
+                <View style={styling.flexer}>
+                    <DodgeKeyboard
+                        offset={keyboardDodgingOffset}
+                        disabled={!sameIndex || disableDodging}
+                        onHandleDodging={({ liftUp }) => {
+                            setDodgeOffset(liftUp);
+                        }}>
+                        {ReactHijacker({
+                            children,
+                            doHijack: (node, path) => {
+                                if (node?.props?.['snap_sheet_scan_off']) return { element: node };
+
+                                if (isScrollable(node)) {
+                                    const instanceId = path.join(',');
+
+                                    const initNode = () => {
+                                        if (!scrollRefObj.current[instanceId])
+                                            scrollRefObj.current[instanceId] = { scrollY: 0, location: path };
+                                        const thisAnchorId = node.props?.snap_sheet_scroll_anchor;
+
+                                        if (scrollRefObj.current[instanceId].anchorId !== thisAnchorId) {
+                                            scheduleAnchorUpdate(300);
+                                        }
+                                        scrollRefObj.current[instanceId].anchorId = thisAnchorId;
+                                    }
+                                    initNode();
+
+                                    return {
+                                        props: {
+                                            ...node?.props,
+                                            ...disableDodging ? {} : { ['dodge_keyboard_scrollable']: true },
+                                            ref: r => {
+                                                if (r) {
+                                                    initNode();
+                                                    // if (scrollRefObj.current[instanceId].ref !== r) scheduleAnchorUpdate();
+                                                    scrollRefObj.current[instanceId].ref = r;
+                                                } else if (scrollRefObj.current[instanceId]) {
+                                                    delete scrollRefObj.current[instanceId];
+                                                    scheduleAnchorUpdate();
+                                                }
+
+                                                const thatRef = node.props?.ref;
+                                                if (typeof thatRef === 'function') {
+                                                    thatRef(r);
+                                                } else if (thatRef) thatRef.current = r;
+                                            },
+                                            ...prefferedAnchor === instanceId ? { scrollEnabled } : {},
+                                            onScroll: (e) => {
+                                                onAnchorScroll(e, instanceId);
+                                                return node.props?.onScroll?.(e);
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        })}
+                    </DodgeKeyboard>
+                </View>
+            </Animated.View>
+            {isLift ?
+                <View
+                    ref={bottomFakePlaceholderRef}
+                    style={styling.fakePlaceholder}
+                    onLayout={updateKeyboardOffset} /> : null}
+        </View>
+    );
+});
+
+const isScrollable = (element, disableTagCheck) => {
+    if (element?.props?.['snap_sheet_scroll_anchor']) return true;
+    if (!element?.type || element?.props?.horizontal || disableTagCheck) return false;
+
+    const scrollableTypes = ["ScrollView", "FlatList", "SectionList", "VirtualizedList"];
+
+    return scrollableTypes.includes(element.type.displayName)
+        || scrollableTypes.includes(element.type?.name);
+};
+
+function extractPath(entry) {
+    return entry.filter(v => typeof v === 'number');
+}
+
+// lexicographic comparison of two paths
+function compareReactPaths(a, b) {
+    const pa = extractPath(a);
+    const pb = extractPath(b);
+
+    const len = Math.max(pa.length, pb.length);
+
+    for (let i = 0; i < len; i++) {
+        const av = pa[i];
+        const bv = pb[i];
+
+        if (av === undefined) return -1;  // a ends early -> comes first
+        if (bv === undefined) return 1;   // b ends early -> comes first
+
+        if (av !== bv) return av - bv;    // normal numeric comparison
+    }
+    return 0;
+}
+
+export default SnapSheet;

package/src/snapsheet_modal.js

@@ -0,0 +1,302 @@
+import { forwardRef, useContext, useEffect, useImperativeHandle, useMemo, useReducer, useRef, useState } from "react";
+import { Pressable, StyleSheet, View } from "react-native";
+import { isDodgeInput, ReactHijacker } from "react-native-dodge-keyboard";
+import { useBackButton } from "react-native-push-back";
+import { doRendable, isNumber } from "./utils";
+import { PortalContext } from "./provider";
+import { styling } from "./styling";
+
+const ModalState = ['closed', 'middle', 'opened'];
+const CenteredSheetStyle = { width: 0 };
+
+export const SnapSheetModalBase = forwardRef(function SnapSheetModalBase({
+    onOpened,
+    onClosed,
+    modalHeight,
+    middleHeight,
+    initialState = 'closed',
+    centered,
+    onStateChanged,
+    renderBackDrop,
+    disableBackdrop,
+    fillScreen = true,
+    unMountChildrenWhenClosed = true,
+    disableBackHandler,
+    containerStyle,
+    disabled,
+    disablePanGesture,
+    children,
+    ...restProps
+}, ref) {
+    centered = !!centered;
+    useMemo(() => {
+        if (centered) {
+            if (modalHeight) console.warn('modalHeight is not needed if centered={true}');
+            if (middleHeight) console.warn('middleHeight is not needed if centered={true}');
+        }
+    }, [centered]);
+
+    if (centered) {
+        middleHeight = undefined;
+        if (initialState === 'middle') initialState = 'opened';
+    }
+
+    const initialSnapIndex = ModalState.indexOf(initialState);
+    if (initialSnapIndex === -1)
+        throw `initialState must be any of ${initialState} but got ${initialState}`;
+    const hasMiddle = isNumber(middleHeight);
+
+    if (!hasMiddle && initialState === 'middle')
+        throw `middleHeight is required if initialState is "middle"`;
+
+    const [futureState, setFutureState] = useState(initialState);
+    const [currentState, setCurrentState] = useState(initialState);
+    const [autoIndexModal, setAutoIndexModal] = useState(initialSnapIndex);
+    const [viewDim, setViewDim] = useReducer((prev, incoming) => {
+        if (!incoming.some((v, i) => prev[i] !== v)) return prev;
+        return incoming;
+    }, [undefined, undefined]);
+    const [contentHeight, setContentHeight] = useState();
+    const [releaseUnmount, setReleaseUnmount] = useState();
+    const [viewWidth, viewHeight] = viewDim;
+
+    const sizingReadyCaller = useRef({ promise: undefined, callback: undefined });
+    const makeSizingPromise = () => {
+        if (centered)
+            sizingReadyCaller.current.promise = new Promise(resolve => {
+                sizingReadyCaller.current.callback = resolve;
+            });
+    }
+
+    useMemo(makeSizingPromise, []);
+
+    const sizingReady = !centered || (contentHeight !== undefined && viewHeight !== undefined);
+
+    useEffect(() => {
+        if (sizingReady) {
+            sizingReadyCaller.current.callback?.();
+            sizingReadyCaller.current.callback = undefined;
+        } else if (!sizingReadyCaller.current.callback) {
+            makeSizingPromise();
+        }
+    }, [sizingReady]);
+
+    const unmountChild = !!(hasClosed && unMountChildrenWhenClosed);
+    useEffect(() => {
+        if (unmountChild && centered) setContentHeight();
+    }, [unmountChild, !centered]);
+
+    const snapPoints = useMemo(() => {
+        if (centered) {
+            if (sizingReady)
+                return [-(contentHeight / 2), viewHeight / 2];
+            return [0, .3];
+        } else return [0, ...isNumber(middleHeight) ? [middleHeight] : [], modalHeight];
+    }, [viewHeight, contentHeight, centered, middleHeight, modalHeight]);
+
+    const willClose = futureState === 'closed';
+    const isOpened = futureState !== 'closed';
+    const hasClosed = futureState === 'closed' && currentState === 'closed';
+
+    const sheetRef = useRef();
+    const inputRefs = useRef({});
+    const snapModal = useRef();
+
+    snapModal.current = async (index, force) => {
+        if (sizingReadyCaller.current.callback) {
+            if (index && unMountChildrenWhenClosed && !releaseUnmount)
+                setReleaseUnmount(true);
+            await sizingReadyCaller.current.promise;
+        }
+
+        if (disabled && !force) return;
+        if (index && !sheetRef.current && !autoIndexModal) {
+            setAutoIndexModal(index);
+        } else if (sheetRef.current) {
+            sheetRef.current.snap(index);
+        }
+    }
+
+    useImperativeHandle(ref, () => ({
+        open: () => snapModal.current(hasMiddle ? 2 : 1, true),
+        close: () => snapModal.current(0, true),
+        middleSnap: () => {
+            if (!hasMiddle) throw 'calling middleSnap() requires middleHeight to be defined in the ref component';
+            snapModal.current(1, true);
+        }
+    }));
+
+    const hasMountAutoIndex = useRef();
+    useEffect(() => {
+        if (hasMountAutoIndex.current) {
+            if (autoIndexModal) snapModal.current(autoIndexModal, true);
+        }
+        hasMountAutoIndex.current = true;
+    }, [!autoIndexModal]);
+
+    useEffect(() => {
+        if (willClose)
+            try {
+                Object.values(inputRefs.current).forEach(e => {
+                    if (e?.isFocused?.()) e?.blur?.();
+                });
+            } catch (error) {
+                console.error('snapSheet remove auto-blur err', error);
+            }
+    }, [willClose]);
+
+    const hasMountState = useRef();
+    useEffect(() => {
+        if (futureState !== currentState) return;
+        if (hasMountState.current) {
+            onStateChanged?.(futureState);
+        }
+        hasMountState.current = true;
+    }, [futureState, currentState]);
+
+    const hasMountOpened = useRef();
+    useEffect(() => {
+        if (futureState !== currentState) return;
+        if (hasClosed) setAutoIndexModal(0);
+        if (hasMountOpened.current)
+            if (hasClosed) {
+                setReleaseUnmount();
+                onClosed?.();
+            } else onOpened?.();
+        hasMountOpened.current = true;
+    }, [hasClosed]);
+
+    useBackButton(() => {
+        snapModal.current(0);
+    }, disableBackHandler || !isOpened);
+
+    const centeredStyle = useMemo(() => centered ? ({
+        position: 'absolute',
+        width: viewWidth || 0,
+        left: 0,
+        top: 0,
+        marginTop: -(contentHeight / 2) || 0
+    }) : undefined, [centered, contentHeight, viewWidth]);
+
+    const renderChild = () =>
+        <View
+            style={styling.absoluteFill}
+            onLayout={e => {
+                const { width, height } = e.nativeEvent.layout;
+                setViewDim([width, height]);
+            }}>
+            {hasClosed ? null :
+                doRendable(
+                    renderBackDrop,
+                    <Pressable
+                        style={styling.backdropStyle}
+                        disabled={!!disableBackdrop}
+                        onPress={() => {
+                            snapModal.current(0);
+                        }} />
+                )}
+            <ReactHijacker
+                doHijack={(node, path) => {
+                    if (isDodgeInput(node)) {
+                        const inputId = path.join('=>');
+
+                        return {
+                            props: {
+                                ...node.props,
+                                ref: r => {
+                                    if (r) {
+                                        inputRefs.current[inputId] = r;
+                                    } else if (inputRefs.current[inputId]) {
+                                        delete inputRefs.current[inputId];
+                                    }
+
+                                    const thatRef = node.props?.ref;
+                                    if (typeof thatRef === 'function') {
+                                        thatRef(r);
+                                    } else if (thatRef) thatRef.current = r;
+                                }
+                            }
+                        };
+                    }
+                }}>
+                <SnapSheet
+                    {...restProps}
+                    ref={sheetRef}
+                    snapPoints={snapPoints}
+                    {...hasClosed ? { keyboardDodgingBehaviour: 'off' } : {}}
+                    {...centered ? {
+                        style: CenteredSheetStyle,
+                        renderHandle: null
+                    } : {}}
+                    __shaky_sheet={centered}
+                    initialSnapIndex={Math.min(ModalState.indexOf(currentState), centered ? 1 : 2)}
+                    disabled={centered || disabled || disablePanGesture}
+                    onSnapFinish={i => {
+                        setCurrentState(ModalState[i]);
+                    }}
+                    onSnapIndex={i => {
+                        setFutureState(ModalState[i]);
+                    }}>
+                    {(hasClosed && (!releaseUnmount && unMountChildrenWhenClosed))
+                        ? null :
+                        <View style={centered ? centeredStyle : styling.flexer}>
+                            <View
+                                style={centered ? restProps.style : styling.flexer}
+                                onLayout={e => {
+                                    if (centered) setContentHeight(e.nativeEvent.layout.height);
+                                }}>
+                                {children}
+                            </View>
+                        </View>}
+                </SnapSheet>
+            </ReactHijacker>
+        </View>
+
+    const conStyle = useMemo(() => {
+        const flatStyle = StyleSheet.flatten(containerStyle);
+
+        return {
+            ...flatStyle,
+            position: 'absolute',
+            width: '100%',
+            height: '100%',
+            top: 0,
+            left: 0,
+            zIndex: hasClosed ? -99 : isNumber(flatStyle?.zIndex) ? flatStyle?.zIndex : 9999,
+            elevation: hasClosed ? 0 : isNumber(flatStyle?.elevation) ? flatStyle?.elevation : 9999,
+            ...hasClosed ? { opacity: 0 } : {}
+        };
+    }, [containerStyle, hasClosed]);
+
+    return (
+        <View style={conStyle}
+            pointerEvents={willClose ? 'none' : 'auto'}>
+            {renderChild()}
+        </View>
+    );
+});
+
+let mountIdIterator = 0;
+
+export const SnapSheetModal = forwardRef(function SnapSheetModal({
+    fillScreen,
+    ...props
+}, ref) {
+    const { updateModal } = useContext(PortalContext) || {};
+
+    const mountID = useMemo(() => ++mountIdIterator, []);
+
+    useEffect(() => {
+        if (fillScreen) updateModal(mountID, props, ref);
+    });
+
+    useEffect(() => {
+        if (fillScreen)
+            return () => {
+                updateModal(mountID);
+            }
+    }, [!fillScreen]);
+
+    if (fillScreen) return null;
+    return <SnapSheetModalBase ref={ref} {...props} />;
+});

package/src/styling.js

@@ -0,0 +1,39 @@
+
+
+export const styling = {
+    flexer: { flex: 1 },
+
+    modalHandle: {
+        alignItems: 'center',
+        justifyContent: 'center',
+        // backgroundColor: 'red',
+        paddingTop: 7,
+        paddingBottom: 7
+    },
+
+    modalHandleItem: {
+        width: 50,
+        height: 5,
+        backgroundColor: 'rgba(222, 222, 222, 1)',
+        borderRadius: 20
+    },
+
+    backdropStyle: {
+        position: 'absolute',
+        width: '100%',
+        height: '100%',
+        top: 0,
+        left: 0,
+        backgroundColor: 'rgba(0, 0, 0, 0.4)'
+    },
+
+    fakePlaceholder: { position: 'absolute', bottom: 0 },
+
+    absoluteFill: {
+        position: 'absolute',
+        width: '100%',
+        height: '100%',
+        left: 0,
+        top: 0
+    }
+};

package/src/utils.js

@@ -0,0 +1,4 @@
+
+export const doRendable = (e, d) => e === undefined ? d : typeof e === 'function' ? e() : e;
+
+export const isNumber = t => typeof t === 'number' && !isNaN(t) && Number.isFinite(t);