@hkdigital/lib-core 0.3.1

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

@@ -0,0 +1,3 @@
+export * as observe from "./observe/index.js";
+export * as stateContext from "./state-context/index.js";
+export * as loading from "./loading/loading-tracker.svelte.js";

package/dist/util/svelte/index.js

@@ -0,0 +1,4 @@
+export * as observe from './observe/index.js';
+export * as stateContext from './state-context/index.js';
+
+export * as loading from './loading/loading-tracker.svelte.js';

package/dist/util/svelte/loading/loading-tracker.svelte.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Simple utility for tracking combined loading progress across multiple components
+ *
+ * @typedef {Object} LoadingProgress
+ * @property {number} bytesLoaded - Number of bytes loaded
+ * @property {number} size - Total size in bytes
+ * @property {boolean} loaded - Whether loading is complete
+ */
+/**
+ * Creates a loading tracker that combines progress from multiple sources
+ *
+ * @returns {Object} Loading tracker instance
+ */
+export function createTracker(): any;
+/**
+ * Simple utility for tracking combined loading progress across multiple components
+ */
+export type LoadingProgress = {
+    /**
+     * - Number of bytes loaded
+     */
+    bytesLoaded: number;
+    /**
+     * - Total size in bytes
+     */
+    size: number;
+    /**
+     * - Whether loading is complete
+     */
+    loaded: boolean;
+};

package/dist/util/svelte/loading/loading-tracker.svelte.js

@@ -0,0 +1,108 @@
+/**
+ * Simple utility for tracking combined loading progress across multiple components
+ *
+ * @typedef {Object} LoadingProgress
+ * @property {number} bytesLoaded - Number of bytes loaded
+ * @property {number} size - Total size in bytes
+ * @property {boolean} loaded - Whether loading is complete
+ */
+
+/**
+ * Creates a loading tracker that combines progress from multiple sources
+ *
+ * @returns {Object} Loading tracker instance
+ */
+export function createTracker() {
+  // Store progress for each item by ID
+  const items = new Map();
+
+  // Computed values
+  let totalBytesLoaded = 0;
+  let totalSize = 0;
+  let allLoaded = false;
+  let progressPercent = 0;
+
+  /**
+   * Update the totals based on current items
+   */
+  function updateTotals() {
+    let bytesLoaded = 0;
+    let size = 0;
+    let loaded = items.size > 0;
+
+    // Loop through all items and sum values
+    for (const progress of items.values()) {
+      bytesLoaded += progress.bytesLoaded || 0;
+      size += progress.size || 0;
+
+      if (!progress.loaded) {
+        loaded = false;
+      }
+    }
+
+    // Update state
+    totalBytesLoaded = bytesLoaded;
+    totalSize = size;
+    allLoaded = items.size > 0 ? loaded : false;
+    progressPercent = size > 0 ? Math.round((bytesLoaded / size) * 100) : 0;
+  }
+
+  /**
+   * Track progress for a component
+   *
+   * @param {LoadingProgress} progress - The progress update
+   * @param {string|Symbol} id - The component identifier
+   */
+  function track(progress, id) {
+    if (progress && id) {
+      items.set(id, progress);
+      updateTotals();
+    }
+  }
+
+  /**
+   * Remove an item from tracking
+   *
+   * @param {string|Symbol} id - Item identifier to remove
+   */
+  function remove(id) {
+    if (items.has(id)) {
+      items.delete(id);
+      updateTotals();
+    }
+  }
+
+  /**
+   * Reset the tracker, clearing all items
+   */
+  function reset() {
+    items.clear();
+    updateTotals();
+  }
+
+  // Return the public API
+  return {
+    track,
+    remove,
+    reset,
+
+    // Read-only properties
+    get state() {
+      return {
+        bytesLoaded: totalBytesLoaded,
+        size: totalSize,
+        loaded: allLoaded,
+        percent: progressPercent,
+        itemCount: items.size
+      };
+    },
+
+    get loaded() {
+      return allLoaded;
+    },
+
+    get percent() {
+      return progressPercent;
+    }
+  };
+}

