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

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

@@ -0,0 +1,635 @@
+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;
+    #isLoaded = false;
+    #isVisible = false;
+
+    #wrapper = null;
+    #canvas = null;
+
+    #data = null; // Component data
+
+    #babylonJSController = null; // BabylonJSController instance
+
+    /**
+     * Create a new instance of the 3D 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 ["show-model", "show-scene", "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
+     * - "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 "show-model":
+                if (_old === value) {
+                    return;
+                }
+                const showModel = value.toLowerCase?.() === "true";
+                showModel ? this.showModel() : this.hideModel();
+                break;
+            case "show-scene":
+                if (_old === value) {
+                    return;
+                }
+                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 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() {
+        this.#createDOMElements();
+        this.#setInitialVisibility();
+        this.#initializeData();
+        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();
+        }
+    }
+
+    /**
+     * Create DOM structure and basic styles used by the component.
+     * @private
+     * @returns {void}
+     */
+    #createDOMElements() {
+        this.#wrapper = document.createElement("div");
+        this.append(this.#wrapper);
+        this.#canvas = document.createElement("canvas");
+        this.#wrapper.appendChild(this.#canvas);
+        const style = document.createElement("style");
+        style.textContent = `pref-viewer-3d[visible="true"] { display: block; } pref-viewer-3d[visible="false"] { display: none; } pref-viewer-3d, pref-viewer-3d > div, pref-viewer-3d > div > canvas { width: 100%; height: 100%; display: block; position: relative; outline: none; box-sizing: border-box; }`;
+        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 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: {
+                model: new ContainerData("model"),
+                environment: new ContainerData("environment"),
+                materials: new ContainerData("materials"),
+            },
+            options: {
+                camera: new CameraData("activeCamera", null, true),
+                materials: {
+                    innerWall: new MaterialData("innerWall", undefined, undefined, ["innerWall"]),
+                    outerWall: new MaterialData("outerWall", undefined, undefined, ["outerWall"]),
+                    innerFloor: new MaterialData("innerFloor", undefined, undefined, ["innerFloor"]),
+                    outerFloor: new MaterialData("outerFloor", undefined, undefined, ["outerFloor"]),
+                },
+            },
+        };
+    }
+
+    /**
+     * 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());
+        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;
+        const modelNeedToChangeVisibility = config.model?.visible !== undefined && config.model?.visible !== modelState.show;
+        if (modelHasStorage) {
+            modelState.setPending(modelHasStorage ? config.model.storage : null, modelNeedToChangeVisibility ? config.model.visible : undefined);
+        } else if (modelNeedToChangeVisibility) {
+            modelState.show = config.model.visible;
+        }
+
+        const environmentState = this.#data.containers.environment;
+        const environmentHasStorage = !!config.scene?.storage;
+        const environmentNeedToChangeVisibility = config.scene?.visible !== undefined && config.scene?.visible !== environmentState.show;
+        if (environmentHasStorage) {
+            environmentState.setPending(environmentHasStorage ? config.scene.storage : null, environmentNeedToChangeVisibility ? config.scene.visible : undefined);
+        } else if (environmentNeedToChangeVisibility) {
+            environmentState.show = config.scene.visible;
+        }
+
+        // Materials container. Visibility is not established for this container because it does not contain geometry.
+        const materialsState = this.#data.containers.materials;
+        const materialsHasStorage = !!config.materials?.storage;
+        if (materialsHasStorage) {
+            materialsState.setPending(materialsHasStorage ? config.materials.storage : null, null);
+        }
+    }
+
+    /**
+     * 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;
+        }
+        const cameraState = this.#data.options.camera;
+        const needUpdate = options.camera !== cameraState.value;
+        if (needUpdate) {
+            cameraState.setPending(options.camera);
+        }
+        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;
+        }
+        let someNeedUpdate = false;
+        Object.keys(this.#data.options.materials).forEach((material) => {
+            const key = `${material}Material`;
+            const materialState = this.#data.options.materials[material];
+            const previousValue = materialState.value;
+            const incomingValue = options[key];
+            const needUpdate = !!incomingValue && incomingValue !== previousValue;
+            if (needUpdate) {
+                materialState.setPending(incomingValue);
+            }
+            someNeedUpdate = someNeedUpdate || needUpdate;
+        });
+        return someNeedUpdate;
+    }
+
+    /**
+     * Dispatches a "prefviewer3d-loading" event and updates loading state attributes.
+     * Used internally when a loading operation starts.
+     * @private
+     * @returns {void}
+     */
+    #onLoading() {
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+        };
+        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,
+            container_scene: this.#data.containers.environment.isPending,
+            container_materials: this.#data.containers.materials.isPending,
+            options_camera: this.#data.options.camera.isPending,
+            options_material_innerWall: this.#data.options.materials.innerWall.isPending,
+            options_material_outerWall: this.#data.options.materials.outerWall.isPending,
+            options_material_innerFloor: this.#data.options.materials.innerFloor.isPending,
+            options_material_outerFloor: this.#data.options.materials.outerFloor.isPending,
+        };
+        const loadedDetail = {
+            container_model: this.#data.containers.model.isSuccess,
+            container_scene: this.#data.containers.environment.isSuccess,
+            container_materials: this.#data.containers.materials.isSuccess,
+            options_camera: this.#data.options.camera.isSuccess,
+            options_material_innerWall: this.#data.options.materials.innerWall.isSuccess,
+            options_material_outerWall: this.#data.options.materials.outerWall.isSuccess,
+            options_material_innerFloor: this.#data.options.materials.innerFloor.isSuccess,
+            options_material_outerFloor: this.#data.options.materials.outerFloor.isSuccess,
+        };
+        const detail = {
+            tried: toLoadDetail,
+            success: loadedDetail,
+        };
+
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            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() {
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+        };
+        this.dispatchEvent(new CustomEvent("scene-setting-options", customEventOptions));
+
+        this.removeAttribute("loaded");
+        this.setAttribute("loading", "");
+
+        if (this.#isLoaded === true) {
+            this.#isLoaded = false;
+        }
+    }
+
+    /**
+     * 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,
+            outerWallMaterial: this.#data.options.materials.outerWall.isPending,
+            innerFloorMaterial: this.#data.options.materials.innerFloor.isPending,
+            outerFloorMaterial: this.#data.options.materials.outerFloor.isPending,
+        };
+        const settedDetail = {
+            camera: this.#data.options.camera.isSuccess,
+            innerWallMaterial: this.#data.options.materials.innerWall.isSuccess,
+            outerWallMaterial: this.#data.options.materials.outerWall.isSuccess,
+            innerFloorMaterial: this.#data.options.materials.innerFloor.isSuccess,
+            outerFloorMaterial: this.#data.options.materials.outerFloor.isSuccess,
+        };
+        const detail = {
+            tried: toSetDetail,
+            success: settedDetail,
+        };
+        
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail: detail,
+        };
+        this.dispatchEvent(new CustomEvent("scene-set-options", customEventOptions));
+
+        this.removeAttribute("loading");
+        this.setAttribute("loaded", "");
+
+        this.#resetUpdateFlags();
+        this.#isLoaded = true;
+
+        return detail;
+    }
+
+    /**
+     * ---------------------------
+     * 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");
+    }
+
+    /**
+     * 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
+        this.#checkNeedToUpdateContainers(config);
+
+        // Options
+        if (config.options) {
+            this.#checkNeedToUpdateCamera(config.options);
+            this.#checkNeedToUpdateMaterials(config.options);
+        }
+
+        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;
+        }
+
+        this.#onSettingOptions();
+
+        let someSetted = false;
+        if (this.#checkNeedToUpdateCamera(options)) {
+            someSetted = someSetted || this.#babylonJSController.setCameraOptions();
+        }
+        if (this.#checkNeedToUpdateMaterials(options)) {
+            someSetted = someSetted || this.#babylonJSController.setMaterialOptions();
+        }
+        const detail = this.#onSetOptions();
+        return { success: someSetted, detail: detail };
+    }
+
+    /**
+     * Shows the 3D model within the viewer.
+     * @public
+     * @returns {void}
+     */
+    showModel() {
+        if (!this.#babylonJSController) {
+            return;
+        }
+        this.#babylonJSController.setContainerVisibility("model", true);
+    }
+
+    /**
+     * Hides the 3D model within the viewer.
+     * @public
+     * @returns {void}
+     */
+    hideModel() {
+        if (!this.#babylonJSController) {
+            return;
+        }
+        this.#babylonJSController.setContainerVisibility("model", false);
+    }
+
+    /**
+     * Shows the 3D environment/scene within the viewer.
+     * @public
+     * @returns {void}
+     */
+    showEnvironment() {
+        if (!this.#babylonJSController) {
+            return;
+        }
+        this.#babylonJSController.setContainerVisibility("environment", true);
+    }
+
+    /**
+     * Hides the 3D environment/scene within the viewer.
+     * @public
+     * @returns {void}
+     */
+    hideEnvironment() {
+        if (!this.#babylonJSController) {
+            return;
+        }
+        this.#babylonJSController.setContainerVisibility("environment", false);
+    }
+
+    /**
+     * Downloads the current 3D model as a GLB file.
+     * @public
+     * @returns {void}
+     */
+    downloadModelGLB() {
+        if (!this.#babylonJSController) {
+            return;
+        }
+        this.#babylonJSController.downloadModelGLB();
+    }
+
+    /**
+     * Downloads the current 3D model as a USDZ file.
+     * @public
+     * @returns {void}
+     */
+    downloadModelUSDZ() {
+        if (!this.#babylonJSController) {
+            return;
+        }
+        this.#babylonJSController.downloadModelUSDZ();
+    }
+
+    /**
+     * Downloads both the 3D model and scene as a USDZ file.
+     * @public
+     * @returns {void}
+     */
+    downloadModelAndSceneUSDZ() {
+        if (!this.#babylonJSController) {
+            return;
+        }
+        this.#babylonJSController.downloadModelAndSceneUSDZ();
+    }
+
+    /**
+     * Downloads both the 3D model and scene as a GLB file.
+     * @public
+     * @returns {void}
+     */
+    downloadModelAndSceneGLB() {
+        if (!this.#babylonJSController) {
+            return;
+        }
+        this.#babylonJSController.downloadModelAndSceneGLB();
+    }
+
+    /**
+     * 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 GLTF/GLB content is loaded and ready.
+     * @public
+     * @returns {boolean} True if the GLTF/GLB 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-task.js

@@ -0,0 +1,54 @@
+/**
+ * PrefViewerTask - Represents a single task or operation to be processed by the PrefViewer.
+ *
+ * Responsibilities:
+ *  - Encapsulates the payload and type of a viewer task (e.g., loading a model, updating materials).
+ *  - Validates the task type against a predefined set of allowed types.
+ *  - Provides an immutable instance to ensure task integrity.
+ *
+ * Usage:
+ *  - Instantiate with a value and a type:
+ *      new PrefViewerTask(data, PrefViewerTask.Types.Model)
+ *  - Access the payload via the `value` property and the normalized type via the `type` property.
+ *
+ * Static Properties:
+ *  - Types: An object containing all allowed task types as string constants.
+ *
+ * Constructor:
+ *  - Validates the type (case-insensitive) and throws a TypeError if invalid.
+ *  - Freezes the instance to prevent further modification.
+ */
+export class PrefViewerTask {
+    static Types = Object.freeze({
+        Config: "config",
+        Drawing: "drawing",
+        Environment: "environment",
+        Materials: "materials",
+        Model: "model",
+        Options: "options",
+        Visibility: "visibility",
+    });
+
+    /**
+     * Creates a new PrefViewerTask instance.
+     * Validates that the provided type matches one of the allowed task types (case-insensitive).
+     * If the type is invalid, throws a TypeError.
+     * The instance is frozen to prevent further modification.
+     *
+     * @param {*} value - The payload or data associated with the task.
+     * @param {string} type - The type of task; must match one of PrefViewerTask.Types values.
+     * @throws {TypeError} If the type is not valid.
+     */
+    constructor(value, type) {
+        this.value = value;
+
+        const t = typeof type === "string" ? type.toLowerCase() : String(type).toLowerCase();
+        const allowed = Object.values(PrefViewerTask.Types);
+        if (!allowed.includes(t)) {
+            throw new TypeError(`PrefViewerTask: invalid type "${type}". Allowed types: ${allowed.join(", ")}`);
+        }
+        this.type = t;
+
+        Object.freeze(this);
+    }
+}