@hkdigital/lib-sveltekit 0.1.22 → 0.1.23

package/dist/classes/svelte/image/ImageScene.svelte.d.ts

@@ -1,50 +1,78 @@
+/**
+ * @typedef {object} SourceConfig
+ * // property ...
+ */
+/**
+ * @typedef {object} ImageSource
+ * @property {string} label
+ * @property {ImageLoader} imageLoader
+ * @property {ImageMeta} [imageMeta]
+ */
 export default class ImageScene {
+    state: string;
+    loaded: boolean;
+    destroy(): void;
     /**
-     * Define an image to be managed by this scene
+     * Add image source
+     * - Uses an ImageLoader instance to load image data from network
      *
-     * @param {object} params
-     * @param {string} params.label - Unique identifier for the image
-     * @param {ImageMeta|ImageMeta[]} params.imageMeta - Image metadata (single or variants)
+     * @param {object} _
+     * @param {string} _.label
+     * @param {ImageMeta|ImageMeta[]} _.imageMeta
      */
     defineImage({ label, imageMeta }: {
         label: string;
         imageMeta: ImageMeta | ImageMeta[];
     }): void;
     /**
-     * Start loading all defined images
+     * Start loading all image sources
      */
     load(): void;
     /**
-     * Unload all images and free resources
+     * Get image scene loading progress
      */
-    unload(): void;
+    get progress(): {
+        totalBytesLoaded: number;
+        totalSize: number;
+        sourcesLoaded: number;
+        numberOfSources: number;
+    };
     /**
-     * Get the image loader for a specific label
+     * Get an image loader
      *
-     * @param {string} label - Image identifier
-     * @returns {ImageLoader|null} The image loader or null if not found
-     */
-    getImageLoader(label: string): ImageLoader | null;
-    /**
-     * Check if the scene is currently loading
+     * @param {string} label
+     *
+     * @returns {ImageLoader}
      */
-    get loading(): boolean;
+    getImageLoader(label: string): ImageLoader;
     /**
-     * Check if all images in the scene are loaded
+     * Get object URL that can be used as src parameter of an HTML image
+     *
+     * @param {string} label
+     *
+     * @returns {ImageMeta}
      */
-    get loaded(): boolean;
+    getImageMeta(label: string): ImageMeta;
     /**
-     * Get the current loading progress
+     * Get object URL that can be used as src parameter of an HTML image
+     *
+     * @param {string} label
+     *
+     * @note the objectURL should be revoked when no longer used
+     *
+     * @returns {string}
      */
-    get progress(): {
-        bytesLoaded: number;
-        size: number;
-        loaded: boolean;
-    };
+    getObjectURL(label: string): string;
     #private;
 }
+export type ImageMeta = import("./typedef.js").ImageMeta;
 /**
- * A simple class to preload and manage images for a scene
+ * // property ...
  */
-export type ImageMeta = import("../../../config/typedef.js").ImageMeta;
-import { ImageLoader } from './index.js';
+export type SourceConfig = object;
+export type ImageSource = {
+    label: string;
+    imageLoader: ImageLoader;
+    imageMeta?: ImageMeta;
+};
+import ImageLoader from './ImageLoader.svelte.js';

package/dist/classes/svelte/image/ImageScene.svelte.js

@@ -1,120 +1,253 @@
+/** @typedef {import('./typedef.js').ImageMeta} ImageMeta */
+
+import * as expect from '../../../util/expect/index.js';
+
+import {
+  LoadingStateMachine,
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_UNLOADING,
+  STATE_LOADED,
+  STATE_CANCELLED,
+  STATE_ERROR,
+  LOAD,
+  // CANCEL,
+  ERROR,
+  LOADED,
+  UNLOAD,
+  INITIAL
+} from '../loading-state-machine/index.js';
+
+import ImageLoader from './ImageLoader.svelte.js';
+
+/**
+ * @typedef {object} SourceConfig
+ * // property ...
+ */
+
 /**
- * A simple class to preload and manage images for a scene
- *
- * @typedef {import('../../../config/typedef.js').ImageMeta} ImageMeta
+ * @typedef {object} ImageSource
+ * @property {string} label
+ * @property {ImageLoader} imageLoader
+ * @property {ImageMeta} [imageMeta]
  */
