@hkdigital/lib-core 0.4.26 → 0.4.28

package/dist/network/loaders/base/SceneBase.svelte.js

@@ -0,0 +1,283 @@
+import { LoadingStateMachine } from '../../../state/machines.js';
+
+import {
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_LOADED,
+  STATE_ABORTING,
+  STATE_ABORTED,
+  STATE_ERROR,
+  LOAD,
+  LOADED,
+  ABORT,
+  ABORTED
+} from '../../../state/machines.js';
+
+import { waitForState } from '../../../util/svelte.js';
+
+/**
+ * Base class for scene loaders that manage collections of media sources
+ */
+export default class SceneBase {
+  #state = new LoadingStateMachine();
+
+  // @note this exported state is set by onenter
+  state = $state(STATE_INITIAL);
+
+  loaded = $derived.by(() => {
+    return this.state === STATE_LOADED;
+  });
+
+  #progress = $derived.by(() => {
+    let totalSize = 0;
+    let totalBytesLoaded = 0;
+    let sourcesLoaded = 0;
+
+    const sources = this.sources;
+    const numberOfSources = sources.length;
+
+    for (let j = 0; j < numberOfSources; j++) {
+      const source = sources[j];
+      const loader = this.getLoaderFromSource(source);
+
+      const { bytesLoaded, size, loaded } = loader.progress;
+
+      totalSize += size;
+      totalBytesLoaded += bytesLoaded;
+
+      if (loaded) {
+        sourcesLoaded++;
+      }
+    }
+
+    return {
+      totalBytesLoaded,
+      totalSize,
+      sourcesLoaded,
+      numberOfSources
+    };
+  });
+
+  #abortProgress = $derived.by(() => {
+    let sourcesAborted = 0;
+    const sources = this.sources;
+    const numberOfSources = sources.length;
+
+    for (let j = 0; j < numberOfSources; j++) {
+      const source = sources[j];
+      const loader = this.getLoaderFromSource(source);
+      const loaderState = loader.state;
+
+      if (loaderState === STATE_ABORTED || loaderState === STATE_ERROR) {
+        sourcesAborted++;
+      }
+    }
+
+    return {
+      sourcesAborted,
+      numberOfSources
+    };
+  });
+
+  /**
+   * Construct SceneBase
+   */
+  constructor() {
+    const state = this.#state;
+
+    $effect(() => {
+      if (state.current === STATE_LOADING) {
+        const { sourcesLoaded, numberOfSources } = this.#progress;
+
+        if (sourcesLoaded === numberOfSources) {
+          this.#state.send(LOADED);
+        }
+      }
+    });
+
+    $effect(() => {
+      if (state.current === STATE_ABORTING) {
+        const { sourcesAborted, numberOfSources } = this.#abortProgress;
+
+        if (sourcesAborted === numberOfSources) {
+          this.#state.send(ABORTED);
+        }
+      }
+    });
+
+    state.onenter = (currentState) => {
+      if (currentState === STATE_LOADING) {
+        this.#startLoading();
+      } else if (currentState === STATE_ABORTING) {
+        this.#startAbort();
+      }
+
+      this.state = currentState;
+    };
+  }
+
+  /* ==== Abstract methods - must be implemented by subclasses */
+
+  /**
+   * Get the array of sources managed by this scene
+   *
+   * @returns {Array} Array of source objects
+   */
+  get sources() {
+    throw new Error('Subclass must implement sources getter');
+  }
+
+  /**
+   * Extract the loader from a source object
+   *
+   * @param {*} source
+   *
+   * @returns {*} Loader object with progress and state properties
+   */
+  // eslint-disable-next-line no-unused-vars
+  getLoaderFromSource(source) {
+    throw new Error('Subclass must implement getLoaderFromSource method');
+  }
+
+  /* ==== Common loader interface */
+
+  /**
+   * Get scene loading progress
+   */
+  get progress() {
+    return this.#progress;
+  }
+
+  /**
+   * Get scene abort progress
+   */
+  get abortProgress() {
+    return this.#abortProgress;
+  }
+
+  /**
+   * Start loading all sources
+   */
+  load() {
+    this.#state.send(LOAD);
+  }
+
+  /**
+   * Abort loading all sources
+   */
+  abort() {
+    this.#state.send(ABORT);
+  }
+
+  /**
+   * Preload all sources with progress tracking and abort capability
+   * - Starts loading and waits for completion
+   * - Supports timeout and progress callbacks
+   * - Returns object with promise and abort function
+   *
+   * @param {object} [options]
+   * @param {number} [options.timeoutMs=10000] - Timeout in milliseconds
+   * @param {Function} [options.onProgress] - Progress callback function
+   *
+   * @returns {object} Object with promise and abort function
+   * @returns {Promise<SceneBase>} returns.promise - Promise that resolves when loaded
+   * @returns {Function} returns.abort - Function to abort preloading
+   */
+  preload({ timeoutMs = 10000, onProgress } = {}) {
+    let timeoutId = null;
+    let progressIntervalId = null;
+    let isAborted = false;
+
+    const abort = () => {
+      if (isAborted) return;
+      isAborted = true;
+
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+
+      if (progressIntervalId) {
+        clearInterval(progressIntervalId);
+        progressIntervalId = null;
+      }
+
+      this.abort();
+    };
+
+    const promise = new Promise((resolve, reject) => {
+      // Set up progress tracking with polling
+      if (onProgress) {
+        progressIntervalId = setInterval(() => {
+          if (!isAborted) {
+            onProgress(this.progress);
+          }
+        }, 50); // Poll every 50ms
+      }
+
+      // Set up timeout
+      if (timeoutMs > 0) {
+        timeoutId = setTimeout(() => {
+          abort();
+          reject(new Error(`Preload timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+
+      // Start loading
+      this.load();
+
+      // Wait for completion with extended timeout
+      const waitTimeout = Math.max(timeoutMs + 1000, 2000);
+      waitForState(() => {
+        return this.loaded ||
+               this.state === STATE_ABORTED ||
+               this.state === STATE_ERROR;
+      }, waitTimeout)
+        .then(() => {
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+          }
+
+          if (progressIntervalId) {
+            clearInterval(progressIntervalId);
+            progressIntervalId = null;
+          }
+
+          if (isAborted || this.state === STATE_ABORTED) {
+            reject(new Error('Preload was aborted'));
+          } else if (this.state === STATE_ERROR) {
+            reject(new Error('Preload failed due to error'));
+          } else if (this.loaded) {
+            resolve(this);
+          } else {
+            reject(new Error(`Preload failed: unexpected state ${this.state}`));
+          }
+        })
+        .catch(reject);
+    });
+
+    return { promise, abort };
+  }
+
+  destroy() {
+    // TODO: disconnect all sources?
+    // TODO: Unload loaders?
+  }
+
+  /* ==== Internal methods */
+
+  #startLoading() {
+    for (const source of this.sources) {
+      const loader = this.getLoaderFromSource(source);
+      loader.load();
+    }
+  }
+
+  #startAbort() {
+    for (const source of this.sources) {
+      const loader = this.getLoaderFromSource(source);
+      loader.abort();
+    }
+  }
+}

package/dist/network/loaders/image/ImageScene.svelte.d.ts

@@ -7,23 +7,21 @@
  * @property {string} label
  * @property {ImageLoader} imageLoader
  */
-export default class ImageScene {
-    state: string;
-    loaded: boolean;
+export default class ImageScene extends SceneBase {
     /**
-     * Get image scene loading progress
+     * Get the array of image sources managed by this scene
+     *
+     * @returns {ImageSceneSource[]}
      */
-    get progress(): {
-        totalBytesLoaded: number;
-        totalSize: number;
-        sourcesLoaded: number;
-        numberOfSources: number;
-    };
+    get sources(): ImageSceneSource[];
     /**
-     * Start loading all image sources
+     * Extract the image loader from a source object
+     *
+     * @param {ImageSceneSource} source
+     *
+     * @returns {ImageLoader}
      */
-    load(): void;
-    destroy(): void;
+    getLoaderFromSource(source: ImageSceneSource): ImageLoader;
     /**
      * Add image source
      * - Uses an ImageLoader instance to load image data from network
@@ -73,4 +71,5 @@ export type ImageSceneSource = {
     label: string;
     imageLoader: ImageLoader;
 };
+import SceneBase from '../base/SceneBase.svelte.js';
 import ImageLoader from './ImageLoader.svelte.js';

package/dist/network/loaders/image/ImageScene.svelte.js

@@ -2,16 +2,7 @@
 
 import * as expect from '../../../util/expect.js';
 
-import { LoadingStateMachine } from '../../../state/machines.js';
-
-import {
-  STATE_INITIAL,
-  STATE_LOADING,
-  STATE_LOADED,
-  LOAD,
-  LOADED
-} from '../../../state/machines.js';
-
+import SceneBase from '../base/SceneBase.svelte.js';
 import ImageLoader from './ImageLoader.svelte.js';
 
 /**
@@ -25,101 +16,40 @@ import ImageLoader from './ImageLoader.svelte.js';
  * @property {ImageLoader} imageLoader
  */
 
-export default class ImageScene {
-  #state = new LoadingStateMachine();
-
-  // @note this exported state is set by onenter
-  state = $state(STATE_INITIAL);
-
-  loaded = $derived.by(() => {
-    return this.state === STATE_LOADED;
-  });
+export default class ImageScene extends SceneBase {
 
   /** @type {ImageSceneSource[]} */
   #imageSources = $state([]);
 
-  #progress = $derived.by(() => {
-    // console.log('update progress');
-
-    let totalSize = 0;
-    let totalBytesLoaded = 0;
-    let sourcesLoaded = 0;
-
-    const sources = this.#imageSources;
-    const numberOfSources = sources.length;
-
-    for (let j = 0; j < numberOfSources; j++) {
-      const source = sources[j];
-      const { imageLoader } = source;
-
-      const { bytesLoaded, size, loaded } = imageLoader.progress;
-
-      totalSize += size;
-      totalBytesLoaded += bytesLoaded;
-
-      if (loaded) {
-        sourcesLoaded++;
-      }
-    } // end for
-
-    return {
-      totalBytesLoaded,
-      totalSize,
-      sourcesLoaded,
-      numberOfSources
-    };
-  });
-
-  #sourcesLoaded = $derived( this.#progress.sourcesLoaded );
-  #numberOfSources = $derived( this.#progress.numberOfSources );
 
   /**
    * Construct ImageScene
    */
   constructor() {
-    const state = this.#state;
-
-    $effect( () => {
-      if (state.current === STATE_LOADING) {
-        if (this.#sourcesLoaded === this.#numberOfSources) {
-          // console.log(`All [${this.#numberOfSources}] sources loaded`);
-          this.#state.send(LOADED);
-        }
-      }
-    } );
-
-    state.onenter = ( currentState ) => {
-      // console.log('onenter', currentState );
-
-      if(currentState === STATE_LOADING )
-      {
-        // console.log('ImageScene:loading');
-        this.#startLoading();
-      }
-
-      this.state = currentState;
-    };
+    super();
   }
 
-  /* ==== Common loader interface */
+  /* ==== SceneBase implementation */
 
   /**
-   * Get image scene loading progress
+   * Get the array of image sources managed by this scene
+   *
+   * @returns {ImageSceneSource[]}
    */
-  get progress() {
-    return this.#progress;
+  get sources() {
+    return this.#imageSources;
   }
 
   /**
-   * Start loading all image sources
+   * Extract the image loader from a source object
+   *
+   * @param {ImageSceneSource} source
+   *
+   * @returns {ImageLoader}
    */
-  load() {
-    this.#state.send(LOAD);
-  }
-
-  destroy() {
-    // TODO: disconnect all image sources?
-    // TODO: Unload ImageLoaders?
+  // eslint-disable-next-line no-unused-vars
+  getLoaderFromSource(source) {
+    return source.imageLoader;
   }
 
   /* ==== Source definitions */
@@ -185,12 +115,6 @@ export default class ImageScene {
     return source.imageLoader.getObjectURL();
   }
 
-  async #startLoading() {
-    for (const { imageLoader } of this.#imageSources) {
-      imageLoader.load();
-    }
-  }
-
   /* ==== Internals */
 
   /**

package/dist/network/states/NetworkLoader.svelte.d.ts

@@ -45,9 +45,9 @@ export default class NetworkLoader {
     /**
      * Abort the current loading operation
      * - Only works when in STATE_LOADING
-     * - Aborts network requests and transitions to STATE_CANCELLED
+     * - Aborts network requests and transitions to STATE_ABORTING
      */
-    doAbort(): void;
+    abort(): void;
     /**
      * Get network data size in bytes
      * - Info comes from the content length response header

package/dist/network/states/NetworkLoader.svelte.js

@@ -7,14 +7,14 @@ import {
   STATE_LOADING,
   STATE_UNLOADING,
   STATE_LOADED,
-  STATE_CANCELLED,
-  STATE_ERROR,
+  STATE_ABORTING,
   LOAD,
   ERROR,
   LOADED,
   UNLOAD,
   INITIAL,
-  CANCEL
+  ABORT,
+  ABORTED
 } from '../../state/machines.js';
 
 import * as expect from '../../util/expect.js';
@@ -123,21 +123,23 @@ export default class NetworkLoader {
           }
           break;
 
-        case STATE_CANCELLED:
+        case STATE_ABORTING:
           {
-            // console.log('NetworkLoader:cancelled');
+            // console.log('NetworkLoader:aborting');
             if (this._abortLoading) {
               this._abortLoading();
               this._abortLoading = null;
             }
+            // Transition to aborted state after abort completes
+            this._state.send(ABORTED);
           }
           break;
 
-        case STATE_ERROR:
-          {
-            console.log('NetworkLoader:error', state.error);
-          }
-          break;
+        // case STATE_ERROR:
+        //   {
+        //     console.log('NetworkLoader:error', state.error);
+        //   }
+        //   break;
       } // end switch
     };
   }
@@ -160,10 +162,10 @@ export default class NetworkLoader {
   /**
    * Abort the current loading operation
    * - Only works when in STATE_LOADING
-   * - Aborts network requests and transitions to STATE_CANCELLED
+   * - Aborts network requests and transitions to STATE_ABORTING
    */
-  doAbort() {
-    this._state.send(CANCEL);
+  abort() {
+    this._state.send(ABORT);
   }
 
   /**

package/dist/state/machines/loading-state-machine/LoadingStateMachine.svelte.d.ts

@@ -10,13 +10,13 @@ export default class LoadingStateMachine extends FiniteStateMachine {
      * - Only valid when currently loading
      * - Useful for external timeout management
      */
-    doTimeout(): void;
+    timeout(): void;
     /**
-     * Transition to cancelled state
+     * Transition to aborting state
      * - Only valid when currently loading
-     * - Useful for external cancellation management
+     * - Useful for external abort management
      */
-    doCancel(): void;
+    abort(): void;
     #private;
 }
 import FiniteStateMachine from '../finite-state-machine/FiniteStateMachine.svelte.js';

package/dist/state/machines/loading-state-machine/LoadingStateMachine.svelte.js

@@ -8,14 +8,16 @@ import {
   STATE_LOADING,
   STATE_UNLOADING,
   STATE_LOADED,
-  STATE_CANCELLED,
+  STATE_ABORTING,
+  STATE_ABORTED,
   STATE_ERROR,
   STATE_TIMEOUT,
 
   // > Signals
   INITIAL,
   LOAD,
-  CANCEL,
+  ABORT,
+  ABORTED,
   ERROR,
   LOADED,
   UNLOAD,
@@ -41,7 +43,7 @@ export default class LoadingStateMachine extends FiniteStateMachine {
         // _enter: () => {
         //   console.log('LoadingStateMachine: enter LOADING');
         // },
-        [CANCEL]: STATE_CANCELLED,
+        [ABORT]: STATE_ABORTING,
         [ERROR]: STATE_ERROR,
         [LOADED]: STATE_LOADED,
         [TIMEOUT]: STATE_TIMEOUT
@@ -57,7 +59,11 @@ export default class LoadingStateMachine extends FiniteStateMachine {
         [ERROR]: STATE_ERROR,
         [INITIAL]: STATE_INITIAL
       },
-      [STATE_CANCELLED]: {
+      [STATE_ABORTING]: {
+        [ERROR]: STATE_ERROR,
+        [ABORTED]: STATE_ABORTED
+      },
+      [STATE_ABORTED]: {
         [LOAD]: STATE_LOADING,
         [UNLOAD]: STATE_UNLOADING
       },
@@ -99,16 +105,16 @@ export default class LoadingStateMachine extends FiniteStateMachine {
    * - Only valid when currently loading
    * - Useful for external timeout management
    */
-  doTimeout() {
+  timeout() {
     this.send(TIMEOUT);
   }
 
   /**
-   * Transition to cancelled state
+   * Transition to aborting state
    * - Only valid when currently loading
-   * - Useful for external cancellation management
+   * - Useful for external abort management
    */
-  doCancel() {
-    this.send(CANCEL);
+  abort() {
+    this.send(ABORT);
   }
 }