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

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

@@ -0,0 +1,39 @@
+/* Variables */
+pref-viewer-2d {
+    --pref-viewer-2d-bg-color: #ffffff;
+    --pref-viewer-2d-svg-padding: 10px;
+}
+
+pref-viewer-2d[visible="true"] {
+    display: block;
+}
+
+pref-viewer-2d[visible="false"] {
+    display: none;
+}
+
+pref-viewer-2d {
+    grid-column: 1;
+    grid-row: 1;
+    overflow: hidden;
+    min-width: 0; 
+    min-height: 0;
+    align-self: stretch;
+    justify-self: stretch;
+    background: var(--pref-viewer-2d-bg-color);
+}
+
+pref-viewer-2d,
+pref-viewer-2d>div,
+pref-viewer-2d>div>svg {
+    width: 100%;
+    height: 100%;
+    display: block;
+    position: relative;
+    outline: none;
+    box-sizing: border-box;
+}
+
+pref-viewer-2d>div>svg {
+    padding: var(--pref-viewer-2d-svg-padding);
+}

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

@@ -0,0 +1,28 @@
+pref-viewer-3d[visible="true"] {
+    display: block;
+}
+
+pref-viewer-3d[visible="false"] {
+    display: none;
+}
+
+pref-viewer-3d {
+    grid-column: 1;
+    grid-row: 1;
+    overflow: hidden;
+    min-width: 0; 
+    min-height: 0;
+    align-self: stretch;
+    justify-self: stretch;
+}
+
+pref-viewer-3d,
+pref-viewer-3d>div,
+pref-viewer-3d>div>canvas {
+    width: 100%;
+    height: 100%;
+    display: block;
+    position: relative;
+    outline: none;
+    box-sizing: border-box;
+}

package/src/css/pref-viewer-dialog.css

@@ -0,0 +1,105 @@
+/* Variables */
+pref-viewer-dialog {
+    --brand-color: #ff6700;
+    --dialog-general-space: 16px;
+    --dialog-bg-color: #ffffff;
+    --dialog-backdrop-color: rgba(0, 0, 0, 0.25);
+    --dialog-border-color: #e7e7e7;
+    --dialog-border-radius: 8px;
+    --dialog-box-shadow: 0 4px 24px rgba(0, 0, 0, 0.25);
+    --button-default-bg-color: #bbbbbb;
+    --button-default-bg-color-hover: #a1a1a1;
+    --button-primary-bg-color: color-mix(in oklab, var(--brand-color), white 25%);
+    --button-primary-bg-color-hover: var(--brand-color);
+    --button-border-radius: 4px;
+    --button-padding-horizontal: 16px;
+    --button-padding-vertical: 8px;
+}
+
+pref-viewer-dialog:not {
+    display: none;
+}
+
+pref-viewer-dialog[open] {
+    font-family: 'Roboto', ui-sans-serif, system-ui, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol, Noto Color Emoji;
+    grid-row: 1;
+    grid-column: 1;
+    overflow: hidden;
+    min-width: 0; 
+    min-height: 0;
+    align-self: stretch;
+    justify-self: stretch;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background-color: var(--dialog-backdrop-color);
+    position: relative;
+    z-index: 1000;
+}
+
+pref-viewer-dialog>.dialog-wrapper {
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    background: var(--dialog-bg-color);
+    border: 1px solid var(--dialog-border-color);
+    border-radius: var(--dialog-border-radius);
+    box-shadow: var(--dialog-box-shadow);
+    padding: 0;
+    min-width: 320px;
+    max-width: 90%;
+    max-height: 90%;
+    overflow: auto;
+}
+
+pref-viewer-dialog .dialog-header {
+    padding: var(--dialog-general-space);
+    border-bottom: 1px solid var(--dialog-border-color);
+}
+
+pref-viewer-dialog .dialog-header h3 {
+    margin: 0;
+    font-weight: 500;
+    font-size: 1.1em;
+}
+
+pref-viewer-dialog .dialog-content {
+    padding: var(--dialog-general-space);
+}
+
+pref-viewer-dialog .dialog-content h4 {
+    margin: 0;
+    font-weight: 500;
+    font-size: 1.05em;
+}
+
+pref-viewer-dialog .dialog-footer {
+    border-top: 1px solid var(--dialog-border-color);
+    padding: var(--dialog-general-space);
+    display: flex;
+    gap: var(--dialog-general-space);
+    justify-content: stretch;
+}
+
+pref-viewer-dialog .dialog-footer button {
+    width: 100%;
+    font-size: 1em;
+    padding: var(--button-padding-vertical) var(--button-padding-horizontal);
+    border-radius: var(--button-border-radius);
+    border: none;
+    background: var(--button-default-bg-color);
+    cursor: pointer;
+    transition: background 0.2s;
+}
+
+pref-viewer-dialog .dialog-footer button.primary {
+    background: var(--button-primary-bg-color);
+}
+
+pref-viewer-dialog .dialog-footer button:hover {
+    background: var(--button-default-bg-color-hover);
+}
+
+pref-viewer-dialog .dialog-footer button.primary:hover {
+    background: var(--button-primary-bg-color-hover);
+}