package/dist/util/svelte/observe/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @param {function} target
+ * @param {(entries:ResizeObserverEntry[]) => void} callback
+ * @param {object} [options]
+ *
+ * @returns {{ stop: () => void }}
+ */
+export function useResizeObserver(target: Function, callback: (entries: ResizeObserverEntry[]) => void, options?: object): {
+    stop: () => void;
+};

package/dist/util/svelte/observe/index.js

@@ -0,0 +1,49 @@
+import { onMount, onDestroy } from 'svelte';
+
+/**
+ * @param {function} target
+ * @param {(entries:ResizeObserverEntry[]) => void} callback
+ * @param {object} [options]
+ *
+ * @returns {{ stop: () => void }}
+ */
+export function useResizeObserver(target, callback, options) {
+	/** @type {HTMLInputElement} */
+	let elem;
+
+	/** @type {ResizeObserver|undefined} */
+	let resizeObserver;
+
+	onMount(() => {
+		// console.log('useResizeObserver:onMount');
+
+		if (target instanceof HTMLInputElement) {
+			elem = target;
+		} else if (typeof target === 'function') {
+			let output = target();
+
+			// console.log({ output });
+
+			elem = output;
+		} else {
+			throw new Error('Invalid value for parameter [target]');
+		}
+
+		resizeObserver = new ResizeObserver(callback);
+
+		resizeObserver.observe(elem);
+	});
+
+	onDestroy(() => {
+		// console.log('useResizeObserver:onDestroy');
+
+		if (resizeObserver) {
+			resizeObserver.unobserve(elem);
+			resizeObserver = undefined;
+		}
+	});
+
+	return {
+		stop: () => {}
+	};
+}

package/dist/util/svelte/state-context/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Define a state context:
+ * - Returns a function 'createOrGetState' that can be used to create a new state
+ *   or get an existing one
+ * - Returns a function 'createState' that can be used to create a new state
+ *
+ * @template T
+ *
+ * @param {new() => T} State - Class that can be used to construct the state
+ *
+ * @returns {[
+ *   createOrGetState,
+ *   createState,
+ *   getState
+ * ]}
+ */
+export function defineStateContext<T>(State: new () => T): [(contextKey?: import("../../../typedef").ContextKey) => T, (contextKey?: import("../../../typedef").ContextKey) => T, (contextKey?: import("../../../typedef").ContextKey) => T];
+export const DEFAULT_CONTEXT_KEY: "default";

package/dist/util/svelte/state-context/index.js

