@preference-sl/pref-viewer 2.11.0-beta.1 → 2.11.0-beta.3

package/src/index.js

@@ -1,21 +1,32 @@
 import { PrefViewer2D } from "./pref-viewer-2d.js";
 import { PrefViewer3D } from "./pref-viewer-3d.js";
-import {PrefViewerTask} from "./pref-viewer-task.js";
+import { PrefViewerTask } from "./pref-viewer-task.js";
 
 /**
- * PrefViewer - Custom Web Component for rendering and managing 2D and 3D product visualizations.
+ * PrefViewer - Custom Web Component for advanced 2D and 3D product visualization and configuration.
  *
  * Overview:
- *  - Encapsulates both 2D and 3D viewers using Babylon.js, supporting glTF/GLB models and environments.
- *  - Handles loading from remote URLs, Base64 data URIs, and IndexedDB sources.
+ *  - Encapsulates both 2D (SVG) and 3D (Babylon.js) viewers, supporting glTF/GLB models, environments, and drawings.
+ *  - Loads assets from remote URLs, Base64 data URIs, and IndexedDB sources.
  *  - Provides a unified API for loading models, scenes, drawings, materials, and configuration via attributes or methods.
  *  - Manages an internal task queue for sequential processing of viewer operations.
  *  - Emits custom events for loading, errors, and state changes to facilitate integration.
+ *  - Supports downloading models and scenes in GLB and USDZ formats.
+ *  - Automatically updates the viewer when reactive attributes change.
  *
  * Usage:
  *  - Use as a custom HTML element: <pref-viewer ...>
- *  - Configure via attributes (e.g., config, model, scene, materials, drawing, options).
- *  - Control visibility, downloads, and viewer mode via public methods.
+ *  - Configure via attributes (config, model, scene, materials, drawing, options, mode).
+ *  - Control viewer mode, visibility, and downloads via public methods.
+ *
+ * Reactive Attributes:
+ *  - config: URL or Base64 for configuration file.
+ *  - model: URL or Base64 for 3D model (glTF/GLB).
+ *  - scene: URL or Base64 for environment/scene (glTF/GLB).
+ *  - materials: URL or Base64 for materials definition.
+ *  - drawing: URL or Base64 for SVG drawing.
+ *  - options: JSON string for viewer options.
+ *  - mode: Viewer mode ("2d" or "3d").
  *
  * Public Methods:
  *  - loadConfig(config), loadModel(model), loadScene(scene), loadMaterials(materials), loadDrawing(drawing)
@@ -23,16 +34,21 @@ import {PrefViewerTask} from "./pref-viewer-task.js";
  *  - setMode(mode): Sets the viewer mode to "2d" or "3d" and updates component visibility.
  *  - showModel(), hideModel(), showScene(), hideScene()
  *  - downloadModelGLB(), downloadModelUSDZ(), downloadModelAndSceneGLB(), downloadModelAndSceneUSDZ()
+ *  - zoomCenter(), zoomExtentsAll(), zoomIn(), zoomOut()
  *
  * Public Properties:
- *  - initialized: Indicates if the viewer is initialized.
- *  - loaded: Indicates if the viewer has finished loading.
- *  - loading: Indicates if the viewer is currently loading.
+ *  - isInitialized: Indicates if the viewer is initialized.
+ *  - isLoaded: Indicates if the viewer has finished loading.
+ *  - isLoading: Indicates if the viewer is currently loading.
+ *  - isMode2D: Indicates if the viewer is in 2D mode.
+ *  - isMode3D: Indicates if the viewer is in 3D mode.
  *
  * Events:
- *  - "scene-loading": Dispatched when a loading operation starts.
- *  - "scene-loaded": Dispatched when a loading operation completes.
- *  - "scene-error": Dispatched when initialization fails.
+ *  - "scene-loading": Dispatched when a 3D loading operation starts.
+ *  - "scene-loaded": Dispatched when a 3D loading operation completes.
+ *  - "drawing-loading": Dispatched when a 2D drawing loading operation starts.
+ *  - "drawing-loaded": Dispatched when a 2D drawing loading operation completes.
+ *  - "drawing-zoom-changed": Dispatched when the 2D drawing zoom/pan state changes.
  *
  * Notes:
  *  - Automatically creates and manages 2D and 3D viewer components in its shadow DOM.
@@ -125,7 +141,6 @@ class PrefViewer extends HTMLElement {
     /**
      * Called when the element is inserted into the DOM.
      * Initializes the 3D and 2D viewer components and starts processing tasks.
-     * If the "config" attribute is missing, dispatches a "scene-error" event and stops initialization.
      * @public
      * @returns {void|boolean} Returns false if initialization fails; otherwise void.
      */
