Fix minVelocity props behavior (#4327)

## Description

`Pan`'s velocity-based activation criteria (`minVelocity`,
`minVelocityX`, `minVelocityY`) had three
long-standing problems:

1. **Android: `minVelocityY` tested the horizontal velocity.**
`shouldActivate()` declared
`val vy = velocityY` but compared `vx` in both comparisons of the Y
branch, so a pan configured
with only `minVelocityY` activated on fast horizontal movement and never
on vertical movement.
   The typo predates the 2022 repo restructure (#2270).

2. **All platforms: per-axis thresholds were compared with sign.** A
positive `minVelocityY` only
activated on downward movement, negative only on upward. This is
surprising — `minVelocityY: 100`
reads as "vertical speed of at least 100", not "drag down". The signed
logic appears to have been
copied from the offset-range checks (`activeOffsetX/Y`), where signed
semantics actually make
sense. The checks now compare absolute values: `abs(velocity) >=
abs(threshold)`, so movement in
either direction along the axis activates. (`minVelocity` already
compared the velocity vector
   magnitude and is unchanged.)

3. **Web: `minVelocity` meant something different than on native.** It
was mapped onto the per-axis
X/Y thresholds ("either axis exceeds the value") instead of the vector
magnitude like Android and
iOS compute it. The `minVelocitySq` field existed for this but was never
assigned from the config.
It is now wired up, matching native behavior (e.g. a diagonal drag at
600 pt/s with
   `minVelocity: 500` now activates on web as it does on native).

None of these props were documented anywhere. This PR adds them to the
docs (new API + 2.x pages)
and to the JSDoc of all three API layers, described as speed "expressed
in points per second".

> [!WARNING]
> I've used [`grep.app`](https://grep.app/) to check whether these props
are used and seems that they're not, so it _should be safe_ to introduce
these changes.

## Test plan

<details>
<summary>Tested on the following code:</summary>

```tsx
// Repro for Pan minVelocityY issues:
// 1. Android compared vx (horizontal velocity) in the minVelocityY branch,
//    so a fast horizontal swipe wrongly activated the pan.
// 2. All platforms compared the velocity with its sign, so a positive
//    minVelocityY only activated on downward movement. The checks now use
//    absolute values: either direction along the axis activates.
//
// Setup: minDistance is set huge so distance can never activate the pan —
// only the velocity criteria can. Expected: swiping DOWN or UP faster than
// 500 activates; a fast horizontal swipe never does.
import React, { useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';
import {
  GestureDetector,
  GestureHandlerRootView,
  usePanGesture,
} from 'react-native-gesture-handler';

export default function EmptyExample() {
  const [log, setLog] = useState<string[]>([]);

  const append = (entry: string) =>
    setLog((prev) => [...prev.slice(-8), entry]);

  const pan = usePanGesture({
    minVelocityY: 800,
    runOnJS: true,
    onActivate: (e) => {
      append(
        `ACTIVATED vx=${Math.round(e.velocityX)} vy=${Math.round(e.velocityY)}`
      );
    },
    onFinalize: (e) => {
      if (e.canceled) {
        append('finished without activation');
      }
    },
  });

  return (
    <GestureHandlerRootView style={styles.container}>
      <Text style={styles.title}>minVelocityY = 500, minDistance = 10000</Text>
      <Text style={styles.hint}>
        Fast horizontal swipe should NOT activate.{'\n'}
        Fast vertical swipe (up OR down) SHOULD activate.
      </Text>
      <GestureDetector gesture={pan}>
        <View style={styles.box} testID="panBox">
          <Text style={styles.boxLabel}>swipe here</Text>
        </View>
      </GestureDetector>
      <View style={styles.log}>
        {log.map((entry, i) => (
          <Text key={i} style={styles.logLine}>
            {entry}
          </Text>
        ))}
      </View>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    paddingTop: 60,
  },
  title: {
    fontSize: 16,
    fontWeight: 'bold',
  },
  hint: {
    textAlign: 'center',
    marginVertical: 12,
    color: '#666',
  },
  box: {
    width: 300,
    height: 300,
    backgroundColor: 'tomato',
    borderRadius: 16,
    justifyContent: 'center',
    alignItems: 'center',
  },
  boxLabel: {
    color: 'white',
    fontSize: 18,
  },
  log: {
    marginTop: 20,
    minHeight: 200,
    alignSelf: 'stretch',
    paddingHorizontal: 24,
  },
  logLine: {
    fontFamily: 'monospace',
    fontSize: 13,
  },
});
```

</details>

Author: m-bert

packages/docs-gesture-handler/docs/gestures/use-pan-gesture.mdx

@@ -126,6 +126,30 @@ minDistance: number | SharedValue<number>;
 
 Minimum distance the finger (or multiple fingers) need to travel before the gesture activates. Expressed in points.
 
+### minVelocity
+
+```ts
+minVelocity: number | SharedValue<number>;
+```
+
+Minimum speed the pointer has to reach in order to activate the gesture. Expressed in points per second.
+
+### minVelocityX
+
+```ts
+minVelocityX: number | SharedValue<number>;
+```
+
+Minimum speed along X axis the pointer has to reach in order to activate the gesture. Expressed in points per second.
+
+### minVelocityY
+
+```ts
+minVelocityY: number | SharedValue<number>;
+```
+
+Minimum speed along Y axis the pointer has to reach in order to activate the gesture. Expressed in points per second.
+
 ### minPointers
 
 ```ts

packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md

@@ -52,6 +52,18 @@ See [set of properties inherited from base handler class](/docs/2.x/gesture-hand
 
 Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/2.x/under-the-hood/state#active). Expressed in points.
 
+### `minVelocity`
+
+Minimum speed the pointer has to reach in order for the handler to [activate](/docs/2.x/under-the-hood/state#active). Expressed in points per second.
+
+### `minVelocityX`
+
+Minimum speed along X axis the pointer has to reach in order for the handler to [activate](/docs/2.x/under-the-hood/state#active). Expressed in points per second.
+
+### `minVelocityY`
+
+Minimum speed along Y axis the pointer has to reach in order for the handler to [activate](/docs/2.x/under-the-hood/state#active). Expressed in points per second.
+
 ### `minPointers`
 
 A number of fingers that is required to be placed before handler can [activate](/docs/2.x/under-the-hood/state#active). Should be an integer greater than or equal to 0.

packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/pan-gesture.md

@@ -117,6 +117,18 @@ If you wish to track the "center of mass" virtual pointer and account for its ch
 
 Minimum distance the finger (or multiple fingers) need to travel before the gesture [activates](/docs/2.x/fundamentals/states-events#active). Expressed in points.
 
+### `minVelocity(value: number)`
+
+Minimum speed the pointer has to reach in order for the gesture to [activate](/docs/2.x/fundamentals/states-events#active). Expressed in points per second.
+
+### `minVelocityX(value: number)`
+
+Minimum speed along X axis the pointer has to reach in order for the gesture to [activate](/docs/2.x/fundamentals/states-events#active). Expressed in points per second.
+
+### `minVelocityY(value: number)`
+
+Minimum speed along Y axis the pointer has to reach in order for the gesture to [activate](/docs/2.x/fundamentals/states-events#active). Expressed in points per second.
+
 ### `minPointers(value: number)`
 
 A number of fingers that is required to be placed before the gesture can [activate](/docs/2.x/fundamentals/states-events#active). Should be an integer greater than or equal to 0.

packages/react-native-gesture-handler/android/src/main/java/com/swmansion/gesturehandler/core/PanGestureHandler.kt

@@ -11,6 +11,7 @@ import com.facebook.react.uimanager.PixelUtil
 import com.swmansion.gesturehandler.core.GestureUtils.getLastPointerX
 import com.swmansion.gesturehandler.core.GestureUtils.getLastPointerY
 import com.swmansion.gesturehandler.react.events.eventbuilders.PanGestureHandlerEventDataBuilder
+import kotlin.math.abs
 
 class PanGestureHandler(context: Context?) : GestureHandler() {
   override val isContinuous = true
@@ -115,15 +116,11 @@ class PanGestureHandler(context: Context?) : GestureHandler() {
       return true
     }
     val vx = velocityX
-    if (minVelocityX != MIN_VALUE_IGNORE &&
-      (minVelocityX < 0 && vx <= minVelocityX || minVelocityX in 0.0f..vx)
-    ) {
+    if (minVelocityX != MIN_VALUE_IGNORE && abs(vx) >= abs(minVelocityX)) {
       return true
     }
     val vy = velocityY
-    if (minVelocityY != MIN_VALUE_IGNORE &&
-      (minVelocityY < 0 && vx <= minVelocityY || minVelocityY in 0.0f..vx)
-    ) {
+    if (minVelocityY != MIN_VALUE_IGNORE && abs(vy) >= abs(minVelocityY)) {
       return true
     }
     val velocitySq = vx * vx + vy * vy

packages/react-native-gesture-handler/apple/Handlers/RNPanHandler.m

@@ -337,10 +337,10 @@ - (BOOL)shouldActivateUnderCustomCriteria
   }
 
   CGPoint velocity = [self velocityInView:self.view];
-  if (TEST_MIN_IF_NOT_NAN(velocity.x, _minVelocityX)) {
+  if (TEST_ABS_MIN_IF_NOT_NAN(velocity.x, _minVelocityX)) {
     return YES;
   }
-  if (TEST_MIN_IF_NOT_NAN(velocity.y, _minVelocityY)) {
+  if (TEST_ABS_MIN_IF_NOT_NAN(velocity.y, _minVelocityY)) {
     return YES;
   }
   if (TEST_MIN_IF_NOT_NAN(VEC_LEN_SQ(velocity), _minVelocitySq)) {

packages/react-native-gesture-handler/apple/RNGestureHandler.h

@@ -15,6 +15,8 @@
 #define TEST_MIN_IF_NOT_NAN(value, limit) \
   (!isnan(limit) && ((limit < 0 && value <= limit) || (limit >= 0 && value >= limit)))
 
+#define TEST_ABS_MIN_IF_NOT_NAN(value, limit) (!isnan(limit) && fabs(value) >= fabs(limit))
+
 #define TEST_MAX_IF_NOT_NAN(value, max) (!isnan(max) && ((max < 0 && value < max) || (max >= 0 && value > max)))
 
 #define APPLY_PROP(recognizer, config, type, prop, propName) \

packages/react-native-gesture-handler/src/handlers/PanGestureHandler.ts

@@ -63,9 +63,24 @@ interface CommonPanProperties {
    */
   maxPointers?: number;
 
+  /**
+   * Minimum speed the pointer has to reach in order to activate the handler.
+   * Expressed in points per second.
+   */
   minVelocity?: number;
+
+  /**
+   * Minimum speed along X axis the pointer has to reach in order to activate
+   * the handler. Expressed in points per second.
+   */
   minVelocityX?: number;
+
+  /**
+   * Minimum speed along Y axis the pointer has to reach in order to activate
+   * the handler. Expressed in points per second.
+   */
   minVelocityY?: number;
+
   activateAfterLongPress?: number;
 }
 

packages/react-native-gesture-handler/src/handlers/gestures/panGesture.ts

@@ -154,7 +154,8 @@ export class PanGesture extends ContinousBaseGesture<
   }
 
   /**
-   * Minimum velocity the finger has to reach in order to activate handler.
+   * Minimum speed the pointer has to reach in order to activate handler.
+   * Expressed in points per second.
    * @param velocity
    */
   minVelocity(velocity: number) {
@@ -163,7 +164,8 @@ export class PanGesture extends ContinousBaseGesture<
   }
 
   /**
-   * Minimum velocity along X axis the finger has to reach in order to activate handler.
+   * Minimum speed along X axis the pointer has to reach in order to activate handler.
+   * Expressed in points per second.
    * @param velocity
    */
   minVelocityX(velocity: number) {
@@ -172,7 +174,8 @@ export class PanGesture extends ContinousBaseGesture<
   }
 
   /**
-   * Minimum velocity along Y axis the finger has to reach in order to activate handler.
+   * Minimum speed along Y axis the pointer has to reach in order to activate handler.
+   * Expressed in points per second.
    * @param velocity
    */
   minVelocityY(velocity: number) {

packages/react-native-gesture-handler/src/v3/hooks/gestures/pan/PanTypes.ts

@@ -40,9 +40,24 @@ type CommonPanGestureProperties = {
    */
   maxPointers?: number;
 
+  /**
+   * Minimum speed the pointer has to reach in order to activate the gesture.
+   * Expressed in points per second.
+   */
   minVelocity?: number;
+
+  /**
+   * Minimum speed along X axis the pointer has to reach in order to activate
+   * the gesture. Expressed in points per second.
+   */
   minVelocityX?: number;
+
+  /**
+   * Minimum speed along Y axis the pointer has to reach in order to activate
+   * the gesture. Expressed in points per second.
+   */
   minVelocityY?: number;
+
   activateAfterLongPress?: number;
 };
 

packages/react-native-gesture-handler/src/web/handlers/PanGestureHandler.ts

@@ -75,8 +75,7 @@ export default class PanGestureHandler extends GestureHandler {
     }
 
     if (config.minVelocity !== undefined) {
-      this.minVelocityX = config.minVelocity;
-      this.minVelocityY = config.minVelocity;
+      this.minVelocitySq = config.minVelocity * config.minVelocity;
       this.hasCustomActivationCriteria = true;
     }
 
@@ -432,17 +431,15 @@ export default class PanGestureHandler extends GestureHandler {
 
     if (
       this.minVelocityX !== Number.MAX_SAFE_INTEGER &&
-      ((this.minVelocityX < 0 && vx <= this.minVelocityX) ||
-        (this.minVelocityX >= 0 && this.minVelocityX <= vx))
+      Math.abs(vx) >= Math.abs(this.minVelocityX)
     ) {
       return true;
     }
 
     const vy: number = this.velocityY;
     if (
       this.minVelocityY !== Number.MAX_SAFE_INTEGER &&
-      ((this.minVelocityY < 0 && vy <= this.minVelocityY) ||
-        (this.minVelocityY >= 0 && this.minVelocityY <= vy))
+      Math.abs(vy) >= Math.abs(this.minVelocityY)
     ) {
       return true;
     }