library: feat: Add ScrollEndHaptic modifier

YuKongA · YuKongA · commit 1c6b0d565013 · 2025-05-18T00:50:18.000+08:00
* Provides haptic feedback when a scrollable container
is flung to its start or end boundaries.
* Just like xiaomi official?
diff --git a/docs/guide/utils.md b/docs/guide/utils.md
@@ -50,7 +50,7 @@ Normally, you don't need to use it actively. See the [ListPopup](../components/l
 
 ## Overscroll Effects
 
-Miuix provides easy-to-use overscroll effects for smoother and more natural scrolling experiences.
+Miuix provides easy-to-use overscroll effects modifier for smoother and more natural scrolling experiences.
 
 ### Vertical Overscroll
 
@@ -105,6 +105,28 @@ LazyColumn(
 *   `springDamp`: Float, defines the spring damping for the rebound animation. Higher values result in less oscillation. Defaults to `1f`.
 *   `isEnabled`: A lambda expression returning a Boolean, used to dynamically control whether the overscroll effect is enabled. By default, it is enabled only on Android and iOS platforms.
 
+
+## Scroll End Haptic Feedback
+
+Miuix provides a `scrollEndHaptic` modifier to trigger haptic feedback when a scrollable container is flung to its start or end boundaries. This enhances the user experience by providing a tactile confirmation that the end of the list has been reached.
+
+```kotlin
+LazyColumn(
+    modifier = Modifier
+        .fillMaxSize()
+        // Add scroll end haptic feedback
+        .scrollEndHaptic(
+            hapticFeedbackType = HapticFeedbackType.LongPress // Default value
+        )
+) {
+    // List content
+}
+```
+
+**Parameter Explanation:**
+
+*   `hapticFeedbackType`: Specifies the type of haptic feedback to be performed when the scroll reaches its end. Defaults to `HapticFeedbackType.TextHandleMove`. You can use other types available in `androidx.compose.ui.hapticfeedback.HapticFeedbackType`.
+
 ## Press Feedback Effects
 
 Miuix provides visual feedback effects to enhance user interaction experience, improving operability through tactile-like responses.
@@ -175,10 +197,10 @@ Box(
 
 The `PressFeedbackType` enum defines different types of visual feedback that can be applied when the component is pressed.
 
-| Type | Description |
-|------|-------------|
-| None | No visual feedback |
-| Sink | Applies a sink effect, where the component scales down slightly when pressed |
+| Type | Description                                                                           |
+| ---- | ------------------------------------------------------------------------------------- |
+| None | No visual feedback                                                                    |
+| Sink | Applies a sink effect, where the component scales down slightly when pressed          |
 | Tilt | Applies a tilt effect, where the component tilts slightly based on the touch position |
 
 ## Smooth Rounded Corners (SmoothRoundedCornerShape)
diff --git a/docs/zh_CN/guide/utils.md b/docs/zh_CN/guide/utils.md
@@ -51,7 +51,7 @@ PopupLayout(
 
 ## 越界回弹效果 (Overscroll)
 
-Miuix 提供了易于使用的越界回弹效果，让滚动体验更加流畅自然。
+Miuix 提供了易于使用的越界回弹效果修饰符，让滚动体验更加流畅自然。
 
 ### 垂直越界回弹
 
@@ -106,6 +106,27 @@ LazyColumn(
 *   `springDamp`: 浮点数，定义回弹动画的弹簧阻尼。值越高，振荡越小。默认为 `1f`。
 *   `isEnabled`: 一个返回布尔值的 Lambda 表达式，用于动态控制是否启用越界回弹效果。默认情况下，仅在 Android 和 iOS 平台上启用。
 
+## 滚动到边界触觉反馈
+
+Miuix 提供了用于在可滚动容器快速滑动到其开始或结束边界时触发触觉反馈的修饰符，通过触觉反馈确认已到达边界增强用户的交互体验。
+
+```kotlin
+LazyColumn(
+    modifier = Modifier
+        .fillMaxSize()
+        // 添加滚动到边界触觉反馈
+        .scrollEndHaptic(
+            hapticFeedbackType = HapticFeedbackType.TextHandleMove // 默认值
+        )
+) {
+    // 列表内容
+}
+```
+
+**参数说明:**
+
+*   `hapticFeedbackType`: 指定滚动到达末端时要执行的触觉反馈类型。默认为 `HapticFeedbackType.TextHandleMove`。您可以使用 `androidx.compose.ui.hapticfeedback.HapticFeedbackType` 中可用的其他类型。
+
 ## 按压反馈效果 (PressFeedback)
 
 Miuix 提供了视觉反馈效果来增强用户交互体验，通过类似触觉的响应提升操作感。
@@ -176,10 +197,10 @@ Box(
 
 `PressFeedbackType` 枚举定义了组件被按下时可以应用的不同类型的视觉反馈。
 
-| 类型 | 说明 |
-|------|-------------|
-| None | 无视觉反馈 |
-| Sink | 应用下沉效果，组件在按下时轻微缩小 |
+| 类型 | 说明                                   |
+| ---- | -------------------------------------- |
+| None | 无视觉反馈                             |
+| Sink | 应用下沉效果，组件在按下时轻微缩小     |
 | Tilt | 应用倾斜效果，组件根据触摸位置轻微倾斜 |
 
 ## 平滑圆角 (SmoothRoundedCornerShape)
diff --git a/example/src/commonMain/kotlin/MainPage.kt b/example/src/commonMain/kotlin/MainPage.kt
@@ -36,6 +36,7 @@ import top.yukonga.miuix.kmp.basic.SmallTitle
 import top.yukonga.miuix.kmp.basic.Text
 import top.yukonga.miuix.kmp.theme.MiuixTheme
 import top.yukonga.miuix.kmp.utils.overScrollVertical
+import top.yukonga.miuix.kmp.utils.scrollEndHaptic
 
 @Composable
 fun MainPage(
@@ -83,6 +84,7 @@ fun MainPage(
         if (maxWidth < 840.dp) {
             LazyColumn(
                 modifier = Modifier
+                    .scrollEndHaptic()
                     .overScrollVertical()
                     .nestedScroll(topAppBarScrollBehavior.nestedScrollConnection),
                 contentPadding = PaddingValues(top = padding.calculateTopPadding()),
@@ -160,6 +162,7 @@ fun MainPage(
                 LazyColumn(
                     modifier = Modifier
                         .nestedScroll(topAppBarScrollBehavior.nestedScrollConnection)
+                        .scrollEndHaptic()
                         .weight(1f),
                     contentPadding = PaddingValues(top = padding.calculateTopPadding())
                 ) {
@@ -223,6 +226,7 @@ fun MainPage(
                 LazyColumn(
                     modifier = Modifier
                         .nestedScroll(topAppBarScrollBehavior.nestedScrollConnection)
+                        .scrollEndHaptic()
                         .padding(end = 12.dp, bottom = 12.dp)
                         .weight(1f),
                     contentPadding = PaddingValues(top = padding.calculateTopPadding())
diff --git a/example/src/commonMain/kotlin/SecondPage.kt b/example/src/commonMain/kotlin/SecondPage.kt
@@ -20,6 +20,7 @@ import top.yukonga.miuix.kmp.basic.rememberPullToRefreshState
 import top.yukonga.miuix.kmp.extra.SuperDropdown
 import top.yukonga.miuix.kmp.utils.getWindowSize
 import top.yukonga.miuix.kmp.utils.overScrollVertical
+import top.yukonga.miuix.kmp.utils.scrollEndHaptic
 
 @Composable
 fun SecondPage(
@@ -50,6 +51,7 @@ fun SecondPage(
     ) {
         LazyColumn(
             modifier = Modifier
+                .scrollEndHaptic()
                 .overScrollVertical()
                 .nestedScroll(topAppBarScrollBehavior.nestedScrollConnection)
                 .height(getWindowSize().height.dp),
diff --git a/example/src/commonMain/kotlin/ThirdPage.kt b/example/src/commonMain/kotlin/ThirdPage.kt
@@ -24,6 +24,7 @@ import top.yukonga.miuix.kmp.extra.SuperSwitch
 import top.yukonga.miuix.kmp.theme.MiuixTheme
 import top.yukonga.miuix.kmp.utils.getWindowSize
 import top.yukonga.miuix.kmp.utils.overScrollVertical
+import top.yukonga.miuix.kmp.utils.scrollEndHaptic
 
 @Composable
 fun ThirdPage(
@@ -58,6 +59,7 @@ fun ThirdPage(
     val showDialog = remember { mutableStateOf(false) }
     LazyColumn(
         modifier = Modifier
+            .scrollEndHaptic()
             .overScrollVertical()
             .nestedScroll(topAppBarScrollBehavior.nestedScrollConnection)
             .height(getWindowSize().height.dp),
diff --git a/miuix/src/commonMain/kotlin/top/yukonga/miuix/kmp/basic/Slider.kt b/miuix/src/commonMain/kotlin/top/yukonga/miuix/kmp/basic/Slider.kt
@@ -207,14 +207,17 @@ internal class SliderHapticState {
 object SliderDefaults {
     val MinHeight = 30.dp
 
+    /**
+     * The type of haptic feedback to be used for the slider.
+     */
     enum class SliderHapticEffect {
-        /** No haptic feedback */
+        /** No haptic feedback. */
         None,
 
-        /** Haptic feedback at 0% and 100% */
+        /** Haptic feedback at 0% and 100%. */
         Edge,
 
-        /** Haptic feedback at steps */
+        /** Haptic feedback at steps. */
         Step
     }
 
diff --git a/miuix/src/commonMain/kotlin/top/yukonga/miuix/kmp/utils/PressFeedback.kt b/miuix/src/commonMain/kotlin/top/yukonga/miuix/kmp/utils/PressFeedback.kt
@@ -16,28 +16,17 @@ import androidx.compose.ui.draw.scale
 import androidx.compose.ui.graphics.TransformOrigin
 import androidx.compose.ui.graphics.graphicsLayer
 import androidx.compose.ui.input.pointer.pointerInput
-import top.yukonga.miuix.kmp.utils.PressFeedbackType.None
-import top.yukonga.miuix.kmp.utils.PressFeedbackType.Sink
-import top.yukonga.miuix.kmp.utils.PressFeedbackType.Tilt
 
-/**
- * Default sink amount for the press sink effect.
- */
+/** Default sink amount for the press sink effect. */
 internal const val SinkAmount: Float = 0.94f
 
-/**
- * Default tilt amount for the press tilt effect.
- */
+/** Default tilt amount for the press tilt effect. */
 internal const val TiltAmount: Float = 8f
 
-/**
- * Default damping ratio for the press feedback spring animations.
- */
+/** Default damping ratio for the press feedback spring animations. */
 internal const val DampingRatio: Float = 0.6f
 
-/**
- * Default stiffness for the press feedback spring animations.
- */
+/** Default stiffness for the press feedback spring animations. */
 internal const val Stiffness: Float = 400f
 
 /**
@@ -130,13 +119,14 @@ fun Modifier.pressTilt(
 
 /**
  * The type of visual feedback to apply when the component is pressed.
- *
- * @property None No visual feedback.
- * @property Sink Sink effect, where the component scales down slightly when pressed.
- * @property Tilt Tilt effect, where the component tilts slightly based on the touch position.
  */
 enum class PressFeedbackType {
+    /** No feedback effect. */
     None,
+
+    /** Sinks slightly when pressed. */
     Sink,
+
+    /** Tilts based on touch position when pressed. */
     Tilt
 }
diff --git a/miuix/src/commonMain/kotlin/top/yukonga/miuix/kmp/utils/ScrollEndHaptic.kt b/miuix/src/commonMain/kotlin/top/yukonga/miuix/kmp/utils/ScrollEndHaptic.kt
@@ -0,0 +1,137 @@
+package top.yukonga.miuix.kmp.utils
+
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.composed
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.hapticfeedback.HapticFeedback
+import androidx.compose.ui.hapticfeedback.HapticFeedbackType
+import androidx.compose.ui.input.nestedscroll.NestedScrollConnection
+import androidx.compose.ui.input.nestedscroll.NestedScrollSource
+import androidx.compose.ui.input.nestedscroll.nestedScroll
+import androidx.compose.ui.platform.LocalHapticFeedback
+import androidx.compose.ui.unit.Velocity
+import kotlin.math.abs
+
+/**
+ * A [NestedScrollConnection] that provides haptic feedback when a scrollable container
+ * is flung to its start or end boundaries.
+ *
+ * @param hapticFeedback The [HapticFeedback] instance to perform feedback.
+ * @param hapticFeedbackType The type of haptic feedback to perform.
+ */
+private class ScrollEndHapticConnection(
+    private val hapticFeedback: HapticFeedback,
+    private val hapticFeedbackType: HapticFeedbackType
+) : NestedScrollConnection {
+
+    private enum class OverscrollState {
+        /** No overscroll detected. */
+        Idle,
+
+        /** Overscroll detected at the top boundary. */
+        TopBoundaryHit,
+
+        /** Overscroll detected at the bottom boundary. */
+        BottomBoundaryHit
+    }
+
+    private var overscrollState: OverscrollState = OverscrollState.Idle
+
+    private fun Float.isAlmostZero(tolerance: Float = 0.01f): Boolean = abs(this) < tolerance
+
+    override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
+        // Reset state when scrolling away from a boundary into content.
+        if (overscrollState == OverscrollState.TopBoundaryHit && available.y > 0.1f) {
+            overscrollState = OverscrollState.Idle
+        } else if (overscrollState == OverscrollState.BottomBoundaryHit && available.y < -0.1f) {
+            overscrollState = OverscrollState.Idle
+        }
+        return Offset.Zero
+    }
+
+    override fun onPostScroll(
+        consumed: Offset,
+        available: Offset,
+        source: NestedScrollSource
+    ): Offset {
+        val isSideEffect = source == NestedScrollSource.SideEffect
+
+        if (isSideEffect) {
+            // Attempting to scroll beyond the bottom boundary.
+            if (available.y > 0.1f && consumed.y.isAlmostZero()) {
+                if (overscrollState != OverscrollState.BottomBoundaryHit) {
+                    // Update state; haptic feedback is primarily handled in onPostFling for fling-to-end.
+                    overscrollState = OverscrollState.BottomBoundaryHit
+                }
+            }
+            // Attempting to scroll beyond the top boundary.
+            else if (available.y < -0.1f && consumed.y.isAlmostZero()) {
+                if (overscrollState != OverscrollState.TopBoundaryHit) {
+                    // Update state; haptic feedback is primarily handled in onPostFling for fling-to-end.
+                    overscrollState = OverscrollState.TopBoundaryHit
+                }
+            }
+            // Content is still scrolling.
+            else if (!consumed.y.isAlmostZero()) {
+                if (overscrollState != OverscrollState.Idle) {
+                    overscrollState = OverscrollState.Idle
+                }
+            }
+        }
+        return Offset.Zero
+    }
+
+    override suspend fun onPreFling(available: Velocity): Velocity {
+        // Reset state when flinging away from a boundary into content.
+        if (overscrollState == OverscrollState.TopBoundaryHit && available.y > 1f) {
+            overscrollState = OverscrollState.Idle
+        } else if (overscrollState == OverscrollState.BottomBoundaryHit && available.y < -1f) {
+            overscrollState = OverscrollState.Idle
+        }
+        return Velocity.Zero
+    }
+
+    override suspend fun onPostFling(consumed: Velocity, available: Velocity): Velocity {
+        // Flinging beyond the bottom boundary.
+        if (available.y > 1f) {
+            if (overscrollState != OverscrollState.BottomBoundaryHit) {
+                hapticFeedback.performHapticFeedback(hapticFeedbackType)
+                overscrollState = OverscrollState.BottomBoundaryHit
+            }
+        }
+        // Flinging beyond the top boundary.
+        else if (available.y < -1f) {
+            if (overscrollState != OverscrollState.TopBoundaryHit) {
+                hapticFeedback.performHapticFeedback(hapticFeedbackType)
+                overscrollState = OverscrollState.TopBoundaryHit
+            }
+        }
+        // Fling is consumed by content or stops at boundary without significant overshoot.
+        else if (!consumed.y.isAlmostZero(1f)) {
+            if (overscrollState != OverscrollState.Idle) {
+                overscrollState = OverscrollState.Idle
+            }
+        }
+        return Velocity.Zero
+    }
+}
+
+/**
+ * Applies a haptic feedback effect when a scrollable container is flung to its boundaries.
+ *
+ * @param hapticFeedbackType The type of haptic feedback to perform.
+ */
+fun Modifier.scrollEndHaptic(
+    hapticFeedbackType: HapticFeedbackType = HapticFeedbackType.TextHandleMove
+): Modifier = composed {
+    val haptic = LocalHapticFeedback.current
+
+    val connection = remember(haptic, hapticFeedbackType) {
+        ScrollEndHapticConnection(
+            hapticFeedback = haptic,
+            hapticFeedbackType = hapticFeedbackType
+        )
+    }
+    Modifier.nestedScroll(connection)
+}
diff --git a/miuix/src/commonMain/kotlin/top/yukonga/miuix/kmp/utils/SmoothRoundedCornerShape.kt b/miuix/src/commonMain/kotlin/top/yukonga/miuix/kmp/utils/SmoothRoundedCornerShape.kt
