@lodev09/react-native-true-sheet 4.0.0-beta.0 → 4.0.0-beta.2

package/src/navigation/expo-router/index.ts

@@ -0,0 +1,89 @@
+import type { ParamListBase } from '@react-navigation/core';
+import { StackRouter, unstable_integrateWithRouter, useNavigation } from 'expo-router';
+
+import {
+  createTrueSheetRouter,
+  type StackRouterFactory,
+  type TrueSheetRouterOptions,
+} from '../createTrueSheetRouter';
+import { trueSheetNavigator } from '../navigator';
+import type {
+  TrueSheetNavigationOptions,
+  TrueSheetNavigationProp,
+  TrueSheetNavigationState,
+  TrueSheetNavigatorContentExtraProps,
+  TrueSheetNavigatorProps,
+  TrueSheetStandardEventMap,
+} from '../types';
+
+const SheetNavigator = unstable_integrateWithRouter<
+  TrueSheetNavigationOptions,
+  TrueSheetNavigationState<ParamListBase>,
+  TrueSheetStandardEventMap,
+  TrueSheetNavigatorContentExtraProps,
+  TrueSheetRouterOptions
+>(
+  trueSheetNavigator,
+  // expo-router's vendored StackRouter is structurally identical to @react-navigation's
+  createTrueSheetRouter(StackRouter as StackRouterFactory),
+  {
+    createProps: ({ state, dispatch }) => ({
+      routes: state.routes,
+      dispatch,
+    }),
+  }
+);
+
+// Public props: `routes`/`dispatch` are injected by `createProps` (optional here
+// so the navigator type stays comparable), and expo-router intersects the event
+// map with an index signature which breaks precisely typed `screenListeners`
+// callbacks - replace it with the exact map
+type SheetProps = Omit<
+  React.ComponentProps<typeof SheetNavigator>,
+  'screenListeners' | 'routes' | 'dispatch'
+> &
+  Partial<Pick<React.ComponentProps<typeof SheetNavigator>, 'routes' | 'dispatch'>> &
+  Pick<TrueSheetNavigatorProps, 'screenListeners'>;
+
+/**
+ * TrueSheet navigator layout for Expo Router.
+ *
+ * @example
+ * ```tsx
+ * // app/sheet/_layout.tsx
+ * import { Sheet } from '@lodev09/react-native-true-sheet/navigation/expo-router';
+ *
+ * export default function SheetLayout() {
+ *   return (
+ *     <Sheet initialRouteName="(home)">
+ *       <Sheet.Screen name="details" options={{ detents: [0.5, 1] }} />
+ *     </Sheet>
+ *   );
+ * }
+ * ```
+ */
+export const Sheet = SheetNavigator as React.ComponentType<SheetProps> & {
+  Screen: typeof SheetNavigator.Screen;
+  Protected: typeof SheetNavigator.Protected;
+};
+
+/**
+ * Hook to access TrueSheet navigation with the resize helper.
+ * Built on expo-router's `useNavigation`.
+ */
+export const useTrueSheetNavigation = <
+  T extends ParamListBase = ParamListBase,
+>(): TrueSheetNavigationProp<T> => useNavigation<TrueSheetNavigationProp<T>>();
+
+export { TrueSheetActions, type TrueSheetActionType } from '../actions';
+
+export type { DetentInfoEventPayload, PositionChangeEventPayload } from '../../TrueSheet.types';
+
+export type {
+  TrueSheetNavigationEventMap,
+  TrueSheetNavigationHelpers,
+  TrueSheetNavigationOptions,
+  TrueSheetNavigationProp,
+  TrueSheetNavigationState,
+  TrueSheetScreenProps,
+} from '../types';

package/src/navigation/index.ts

