@preference-sl/pref-viewer 2.11.0-beta.0 → 2.11.0-beta.10

package/src/pref-viewer-dialog.js

@@ -0,0 +1,139 @@
+/**
+ * PrefViewerDialog - Custom Web Component for displaying modal dialogs in PrefViewer.
+ *
+ * Overview:
+ *  - Provides a modal dialog overlay for user interactions such as downloads or confirmations.
+ *  - Handles DOM creation, styling, and open/close logic.
+ *  - Ensures dialog content is centered and styled appropriately.
+ *  - Automatically focuses the canvas when closed for improved accessibility.
+ *
+ * Usage:
+ *  - Use as a custom HTML element: <pref-viewer-dialog></pref-viewer-dialog>
+ *  - Call open(title, content, footer) to display the dialog with a header, content, and footer.
+ *  - Call close() to hide and remove the dialog.
+ *
+ * Methods:
+ *  - constructor(): Initializes the custom element.
+ *  - connectedCallback(): Called when the element is added to the DOM; sets up DOM and styles.
+ *  - disconnectedCallback(): Called when the element is removed from the DOM; cleans up resources.
+ *  - open(title, content, footer): Displays the dialog and sets its header, content, and footer.
+ *  - close(): Hides and removes the dialog, refocuses the canvas if available.
+ *  - #createDOMElements(): Creates the dialog structure and applies styles.
+ */
+export class PrefViewerDialog extends HTMLElement {
+    #wrapper = null;
+    #header = null;
+    #content = null;
+    #footer = null;
+
+    /**
+     * Initializes the custom dialog element.
+     * Only calls super(); heavy initialization is deferred to connectedCallback.
+     */
+    constructor() {
+        super();
+    }
+
+    /**
+     * Called when the element is inserted into the DOM.
+     * Sets up the dialog's DOM structure and styles.
+     * @returns {void}
+     */
+    connectedCallback() {
+        this.#createDOMElements();
+    }
+
+    /**
+     * Called when the element is removed from the DOM.
+     * Cleans up resources and event listeners.
+     * @returns {void}
+     */
+    disconnectedCallback() {
+        this.removeEventListener("click", this.#closeOnBackdropClick.bind(this));
+    }
+
+    /**
+     * Creates the dialog's DOM structure and applies CSS styles.
+     * Adds a click handler to close the dialog when clicking outside the content.
+     * @private
+     * @returns {void}
+     */
+    #createDOMElements() {
+        this.#wrapper = document.createElement("div");
+        this.#wrapper.classList.add("dialog-wrapper");
+        this.#wrapper.innerHTML = `
+            <div class="dialog-header"><h3 class="dialog-header-title"></h3></div>
+            <div class="dialog-content"></div>
+            <div class="dialog-footer"></div>`;
+        this.append(this.#wrapper);
+
+        const style = document.createElement("style");
+        style.textContent = `@import "/dist/css/pref-viewer-dialog.css";`;
+        this.append(style);
+
+        this.addEventListener("click", this.#closeOnBackdropClick.bind(this));
+
+        this.#header = this.#wrapper.querySelector(".dialog-header");
+        this.#content = this.#wrapper.querySelector(".dialog-content");
+        this.#footer = this.#wrapper.querySelector(".dialog-footer");
+    }
+
+    #closeOnBackdropClick(event) {
+        if (event.target === this) {
+            this.close();
+        }
+    }
+
+    /**
+     * Opens the dialog and sets its header, content, and footer.
+     * @param {string} title - The dialog title to display in the header.
+     * @param {string} content - The HTML content to display in the dialog body.
+     * @param {string} footer - The HTML content to display in the dialog footer (e.g., action buttons).
+     * @returns {boolean} True if the dialog was opened, false if no content was provided.
+     */
+    open(title = "", content = "", footer = "") {
+        if (this.#wrapper === null || this.#header === null || this.#content === null || this.#footer === null) {
+            return false;
+        }
+        if (title === "" && content === "" && footer === "") {
+            return false;
+        }
+
+        if (title === "") {
+            this.#header.style.display = "none";
+        }
+        if (footer === "") {
+            this.#footer.style.display = "none";
+        }
+
+        this.#header.querySelector(".dialog-header-title").innerHTML = title;
+        this.#content.innerHTML = content;
+        this.#footer.innerHTML = footer;
+        this.setAttribute("open", "");
+        return true;
+    }
+
+    /**
+     * Closes and removes the dialog from the DOM.
+     * @returns {void}
+     */
+    close() {
+        this.removeAttribute("open");
+        const parent = this.getRootNode().host;
+        if (parent) {
+            // Refocus 3D canvas or 2D component for accessibility
+            const canvas = parent.shadowRoot.querySelector("pref-viewer-3d[visible='true'] canvas");
+            if (canvas) {
+                canvas.focus();
+            } else {
+                const component2D = parent.shadowRoot.querySelector("pref-viewer-2d[visible='true']");
+                if (component2D) {
+                    component2D.focus();
+                }
+            }
+
+        }
+        this.#wrapper = this.#header = this.#content = this.#footer = null;
+        this.remove();
+    }
+}

package/src/pref-viewer-task.js

@@ -0,0 +1,54 @@
+/**
+ * PrefViewerTask - Represents a single task or operation to be processed by the PrefViewer.
+ *
+ * Responsibilities:
+ *  - Encapsulates the payload and type of a viewer task (e.g., loading a model, updating materials).
+ *  - Validates the task type against a predefined set of allowed types.
+ *  - Provides an immutable instance to ensure task integrity.
+ *
+ * Usage:
+ *  - Instantiate with a value and a type:
+ *      new PrefViewerTask(data, PrefViewerTask.Types.Model)
+ *  - Access the payload via the `value` property and the normalized type via the `type` property.
+ *
+ * Static Properties:
+ *  - Types: An object containing all allowed task types as string constants.
+ *
+ * Constructor:
+ *  - Validates the type (case-insensitive) and throws a TypeError if invalid.
+ *  - Freezes the instance to prevent further modification.
+ */
+export class PrefViewerTask {
+    static Types = Object.freeze({
+        Config: "config",
+        Drawing: "drawing",
+        Environment: "environment",
+        Materials: "materials",
+        Model: "model",
+        Options: "options",
+        Visibility: "visibility",
+    });
+
+    /**
+     * Creates a new PrefViewerTask instance.
+     * Validates that the provided type matches one of the allowed task types (case-insensitive).
+     * If the type is invalid, throws a TypeError.
+     * The instance is frozen to prevent further modification.
+     *
+     * @param {*} value - The payload or data associated with the task.
+     * @param {string} type - The type of task; must match one of PrefViewerTask.Types values.
+     * @throws {TypeError} If the type is not valid.
+     */
+    constructor(value, type) {
+        this.value = value;
+
+        const t = typeof type === "string" ? type.toLowerCase() : String(type).toLowerCase();
+        const allowed = Object.values(PrefViewerTask.Types);
+        if (!allowed.includes(t)) {
+            throw new TypeError(`PrefViewerTask: invalid type "${type}". Allowed types: ${allowed.join(", ")}`);
+        }
+        this.type = t;
+
+        Object.freeze(this);
+    }
+}

package/src/svg-resolver.js

@@ -0,0 +1,281 @@
+import isSvg from "is-svg";
+import { initDb, loadModel } from "./gltf-storage.js";
+
+/**
+ * SVGResolver - Utility class for resolving, decoding, and validating SVG resources from multiple sources.
+ *
+ * Responsibilities:
+ *  - Handles SVG input from:
+ *      * IndexedDB records (storage.db, storage.table, storage.id)
+ *      * remote URLs (storage.url)
+ *      * data URIs (base64 or plain SVG) (storage.url)
+ *      * direct SVG strings (storage.url)
+ *  - Decodes base64 and validates SVG content.
+ *  - Avoids unnecessary reloads by comparing size and Last-Modified timestamp.
+ *  - Provides a unified API for consumers to obtain SVG content and metadata.
+ *
+ * Usage:
+ *  - Instantiate with an initial SVG state object (required).
+ *      Example: const resolver = new SVGResolver({ value: "", size: 0, timeStamp: null, update: true });
+ *  - Call getSVG(svgConfig) to resolve and update the SVG state.
+ *      Example: await resolver.getSVG({ storage: { url: "data:image/svg+xml;base64,..." } });
+ *
+ * Public methods:
+ *  - getSVG(svgConfig, svg?): Resolves and prepares SVG from the given configuration, updating internal and optionally external state.
+ *
+ * Internal methods:
+ *  - #initializeStorage(db, table): Ensures IndexedDB store is initialized.
+ *  - #parseSource(source): Decodes and validates SVG from string or data URI.
+ *  - #getServerFileMetaData(uri): Gets file size and last modified from server.
+ *  - #getServerSVG(uri): Downloads SVG text from server.
+ *
+ * Events:
+ *  - None (state is updated via returned object).
+ *
+ * Notes:
+ *  - The internal SVG state is always kept up-to-date and can be referenced externally if passed in the constructor.
+ *  - Designed for extensibility and integration with custom storage or fetch logic.
+ */
+export default class SVGResolver {
+    #svg = {
+        value: "",
+        size: 0,
+        timeStamp: null,
+        update: true,
+    };
+
+    /**
+     * Create a new SVGResolver instance.
+     * @param {{value?:string, size?:number, timeStamp?:string|null, update?:boolean}=} svg - Optional initial SVG state to seed the resolver's internal cache.
+     *   If omitted, the internal state defaults to: { value: "", size: 0, timeStamp: null, update: true }
+     * @description
+     * The 'svg' parameter allows you to preload the resolver with a known SVG state that will always be up-to-date since it's a referenced object.
+     * If this parameter isn't passed when creating the instance, it must be passed as a parameter in the 'getSVG' public method to keep it updated.
+     */
+    constructor(svg) {
+        if (svg && typeof svg === "object") {
+            this.#svg = svg;
+        }
+    }
+
+    /**
+     * Ensure the IndexedDB object store for GLTF/SVG storage is initialized.
+     * @private
+     * @param {string} db - Database name.
+     * @param {string} table - Object store name.
+     * @returns {Promise<void>}
+     * @description
+     * If a global PrefConfigurator.db already references the requested DB and table, no action is taken. Otherwise delegates to initDb to create/open the store.
+     */
+    async #initializeStorage(db, table) {
+        if (typeof window !== "undefined" && window.PrefConfigurator.db && window.PrefConfigurator.db.name === db && window.PrefConfigurator.db.objectStoreNames.contains(table)) {
+            return;
+        }
+        await initDb(db, table);
+    }
+
+    /**
+     * Parse an input that may be a plain SVG string or a data URI (possibly base64).
+     * @private
+     * @param {string} source - Data URI or raw string to decode/check.
+     * @returns {{value: string|null, size: number}} value when detected/decoded, and size (length of the text string).
+     */
+    #parseSource(source) {
+        let value = null;
+        let size = 0;
+
+        if (typeof source !== "string") {
+            return [value, size];
+        }
+
+        if (isSvg(source)) {
+            value = source;
+            size = source.length;
+            return [value, size];
+        }
+
+        let raw;
+        if (source.startsWith("data:")) {
+            const commaIndex = source.indexOf(",");
+            raw = commaIndex !== -1 ? source.slice(commaIndex + 1) : source;
+        } else {
+            raw = source;
+        }
+
+        if (isSvg(raw)) {
+            size = raw.length;
+            value = raw;
+            return [value, size];
+        }
+
+        let decoded = "";
+        try {
+            decoded = atob(raw);
+        } catch {
+            return [value, size];
+        }
+
+        if (isSvg(decoded)) {
+            size = raw.length;
+            value = decoded;
+            return [value, size];
+        }
+
+        return [value, size];
+    }
+
+    /**
+     * Perform a HEAD request to gather server-side file metadata (Content-Length and Last-Modified).
+     * @private
+     * @param {string} uri - Resource URI to probe.
+     * @returns {Promise<{size:number,timeStamp:string|null}>} Object with size (0 when unknown) and ISO timeStamp or null.
+     */
+    async #getServerFileMetaData(uri) {
+        let data = {
+            size: 0,
+            timeStamp: null,
+        };
+        return new Promise((resolve) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("HEAD", uri, true);
+            xhr.responseType = "blob";
+            xhr.onload = () => {
+                if (xhr.status === 200) {
+                    const lastModified = xhr.getResponseHeader("Last-Modified");
+                    data.timeStamp = lastModified ? new Date(lastModified).toISOString() : null;
+                    const contentLength = xhr.getResponseHeader("Content-Length");
+                    data.size = contentLength ? parseInt(contentLength, 10) : 0;
+                    resolve(data);
+                } else {
+                    resolve(data);
+                }
+            };
+            xhr.onerror = () => {
+                resolve(data);
+            };
+            xhr.send();
+        });
+    }
+
+    /**
+     * Download an SVG document as text from the server.
+     * @private
+     * @param {string} uri - Resource URI.
+     * @returns {Promise<string>} The SVG text or empty string on failure.
+     */
+    async #getServerSVG(uri) {
+        let svg = "";
+        return new Promise((resolve) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("GET", uri, true);
+            xhr.responseType = "text";
+            xhr.onload = () => {
+                if (xhr.status === 200) {
+                    svg = xhr.responseText;
+                    resolve(svg);
+                } else {
+                    resolve(svg);
+                }
+            };
+            xhr.onerror = () => {
+                resolve(svg);
+            };
+            xhr.send();
+        });
+    }
+
+    /**
+     * Resolve and prepare an SVG from multiple storage forms.
+     * @public
+     * @param {object|string} svgConfig - Configuration object. Expected shape for storage:
+     *   { storage: { url: "<url>" } } // remote URL or data URI (base64 or plain)
+     *   { storage: { db: "<db>", table: "<table>", id: "<id>" } } // IndexedDB record
+     * @param {object} [svg] - Optional external SVG state object to seed/update. If provided, the resolver
+     *   updates this object in-place: { value: string, size: number, timeStamp: string|null, update: boolean }.
+     * @returns {Promise<false|{value:string,size:number,timeStamp:string|null,update:boolean}>}
+     *   - Resolves to false when no update is required or on error.
+     *   - Resolves to the internal SVG state object when an update was prepared.
+     * @description
+     *  - Accepts SVG (base64 or plain string) from IndexedDB (storage.db/table/id), from a data URI (base64 or plain string) (storage.url),
+     *    from a remote URL (storage.url) or from direct SVG string (storage.url).
+     *  - Compares sizes and timestamps to avoid unnecessary reloads.
+     *  - If the 'svg' parameter was provided when creating the instance, the referenced object will also be updated.
+     */
+    async getSVG(svgConfig, svg) {
+        if (svg && typeof svg === "object") {
+            this.#svg = svg;
+        }
+        const storage = svgConfig?.storage;
+        if (!storage) {
+            return false;
+        }
+
+        let source = storage.url || null;
+        let idbSize = 0;
+        let idbTimeStamp = null;
+
+        // SVG from an entry stored in IndexedDB (storage.db, storage.table, storage.id)
+        if (storage.db && storage.table && storage.id) {
+            await this.#initializeStorage(storage.db, storage.table);
+            const object = await loadModel(storage.id, storage.table);
+            source = object.data;
+            idbSize = object.size;
+            idbTimeStamp = object.timeStamp;
+            if (this.#svg.size === idbSize && this.#svg.timeStamp === idbTimeStamp) {
+                this.#svg.update = false;
+                return false;
+            } else {
+                this.#svg.update = true;
+            }
+        }
+
+        if (!source) {
+            this.#svg.update = false;
+            return false;
+        }
+
+        let [svgValue, svgSize] = this.#parseSource(source);
+
+        // SVG decoded successfully from Base64 or plain string, from object stored in IndexedDB (storage.db, storage.table, storage.id) or Base64 data URI (storage.url)
+        if (svgValue && svgSize) {
+            if (this.#svg.update) {
+                // From object stored in IndexedDB (storage.db, storage.table, storage.id)
+                this.#svg.value = svgValue;
+                this.#svg.size = idbSize;
+                this.#svg.timeStamp = idbTimeStamp;
+                return this.#svg;
+            } else {
+                // From Base64 data URI (storage.url)
+                if (this.#svg.size === svgSize && this.#svg.timeStamp === null) {
+                    this.#svg.update = false;
+                    return false;
+                } else {
+                    this.#svg.size = svgSize;
+                    this.#svg.timeStamp = null;
+                    this.#svg.update = true;
+                    this.#svg.value = svgValue;
+                    return this.#svg;
+                }
+            }
+        } else {
+            // SVG from remote URL (storage.url)
+            let fileData = await this.#getServerFileMetaData(source);
+            if (this.#svg.size === fileData.size && this.#svg.timeStamp === fileData.timeStamp) {
+                this.#svg.update = false;
+                return false;
+            } else {
+                svgValue = await this.#getServerSVG(source);
+                if (isSvg(svgValue)) {
+                    this.#svg.size = fileData.size;
+                    this.#svg.timeStamp = fileData.timeStamp;
+                    this.#svg.update = true;
+                    this.#svg.value = svgValue;
+                    return this.#svg;
+                } else {
+                    this.#svg.update = false;
+                    return false;
+                }
+            }
+        }
+    }
+}