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

package/src/pref-viewer-2d.js

@@ -0,0 +1,459 @@
+import SVGResolver from "./svg-resolver.js";
+import PanzoomController from "./panzoom-controller.js";
+
+/**
+ * PrefViewer2D - Custom element for rendering and interacting with 2D SVG content.
+ *
+ * Summary
+ *  - Renders an SVG string into an internal wrapper element and provides pan/zoom interactions using the Panzoom library.
+ *  - Supports SVG input from:
+ *      * data URI (storage.url) (base64 or plain string)
+ *      * IndexedDB record (base64 or plain string) (storage.db, storage.table, storage.id)
+ *      * remote URL (storage.url)
+ *      * direct SVG strings (storage.url)
+ *  - Avoids unnecessary reloads by comparing stored size and Last-Modified timestamp.
+ *
+ * Public attributes
+ *  - svg: string (setting triggers load)
+ *  - visible: "true" | "false" (controls visibility and event subscription)
+ *
+ * Public methods
+ *  - async load(svgConfig) : Promise<boolean> — accept SVG input/config and prepare for render
+ *  - show(), hide() — toggle visibility and event subscriptions
+ *  - zoomIn(), zoomOut(), zoomCenter(), zoomExtentsAll() — pan/zoom controls
+ * 
+ * * Public Properties:
+ *  - isInitialized: Indicates whether the component has completed initialization.
+ *  - isLoaded: Indicates whether the SVG content is loaded and ready.
+ *  - isVisible: Indicates whether the component is currently visible.
+ *
+ * Events
+ *  - "drawing-loading": emitted before loading starts
+ *  - "drawing-loaded": emitted after content and Panzoom are ready
+ *  - "drawing-error": emitted on validation/fetch errors (detail.error: Error)
+ *  - "drawing-zoom-changed": emitted when pan/zoom state changes (detail: { moved, scaled, maximized, minimized })
+ *
+ * Implementation notes
+ *  - Keeps internal state in private fields (#svg, #panzoom, #panzoomOptions, ...).
+ *  - Validates SVG content with is-svg and decodes base64 with atob.
+ *  - Performs HEAD requests to obtain Content-Length and Last-Modified for remote URLs.
+ *  - Focus is set on the component's parent to enable keyboard shortcuts without Panzoom focus issues.
+ *
+ * Usage examples
+ *  - load plain SVG: el.load({ storage: { url: '<svg...>' } }) or el.load('<svg...>');
+ *  - load from IndexedDB: el.load({ storage: { db: 'db', table: 'tbl', id: 'recId' } });
+ *
+ * Notes on extensibility
+ *  - Modeled for easy addition of other input sources or interaction modes (e.g., selection callbacks).
+ */
+export class PrefViewer2D extends HTMLElement {
+    // State flags
+    #isInitialized = false;
+    #isLoaded = false;
+    #isVisible = false;
+
+    #options = {
+        resetOnReload: true,
+    };
+
+    // Current SVG state
+    #svg = {
+        value: "",
+        size: 0,
+        timeStamp: null,
+        update: true,
+    };
+
+    #svgResolver = null; // SVGResolver instance
+    #wrapper = null; // Panzoom element
+    #panzoomController = null; // PanzoomController instance
+
+    /**
+     * Create a new instance of the 2D viewer component.
+     * The constructor only calls super(); heavy initialization happens in connectedCallback.
+     */
+    constructor() {
+        super();
+    }
+
+    /**
+     * Attributes observed by the custom element.
+     * @returns {string[]} Array of attribute names that trigger attributeChangedCallback.
+     */
+    static get observedAttributes() {
+        return ["svg", "visible"];
+    }
+
+    /**
+     * Handles changes to observed attributes and updates the component state accordingly.
+     * @param {string} name - The name of the changed attribute.
+     * @param {string|null} _old - The previous value of the attribute.
+     * @param {string|null} value - The new value of the attribute.
+     * @returns {void}
+     * @description
+     * - "svg": triggers load of new SVG content.
+     * - "visible": shows or hides the component according to the attribute value ("true"/"false").
+     */
+    attributeChangedCallback(name, _old, value) {
+        switch (name) {
+            case "svg":
+                this.load(value);
+                break;
+            case "visible":
+                if (_old === value) {
+                    return;
+                }
+                if (value === "true" && this.#isVisible === false) {
+                    this.show();
+                } else if (value === "false" && this.#isVisible === true) {
+                    this.hide();
+                }
+        }
+    }
+
+    /**
+     * Called when the element is inserted into the DOM.
+     * Sets up DOM nodes, initial visibility and starts loading the SVG if provided.
+     * @returns {void}
+     */
+    connectedCallback() {
+        this.#createDOMElements();
+        this.#setInitialVisibility();
+        this.#initializePanzoom();
+        this.#isInitialized = true;
+        this.#loadSVG();
+    }
+
+    /**
+     * Called when the element is removed from the DOM.
+     * Disables the PanzoomController to clean up event listeners and resources.
+     * @returns {void}
+     */
+    disconnectedCallback() {
+        if (this.#panzoomController) {
+            this.#panzoomController.disable();
+        }
+    }
+
+    /**
+     * Create DOM structure and basic styles used by the component.
+     * @private
+     * @returns {void}
+     */
+    #createDOMElements() {
+        this.#wrapper = document.createElement("div");
+        this.append(this.#wrapper);
+        const style = document.createElement("style");
+        style.textContent = `pref-viewer-2d[visible="true"] { display: block; } pref-viewer-2d[visible="false"] { display: none; } pref-viewer-2d, pref-viewer-2d > div, pref-viewer-2d > div > svg { width: 100%; height: 100%; display: block; position: relative; outline: none; box-sizing: border-box; } pref-viewer-2d > div > svg { padding: 10px; }`;
+        this.append(style);
+    }
+
+    /**
+     * Set initial visibility based on inline style and the visible attribute.
+     * @private
+     * @returns {void}
+     * @description If the "visible" attribute is not present, defaults to visible.
+     */
+    #setInitialVisibility() {
+        const visible = !this.hasAttribute("visible") || this.getAttribute("visible") === "true";
+        visible ? this.show() : this.hide();
+    }
+
+    /**
+     * Initializes the PanzoomController instance for the SVG wrapper element.
+     * Sets up the controller with default options and binds the state change callback.
+     * @private
+     * @returns {void}
+     */
+    #initializePanzoom() {
+        this.#panzoomController = new PanzoomController(this.#wrapper, undefined, this.#onPanzoomChanged.bind(this));
+    }
+
+    /**
+     * Render the current SVG into the wrapper and (re)initialize the Panzoom instance as required.
+     * @private
+     * @returns {boolean} Returns false when no SVG should be loaded or when validation fails; otherwise performs rendering and returns true.
+     * @description
+     * Behavior:
+     *  - If this.#svg.update === false the method returns false (no work needed).
+     *  - SVG is not validated here because it is already handled by SVGResolver.
+     *  - Calls #onLoading() before making DOM changes and #onLoaded() after Panzoom is ready.
+     *  - When options.resetOnReload is true (or there is no SVG value) it destroys the existing Panzoom
+     *    instance so a fresh one is created for the new content.
+     *  - If the SVG content is empty the method sets loaded state and returns false (no Panzoom initialization).
+     */
+    #loadSVG() {
+        if (!this.#svgResolver) {
+            this.#svgResolver = new SVGResolver(this.#svg);
+        }
+        if (this.#svg.update === false) {
+            return false;
+        }
+
+        this.#onLoading();
+
+        if (this.#options.resetOnReload || !this.#svg.value) {
+            this.#panzoomController.disable();
+        }
+
+        this.#wrapper.innerHTML = this.#svg.value;
+
+        // If SVG is empty, do not initialize Panzoom but don't emit an error
+        if (!this.#svg.value) {
+            this.#onLoaded();
+            return false;
+        }
+
+        if (!this.#panzoomController.panzoom) {
+            this.#panzoomController.enable();
+        }
+
+        this.#onLoaded();
+        return true;
+    }
+
+    /**
+     * Handles invalid or unsupported SVG input by emitting a custom error event.
+     * @private
+     * @returns {object} Detail object with an Error describing the SVG input issue.
+     */
+    #onError() {
+        const error = "PrefViewer2D: Error in SVG provided for loading. Ensure the SVG is a URL to an SVG file, a string containing a SVG, or a string containing a base64-encoded SVG.";
+        const detail = { error: new Error(error) };
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail: detail,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-error", customEventOptions));
+        return detail;
+    }
+
+    /**
+     * Called when SVG and Panzoom are ready; sets loaded flag and subscribes to events.
+     * @private
+     * @returns {void}
+     */
+    #onLoaded() {
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions));
+
+        this.removeAttribute("loading");
+        this.setAttribute("loaded", "");
+
+        this.#isLoaded = true;
+        this.#subscribeToEvents();
+    }
+
+    /**
+     * Called before loading starts; clears loaded flag and unsubscribes from events.
+     * @private
+     * @returns {void}
+     */
+    #onLoading() {
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions));
+
+        this.removeAttribute("loaded");
+        this.setAttribute("loading", "");
+
+        if (this.#isLoaded === true) {
+            this.#isLoaded = false;
+        }
+
+        this.#unsubscribeToEvents();
+    }
+
+    /**
+     * Handles Panzoom state changes by dispatching a "prefviewer2d-zoomchanged" custom event.
+     * @private
+     * @param {object} state - The current Panzoom state object.
+     * @returns {void}
+     * @description
+     * The event detail contains the Panzoom state: { moved, scaled, maximized, minimized } to provide
+     * the UI with the enabled/disabled status of the zoomIn, zoomOut, center, and zoomExtentsAll buttons.
+     */
+    #onPanzoomChanged(state) {
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail: state,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-zoom-changed", customEventOptions));
+    }
+
+    /**
+     * Subscribe DOM events required by Panzoom and keyboard interactions.
+     * @private
+     * @returns {void}
+                composed: true,
+                detail: state,
+            })
+        );
+    }
+
+    /**
+     * Subscribe DOM events required by Panzoom and keyboard interactions.
+     * @private
+     * @returns {void}
+     * @description
+     * Adds listeners only when Panzoom exists and component is visible.
+     * Delegates event binding to PanzoomController instance.
+     */
+    #subscribeToEvents() {
+        if (!this.#panzoomController || !this.#isVisible) {
+            return;
+        }
+        this.#panzoomController.enableEvents();
+    }
+
+    /**
+     * Unsubscribe previously attached DOM events.
+     * @private
+     * @returns {void}
+     * @description
+     * Delegates event binding to PanzoomController instance.
+     */
+    #unsubscribeToEvents() {
+        if (!this.#panzoomController) {
+            return;
+        }
+        this.#panzoomController.disableEvents();
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
+
+    /**
+     * Load a new SVG resource into the viewer.
+     * @public
+     * @param {object} svgConfig - SVG configuration. An object with a `storage` property describing the source:
+     *      { storage: { url: "<url>" } }
+     *      or { storage: { db: "<db>", table: "<table>", id: "<id>" } }
+     * @returns {Promise<{success: boolean, error: Error|null}>}
+     * - Resolves to { success: false, error: <Error> } when the input is invalid or the SVG could not be retrieved/decoded, or when there is no update required (cached copy unchanged).
+     * - Resolves to { success: true, error: null } when the SVG was accepted and the component has started rendering.
+     */
+    async load(svgConfig) {
+        if (!svgConfig || !(await this.#svgResolver.getSVG(svgConfig))) {
+            const errorDetail = this.#onError();
+            return { success: false, ...errorDetail };
+        }
+        const success = this.#isInitialized && this.#loadSVG();
+        return { success: success, error: null };
+    }
+
+    /**
+     * Hide the component: set style, attribute and unsubscribe from events.
+     * @public
+     * @returns {void}
+     */
+    hide() {
+        this.#isVisible = false;
+        this.setAttribute("visible", "false");
+        this.#unsubscribeToEvents();
+    }
+
+    /**
+     * Show the component: set style, attribute and subscribe to events.
+     * @public
+     * @returns {void}
+     */
+    show() {
+        this.#isVisible = true;
+        this.setAttribute("visible", "true");
+        this.#subscribeToEvents();
+    }
+
+    /**
+     * Pans the SVG view to the center without changing the zoom level.
+     * Delegates the pan action to the PanzoomController instance.
+     * @public
+     * @returns {void}
+     */
+    zoomCenter() {
+        if (!this.#panzoomController) {
+            return;
+        }
+        this.#panzoomController.pan(0, 0);
+    }
+
+    /**
+     * Resets pan and zoom so the entire SVG drawing fits within the available space.
+     * Delegates the reset action to the PanzoomController instance.
+     * @public
+     * @returns {void}
+     */
+    zoomExtentsAll() {
+        if (!this.#panzoomController) {
+            return;
+        }
+        this.#panzoomController.reset();
+    }
+
+    /**
+     * Zoom in the SVG view one step.
+     * Delegates the zoom-in action to the PanzoomController instance.
+     * @public
+     * @returns {void}
+     */
+    zoomIn() {
+        if (!this.#panzoomController) {
+            return;
+        }
+        this.#panzoomController.zoomIn();
+    }
+
+    /**
+     * Zoom out the SVG view one step.
+     * Delegates the zoom-out action to the PanzoomController instance.
+     * @public
+     * @returns {void}
+     */
+    zoomOut() {
+        if (!this.#panzoomController) {
+            return;
+        }
+        this.#panzoomController.zoomOut();
+    }
+
+    /**
+     * Indicates whether the component has completed its initialization.
+     * @public
+     * @returns {boolean} True if the component is initialized; otherwise, false.
+     */
+    get isInitialized() {
+        return this.#isInitialized;
+    }
+
+    /**
+     * Indicates whether the SVG content is loaded and ready.
+     * @public
+     * @returns {boolean} True if the SVG is loaded; otherwise, false.
+     */
+    get isLoaded() {
+        return this.#isLoaded;
+    }
+
+    /**
+     * Indicates whether the component is currently visible.
+     * @public
+     * @returns {boolean} True if the component is visible; otherwise, false.
+     */
+    get isVisible() {
+        return this.#isVisible;
+    }
+}