@@ -0,0 +1,81 @@
+import {
+  createStandardNavigationFactories,
+  StackRouter,
+  type StandardNavigationTypeBagBase,
+} from '@react-navigation/native';
+
+import { createTrueSheetRouter, type StackRouterFactory } from './createTrueSheetRouter';
+import { trueSheetNavigator } from './navigator';
+import type {
+  TrueSheetActionHelpers,
+  TrueSheetNavigationOptions,
+  TrueSheetNavigationEventMap,
+  TrueSheetNavigationState,
+  TrueSheetNavigatorContentExtraProps,
+} from './types';
+import type { TrueSheetRouterOptions } from './createTrueSheetRouter';
+
+export interface TrueSheetNavigationTypeBag extends StandardNavigationTypeBagBase {
+  State: TrueSheetNavigationState<this['ParamList']>;
+  ActionHelpers: TrueSheetActionHelpers<this['ParamList']>;
+  ScreenOptions: TrueSheetNavigationOptions;
+  EventMap: TrueSheetNavigationEventMap;
+  RouterOptions: TrueSheetRouterOptions;
+}
+
+const { createNavigator, createScreen } = createStandardNavigationFactories<
+  TrueSheetNavigationTypeBag,
+  {},
+  TrueSheetNavigatorContentExtraProps
+>(
+  trueSheetNavigator,
+  createTrueSheetRouter(StackRouter as StackRouterFactory),
+  ({ state, navigation }) => ({ routes: state.routes, dispatch: navigation.dispatch })
+);
+
+/**
+ * Creates a TrueSheet navigator.
+ *
+ * @example
+ * ```tsx
+ * const Sheet = createTrueSheetNavigator();
+ *
+ * function App() {
+ *   return (
+ *     <Sheet.Navigator>
+ *       <Sheet.Screen name="Home" component={HomeScreen} />
+ *       <Sheet.Screen
+ *         name="Details"
+ *         component={DetailsSheet}
+ *         options={{ detents: [0.5, 1] }}
+ *       />
+ *     </Sheet.Navigator>
+ *   );
+ * }
+ * ```
+ */
+export const createTrueSheetNavigator = createNavigator;
+
+/**
+ * Creates a screen configuration for the static API.
+ */
+export const createTrueSheetScreen = createScreen;
+
+export { TrueSheetActions, type TrueSheetActionType } from './actions';
+export {
+  createTrueSheetRouter,
+  type StackRouterFactory,
+  type TrueSheetRouterOptions,
+} from './createTrueSheetRouter';
+export { useTrueSheetNavigation } from './useTrueSheetNavigation';
+
+export type { DetentInfoEventPayload, PositionChangeEventPayload } from '../TrueSheet.types';
+
+export type {
+  TrueSheetNavigationEventMap,
+  TrueSheetNavigationHelpers,
+  TrueSheetNavigationOptions,
+  TrueSheetNavigationProp,
+  TrueSheetNavigationState,
+  TrueSheetScreenProps,
+} from './types';

package/src/navigation/navigator.ts

@@ -0,0 +1,18 @@
+import { createStandardNavigator } from 'standard-navigation';
+
+import { TrueSheetNavigatorContent } from './TrueSheetNavigatorContent';
+import type {
+  TrueSheetNavigationOptions,
+  TrueSheetNavigatorContentExtraProps,
+  TrueSheetStandardEventMap,
+} from './types';
+
+/**
+ * Framework-agnostic TrueSheet navigator.
+ * Wired into React Navigation via `./index` and Expo Router via `./expo-router`.
+ */
+export const trueSheetNavigator = createStandardNavigator<
+  TrueSheetNavigationOptions,
+  TrueSheetStandardEventMap,
+  TrueSheetNavigatorContentExtraProps
+>(TrueSheetNavigatorContent);

package/src/navigation/screen/ReanimatedTrueSheetScreen.tsx

