@hkdigital/lib-core 0.5.57 → 0.5.59

package/dist/logging/internal/logger/Logger.js

@@ -264,7 +264,7 @@ export default class Logger extends EventEmitter {
       ...this.#defaultContext
     };
 
-    const childName = `${this.name}>${name}`;
+    const childName = `${this.name}:${name}`;
 
     const child = new Logger(childName, level ?? this.level, context);
 

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

@@ -5,124 +5,113 @@ export default class PageMachine {
      * @param {Object} config - Configuration object
      * @param {string} config.startPath
      *   Start path for this route group (e.g., '/game/play')
-     * @param {Record<string, string>} [config.routeMap={}]
-     *   Map of states to route paths
+     * @param {string[]} [config.routes=[]]
+     *   Optional list of valid routes (for validation/dev tools)
      * @param {Record<string, any>} [config.initialData={}]
-     *   Initial data properties (from server)
-     * @param {Record<string, Function>} [config.onEnterHooks={}]
-     *   Map of states to onEnter hook functions
+     *   Initial data properties (use KEY_ constants for keys)
      * @param {import('../../../logging/client.js').Logger} [config.logger]
-     *   Logger instance (optional, if not provided no logging occurs)
+     *   Logger instance (optional)
      *
      * @example
      * ```javascript
+     * const ROUTE_INTRO = '/intro/start';
+     * const KEY_INTRO_COMPLETED = 'intro-completed';
+     * const KEY_SCORE = 'score';
+     *
      * const machine = new PageMachine({
-     *   startPath: '/intro/start',
-     *   routeMap: {
-     *     [STATE_START]: '/intro/start',
-     *     [STATE_ANIMATE]: '/intro/animate'
-     *   },
+     *   startPath: ROUTE_INTRO,
+     *   routes: [ROUTE_INTRO, '/intro/profile'],
      *   initialData: {
-     *     INTRO_COMPLETED: false
-     *   },
-     *   onEnterHooks: {
-     *     [STATE_ANIMATE]: (done) => {
-     *       setTimeout(() => done(STATE_START), 1000);
-     *       return {
-     *         abort: () => clearTimeout(...),
-     *         complete: () => done(STATE_START)
-     *       };
-     *     }
+     *     [KEY_INTRO_COMPLETED]: false,
+     *     [KEY_SCORE]: 0
      *   }
      * });
      * ```
      */
-    constructor({ startPath, routeMap, initialData, onEnterHooks, logger }: {
+    constructor({ startPath, routes, initialData, logger }: {
         startPath: string;
-        routeMap?: Record<string, string> | undefined;
+        routes?: string[] | undefined;
         initialData?: Record<string, any> | undefined;
-        onEnterHooks?: Record<string, Function> | undefined;
         logger?: import("../../../logging/client.js").Logger | undefined;
     });
     /**
-     * Logger instance for state machine
+     * Logger instance
      * @type {import('../../../logging/client.js').Logger}
      */
     logger: import("../../../logging/client.js").Logger;
     /**
-     * Synchronize machine state with URL path
+     * Synchronize machine with URL path
      *
-     * Call this in a $effect that watches $page.url.pathname
-     * Automatically tracks visited states and triggers onEnter hooks
+     * Call this in a $effect that watches $page.url.pathname.
+     * Automatically tracks visited routes.
      *
      * @param {string} currentPath - Current URL pathname
      *
-     * @returns {boolean} True if state was changed
+     * @returns {boolean} True if route was changed
      */
     syncFromPath(currentPath: string): boolean;
     /**
-     * Get route path for a given state
-     *
-     * @param {string} state - State name
-     *
-     * @returns {string} Route path or null if no mapping
-     */
-    getPathForState(state: string): string;
-    /**
-     * Navigate to the route path for a given state
-     *
-     * @param {string} state - State name
-     */
-    navigateToState(state: string): void;
-    /**
-     * Get route path for current state
-     *
-     * @returns {string|null} Route path or null if no mapping
-     */
-    getCurrentPath(): string | null;
-    /**
-     * Get current state
+     * Get current route
      *
-     * @returns {string} Current state name
+     * @returns {string} Current route path
      */
     get current(): string;
     /**
-     * Get the route map
+     * Get the routes list
      *
-     * @returns {Record<string, string>} Copy of route map
+     * @returns {string[]} Copy of routes list
      */
-    get routeMap(): Record<string, string>;
+    get routes(): string[];
     /**
      * Set a data property value
      *
-     * @param {string} key - Property key
+     * Automatically reactive - effects watching this key will re-run.
+     * Uses fine-grained reactivity, so only effects watching this specific
+     * key will be triggered.
+     *
+     * @param {string} key - Property key (use KEY_ constant)
      * @param {any} value - Property value
      *
      * @example
      * ```javascript
-     * machine.setData('HAS_STRONG_PROFILE', true);
-     * machine.setData('PROFILE_SCORE', 85);
+     * const KEY_HAS_STRONG_PROFILE = 'has-strong-profile';
+     * const KEY_PROFILE_SCORE = 'profile-score';
+     *
+     * machine.setData(KEY_HAS_STRONG_PROFILE, true);
+     * machine.setData(KEY_PROFILE_SCORE, 85);
      * ```
      */
     setData(key: string, value: any): void;
     /**
      * Get a data property value
      *
-     * @param {string} key - Property key
+     * Automatically reactive - creates a dependency on this specific key.
+     * The effect will only re-run when THIS key changes, not when other
+     * keys change.
+     *
+     * @param {string} key - Property key (use KEY_ constant)
      *
      * @returns {any} Property value or undefined
      *
      * @example
      * ```javascript
-     * const hasProfile = machine.getData('HAS_STRONG_PROFILE');
-     * const score = machine.getData('PROFILE_SCORE');
+     * const KEY_SCORE = 'score';
+     *
+     * // Reactive - re-runs only when KEY_SCORE changes
+     * $effect(() => {
+     *   const score = machine.getData(KEY_SCORE);
+     *   console.log('Score:', score);
+     * });
      * ```
      */
     getData(key: string): any;
     /**
-     * Get all data properties
+     * Get all data properties as plain object
+     *
+     * Note: This returns a snapshot (plain object), not a reactive map.
+     * Use this for serialization or server sync, not for reactive tracking.
      *
-     * @returns {Record<string, any>} Copy of all data
+     * @returns {Record<string, any>} Plain object with all data
      *
      * @example
      * ```javascript
@@ -134,154 +123,173 @@ export default class PageMachine {
     /**
      * Update multiple data properties at once
      *
-     * @param {Record<string, any>} dataUpdates - Object with key-value pairs
+     * Each property update triggers fine-grained reactivity.
+     *
+     * @param {Record<string, any>} dataUpdates
+     *   Object with key-value pairs (use KEY_ constants for keys)
      *
      * @example
      * ```javascript
+     * const KEY_HAS_STRONG_PROFILE = 'has-strong-profile';
+     * const KEY_PROFILE_SCORE = 'profile-score';
+     * const KEY_MATCHED_SECTOR = 'matched-sector';
+     *
      * machine.updateData({
-     *   HAS_STRONG_PROFILE: true,
-     *   PROFILE_SCORE: 85,
-     *   MATCHED_SECTOR: 'technology'
+     *   [KEY_HAS_STRONG_PROFILE]: true,
+     *   [KEY_PROFILE_SCORE]: 85,
+     *   [KEY_MATCHED_SECTOR]: 'technology'
      * });
      * ```
      */
     updateData(dataUpdates: Record<string, any>): void;
     /**
-     * Check if a state has been visited
+     * Delete a data property
      *
-     * @param {string} state - State name to check
+     * @param {string} key - Property key to delete (use KEY_ constant)
      *
-     * @returns {boolean} True if the state has been visited
+     * @returns {boolean} True if the key existed and was deleted
      *
      * @example
      * ```javascript
-     * if (machine.hasVisited(STATE_PROFILE)) {
-     *   // User has seen profile page, skip intro
-     * }
+     * const KEY_TEMPORARY_FLAG = 'temporary-flag';
+     *
+     * machine.deleteData(KEY_TEMPORARY_FLAG);
      * ```
      */
-    hasVisited(state: string): boolean;
+    deleteData(key: string): boolean;
     /**
-     * Check if the start state has been visited
+     * Check if data property exists
+     *
+     * @param {string} key - Property key to check (use KEY_ constant)
      *
-     * @returns {boolean} True if the start state has been visited
+     * @returns {boolean} True if the key exists
      *
      * @example
      * ```javascript
-     * if (machine.hasVisitedStart) {
-     *   // User has been to the start page
+     * const KEY_TUTORIAL_SEEN = 'tutorial-seen';
+     *
+     * if (machine.hasData(KEY_TUTORIAL_SEEN)) {
+     *   // Skip tutorial
      * }
      * ```
      */
-    get hasVisitedStart(): boolean;
+    hasData(key: string): boolean;
     /**
-     * Get all visited states
+     * Clear all data properties
      *
-     * @returns {string[]} Array of visited state names
-     */
-    getVisitedStates(): string[];
-    /**
-     * Reset visited states tracking
-     * Useful for testing or resetting experience
+     * @example
+     * ```javascript
+     * machine.clearData();  // Reset all game data
+     * ```
      */
-    resetVisitedStates(): void;
+    clearData(): void;
     /**
-     * Get the start path
+     * Get number of data properties
      *
-     * @returns {string} Start path
+     * @returns {number} Number of data entries
      */
-    get startPath(): string;
+    get dataSize(): number;
     /**
-     * Get the start state
+     * Check if a route has been visited
      *
-     * @returns {string} Start state name
-     */
-    get startState(): string;
-    /**
-     * Check if the supplied path matches the start path
+     * Automatically reactive - creates a dependency on the visited routes set.
      *
-     * @param {string} path - Path to check
+     * @param {string} route - Route path to check
      *
-     * @returns {boolean} True if path matches start path
+     * @returns {boolean} True if the route has been visited
      *
      * @example
      * ```javascript
-     * if (machine.isStartPath('/game/play')) {
-     *   // User is on the start page
-     * }
+     * // Reactive - re-runs when visited routes change
+     * $effect(() => {
+     *   if (machine.hasVisited('/intro/profile')) {
+     *     console.log('User has seen profile page');
+     *   }
+     * });
      * ```
      */
-    isStartPath(path: string): boolean;
+    hasVisited(route: string): boolean;
     /**
-     * Check if currently on the start state
+     * Check if the start route has been visited
      *
-     * @returns {boolean} True if current state is the start state
+     * @returns {boolean} True if the start route has been visited
      *
      * @example
      * ```javascript
-     * if (machine.isOnStartState) {
-     *   // Show onboarding
+     * if (machine.hasVisitedStart) {
+     *   // User has been to the start page
      * }
      * ```
      */
-    get isOnStartState(): boolean;
+    get hasVisitedStart(): boolean;
     /**
-     * Navigate to the start path
+     * Get all visited routes as array
      *
-     * @example
-     * ```javascript
-     * // Redirect user to start
-     * machine.redirectToStartPath();
-     * ```
+     * Note: Returns a snapshot (plain array), not reactive.
+     *
+     * @returns {string[]} Array of visited route paths
      */
-    redirectToStartPath(): void;
+    getVisitedRoutes(): string[];
     /**
-     * Abort current state's transitions
-     * Cancels animations/operations immediately (incomplete state)
+     * Reset visited routes tracking
+     *
+     * Clears all visited routes and marks only the current route as visited.
      *
      * @example
      * ```javascript
-     * // User clicks "Cancel" button
-     * machine.abortTransitions();
+     * machine.resetVisitedRoutes();  // Reset progress tracking
      * ```
      */
-    abortTransitions(): void;
+    resetVisitedRoutes(): void;
+    /**
+     * Get number of visited routes
+     *
+     * @returns {number} Number of routes visited
+     */
+    get visitedRoutesCount(): number;
+    /**
+     * Get the start path
+     *
+     * @returns {string} Start path
+     */
+    get startPath(): string;
     /**
-     * Complete current state's transitions immediately
-     * Fast-forwards animations/operations to completion (complete state)
+     * Check if the supplied path matches the start path
+     *
+     * @param {string} path - Path to check
+     *
+     * @returns {boolean} True if path matches start path
      *
      * @example
      * ```javascript
-     * // User clicks "Skip" or "Next" button
-     * machine.completeTransitions();
+     * if (machine.isStartPath('/game/play')) {
+     *   // User is on the start page
+     * }
      * ```
      */
-    completeTransitions(): void;
+    isStartPath(path: string): boolean;
     /**
-     * Check if current state has transitions that can be completed
+     * Check if currently on the start path
      *
-     * @returns {boolean} True if completeTransitions() can be called
+     * @returns {boolean} True if current route is the start path
      *
      * @example
-     * ```svelte
-     * {#if machine.canCompleteTransitions}
-     *   <button onclick={() => machine.completeTransitions()}>Skip</button>
-     * {/if}
+     * ```javascript
+     * if (machine.isOnStartPath) {
+     *   // Show onboarding
+     * }
      * ```
      */
-    get canCompleteTransitions(): boolean;
+    get isOnStartPath(): boolean;
     /**
-     * Check if current state has transitions that can be aborted
-     *
-     * @returns {boolean} True if abortTransitions() can be called
+     * Navigate to the start path
      *
      * @example
-     * ```svelte
-     * {#if machine.canAbortTransitions}
-     *   <button onclick={() => machine.abortTransitions()}>Cancel</button>
-     * {/if}
+     * ```javascript
+     * // Redirect user to start
+     * machine.redirectToStartPath();
      * ```
      */
-    get canAbortTransitions(): boolean;
+    redirectToStartPath(): void;
     #private;
 }