@@ -0,0 +1,117 @@
+import { setContext, getContext, hasContext } from 'svelte';
+
+export const DEFAULT_CONTEXT_KEY = 'default';
+
+/* ----------------------------------------------------------- Create and Get */
+
+/**
+ * Define a state context:
+ * - Returns a function 'createOrGetState' that can be used to create a new state
+ *   or get an existing one
+ * - Returns a function 'createState' that can be used to create a new state
+ *
+ * @template T
+ *
+ * @param {new() => T} State - Class that can be used to construct the state
+ *
+ * @returns {[
+ *   createOrGetState,
+ *   createState,
+ *   getState
+ * ]}
+ */
+export function defineStateContext(State) {
+  const stateName = State.name;
+
+  const sharedKey = Symbol(stateName);
+
+  // console.debug(`Creating state context for ${stateName}`, { sharedKey });
+
+  /**
+   * Internal function to get the supplied key or the shared key
+   *
+   * @param {import('../../../typedef').ContextKey} [contextKey]
+   *
+   * @returns {Symbol} key
+   */
+  function getKey(contextKey) {
+    if (typeof contextKey === 'symbol') {
+      return contextKey;
+    }
+
+    if (
+      contextKey === undefined ||
+      contextKey === null ||
+      contextKey === DEFAULT_CONTEXT_KEY
+    ) {
+      return sharedKey;
+    }
+
+    throw new Error(
+      `Invalid contextKey (use a Symbol or DEFAULT_CONTEXT_KEY)`
+    );
+  }
+
+  /**
+   * Create component state
+   *
+   * @param {import('../../../typedef').ContextKey} [contextKey]
+   *
+   * @returns {T} state
+   */
+  function createState(contextKey) {
+    const key = getKey(contextKey);
+
+    // console.log('Create state', key);
+    // console.debug(`Creating new state for ${stateName}`, {
+    //   key,
+    //   contextKey,
+    //   isDefaultKey: key === sharedKey
+    // });
+
+    const state = new State();
+
+    // @ts-ignore
+    state._contextKey = contextKey;
+
+    return setContext(key, state);
+  }
+
+  /**
+   * Get component state or create a new state if it does not yet exist
+   *
+   * @param {import('../../../typedef').ContextKey} [contextKey]
+   *
+   * @returns {T} state
+   */
+  function createOrGetState(contextKey) {
+    let key = getKey(contextKey);
+
+    if (!hasContext(key)) {
+      return createState(key);
+    }
+
+    return getContext(key);
+  }
+
+  /**
+   * Get component state
+   *
+   * @throws Will throw an error if the state-context does not exist
+   *
+   * @param {import('../../../typedef').ContextKey} [contextKey]
+   *
+   * @returns {T} state
+   */
+  function getState(contextKey) {
+    let key = getKey(contextKey);
+
+    if (!hasContext(key)) {
+      throw new Error(`No state context found. Create one first`);
+    }
+
+    return getContext(key);
+  }
+
+  return [createOrGetState, createState, getState];
+}

package/dist/util/svelte/wait/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Waits for a state condition to be met by running the checkFn
+ * function after each Svelte tick
+ *
+ * @param {() => boolean} checkFn -
+ *   Should return true when desired state is reached
+ *
+ * @param {number} [maxWaitMs=1000]
+ *
+ * @returns {Promise<void>} Promise that resolves when the check
+ *   function returns true
+ * @throws {Error} if maxAttempts is reached before
+ * predicate returns true
+ */
+export function waitForState(checkFn: () => boolean, maxWaitMs?: number): Promise<void>;

package/dist/util/svelte/wait/index.js

@@ -0,0 +1,38 @@
+import { tick } from 'svelte';
+
+/**
+ * Waits for a state condition to be met by running the checkFn
+ * function after each Svelte tick
+ *
+ * @param {() => boolean} checkFn -
+ *   Should return true when desired state is reached
+ *
+ * @param {number} [maxWaitMs=1000]
+ *
+ * @returns {Promise<void>} Promise that resolves when the check
+ *   function returns true
+ * @throws {Error} if maxAttempts is reached before
+ * predicate returns true
+ */
+export function waitForState(checkFn, maxWaitMs = 1000) {
+  let startedAt = Date.now();
+
+  return new Promise((resolve, reject) => {
+    async function checkLoop() {
+      if (checkFn()) {
+        resolve();
+        return;
+      }
+
+      if (Date.now() - startedAt >= maxWaitMs) {
+        reject(new Error(`State change timeout`));
+        return;
+      }
+
+      await tick();
+      checkLoop();
+    }
+
+    checkLoop();
+  });
+}

package/dist/util/sveltekit/index.d.ts

@@ -0,0 +1 @@
+export * from "./route-folders/index.js";

package/dist/util/sveltekit/index.js

@@ -0,0 +1 @@
+export * from './route-folders/index.js';

