@lodev09/react-native-true-sheet 3.0.0-beta.12 → 3.0.0-beta.13

package/README.md

@@ -13,7 +13,7 @@ The true native bottom sheet experience for your React Native Apps. 💩
 * 🚀 **Native** - Implemented in the native realm
 * 🎯 **Type-safe** - Full TypeScript support with Codegen-generated native interfaces
 * ♿ **Accessible** - Native accessibility and screen reader support out of the box
-* 🔄 **Imperative API** - Asynchronus `ref` [Methods](https://sheet.lodev09.com/reference/methods#ref-methods)
+* 🔄 **Flexible API** - Use [imperative methods](https://sheet.lodev09.com/reference/methods#ref-methods) or [lifecycle events](https://sheet.lodev09.com/reference/props#events)
 * 🪟 **Liquid Glass** - iOS 26+ Liquid Glass support out of the box. Featured in [Expo Blog](https://expo.dev/blog/how-to-create-apple-maps-style-liquid-glass-sheets)
 
 ## Installation

package/android/src/main/java/com/lodev09/truesheet/TrueSheetModule.kt

@@ -8,6 +8,7 @@ import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.turbomodule.core.interfaces.TurboModule
 import com.facebook.react.uimanager.UIManagerHelper
+import com.lodev09.truesheet.core.TrueSheetDialogObserver
 import java.util.concurrent.ConcurrentHashMap
 
 /**
@@ -27,10 +28,11 @@ class TrueSheetModule(reactContext: ReactApplicationContext) :
 
   override fun invalidate() {
     super.invalidate()
-    // Clear all registered views on module invalidation
+    // Clear all registered views and observer on module invalidation
     synchronized(viewRegistry) {
       viewRegistry.clear()
     }
+    TrueSheetDialogObserver.clear()
   }
 
   /**

package/android/src/main/java/com/lodev09/truesheet/TrueSheetView.kt

@@ -2,7 +2,6 @@ package com.lodev09.truesheet
 
 import android.annotation.SuppressLint
 import android.view.View
-import android.view.ViewGroup
 import android.view.ViewStructure
 import android.view.accessibility.AccessibilityEvent
 import androidx.annotation.UiThread
@@ -14,12 +13,15 @@ import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.UIManagerHelper
 import com.facebook.react.uimanager.events.EventDispatcher
 import com.facebook.react.views.view.ReactViewGroup
+import com.lodev09.truesheet.core.TrueSheetDialogObserver
+import com.lodev09.truesheet.events.BlurEvent
 import com.lodev09.truesheet.events.DetentChangeEvent
 import com.lodev09.truesheet.events.DidDismissEvent
 import com.lodev09.truesheet.events.DidPresentEvent
 import com.lodev09.truesheet.events.DragBeginEvent
 import com.lodev09.truesheet.events.DragChangeEvent
 import com.lodev09.truesheet.events.DragEndEvent
+import com.lodev09.truesheet.events.FocusEvent
 import com.lodev09.truesheet.events.MountEvent
 import com.lodev09.truesheet.events.PositionChangeEvent
 import com.lodev09.truesheet.events.WillDismissEvent
@@ -36,7 +38,7 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
   TrueSheetViewControllerDelegate,
   TrueSheetContainerViewDelegate {
 
-  private val viewController: TrueSheetViewController = TrueSheetViewController(reactContext)
+  internal val viewController: TrueSheetViewController = TrueSheetViewController(reactContext)
 
   private val containerView: TrueSheetContainerView?
     get() = viewController.getChildAt(0) as? TrueSheetContainerView
@@ -63,9 +65,6 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
   // Flag to prevent multiple pending sheet updates
   private var isSheetUpdatePending: Boolean = false
 
-  // Reference to parent sheet's controller (for stacking support)
-  private var parentViewController: TrueSheetViewController? = null
-
   init {
     reactContext.addLifecycleEventListener(this)
     viewController.delegate = this
@@ -144,6 +143,7 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
   fun onDropInstance() {
     reactContext.removeLifecycleEventListener(this)
     TrueSheetModule.unregisterView(id)
+    TrueSheetDialogObserver.removeSheet(this)
 
     if (viewController.isPresented) {
       viewController.dismiss()
@@ -164,14 +164,14 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
 
   // ==================== TrueSheetViewControllerDelegate Implementation ====================
 
-  override fun viewControllerWillPresent(index: Int, position: Float) {
+  override fun viewControllerWillPresent(index: Int, position: Float, detent: Float) {
     val surfaceId = UIManagerHelper.getSurfaceId(this)
-    eventDispatcher?.dispatchEvent(WillPresentEvent(surfaceId, id, index, position))
+    eventDispatcher?.dispatchEvent(WillPresentEvent(surfaceId, id, index, position, detent))
   }
 
-  override fun viewControllerDidPresent(index: Int, position: Float) {
+  override fun viewControllerDidPresent(index: Int, position: Float, detent: Float) {
     val surfaceId = UIManagerHelper.getSurfaceId(this)
-    eventDispatcher?.dispatchEvent(DidPresentEvent(surfaceId, id, index, position))
+    eventDispatcher?.dispatchEvent(DidPresentEvent(surfaceId, id, index, position, detent))
 
     // Enable touch event dispatching to React Native
     viewController.eventDispatcher = eventDispatcher
@@ -191,40 +191,49 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
     val surfaceId = UIManagerHelper.getSurfaceId(this)
     eventDispatcher?.dispatchEvent(DidDismissEvent(surfaceId, id))
 
-    // Show parent sheet again if this was a stacked sheet
-    parentViewController?.showDialog()
-    parentViewController = null
+    // Notify observer that this sheet was dismissed (will show/focus parent sheet)
+    TrueSheetDialogObserver.onSheetDidDismiss(this)
   }
 
-  override fun viewControllerDidChangeDetent(index: Int, position: Float) {
+  override fun viewControllerDidChangeDetent(index: Int, position: Float, detent: Float) {
     val surfaceId = UIManagerHelper.getSurfaceId(this)
-    eventDispatcher?.dispatchEvent(DetentChangeEvent(surfaceId, id, index, position))
+    eventDispatcher?.dispatchEvent(DetentChangeEvent(surfaceId, id, index, position, detent))
   }
 
-  override fun viewControllerDidDragBegin(index: Int, position: Float) {
+  override fun viewControllerDidDragBegin(index: Int, position: Float, detent: Float) {
     val surfaceId = UIManagerHelper.getSurfaceId(this)
-    eventDispatcher?.dispatchEvent(DragBeginEvent(surfaceId, id, index, position))
+    eventDispatcher?.dispatchEvent(DragBeginEvent(surfaceId, id, index, position, detent))
   }
 
-  override fun viewControllerDidDragChange(index: Int, position: Float) {
+  override fun viewControllerDidDragChange(index: Int, position: Float, detent: Float) {
     val surfaceId = UIManagerHelper.getSurfaceId(this)
-    eventDispatcher?.dispatchEvent(DragChangeEvent(surfaceId, id, index, position))
+    eventDispatcher?.dispatchEvent(DragChangeEvent(surfaceId, id, index, position, detent))
   }
 
-  override fun viewControllerDidDragEnd(index: Int, position: Float) {
+  override fun viewControllerDidDragEnd(index: Int, position: Float, detent: Float) {
     val surfaceId = UIManagerHelper.getSurfaceId(this)
-    eventDispatcher?.dispatchEvent(DragEndEvent(surfaceId, id, index, position))
+    eventDispatcher?.dispatchEvent(DragEndEvent(surfaceId, id, index, position, detent))
   }
 
-  override fun viewControllerDidChangePosition(index: Int, position: Float, transitioning: Boolean) {
+  override fun viewControllerDidChangePosition(index: Float, position: Float, detent: Float, transitioning: Boolean) {
     val surfaceId = UIManagerHelper.getSurfaceId(this)
-    eventDispatcher?.dispatchEvent(PositionChangeEvent(surfaceId, id, index, position, transitioning))
+    eventDispatcher?.dispatchEvent(PositionChangeEvent(surfaceId, id, index, position, detent, transitioning))
   }
 
   override fun viewControllerDidChangeSize(width: Int, height: Int) {
     updateState(width, height)
   }
 
+  override fun viewControllerDidFocus() {
+    val surfaceId = UIManagerHelper.getSurfaceId(this)
+    eventDispatcher?.dispatchEvent(FocusEvent(surfaceId, id))
+  }
+
+  override fun viewControllerDidBlur() {
+    val surfaceId = UIManagerHelper.getSurfaceId(this)
+    eventDispatcher?.dispatchEvent(BlurEvent(surfaceId, id))
+  }
+
   // ==================== Property Setters (forward to controller) ====================
 
   fun setMaxHeight(height: Int) {
@@ -300,15 +309,9 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
 
   @UiThread
   fun present(detentIndex: Int, animated: Boolean = true, promiseCallback: () -> Unit) {
-    // Find and hide parent sheet if this sheet is nested inside another TrueSheet
-    // Only hide if parent is not expanded (otherwise it's already covering the screen)
+    // Notify observer that this sheet will present (will hide/blur topmost sheet)
     if (!viewController.isPresented) {
-      parentViewController = findParentViewController()
-      if (parentViewController?.isExpanded == false) {
-        parentViewController?.hideDialog()
-      } else {
-        parentViewController = null
-      }
+      TrueSheetDialogObserver.onSheetWillPresent(this, detentIndex)
     }
 
     viewController.presentPromise = promiseCallback
@@ -321,21 +324,6 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
     viewController.dismiss()
   }
 
-  /**
-   * Traverses up the view hierarchy to find a parent TrueSheetViewController.
-   * This is used to detect if this sheet is nested inside another TrueSheet's content.
-   */
-  private fun findParentViewController(): TrueSheetViewController? {
-    var current: ViewGroup? = parent as? ViewGroup
-    while (current != null) {
-      if (current is TrueSheetViewController) {
-        return current
-      }
-      current = current.parent as? ViewGroup
-    }
-    return null
-  }
-
   /**
    * Debounced sheet update to handle rapid content/header size changes.
    * Uses post to ensure all layout passes complete before reconfiguring.

package/android/src/main/java/com/lodev09/truesheet/TrueSheetViewController.kt

@@ -31,16 +31,18 @@ import com.lodev09.truesheet.utils.ScreenUtils
 data class DetentInfo(val index: Int, val position: Float)
 
 interface TrueSheetViewControllerDelegate {
-  fun viewControllerWillPresent(index: Int, position: Float)
-  fun viewControllerDidPresent(index: Int, position: Float)
+  fun viewControllerWillPresent(index: Int, position: Float, detent: Float)
+  fun viewControllerDidPresent(index: Int, position: Float, detent: Float)
   fun viewControllerWillDismiss()
   fun viewControllerDidDismiss()
-  fun viewControllerDidChangeDetent(index: Int, position: Float)
-  fun viewControllerDidDragBegin(index: Int, position: Float)
-  fun viewControllerDidDragChange(index: Int, position: Float)
-  fun viewControllerDidDragEnd(index: Int, position: Float)
-  fun viewControllerDidChangePosition(index: Int, position: Float, transitioning: Boolean)
+  fun viewControllerDidChangeDetent(index: Int, position: Float, detent: Float)
+  fun viewControllerDidDragBegin(index: Int, position: Float, detent: Float)
+  fun viewControllerDidDragChange(index: Int, position: Float, detent: Float)
+  fun viewControllerDidDragEnd(index: Int, position: Float, detent: Float)
+  fun viewControllerDidChangePosition(index: Float, position: Float, detent: Float, transitioning: Boolean)
   fun viewControllerDidChangeSize(width: Int, height: Int)
+  fun viewControllerDidFocus()
+  fun viewControllerDidBlur()
 }
 
 /**
@@ -112,6 +114,7 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
 
   private var isDragging = false
   private var windowAnimation: Int = 0
+  private var lastEmittedPositionPx: Int = -1
 
   var presentPromise: (() -> Unit)? = null
   var dismissPromise: (() -> Unit)? = null
@@ -206,7 +209,7 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
     val style = if (edgeToEdgeEnabled) {
       com.lodev09.truesheet.R.style.TrueSheetEdgeToEdgeEnabledDialog
     } else {
-      0
+      com.lodev09.truesheet.R.style.TrueSheetDialog
     }
 
     dialog = BottomSheetDialog(reactContext, style).apply {
@@ -239,6 +242,7 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
     dialog = null
     isDragging = false
     isPresented = false
+    lastEmittedPositionPx = -1
   }
 
   private fun setupDialogListeners(dialog: BottomSheetDialog) {
@@ -250,8 +254,10 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
 
       sheetContainer?.post {
         val detentInfo = getDetentInfoForIndex(currentDetentIndex)
-        delegate?.viewControllerDidPresent(detentInfo.index, detentInfo.position)
-        delegate?.viewControllerDidChangePosition(detentInfo.index, detentInfo.position, transitioning = true)
+        val detent = getDetentValueForIndex(detentInfo.index)
+        val positionPx = bottomSheetView?.let { ScreenUtils.getScreenY(it) } ?: screenHeight
+        delegate?.viewControllerDidPresent(detentInfo.index, detentInfo.position, detent)
+        emitChangePositionDelegate(detentInfo.index, positionPx, transitioning = true)
 
         presentPromise?.invoke()
         presentPromise = null
@@ -277,8 +283,10 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
       object : BottomSheetBehavior.BottomSheetCallback() {
         override fun onSlide(sheetView: View, slideOffset: Float) {
           val behavior = behavior ?: return
-          val detentInfo = getCurrentDetentInfo(sheetView)
-          delegate?.viewControllerDidChangePosition(detentInfo.index, detentInfo.position, transitioning = false)
+          val positionPx = getCurrentPositionPx(sheetView)
+          val detentIndex = getDetentIndexForPosition(positionPx)
+
+          emitChangePositionDelegate(detentIndex, positionPx, transitioning = false)
 
           when (behavior.state) {
             BottomSheetBehavior.STATE_DRAGGING,
@@ -347,12 +355,32 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
       return sheetTop <= statusBarHeight
     }
 
+  /**
+   * Returns the current top position of the sheet (Y coordinate from screen top).
+   * Used for comparing sheet positions during stacking.
+   */
+  val currentSheetTop: Int
+    get() = bottomSheetView?.let { ScreenUtils.getScreenY(it) } ?: screenHeight
+
+  /**
+   * Returns the expected top position of the sheet when presented at the given detent index.
+   * Used for comparing sheet positions before presentation.
+   */
+  fun getExpectedSheetTop(detentIndex: Int): Int {
+    if (detentIndex < 0 || detentIndex >= detents.size) return screenHeight
+    val detentHeight = getDetentHeight(detents[detentIndex])
+    return screenHeight - detentHeight
+  }
+
   /**
    * Hides the dialog without dismissing it.
    * Used when another TrueSheet presents on top.
    */
   fun hideDialog() {
     dialog?.window?.decorView?.visibility = View.INVISIBLE
+
+    // Emit off-screen position (detent = 0 since sheet is fully hidden)
+    emitChangePositionDelegate(currentDetentIndex, screenHeight, transitioning = true)
   }
 
   /**
@@ -361,6 +389,10 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
    */
   fun showDialog() {
     dialog?.window?.decorView?.visibility = View.VISIBLE
+
+    // Emit current position
+    val positionPx = bottomSheetView?.let { ScreenUtils.getScreenY(it) } ?: screenHeight
+    emitChangePositionDelegate(currentDetentIndex, positionPx, transitioning = true)
   }
 
   // ====================================================================
@@ -378,7 +410,8 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
 
     if (isPresented) {
       val detentInfo = getDetentInfoForIndex(detentIndex)
-      delegate?.viewControllerDidChangeDetent(detentInfo.index, detentInfo.position)
+      val detent = getDetentValueForIndex(detentInfo.index)
+      delegate?.viewControllerDidChangeDetent(detentInfo.index, detentInfo.position, detent)
       setStateForDetentIndex(detentIndex)
     } else {
       isDragging = false
@@ -386,7 +419,8 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
       setStateForDetentIndex(detentIndex)
 
       val detentInfo = getDetentInfoForIndex(detentIndex)
-      delegate?.viewControllerWillPresent(detentInfo.index, detentInfo.position)
+      val detent = getDetentValueForIndex(detentInfo.index)
+      delegate?.viewControllerWillPresent(detentInfo.index, detentInfo.position, detent)
 
       if (!animated) {
         dialog.window?.setWindowAnimations(0)
@@ -398,8 +432,8 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
 
   fun dismiss() {
     this.post {
-      val offScreenPosition = screenHeight.pxToDp()
-      delegate?.viewControllerDidChangePosition(currentDetentIndex, offScreenPosition, transitioning = true)
+      // Emit off-screen position (detent = 0 since sheet is fully hidden)
+      emitChangePositionDelegate(currentDetentIndex, screenHeight, transitioning = true)
     }
     dialog?.dismiss()
   }
@@ -565,6 +599,76 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
     }
   }
 
+  // ====================================================================
+  // MARK: - Position Change Delegate
+  // ====================================================================
+
+  /**
+   * Emits position change to the delegate if the position has changed.
+   * @param index The current detent index (discrete, used as fallback)
+   * @param positionPx The current position in pixels (screen Y coordinate)
+   * @param transitioning Whether the sheet is transitioning (programmatic) vs dragging
+   */
+  private fun emitChangePositionDelegate(index: Int, positionPx: Int, transitioning: Boolean) {
+    if (positionPx == lastEmittedPositionPx) return
+
+    lastEmittedPositionPx = positionPx
+    val position = positionPx.pxToDp()
+    val interpolatedIndex = getInterpolatedIndexForPosition(positionPx)
+    val detent = getDetentValueForIndex(kotlin.math.round(interpolatedIndex).toInt())
+    delegate?.viewControllerDidChangePosition(interpolatedIndex, position, detent, transitioning)
+  }
+
+  /**
+   * Calculates the interpolated index based on position.
+   * Returns a continuous value (e.g., 0.5 means halfway between detent 0 and 1).
+   */
+  private fun getInterpolatedIndexForPosition(positionPx: Int): Float {
+    val count = detents.size
+    if (count == 0) return -1f
+    if (count == 1) return 0f
+
+    // Convert position to detent fraction
+    val currentDetent = (screenHeight - positionPx).toFloat() / screenHeight.toFloat()
+
+    // Handle below first detent (interpolate from -1 to 0)
+    val firstDetentValue = getDetentValueForIndex(0)
+    if (currentDetent < firstDetentValue) {
+      if (firstDetentValue <= 0) return 0f
+      val progress = currentDetent / firstDetentValue
+      return progress - 1f
+    }
+
+    // Find which segment the current detent falls into and interpolate
+    for (i in 0 until count - 1) {
+      val detentValue = getDetentValueForIndex(i)
+      val nextDetentValue = getDetentValueForIndex(i + 1)
+
+      if (currentDetent <= nextDetentValue) {
+        val range = nextDetentValue - detentValue
+        if (range <= 0) return i.toFloat()
+        val progress = (currentDetent - detentValue) / range
+        return i + maxOf(0f, minOf(1f, progress))
+      }
+    }
+
+    return (count - 1).toFloat()
+  }
+
+  /**
+   * Gets the detent value (fraction) for a given index.
+   * For auto (-1), calculates the actual fraction from content + header height.
+   */
+  private fun getDetentValueForIndex(index: Int): Float {
+    if (index < 0 || index >= detents.size) return 0f
+    val value = detents[index]
+    return if (value == -1.0) {
+      (contentHeight + headerHeight).toFloat() / screenHeight.toFloat()
+    } else {
+      value.toFloat()
+    }
+  }
+
   // ====================================================================
   // MARK: - Drag Handling
   // ====================================================================
@@ -574,16 +678,40 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
     return DetentInfo(currentDetentIndex, screenY.pxToDp())
   }
 
+  private fun getCurrentPositionPx(sheetView: View): Int = ScreenUtils.getScreenY(sheetView)
+
+  /**
+   * Returns the detent index for the current position.
+   * Only reports a higher index when the sheet has reached that detent's height.
+   */
+  private fun getDetentIndexForPosition(positionPx: Int): Int {
+    if (detents.isEmpty()) return 0
+
+    val sheetHeight = screenHeight - positionPx
+
+    // Find the highest detent index that the sheet has reached
+    for (i in detents.indices.reversed()) {
+      val detentHeight = getDetentHeight(detents[i])
+      if (sheetHeight >= detentHeight) {
+        return i
+      }
+    }
+
+    return 0
+  }
+
   private fun handleDragBegin(sheetView: View) {
     val detentInfo = getCurrentDetentInfo(sheetView)
-    delegate?.viewControllerDidDragBegin(detentInfo.index, detentInfo.position)
+    val detent = getDetentValueForIndex(detentInfo.index)
+    delegate?.viewControllerDidDragBegin(detentInfo.index, detentInfo.position, detent)
     isDragging = true
   }
 
   private fun handleDragChange(sheetView: View) {
     if (!isDragging) return
     val detentInfo = getCurrentDetentInfo(sheetView)
-    delegate?.viewControllerDidDragChange(detentInfo.index, detentInfo.position)
+    val detent = getDetentValueForIndex(detentInfo.index)
+    delegate?.viewControllerDidDragChange(detentInfo.index, detentInfo.position, detent)
   }
 
   private fun handleDragEnd(state: Int) {
@@ -591,7 +719,8 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
 
     val detentInfo = getDetentInfoForState(state)
     detentInfo?.let {
-      delegate?.viewControllerDidDragEnd(it.index, it.position)
+      val detent = getDetentValueForIndex(it.index)
+      delegate?.viewControllerDidDragEnd(it.index, it.position, detent)
 
       if (it.index != currentDetentIndex) {
         presentPromise?.invoke()
@@ -599,7 +728,7 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
 
         currentDetentIndex = it.index
         setupDimmedBackground(it.index)
-        delegate?.viewControllerDidChangeDetent(it.index, it.position)
+        delegate?.viewControllerDidChangeDetent(it.index, it.position, detent)
       }
     }
 
@@ -705,8 +834,8 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
       setupSheetDetents()
       this.post {
         positionFooter()
-        val detentInfo = getDetentInfoForIndex(currentDetentIndex)
-        delegate?.viewControllerDidChangePosition(detentInfo.index, detentInfo.position, transitioning = true)
+        val positionPx = bottomSheetView?.let { ScreenUtils.getScreenY(it) } ?: screenHeight
+        emitChangePositionDelegate(currentDetentIndex, positionPx, transitioning = true)
       }
     }
   }

package/android/src/main/java/com/lodev09/truesheet/core/TrueSheetDialogObserver.kt

@@ -0,0 +1,93 @@
+package com.lodev09.truesheet.core
+
+import com.lodev09.truesheet.TrueSheetView
+
+/**
+ * Observes TrueSheet dialog lifecycle to manage sheet stacking.
+ * Automatically hides/shows sheets and dispatches focus/blur events
+ * when sheets are presented on top of each other.
+ */
+object TrueSheetDialogObserver {
+
+  /**
+   * Stack of currently presented sheet views (most recent on top)
+   */
+  private val presentedSheetStack = mutableListOf<TrueSheetView>()
+
+  /**
+   * Called when a sheet is about to be presented.
+   * Hides and blurs the current topmost sheet if exists.
+   *
+   * @param sheetView The sheet that is about to be presented
+   * @param detentIndex The detent index the sheet will be presented at
+   */
+  @JvmStatic
+  fun onSheetWillPresent(sheetView: TrueSheetView, detentIndex: Int) {
+    synchronized(presentedSheetStack) {
+      // Get the current topmost sheet
+      val topSheet = presentedSheetStack.lastOrNull()
+
+      // Hide and blur the topmost sheet if it exists
+      topSheet?.let {
+        // Don't hide if the top sheet is fully expanded (covers the screen)
+        // or if the top sheet is smaller than the presenting sheet
+        // A smaller topSheetTop value means the sheet is taller (closer to top of screen)
+        val topSheetTop = it.viewController.currentSheetTop
+        val presentingSheetTop = sheetView.viewController.getExpectedSheetTop(detentIndex)
+
+        if (!it.viewController.isExpanded && topSheetTop <= presentingSheetTop) {
+          it.viewController.hideDialog()
+        }
+        it.viewControllerDidBlur()
+      }
+
+      // Add new sheet to stack
+      if (!presentedSheetStack.contains(sheetView)) {
+        presentedSheetStack.add(sheetView)
+      }
+    }
+  }
+
+  /**
+   * Called when a sheet has been dismissed.
+   * Shows and focuses the sheet below it (if any).
+   *
+   * @param sheetView The sheet that was dismissed
+   */
+  @JvmStatic
+  fun onSheetDidDismiss(sheetView: TrueSheetView) {
+    synchronized(presentedSheetStack) {
+      presentedSheetStack.remove(sheetView)
+
+      // Show and focus the new topmost sheet
+      presentedSheetStack.lastOrNull()?.let {
+        it.viewController.showDialog()
+        it.viewControllerDidFocus()
+      }
+    }
+  }
+
+  /**
+   * Removes a sheet from the stack without triggering focus events.
+   * Used when a sheet is being destroyed/cleaned up.
+   *
+   * @param sheetView The sheet to remove
+   */
+  @JvmStatic
+  fun removeSheet(sheetView: TrueSheetView) {
+    synchronized(presentedSheetStack) {
+      presentedSheetStack.remove(sheetView)
+    }
+  }
+
+  /**
+   * Clears all tracked sheets.
+   * Used when the module is invalidated.
+   */
+  @JvmStatic
+  fun clear() {
+    synchronized(presentedSheetStack) {
+      presentedSheetStack.clear()
+    }
+  }
+}

package/android/src/main/java/com/lodev09/truesheet/events/BlurEvent.kt

@@ -0,0 +1,20 @@
+package com.lodev09.truesheet.events
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.events.Event
+
+/**
+ * Fired when the sheet loses focus because another sheet is presented on top of it
+ */
+class BlurEvent(surfaceId: Int, viewId: Int) : Event<BlurEvent>(surfaceId, viewId) {
+
+  override fun getEventName(): String = EVENT_NAME
+
+  override fun getEventData(): WritableMap = Arguments.createMap()
+
+  companion object {
+    const val EVENT_NAME = "topDidBlur"
+    const val REGISTRATION_NAME = "onDidBlur"
+  }
+}

package/android/src/main/java/com/lodev09/truesheet/events/DetentChangeEvent.kt

@@ -8,7 +8,7 @@ import com.facebook.react.uimanager.events.Event
  * Fired when the active detent changes
  * Payload: { index: number, position: number }
  */
-class DetentChangeEvent(surfaceId: Int, viewId: Int, private val index: Int, private val position: Float) :
+class DetentChangeEvent(surfaceId: Int, viewId: Int, private val index: Int, private val position: Float, private val detent: Float) :
   Event<DetentChangeEvent>(surfaceId, viewId) {
 
   override fun getEventName(): String = EVENT_NAME
@@ -17,6 +17,7 @@ class DetentChangeEvent(surfaceId: Int, viewId: Int, private val index: Int, pri
     Arguments.createMap().apply {
       putInt("index", index)
       putDouble("position", position.toDouble())
+      putDouble("detent", detent.toDouble())
     }
 
   companion object {

package/android/src/main/java/com/lodev09/truesheet/events/DidPresentEvent.kt

@@ -8,7 +8,7 @@ import com.facebook.react.uimanager.events.Event
  * Fired after the sheet presentation is complete
  * Payload: { index: number, position: number }
  */
-class DidPresentEvent(surfaceId: Int, viewId: Int, private val index: Int, private val position: Float) :
+class DidPresentEvent(surfaceId: Int, viewId: Int, private val index: Int, private val position: Float, private val detent: Float) :
   Event<DidPresentEvent>(surfaceId, viewId) {
 
   override fun getEventName(): String = EVENT_NAME
@@ -17,6 +17,7 @@ class DidPresentEvent(surfaceId: Int, viewId: Int, private val index: Int, priva
     Arguments.createMap().apply {
       putInt("index", index)
       putDouble("position", position.toDouble())
+      putDouble("detent", detent.toDouble())
     }
 
   companion object {

package/android/src/main/java/com/lodev09/truesheet/events/DragBeginEvent.kt

@@ -8,7 +8,7 @@ import com.facebook.react.uimanager.events.Event
  * Fired when user starts dragging the sheet
  * Payload: { index: number, position: number }
  */
-class DragBeginEvent(surfaceId: Int, viewId: Int, private val index: Int, private val position: Float) :
+class DragBeginEvent(surfaceId: Int, viewId: Int, private val index: Int, private val position: Float, private val detent: Float) :
   Event<DragBeginEvent>(surfaceId, viewId) {
 
   override fun getEventName(): String = EVENT_NAME
@@ -17,6 +17,7 @@ class DragBeginEvent(surfaceId: Int, viewId: Int, private val index: Int, privat
     Arguments.createMap().apply {
       putInt("index", index)
       putDouble("position", position.toDouble())
+      putDouble("detent", detent.toDouble())
     }
 
   companion object {