package/src/pref-viewer-3d-data.js

@@ -0,0 +1,178 @@
+/**
+ * ContainerData - Represents the state and metadata of a asset container in the 3D viewer (e.g., model, environment, materials).
+ *
+ * Responsibilities:
+ *  - Tracks container name, show (if must be visible), visibility (if currently visible), size, and timestamp.
+ *  - Manages update state for asynchronous operations (pending, success, etc.).
+ *  - Provides methods to reset, set pending, and set success states.
+ *
+ * Usage:
+ *  - Instantiate with a name: new ContainerData("model")
+ *  - Use setPending(), setSuccess(), and reset() to manage update state.
+ *  - Access status via isPending, isSuccess, isVisible getters.
+ */
+export class ContainerData {
+    constructor(name = "") {
+        this.name = name;
+        this.show = true;
+        this.size = 0;
+        this.timeStamp = null;
+        this.visible = false;
+        // Set initial information about ongoing update
+        this.reset();
+    }
+    reset() {
+        this.update = {
+            pending: false,
+            storage: null,
+            success: false,
+            show: null,
+            size: 0,
+            timeStamp: null,
+        };
+    }
+    setSuccess(success = false) {
+        if (success) {
+            this.update.success = true;
+            this.show = this.update.show !== null ? this.update.show : this.show;
+            this.size = this.update.size;
+            this.timeStamp = this.update.timeStamp;
+        } else {
+            this.update.success = false;
+        }
+    }
+    setPending(storage = null, show) {
+        this.reset();
+        this.update.pending = true;
+        this.update.storage = storage;
+        this.update.success = false;
+        this.update.show = show !== undefined ? show : this.update.show;
+    }
+    setPendingCacheData(size = 0, timeStamp = null) {
+        this.update.size = size;
+        this.update.timeStamp = timeStamp;
+    }
+    get isPending() {
+        return this.update.pending === true;
+    }
+    get isSuccess() {
+        return this.update.success === true;
+    }
+    get isVisible() {
+        return this.visible === true;
+    }
+    get mustBeShown() {
+        return this.show === true;
+    }
+}
+
+/**
+ * MaterialData - Represents the state and metadata of a material in the 3D viewer.
+ *
+ * Responsibilities:
+ *  - Tracks material name, value, node names, and node prefixes.
+ *  - Manages update state for asynchronous operations (pending, success, etc.).
+ *  - Provides methods to reset, set pending, and set success states.
+ *
+ * Usage:
+ *  - Instantiate with a name and optional value: new MaterialData("innerWall", value, nodeNames, nodePrefixes)
+ *  - Use setPending(), setSuccess(), and reset() to manage update state.
+ *  - Access status via isPending, isSuccess getters.
+ */
+export class MaterialData {
+    constructor(name = "", value = null, nodeNames = [], nodePrefixes = []) {
+        this.name = name;
+        this.nodeNames = nodeNames;
+        this.nodePrefixes = nodePrefixes;
+        this.value = value;
+        // Set initial information about ongoing update
+        this.reset();
+    }
+    reset() {
+        this.update = {
+            pending: false,
+            success: false,
+            value: null,
+        };
+    }
+    setSuccess(success = false) {
+        if (success) {
+            this.update.success = true;
+            this.value = this.update.value;
+        } else {
+            this.update.success = false;
+        }
+    }
+    setPending(value = null) {
+        this.reset();
+        this.update.pending = true;
+        this.update.success = false;
+        this.update.value = value;
+    }
+    setPendingWithCurrent() {
+        this.setPending(this.value);
+    }
+    get isPending() {
+        return this.update.pending === true;
+    }
+    get isSuccess() {
+        return this.update.success === true;
+    }
+}
+
+/**
+ * CameraData - Represents the state and metadata of a camera in the 3D viewer.
+ *
+ * Responsibilities:
+ *  - Tracks camera name, value, and locked status.
+ *  - Manages update state for asynchronous operations (pending, success, etc.).
+ *  - Provides methods to reset, set pending, and set success states.
+ *
+ * Usage:
+ *  - Instantiate with a name and optional value: new CameraData("camera", value, locked)
+ *  - Use setPending(), setSuccess(), and reset() to manage update state.
+ *  - Access status via isPending, isSuccess getters.
+ */
+export class CameraData {
+    constructor(name = "", value = null, locked = true) {
+        this.name = name;
+        this.value = value;
+        this.locked = locked;
+        // Set initial information about ongoing update
+        this.reset();
+    }
+    reset() {
+        this.update = {
+            pending: false,
+            success: false,
+            value: null,
+        };
+    }
+    setSuccess(success = false) {
+        if (success) {
+            this.update.success = true;
+            this.value = this.update.value;
+        } else {
+            this.update.success = false;
+        }
+    }
+    setPending(value = undefined, locked = true) {
+        this.reset();
+        if (value === undefined) {
+            return;
+        }
+        if (value === null) {
+            locked = false;
+        }
+        this.update.pending = true;
+        this.update.success = false;
+        this.update.value = value;
+        this.update.locked = locked;
+    }
+    get isPending() {
+        return this.update.pending === true;
+    }
+    get isSuccess() {
+        return this.update.success === true;
+    }
+}