Feature: Option to configure keyboard displacement in the drag gesture (#577)

markjaniczak · Mark Janiczak · web-flow · commit 60aae2149a17 · 2023-01-28T10:29:32.000+01:00
* Added option to configure keyboard displacement in the drag gesture

* Updated options doc

* Moved computation of the key delta map

* Added default values to factor

* chore: update deps + add changeset

---------

Co-authored-by: Mark Janiczak &lt;janiczak.mark@abc.net.au&gt;
diff --git a/.changeset/big-wombats-count.md b/.changeset/big-wombats-count.md
@@ -0,0 +1,5 @@
+---
+'@use-gesture/core': patch
+---
+
+feat: Added option to configure keyboard displacement in the drag gesture
diff --git a/demo/package.json b/demo/package.json
@@ -31,7 +31,7 @@
     "@types/three": "^0.140.0",
     "@vitejs/plugin-react": "^1.3.2",
     "typescript": "^4.8.4",
-    "typescript-plugin-css-modules": "^3.4.0",
-    "vite": "2.9.9"
+    "typescript-plugin-css-modules": "^4.1.1",
+    "vite": "^4.0.3"
   }
 }
diff --git a/documentation/pages/docs/options.mdx b/documentation/pages/docs/options.mdx
@@ -127,6 +127,7 @@ Here are all options that can be applied to gestures.
 | [`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.                                                                                     |
 | [`swipe.duration`](#swipeduration)        |                                           **drag**                                            | The maximum duration in milliseconds that a swipe is detected.                                                                                                                                       |
+| `keyboardDisplacement`                    |                                           **drag**                                            | The distance (in `pixels`) emulated by arrow keys. Default is `10`.                                                                                                                                  |
 | `mouseOnly`                               |                                        **hover, move**                                        | Set to `false` if you want your `hover` or `move` handlers to be triggered on non-mouse events. This is a useful option in case you want to perform logic on touch-enabled devices.                  |
 
 ## Options explained
diff --git a/package.json b/package.json
@@ -5,9 +5,6 @@
   "license": "MIT",
   "private": true,
   "preconstruct": {
-    "___experimentalFlags_WILL_CHANGE_IN_PATCH": {
-      "exports": true
-    },
     "packages": [
       "packages/*"
     ]
@@ -75,39 +72,39 @@
     ]
   },
   "devDependencies": {
-    "@babel/core": "^7.19.6",
+    "@babel/core": "^7.20.12",
     "@babel/plugin-syntax-flow": "^7.18.6",
-    "@babel/plugin-transform-react-jsx": "^7.19.0",
-    "@babel/preset-env": "^7.19.4",
+    "@babel/plugin-transform-react-jsx": "^7.20.13",
+    "@babel/preset-env": "^7.20.2",
     "@babel/preset-react": "^7.18.6",
     "@babel/preset-typescript": "^7.18.6",
-    "@changesets/cli": "^2.25.1",
-    "@preconstruct/cli": "^2.2.2",
+    "@changesets/cli": "^2.26.0",
+    "@preconstruct/cli": "^2.3.0",
     "@size-limit/preset-small-lib": "^7.0.8",
     "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/react": "^13.2.0",
     "@types/jest": "^27.5.1",
-    "@types/node": "^18.11.7",
-    "@types/react": "^18.0.24",
-    "@types/react-dom": "^18.0.8",
-    "@typescript-eslint/eslint-plugin": "^5.41.0",
-    "@typescript-eslint/parser": "^5.41.0",
-    "babel-jest": "^27.5.1",
-    "eslint": "^8.26.0",
+    "@types/node": "^18.11.18",
+    "@types/react": "^18.0.27",
+    "@types/react-dom": "^18.0.10",
+    "@typescript-eslint/eslint-plugin": "^5.49.0",
+    "@typescript-eslint/parser": "^5.49.0",
+    "babel-jest": "^29.4.1",
+    "eslint": "^8.32.0",
     "eslint-config-react-app": "^7.0.1",
-    "eslint-plugin-jest-dom": "^4.0.2",
+    "eslint-plugin-jest-dom": "^4.0.3",
     "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-testing-library": "^5.9.1",
-    "husky": "^8.0.1",
+    "eslint-plugin-testing-library": "^5.10.0",
+    "husky": "^8.0.3",
     "jest": "^27.5.1",
-    "pnpm": "^7.14.1",
+    "pnpm": "^7.26.1",
     "postinstall-postinstall": "^2.1.0",
-    "prettier": "^2.7.1",
+    "prettier": "^2.8.3",
     "pretty-quick": "^3.1.3",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "size-limit": "^7.0.8",
-    "tsd": "^0.24.1",
-    "typescript": "^4.8.4"
+    "tsd": "^0.25.0",
+    "typescript": "^4.9.4"
   }
 }
diff --git a/packages/core/src/config/dragConfigResolver.ts b/packages/core/src/config/dragConfigResolver.ts
@@ -9,6 +9,7 @@ export const DEFAULT_DRAG_DELAY = 180
 export const DEFAULT_SWIPE_VELOCITY = 0.5
 export const DEFAULT_SWIPE_DISTANCE = 50
 export const DEFAULT_SWIPE_DURATION = 250
+export const DEFAULT_KEYBOARD_DISPLACEMENT = 10
 
 const DEFAULT_DRAG_AXIS_THRESHOLD: Record<PointerType, number> = { mouse: 0, touch: 0, pen: 8 }
 
@@ -82,6 +83,9 @@ export const dragConfigResolver = {
   axisThreshold(value: Record<PointerType, number>) {
     if (!value) return DEFAULT_DRAG_AXIS_THRESHOLD
     return { ...DEFAULT_DRAG_AXIS_THRESHOLD, ...value }
+  },
+  keyboardDisplacement(value: number = DEFAULT_KEYBOARD_DISPLACEMENT) {
+    return value
   }
 }
 
diff --git a/packages/core/src/engines/DragEngine.ts b/packages/core/src/engines/DragEngine.ts
@@ -4,13 +4,11 @@ import { pointerId, getPointerType, pointerValues } from '../utils/events'
 import { V } from '../utils/maths'
 import { Vector2 } from '../types'
 
-const DISPLACEMENT = 10
-
 const KEYS_DELTA_MAP = {
-  ArrowRight: (factor = 1) => [DISPLACEMENT * factor, 0],
-  ArrowLeft: (factor = 1) => [-DISPLACEMENT * factor, 0],
-  ArrowUp: (factor = 1) => [0, -DISPLACEMENT * factor],
-  ArrowDown: (factor = 1) => [0, DISPLACEMENT * factor]
+  ArrowRight: (displacement: number, factor: number = 1) => [displacement * factor, 0],
+  ArrowLeft: (displacement: number, factor: number = 1) => [-1 * displacement * factor, 0],
+  ArrowUp: (displacement: number, factor: number = 1) => [0, -1 * displacement * factor],
+  ArrowDown: (displacement: number, factor: number = 1) => [0, displacement * factor]
 }
 
 export class DragEngine extends CoordinatesEngine<'drag'> {
@@ -341,7 +339,7 @@ export class DragEngine extends CoordinatesEngine<'drag'> {
 
       this.start(event)
 
-      state._delta = deltaFn(factor)
+      state._delta = deltaFn(this.config.keyboardDisplacement, factor)
       state._keyboardActive = true
       V.addTo(state._movement, state._delta)
 
diff --git a/packages/core/src/engines/Engine.ts b/packages/core/src/engines/Engine.ts
@@ -303,6 +303,7 @@ export abstract class Engine<Key extends GestureKey> {
 
       if (event) {
         if (state.first) {
+          // @ts-expect-error (4.9 regression https://github.com/microsoft/TypeScript/issues/51501)
           if ('bounds' in config) state._bounds = call(config.bounds, state)
           if (this.setup) this.setup()
         }
diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts
@@ -227,6 +227,10 @@ export type DragConfig = Omit<CoordinatesConfig<'drag'>, 'axisThreshold' | 'boun
    * be calculated.
    */
   axisThreshold?: Partial<Record<PointerType, number>>
+  /**
+   * The distance (in pixels) emulated by arrow keys.
+   */
+  keyboardDisplacement?: number
 }
 
 export type UserDragConfig = GenericOptions & DragConfig
diff --git a/packages/core/src/types/internalConfig.ts b/packages/core/src/types/internalConfig.ts
@@ -46,6 +46,7 @@ export type InternalDragOptions = Omit<InternalCoordinatesOptions<'drag'>, 'axis
   }
   delay: number
   axisThreshold: Record<PointerType, number>
+  keyboardDisplacement: number
 }
 
 export type InternalPinchOptions = InternalGestureOptions<'pinch'> & {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/test/config.test.tsx b/test/config.test.tsx
diff --git a/test/drag.test.tsx b/test/drag.test.tsx

Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@`
`31`	`31`	`"@types/three": "^0.140.0",`
`32`	`32`	`"@vitejs/plugin-react": "^1.3.2",`
`33`	`33`	`"typescript": "^4.8.4",`
`34`		`- "typescript-plugin-css-modules": "^3.4.0",`
`35`		`- "vite": "2.9.9"`
	`34`	`+ "typescript-plugin-css-modules": "^4.1.1",`
	`35`	`+ "vite": "^4.0.3"`
`36`	`36`	`}`
`37`	`37`	`}`
Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@ export const DEFAULT_DRAG_DELAY = 180`
`9`	`9`	`export const DEFAULT_SWIPE_VELOCITY = 0.5`
`10`	`10`	`export const DEFAULT_SWIPE_DISTANCE = 50`
`11`	`11`	`export const DEFAULT_SWIPE_DURATION = 250`
	`12`	`+export const DEFAULT_KEYBOARD_DISPLACEMENT = 10`
`12`	`13`
`13`	`14`	`const DEFAULT_DRAG_AXIS_THRESHOLD: Record<PointerType, number> = { mouse: 0, touch: 0, pen: 8 }`
`14`	`15`
`@@ -82,6 +83,9 @@ export const dragConfigResolver = {`
`82`	`83`	`axisThreshold(value: Record<PointerType, number>) {`
`83`	`84`	`if (!value) return DEFAULT_DRAG_AXIS_THRESHOLD`
`84`	`85`	`return { ...DEFAULT_DRAG_AXIS_THRESHOLD, ...value }`
	`86`	`+ },`
	`87`	`+ keyboardDisplacement(value: number = DEFAULT_KEYBOARD_DISPLACEMENT) {`
	`88`	`+ return value`
`85`	`89`	`}`
`86`	`90`	`}`
`87`	`91`
Original file line number	Diff line number	Diff line change
`@@ -303,6 +303,7 @@ export abstract class Engine<Key extends GestureKey> {`
`303`	`303`
`304`	`304`	`if (event) {`
`305`	`305`	`if (state.first) {`
	`306`	`+ // @ts-expect-error (4.9 regression https://github.com/microsoft/TypeScript/issues/51501)`
`306`	`307`	`if ('bounds' in config) state._bounds = call(config.bounds, state)`
`307`	`308`	`if (this.setup) this.setup()`
`308`	`309`	`}`
Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,7 @@ export type InternalDragOptions = Omit<InternalCoordinatesOptions<'drag'>, 'axis`
`46`	`46`	`}`
`47`	`47`	`delay: number`
`48`	`48`	`axisThreshold: Record<PointerType, number>`
	`49`	`+ keyboardDisplacement: number`
`49`	`50`	`}`
`50`	`51`
`51`	`52`	`export type InternalPinchOptions = InternalGestureOptions<'pinch'> & {`