@hkdigital/lib-core 0.5.45 → 0.5.47

package/dist/state/machines/page-machine/README.md

@@ -6,17 +6,13 @@ State machine for managing page view states with URL route mapping.
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│ MyFlowPageMachine (extends PageMachine)                 │
+│ PuzzleState (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; }         │
+│ - Manages start path and navigation                     │
+│ - Provides computed properties (inIntro, inLevel1, etc.)│
+│ - Contains GameLogic for reactive game state            │
+│ - Optional: services, preload, reset, etc.              │
 └────────────────┬────────────────────────────────────────┘
                  │
                  │ Context provided to layout
@@ -25,11 +21,11 @@ State machine for managing page view states with URL route mapping.
 │ +layout.svelte                                          │
 │ IMPORTANT: Must sync URL with state:                    │
 │   $effect(() => {                                       │
-│     pageMachine.syncFromPath($page.url.pathname);       │
+│     puzzleState.syncFromPath($page.url.pathname);       │
 │   });                                                   │
 └────────────────┬────────────────────────────────────────┘
                  │
-                 │ Pages use machine state
+                 │ Pages use state directly
                  │
         ┌────────┴─────────┬────────────────┐
         ▼                  ▼                ▼
@@ -37,37 +33,71 @@ State machine for managing page view states with URL route mapping.
   │ +page    │      │ +page    │    │ Component│
   │          │      │          │    │          │
   └──────────┘      └──────────┘    └──────────┘
-  Access via: pageMachine.current, pageMachine.inIntro, etc.
+  Access via: puzzleState.current, puzzleState.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
+3. **Manage start path** - Define and navigate to the entry point
+4. **Sync with browser navigation** - Keep state in sync with URL
+5. **Track visited states** - Know which pages user has seen
 
 ## Basic Usage
 
-### 1. Create a page machine class
+### 1. Define state constants
+
+```javascript
+// puzzle.constants.js
+export const STATE_INTRO = 'intro';
+export const STATE_TUTORIAL = 'tutorial';
+export const STATE_LEVEL1 = 'level1';
+export const STATE_LEVEL2 = 'level2';
+export const STATE_COMPLETE = 'complete';
+```
+
+### 2. Create state class (extends PageMachine)
 
 ```javascript
-// my-flow.machine.svelte.js
+// puzzle.state.svelte.js
+import { defineStateContext } from '@hkdigital/lib-core/state/context.js';
 import PageMachine from '$lib/state/machines/PageMachine.svelte.js';
+import PuzzleGameLogic from './puzzle.game-logic.svelte.js';
+import {
+  STATE_INTRO,
+  STATE_TUTORIAL,
+  STATE_LEVEL1,
+  STATE_LEVEL2,
+  STATE_COMPLETE
+} from './puzzle.constants.js';
+
+// Data keys for persistent data
+const KEY_TUTORIAL_SEEN = 'tutorial-seen';
+const KEY_HIGHEST_LEVEL = 'highest-level';
+const KEY_DIFFICULTY = 'difficulty';
+
+export class PuzzleState extends PageMachine {
+  #gameLogic;
 
-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);
+  constructor() {
+    // Call PageMachine constructor with route config
+    super({
+      startPath: '/puzzle/intro',
+      routeMap: {
+        [STATE_INTRO]: '/puzzle/intro',
+        [STATE_TUTORIAL]: '/puzzle/tutorial',
+        [STATE_LEVEL1]: '/puzzle/level1',
+        [STATE_LEVEL2]: '/puzzle/level2',
+        [STATE_COMPLETE]: '/puzzle/complete'
+      }
+    });
+
+    this.#gameLogic = new PuzzleGameLogic();
+  }
+
+  get gameLogic() {
+    return this.#gameLogic;
   }
 
   // Computed properties for convenience
@@ -75,31 +105,63 @@ export default class MyFlowPageMachine extends PageMachine {
     return this.current === STATE_INTRO;
   }
 
-  get inStep1() {
-    return this.current === STATE_STEP1;
+  get inTutorial() {
+    return this.current === STATE_TUTORIAL;
   }
-}
-```
 
-### 2. Use in state container
+  get inLevel1() {
+    return this.current === STATE_LEVEL1;
+  }
 
