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

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

@@ -0,0 +1,557 @@
+import { PrefViewerMenu3DStyles } from "./styles.js";
+import BabylonJSController from "./babylonjs-controller.js";
+import { DEFAULT_LOCALE, resolveLocale, translate } from "./localization/i18n.js";
+
+/**
+ * PrefViewerMenu3D - Localized floating control surface for Babylon render toggles used by PrefViewer.
+ *
+ * Capabilities:
+ *  - 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.
+ *  - Emits `pref-viewer-menu-apply` whenever the user confirms toggles, allowing PrefViewer/BabylonJSController to persist.
+ *  - Shows transient status/error messages and per-switch pending states while operations complete.
+ *
+ * Public API:
+ *  - `setSettings(settings)`: hydrates switches with the latest applied render snapshot.
+ *  - `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.
+ *  - `setCulture(cultureId)`: forces a locale change and re-renders copy from the i18n layer.
+ *
+ * Lifecycle & Integration:
+ *  - Automatically creates shadow DOM/UI in `connectedCallback`, wiring hover/focus listeners and ARIA labels.
+ *  - Exposes a single `culture` observed attribute so hosts can drive localization declaratively.
+ *
+ * Accessibility:
+ *  - Uses ARIA labels/live regions for the toggle button, dialog panel, pending indicator, and status slot.
+ */
+export default class PrefViewerMenu3D extends HTMLElement {
+    #elements = {
+        applyButton: null,
+        panel: null,
+        pendingLabel: null,
+        status: null,
+        subtitle: null,
+        switches: {},
+        switchCopyNodes: {},
+        switchWrappers: {},
+        title: null,
+        toggleButton: null,
+    };
+
+    #handles = {
+        onApplyClick: null,
+        onHostLeave: null,
+        onPanelEnter: null,
+        onSwitchChange: null,
+        onToggleEnter: null,
+    };
+
+    #DEFAULT_RENDER_SETTINGS = { ...BabylonJSController.DEFAULT_RENDER_SETTINGS };
+    #MENU_SWITCHES = Object.keys(this.#DEFAULT_RENDER_SETTINGS);
+    #appliedSettings = { ...this.#DEFAULT_RENDER_SETTINGS };
+    #draftSettings = { ...this.#DEFAULT_RENDER_SETTINGS };
+    #statusTimeout = null;
+    #isApplying = false;
+    #isEnabled = true;
+
+    #culture = DEFAULT_LOCALE;
+    #texts = {};
+    
+    constructor() {
+        super();
+    }
+    
+    /**
+     * Returns the list of attributes to observe for changes.
+     * @public
+     * @returns {string[]} Array of attribute names to observe.
+     */
+    static get observedAttributes() {
+        return ["culture"];
+    }
+    
+    /**
+     * Reacts to observed attribute mutations, currently handling locale changes.
+     * @public
+     * @param {string} name - Attribute name that changed.
+     * @param {*} _old - Previous attribute value (unused).
+     * @param {*} value - New attribute value.
+     * @returns {void}
+     */
+    attributeChangedCallback(name, _old, value) {
+        if (name === "culture") {
+            this.#setCultureInternal(value || DEFAULT_LOCALE);
+        }
+    }
+
+    /**
+     * Lifecycle hook invoked when the element is added to the DOM.
+     * Builds the internal structure, wires listeners, and syncs switches with current settings.
+     * @public
+     * @returns {void}
+     */
+    connectedCallback() {
+        if (!this.#elements.toggleButton) {
+            this.#texts = this.#getMenuTexts();
+            this.#createDOMElements();
+            this.#cacheElements();
+            this.#attachEvents();
+            this.setSettings(this.#appliedSettings);
+        }
+    }
+
+    /**
+     * Lifecycle hook invoked when the element is removed from the DOM.
+     * Cleans up listeners and pending timers to avoid leaks.
+     * @public
+     * @returns {void}
+     */
+    disconnectedCallback() {
+        this.#detachEvents();
+        if (this.#statusTimeout) {
+            clearTimeout(this.#statusTimeout);
+            this.#statusTimeout = null;
+        }
+    }
+
+    /**
+     * Builds the shadow DOM structure for the toggle button, panel, switches, and footer controls.
+     * @private
+     * @returns {void}
+     */
+    #createDOMElements() {
+        const wrapper = document.createElement("div");
+        wrapper.className = "menu-wrapper";
+        wrapper.innerHTML = `
+            <button class="menu-toggle" type="button" aria-label="${this.#texts.title}">
+                <svg viewBox="0 0 24 24"><path d="M12,8A4,4 0 0,1 16,12A4,4 0 0,1 12,16A4,4 0 0,1 8,12A4,4 0 0,1 12,8M12,10A2,2 0 0,0 10,12A2,2 0 0,0 12,14A2,2 0 0,0 14,12A2,2 0 0,0 12,10M10,22C9.75,22 9.54,21.82 9.5,21.58L9.13,18.93C8.5,18.68 7.96,18.34 7.44,17.94L4.95,18.95C4.73,19.03 4.46,18.95 4.34,18.73L2.34,15.27C2.21,15.05 2.27,14.78 2.46,14.63L4.57,12.97L4.5,12L4.57,11L2.46,9.37C2.27,9.22 2.21,8.95 2.34,8.73L4.34,5.27C4.46,5.05 4.73,4.96 4.95,5.05L7.44,6.05C7.96,5.66 8.5,5.32 9.13,5.07L9.5,2.42C9.54,2.18 9.75,2 10,2H14C14.25,2 14.46,2.18 14.5,2.42L14.87,5.07C15.5,5.32 16.04,5.66 16.56,6.05L19.05,5.05C19.27,4.96 19.54,5.05 19.66,5.27L21.66,8.73C21.79,8.95 21.73,9.22 21.54,9.37L19.43,11L19.5,12L19.43,13L21.54,14.63C21.73,14.78 21.79,15.05 21.66,15.27L19.66,18.73C19.54,18.95 19.27,19.04 19.05,18.95L16.56,17.95C16.04,18.34 15.5,18.68 14.87,18.93L14.5,21.58C14.46,21.82 14.25,22 14,22H10M11.25,4L10.88,6.61C9.68,6.86 8.62,7.5 7.85,8.39L5.44,7.35L4.69,8.65L6.8,10.2C6.4,11.37 6.4,12.64 6.8,13.8L4.68,15.36L5.43,16.66L7.86,15.62C8.63,16.5 9.68,17.14 10.87,17.38L11.24,20H12.76L13.13,17.39C14.32,17.14 15.37,16.5 16.14,15.62L18.57,16.66L19.32,15.36L17.2,13.81C17.6,12.64 17.6,11.37 17.2,10.2L19.31,8.65L18.56,7.35L16.15,8.39C15.38,7.5 14.32,6.86 13.12,6.62L12.75,4H11.25Z" /></svg>
+            </button>
+            <div class="menu-panel" role="dialog" aria-label="${this.#texts.title}">
+                <div class="menu-header">
+                    <p class="menu-title">${this.#texts.title}</p>
+                    <p class="menu-subtitle">${this.#texts.subtitle}</p>
+                </div>
+                <div class="menu-switches">
+                    ${this.#MENU_SWITCHES.map((key) => this.#renderSwitchRow(key, this.#texts)).join("")}
+                </div>
+                <div class="menu-footer">
+                    <span class="menu-pending" aria-live="polite">${this.#texts.pendingLabel}</span>
+                    <span class="menu-status" aria-live="assertive"></span>
+                    <button class="menu-apply" type="button" disabled>${this.#texts.actions.apply}</button>
+                </div>
+            </div>
+        `;
+        const style = document.createElement("style");
+        style.textContent = PrefViewerMenu3DStyles;
+        this.append(wrapper, style);
+    }
+
+    /**
+     * Generates the HTML fragment for a single render-setting switch.
+     * @private
+     * @param {string} key - Render setting identifier (aa, ssao, ibl, etc.).
+     * @param {object} copy - Locale-aware copy bundle used for labels.
+     * @returns {string} HTML string representing the switch row.
+     */
+    #renderSwitchRow(key, copy) {
+        const switchCopy = copy.switches?.[key] ?? {};
+        const label = switchCopy.label ?? key;
+        const helper = switchCopy.helper ?? "";
+        return `
+            <label class="menu-switch" data-setting="${key}">
+                <span class="menu-switch-copy">
+                    <span class="menu-switch-title">${label}</span>
+                    <small>${helper}</small>
+                </span>
+                <span class="menu-switch-control">
+                    <input type="checkbox" data-setting="${key}">
+                    <span class="menu-switch-visual" aria-hidden="true"></span>
+                </span>
+            </label>
+        `;
+    }
+
+    /**
+     * Pulls the full translation namespace for the menu using the active culture.
+     * @private
+     * @returns {object} Resolved translation object or an empty fallback.
+     */
+    #getMenuNamespace() {
+        const namespace = translate("prefViewer.menu3d", { locale: this.#culture });
+        return namespace && typeof namespace === "object" ? namespace : {};
+    }
+
+    /**
+     * Normalizes locale data into a predictable shape consumed by the UI helpers.
+     * @private
+     * @returns {object} Structured copy bundle for titles, actions, status, and switches.
+     */
+    #getMenuTexts() {
+        const data = this.#getMenuNamespace();
+        return {
+            title: data.title || "",
+            subtitle: data.subtitle || "",
+            pendingLabel: data.pendingLabel || "",
+            actions: {
+                apply: data.actions?.apply || "",
+                applying: data.actions?.applying || "",
+            },
+            status: {
+                error: data.status?.error || "",
+            },
+            switches: data.switches || {},
+        };
+    }
+
+    /**
+     * Replaces all textual UI nodes with the latest localized strings.
+     * @private
+     * @returns {void}
+     */
+    #refreshLocaleTexts() {
+        if (!this.#elements.toggleButton) {
+            return;
+        }
+        this.#elements.toggleButton.setAttribute("aria-label", this.#texts.title);
+        this.#elements.panel?.setAttribute("aria-label", this.#texts.title);
+        if (this.#elements.title) {
+            this.#elements.title.textContent = this.#texts.title;
+        }
+        if (this.#elements.subtitle) {
+            this.#elements.subtitle.textContent = this.#texts.subtitle;
+        }
+        if (this.#elements.pendingLabel) {
+            this.#elements.pendingLabel.textContent = this.#texts.pendingLabel;
+        }
+        if (this.#elements.applyButton) {
+            this.#elements.applyButton.textContent = this.#isApplying ? this.#texts.actions.applying : this.#texts.actions.apply;
+        }
+        Object.entries(this.#elements.switchCopyNodes).forEach(([key, nodes]) => {
+            if (!nodes) {
+                return;
+            }
+            const switchCopy = this.#texts.switches?.[key] ?? {};
+            nodes.title && (nodes.title.textContent = switchCopy.label ?? key);
+            nodes.helper && (nodes.helper.textContent = switchCopy.helper ?? "");
+        });
+    }
+
+    /**
+     * Resolves and applies a locale internally, updating texts when it changes.
+     * @private
+     * @param {string} [cultureId=DEFAULT_LOCALE] - Desired locale identifier.
+     * @returns {string} The applied locale.
+     */
+    #setCultureInternal(cultureId = DEFAULT_LOCALE) {
+        const resolved = resolveLocale(cultureId);
+        if (resolved === this.#culture) {
+            return this.#culture;
+        }
+        this.#culture = resolved;
+        this.#texts = this.#getMenuTexts();
+        this.#refreshLocaleTexts();
+        return this.#culture;
+    }
+
+    /**
+     * Caches references to frequently used DOM nodes for faster lookups.
+     * @private
+     * @returns {void}
+     */
+    #cacheElements() {
+        this.#elements.toggleButton = this.querySelector(".menu-toggle");
+        this.#elements.panel = this.querySelector(".menu-panel");
+        this.#elements.title = this.querySelector(".menu-title");
+        this.#elements.subtitle = this.querySelector(".menu-subtitle");
+        this.#elements.applyButton = this.querySelector(".menu-apply");
+        this.#elements.pendingLabel = this.querySelector(".menu-pending");
+        this.#elements.status = this.querySelector(".menu-status");
+        this.#MENU_SWITCHES.forEach((key) => {
+            this.#elements.switches[key] = this.querySelector(`input[data-setting="${key}"]`);
+            const wrapper = this.querySelector(`.menu-switch[data-setting="${key}"]`);
+            this.#elements.switchWrappers[key] = wrapper;
+            this.#elements.switchCopyNodes[key] = {
+                title: wrapper ? wrapper.querySelector(".menu-switch-title") : null,
+                helper: wrapper ? wrapper.querySelector("small") : null,
+            };
+        });
+    }
+
+    /**
+     * Attaches all interactive event listeners for hover, focus, switch changes, and apply clicks.
+     * @private
+     * @returns {void}
+     */
+    #attachEvents() {
+        if (!this.#elements.toggleButton || !this.#elements.panel) {
+            return;
+        }
+        this.#handles.onToggleEnter = () => this.#openMenu();
+        this.#handles.onPanelEnter = () => this.#openMenu();
+        this.#handles.onHostLeave = (event) => {
+            if (event.relatedTarget && this.contains(event.relatedTarget)) {
+                return;
+            }
+            this.#closeMenu();
+        };
+        this.#handles.onSwitchChange = (event) => this.#handleSwitchChange(event);
+        this.#handles.onApplyClick = () => this.#emitApply();
+
+        this.#elements.toggleButton.addEventListener("mouseenter", this.#handles.onToggleEnter);
+        this.#elements.toggleButton.addEventListener("focus", this.#handles.onToggleEnter);
+        this.#elements.panel.addEventListener("mouseenter", this.#handles.onPanelEnter);
+        this.addEventListener("mouseleave", this.#handles.onHostLeave);
+        Object.values(this.#elements.switches).forEach((input) => input?.addEventListener("change", this.#handles.onSwitchChange));
+        this.#elements.applyButton.addEventListener("click", this.#handles.onApplyClick);
+    }
+
+    /**
+     * Removes previously attached event listeners, guarding against partially initialized states.
+     * @private
+     * @returns {void}
+     */
+    #detachEvents() {
+        if (!this.#elements.toggleButton) {
+            return;
+        }
+        this.#elements.toggleButton.removeEventListener("mouseenter", this.#handles.onToggleEnter);
+        this.#elements.toggleButton.removeEventListener("focus", this.#handles.onToggleEnter);
+        this.#elements.panel?.removeEventListener("mouseenter", this.#handles.onPanelEnter);
+        this.removeEventListener("mouseleave", this.#handles.onHostLeave);
+        Object.values(this.#elements.switches).forEach((input) => input?.removeEventListener("change", this.#handles.onSwitchChange));
+        this.#elements.applyButton?.removeEventListener("click", this.#handles.onApplyClick);
+    }
+
+    /**
+     * Opens the menu panel when the viewer is hovered and the menu is enabled.
+     * @private
+     * @returns {void}
+     */
+    #openMenu() {
+        if (!this.#isEnabled || !this.hasAttribute("data-viewer-hover")) {
+            return;
+        }
+        this.setAttribute("data-open", "true");
+    }
+
+    /**
+     * Closes the menu panel and removes its open state attribute.
+     * @private
+     * @returns {void}
+     */
+    #closeMenu() {
+        this.removeAttribute("data-open");
+    }
+
+    /**
+     * Handles switch changes by updating the draft settings and recomputing pending indicators.
+     * @private
+     * @param {Event} event - Change event triggered by a switch input.
+     * @returns {void}
+     */
+    #handleSwitchChange(event) {
+        const key = event.currentTarget?.dataset?.setting;
+        if (!key) {
+            return;
+        }
+        this.#draftSettings[key] = event.currentTarget.checked;
+        this.#updatePendingState();
+    }
+
+    /**
+     * Emits the apply event with the current draft settings when changes are pending.
+     * @private
+     * @returns {void}
+     */
+    #emitApply() {
+        if (this.#isApplying || !this.#hasPendingChanges()) {
+            return;
+        }
+        const detail = { settings: { ...this.#draftSettings } };
+        this.dispatchEvent(new CustomEvent("pref-viewer-menu-apply", { detail, bubbles: true, composed: true }));
+    }
+
+    /**
+     * Synchronizes checkbox states with the draft settings snapshot.
+     * @private
+     * @returns {void}
+     */
+    #updateSwitches() {
+        Object.entries(this.#elements.switches).forEach(([key, input]) => {
+            if (input) {
+                input.checked = Boolean(this.#draftSettings[key]);
+            }
+        });
+    }
+
+    /**
+     * Toggles pending labels, apply button state, and per-switch markers based on outstanding changes.
+     * @private
+     * @returns {void}
+     */
+    #updatePendingState() {
+        const pendingKeys = this.#getPendingKeys();
+        const pending = pendingKeys.length > 0;
+        if (this.#elements.pendingLabel) {
+            this.#elements.pendingLabel.hidden = !pending;
+        }
+        if (!this.#isApplying && this.#elements.applyButton) {
+            this.#elements.applyButton.disabled = !pending;
+        }
+        this.#updateSwitchPendingIndicators(pendingKeys);
+    }
+
+    /**
+     * Calculates which render keys differ between draft and applied snapshots.
+     * @private
+     * @returns {string[]} Keys currently pending application.
+     */
+    #getPendingKeys() {
+        return Object.keys(this.#DEFAULT_RENDER_SETTINGS).filter((key) => this.#draftSettings[key] !== this.#appliedSettings[key]);
+    }
+
+    /**
+     * Convenience helper to check if any pending changes exist.
+     * @private
+     * @returns {boolean}
+     */
+    #hasPendingChanges() {
+        return this.#getPendingKeys().length > 0;
+    }
+
+    /**
+     * Adds or removes the `data-pending` attribute on switch wrappers to visually flag unsaved toggles.
+     * @private
+     * @param {string[]} pendingKeys - Keys currently pending.
+     * @returns {void}
+     */
+    #updateSwitchPendingIndicators(pendingKeys = []) {
+        Object.entries(this.#elements.switchWrappers).forEach(([key, wrapper]) => {
+            if (!wrapper) {
+                return;
+            }
+            wrapper.toggleAttribute("data-pending", pendingKeys.includes(key));
+        });
+    }
+
+    /**
+     * Shows a transient status message in the footer and schedules it to auto-clear.
+     * @private
+     * @param {string} message - The status text to display.
+     * @returns {void}
+     */
+    #setStatusMessage(message) {
+        if (!this.#elements.status) {
+            return;
+        }
+        this.#elements.status.textContent = message;
+        if (message) {
+            this.setAttribute("data-status", "visible");
+        } else {
+            this.removeAttribute("data-status");
+        }
+        if (this.#statusTimeout) {
+            clearTimeout(this.#statusTimeout);
+            this.#statusTimeout = null;
+        }
+        if (message) {
+            const schedule = typeof window !== "undefined" ? window.setTimeout : setTimeout;
+            this.#statusTimeout = schedule(() => {
+                this.#elements.status.textContent = "";
+                this.removeAttribute("data-status");
+                this.#statusTimeout = null;
+            }, 4000);
+        }
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
+
+    /**
+     * Locks or unlocks the menu while changes are applied and updates the footer status text.
+     * @public
+     * @param {boolean} isApplying - Whether an apply operation is currently running.
+     * @param {boolean} [hasError=false] - Optional flag to show an error message.
+     * @returns {void}
+     */
+    setApplying(isApplying, hasError = false) {
+        this.#isApplying = isApplying;
+        this.toggleAttribute("data-applying", isApplying);
+        if (this.#elements.applyButton) {
+            this.#elements.applyButton.textContent = isApplying ? this.#texts.actions.applying : this.#texts.actions.apply;
+            this.#elements.applyButton.disabled = isApplying || !this.#hasPendingChanges();
+        }
+        if (hasError) {
+            this.#setStatusMessage(this.#texts.status.error);
+        } else if (!isApplying) {
+            this.#setStatusMessage("");
+        }
+    }
+    
+    /**
+     * 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);
+        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
+     * @param {boolean} isEnabled - True to show the menu, false to hide and reset hover state.
+     * @returns {void}
+     */
+    setEnabled(isEnabled) {
+        this.#isEnabled = Boolean(isEnabled);
+        this.toggleAttribute("hidden", !this.#isEnabled);
+        if (!this.#isEnabled) {
+            this.removeAttribute("data-viewer-hover");
+            this.#closeMenu();
+        }
+    }
+
+    /**
+     * Applies a new set of render settings to the UI, resetting draft state and pending markers.
+     * @public
+     * @param {object} settings - Render settings snapshot from PrefViewer.
+     * @returns {void}
+     */
+    setSettings(settings = {}) {
+        this.#appliedSettings = { ...this.#DEFAULT_RENDER_SETTINGS, ...settings };
+        this.#draftSettings = { ...this.#appliedSettings };
+        this.#updateSwitches();
+        this.#updatePendingState();
+        this.setApplying(false);
+        this.#setStatusMessage("");
+    }
+    
+    /**
+     * Receives viewer hover state so the menu only opens when the user interacts with the 3D viewport.
+     * @public
+     * @param {boolean} isHovering - True when the viewer is hovered.
+     * @returns {void}
+     */
+    setViewerHover(isHovering) {
+        if (!this.#isEnabled) {
+            return;
+        }
+        if (isHovering) {
+            this.setAttribute("data-viewer-hover", "true");
+        } else {
+            this.removeAttribute("data-viewer-hover");
+            this.#closeMenu();
+        }
+    }
+}

package/src/pref-viewer-task.js

@@ -21,6 +21,7 @@
 export default class PrefViewerTask {
     static Types = Object.freeze({
         Config: "config",
+        Culture: "culture",
         Drawing: "drawing",
         Environment: "environment",
         Materials: "materials",