@hkdigital/lib-core 0.3.1

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

@@ -0,0 +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;
+    /**
+     * 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 }: {
+        label: string;
+        imageMeta: ImageMeta | ImageMeta[];
+    }): void;
+    /**
+     * Start loading all image sources
+     */
+    load(): void;
+    /**
+     * Get image scene loading progress
+     */
+    get progress(): {
+        totalBytesLoaded: number;
+        totalSize: number;
+        sourcesLoaded: number;
+        numberOfSources: number;
+    };
+    /**
+     * Get an image loader
+     *
+     * @param {string} label
+     *
+     * @returns {ImageLoader}
+     */
+    getImageLoader(label: string): ImageLoader;
+    /**
+     * Get object URL that can be used as src parameter of an HTML image
+     *
+     * @param {string} label
+     *
+     * @returns {ImageMeta}
+     */
+    getImageMeta(label: string): ImageMeta;
+    /**
+     * 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}
+     */
+    getObjectURL(label: string): string;
+    #private;
+}
+export type ImageMeta = import("./typedef.js").ImageMeta;
+/**
+ * // property ...
+ */
+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

@@ -0,0 +1,249 @@
+/** @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,
+  LOADED
+} from '../loading-state-machine/index.js';
+
+import ImageLoader from './ImageLoader.svelte.js';
+
+/**
+ * @typedef {object} SourceConfig
+ * // property ...
+ */
+
+/**
+ * @typedef {object} ImageSource
+ * @property {string} label
+ * @property {ImageLoader} imageLoader
+ * @property {ImageMeta} [imageMeta]
+ */
+
+export default class ImageScene {
+  #state = new LoadingStateMachine();
+
+  // @note this exported state is set by $effect's
+  state = $state(STATE_INITIAL);
+
+  // @note this exported state is set by $effect's
+  loaded = $derived.by(() => {
+    return this.state === STATE_LOADED;
+  });
+
+  /** @type {ImageSource[]} */
+  #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
+    };
+  });
+
+  /**
+   * Construct ImageScene
+   */
+  constructor() {
+    const state = this.#state;
+
+    $effect(() => {
+      if (state.current === STATE_LOADING) {
+        // console.log(
+        //   'progress',
+        //   JSON.stringify($state.snapshot(this.#progress))
+        // );
+
+        const { sourcesLoaded, numberOfSources } = this.#progress;
+
+        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 });
+  }
+
+  /**
+   * Start loading all image sources
+   */
+  load() {
+    this.#state.send(LOAD);
+
+    // FIXME: in unit test when moved to startloading it hangs!
+
+    for (const { imageLoader } of this.#imageSources) {
+      imageLoader.load();
+    }
+  }
+
+  async #startLoading() {
+    // console.log('#startLoading');
+    // FIXME: in unit test when moved to startloading it hangs!
+    // for (const { audioLoader } of this.#memorySources) {
+    //   audioLoader.load();
+    // }
+  }
+
+  /**
+   * Get Image source
+   *
+   * @param {string} label
+   *
+   * @returns {ImageSource}
+   */
+  #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;
+  }
+
+  /**
+   * Get an image loader
+   *
+   * @param {string} label
+   *
+   * @returns {ImageLoader}
+   */
+  getImageLoader(label) {
+    const source = this.#getImageSource(label);
+
+    return source.imageLoader;
+  }
+
+  /**
+   * Get object URL that can be used as src parameter of an HTML image
+   *
+   * @param {string} label
+   *
+   * @returns {ImageMeta}
+   */
+  getImageMeta(label) {
+    const source = this.#getImageSource(label);
+
+    return source.imageMeta;
+  }
+
+  /**
+   * 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}
+   */
+  getObjectURL(label) {
+    const source = this.#getImageSource(label);
+
+    return source.imageLoader.getObjectURL();
+  }
+}

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

