@preference-sl/pref-viewer 2.13.0-beta.4 → 2.13.0-beta.6

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.13.0-beta.4",
+    "version": "2.13.0-beta.6",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {

package/src/babylonjs-animation-controller.js

@@ -43,11 +43,9 @@ export default class BabylonJSAnimationController {
      * @param {AssetContainer|Scene} assetContainer - The Babylon.js asset container or scene instance.
      */
     constructor(assetContainer) {
-        if (assetContainer instanceof AssetContainer || assetContainer instanceof Scene) {
-            this.#scene = assetContainer.scene ? assetContainer.scene : assetContainer;
-            this.#assetContainer = assetContainer;
-            this.#canvas = this.#scene._engine._renderingCanvas;
-        }
+        this.#scene = assetContainer.scene ? assetContainer.scene : assetContainer;
+        this.#assetContainer = assetContainer;
+        this.#canvas = this.#scene._engine._renderingCanvas;
         this.#initializeAnimations();
     }
 
@@ -163,7 +161,8 @@ export default class BabylonJSAnimationController {
         const RENDERING_GROUP_ID = 0; // MUST be > 0 to render on top of main scene
 
         // Use UtilityLayerRenderer for rendering
-        const uScene = UtilityLayerRenderer.DefaultKeepDepthUtilityLayer.utilityLayerScene;
+        const utilityLayer = new UtilityLayerRenderer(this.#scene, undefined, undefined);
+        const uScene = utilityLayer.utilityLayerScene;
 
         // Cache map: baseMesh -> overlayBaseMesh to reuse for InstancedMeshes
         const baseToOverlayBase = new Map();

package/src/babylonjs-controller.js

@@ -388,7 +388,7 @@ export default class BabylonJSController {
 
         let lightsChanged = false;
 
-        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl && this.#options.ibl.cachedUrl !== null;
+        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl?.cachedUrl !== null;
 
         if (iblEnabled) {
             if (hemiLight) {
@@ -935,7 +935,7 @@ export default class BabylonJSController {
 
         this.#ensureMeshesReceiveShadows();
 
-        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl && this.#options.ibl.cachedUrl !== null;
+        const iblEnabled = this.#settings.iblEnabled && this.#options.ibl?.cachedUrl !== null;
         const iblShadowsEnabled = iblEnabled && this.#options.ibl.shadows;
 
         if (iblShadowsEnabled) {

package/src/localization/translations.js

@@ -22,7 +22,7 @@ export const translations = {
                         helper: "Reduction of ambient light in corners and areas close to surfaces.",
                     },
                     iblEnabled: {
-                        label: "IBL",
+                        label: "Image Based Lighting (IBL)",
                         helper: "Uses the HDR environment to light the scene.",
                     },
                     shadowsEnabled: {
@@ -68,11 +68,11 @@ export const translations = {
                         helper: "Suaviza aristas y líneas.",
                     },
                     ambientOcclusionEnabled: {
-                        label: "Ambient Occlusion",
+                        label: "Oclusión ambiental",
                         helper: "Atenuación de la luz ambiental en rincones y zonas cercanas entre superficies.",
                     },
                     iblEnabled: {
-                        label: "IBL",
+                        label: "Iluminación basada en imagen (IBL)",
                         helper: "Usa la imagen HDR de entorno para iluminar la escena.",
                     },
                     shadowsEnabled: {

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

@@ -1,15 +1,18 @@
 /**
- * ContainerData - Represents the state and metadata of a asset container in the 3D viewer (e.g., model, environment, materials).
+ * ContainerData - Represents state, cache metadata, and update lifecycle for a 3D asset container
+ * (for example: model, environment, or 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.
+ *  - Tracks persistent container fields (`storage`, `show`, `size`, `timeStamp`, `metadata`, `visible`).
+ *  - Tracks staged update data in `update` (`pending`, `success`, staged storage/show/cache info).
+ *  - Provides helpers to stage updates (`setPending`, `setPendingCacheData`, `setPendingWithCurrentStorage`)
+ *    and commit them (`setSuccess(true)`).
  *
  * Usage:
- *  - Instantiate with a name: new ContainerData("model")
- *  - Use setPending(), setSuccess(), and reset() to manage update state.
- *  - Access status via isPending, isSuccess, isVisible getters.
+ *  - Instantiate with a name: `new ContainerData("model")`.
+ *  - Stage a reload with `setPending(...)`, optionally seed cache metadata, then finalize with `setSuccess(true)`.
+ *  - Use `setPendingWithCurrentStorage()` to request a reload from the currently stored source.
+ *  - Inspect flags via `isPending`, `isSuccess`, `isVisible`, and `mustBeShown`.
  */
 export class ContainerData {
     constructor(name = "") {
@@ -88,17 +91,18 @@ export class ContainerData {
 }
 
 /**
- * MaterialData - Represents the state and metadata of a material in the 3D viewer.
+ * MaterialData - Represents a material option plus its update lifecycle 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.
+ *  - Stores material identity and targeting info (`name`, `nodeNames`, `nodePrefixes`).
+ *  - Stores current applied material value (`value`).
+ *  - Tracks staged material changes in `update` (`pending`, `success`, `value`).
  *
  * 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.
+ *  - Instantiate with initial values: `new MaterialData("innerWall", value, nodeNames, nodePrefixes)`.
+ *  - Stage a change with `setPending(...)`, then commit with `setSuccess(true)`.
+ *  - Use `setPendingWithCurrent()` to reapply the currently stored material value.
+ *  - Inspect flags via `isPending` and `isSuccess`.
  */
 export class MaterialData {
     constructor(name = "", value = null, nodeNames = [], nodePrefixes = []) {
@@ -146,17 +150,18 @@ export class MaterialData {
 }
 
 /**
- * CameraData - Represents the state and metadata of a camera in the 3D viewer.
+ * CameraData - Represents camera selection state and camera-lock behavior for 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.
+ *  - Stores current camera selection (`value`) and lock state (`locked`).
+ *  - Tracks staged camera updates in `update` (`pending`, `success`, `value`, `locked`).
+ *  - Provides helpers to stage (`setPending`, `setPendingWithCurrent`) and commit (`setSuccess(true)`) updates.
  *
  * 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.
+ *  - Instantiate with a name and optional value: `new CameraData("camera", value, locked)`.
+ *  - Stage a camera update with `setPending(value, locked)`.
+ *  - Pass `null` as value to request an unlocked/default camera behavior.
+ *  - Inspect flags via `isPending` and `isSuccess`.
  */
 export class CameraData {
     defaultLocked = true;
@@ -210,33 +215,40 @@ export class CameraData {
 }
 
 /**
- * IBLData - Tracks configurable settings for image-based lighting assets (IBL/HDR environments).
+ * IBLData - Stores image-based lighting configuration for HDR environment rendering.
  *
  * Responsibilities:
- *  - Stores the HDR url, intensity scalar, whether environment-provided shadows should render, and cache timestamp.
- *  - Exposes a lightweight pending/success state machine so UI flows know when a new IBL selection is being fetched.
- *  - Provides helpers to update values atomically via `setValues`, toggle pending state, and mark completion.
+ *  - Stores source and cache references (`url`, `cachedUrl`) for the HDR environment map.
+ *  - Stores runtime tuning values (`intensity`, `shadows`) and cache identity (`timeStamp`).
+ *  - Provides helpers to fully reset IBL state (`reset`) or partially update known fields (`setValues`).
  *
  * Usage:
- *  - Instantiate with defaults: `const ibl = new IBLData();`
- *  - Call `setPending()` before kicking off an async download, `setValues()` as metadata streams in, and `setSuccess(true)` once loading finishes.
- *  - Inspect `isPending`/`isSuccess` to drive UI or re-render logic.
+ *  - Instantiate with defaults: `const ibl = new IBLData();`.
+ *  - Call `setValues(...)` with only the fields you want to update (undefined preserves current values).
+ *  - Call `reset()` to clear the current IBL environment and restore default intensity/shadows.
  */
 export class IBLData {
     defaultIntensity = 1.0;
     defaultShadows = false;
-    constructor(url = null, intensity = this.defaultIntensity, shadows = this.defaultShadows, timeStamp = null) {
-        this.url = url;
-        this.cachedUrl = null;
-        this.intensity = intensity;
-        this.shadows = shadows;
-        this.timeStamp = timeStamp;
-    }
-    setValues(url, cachedUrl = null, intensity = this.defaultIntensity, shadows = this.defaultShadows, timeStamp = null) {
+    constructor(url = null, cachedUrl = null, intensity = this.defaultIntensity, shadows = this.defaultShadows, timeStamp = null) {
         this.url = url;
         this.cachedUrl = cachedUrl;
         this.intensity = intensity;
         this.shadows = shadows;
         this.timeStamp = timeStamp;
     }
+    reset() {
+        this.url = null
+        this.cachedUrl = null;
+        this.intensity = this.defaultIntensity;
+        this.shadows = this.defaultShadows;
+        this.timeStamp = null;
+    }
+    setValues(url, cachedUrl, intensity, shadows, timeStamp) {
+        this.url = url !== undefined ? url : this.url;
+        this.cachedUrl = cachedUrl !== undefined ? cachedUrl : this.cachedUrl;
+        this.intensity = intensity !== undefined ? intensity : this.intensity;
+        this.shadows = shadows !== undefined ? shadows : this.shadows;
+        this.timeStamp = timeStamp !== undefined ? timeStamp : this.timeStamp;
+    }
 }

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

@@ -323,6 +323,10 @@ export default class PrefViewer3D extends HTMLElement {
     /**
      * Resolves incoming IBL settings (HDR URL, timestamp, intensity, shadows) and marks the option as pending when changed.
      * Fetches signed URLs/time stamps when storage keys are provided so the Babylon controller can reload the environment map.
+     * If `options.ibl` exists but `options.ibl.url` is undefined (missing), the current IBL URL is kept and not marked as pending.
+     * This allows updating other IBL properties (such as intensity or shadows) without requiring a new URL.
+     * If `options.ibl.url` is explicitly provided as `null` (or resolves to an unavailable URL), it is treated as a request to
+     * clear the current IBL environment, and the IBL state is reset so Babylon can remove the environment map.
      * @private
      * @param {object} options - Options payload that may contain an `ibl` block with url, intensity, or shadow flags.
      * @returns {Promise<boolean>} Resolves to true when any IBL property differs from the cached state, otherwise false.
@@ -339,14 +343,20 @@ export default class PrefViewer3D extends HTMLElement {
         let shadows = undefined;
         let intensity = undefined;
 
-        if (options.ibl.url) {
-            url = options.ibl.url;
+        if (typeof options.ibl.url === "string" && options.ibl.url.length > 0) {
             const fileStorage = new FileStorage("PrefViewer", "Files");
             const newURL = await fileStorage.getURL(options.ibl.url);
             if (newURL) {
+                url = options.ibl.url;
                 cachedUrl = newURL;
                 timeStamp = await fileStorage.getTimeStamp(options.ibl.url);
+            } else {
+                url = null;
+                cachedUrl = null;
             }
+        } else if (options.ibl.url === null) {
+            url = null;
+            cachedUrl = null;
         }
         if (options.ibl.shadows !== undefined) {
             shadows = options.ibl.shadows;
@@ -362,7 +372,11 @@ export default class PrefViewer3D extends HTMLElement {
             intensity !== undefined && intensity !== iblState.intensity ||
             intensity === undefined && iblState.intensity !== iblState.defaultIntensity;
         if (needUpdate) {
-            iblState.setValues(url, cachedUrl, intensity, shadows, timeStamp);
+            if (url === null || cachedUrl === null) {
+                iblState.reset();
+            } else {
+                iblState.setValues(url, cachedUrl, intensity, shadows, timeStamp);
+            }
         }
         
         return needUpdate;
@@ -756,6 +770,16 @@ export default class PrefViewer3D extends HTMLElement {
         return this.#babylonJSController.getRenderSettings();
     }
 
+    /**
+     * Reports whether an IBL environment map is currently available (cached URL present).
+     * @public
+     * @returns {boolean} True when `options.ibl.cachedUrl` exists and is non-empty.
+     */
+    isIBLAvailable() {
+        const cachedUrl = this.#data?.options?.ibl?.cachedUrl;
+        return typeof cachedUrl === "string" ? cachedUrl.length > 0 : Boolean(cachedUrl);
+    }
+
     /**
      * Applies render settings that require reloading the Babylon.js scene.
      * @public

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

@@ -9,6 +9,7 @@ import { DEFAULT_LOCALE, resolveLocale, translate } from "./localization/i18n.js
  *  - Builds an accessible hover/focus-activated panel with switches for AA, SSAO, IBL, and dynamic shadows.
  *  - Caches translated copy in `#texts` and listens for culture changes via the `culture` attribute or `setCulture()`.
  *  - Tracks applied vs. draft render settings so pending diffs, button enablement, and status text stay in sync.
+ *  - Supports per-switch availability (enabled/disabled), preventing interaction and pending diffs for unavailable toggles.
  *  - Emits `pref-viewer-menu-3d-apply` whenever the user confirms toggles, allowing PrefViewer/BabylonJSController to persist.
  *  - Shows transient status/error messages and per-switch pending states while operations complete.
  *
@@ -17,6 +18,7 @@ import { DEFAULT_LOCALE, resolveLocale, translate } from "./localization/i18n.js
  *  - `setApplying(isApplying, hasError?)`: locks the UI and optionally displays errors while async updates run.
  *  - `setViewerHover(isHovering)`: opens/closes the panel based on viewer hover state.
  *  - `setEnabled(isEnabled)`: hides the menu in 2D mode and clears hover data.
+ *  - `setSwitchEnabled(settingKey, isEnabled)`: enables/disables a concrete toggle (e.g. IBL) based on runtime availability.
  *  - `setCulture(cultureId)`: forces a locale change and re-renders copy from the i18n layer.
  *
  * Lifecycle & Integration:
@@ -52,6 +54,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     #MENU_SWITCHES = Object.keys(this.#DEFAULT_RENDER_SETTINGS);
     #appliedSettings = { ...this.#DEFAULT_RENDER_SETTINGS };
     #draftSettings = { ...this.#DEFAULT_RENDER_SETTINGS };
+    #switchAvailability = {};
     #statusTimeout = null;
     #isApplying = false;
     #isEnabled = true;
@@ -352,6 +355,9 @@ export default class PrefViewerMenu3D extends HTMLElement {
      * @returns {void}
      */
     #handleSwitchChange(event) {
+        if (event.currentTarget?.disabled) {
+            return;
+        }
         const key = event.currentTarget?.dataset?.setting;
         if (!key) {
             return;
@@ -388,7 +394,10 @@ export default class PrefViewerMenu3D extends HTMLElement {
     #updateSwitches() {
         Object.entries(this.#elements.switches).forEach(([key, input]) => {
             if (input) {
+                const isEnabled = this.#switchAvailability[key] !== false;
                 input.checked = Boolean(this.#draftSettings[key]);
+                input.disabled = !isEnabled;
+                this.#elements.switchWrappers[key]?.toggleAttribute("data-disabled", !isEnabled);
             }
         });
     }
@@ -416,7 +425,12 @@ export default class PrefViewerMenu3D extends HTMLElement {
      * @returns {string[]} Keys currently pending application.
      */
     #getPendingKeys() {
-        return Object.keys(this.#DEFAULT_RENDER_SETTINGS).filter((key) => this.#draftSettings[key] !== this.#appliedSettings[key]);
+        return Object.keys(this.#DEFAULT_RENDER_SETTINGS).filter((key) => {
+            if (this.#elements.switches[key]?.disabled) {
+                return false;
+            }
+            return this.#draftSettings[key] !== this.#appliedSettings[key];
+        });
     }
 
     /**
@@ -561,4 +575,24 @@ export default class PrefViewerMenu3D extends HTMLElement {
             this.#closeMenu();
         }
     }
+
+    /**
+     * Enables or disables a specific render-setting switch in the menu.
+     * @public
+     * @param {string} settingKey - Switch key (e.g. "iblEnabled").
+     * @param {boolean} [isEnabled=true] - True to allow interaction, false to disable it.
+     * @returns {void}
+     */
+    setSwitchEnabled(settingKey, isEnabled = true) {
+        if (!settingKey || !this.#MENU_SWITCHES.includes(settingKey)) {
+            return;
+        }
+        const enabled = Boolean(isEnabled);
+        this.#switchAvailability[settingKey] = enabled;
+        if (!enabled) {
+            this.#draftSettings[settingKey] = this.#appliedSettings[settingKey];
+        }
+        this.#updateSwitches();
+        this.#updatePendingState();
+    }
 }

package/src/pref-viewer.js

@@ -286,6 +286,7 @@ export default class PrefViewer extends HTMLElement {
 
         this.#wrapper.appendChild(this.#menu3D);
         this.#menu3DSyncSettings();
+        this.#menu3DUpdateSwitchAvailability();
         this.#menu3DUpdateAvailability();
     }
 
@@ -372,6 +373,19 @@ export default class PrefViewer extends HTMLElement {
         this.#menu3D.setEnabled?.(isMode3D);
     }
 
+    /**
+     * Enables/disables menu switches according to current 3D option availability.
+     * @private
+     * @returns {void}
+     */
+    #menu3DUpdateSwitchAvailability() {
+        if (!this.#menu3D) {
+            return;
+        }
+        const iblAvailable = this.#component3D?.isIBLAvailable?.() === true;
+        this.#menu3D.setSwitchEnabled?.("iblEnabled", iblAvailable);
+    }
+
     /**
      * Applies render toggles via PrefViewer3D, showing progress in the menu and resyncing on completion.
      * When no changes occur, the menu is simply refreshed to match the controller snapshot.
@@ -520,6 +534,9 @@ export default class PrefViewer extends HTMLElement {
     #on3DLoaded(detail) {
         this.#isLoaded = true;
         this.#isLoading = false;
+        
+        this.#menu3DSyncSettings();
+        this.#menu3DUpdateSwitchAvailability();
 
         this.removeAttribute("loading-3d");
         this.setAttribute("loaded-3d", "");

package/src/styles.js

@@ -234,7 +234,7 @@ export const PrefViewerMenu3DStyles = `
         border-bottom: none;
     }
 
-    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch .menu-switch-copy {
+    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch>.menu-switch-copy {
         display: flex;
         flex-direction: column;
         gap: calc(var(--panel-spacing) / 4);
@@ -262,14 +262,14 @@ export const PrefViewerMenu3DStyles = `
         font-size: var(--font-size-small);
     }
 
-    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch .menu-switch-control {
+    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch>.menu-switch-control {
         position: relative;
         width: var(--switch-control-width);
         min-width: var(--switch-control-width);
         height: var(--switch-control-height);
     }
 
-    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch .menu-switch-control input {
+    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch>.menu-switch-control input {
         position: absolute;
         inset: 0;
         margin: 0;
@@ -277,6 +277,18 @@ export const PrefViewerMenu3DStyles = `
         cursor: pointer;
     }
 
+    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch[data-disabled]>.menu-switch-copy {
+        opacity: 0.6;
+    }
+
+    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch[data-disabled]>.menu-switch-control {
+        opacity: 0.4;
+    }
+
+    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch>.menu-switch-control input:disabled {
+        cursor: not-allowed;
+    }
+
     pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch .menu-switch-visual {
         position: absolute;
         inset: 0;
@@ -286,6 +298,10 @@ export const PrefViewerMenu3DStyles = `
         cursor: pointer;
     }
 
+    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch>.menu-switch-control input:disabled + .menu-switch-visual {
+        cursor: not-allowed;
+    }
+
     pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch .menu-switch-visual::after {
         content: "";
         position: absolute;
@@ -299,11 +315,11 @@ export const PrefViewerMenu3DStyles = `
         transition: transform 0.2s ease;
     }
 
-    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch .menu-switch-control input:checked + .menu-switch-visual {
+    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch>.menu-switch-control input:checked + .menu-switch-visual {
         background: var(--switch-control-bar-checked-color);
     }
 
-    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch .menu-switch-control input:checked + .menu-switch-visual::after {
+    pref-viewer-menu-3d>.menu-wrapper>.menu-panel>.menu-switches>.menu-switch>.menu-switch-control input:checked + .menu-switch-visual::after {
         transform: translateX(var(--switch-control-thumb-size));
     }