package/src/css/pref-viewer.css

@@ -0,0 +1,11 @@
+:host .pref-viewer-wrapper {
+    display: grid !important;
+    position: relative;
+    width: 100%;
+    height: 100%;
+    grid-template-columns: 1fr;
+    grid-template-rows: 1fr;
+    grid-gap: 0;
+    min-width: 0; 
+    min-height: 0;
+}

package/src/file-storage.js

@@ -1,12 +1,119 @@
-/**
- * FileStore class to manage file storage in IndexedDB using a promise-based wrapper around the IndexedDB API.
- * @see {@link https://github.com/jakearchibald/idb|GitHub - jakearchibald/idb: IndexedDB, but with promises}
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API|IndexedDB API - MDN}
- * @see {@link https://www.npmjs.com/package/idb|idb - npm}
- */
-
 import { openDB } from "idb";
 
+/**
+ * FileStorage - Class for managing file storage in IndexedDB with server synchronization.
+ *
+ * Overview:
+ *  - Provides a promise-based wrapper around the IndexedDB API for file caching.
+ *  - Automatically manages cache versioning by comparing server and cached file timestamps.
+ *  - Falls back to direct server access when IndexedDB is unavailable.
+ *  - Supports file blob retrieval, timestamp checking, and size queries.
+ *  - Uses the idb library for simplified IndexedDB operations.
+ *
+ * Dependencies:
+ *  - idb (IndexedDB wrapper library)
+ *  - Modern browser with IndexedDB support
+ *
+ * Constructor:
+ *  - FileStorage(dbName, osName): Creates a new FileStorage instance.
+ *    Parameters:
+ *      - dbName: Name of the IndexedDB database (default: "FilesDB")
+ *      - osName: Name of the object store (default: "FilesObjectStore")
+ *
+ * Private Methods:
+ *  - #createObjectStore(db, osName): Creates the object store if it doesn't exist.
+ *  - #openDB(): Opens or creates the IndexedDB database.
+ *  - #getServerFile(uri): Downloads file blob and timestamp from server.
+ *  - #getServerFileTimeStamp(uri): Retrieves Last-Modified timestamp via HEAD request.
+ *  - #getServerFileSize(uri): Retrieves Content-Length via HEAD request.
+ *  - #putFile(file, uri): Stores file record in IndexedDB.
+ *  - #getFile(uri): Retrieves file record from IndexedDB.
+ *
+ * Public Methods:
+ *  - getURL(uri): Gets an object URL for cached blob or original URI.
+ *  - getTimeStamp(uri): Retrieves cached or server Last-Modified timestamp.
+ *  - getSize(uri): Gets cached or server file size in bytes.
+ *  - getBlob(uri): Retrieves file blob from cache or server.
+ *  - get(uri): Gets file from cache with automatic server sync and cache versioning.
+ *  - put(uri): Stores file from server in IndexedDB cache.
+ *
+ * Features:
+ *  - Automatic Cache Versioning: Compares server and cached timestamps to update cache.
+ *  - Fallback Support: Uses direct server access when IndexedDB is unavailable.
+ *  - Object URL Generation: Creates efficient object URLs for cached blobs.
+ *  - HEAD Request Optimization: Uses HEAD requests to check metadata without downloading full files.
+ *  - Promise-Based API: All operations return promises for async/await usage.
+ *
+ * Usage Example:
+ *  const storage = new FileStorage("MyFilesDB", "CachedFiles");
+ *  
+ *  // Get file blob with automatic caching
+ *  const file = await storage.get("https://example.com/model.glb");
+ *  
+ *  // Get object URL for cached file
+ *  const url = await storage.getURL("https://example.com/model.glb");
+ *  
+ *  // Check file timestamp
+ *  const timestamp = await storage.getTimeStamp("https://example.com/model.glb");
+ *  
+ *  // Get file size
+ *  const size = await storage.getSize("https://example.com/model.glb");
+ *  
+ *  // Manually cache a file
+ *  await storage.put("https://example.com/model.glb");
+ *
+ * Cache Behavior:
+ *  - First call: Downloads from server and caches in IndexedDB
+ *  - Subsequent calls: Returns cached version if timestamp matches
+ *  - Updated file: Detects timestamp change and re-downloads automatically
+ *  - No server access: Returns cached version if available
+ *  - IndexedDB unavailable: Falls back to direct server access
+ *
+ * Return Values:
+ *  - get(uri): Blob | undefined | false
+ *    - Blob: File successfully retrieved
+ *    - undefined: Download failed but no cached copy exists
+ *    - false: URI is falsy
+ *  
+ *  - getURL(uri): string | boolean
+ *    - string: Object URL or original URI
+ *    - false: File not available
+ *  
+ *  - getTimeStamp(uri): string | null
+ *    - string: ISO 8601 timestamp
+ *    - null: Timestamp unavailable
+ *  
+ *  - getSize(uri): number | null
+ *    - number: File size in bytes
+ *    - null: Size unavailable
+ *  
+ *  - put(uri): boolean
+ *    - true: Successfully cached
+ *    - false: Failed to cache
+ *
+ * Storage Limits:
+ *  - Chrome/Edge: ~50GB per origin
+ *  - Firefox: ~1GB per origin
+ *  - Safari: ~1GB per origin
+ *
+ * Notes:
+ *  - Requires CORS headers for cross-origin file access
+ *  - Uses XMLHttpRequest for file downloads and HEAD requests
+ *  - Supports both HTTPS and HTTP (HTTP not recommended for production)
+ *  - Object URLs should be revoked after use to free memory
+ *  - IndexedDB quota management should be implemented for long-term storage
+ *
+ * Error Handling:
+ *  - Network failures: Returns undefined (get) or false (other methods)
+ *  - IndexedDB errors: Falls back to server access or returns false
+ *  - CORS errors: Treated as download failures
+ *  - Invalid URIs: Returns false or undefined
+ *
+ * References:
+ *  - MDN IndexedDB API: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
+ *  - idb Library: https://github.com/jakearchibald/idb
+ *  - npm idb: https://www.npmjs.com/package/idb
+ */
 export class FileStorage {
     #supported = "indexedDB" in window && openDB; // true if IndexedDB is available in the browser and the idb helper is loaded
     #dbVersion = 1; // single DB version; cache is managed per-file
@@ -19,19 +126,22 @@ export class FileStorage {
 
     /**
      * Create the object store if it does not exist.
+     * @private
      * @param {IDBDatabase} db IndexedDB database instance
+     * @param {String} osName Object store name
      */
-    #createObjectStore = (db, osName) => {
+    #createObjectStore(db, osName) {
         if (!db.objectStoreNames.contains(osName)) {
             db.createObjectStore(osName);
         }
-    };
+    }
 
     /**
      * Open the IndexedDB database (creating it if needed) and ensure the object store for files exists.
+     * @private
      * @returns {Promise<IDBDatabase|null>} Resolves with the opened database or null if IndexedDB is not supported or opening fails.
      */