@@ -0,0 +1,43 @@
+/** @typedef {import('../../../typedef/image.js').ImageMeta} ImageMeta */
+export default class ImageVariantsLoader {
+    /**
+     * @param {ImageMeta[]} imagesMeta
+     */
+    constructor(imagesMeta: ImageMeta[], { devicePixelRatio }?: {
+        devicePixelRatio?: number;
+    });
+    /**
+     * Set new optimal image variant or keep current
+     *
+     * @param {object} params
+     * @param {number} [params.containerWidth] Container width
+     * @param {number} [params.containerHeight] Container height
+     * @param {'cover'|'contain'|'fill'} [params.fit='contain'] Fit mode
+     */
+    updateOptimalImageMeta({ containerWidth, containerHeight, fit }: {
+        containerWidth?: number;
+        containerHeight?: number;
+        fit?: "cover" | "contain" | "fill";
+    }): void;
+    get loaded(): boolean;
+    get variant(): import("../../../typedef/image.js").ImageMeta;
+    /**
+     * Get object URL that can be used as src parameter of an HTML image
+     *
+     * @note the objectURL should be revoked when no longer used
+     *
+     * @returns {string|null}
+     */
+    getObjectURL(): string | null;
+    get progress(): import("../index.js").LoadingProgress;
+    /**
+     * Get optimal image variant
+     *
+     * @param {number} containerWidth
+     *
+     * @returns {ImageMeta|null}
+     */
+    getOptimalImageMeta(containerWidth: number): ImageMeta | null;
+    #private;
+}
+export type ImageMeta = import("../../../typedef/image.js").ImageMeta;

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

@@ -0,0 +1,152 @@
+import { calculateEffectiveWidth } from '../../../util/image/index.js';
+
+import ImageLoader from './ImageLoader.svelte.js';
+
+/** @typedef {import('../../../typedef/image.js').ImageMeta} ImageMeta */
+
+export default class ImageVariantsLoader {
+  /** @type {number} */
+  #devicePixelRatio;
+
+  /** @type {ImageMeta[]} */
+  #imagesMeta;
+
+  /** @type {ImageMeta|null} */
+  #imageVariant = $state(null);
+
+  /** @type {ImageLoader|null} */
+  #imageLoader = $state(null);
+
+  #progress = $derived.by(() => {
+    if (this.#imageLoader) {
+      return this.#imageLoader.progress;
+    } else {
+      return { 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);
+    // console.debug("imagesMeta",imagesMeta);
+  }
+
+  /**
+   * Set new optimal image variant or keep current
+   *
+   * @param {object} params
+   * @param {number} [params.containerWidth] Container width
+   * @param {number} [params.containerHeight] Container height
+   * @param {'cover'|'contain'|'fill'} [params.fit='contain'] Fit mode
+   */
+  updateOptimalImageMeta({ containerWidth, containerHeight, fit = 'contain' }) {
+    const baseImage = this.#imagesMeta[0];
+    const imageAspectRatio = baseImage.width / baseImage.height;
+
+    const effectiveWidth = calculateEffectiveWidth({
+      containerWidth,
+      containerHeight,
+      imageAspectRatio,
+      fit
+    });
+
+    const newVariant = this.getOptimalImageMeta(effectiveWidth);
+
+    // console.debug("updateOptimalImageMeta", effectiveWidth, newVariant );
+
+    if (
+      !newVariant ||
+      !this.#imageVariant ||
+      newVariant.width > this.#imageVariant.width
+    ) {
+      this.#imageVariant = newVariant;
+
+      // Create and start loader here directly when variant changes
+      if (this.#imageLoader?.initial) {
+        this.#imageLoader.unload();
+      }
+
+      this.#imageLoader = new ImageLoader({
+        imageMeta: newVariant
+      });
+
+
+      this.#imageLoader.load();
+    }
+  }
+
+  get loaded() {
+    return this.#loaded;
+  }
+
+  get variant() {
+    return this.#imageVariant;
+  }
+
+  /**
+   * Get object URL that can be used as src parameter of an HTML image
+   *
+   * @note the objectURL should be revoked when no longer used
+   *
+   * @returns {string|null}
+   */
+  getObjectURL() {
+    // 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() {
+    return this.#progress;
+  }
+
+  /**
+   * Get optimal image variant
+   *
+   * @param {number} containerWidth
+   *
+   * @returns {ImageMeta|null}
+   */
+  getOptimalImageMeta(containerWidth) {
+    if (!containerWidth) {
+      return null;
+    }
+
+    // Calculate the required width (container * DPR)
+    const requiredWidth = containerWidth * this.#devicePixelRatio;
+
+    const imagesMeta = this.#imagesMeta;
+
+    // Find the smallest image that's larger than our required width
+
+    const optimal = imagesMeta.find(
+      (current) => current.width >= requiredWidth
+    );
+
+    // Fall back to the largest image if nothing is big enough
+    return optimal || imagesMeta[imagesMeta.length - 1];
+  }
+} // end class

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

