@preference-sl/pref-viewer 2.11.0-beta.0 → 2.11.0-beta.2

package/src/panzoom-controller.js

@@ -0,0 +1,494 @@
+import "@panzoom/panzoom";
+
+/**
+ * PanzoomController - Encapsulates the logic for managing pan and zoom interactions on a given DOM element.
+ *
+ * Responsibilities:
+ *  - Provides an interface to enable, disable, and control pan/zoom interactions.
+ *  - Manages event listeners for mouse, keyboard, and touch interactions.
+ *  - Tracks the current pan/zoom state and invokes a callback when the state changes.
+ *  - Supports zooming in/out, panning, resetting, and mouse wheel zoom.
+ *
+ * Usage:
+ *  - Instantiate the controller with a DOM element and optional configuration:
+ *      const controller = new PanzoomController(wrapperElement, options, stateChangeCallback);
+ *  - Use public methods like `enable()`, `zoomIn()`, `pan(x, y)`, etc., to control interactions.
+ *  - Call `disable()` to remove all event listeners and destroy the Panzoom instance.
+ *
+ * Constructor Parameters:
+ *  - `wrapper` (HTMLElement): The DOM element to apply pan/zoom interactions to.
+ *  - `options` (object): Configuration options for Panzoom (e.g., minScale, maxScale, step).
+ *  - `changedCallback` (function): Optional callback invoked when the pan/zoom state changes.
+ *
+ * Public Methods:
+ *  - `enable()`: Enables the Panzoom instance and initializes it if not already enabled.
+ *  - `disable()`: Disables the Panzoom instance and removes all event listeners.
+ *  - `enableEvents()`: Attaches all required event listeners for interactions.
+ *  - `disableEvents()`: Removes all previously attached event listeners.
+ *  - `pan(x, y)`: Pans the view to the specified coordinates.
+ *  - `reset()`: Resets pan and zoom to fit the entire content within the available space.
+ *  - `zoomIn(focal?)`: Zooms in by one step, optionally centered on a focal point.
+ *  - `zoomOut(focal?)`: Zooms out by one step, optionally centered on a focal point.
+ *
+ * Getters:
+ *  - `panzoom`: Returns the current Panzoom instance or `null` if not initialized.
+ *  - `state`: Returns the current pan/zoom state (e.g., moved, scaled, maximized, minimized).
+ *
+ * Private Methods:
+ *  - `#checkPanzoomState(transform)`: Updates the internal state and invokes the state change callback.
+ *  - `#resetTransform()`: Resets the transform applied to the wrapper element.
+ *  - `#setFocus()`: Sets focus on the parent element to enable keyboard interactions.
+ *  - `#onPanzoomStart(e)`: Handles the start of a pan/zoom interaction.
+ *  - `#onPanzoomChange(e)`: Handles changes in pan/zoom state.
+ *  - `#onPanzoomEnd(e)`: Handles the end of a pan/zoom interaction.
+ *  - `#onZoomWithWheel(e)`: Handles zoom interactions via the mouse wheel.
+ *  - `#enableMouseWheelZoom()`: Enables zooming with the mouse wheel.
+ *  - `#disableMouseWheelZoom()`: Disables zooming with the mouse wheel.
+ *  - `#getDistanceBetweenPoints(point1, point2)`: Calculates the Euclidean distance between two points.
+ *  - `#getPointFromEvent(e)`: Extracts client coordinates from a mouse or touch event.
+ *
+ * Notes:
+ *  - Designed to work with the Panzoom library for managing pan/zoom interactions.
+ *  - Provides a clean separation of concerns by encapsulating all pan/zoom logic in a single class.
+ *  - Can be extended or customized by overriding methods or providing additional options.
+ */
+export default class PanzoomController {
+    #changedCallback = null;
+    #interactionOptions = {
+        clickThreshold: 6, // Threshold to avoid false clicks on elements when panning or zooming
+    };
+    #options = {
+        canvas: true,
+        minScale: 0.1,
+        maxScale: 10,
+        step: 0.3,
+        cursor: "default",
+        disablePan: false,
+        disableZoom: false,
+    };
+    #panzoom = null; // Panzoom Object
+    #pointerEvents = {
+        lastPointerDownPosition: null,
+        partialCounter: 0,
+        totalCounter: 0,
+    };
+    #state = {
+        moved: false,
+        scaled: false,
+        maximized: false,
+        minimized: false,
+    };
+    #wrapper = null;
+
+    constructor(wrapper = null, options = {}, changedCallback = null) {
+        this.#wrapper = wrapper;
+        Object.assign(this.#options, options);
+        this.#changedCallback = changedCallback;
+    }
+
+    /**
+     * Calculate Euclidean distance between two points {x,y}.
+     * @private
+     * @param {{x:number,y:number}} point1
+     * @param {{x:number,y:number}} point2
+     * @returns {number} Distance in pixels (0 when points are invalid).
+     */
+    #getDistanceBetweenPoints(point1, point2) {
+        let distance = 0;
+        if (point1 && point2) {
+            distance = Math.sqrt(Math.pow(point2.x - point1.x, 2) + Math.pow(point2.y - point1.y, 2));
+        }
+        return distance;
+    }
+
+    /**
+     * Extract client coordinates from a mouse/touch event.
+     * @private
+     * @param {Event} e - Mouse or touch event.
+     * @returns {{x:number,y:number}|null} Point or null if coordinates not present.
+     */
+    #getPointFromEvent(e) {
+        if (e.clientX && e.clientY) {
+            return {
+                x: e.clientX,
+                y: e.clientY,
+            };
+        } else {
+            return null;
+        }
+    }
+
+    /**
+     * Update internal pan/zoom state and emit a custom event with current values.
+     * If a changed callback is defined, it is invoked with the updated state object.
+     * @private
+     * @param {{scale:number,x:number,y:number}} transform - Current transform values.
+     * @returns {void}
+     */
+    #checkPanzoomState(transform) {
+        this.#state = {
+            moved: transform.x !== 0 || transform.y !== 0,
+            scaled: transform.scale !== 1,
+            maximized: transform.scale === this.#options.maxScale,
+            minimized: transform.scale === this.#options.minScale,
+        };
+
+        if (this.#changedCallback && typeof this.#changedCallback === "function") {
+            this.#changedCallback(this.#state);
+        }
+    }
+
+    /**
+     * Remove any transform applied to the wrapper (reset pan/zoom). Resets internal Panzoom state accordingly.
+     * @private
+     * @returns {void}
+     */
+    #resetTransform() {
+        const transform = {
+            scale: 1,
+            x: 0,
+            y: 0,
+        };
+        if (this.#wrapper) {
+            this.#wrapper.style.removeProperty("transform");
+        }
+        this.#checkPanzoomState(transform);
+    }
+
+    /**
+     * Set focus on the viewer's parent element to enable keyboard interactions.
+     * @private
+     * @returns {void}
+     * @description Focus is set on the parent element because when Panzoom had focus with a positive Y translation (part of the drawing outside the parent container), the Y translation was reset.
+     */
+    #setFocus() {
+        if (this.#wrapper) {
+            this.#wrapper.parentElement.focus();
+        }
+    }
+
+    /**
+     * Contextmenu handler to prevent the browser's default context menu.
+     * @private
+     * @param {Event} e - Contextmenu event.
+     * @returns {void}
+     */
+    #onContextMenu(e) {
+        e.preventDefault();
+    }
+
+    /**
+     * Keyboard handler to support '+' and '-' shortcuts for zoom.
+     * @private
+     * @param {KeyboardEvent} e - Key event.
+     * @returns {void}
+     */
+    #onKeyUp(e) {
+        // '+' zoom in
+        if (e.key === "+") {
+            this.zoomIn();
+        }
+        // '-' zoom out
+        if (e.key === "-") {
+            this.zoomOut();
+        }
+    }
+
+    /**
+     * Panzoom "change" (pan, zoom, reset) event handler. Updates internal transform state.
+     * @private
+     * @param {CustomEvent} e - Panzoom custom event with detail.scale/x/y
+     * @returns {void}
+     * @description This event is not fired when options.setTransform is called directly.
+     */
+    #onPanzoomChange(e) {
+        const transform = {
+            scale: e.detail.scale,
+            x: e.detail.x,
+            y: e.detail.y,
+        };
+        this.#checkPanzoomState(transform);
+    }
+
+    /**
+     * Panzoom "end" event handler. Determines whether the gesture should be considered a click (for selection) or a pan/zoom gesture and acts accordingly.
+     * @private
+     * @param {CustomEvent} e - Panzoom custom event with originalEvent property.
+     * @returns {void}
+     * @todo Implement selection/click logic.
+     */
+    #onPanzoomEnd(e) {
+        this.#pointerEvents.partialCounter--;
+
+        if (this.#pointerEvents.partialCounter > 0) {
+            return;
+        } else if (this.#pointerEvents.totalCounter > 1) {
+            this.#pointerEvents.partialCounter = 0;
+            this.#pointerEvents.totalCounter = 0;
+            return;
+        }
+
+        this.#pointerEvents.partialCounter = 0;
+        this.#pointerEvents.totalCounter = 0;
+
+        const originalEvent = e.detail.originalEvent;
+        const point = this.#getPointFromEvent(originalEvent);
+        const distance = this.#getDistanceBetweenPoints(point, this.#pointerEvents.lastPointerDownPosition);
+
+        let proceedToPick = true;
+
+        if (!point || distance > this.#interactionOptions.clickThreshold) {
+            proceedToPick = false;
+        }
+
+        if (originalEvent.button !== 0) {
+            proceedToPick = false;
+        }
+
+        this.#pointerEvents.lastPointerDownPosition = null;
+
+        if (!proceedToPick) {
+            return;
+        }
+
+        if (!originalEvent.target) {
+            return;
+        }
+
+        // Selection/click logic can be implemented here.
+    }
+
+    /**
+     * Panzoom "start" event handler. Store pointer state and set focus.
+     * @private
+     * @param {CustomEvent} e - Panzoom custom event with originalEvent property.
+     * @returns {void}
+     */
+    #onPanzoomStart(e) {
+        const originalEvent = e.detail.originalEvent;
+        this.#pointerEvents.partialCounter++;
+        this.#pointerEvents.totalCounter++;
+        this.#pointerEvents.lastPointerDownPosition = this.#getPointFromEvent(originalEvent);
+        this.#setFocus();
+    }
+
+    /**
+     * Delegate wheel events to Panzoom zoom handler.
+     * @private
+     * @param {WheelEvent} e - Wheel event.
+     * @returns {void}
+     */
+    #onZoomWithWheel(e) {
+        if (!this.#panzoom) {
+            return;
+        }
+        this.#panzoom.zoomWithWheel(e);
+    }
+
+    /**
+     * Disable mouse wheel zoom by removing the wheel event listener from the parent element.
+     * @private
+     * @returns {void}
+     */
+    #disableMouseWheelZoom() {
+        if (!this.#panzoom) {
+            return;
+        }
+        this.#wrapper.parentElement.removeEventListener("wheel", this.#onZoomWithWheel.bind(this));
+    }
+
+    /**
+     * Enable mouse wheel zoom by adding the wheel event listener to the parent element.
+     * @private
+     * @returns {void}
+     * @description
+     * Removes any previous wheel event listener before adding a new one to avoid duplicates.
+     */
+    #enableMouseWheelZoom() {
+        if (!this.#panzoom) {
+            return;
+        }
+        this.#disableMouseWheelZoom();
+        this.#wrapper.parentElement.addEventListener("wheel", this.#onZoomWithWheel.bind(this));
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
+
+    /**
+     * Enables the Panzoom instance for the wrapper element.
+     * Initializes Panzoom with the provided options if not already enabled.
+     * @public
+     * @returns {void}
+     */
+    enable() {
+        if (!this.#wrapper) {
+            return;
+        }
+        if (!this.#panzoom) {
+            this.#panzoom = Panzoom(this.#wrapper, this.#options);
+        }
+    }
+
+    /**
+     * Disables the Panzoom instance and removes all related event listeners.
+     * Destroys the Panzoom object and resets transforms.
+     * @public
+     * @returns {void}
+     */
+    disable() {
+        if (!this.#panzoom) {
+            return;
+        }
+        this.disableEvents();
+        this.#panzoom.destroy();
+        this.#panzoom = null;
+        this.#resetTransform();
+    }
+
+    /**
+     * Subscribes all required Panzoom and interaction event listeners.
+     * Adds listeners for panzoom events, keyboard shortcuts, mouse wheel zoom, and context menu.
+     * Sets focus and enables keyboard navigation.
+     * @public
+     * @returns {void}
+     */
+    enableEvents() {
+        if (!this.#panzoom) {
+            return;
+        }
+
+        this.disableEvents();
+
+        this.#wrapper.addEventListener("panzoomstart", this.#onPanzoomStart.bind(this));
+        this.#wrapper.addEventListener("panzoomchange", this.#onPanzoomChange.bind(this));
+        this.#wrapper.addEventListener("panzoomend", this.#onPanzoomEnd.bind(this));
+        this.#wrapper.parentElement.addEventListener("keyup", this.#onKeyUp.bind(this));
+        this.#wrapper.parentElement.addEventListener("focus", this.#enableMouseWheelZoom.bind(this), true);
+        this.#wrapper.parentElement.addEventListener("blur", this.#disableMouseWheelZoom.bind(this), true);
+        this.#wrapper.parentElement.addEventListener("contextmenu", this.#onContextMenu);
+        this.#wrapper.parentElement.setAttribute("tabindex", 0);
+        this.#setFocus();
+    }
+
+    /**
+     * Unsubscribes all Panzoom and interaction event listeners previously attached.
+     * Removes listeners for panzoom events, keyboard shortcuts, mouse wheel zoom, and context menu.
+     * @public
+     * @returns {void}
+     */
+    disableEvents() {
+        if (!this.#wrapper) {
+            return;
+        }
+        this.#wrapper.parentElement.removeAttribute("tabindex");
+        this.#wrapper.removeEventListener("panzoomstart", this.#onPanzoomStart.bind(this));
+        this.#wrapper.removeEventListener("panzoomchange", this.#onPanzoomChange.bind(this));
+        this.#wrapper.removeEventListener("panzoomend", this.#onPanzoomEnd.bind(this));
+        this.#wrapper.parentElement.removeEventListener("keyup", this.#onKeyUp.bind(this));
+        this.#wrapper.parentElement.removeEventListener("focus", this.#enableMouseWheelZoom.bind(this));
+        this.#wrapper.parentElement.removeEventListener("blur", this.#disableMouseWheelZoom.bind(this));
+        this.#wrapper.parentElement.removeEventListener("contextmenu", this.#onContextMenu);
+    }
+
+    /**
+     * Pans the SVG view to the specified coordinates.
+     * Sets focus on the parent element after panning.
+     * @public
+     * @param {number} x - The x coordinate to pan to.
+     * @param {number} y - The y coordinate to pan to.
+     * @returns {void}
+     */
+    pan(x, y) {
+        if (!this.#panzoom) {
+            return;
+        }
+        if (typeof x !== "number" || typeof y !== "number") {
+            return;
+        }
+        this.#panzoom.pan(x, y, { animate: false });
+        this.#setFocus();
+    }
+
+    /**
+     * Resets pan and zoom so the entire SVG drawing fits within the available space.
+     * Sets focus on the parent element after resetting.
+     * @public
+     * @returns {void}
+     */
+    reset() {
+        if (!this.#panzoom) {
+            return;
+        }
+        this.#panzoom.reset({ animate: false });
+        this.#setFocus();
+    }
+
+    /**
+     * Zooms in the SVG view by one step.
+     * If a focal point is provided, the zoom is centered on that point; otherwise, it is centered on the drawing.
+     * Sets focus on the parent element after zooming.
+     * @param {{x:number, y:number}=} focal - Optional focal point for the zoom operation.
+     * @public
+     * @returns {void}
+     */
+    zoomIn(focal) {
+        if (!this.#panzoom) {
+            return;
+        }
+        const options = {
+            exponential: false,
+            animate: false,
+        };
+
+        if (typeof focal === "object" && focal && "x" in focal && "y" in focal) {
+            options.focal = focal;
+        }
+        this.#panzoom.zoomIn(options);
+        this.#setFocus();
+    }
+
+    /**
+     * Zooms out the SVG view by one step.
+     * If a focal point is provided, the zoom is centered on that point; otherwise, it is centered on the drawing.
+     * Sets focus on the parent element after zooming.
+     * @param {{x:number, y:number}=} focal - Optional focal point for the zoom operation.
+     * @public
+     * @returns {void}
+     */
+    zoomOut(focal) {
+        if (!this.#panzoom) {
+            return;
+        }
+        const options = {
+            exponential: false,
+            animate: false,
+        };
+        if (typeof focal === "object" && focal && "x" in focal && "y" in focal) {
+            options.focal = focal;
+        }
+        this.#panzoom.zoomOut(options);
+        this.#setFocus();
+    }
+
+    /**
+     * Returns the current Panzoom instance.
+     * @public
+     * @returns {object|null} The Panzoom object or null if not initialized.
+     */
+    get panzoom() {
+        return this.#panzoom;
+    }
+
+    /**
+     * Returns the current pan/zoom state.
+     * @public
+     * @returns {object} The state object: { moved, scaled, maximized, minimized }.
+     */
+    get state() {
+        return this.#state;
+    }
+}