-    #openDB = async () => {
+    async #openDB() {
         if (!this.#supported) {
             return null;
         }
@@ -45,16 +155,17 @@ export class FileStorage {
         } catch (error) {
             return null;
         }
-    };
+    }
 
     /**
      * Download the file from the server (forced download).
+     * @private
      * @param {String} uri File URI
      * @returns {Promise<{blob: Blob, timeStamp: string}|undefined>} Resolves with:
      *   - { blob, timeStamp }: object with the downloaded Blob and the Last-Modified timestamp (ISO string) on success
      *   - undefined: if the download fails (non-200 status or network error)
      */
-    #getServerFile = async (uri) => {
+    async #getServerFile(uri) {
         let file = undefined;
         return new Promise((resolve) => {
             const xhr = new XMLHttpRequest();
@@ -75,16 +186,17 @@ export class FileStorage {
             };
             xhr.send();
         });
-    };
+    }
 
     /**
      * Get the Last-Modified timestamp of the file on the server without downloading its content.
+     * @private
      * @param {String} uri File URI
      * @returns {Promise<string|null>} Resolves with:
      *   - ISO 8601 string from the Last-Modified header if available
      *   - null if the header is not present or on error
      */
-    #getServerFileTimeStamp = async (uri) => {
+    async #getServerFileTimeStamp(uri) {
         let timeStamp = null;
         return new Promise((resolve) => {
             const xhr = new XMLHttpRequest();
@@ -103,16 +215,17 @@ export class FileStorage {
             };
             xhr.send();
         });
