@niibase/bottom-sheet-manager 1.2.0 → 1.4.0

package/src/router/router.ts

@@ -1,57 +1,124 @@
 import {
-    ParamListBase,
-    Router,
     StackActions,
-    StackActionType,
     StackRouter,
-    StackRouterOptions,
+    useNavigation,
+    type CommonActions,
+    type ParamListBase,
+    type Router,
+    type StackActionType,
+    type StackRouterOptions,
 } from "@react-navigation/native";
 import { nanoid } from "nanoid/non-secure";
 
-import type { BottomSheetNavigationState } from "./types";
+import type { BottomSheetNavigationProp, BottomSheetNavigationState } from "./types";
 
 export type BottomSheetRouterOptions = StackRouterOptions;
 
 export type BottomSheetActionType =
     | StackActionType
+    | ReturnType<typeof CommonActions.goBack>
     | {
           type: "SNAP_TO";
           index: number;
           source?: string;
           target?: string;
+      }
+    | {
+          type: "DISMISS";
+          source?: string;
+          target?: string;
+      }
+    | {
+          type: "REMOVE";
+          source?: string;
+          target?: string;
       };
 
 export const BottomSheetActions = {
     ...StackActions,
-    snapTo(index: number): BottomSheetActionType {
-        return { type: "SNAP_TO", index };
-    },
+    /**
+     * Snap the bottom sheet to a specific index.
+     */
+    snapTo: (index: number): BottomSheetActionType => ({ type: "SNAP_TO", index }),
+    /**
+     * Dismiss the current bottom sheet.
+     */
+    dismiss: (): BottomSheetActionType => ({ type: "DISMISS" }),
+    /**
+     * Remove the sheet from navigation state after dismiss animation completes.
+     */
+    remove: (): BottomSheetActionType => ({ type: "REMOVE" }),
+};
+
+/**
+ * Ensures the base route (first screen) exists in the navigation state.
+ * This is important because the first screen is the main content,
+ * and subsequent screens are rendered as bottom sheets.
+ */
+const ensureBaseRoute = <T extends { routes: { name: string }[] }>(
+    state: T,
+    baseRouteName: string | undefined,
+    routeParamList: Record<string, object | undefined> | undefined,
+): T & { index: number; routes: T["routes"] } => {
+    if (!baseRouteName) {
+        return state as T & { index: number; routes: T["routes"] };
+    }
+
+    const hasBaseRoute = state.routes.some((r) => r.name === baseRouteName);
+
+    if (!hasBaseRoute) {
+        const baseRoute = {
+            key: `${baseRouteName}-${nanoid()}`,
+            name: baseRouteName,
+            params: routeParamList?.[baseRouteName],
+        };
+
+        return {
+            ...state,
+            index: state.routes.length,
+            routes: [baseRoute, ...state.routes],
+        } as T & { index: number; routes: T["routes"] };
+    }
+
+    return state as T & { index: number; routes: T["routes"] };
 };
 
