@hkdigital/lib-core 0.5.51 → 0.5.53

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

@@ -1,61 +1,3 @@
-/**
- * Base class for page state machines with URL route mapping
- *
- * Simple state tracker that maps states to URL routes.
- * Does NOT enforce FSM transitions - allows free navigation
- * (because users can navigate to any URL via browser).
- *
- * Features:
- * - State-to-route mapping and sync
- * - Start path management
- * - Data properties for business/domain state
- * - Visited states tracking
- * - onEnter hooks with abort/complete handlers for animations
- *
- * Basic usage:
- * ```javascript
- * const machine = new PageMachine({
- *   startPath: '/intro/start',
- *   routeMap: {
- *     [STATE_START]: '/intro/start',
- *     [STATE_PROFILE]: '/intro/profile'
- *   }
- * });
- *
- * // Sync machine state with URL changes
- * $effect(() => {
- *   machine.syncFromPath($page.url.pathname);
- * });
- * ```
- *
- * With onEnter hooks (for animations):
- * ```javascript
- * const machine = new PageMachine({
- *   startPath: '/game/animate',
- *   routeMap: {
- *     [STATE_ANIMATE]: '/game/animate',
- *     [STATE_PLAY]: '/game/play'
- *   },
- *   onEnterHooks: {
- *     [STATE_ANIMATE]: (done) => {
- *       const animation = playAnimation(1000);
- *       animation.finished.then(() => done(STATE_PLAY));
- *
- *       return {
- *         abort: () => animation.cancel(),
- *         complete: () => animation.finish()
- *       };
- *     }
- *   }
- * });
- *
- * // Fast-forward animation
- * machine.completeTransitions();
- *
- * // Cancel animation
- * machine.abortTransitions();
- * ```
- */
 export default class PageMachine {
     /**
      * Constructor
@@ -111,7 +53,7 @@ export default class PageMachine {
      * Synchronize machine state with URL path
      *
      * Call this in a $effect that watches $page.url.pathname
-     * Automatically tracks visited states
+     * Automatically tracks visited states and triggers onEnter hooks
      *
      * @param {string} currentPath - Current URL pathname
      *
@@ -119,20 +61,19 @@ export default class PageMachine {
      */
     syncFromPath(currentPath: string): boolean;
     /**
-     * Set the current state directly
-     * Handles onEnter hooks and auto-transitions
+     * Get route path for a given state
+     *
+     * @param {string} state - State name
      *
-     * @param {string} newState - Target state
+     * @returns {string} Route path or null if no mapping
      */
-    setState(newState: string): Promise<void>;
+    getPathForState(state: string): string;
     /**
-     * Get route path for a given state
+     * Navigate to the route path for a given state
      *
      * @param {string} state - State name
-     *
-     * @returns {string|null} Route path or null if no mapping
      */
-    getPathForState(state: string): string | null;
+    navigateToState(state: string): void;
     /**
      * Get route path for current state
      *

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

@@ -56,6 +56,8 @@
  * machine.abortTransitions();
  * ```
  */
+import { switchToPage } from '../../../util/sveltekit.js';
+
 export default class PageMachine {
 	/**
 	 * Logger instance for state machine
@@ -241,7 +243,7 @@ export default class PageMachine {
 	 * Synchronize machine state with URL path
 	 *
 	 * Call this in a $effect that watches $page.url.pathname
-	 * Automatically tracks visited states
+	 * Automatically tracks visited states and triggers onEnter hooks
 	 *
 	 * @param {string} currentPath - Current URL pathname
 	 *
@@ -251,13 +253,13 @@ export default class PageMachine {
 		const targetState = this.#getStateFromPath(currentPath);
 
 		if (targetState && targetState !== this.#current) {
-			// const oldState = this.#current;
-			this.#current = targetState;
-			this.#visitedStates.add(targetState);
-			this.#revision++;
-
 			// Log state transition from URL sync
-			this.logger?.debug(`syncFromPath: ${currentPath} → targetState: ${targetState}`);
+			this.logger?.debug(
+				`syncFromPath: ${currentPath} → targetState: ${targetState}`
+			);
+
+			// Use #setState to handle onEnter hooks
+			this.#setState(targetState);
 
 			return true;
 		}
@@ -266,12 +268,16 @@ export default class PageMachine {
 	}
 
 	/**
-	 * Set the current state directly
+	 * Set the current state directly (internal use only)
 	 * Handles onEnter hooks and auto-transitions
 	 *
+	 * Note: This is private to enforce URL-first navigation.
+	 * To change state, navigate to the URL using switchToPage()
+	 * and let syncFromPath() update the state.
+	 *
 	 * @param {string} newState - Target state
 	 */
-	async setState(newState) {
+	async #setState(newState) {
 		if (newState === this.#current || this.#isTransitioning) {
 			return;
 		}
@@ -297,11 +303,11 @@ export default class PageMachine {
 			// Create done callback for auto-transition
 			let doneCalled = false;
 
-			const done = ( /** @type {string} */ nextState) => {
+			const done = (/** @type {string} */ nextState) => {
 				if (!doneCalled && nextState && nextState !== newState) {
 					doneCalled = true;
 					this.#isTransitioning = false;
-					this.setState(nextState);
+					this.#setState(nextState);
 				}
 			};
 
@@ -363,10 +369,26 @@ export default class PageMachine {
 	 *
 	 * @param {string} state - State name
 	 *
-	 * @returns {string|null} Route path or null if no mapping
+	 * @returns {string} Route path or null if no mapping
 	 */
 	getPathForState(state) {
-		return this.#routeMap[state] || null;
+		const path = this.#routeMap[state];
+
+		if (!path) {
+			throw new Error(`No path found for state [${state}]`);
+		}
+
+		return path;
+	}
+
+	/**
+	 * Navigate to the route path for a given state
+	 *
+	 * @param {string} state - State name
+	 */
+	navigateToState(state) {
+		const path = this.getPathForState(state);
+		switchToPage(path);
 	}
 
 	/**

package/package.json

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