-    };
+    }
 
     /**
      * Get the size of the file on the server without downloading its content.
+     * @private
      * @param {String} uri File URI
      * @returns {Promise<number>} Promise that resolves with:
      *   - number: Content-Length in bytes when the HEAD request succeeds and the header is present
      *   - 0: when the header is missing or the request fails
      */
-    #getServerFileSize = async (uri) => {
+    async #getServerFileSize(uri) {
         let size = 0;
         return new Promise((resolve) => {
             const xhr = new XMLHttpRequest();
@@ -131,10 +244,11 @@ export class FileStorage {
             };
             xhr.send();
         });
-    };
+    }
 
     /**
      * Stores a file record in IndexedDB under the provided key (uri).
+     * @private
      * @param {Object|Blob} file The value to store (for example an object {blob, timeStamp} or a Blob).
      * @param {String} uri Key to use for storage (the original URI).
      * @returns {Promise<any|undefined>} Resolves with the value returned by the underlying idb store.put (usually the record key — string or number)
@@ -142,7 +256,7 @@ export class FileStorage {
      *   - resolves to undefined if the database could not be opened
      *   - rejects if the underlying put operation throws
      */
-    #putFile = async (file, uri) => {
+    async #putFile(file, uri) {
         if (this.#db === undefined) {
             this.#db = await this.#openDB();
         }
@@ -152,17 +266,18 @@ export class FileStorage {
         const transation = this.#db.transaction(this.osName, "readwrite");
         const store = transation.objectStore(this.osName);
         return store.put(file, uri);
-    };
+    }
 
     /**
      * Retrieve a file record from IndexedDB.
+     * @private
      * @param {String} uri File URI
      * @returns {Promise<{blob: Blob, timeStamp: string}|undefined|false>} Resolves with:
      *   - {blob, timeStamp}: object with the Blob and ISO timestamp if the entry exists in IndexedDB
      *   - undefined: if there is no stored entry for that URI
      *   - false: if the database could not be opened (IndexedDB unsupported or open failure)
      */
