feat: add modifierKey for wheel option (#477)

Defaults to `'ctrlKey'`

Author: dbismut

.changeset/grumpy-beds-hang.md

@@ -0,0 +1,5 @@
+---
+'@use-gesture/core': patch
+---
+
+feat: add modifierKey for wheel option. Defaults to `'ctrlKey'`.

documentation/pages/docs/options.mdx

@@ -107,6 +107,7 @@ Here are all options that can be applied to gestures.
 | [`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.                                                                                                                                                   |
+| [`modifierKey`](#modifierKey)             |    **pinch**    | The modifier key that triggers a scale when wheeling. Defaults to `'ctrlKey'`. Can be null.                                                                                                          |
 | [`rubberband`](#rubberband)               |     **all**     | The elasticity coefficient of the gesture when going out of bounds. When set to `true`, the elasticity coefficient will be defaulted to `0.15`                                                       |
 | [`transform`](#transform)                 |     **all**     | A function that you can use to transform pointer values. Useful to map your screen coordinates to custom space coordinates such as a canvas.                                                         |
 | [`filterTaps`](#filtertaps)               |    **drag**     | If `true`, the component won't trigger your drag logic if the user just clicked on the component.                                                                                                    |
@@ -306,6 +307,12 @@ function InitialExample() {
 
 > Unless your initial position is static or depends on `state`, make sure you use a function rather than a static array.
 
+### modifierKey
+
+<Specs gestures={['pinch']} types={[`'ctrlKey'`, `'altKey'`, `'metaKey'`, 'null']} defaultValue={`'ctrlKey'`} />
+
+This option lets you set the modifier key that triggers a scale gesture when using wheel inside the `onPinch` handler.
+
 ### pointer.buttons
 
 <Specs gestures={['drag']} types={['number', 'number[]']} defaultValue="1" />

packages/core/src/config/pinchConfigResolver.ts

@@ -1,3 +1,4 @@
+import { ModifierKey } from '../types'
 import { PinchConfig, GenericOptions, InternalPinchOptions, State, Vector2 } from '../types'
 import { call, assignDefault } from '../utils/fn'
 import { V } from '../utils/maths'
@@ -42,5 +43,9 @@ export const pinchConfigResolver = {
     this.lockDirection = config.axis === 'lock'
     const threshold = V.toVector(value, this.lockDirection ? [0.1, 3] : 0)
     return threshold
+  },
+  modifierKey(value: ModifierKey) {
+    if (value === undefined) return 'ctrlKey'
+    return value
   }
 }

packages/core/src/engines/PinchEngine.ts

@@ -233,7 +233,8 @@ export class PinchEngine extends Engine<'pinch'> {
   }
 
   wheel(event: WheelEvent) {
-    if (!event.ctrlKey) return
+    const modifierKey = this.config.modifierKey
+    if (modifierKey && !event[modifierKey]) return
     if (!this.state._active) this.wheelStart(event)
     else this.wheelChange(event)
     this.timeoutStore.add('wheelEnd', this.wheelEnd.bind(this))

packages/core/src/types/config.ts

@@ -87,6 +87,7 @@ export type CoordinatesConfig<Key extends CoordinatesKey = CoordinatesKey> = Ges
 }
 
 export type PinchBounds = { min?: number; max?: number }
+export type ModifierKey = 'ctrlKey' | 'altKey' | 'metaKey' | null
 
 export type PinchConfig = GestureOptions<'pinch'> & {
   pointer?: {
@@ -107,6 +108,10 @@ export type PinchConfig = GestureOptions<'pinch'> & {
    * Scales OR rotates when set to 'lock'.
    */
   axis?: 'lock' | undefined
+  /**
+   * Key that triggers scale when using the wheel. Defaults to `'ctrlKey'`.
+   */
+  modifierKey?: ModifierKey
 }
 
 export type DragBounds = Bounds | HTMLElement | React.RefObject<HTMLElement>

packages/core/src/types/internalConfig.ts

@@ -1,4 +1,4 @@
-import { GestureKey, CoordinatesKey } from './config'
+import { GestureKey, CoordinatesKey, ModifierKey } from './config'
 import { State } from './state'
 import { Vector2 } from './utils'
 
@@ -50,6 +50,7 @@ export type InternalPinchOptions = InternalGestureOptions<'pinch'> & {
    */
   device: 'gesture' | 'pointer' | 'touch' | undefined
   lockDirection: boolean
+  modifierKey: ModifierKey
 }
 
 type MoveAndHoverMouseOnly = {

test/config.test.tsx

@@ -161,7 +161,8 @@ describe('testing derived config', () => {
         lockDirection: false,
         from: undefined,
         threshold: [0, 0],
-        rubberband: [0, 0]
+        rubberband: [0, 0],
+        modifierKey: 'ctrlKey'
       })
     })
 
@@ -173,5 +174,10 @@ describe('testing derived config', () => {
         [0, 270]
       ])
     })
+
+    test(`setting modifierKey to null should result in modifierKey being null`, () => {
+      config = { modifierKey: null }
+      expect(parse(config, 'pinch').pinch).toHaveProperty('modifierKey', null)
+    })
   })
 })