feat(graph): add mousewheel factorByDelta for smooth trackpad zoom

[xianjianlf2]

Need

Fixes #1725 (and the trackpad half of #1090). On a Mac trackpad, pinch-to-zoom on the canvas is far too fast/jumpy.

Updating Reason

MouseWheel.onMouseWheel ignores the wheel-delta magnitude — it only looks at deltaY's sign and clamps every event to a fixed step (5% above 15% scale, with a hard floor of 1.05):

const delta = e.deltaY
if (delta < 0) {
  this.cumulatedFactor = Math.round(this.currentScale * factor * 20) / 20 / this.currentScale
  if (this.cumulatedFactor <= 1) this.cumulatedFactor = 1.05  // floored
}

A mouse wheel emits one event per notch, so a fixed 5% step feels right. But a trackpad pinch emits many small high-frequency wheel events, and each one applies a full step → the canvas rockets in/out. Lowering factor cannot fix it because values below 1.05 are floored.

This PR adds an opt-in factorByDelta option. When enabled, the zoom step is proportional to the wheel delta:

this.cumulatedFactor = factor ** (-d / 100)

A standard ~100px notch equals one factor multiplication (classic mouse-wheel feel preserved), while small trackpad deltas produce smooth, proportionally small steps. It consumes the per-frame accumulated delta that MouseWheelHandle already computes via requestAnimationFrame and passes to the callback but the handler previously discarded.

The default is false, so existing behavior is unchanged — the legacy quantized path is byte-for-byte identical.

Related Testing

Extended __tests__/graph/mousewheel.spec.ts with a factorByDelta suite:

• zoom step is proportional to the wheel delta (1.2 ** (-delta/100))
• a large delta zooms more than a small delta
• positive delta zooms out
• prefers the accumulated deltaY batched by MouseWheelHandle
• the quantized path is untouched when the option is disabled

All 12 tests pass; tsc --noEmit is clean; the change adds no new lint findings to src/graph/mousewheel.ts.

User Tips

New optional MouseWheelOptions.factorByDelta?: boolean (default false). Opt in for trackpad-friendly, proportional zooming:

new Graph({
  container,
  mousewheel: { enabled: true, factorByDelta: true },
})

Docs updated in site/docs/api/graph/mousewheel.{en,zh}.md.

[gemini-code-assist]

Code Review

This pull request introduces a new factorByDelta option to the mouse wheel zoom functionality, enabling smooth, trackpad-friendly zooming by scaling the zoom step proportionally to the wheel-delta magnitude. It also includes corresponding documentation updates and unit tests. The feedback suggests adding safety checks to ensure that the zoom factor calculation does not result in NaN or invalid values if the delta is non-finite or the factor is negative.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If deltaY and delta are both undefined or NaN (e.g., due to a custom or malformed event), or if factor is configured as a negative number, factor ** (-d / 100) will evaluate to NaN or an invalid value. This can propagate to targetScale and cause rendering errors or exceptions when calling this.graph.zoom(NaN).

To prevent this, we should ensure d is a finite number and factor is positive before performing the exponentiation.

Suggested change

	const d = deltaY != null ? deltaY : delta
	this.cumulatedFactor = factor ** (-d / 100)
	const d = deltaY != null ? deltaY : delta
	const f = factor > 0 ? factor : 1.2
	this.cumulatedFactor = Number.isFinite(d) ? f ** (-d / 100) : 1

[xianjianlf2]

Thanks for the review. Applied in d21661d: on a non-finite delta the step falls back to 1 (no zoom), and a non-positive factor falls back to the default 1.2, so a malformed event or a misconfigured factor can no longer reach zoom(NaN). This brings the new path to parity with the quantized path, which is NaN-safe by construction. Added two tests covering both cases (14 passing).