package/dist/util/sveltekit/route-folders/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Validates if a path is within the project's src/routes directory
+ * @param {string} path - Path to validate
+ * @returns {boolean}
+ */
+export function isValidRoutePath(path: string): boolean;
+/**
+ * Scans route folders recursively, only including folders with +page.svelte
+ * @param {Object} options - Scan options
+ * @param {string} options.dirPath - Directory path to scan
+ * @param {number} [options.maxDepth=1] - Maximum depth to scan
+ * @param {Set<string>} [options.skipFolders] - Folders to skip
+ *
+ * @param {number} [depth=0] - Do not set manually!
+ *
+ * @returns {Promise<Array<{displayName: string, path: string, depth: number}>>}
+ *
+ * @throws {Error} If path is outside project routes directory
+ */
+export function scanRouteFolders({ dirPath, maxDepth, skipFolders }: {
+    dirPath: string;
+    maxDepth?: number;
+    skipFolders?: Set<string>;
+}, depth?: number): Promise<Array<{
+    displayName: string;
+    path: string;
+    depth: number;
+}>>;

package/dist/util/sveltekit/route-folders/index.js

@@ -0,0 +1,101 @@
+import { readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { kebabToTitleCase, basename } from '../../string/index.js';
+
+/**
+ * Validates if a path is within the project's src/routes directory
+ * @param {string} path - Path to validate
+ * @returns {boolean}
+ */
+export function isValidRoutePath(path) {
+  const normalizedPath = resolve(path);
+  const routesPath = resolve(process.cwd(), 'src/routes');
+  return normalizedPath.startsWith(routesPath);
+}
+
+/**
+ * Scans route folders recursively, only including folders with +page.svelte
+ * @param {Object} options - Scan options
+ * @param {string} options.dirPath - Directory path to scan
+ * @param {number} [options.maxDepth=1] - Maximum depth to scan
+ * @param {Set<string>} [options.skipFolders] - Folders to skip
+ *
+ * @param {number} [depth=0] - Do not set manually!
+ *
+ * @returns {Promise<Array<{displayName: string, path: string, depth: number}>>}
+ *
+ * @throws {Error} If path is outside project routes directory
+ */
+export async function scanRouteFolders(
+  { dirPath, maxDepth = 1, skipFolders },
+  depth = 0
+) {
+  // console.debug({
+  //   maxDepth,
+  //   depth
+  // });
+
+  if (!isValidRoutePath(dirPath)) {
+    throw new Error('Invalid path: Must be within src/routes directory');
+  }
+
+  if (depth > maxDepth) return [];
+
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    const results = [];
+
+    for (const entry of entries) {
+      if (
+        !entry.isDirectory() ||
+        skipFolders?.has(entry.name) ||
+        entry.name.startsWith('.')
+      ) {
+        continue;
+      }
+
+      const fullPath = join(dirPath, entry.name);
+      const currentPath = entry.name;
+
+      const dirContents = await readdir(fullPath);
+      const hasPageFile = dirContents.includes('+page.svelte');
+
+      if (hasPageFile) {
+        results.push({
+          displayName: entry.name,
+          path: currentPath,
+          depth
+        });
+      }
+
+      if (maxDepth > 1) {
+        const subFolders = await scanRouteFolders(
+          {
+            dirPath: fullPath,
+            maxDepth,
+            skipFolders
+          },
+          depth + 1
+        );
+
+        for (const subFolder of subFolders) {
+          const path = `${currentPath}/${subFolder.path}`;
+
+          const displayName = kebabToTitleCase(basename(subFolder.path));
+
+          results.push({
+            displayName,
+            path,
+            depth: subFolder.depth
+          });
+        }
+      }
+    }
+
+    return results;
+  } catch (err) {
+    console.error(err);
+    throw new Error('Failed to scan directory');
+  }
+}