-export function BottomSheetRouter(
+export const BottomSheetRouter = (
     routerOptions: StackRouterOptions,
-): Router<BottomSheetNavigationState<ParamListBase>, BottomSheetActionType> {
+): Router<
+    BottomSheetNavigationState<ParamListBase>,
+    BottomSheetActionType
+> => {
     const baseRouter = StackRouter(routerOptions) as unknown as Router<
         BottomSheetNavigationState<ParamListBase>,
         BottomSheetActionType
     >;
+
     return {
         ...baseRouter,
         type: "bottom-sheet",
+
         getInitialState(options) {
             const state = baseRouter.getInitialState(options);
+            const baseRouteName = routerOptions.initialRouteName ?? options.routeNames[0];
+            const stateWithBaseRoute = ensureBaseRoute(
+                state,
+                baseRouteName,
+                options.routeParamList,
+            );
 
             return {
-                ...state,
+                ...stateWithBaseRoute,
                 stale: false,
                 type: "bottom-sheet",
                 key: `bottom-sheet-${nanoid()}`,
             };
         },
+
         getStateForAction(state, action, options) {
             switch (action.type) {
                 case "SNAP_TO": {
-                    const index =
+                    const routeIndex =
                         action.target === state.key && action.source
                             ? state.routes.findIndex((r) => r.key === action.source)
                             : state.index;
@@ -59,19 +126,93 @@ export function BottomSheetRouter(
                     return {
                         ...state,
                         routes: state.routes.map((route, i) =>
-                            i === index
+                            i === routeIndex
                                 ? {
                                       ...route,
                                       snapToIndex: action.index,
+                                      snapToKey: (route.snapToKey ?? 0) + 1,
                                   }
                                 : route,
                         ),
                     };
                 }
+
+                case "GO_BACK":
+                case "DISMISS": {
+                    return this.getStateForAction(state, StackActions.pop(1), options);
+                }
+
+                case "POP": {
+                    // Only base screen remains - let parent navigator handle it
+                    if (state.routes.length <= 1) {
+                        return null;
+                    }
+
+                    const count =
+                        "payload" in action && typeof action.payload?.count === "number"
+                            ? action.payload.count
+                            : 1;
+
+                    // Calculate how many routes we can actually pop (don't pop base screen)
+                    const maxPopCount = state.routes.length - 1;
+                    const actualCount = Math.min(count, maxPopCount);
+
+                    // Base screen - let parent navigator handle it
+                    if (actualCount <= 0) {
+                        return null;
+                    }
+
+                    // Target index is the route we want to stay on (land on after pop)
+                    // closingIndex is the first route to be dismissed (the one after target)
+                    const targetIndex = state.routes.length - 1 - actualCount;
+                    const closingIndex = targetIndex + 1;
+
+                    // Mark only the bottom-most route to pop as closing
+                    // The sheet's dismiss() will handle dismissing sheets above it first
+                    return {
+                        ...state,
+                        index: closingIndex,
+                        routes: state.routes.map((route, i) =>
+                            i === closingIndex ? { ...route, closing: true } : route,
+                        ),
+                    };
+                }
+
+                case "POP_TO_TOP": {
+                    const popCount = state.routes.length - 1;
+                    return this.getStateForAction(
+                        state,
+                        StackActions.pop(popCount),
+                        options,
+                    );
+                }
+
+                case "REMOVE": {
+                    // Actually remove the closing route and all routes above it
+                    const routeKey = action.source;
+                    const routeIndex = routeKey
+                        ? state.routes.findIndex((r) => r.key === routeKey)
+                        : state.routes.findIndex((r) => r.closing);
+
+                    if (routeIndex === -1) {
+                        return state;
+                    }
+
+                    // Remove the route and all routes above it (they were dismissed together)
+                    const routes = state.routes.filter((_, i) => i < routeIndex);
+
+                    return {
+                        ...state,
+                        index: Math.min(state.index, routes.length - 1),
+                        routes,
+                    };
+                }
+
                 default:
                     return baseRouter.getStateForAction(state, action, options);
             }
         },
+
         getRehydratedState(partialState, { routeNames, routeParamList, routeGetIdList }) {
             if (partialState.stale === false) {
                 return partialState;
@@ -83,12 +224,44 @@ export function BottomSheetRouter(
                 routeGetIdList,
             });
 
+            const baseRouteName = routerOptions.initialRouteName ?? routeNames[0];
+            const stateWithBaseRoute = ensureBaseRoute(
+                state,
+                baseRouteName,
+                routeParamList,
+            );
+
             return {
-                ...state,
+                ...stateWithBaseRoute,
                 type: "bottom-sheet",
                 key: `bottom-sheet-${nanoid()}`,
             };
         },
+
         actionCreators: BottomSheetActions,
     };
-}
+};
+
+/**
+ * Hook to access BottomSheet navigation with the snapTo helper.
+ *
+ * @example
+ * ```tsx
+ * function MySheet() {
+ *   const navigation = useBottomSheetNavigation();
+ *
+ *   // Snap to a specific index
+ *   const handleExpand = () => {
+ *     navigation.snapTo(1); // Snap to second index
+ *   };
+ *
+ *   return (
+ *     <Button title="Expand" onPress={handleExpand} />
+ *   );
+ * }
+ * ```
+ */
+export const useBottomSheetNavigation = <
+    T extends ParamListBase = ParamListBase,
+>(): BottomSheetNavigationProp<T> =>
+    useNavigation<BottomSheetNavigationProp<T>>();

package/src/router/types.ts

@@ -1,4 +1,3 @@
-import type { BottomSheetModalProps } from "@gorhom/bottom-sheet";
 import type {
     DefaultNavigatorOptions,
     Descriptor,
@@ -8,43 +7,170 @@ import type {
     ParamListBase,
     RouteProp,
     StackActionHelpers,
+    StackNavigationState,
+    StackRouterOptions,
 } from "@react-navigation/native";
+import type { BottomSheetModalProps, SNAP_POINT_TYPE } from "@gorhom/bottom-sheet";
 
-// TODO: Sheet open / close / snap / events.
-export type BottomSheetNavigationEventMap = {};
-
-export type BottomSheetNavigationState<ParamList extends ParamListBase> = Omit<
-    NavigationState<ParamList>,
-    "routes"
+/**
+ * Bottom-sheet-specific screen options.
+ * These only take effect when `presentation: "bottomSheet"`.
+ */
+export type BottomSheetScreenOptions = Omit<
+    BottomSheetModalProps,
+    // Remove props that are managed by the navigator
+    | "containerHeight"
+    | "snapPoints"
+    | "gestureEventsHandlersHook"
+    | "iosModalSheetTypeOfAnimation"
+    | "animatedPosition"
+    | "onBeforeShow"
+    | "onChange"
+    | "onClose"
+    | "onDismiss"
+    | "onAnimate"
+    | "children"
+    | "$modal"
+    | "waitFor"
+    | "simultaneousHandlers"
 > & {
-    type: "bottom-sheet";
-    routes: (NavigationState<ParamList>["routes"][number] & {
-        snapToIndex?: number | null;
-    })[];
+    /**
+     * Points for the bottom sheet to snap to.
+     * Accepts an array of numbers (pixels) or strings (percentages).
+     *
+     * @example
+     * snapPoints={[200, 500]}
+     * snapPoints={[200, '50%']}
+     * snapPoints={['100%']}
+     *
+     * @default ['66%']
+     */
+    snapPoints?: Array<string | number>;
+
+    /**
+     * When `true`, tapping on the backdrop will not dismiss the sheet.
+     * @default false
+     */
+    passThrough?: boolean;
+
+    /**
+     * Opacity of the backdrop overlay.
+     * @default 0.45
+     */
+    opacity?: number;
+};
+
+/**
+ * Navigation options for the bottom sheet navigator.
+ *
+ * The first screen is rendered as the base content.
+ * All subsequent screens are rendered as bottom sheets using these options.
+ */
+export type BottomSheetNavigationOptions = Partial<BottomSheetScreenOptions>;
+
+/**
+ * Navigation events emitted by the bottom sheet navigator.
+ */
+export type BottomSheetNavigationEventMap = {
+    /**
+     * Event emitted when a sheet is presented.
+     */
+    sheetPresent: { data: unknown };
+    /**
+     * Event emitted when a sheet is dismissed.
+     */
+    sheetDismiss: { data: unknown };
+    /**
+     * Event emitted when a sheet changes between position/snap points
+     */
+    sheetOnChange: {
+        data: {
+            index: number;
+            position: number;
+            type: SNAP_POINT_TYPE;
+        };
+    };
+    /**
+     * Event emitted when a sheet animates between snap points.
+     */
+    sheetOnAnimate: {
+        data: {
+            fromIndex: number;
+            toIndex: number;
+            fromPosition: number;
+            toPosition: number;
+        };
+    };
 };
 
+/**
+ * Extended route type with bottom sheet specific properties.
+ */
+export type BottomSheetRoute<ParamList extends ParamListBase = ParamListBase> =
+    NavigationState<ParamList>["routes"][number] & {
+        /**
+         * The snap point index the sheet should animate to.
+         */
+        snapToIndex?: number | null;
+        /**
+         * Key to track snap changes for re-rendering.
+         */
+        snapToKey?: number;
+        /**
+         * Whether this route is in the process of being closed.
+         */
+        closing?: boolean;
+    };
+
+/**
+ * Navigation state type for the bottom sheet navigator.
+ *
+ * Extends `StackNavigationState` with bottom-sheet-specific route properties
+ * and a `"bottom-sheet"` type discriminator.
+ */
+export type BottomSheetNavigationState<ParamList extends ParamListBase = ParamListBase> =
+    Omit<StackNavigationState<ParamList>, "routes" | "type"> & {
+        type: "bottom-sheet";
+        routes: BottomSheetRoute<ParamList>[];
+    };
+
+/**
+ * Action helpers available on the navigation object.
+ */
 export type BottomSheetActionHelpers<ParamList extends ParamListBase> =
     StackActionHelpers<ParamList> & {
         /**
-         * Snap the drawer to a point.
+         * Snap the sheet to a specific point.
+         * @param index The snap point index to snap to.
          */
-        snapTo(index?: number): void;
+        snapTo(index: number): void;
+
+        /**
+         * Dismiss the current sheet.
+         */
+        dismiss(): void;
     };
 
+/**
+ * Navigation prop type for screens in the bottom sheet navigator.
+ */
 export type BottomSheetNavigationProp<
-    ParamList extends ParamListBase,
+    ParamList extends ParamListBase = ParamListBase,
     RouteName extends keyof ParamList = string,
     NavigatorID extends string | undefined = undefined,
 > = NavigationProp<
     ParamList,
     RouteName,
     NavigatorID,
-    BottomSheetNavigationState<ParamList>,
+    BottomSheetNavigationState<ParamListBase>,
     BottomSheetNavigationOptions,
     BottomSheetNavigationEventMap
 > &
     BottomSheetActionHelpers<ParamList>;
 
+/**
+ * Props available to screen components in the bottom sheet navigator.
+ */
 export type BottomSheetScreenProps<
     ParamList extends ParamListBase,
     RouteName extends keyof ParamList = string,
@@ -54,64 +180,53 @@ export type BottomSheetScreenProps<
     route: RouteProp<ParamList, RouteName>;
 };
 
+/**
+ * Navigation helpers type for the bottom sheet navigator.
+ */
 export type BottomSheetNavigationHelpers = NavigationHelpers<
     ParamListBase,
     BottomSheetNavigationEventMap
->;
-
-// We want it to be an empty object because navigator does not have any additional props
-export type BottomSheetNavigationConfig = {};
-
-export type BottomSheetNavigationOptions = Omit<
-    BottomSheetModalProps,
-    // Remove some props that aren't useful as navigation options.
-    | "containerHeight"
-    | "snapPoints"
-    | "gestureEventsHandlersHook"
-    | "animatedPosition"
-    | "animatedIndex"
-    | "topInset"
-    | "onChange"
-    | "onAnimate"
-    | "onClose"
-    | "children"
-    | "$modal"
-    | "waitFor"
-    | "simultaneousHandlers"
-> & {
-    /**
-     * Points for the bottom sheet to snap to. It accepts array of number, string or mix.
-     * String values should be a percentage.
-     * @example
-     * snapPoints={[200, 500]}
-     * snapPoints={[200, '%50']}
-     * snapPoints={['%100']}
-     * @type Array<string | number>
-     */
-    snapPoints?: Array<string | number>;
-    /**
-     * When `true`, tapping on the backdrop will not dismiss the modal.
-     * @default false
-     */
-    clickThrough?: boolean;
-};
+> &
+    BottomSheetActionHelpers<ParamListBase>;
 
+/**
+ * Props for the bottom sheet navigator component.
+ */
 export type BottomSheetNavigatorProps = DefaultNavigatorOptions<
     ParamListBase,
-    undefined, // or your ID if you want a named ID, e.g. 'BottomSheetNavigator'
+    string | undefined,
     BottomSheetNavigationState<ParamListBase>,
     BottomSheetNavigationOptions,
     BottomSheetNavigationEventMap,
-    BottomSheetNavigationHelpers
+    BottomSheetNavigationProp<ParamListBase>
 > &
-    BottomSheetNavigationConfig;
+    StackRouterOptions;
 
+/**
+ * Descriptor type for bottom sheet screens.
+ */
 export type BottomSheetDescriptor = Descriptor<
     BottomSheetNavigationOptions,
-    BottomSheetNavigationProp<ParamListBase>,
+    BottomSheetNavigationProp<ParamListBase, string, undefined>,
     RouteProp<ParamListBase>
 >;
 
+/**
+ * Map of route keys to their descriptors.
+ */
 export type BottomSheetDescriptorMap = {
     [key: string]: BottomSheetDescriptor;
 };
+
+export type BottomSheetModalScreenProps = Omit<BottomSheetModalProps, "onDismiss"> & {
+    route: BottomSheetRoute;
+    navigation: BottomSheetNavigationHelpers;
+
+    passThrough?: boolean;
+    opacity?: number;
+
+    /**
+     * Callback when sheet animation changes.
+     */
+    onSheetAnimate?: (from: number, to: number) => void;
+};