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

package/src/index.js

@@ -1,38 +1,75 @@
 import { PrefViewer2D } from "./pref-viewer-2d.js";
 import { PrefViewer3D } from "./pref-viewer-3d.js";
-import {PrefViewerTask} from "./pref-viewer-task.js";
+import { PrefViewerDialog } from "./pref-viewer-dialog.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)
- *  - setOptions(options)
+ *  - loadConfig(config): Loads a configuration object or JSON string.
+ *  - loadModel(model): Loads a model object or JSON string.
+ *  - loadScene(scene): Loads a scene/environment object or JSON string.
+ *  - loadMaterials(materials): Loads materials object or JSON string.
+ *  - loadDrawing(drawing): Loads a drawing object or JSON string.
+ *  - setOptions(options): Sets viewer options from an object or JSON string.
  *  - setMode(mode): Sets the viewer mode to "2d" or "3d" and updates component visibility.
- *  - showModel(), hideModel(), showScene(), hideScene()
- *  - downloadModelGLB(), downloadModelUSDZ(), downloadModelAndSceneGLB(), downloadModelAndSceneUSDZ()
+ *  - showModel(): Shows the 3D model.
+ *  - hideModel(): Hides the 3D model.
+ *  - showScene(): Shows the 3D environment/scene.
+ *  - hideScene(): Hides the 3D environment/scene.
+ *  - zoomCenter(): Centers the 2D drawing view.
+ *  - zoomExtentsAll(): Zooms the 2D drawing to fit all content.
+ *  - zoomIn(): Zooms in on the 2D drawing.
+ *  - zoomOut(): Zooms out of the 2D drawing.
+ *  - downloadModelGLB(): Downloads the current 3D model as a GLB file.
+ *  - downloadModelGLTF(): Downloads the current 3D model as a glTF ZIP file.
+ *  - downloadModelUSDZ(): Downloads the current 3D model as a USDZ file.
+ *  - downloadModelAndSceneGLB(): Downloads both the model and scene as a GLB file.
+ *  - downloadModelAndSceneGLTF(): Downloads both the model and scene as a glTF ZIP file.
+ *  - downloadModelAndSceneUSDZ(): Downloads both the model and scene as a USDZ file.
+ *  - downloadSceneGLB(): Downloads the environment as a GLB file.
+ *  - downloadSceneGLTF(): Downloads the environment as a glTF ZIP file.
+ *  - downloadSceneUSDZ(): Downloads the environment as a USDZ file.
+ *  - openDialog(title, content, footer): Opens a modal dialog with the specified title, content, and footer.
+ *  - closeDialog(): Closes the currently open dialog, if any, and removes it from the DOM.
  *
  * 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.