-    #getFile = async (uri) => {
+    async #getFile(uri) {
         if (this.#db === undefined) {
             this.#db = await this.#openDB();
         }
@@ -172,75 +287,86 @@ export class FileStorage {
         const transation = this.#db.transaction(this.osName, "readonly");
         const store = transation.objectStore(this.osName);
         return store.get(uri);
-    };
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
 
     /**
      * Get a URL to the file: either an object URL for the cached Blob, or the original URI if the server copy is available and IndexedDB isn't supported.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<string|boolean>} Resolves with:
      *   - object URL string for the cached Blob
      *   - original URI string if IndexedDB unsupported but server file exists
      *   - false if the file is not available on the server
      */
-    getURL = async (uri) => {
+    async getURL(uri) {
         if (!this.#supported) {
             return (await this.#getServerFileTimeStamp(uri)) ? uri : false;
         }
         const storedFile = await this.get(uri);
         return storedFile ? URL.createObjectURL(storedFile.blob) : (await this.#getServerFileTimeStamp(uri)) ? uri : false;
-    };
+    }
 
     /**
      * Get the cached or server Last-Modified timestamp for a file.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<string|null>} Resolves with:
      *   - ISO 8601 string: Last-Modified timestamp from the cached record (when using IndexedDB) or from the server HEAD response
      *   - null: when no timestamp is available or on error
      */
-    getTimeStamp = async (uri) => {
+    async getTimeStamp(uri) {
         if (!this.#supported) {
             const serverFileTimeStamp = await this.#getServerFileTimeStamp(uri);
             return serverFileTimeStamp ? serverFileTimeStamp : null;
         }
         const storedFile = await this.get(uri);
         return storedFile ? storedFile.timeStamp : null;
-    };
+    }
 
     /**
      * Get the cached or server size of a file in bytes.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<number|null>} Resolves with:
      *   - number: size in bytes when available (from cache or server)
      *   - null: when size is not available or on error
      */
-    getSize = async (uri) => {
+    async getSize(uri) {
         if (!this.#supported) {
             const serverFileSize = await this.#getServerFileSize(uri);
             return serverFileSize ? serverFileSize : null;
         }
         const storedFile = await this.get(uri);
         return storedFile ? storedFile.blob.size : null;
-    };
+    }
 
     /**
      * Retrieve the Blob for a file from cache or server.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<Blob|false>} Resolves with:
      *   - Blob: the file blob when available (from cache or server)
      *   - false: when the file cannot be retrieved
      */
-    getBlob = async (uri) => {
+    async getBlob(uri) {
         if (!this.#supported) {
             const serverFile = await this.#getServerFile(uri);
             return serverFile ? serverFile.blob : false;
         }
         const storedFile = await this.get(uri);
         return storedFile ? storedFile.blob : false;
-    };
+    }
 
     /**
      * Get the file Blob from IndexedDB if stored; otherwise download and store it, then return the Blob.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<Blob|undefined|false>} Resolves with:
      *   - Blob of the stored file
      *   - undefined if the download fails
@@ -250,7 +376,7 @@ export class FileStorage {
      * the file is re-downloaded from the server and stored again in IndexedDB.
      * If the server file is not available at that time to check its age but is stored, the stored file is returned.
      */
-    get = async (uri) => {
+    async get(uri) {
         if (!uri) {
             return false;
         }
@@ -269,20 +395,21 @@ export class FileStorage {
             }
         }
         return storedFile;
-    };
+    }
 
     /**
      * Store the file in IndexedDB.
-     * @param {String} uri File URI
+     * @public
+     * @param {String} uri - File URI
      * @returns {Promise<boolean>} Resolves with:
      *   - true if the file was stored successfully
      *   - false if IndexedDB is not supported or storing failed
      */
-    put = async (uri) => {
+    async put(uri) {
         if (!this.#supported) {
             return false;
         }
         const fileToStore = await this.#getServerFile(uri);
         return fileToStore ? !!(await this.#putFile(fileToStore, uri)) : false;
-    };
+    }
 }