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

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

@@ -45,7 +45,7 @@ import { PrefViewer2DStyles } from "./styles.js";
  *  - Focus is set on the component's parent to enable keyboard shortcuts without Panzoom focus issues.
  *
  * Usage examples
- *  - load plain SVG: el.load({ storage: { url: '<svg...>' } }) or el.load('<svg...>');
+ *  - load plain SVG: el.load({ storage: { url: '<svg...>' } }); load expects a storage descriptor, not a raw string.
  *  - load from IndexedDB: el.load({ storage: { db: 'db', table: 'tbl', id: 'recId' } });
  *
  * Notes on extensibility
@@ -584,19 +584,31 @@ export default class PrefViewer2D extends HTMLElement {
         return [clone];
     }
 
-    /** Remove all visual selection clones and cloned definitions. */
+    /**
+     * Remove all visual selection clones and cloned definitions.
+     * @private
+     * @returns {void}
+     */
     #clearSelectionLayers() {
         this.#selectionNodes.forEach((node) => node.parentNode?.removeChild(node));
         this.#selectionNodes = [];
     }
 
-    /** Remove all host-provided SVG nodes and clear their registry. */
+    /**
+     * Remove all host-provided SVG nodes and clear their registry.
+     * @private
+     * @returns {void}
+     */
     #removeAppendedSvgNodes() {
         this.#appendedSvgElements.forEach((entry) => entry.svg?.parentNode?.removeChild(entry.svg));
         this.#appendedSvgElements = [];
     }
 
-    /** Rebuild visual layers from the latest semantic snapshot. */
+    /**
+     * Rebuild visual layers from the latest semantic snapshot.
+     * @private
+     * @returns {void}
+     */
     #reconcileSelectionState() {
         this.#clearSelectionLayers();
         if (!this.#isLoaded || !this.#getSvgRoot()) {

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

@@ -25,6 +25,7 @@ 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-view-cube: Enable the orientation overlay while visible; only "false" disables it (default: enabled).
  *
  * Public Methods:
  *  - show(): Shows the 3D viewer component.
@@ -39,6 +40,7 @@ import FileStorage from "./file-storage.js";
  *  - 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.
+ *  - refreshViewCube(): Internally synchronizes an existing cube after a host culture change.
  *  - 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.
@@ -69,11 +71,13 @@ import FileStorage from "./file-storage.js";
  *  - #onLoading/#onLoaded/#onSettingOptions/#onSetOptions(): Dispatch lifecycle events and synchronize attributes.
  *
  * Events:
+ *  - "view-cube-layout": Internal, non-bubbling event with {offset, height} in CSS pixels for host menu layout; disposal clears both.
  *  - "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.
+ *  - "pref-viewer-3d-element-click": Internal event carrying distance-ordered semantic model mesh ids.
  *
  * Notes:
  *  - Internal state and heavy initialization are handled in connectedCallback.
@@ -107,7 +111,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"];
+        return ["show-model", "show-scene", "visible", "show-view-cube"];
     }
 
     /**
@@ -120,9 +124,13 @@ 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-view-cube": activates the cube only while visible and the attribute is not "false".
      */
     attributeChangedCallback(name, _old, value) {
         switch (name) {
+            case "show-view-cube":
+                this.#babylonJSController?.setViewCubeEnabled(this.#isVisible && value !== "false");
+                break;
             case "show-model":
                 if (_old === value) {
                     return;
@@ -237,12 +245,18 @@ export default class PrefViewer3D extends HTMLElement {
     }
 
     /**
-     * Initializes the BabylonJSController and enables the Babylon.js engine for rendering.
+     * Initializes the Babylon controller with asset/option state and the visibility-aware cube contract.
+     * Supplies current host culture and dispatches measured view-cube-layout events for render-menu positioning.
+     * Starts asynchronous engine initialization without waiting for asset loading.
      * @private
      * @returns {void}
      */
     #initializeBabylonJS() {
-        this.#babylonJSController = new BabylonJSController(this.#canvas, this.#data.containers, this.#data.options);
+        this.#babylonJSController = new BabylonJSController(this.#canvas, this.#data.containers, this.#data.options, {
+            enabled: this.#isVisible && this.getAttribute("show-view-cube") !== "false",
+            getCulture: () => this.getRootNode().host?.culture,
+            onLayout: (offset, height) => this.dispatchEvent(new CustomEvent("view-cube-layout", { detail: { offset, height } })),
+        });
         this.#babylonJSController.enable();
 
     }
@@ -608,22 +622,24 @@ export default class PrefViewer3D extends HTMLElement {
      */
 
     /**
-     * Hides the 3D viewer component by updating its visibility state and DOM attribute.
+     * Hides the 3D viewer and releases its cube resources while retaining the requested show-view-cube attribute.
      * @public
      * @returns {void}
      */
     hide() {
         this.#isVisible = false;
+        this.#babylonJSController?.setViewCubeEnabled(false);
         this.setAttribute("visible", "false");
     }
 
     /**
-     * Shows the 3D viewer component by updating its visibility state and DOM attribute.
+     * Shows/focuses the 3D viewer and lazily recreates its cube when show-view-cube is not "false".
      * @public
      * @returns {void}
      */
     show() {
         this.#isVisible = true;
+        this.#babylonJSController?.setViewCubeEnabled(this.getAttribute("show-view-cube") !== "false");
         this.setAttribute("visible", "true");
         this.#canvas.focus();
     }
@@ -779,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
@@ -900,6 +926,15 @@ export default class PrefViewer3D extends HTMLElement {
         return this.#babylonJSController.getRenderSettings();
     }
 
+    /**
+     * Forwards an internal culture/camera refresh to the existing overlay without activating a disabled cube.
+     * @public
+     * @returns {void}
+     */
+    refreshViewCube() {
+        this.#babylonJSController?.refreshViewCube();
+    }
+
     /**
      * Returns a snapshot of all available animations and their current state.
      * @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();