@@ -47,8 +84,10 @@ class PrefViewer extends HTMLElement {
 
     #taskQueue = [];
 
+    #wrapper = null;
     #component2D = null;
     #component3D = null;
+    #dialog = null;
 
     /**
      * Creates a new PrefViewer instance and attaches a shadow DOM.
@@ -125,11 +164,19 @@ 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.
      */
     connectedCallback() {
+        this.#wrapper = document.createElement("div");
+        this.#wrapper.classList.add("pref-viewer-wrapper");
+        this.shadowRoot.append(this.#wrapper);
+
+        const style = document.createElement("style");
+        const cssUrl = new URL("./css/pref-viewer.css", import.meta.url);
+        style.textContent = `@import "${cssUrl}";`;
+        this.shadowRoot.append(style);
+
         this.#createComponent3D();
         this.#createComponent2D();
 
@@ -137,20 +184,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,7 +197,8 @@ class PrefViewer extends HTMLElement {
     #createComponent2D() {
         this.#component2D = document.createElement("pref-viewer-2d");
         this.#component2D.setAttribute("visible", "false");
-        this.shadowRoot.appendChild(this.#component2D);
+        this.#component2D.addEventListener("drawing-zoom-changed", this.#on2DZoomChanged.bind(this));
+        this.#wrapper.appendChild(this.#component2D);
     }
 
     /**
@@ -176,7 +210,7 @@ class PrefViewer extends HTMLElement {
     #createComponent3D() {
         this.#component3D = document.createElement("pref-viewer-3d");
         this.#component3D.setAttribute("visible", "false");
-        this.shadowRoot.appendChild(this.#component3D);
+        this.#wrapper.appendChild(this.#component3D);
     }
 
     /**
@@ -243,37 +277,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 +323,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 +408,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 +495,7 @@ class PrefViewer extends HTMLElement {
      * Public methods
      * ---------------------------
      */
-    
+
     /**
      * Sets the viewer mode to "2d" or "3d" and updates component visibility accordingly.
      * @public
@@ -448,18 +505,21 @@ 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") {
             this.#component3D?.hide();
             this.#component2D?.show();
         } else {
-            this.#component3D?.show();
             this.#component2D?.hide();
+            this.#component3D?.show();
         }
         if (this.getAttribute("mode") !== mode) {
             this.setAttribute("mode", mode);
+            if (this.#dialog) {
+                this.closeDialog();
+            }
         }
     }
 
@@ -595,6 +655,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.
@@ -609,6 +724,19 @@ class PrefViewer extends HTMLElement {
         this.#component3D.downloadModelGLB();
     }
 
+    /**
+     * Initiates download of the current 3D model in GLTF format.
+     * @public
+     * @returns {void}
+     */
+    downloadModelGLTF() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadModelGLTF();
+    }
+
     /**
      * Initiates download of the current 3D model in USDZ format.
      * @public
@@ -623,7 +751,33 @@ class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Initiates download of both the 3D model and scene in USDZ format.
+     * Initiates download of the current complete scene (3D model and environment) in GLB format.
+     * @public
+     * @returns {void}
+     */
+    downloadModelAndSceneGLB() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadModelAndSceneGLB();
+    }
+
+    /**
+     * Initiates download of the current complete scene (3D model and environment) in GLTF format.
+     * @public
+     * @returns {void}
+     */
+    downloadModelAndSceneGLTF() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadModelAndSceneGLTF();
+    }
+
+    /**
+     * Initiates download of the current complete scene (3D model and environment) in USDZ format.
      * @public
      * @returns {void}
      */
@@ -636,24 +790,88 @@ class PrefViewer extends HTMLElement {
     }
 
     /**
-     * Initiates download of both the 3D model and scene in GLB format.
+     * Initiates download of the current 3D environment in GLB format.
      * @public
      * @returns {void}
      */
-    downloadModelAndSceneGLB() {
+    downloadSceneGLB() {
         if (!this.#component3D) {
             return;
         }
 
-        this.#component3D.downloadModelAndSceneGLB();
+        this.#component3D.downloadSceneGLB();
     }
 
+    /**
+     * Initiates download of the current 3D environment in GLTF format.
+     * @public
+     * @returns {void}
+     */
+    downloadSceneGLTF() {
+        if (!this.#component3D) {
+            return;
+        }
+
+        this.#component3D.downloadSceneGLTF();
+    }
+
+    /**
+     * Initiates download of the current 3D environment in USDZ format.
+     * @public
+     * @returns {void}
+     */
+    downloadSceneUSDZ() {
+        if (!this.#component3D) {
+            return;
+        }
+        this.#component3D.downloadSceneUSDZ();
+    }
+
+    /**
+     * Opens a modal dialog with the specified title, content, and footer.
+     * @public
+     * @param {string} title - The dialog title to display in the header.
+     * @param {string} content - The HTML content to display in the dialog body.
+     * @param {string} footer - The HTML content to display in the dialog footer (e.g., action buttons).
+     * @returns {HTMLElement} The created dialog element.
+     * @description
+     * If a dialog is already open, it is closed before opening the new one.
+     * The dialog is appended to the viewer's shadow DOM and returned for further manipulation.
+     */
+    openDialog(title, content, footer) {
+        if (this.#dialog && this.#dialog.hasAttribute("open")) {
+            this.#dialog.close();
+        }
+        this.#dialog = document.createElement("pref-viewer-dialog");
+        this.shadowRoot.querySelector(".pref-viewer-wrapper").appendChild(this.#dialog);
+        const opened = this.#dialog.open(title, content, footer);
+        return opened ? this.#dialog : null;
+    }
+
+    /**
+     * Closes the currently open dialog, if any, and removes it from the DOM.
+     * @public
+     * @returns {void}
+     */
+    closeDialog() {
+        if (this.#dialog) {
+            this.#dialog.close();
+            this.#dialog = null;
+        }
+    }
+
+    /**
+     * ---------------------------
+     * Public properties
+     * ---------------------------
+     */
+
     /**
      * Indicates whether the viewer has been initialized.
      * @public
      * @returns {boolean} True if initialized; otherwise, false.
      */
-    get initialized() {
+    get isInitialized() {
         return this.#isInitialized;
     }
 
@@ -662,7 +880,7 @@ class PrefViewer extends HTMLElement {
      * @public
      * @returns {boolean} True if loaded; otherwise, false.
      */
-    get loaded() {
+    get isLoaded() {
         return this.#isLoaded;
     }
 
@@ -671,11 +889,30 @@ 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);
 customElements.define("pref-viewer-3d", PrefViewer3D);
+customElements.define("pref-viewer-dialog", PrefViewerDialog);
 customElements.define("pref-viewer", PrefViewer);