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

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;
+                }
+            }
+        }
+    }
+}