@@ -137,20 +152,6 @@ class PrefViewer extends HTMLElement {
             this.setMode();
         }
 
-        if (!this.hasAttribute("config")) {
-            const error = 'PrefViewer: provide "config" as a configuration object to initialize the viewer.';
-            console.error(error);
-            this.dispatchEvent(
-                new CustomEvent("scene-error", {
-                    bubbles: true,
-                    cancelable: false,
-                    composed: true,
-                    detail: { error: new Error(error) },
-                })
-            );
-            return false;
-        }
-
         this.#isInitialized = true;
         this.#processNextTask();
     }
@@ -164,6 +165,7 @@ class PrefViewer extends HTMLElement {
     #createComponent2D() {
         this.#component2D = document.createElement("pref-viewer-2d");
         this.#component2D.setAttribute("visible", "false");
+        this.#component2D.addEventListener("drawing-zoom-changed", this.#on2DZoomChanged.bind(this));
         this.shadowRoot.appendChild(this.#component2D);
     }
 
@@ -243,37 +245,38 @@ class PrefViewer extends HTMLElement {
 
         this.removeAttribute("loaded-3d");
         this.setAttribute("loading-3d", "");
-        this.dispatchEvent(
-            new CustomEvent("scene-loading", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            })
-        );
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+        };
+        this.dispatchEvent(new CustomEvent("scene-loading", customEventOptions));
     }
 
     /**
      * Handles the completion of a 3D loading operation.
      * Updates loading state, sets attributes, dispatches a "scene-loaded" event, and processes the next task.
      * @private
-     * @param {object} [detail={}] - Optional details to include in the event.
+     * @param {object} [detail] - Optional details to include in the event.
      * @returns {void}
      */
-    #on3DLoaded(detail = {}) {
-        this.dispatchEvent(
-            new CustomEvent("scene-loaded", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-                detail: detail,
-            })
-        );
+    #on3DLoaded(detail) {
+        this.#isLoaded = true;
+        this.#isLoading = false;
 
         this.removeAttribute("loading-3d");
         this.setAttribute("loaded-3d", "");
 
-        this.#isLoaded = true;
-        this.#isLoading = false;
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+        };
+        if (detail) {
+            customEventOptions.detail = detail;
+        }
+        this.dispatchEvent(new CustomEvent("scene-loaded", customEventOptions));
     }
 
     /**
@@ -288,35 +291,57 @@ class PrefViewer extends HTMLElement {
 
         this.removeAttribute("loaded-2d");
         this.setAttribute("loading-2d", "");
-        this.dispatchEvent(
-            new CustomEvent("drawing-loading", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            })
-        );
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions));
     }
 
     /**
      * Handles the completion of a 2D loading operation.
      * Updates loading state, sets attributes, dispatches a "drawing-loaded" event, and processes the next task.
      * @private
+     * @param {object} [detail] - Optional details to include in the event.
      * @returns {void}
      */
-    #on2DLoaded() {
-        this.dispatchEvent(
-            new CustomEvent("drawing-loaded", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            })
-        );
+    #on2DLoaded(detail) {
+        this.#isLoaded = true;
+        this.#isLoading = false;
 
         this.removeAttribute("loading-2d");
         this.setAttribute("loaded-2d", "");
 
-        this.#isLoaded = true;
-        this.#isLoading = false;
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+        };
+        if (detail) {
+            customEventOptions.detail = detail;
+        }
+        this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions));
+    }
+
+    /**
+     * Handles the "drawing-zoom-changed" event from the 2D viewer component.
+     * Dispatches a custom "drawing-zoom-changed" event from the PrefViewer element, forwarding the event detail to external listeners.
+     * @private
+     * @param {CustomEvent} event - The original zoom change event from the 2D viewer.
+     * @returns {void}
+     */
+    #on2DZoomChanged(event) {
+        event.stopPropagation();
+        event.preventDefault();
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            detail: event.detail,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-zoom-changed", customEventOptions));
     }
 
     /**
@@ -351,8 +376,8 @@ class PrefViewer extends HTMLElement {
         }
 
         this.#on2DLoading();
-        this.#component2D.load(drawing).then(() => {
-            this.#on2DLoaded();
+        this.#component2D.load(drawing).then((detail) => {
+            this.#on2DLoaded(detail);
             this.#processNextTask();
         });
     }
@@ -438,7 +463,7 @@ class PrefViewer extends HTMLElement {
      * Public methods
      * ---------------------------
      */
