@hkdigital/lib-core 0.5.45 → 0.5.46

package/dist/state/machines/page-machine/PageMachine.svelte.d.ts

@@ -9,10 +9,17 @@
  * - State-to-route mapping and sync
  * - Data properties for business/domain state
  * - Visited states tracking
+ * - onEnter hooks with abort/complete handlers for animations
  *
  * Basic usage:
  * ```javascript
- * const machine = cityState.getOrCreatePageMachine('intro', IntroPageMachine);
+ * const machine = new PageMachine({
+ *   initialState: STATE_START,
+ *   routeMap: {
+ *     [STATE_START]: '/intro/start',
+ *     [STATE_PROFILE]: '/intro/profile'
+ *   }
+ * });
  *
  * // Sync machine state with URL changes
  * $effect(() => {
@@ -20,54 +27,73 @@
  * });
  * ```
  *
- * With data properties (for business logic):
+ * With onEnter hooks (for animations):
  * ```javascript
- * // Initialize with server data
- * const initialData = {
- *   HAS_STRONG_PROFILE: false,
- *   PROFILE_COMPLETED: false,
- *   MATCHED_SECTOR: null
- * };
- * const machine = new CircuitPageMachine(initialState, routeMap, initialData);
+ * const machine = new PageMachine({
+ *   initialState: STATE_ANIMATE,
+ *   routeMap: {
+ *     [STATE_ANIMATE]: '/game/animate',
+ *     [STATE_PLAY]: '/game/play'
+ *   },
+ *   onEnterHooks: {
+ *     [STATE_ANIMATE]: (done) => {
+ *       const animation = playAnimation(1000);
+ *       animation.finished.then(() => done(STATE_PLAY));
  *
- * // Read data
- * if (machine.getData('HAS_STRONG_PROFILE')) {
- *   // Show advanced content
- * }
+ *       return {
+ *         abort: () => animation.cancel(),
+ *         complete: () => animation.finish()
+ *       };
+ *     }
+ *   }
+ * });
  *
- * // Update data (triggers reactivity)
- * machine.setData('HAS_STRONG_PROFILE', true);
+ * // Fast-forward animation
+ * machine.completeTransitions();
  *
- * // Check visited states
- * if (machine.hasVisited(STATE_PROFILE)) {
- *   // User has seen profile page before
- * }
+ * // Cancel animation
+ * machine.abortTransitions();
  * ```
  */
 export default class PageMachine {
     /**
      * Constructor
      *
-     * @param {string} initialState - Initial state name
-     * @param {Record<string, string>} routeMap - Map of states to route paths
-     * @param {Record<string, any>} [initialData={}] - Initial data properties (from server)
+     * @param {Object} config - Configuration object
+     * @param {string} config.initialState - Initial state name
+     * @param {Record<string, string>} [config.routeMap={}] - Map of states to route paths
+     * @param {Record<string, any>} [config.initialData={}] - Initial data properties (from server)
+     * @param {Record<string, Function>} [config.onEnterHooks={}] - Map of states to onEnter hook functions
      *
      * @example
      * ```javascript
-     * const routeMap = {
-     *   [STATE_MATCH]: '/city/intro/match',
-     *   [STATE_CIRCUIT]: '/city/intro/racecircuit'
-     * };
-     *
-     * const initialData = {
-     *   INTRO_COMPLETED: false,
-     *   PROFILE_SCORE: 0
-     * };
-     *
-     * const machine = new CityIntroPageMachine(STATE_START, routeMap, initialData);
+     * const machine = new PageMachine({
+     *   initialState: STATE_START,
+     *   routeMap: {
+     *     [STATE_START]: '/intro/start',
+     *     [STATE_ANIMATE]: '/intro/animate'
+     *   },
+     *   initialData: {
+     *     INTRO_COMPLETED: false
+     *   },
+     *   onEnterHooks: {
+     *     [STATE_ANIMATE]: (done) => {
+     *       setTimeout(() => done(STATE_START), 1000);
+     *       return {
+     *         abort: () => clearTimeout(...),
+     *         complete: () => done(STATE_START)
+     *       };
+     *     }
+     *   }
+     * });
      * ```
      */
-    constructor(initialState: string, routeMap?: Record<string, string>, initialData?: Record<string, any>);
+    constructor({ initialState, routeMap, initialData, onEnterHooks }: {
+        initialState: string;
+        routeMap?: Record<string, string> | undefined;
+        initialData?: Record<string, any> | undefined;
+        onEnterHooks?: Record<string, Function> | undefined;
+    });
     /**
      * Synchronize machine state with URL path
      *
@@ -81,10 +107,11 @@ export default class PageMachine {
     syncFromPath(currentPath: string): boolean;
     /**
      * Set the current state directly
+     * Handles onEnter hooks and auto-transitions
      *
      * @param {string} newState - Target state
      */
-    setState(newState: string): void;
+    setState(newState: string): Promise<void>;
     /**
      * Get route path for a given state
      *
@@ -191,5 +218,53 @@ export default class PageMachine {
      * Useful for testing or resetting experience
      */
     resetVisitedStates(): void;
+    /**
+     * Abort current state's transitions
+     * Cancels animations/operations immediately (incomplete state)
+     *
+     * @example
+     * ```javascript
+     * // User clicks "Cancel" button
+     * machine.abortTransitions();
+     * ```
+     */
+    abortTransitions(): void;
+    /**
+     * Complete current state's transitions immediately
+     * Fast-forwards animations/operations to completion (complete state)
+     *
+     * @example
+     * ```javascript
+     * // User clicks "Skip" or "Next" button
+     * machine.completeTransitions();
+     * ```
+     */
+    completeTransitions(): void;
+    /**
+     * Check if current state has transitions that can be completed
+     *
+     * @returns {boolean} True if completeTransitions() can be called
+     *
+     * @example
+     * ```svelte
+     * {#if machine.canCompleteTransitions}
+     *   <button onclick={() => machine.completeTransitions()}>Skip</button>
+     * {/if}
+     * ```
+     */
+    get canCompleteTransitions(): boolean;
+    /**
+     * Check if current state has transitions that can be aborted
+     *
+     * @returns {boolean} True if abortTransitions() can be called
+     *
+     * @example
+     * ```svelte
+     * {#if machine.canAbortTransitions}
+     *   <button onclick={() => machine.abortTransitions()}>Cancel</button>
+     * {/if}
+     * ```
+     */
+    get canAbortTransitions(): boolean;
     #private;
 }