-```javascript
-// my-flow.state.svelte.js
-import { RouteStateContext } from '$lib/state/context.js';
-import MyFlowPageMachine from './my-flow.machine.svelte.js';
+  get inLevel2() {
+    return this.current === STATE_LEVEL2;
+  }
 
-export class MyFlowState extends RouteStateContext {
-  #pageMachine;
+  get isComplete() {
+    return this.current === STATE_COMPLETE;
+  }
 
-  constructor() {
-    super();
-    this.#pageMachine = new MyFlowPageMachine();
+  // Persistent settings/progress (use getData/setData)
+  get hasSeenTutorial() {
+    return this.getData(KEY_TUTORIAL_SEEN) || false;
+  }
+
+  markTutorialComplete() {
+    this.setData(KEY_TUTORIAL_SEEN, true);
+  }
+
+  get highestLevel() {
+    return this.getData(KEY_HIGHEST_LEVEL) || 1;
+  }
+
+  updateHighestLevel(level) {
+    const current = this.highestLevel;
+    if (level > current) {
+      this.setData(KEY_HIGHEST_LEVEL, level);
+    }
+  }
+
+  get difficulty() {
+    return this.getData(KEY_DIFFICULTY) || 'normal';
   }
 
-  get pageMachine() {
-    return this.#pageMachine;
+  setDifficulty(level) {
+    this.setData(KEY_DIFFICULTY, level);
+  }
+
+  // Optional: Lifecycle methods
+  preload(onProgress) {
+    return loadPuzzleAssets(onProgress);
+  }
+
+  reset() {
+    this.#gameLogic = new PuzzleGameLogic();
   }
 }
+
+// Export context helpers
+export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
+  defineStateContext(PuzzleState);
 ```
 
 ### 3. Sync with route in +layout.svelte component
