Skip to content

AI-native design editor. Open-source Figma alternative.

fix(canvas): pan and zoom with trackpads and mouse wheels as Figma does (#1109)

Danila Poyarkov86610cc99937
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 38312b8f1..c7f43165b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,10 @@
## Unreleased
+### Changed
+
+- Trackpads and mouse wheels pan and zoom the canvas as in Figma. A two-finger pan moves the canvas twice as far, up to 120 px per scroll event. A pinch zooms as far in the desktop app and Safari as in other browsers, where it zooms a little less than before. In the desktop app and Safari, a pinch over Preview's live controls or comment pins now zooms the canvas, where it did nothing. On Windows each mouse wheel notch pans 16 px instead of 100 px, and notches less than 50 ms apart pan up to 120 px each.
+
### Fixed
- HTML, Vue, and React exports name a JPEG, GIF, or WebP image fill by its own type in the data URL instead of calling every image PNG.
diff --git a/packages/vue/src/shared/input/gesture.ts b/packages/vue/src/shared/input/gesture.ts
index acbcf1727..3bc9fe937 100644
--- a/packages/vue/src/shared/input/gesture.ts
+++ b/packages/vue/src/shared/input/gesture.ts
@@ -1,11 +1,19 @@
import { useEventListener } from '@vueuse/core'
-import type { Ref } from 'vue'
+import { computed, type Ref } from 'vue'
import type { Editor } from '@open-pencil/core/editor'
import { createRafScheduler } from '#vue/shared/input/raf-scheduler'
+import { PINCH_SCALE_EXPONENT } from '#vue/shared/input/wheel'
+/**
+ * Zooms on WebKit pinch gestures, which WebKit reports as gesture events instead of Ctrl+wheel.
+ * It listens on the canvas's container, so pinches over layers laid on the canvas, such as
+ * Preview's live controls and comment pins, zoom it too; they can forward wheel events, but not
+ * gestures.
+ */
export function setupSafariGestureZoom(canvasRef: Ref<HTMLCanvasElement | null>, editor: Editor) {
+ const surface = computed(() => canvasRef.value?.parentElement ?? null)
let gestureStartZoom = 1
let pendingGesture: { scale: number; sx: number; sy: number } | null = null
@@ -14,13 +22,13 @@ export function setupSafariGestureZoom(canvasRef: Ref<HTMLCanvasElement | null>,
editor.setHoveredNode(null)
const { scale, sx, sy } = pendingGesture
pendingGesture = null
- editor.setZoomAroundPoint(gestureStartZoom * scale, sx, sy)
+ editor.setZoomAroundPoint(gestureStartZoom * scale ** PINCH_SCALE_EXPONENT, sx, sy)
}
const gestureScheduler = createRafScheduler(flushGesture)
useEventListener(
- canvasRef,
+ surface,
'gesturestart' as keyof HTMLElementEventMap,
(e: Event) => {
e.preventDefault()
@@ -29,7 +37,7 @@ export function setupSafariGestureZoom(canvasRef: Ref<HTMLCanvasElement | null>,
{ passive: false }
)
useEventListener(
- canvasRef,
+ surface,
'gesturechange' as keyof HTMLElementEventMap,
(e: Event) => {
e.preventDefault()
@@ -47,7 +55,7 @@ export function setupSafariGestureZoom(canvasRef: Ref<HTMLCanvasElement | null>,
{ passive: false }
)
useEventListener(
- canvasRef,
+ surface,
'gestureend' as keyof HTMLElementEventMap,
(e: Event) => {
e.preventDefault()
diff --git a/packages/vue/src/shared/input/wheel.ts b/packages/vue/src/shared/input/wheel.ts
index 138eb56a9..45cedf199 100644
--- a/packages/vue/src/shared/input/wheel.ts
+++ b/packages/vue/src/shared/input/wheel.ts
@@ -9,6 +9,38 @@ import { createRafScheduler } from '#vue/shared/input/raf-scheduler'
const WHEEL_DELTA_LINE = 1
const WHEEL_DELTA_PAGE = 2
+/*
+ * Wheel navigation follows Figma's, measured in Figma 126 with real trackpad recordings and its
+ * own wheel handler. Every event pans twice its delta, at most 120 px. Ctrl+wheel, which is how
+ * Chromium reports a touchpad pinch (deltaY = -100 ln scale), zooms by 2^(-deltaY / 50); a
+ * mouse wheel zoom (Meta+wheel, or Ctrl with a Windows wheel notch) zooms by e^(-0.005 deltaY).
+ */
+const PAN_SCALE = 2
+const MAX_PAN_PER_EVENT = 120
+const PINCH_ZOOM_PER_DELTA = Math.LN2 / 50
+const WHEEL_ZOOM_PER_DELTA = 0.005
+const MAX_ZOOM_STEP = Math.log(10)
+
+/*
+ * Windows reports each mouse wheel notch as wheelDelta 120. Figma moves 8 units per notch and
+ * multiplies the step by 2.5 for each notch that follows within 50 ms in the same direction, up
+ * to 120 units, or 40 while zooming, so a slow turn moves 16 px and a fast spin speeds up.
+ */
+const WHEEL_NOTCH = 120
+const MIN_WHEEL_NOTCH = 99
+const NOTCH_STEP = 8
+const NOTCH_ACCELERATION = 2.5
+const NOTCH_ACCELERATION_WINDOW_MS = 50
+const MAX_NOTCH_PAN = 120
+const MAX_NOTCH_ZOOM = 40
+
+/**
+ * Chromium encodes a pinch as Ctrl+wheel with deltaY = -100 ln(scale), while WebKit reports the
+ * gesture's scale. Raising the scale to this power zooms a WebKit pinch as far as the same pinch
+ * zooms in Chromium.
+ */
+export const PINCH_SCALE_EXPONENT = 100 * PINCH_ZOOM_PER_DELTA
+
type WheelAccum = {
deltaX: number
deltaY: number
@@ -21,10 +53,19 @@ type WheelAccum = {
type WheelPanInput = Pick<WheelEvent, 'deltaX' | 'deltaY' | 'deltaMode' | 'shiftKey'>
type WheelModifierInput = Pick<WheelEvent, 'ctrlKey' | 'metaKey'>
+/** The wheel event fields navigation reads; `wheelDeltaX/Y` are Chromium's legacy notch fields. */
+export type WheelInput = WheelPanInput &
+ WheelModifierInput &
+ Pick<WheelEvent, 'timeStamp'> & { wheelDeltaX?: number; wheelDeltaY?: number }
+
export type WheelPanDelta = { dx: number; dy: number }
+export type WheelPlatform = 'mac' | 'windows' | 'other'
+export type WheelStep = { kind: 'pan'; dx: number; dy: number } | { kind: 'zoom'; scale: number }
-function isMacOs() {
- return typeof navigator !== 'undefined' && /Mac|iPhone|iPad|iPod/.test(navigator.platform)
+export function currentWheelPlatform(): WheelPlatform {
+ if (typeof navigator === 'undefined') return 'other'
+ if (/Mac|iPhone|iPad|iPod/.test(navigator.platform)) return 'mac'
+ return /Win/.test(navigator.platform) ? 'windows' : 'other'
}
function normalizedWheelDelta(event: WheelPanInput): WheelPanDelta {
@@ -43,25 +84,84 @@ export function isWheelZoom(event: WheelModifierInput): boolean {
return event.ctrlKey || event.metaKey
}
-export function wheelPanDelta(event: WheelPanInput): WheelPanDelta {
- const delta = normalizedWheelDelta(event)
- if (!event.shiftKey || Math.abs(delta.dx) >= Math.abs(delta.dy)) return delta
+function shiftToHorizontal(delta: WheelPanDelta, shiftKey: boolean): WheelPanDelta {
+ if (!shiftKey || Math.abs(delta.dx) >= Math.abs(delta.dy)) return delta
return { dx: delta.dy, dy: 0 }
}
-const WHEEL_ZOOM_SPEED = 1.25
-const NAVIGATION_SETTLE_DELAY_MS = 120
+export function wheelPanDelta(event: WheelPanInput): WheelPanDelta {
+ return shiftToHorizontal(normalizedWheelDelta(event), event.shiftKey)
+}
-function wheelDeltaModeScale(event: WheelEvent) {
- if (event.deltaMode === 1) return 0.05
- return event.deltaMode ? 1 : 0.002
+function capLength(delta: WheelPanDelta, max: number): WheelPanDelta {
+ const length = Math.hypot(delta.dx, delta.dy)
+ if (length <= max) return delta
+ return { dx: (delta.dx * max) / length, dy: (delta.dy * max) / length }
}
-function wheelZoomDelta(event: WheelEvent) {
- const factor = event.ctrlKey && isMacOs() ? 10 : 1
- return -event.deltaY * wheelDeltaModeScale(event) * factor * WHEEL_ZOOM_SPEED
+/** Whole wheel notches in deltaY's direction, when this Windows event is a mouse wheel notch. */
+function windowsNotches(event: WheelInput): WheelPanDelta | null {
+ if (!Number.isInteger(event.deltaX) || !Number.isInteger(event.deltaY)) return null
+ const notches =
+ event.wheelDeltaX !== undefined && event.wheelDeltaY !== undefined
+ ? { dx: -event.wheelDeltaX, dy: -event.wheelDeltaY }
+ : normalizedWheelDelta(event)
+ if (Math.abs(notches.dx) < MIN_WHEEL_NOTCH && Math.abs(notches.dy) < MIN_WHEEL_NOTCH) return null
+ return { dx: notches.dx / WHEEL_NOTCH, dy: notches.dy / WHEEL_NOTCH }
}
+function zoomStep(delta: number, perDelta: number): WheelStep {
+ const exponent = Math.max(-MAX_ZOOM_STEP, Math.min(MAX_ZOOM_STEP, -delta * perDelta))
+ return { kind: 'zoom', scale: Math.exp(exponent) }
+}
+
+/**
+ * Turns wheel events into pan and zoom steps. It keeps the last Windows notch so a fast spin
+ * accelerates, so each canvas uses its own.
+ */
+export function createWheelSteps(platform: WheelPlatform = currentWheelPlatform()) {
+ let lastNotch = { time: Number.NEGATIVE_INFINITY, signX: 0, signY: 0, step: 0 }
+
+ function notchStep(event: WheelInput, notches: WheelPanDelta, zoom: boolean): WheelPanDelta {
+ const time = event.timeStamp
+ const signX = Math.sign(notches.dx)
+ const signY = Math.sign(notches.dy)
+ const accelerates =
+ time - lastNotch.time < NOTCH_ACCELERATION_WINDOW_MS &&
+ signX === lastNotch.signX &&
+ signY === lastNotch.signY
+ // The step stops growing at the largest movement, so a long fast spin cannot overflow it.
+ const step = accelerates
+ ? Math.min(lastNotch.step * NOTCH_ACCELERATION, MAX_NOTCH_PAN)
+ : NOTCH_STEP
+ lastNotch = { time, signX, signY, step }
+ return capLength(
+ { dx: notches.dx * step, dy: notches.dy * step },
+ zoom ? MAX_NOTCH_ZOOM : MAX_NOTCH_PAN
+ )
+ }
+
+ return function wheelStep(event: WheelInput): WheelStep {
+ const zoom = isWheelZoom(event)
+ const notches = platform === 'windows' ? windowsNotches(event) : null
+ const delta = notches ? notchStep(event, notches, zoom) : normalizedWheelDelta(event)
+
+ if (zoom) {
+ const perDelta = event.ctrlKey && !notches ? PINCH_ZOOM_PER_DELTA : WHEEL_ZOOM_PER_DELTA
+ return zoomStep(delta.dy, perDelta)
+ }
+
+ const pan = shiftToHorizontal(delta, event.shiftKey)
+ const { dx, dy } = capLength(
+ { dx: pan.dx * PAN_SCALE, dy: pan.dy * PAN_SCALE },
+ MAX_PAN_PER_EVENT
+ )
+ return { kind: 'pan', dx, dy }
+ }
+}
+
+const NAVIGATION_SETTLE_DELAY_MS = 120
+
export function setupWheelPanZoom(canvasRef: Ref<HTMLCanvasElement | null>, editor: Editor) {
const wheelAccum: WheelAccum = {
deltaX: 0,
@@ -72,6 +172,7 @@ export function setupWheelPanZoom(canvasRef: Ref<HTMLCanvasElement | null>, edit
hasZoom: false
}
+ const wheelStep = createWheelSteps()
let settleTimer: ReturnType<typeof setTimeout> | null = null
function scheduleSettle() {
@@ -126,18 +227,18 @@ export function setupWheelPanZoom(canvasRef: Ref<HTMLCanvasElement | null>, edit
trusted: event.isTrusted
})
- editor.setNavigationPhase(isWheelZoom(event) ? 'zoom' : 'pan', performance.now())
+ const step = wheelStep(event)
+ editor.setNavigationPhase(step.kind, performance.now())
- if (isWheelZoom(event)) {
+ if (step.kind === 'zoom') {
const rect = canvas.getBoundingClientRect()
wheelAccum.zoomCenterX = event.clientX - rect.left
wheelAccum.zoomCenterY = event.clientY - rect.top
- wheelAccum.zoomScale *= 2 ** wheelZoomDelta(event)
+ wheelAccum.zoomScale *= step.scale
wheelAccum.hasZoom = true
} else {
- const { dx, dy } = wheelPanDelta(event)
- wheelAccum.deltaX -= dx
- wheelAccum.deltaY -= dy
+ wheelAccum.deltaX -= step.dx
+ wheelAccum.deltaY -= step.dy
}
wheelScheduler.schedule()
}
diff --git a/tests/engine/vue/shared/wheel.test.ts b/tests/engine/vue/shared/wheel.test.ts
index 3e6109591..e9c59b8eb 100644
--- a/tests/engine/vue/shared/wheel.test.ts
+++ b/tests/engine/vue/shared/wheel.test.ts
@@ -1,6 +1,13 @@
import { describe, expect, test } from 'bun:test'
-import { isWheelZoom, wheelPanDelta } from '#vue/shared/input/wheel'
+import {
+ createWheelSteps,
+ isWheelZoom,
+ PINCH_SCALE_EXPONENT,
+ wheelPanDelta,
+ type WheelInput,
+ type WheelStep
+} from '#vue/shared/input/wheel'
function wheelInput(
deltaX: number,
@@ -45,3 +52,94 @@ describe('wheel navigation', () => {
expect(isWheelZoom({ ctrlKey: false, metaKey: false })).toBeFalse()
})
})
+
+function event(deltaY: number, options: Partial<WheelInput> = {}): WheelInput {
+ return {
+ deltaX: 0,
+ deltaY,
+ deltaMode: 0,
+ shiftKey: false,
+ ctrlKey: false,
+ metaKey: false,
+ timeStamp: 0,
+ ...options
+ }
+}
+
+function notch(timeStamp: number, options: Partial<WheelInput> = {}): WheelInput {
+ return event(100, { wheelDeltaX: 0, wheelDeltaY: -120, timeStamp, ...options })
+}
+
+function panY(step: WheelStep): number {
+ if (step.kind !== 'pan') throw new Error(`expected a pan, got ${step.kind}`)
+ return step.dy
+}
+
+function zoomScale(step: WheelStep): number {
+ if (step.kind !== 'zoom') throw new Error(`expected a zoom, got ${step.kind}`)
+ return step.scale
+}
+
+describe('wheel steps', () => {
+ test('pans twice the touchpad delta, at most 120 px along the movement', () => {
+ const step = createWheelSteps('mac')
+ expect(step(event(4))).toEqual({ kind: 'pan', dx: 0, dy: 8 })
+ expect(step(event(400))).toEqual({ kind: 'pan', dx: 0, dy: 120 })
+ const diagonal = step(event(100, { deltaX: 100 }))
+ if (diagonal.kind !== 'pan') throw new Error('expected a pan')
+ expect(diagonal.dx).toBeCloseTo(84.85, 2)
+ expect(diagonal.dy).toBeCloseTo(84.85, 2)
+ })
+
+ test('zooms a Ctrl+wheel pinch by 2^(-deltaY / 50) on every platform', () => {
+ expect(zoomScale(createWheelSteps('mac')(event(50, { ctrlKey: true })))).toBeCloseTo(0.5)
+ expect(zoomScale(createWheelSteps('windows')(event(-4.5, { ctrlKey: true })))).toBeCloseTo(
+ 2 ** (4.5 / 50)
+ )
+ })
+
+ test('zooms a Meta+wheel turn more gently and limits one event to 10x', () => {
+ const step = createWheelSteps('mac')
+ expect(zoomScale(step(event(10, { metaKey: true })))).toBeCloseTo(Math.exp(-0.05))
+ expect(zoomScale(step(event(1000, { ctrlKey: true })))).toBeCloseTo(0.1)
+ })
+
+ test('moves 16 px per Windows wheel notch and speeds up when notches come within 50 ms', () => {
+ const step = createWheelSteps('windows')
+ expect(panY(step(notch(0)))).toBe(16)
+ expect(panY(step(notch(30)))).toBe(40)
+ expect(panY(step(notch(60)))).toBe(100)
+ expect(panY(step(notch(90)))).toBe(120)
+ expect(panY(step(notch(200)))).toBe(16)
+ })
+
+ test('restarts the notch step when the direction changes', () => {
+ const step = createWheelSteps('windows')
+ expect(panY(step(notch(0)))).toBe(16)
+ expect(panY(step(notch(20, { deltaY: -100, wheelDeltaY: 120 })))).toBe(-16)
+ })
+
+ test('zooms a Ctrl+notch on Windows like a mouse wheel zoom', () => {
+ const step = createWheelSteps('windows')
+ expect(zoomScale(step(notch(0, { ctrlKey: true })))).toBeCloseTo(Math.exp(-0.04))
+ })
+
+ test('treats fractional Windows deltas and other platforms as touchpad movement', () => {
+ expect(panY(createWheelSteps('windows')(event(4.5, { wheelDeltaY: -120 })))).toBe(9)
+ expect(panY(createWheelSteps('mac')(notch(0)))).toBe(120)
+ })
+
+ test('keeps panning a bounded step through a long fast spin', () => {
+ const step = createWheelSteps('windows')
+ let last = 0
+ for (let index = 0; index < 1000; index++) last = panY(step(notch(index * 10)))
+ expect(last).toBe(120)
+ })
+
+ test('zooms a WebKit pinch as far as the same pinch zooms in Chromium', () => {
+ // Chromium reports a pinch that doubles the finger spread as Ctrl+wheel with -100 ln 2.
+ const chromium = zoomScale(createWheelSteps('mac')(event(-100 * Math.LN2, { ctrlKey: true })))
+ expect(chromium).toBeCloseTo(2.61, 2)
+ expect(2 ** PINCH_SCALE_EXPONENT).toBeCloseTo(chromium)
+ })
+})