@preference-sl/pref-viewer 2.16.0-beta.10 → 2.16.0-beta.12

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

@@ -19,20 +19,20 @@ import { PrefViewer2DStyles } from "./styles.js";
  *  - visible: "true" | "false" (controls visibility and event subscription)
  *
  * Public methods
- *  - async load(svgConfig) : Promise<boolean> — accept SVG input/config and prepare for render
+ *  - async load(svgConfig) : Promise<{success: boolean, error: Error|null}> — accept SVG input/config and prepare for render
  *  - show(), hide() — toggle visibility and event subscriptions
  *  - zoomIn(), zoomOut(), zoomCenter(), zoomExtentsAll() — pan/zoom controls
  * 
- * * Public Properties:
+ * 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
- *  - "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 })
+ *  - "pref-viewer-2d-loading": emitted before loading starts. Legacy alias: "drawing-loading"
+ *  - "pref-viewer-2d-loaded": emitted after content and Panzoom are ready. Legacy alias: "drawing-loaded"
+ *  - "pref-viewer-2d-error": emitted on validation/fetch errors (detail.error: Error). Legacy alias: "drawing-error"
+ *  - "pref-viewer-2d-viewport-changed": emitted when pan/zoom state changes (detail: { moved, scaled, maximized, minimized })
  *
  * Implementation notes
  *  - Keeps internal state in private fields (#svg, #panzoom, #panzoomOptions, ...).
@@ -235,7 +235,8 @@ export default class PrefViewer2D extends HTMLElement {
             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));
+        this.dispatchEvent(new CustomEvent("pref-viewer-2d-error", customEventOptions));
+        this.dispatchEvent(new CustomEvent("drawing-error", customEventOptions)); // Legacy alias for backward compatibility
         return detail;
     }
 
@@ -250,7 +251,8 @@ export default class PrefViewer2D extends HTMLElement {
             cancelable: true,
             composed: false,
         };
-        this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-2d-loaded", customEventOptions));
+        this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
@@ -270,7 +272,8 @@ export default class PrefViewer2D extends HTMLElement {
             cancelable: true,
             composed: false,
         };
