Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import "./zoom_pan.css";
import { useEffect } from "preact/hooks";
import type { ReactZoomPanPinchRef } from "react-zoom-pan-pinch";
import type { ShortcutHintDefinition } from "../../services/shortcut_hints";
import { isAppShortcutChord } from "../../services/shortcuts";
import { clampPan, panBounds, zoomToPointPosition } from "./zoom_pan";
export type ZoomPanControl =
| "zoomIn" | "zoomOut" | "reset"
| "panUp" | "panDown" | "panLeft" | "panRight";
/** Draws the focus ring in zoom_pan.css. Put it on whichever element the caller gives `tabIndex`. */
export const ZOOM_PAN_VIEWPORT_CLASS = "tn-zoom-pan-viewport";
/**
* Shortcut hints for the keys {@link codeToControl} maps. A caller with more shortcuts spreads this
* and appends its own sections, as `ImageViewer` does for image navigation.
*/
export const ZOOM_PAN_HINTS: ShortcutHintDefinition = [
{
titleKey: "zoom_controls.hints.zoom",
hints: [
{ keys: ["Ctrl++", "E"], labelKey: "zoom_controls.hints.zoom_in" },
{ keys: ["Ctrl+-", "Q"], labelKey: "zoom_controls.hints.zoom_out" },
{ keys: ["/", "Numpad /"], labelKey: "zoom_controls.hints.reset_zoom" }
]
},
{
titleKey: "zoom_controls.hints.pan",
hints: [
{ keys: ["Up", "W"], labelKey: "zoom_controls.hints.pan_up" },
{ keys: ["Down", "S"], labelKey: "zoom_controls.hints.pan_down" },
{ keys: ["Left", "A"], labelKey: "zoom_controls.hints.pan_left" },
{ keys: ["Right", "D"], labelKey: "zoom_controls.hints.pan_right" },
{ keys: ["Shift"], labelKey: "zoom_controls.hints.pan_fast" }
]
}
];
/** Continuous keyboard zoom rate, as a per-second exponent fed to the library's zoomIn/zoomOut. */
const ZOOM_RATE = 2.5;
/** Continuous keyboard pan speed, in CSS pixels per second. */
const PAN_SPEED = 1200;
/** Pan speed multiplier while Shift is held. */
const PAN_FAST_FACTOR = 2.5;
/**
* The keys the browser and the OS zoom with, which the viewer claims even with Ctrl/Cmd held: while an
* image is focused, Ctrl+= should zoom the image rather than the whole UI. Their letter aliases (E/Q) are
* deliberately absent — Ctrl+E and Ctrl+Q belong to the application (Ctrl+Q quits, on Linux).
*/
const ZOOM_GESTURE_CODES = new Set([ "Equal", "Minus", "NumpadAdd", "NumpadSubtract" ]);
/**
* Whether the viewer acts on this keystroke, or leaves it to Trilium's own shortcuts. Bare keys (and
* Shift, which pans faster) are the viewer's; a chord is the application's — otherwise Ctrl+W would pan up
* instead of closing the tab, since the viewer stops the event from ever reaching the global handler.
*/
export function claimsKeystroke(e: { code: string; ctrlKey: boolean; metaKey: boolean; altKey: boolean }): boolean {
return !isAppShortcutChord(e) || ZOOM_GESTURE_CODES.has(e.code);
}
/**
* Maps a physical key (`KeyboardEvent.code`) to a viewer control, independent of modifiers — whether the
* viewer may act on a modified one is {@link claimsKeystroke}'s call. Using `code` keeps it
* keyboard-layout independent.
*/
export function codeToControl(code: string): ZoomPanControl | null {
switch (code) {
case "Equal": case "NumpadAdd": case "KeyE": return "zoomIn";
case "Minus": case "NumpadSubtract": case "KeyQ": return "zoomOut";
case "Slash": case "NumpadDivide": return "reset";
case "ArrowUp": case "KeyW": return "panUp";
case "ArrowDown": case "KeyS": return "panDown";
case "ArrowLeft": case "KeyA": return "panLeft";
case "ArrowRight": case "KeyD": return "panRight";
default: return null;
}
}
/**
* Pan delta (in content-translation pixels) for the held direction controls. An arrow/WASD key
* moves the *view* that way (Right reveals the right side), so the content translates the opposite
* way. Scaled by elapsed time, so the speed is frame-rate independent; Shift speeds it up.
*/
export function getPanDelta(controls: Iterable<ZoomPanControl>, shiftKey: boolean, dtSeconds: number): { dx: number; dy: number } {
const held = controls instanceof Set ? controls : new Set(controls);
const speed = PAN_SPEED * (shiftKey ? PAN_FAST_FACTOR : 1) * dtSeconds;
let dx = 0;
let dy = 0;
if (held.has("panLeft")) dx += speed;
if (held.has("panRight")) dx -= speed;
if (held.has("panUp")) dy += speed;
if (held.has("panDown")) dy -= speed;
return { dx, dy };
}
/**
* 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
* keys are held it runs a requestAnimationFrame loop that reuses the library's own
* `zoomIn`/`zoomOut`/`setTransform`, so the motion is smooth and stays within the library's bounds.
* Only active while `element` has focus, which a press on it gives; clicking an adjacent editor
* takes focus back, as with any other pane.
*
* Takes the element rather than a ref so the effect re-runs when a viewport mounts after the hook,
* as the preview pane does when a display-mode switch adds it.
*/
export function useZoomPanKeyboard(
apiRef: { current: ReactZoomPanPinchRef | null },
element: HTMLElement | null
) {
useEffect(() => {
if (!element) return;
const heldCodes = new Set<string>();
let shift = false;
let rafId = 0;
let lastTime = 0;
const stop = () => {
if (rafId) cancelAnimationFrame(rafId);
rafId = 0;
lastTime = 0;
};
const activeControls = () => {
const controls: ZoomPanControl[] = [];
for (const code of heldCodes) {
const control = codeToControl(code);
if (control && control !== "reset") controls.push(control);
}
return controls;
};
const tick = (time: number) => {
const dt = lastTime ? Math.min((time - lastTime) / 1000, 0.05) : 0;
lastTime = time;
const api = apiRef.current;
const controls = activeControls();
if (api && dt > 0 && controls.length) {
if (controls.includes("zoomIn") || controls.includes("zoomOut")) {
const { scale, positionX, positionY } = api.instance.state;
if (controls.includes("zoomIn")) api.zoomIn(ZOOM_RATE * dt, 0);
if (controls.includes("zoomOut")) api.zoomOut(ZOOM_RATE * dt, 0);
anchorZoomToCursor(api, scale, positionX, positionY);
}
const { dx, dy } = getPanDelta(controls, shift, dt);
if (dx || dy) {
const { scale, positionX, positionY } = api.instance.state;
const bounds = panBounds(api);
// A bounded instance has no bounds until its first layout.
if (bounds || !api.instance.setup.limitToBounds) {
const next = bounds
? clampPan(positionX + dx, positionY + dy, bounds)
: { x: positionX + dx, y: positionY + dy };
api.setTransform(next.x, next.y, scale, 0);
// Keyboard panning shifts the image under a held mouse cursor; re-anchor the
// drag so the new point under the cursor becomes its grab point.
reanchorPan(api, positionX, positionY);
}
}
}
if (controls.length) rafId = requestAnimationFrame(tick);
else stop();
};
const start = () => {
if (!rafId) rafId = requestAnimationFrame(tick);
};
const onKeyDown = (e: KeyboardEvent) => {
shift = e.shiftKey;
const control = codeToControl(e.code);
if (!control || !claimsKeystroke(e)) return;
// Claim the key so the browser (Ctrl +/-) and Trilium's global shortcuts
// (arrow tree navigation, app zoom, quick search) don't also act on it.
e.preventDefault();
e.stopPropagation();
if (control === "reset") {
apiRef.current?.resetTransform();
return;
}
heldCodes.add(e.code);
start();
};
const onKeyUp = (e: KeyboardEvent) => {
shift = e.shiftKey;
heldCodes.delete(e.code);
};
const onBlur = () => {
heldCodes.clear();
stop();
};
// Focus on pointer release (capture phase). The library calls preventDefault on mousedown
// for panning, which both stops propagation and reverts a focus set during the press — so we
// focus on the capture-phase pointerup, once the press has been fully handled.
const onPointerUp = () => element.focus();
element.addEventListener("keydown", onKeyDown);
element.addEventListener("keyup", onKeyUp);
element.addEventListener("blur", onBlur);
element.addEventListener("pointerup", onPointerUp, true);
return () => {
element.removeEventListener("keydown", onKeyDown);
element.removeEventListener("keyup", onKeyUp);
element.removeEventListener("blur", onBlur);
element.removeEventListener("pointerup", onPointerUp, true);
stop();
};
}, [ apiRef, element ]);
}
/**
* After a programmatic (keyboard) zoom, keeps a simultaneous mouse drag smooth and anchored on the
* cursor. Two things otherwise fight a drag+zoom: the library zooms toward the viewport centre, not
* the grabbed point; and it recomputes the pan position each mousemove from startCoords captured at
* press time, discarding the zoom's shift. So while panning we relocate the freshly-scaled view to
* keep the cursor's content-point fixed, then offset startCoords by that move so the drag carries on
* from there. The cursor is recovered from the pan's own invariant (clientX = positionX +
* startCoords.x), so no pointer tracking is needed. `scale0`/`posX0`/`posY0` are the transform before
* the zoom; the new scale is read live from the instance.
*/
function anchorZoomToCursor(api: ReactZoomPanPinchRef, scale0: number, posX0: number, posY0: number) {
const { startCoords, isPanning, state, wrapperComponent } = api.instance;
if (!isPanning || !startCoords) return;
const rect = wrapperComponent?.getBoundingClientRect();
if (rect) {
const cursorX = posX0 + startCoords.x - rect.left;
const cursorY = posY0 + startCoords.y - rect.top;
const { x, y } = zoomToPointPosition(scale0, posX0, posY0, state.scale, cursorX, cursorY);
api.setTransform(x, y, state.scale, 0);
}
reanchorPan(api, posX0, posY0);
}
/**
* Keeps an in-progress mouse drag smooth after a programmatic transform. The library recomputes the
* pan position each mousemove from startCoords captured at press time, so without this the next move
* would discard the keyboard zoom/pan's shift (snapping back). Offsetting startCoords by the position
* change — from (`beforeX`, `beforeY`) to the live position — makes the drag continue from there.
*/
function reanchorPan(api: ReactZoomPanPinchRef, beforeX: number, beforeY: number) {
const { startCoords, isPanning, state } = api.instance;
if (!isPanning || !startCoords) return;
startCoords.x -= state.positionX - beforeX;
startCoords.y -= state.positionY - beforeY;
}