-    
+
     /**
      * Sets the viewer mode to "2d" or "3d" and updates component visibility accordingly.
      * @public
@@ -448,7 +473,7 @@ class PrefViewer extends HTMLElement {
     setMode(mode = this.#mode) {
         if (mode !== "2d" && mode !== "3d") {
             console.warn(`PrefViewer: invalid mode "${mode}". Allowed modes are "2d" and "3d".`);
-            return;
+            mode = this.#mode;
         }
         this.#mode = mode;
         if (mode === "2d") {
@@ -595,6 +620,61 @@ class PrefViewer extends HTMLElement {
         this.#addTaskToQueue(config, "visibility");
     }
 
+    /**
+     * Centers the 2D drawing view in the viewer.
+     * @public
+     * @returns {void}
+     * @description
+     * Only works when the viewer is in 2D mode. Pending implementation for 3D mode when active camera is not blocked.
+     */
+    zoomCenter() {
+        if (!this.#component2D || this.#mode !== "2d") {
+            return;
+        }
+        this.#component2D.zoomCenter();
+    }
+
+    /**
+     * Zooms the 2D drawing to fit all content within the viewer.
+     * @public
+     * @returns {void}
+     * @description
+     * Only works when the viewer is in 2D mode. Pending implementation for 3D mode when active camera is not blocked.
+     */
+    zoomExtentsAll() {
+        if (!this.#component2D || this.#mode !== "2d") {
+            return;
+        }
+        this.#component2D.zoomExtentsAll();
+    }
+
+    /**
+     * Zooms in on the 2D drawing.
+     * @public
+     * @returns {void}
+     * @description
+     * Only works when the viewer is in 2D mode. Pending implementation for 3D mode when active camera is not blocked.
+     */
+    zoomIn() {
+        if (!this.#component2D || this.#mode !== "2d") {
+            return;
+        }
+        this.#component2D.zoomIn();
+    }
+
+    /**
+     * Zooms out of the 2D drawing.
+     * @public
+     * @returns {void}
+     * @description
+     * Only works when the viewer is in 2D mode. Pending implementation for 3D mode when active camera is not blocked.
+     */
+    zoomOut() {
+        if (!this.#component2D || this.#mode !== "2d") {
+            return;
+        }
+        this.#component2D.zoomOut();
+    }
 
     /**
      * Initiates download of the current 3D model in GLB format.
@@ -653,7 +733,7 @@ class PrefViewer extends HTMLElement {
      * @public
      * @returns {boolean} True if initialized; otherwise, false.
      */
