Skip to content

Build your personal knowledge base with Trilium Notes

fix(client): make a wheel notch reversible, taking the wheel off the library

Elian Doran7aab4ebd92df
diff --git a/apps/client/src/widgets/react/ImageViewer.spec.tsx b/apps/client/src/widgets/react/ImageViewer.spec.tsx
index c4e68ae047..f560d2ec03 100644
--- a/apps/client/src/widgets/react/ImageViewer.spec.tsx
+++ b/apps/client/src/widgets/react/ImageViewer.spec.tsx
@@ -110,7 +110,8 @@ describe("ImageViewer", () => {
expect(props.doubleClick).toEqual({ mode: "reset" });
// Numeric envelope is user-tunable — assert sane relationships, not exact values.
expect(props.maxScale).toBeGreaterThan(props.minScale);
- expect(props.wheel.step).toBeGreaterThan(0);
+ // The library cannot make a notch each way cancel, so useZoomPanWheel handles the wheel.
+ expect(props.wheel).toEqual({ disabled: true });
});
it("lets minScale and maxScale be overridden", () => {
diff --git a/apps/client/src/widgets/react/ImageViewer.tsx b/apps/client/src/widgets/react/ImageViewer.tsx
index d849ddfa3b..b18578bdbe 100644
--- a/apps/client/src/widgets/react/ImageViewer.tsx
+++ b/apps/client/src/widgets/react/ImageViewer.tsx
@@ -10,7 +10,7 @@ import ShortcutHintButton from "../shortcut_hints/shortcut_hint_button";
import ContentErrorMessage from "./ContentErrorMessage";
import { useContextualShortcutHints } from "./hooks";
import OverlayControlGroup, { ZoomControls } from "./OverlayControlGroup";
-import { useZoomPanPinch } from "./zoom_pan";
+import { useZoomPanPinch, useZoomPanWheel } from "./zoom_pan";
import { useZoomPanKeyboard, ZOOM_PAN_HINTS, ZOOM_PAN_VIEWPORT_CLASS } from "./zoom_pan_keyboard";
interface ImageViewerProps {
@@ -118,6 +118,7 @@ export default function ImageViewer({ src, imgClassName, alt = "", minScale = 0.
}, [ src ]);
useZoomPanKeyboard(zoom.ref, rootEl);
+ useZoomPanWheel(zoom.ref, rootEl);
useContextualShortcutHints(IMAGE_VIEWER_HINTS);
const wrapperClass = [
diff --git a/apps/client/src/widgets/react/zoom_pan.spec.ts b/apps/client/src/widgets/react/zoom_pan.spec.ts
index 4ef5937a4c..73ee87988f 100644
--- a/apps/client/src/widgets/react/zoom_pan.spec.ts
+++ b/apps/client/src/widgets/react/zoom_pan.spec.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
-import { wheelStep, zoomStep } from "./zoom_pan";
+import { clampPan, wheelTargetScale, zoomStep, zoomToPointPosition } from "./zoom_pan";
describe("zoomStep", () => {
it("is the increment react-zoom-pan-pinch needs for a ×1.2 step, at any scale", () => {
@@ -20,20 +20,72 @@ describe("zoomStep", () => {
});
});
-describe("wheelStep", () => {
- it("makes a notch the same tenth of the view at any scale", () => {
- // The library adds `step * |deltaY|` to the scale, so a notch is asserted where it lands.
- const notch = (scale: number, deltaY = 100) => scale + wheelStep(scale) * deltaY;
+describe("wheelTargetScale", () => {
+ // A wheel reports deltaY down the page for a notch out, and up the page for a notch in.
+ const OUT = 100;
+ const IN = -100;
- expect(notch(0.5)).toBeCloseTo(0.55);
- expect(notch(8)).toBeCloseTo(8.8);
+ it("makes a notch the same tenth of the view at any scale", () => {
+ expect(wheelTargetScale(0.5, IN)).toBeCloseTo(0.55);
+ expect(wheelTargetScale(8, IN)).toBeCloseTo(8.8);
- // The library's own default step would have put that first notch on 2.0 — a diagram fitted
- // at 50% jumping past 200% on one scroll.
+ // The library's own arithmetic would have put that first notch on 2.0 — a diagram fitted at
+ // 50% jumping past 200% on one scroll.
expect(0.5 + 0.015 * 100).toBe(2);
- expect(notch(0.5)).toBeLessThan(0.6);
+ });
+
+ it("returns to where it started when a notch is taken back", () => {
+ // The library cannot do this: it adds or subtracts one step, so a notch each way leaves the
+ // content at 1 - k² of where it was and scrubbing walks the view steadily smaller.
+ expect(wheelTargetScale(wheelTargetScale(1, IN), OUT)).toBeCloseTo(1);
+
+ let scale = 1;
+ for (let i = 0; i < 20; i++) scale = wheelTargetScale(wheelTargetScale(scale, IN), OUT);
+ expect(scale).toBeCloseTo(1);
+ });
+
+ it("moves the scale by the fraction of a notch a trackpad reports", () => {
+ expect(wheelTargetScale(1, IN / 10)).toBeCloseTo(1.1 ** 0.1);
+ // Ten of those fractions make exactly the one notch they are a tenth of.
+ let scale = 1;
+ for (let i = 0; i < 10; i++) scale = wheelTargetScale(scale, IN / 10);
+ expect(scale).toBeCloseTo(1.1);
+ });
+});
+
+describe("clampPan", () => {
+ const bounds = { minPositionX: -100, maxPositionX: 0, minPositionY: -50, maxPositionY: 0 };
+
+ it("leaves an in-bounds position unchanged", () => {
+ expect(clampPan(-40, -20, bounds)).toEqual({ x: -40, y: -20 });
+ });
+
+ it("clamps a position past either edge", () => {
+ expect(clampPan(20, 20, bounds)).toEqual({ x: 0, y: 0 });
+ expect(clampPan(-200, -200, bounds)).toEqual({ x: -100, y: -50 });
+ });
+});
+
+describe("zoomToPointPosition", () => {
+ it("leaves the position unchanged when the cursor sits on the content origin", () => {
+ // Cursor at (posX0, posY0) → content point 0, so scaling moves nothing.
+ expect(zoomToPointPosition(1, 50, 50, 3, 50, 50)).toEqual({ x: 50, y: 50 });
+ });
+
+ it("shifts the position so the cursor's content point stays under the cursor when zooming in", () => {
+ // scale 1→2 at cursor (100,100) over origin: content point 100 must stay put → pos = 100 - 100*2.
+ expect(zoomToPointPosition(1, 0, 0, 2, 100, 100)).toEqual({ x: -100, y: -100 });
+ });
+
+ it("shifts the other way when zooming out, from a non-zero starting transform", () => {
+ // content point = (120-20)/2 = 50; new pos = 120 - 50*1 = 70 (x), (90-(-10))/2=50 → 90-50=40 (y).
+ expect(zoomToPointPosition(2, 20, -10, 1, 120, 90)).toEqual({ x: 70, y: 40 });
+ });
- // A trackpad reports a fraction of a notch, and moves the view by that same fraction.
- expect(notch(1, 10)).toBeCloseTo(1.01);
+ it("keeps the cursor's content point invariant across the scale change", () => {
+ const [ scale0, posX0, posY0, scale1, cursorX, cursorY ] = [ 1.5, 12, -8, 4.2, 230, 70 ];
+ const { x, y } = zoomToPointPosition(scale0, posX0, posY0, scale1, cursorX, cursorY);
+ expect((cursorX - x) / scale1).toBeCloseTo((cursorX - posX0) / scale0);
+ expect((cursorY - y) / scale1).toBeCloseTo((cursorY - posY0) / scale0);
});
});
diff --git a/apps/client/src/widgets/react/zoom_pan.ts b/apps/client/src/widgets/react/zoom_pan.ts
index 6b1d2f0f30..2889b8fe03 100644
--- a/apps/client/src/widgets/react/zoom_pan.ts
+++ b/apps/client/src/widgets/react/zoom_pan.ts
@@ -17,7 +17,8 @@ interface ZoomPanPinchOptions {
* whether either step has room left, and the three things a set of zoom controls does to it.
*
* `onTransform` goes on the wrapper, so the scale here follows every change — a button, the wheel,
- * a pinch, a double click.
+ * a pinch, a double click. `wheel` turns the library's own wheel handler off in favour of
+ * {@link useZoomPanWheel}.
*/
export function useZoomPanPinch({ minScale, maxScale, resetOn, onScaleChange }: ZoomPanPinchOptions) {
const ref = useRef<ReactZoomPanPinchRef>(null);
@@ -38,7 +39,7 @@ export function useZoomPanPinch({ minScale, maxScale, resetOn, onScaleChange }:
ref,
scale,
onTransform,
- wheel: { step: wheelStep(scale) },
+ wheel: { disabled: true },
canZoomIn: scale < maxScale * (1 - ZOOM_LIMIT_TOLERANCE),
canZoomOut: scale > minScale * (1 + ZOOM_LIMIT_TOLERANCE),
zoomIn: () => ref.current?.zoomIn(zoomStep(currentScale(ref), "in")),
@@ -47,6 +48,53 @@ export function useZoomPanPinch({ minScale, maxScale, resetOn, onScaleChange }:
};
}
+/**
+ * Zooms the content on a wheel notch, anchored on the pointer, in place of the library's own wheel
+ * handler.
+ *
+ * That handler adds `step * |deltaY|` to the current scale (`handleWheelZoom`), and one step cannot
+ * be both the `scale * (k - 1)` a notch in needs and the `scale * (1 - 1 / k)` a notch back needs.
+ * A notch each way therefore leaves the content at `1 - k²` of where it started, so scrubbing the
+ * wheel walks the view steadily smaller. Reading the direction off the event — which the library
+ * cannot do before it has picked the step — and asking for a target scale removes that.
+ *
+ * `zoomIn`/`zoomOut` take the increment from the current scale to that target so that the library
+ * clamps it to `minScale`/`maxScale` and recomputes its bounds; the transform that follows puts the
+ * content back under the pointer, the library having zoomed toward the middle of the view.
+ */
+export function useZoomPanWheel(apiRef: RefObject<ReactZoomPanPinchRef>, element: HTMLElement | null) {
+ useEffect(() => {
+ if (!element) return;
+
+ const onWheel = (event: WheelEvent) => {
+ const api = apiRef.current;
+ // A purely horizontal wheel carries no zoom, and is left to whatever else wants it.
+ if (!api || event.deltaY === 0) return;
+ event.preventDefault();
+
+ const { scale, positionX, positionY } = api.instance.state;
+ const target = wheelTargetScale(scale, event.deltaY);
+ if (target > scale) api.zoomIn(target - scale, 0);
+ else api.zoomOut(scale - target, 0);
+
+ const rect = api.instance.wrapperComponent?.getBoundingClientRect();
+ if (!rect) return;
+
+ const zoomed = api.instance.state.scale;
+ const anchored = zoomToPointPosition(
+ scale, positionX, positionY, zoomed,
+ event.clientX - rect.left, event.clientY - rect.top
+ );
+ const bounds = api.instance.bounds;
+ const { x, y } = bounds ? clampPan(anchored.x, anchored.y, bounds) : anchored;
+ api.setTransform(x, y, zoomed, 0);
+ };
+
+ element.addEventListener("wheel", onWheel, { passive: false });
+ return () => element.removeEventListener("wheel", onWheel);
+ }, [ apiRef, element ]);
+}
+
/** What one press of a zoom step multiplies the scale by. */
const ZOOM_STEP = 1.2;
/**
@@ -76,19 +124,34 @@ export function zoomStep(scale: number, direction: "in" | "out") {
}
/**
- * The `wheel.step` that makes a notch a {@link WHEEL_STEP}, at the scale the content is drawn at.
- *
- * react-zoom-pan-pinch adds `step * |deltaY|` to the current scale (see `handleWheelZoom`), so its
- * own default of 0.015 is a flat +1.5 a notch: from a diagram fitted at 0.5 one notch reaches 2.0,
- * while at 8 the same notch is barely a twelfth of what is on screen. Scaling the step by the scale
- * it applies to keeps a notch the same fraction of the view wherever it is taken from.
- *
- * The scale is the one last reported through `onTransform`, so a scroll fast enough to outrun a
- * render takes a notch or two sized for where it just was. The error is a fraction of one notch and
- * corrects itself on the next.
+ * The scale a wheel notch takes `scale` to, multiplying or dividing by {@link WHEEL_STEP} so that a
+ * notch each way returns to where it started. A trackpad reports a fraction of a notch and moves the
+ * scale by that same fraction of the step.
+ */
+export function wheelTargetScale(scale: number, deltaY: number) {
+ const factor = WHEEL_STEP ** (Math.abs(deltaY) / WHEEL_NOTCH_DELTA);
+ return deltaY < 0 ? scale * factor : scale / factor;
+}
+
+interface PanBounds { minPositionX: number; maxPositionX: number; minPositionY: number; maxPositionY: number; }
+
+/** Clamps a candidate content position to the library's computed pan bounds. */
+export function clampPan(x: number, y: number, bounds: PanBounds): { x: number; y: number } {
+ return {
+ x: Math.min(Math.max(x, bounds.minPositionX), bounds.maxPositionX),
+ y: Math.min(Math.max(y, bounds.minPositionY), bounds.maxPositionY)
+ };
+}
+
+/**
+ * The content translation that keeps a viewport point fixed across a scale change — i.e. a zoom
+ * anchored on (`cursorX`, `cursorY`) (wrapper-local pixels) rather than the viewport centre.
+ * `scale0`/`posX0`/`posY0` describe the transform before zooming to `scale1`.
*/
-export function wheelStep(scale: number) {
- return (scale * (WHEEL_STEP - 1)) / WHEEL_NOTCH_DELTA;
+export function zoomToPointPosition(scale0: number, posX0: number, posY0: number, scale1: number, cursorX: number, cursorY: number): { x: number; y: number } {
+ const contentX = (cursorX - posX0) / scale0;
+ const contentY = (cursorY - posY0) / scale0;
+ return { x: cursorX - contentX * scale1, y: cursorY - contentY * scale1 };
}
/** The scale the instance is at now, read as a button is pressed rather than when it was drawn. */
diff --git a/apps/client/src/widgets/react/zoom_pan_keyboard.spec.ts b/apps/client/src/widgets/react/zoom_pan_keyboard.spec.ts
index b4e5fddfe3..dff8030733 100644
--- a/apps/client/src/widgets/react/zoom_pan_keyboard.spec.ts
+++ b/apps/client/src/widgets/react/zoom_pan_keyboard.spec.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
-import { claimsKeystroke, clampPan, codeToControl, getPanDelta, zoomToPointPosition } from "./zoom_pan_keyboard";
+import { claimsKeystroke, codeToControl, getPanDelta } from "./zoom_pan_keyboard";
describe("codeToControl", () => {
it("maps zoom/reset keys (Equal/Minus/Slash, numpad, Q/E) regardless of modifiers", () => {
@@ -80,40 +80,3 @@ describe("getPanDelta", () => {
expect(fast).toBeGreaterThan(normal);
});
});
-
-describe("clampPan", () => {
- const bounds = { minPositionX: -100, maxPositionX: 0, minPositionY: -50, maxPositionY: 0 };
-
- it("leaves an in-bounds position unchanged", () => {
- expect(clampPan(-40, -20, bounds)).toEqual({ x: -40, y: -20 });
- });
-
- it("clamps a position past either edge", () => {
- expect(clampPan(20, 20, bounds)).toEqual({ x: 0, y: 0 });
- expect(clampPan(-200, -200, bounds)).toEqual({ x: -100, y: -50 });
- });
-});
-
-describe("zoomToPointPosition", () => {
- it("leaves the position unchanged when the cursor sits on the content origin", () => {
- // Cursor at (posX0, posY0) → content point 0, so scaling moves nothing.
- expect(zoomToPointPosition(1, 50, 50, 3, 50, 50)).toEqual({ x: 50, y: 50 });
- });
-
- it("shifts the position so the cursor's content point stays under the cursor when zooming in", () => {
- // scale 1→2 at cursor (100,100) over origin: content point 100 must stay put → pos = 100 - 100*2.
- expect(zoomToPointPosition(1, 0, 0, 2, 100, 100)).toEqual({ x: -100, y: -100 });
- });
-
- it("shifts the other way when zooming out, from a non-zero starting transform", () => {
- // content point = (120-20)/2 = 50; new pos = 120 - 50*1 = 70 (x), (90-(-10))/2=50 → 90-50=40 (y).
- expect(zoomToPointPosition(2, 20, -10, 1, 120, 90)).toEqual({ x: 70, y: 40 });
- });
-
- it("keeps the cursor's content point invariant across the scale change", () => {
- const [ scale0, posX0, posY0, scale1, cursorX, cursorY ] = [ 1.5, 12, -8, 4.2, 230, 70 ];
- const { x, y } = zoomToPointPosition(scale0, posX0, posY0, scale1, cursorX, cursorY);
- expect((cursorX - x) / scale1).toBeCloseTo((cursorX - posX0) / scale0);
- expect((cursorY - y) / scale1).toBeCloseTo((cursorY - posY0) / scale0);
- });
-});
diff --git a/apps/client/src/widgets/react/zoom_pan_keyboard.ts b/apps/client/src/widgets/react/zoom_pan_keyboard.ts
index 106362a2f2..44d71e0224 100644
--- a/apps/client/src/widgets/react/zoom_pan_keyboard.ts
+++ b/apps/client/src/widgets/react/zoom_pan_keyboard.ts
@@ -5,6 +5,7 @@ import type { ReactZoomPanPinchRef } from "react-zoom-pan-pinch";
import type { ShortcutHintDefinition } from "../../services/shortcut_hints";
import { isAppShortcutChord } from "../../services/shortcuts";
+import { clampPan, zoomToPointPosition } from "./zoom_pan";
export type ZoomPanControl =
| "zoomIn" | "zoomOut" | "reset"
@@ -99,27 +100,6 @@ export function getPanDelta(controls: Iterable<ZoomPanControl>, shiftKey: boolea
return { dx, dy };
}
-interface PanBounds { minPositionX: number; maxPositionX: number; minPositionY: number; maxPositionY: number; }
-
-/** Clamps a candidate content position to the library's computed pan bounds. */
-export function clampPan(x: number, y: number, bounds: PanBounds): { x: number; y: number } {
- return {
- x: Math.min(Math.max(x, bounds.minPositionX), bounds.maxPositionX),
- y: Math.min(Math.max(y, bounds.minPositionY), bounds.maxPositionY)
- };
-}
-
-/**
- * The content translation that keeps a viewport point fixed across a scale change — i.e. a zoom
- * anchored on (`cursorX`, `cursorY`) (wrapper-local pixels) rather than the viewport centre.
- * `scale0`/`posX0`/`posY0` describe the transform before zooming to `scale1`.
- */
-export function zoomToPointPosition(scale0: number, posX0: number, posY0: number, scale1: number, cursorX: number, cursorY: number): { x: number; y: number } {
- const contentX = (cursorX - posX0) / scale0;
- const contentY = (cursorY - posY0) / scale0;
- return { x: cursorX - contentX * scale1, y: cursorY - contentY * scale1 };
-}
-
/**
* Wires keyboard zoom (`+`/`-`/`/`, with or without Ctrl/Cmd) and pan (arrows / WASD, Shift to speed
* up) onto the focusable `element`, driving the react-zoom-pan-pinch instance in `apiRef`. While
diff --git a/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.tsx b/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.tsx
index b2a6685848..706cc4cee4 100644
--- a/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.tsx
+++ b/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.tsx
@@ -8,7 +8,7 @@ import utils, { isMobile } from "../../../services/utils";
import { useContextualShortcutHints, useEffectiveReadOnly, useNoteLabel, useTriliumEvent } from "../../react/hooks";
import OverlayControlGroup, { ZoomControls } from "../../react/OverlayControlGroup";
import { RawHtmlBlock } from "../../react/RawHtml";
-import { useZoomPanPinch } from "../../react/zoom_pan";
+import { useZoomPanPinch, useZoomPanWheel } from "../../react/zoom_pan";
import { useZoomPanKeyboard, ZOOM_PAN_HINTS, ZOOM_PAN_VIEWPORT_CLASS } from "../../react/zoom_pan_keyboard";
import { ShortcutHintOverlayButton } from "../../shortcut_hints/shortcut_hint_button";
import SplitEditor, { SplitEditorProps } from "./SplitEditor";
@@ -53,6 +53,7 @@ export default function SvgSplitEditor({ ntxId, note, attachmentTitle, renderSvg
const readOnly = useEffectiveReadOnly(note, props.noteContext);
const mode = resolveDisplayMode(displayMode, readOnly);
useZoomPanKeyboard(zoom.ref, previewEl);
+ useZoomPanWheel(zoom.ref, previewEl);
useContextualShortcutHints(mode !== "source" ? ZOOM_PAN_HINTS : []);
// Reset the render state when switching notes so a previous note's render (and the