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

package/src/TrueSheet.tsx

@@ -10,6 +10,8 @@ import {
 
 import type {
   TrueSheetProps,
+  TrueSheetMethods,
+  TrueSheetStaticMethods,
   DragBeginEvent,
   DragChangeEvent,
   DragEndEvent,
@@ -20,16 +22,28 @@ import type {
   DidDismissEvent,
   WillDismissEvent,
   MountEvent,
-  SizeChangeEvent,
+  WillFocusEvent,
+  DidFocusEvent,
+  WillBlurEvent,
+  DidBlurEvent,
 } from './TrueSheet.types';
 import TrueSheetViewNativeComponent from './fabric/TrueSheetViewNativeComponent';
 import TrueSheetContainerViewNativeComponent from './fabric/TrueSheetContainerViewNativeComponent';
 import TrueSheetContentViewNativeComponent from './fabric/TrueSheetContentViewNativeComponent';
+import TrueSheetHeaderViewNativeComponent from './fabric/TrueSheetHeaderViewNativeComponent';
 import TrueSheetFooterViewNativeComponent from './fabric/TrueSheetFooterViewNativeComponent';
 
 import TrueSheetModule from './specs/NativeTrueSheetModule';
 
-import { Platform, processColor, StyleSheet, findNodeHandle } from 'react-native';
+import {
+  Platform,
+  StyleSheet,
+  BackHandler,
+  findNodeHandle,
+  processColor,
+  type NativeEventSubscription,
+  type GestureResponderEvent,
+} from 'react-native';
 
 const LINKING_ERROR =
   `The package '@lodev09/react-native-true-sheet' doesn't seem to be linked. Make sure: \n\n` +
@@ -44,17 +58,31 @@ if (!TrueSheetModule) {
 
 type NativeRef = ComponentRef<typeof TrueSheetViewNativeComponent>;
 
+// Claim touches that no descendant claimed so the responder negotiation
+// doesn't bubble up to touchables outside the sheet
+const absorbUnclaimedTouches = () => true;
+
+// Stop raw touch events from bubbling past the sheet to outside ancestors
+const stopTouchPropagation = (event: GestureResponderEvent) => event.stopPropagation();
+
 interface TrueSheetState {
   shouldRenderNativeView: boolean;
-  containerWidth?: number;
-  containerHeight?: number;
 }
 
-export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
+export class TrueSheet
+  extends PureComponent<TrueSheetProps, TrueSheetState>
+  implements TrueSheetMethods
+{
   displayName = 'TrueSheet';
 
   private readonly nativeRef: RefObject<NativeRef | null>;
 
+  private cachedGrabberOptions: TrueSheetProps['grabberOptions'] | undefined;
+  private resolvedGrabberOptions: Record<string, unknown> | undefined;
+  private backHandlerSubscription: NativeEventSubscription | null = null;
+  private isPresented: boolean = false;
+  private isSheetVisible: boolean = true;
+
   /**
    * Map of sheet names against their instances.
    */
@@ -65,6 +93,11 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
    */
   private presentationResolver: (() => void) | null = null;
 
+  /**
+   * Tracks if a present operation is in progress
+   */
+  private isPresenting: boolean = false;
+
   constructor(props: TrueSheetProps) {
     super(props);
 
@@ -78,8 +111,6 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
 
     this.state = {
       shouldRenderNativeView: shouldRenderImmediately,
-      containerWidth: undefined,
-      containerHeight: undefined,
     };
 
     this.onMount = this.onMount.bind(this);
@@ -92,7 +123,12 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
     this.onDragChange = this.onDragChange.bind(this);
     this.onDragEnd = this.onDragEnd.bind(this);
     this.onPositionChange = this.onPositionChange.bind(this);
-    this.onSizeChange = this.onSizeChange.bind(this);
+    this.onWillFocus = this.onWillFocus.bind(this);
+    this.onDidFocus = this.onDidFocus.bind(this);
+    this.onWillBlur = this.onWillBlur.bind(this);
+    this.onDidBlur = this.onDidBlur.bind(this);
+    this.handleBackPress = this.handleBackPress.bind(this);
+    this.onVisibilityChange = this.onVisibilityChange.bind(this);
   }
 
   private validateDetents(): void {
@@ -108,7 +144,7 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
     // Warn for invalid detent fractions
     if (detents) {
       detents.forEach((detent, index) => {
-        if (detent !== 'auto' && typeof detent === 'number') {
+        if (typeof detent === 'number' && detent !== -1 && detent !== -2) {
           if (detent <= 0 || detent > 1) {
             console.warn(
               `TrueSheet: detent at index ${index} (${detent}) should be between 0 and 1. It will be clamped.`
@@ -152,31 +188,53 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
    * Present the sheet by given `name` (Promise-based)
    * @param name - Sheet name (must match sheet's name prop)
    * @param index - Detent index (default: 0)
+   * @param animated - Whether to animate the presentation (default: true)
    * @returns Promise that resolves when sheet is fully presented
    * @throws Error if sheet not found or presentation fails
    */
-  public static async present(name: string, index: number = 0): Promise<void> {
+  public static async present(
+    name: string,
+    index: number = 0,
+    animated: boolean = true
+  ): Promise<void> {
     const instance = TrueSheet.getInstance(name);
     if (!instance) {
       throw new Error(`Sheet with name "${name}" not found`);
     }
 
-    return instance.present(index);
+    return instance.present(index, animated);
   }
 
   /**
    * Dismiss the sheet by given `name` (Promise-based)
    * @param name - Sheet name
+   * @param animated - Whether to animate the dismissal (default: true)
    * @returns Promise that resolves when sheet is fully dismissed
    * @throws Error if sheet not found or dismissal fails
    */
-  public static async dismiss(name: string): Promise<void> {
+  public static async dismiss(name: string, animated: boolean = true): Promise<void> {
     const instance = TrueSheet.getInstance(name);
     if (!instance) {
       throw new Error(`Sheet with name "${name}" not found`);
     }
 
-    return instance.dismiss();
+    return instance.dismiss(animated);
+  }
+
+  /**
+   * Dismiss only the sheets presented on top of a sheet by given `name`
+   * @param name - Sheet name
+   * @param animated - Whether to animate the dismissal (default: true)
+   * @returns Promise that resolves when all child sheets are dismissed
+   * @throws Error if sheet not found
+   */
+  public static async dismissStack(name: string, animated: boolean = true): Promise<void> {
+    const instance = TrueSheet.getInstance(name);
+    if (!instance) {
+      throw new Error(`Sheet with name "${name}" not found`);
+    }
+
+    return instance.dismissStack(animated);
   }
 
   /**
@@ -195,6 +253,16 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
     return instance.resize(index);
   }
 
+  /**
+   * Dismiss all presented sheets by dismissing from the bottom of the stack.
+   * This ensures child sheets are dismissed first before their parent.
+   * @param animated - Whether to animate the dismissals (default: true)
+   * @returns Promise that resolves when all sheets are dismissed
+   */
+  public static async dismissAll(animated: boolean = true): Promise<void> {
+    return TrueSheetModule?.dismissAll(animated);
+  }
+
   private registerInstance(): void {
     if (this.props.name) {
       TrueSheet.instances[this.props.name] = this;
@@ -216,6 +284,16 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
   }
 
   private onDidPresent(event: DidPresentEvent): void {
+    this.isPresented = true;
+
+    if (Platform.OS === 'android') {
+      this.backHandlerSubscription?.remove();
+      this.backHandlerSubscription = BackHandler.addEventListener(
+        'hardwareBackPress',
+        this.handleBackPress
+      );
+    }
+
     this.props.onDidPresent?.(event);
   }
 
@@ -224,8 +302,17 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
   }
 
   private onDidDismiss(event: DidDismissEvent): void {
-    // Clean up native view after dismiss for lazy loading
-    this.setState({ shouldRenderNativeView: false });
+    this.isPresented = false;
+    this.isSheetVisible = true;
+    this.backHandlerSubscription?.remove();
+    this.backHandlerSubscription = null;
+
+    // Clean up native view after dismiss for lazy loading.
+    // Skip unmount if a present is in progress to avoid race condition.
+    if (!this.isPresenting) {
+      this.setState({ shouldRenderNativeView: false });
+    }
+
     this.props.onDidDismiss?.(event);
   }
 
@@ -255,23 +342,50 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
     this.props.onPositionChange?.(event);
   }
 
-  private onSizeChange(event: SizeChangeEvent): void {
-    const { width, height } = event.nativeEvent;
+  private onWillFocus(event: WillFocusEvent): void {
+    this.props.onWillFocus?.(event);
+  }
 
-    // Update container view dimensions in state
-    this.setState({
-      containerWidth: width,
-      containerHeight: height,
-    });
+  private onDidFocus(event: DidFocusEvent): void {
+    this.props.onDidFocus?.(event);
+  }
 
-    // Internal handler only - not exposed to users
+  private onWillBlur(event: WillBlurEvent): void {
+    this.props.onWillBlur?.(event);
+  }
+
+  private onDidBlur(event: DidBlurEvent): void {
+    this.props.onDidBlur?.(event);
+  }
+
+  private onVisibilityChange(event: { nativeEvent: { visible: boolean } }): void {
+    this.isSheetVisible = event.nativeEvent.visible;
+  }
+
+  private handleBackPress(): boolean {
+    if (!this.isPresented || !this.isSheetVisible) return false;
+
+    // The native view can be detached (e.g. host screen unmounted by navigation)
+    // before onDidDismiss removes this subscription. Treat back press as a no-op
+    // instead of throwing from the handle getter.
+    const nodeHandle = findNodeHandle(this.nativeRef.current);
+    if (nodeHandle == null || nodeHandle === -1) return false;
+
+    // When not dismissible, let back propagate (e.g. navigation goes back to the previous screen)
+    if (this.props.dismissible === false) {
+      return this.props.onBackPress?.() ?? false;
+    }
+
+    TrueSheetModule?.handleBackPress(nodeHandle);
+    return this.props.onBackPress?.() ?? true;
   }
 
   /**
-   * Present the Sheet by `index` (Promise-based)
-   * @param index - Detent index (default: 0)
+   * Present the sheet at a given detent index.
+   * @param index - The detent index to present at (default: 0)
+   * @param animated - Whether to animate the presentation (default: true)
    */
-  public async present(index: number = 0): Promise<void> {
+  public async present(index: number = 0, animated: boolean = true): Promise<void> {
     const detentsLength = Math.min(this.props.detents?.length ?? 2, 3); // Max 3 detents
     if (index < 0 || index >= detentsLength) {
       throw new Error(
@@ -279,6 +393,8 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
       );
     }
 
+    this.isPresenting = true;
+
     // Lazy load: render native view if not already rendered
     if (!this.state.shouldRenderNativeView) {
       await new Promise<void>((resolve) => {
@@ -287,22 +403,33 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
       });
     }
 
-    return TrueSheetModule?.presentByRef(this.handle, index);
+    await TrueSheetModule?.presentByRef(this.handle, index, animated);
+    this.isPresenting = false;
   }
 
   /**
-   * Resizes the Sheet programmatically by `index`.
-   * This is an alias of the `present(index)` method.
+   * Resize the sheet to a given detent index.
+   * @param index - The detent index to resize to
    */
   public async resize(index: number): Promise<void> {
-    await this.present(index);
+    await TrueSheetModule?.resizeByRef(this.handle, index);
   }
 
   /**
-   * Dismisses the Sheet
+   * Dismiss this sheet and all sheets presented on top of it in a single animation.
+   * @param animated - Whether to animate the dismissal (default: true)
    */
-  public async dismiss(): Promise<void> {
-    return TrueSheetModule?.dismissByRef(this.handle);
+  public async dismiss(animated: boolean = true): Promise<void> {
+    return TrueSheetModule?.dismissByRef(this.handle, animated);
+  }
+
+  /**
+   * Dismiss only the sheets presented on top of this sheet, keeping this sheet presented.
+   * If no sheets are presented on top, this method does nothing.
+   * @param animated - Whether to animate the dismissal (default: true)
+   */
+  public async dismissStack(animated: boolean = true): Promise<void> {
+    return TrueSheetModule?.dismissStackByRef(this.handle, animated);
   }
 
   componentDidMount(): void {
@@ -320,35 +447,49 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
 
   componentWillUnmount(): void {
     this.unregisterInstance();
-
-    // Clean up presentation resolver
+    this.backHandlerSubscription?.remove();
+    this.backHandlerSubscription = null;
     this.presentationResolver = null;
   }
 
   render(): ReactNode {
     const {
       detents = [0.5, 1],
-      backgroundColor = 'white',
+      backgroundColor,
       dismissible = true,
+      draggable = true,
       grabber = true,
+      grabberOptions,
+      accessibilityOptions,
       dimmed = true,
       initialDetentIndex = -1,
       initialDetentAnimated = true,
-      keyboardMode = 'resize',
-      dimmedIndex,
-      blurTint,
+      dimmedDetentIndex,
+      backgroundBlur,
+      blurOptions,
       cornerRadius,
-      maxHeight,
-      edgeToEdgeFullScreen,
+      maxContentHeight,
+      maxContentWidth,
+      anchor = 'center',
+      anchorOffset,
+      scrollableOptions,
+      footerOptions,
+      presentation = 'page',
       children,
       style,
+      header,
+      headerStyle,
+      headerOptions,
       footer,
-      testID,
+      footerStyle,
+      insetAdjustment = 'automatic',
+      ...rest
     } = this.props;
 
     // Trim to max 3 detents and clamp fractions
-    const resolvedDetents = detents.slice(0, 3).map((detent) => {
+    const resolvedDetents: number[] = detents.slice(0, 3).map((detent) => {
       if (detent === 'auto' || detent === -1) return -1;
+      if (detent === 'peek' || detent === -2) return -2;
 
       // Default to 0.1 if zero or below
       if (detent <= 0) return 0.1;
@@ -357,23 +498,46 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
       return Math.min(1, detent);
     });
 
+    // Cache grabberOptions to avoid creating a new object every render
+    if (grabberOptions !== this.cachedGrabberOptions) {
+      this.cachedGrabberOptions = grabberOptions;
+      this.resolvedGrabberOptions = {
+        ...grabberOptions,
+        color: processColor(grabberOptions?.color),
+      };
+    }
+
     return (
       <TrueSheetViewNativeComponent
+        {...rest}
         ref={this.nativeRef}
         style={styles.sheetView}
         detents={resolvedDetents}
-        blurTint={blurTint}
-        background={(processColor(backgroundColor) as number) ?? 0}
+        backgroundBlur={backgroundBlur}
+        blurOptions={blurOptions}
+        backgroundColor={backgroundColor}
         cornerRadius={cornerRadius}
         grabber={grabber}
+        grabberOptions={this.resolvedGrabberOptions}
+        accessibilityOptions={accessibilityOptions}
         dimmed={dimmed}
-        dimmedIndex={dimmedIndex}
-        keyboardMode={keyboardMode}
+        dimmedDetentIndex={dimmedDetentIndex}
         initialDetentIndex={initialDetentIndex}
         initialDetentAnimated={initialDetentAnimated}
         dismissible={dismissible}
-        maxHeight={maxHeight}
-        edgeToEdgeFullScreen={edgeToEdgeFullScreen}
+        draggable={draggable}
+        maxContentHeight={maxContentHeight}
+        maxContentWidth={maxContentWidth}
+        anchor={anchor}
+        anchorOffset={anchorOffset}
+        scrollableOptions={scrollableOptions}
+        headerOptions={headerOptions}
+        footerOptions={{
+          footerPosition: footerOptions?.position,
+          keyboardOffset: footerOptions?.keyboardOffset,
+        }}
+        presentation={presentation}
+        insetAdjustment={insetAdjustment}
         onMount={this.onMount}
         onWillPresent={this.onWillPresent}
         onDidPresent={this.onDidPresent}
@@ -384,22 +548,46 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
         onDragChange={this.onDragChange}
         onDragEnd={this.onDragEnd}
         onPositionChange={this.onPositionChange}
-        onSizeChange={this.onSizeChange}
+        onWillFocus={this.onWillFocus}
+        onDidFocus={this.onDidFocus}
+        onWillBlur={this.onWillBlur}
+        onDidBlur={this.onDidBlur}
+        onVisibilityChange={this.onVisibilityChange}
       >
         {this.state.shouldRenderNativeView && (
           <TrueSheetContainerViewNativeComponent
-            testID={testID}
-            style={{
-              width: this.state.containerWidth,
-              height: this.state.containerHeight,
-            }}
-            collapsable={false}
+            style={styles.container}
+            onStartShouldSetResponder={absorbUnclaimedTouches}
+            onTouchStart={stopTouchPropagation}
+            onTouchMove={stopTouchPropagation}
+            onTouchEnd={stopTouchPropagation}
+            onTouchCancel={stopTouchPropagation}
           >
-            <TrueSheetContentViewNativeComponent style={style} collapsable={false}>
+            {header && (
+              <TrueSheetHeaderViewNativeComponent
+                style={[
+                  styles.header,
+                  headerOptions?.position === 'absolute' && styles.absoluteHeader,
+                  headerStyle,
+                ]}
+              >
+                {isValidElement(header) ? header : createElement(header)}
+              </TrueSheetHeaderViewNativeComponent>
+            )}
+            <TrueSheetContentViewNativeComponent style={style}>
               {children}
             </TrueSheetContentViewNativeComponent>
             {footer && (
-              <TrueSheetFooterViewNativeComponent style={styles.footer} collapsable={false}>
+              <TrueSheetFooterViewNativeComponent
+                autoBottomInset={insetAdjustment === 'automatic'}
+                style={[
+                  styles.footer,
+                  footerOptions?.position === 'absolute'
+                    ? styles.absoluteFooter
+                    : styles.relativeFooter,
+                  footerStyle,
+                ]}
+              >
                 {isValidElement(footer) ? footer : createElement(footer)}
               </TrueSheetFooterViewNativeComponent>
             )}
@@ -410,15 +598,43 @@ export class TrueSheet extends PureComponent<TrueSheetProps, TrueSheetState> {
   }
 }
 
+// Compile-time check: `TrueSheet`'s static surface must satisfy `TrueSheetStaticMethods`.
+TrueSheet satisfies TrueSheetStaticMethods;
+
 const styles = StyleSheet.create({
   sheetView: {
-    position: 'absolute',
-    width: '100%',
+    ...StyleSheet.absoluteFill,
     zIndex: -9999,
+    pointerEvents: 'box-none',
+  },
+  // Fill the sheet so flex layouts track the sheet's size per detent
+  container: {
+    ...StyleSheet.absoluteFill,
+  },
+  header: {
+    pointerEvents: 'box-none',
+  },
+  // Floats over the content so it doesn't take up layout space
+  absoluteHeader: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    zIndex: 1,
   },
   footer: {
+    pointerEvents: 'box-none',
+  },
+  // Pinned to the sheet's bottom edge via Yoga since the container tracks the
+  // sheet's visible height — takes up layout space below the content
+  relativeFooter: {
+    marginTop: 'auto',
+  },
+  // Floats over the content so it doesn't take up layout space
+  absoluteFooter: {
     position: 'absolute',
     left: 0,
     right: 0,
+    bottom: 0,
   },
 });