@hkdigital/lib-core 0.5.44 → 0.5.46

package/dist/state/context/README.md

@@ -0,0 +1,226 @@
+# RouteStateContext
+
+Base class for route-level state containers.
+
+## How it connects
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ PuzzleState (extends RouteStateContext)                 │
+│ - Container for route-level concerns                    │
+│ - Contains PageMachine instance                         │
+│ - Optional: services, preload, reset, etc.              │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Provided via Svelte context
+                 │
+┌────────────────▼────────────────────────────────────────┐
+│ +layout.svelte                                          │
+│ - Creates state with createOrGetPuzzleState()           │
+│ - IMPORTANT: Syncs URL with pageMachine.syncFromPath()  │
+│ - Optional: Calls validateAndRedirect() for protection  │
+└────────────────┬────────────────────────────────────────┘
+                 │
+                 │ Context available to children
+                 │
+        ┌────────┴─────────┬────────────────┐
+        ▼                  ▼                ▼
+  ┌──────────┐      ┌──────────┐    ┌──────────┐
+  │ +page    │      │ +page    │    │ Component│
+  │ .svelte  │      │ .svelte  │    │          │
+  └──────────┘      └──────────┘    └──────────┘
+  Gets state via getPuzzleState()
+```
+
+## Main Purposes
+
+1. **State container** - Hold route-level concerns in one place
+2. **Apply enforceStartPath** - Control navigation flow (users must visit
+   start path before accessing subroutes)
+3. **Provide validateAndRedirect** - Route protection via layout
+
+## Key Features
+
+- Share state between layout and pages without prop drilling
+- Persist state across navigation within the same route group
+- Lifecycle methods for setup/teardown (preload, reset)
+
+## Basic Usage
+
+### 1. Create state container class
+
+```javascript
+// routes/puzzle/puzzle.state.svelte.js
+import { defineStateContext } from '@hkdigital/lib-core/state/context.js';
+import { RouteStateContext } from '$lib/state/context.js';
+import PuzzlePageMachine from './puzzle.machine.svelte.js';
+
+export class PuzzleState extends RouteStateContext {
+  #pageMachine;
+
+  constructor() {
+    super({
+      startPath: '/puzzle',
+      enforceStartPath: true  // Optional: enforce route protection
+    });
+    this.#pageMachine = new PuzzlePageMachine();
+  }
+
+  get pageMachine() {
+    return this.#pageMachine;
+  }
+
+  // Optional: Service accessors
+  getPuzzleService() {
+    return getPuzzleService();
+  }
+
+  // Optional: Lifecycle methods
+  preload(onProgress) {
+    return loadPuzzleAssets(onProgress);
+  }
+
+  reset() {
+    // Reset state when needed
+  }
+}
+
+// Export helper functions
+export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
+  defineStateContext(PuzzleState);
+```
+
+### 2. Provide context in layout
+
+```svelte
+<!-- routes/puzzle/+layout.svelte -->
+<script>
+  import { page } from '$app/stores';
+  import { createOrGetPuzzleState } from './puzzle.state.svelte.js';
+
+  // Create or get existing state container
+  const puzzleState = createOrGetPuzzleState();
+
+  // IMPORTANT: Sync URL with PageMachine state
+  $effect(() => {
+    puzzleState.pageMachine.syncFromPath($page.url.pathname);
+  });
+
+  // Optional: Enforce start path (redirect if user skips intro)
+  $effect(() => {
+    puzzleState.validateAndRedirect($page.url.pathname);
+  });
+
+  // Optional: Preload assets
+  puzzleState.preload((progress) => {
+    console.log('Loading:', progress);
+  });
+</script>
+
+<slot />
+```
+
+### 3. Consume context in pages
+
+```svelte
+<!-- routes/puzzle/level1/+page.svelte -->
+<script>
+  import { getPuzzleState } from '../puzzle.state.svelte.js';
+
+  const puzzleState = getPuzzleState();
+  const pageMachine = puzzleState.pageMachine;
+</script>
+
+<div>Current state: {pageMachine.current}</div>
+```
+
+## Context Helpers
+
+The `defineStateContext` helper creates three functions:
+
+```javascript
+// Get existing or create new (use in layout)
+const state = createOrGetPuzzleState();
+
+// Force create new instance
+const state = createPuzzleState();
+
+// Get existing (throws if not found, use in pages/components)
+const state = getPuzzleState();
+```
+
+## Constructor Options
+
+```javascript
+constructor({ startPath, enforceStartPath })
+```
+
+- `startPath` **(required)** - The start path for this route
+  (e.g., `/puzzle`)
+- `enforceStartPath` **(optional, default: false)** - If true, users must
+  visit the start path before accessing subroutes
+
+## validateAndRedirect Method
+
+Automatically redirects users if they try to access subroutes before visiting
+the start path.
+
+**How it works:**
+- If `enforceStartPath: true` is set in constructor
+- User tries to access a subroute (e.g., `/puzzle/level2`)
+- But hasn't visited the start path yet (`/puzzle`)
+- → Automatically redirects to start path
+
+**Example use case:** Puzzle game where users must see the intro before
+accessing puzzle levels.
+
+```javascript
+// In state constructor
+export class PuzzleState extends RouteStateContext {
+  constructor() {
+    super({
+      startPath: '/puzzle',
+      enforceStartPath: true
+    });
+  }
+}
+```
+
+```svelte
+<!-- In +layout.svelte -->
+<script>
+  import { page } from '$app/stores';
+
+  const puzzleState = createOrGetPuzzleState();
+
+  // Enforce route protection
+  $effect(() => {
+    puzzleState.validateAndRedirect($page.url.pathname);
+  });
+</script>
+```
+
+**Result:** If user navigates directly to `/puzzle/level2`, they'll be
+redirected to `/puzzle` first. After visiting `/puzzle`, they can freely
+navigate to any subroute.
+
+**Custom redirect URL:**
+```javascript
+// Redirect to a different URL instead of startPath
+puzzleState.validateAndRedirect($page.url.pathname, '/puzzle/welcome');
+```
+
+## Separation of Concerns
+
+**State Container** = Route-level concerns (MULTIPLE responsibilities)
+- PageMachine instance
+- Game engines
+- Service accessors
+- Media preloading
+- Any other route-level concern
+
+**PageMachine** = Page/view state ONLY (SINGLE responsibility)
+- Current page state
+- Route mapping
+- Visited states
+- Computed properties for state checks

package/dist/state/context/RouteStateContext.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Base class for route state containers
+ *
+ * Main purposes:
+ * - Container for route-level concerns (PageMachine, services, engines)
+ * - Apply enforceStartPath to control navigation flow
+ * - Provide validateAndRedirect for route protection
+ *
+ * @example
+ * ```javascript
+ * export class PuzzleState extends RouteStateContext {
+ *   constructor() {
+ *     super({
+ *       startPath: '/puzzle',
+ *       enforceStartPath: true
+ *     });
+ *   }
+ *
+ *   preload(onProgress) {
+ *     return loadAudioAndVideoScenes(onProgress);
+ *   }
+ * }
+ * ```
+ */
+export default class RouteStateContext {
+    /**
+     * @param {Object} options - Configuration options
+     * @param {string} options.startPath - Start path for this route (required)
+     * @param {boolean} [options.enforceStartPath=false] - If true, redirect to start path before allowing subroutes
+     */
+    constructor({ startPath, enforceStartPath }: {
+        startPath: string;
+        enforceStartPath?: boolean | undefined;
+    });
+    /**
+     * Validate current path and redirect if needed
+     * Call this in a $effect in the layout
+     *
+     * @param {string} currentPath - Current URL pathname
+     * @param {string} [redirectUrl] - Optional redirect URL (defaults to startPath)
+     */
+    validateAndRedirect(currentPath: string, redirectUrl?: string): void;
+    #private;
+}

package/dist/state/context/RouteStateContext.svelte.js

@@ -0,0 +1,119 @@
+import { goto } from '$app/navigation';
+
+/**
+ * Base class for route state containers
+ *
+ * Main purposes:
+ * - Container for route-level concerns (PageMachine, services, engines)
+ * - Apply enforceStartPath to control navigation flow
+ * - Provide validateAndRedirect for route protection
+ *
+ * @example
+ * ```javascript
+ * export class PuzzleState extends RouteStateContext {
+ *   constructor() {
+ *     super({
+ *       startPath: '/puzzle',
+ *       enforceStartPath: true
+ *     });
+ *   }
+ *
+ *   preload(onProgress) {
+ *     return loadAudioAndVideoScenes(onProgress);
+ *   }
+ * }
+ * ```
+ */
+export default class RouteStateContext {
+	/**
+	 * Start path for this route
+	 * @type {string}
+	 */
+	#startPath;
+
+	/**
+	 * Whether to enforce that users visit start path before subroutes
+	 * @type {boolean}
+	 */
+	#enforceStartPath = false;
+
+	/**
+	 * Track which paths have been visited during this session
+	 * Used for enforceStartPath validation
+	 * @type {Set<string>}
+	 */
+	// eslint-disable-next-line svelte/prefer-svelte-reactivity
+	#visitedPaths = new Set();
+
+	/**
+	 * @param {Object} options - Configuration options
+	 * @param {string} options.startPath - Start path for this route (required)
+	 * @param {boolean} [options.enforceStartPath=false] - If true, redirect to start path before allowing subroutes
+	 */
+	constructor({ startPath, enforceStartPath = false }) {
+		if (!startPath) {
+			throw new Error(
+				'RouteStateContext requires startPath parameter'
+			);
+		}
+
+		this.#startPath = startPath;
+		this.#enforceStartPath = enforceStartPath;
+	}
+
+	/**
+	 * Determine if current path needs redirection
+	 * Private method - enforces sequential access to subroutes
+	 *
+	 * @param {string} currentPath - Current URL pathname
+	 *
+	 * @returns {string|null}
+	 *   Path to redirect to, or null if no redirect needed
+	 */
+	#determineRedirect(currentPath) {
+		// No enforcement configured
+		if (!this.#enforceStartPath) {
+			return null;
+		}
+
+		// Currently on the start path - mark as visited and allow
+		if (currentPath === this.#startPath) {
+			this.#visitedPaths.add(currentPath);
+			return null;
+		}
+
+		// On a subroute - check if start path was visited
+		if (currentPath.startsWith(this.#startPath + '/')) {
+			// Allow if user has visited the start path
+			if (this.#visitedPaths.has(this.#startPath)) {
+				return null;
+			}
+			// Redirect to start path if not visited yet
+			return this.#startPath;
+		}
+
+		// Path is valid (not a subroute)
+		return null;
+	}
+
+	/**
+	 * Validate current path and redirect if needed
+	 * Call this in a $effect in the layout
+	 *
+	 * @param {string} currentPath - Current URL pathname
+	 * @param {string} [redirectUrl] - Optional redirect URL (defaults to startPath)
+	 */
+	validateAndRedirect(currentPath, redirectUrl = null) {
+		const redirectPath = this.#determineRedirect(currentPath);
+
+		if (redirectPath && redirectPath !== currentPath) {
+			const targetPath = redirectUrl || redirectPath;
+
+			console.debug(
+				`[${this.constructor.name}] Redirecting: ${currentPath} → ${targetPath}`
+			);
+
+			goto(targetPath, { replaceState: true });
+		}
+	}
+}

package/dist/state/context.d.ts

@@ -1 +1,2 @@
-export { defineStateContext, DEFAULT_CONTEXT_KEY } from "./context/state-context.js";
+export { default as RouteStateContext } from "./context/RouteStateContext.svelte.js";
+export { defineStateContext, DEFAULT_CONTEXT_KEY } from "./context/util.js";

package/dist/state/context.js

@@ -1 +1,2 @@
-export { defineStateContext, DEFAULT_CONTEXT_KEY } from './context/state-context.js';
+export { default as RouteStateContext } from './context/RouteStateContext.svelte.js';
+export { defineStateContext, DEFAULT_CONTEXT_KEY } from './context/util.js';

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

@@ -0,0 +1,270 @@
+/**
+ * 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 {
+    /**
+     * 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 }: {
+        initialState: string;
+        routeMap?: Record<string, string> | undefined;
+        initialData?: Record<string, any> | undefined;
+        onEnterHooks?: Record<string, Function> | undefined;
+    });
+    /**
+     * 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: string): boolean;
+    /**
+     * Set the current state directly
+     * Handles onEnter hooks and auto-transitions
+     *
+     * @param {string} newState - Target state
+     */
+    setState(newState: string): Promise<void>;
+    /**
+     * Get 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;
+    /**
+     * Get route path for current state
+     *
+     * @returns {string|null} Route path or null if no mapping
+     */
+    getCurrentPath(): string | null;
+    /**
+     * Get current state
+     *
+     * @returns {string} Current state name
+     */
+    get current(): string;
+    /**
+     * Get the route map
+     *
+     * @returns {Record<string, string>} Copy of route map
+     */
+    get routeMap(): Record<string, string>;
+    /**
+     * 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: string, value: any): void;
+    /**
+     * 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: string): any;
+    /**
+     * Get all data properties
+     *
+     * @returns {Record<string, any>} Copy of all data
+     *
+     * @example
+     * ```javascript
+     * const allData = machine.getAllData();
+     * await playerService.saveData(allData);
+     * ```
+     */
+    getAllData(): Record<string, any>;
+    /**
+     * 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: Record<string, any>): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * Get all visited states
+     *
+     * @returns {string[]} Array of visited state names
+     */
+    getVisitedStates(): string[];
+    /**
+     * Reset visited states tracking
+     * 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;
+}