@@ -0,0 +1,61 @@
+import Animated from 'react-native-reanimated';
+import { scheduleOnRN } from 'react-native-worklets';
+
+import { useReanimatedPositionChangeHandler } from '../../reanimated';
+import { TrueSheet } from '../../TrueSheet';
+import type { PositionChangeEvent } from '../../TrueSheet.types';
+import type { TrueSheetScreenProps } from './types';
+import { useSheetScreenState } from './useSheetScreenState';
+
+const AnimatedTrueSheet = Animated.createAnimatedComponent(TrueSheet);
+
+export const ReanimatedTrueSheetScreen = ({
+  detentIndex,
+  resizeKey,
+  dispatch,
+  emit,
+  routeKey,
+  closing,
+  detents,
+  children,
+  positionChangeHandler,
+  ...sheetProps
+}: TrueSheetScreenProps) => {
+  const {
+    ref,
+    initialDetentIndex,
+    eventHandlers: { onPositionChange, ...eventHandlers },
+  } = useSheetScreenState({
+    detentIndex,
+    resizeKey,
+    closing,
+    dispatch,
+    routeKey,
+    emit,
+  });
+
+  const reanimatedPositionChangeHandler = useReanimatedPositionChangeHandler(
+    (payload) => {
+      'worklet';
+      positionChangeHandler?.(payload);
+      scheduleOnRN(onPositionChange, {
+        nativeEvent: payload,
+      } as PositionChangeEvent);
+    },
+    [onPositionChange, positionChangeHandler]
+  );
+
+  return (
+    <AnimatedTrueSheet
+      ref={ref}
+      name={`navigation-sheet-${routeKey}`}
+      initialDetentIndex={initialDetentIndex}
+      detents={detents}
+      onPositionChange={reanimatedPositionChangeHandler}
+      {...sheetProps}
+      {...eventHandlers}
+    >
+      {children}
+    </AnimatedTrueSheet>
+  );
+};

package/src/navigation/screen/TrueSheetScreen.tsx

@@ -0,0 +1,54 @@
+import { useCallback } from 'react';
+
+import { TrueSheet } from '../../TrueSheet';
+import type { PositionChangeEvent } from '../../TrueSheet.types';
+import type { TrueSheetScreenProps } from './types';
+import { useSheetScreenState } from './useSheetScreenState';
+
+export const TrueSheetScreen = ({
+  detentIndex,
+  resizeKey,
+  dispatch,
+  emit,
+  routeKey,
+  closing,
+  detents,
+  children,
+  positionChangeHandler,
+  ...sheetProps
+}: TrueSheetScreenProps) => {
+  const {
+    ref,
+    initialDetentIndex,
+    eventHandlers: { onPositionChange, ...eventHandlers },
+  } = useSheetScreenState({
+    detentIndex,
+    resizeKey,
+    closing,
+    dispatch,
+    routeKey,
+    emit,
+  });
+
+  const handlePositionChange = useCallback(
+    (e: PositionChangeEvent) => {
+      onPositionChange(e);
+      positionChangeHandler?.(e.nativeEvent);
+    },
+    [onPositionChange, positionChangeHandler]
+  );
+
+  return (
+    <TrueSheet
+      ref={ref}
+      name={`navigation-sheet-${routeKey}`}
+      initialDetentIndex={initialDetentIndex}
+      detents={detents}
+      onPositionChange={handlePositionChange}
+      {...sheetProps}
+      {...eventHandlers}
+    >
+      {children}
+    </TrueSheet>
+  );
+};

package/src/navigation/screen/index.ts

@@ -0,0 +1,3 @@
+export { TrueSheetScreen } from './TrueSheetScreen';
+export { useSheetScreenState } from './useSheetScreenState';
+export type { TrueSheetScreenProps } from './types';

package/src/navigation/screen/types.ts

@@ -0,0 +1,19 @@
+import type { TrueSheetProps } from '../../TrueSheet.types';
+import type {
+  PositionChangeHandler,
+  TrueSheetDispatch,
+  TrueSheetEmitFn,
+  TrueSheetNavigationSheetProps,
+} from '../types';
+
+export interface TrueSheetScreenProps extends TrueSheetNavigationSheetProps {
+  detentIndex: number;
+  resizeKey?: number;
+  dispatch: TrueSheetDispatch;
+  emit: TrueSheetEmitFn;
+  routeKey: string;
+  closing?: boolean;
+  detents: TrueSheetProps['detents'];
+  children: React.ReactNode;
+  positionChangeHandler?: PositionChangeHandler;
+}

