@hkdigital/lib-core 0.5.44 → 0.5.46

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

@@ -0,0 +1,537 @@
+/**
+ * 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
+ * - Data properties for business/domain state
+ * - Visited states tracking
+ * - onEnter hooks with abort/complete handlers for animations
+ *
+ * Basic usage:
+ * ```javascript
+ * const machine = new PageMachine({
+ *   initialState: STATE_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({
+ *   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));
+ *
+ *       return {
+ *         abort: () => animation.cancel(),
+ *         complete: () => animation.finish()
+ *       };
+ *     }
+ *   }
+ * });
+ *
+ * // Fast-forward animation
+ * machine.completeTransitions();
+ *
+ * // Cancel animation
+ * machine.abortTransitions();
+ * ```
+ */
+export default class PageMachine {
+	/**
+	 * Current state
+	 * @type {string}
+	 */
+	// @ts-ignore
+	#current = $state();
+
+	/**
+	 * Map of states to route paths
+	 * @type {Record<string, string>}
+	 */
+	#routeMap = {};
+
+	/**
+	 * Reverse map of route paths to states
+	 * @type {Record<string, string>}
+	 */
+	#pathToStateMap = {};
+
+	/**
+	 * Data properties for business/domain state
+	 * Can be initialized from server and synced back
+	 * @type {Record<string, any>}
+	 */
+	#data = $state({});
+
+	/**
+	 * Track which states have been visited during this session
+	 * Useful for showing first-time hints/tips
+	 * @type {Set<string>}
+	 */
+	// eslint-disable-next-line svelte/prefer-svelte-reactivity
+	#visitedStates = new Set();
+
+	/**
+	 * Revision counter for triggering reactivity
+	 * @type {number}
+	 */
+	#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 {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 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 = {}, 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)) {
+			this.#pathToStateMap[path] = state;
+		}
+
+		// Mark initial state as visited
+		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
+	 *
+	 * Call this in a $effect that watches $page.url.pathname
+	 * Automatically tracks visited states
+	 *
+	 * @param {string} currentPath - Current URL pathname
+	 *
+	 * @returns {boolean} True if state was changed
+	 */
+	syncFromPath(currentPath) {
+		const targetState = this.#getStateFromPath(currentPath);
+
+		if (targetState && targetState !== this.#current) {
+			this.#current = targetState;
+			this.#visitedStates.add(targetState);
+			this.#revision++;
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Set the current state directly
+	 * Handles onEnter hooks and auto-transitions
+	 *
+	 * @param {string} newState - Target state
+	 */
+	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++;
+	}
+
+	/**
+	 * Get state name from URL path
+	 *
+	 * @param {string} path - URL pathname
+	 *
+	 * @returns {string|null} State name or null
+	 */
+	#getStateFromPath(path) {
+		// Try exact match first
+		if (this.#pathToStateMap[path]) {
+			return this.#pathToStateMap[path];
+		}
+
+		// Try partial match (path includes route)
+		for (const [routePath, state] of Object.entries(this.#pathToStateMap)) {
+			if (path.includes(routePath)) {
+				return state;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Get route path for a given state
+	 *
+	 * @param {string} state - State name
+	 *
+	 * @returns {string|null} Route path or null if no mapping
+	 */
+	getPathForState(state) {
+		return this.#routeMap[state] || null;
+	}
+
+	/**
+	 * Get route path for current state
+	 *
+	 * @returns {string|null} Route path or null if no mapping
+	 */
+	getCurrentPath() {
+		return this.getPathForState(this.#current);
+	}
+
+	/**
+	 * Get current state
+	 *
+	 * @returns {string} Current state name
+	 */
+	get current() {
+		return this.#current;
+	}
+
+	/**
+	 * Get the route map
+	 *
+	 * @returns {Record<string, string>} Copy of route map
+	 */
+	get routeMap() {
+		return { ...this.#routeMap };
+	}
+
+	/* ===== Data Properties (Business/Domain State) ===== */
+
+	/**
+	 * Set a data property value
+	 *
+	 * @param {string} key - Property key
+	 * @param {any} value - Property value
+	 *
+	 * @example
+	 * ```javascript
+	 * machine.setData('HAS_STRONG_PROFILE', true);
+	 * machine.setData('PROFILE_SCORE', 85);
+	 * ```
+	 */
+	setData(key, value) {
+		this.#data[key] = value;
+		this.#revision++;
+	}
+
+	/**
+	 * Get a data property value
+	 *
+	 * @param {string} key - Property key
+	 *
+	 * @returns {any} Property value or undefined
+	 *
+	 * @example
+	 * ```javascript
+	 * const hasProfile = machine.getData('HAS_STRONG_PROFILE');
+	 * const score = machine.getData('PROFILE_SCORE');
+	 * ```
+	 */
+	getData(key) {
+		// Access revision to ensure reactivity
+		this.#revision;
+		return this.#data[key];
+	}
+
+	/**
+	 * Get all data properties
+	 *
+	 * @returns {Record<string, any>} Copy of all data
+	 *
+	 * @example
+	 * ```javascript
+	 * const allData = machine.getAllData();
+	 * await playerService.saveData(allData);
+	 * ```
+	 */
+	getAllData() {
+		// Access revision to ensure reactivity
+		this.#revision;
+		return { ...this.#data };
+	}
+
+	/**
+	 * Update multiple data properties at once
+	 *
+	 * @param {Record<string, any>} dataUpdates - Object with key-value pairs
+	 *
+	 * @example
+	 * ```javascript
+	 * machine.updateData({
+	 *   HAS_STRONG_PROFILE: true,
+	 *   PROFILE_SCORE: 85,
+	 *   MATCHED_SECTOR: 'technology'
+	 * });
+	 * ```
+	 */
+	updateData(dataUpdates) {
+		for (const [key, value] of Object.entries(dataUpdates)) {
+			this.#data[key] = value;
+		}
+		this.#revision++;
+	}
+
+	/* ===== Visited States Tracking ===== */
+
+	/**
+	 * Check if a state has been visited
+	 *
+	 * @param {string} state - State name to check
+	 *
+	 * @returns {boolean} True if the state has been visited
+	 *
+	 * @example
+	 * ```javascript
+	 * if (machine.hasVisited(STATE_PROFILE)) {
+	 *   // User has seen profile page, skip intro
+	 * }
+	 * ```
+	 */
+	hasVisited(state) {
+		// Access revision to ensure reactivity
+		this.#revision;
+		return this.#visitedStates.has(state);
+	}
+
+	/**
+	 * Get all visited states
+	 *
+	 * @returns {string[]} Array of visited state names
+	 */
+	getVisitedStates() {
+		// Access revision to ensure reactivity
+		this.#revision;
+		return Array.from(this.#visitedStates);
+	}
+
+	/**
+	 * Reset visited states tracking
+	 * Useful for testing or resetting experience
+	 */
+	resetVisitedStates() {
+		this.#visitedStates.clear();
+		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/state/machines/page-machine/README.md

@@ -0,0 +1,157 @@
+# PageMachine
+
+State machine for managing page view states with URL route mapping.
+
+## How it connects
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ MyFlowPageMachine (extends PageMachine)                 │
+│ - Maps states to URL routes                             │
+│ - Tracks current state and visited states               │
+│ - Provides computed properties (inIntro, inStep1, etc.) │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Contained in state
+                 │
+┌────────────────▼────────────────────────────────────────┐
+│ MyFlowState (extends RouteStateContext)                 │
+│ get pageMachine() { return this.#pageMachine; }         │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Context provided to layout
+                 │
+┌────────────────▼────────────────────────────────────────┐
+│ +layout.svelte                                          │
+│ IMPORTANT: Must sync URL with state:                    │
+│   $effect(() => {                                       │
+│     pageMachine.syncFromPath($page.url.pathname);       │
+│   });                                                   │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Pages use machine state
+                 │
+        ┌────────┴─────────┬────────────────┐
+        ▼                  ▼                ▼
+  ┌──────────┐      ┌──────────┐    ┌──────────┐
+  │ +page    │      │ +page    │    │ Component│
+  │          │      │          │    │          │
+  └──────────┘      └──────────┘    └──────────┘
+  Access via: pageMachine.current, pageMachine.inIntro, etc.
+```
+
+## Main Purposes
+
+1. **Track current view/step** - Which page is active
+2. **Map states to URL paths** - Connect state names to routes
+3. **Sync with browser navigation** - Keep state in sync with URL
+4. **Track visited states** - Know which pages user has seen
+
+## Basic Usage
+
+### 1. Create a page machine class
+
+```javascript
+// my-flow.machine.svelte.js
+import PageMachine from '$lib/state/machines/PageMachine.svelte.js';
+
+export const STATE_INTRO = 'intro';
+export const STATE_STEP1 = 'step1';
+export const STATE_STEP2 = 'step2';
+
+export default class MyFlowPageMachine extends PageMachine {
+  constructor(initialData = {}) {
+    const routeMap = {
+      [STATE_INTRO]: '/my-flow/intro',
+      [STATE_STEP1]: '/my-flow/step1',
+      [STATE_STEP2]: '/my-flow/step2'
+    };
+
+    super(STATE_INTRO, routeMap, initialData);
+  }
+
+  // Computed properties for convenience
+  get inIntro() {
+    return this.current === STATE_INTRO;
+  }
+
+  get inStep1() {
+    return this.current === STATE_STEP1;
+  }
+}
+```
+
+### 2. Use in state container
+
+```javascript
+// my-flow.state.svelte.js
+import { RouteStateContext } from '$lib/state/context.js';
+import MyFlowPageMachine from './my-flow.machine.svelte.js';
+
+export class MyFlowState extends RouteStateContext {
+  #pageMachine;
+
+  constructor() {
+    super();
+    this.#pageMachine = new MyFlowPageMachine();
+  }
+
+  get pageMachine() {
+    return this.#pageMachine;
+  }
+}
+```
+
+### 3. Sync with route in +layout.svelte component
+
+**This is IMPORTANT for url path to be connected to the page machine**
+
+```svelte
+<script>
+  import { page } from '$app/stores';
+  import { getMyFlowState } from '../my-flow.state.svelte.js';
+
+  const flowState = getMyFlowState();
+  const pageMachine = flowState.pageMachine;
+
+  // Sync machine with URL changes
+  $effect(() => {
+    pageMachine.syncFromPath($page.url.pathname);
+  });
+</script>
+
+{#if pageMachine.inIntro}
+  <IntroView />
+{:else if pageMachine.inStep1}
+  <Step1View />
+{/if}
+```
+
+## Key Methods
+
+```javascript
+// Sync with URL path
+machine.syncFromPath(currentPath)
+
+// Get current state
+machine.current
+
+// Get route for state
+machine.getPathForState(stateName)
+
+// Data properties (for business logic)
+machine.setData('KEY', value)
+machine.getData('KEY')
+
+// Visited states tracking
+machine.hasVisited(stateName)
+machine.getVisitedStates()
+```
+
+## Important Notes
+
+- Not a finite state machine - allows free navigation
+- States map 1:1 with routes
+- Use state constants instead of magic strings
+- Always sync in `$effect` watching `$page.url.pathname`
+- Data properties are for business logic, not UI state

package/dist/state/machines.d.ts

@@ -1,2 +1,3 @@
 export * from "./machines/finite-state-machine/index.js";
 export * from "./machines/loading-state-machine/index.js";
+export { default as PageMachine } from "./machines/page-machine/PageMachine.svelte.js";

package/dist/state/machines.js

@@ -1,2 +1,4 @@
 export * from './machines/finite-state-machine/index.js';
 export * from './machines/loading-state-machine/index.js';
+
+export { default as PageMachine } from './machines/page-machine/PageMachine.svelte.js';

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