feat: add keys option to disable arrow keys drag (#522)

Author: dbismut

.changeset/famous-hats-peel.md

@@ -0,0 +1,5 @@
+---
+'@use-gesture/core': patch
+---
+
+feat: add option to remove arrow keys listeners for the drag gesture.

demo/src/sandboxes/gesture-drag-vanilla/src/App.tsx

@@ -21,8 +21,10 @@ function Draggable() {
     gesture: { options: ['offset', 'movement'] },
     axis: { options: [undefined, 'x', 'y', 'lock'] },
     filterTaps: false,
-    boundToParent: false
+    boundToParent: false,
+    keys: true
   })
+
   const pointerOptions = useControls('pointer', { touch: false, capture: true, lock: false })
 
   useEffect(() => {

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

@@ -22,7 +22,8 @@ function Draggable() {
     boundToParent: false,
     rubberband: false,
     threshold: { value: [3, 3], step: 10 },
-    delay: { value: 1000, step: 100, min: 0, max: 3000, optional: true, disabled: true }
+    delay: { value: 1000, step: 100, min: 0, max: 3000, optional: true, disabled: true },
+    keys: true
   })
 
   const pointerOptions = useControls('pointer', { touch: false, capture: true, lock: false, mouse: false })

documentation/pages/docs/options.mdx

@@ -121,6 +121,7 @@ Here are all options that can be applied to gestures.
 | `pointer.mouse`                           |                                           **drag**                                            | If `true`, drag will use mouse event listeners instead of pointer listeners when possible.                                                                                                           |
 | [`pointer.buttons`](#pointerbuttons)      |                                           **drag**                                            | Combination of buttons that triggers the drag gesture. [Read more below](#pointerbuttons).                                                                                                           |
 | [`pointer.lock`](#pointerlock)            |                                           **drag**                                            | If `true`, the pointer will enter pointer lock mode when drag starts, and exit pointer lock when drag ends. [Read more below](#pointerlock).                                                         |
+| [`keys`](#keys)                           |                                           **drag**                                            | By default, the drag gesture can be triggered by arrow keys when the draggable element is focused. Setting `keys` to `false` won't add keyboard event listeners.                                     |
 | [`delay`](#delay)                         |                                           **drag**                                            | If set, the handler will be delayed for the duration of the delay (in `ms`) — or if the user starts moving. When set to `true`, `delay` is defaulted to `180ms`.                                     |
 | [`swipe.distance`](#swipedistance)        |                                           **drag**                                            | The minimum distance per axis (in `pixels`) the drag gesture needs to travel to trigger a swipe.                                                                                                     |
 | [`swipe.velocity`](#swipevelocity)        |                                           **drag**                                            | The minimum velocity per axis (in `pixels / ms`) the drag gesture needs to reach before the pointer is released.                                                                                     |
@@ -325,6 +326,14 @@ function InitialExample() {
 
 > Unless your initial position is static or depends on `state`, make sure you use a function rather than a static array.
 
+### keys
+
+<Specs gestures={['drag']} types="boolean" defaultValue="true" />
+
+By default, the drag gesture is accessible, meaning you can control the drag of an element with arrow keys. The ` shiftKey` modifier will make the drag 10x faster, the `altKey` will make the drag 10x slower.
+
+If you set `keys` to `false`, your drag handler won't respond to keyboard events.
+
 ### modifierKey
 
 <Specs gestures={['pinch']} types={[`'ctrlKey'`, `'altKey'`, `'metaKey'`, 'null']} defaultValue={`'ctrlKey'`} />

packages/core/src/config/dragConfigResolver.ts

@@ -41,6 +41,9 @@ export const dragConfigResolver = {
     this.pointerButtons = buttons
     return !this.pointerLock && this.device === 'pointer' && capture
   },
+  keys(value = true) {
+    return value
+  },
   threshold(
     this: InternalDragOptions,
     value: number | Vector2,

packages/core/src/engines/DragEngine.ts

@@ -367,9 +367,10 @@ export class DragEngine extends CoordinatesEngine<'drag'> {
       bindFunction('lostPointerCapture', '', this.pointerUp.bind(this))
     }
 
-    bindFunction('key', 'down', this.keyDown.bind(this))
-    bindFunction('key', 'up', this.keyUp.bind(this))
-
+    if (this.config.keys) {
+      bindFunction('key', 'down', this.keyDown.bind(this))
+      bindFunction('key', 'up', this.keyUp.bind(this))
+    }
     if (this.config.filterTaps) {
       bindFunction('click', '', this.pointerClick.bind(this), { capture: true, passive: false })
     }

packages/core/src/types/config.ts

@@ -168,6 +168,11 @@ export type DragConfig = Omit<CoordinatesConfig<'drag'>, 'axisThreshold' | 'boun
      * mouse events on non touch devices.
      */
     mouse?: boolean
+    /**
+     * If false, will disable KeyboardEvents that would otherwise trigger the
+     * drag gesture when the element is focused. Defaults to true.
+     */
+    keys?: boolean
     /**
      * Doesn't use setPointerCapture when false and delegate drag handling to
      * window

packages/core/src/types/internalConfig.ts

@@ -37,6 +37,7 @@ export type InternalDragOptions = Omit<InternalCoordinatesOptions<'drag'>, 'axis
   preventScrollDelay?: number
   preventScrollAxis?: 'x' | 'y' | 'xy'
   pointerLock: boolean
+  keys: boolean
   device: 'pointer' | 'touch' | 'mouse'
   swipe: {
     velocity: Vector2

test/config.test.tsx

@@ -60,6 +60,7 @@ describe('testing derived config', () => {
         transform: identity,
         hasCustomTransform: false,
         preventDefault: false,
+        keys: true,
         triggerAllEvents: false,
         delay: 0,
         swipe: {