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

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

@@ -1,6 +1,56 @@
 import { ContainerData, MaterialData, CameraData } from "./pref-viewer-3d-data.js";
 import BabylonJSController from "./babylonjs-controller.js";
 
+/**
+ * PrefViewer3D - Custom Web Component for interactive 3D visualization and configuration.
+ *
+ * Overview:
+ *  - Encapsulates a Babylon.js-powered 3D viewer for displaying models, environments, and materials.
+ *  - Manages internal state for containers (model, environment, materials) and options (camera, materials).
+ *  - Handles asset loading, configuration, and option updates through attributes and public methods.
+ *  - Provides API for showing/hiding the viewer, model, and environment, and for downloading assets.
+ *  - Emits custom events for loading, loaded, and option-setting states.
+ *
+ * Usage:
+ *  - Use as a custom HTML element: <pref-viewer-3d ...>
+ *  - Configure via attributes (config, options, show-model, show-scene, visible).
+ *  - Control viewer state and assets via public methods.
+ *
+ * Observed Attributes:
+ *  - show-model: Show or hide the 3D model ("true"/"false").
+ *  - show-scene: Show or hide the 3D environment ("true"/"false").
+ *  - visible: Show or hide the entire viewer ("true"/"false").
+ *
+ * Public Methods:
+ *  - show(): Shows the 3D viewer component.
+ *  - hide(): Hides the 3D viewer component.
+ *  - load(config): Loads the provided configuration into the viewer.
+ *  - setOptions(options): Sets viewer options such as camera and materials.
+ *  - showModel(): Shows the 3D model.
+ *  - hideModel(): Hides the 3D model.
+ *  - showEnvironment(): Shows the 3D environment/scene.
+ *  - hideEnvironment(): Hides the 3D environment/scene.
+ *  - downloadModelGLB(): Downloads the current 3D model as a GLB file.
+ *  - downloadModelUSDZ(): Downloads the current 3D model as a USDZ file.
+ *  - downloadModelAndSceneGLB(): Downloads both the model and scene as a GLB file.
+ *  - downloadModelAndSceneUSDZ(): Downloads both the model and scene as a USDZ file.
+ *
+ * Public Properties:
+ *  - isInitialized: Indicates whether the component has completed initialization.
+ *  - isLoaded: Indicates whether the GLTF/GLB content is loaded and ready.
+ *  - isVisible: Indicates whether the component is currently visible.
+ *
+ * Events:
+ *  - "scene-loading": Dispatched when a loading operation starts.
+ *  - "scene-loaded": Dispatched when a loading operation completes.
+ *  - "scene-setting-options": Dispatched when viewer options are being set.
+ *  - "scene-set-options": Dispatched when viewer options have been set.
+ *
+ * Notes:
+ *  - Internal state and heavy initialization are handled in connectedCallback.
+ *  - Designed for extensibility and integration in product configurators and visualization tools.
+ *  - All resource management and rendering operations are performed asynchronously for performance.
+ */
 export class PrefViewer3D extends HTMLElement {
     // State flags
     #isInitialized = false;
@@ -15,7 +65,7 @@ export class PrefViewer3D extends HTMLElement {
     #babylonJSController = null; // BabylonJSController instance
 
     /**
-     * Create a new instance of the 2D viewer component.
+     * Create a new instance of the 3D viewer component.
      * The constructor only calls super(); heavy initialization happens in connectedCallback.
      */
     constructor() {
@@ -27,31 +77,22 @@ export class PrefViewer3D extends HTMLElement {
      * @returns {string[]} Array of attribute names that trigger attributeChangedCallback.
      */
     static get observedAttributes() {
-        return ["config", "options", "show-model", "show-scene", "visible"];
+        return ["show-model", "show-scene", "visible"];
     }
 
     /**
-     * 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.
+     * - "show-model": shows or hides the model according to the attribute value ("true"/"false").
+     * - "show-scene": shows or hides the scene according to the attribute value ("true"/"false").
      * - "visible": shows or hides the component according to the attribute value ("true"/"false").
      */
     attributeChangedCallback(name, _old, value) {
         switch (name) {
-            case "visible":
-                if (_old === value) {
-                    return;
-                }
-                if (value === "true" && this.#isVisible === false) {
-                    this.show();
-                } else if (value === "false" && this.#isVisible === true) {
-                    this.hide();
-                }
-                break;
             case "show-model":
                 if (_old === value) {
                     return;
@@ -66,12 +107,23 @@ export class PrefViewer3D extends HTMLElement {
                 const showScene = value.toLowerCase?.() === "true";
                 showScene ? this.showEnvironment() : this.hideEnvironment();
                 break;
+            case "visible":
+                if (_old === value) {
+                    return;
+                }
+                if (value === "true" && this.#isVisible === false) {
+                    this.show();
+                } else if (value === "false" && this.#isVisible === true) {
+                    this.hide();
+                }
+                break;
         }
     }
 
     /**
-     * Called when the element is inserted into the DOM.
-     * Sets up DOM nodes, initial visibility and starts loading the SVG if provided.
+     * Called when the element is added to the DOM.
+     * Creates the DOM structure, sets initial visibility, initializes component data, and sets up the BabylonJSController.
+     * Performs heavy initialization tasks required for the 3D viewer.
      * @returns {void}
      */
     connectedCallback() {
@@ -81,6 +133,11 @@ export class PrefViewer3D extends HTMLElement {
         this.#initializeBabylonJS();
     }
 
+    /**
+     * Called when the element is removed from the DOM.
+     * Disables the BabylonJSController to clean up resources and event listeners associated with the 3D viewer.
+     * @returns {void}
+     */
     disconnectedCallback() {
         if (this.#babylonJSController) {
             this.#babylonJSController.disable();
@@ -113,6 +170,12 @@ export class PrefViewer3D extends HTMLElement {
         visible ? this.show() : this.hide();
     }
 
+    /**
+     * Initializes the internal data structure for containers and options used by the 3D viewer.
+     * Sets up default states for model, environment, materials, camera, and material options.
+     * @private
+     * @returns {void}
+     */
     #initializeData() {
         this.#data = {
             containers: {
@@ -132,17 +195,34 @@ export class PrefViewer3D extends HTMLElement {
         };
     }
 
+    /**
+     * Initializes the BabylonJSController and enables the Babylon.js engine for rendering.
+     * @private
+     * @returns {void}
+     */
     #initializeBabylonJS() {
         this.#babylonJSController = new BabylonJSController(this.#canvas, this.#data.containers, this.#data.options);
         this.#babylonJSController.enable();
     }
 
+    /**
+     * Resets update flags for all containers and material/camera options after loading or setting options.
+     * @private
+     * @returns {void}
+     */
     #resetUpdateFlags() {
-        Object.values(this.#data.containers).forEach(container => container.reset());
-        Object.values(this.#data.options.materials).forEach(material => material.reset());
+        Object.values(this.#data.containers).forEach((container) => container.reset());
+        Object.values(this.#data.options.materials).forEach((material) => material.reset());
         this.#data.options.camera.reset();
     }
 
+    /**
+     * Checks if any container (model, environment, materials) needs to be updated based on the provided config.
+     * Sets pending state for containers if storage or visibility changes are detected.
+     * @private
+     * @param {object} config - Configuration object containing model, scene, and materials info.
+     * @returns {void}
+     */
     #checkNeedToUpdateContainers(config) {
         const modelState = this.#data.containers.model;
         const modelHasStorage = !!config.model?.storage;
@@ -170,6 +250,13 @@ export class PrefViewer3D extends HTMLElement {
         }
     }
 
+    /**
+     * Checks if the camera option needs to be updated based on the provided options.
+     * Sets pending state for the camera if a change is detected.
+     * @private
+     * @param {object} options - Options object containing camera info.
+     * @returns {boolean} True if camera needs update, false otherwise.
+     */
     #checkNeedToUpdateCamera(options) {
         if (!options || options.camera === undefined || options.camera === "") {
             return false;
@@ -182,6 +269,13 @@ export class PrefViewer3D extends HTMLElement {
         return needUpdate;
     }
 
+    /**
+     * Checks if any material option needs to be updated based on the provided options.
+     * Sets pending state for materials if changes are detected.
+     * @private
+     * @param {object} options - Options object containing material info.
+     * @returns {boolean} True if any material needs update, false otherwise.
+     */
     #checkNeedToUpdateMaterials(options) {
         if (!options) {
             return false;
@@ -201,24 +295,34 @@ export class PrefViewer3D extends HTMLElement {
         return someNeedUpdate;
     }
 
-    
+    /**
+     * Dispatches a "prefviewer3d-loading" event and updates loading state attributes.
+     * Used internally when a loading operation starts.
+     * @private
+     * @returns {void}
+     */
     #onLoading() {
-        this.dispatchEvent(
-            new CustomEvent("prefviewer3d-loading", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            })
-        );
-        
+        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
+        };
+        this.dispatchEvent(new CustomEvent("scene-loading", customEventOptions));
+
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
-        
+
         if (this.#isLoaded === true) {
             this.#isLoaded = false;
         }
     }
-    
+
+    /**
+     * Dispatches a "prefviewer3d-loaded" event with details about what was loaded and updates state attributes.
+     * Used internally when a loading operation completes.
+     * @private
+     * @returns {object} Detail object describing what was tried and what succeeded.
+     */
     #onLoaded() {
         const toLoadDetail = {
             container_model: this.#data.containers.model.isPending,
@@ -245,42 +349,52 @@ export class PrefViewer3D extends HTMLElement {
             success: loadedDetail,
         };
 
-        this.dispatchEvent(
-            new CustomEvent("prefviewer3d-loaded", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-                detail: detail,
-            })
-        );
-        
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+            detail: detail,
+        };
+        this.dispatchEvent(new CustomEvent("scene-loaded", customEventOptions));
+
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
-        
+
         this.#resetUpdateFlags();
         this.#isLoaded = true;
 
         return detail;
     }
 
+    /**
+     * Dispatches a "prefviewer3d-setting-options" event and updates loading state attributes.
+     * Used internally when options are being set.
+     * @private
+     * @returns {void}
+     */
     #onSettingOptions() {
-        this.dispatchEvent(
-            new CustomEvent("prefviewer3d-setting-options", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            })
-        );
-        
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+        };
+        this.dispatchEvent(new CustomEvent("scene-setting-options", customEventOptions));
+
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
-        
+
         if (this.#isLoaded === true) {
             this.#isLoaded = false;
         }
     }
-    
-    #onSettedOptions() {
+
+    /**
+     * Dispatches a "prefviewer3d-loaded" event with details about what options were set and updates state attributes.
+     * Used internally when options have been set.
+     * @private
+     * @returns {object} Detail object describing what was tried and what succeeded.
+     */
+    #onSetOptions() {
         const toSetDetail = {
             camera: this.#data.options.camera.isPending,
             innerWallMaterial: this.#data.options.materials.innerWall.isPending,
@@ -299,19 +413,18 @@ export class PrefViewer3D extends HTMLElement {
             tried: toSetDetail,
             success: settedDetail,
         };
-
-        this.dispatchEvent(
-            new CustomEvent("prefviewer3d-loaded", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-                detail: detail,
-            })
-        );
         
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+            detail: detail,
+        };
+        this.dispatchEvent(new CustomEvent("scene-set-options", customEventOptions));
+
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
-        
+
         this.#resetUpdateFlags();
         this.#isLoaded = true;
 
@@ -322,22 +435,40 @@ export class PrefViewer3D extends HTMLElement {
      * ---------------------------
      * Public methods
      * ---------------------------
-    */
+     */
+
+    /**
+     * Hides the 3D viewer component by updating its visibility state and DOM attribute.
+     * @public
+     * @returns {void}
+     */
     hide() {
-       this.#isVisible = false;
-       this.setAttribute("visible", "false");
+        this.#isVisible = false;
+        this.setAttribute("visible", "false");
     }
-    
+
+    /**
+     * Shows the 3D viewer component by updating its visibility state and DOM attribute.
+     * @public
+     * @returns {void}
+     */
     show() {
         this.#isVisible = true;
         this.setAttribute("visible", "true");
     }
 
+    /**
+     * Loads the provided configuration into the 3D viewer.
+     * Updates containers and options, triggers loading events, and returns the loading result.
+     * @public
+     * @param {object} config - Configuration object containing containers and options.
+     * @returns {Promise<object>} Resolves with an object containing success and error status and loading details.
+     */
     async load(config) {
         if (!this.#babylonJSController) {
             return;
         }
-        
+
         this.#onLoading();
 
         // Containers
@@ -349,11 +480,18 @@ export class PrefViewer3D extends HTMLElement {
             this.#checkNeedToUpdateMaterials(config.options);
         }
 
-        const success = await this.#babylonJSController.load();
-        
-        return { success: success, detail: this.#onLoaded() };
+        const loadDetail = await this.#babylonJSController.load();
+
+        return { ...loadDetail, load: this.#onLoaded() };
     }
 
+    /**
+     * Sets viewer options such as camera and materials.
+     * Updates internal states, triggers option setting events, and returns the result.
+     * @public
+     * @param {object} options - Options object containing camera and material settings.
+     * @returns {object} Object containing success status and details of set options.
+     */
     setOptions(options) {
         if (!this.#babylonJSController) {
             return;
@@ -368,10 +506,15 @@ export class PrefViewer3D extends HTMLElement {
         if (this.#checkNeedToUpdateMaterials(options)) {
             someSetted = someSetted || this.#babylonJSController.setMaterialOptions();
         }
-        const detail = this.#onSettedOptions();
-        return {success: someSetted, detail: detail};
+        const detail = this.#onSetOptions();
+        return { success: someSetted, detail: detail };
     }
 
+    /**
+     * Shows the 3D model within the viewer.
+     * @public
+     * @returns {void}
+     */
     showModel() {
         if (!this.#babylonJSController) {
             return;
@@ -379,6 +522,11 @@ export class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.setContainerVisibility("model", true);
     }
 
+    /**
+     * Hides the 3D model within the viewer.
+     * @public
+     * @returns {void}
+     */
     hideModel() {
         if (!this.#babylonJSController) {
             return;
@@ -386,6 +534,11 @@ export class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.setContainerVisibility("model", false);
     }
 
+    /**
+     * Shows the 3D environment/scene within the viewer.
+     * @public
+     * @returns {void}
+     */
     showEnvironment() {
         if (!this.#babylonJSController) {
             return;
@@ -393,6 +546,11 @@ export class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.setContainerVisibility("environment", true);
     }
 
+    /**
+     * Hides the 3D environment/scene within the viewer.
+     * @public
+     * @returns {void}
+     */
     hideEnvironment() {
         if (!this.#babylonJSController) {
             return;
@@ -400,6 +558,11 @@ export class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.setContainerVisibility("environment", false);
     }
 
+    /**
+     * Downloads the current 3D model as a GLB file.
+     * @public
+     * @returns {void}
+     */
     downloadModelGLB() {
         if (!this.#babylonJSController) {
             return;
@@ -407,6 +570,11 @@ export class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.downloadModelGLB();
     }
 
+    /**
+     * Downloads the current 3D model as a USDZ file.
+     * @public
+     * @returns {void}
+     */
     downloadModelUSDZ() {
         if (!this.#babylonJSController) {
             return;
@@ -414,6 +582,11 @@ export class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.downloadModelUSDZ();
     }
 
+    /**
+     * Downloads both the 3D model and scene as a USDZ file.
+     * @public
+     * @returns {void}
+     */
     downloadModelAndSceneUSDZ() {
         if (!this.#babylonJSController) {
             return;
@@ -421,6 +594,11 @@ export class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.downloadModelAndSceneUSDZ();
     }
 
+    /**
+     * Downloads both the 3D model and scene as a GLB file.
+     * @public
+     * @returns {void}
+     */
     downloadModelAndSceneGLB() {
         if (!this.#babylonJSController) {
             return;
@@ -433,7 +611,7 @@ export class PrefViewer3D extends HTMLElement {
      * @public
      * @returns {boolean} True if the component is initialized; otherwise, false.
      */
-    get initialized() {
+    get isInitialized() {
         return this.#isInitialized;
     }
 
@@ -442,7 +620,7 @@ export class PrefViewer3D extends HTMLElement {
      * @public
      * @returns {boolean} True if the GLTF/GLB is loaded; otherwise, false.
      */
-    get loaded() {
+    get isLoaded() {
         return this.#isLoaded;
     }
 
@@ -451,7 +629,7 @@ export class PrefViewer3D extends HTMLElement {
      * @public
      * @returns {boolean} True if the component is visible; otherwise, false.
      */
-    get visible() {
+    get isVisible() {
         return this.#isVisible;
     }
 }