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

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

@@ -0,0 +1,375 @@
+package com.lodev09.truesheet.core
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.content.res.Configuration
+import android.view.MotionEvent
+import android.view.View
+import android.view.ViewConfiguration
+import android.view.ViewGroup
+import android.widget.EditText
+import androidx.coordinatorlayout.widget.CoordinatorLayout
+import androidx.swiperefreshlayout.widget.SwipeRefreshLayout
+import com.facebook.react.uimanager.PixelUtil.dpToPx
+import com.facebook.react.uimanager.PointerEvents
+import com.facebook.react.uimanager.ReactPointerEventsView
+import com.facebook.react.uimanager.TouchTargetHelper
+import com.lodev09.truesheet.utils.KeyboardUtils
+import com.lodev09.truesheet.utils.isDescendantOf
+
+interface TrueSheetCoordinatorLayoutDelegate {
+  fun coordinatorLayoutDidLayout(changed: Boolean)
+  fun coordinatorLayoutDidChangeConfiguration()
+  fun findScrollView(): ViewGroup?
+  fun findSheetView(): TrueSheetBottomSheetView?
+
+  /**
+   * A downward pull the sheet couldn't follow ended; `overdragPx` is the travel it
+   * didn't follow, `keyboardWasVisible` whether the keyboard was up when it began.
+   */
+  fun coordinatorLayoutDidPullDown(overdragPx: Int, keyboardWasVisible: Boolean)
+}
+
+/**
+ * Custom CoordinatorLayout that hosts the bottom sheet and dim view.
+ * Implements ReactPointerEventsView to allow touch events to pass through
+ * to underlying React Native views when appropriate.
+ */
+@SuppressLint("ViewConstructor")
+class TrueSheetCoordinatorLayout(context: Context) :
+  CoordinatorLayout(context),
+  ReactPointerEventsView {
+
+  var delegate: TrueSheetCoordinatorLayoutDelegate? = null
+
+  private val touchSlop: Int = ViewConfiguration.get(context).scaledTouchSlop
+  private var dragging = false
+  private var initialY = 0f
+  private var activePointerId = 0
+
+  // Horizontal-dominance tracking. iOS lets horizontal child gestures win over
+  // the sheet's vertical pan; we mirror that by locking out BottomSheetBehavior
+  // interception once the first significant movement of a stream is horizontal.
+  private var streamInitialX = 0f
+  private var streamInitialY = 0f
+  private var streamHorizontalLocked = false
+  private var streamDirectionDecided = false
+
+  // Native-gesture-claim tracking. RNGH handlers activate past BottomSheetBehavior's
+  // drag slop and never call requestDisallowInterceptTouchEvent, so the sheet would
+  // steal vertical gestures (e.g. a vertical pan) before they can activate. While the
+  // touch is inside a descendant GestureHandlerRootView we hold off interception within
+  // a grace distance; once a child claims the gesture (relayed from the RootView impls
+  // via childDidClaimNativeGesture) we yield the rest of the stream, mirroring iOS.
+  private var streamHasGestureRoot = false
+  private var streamGestureClaimed = false
+
+  // Whether the sheet owns vertical drags for this stream: the touch target is inside
+  // the sheet but outside the detected scrollable (e.g. a header overlaying it), with
+  // nothing vertically scrollable along its chain. Such targets consume the stream
+  // natively (no nested scroll), and BottomSheetBehavior won't intercept because the
+  // scrollable's bounds still contain the point (touchingScrollingChild) — intercept
+  // manually.
+  private var streamSheetDraggable = false
+  private var streamDraggableEditText = false
+
+  // Pull-down tracking. BottomSheetBehavior gives no callback when a downward drag
+  // is clamped by `isHideable = false` — the sheet stays put (or the scrollable
+  // overscrolls) and no state change fires. Accumulate the downward finger travel
+  // neither the sheet nor its scrollable followed and report it on release so the
+  // controller can surface a blocked dismiss attempt.
+  private var pullTracking = false
+  private var pullStartX = 0f
+  private var pullStartY = 0f
+  private var pullLastY = 0f
+  private var pullOverdrag = 0f
+  private var pullKeyboardVisible = false
+
+  init {
+    layoutParams = LayoutParams(
+      LayoutParams.MATCH_PARENT,
+      LayoutParams.MATCH_PARENT
+    )
+
+    clipChildren = false
+    clipToPadding = false
+  }
+
+  override fun onLayout(
+    changed: Boolean,
+    l: Int,
+    t: Int,
+    r: Int,
+    b: Int
+  ) {
+    super.onLayout(changed, l, t, r, b)
+    delegate?.coordinatorLayoutDidLayout(changed)
+  }
+
+  override fun onConfigurationChanged(newConfig: Configuration?) {
+    super.onConfigurationChanged(newConfig)
+    delegate?.coordinatorLayoutDidChangeConfiguration()
+  }
+
+  override val pointerEvents: PointerEvents
+    get() = PointerEvents.BOX_NONE
+
+  override fun dispatchTouchEvent(ev: MotionEvent): Boolean {
+    when (ev.actionMasked) {
+      MotionEvent.ACTION_DOWN -> {
+        val sheet = delegate?.findSheetView()
+        pullTracking = sheet != null && isTouchInside(sheet, ev)
+        pullStartX = ev.rawX
+        pullStartY = ev.rawY
+        pullLastY = ev.rawY
+        pullOverdrag = 0f
+        pullKeyboardVisible = pullTracking && KeyboardUtils.isKeyboardVisible(this)
+      }
+
+      MotionEvent.ACTION_MOVE -> if (pullTracking) {
+        val sheet = delegate?.findSheetView()
+        val topBefore = sheet?.top
+        val handled = super.dispatchTouchEvent(ev)
+        val step = ev.rawY - pullLastY
+        pullLastY = ev.rawY
+        // Finger moved down but the sheet stayed put and the scrollable is at
+        // its top — the pull was clamped
+        if (step > 0 && sheet != null && sheet.top == topBefore && delegate?.findScrollView()?.canScrollVertically(-1) != true) {
+          pullOverdrag += step
+        }
+        return handled
+      }
+
+      MotionEvent.ACTION_UP -> if (pullTracking) {
+        pullTracking = false
+        val dx = kotlin.math.abs(ev.rawX - pullStartX)
+        val dy = ev.rawY - pullStartY
+        // Let the behavior settle first so the controller sees the resting position.
+        val handled = super.dispatchTouchEvent(ev)
+        if (dy > dx && pullOverdrag > PULL_DOWN_THRESHOLD_DP.dpToPx()) {
+          delegate?.coordinatorLayoutDidPullDown(pullOverdrag.toInt(), pullKeyboardVisible)
+        }
+        return handled
+      }
+
+      MotionEvent.ACTION_CANCEL -> pullTracking = false
+    }
+    return super.dispatchTouchEvent(ev)
+  }
+
+  /**
+   * Clears stale `nestedScrollingChildRef` from BottomSheetBehavior.
+   *
+   * The cached `nestedScrollingChildRef` can become stale when a child sheet
+   * with a ScrollView is dismissed and its ScrollView returns to this hierarchy.
+   */
+  private fun clearStaleNestedScrollingChildRef() {
+    val sheet = delegate?.findSheetView() ?: return
+    val behavior = sheet.behavior ?: return
+    try {
+      val field = behavior.javaClass.superclass.getDeclaredField("nestedScrollingChildRef")
+      field.isAccessible = true
+      @Suppress("UNCHECKED_CAST")
+      val ref = field.get(behavior) as? java.lang.ref.WeakReference<android.view.View> ?: return
+      val view = ref.get()
+      if (view == null || !view.isDescendantOf(sheet)) {
+        ref.clear()
+      }
+    } catch (_: Exception) {}
+  }
+
+  override fun requestDisallowInterceptTouchEvent(disallowIntercept: Boolean) {
+    // RN's ReactEditText fires this(true) on ACTION_DOWN, killing sheet drag over an input.
+    // Swallow only that case — nothing between the touched EditText and the sheet scrolls
+    // (an overflowing multiline EditText or an input inside a scrollable that can actually
+    // scroll still scrolls). Other children (maps, sliders, scrollables) keep the standard
+    // disallow contract.
+    if (disallowIntercept && streamDraggableEditText) return
+    super.requestDisallowInterceptTouchEvent(disallowIntercept)
+  }
+
+  /**
+   * Resolves the stream's touch target (respecting zIndex and pointerEvents) and
+   * decides whether the sheet may drag from it — inside the sheet, outside the detected
+   * scrollable, and nothing along the target's chain scrolls vertically.
+   */
+  private fun updateStreamTargetFlags(ev: MotionEvent) {
+    streamSheetDraggable = false
+    streamDraggableEditText = false
+
+    val sheet = delegate?.findSheetView() ?: return
+    val target = TouchTargetHelper.findTargetPathAndCoordinatesForTouch(ev.x, ev.y, this, FloatArray(2))
+      .firstNotNullOfOrNull { it.getView() } ?: return
+    if (target !== sheet && !target.isDescendantOf(sheet)) return
+
+    // A detected scrollable that can scroll (or hosts pull-to-refresh) owns its
+    // touches — nested scrolling drags the sheet. When it can't scroll (e.g.
+    // the sheet is fully expanded and the content fits) it eats the gesture
+    // instead, so fall through and let the sheet drag from it — an EditText
+    // target needs the disallow-intercept swallow or its stream dies.
+    val scrollView = delegate?.findScrollView()
+    if (scrollView != null && (target === scrollView || target.isDescendantOf(scrollView))) {
+      val hasRefreshControl = scrollView.parent is SwipeRefreshLayout
+      if (hasRefreshControl || scrollView.scrollY > 0 || scrollView.canScrollVertically(1)) return
+    }
+
+    var view: View? = target
+    while (view != null && view !== this) {
+      if (view.canScrollVertically(1) || view.canScrollVertically(-1)) return
+      view = view.parent as? View
+    }
+
+    streamSheetDraggable = true
+    streamDraggableEditText = target is EditText
+  }
+
+  private fun isTouchInside(view: View, ev: MotionEvent): Boolean {
+    val loc = IntArray(2)
+    view.getLocationOnScreen(loc)
+    val x = ev.rawX.toInt()
+    val y = ev.rawY.toInt()
+    return x >= loc[0] && x <= loc[0] + view.width && y >= loc[1] && y <= loc[1] + view.height
+  }
+
+  private fun findDescendantViewAt(view: View, rawX: Int, rawY: Int, predicate: (View) -> Boolean): View? {
+    val loc = IntArray(2)
+    view.getLocationOnScreen(loc)
+    if (rawX < loc[0] || rawX > loc[0] + view.width || rawY < loc[1] || rawY > loc[1] + view.height) return null
+    if (predicate(view)) return view
+    if (view is ViewGroup) {
+      for (i in 0 until view.childCount) {
+        findDescendantViewAt(view.getChildAt(i), rawX, rawY, predicate)?.let { return it }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Called by descendant RootView implementations (controller, footer) when a child
+   * starts a native gesture — e.g. an RNGH handler activated or a scrollable began
+   * scrolling. Yields sheet interception for the rest of the touch stream.
+   */
+  fun childDidClaimNativeGesture() {
+    streamGestureClaimed = true
+  }
+
+  /**
+   * Intercepts touch events for ScrollViews that can't scroll (content < viewport),
+   * allowing the sheet to be dragged in these cases.
+   *
+   * TODO: Remove this workaround once NestedScrollView is merged into react-native core.
+   * See: https://github.com/facebook/react-native/pull/44099
+   */
+  override fun onInterceptTouchEvent(ev: MotionEvent): Boolean {
+    val action = ev.actionMasked
+
+    if (action == MotionEvent.ACTION_DOWN) {
+      clearStaleNestedScrollingChildRef()
+
+      streamInitialX = ev.rawX
+      streamInitialY = ev.rawY
+      streamHorizontalLocked = false
+      streamDirectionDecided = false
+      streamGestureClaimed = false
+      streamHasGestureRoot = findDescendantViewAt(this, ev.rawX.toInt(), ev.rawY.toInt()) {
+        it.javaClass.name == GESTURE_HANDLER_ROOT_VIEW_CLASS
+      } != null
+      updateStreamTargetFlags(ev)
+    }
+
+    // Decide gesture direction on first significant movement of the stream.
+    // If horizontal wins, lock out BottomSheetBehavior for the rest of the stream
+    // so child handlers (carousels, swipe buttons, etc.) can claim the touch.
+    if (!streamDirectionDecided && action == MotionEvent.ACTION_MOVE) {
+      val dx = kotlin.math.abs(ev.rawX - streamInitialX)
+      val dy = kotlin.math.abs(ev.rawY - streamInitialY)
+      if (dx > touchSlop || dy > touchSlop) {
+        streamDirectionDecided = true
+        streamHorizontalLocked = dx > dy
+      }
+    }
+
+    if (streamHorizontalLocked) {
+      if (action == MotionEvent.ACTION_UP || action == MotionEvent.ACTION_CANCEL) {
+        streamHorizontalLocked = false
+        streamDirectionDecided = false
+      }
+      return false
+    }
+
+    if (streamGestureClaimed) {
+      if (action == MotionEvent.ACTION_UP || action == MotionEvent.ACTION_CANCEL) {
+        streamGestureClaimed = false
+      }
+      return false
+    }
+
+    // Hold off BottomSheetBehavior within the grace distance so a gesture handler
+    // under the touch can activate and claim the stream first.
+    if (streamHasGestureRoot &&
+      action == MotionEvent.ACTION_MOVE &&
+      kotlin.math.abs(ev.rawY - streamInitialY) < touchSlop * GESTURE_CLAIM_SLOP_FACTOR
+    ) {
+      return false
+    }
+
+    val scrollView = delegate?.findScrollView()
+    val hasRefreshControl = scrollView?.parent is SwipeRefreshLayout
+    val cannotScroll = scrollView != null &&
+      !hasRefreshControl &&
+      scrollView.scrollY == 0 &&
+      !scrollView.canScrollVertically(1)
+
+    if (cannotScroll || streamSheetDraggable) {
+      when (ev.action and MotionEvent.ACTION_MASK) {
+        MotionEvent.ACTION_DOWN -> {
+          dragging = false
+          initialY = ev.y
+          activePointerId = ev.getPointerId(0)
+        }
+
+        MotionEvent.ACTION_MOVE -> {
+          val pointerIndex = ev.findPointerIndex(activePointerId)
+          if (pointerIndex != -1) {
+            val y = ev.getY(pointerIndex)
+            val deltaY = initialY - y
+            if (kotlin.math.abs(deltaY) > touchSlop) {
+              dragging = true
+              parent?.requestDisallowInterceptTouchEvent(true)
+            }
+          }
+        }
+
+        MotionEvent.ACTION_UP,
+        MotionEvent.ACTION_CANCEL -> {
+          dragging = false
+        }
+      }
+    } else {
+      dragging = false
+    }
+
+    return dragging || super.onInterceptTouchEvent(ev)
+  }
+
+  @SuppressLint("ClickableViewAccessibility")
+  override fun onTouchEvent(ev: MotionEvent): Boolean {
+    if (dragging) {
+      when (ev.action and MotionEvent.ACTION_MASK) {
+        MotionEvent.ACTION_UP,
+        MotionEvent.ACTION_CANCEL -> {
+          dragging = false
+        }
+      }
+      // Let parent CoordinatorLayout handle the touch for BottomSheetBehavior
+      return super.onTouchEvent(ev)
+    }
+    return super.onTouchEvent(ev)
+  }
+
+  companion object {
+    private const val GESTURE_HANDLER_ROOT_VIEW_CLASS = "com.swmansion.gesturehandler.react.RNGestureHandlerRootView"
+    private const val GESTURE_CLAIM_SLOP_FACTOR = 3
+    private const val PULL_DOWN_THRESHOLD_DP = 24f
+  }
+}

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

@@ -0,0 +1,299 @@
+package com.lodev09.truesheet.core
+
+import com.facebook.react.uimanager.PixelUtil.dpToPx
+import com.facebook.react.uimanager.PixelUtil.pxToDp
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.util.RNLog
+import com.google.android.material.bottomsheet.BottomSheetBehavior
+
+/**
+ * Provides screen dimensions and content measurements for detent calculations.
+ */
+interface TrueSheetDetentCalculatorDelegate {
+  val screenHeight: Int
+  val realScreenHeight: Int
+  val detents: MutableList<Double>
+  val contentHeight: Int
+  val headerHeight: Int
+  val absoluteHeader: Boolean
+  val footerHeight: Int
+  val absoluteFooter: Boolean
+  val peekContentHeight: Int
+  val contentBottomInset: Int
+  val maxContentHeight: Int?
+  val keyboardInset: Int
+  val topInset: Int
+
+  /**
+   * True while the keyboard holds the sheet up: the collapsed stop then sits at
+   * the keyboard-free first detent (the "floor") so a drag-down dismisses the
+   * keyboard before it can dismiss the sheet.
+   */
+  val hasKeyboardFloor: Boolean
+}
+
+/**
+ * Handles all detent-related calculations for the bottom sheet.
+ */
+class TrueSheetDetentCalculator(private val reactContext: ThemedReactContext) {
+
+  var delegate: TrueSheetDetentCalculatorDelegate? = null
+
+  private val screenHeight: Int get() = delegate?.screenHeight ?: 0
+  private val realScreenHeight: Int get() = delegate?.realScreenHeight ?: 0
+  private val detents: List<Double> get() = delegate?.detents ?: emptyList()
+  private val contentHeight: Int get() = delegate?.contentHeight ?: 0
+
+  private val headerHeight: Int get() = delegate?.headerHeight ?: 0
+  private val footerHeight: Int get() = delegate?.footerHeight ?: 0
+  private val peekContentHeight: Int get() = delegate?.peekContentHeight ?: 0
+  private val contentBottomInset: Int get() = delegate?.contentBottomInset ?: 0
+  private val maxContentHeight: Int? get() = delegate?.maxContentHeight
+  private val keyboardInset: Int get() = delegate?.keyboardInset ?: 0
+  private val topInset: Int get() = delegate?.topInset ?: 0
+  private val hasKeyboardFloor: Boolean get() = delegate?.hasKeyboardFloor == true
+
+  /**
+   * Height for auto (-1.0) detents: content + header + footer height.
+   * An absolute (floating) header or footer overlaps the content, so it contributes no height.
+   */
+  private val autoDetentHeight: Int
+    get() = contentHeight +
+      (if (delegate?.absoluteHeader == true) 0 else headerHeight) +
+      (if (delegate?.absoluteFooter == true) 0 else footerHeight)
+
+  /**
+   * Bottom inset for auto detents. A relative footer owns the sheet's bottom
+   * edge, so it absorbs the inset instead of adding it to the auto height.
+   */
+  private val autoDetentBottomInset: Int
+    get() = if (footerHeight > 0 && delegate?.absoluteFooter == false) 0 else contentBottomInset
+
+  /**
+   * Bottom inset for peek detents. An absolute footer counts toward the peek
+   * height and absorbs the inset, so it isn't added again.
+   */
+  private val peekDetentBottomInset: Int
+    get() = if (footerHeight > 0 && delegate?.absoluteFooter == true) 0 else contentBottomInset
+
+  /**
+   * Height for peek (-2.0) detents: header + footer + peek content height.
+   * A relative footer is pushed off-screen at peek, so it contributes no height.
+   * Falls back to 150dp when none is present.
+   */
+  private val peekDetentHeight: Int
+    get() {
+      val height = headerHeight +
+        (if (delegate?.absoluteFooter == true) footerHeight else 0) +
+        peekContentHeight
+      return if (height > 0) height else DEFAULT_PEEK_HEIGHT.dpToPx().toInt()
+    }
+
+  /**
+   * Calculate the height in pixels for a given detent value.
+   * @param detent The detent value: -1.0 for content-fit, -2.0 for peek, or 0.0-1.0 for screen fraction
+   */
+  fun getDetentHeight(detent: Double, includeKeyboard: Boolean = true): Int {
+    val baseHeight = if (detent == -1.0) {
+      autoDetentHeight + autoDetentBottomInset
+    } else if (detent == -2.0) {
+      peekDetentHeight + peekDetentBottomInset
+    } else {
+      if (detent <= 0.0 || detent > 1.0) {
+        throw IllegalArgumentException("TrueSheet: detent fraction ($detent) must be between 0 and 1")
+      }
+      (detent * screenHeight).toInt() + contentBottomInset
+    }
+
+    val height = if (includeKeyboard) baseHeight + keyboardInset else baseHeight
+    val maxAllowedHeight = screenHeight + contentBottomInset
+    return maxContentHeight?.let { minOf(height, it, maxAllowedHeight) } ?: minOf(height, maxAllowedHeight)
+  }
+
+  /**
+   * Get the expected sheet top position for a detent index.
+   */
+  fun getSheetTopForDetentIndex(index: Int): Int {
+    if (index < 0 || index >= detents.size) {
+      RNLog.w(reactContext, "TrueSheet: Detent index ($index) is out of bounds (0..${detents.size - 1})")
+      return realScreenHeight
+    }
+    // With a keyboard floor only the last detent stays keyboard-shifted — it's
+    // the keyboard-expanded resting position; the stops below it are keyboard-free
+    val isKeyboardFreeStop = hasKeyboardFloor && index != detents.size - 1
+    return getSheetTop(detents[index], includeKeyboard = !isKeyboardFreeStop)
+  }
+
+  /**
+   * Top of the lowest stop the sheet can rest at: the keyboard floor while it's
+   * active, else the first detent.
+   */
+  fun getLowestSheetTop(): Int = if (hasKeyboardFloor) getSheetTop(detents[0], includeKeyboard = false) else getSheetTopForDetentIndex(0)
+
+  /**
+   * Top of the half stop while the keyboard floor is active: the keyboard-free
+   * second detent, or the floor itself for a single detent.
+   */
+  fun getKeyboardHalfStopTop(): Int = getSheetTop(detents[minOf(1, detents.size - 1)], includeKeyboard = false)
+
+  // Clamp to the space the sheet can actually occupy — matching
+  // setupSheetDetents. A keyboard-inflated detent height can exceed it,
+  // placing the expected top above the screen while the real sheet stops
+  // at the top inset.
+  private fun getSheetTop(detent: Double, includeKeyboard: Boolean = true): Int {
+    val maxAvailableHeight = realScreenHeight - topInset
+    return realScreenHeight - minOf(getDetentHeight(detent, includeKeyboard), maxAvailableHeight)
+  }
+
+  /**
+   * Calculate visible sheet height from sheet top position.
+   */
+  fun getVisibleSheetHeight(sheetTop: Int): Int = realScreenHeight - sheetTop
+
+  /**
+   * Convert visible sheet height to position in dp.
+   */
+  fun getPositionDp(visibleSheetHeight: Int): Float = (screenHeight - visibleSheetHeight).pxToDp()
+
+  /**
+   * Returns the raw screen fraction for a detent index (without bottomInset).
+   */
+  fun getDetentValueForIndex(index: Int): Float {
+    if (index < 0 || index >= detents.size) return 0f
+    val value = detents[index]
+    return if (value == -1.0) {
+      autoDetentHeight.toFloat() / screenHeight.toFloat()
+    } else if (value == -2.0) {
+      peekDetentHeight.toFloat() / screenHeight.toFloat()
+    } else {
+      value.toFloat()
+    }
+  }
+
+  // ====================================================================
+  // MARK: - State Mapping
+  // ====================================================================
+
+  /**
+   * Maps detent index to BottomSheetBehavior state based on detent count.
+   */
+  fun getStateForDetentIndex(index: Int): Int {
+    val stateMap = getDetentStateMap() ?: return BottomSheetBehavior.STATE_HIDDEN
+    // With a keyboard floor the keyboard-expanded last detent lives at the
+    // expanded stop — the half stop (which may share its index) is keyboard-free
+    if (hasKeyboardFloor && index == detents.size - 1) return BottomSheetBehavior.STATE_EXPANDED
+    return stateMap.entries.find { it.value == index }?.key ?: BottomSheetBehavior.STATE_HIDDEN
+  }
+
+  /**
+   * Maps BottomSheetBehavior state to detent index.
+   * @return The detent index, or null if state is not mapped
+   */
+  fun getDetentIndexForState(state: Int): Int? {
+    val stateMap = getDetentStateMap() ?: return null
+    return stateMap[state]
+  }
+
+  /**
+   * Returns state-to-index mapping based on detent count.
+   */
+  private fun getDetentStateMap(): Map<Int, Int>? =
+    when (detents.size) {
+      // With one detent halfExpandedRatio matches the peek height, so the
+      // behavior can settle HALF_EXPANDED at the same position (e.g. an upward
+      // drag release) — map it too, or the settle is unmappable
+      1 -> mapOf(
+        BottomSheetBehavior.STATE_COLLAPSED to 0,
+        BottomSheetBehavior.STATE_HALF_EXPANDED to 0,
+        BottomSheetBehavior.STATE_EXPANDED to 0
+      )
+
+      2 -> mapOf(
+        BottomSheetBehavior.STATE_COLLAPSED to 0,
+        BottomSheetBehavior.STATE_HALF_EXPANDED to 1,
+        BottomSheetBehavior.STATE_EXPANDED to 1
+      )
+
+      3 -> mapOf(
+        BottomSheetBehavior.STATE_COLLAPSED to 0,
+        BottomSheetBehavior.STATE_HALF_EXPANDED to 1,
+        BottomSheetBehavior.STATE_EXPANDED to 2
+      )
+
+      else -> null
+    }
+
+  // ====================================================================
+  // MARK: - Interpolation
+  // ====================================================================
+
+  /**
+   * Find which segment the position falls into for interpolation.
+   * @return Triple(fromIndex, toIndex, progress) where progress is 0-1, or null if no detents
+   */
+  private fun findSegmentForPosition(positionPx: Int): Triple<Int, Int, Float>? {
+    val count = detents.size
+    if (count == 0) return null
+
+    // A single keyboard-shifted detent can rest down at its keyboard floor —
+    // that range is still index 0, not a dismissal
+    val floorPos = getLowestSheetTop()
+
+    // Position is below the lowest stop (sheet is being dragged down to dismiss)
+    if (positionPx > floorPos) {
+      val range = realScreenHeight - floorPos
+      val progress = if (range > 0) (positionPx - floorPos).toFloat() / range else 0f
+      return Triple(-1, 0, progress)
+    }
+
+    if (count == 1) return Triple(0, 0, 0f)
+
+    val lastPos = getSheetTopForDetentIndex(count - 1)
+    // Position is above last detent
+    if (positionPx < lastPos) {
+      return Triple(count - 1, count - 1, 0f)
+    }
+
+    // Find the segment containing this position
+    for (i in 0 until count - 1) {
+      val pos = getSheetTopForDetentIndex(i)
+      val nextPos = getSheetTopForDetentIndex(i + 1)
+
+      // Skip degenerate segments — keyboard growth can clamp adjacent detents
+      // to the same top; falling through reports the topmost detent
+      if (pos == nextPos) continue
+
+      if (positionPx in nextPos..pos) {
+        val range = pos - nextPos
+        val progress = if (range > 0) (pos - positionPx).toFloat() / range else 0f
+        return Triple(i, i + 1, maxOf(0f, minOf(1f, progress)))
+      }
+    }
+
+    return Triple(count - 1, count - 1, 0f)
+  }
+
+  /**
+   * Returns interpolated continuous index (e.g., 0.5 = halfway between detent
+   * 0 and 1) and screen fraction for a position, sharing a single segment
+   * lookup — this runs on every position frame.
+   */
+  fun getInterpolatedPositionInfo(positionPx: Int): Pair<Float, Float> {
+    if (detents.isEmpty()) return Pair(-1f, 0f)
+
+    val (fromIndex, toIndex, progress) = findSegmentForPosition(positionPx)
+      ?: return Pair(0f, getDetentValueForIndex(0))
+
+    if (fromIndex == -1) {
+      return Pair(-progress, maxOf(0f, getDetentValueForIndex(0) * (1 - progress)))
+    }
+
+    val fromDetent = getDetentValueForIndex(fromIndex)
+    val toDetent = getDetentValueForIndex(toIndex)
+    return Pair(fromIndex + progress, fromDetent + progress * (toDetent - fromDetent))
+  }
+
+  companion object {
+    private const val DEFAULT_PEEK_HEIGHT = 150f
+  }
+}