@hkdigital/lib-core 0.5.56 → 0.5.58

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

@@ -1,3 +1,45 @@
+/**
+ * Route-aware data manager for page groups
+ *
+ * Tracks navigation within a route group and manages business/domain data.
+ * Does NOT enforce transitions - allows free navigation via browser.
+ *
+ * Features:
+ * - Current route tracking and synchronization
+ * - Start path management
+ * - Data properties for business/domain state
+ * - Visited routes tracking
+ *
+ * Basic usage:
+ * ```javascript
+ * const machine = new PageMachine({
+ *   startPath: '/intro/start',
+ *   routes: ['/intro/start', '/intro/profile', '/intro/complete']
+ * });
+ *
+ * // Sync machine with URL changes
+ * $effect(() => {
+ *   machine.syncFromPath($page.url.pathname);
+ * });
+ *
+ * // Check current route
+ * if (machine.current === '/intro/profile') {
+ *   // Do something
+ * }
+ * ```
+ *
+ * Animations and page-specific logic should use $effect in pages:
+ * ```javascript
+ * // In +page.svelte
+ * const animations = new PageAnimations();
+ *
+ * $effect(() => {
+ *   if (someCondition) {
+ *     animations.start();
+ *   }
+ * });
+ * ```
+ */
 export default class PageMachine {
     /**
      * Constructor
@@ -5,93 +47,58 @@ 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
      * @param {import('../../../logging/client.js').Logger} [config.logger]
-     *   Logger instance (optional, if not provided no logging occurs)
+     *   Logger instance (optional)
      *
      * @example
      * ```javascript
      * const machine = new PageMachine({
      *   startPath: '/intro/start',
-     *   routeMap: {
-     *     [STATE_START]: '/intro/start',
-     *     [STATE_ANIMATE]: '/intro/animate'
-     *   },
+     *   routes: ['/intro/start', '/intro/profile'],
      *   initialData: {
      *     INTRO_COMPLETED: false
-     *   },
-     *   onEnterHooks: {
-     *     [STATE_ANIMATE]: (done) => {
-     *       setTimeout(() => done(STATE_START), 1000);
-     *       return {
-     *         abort: () => clearTimeout(...),
-     *         complete: () => done(STATE_START)
-     *       };
-     *     }
      *   }
      * });
      * ```
      */
-    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
+     * Get current route
      *
-     * @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
-     *
-     * @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
      *
@@ -134,7 +141,8 @@ export default class PageMachine {
     /**
      * Update multiple data properties at once
      *
-     * @param {Record<string, any>} dataUpdates - Object with key-value pairs
+     * @param {Record<string, any>} dataUpdates
+     *   Object with key-value pairs
      *
      * @example
      * ```javascript
@@ -147,24 +155,24 @@ export default class PageMachine {
      */
     updateData(dataUpdates: Record<string, any>): void;
     /**
-     * Check if a state has been visited
+     * Check if a route has been visited
      *
-     * @param {string} state - State name to check
+     * @param {string} route - Route path to check
      *
-     * @returns {boolean} True if the state has been visited
+     * @returns {boolean} True if the route has been visited
      *
      * @example
      * ```javascript
-     * if (machine.hasVisited(STATE_PROFILE)) {
+     * if (machine.hasVisited('/intro/profile')) {
      *   // User has seen profile page, skip intro
      * }
      * ```
      */
-    hasVisited(state: string): boolean;
+    hasVisited(route: string): boolean;
     /**
-     * Check if the start state has been visited
+     * Check if the start route has been visited
      *
-     * @returns {boolean} True if the start state has been visited
+     * @returns {boolean} True if the start route has been visited
      *
      * @example
      * ```javascript
@@ -175,28 +183,22 @@ export default class PageMachine {
      */
     get hasVisitedStart(): boolean;
     /**
-     * Get all visited states
+     * Get all visited routes
      *
-     * @returns {string[]} Array of visited state names
+     * @returns {string[]} Array of visited route paths
      */
-    getVisitedStates(): string[];
+    getVisitedRoutes(): string[];
     /**
-     * Reset visited states tracking
+     * Reset visited routes tracking
      * Useful for testing or resetting experience
      */
-    resetVisitedStates(): void;
+    resetVisitedRoutes(): void;
     /**
      * Get the start path
      *
      * @returns {string} Start path
      */
     get startPath(): string;
-    /**
-     * Get the start state
-     *
-     * @returns {string} Start state name
-     */
-    get startState(): string;
     /**
      * Check if the supplied path matches the start path
      *
@@ -213,18 +215,18 @@ export default class PageMachine {
      */
     isStartPath(path: string): boolean;
     /**
-     * Check if currently on the start state
+     * Check if currently on the start path
      *
-     * @returns {boolean} True if current state is the start state
+     * @returns {boolean} True if current route is the start path
      *
      * @example
      * ```javascript
-     * if (machine.isOnStartState) {
+     * if (machine.isOnStartPath) {
      *   // Show onboarding
      * }
      * ```
      */
-    get isOnStartState(): boolean;
+    get isOnStartPath(): boolean;
     /**
      * Navigate to the start path
      *
@@ -235,53 +237,5 @@ export default class PageMachine {
      * ```
      */
     redirectToStartPath(): 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;
 }