package/src/navigation/screen/useSheetScreenState.ts

@@ -0,0 +1,100 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { TrueSheet } from '../../TrueSheet';
+import type {
+  DetentChangeEvent,
+  DetentInfoEventPayload,
+  DidBlurEvent,
+  DidFocusEvent,
+  DidPresentEvent,
+  DragBeginEvent,
+  DragChangeEvent,
+  DragEndEvent,
+  PositionChangeEvent,
+  PositionChangeEventPayload,
+  WillBlurEvent,
+  WillDismissEvent,
+  WillFocusEvent,
+  WillPresentEvent,
+} from '../../TrueSheet.types';
+import type { TrueSheetDispatch, TrueSheetEmitFn, TrueSheetNavigationEventMap } from '../types';
+import { TrueSheetActions } from '../actions';
+
+interface UseSheetScreenStateProps {
+  detentIndex: number;
+  resizeKey?: number;
+  closing?: boolean;
+  dispatch: TrueSheetDispatch;
+  routeKey: string;
+  emit: TrueSheetEmitFn;
+}
+
+export const useSheetScreenState = (props: UseSheetScreenStateProps) => {
+  const { detentIndex, resizeKey, closing, dispatch, routeKey, emit } = props;
+
+  const ref = useRef<TrueSheet>(null);
+  const isDismissedRef = useRef(false);
+  const isFirstRenderRef = useRef(true);
+  const initialDetentIndexRef = useRef(detentIndex);
+
+  useEffect(() => {
+    if (closing && !isDismissedRef.current) {
+      isDismissedRef.current = true;
+      ref.current?.dismiss();
+    }
+  }, [closing]);
+
+  useEffect(() => {
+    if (isFirstRenderRef.current) {
+      isFirstRenderRef.current = false;
+      return;
+    }
+    ref.current?.resize(detentIndex);
+  }, [detentIndex, resizeKey]);
+
+  const emitEvent = useCallback(
+    (
+      type: keyof TrueSheetNavigationEventMap,
+      data: DetentInfoEventPayload | PositionChangeEventPayload | undefined
+    ) => {
+      emit({
+        type,
+        target: routeKey,
+        data,
+      } as Parameters<TrueSheetEmitFn>[0]);
+    },
+    [emit, routeKey]
+  );
+
+  const onDidDismiss = useCallback(() => {
+    emitEvent('sheetDidDismiss', undefined);
+    isDismissedRef.current = true;
+    dispatch({ ...TrueSheetActions.remove(), source: routeKey });
+  }, [emitEvent, dispatch, routeKey]);
+
+  const eventHandlers = useMemo(
+    () => ({
+      onWillPresent: (e: WillPresentEvent) => emitEvent('sheetWillPresent', e.nativeEvent),
+      onDidPresent: (e: DidPresentEvent) => emitEvent('sheetDidPresent', e.nativeEvent),
+      onWillDismiss: (_e: WillDismissEvent) => emitEvent('sheetWillDismiss', undefined),
+      onDidDismiss,
+      onDetentChange: (e: DetentChangeEvent) => emitEvent('sheetDetentChange', e.nativeEvent),
+      onDragBegin: (e: DragBeginEvent) => emitEvent('sheetDragBegin', e.nativeEvent),
+      onDragChange: (e: DragChangeEvent) => emitEvent('sheetDragChange', e.nativeEvent),
+      onDragEnd: (e: DragEndEvent) => emitEvent('sheetDragEnd', e.nativeEvent),
+      onPositionChange: (e: PositionChangeEvent) => emitEvent('sheetPositionChange', e.nativeEvent),
+      onWillFocus: (_e: WillFocusEvent) => emitEvent('sheetWillFocus', undefined),
+      onDidFocus: (_e: DidFocusEvent) => emitEvent('sheetDidFocus', undefined),
+      onWillBlur: (_e: WillBlurEvent) => emitEvent('sheetWillBlur', undefined),
+      onDidBlur: (_e: DidBlurEvent) => emitEvent('sheetDidBlur', undefined),
+    }),
+    [emitEvent, onDidDismiss]
+  );
+
+  return {
+    ref,
+    initialDetentIndex: initialDetentIndexRef.current,
+    emitEvent,
+    eventHandlers,
+  };
+};