@@ -0,0 +1,2 @@
+export { default as ImageLoader } from "./ImageLoader.svelte.js";
+export { default as ImageVariantsLoader } from "./ImageVariantsLoader.svelte.js";

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

@@ -0,0 +1,4 @@
+export { default as ImageLoader } from './ImageLoader.svelte.js';
+export { default as ImageVariantsLoader } from './ImageVariantsLoader.svelte.js';
+
+// export * from './constants.js';

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

@@ -0,0 +1,7 @@
+/**
+ * Create a response value that can be used by a mocked
+ * fetch function
+ *
+ * @returns {Response}
+ */
+export function createPngResponse(): Response;

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

@@ -0,0 +1,35 @@
+import { CONTENT_TYPE, CONTENT_LENGTH } from '../../../constants/http/index.js';
+
+import { IMAGE_PNG } from '../../../constants/mime/image.js';
+
+/**
+ * A minimal 1x1 black PNG encoded as base64
+ * @constant {string}
+ */
+const BASE64_PNG =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==';
+
+/**
+ * Create a response value that can be used by a mocked
+ * fetch function
+ *
+ * @returns {Response}
+ */
+export function createPngResponse(/* data , options */) {
+  // Convert base64 to binary
+  const binaryString = atob(BASE64_PNG);
+  const bytes = new Uint8Array(binaryString.length);
+
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+
+  const response = new Response(bytes, {
+    headers: new Headers({
+      [CONTENT_TYPE]: IMAGE_PNG,
+      [CONTENT_LENGTH]: String(bytes.length)
+    })
+  });
+
+  return response;
+}

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

@@ -0,0 +1,16 @@
+declare const _default: {};
+export default _default;
+export type ImageMeta = {
+    /**
+     * - URL of the image
+     */
+    src: string;
+    /**
+     * - Width of the image
+     */
+    width: number;
+    /**
+     * - Height of the image
+     */
+    height: number;
+};

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

@@ -0,0 +1,8 @@
+/**
+ * @typedef {Object} ImageMeta
+ * @property {string} src - URL of the image
+ * @property {number} width - Width of the image
+ * @property {number} height - Height of the image
+ */
+
+export default {};

package/dist/classes/svelte/index.d.ts

@@ -0,0 +1,9 @@
+export { default as AudioScene } from "./audio/AudioScene.svelte.js";
+export { default as AudioLoader } from "./audio/AudioLoader.svelte.js";
+export { default as FiniteStateMachine } from "./finite-state-machine/FiniteStateMachine.svelte.js";
+export { default as ImageLoader } from "./image/ImageLoader.svelte.js";
+export { default as ImageScene } from "./image/ImageScene.svelte.js";
+export { default as ImageVariantsLoader } from "./image/ImageVariantsLoader.svelte.js";
+export { default as NetworkLoader } from "./network-loader/NetworkLoader.svelte.js";
+export * from "./image/typedef.js";
+export * from "./network-loader/typedef.js";

package/dist/classes/svelte/index.js

@@ -0,0 +1,14 @@
+
+export { default as AudioScene } from './audio/AudioScene.svelte.js';
+export { default as AudioLoader } from './audio/AudioLoader.svelte.js';
+
+export { default as FiniteStateMachine } from './finite-state-machine/FiniteStateMachine.svelte.js';
+
+export { default as ImageLoader } from './image/ImageLoader.svelte.js';
+export { default as ImageScene } from './image/ImageScene.svelte.js';
+export { default as ImageVariantsLoader } from './image/ImageVariantsLoader.svelte.js';
+
+export { default as NetworkLoader } from './network-loader/NetworkLoader.svelte.js';
+
+export * from './image/typedef.js';
+export * from './network-loader/typedef.js';

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

@@ -0,0 +1,12 @@
+/**
+ * extends FiniteStateMachine<StatesT, EventsT>
+ */
+export default class LoadingStateMachine extends FiniteStateMachine {
+    constructor();
+    /** @type {(( state: string )=>void)|null} */
+    onenter: ((state: string) => void) | null;
+    /** The last error */
+    get error(): Error;
+    #private;
+}
+import { FiniteStateMachine } from '../finite-state-machine/index.js';