-    get initialized() {
+    get isInitialized() {
         return this.#isInitialized;
     }
 
@@ -662,7 +742,7 @@ class PrefViewer extends HTMLElement {
      * @public
      * @returns {boolean} True if loaded; otherwise, false.
      */
-    get loaded() {
+    get isLoaded() {
         return this.#isLoaded;
     }
 
@@ -671,9 +751,27 @@ class PrefViewer extends HTMLElement {
      * @public
      * @returns {boolean} True if loading; otherwise, false.
      */
-    get loading() {
+    get isLoading() {
         return this.#isLoading;
     }
+
+    /**
+     * Indicates whether the viewer is currently in 2D mode.
+     * @public
+     * @returns {boolean} True if the viewer is in 2D mode; otherwise, false.
+     */
+    get isMode2D() {
+        return this.#mode === "2d";
+    }
+
+    /**
+     * Indicates whether the viewer is currently in 3D mode.
+     * @public
+     * @returns {boolean} True if the viewer is in 3D mode; otherwise, false.
+     */
+    get isMode3D() {
+        return this.#mode === "3d";
+    }
 }
 
 customElements.define("pref-viewer-2d", PrefViewer2D);

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

@@ -21,12 +21,17 @@ import PanzoomController from "./panzoom-controller.js";
  *  - 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
- *  - "prefviewer2d-loading": emitted before loading starts
- *  - "prefviewer2d-loaded": emitted after content and Panzoom are ready
- *  - "prefviewer2d-error": emitted on validation/fetch errors (detail.error: Error)
- *  - "prefviewer2d-zoomchanged": emitted when pan/zoom state changes (detail: { moved, scaled, maximized, minimized })
+ *  - "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, ...).
@@ -80,10 +85,10 @@ export class PrefViewer2D extends HTMLElement {
     }
 
     /**
-     * Handle attribute changes.
-     * @param {string} name - Attribute name.
-     * @param {string|null} _old - Previous attribute value (unused).
-     * @param {string|null} value -New attribute value.
+     * 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.
@@ -119,6 +124,11 @@ export class PrefViewer2D extends HTMLElement {
         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();
@@ -203,20 +213,21 @@ export class PrefViewer2D extends HTMLElement {
     }
 
     /**
-     * Handle invalid or unsupported SVG input. Emits a custom error event.
+     * Handles invalid or unsupported SVG input by emitting a custom error event.
      * @private
-     * @returns {void}
+     * @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.";
-        this.dispatchEvent(
-            new CustomEvent("prefviewer2d-error", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-                detail: { error: new Error(error) },
-            })
-        );
+        const detail = { error: new Error(error) };
+        const customEventOptions = {
+            bubbles: true, // indicates whether the event bubbles up through the DOM tree or not
+            cancelable: true, // indicates whether the event can be canceled, and therefore prevented as if the event never happened
+            composed: false, // indicates whether or not the event will propagate across the shadow DOM boundary into the standard DOM
+            detail: detail,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-error", customEventOptions));
+        return detail;
     }
 
     /**
@@ -225,13 +236,12 @@ export class PrefViewer2D extends HTMLElement {
      * @returns {void}
      */
     #onLoaded() {
-        this.dispatchEvent(
-            new CustomEvent("prefviewer2d-loaded", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            })
-        );
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions));
 
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
@@ -246,13 +256,12 @@ export class PrefViewer2D extends HTMLElement {
      * @returns {void}
      */
     #onLoading() {
-        this.dispatchEvent(
-            new CustomEvent("prefviewer2d-loading", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            })
-        );
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions));
 
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
@@ -274,10 +283,20 @@ export class PrefViewer2D extends HTMLElement {
      * the UI with the enabled/disabled status of the zoomIn, zoomOut, center, and zoomExtentsAll buttons.
      */
     #onPanzoomChanged(state) {
-        this.dispatchEvent(
-            new CustomEvent("prefviewer2d-zoomchanged", {
-                bubbles: true,
-                cancelable: false,
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+            detail: state,
+        };
+        customEventOptions.detail.desde2d = "true";
+        this.dispatchEvent(new CustomEvent("drawing-zoom-changed", customEventOptions));
+    }
+
+    /**
+     * Subscribe DOM events required by Panzoom and keyboard interactions.
+     * @private
+     * @returns {void}
                 composed: true,
                 detail: state,
             })
@@ -325,17 +344,17 @@ export class PrefViewer2D extends HTMLElement {
      * @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<boolean|void>}
-     * - Resolves to false 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 true when the SVG was accepted and the component has started rendering.
+     * @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))) {
-            this.#onError();
-            return false;
+            const errorDetail = this.#onError();
+            return { success: false, ...errorDetail };
         }
-        this.#isInitialized && this.#loadSVG();
-        return true;
+        const success = this.#isInitialized && this.#loadSVG();
+        return { success: success, error: null };
     }
 
     /**
@@ -417,7 +436,7 @@ export class PrefViewer2D extends HTMLElement {
      * @public
      * @returns {boolean} True if the component is initialized; otherwise, false.
      */
-    get initialized() {
+    get isInitialized() {
         return this.#isInitialized;
     }
 
@@ -426,7 +445,7 @@ export class PrefViewer2D extends HTMLElement {
      * @public
      * @returns {boolean} True if the SVG is loaded; otherwise, false.
      */
-    get loaded() {
+    get isLoaded() {
         return this.#isLoaded;
     }
 
@@ -435,7 +454,7 @@ export class PrefViewer2D extends HTMLElement {
      * @public
      * @returns {boolean} True if the component is visible; otherwise, false.
      */
-    get visible() {
+    get isVisible() {
         return this.#isVisible;
     }
 }