-import { ImageLoader } from './index.js';
 
 export default class ImageScene {
-  /** @type {Map<string, ImageLoader>} */
-  #loaders = $state.raw(new Map());
+  #state = new LoadingStateMachine();
 
-  /** @type {boolean} */
-  #loading = $state(false);
+  // @note this exported state is set by $effect's
+  state = $state(STATE_INITIAL);
 
-  /** @type {boolean} */
-  #loaded = $state(false);
+  // @note this exported state is set by $effect's
+  loaded = $derived.by(() => {
+    return this.state === STATE_LOADED;
+  });
 
-  /** @type {{ bytesLoaded: number, size: number, loaded: boolean }} */
-  #progress = $state({ bytesLoaded: 0, size: 0, loaded: false });
+  /** @type {ImageSource[]} */
+  #imageSources = $state([]);
 
-  /**
-   * Define an image to be managed by this scene
-   *
-   * @param {object} params
-   * @param {string} params.label - Unique identifier for the image
-   * @param {ImageMeta|ImageMeta[]} params.imageMeta - Image metadata (single or variants)
-   */
-  defineImage({ label, imageMeta }) {
-    // Create loader for this image
-    const loader = new ImageLoader({ imageMeta });
-    this.#loaders.set(label, loader);
-  }
+  #progress = $derived.by(() => {
+    // console.log('update progress');
 
-  /**
-   * Start loading all defined images
-   */
-  load() {
-    if (this.#loading || this.#loaded) return;
+    let totalSize = 0;
+    let totalBytesLoaded = 0;
+    let sourcesLoaded = 0;
 
-    this.#loading = true;
+    const sources = this.#imageSources;
+    const numberOfSources = sources.length;
 
-    // Start loading all images
-    for (const loader of this.#loaders.values()) {
-      loader.load();
-    }
+    for (let j = 0; j < numberOfSources; j++) {
+      const source = sources[j];
+      const { imageLoader } = source;
 
-    // Track overall loading progress
-    $effect(() => {
-      if (this.#loaders.size === 0) return;
+      const { bytesLoaded, size, loaded } = imageLoader.progress;
 
-      let totalBytesLoaded = 0;
-      let totalSize = 0;
-      let allLoaded = true;
+      totalSize += size;
+      totalBytesLoaded += bytesLoaded;
 
-      for (const loader of this.#loaders.values()) {
-        const progress = loader.progress;
+      if (loaded) {
+        sourcesLoaded++;
+      }
+    } // end for
 
-        totalBytesLoaded += progress.bytesLoaded;
-        totalSize += progress.size || 0;
+    return {
+      totalBytesLoaded,
+      totalSize,
+      sourcesLoaded,
+      numberOfSources
+    };
+  });
 
-        if (!progress.loaded) {
-          allLoaded = false;
-        }
-      }
+  /**
+   * Construct ImageScene
+   */
+  constructor() {
+    const state = this.#state;
+
+    $effect(() => {
+      if (state.current === STATE_LOADING) {
+        // console.log(
+        //   'progress',
+        //   JSON.stringify($state.snapshot(this.#progress))
+        // );
 
-      this.#progress = {
-        bytesLoaded: totalBytesLoaded,
-        size: totalSize,
-        loaded: allLoaded
-      };
+        const { sourcesLoaded, numberOfSources } = this.#progress;
 
-      if (allLoaded && this.#loading) {
-        this.#loaded = true;
+        if (sourcesLoaded === numberOfSources) {
+          // console.log(`All [${numberOfSources}] sources loaded`);
+          this.#state.send(LOADED);
+        }
       }
     });
+
+    $effect(() => {
+      switch (state.current) {
+        case STATE_LOADING:
+          {
+            // console.log('ImageScene:loading');
+            this.#startLoading();
+          }
+          break;
+
+        case STATE_UNLOADING:
+          {
+            // console.log('ImageScene:unloading');
+            // this.#startUnLoading();
+          }
+          break;
+
+        case STATE_LOADED:
+          {
+            // console.log('ImageScene:loaded');
+            // TODO
+            // this.#abortLoading = null;
+          }
+          break;
+
+        case STATE_CANCELLED:
+          {
+            // console.log('ImageScene:cancelled');
+            // TODO
+          }
+          break;
+
+        case STATE_ERROR:
+          {
+            console.log('ImageScene:error', state.error);
+          }
+          break;
+      } // end switch
+
+      this.state = state.current;
+    });
+  }
+
+  destroy() {
+    // TODO: disconnect all image sources?
+    // TODO: Unload ImageLoaders?
+  }
+
+  /**
+   * Add image source
+   * - Uses an ImageLoader instance to load image data from network
+   *
+   * @param {object} _
+   * @param {string} _.label
+   * @param {ImageMeta|ImageMeta[]} _.imageMeta
+   */
+  defineImage({ label, imageMeta }) {
+    expect.notEmptyString(label);
+
+    // expect.notEmptyString(url);
+
+    const imageLoader = new ImageLoader({ imageMeta });
+
+    this.#imageSources.push({ label, imageLoader, imageMeta });
   }
 
   /**
-   * Unload all images and free resources
+   * Start loading all image sources
    */
-  unload() {
-    for (const loader of this.#loaders.values()) {
-      loader.unload();
+  load() {
+    this.#state.send(LOAD);
+
+    // FIXME: in unit test when moved to startloading it hangs!
+
+    for (const { imageLoader } of this.#imageSources) {
+      imageLoader.load();
     }
+  }
 
-    this.#loading = false;
-    this.#loaded = false;
+  async #startLoading() {
+    // console.log('#startLoading');
+    // FIXME: in unit test when moved to startloading it hangs!
+    // for (const { audioLoader } of this.#memorySources) {
+    //   audioLoader.load();
+    // }
   }
 
   /**
-   * Get the image loader for a specific label
+   * Get Image source
    *
-   * @param {string} label - Image identifier
-   * @returns {ImageLoader|null} The image loader or null if not found
+   * @param {string} label
+   *
+   * @returns {ImageSource}
    */
-  getImageLoader(label) {
-    return this.#loaders.get(label) || null;
+  #getImageSource(label) {
+    for (const source of this.#imageSources) {
+      if (label === source.label) {
+        return source;
+      }
+    }
+
+    throw new Error(`Source [${label}] has not been defined`);
+  }
+
+  /**
+   * Get image scene loading progress
+   */
+  get progress() {
+    return this.#progress;
   }
 
   /**
-   * Check if the scene is currently loading
+   * Get an image loader
+   *
+   * @param {string} label
+   *
+   * @returns {ImageLoader}
    */
-  get loading() {
-    return this.#loading;
+  getImageLoader(label) {
+    const source = this.#getImageSource(label);
+
+    return source.imageLoader;
   }
 
   /**
-   * Check if all images in the scene are loaded
+   * Get object URL that can be used as src parameter of an HTML image
+   *
+   * @param {string} label
+   *
+   * @returns {ImageMeta}
    */
-  get loaded() {
-    return this.#loaded;
+  getImageMeta(label) {
+    const source = this.#getImageSource(label);
+
+    return source.imageMeta;
   }
 
   /**
-   * Get the current loading progress
+   * Get object URL that can be used as src parameter of an HTML image
+   *
+   * @param {string} label
+   *
+   * @note the objectURL should be revoked when no longer used
+   *
+   * @returns {string}
    */
-  get progress() {
-    return this.#progress;
+  getObjectURL(label) {
+    const source = this.#getImageSource(label);
+
+    return source.imageLoader.getObjectURL();
   }
 }

package/dist/classes/svelte/image/ImageVariantsLoader.svelte.d.ts

@@ -1,5 +1,8 @@
 export default class ImageVariantsLoader {
-    constructor(imagesMeta: any, { devicePixelRatio }?: {
+    /**
+     * @param {ImageMeta[]} imagesMeta
+     */
+    constructor(imagesMeta: ImageMeta[], { devicePixelRatio }?: {
         devicePixelRatio?: number;
     });
     /**
@@ -25,11 +28,7 @@ export default class ImageVariantsLoader {
      * @returns {string|null}
      */
     getObjectURL(): string | null;
-    get progress(): {
-        bytesLoaded: any;
-        size: any;
-        loaded: boolean;
-    };
+    get progress(): import("../network-loader/typedef.js").LoadingProgress;
     /**
      * Get optimal image variant
      *

package/dist/classes/svelte/image/ImageVariantsLoader.svelte.js

@@ -1,7 +1,11 @@
 /** @typedef {import('./typedef.js').ImageMeta} ImageMeta */
 
+// import * as expect from '../../../util/expect/index.js';
+
 import { calculateEffectiveWidth } from '../../../util/image/index.js';
+
 import { untrack } from 'svelte';
+
 import ImageLoader from './ImageLoader.svelte.js';
 
 export default class ImageVariantsLoader {
@@ -17,32 +21,22 @@ export default class ImageVariantsLoader {
   /** @type {ImageLoader|null} */
   #imageLoader = $state(null);
 
-  /** @type {boolean} */
-  #isObjectUrlCreated = $state(false);
-
-  /** @type {boolean} */
-  #variantLoaded = $state(false);
+  #progress = $derived.by(() => {
+    if (this.#imageLoader) {
+      return this.#imageLoader.progress;
+    } else {
+      return { bytesLoaded: 0, size: 0, loaded: false };
+    }
+  });
 
-  /** @type {Object} */
-  #baseProgress = $state({ bytesLoaded: 0, size: 0, loaded: false });
+  #loaded = $derived.by(() => this.#progress?.loaded || false);
 
+  /**
+   * @param {ImageMeta[]} imagesMeta
+   */
   constructor(imagesMeta, { devicePixelRatio = 1 } = {}) {
     this.#devicePixelRatio = devicePixelRatio ?? 1;
     this.#imagesMeta = [...imagesMeta].sort((a, b) => a.width - b.width);
-
-    // Track the imageLoader's progress
-    $effect(() => {
-      if (this.#imageLoader) {
-        // Store the base progress from the loader
-        this.#baseProgress = this.#imageLoader.progress;
-
-        // When the base image is loaded, we can say variant is loaded
-        // if an object URL has been created
-        if (this.#baseProgress.loaded && this.#isObjectUrlCreated) {
-          this.#variantLoaded = true;
-        }
-      }
-    });
   }
 
   /**
@@ -73,11 +67,7 @@ export default class ImageVariantsLoader {
     ) {
       this.#imageVariant = newVariant;
 
-      // Reset our loaded flags when changing variants
-      this.#isObjectUrlCreated = false;
-      this.#variantLoaded = false;
-
-      // Clean up and create a new loader
+      // Create and start loader here directly when variant changes
       if (this.#imageLoader?.initial) {
         this.#imageLoader.unload();
       }
@@ -91,7 +81,7 @@ export default class ImageVariantsLoader {
   }
 
   get loaded() {
-    return this.#variantLoaded;
+    return this.#loaded;
   }
 
   get variant() {
@@ -106,38 +96,31 @@ export default class ImageVariantsLoader {
    * @returns {string|null}
    */
   getObjectURL() {
-    if (!this.#imageLoader) {
-      return null;
-    }
-
-    const blob = this.#imageLoader.getBlob();
-
-    if (!blob) {
-      return null;
-    }
-
-    // Get the URL
-    const url = URL.createObjectURL(blob);
-
-    // Mark that we've successfully created an object URL
-    this.#isObjectUrlCreated = true;
-
-    // If the underlying loader is also loaded, we can consider
-    // the whole variant loaded
-    if (this.#baseProgress.loaded) {
-      this.#variantLoaded = true;
-    }
+    // Example usage:
+    //
+    // $effect(() => {
+    //   if (variantsLoader.loaded) {
+    //     // @ts-ignore
+    //     imageUrl = variantsLoader.getObjectURL();
+    //   }
+
+    //   return () => {
+    //     if (imageUrl) {
+    //       URL.revokeObjectURL(imageUrl);
+    //       imageUrl = null;
+    //     }
+    //   };
+    // });
+
+    const blob = this.#imageLoader?.getBlob();
+
+    const url = blob ? URL.createObjectURL(blob) : null;
 
     return url;
   }
 
   get progress() {
-    // Only return loaded:true in the progress when we're fully loaded
-    return {
-      bytesLoaded: this.#baseProgress.bytesLoaded,
-      size: this.#baseProgress.size,
-      loaded: this.#variantLoaded
-    };
+    return this.#progress;
   }
 
   /**
@@ -158,6 +141,7 @@ export default class ImageVariantsLoader {
     const imagesMeta = this.#imagesMeta;
 
     // Find the smallest image that's larger than our required width
+
     const optimal = imagesMeta.find(
       (current) => current.width >= requiredWidth
     );
@@ -165,4 +149,4 @@ export default class ImageVariantsLoader {
     // Fall back to the largest image if nothing is big enough
     return optimal || imagesMeta[imagesMeta.length - 1];
   }
-}
+} // end class

package/dist/components/area/HkArea.svelte.d.ts

@@ -1,18 +1,4 @@
 export default HkArea;
-type HkArea = {
-    $on?(type: string, callback: (e: any) => void): () => void;
-    $set?(props: Partial<{
-        base?: string;
-        bg?: string;
-        padding?: string;
-        margin?: string;
-        classes?: string;
-        style?: string;
-        children: Snippet<[]>;
-    } & {
-        [attr: string]: any;
-    }>): void;
-};
 declare const HkArea: import("svelte").Component<{
     base?: string;
     bg?: string;

package/dist/components/area/HkGridArea.svelte.d.ts

@@ -1,26 +1,4 @@
 export default HkGridArea;
-type HkGridArea = {
-    $on?(type: string, callback: (e: any) => void): () => void;
-    $set?(props: Partial<{
-        base?: string;
-        bg?: string;
-        padding?: string;
-        margin?: string;
-        classes?: string;
-        style?: string;
-        boxBase?: string;
-        boxBg?: string;
-        boxPadding?: string;
-        boxMargin?: string;
-        boxClasses?: string;
-        boxAttrs?: {
-            [attr: string]: any;
-        };
-        children: Snippet<[]>;
-    } & {
-        [attr: string]: any;
-    }>): void;
-};
 declare const HkGridArea: import("svelte").Component<{
     base?: string;
     bg?: string;

package/dist/components/buttons/button/Button.svelte.d.ts

@@ -1,25 +1,4 @@
 export default Button;
-type Button = {
-    $on?(type: string, callback: (e: any) => void): () => void;
-    $set?(props: Partial<{
-        [key: string]: any;
-        base?: string;
-        bg?: string;
-        classes?: string;
-        type?: string;
-        role?: "custom" | "primary" | "secondary" | "tertiary";
-        size?: "sm" | "md" | "lg";
-        variant?: string;
-        active?: boolean;
-        selected?: boolean;
-        loading?: boolean;
-        error?: boolean;
-        disabled?: boolean;
-        snippetLoading?: Snippet<[]>;
-        snippetError?: Snippet<[]>;
-        children: Snippet<[]>;
-    }>): void;
-};
 declare const Button: import("svelte").Component<{
     [key: string]: any;
     base?: string;