react-native-bottom-sheet-stack 1.9.2 → 1.10.0

package/src/adapters/react-native-modal/ReactNativeModalAdapter.tsx

@@ -1,6 +1,7 @@
 import React, { useImperativeHandle, useState } from 'react';
 
 import type { SheetAdapterRef } from '../../adapter.types';
+import { useSheetPreventDismiss } from '../../bottomSheet.store';
 import { createSheetEventHandlers } from '../../bottomSheetCoordinator';
 import { useAdapterRef } from '../../useAdapterRef';
 import { useAnimatedIndex } from '../../useAnimatedIndex';
@@ -34,6 +35,7 @@ export const ReactNativeModalAdapter = React.forwardRef<
   const { id } = useBottomSheetContext();
   const ref = useAdapterRef(forwardedRef);
   const animatedIndex = useAnimatedIndex();
+  const preventDismiss = useSheetPreventDismiss(id);
   const [isVisible, setIsVisible] = useState(false);
 
   const { handleDismiss, handleOpened, handleClosed } =
@@ -57,7 +59,7 @@ export const ReactNativeModalAdapter = React.forwardRef<
   return (
     <RNModal
       // Adapter defaults (overridable via spread)
-      swipeDirection="down"
+      swipeDirection={preventDismiss ? undefined : 'down'}
       useNativeDriver
       hideModalContentWhileAnimating
       {...modalProps}
@@ -71,7 +73,7 @@ export const ReactNativeModalAdapter = React.forwardRef<
       onModalShow={handleOpened}
       onModalHide={handleClosed}
       onBackButtonPress={handleDismiss}
-      onSwipeComplete={handleDismiss}
+      onSwipeComplete={preventDismiss ? undefined : handleDismiss}
     >
       {children}
     </RNModal>

package/src/bottomSheetCoordinator.ts

@@ -1,5 +1,6 @@
 import type { SheetAdapterEvents } from './adapter.types';
 import { useBottomSheetStore } from './bottomSheet.store';
+import { getOnBeforeClose } from './onBeforeCloseRegistry';
 import { getSheetRef } from './refsMap';
 
 /**
@@ -42,6 +43,126 @@ export function initBottomSheetCoordinator(groupId: string) {
   );
 }
 
+/**
+ * Attempts to close a sheet, respecting the onBeforeClose interceptor.
+ *
+ * If an onBeforeClose callback is registered for the sheet and it returns
+ * `false` (or resolves to `false`), the close is cancelled.
+ *
+ * @returns `true` if the close proceeded, `false` if it was intercepted.
+ */
+export async function requestClose(sheetId: string): Promise<boolean> {
+  const state = useBottomSheetStore.getState();
+  const currentStatus = state.sheetsById[sheetId]?.status;
+
+  // Don't run interceptor if sheet is already closing
+  // This prevents duplicate interceptor calls during close animations
+  if (currentStatus === 'closing') {
+    return false;
+  }
+
+  const interceptor = getOnBeforeClose(sheetId);
+
+  if (interceptor) {
+    try {
+      const allowed = await new Promise<boolean>((resolve) => {
+        const result = interceptor({
+          onConfirm: () => resolve(true),
+          onCancel: () => resolve(false),
+        });
+
+        if (result) {
+          if (typeof result === 'boolean') {
+            resolve(result);
+          } else if (
+            result &&
+            typeof result === 'object' &&
+            'then' in result &&
+            typeof result.then === 'function'
+          ) {
+            // It's a Promise
+            result.then(resolve);
+          }
+        }
+      });
+
+      if (!allowed) {
+        return false;
+      }
+    } catch (error) {
+      // If the interceptor throws, cancel the close for safety
+      if (__DEV__) {
+        console.warn(
+          `[BottomSheet] onBeforeClose interceptor threw an error for sheet "${sheetId}". ` +
+            'Close cancelled for safety. Fix the interceptor to avoid this warning.',
+          error
+        );
+      }
+      return false;
+    }
+  }
+
+  if (currentStatus === 'open' || currentStatus === 'opening') {
+    state.startClosing(sheetId);
+  }
+
+  return true;
+}
+
+/**
+ * Default stagger delay between cascading close animations (ms).
+ */
+const DEFAULT_STAGGER_MS = 100;
+
+/**
+ * Closes all sheets in a group from top to bottom with cascading animation.
+ *
+ * Each sheet is closed with a staggered delay so the user sees them
+ * peel off one-by-one (similar to `popToRoot` in React Navigation).
+ *
+ * If a sheet has an `onBeforeClose` interceptor that rejects, the cascade
+ * stops at that sheet — sheets below it remain open.
+ *
+ * @param groupId - The manager group to close sheets in.
+ * @param options.stagger - Delay in ms between each close (default: 100).
+ * @returns A promise that resolves when the cascade finishes (or is stopped).
+ */
+export async function closeAllAnimated(
+  groupId: string,
+  options?: { stagger?: number }
+): Promise<void> {
+  const stagger = options?.stagger ?? DEFAULT_STAGGER_MS;
+
+  const state = useBottomSheetStore.getState();
+  const groupSheetIds = state.stackOrder.filter(
+    (id) => state.sheetsById[id]?.groupId === groupId
+  );
+
+  // Close from top to bottom (reverse order)
+  const reversed = [...groupSheetIds].reverse();
+
+  for (const sheetId of reversed) {
+    const currentState = useBottomSheetStore.getState();
+    const sheet = currentState.sheetsById[sheetId];
+
+    // Skip sheets that are already closing or hidden
+    if (!sheet || sheet.status === 'closing' || sheet.status === 'hidden') {
+      continue;
+    }
+
+    const closed = await requestClose(sheetId);
+
+    if (!closed) {
+      // Interceptor blocked — stop the cascade
+      break;
+    }
+
+    if (stagger > 0 && reversed.indexOf(sheetId) < reversed.length - 1) {
+      await new Promise<void>((resolve) => setTimeout(resolve, stagger));
+    }
+  }
+}
+
 /**
  * Creates event handlers that adapters call to sync UI state back to the store.
  * Direction: Adapter Events → Store
@@ -53,6 +174,13 @@ export function initBottomSheetCoordinator(groupId: string) {
  */
 export function createSheetEventHandlers(sheetId: string): SheetAdapterEvents {
   const handleDismiss = () => {
+    const interceptor = getOnBeforeClose(sheetId);
+
+    if (interceptor) {
+      requestClose(sheetId);
+      return;
+    }
+
     const state = useBottomSheetStore.getState();
     const currentStatus = state.sheetsById[sheetId]?.status;
 

package/src/index.tsx

@@ -20,14 +20,21 @@ export type {
 } from './adapter.types';
 
 // Adapter utilities (for custom adapter authors)
-export { createSheetEventHandlers } from './bottomSheetCoordinator';
+export {
+  createSheetEventHandlers,
+  requestClose,
+  closeAllAnimated,
+} from './bottomSheetCoordinator';
 export { useAdapterRef } from './useAdapterRef';
 export { useAnimatedIndex } from './useAnimatedIndex';
 export { useBackHandler } from './useBackHandler';
 export { getAnimatedIndex, setAnimatedIndexValue } from './animatedRegistry';
 
 // Hooks
-export { useBottomSheetManager } from './useBottomSheetManager';
+export {
+  useBottomSheetManager,
+  type CloseAllOptions,
+} from './useBottomSheetManager';
 export {
   useBottomSheetControl,
   type UseBottomSheetControlReturn,
@@ -41,6 +48,7 @@ export {
   useBottomSheetStatus,
   type UseBottomSheetStatusReturn,
 } from './useBottomSheetStatus';
+export { useOnBeforeClose } from './useOnBeforeClose';
 
 // Types
 export type { ScaleConfig, ScaleAnimationConfig } from './useScaleAnimation';
@@ -57,6 +65,10 @@ export type {
 
 export { useBottomSheetStore } from './bottomSheet.store';
 
+// onBeforeClose registry
+export type { OnBeforeCloseCallback } from './onBeforeCloseRegistry';
+export { setOnBeforeClose, removeOnBeforeClose } from './onBeforeCloseRegistry';
+
 // Testing utilities (internal use)
 export { __resetSheetRefs } from './refsMap';
 export {
@@ -64,3 +76,4 @@ export {
   __getAllAnimatedIndexes,
 } from './animatedRegistry';
 export { __resetPortalSessions } from './portalSessionRegistry';
+export { __resetOnBeforeClose } from './onBeforeCloseRegistry';

package/src/onBeforeCloseRegistry.ts

@@ -0,0 +1,44 @@
+/**
+ * Registry for onBeforeClose interceptors.
+ *
+ * Callbacks are keyed by sheet ID. When a sheet is about to close,
+ * the coordinator checks this registry and calls the interceptor.
+ *
+ * The interceptor receives `onConfirm` and `onCancel` callbacks that
+ * should be called when the user makes a decision. Alternatively, it can
+ * return `boolean` or `Promise<boolean>` for backward compatibility.
+ *
+ * If the interceptor returns `false` (or resolves to `false`), or if
+ * `onCancel()` is called, the close is cancelled.
+ */
+export type OnBeforeCloseCallback = (context: {
+  onConfirm: () => void;
+  onCancel: () => void;
+}) => void | boolean | Promise<boolean>;
+
+const onBeforeCloseMap = new Map<string, OnBeforeCloseCallback>();
+
+export function getOnBeforeClose(
+  sheetId: string
+): OnBeforeCloseCallback | undefined {
+  return onBeforeCloseMap.get(sheetId);
+}
+
+export function setOnBeforeClose(
+  sheetId: string,
+  callback: OnBeforeCloseCallback
+): void {
+  onBeforeCloseMap.set(sheetId, callback);
+}
+
+export function removeOnBeforeClose(sheetId: string): void {
+  onBeforeCloseMap.delete(sheetId);
+}
+
+/**
+ * Reset all interceptors. Useful for testing.
+ * @internal
+ */
+export function __resetOnBeforeClose(): void {
+  onBeforeCloseMap.clear();
+}

package/src/store/hooks.ts

@@ -22,6 +22,11 @@ export const useSheetKeepMounted = (id: string) =>
   useBottomSheetStore((state) => state.sheetsById[id]?.keepMounted, shallow);
 export const useSheetPortalSession = (id: string) =>
   useBottomSheetStore((state) => state.sheetsById[id]?.portalSession, shallow);
+export const useSheetPreventDismiss = (id: string) =>
+  useBottomSheetStore(
+    (state) => state.sheetsById[id]?.preventDismiss ?? false,
+    shallow
+  );
 
 export const useSheetExists = (id: string) =>
   useBottomSheetStore((state) => !!state.sheetsById[id], shallow);
@@ -70,6 +75,9 @@ export const useUpdateParams = () =>
 export const useClearGroup = () =>
   useBottomSheetStore((state) => state.clearGroup);
 
+export const useSetPreventDismiss = () =>
+  useBottomSheetStore((state) => state.setPreventDismiss);
+
 export const useMount = () => useBottomSheetStore((state) => state.mount);
 
 export const useUnmount = () => useBottomSheetStore((state) => state.unmount);

package/src/store/store.ts

@@ -130,6 +130,16 @@ export const useBottomSheetStore = create(
         return { sheetsById: updateSheet(state.sheetsById, id, { params }) };
       }),
 
+    setPreventDismiss: (id, prevent) =>
+      set((state) => {
+        if (!state.sheetsById[id]) return state;
+        return {
+          sheetsById: updateSheet(state.sheetsById, id, {
+            preventDismiss: prevent,
+          }),
+        };
+      }),
+
     clearGroup: (groupId) =>
       set((state) => {
         const idsToRemove = new Set(

package/src/store/types.ts

@@ -18,6 +18,13 @@ export interface BottomSheetState {
    * react-native-teleport connection issues after replace flows.
    */
   portalSession?: number;
+  /**
+   * When true, the adapter should block user-initiated dismiss gestures
+   * (swipe down, backdrop tap). Set by `useOnBeforeClose` to ensure the
+   * interceptor runs before closing. Programmatic close via `forceClose()`
+   * bypasses this.
+   */
+  preventDismiss?: boolean;
 }
 
 export type TriggerState = Omit<BottomSheetState, 'status'>;
@@ -33,6 +40,7 @@ export interface BottomSheetStoreActions {
   startClosing(id: string): void;
   finishClosing(id: string): void;
   updateParams(id: string, params: Record<string, unknown> | undefined): void;
+  setPreventDismiss(id: string, prevent: boolean): void;
   clearGroup(groupId: string): void;
   clearAll(): void;
   mount(sheet: Omit<BottomSheetState, 'status'>): void;

package/src/useBottomSheetContext.ts

@@ -1,5 +1,6 @@
 import { useMaybeBottomSheetContext } from './BottomSheet.context';
 import { useSheetParams, useStartClosing } from './bottomSheet.store';
+import { requestClose } from './bottomSheetCoordinator';
 import type {
   BottomSheetPortalId,
   BottomSheetPortalParams,
@@ -9,6 +10,11 @@ export interface UseBottomSheetContextReturn<TParams> {
   id: string;
   params: TParams;
   close: () => void;
+  /**
+   * Close the sheet, bypassing any onBeforeClose interceptor.
+   * Useful for force-closing from within onBeforeClose confirmation flows.
+   */
+  forceClose: () => void;
   /** @deprecated Use `close` instead */
   closeBottomSheet: () => void;
 }
@@ -32,12 +38,16 @@ export function useBottomSheetContext<
     );
   }
 
-  const close = () => startClosing(context.id);
+  const close = () => {
+    requestClose(context.id);
+  };
+  const forceClose = () => startClosing(context.id);
 
   return {
     id: context.id,
     params: params as BottomSheetPortalParams<T>,
     close,
+    forceClose,
     closeBottomSheet: close,
   };
 }

package/src/useBottomSheetControl.ts

@@ -1,19 +1,16 @@
 import React from 'react';
 import type { SheetAdapterRef } from './adapter.types';
 
-import {
-  useOpen,
-  useStartClosing,
-  useUpdateParams,
-  type OpenMode,
-} from './bottomSheet.store';
+import { useOpen, useUpdateParams, type OpenMode } from './bottomSheet.store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.provider';
+import { closeAllAnimated, requestClose } from './bottomSheetCoordinator';
 import type {
   BottomSheetPortalId,
   BottomSheetPortalParams,
   HasParams,
 } from './portal.types';
 import { getSheetRef, setSheetRef } from './refsMap';
+import type { CloseAllOptions } from './useBottomSheetManager';
 
 interface BaseOpenOptions<TParams> {
   mode?: OpenMode;
@@ -37,6 +34,7 @@ type OpenFunction<T extends BottomSheetPortalId> =
 export interface UseBottomSheetControlReturn<T extends BottomSheetPortalId> {
   open: OpenFunction<T>;
   close: () => void;
+  closeAll: (options?: CloseAllOptions) => Promise<void>;
   updateParams: (params: BottomSheetPortalParams<T>) => void;
   resetParams: () => void;
 }
@@ -47,7 +45,6 @@ export function useBottomSheetControl<T extends BottomSheetPortalId>(
   const bottomSheetManagerContext = useMaybeBottomSheetManagerContext();
 
   const storeOpen = useOpen();
-  const startClosing = useStartClosing();
   const storeUpdateParams = useUpdateParams();
 
   const open = (options?: OpenOptions<T>) => {
@@ -74,7 +71,12 @@ export function useBottomSheetControl<T extends BottomSheetPortalId>(
   };
 
   const close = () => {
-    startClosing(id);
+    requestClose(id);
+  };
+
+  const closeAll = (options?: CloseAllOptions) => {
+    const groupId = bottomSheetManagerContext?.groupId || 'default';
+    return closeAllAnimated(groupId, options);
   };
 
   const updateParams = (params: BottomSheetPortalParams<T>) => {
@@ -88,6 +90,7 @@ export function useBottomSheetControl<T extends BottomSheetPortalId>(
   return {
     open: open as OpenFunction<T>,
     close,
+    closeAll,
     updateParams,
     resetParams,
   };

package/src/useBottomSheetManager.tsx

@@ -1,20 +1,20 @@
 import React from 'react';
 
-import {
-  useOpen,
-  useStartClosing,
-  useClearGroup,
-  type OpenMode,
-} from './bottomSheet.store';
+import { useOpen, useClearGroup, type OpenMode } from './bottomSheet.store';
 import { useMaybeBottomSheetManagerContext } from './BottomSheetManager.provider';
 import type { SheetAdapterRef } from './adapter.types';
+import { closeAllAnimated, requestClose } from './bottomSheetCoordinator';
 import { setSheetRef } from './refsMap';
 
+export interface CloseAllOptions {
+  /** Delay in ms between each cascading close animation. Default: 100 */
+  stagger?: number;
+}
+
 export const useBottomSheetManager = () => {
   const bottomSheetManagerContext = useMaybeBottomSheetManagerContext();
 
   const storeOpen = useOpen();
-  const startClosing = useStartClosing();
   const storeClearGroup = useClearGroup();
 
   const openBottomSheet = (
@@ -52,7 +52,12 @@ export const useBottomSheetManager = () => {
   };
 
   const close = (id: string) => {
-    startClosing(id);
+    requestClose(id);
+  };
+
+  const closeAll = (options?: CloseAllOptions) => {
+    const groupId = bottomSheetManagerContext?.groupId || 'default';
+    return closeAllAnimated(groupId, options);
   };
 
   const clear = () => {
@@ -63,6 +68,7 @@ export const useBottomSheetManager = () => {
   return {
     open: openBottomSheet,
     close,
+    closeAll,
     clear,
     /** @deprecated Use `open` instead */
     openBottomSheet,

package/src/useOnBeforeClose.ts

@@ -0,0 +1,92 @@
+import { useEffect } from 'react';
+
+import { useMaybeBottomSheetContext } from './BottomSheet.context';
+import { useSetPreventDismiss } from './bottomSheet.store';
+import type { OnBeforeCloseCallback } from './onBeforeCloseRegistry';
+import { removeOnBeforeClose, setOnBeforeClose } from './onBeforeCloseRegistry';
+import { useEvent } from './useEvent';
+
+/**
+ * Registers an interceptor that is called before the sheet closes.
+ *
+ * When active, this hook:
+ * 1. Sets `preventDismiss` on the sheet so adapters block user-initiated
+ *    gestures (swipe down, pan-to-close) at the native level.
+ * 2. Intercepts all programmatic close paths (backdrop tap, back button,
+ *    `close()`, `closeAll()`) and calls the callback first.
+ *
+ * The interceptor receives `onConfirm` and `onCancel` callbacks. Call these
+ * when the user makes a decision. This works seamlessly with `Alert.alert`:
+ *
+ * ```tsx
+ * useOnBeforeClose(({ onConfirm, onCancel }) => {
+ *   if (dirty) {
+ *     Alert.alert('Discard changes?', '', [
+ *       { text: 'Cancel', onPress: onCancel },
+ *       { text: 'Discard', onPress: onConfirm },
+ *     ]);
+ *   } else {
+ *     onConfirm(); // Allow close immediately
+ *   }
+ * });
+ * ```
+ *
+ * For backward compatibility, you can still return `boolean` or `Promise<boolean>`:
+ * - Return `false` (or resolve to `false`) to prevent closing
+ * - Return `true` (or resolve to `true`) to allow closing
+ *
+ * Use `forceClose()` from `useBottomSheetContext` to bypass the interceptor entirely.
+ *
+ * Must be used inside a sheet component (within BottomSheetContext).
+ *
+ * @example Callback pattern (recommended)
+ * ```tsx
+ * function MySheet() {
+ *   const [dirty, setDirty] = useState(false);
+ *
+ *   useOnBeforeClose(({ onConfirm, onCancel }) => {
+ *     if (dirty) {
+ *       Alert.alert('Discard changes?', '', [
+ *         { text: 'Cancel', style: 'cancel', onPress: onCancel },
+ *         { text: 'Discard', onPress: onConfirm },
+ *       ]);
+ *     } else {
+ *       onConfirm();
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example Boolean return (backward compatible)
+ * ```tsx
+ * function MySheet() {
+ *   const [dirty, setDirty] = useState(false);
+ *
+ *   useOnBeforeClose(() => {
+ *     return !dirty; // false blocks, true allows
+ *   });
+ * }
+ * ```
+ */
+export function useOnBeforeClose(callback: OnBeforeCloseCallback): void {
+  const context = useMaybeBottomSheetContext();
+  const setPreventDismiss = useSetPreventDismiss();
+
+  if (!context?.id) {
+    throw new Error(
+      'useOnBeforeClose must be used within a BottomSheet component'
+    );
+  }
+
+  const id = context.id;
+  const stableCallback = useEvent(callback);
+
+  useEffect(() => {
+    setOnBeforeClose(id, stableCallback);
+    setPreventDismiss(id, true);
+    return () => {
+      removeOnBeforeClose(id);
+      setPreventDismiss(id, false);
+    };
+  }, [id, stableCallback, setPreventDismiss]);
+}