@hkdigital/lib-core 0.5.45 → 0.5.47

package/dist/state/context/README.md

@@ -1,68 +1,72 @@
-# RouteStateContext
+# State Context Utilities
 
-Base class for route-level state containers.
+Helper functions for managing Svelte context in route-level state containers.
 
-## How it connects
+## defineStateContext
 
+Creates context helper functions for a state container class.
+
+```javascript
+import { defineStateContext } from '@hkdigital/lib-core/state/context.js';
+
+class PuzzleState {
+  #pageMachine;
+
+  constructor() {
+    this.#pageMachine = new PuzzlePageMachine();
+  }
+
+  get pageMachine() {
+    return this.#pageMachine;
+  }
+}
+
+// Export helper functions
+export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
+  defineStateContext(PuzzleState);
 ```
-┌─────────────────────────────────────────────────────────┐
-│ 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()
+
+## Helper Functions
+
+The `defineStateContext` helper creates three functions:
+
+### createOrGetPuzzleState()
+
+Get existing instance or create new one. Use in `+layout.svelte`.
+
+```javascript
+// routes/puzzle/+layout.svelte
+const state = createOrGetPuzzleState();
 ```
 
-## Main Purposes
+### createPuzzleState()
 
-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
+Force create new instance (discards existing).
 
-## Key Features
+```javascript
+const state = createPuzzleState();
+```
 
-- 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)
+### getPuzzleState()
 
-## Basic Usage
+Get existing instance. Throws error if not found. Use in pages/components.
 
-### 1. Create state container class
+```javascript
+// routes/puzzle/level1/+page.svelte
+const state = getPuzzleState();
+```
+
+## Complete Example
 
 ```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 {
+export class PuzzleState {
   #pageMachine;
 
   constructor() {
-    super({
-      startPath: '/puzzle',
-      enforceStartPath: true  // Optional: enforce route protection
-    });
     this.#pageMachine = new PuzzlePageMachine();
   }
 
@@ -81,34 +85,26 @@ export class PuzzleState extends RouteStateContext {
   }
 
   reset() {
-    // Reset state when needed
+    this.#pageMachine = new PuzzlePageMachine();
   }
 }
 
-// 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();
+  const pageMachine = puzzleState.pageMachine;
 
   // 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);
+    pageMachine.syncFromPath($page.url.pathname);
   });
 
   // Optional: Preload assets
@@ -120,8 +116,6 @@ export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
 <slot />
 ```
 
-### 3. Consume context in pages
-
 ```svelte
 <!-- routes/puzzle/level1/+page.svelte -->
 <script>
@@ -134,81 +128,12 @@ export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
 <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.
+## Key Features
 
-**Custom redirect URL:**
-```javascript
-// Redirect to a different URL instead of startPath
-puzzleState.validateAndRedirect($page.url.pathname, '/puzzle/welcome');
-```
+- 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)
+- PageMachine integration for route/state management
 
 ## Separation of Concerns
 
@@ -222,5 +147,6 @@ puzzleState.validateAndRedirect($page.url.pathname, '/puzzle/welcome');
 **PageMachine** = Page/view state ONLY (SINGLE responsibility)
 - Current page state
 - Route mapping
+- Start path management
 - Visited states
 - Computed properties for state checks

package/dist/state/context.d.ts

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

package/dist/state/context.js

@@ -1,2 +1 @@
-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

@@ -7,12 +7,20 @@
  *
  * Features:
  * - State-to-route mapping and sync
+ * - Start path management
  * - Data properties for business/domain state
  * - Visited states tracking
+ * - onEnter hooks with abort/complete handlers for animations
  *
  * Basic usage:
  * ```javascript
- * const machine = cityState.getOrCreatePageMachine('intro', IntroPageMachine);
+ * const machine = new PageMachine({
+ *   startPath: '/intro/start',
+ *   routeMap: {
+ *     [STATE_START]: '/intro/start',
+ *     [STATE_PROFILE]: '/intro/profile'
+ *   }
+ * });
  *
  * // Sync machine state with URL changes
  * $effect(() => {
@@ -20,54 +28,77 @@
  * });
  * ```
  *
- * With data properties (for business logic):
+ * With onEnter hooks (for animations):
  * ```javascript
