@preference-sl/pref-viewer 2.17.0-beta.0 → 2.17.0-beta.1

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

@@ -15,6 +15,11 @@
  *  - Inspect flags via `isPending`, `isSuccess`, `isVisible`, and `mustBeShown`.
  */
 export class ContainerData {
+    /**
+     * Creates container state with no loaded assets and resets its staged update.
+     * @public
+     * @param {string} [name=""] - Container identity, such as model or environment.
+     */
     constructor(name = "") {
         this.metadata = {};
         this.name = name;
@@ -26,6 +31,12 @@ export class ContainerData {
         // Set initial information about ongoing update
         this.reset();
     }
+
+    /**
+     * Clears staged cache and load flags while preserving committed container fields.
+     * @public
+     * @returns {void}
+     */
     reset() {
         this.update = {
             metadata: {},
@@ -37,6 +48,13 @@ export class ContainerData {
             timeStamp: null,
         };
     }
+
+    /**
+     * Marks the staged result; success commits visibility intent, cache metadata and a supplied source.
+     * @public
+     * @param {boolean} [success=false] - Whether the staged load succeeded.
+     * @returns {void}
+     */
     setSuccess(success = false) {
         if (success) {
             this.update.success = true;
@@ -51,6 +69,14 @@ export class ContainerData {
             this.update.success = false;
         }
     }
+
+    /**
+     * Resets staged state and queues a source and visibility intent for the next load.
+     * @public
+     * @param {object|null} [storage=null] - URL or IndexedDB storage descriptor.
+     * @param {boolean} [show] - Requested visibility; omission retains the current intent.
+     * @returns {void}
+     */
     setPending(storage = null, show) {
         this.reset();
         this.update.pending = true;
@@ -61,11 +87,26 @@ export class ContainerData {
             this.storage = storage;
         }
     }
+
+    /**
+     * Stages resolved source size, timestamp and a copied metadata snapshot.
+     * @public
+     * @param {number} [size=0] - Resolved source size.
+     * @param {string|null} [timeStamp=null] - Source modification marker.
+     * @param {object} [metadata={}] - Source metadata to copy.
+     * @returns {void}
+     */
     setPendingCacheData(size = 0, timeStamp = null, metadata = {}) {
         this.update.size = size;
         this.update.timeStamp = timeStamp;
         this.update.metadata = { ...(metadata ?? {}) };
     }
+
+    /**
+     * Queues the committed source and cache metadata again when a source is available.
+     * @public
+     * @returns {boolean}
+     */
     setPendingWithCurrentStorage() {
         const storedSource = this.storage ?? null;
         if (!storedSource) {
@@ -76,15 +117,39 @@ export class ContainerData {
         this.setPendingCacheData(this.size, this.timeStamp, this.metadata);
         return true;
     }
+
+    /**
+     * Reports whether a container load is staged.
+     * @public
+     * @returns {boolean}
+     */
     get isPending() {
         return this.update.pending === true;
     }
+
+    /**
+     * Reports whether the staged load succeeded.
+     * @public
+     * @returns {boolean}
+     */
     get isSuccess() {
         return this.update.success === true;
     }
+
+    /**
+     * Reports whether the container is currently attached as visible.
+     * @public
+     * @returns {boolean}
+     */
     get isVisible() {
         return this.visible === true;
     }
+
+    /**
+     * Resolves visibility intent from the staged value or committed show flag.
+     * @public
+     * @returns {boolean}
+     */
     get mustBeShown() {
         return this.update.show !== null ? this.update.show === true : this.show === true;
     }
@@ -105,6 +170,14 @@ export class ContainerData {
  *  - Inspect flags via `isPending` and `isSuccess`.
  */
 export class MaterialData {
+    /**
+     * Creates material option state and stores exact-name and prefix targets.
+     * @public
+     * @param {string} [name=""] - Material option identity.
+     * @param {string|null} [value=null] - Selected material name.
+     * @param {string[]} [nodeNames=[]] - Exact mesh names to target.
+     * @param {string[]} [nodePrefixes=[]] - Mesh-name prefixes to target.
+     */
     constructor(name = "", value = null, nodeNames = [], nodePrefixes = []) {
         this.name = name;
         this.nodeNames = nodeNames;
@@ -113,6 +186,12 @@ export class MaterialData {
         // Set initial information about ongoing update
         this.reset();
     }
+
+    /**
+     * Clears staged material flags without changing the committed selection.
+     * @public
+     * @returns {void}
+     */
     reset() {
         this.update = {
             pending: false,
@@ -120,6 +199,13 @@ export class MaterialData {
             value: null,
         };
     }
+
+    /**
+     * Marks the result and commits the staged material value only on success.
+     * @public
+     * @param {boolean} [success=false] - Whether material application succeeded.
+     * @returns {void}
+     */
     setSuccess(success = false) {
         if (success) {
             this.update.success = true;
@@ -128,12 +214,25 @@ export class MaterialData {
             this.update.success = false;
         }
     }
+
+    /**
+     * Resets staged state and queues a material value for application.
+     * @public
+     * @param {string|null} [value=null] - Material name to apply.
+     * @returns {void}
+     */
     setPending(value = null) {
         this.reset();
         this.update.pending = true;
         this.update.success = false;
         this.update.value = value;
     }
+
+    /**
+     * Queues the committed material value unless it is undefined.
+     * @public
+     * @returns {boolean}
+     */
     setPendingWithCurrent() {
         if (this.value === undefined) {
             return false;
@@ -141,9 +240,21 @@ export class MaterialData {
         this.setPending(this.value);
         return true;
     }
+
+    /**
+     * Reports whether a material change is staged.
+     * @public
+     * @returns {boolean}
+     */
     get isPending() {
         return this.update.pending === true;
     }
+
+    /**
+     * Reports whether the staged material change succeeded.
+     * @public
+     * @returns {boolean}
+     */
     get isSuccess() {
         return this.update.success === true;
     }
@@ -165,6 +276,13 @@ export class MaterialData {
  */
 export class CameraData {
     defaultLocked = true;
+    /**
+     * Creates camera selection and lock state and resets its staged update.
+     * @public
+     * @param {string} [name=""] - Camera option identity.
+     * @param {string|null} [value=null] - Authored camera name or null for the default camera.
+     * @param {boolean} [locked=true] - Initial navigation lock.
+     */
     constructor(name = "", value = null, locked = this.defaultLocked) {
         this.name = name;
         this.value = value;
@@ -172,6 +290,12 @@ export class CameraData {
         // Set initial information about ongoing update
         this.reset();
     }
+
+    /**
+     * Clears staged camera flags while preserving the committed camera selection.
+     * @public
+     * @returns {void}
+     */
     reset() {
         this.update = {
             pending: false,
@@ -179,6 +303,13 @@ export class CameraData {
             value: null,
         };
     }
+
+    /**
+     * Marks the result and commits the staged camera value and lock only on success.
+     * @public
+     * @param {boolean} [success=false] - Whether camera application succeeded.
+     * @returns {void}
+     */
     setSuccess(success = false) {
         if (success) {
             this.update.success = true;
@@ -188,6 +319,14 @@ export class CameraData {
             this.update.success = false;
         }
     }
+
+    /**
+     * Queues a camera change; undefined clears staging and null requests an unlocked default camera.
+     * @public
+     * @param {string|null|undefined} [value] - Camera selection to stage.
+     * @param {boolean} [locked=true] - Navigation lock for an authored camera.
+     * @returns {void}
+     */
     setPending(value = undefined, locked = this.defaultLocked) {
         this.reset();
         if (value === undefined) {
@@ -201,14 +340,31 @@ export class CameraData {
         this.update.value = value;
         this.update.locked = locked;
     }
+
+    /**
+     * Queues the committed camera selection and lock again.
+     * @public
+     * @returns {boolean}
+     */
     setPendingWithCurrent() {
         const currentValue = this.value !== undefined ? this.value : null;
         this.setPending(currentValue, this.locked);
         return true;
     }
+
+    /**
+     * Reports whether a camera change is staged.
+     * @public
+     * @returns {boolean}
+     */
     get isPending() {
         return this.update.pending === true;
     }
+    /**
+     * Reports whether the staged camera change succeeded.
+     * @public
+     * @returns {boolean}
+     */
     get isSuccess() {
         return this.update.success === true;
     }
@@ -234,6 +390,16 @@ export class CameraData {
 export class IBLData {
     defaultIntensity = 1.0;
     defaultShadows = false;
+    /**
+     * Creates HDR source/cache references and effective image-based lighting settings.
+     * @public
+     * @param {string|null} [url=null] - HDR source identifier.
+     * @param {string|null} [cachedUrl=null] - Resolved temporary HDR URL.
+     * @param {number} [intensity=1] - Environment intensity.
+     * @param {boolean} [shadows=false] - IBL shadow toggle.
+     * @param {string|null} [timeStamp=null] - Source modification marker.
+     * @param {boolean} [valid=false] - Whether a reusable HDR texture is available.
+     */
     constructor(url = null, cachedUrl = null, intensity = this.defaultIntensity, shadows = this.defaultShadows, timeStamp = null, valid = false) {
         this.url = url;
         this.cachedUrl = cachedUrl;

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

@@ -77,6 +77,7 @@ import FileStorage from "./file-storage.js";
  *  - "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.
+ *  - "pref-viewer-3d-element-click": Internal event carrying distance-ordered semantic model mesh ids.
  *
  * Notes:
  *  - Internal state and heavy initialization are handled in connectedCallback.
@@ -794,6 +795,16 @@ export default class PrefViewer3D extends HTMLElement {
         this.#babylonJSController.setContainerVisibility("environment", false);
     }
 
+    /**
+     * Applies the host-owned semantic selection snapshot to the 3D model.
+     * @public
+     * @param {object} state - Canonical PrefViewer selection state.
+     * @returns {void}
+     */
+    applySelectionState(state = {}) {
+        this.#babylonJSController?.applySelectionState(state);
+    }
+
     /**
      * Downloads the current 3D model as a GLB file.
      * @public

package/src/pref-viewer-dialog.js

@@ -44,7 +44,7 @@ export default class PrefViewerDialog extends HTMLElement {
      * Called when the element is inserted into the DOM.
      * Sets up the dialog's DOM structure and styles.
      * @returns {void}
-    */
+     */
    connectedCallback() {
         this.#handles.onBackdropClick = this.#onBackdropClick.bind(this);
         this.#createDOMElements();
@@ -85,6 +85,12 @@ export default class PrefViewerDialog extends HTMLElement {
         this.#footer = this.#wrapper.querySelector(".dialog-footer");
     }
 
+    /**
+     * Closes the dialog only when its own backdrop is clicked, preserving content interactions.
+     * @private
+     * @param {MouseEvent} event - Dialog click event.
+     * @returns {void}
+     */
     #onBackdropClick(event) {
         if (event.target === this) {
             this.close();

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

@@ -1,6 +1,6 @@
 import { PrefViewerMenu3DStyles } from "./styles.js";
 import BabylonJSController from "./babylonjs-controller.js";
-import { DEFAULT_LOCALE, resolveLocale, translate } from "./localization/i18n.js";
+import I18n from "./localization/i18n.js";
 
 /**
  * PrefViewerMenu3D - Localized floating control panel for Babylon.js render settings.
@@ -55,6 +55,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
         onColorSliderInput: null,
         onLightingSliderInput: null,
         onLightingPlayClick: null,
+        onLightingTick: null,
         onHostLeave: null,
         onPanelEnter: null,
         onSwitchChange: null,
@@ -63,7 +64,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
 
     #DEFAULT_RENDER_SETTINGS = { ...BabylonJSController.config.render.defaultSettings };
     // Only include boolean settings as switches; scalar settings are handled by sliders.
-    #MENU_SWITCHES = Object.keys(this.#DEFAULT_RENDER_SETTINGS).filter(key => 
+    #MENU_SWITCHES = Object.keys(this.#DEFAULT_RENDER_SETTINGS).filter(key =>
         typeof this.#DEFAULT_RENDER_SETTINGS[key] === "boolean"
     );
     #settings = { ...this.#DEFAULT_RENDER_SETTINGS };
@@ -77,9 +78,9 @@ export default class PrefViewerMenu3D extends HTMLElement {
     #lightingPlaybackBase = 0.5;
     #lightingPlaybackDurationMs = 15000;
 
-    #culture = DEFAULT_LOCALE;
+    #culture = I18n.DEFAULT_LOCALE;
     #texts = {};
-    
+
     /**
      * Creates the menu custom element.
      * Rendering is deferred until connectedCallback() so attributes can be set before the UI is built.
@@ -87,8 +88,9 @@ export default class PrefViewerMenu3D extends HTMLElement {
      */
     constructor() {
         super();
+        this.#handles.onLightingTick = this.#tickLightingPlayback.bind(this);
     }
-    
+
     /**
      * Returns the list of attributes to observe for changes.
      * @public
@@ -97,7 +99,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     static get observedAttributes() {
         return ["culture"];
     }
-    
+
     /**
      * Reacts to observed attribute mutations and mirrors them into the internal settings/UI state.
      * @public
@@ -109,7 +111,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
     attributeChangedCallback(name, _old, value) {
         switch (name) {
             case "culture":
-                this.#setCultureInternal(value || DEFAULT_LOCALE);
+                this.#setCultureInternal(value || I18n.DEFAULT_LOCALE);
                 break;
         }
     }
@@ -222,7 +224,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
      * @returns {object} Resolved `prefViewer.menu3d` translation object or an empty fallback.
      */
     #getMenuNamespace() {
-        const namespace = translate("prefViewer.menu3d", { locale: this.#culture });
+        const namespace = I18n.translate("prefViewer.menu3d", { locale: this.#culture });
         return namespace && typeof namespace === "object" ? namespace : {};
     }
 
@@ -291,11 +293,11 @@ export default class PrefViewerMenu3D extends HTMLElement {
     /**
      * Resolves and applies a locale internally, updating texts when it changes.
      * @private
-     * @param {string} [cultureId=DEFAULT_LOCALE] - Desired locale identifier.
+     * @param {string} [cultureId=I18n.DEFAULT_LOCALE] - Desired locale identifier.
      * @returns {string} The applied locale.
      */
-    #setCultureInternal(cultureId = DEFAULT_LOCALE) {
-        const resolved = resolveLocale(cultureId);
+    #setCultureInternal(cultureId = I18n.DEFAULT_LOCALE) {
+        const resolved = I18n.resolveLocale(cultureId);
         if (resolved === this.#culture) {
             return this.#culture;
         }
@@ -333,7 +335,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#elements.sliderWrappers["highlightColor"] = this.querySelector(".menu-slider[data-setting='highlightColor']");
         this.#elements.sliders["lightingTimeOfDay"] = this.querySelector("input[data-setting='lightingTimeOfDay']");
         this.#elements.sliderWrappers["lightingTimeOfDay"] = this.querySelector(".menu-slider[data-setting='lightingTimeOfDay']");
-        
+
         this.#MENU_SWITCHES.forEach((key) => {
             this.#elements.switches[key] = this.querySelector(`input[data-setting="${key}"]`);
             const wrapper = this.querySelector(`.menu-switch[data-setting="${key}"]`);
@@ -499,19 +501,26 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#lightingPlaybackBase = this.#settings.lightingTimeOfDay ?? 0.5;
         this.#lightingPlaybackStart = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
         this.#updateLightingPlayButtonUI();
-        const tick = () => {
-            if (!this.#isLightingPlaying) {
-                return;
-            }
-            const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
-            const elapsed = now - this.#lightingPlaybackStart;
-            const cycle = (this.#lightingPlaybackBase + (elapsed / this.#lightingPlaybackDurationMs)) % 1;
-            this.#settings.lightingTimeOfDay = cycle;
-            this.#updateLightingSliderUI(cycle);
-            this.#emitApply({ lightingTimeOfDay: cycle, persist: false }, { partial: true });
-            this.#lightingAnimationFrame = requestAnimationFrame(tick);
-        };
-        this.#lightingAnimationFrame = requestAnimationFrame(tick);
+
+        this.#lightingAnimationFrame = requestAnimationFrame(this.#handles.onLightingTick);
+    }
+
+    /**
+     * Advances the time-of-day playback cycle and emits transient settings while playback remains active.
+     * @private
+     * @returns {void}
+     */
+    #tickLightingPlayback() {
+        if (!this.#isLightingPlaying) {
+            return;
+        }
+        const now = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        const elapsed = now - this.#lightingPlaybackStart;
+        const cycle = (this.#lightingPlaybackBase + (elapsed / this.#lightingPlaybackDurationMs)) % 1;
+        this.#settings.lightingTimeOfDay = cycle;
+        this.#updateLightingSliderUI(cycle);
+        this.#emitApply({ lightingTimeOfDay: cycle, persist: false }, { partial: true });
+        this.#lightingAnimationFrame = requestAnimationFrame(this.#handles.onLightingTick);
     }
 
     /**
@@ -555,11 +564,22 @@ export default class PrefViewerMenu3D extends HTMLElement {
     static #hueToHex(hue) {
         const h = ((hue % 360) + 360) % 360;
         const a = Math.min(0.5, 1 - 0.5);
-        const f = (n) => {
-            const k = (n + h / 30) % 12;
-            return 0.5 - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
-        };
-        return '#' + [f(0), f(8), f(4)].map((v) => Math.round(v * 255).toString(16).padStart(2, '0')).join('');
+
+        return '#' + [0, 8, 4].map((phase) => PrefViewerMenu3D.#hueChannel(phase, h, a)).map((v) => Math.round(v * 255).toString(16).padStart(2, '0')).join('');
+    }
+
+    /**
+     * Computes a normalized RGB channel from the current hue.
+     * @private
+     * @static
+     * @param {number} phase - Channel phase offset.
+     * @param {number} hue - Normalized hue angle in degrees.
+     * @param {number} amplitude - RGB channel amplitude.
+     * @returns {number}
+     */
+    static #hueChannel(phase, hue, amplitude) {
+        const k = (phase + hue / 30) % 12;
+        return 0.5 - amplitude * Math.max(Math.min(k - 3, 9 - k, 1), -1);
     }
 
     /**
@@ -724,21 +744,21 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#isApplying = isApplying;
         this.toggleAttribute("data-applying", isApplying);
     }
-    
+
     /**
      * Sets the locale used for menu labels and helper text.
      * @public
      * @param {string} cultureId - Locale identifier, e.g., "en-EN".
      * @returns {void}
      */
-    setCulture(cultureId = DEFAULT_LOCALE) {
-        const resolved = resolveLocale(cultureId);
+    setCulture(cultureId = I18n.DEFAULT_LOCALE) {
+        const resolved = I18n.resolveLocale(cultureId);
         const applied = this.#setCultureInternal(resolved);
         if (this.getAttribute("culture") !== applied) {
             this.setAttribute("culture", applied);
         }
     }
-    
+
     /**
      * Enables or disables the menu entirely, hiding it when 3D mode is unavailable.
      * @public
@@ -774,7 +794,7 @@ export default class PrefViewerMenu3D extends HTMLElement {
         this.#updateLightingPlayButtonUI();
         this.setApplying(false);
     }
-    
+
     /**
      * Receives viewer hover state so the menu only opens when the user interacts with the 3D viewport.
      * @public