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
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.tsxindex 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.tsxindex 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.tsxindex 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 }: OverlayFullsinterface 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.cssindex 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.tsindex 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>, elementconst 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: numberreturn { 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.tsindex 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.cssindex 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.tsxindex 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.tsxindex 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, renderSvgconst 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.tsindex 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 }: DividerDragconst 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();