- * // Initialize with server data
- * const initialData = {
- *   HAS_STRONG_PROFILE: false,
- *   PROFILE_COMPLETED: false,
- *   MATCHED_SECTOR: null
- * };
- * const machine = new CircuitPageMachine(initialState, routeMap, initialData);
+ * const machine = new PageMachine({
+ *   startPath: '/game/animate',
+ *   routeMap: {
+ *     [STATE_ANIMATE]: '/game/animate',
+ *     [STATE_PLAY]: '/game/play'
+ *   },
+ *   onEnterHooks: {
+ *     [STATE_ANIMATE]: (done) => {
+ *       const animation = playAnimation(1000);
+ *       animation.finished.then(() => done(STATE_PLAY));
  *
- * // Read data
- * if (machine.getData('HAS_STRONG_PROFILE')) {
- *   // Show advanced content
- * }
+ *       return {
+ *         abort: () => animation.cancel(),
+ *         complete: () => animation.finish()
+ *       };
+ *     }
+ *   }
+ * });
  *
- * // Update data (triggers reactivity)
- * machine.setData('HAS_STRONG_PROFILE', true);
+ * // Fast-forward animation
+ * machine.completeTransitions();
  *
- * // Check visited states
- * if (machine.hasVisited(STATE_PROFILE)) {
- *   // User has seen profile page before
- * }
+ * // Cancel animation
+ * machine.abortTransitions();
  * ```
  */
 export default class PageMachine {
     /**
      * Constructor
      *
-     * @param {string} initialState - Initial state name
-     * @param {Record<string, string>} routeMap - Map of states to route paths
-     * @param {Record<string, any>} [initialData={}] - Initial data properties (from server)
+     * @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 {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 routeMap = {
-     *   [STATE_MATCH]: '/city/intro/match',
-     *   [STATE_CIRCUIT]: '/city/intro/racecircuit'
-     * };
-     *
-     * const initialData = {
-     *   INTRO_COMPLETED: false,
-     *   PROFILE_SCORE: 0
-     * };
-     *
-     * const machine = new CityIntroPageMachine(STATE_START, routeMap, initialData);
+     * const machine = new PageMachine({
+     *   startPath: '/intro/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: string, routeMap?: Record<string, string>, initialData?: Record<string, any>);
+    constructor({ startPath, routeMap, initialData, onEnterHooks }: {
+        startPath: string;
+        routeMap?: Record<string, string> | undefined;
+        initialData?: Record<string, any> | undefined;
+        onEnterHooks?: Record<string, Function> | undefined;
+    });
     /**
      * Synchronize machine state with URL path
      *
@@ -81,10 +112,11 @@ export default class PageMachine {
     syncFromPath(currentPath: string): boolean;
     /**
      * Set the current state directly
+     * Handles onEnter hooks and auto-transitions
      *
      * @param {string} newState - Target state
      */
-    setState(newState: string): void;
+    setState(newState: string): Promise<void>;
     /**
      * Get route path for a given state
      *
@@ -191,5 +223,103 @@ export default class PageMachine {
      * Useful for testing or resetting experience
      */
     resetVisitedStates(): 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
+     *
+     * @param {string} path - Path to check
+     *
+     * @returns {boolean} True if path matches start path
+     *
+     * @example
+     * ```javascript
+     * if (machine.isStartPath('/game/play')) {
+     *   // User is on the start page
+     * }
+     * ```
+     */
+    isStartPath(path: string): boolean;
+    /**
+     * Check if currently on the start state
+     *
+     * @returns {boolean} True if current state is the start state
+     *
+     * @example
+     * ```javascript
+     * if (machine.isOnStartState) {
+     *   // Show onboarding
+     * }
+     * ```
+     */
+    get isOnStartState(): boolean;
+    /**
+     * Navigate to the start path
+     *
+     * @example
+     * ```javascript
+     * // Redirect user to start
+     * machine.redirectToStartPath();
+     * ```
+     */
+    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;
 }