package/dist/util/time/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Returns a promise that resolves after a specified timeout
+ * - If the returned promise is rejected, the timeout is cancelled
+ *
+ * @param  {number} delayOrMinDelayMs
+ *   Number of milliseconds to wait before promise resolves
+ *
+ * @param  {number} [maxDelayMs=delayOrMinDelayMs]
+ *   Maximum number of milliseconds to wait before the returned promise
+ *   resolves. If this parameter is set, the delay will be chosen randomly
+ *   between the values [delayOrMinDelayMs, maxDelayMs]
+ *
+ * @returns {HkPromise} promise that resolves after a specified timeout
+ */
+export function delay(delayOrMinDelayMs: number, maxDelayMs?: number): HkPromise;
+/**
+ * Get the number of milliseconds since the specified time stamp of the default
+ * reference time stamp TIME_2025_01_01
+ *
+ * @param {number} [sinceMs=TIME_2025_01_01]
+ *
+ * @returns {number} number of milliseconds since the specified time
+ */
+export function sinceMs(sinceMs?: number): number;
+/**
+ * Get a string that represents the time in a readable
+ * string format: [DD:][HH:]MM:SS.mmm
+ *
+ * @param {number} timeMs [description]
+ *
+ * @returns {string} time in human readable format
+ */
+export function timeToString(timeMs: number): string;
+/**
+ * Returns a Date object
+ * - The input can be a Date object or a numeric timestamp
+ *
+ * @param {Date|number} dateOrTimestamp
+ *
+ * @returns {Date} date object
+ */
+export function toDate(dateOrTimestamp: Date | number): Date;
+/**
+ * Get the ISO 8601 week number of the specified date
+ *
+ * @see https://stackoverflow.com
+ *      /questions/6117814/get-week-of-year-in-javascript-like-in-php
+ *
+ * @param {Date|number} dateOrTimestamp
+ *
+ * @returns {number} week number
+ */
+export function getWeekNumber(dateOrTimestamp: Date | number): number;
+/**
+ * Get the name of the month
+ * - Returns the month name using Intl.DateTimeFormat
+ * - By default uses English locale, but locale can be specified
+ *
+ * @param {Date|number} dateOrTimestamp - Date object or timestamp
+ * @param {string} [locale='nl-NL'] - The locale to use for the month name
+ *
+ * @param {Object} [options]
+ * @param {'numeric'|'2-digit'|'narrow'|'short'|'long'} [options.month='long']
+ * @param {string} [options.timeZone] - Optional timezone
+ *
+ * @returns {string} name of the month in the specified locale
+ */
+export function getMonthName(dateOrTimestamp: Date | number, locale?: string, options?: {
+    month?: "numeric" | "2-digit" | "narrow" | "short" | "long";
+    timeZone?: string;
+}): string;
+/**
+ * Get the name of the day of the week
+ * - Returns the day name using Intl.DateTimeFormat
+ * - By default uses English locale, but locale can be specified
+ *
+ * @param {Date|number} dateOrTimestamp - Date object or timestamp
+ * @param {string} [locale='nl-NL'] - The locale to use for the day name
+ *
+ * @param {Object} [options]
+ * @param {'narrow'|'short'|'long'} [options.weekday='long']
+ * @param {string} [options.timeZone] - Optional timezone
+ *
+ * @returns {string} name of the day in the specified locale
+ */
+export function getDayName(dateOrTimestamp: Date | number, locale?: string, options?: {
+    weekday?: "narrow" | "short" | "long";
+    timeZone?: string;
+}): string;
+/**
+ * Return the timestamp of the start of the day
+ * - Midnight
+ *
+ * @param {Date|number} [dateOrTimestamp]
+ *
+ * @returns {number} timestamp of start of the day (00:00:00:0000)
+ */
+export function getTimeAtStartOfDay(dateOrTimestamp?: Date | number): number;
+/**
+ * Return the timestamp of the end of the day
+ * - Midnight - 1 millisecond
+ *
+ * @param {Date|number} [dateOrTimestamp]
+ *
+ * @returns {number} timestamp of start of the day
+ */
+export function getTimeAtEndOfDay(dateOrTimestamp?: Date | number): number;
+import { HkPromise } from '../../classes/promise/index.js';