feat(FloatingPanel): support inertia factor

Author: Passing-of-A-Dream

src/components/floating-panel/floating-panel.tsx

@@ -27,16 +27,18 @@ export type FloatingPanelProps = {
   onHeightChange?: (height: number, animating: boolean) => void
   handleDraggingOfContent?: boolean
   placement?: 'bottom' | 'top'
+  inertiaFactor?: number
 } & NativeProps<'--border-radius' | '--z-index' | '--header-height'>
 
 const defaultProps = {
   handleDraggingOfContent: true,
+  inertiaFactor: 50,
 }
 
 export const FloatingPanel = forwardRef<FloatingPanelRef, FloatingPanelProps>(
   (p, ref) => {
     const props = mergeProps(defaultProps, p)
-    const { anchors, placement = 'bottom' } = props
+    const { anchors, placement = 'bottom', inertiaFactor } = props
     const maxHeight = anchors[anchors.length - 1] ?? window.innerHeight
 
     const isBottomPlacement = placement !== 'top'
@@ -96,7 +98,9 @@ export const FloatingPanel = forwardRef<FloatingPanelRef, FloatingPanelProps>(
         if (state.last) {
           pullingRef.current = false
           setPulling(false)
-          nextY = nearest(possibles, offsetY)
+          const [, vy] = state.velocity
+          const [, dy] = state.direction
+          nextY = nearest(possibles, offsetY + dy * vy * (inertiaFactor ?? 0))
         }
         api.start({
           y: nextY,

src/components/floating-panel/index.en.md

@@ -20,12 +20,13 @@ Users can freely and flexibly slide up and down to browse the content, which is
 
 ### Props
 
-| Name | Description | Type | Description | Version |
+| Name | Description | Type | Default | Version |
 | --- | --- | --- | --- | --- |
 | anchors | What height can be dragged to, the unit is `px` | `number[]` | - |  |
 | handleDraggingOfContent | Whether to handle the drag event of the panel content area. If disabled, only the head area can be dragged | `boolean` | `true` |  |
 | onHeightChange | Triggered when the height changes, the `animating` parameter indicates whether it is in the process of animation | `(height: number, animating: boolean) => void` |  |  |
 | placement | Specify the direction in which the panel appears. | `'bottom' \| 'top'` | `'bottom'` | 5.39.0 |
+| inertiaFactor | Inertia factor for snap behavior. When the user flicks fast, velocity adds extra displacement to the snap target, making it easier to reach distant anchors. Set to 0 to disable. Recommended value: 50~100 | `number` | `50` | 5.42.3 |
 
 ### Ref
 

src/components/floating-panel/index.zh.md

@@ -26,6 +26,7 @@
 | handleDraggingOfContent | 是否会处理面板内容区域的拖拽事件，禁用后则只能拖拽头部区域 | `boolean` | `true` |  |
 | onHeightChange | 当高度变化时触发，`animating` 参数表示是否处于动画过程中 | `(height: number, animating: boolean) => void` |  |  |
 | placement | 指定面板出现的方向 | `'bottom' \| 'top'` | `'bottom'` | 5.39.0 |
+| inertiaFactor | 惯性系数，用于吸附判定。快速滑动时速度会附加额外位移，使面板更容易到达较远的锚点。设为 0 可禁用。推荐值：50~100 | `number` | `50` | 5.42.3 |
 
 ### Ref
 

src/components/floating-panel/tests/floating-panel.test.tsx

@@ -1,7 +1,8 @@
-import React, { useRef, forwardRef } from 'react'
-import { render, testA11y, fireEvent, waitFor } from 'testing'
-import FloatingPanel, { FloatingPanelRef } from '..'
 import { reduceMotion, restoreMotion } from 'antd-mobile'
+import React, { forwardRef, useRef } from 'react'
+import { fireEvent, mockTimedDrag, render, testA11y, waitFor } from 'testing'
+import FloatingPanel, { FloatingPanelRef } from '..'
+import { nearest } from '../../../utils/nearest'
 
 const classPrefix = `adm-floating-panel`
 
@@ -157,3 +158,91 @@ describe('FloatingPanel', () => {
     )
   })
 })
+
+describe('FloatingPanel inertiaFactor logic', () => {
+  const possibles = anchors.map(x => -x) // [-100, -200, -400]
+
+  test('inertiaFactor=0 ignores velocity', () => {
+    expect(nearest(possibles, -120 + -1 * 1.5 * 0)).toBe(-100)
+  })
+
+  test('upward flick pushes snap toward higher anchor', () => {
+    expect(nearest(possibles, -120 + -1 * 1.5 * 50)).toBe(-200)
+  })
+
+  test('downward flick pushes snap toward lower anchor', () => {
+    expect(nearest(possibles, -280 + 1 * 1.5 * 100)).toBe(-100)
+  })
+
+  test('small inertiaFactor has minimal effect', () => {
+    expect(nearest(possibles, -120 + -1 * 1.5 * 5)).toBe(-100)
+  })
+
+  test('large inertiaFactor can skip to farthest anchor', () => {
+    expect(nearest(possibles, -120 + -1 * 1.5 * 200)).toBe(-400)
+  })
+})
+
+describe('FloatingPanel inertiaFactor integration', () => {
+  const App = forwardRef((props: any, ref) => (
+    <FloatingPanel anchors={anchors} data-testid='panel' {...props} ref={ref}>
+      {data.map(item => (
+        <div key={item} style={{ height: 20 }}>
+          {item}
+        </div>
+      ))}
+    </FloatingPanel>
+  ))
+
+  test('without inertiaFactor, fast flick stays at nearest anchor', async () => {
+    const { getByTestId } = render(<App inertiaFactor={0} />)
+    const panelEl = getByTestId('panel')
+
+    mockTimedDrag(panelEl, 200, 170, 16, 3)
+
+    await waitFor(() =>
+      expect(panelEl.style.transform).toBe(
+        `translateY(calc(100% + (-${anchors[0]}px)))`
+      )
+    )
+  })
+
+  test('with inertiaFactor, fast flick snaps to higher anchor', async () => {
+    const { getByTestId } = render(<App inertiaFactor={50} />)
+    const panelEl = getByTestId('panel')
+
+    mockTimedDrag(panelEl, 200, 170, 32, 3)
+
+    await waitFor(() =>
+      expect(panelEl.style.transform).toBe(
+        `translateY(calc(100% + (-${anchors[1]}px)))`
+      )
+    )
+  })
+
+  test('with inertiaFactor, slow drag stays at nearest anchor', async () => {
+    const { getByTestId } = render(<App inertiaFactor={100} />)
+    const panelEl = getByTestId('panel')
+
+    mockTimedDrag(panelEl, 200, 170, 1000, 10)
+
+    await waitFor(() =>
+      expect(panelEl.style.transform).toBe(
+        `translateY(calc(100% + (-${anchors[0]}px)))`
+      )
+    )
+  })
+
+  test('large inertiaFactor with fast flick skips to farthest anchor', async () => {
+    const { getByTestId } = render(<App inertiaFactor={300} />)
+    const panelEl = getByTestId('panel')
+
+    mockTimedDrag(panelEl, 200, 170, 16, 3)
+
+    await waitFor(() =>
+      expect(panelEl.style.transform).toBe(
+        `translateY(calc(100% + (-${anchors[2]}px)))`
+      )
+    )
+  })
+})

src/tests/testing.tsx

@@ -156,3 +156,42 @@ export const mockDrag = async (el: Element, options: any[], time?: number) => {
   }
   fireEvent.mouseUp(el)
 }
+
+/**
+ * Simulates a vertical drag with velocity — smaller duration means faster flick
+ *
+ * @param el       Target element
+ * @param from     Starting clientY
+ * @param to       Ending clientY
+ * @param duration Drag duration in ms
+ * @param steps    Number of mouseMove events
+ */
+export const mockTimedDrag = (
+  el: Element,
+  from: number,
+  to: number,
+  duration: number,
+  steps: number,
+) => {
+  const dispatch = (
+    type: 'mousedown' | 'mousemove' | 'mouseup',
+    clientY: number,
+    timeStamp: number,
+  ) => {
+    const ev = new MouseEvent(type, {
+      clientY,
+      buttons: 1,
+      bubbles: true,
+      cancelable: true,
+    })
+    Object.defineProperty(ev, 'timeStamp', { value: timeStamp, configurable: true })
+    fireEvent(el, ev)
+  }
+
+  dispatch('mousedown', from, 1000)
+  for (let i = 1; i <= steps; i++) {
+    const progress = i / steps
+    dispatch('mousemove', from + (to - from) * progress, 1000 + duration * progress)
+  }
+  dispatch('mouseup', to, 1000 + duration)
+}