Skip to content

Build your personal knowledge base with Trilium Notes

docs(client): write the new zoom/pan comments in the house style

Elian Doran51ee02746beb
diff --git a/apps/client/src/widgets/react/ImageViewer.tsx b/apps/client/src/widgets/react/ImageViewer.tsx
index b18578bdbe..1964e06ade 100644
--- a/apps/client/src/widgets/react/ImageViewer.tsx
+++ b/apps/client/src/widgets/react/ImageViewer.tsx
@@ -27,7 +27,7 @@ const CRISP_NATIVE_SCALE = 4;
/** Reveal the image even if `decode()` never settles (it can stall for some images, e.g. SVGs). */
const REVEAL_FALLBACK_MS = 1000;
-// The zoom and pan keys are every viewport's; walking the images of a folder is this one's alone.
+// The zoom and pan keys are shared; only this viewer navigates between a folder's images.
const IMAGE_VIEWER_HINTS: ShortcutHintDefinition = [
...ZOOM_PAN_HINTS,
{
diff --git a/apps/client/src/widgets/react/OverlayControlGroup.spec.tsx b/apps/client/src/widgets/react/OverlayControlGroup.spec.tsx
index b5a0f49fae..c3db90eed0 100644
--- a/apps/client/src/widgets/react/OverlayControlGroup.spec.tsx
+++ b/apps/client/src/widgets/react/OverlayControlGroup.spec.tsx
@@ -335,7 +335,7 @@ describe("ZoomControls", () => {
const [ zoomOut, readout, zoomIn ] = container.querySelectorAll("button");
expect(zoomOut.disabled).toBe(true);
expect(zoomIn.disabled).toBe(true);
- // The way back is never refused: a bound is about the steps, not about the fitted view.
+ // A bound disables the steps, not the readout, which always resets to the fitted view.
expect(readout.disabled).toBe(false);
});
diff --git a/apps/client/src/widgets/react/OverlayControlGroup.tsx b/apps/client/src/widgets/react/OverlayControlGroup.tsx
index 739bd1d7f7..106a836fc2 100644
--- a/apps/client/src/widgets/react/OverlayControlGroup.tsx
+++ b/apps/client/src/widgets/react/OverlayControlGroup.tsx
@@ -177,26 +177,27 @@ export function OverlayFullscreenButton({ isFullscreen, onToggle }: OverlayFulls
interface ZoomControlsProps {
/**
- * The scale as a percentage of whatever the content's own hundred is — its native resolution,
- * its fitted view, its natural size. Left out, the two steps stand alone: a map's zoom level is a
- * number out of the cartographer's toolbox, not the reader's.
+ * The scale to show between the two steps, as a percentage. What 100% means is the caller's
+ * choice: native resolution in `ImageViewer`, the fitted view in `SvgSplitEditor`, natural size
+ * in the mind map. Omit it to render the two steps with no readout, as the geo map does — a
+ * MapLibre zoom level means nothing as a percentage.
*/
percent?: number;
- /** Whether either step has room left; a step that would do nothing is shown disabled. */
+ /** Disables the matching step. Pass `false` once the scale has reached a bound. */
canZoomIn?: boolean;
canZoomOut?: boolean;
onZoomIn: () => void;
onZoomOut: () => void;
- /** Only reached through the readout, so only needed where there is a `percent` to show. */
+ /** Runs when the readout is clicked, so it is only needed alongside `percent`. */
onReset?: () => void;
}
/**
- * The zoom steps every set of controls over content carries: out, the scale, and in.
+ * Renders the three zoom controls — out, the readout, in — for an {@link OverlayControlGroup} to
+ * hold.
*
- * Buttons rather than a group of their own, the image viewer and the diagram preview showing nothing
- * else while the maps stand them among a tilt, a recenter and a fullscreen. What a hundred percent
- * means is the content's to say, so the readout is handed a percentage rather than a scale.
+ * Buttons rather than a group of their own, because the geo map and mind map toolbars put them in
+ * one group beside a tilt, a recenter and a fullscreen button.
*/
export function ZoomControls({ percent, canZoomIn = true, canZoomOut = true, onZoomIn, onZoomOut, onReset }: ZoomControlsProps) {
return (
diff --git a/apps/client/src/widgets/react/zoom_pan.css b/apps/client/src/widgets/react/zoom_pan.css
index 16bcce259f..a389f845a9 100644
--- a/apps/client/src/widgets/react/zoom_pan.css
+++ b/apps/client/src/widgets/react/zoom_pan.css
@@ -1,8 +1,8 @@
-/* A viewport holding the keys is the pane the reader's input is going to, which is what the active
- split in a multi-split view already says about itself — the same accent, the same fade (see the
- `.note-split` rules in theme-next/shell.css). Drawn as an inset outline rather than that border,
- so it costs the content no room and leaves nothing to suppress the browser's own ring with.
- The fallback carries the legacy light and dark themes, which define no accent. */
+/* Marks the focused viewport the way `.note-split.active` marks the active split: same accent, same
+ 150ms fade (theme-next/shell.css). An inset outline rather than that rule's border — a border on a
+ viewport sized to 100% of its pane costs the content 4px, and declaring an outline here replaces
+ the browser's own focus ring without needing `outline: none`.
+ The fallback covers theme-light.css and theme-dark.css, which define no accent. */
.tn-zoom-pan-viewport {
outline: 2px solid transparent;
outline-offset: -2px;
diff --git a/apps/client/src/widgets/react/zoom_pan.ts b/apps/client/src/widgets/react/zoom_pan.ts
index 2889b8fe03..4472055d41 100644
--- a/apps/client/src/widgets/react/zoom_pan.ts
+++ b/apps/client/src/widgets/react/zoom_pan.ts
@@ -3,22 +3,21 @@ import { useCallback, useEffect, useRef, useState } from "preact/hooks";
import type { ReactZoomPanPinchRef } from "react-zoom-pan-pinch";
interface ZoomPanPinchOptions {
- /** The closest in and the furthest out the content can be taken, as the wrapper is given them. */
+ /** Passed through to `TransformWrapper`, and used here for `canZoomIn`/`canZoomOut`. */
minScale: number;
maxScale: number;
- /** Puts the scale back to 1 when this changes, for a wrapper that is remounted under the hook. */
+ /** Resets `scale` to 1 when this value changes, for a wrapper the caller remounts. */
resetOn?: unknown;
- /** Called with the scale on every change, for whatever else a caller derives from it. */
+ /** Called with the new scale after every transform, for values the caller derives from it. */
onScaleChange?: (scale: number) => void;
}
/**
- * Drives a react-zoom-pan-pinch instance: the ref to hand `TransformWrapper`, the scale it is at,
- * whether either step has room left, and the three things a set of zoom controls does to it.
+ * Drives a react-zoom-pan-pinch instance. Returns the ref for `TransformWrapper`, the current
+ * scale, whether each step has room left, and `zoomIn`/`zoomOut`/`reset`.
*
- * `onTransform` goes on the wrapper, so the scale here follows every change — a button, the wheel,
- * a pinch, a double click. `wheel` turns the library's own wheel handler off in favour of
- * {@link useZoomPanWheel}.
+ * Pass `onTransform` to the wrapper so `scale` tracks buttons, wheel, pinch and double click alike.
+ * `wheel` disables the library's own wheel handler in favour of {@link useZoomPanWheel}.
*/
export function useZoomPanPinch({ minScale, maxScale, resetOn, onScaleChange }: ZoomPanPinchOptions) {
const ref = useRef<ReactZoomPanPinchRef>(null);
@@ -52,15 +51,15 @@ 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.
+ * That handler adds `step * |deltaY|` to the current scale (`handleWheelZoom`). One step cannot be
+ * both the `scale * (k - 1)` a notch in needs and the `scale * (1 - 1 / k)` a notch back needs, so a
+ * notch each way lands at `1 - k²` of the starting scale and scrubbing shrinks the view. The library
+ * picks its step before it reads the event, so no value of `wheel.step` fixes that; this reads the
+ * direction from `deltaY` and computes a target scale instead.
*
- * `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.
+ * `zoomIn`/`zoomOut` take the increment up to that target, so the library still clamps to
+ * `minScale`/`maxScale` and recomputes its bounds. It zooms toward the middle of the view, so the
+ * `setTransform` that follows re-anchors the content under the pointer.
*/
export function useZoomPanWheel(apiRef: RefObject<ReactZoomPanPinchRef>, element: HTMLElement | null) {
useEffect(() => {
@@ -68,7 +67,7 @@ export function useZoomPanWheel(apiRef: RefObject<ReactZoomPanPinchRef>, element
const onWheel = (event: WheelEvent) => {
const api = apiRef.current;
- // A purely horizontal wheel carries no zoom, and is left to whatever else wants it.
+ // A purely horizontal wheel means no zoom; leave the event for anything else to use.
if (!api || event.deltaY === 0) return;
event.preventDefault();
@@ -97,16 +96,13 @@ export function useZoomPanWheel(apiRef: RefObject<ReactZoomPanPinchRef>, element
/** What one press of a zoom step multiplies the scale by. */
const ZOOM_STEP = 1.2;
-/**
- * What one wheel notch multiplies the scale by — gentler than a press, a notch being easy to repeat
- * and easy to overshoot with.
- */
+/** What one wheel notch multiplies the scale by. Below {@link ZOOM_STEP}: notches arrive in bursts. */
const WHEEL_STEP = 1.1;
-/** The `deltaY` a wheel notch reports where it reports a whole one; a trackpad reports far less. */
+/** The `deltaY` of one mouse-wheel notch. A trackpad reports a fraction of this per event. */
const WHEEL_NOTCH_DELTA = 100;
/**
- * How near a bound counts as being on it. The zoom animation reaches its target by adding the whole
- * difference back to the scale it started from, which can land a float's width short of the bound.
+ * How near a bound counts as reaching it. `animate()` computes its last frame as `scale + diff * 1`,
+ * which can land one float's width short of the bound.
*/
const ZOOM_LIMIT_TOLERANCE = 1e-6;
@@ -114,19 +110,19 @@ const ZOOM_LIMIT_TOLERANCE = 1e-6;
* The increment that takes `scale` one {@link ZOOM_STEP} in the given direction.
*
* react-zoom-pan-pinch adds the step to the current scale rather than multiplying by it (see
- * `handleCalculateButtonZoom`), so a fixed step is a leap at the bottom of the range and a crawl at
- * the top: from a fitted view one press of a 0.5 step reaches a `minScale` of 0.5, while 98 more are
- * needed to reach a `maxScale` of 50. Scaling the step by the scale it applies to keeps every press
- * the same proportion of what is on screen.
+ * `handleCalculateButtonZoom`), so a fixed step changes the view far more at a small scale than at a
+ * large one: from a fitted view, one press of a 0.5 step reaches a `minScale` of 0.5, and 98 more
+ * are needed to reach a `maxScale` of 50. Scaling the step by the current scale keeps every press
+ * the same proportion of the view.
*/
export function zoomStep(scale: number, direction: "in" | "out") {
return direction === "in" ? scale * (ZOOM_STEP - 1) : scale * (1 - 1 / ZOOM_STEP);
}
/**
- * 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.
+ * The scale one wheel notch takes `scale` to. Multiplies or divides by {@link WHEEL_STEP}, so a notch
+ * each way returns to the starting scale. A fractional `deltaY` moves the scale by that fraction of
+ * the step, which is how a trackpad reports.
*/
export function wheelTargetScale(scale: number, deltaY: number) {
const factor = WHEEL_STEP ** (Math.abs(deltaY) / WHEEL_NOTCH_DELTA);
@@ -154,7 +150,7 @@ export function zoomToPointPosition(scale0: number, posX0: number, posY0: number
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. */
+/** The instance's live scale. Read at click time rather than render time, so the step is current. */
function currentScale(ref: RefObject<ReactZoomPanPinchRef>) {
return ref.current?.instance?.state?.scale ?? 1;
}
diff --git a/apps/client/src/widgets/react/zoom_pan_keyboard.ts b/apps/client/src/widgets/react/zoom_pan_keyboard.ts
index 44d71e0224..65839fcd21 100644
--- a/apps/client/src/widgets/react/zoom_pan_keyboard.ts
+++ b/apps/client/src/widgets/react/zoom_pan_keyboard.ts
@@ -11,15 +11,12 @@ export type ZoomPanControl =
| "zoomIn" | "zoomOut" | "reset"
| "panUp" | "panDown" | "panLeft" | "panRight";
-/**
- * The class a focusable zoom/pan viewport wears, for the focus ring in zoom_pan.css — without one a
- * viewport reached by Tab gives no sign of having been reached.
- */
+/** 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";
/**
- * What the keys below do, said where the reader can find it. Every viewport this hook is wired to
- * shows the same two sections; a caller with more to say appends its own.
+ * 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 = [
{
@@ -105,11 +102,11 @@ export function getPanDelta(controls: Iterable<ZoomPanControl>, shiftKey: boolea
* 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 the element is focused, which a press on the viewport is what gives it: an
- * editor beside it takes the focus back on the next press into it, as any other pane would.
+ * Only active while `element` has focus, which a press on it gives; clicking an adjacent editor
+ * takes focus back, as with any other pane.
*
- * The element is taken rather than a ref to it, so that a viewport mounted later than the hook — a
- * preview pane that a display-mode switch brings in — is wired when it arrives.
+ * 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 },
diff --git a/apps/client/src/widgets/type_widgets/helpers/SplitEditor.css b/apps/client/src/widgets/type_widgets/helpers/SplitEditor.css
index 9a9a206c2c..e08a8f0ea8 100644
--- a/apps/client/src/widgets/type_widgets/helpers/SplitEditor.css
+++ b/apps/client/src/widgets/type_widgets/helpers/SplitEditor.css
@@ -177,8 +177,8 @@ body.desktop .note-detail-split .note-detail-code-editor {
max-width: 100% !important;
}
-/* OverlayControlGroup pins the controls to the corner its `placement` names; the z-index is what
- keeps them over the error card the preview can be dimmed behind. */
+/* OverlayControlGroup pins the controls by its `placement`. The z-index keeps them above
+ `.note-detail-error-card`, which uses 10 as well. */
.note-detail-split.svg-editor .svg-preview-controls {
z-index: 10;
}
diff --git a/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.spec.tsx b/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.spec.tsx
index 93632d78d6..8ac50bae77 100644
--- a/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.spec.tsx
+++ b/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.spec.tsx
@@ -7,10 +7,10 @@ import type { SplitEditorProps } from "./SplitEditor";
import SvgSplitEditor from "./SvgSplitEditor";
// react-zoom-pan-pinch measures its boxes, which happy-dom cannot do. This fake keeps the parts the
-// controls drive: `zoomIn`/`zoomOut` add their step to the current scale and clamp it to the bounds
-// it was given (the library's own arithmetic — see handleCalculateButtonZoom), `resetTransform`
-// returns to the fitted view, and every change is reported through `onTransform`, which is what the
-// readout follows. The props are captured too, so what is handed to the library can be asserted.
+// controls drive: `zoomIn`/`zoomOut` add their step to the current scale and clamp it to the given
+// bounds, copying `handleCalculateButtonZoom`; `resetTransform` returns to the fitted view; and each
+// change calls `onTransform`, which is what updates the readout. It also records the props, so the
+// tests can assert what the component passes to the library.
const { transformWrapperSpy } = vi.hoisted(() => ({ transformWrapperSpy: vi.fn() }));
vi.mock("react-zoom-pan-pinch", async () => {
@@ -86,8 +86,8 @@ describe("SvgSplitEditor", () => {
expect.objectContaining({ minScale: 0.5, maxScale: 10 })
);
- // The keys are the only way a reader with no pointer pans the diagram, so what they are has
- // to be readable from the preview itself.
+ // Without a pointer the keys are the only way to pan, so the preview shows a hints button
+ // alongside the three zoom steps.
expect(controls().all.length).toBe(4);
unmount();
@@ -113,8 +113,8 @@ describe("SvgSplitEditor", () => {
});
it("takes the keys on a press, in a split with the editor as much as on its own", async () => {
- // Beside the editor is where it matters most: the code pane swallows Tab to indent with, so
- // a press on the preview is the only way a reader reaches the keys that pan the diagram.
+ // This matters most beside the editor: `smartIndentWithTab` consumes Tab, so a press on the
+ // preview is the only way to reach the keys that pan the diagram.
const modes: Record<string, string>[] = [ {}, { displayMode: "preview" } ];
for (const labels of modes) {
const { container, preview, unmount } = await mount(labels);
@@ -153,9 +153,8 @@ describe("SvgSplitEditor", () => {
});
/**
- * Mounts `SvgSplitEditor` and waits for the rendered diagram and the controls over it to appear,
- * handing back a reader for the three buttons. They are read afresh on every call, the group being
- * drawn anew whenever the scale changes.
+ * Mounts `SvgSplitEditor` and waits for the rendered diagram and its controls. `controls()` re-reads
+ * the buttons on every call, because the group re-renders whenever the scale changes.
*/
async function mount(labels: Record<string, string> = {}) {
const container = document.createElement("div");
diff --git a/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.tsx b/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.tsx
index 706cc4cee4..3c61b7ac74 100644
--- a/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.tsx
+++ b/apps/client/src/widgets/type_widgets/helpers/SvgSplitEditor.tsx
@@ -47,8 +47,8 @@ export default function SvgSplitEditor({ ntxId, note, attachmentTitle, renderSvg
const zoom = useZoomPanPinch({ minScale: MIN_ZOOM, maxScale: MAX_ZOOM, resetOn: note.noteId });
const [ previewEl, setPreviewEl ] = useState<HTMLDivElement | null>(null);
- // The keys are wired whatever the display mode: a reader with no pointer has no other way to pan
- // the diagram. Source-only mounts no preview, so it has nothing to say about them either.
+ // Wire the keys in every display mode: without a pointer there is no other way to pan the
+ // diagram. Source-only mounts no preview, so it registers no hints for it.
const [ displayMode ] = useNoteLabel(note, "displayMode");
const readOnly = useEffectiveReadOnly(note, props.noteContext);
const mode = resolveDisplayMode(displayMode, readOnly);
@@ -103,8 +103,8 @@ export default function SvgSplitEditor({ ntxId, note, attachmentTitle, renderSvg
}).catch(e => console.error("Failed to get attachments for SVGSplitEditor", e));
}, [ note, svg, attachmentTitle, onSave ]);
- // Import/export. The renderer's `svg` string is exported rather than the on-screen element, so
- // the export never carries what the preview did to fit the diagram into its pane.
+ // Import/export. Exports the `svg` string from `renderSvg()` rather than the on-screen element,
+ // which CSS has sized to the preview pane.
useTriliumEvent("exportSvg", ({ ntxId: eventNtxId }) => {
if (eventNtxId !== ntxId || !svg) return;
@@ -183,11 +183,11 @@ export default function SvgSplitEditor({ ntxId, note, attachmentTitle, renderSvg
}
/**
- * How far in and out the diagram can be taken, as a multiple of the view it opened at.
+ * Zoom bounds, as a multiple of the fitted view.
*
* CSS fits the SVG to the preview pane through its `viewBox` and `preserveAspectRatio` (see the SVG
- * section of SplitEditor.css), so a scale of 1 already is that fitted view and these bounds need no
- * measurement of their own.
+ * section of SplitEditor.css), so a scale of 1 is already that fitted view and these bounds need no
+ * measurement.
*/
const MIN_ZOOM = 0.5;
const MAX_ZOOM = 10;
diff --git a/packages/trilium-e2e/src/note_types/mermaid.spec.ts b/packages/trilium-e2e/src/note_types/mermaid.spec.ts
index 2105fdbef6..25b243da1d 100644
--- a/packages/trilium-e2e/src/note_types/mermaid.spec.ts
+++ b/packages/trilium-e2e/src/note_types/mermaid.spec.ts
@@ -124,7 +124,7 @@ async function testDividerDragSurvival({ page, context, noteTitle }: DividerDrag
const drawnHeight = () => svgData.evaluate((svg: SVGSVGElement) =>
svg.getBBox().height * (svg.getScreenCTM()?.d ?? 0));
- // Let the layout settle, mermaid sizing the diagram shortly after it mounts.
+ // Let the layout settle; mermaid sizes the diagram shortly after it mounts.
await page.waitForTimeout(500);
const beforeHeight = await drawnHeight();