-        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-2d-loading", customEventOptions));
+        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
@@ -283,7 +286,7 @@ export default class PrefViewer2D extends HTMLElement {
     }
 
     /**
-     * Handles Panzoom state changes by dispatching a "prefviewer2d-zoomchanged" custom event.
+     * Handles Panzoom state changes by dispatching the public "pref-viewer-2d-viewport-changed" event.
      * @private
      * @param {object} state - The current Panzoom state object.
      * @returns {void}
@@ -299,17 +302,7 @@ export default class PrefViewer2D extends HTMLElement {
             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,
-            })
-        );
+        this.dispatchEvent(new CustomEvent("pref-viewer-2d-viewport-changed", customEventOptions));
     }
 
     /**

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

@@ -25,9 +25,6 @@ import FileStorage from "./file-storage.js";
  *  - 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").
- *  - show-animation-menu: Show or hide animation controls in the 3D controller.
- *  - highlight-color: Hex color used for hover highlight on animated meshes.
- *  - highlight-enabled: Enable or disable hover highlight ("true"/"false").
  *
  * Public Methods:
  *  - show(): Shows the 3D viewer component.
@@ -40,6 +37,13 @@ import FileStorage from "./file-storage.js";
  *  - hideModel(): Hides the 3D model.
  *  - showEnvironment(): Shows the 3D environment/scene.
  *  - hideEnvironment(): Hides the 3D environment/scene.
+ *  - isIBLAvailable(): Reports whether a valid IBL environment map is currently available.
+ *  - isAnimationMenuEnabled(): Reports whether the animation control menu is currently enabled.
+ *  - getDebugInfo(): Returns a diagnostic snapshot of the underlying Babylon.js runtime.
+ *  - getAnimations(): Returns a snapshot of all available animations and their current state.
+ *  - playAnimation(name, action): Controls a named animation by applying the specified action.
+ *  - setAnimationProgress(name, progress): Seeks a named animation to a normalized progress position (0–1).
+ *  - setAnimationLoop(name, loop): Enables or disables loop mode for a named animation.
  *  - 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.
@@ -60,14 +64,16 @@ import FileStorage from "./file-storage.js";
  *  - #checkNeedToUpdateCamera(options): Detects camera option changes and marks them pending.
  *  - #checkNeedToUpdateMaterials(options): Resolves material overrides that require updates.
  *  - #checkNeedToUpdateIBL(options): Fetches HDR URLs/timestamps and enqueues IBL updates when needed.
+ *  - #checkNeedToUpdateLighting(options): Resolves time-of-day changes and marks lighting as pending.
  *  - #resetUpdateFlags(): Clears pending/success flags after loads or option-setting flows.
  *  - #onLoading/#onLoaded/#onSettingOptions/#onSetOptions(): Dispatch lifecycle events and synchronize attributes.
  *
  * 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.
+ *  - "pref-viewer-3d-loading": Dispatched when a loading operation starts. Legacy alias: "scene-loading".
+ *  - "pref-viewer-3d-loaded": Dispatched when a loading operation completes. Legacy alias: "scene-loaded".
+ *  - "pref-viewer-3d-options-applying": Dispatched when viewer options are being set. Legacy alias: "scene-setting-options".
+ *  - "pref-viewer-3d-options-applied": Dispatched when viewer options have been set. Legacy alias: "scene-set-options".
+ *  - "pref-viewer-3d-animation-changed": Dispatched by OpeningAnimation instances via the pref-viewer-3d host when an animation state, progress, or loop value changes.
  *
  * Notes:
  *  - Internal state and heavy initialization are handled in connectedCallback.
@@ -101,7 +107,7 @@ export default class PrefViewer3D extends HTMLElement {
      * @returns {string[]} Array of attribute names that trigger attributeChangedCallback.
      */
     static get observedAttributes() {
-        return ["show-model", "show-scene", "visible", "show-animation-menu", "highlight-color", "highlight-enabled"];
+        return ["show-model", "show-scene", "visible"];
     }
 
     /**
@@ -114,7 +120,6 @@ export default class PrefViewer3D extends HTMLElement {
      * - "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").
-     * - "show-animation-menu", "highlight-color", and "highlight-enabled": forward runtime UI/highlight settings to BabylonJSController.
      */
     attributeChangedCallback(name, _old, value) {
         switch (name) {
@@ -142,18 +147,6 @@ export default class PrefViewer3D extends HTMLElement {
                     this.hide();
                 }
                 break;
-            case "show-animation-menu":
-            case "highlight-color":
-            case "highlight-enabled":
-                // Pass these to BabylonJSController if initialized
-                if (this.#babylonJSController && typeof this.#babylonJSController.setIlluminationConfig === "function") {
-                    this.#babylonJSController.setIlluminationConfig({
-                        showAnimationMenu: this.getAttribute("show-animation-menu"),
-                        highlightColor: this.getAttribute("highlight-color"),
-                        highlightEnabled: this.getAttribute("highlight-enabled"),
-                    });
-                }
-                break;
         }
     }
 
@@ -234,8 +227,10 @@ export default class PrefViewer3D extends HTMLElement {
                     outerFloor: new MaterialData("outerFloor", undefined, undefined, ["outerFloor"]),
                 },
                 ibl: new IBLData(),
-                lighting: {
-                    timeOfDay: 0.5,
+                render: {
+                    showAnimationMenu: false,
+                    lightingTimeOfDay: 0.5,
+                    showLightingTimeOfDay: false,
                 },
             },
         };
@@ -250,15 +245,6 @@ export default class PrefViewer3D extends HTMLElement {
         this.#babylonJSController = new BabylonJSController(this.#canvas, this.#data.containers, this.#data.options);
         this.#babylonJSController.enable();
 
-        // Apply highlight attributes that were set before the controller was ready
-        const highlightColor = this.getAttribute("highlight-color");
-        const highlightEnabled = this.getAttribute("highlight-enabled");
-        if (highlightColor !== null || highlightEnabled !== null) {
-            this.#babylonJSController.setIlluminationConfig({
-                highlightColor: highlightColor ?? undefined,
-                highlightEnabled: highlightEnabled ?? undefined,
-            });
-        }
     }
 
     /**
@@ -430,29 +416,37 @@ export default class PrefViewer3D extends HTMLElement {
                 iblState.setValues(url, cachedUrl, intensity, shadows, timeStamp);
             }
         }
-        
+
         return needUpdate;
     }
 
     /**
-     * Resolves incoming lighting settings (time-of-day slider) and marks the option as pending when changed.
-     * Supports both nested `options.lighting.timeOfDay` and flat `options.lightingTimeOfDay` payloads so the menu
-     * and external API can share the same controller path.
+     * Checks whether any lighting-related value in `options.render` differs from the cached state.
+     * `options.render.showLightingTimeOfDay` updates slider visibility, while
+     * `options.render.lightingTimeOfDay` updates the normalized 0..1 lighting value.
      * @private
-     * @param {object} options - Options payload containing lighting state.
-     * @returns {boolean} True when lighting differs from the cached state, otherwise false.
+     * @param {object} options - Options payload containing a `render` sub-object.
+     * @param {boolean|string} [options.render.showLightingTimeOfDay] - Whether the time-of-day slider should be visible.
+     * @param {number} [options.render.lightingTimeOfDay] - Desired time-of-day, normalized to 0..1.
+     * @returns {boolean} True when either the visibility flag or the time value differs from the cached state.
      */
     #checkNeedToUpdateLighting(options) {
         if (!options) {
             return false;
         }
 
