Fix/prevent scroll pencil (#475)

Author: dbismut

.changeset/clean-maps-happen.md

@@ -0,0 +1,8 @@
+---
+'@use-gesture/core': patch
+---
+
+- fix: trigger `pointerDown` event when `triggerAllEvents` and `delay` options are set
+- fix: disable scroll prevention when the event type is `'mouse'`
+- feat: add `axisThreshold` property to set a threshold for axis calculation (can be set per device for the drag gesture)
+- fix: axis are now calculated on pixel movement rather than on transformed movement

demo/src/sandboxes/gesture-drag/src/App.jsx

@@ -53,8 +53,6 @@ function Draggable() {
     }
   )
 
-  console.log(bind())
-
   return (
     <>
       <a.div tabIndex={-1} {...bind()} className={styles.drag} style={style}>

documentation/pages/docs/options.mdx

@@ -104,6 +104,7 @@ Here are all options that can be applied to gestures.
 | [`preventDefault`](#preventdefault)       |     **all**     | Will `preventDefault` all events triggered by the handler.                                                                                                                                           |
 | [`triggerAllEvents`](#triggerallevents)   |     **all**     | Forces the handler to fire even for non intentional displacement (ignores the `threshold`). In that case, the `intentional` attribute from state will remain `false` until the threshold is reached. |
 | [`axis`](#axis)                           |     **all**     | Your handler will only trigger if a movement is detected on the specified axis.                                                                                                                      |
+| [`axisThreshold`](#axisthreshold)         |     **xy**      | Axes are calculated based on a threshold. For drag, thresholds are specified per device type.                                                                                                        |
 | [`bounds`](#bounds)                       |     **xy**      | Limits the gesture `offset` to the specified bounds.                                                                                                                                                 |
 | [`scaleBounds`](#scalebounds)             |    **pinch**    | Limits the scale `offset` to the specified bounds.                                                                                                                                                   |
 | [`angleBounds`](#anglebounds)             |    **pinch**    | Limits the angle `offset` to the specified bounds.                                                                                                                                                   |
@@ -181,6 +182,22 @@ function LockAxisExample() {
 }
 ```
 
+### axisThreshold
+
+A gesture axis is determined whenever x-axis and y-axis displacements reach a threshold.
+
+#### xy gestures (except for drag)
+
+<Specs types="number" defaultValue={0} />
+
+For non-drag xy gestures, that threshold is always a number, which defaults to `0`.
+
+#### drag
+
+<Specs types="{ mouse: number, pen: number, touch: number }" defaultValue="{ mouse: 0, pen: 8, touch: 0 }" />
+
+Drag logic is the same, but you must specify the threshold for a specific device. Since pen is much more sensitive than other devices, the default threshold has been empirically set to `8`.
+
 ### bounds
 
 <Specs
@@ -560,7 +577,7 @@ function Transform() {
 }
 ```
 
-> When you use the `useGesture` hook, you can set the `transform` option at the shared level and at the gesture level, with the `transform` set at the gesture level oveerriding the shared one.
+> When you use the `useGesture` hook, you can set the `transform` option at the shared level and at the gesture level, with the `transform` set at the gesture level overriding the shared one.
 
 ```js
 useGesture({/* handlers */ }, {
@@ -577,6 +594,8 @@ useGesture({/* handlers */ }, {
 
 Forces the handler to fire even for non intentional displacement (ignores the `threshold`). In that case, the `intentional` attribute from state will remain `false` until the threshold is reached.
 
+> At this point, this option will not work as expected when using `preventScroll` or `preventScrollAxis`. Please flag an issue if this breaks your usecase.
+
 ### window
 
 <Specs types="node" defaultValue="window" />

packages/core/src/config/coordinatesConfigResolver.ts

@@ -1,6 +1,8 @@
 import { commonConfigResolver } from './commonConfigResolver'
 import { InternalCoordinatesOptions, CoordinatesConfig, Bounds, DragBounds, State, Vector2 } from '../types'
 
+const DEFAULT_AXIS_THRESHOLD = 0
+
 export const coordinatesConfigResolver = {
   ...commonConfigResolver,
   axis(
@@ -12,6 +14,9 @@ export const coordinatesConfigResolver = {
     this.lockDirection = axis === 'lock'
     if (!this.lockDirection) return axis as any
   },
+  axisThreshold(value = DEFAULT_AXIS_THRESHOLD) {
+    return value
+  },
   bounds(
     value: DragBounds | ((state: State) => DragBounds) = {}
   ): (() => EventTarget | null) | HTMLElement | [Vector2, Vector2] {

packages/core/src/config/dragConfigResolver.ts

@@ -1,3 +1,4 @@
+import { PointerType } from '../types'
 import { DragConfig, InternalDragOptions, Vector2 } from '../types'
 import { V } from '../utils/maths'
 import { coordinatesConfigResolver } from './coordinatesConfigResolver'
@@ -9,6 +10,8 @@ export const DEFAULT_SWIPE_VELOCITY = 0.5
 export const DEFAULT_SWIPE_DISTANCE = 50
 export const DEFAULT_SWIPE_DURATION = 250
 
+const DEFAULT_DRAG_AXIS_THRESHOLD: Record<PointerType, number> = { mouse: 0, touch: 0, pen: 8 }
+
 export const dragConfigResolver = {
   ...coordinatesConfigResolver,
   device(
@@ -69,6 +72,10 @@ export const dragConfigResolver = {
       default:
         return value
     }
+  },
+  axisThreshold(value: Record<PointerType, number>) {
+    if (!value) return DEFAULT_DRAG_AXIS_THRESHOLD
+    return { ...DEFAULT_DRAG_AXIS_THRESHOLD, ...value }
   }
 }
 

packages/core/src/engines/CoordinatesEngine.ts

@@ -1,23 +1,19 @@
 import { Engine } from './Engine'
 import { V } from '../utils/maths'
 import { CoordinatesKey, Vector2 } from '../types'
+import { getPointerType } from '../utils/events'
 
-function selectAxis([dx, dy]: Vector2) {
-  const d = Math.abs(dx) - Math.abs(dy)
-  if (d > 0) return 'x'
-  if (d < 0) return 'y'
-  return undefined
-}
+function selectAxis([dx, dy]: Vector2, threshold: number) {
+  const absDx = Math.abs(dx)
+  const absDy = Math.abs(dy)
 
-function restrictVectorToAxis(v: Vector2, axis?: 'x' | 'y') {
-  switch (axis) {
-    case 'x':
-      v[1] = 0
-      break // [ x, 0 ]
-    case 'y':
-      v[0] = 0
-      break // [ 0, y ]
+  if (absDx > absDy && absDx > threshold) {
+    return 'x'
+  }
+  if (absDy > absDx && absDy > threshold) {
+    return 'y'
   }
+  return undefined
 }
 
 export abstract class CoordinatesEngine<Key extends CoordinatesKey> extends Engine<Key> {
@@ -41,20 +37,34 @@ export abstract class CoordinatesEngine<Key extends CoordinatesKey> extends Engi
     this.state.movement = V.sub(this.state.offset, this.state.lastOffset)
   }
 
-  intent(v: Vector2) {
-    this.state.axis = this.state.axis || selectAxis(v)
+  axisIntent(event?: UIEvent) {
+    const state = this.state
+    const config = this.config
+
+    if (!state.axis && event) {
+      const threshold =
+        typeof config.axisThreshold === 'object' ? config.axisThreshold[getPointerType(event)] : config.axisThreshold
+
+      state.axis = selectAxis(state._movement, threshold)
+    }
 
     // We block the movement if either:
     // - config.lockDirection or config.axis was set but axis isn't detected yet
     // - config.axis was set but is different than detected axis
-    this.state._blocked =
-      ((this.config.lockDirection || !!this.config.axis) && !this.state.axis) ||
-      (!!this.config.axis && this.config.axis !== this.state.axis)
-
-    if (this.state._blocked) return
+    state._blocked =
+      ((config.lockDirection || !!config.axis) && !state.axis) || (!!config.axis && config.axis !== state.axis)
+  }
 
+  restrictToAxis(v: Vector2) {
     if (this.config.axis || this.config.lockDirection) {
-      restrictVectorToAxis(v, this.state.axis)
+      switch (this.state.axis) {
+        case 'x':
+          v[1] = 0
+          break // [ x, 0 ]
+        case 'y':
+          v[0] = 0
+          break // [ 0, y ]
+      }
     }
   }
 }

packages/core/src/engines/DragEngine.ts

@@ -1,6 +1,6 @@
 import { CoordinatesEngine } from './CoordinatesEngine'
 import { coordinatesConfigResolver } from '../config/coordinatesConfigResolver'
-import { pointerId, pointerValues } from '../utils/events'
+import { pointerId, getPointerType, pointerValues } from '../utils/events'
 import { V } from '../utils/maths'
 import { Vector2 } from '../types'
 
@@ -106,13 +106,18 @@ export class DragEngine extends CoordinatesEngine<'drag'> {
     this.computeValues(pointerValues(event))
     this.computeInitial()
 
-    if (config.preventScrollAxis) {
+    if (config.preventScrollAxis && getPointerType(event) !== 'mouse') {
       // when preventScrollAxis is set we don't consider the gesture active
       // until it's deliberate
       state._active = false
       this.setupScrollPrevention(event)
     } else if (config.delay > 0) {
       this.setupDelayTrigger(event)
+      // makes sure we emit all events when `triggerAllEvents` flag is `true`
+      if (config.triggerAllEvents) {
+        this.compute(event)
+        this.emit()
+      }
     } else {
       this.startPointerDrag(event)
     }

packages/core/src/engines/Engine.ts

@@ -35,9 +35,11 @@ export interface Engine<Key extends GestureKey> {
    * Function used by some gestures to determine the intentionality of a
    * a movement depending on thresholds. The intent function can change the
    * `state._active` or `state._blocked` flags if the gesture isn't intentional.
-   * @param movement
+   * @param event
    */
-  intent?(movement: Vector2): void
+  axisIntent?(event?: UIEvent): void
+
+  restrictToAxis?(movement: Vector2): void
 }
 
 export abstract class Engine<Key extends GestureKey> {
@@ -251,6 +253,9 @@ export abstract class Engine<Key extends GestureKey> {
       V.addTo(state._distance, _absoluteDelta)
     }
 
+    // let's run intentionality check.
+    if (this.axisIntent) this.axisIntent(event)
+
     // _movement is calculated by each gesture engine
     const [_m0, _m1] = state._movement
     const [t0, t1] = config.threshold
@@ -284,8 +289,8 @@ export abstract class Engine<Key extends GestureKey> {
       movement[1] = _step[1] !== false ? _m1 - _step[1] : 0
     }
 
-    // let's run intentionality check.
-    if (this.intent) this.intent(movement)
+    if (this.restrictToAxis && !state._blocked) this.restrictToAxis(movement)
+
     const previousOffset = state.offset
 
     const gestureIsActive = (state._active && !state._blocked) || state.active

packages/core/src/engines/PinchEngine.ts

@@ -40,17 +40,20 @@ export class PinchEngine extends Engine<'pinch'> {
     this.state.movement = [offset[0] / lastOffset[0], offset[1] - lastOffset[1]]
   }
 
-  intent(v: Vector2) {
+  axisIntent() {
     const state = this.state
+    const [_m0, _m1] = state._movement
     if (!state.axis) {
-      const axisMovementDifference = Math.abs(v[0]) * SCALE_ANGLE_RATIO_INTENT_DEG - Math.abs(v[1])
+      const axisMovementDifference = Math.abs(_m0) * SCALE_ANGLE_RATIO_INTENT_DEG - Math.abs(_m1)
       if (axisMovementDifference < 0) state.axis = 'angle'
       else if (axisMovementDifference > 0) state.axis = 'scale'
     }
+  }
 
+  restrictToAxis(v: Vector2) {
     if (this.config.lockDirection) {
-      if (state.axis === 'scale') v[1] = 0
-      else if (state.axis === 'angle') v[0] = 0
+      if (this.state.axis === 'scale') v[1] = 0
+      else if (this.state.axis === 'angle') v[0] = 0
     }
   }
 

packages/core/src/types/config.ts

@@ -1,5 +1,5 @@
 import { State } from './state'
-import { Vector2, Target } from './utils'
+import { Vector2, Target, PointerType } from './utils'
 
 export type GestureKey = Exclude<keyof State, 'shared'>
 export type CoordinatesKey = Exclude<GestureKey, 'pinch'>
@@ -84,6 +84,11 @@ export type CoordinatesConfig<Key extends CoordinatesKey = CoordinatesKey> = Ges
    * Limits the gesture `offset` to the specified bounds.
    */
   bounds?: Bounds | ((state: State[Key]) => Bounds)
+  /**
+   * Determines the number of pixels in one direction needed for axises to be
+   * calculated.
+   */
+  axisThreshold?: number
 }
 
 export type PinchBounds = { min?: number; max?: number }
@@ -127,7 +132,7 @@ export type MoveConfig = CoordinatesConfig<'move'> & MoveAndHoverMouseOnly
 
 export type HoverConfig = MoveAndHoverMouseOnly
 
-export type DragConfig = CoordinatesConfig<'drag'> & {
+export type DragConfig = Omit<CoordinatesConfig<'drag'>, 'axisThreshold'> & {
   /**
    * If true, the component won't trigger your drag logic if the user just clicked on the component.
    */
@@ -203,6 +208,12 @@ export type DragConfig = CoordinatesConfig<'drag'> & {
    * to 180ms.
    */
   delay?: boolean | number
+  /**
+   * Key-number record that determines for each device (`'mouse'`, `'touch'`,
+   * `'pen'`) the number of pixels of drag in one direction needed for axises to
+   * be calculated.
+   */
+  axisThreshold?: Partial<Record<PointerType, number>>
 }
 
 export type UserDragConfig = GenericOptions & DragConfig

packages/core/src/types/internalConfig.ts

@@ -1,6 +1,6 @@
 import { GestureKey, CoordinatesKey, ModifierKey } from './config'
 import { State } from './state'
-import { Vector2 } from './utils'
+import { PointerType, Vector2 } from './utils'
 
 export type InternalGenericOptions = {
   target?: () => EventTarget
@@ -25,9 +25,10 @@ export type InternalGestureOptions<Key extends GestureKey = GestureKey> = {
 export type InternalCoordinatesOptions<Key extends CoordinatesKey = CoordinatesKey> = InternalGestureOptions<Key> & {
   axis?: 'x' | 'y'
   lockDirection: boolean
+  axisThreshold: number
 }
 
-export type InternalDragOptions = InternalCoordinatesOptions<'drag'> & {
+export type InternalDragOptions = Omit<InternalCoordinatesOptions<'drag'>, 'axisThreshold'> & {
   filterTaps: boolean
   tapsThreshold: number
   pointerButtons: number | number[]
@@ -42,6 +43,7 @@ export type InternalDragOptions = InternalCoordinatesOptions<'drag'> & {
     duration: number
   }
   delay: number
+  axisThreshold: Record<PointerType, number>
 }
 
 export type InternalPinchOptions = InternalGestureOptions<'pinch'> & {

packages/core/src/types/utils.ts

@@ -1,3 +1,4 @@
 export type Vector2 = [number, number]
 export type WebKitGestureEvent = PointerEvent & { scale: number; rotation: number }
 export type Target = EventTarget | React.RefObject<EventTarget>
+export type PointerType = 'mouse' | 'touch' | 'pen'

packages/core/src/utils/events.ts

@@ -1,3 +1,4 @@
+import { PointerType } from '../types'
 import { Vector2 } from '../types'
 
 const EVENT_TYPE_MAP: any = {
@@ -43,6 +44,12 @@ export function isTouch(event: UIEvent) {
   return 'touches' in event
 }
 
+export function getPointerType(event: UIEvent): PointerType {
+  if (isTouch(event)) return 'touch'
+  if ('pointerType' in event) return (event as PointerEvent).pointerType as PointerType
+  return 'mouse'
+}
+
 function getCurrentTargetTouchList(event: TouchEvent) {
   return Array.from(event.touches).filter(
     (e) => e.target === event.currentTarget || (event.currentTarget as Node)?.contains?.(e.target as Node)

test/config.test.tsx

@@ -76,7 +76,8 @@ describe('testing derived config', () => {
         pointerLock: false,
         pointerCapture: true,
         filterTaps: false,
-        tapsThreshold: 3
+        tapsThreshold: 3,
+        axisThreshold: { mouse: 0, pen: 8, touch: 0 }
       })
     })
 
@@ -118,6 +119,12 @@ describe('testing derived config', () => {
       expect(parse(dragConfig, 'drag').drag).toHaveProperty('device', 'pointer')
     })
 
+    test(`derived axisThreshold is preoperly computer`, () => {
+      const axisThreshold = { pen: 3, mouse: 2 }
+      dragConfig = { axisThreshold }
+      expect(parse(dragConfig, 'drag').drag).toHaveProperty('axisThreshold', { mouse: 2, pen: 3, touch: 0 })
+    })
+
     test(`derived transform is properly computed`, () => {
       const transform = ([x, y]: Vector2) => [x / 2, y / 4] as Vector2