package/dist/state/machines/page-machine/PageMachine.svelte.js

@@ -9,10 +9,17 @@
  * - State-to-route mapping and sync
  * - Data properties for business/domain state
  * - Visited states tracking
+ * - onEnter hooks with abort/complete handlers for animations
  *
  * Basic usage:
  * ```javascript
- * const machine = cityState.getOrCreatePageMachine('intro', IntroPageMachine);
+ * const machine = new PageMachine({
+ *   initialState: STATE_START,
+ *   routeMap: {
+ *     [STATE_START]: '/intro/start',
+ *     [STATE_PROFILE]: '/intro/profile'
+ *   }
+ * });
  *
  * // Sync machine state with URL changes
  * $effect(() => {
@@ -20,28 +27,32 @@
  * });
  * ```
  *
- * With data properties (for business logic):
+ * With onEnter hooks (for animations):
  * ```javascript
- * // Initialize with server data
- * const initialData = {
- *   HAS_STRONG_PROFILE: false,
- *   PROFILE_COMPLETED: false,
- *   MATCHED_SECTOR: null
- * };
- * const machine = new CircuitPageMachine(initialState, routeMap, initialData);
+ * const machine = new PageMachine({
+ *   initialState: STATE_ANIMATE,
+ *   routeMap: {
+ *     [STATE_ANIMATE]: '/game/animate',
+ *     [STATE_PLAY]: '/game/play'
+ *   },
+ *   onEnterHooks: {
+ *     [STATE_ANIMATE]: (done) => {
+ *       const animation = playAnimation(1000);
+ *       animation.finished.then(() => done(STATE_PLAY));
  *
- * // Read data
- * if (machine.getData('HAS_STRONG_PROFILE')) {
- *   // Show advanced content
- * }
+ *       return {
+ *         abort: () => animation.cancel(),
+ *         complete: () => animation.finish()
+ *       };
+ *     }
+ *   }
+ * });
  *
- * // Update data (triggers reactivity)
- * machine.setData('HAS_STRONG_PROFILE', true);
+ * // Fast-forward animation
+ * machine.completeTransitions();
  *
- * // Check visited states
- * if (machine.hasVisited(STATE_PROFILE)) {
- *   // User has seen profile page before
- * }
+ * // Cancel animation
+ * machine.abortTransitions();
  * ```
  */
 export default class PageMachine {
@@ -85,32 +96,71 @@ export default class PageMachine {
 	 */
 	#revision = $state(0);
 
+	/**
+	 * Map of state names to onEnter hook configurations
+	 * @type {Record<string, {onEnter: Function}>}
+	 */
+	#onEnterHooks = {};
+
+	/**
+	 * Current state's onEnter handler (abort/complete functions)
+	 * @type {{abort?: Function, complete?: Function} | null}
+	 */
+	#currentOnEnterHandler = null;
+
+	/**
+	 * Current state's done callback
+	 * @type {Function | null}
+	 */
+	#currentOnEnterDone = null;
+
+	/**
+	 * Flag to prevent concurrent state transitions
+	 * @type {boolean}
+	 */
+	#isTransitioning = false;
+
 	/**
 	 * Constructor
 	 *
-	 * @param {string} initialState - Initial state name
-	 * @param {Record<string, string>} routeMap - Map of states to route paths
-	 * @param {Record<string, any>} [initialData={}] - Initial data properties (from server)
+	 * @param {Object} config - Configuration object
+	 * @param {string} config.initialState - Initial state name
+	 * @param {Record<string, string>} [config.routeMap={}] - Map of states to route paths
+	 * @param {Record<string, any>} [config.initialData={}] - Initial data properties (from server)
+	 * @param {Record<string, Function>} [config.onEnterHooks={}] - Map of states to onEnter hook functions
 	 *
 	 * @example
 	 * ```javascript
-	 * const routeMap = {
-	 *   [STATE_MATCH]: '/city/intro/match',
-	 *   [STATE_CIRCUIT]: '/city/intro/racecircuit'
-	 * };
-	 *
-	 * const initialData = {
-	 *   INTRO_COMPLETED: false,
-	 *   PROFILE_SCORE: 0
-	 * };
-	 *
-	 * const machine = new CityIntroPageMachine(STATE_START, routeMap, initialData);
+	 * const machine = new PageMachine({
+	 *   initialState: STATE_START,
+	 *   routeMap: {
+	 *     [STATE_START]: '/intro/start',
+	 *     [STATE_ANIMATE]: '/intro/animate'
+	 *   },
+	 *   initialData: {
+	 *     INTRO_COMPLETED: false
+	 *   },
+	 *   onEnterHooks: {
+	 *     [STATE_ANIMATE]: (done) => {
+	 *       setTimeout(() => done(STATE_START), 1000);
+	 *       return {
+	 *         abort: () => clearTimeout(...),
+	 *         complete: () => done(STATE_START)
+	 *       };
+	 *     }
+	 *   }
+	 * });
 	 * ```
 	 */
-	constructor(initialState, routeMap = {}, initialData = {}) {
+	constructor({ initialState, routeMap = {}, initialData = {}, onEnterHooks = {} }) {
+		if (!initialState) {
+			throw new Error('PageMachine requires initialState parameter');
+		}
+
 		this.#current = initialState;
 		this.#routeMap = routeMap;
 		this.#data = initialData;
+		this.#onEnterHooks = this.#normalizeOnEnterHooks(onEnterHooks);
 
 		// Build reverse map (path -> state)
 		for (const [state, path] of Object.entries(routeMap)) {
@@ -121,6 +171,29 @@ export default class PageMachine {
 		this.#visitedStates.add(initialState);
 	}
 
+	/**
+	 * Normalize onEnterHooks to ensure consistent format
+	 * Converts function to {onEnter: function} object
+	 *
+	 * @param {Record<string, Function|Object>} hooks - Raw hooks configuration
+	 * @returns {Record<string, {onEnter: Function}>} Normalized hooks
+	 */
+	#normalizeOnEnterHooks(hooks) {
+		const normalized = {};
+
+		for (const [state, hook] of Object.entries(hooks)) {
+			if (typeof hook === 'function') {
+				// Simple function -> wrap in object
+				normalized[state] = { onEnter: hook };
+			} else if (hook && typeof hook === 'object' && hook.onEnter) {
+				// Already an object with onEnter
+				normalized[state] = hook;
+			}
+		}
+
+		return normalized;
+	}
+
 	/**
 	 * Synchronize machine state with URL path
 	 *
@@ -146,13 +219,66 @@ export default class PageMachine {
 
 	/**
 	 * Set the current state directly
+	 * Handles onEnter hooks and auto-transitions
 	 *
 	 * @param {string} newState - Target state
 	 */
-	setState(newState) {
-		if (newState !== this.#current) {
-			this.#current = newState;
+	async setState(newState) {
+		if (newState === this.#current || this.#isTransitioning) {
+			return;
+		}
+
+		// Abort previous state's onEnter handler
+		if (this.#currentOnEnterHandler?.abort) {
+			this.#currentOnEnterHandler.abort();
 		}
+		this.#currentOnEnterHandler = null;
+		this.#currentOnEnterDone = null;
+
+		this.#isTransitioning = true;
+		this.#current = newState;
+		this.#visitedStates.add(newState);
+
+		// Check if this state has an onEnter hook
+		const hookConfig = this.#onEnterHooks[newState];
+		if (hookConfig?.onEnter) {
+			// Create done callback for auto-transition
+			let doneCalled = false;
+			const done = (nextState) => {
+				if (!doneCalled && nextState && nextState !== newState) {
+					doneCalled = true;
+					this.#isTransitioning = false;
+					this.setState(nextState);
+				}
+			};
+
+			this.#currentOnEnterDone = done;
+
+			// Call the onEnter hook
+			try {
+				const handler = hookConfig.onEnter(done);
+
+				// Store abort/complete handlers if provided
+				if (handler && typeof handler === 'object') {
+					if (handler.abort || handler.complete) {
+						this.#currentOnEnterHandler = {
+							abort: handler.abort,
+							complete: handler.complete
+						};
+					}
+				}
+
+				// If hook returned a promise, await it
+				if (handler?.then) {
+					await handler;
+				}
+			} catch (error) {
+				console.error(`Error in onEnter hook for state ${newState}:`, error);
+			}
+		}
+
+		this.#isTransitioning = false;
+		this.#revision++;
 	}
 
 	/**
@@ -334,4 +460,78 @@ export default class PageMachine {
 		this.#visitedStates.add(this.#current);
 		this.#revision++;
 	}
+
+	/* ===== Transition Control Methods ===== */
+
+	/**
+	 * Abort current state's transitions
+	 * Cancels animations/operations immediately (incomplete state)
+	 *
+	 * @example
+	 * ```javascript
+	 * // User clicks "Cancel" button
+	 * machine.abortTransitions();
+	 * ```
+	 */
+	abortTransitions() {
+		if (this.#currentOnEnterHandler?.abort) {
+			this.#currentOnEnterHandler.abort();
+			this.#currentOnEnterHandler = null;
+			this.#currentOnEnterDone = null;
+			this.#revision++;
+		}
+	}
+
+	/**
+	 * Complete current state's transitions immediately
+	 * Fast-forwards animations/operations to completion (complete state)
+	 *
+	 * @example
+	 * ```javascript
+	 * // User clicks "Skip" or "Next" button
+	 * machine.completeTransitions();
+	 * ```
+	 */
+	completeTransitions() {
+		if (this.#currentOnEnterHandler?.complete) {
+			this.#currentOnEnterHandler.complete();
+			this.#currentOnEnterHandler = null;
+			this.#currentOnEnterDone = null;
+			this.#revision++;
+		}
+	}
+
+	/**
+	 * Check if current state has transitions that can be completed
+	 *
+	 * @returns {boolean} True if completeTransitions() can be called
+	 *
+	 * @example
+	 * ```svelte
+	 * {#if machine.canCompleteTransitions}
+	 *   <button onclick={() => machine.completeTransitions()}>Skip</button>
+	 * {/if}
+	 * ```
+	 */
+	get canCompleteTransitions() {
+		this.#revision; // Ensure reactivity
+		return !!this.#currentOnEnterHandler?.complete;
+	}
+
+	/**
+	 * Check if current state has transitions that can be aborted
+	 *
+	 * @returns {boolean} True if abortTransitions() can be called
+	 *
+	 * @example
+	 * ```svelte
+	 * {#if machine.canAbortTransitions}
+	 *   <button onclick={() => machine.abortTransitions()}>Cancel</button>
+	 * {/if}
+	 * ```
+	 */
+	get canAbortTransitions() {
+		this.#revision; // Ensure reactivity
+		return !!this.#currentOnEnterHandler?.abort;
+	}
 }

package/dist/ui/components/game-box/ScaledContainer.svelte

@@ -1,5 +1,5 @@
 <script>
-  import { clamp, enableContainerScaling } from '../../../design/index.js';
+  import { enableContainerScaling } from '../../../design/index.js';
 
   /**
    * Wrapper component that applies container scaling to its children

package/dist/util/time/index.js

@@ -185,12 +185,16 @@ export function getWeekNumber(dateOrTimestamp) {
 	//
 	// Create a copy of this date object
 	//
-	const target = new Date(date.valueOf());
+	const target = new Date(Date.UTC(
+		date.getUTCFullYear(),
+		date.getUTCMonth(),
+		date.getUTCDate()
+	));
 
 	//
 	// ISO week date weeks start on Monday, so correct the day number
 	//
-	const dayNumber = (date.getDay() + 6) % 7;
+	const dayNumber = (date.getUTCDay() + 6) % 7;
 
 	//
 	// ISO 8601 states that week 1 is the week with the first Thursday
@@ -198,22 +202,29 @@ export function getWeekNumber(dateOrTimestamp) {
 	//
 	// Set the target date to the Thursday in the target week
 	//
-	target.setDate(target.getDate() - dayNumber + 3);
+	target.setUTCDate(target.getUTCDate() - dayNumber + 3);
 
 	//
 	// Store the millisecond value of the target date
 	//
 	const firstThursday = target.valueOf();
 
-	// Set the target to the first Thursday of the year
-	// First, set the target to January 1st
-	target.setMonth(0, 1);
+	//
+	// Get the year of the Thursday in the target week
+	// (This is important for dates near year boundaries)
+	//
+	const yearOfThursday = target.getUTCFullYear();
+
+	// Set the target to the first Thursday of that year
+	// First, set the target to January 1st of that year
+	target.setUTCFullYear(yearOfThursday);
+	target.setUTCMonth(0, 1);
 
 	//
 	// Not a Thursday? Correct the date to the next Thursday
 	//
-	if (target.getDay() !== 4) {
-		target.setMonth(0, 1 + ((4 - target.getDay() + 7) % 7));
+	if (target.getUTCDay() !== 4) {
+		target.setUTCMonth(0, 1 + ((4 - target.getUTCDay() + 7) % 7));
 	}
 
 	//

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.5.45",
+	"version": "0.5.46",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"