-        const lightingState = this.#data.options.lighting;
-        const incomingTime = typeof options.lightingTimeOfDay === "number"
-            ? options.lightingTimeOfDay
-            : typeof options.lighting?.timeOfDay === "number"
-                ? options.lighting.timeOfDay
-                : undefined;
+        const incomingTimeEnabled = options.render?.showLightingTimeOfDay;
+        if (incomingTimeEnabled !== undefined) {
+            const dataTimeEnabled = this.#data.options.render.showLightingTimeOfDay;
+            const needUpdate = dataTimeEnabled !== incomingTimeEnabled;
+            this.#data.options.render.showLightingTimeOfDay = incomingTimeEnabled;
+            if (needUpdate) {
+                return true;
+            }
+        }
+
+        const dataTime = this.#data.options.render.lightingTimeOfDay;
+        const incomingTime = typeof options.render?.lightingTimeOfDay === "number" ? options.render.lightingTimeOfDay : undefined;
 
         if (!Number.isFinite(incomingTime)) {
             return false;
@@ -460,9 +454,9 @@ export default class PrefViewer3D extends HTMLElement {
 
         const normalizedTime = Math.min(1, Math.max(0, incomingTime));
         const controllerTime = this.#babylonJSController?.getRenderSettings?.()?.lightingTimeOfDay;
-        const currentTime = Number.isFinite(controllerTime) ? controllerTime : lightingState.timeOfDay;
+        const currentTime = Number.isFinite(controllerTime) ? controllerTime : dataTime;
         const needUpdate = normalizedTime !== currentTime;
-        lightingState.timeOfDay = normalizedTime;
+        this.#data.options.render.lightingTimeOfDay = normalizedTime;
         return needUpdate;
     }
 
@@ -477,8 +471,10 @@ export default class PrefViewer3D extends HTMLElement {
             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.dispatchEvent(new CustomEvent("pref-viewer-3d-loading", customEventOptions));
+        this.dispatchEvent(new CustomEvent("scene-loading", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
@@ -526,7 +522,8 @@ export default class PrefViewer3D extends HTMLElement {
             composed: false,
             detail: detail,
         };
-        this.dispatchEvent(new CustomEvent("scene-loaded", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-3d-loaded", customEventOptions));
+        this.dispatchEvent(new CustomEvent("scene-loaded", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
@@ -549,7 +546,8 @@ export default class PrefViewer3D extends HTMLElement {
             cancelable: true,
             composed: false,
         };
-        this.dispatchEvent(new CustomEvent("scene-setting-options", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-3d-options-applying", customEventOptions));
+        this.dispatchEvent(new CustomEvent("scene-setting-options", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
@@ -591,7 +589,8 @@ export default class PrefViewer3D extends HTMLElement {
             composed: false,
             detail: detail,
         };
-        this.dispatchEvent(new CustomEvent("scene-set-options", customEventOptions));
+        this.dispatchEvent(new CustomEvent("pref-viewer-3d-options-applied", customEventOptions));
+        this.dispatchEvent(new CustomEvent("scene-set-options", customEventOptions)); // Legacy alias for backward compatibility
 
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
@@ -648,10 +647,15 @@ export default class PrefViewer3D extends HTMLElement {
         this.#checkNeedToUpdateContainers(config);
 
         // Options
-        let needUpdateLighting = false;
         const iblOptions = config.scene?.ibl
-            ? { ...(config.options ?? {}), ibl: { ...(config.options?.ibl ?? {}), ...config.scene.ibl } }
-            : config.options;
+        ? { ...(config.options ?? {}), ibl: { ...(config.options?.ibl ?? {}), ...config.scene.ibl } }
+        : config.options;
+
+        if (iblOptions) {
+            await this.#checkNeedToUpdateIBL(iblOptions);
+        }
+
+        let needUpdateLighting = false;
 
         if (config.options) {
             this.#checkNeedToUpdateCamera(config.options);
@@ -659,16 +663,15 @@ export default class PrefViewer3D extends HTMLElement {
             needUpdateLighting = this.#checkNeedToUpdateLighting(config.options);
         }
 
-        if (iblOptions) {
-            await this.#checkNeedToUpdateIBL(iblOptions);
-        }
-
-        const loadDetail = await this.#babylonJSController.load(forceReload);
-
         if (needUpdateLighting && typeof this.#babylonJSController.setIlluminationConfig === "function") {
-            this.#babylonJSController.setIlluminationConfig({
-                lightingTimeOfDay: this.#data.options.lighting.timeOfDay,
-            });
+            const lightingConfig = {};
+            if (config.options?.render?.lightingTimeOfDay !== undefined) {
+                lightingConfig.lightingTimeOfDay = config.options.render.lightingTimeOfDay;
+            }
+            if (config.options?.render?.showLightingTimeOfDay !== undefined) {
+                lightingConfig.showLightingTimeOfDay = config.options.render.showLightingTimeOfDay;
+            }
+            this.#babylonJSController.setIlluminationConfig(lightingConfig);
         }
 
         // Apply initial render settings if provided in options
@@ -676,6 +679,8 @@ export default class PrefViewer3D extends HTMLElement {
             await this.applyRenderSettings(config.options.render);
         }
 
+        const loadDetail = await this.#babylonJSController.load(forceReload);
+
         return { ...loadDetail, load: this.#onLoaded() };
     }
 
@@ -706,17 +711,22 @@ export default class PrefViewer3D extends HTMLElement {
         }
         const needUpdateLighting = this.#checkNeedToUpdateLighting(options);
         if (needUpdateLighting && typeof this.#babylonJSController.setIlluminationConfig === "function") {
-            this.#babylonJSController.setIlluminationConfig({
-                lightingTimeOfDay: this.#data.options.lighting.timeOfDay,
-            });
+            const lightingConfig = {};
+            if (options.render?.lightingTimeOfDay !== undefined) {
+                lightingConfig.lightingTimeOfDay = options.render.lightingTimeOfDay;
+            }
+            if (options.render?.showLightingTimeOfDay !== undefined) {
+                lightingConfig.showLightingTimeOfDay = options.render.showLightingTimeOfDay;
+            }
+            this.#babylonJSController.setIlluminationConfig(lightingConfig);
             someSetted = true;
         }
-        
+
         // Apply render settings if provided
         if (options.render) {
             await this.applyRenderSettings(options.render);
         }
-        
+
         const detail = this.#onSetOptions();
         return { success: someSetted, detail: detail };
     }
@@ -949,6 +959,38 @@ export default class PrefViewer3D extends HTMLElement {
         return typeof cachedUrl === "string" ? cachedUrl.length > 0 : Boolean(cachedUrl);
     }
 
+    /**
+     * Reports whether the animation control menu is currently enabled.
+     * @public
+     * @returns {boolean} True when the animation menu option is active; otherwise false.
+     */
+    isAnimationMenuEnabled() {
+        const renderSettings = this.getRenderSettings?.() ?? null;
+        if (renderSettings?.showAnimationMenu !== undefined) {
+            return renderSettings.showAnimationMenu === true;
+        }
+        return false;
+    }
+
+    /**
+     * Reports whether the lighting time-of-day control should be visible and interactive.
+     * Requires both `showLightingTimeOfDay === true` and a finite `lightingTimeOfDay` value.
+     * @public
+     * @returns {boolean} True when the time-of-day slider is explicitly visible and has a valid value; otherwise false.
+     */
+    isLightingTimeOfDayAvailable() {
+        const renderSettings = this.getRenderSettings?.() ?? null;
+        return renderSettings?.showLightingTimeOfDay === true && Number.isFinite(renderSettings.lightingTimeOfDay);
+    }
+
+    /**
+     * Returns a diagnostic snapshot of the underlying Babylon.js runtime.
+     * @public
+     * @returns {object|null} Debug information, or null when the controller is not initialized.
+     */
+    getDebugInfo() {
+        return this.#babylonJSController?.getDebugInfo?.() ?? null;
+    }
     /**
      * Applies render settings received from PrefViewerMenu3D or another UI.
      * Highlight and time-of-day lighting values are pushed directly to BabylonJSController; AA/SSAO/IBL/shadow changes
@@ -959,8 +1001,10 @@ export default class PrefViewer3D extends HTMLElement {
      * @param {boolean} [settings.ambientOcclusionEnabled] - Enables or disables SSAO.
      * @param {boolean} [settings.iblEnabled] - Enables or disables image-based lighting.
      * @param {boolean} [settings.shadowsEnabled] - Enables or disables scene shadows.
+     * @param {boolean|string} [settings.showAnimationMenu] - Enables/disables the animation controls when animations are available.
      * @param {boolean|string} [settings.highlightEnabled] - Enables or disables hover highlight; string "false" is normalized to false.
      * @param {string} [settings.highlightColor] - Hex color used for hover highlight.
+     * @param {boolean|string} [settings.showLightingTimeOfDay] - Shows/hides the lighting time-of-day control.
      * @param {number} [settings.lightingTimeOfDay] - Normalized 0..1 time-of-day value.
      * @param {boolean} [settings.persist=true] - False for transient lighting updates such as playback frames.
      * @returns {Promise<{changed: boolean, success: boolean, detail?: object, controller?: object}>} Resolves with the apply/reload summary.
@@ -970,30 +1014,41 @@ export default class PrefViewer3D extends HTMLElement {
             return { changed: false, success: false };
         }
 
-        // Handle highlight settings separately for immediate effect without reload
-        if (settings.highlightEnabled !== undefined || settings.highlightColor !== undefined) {
-            if (typeof this.#babylonJSController.setIlluminationConfig === "function") {
-                // Convert string "false" to boolean false
-                const highlightEnabled = settings.highlightEnabled === "false" ? false : settings.highlightEnabled;
-                this.#babylonJSController.setIlluminationConfig({
-                    highlightEnabled: highlightEnabled,
-                    highlightColor: settings.highlightColor,
-                });
-            }
+        const illuminationSettings = {};
+        if (settings.showAnimationMenu !== undefined) {
+            illuminationSettings.showAnimationMenu = settings.showAnimationMenu;
         }
-
-        // Exclude highlight settings from the reload — they are handled above without requiring a scene reload
-        if (settings.lightingTimeOfDay !== undefined && typeof this.#babylonJSController.setIlluminationConfig === "function") {
+        if (settings.highlightEnabled !== undefined) {
+            illuminationSettings.highlightEnabled = settings.highlightEnabled;
+        }
+        if (settings.highlightColor !== undefined) {
+            illuminationSettings.highlightColor = settings.highlightColor;
+        }
+        if (settings.showLightingTimeOfDay !== undefined) {
+            illuminationSettings.showLightingTimeOfDay = settings.showLightingTimeOfDay;
+        }
+        if (settings.lightingTimeOfDay !== undefined) {
             const lightingTimeOfDay = Number(settings.lightingTimeOfDay);
             if (Number.isFinite(lightingTimeOfDay)) {
-                this.#babylonJSController.setIlluminationConfig({
-                    lightingTimeOfDay,
-                    persist: settings.persist !== false,
-                });
+                illuminationSettings.lightingTimeOfDay = lightingTimeOfDay;
             }
         }
+        if (settings.persist !== undefined) {
+            illuminationSettings.persist = settings.persist;
+        }
+        if (Object.keys(illuminationSettings).length > 0 && typeof this.#babylonJSController.setIlluminationConfig === "function") {
+            this.#babylonJSController.setIlluminationConfig(illuminationSettings);
+        }
 
-        const { highlightEnabled: _he, highlightColor: _hc, lightingTimeOfDay: _lt, lighting: _lighting, persist: _persist, ...reloadSettings } = settings;
+        const {
+            showAnimationMenu: _sam,
+            highlightEnabled: _he,
+            highlightColor: _hc,
+            showLightingTimeOfDay: _slt,
+            lightingTimeOfDay: _lt,
+            persist: _persist,
+            ...reloadSettings
+        } = settings;
         const scheduled = this.#babylonJSController.scheduleRenderSettingsReload(reloadSettings);
         if (!scheduled.changed) {
             return { changed: false, success: true };