@niibase/bottom-sheet-manager 1.1.0 → 1.3.0

package/src/router/index.tsx

@@ -1,14 +1,13 @@
 import {
   createNavigatorFactory,
-  NavigatorTypeBagBase,
-  ParamListBase,
-  StaticConfig,
-  TypedNavigator,
   useNavigationBuilder,
+  type NavigatorTypeBagBase,
+  type ParamListBase,
+  type StaticConfig,
+  type TypedNavigator,
 } from "@react-navigation/native";
-import React from "react";
+import * as React from "react";
 
-import { BottomSheetRouter, BottomSheetRouterOptions } from "./router";
 import type {
   BottomSheetActionHelpers,
   BottomSheetNavigationEventMap,
@@ -17,6 +16,7 @@ import type {
   BottomSheetNavigationState,
   BottomSheetNavigatorProps,
 } from "./types";
+import { BottomSheetRouter, type BottomSheetRouterOptions } from "./router";
 import { BottomSheetView } from "./view";
 
 function BottomSheetNavigator({
@@ -24,6 +24,7 @@ function BottomSheetNavigator({
   children,
   screenListeners,
   screenOptions,
+  initialRouteName,
   ...rest
 }: BottomSheetNavigatorProps) {
   const { state, descriptors, navigation, NavigationContent } = useNavigationBuilder<
@@ -37,6 +38,7 @@ function BottomSheetNavigator({
     children,
     screenListeners,
     screenOptions,
+    initialRouteName,
   });
 
   return (
@@ -52,18 +54,40 @@ function BottomSheetNavigator({
 }
 
 /**
- * To use BottomSheetNavigator with expo-router, the first screen should be your app content
- * and add a border radius of 24px to the root view if want to snap to 100%.
+ * Creates a bottom sheet navigator that renders screens as bottom sheet modals.
+ *
+ * The first screen in the navigator is rendered as the main content,
+ * and subsequent screens are rendered as bottom sheet modals on top.
+ *
+ * @example
+ * ```tsx
+ * // With React Navigation
+ * const { Navigator, Screen } = createBottomSheetNavigator();
+ *
+ * function App() {
+ *   return (
+ *     <Navigator>
+ *       <Screen name="Home" component={HomeScreen} />
+ *       <Screen
+ *         name="Details"
+ *         component={DetailsSheet}
+ *         options={{ snapPoints: ['50%', '100%'] }}
+ *       />
+ *     </Navigator>
+ *   );
+ * }
+ * ```
  *
  * @example
  * ```tsx
+ * // With Expo Router
+ * import { Slot, withLayoutContext } from "expo-router";
  * import {
  *   createBottomSheetNavigator,
  *   BottomSheetNavigationOptions,
  *   BottomSheetNavigationEventMap,
  *   BottomSheetNavigationState,
- * } from "@repo/bottom-sheet";
- * import { Slot, withLayoutContext } from "expo-router";
+ * } from "@niibase/bottom-sheet-manager";
  *
  * const { Navigator } = createBottomSheetNavigator();
  *
@@ -79,36 +103,22 @@ function BottomSheetNavigator({
  * };
  *
  * export default function Layout() {
+ *   // SSR guard - navigator doesn't work on server
  *   if (typeof window === "undefined") return <Slot />;
- *   return (
- *     <BottomSheet
- *       screenOptions={
- *         {
- *           // API Reference: `@repo/design/bottom-sheet/types.ts`
- *           // And: https://gorhom.github.io/react-native-bottom-sheet/modal/props/
- *         }
- *       }
- *.    />
- *   );
+ *
+ *   return <BottomSheet />;
  * }
  * ```
  */
 export function createBottomSheetNavigator<
   const ParamList extends ParamListBase,
   const NavigatorID extends string | undefined = undefined,
-  // We'll define a type bag specialized for bottom sheets:
   const TypeBag extends NavigatorTypeBagBase = {
-    // The param list from the user
     ParamList: ParamList;
-    // Optional ID for this navigator
     NavigatorID: NavigatorID;
-    // The state shape
     State: BottomSheetNavigationState<ParamList>;
-    // The screen options
     ScreenOptions: BottomSheetNavigationOptions;
-    // The event map
     EventMap: BottomSheetNavigationEventMap;
-    // The type of the "navigation" object used by each screen in the navigator
     NavigationList: {
       [RouteName in keyof ParamList]: BottomSheetNavigationProp<
         ParamList,
@@ -116,15 +126,12 @@ export function createBottomSheetNavigator<
         NavigatorID
       >;
     };
-    // The navigator component
     Navigator: typeof BottomSheetNavigator;
   },
-  // The static config allows for "static" route config
   const Config extends StaticConfig<TypeBag> = StaticConfig<TypeBag>,
 >(config?: Config): TypedNavigator<TypeBag, Config> {
-  // We call `createNavigatorFactory` with our un-typed navigator
-  // but pass in the config to get the typed container
   return createNavigatorFactory(BottomSheetNavigator)(config);
 }
 
 export * from "./types";
+export { BottomSheetActions, useBottomSheetNavigation } from "./router";

package/src/router/router.ts

@@ -1,57 +1,121 @@
 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 +123,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 +221,43 @@ 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,
@@ -9,28 +8,72 @@ import type {
     RouteProp,
     StackActionHelpers,
 } from "@react-navigation/native";
+import type { BottomSheetModalProps } from "@gorhom/bottom-sheet";
 
-// TODO: Sheet open / close / snap / events.
-export type BottomSheetNavigationEventMap = {};
+/**
+ * Navigation events emitted by the bottom sheet navigator.
+ */
+export type BottomSheetNavigationEventMap = {
+    /**
+     * Event emitted when a sheet is presented.
+     */
+    sheetPresent: { data: undefined };
+    /**
+     * Event emitted when a sheet is dismissed.
+     */
+    sheetDismiss: { data: undefined };
+};
 
+/**
+ * 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.
+ */
 export type BottomSheetNavigationState<ParamList extends ParamListBase> = Omit<
     NavigationState<ParamList>,
-    "routes"
+    "routes" | "type"
 > & {
     type: "bottom-sheet";
-    routes: (NavigationState<ParamList>["routes"][number] & {
-        snapToIndex?: number | null;
-    })[];
+    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,
     RouteName extends keyof ParamList = string,
@@ -45,6 +88,9 @@ export type BottomSheetNavigationProp<
 > &
     BottomSheetActionHelpers<ParamList>;
 
+/**
+ * Props available to screen components in the bottom sheet navigator.
+ */
 export type BottomSheetScreenProps<
     ParamList extends ParamListBase,
     RouteName extends keyof ParamList = string,
@@ -54,25 +100,37 @@ export type BottomSheetScreenProps<
     route: RouteProp<ParamList, RouteName>;
 };
 
+/**
+ * Navigation helpers type for the bottom sheet navigator.
+ */
 export type BottomSheetNavigationHelpers = NavigationHelpers<
     ParamListBase,
     BottomSheetNavigationEventMap
->;
+> &
+    BottomSheetActionHelpers<ParamListBase>;
 
-// We want it to be an empty object because navigator does not have any additional props
-export type BottomSheetNavigationConfig = {};
+/**
+ * Configuration options for the bottom sheet navigator.
+ */
+export type BottomSheetNavigationConfig = {
+    /**
+     * Whether to detach inactive sheets from the view hierarchy.
+     * @default false
+     */
+    detachInactiveScreens?: boolean;
+};
 
+/**
+ * Screen options available for bottom sheet screens.
+ */
 export type BottomSheetNavigationOptions = Omit<
     BottomSheetModalProps,
-    // Remove some props that aren't useful as navigation options.
+    // Remove props that are managed by the navigator
     | "containerHeight"
     | "snapPoints"
     | "gestureEventsHandlersHook"
     | "animatedPosition"
-    | "animatedIndex"
-    | "topInset"
     | "onChange"
-    | "onAnimate"
     | "onClose"
     | "children"
     | "$modal"
@@ -80,22 +138,55 @@ export type BottomSheetNavigationOptions = Omit<
     | "simultaneousHandlers"
 > & {
     /**
-     * Points for the bottom sheet to snap to. It accepts array of number, string or mix.
-     * String values should be a percentage.
+     * 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']}
-     * @type Array<string | number>
+     * snapPoints={[200, '50%']}
+     * snapPoints={['100%']}
+     *
+     * @default ['66%']
      */
     snapPoints?: Array<string | number>;
+
+    /**
+     * When `true`, tapping on the backdrop will not dismiss the sheet.
+     * @default false
+     */
+    clickThrough?: boolean;
+
     /**
-     * When `true`, tapping on the backdrop will not dismiss the modal.
+     * Whether the bottom sheet is an iOS 18 modal sheet type of animation.
+     * When enabled at snap point 90%, the content behind the sheet scales down and gets a
+     * border radius, similar to iOS 18 system sheets.
      * @default false
      */
+    iosModalSheetTypeOfAnimation?: boolean;
+
+    /**
+     * Opacity of the backdrop overlay.
+     * @default 0.45
+     */
+    opacity?: number;
+};
+
+export type BottomSheetModalScreenProps = Omit<BottomSheetModalProps, "onDismiss"> & {
+    route: BottomSheetRoute;
+    navigation: BottomSheetNavigationHelpers;
+
     clickThrough?: boolean;
+    opacity?: number;
+
+    /**
+     * Callback when sheet animation changes.
+     */
+    onSheetAnimate?: (from: number, to: number) => void;
 };
 
+/**
+ * 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'
@@ -106,12 +197,18 @@ export type BottomSheetNavigatorProps = DefaultNavigatorOptions<
 > &
     BottomSheetNavigationConfig;
 
+/**
+ * Descriptor type for bottom sheet screens.
+ */
 export type BottomSheetDescriptor = Descriptor<
     BottomSheetNavigationOptions,
     BottomSheetNavigationProp<ParamListBase>,
     RouteProp<ParamListBase>
 >;
 
+/**
+ * Map of route keys to their descriptors.
+ */
 export type BottomSheetDescriptorMap = {
     [key: string]: BottomSheetDescriptor;
 };