@preference-sl/pref-viewer 2.11.0-beta.1 → 2.11.0-beta.11

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

@@ -21,12 +21,17 @@ import PanzoomController from "./panzoom-controller.js";
  *  - async load(svgConfig) : Promise<boolean> — accept SVG input/config and prepare for render
  *  - show(), hide() — toggle visibility and event subscriptions
  *  - zoomIn(), zoomOut(), zoomCenter(), zoomExtentsAll() — pan/zoom controls
+ * 
+ * * Public Properties:
+ *  - isInitialized: Indicates whether the component has completed initialization.
+ *  - isLoaded: Indicates whether the SVG content is loaded and ready.
+ *  - isVisible: Indicates whether the component is currently visible.
  *
  * Events
- *  - "prefviewer2d-loading": emitted before loading starts
- *  - "prefviewer2d-loaded": emitted after content and Panzoom are ready
- *  - "prefviewer2d-error": emitted on validation/fetch errors (detail.error: Error)
- *  - "prefviewer2d-zoomchanged": emitted when pan/zoom state changes (detail: { moved, scaled, maximized, minimized })
+ *  - "drawing-loading": emitted before loading starts
+ *  - "drawing-loaded": emitted after content and Panzoom are ready
+ *  - "drawing-error": emitted on validation/fetch errors (detail.error: Error)
+ *  - "drawing-zoom-changed": emitted when pan/zoom state changes (detail: { moved, scaled, maximized, minimized })
  *
  * Implementation notes
  *  - Keeps internal state in private fields (#svg, #panzoom, #panzoomOptions, ...).
@@ -80,10 +85,10 @@ export class PrefViewer2D extends HTMLElement {
     }
 
     /**
-     * Handle attribute changes.
-     * @param {string} name - Attribute name.
-     * @param {string|null} _old - Previous attribute value (unused).
-     * @param {string|null} value -New attribute value.
+     * Handles changes to observed attributes and updates the component state accordingly.
+     * @param {string} name - The name of the changed attribute.
+     * @param {string|null} _old - The previous value of the attribute.
+     * @param {string|null} value - The new value of the attribute.
      * @returns {void}
      * @description
      * - "svg": triggers load of new SVG content.
@@ -119,6 +124,11 @@ export class PrefViewer2D extends HTMLElement {
         this.#loadSVG();
     }
 
+    /**
+     * Called when the element is removed from the DOM.
+     * Disables the PanzoomController to clean up event listeners and resources.
+     * @returns {void}
+     */
     disconnectedCallback() {
         if (this.#panzoomController) {
             this.#panzoomController.disable();
@@ -134,7 +144,8 @@ export class PrefViewer2D extends HTMLElement {
         this.#wrapper = document.createElement("div");
         this.append(this.#wrapper);
         const style = document.createElement("style");
-        style.textContent = `pref-viewer-2d[visible="true"] { display: block; } pref-viewer-2d[visible="false"] { display: none; } 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: 10px; }`;
+        const cssUrl = new URL("./css/pref-viewer-2d.css", import.meta.url);
+        style.textContent = `@import "${cssUrl}";`;
         this.append(style);
     }
 
@@ -203,20 +214,21 @@ export class PrefViewer2D extends HTMLElement {
     }
 
     /**
-     * Handle invalid or unsupported SVG input. Emits a custom error event.
+     * Handles invalid or unsupported SVG input by emitting a custom error event.
      * @private
-     * @returns {void}
+     * @returns {object} Detail object with an Error describing the SVG input issue.
      */
     #onError() {
         const error = "PrefViewer2D: Error in SVG provided for loading. Ensure the SVG is a URL to an SVG file, a string containing a SVG, or a string containing a base64-encoded SVG.";
-        this.dispatchEvent(
-            new CustomEvent("prefviewer2d-error", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-                detail: { error: new Error(error) },
-            })
-        );
+        const detail = { error: new Error(error) };
+        const customEventOptions = {
+            bubbles: true, // indicates whether the event bubbles up through the DOM tree or not
+            cancelable: true, // indicates whether the event can be canceled, and therefore prevented as if the event never happened
+            composed: false, // indicates whether or not the event will propagate across the shadow DOM boundary into the standard DOM
+            detail: detail,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-error", customEventOptions));
+        return detail;
     }
 
     /**
@@ -225,13 +237,12 @@ export class PrefViewer2D extends HTMLElement {
      * @returns {void}
      */
     #onLoaded() {
-        this.dispatchEvent(
-            new CustomEvent("prefviewer2d-loaded", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            })
-        );
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-loaded", customEventOptions));
 
         this.removeAttribute("loading");
         this.setAttribute("loaded", "");
@@ -246,13 +257,12 @@ export class PrefViewer2D extends HTMLElement {
      * @returns {void}
      */
     #onLoading() {
-        this.dispatchEvent(
-            new CustomEvent("prefviewer2d-loading", {
-                bubbles: true,
-                cancelable: false,
-                composed: true,
-            })
-        );
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+        };
+        this.dispatchEvent(new CustomEvent("drawing-loading", customEventOptions));
 
         this.removeAttribute("loaded");
         this.setAttribute("loading", "");
@@ -274,10 +284,20 @@ export class PrefViewer2D extends HTMLElement {
      * the UI with the enabled/disabled status of the zoomIn, zoomOut, center, and zoomExtentsAll buttons.
      */
     #onPanzoomChanged(state) {
-        this.dispatchEvent(
-            new CustomEvent("prefviewer2d-zoomchanged", {
-                bubbles: true,
-                cancelable: false,
+        const customEventOptions = {
+            bubbles: true,
+            cancelable: true,
+            composed: false,
+            detail: state,
+        };
+        customEventOptions.detail.desde2d = "true";
+        this.dispatchEvent(new CustomEvent("drawing-zoom-changed", customEventOptions));
+    }
+
+    /**
+     * Subscribe DOM events required by Panzoom and keyboard interactions.
+     * @private
+     * @returns {void}
                 composed: true,
                 detail: state,
             })
@@ -325,17 +345,17 @@ export class PrefViewer2D extends HTMLElement {
      * @param {object} svgConfig - SVG configuration. An object with a `storage` property describing the source:
      *      { storage: { url: "<url>" } }
      *      or { storage: { db: "<db>", table: "<table>", id: "<id>" } }
-     * @returns {Promise<boolean|void>}
-     * - Resolves to false when the input is invalid or the SVG could not be retrieved/decoded, or when there is no update required (cached copy unchanged).
-     * - Resolves to true when the SVG was accepted and the component has started rendering.
+     * @returns {Promise<{success: boolean, error: Error|null}>}
+     * - Resolves to { success: false, error: <Error> } when the input is invalid or the SVG could not be retrieved/decoded, or when there is no update required (cached copy unchanged).
+     * - Resolves to { success: true, error: null } when the SVG was accepted and the component has started rendering.
      */
     async load(svgConfig) {
         if (!svgConfig || !(await this.#svgResolver.getSVG(svgConfig))) {
-            this.#onError();
-            return false;
+            const errorDetail = this.#onError();
+            return { success: false, ...errorDetail };
         }
-        this.#isInitialized && this.#loadSVG();
-        return true;
+        const success = this.#isInitialized && this.#loadSVG();
+        return { success: success, error: null };
     }
 
     /**
@@ -417,7 +437,7 @@ export class PrefViewer2D extends HTMLElement {
      * @public
      * @returns {boolean} True if the component is initialized; otherwise, false.
      */
-    get initialized() {
+    get isInitialized() {
         return this.#isInitialized;
     }
 
@@ -426,7 +446,7 @@ export class PrefViewer2D extends HTMLElement {
      * @public
      * @returns {boolean} True if the SVG is loaded; otherwise, false.
      */
-    get loaded() {
+    get isLoaded() {
         return this.#isLoaded;
     }
 
@@ -435,7 +455,7 @@ export class PrefViewer2D extends HTMLElement {
      * @public
      * @returns {boolean} True if the component is visible; otherwise, false.
      */
-    get visible() {
+    get isVisible() {
         return this.#isVisible;
     }
 }