package/src/navigation/types.ts

@@ -0,0 +1,251 @@
+import type {
+  DefaultNavigatorOptions,
+  Descriptor,
+  NavigationHelpers,
+  NavigationProp,
+  NavigationState,
+  ParamListBase,
+  RouteProp,
+  StackActionHelpers,
+} from '@react-navigation/core';
+import type { NavigatorArgs } from 'standard-navigation';
+
+import type {
+  DetentInfoEventPayload,
+  PositionChangeEventPayload,
+  TrueSheetProps,
+} from '../TrueSheet.types';
+import type { TrueSheetActionType } from './actions';
+
+export type PositionChangeHandler = (payload: PositionChangeEventPayload) => void;
+
+export type TrueSheetNavigationEventMap = {
+  /**
+   * Event fired when the sheet is about to be presented.
+   */
+  sheetWillPresent: { data: DetentInfoEventPayload };
+  /**
+   * Event fired when the sheet has been presented.
+   */
+  sheetDidPresent: { data: DetentInfoEventPayload };
+  /**
+   * Event fired when the sheet is about to be dismissed.
+   */
+  sheetWillDismiss: { data: undefined };
+  /**
+   * Event fired when the sheet has been dismissed.
+   */
+  sheetDidDismiss: { data: undefined };
+  /**
+   * Event fired when the sheet's detent changes.
+   */
+  sheetDetentChange: { data: DetentInfoEventPayload };
+  /**
+   * Event fired when the user starts dragging the sheet.
+   */
+  sheetDragBegin: { data: DetentInfoEventPayload };
+  /**
+   * Event fired while the user is dragging the sheet.
+   */
+  sheetDragChange: { data: DetentInfoEventPayload };
+  /**
+   * Event fired when the user stops dragging the sheet.
+   */
+  sheetDragEnd: { data: DetentInfoEventPayload };
+  /**
+   * Event fired when the sheet's position changes.
+   */
+  sheetPositionChange: { data: PositionChangeEventPayload };
+  /**
+   * Event fired when the sheet is about to regain focus.
+   */
+  sheetWillFocus: { data: undefined };
+  /**
+   * Event fired when the sheet regains focus.
+   */
+  sheetDidFocus: { data: undefined };
+  /**
+   * Event fired when the sheet is about to lose focus.
+   */
+  sheetWillBlur: { data: undefined };
+  /**
+   * Event fired when the sheet loses focus.
+   */
+  sheetDidBlur: { data: undefined };
+};
+
+export type TrueSheetNavigationState<ParamList extends ParamListBase> = Omit<
+  NavigationState<ParamList>,
+  'routes'
+> & {
+  type: 'true-sheet';
+  routes: (NavigationState<ParamList>['routes'][number] & {
+    resizeIndex?: number;
+    resizeKey?: number;
+    closing?: boolean;
+  })[];
+};
+
+/**
+ * `TrueSheetNavigationEventMap` in the `standard-navigation` event-map shape.
+ */
+export type TrueSheetStandardEventMap = {
+  [K in keyof TrueSheetNavigationEventMap]: {
+    data: TrueSheetNavigationEventMap[K]['data'];
+    canPreventDefault: false;
+  };
+};
+
+export type TrueSheetRoute = TrueSheetNavigationState<ParamListBase>['routes'][number];
+
+export type TrueSheetDispatch = (action: TrueSheetActionType) => void;
+
+export type TrueSheetEmitFn = NavigatorArgs<
+  TrueSheetNavigationOptions,
+  TrueSheetStandardEventMap
+>['emitter']['emit'];
+
+/**
+ * Props injected into the navigator content by each adapter
+ * (React Navigation's `mapper` / Expo Router's `createProps`).
+ * Raw routes carry the custom fields (`closing`, `resizeIndex`, `resizeKey`)
+ * that the standard state strips out.
+ */
+export interface TrueSheetNavigatorContentExtraProps {
+  routes: TrueSheetRoute[];
+  dispatch: TrueSheetDispatch;
+}
+
+export type TrueSheetActionHelpers<ParamList extends ParamListBase> =
+  StackActionHelpers<ParamList> & {
+    /**
+     * Resize the sheet to a specific detent index.
+     */
+    resize(index?: number): void;
+  };
+
+export type TrueSheetNavigationProp<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList = string,
+  NavigatorID extends string | undefined = undefined,
+> = NavigationProp<
+  ParamList,
+  RouteName,
+  NavigatorID,
+  TrueSheetNavigationState<ParamList>,
+  TrueSheetNavigationOptions,
+  TrueSheetNavigationEventMap
+> &
+  TrueSheetActionHelpers<ParamList>;
+
+export type TrueSheetScreenProps<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList = string,
+  NavigatorID extends string | undefined = undefined,
+> = {
+  navigation: TrueSheetNavigationProp<ParamList, RouteName, NavigatorID>;
+  route: RouteProp<ParamList, RouteName>;
+};
+
+export type TrueSheetNavigationHelpers = NavigationHelpers<
+  ParamListBase,
+  TrueSheetNavigationEventMap
+>;
+
+export type TrueSheetNavigationSheetProps = Pick<
+  TrueSheetProps,
+  | 'detents'
+  | 'backgroundColor'
+  | 'cornerRadius'
+  | 'dismissible'
+  | 'draggable'
+  | 'grabber'
+  | 'grabberOptions'
+  | 'accessibilityOptions'
+  | 'dimmed'
+  | 'dimmedDetentIndex'
+  | 'backgroundBlur'
+  | 'blurOptions'
+  | 'maxContentHeight'
+  | 'maxContentWidth'
+  | 'presentation'
+  | 'style'
+  | 'header'
+  | 'headerStyle'
+  | 'headerOptions'
+  | 'footer'
+  | 'footerStyle'
+  | 'footerOptions'
+  | 'scrollableOptions'
+  | 'insetAdjustment'
+  | 'anchor'
+  | 'anchorOffset'
+  | 'elevation'
+  | 'detached'
+  | 'detachedOffset'
+>;
+
+/**
+ * Screen options for TrueSheet navigator screens.
+ */
+export type TrueSheetNavigationOptions = TrueSheetNavigationSheetProps & {
+  /**
+   * The detent index to present at.
+   * @default 0
+   */
+  detentIndex?: number;
+
+  /**
+   * Use ReanimatedTrueSheet for this screen.
+   * Enables worklet-based `onPositionChange` events.
+   *
+   * @default false
+   */
+  reanimated?: boolean;
+
+  /**
+   * A callback that receives position change events.
+   * When `reanimated` is enabled, this must be a worklet function.
+   *
+   * @example
+   * ```tsx
+   * <Navigator.Screen
+   *   name="Sheet"
+   *   options={{
+   *     reanimated: true,
+   *     positionChangeHandler: (payload) => {
+   *       'worklet';
+   *       animatedValue.value = payload.position;
+   *     },
+   *   }}
+   * />
+   * ```
+   */
+  positionChangeHandler?: PositionChangeHandler;
+};
+
+export type TrueSheetNavigatorProps = DefaultNavigatorOptions<
+  ParamListBase,
+  string | undefined,
+  TrueSheetNavigationState<ParamListBase>,
+  TrueSheetNavigationOptions,
+  TrueSheetNavigationEventMap,
+  unknown
+> & {
+  /**
+   * The name of the route to use as the base screen.
+   * This screen will be rendered as a regular screen, while other screens are presented as sheets.
+   * Defaults to the first screen defined in the navigator.
+   */
+  initialRouteName?: string;
+};
+
+export type TrueSheetDescriptor = Descriptor<
+  TrueSheetNavigationOptions,
+  TrueSheetNavigationProp<ParamListBase>,
+  RouteProp<ParamListBase>
+>;
+
+export type TrueSheetDescriptorMap = {
+  [key: string]: TrueSheetDescriptor;
+};