@@ -109,43 +171,126 @@ export class MyFlowState extends RouteStateContext {
 ```svelte
 <script>
   import { page } from '$app/stores';
-  import { getMyFlowState } from '../my-flow.state.svelte.js';
+  import { createOrGetPuzzleState } from '../puzzle.state.svelte.js';
+
+  const puzzleState = createOrGetPuzzleState();
 
-  const flowState = getMyFlowState();
-  const pageMachine = flowState.pageMachine;
+  // Sync state with URL changes
+  $effect(() => {
+    puzzleState.syncFromPath($page.url.pathname);
+  });
 
-  // Sync machine with URL changes
+  // Optional: Enforce that users must visit intro before playing
   $effect(() => {
-    pageMachine.syncFromPath($page.url.pathname);
+    const currentPath = $page.url.pathname;
+
+    if (!puzzleState.isStartPath(currentPath) &&
+        currentPath.startsWith('/puzzle') &&
+        !puzzleState.hasVisited('intro')) {
+      puzzleState.redirectToStartPath();
+    }
+  });
+
+  // Optional: Preload assets
+  puzzleState.preload((progress) => {
+    console.log('Loading:', progress);
   });
 </script>
 
-{#if pageMachine.inIntro}
-  <IntroView />
-{:else if pageMachine.inStep1}
-  <Step1View />
+{#if puzzleState.inIntro}
+  <IntroView onComplete={() => puzzleState.markTutorialComplete()} />
+{:else if puzzleState.inTutorial}
+  <TutorialView />
+{:else if puzzleState.inLevel1}
+  <Level1View gameLogic={puzzleState.gameLogic} />
+{:else if puzzleState.inLevel2}
+  <Level2View gameLogic={puzzleState.gameLogic} />
+{:else if puzzleState.isComplete}
+  <CompleteView
+    score={puzzleState.gameLogic.score}
+    highestLevel={puzzleState.highestLevel} />
 {/if}
 ```
 
 ## Key Methods
 
+All PageMachine methods are directly available on your state class:
+
 ```javascript
 // Sync with URL path
-machine.syncFromPath(currentPath)
+puzzleState.syncFromPath(currentPath)
 
 // Get current state
-machine.current
+puzzleState.current
+
+// Start path management
+puzzleState.startPath                 // Get start path
+puzzleState.startState                // Get start state
+puzzleState.isStartPath(path)         // Check if path is start path
+puzzleState.isOnStartState            // Check if on start state
+puzzleState.redirectToStartPath()     // Navigate to start path
 
 // Get route for state
-machine.getPathForState(stateName)
+puzzleState.getPathForState(stateName)
 
-// Data properties (for business logic)
-machine.setData('KEY', value)
-machine.getData('KEY')
+// Persistent data properties
+puzzleState.setData(KEY_NAME, value)
+puzzleState.getData(KEY_NAME)
 
 // Visited states tracking
-machine.hasVisited(stateName)
-machine.getVisitedStates()
+puzzleState.hasVisited(stateName)
+puzzleState.getVisitedStates()
+
+// Custom computed properties (from your class)
+puzzleState.inIntro
+puzzleState.inLevel1
+puzzleState.hasSeenTutorial
+```
+
+## Data Storage Guidelines
+
+### When to use `getData/setData` (PageMachine)
+
+Use PageMachine's data properties for **persistent settings and progress**:
+
+- ✅ Tutorial completion flags
+- ✅ User preferences (difficulty, language, sound)
+- ✅ Progress tracking (highest level reached)
+- ✅ Settings that survive page navigation
+- ✅ Data that might be saved to server
+
+```javascript
+const KEY_TUTORIAL_SEEN = 'tutorial-seen';
+const KEY_DIFFICULTY = 'difficulty';
+const KEY_HIGHEST_LEVEL = 'highest-level';
+
+// Persistent data
+pageMachine.setData(KEY_TUTORIAL_SEEN, true);
+pageMachine.setData(KEY_DIFFICULTY, 'hard');
+pageMachine.setData(KEY_HIGHEST_LEVEL, 5);
+```
+
+### When to use GameLogic with `$state`
+
+Use a separate GameLogic class with `$state` fields for **reactive game state**:
+
+- ✅ Live scores, lives, health
+- ✅ Current player, selected items
+- ✅ Complex objects (cards, inventory, enemies)
+- ✅ Temporary turn/round state
+- ✅ Reactive UI state that changes frequently
+
+```javascript
+// puzzle.game-logic.svelte.js
+export class PuzzleGameLogic {
+  #score = $state(0);
+  #lives = $state(3);
+  #selectedCards = $state([]);
+  #currentPuzzle = $state(null);
+
+  get score() { return this.#score; }
+  incrementScore(points) { this.#score += points; }
+}
 ```
 
 ## Important Notes
@@ -154,4 +299,5 @@ machine.getVisitedStates()
 - 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
+- Use constants for data keys (e.g., `KEY_TUTORIAL_SEEN = 'tutorial-seen'`)
+- Separate persistent data (PageMachine) from reactive game state (GameLogic)

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

@@ -461,6 +461,7 @@
 
 {#if gameHeight}
   <div
+    data-about="game-box-centering"
     class:center
     style:height={center ? `${iosWindowHeight ?? windowHeight}px` : undefined}
   >

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
@@ -60,6 +60,7 @@
 
 {#if snippet && snippetParams}
   <div
+    data-component="scaled-container"
     bind:this={container}
     class:hidden
     style:width="{width}px"

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

@@ -0,0 +1,7 @@
+/**
+ * Navigate to an internal path
+ * - Replaces the current url
+ *
+ * @param {string} path - Pathname to navigate to
+ */
+export function switchToPage(path: string): void;

package/dist/util/sveltekit/navigation.js

@@ -0,0 +1,12 @@
+import { goto } from '$app/navigation';
+
+/**
+ * Navigate to an internal path
+ * - Replaces the current url
+ *
+ * @param {string} path - Pathname to navigate to
+ */
+export function switchToPage( path ) {
+  // eslint-disable-next-line svelte/no-navigation-without-resolve
+  goto( path, { replaceState: true } );
+}

package/dist/util/sveltekit.d.ts

@@ -0,0 +1 @@
+export * from "./sveltekit/navigation.js";

package/dist/util/sveltekit.js

@@ -0,0 +1 @@
+export * from './sveltekit/navigation.js';

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.47",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"

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

@@ -1,44 +0,0 @@
-/**
- * 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

@@ -1,119 +0,0 @@
-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 });
-		}
-	}
-}