eleva 1.0.1 → 1.1.0

package/src/plugins/Store.js

@@ -1,5 +1,222 @@
 "use strict";
 
+/**
+ * @module eleva/plugins/store
+ * @fileoverview Reactive state management plugin with namespaced modules,
+ * persistence, and subscription system.
+ */
+
+// ============================================================================
+// TYPE DEFINITIONS
+// ============================================================================
+
+// -----------------------------------------------------------------------------
+// External Type Imports
+// -----------------------------------------------------------------------------
+
+/**
+ * Type imports from the Eleva core library.
+ * @typedef {import('eleva').Eleva} Eleva
+ * @typedef {import('eleva').ComponentDefinition} ComponentDefinition
+ * @typedef {import('eleva').ComponentContext} ComponentContext
+ * @typedef {import('eleva').SetupResult} SetupResult
+ * @typedef {import('eleva').ComponentProps} ComponentProps
+ * @typedef {import('eleva').ChildrenMap} ChildrenMap
+ * @typedef {import('eleva').MountResult} MountResult
+ */
+
+/**
+ * Generic type import.
+ * @template T
+ * @typedef {import('eleva').Signal<T>} Signal
+ */
+
+// -----------------------------------------------------------------------------
+// Store Type Definitions
+// -----------------------------------------------------------------------------
+
+/**
+ * Mutation record emitted to subscribers.
+ * @typedef {Object} StoreMutation
+ * @property {string} type
+ *           The action name that was dispatched.
+ * @property {unknown} payload
+ *           The payload passed to the action.
+ * @property {number} timestamp
+ *           Unix timestamp of when the mutation occurred.
+ * @description Record passed to subscribers when state changes via dispatch.
+ * @example
+ * store.subscribe((mutation, state) => {
+ *   console.log(`Action: ${mutation.type}`);
+ *   console.log(`Payload: ${mutation.payload}`);
+ *   console.log(`Time: ${new Date(mutation.timestamp)}`);
+ * });
+ */
+
+/**
+ * Store configuration options.
+ * @typedef {Object} StoreOptions
+ * @property {Record<string, unknown>} [state]
+ *           Initial state object.
+ * @property {Record<string, ActionFunction>} [actions]
+ *           Action functions for state mutations.
+ * @property {Record<string, StoreModule>} [namespaces]
+ *           Namespaced modules for organizing store.
+ * @property {StorePersistenceOptions} [persistence]
+ *           Persistence configuration.
+ * @property {boolean} [devTools]
+ *           Enable development tools integration.
+ * @property {StoreErrorHandler} [onError]
+ *           Error handler function.
+ * @description Configuration options passed to StorePlugin.install().
+ * @example
+ * app.use(StorePlugin, {
+ *   state: { count: 0, user: null },
+ *   actions: {
+ *     increment: (state) => state.count.value++,
+ *     setUser: (state, user) => state.user.value = user
+ *   },
+ *   persistence: { enabled: true, key: 'my-app' }
+ * });
+ */
+
+/**
+ * Namespaced store module definition.
+ * @typedef {Object} StoreModule
+ * @property {Record<string, unknown>} state
+ *           Module state.
+ * @property {Record<string, ActionFunction>} [actions]
+ *           Module actions.
+ * @description Defines a namespaced module for organizing related state and actions.
+ * @example
+ * // Define a module
+ * const authModule = {
+ *   state: { user: null, token: null },
+ *   actions: {
+ *     login: (state, { user, token }) => {
+ *       state.auth.user.value = user;
+ *       state.auth.token.value = token;
+ *     }
+ *   }
+ * };
+ *
+ * // Register dynamically
+ * store.registerModule('auth', authModule);
+ */
+
+/**
+ * Store persistence configuration.
+ * @typedef {Object} StorePersistenceOptions
+ * @property {boolean} [enabled]
+ *           Enable state persistence.
+ * @property {string} [key]
+ *           Storage key (default: "eleva-store").
+ * @property {'localStorage' | 'sessionStorage'} [storage]
+ *           Storage type.
+ * @property {string[]} [include]
+ *           Dot-path prefixes to persist (e.g., "auth.user").
+ * @property {string[]} [exclude]
+ *           Dot-path prefixes to exclude.
+ * @description Configuration for persisting store state to localStorage or sessionStorage.
+ * @example
+ * // Persist only specific state paths
+ * persistence: {
+ *   enabled: true,
+ *   key: 'my-app-store',
+ *   storage: 'localStorage',
+ *   include: ['user', 'settings.theme']
+ * }
+ *
+ * @example
+ * // Exclude sensitive data
+ * persistence: {
+ *   enabled: true,
+ *   exclude: ['auth.token', 'temp']
+ * }
+ */
+
+/**
+ * Store error handler callback.
+ * @typedef {(error: Error, context: string) => void} StoreErrorHandler
+ * @description Custom error handler for store operations.
+ * @example
+ * app.use(StorePlugin, {
+ *   onError: (error, context) => {
+ *     console.error(`Store error in ${context}:`, error);
+ *     // Send to error tracking service
+ *     errorTracker.capture(error, { context });
+ *   }
+ * });
+ */
+
+/**
+ * Reactive state tree containing signals and nested namespaces.
+ * @typedef {Record<string, Signal<unknown> | Record<string, unknown>>} StoreState
+ * @description Represents the store's reactive state structure with support for nested modules.
+ */
+
+/**
+ * Action function signature for store actions.
+ * @typedef {(state: StoreState, payload?: unknown) => unknown} ActionFunction
+ * @description Function that receives state and optional payload, returns action result.
+ */
+
+/**
+ * Dispatch function signature for triggering actions.
+ * @typedef {(actionName: string, payload?: unknown) => Promise<unknown>} DispatchFunction
+ * @description Dispatches an action by name with optional payload, returns action result.
+ */
+
+/**
+ * Subscribe callback signature for mutation listeners.
+ * @typedef {(mutation: StoreMutation, state: StoreState) => void} SubscribeCallback
+ * @description Called after each successful action dispatch with mutation details and current state.
+ */
+
+/**
+ * Store API exposed to components via ctx.store.
+ * @typedef {Object} StoreApi
+ * @property {StoreState} state
+ *           Reactive state signals (supports nested modules).
+ * @property {DispatchFunction} dispatch
+ *           Dispatch an action by name with optional payload.
+ * @property {(callback: SubscribeCallback) => () => void} subscribe
+ *           Subscribe to state mutations. Returns unsubscribe function.
+ * @property {() => Record<string, unknown>} getState
+ *           Get a snapshot of current state values.
+ * @property {(namespace: string, module: StoreModule) => void} registerModule
+ *           Register a namespaced module dynamically.
+ * @property {(namespace: string) => void} unregisterModule
+ *           Unregister a namespaced module.
+ * @property {(key: string, initialValue: unknown) => Signal<unknown>} createState
+ *           Create a new state signal dynamically.
+ * @property {(name: string, actionFn: ActionFunction) => void} createAction
+ *           Register a new action dynamically.
+ * @property {new <T>(value: T) => Signal<T>} signal
+ *           Signal class constructor for manual state creation.
+ * @description The store API injected into component setup as `ctx.store`.
+ * @example
+ * app.component('Counter', {
+ *   setup({ store }) {
+ *     // Access reactive state
+ *     const count = store.state.count;
+ *
+ *     // Dispatch actions
+ *     const increment = () => store.dispatch('increment');
+ *
+ *     // Subscribe to changes
+ *     const unsub = store.subscribe((mutation) => {
+ *       console.log('State changed:', mutation.type);
+ *     });
+ *
+ *     return { count, increment, onUnmount: () => unsub() };
+ *   },
+ *   template: (ctx) => `<button @click="increment">${ctx.count.value}</button>`
+ * });
+ * @see StoreMutation - Mutation record structure.
+ * @see StoreModule - Module definition for namespaces.
+ */
+
 /**
  * @class 🏪 StorePlugin
  * @classdesc A powerful reactive state management plugin for Eleva that enables sharing
@@ -27,7 +244,7 @@
  *   },
  *   actions: {
  *     increment: (state) => state.counter.value++,
- *     addTodo: (state, todo) => state.todos.value.push(todo),
+ *     addTodo: (state, todo) => state.todos.value = [...state.todos.value, todo],
  *     setUser: (state, user) => state.user.value = user
  *   },
  *   persistence: {
@@ -50,7 +267,7 @@
  *     <div>
  *       <p>Hello ${ctx.user.value.name}!</p>
  *       <p>Count: ${ctx.count.value}</p>
- *       <button onclick="ctx.increment()">+</button>
+ *       <button @click="increment">+</button>
  *     </div>
  *   `
  * });
@@ -66,7 +283,7 @@ export const StorePlugin = {
    * Plugin version
    * @type {string}
    */
-  version: "1.0.0",
+  version: "1.1.0",
 
   /**
    * Plugin description
@@ -76,21 +293,28 @@ export const StorePlugin = {
     "Reactive state management for sharing data across the entire Eleva application",
 
   /**
-   * Installs the plugin into the Eleva instance
+   * Installs the plugin into the Eleva instance.
    *
-   * @param {Object} eleva - The Eleva instance
-   * @param {Object} options - Plugin configuration options
-   * @param {Object} [options.state={}] - Initial state object
-   * @param {Object} [options.actions={}] - Action functions for state mutations
-   * @param {Object} [options.namespaces={}] - Namespaced modules for organizing store
-   * @param {Object} [options.persistence] - Persistence configuration
-   * @param {boolean} [options.persistence.enabled=false] - Enable state persistence
-   * @param {string} [options.persistence.key="eleva-store"] - Storage key
-   * @param {"localStorage" | "sessionStorage"} [options.persistence.storage="localStorage"] - Storage type
-   * @param {Array<string>} [options.persistence.include] - State keys to persist (if not provided, all state is persisted)
-   * @param {Array<string>} [options.persistence.exclude] - State keys to exclude from persistence
-   * @param {boolean} [options.devTools=false] - Enable development tools integration
-   * @param {Function} [options.onError=null] - Error handler function
+   * @public
+   * @param {Eleva} eleva - The Eleva instance.
+   * @param {StoreOptions} options - Plugin configuration options.
+   * @param {Record<string, unknown>} [options.state={}] - Initial state object.
+   * @param {Record<string, ActionFunction>} [options.actions={}] - Action functions for state mutations.
+   * @param {Record<string, StoreModule>} [options.namespaces={}] - Namespaced modules for organizing store.
+   * @param {StorePersistenceOptions} [options.persistence] - Persistence configuration.
+   * @param {boolean} [options.persistence.enabled=false] - Enable state persistence.
+   * @param {string} [options.persistence.key="eleva-store"] - Storage key.
+   * @param {'localStorage' | 'sessionStorage'} [options.persistence.storage="localStorage"] - Storage type.
+   * @param {string[]} [options.persistence.include] - Dot-path prefixes to persist (e.g., "auth.user")
+   * @param {string[]} [options.persistence.exclude] - Dot-path prefixes to exclude (applies when include is empty).
+   * @param {boolean} [options.devTools=false] - Enable development tools integration.
+   * @param {(error: Error, context: string) => void} [options.onError=null] - Error handler function.
+   * @returns {void}
+   * @description
+   * Installs the store and injects `store` into component setup context by wrapping
+   * `eleva.mount` and `eleva._mountComponents`. Also exposes `eleva.store` and
+   * helper methods (`eleva.dispatch`, `eleva.getState`, `eleva.subscribe`, `eleva.createAction`).
+   * Uninstall restores the originals.
    *
    * @example
    * // Basic installation
@@ -110,12 +334,12 @@ export const StorePlugin = {
    *       state: { user: null, token: null },
    *       actions: {
    *         login: (state, { user, token }) => {
-   *           state.user.value = user;
-   *           state.token.value = token;
+   *           state.auth.user.value = user;
+   *           state.auth.token.value = token;
    *         },
    *         logout: (state) => {
-   *           state.user.value = null;
-   *           state.token.value = null;
+   *           state.auth.user.value = null;
+   *           state.auth.token.value = null;
    *         }
    *       }
    *     }
@@ -137,15 +361,27 @@ export const StorePlugin = {
     } = options;
 
     /**
-     * Store instance that manages all state and provides the API
+     * @class Store
+     * @classdesc Store instance that manages all state and provides the API.
      * @private
      */
     class Store {
+      /**
+       * Creates a new Store instance.
+       * Initializes state signals, actions, persistence, and devtools integration.
+       *
+       * @constructor
+       */
       constructor() {
+        /** @type {Record<string, Signal | Record<string, unknown>>} */
         this.state = {};
+        /** @type {Record<string, ActionFunction | Record<string, ActionFunction>>} */
         this.actions = {};
+        /** @type {Set<SubscribeCallback>} */
         this.subscribers = new Set();
+        /** @type {StoreMutation[]} */
         this.mutations = [];
+        /** @type {{enabled: boolean, key: string, storage: string, include: string[]|null, exclude: string[]|null}} */
         this.persistence = {
           enabled: false,
           key: "eleva-store",
@@ -154,7 +390,9 @@ export const StorePlugin = {
           exclude: null,
           ...persistence,
         };
+        /** @type {boolean} */
         this.devTools = devTools;
+        /** @type {((error: Error, context: string) => void)|null} */
         this.onError = onError;
 
         this._initializeState(state, actions);
@@ -164,8 +402,13 @@ export const StorePlugin = {
       }
 
       /**
-       * Initializes the root state and actions
+       * Initializes the root state and actions.
+       * Creates reactive signals for each state property and copies actions.
+       *
        * @private
+       * @param {Record<string, unknown>} initialState - The initial state key-value pairs.
+       * @param {Record<string, ActionFunction>} initialActions - The action functions to register.
+       * @returns {void}
        */
       _initializeState(initialState, initialActions) {
         // Create reactive signals for each state property
@@ -178,8 +421,12 @@ export const StorePlugin = {
       }
 
       /**
-       * Initializes namespaced modules
+       * Initializes namespaced modules.
+       * Creates namespace objects and populates them with state signals and actions.
+       *
        * @private
+       * @param {Record<string, StoreModule>} namespaces - Map of namespace names to module definitions.
+       * @returns {void}
        */
       _initializeNamespaces(namespaces) {
         Object.entries(namespaces).forEach(([namespace, module]) => {
@@ -205,8 +452,12 @@ export const StorePlugin = {
       }
 
       /**
-       * Loads persisted state from storage
+       * Loads persisted state from storage.
+       * Reads from localStorage/sessionStorage and applies values to state signals.
+       * Does nothing if persistence is disabled or running in SSR environment.
+       *
        * @private
+       * @returns {void}
        */
       _loadPersistedState() {
         if (!this.persistence.enabled || typeof window === "undefined") {
@@ -234,8 +485,14 @@ export const StorePlugin = {
       }
 
       /**
-       * Applies persisted data to the current state
+       * Applies persisted data to the current state.
+       * Recursively updates signal values for paths that should be persisted.
+       *
        * @private
+       * @param {Record<string, unknown>} data - The persisted data object to apply.
+       * @param {Record<string, unknown>} [currentState=this.state] - The current state object to update.
+       * @param {string} [path=""] - The current dot-notation path (for include/exclude filtering).
+       * @returns {void}
        */
       _applyPersistedData(data, currentState = this.state, path = "") {
         Object.entries(data).forEach(([key, value]) => {
@@ -262,8 +519,12 @@ export const StorePlugin = {
       }
 
       /**
-       * Determines if a state path should be persisted
+       * Determines if a state path should be persisted.
+       * Checks against include/exclude filters configured in persistence options.
+       *
        * @private
+       * @param {string} path - The dot-notation path to check (e.g., "auth.user").
+       * @returns {boolean} True if the path should be persisted, false otherwise.
        */
       _shouldPersist(path) {
         const { include, exclude } = this.persistence;
@@ -280,8 +541,12 @@ export const StorePlugin = {
       }
 
       /**
-       * Saves current state to storage
+       * Saves current state to storage.
+       * Extracts persistable data and writes to localStorage/sessionStorage.
+       * Does nothing if persistence is disabled or running in SSR environment.
+       *
        * @private
+       * @returns {void}
        */
       _saveState() {
         if (!this.persistence.enabled || typeof window === "undefined") {
@@ -302,8 +567,13 @@ export const StorePlugin = {
       }
 
       /**
-       * Extracts data that should be persisted
+       * Extracts data that should be persisted.
+       * Recursively extracts signal values for paths that pass persistence filters.
+       *
        * @private
+       * @param {Record<string, unknown>} [currentState=this.state] - The state object to extract from.
+       * @param {string} [path=""] - The current dot-notation path (for include/exclude filtering).
+       * @returns {Record<string, unknown>} The extracted data object with raw values (not signals).
        */
       _extractPersistedData(currentState = this.state, path = "") {
         const result = {};
@@ -329,8 +599,12 @@ export const StorePlugin = {
       }
 
       /**
-       * Sets up development tools integration
+       * Sets up development tools integration.
+       * Registers the store with Eleva DevTools if available and enabled.
+       * Does nothing if devTools is disabled, running in SSR, or DevTools not installed.
+       *
        * @private
+       * @returns {void}
        */
       _setupDevTools() {
         if (
@@ -345,10 +619,26 @@ export const StorePlugin = {
       }
 
       /**
-       * Dispatches an action to mutate the state
-       * @param {string} actionName - The name of the action to dispatch (supports namespaced actions like "auth.login")
-       * @param {any} payload - The payload to pass to the action
-       * @returns {Promise<any>} The result of the action
+       * Dispatches an action to mutate the state.
+       *
+       * Execution flow:
+       * 1. Retrieves the action function (supports namespaced actions like "auth.login")
+       * 2. Records mutation for devtools/history (keeps last 100 mutations)
+       * 3. Executes action with await (actions can be sync or async)
+       * 4. Saves state if persistence is enabled
+       * 5. Notifies all subscribers with (mutation, state)
+       * 6. Notifies devtools if enabled
+       *
+       * @note Always returns a Promise regardless of whether the action is sync or async.
+       * Subscriber callbacks that throw are caught and passed to onError handler.
+       *
+       * @async
+       * @param {string} actionName - The name of the action to dispatch (supports dot notation for namespaces).
+       * @param {unknown} payload - The payload to pass to the action.
+       * @returns {Promise<unknown>} The result of the action (undefined if action returns nothing).
+       * @throws {Error} If action is not found or action function throws.
+       * @see subscribe - Listen for mutations triggered by dispatch.
+       * @see getState - Get current state values.
        */
       async dispatch(actionName, payload) {
         try {
@@ -410,8 +700,12 @@ export const StorePlugin = {
       }
 
       /**
-       * Gets an action by name (supports namespaced actions)
+       * Gets an action by name (supports namespaced actions).
+       * Traverses the actions object using dot-notation path segments.
+       *
        * @private
+       * @param {string} actionName - The action name, supports dot notation for namespaces (e.g., "auth.login").
+       * @returns {ActionFunction | null} The action function if found and is a function, null otherwise.
        */
       _getAction(actionName) {
         const parts = actionName.split(".");
@@ -428,9 +722,18 @@ export const StorePlugin = {
       }
 
       /**
-       * Subscribes to store mutations
-       * @param {Function} callback - Callback function to call on mutations
-       * @returns {Function} Unsubscribe function
+       * Subscribes to store mutations.
+       * Callback is invoked after every successful action dispatch.
+       *
+       * @param {SubscribeCallback} callback
+       *        Called after each mutation with:
+       *        - mutation.type: The action name that was dispatched
+       *        - mutation.payload: The payload passed to the action
+       *        - mutation.timestamp: When the mutation occurred (Date.now())
+       *        - state: The current state object (contains Signals)
+       * @returns {() => void} Unsubscribe function. Call to stop receiving notifications.
+       * @throws {Error} If callback is not a function.
+       * @see dispatch - Triggers mutations that notify subscribers.
        */
       subscribe(callback) {
         if (typeof callback !== "function") {
@@ -446,16 +749,26 @@ export const StorePlugin = {
       }
 
       /**
-       * Gets a deep copy of the current state values (not signals)
-       * @returns {Object} The current state values
+       * Gets current state values (not signals).
+       *
+       * @note When persistence include/exclude filters are configured,
+       * this returns only the filtered subset of state.
+       * @returns {Record<string, unknown>} The current state values (filtered by persistence config if set).
+       * @see replaceState - Set state values.
+       * @see subscribe - Listen for state changes.
        */
       getState() {
         return this._extractPersistedData();
       }
 
       /**
-       * Replaces the entire state (useful for testing or state hydration)
-       * @param {Object} newState - The new state object
+       * Replaces state values (useful for testing or state hydration).
+       *
+       * @note When persistence include/exclude filters are configured,
+       * this only updates the filtered subset of state.
+       * @param {Record<string, unknown>} newState - The new state object.
+       * @returns {void}
+       * @see getState - Get current state values.
        */
       replaceState(newState) {
         this._applyPersistedData(newState);
@@ -463,7 +776,9 @@ export const StorePlugin = {
       }
 
       /**
-       * Clears persisted state from storage
+       * Clears persisted state from storage.
+       * Does nothing if persistence is disabled or running in SSR.
+       * @returns {void}
        */
       clearPersistedState() {
         if (!this.persistence.enabled || typeof window === "undefined") {
@@ -481,11 +796,14 @@ export const StorePlugin = {
       }
 
       /**
-       * Registers a new namespaced module at runtime
-       * @param {string} namespace - The namespace for the module
-       * @param {Object} module - The module definition
-       * @param {Object} module.state - The module's initial state
-       * @param {Object} module.actions - The module's actions
+       * Registers a new namespaced module at runtime.
+       * Logs a warning if the namespace already exists.
+       * Module state is nested under `state[namespace]` and actions under `actions[namespace]`.
+       * @param {string} namespace - The namespace for the module.
+       * @param {StoreModule} module - The module definition.
+       * @param {Record<string, unknown>} module.state - The module's initial state.
+       * @param {Record<string, ActionFunction>} module.actions - The module's actions.
+       * @returns {void}
        */
       registerModule(namespace, module) {
         if (this.state[namespace] || this.actions[namespace]) {
@@ -504,8 +822,11 @@ export const StorePlugin = {
       }
 
       /**
-       * Unregisters a namespaced module
-       * @param {string} namespace - The namespace to unregister
+       * Unregisters a namespaced module.
+       * Logs a warning if the namespace doesn't exist.
+       * Removes both state and actions under the namespace.
+       * @param {string} namespace - The namespace to unregister.
+       * @returns {void}
        */
       unregisterModule(namespace) {
         if (!this.state[namespace] && !this.actions[namespace]) {
@@ -519,10 +840,11 @@ export const StorePlugin = {
       }
 
       /**
-       * Creates a new reactive state property at runtime
-       * @param {string} key - The state key
-       * @param {*} initialValue - The initial value
-       * @returns {Object} The created signal
+       * Creates a new reactive state property at runtime.
+       *
+       * @param {string} key - The state key.
+       * @param {*} initialValue - The initial value.
+       * @returns {Signal} The created signal, or existing signal if key exists.
        */
       createState(key, initialValue) {
         if (this.state[key]) {
@@ -535,16 +857,42 @@ export const StorePlugin = {
       }
 
       /**
-       * Creates a new action at runtime
-       * @param {string} name - The action name
-       * @param {Function} actionFn - The action function
+       * Creates a new action at runtime.
+       * Overwrites existing action if name already exists.
+       * Supports dot-notation for namespaced actions (e.g., "auth.login").
+       * @param {string} name - The action name (supports dot notation for namespaces).
+       * @param {ActionFunction} actionFn - The action function (receives state and payload).
+       * @returns {void}
+       * @throws {Error} If actionFn is not a function.
+       * @example
+       * // Root-level action
+       * store.createAction("increment", (state) => state.count.value++);
+       *
+       * // Namespaced action
+       * store.createAction("auth.login", async (state, credentials) => {
+       *   // ... login logic
+       * });
        */
       createAction(name, actionFn) {
         if (typeof actionFn !== "function") {
           throw new Error("Action must be a function");
         }
 
-        this.actions[name] = actionFn;
+        // Fast path: no dot means simple action (avoids array allocation)
+        if (name.indexOf(".") === -1) {
+          this.actions[name] = actionFn;
+          return;
+        }
+
+        // Namespaced action, traverse/create nested structure
+        const parts = name.split(".");
+        const lastIndex = parts.length - 1;
+        let current = this.actions;
+
+        for (let i = 0; i < lastIndex; i++) {
+          current = current[parts[i]] || (current[parts[i]] = {});
+        }
+        current[parts[lastIndex]] = actionFn;
       }
     }
 
@@ -555,7 +903,13 @@ export const StorePlugin = {
     const originalMount = eleva.mount;
 
     /**
-     * Override the mount method to inject store context into components
+     * Overridden mount method that injects store context into components.
+     * Wraps the original mount to add `ctx.store` to the component's setup context.
+     *
+     * @param {HTMLElement} container - The DOM element where the component will be mounted.
+     * @param {string | ComponentDefinition} compName - Component name or definition.
+     * @param {ComponentProps} [props={}] - Optional properties to pass to the component.
+     * @returns {Promise<MountResult>} The mount result.
      */
     eleva.mount = async (container, compName, props = {}) => {
       // Get the component definition
@@ -572,7 +926,7 @@ export const StorePlugin = {
       const wrappedComponent = {
         ...componentDef,
         async setup(ctx) {
-          // Inject store into the context with enhanced API
+          /** @type {StoreApi} */
           ctx.store = {
             // Core store functionality
             state: store.state,
@@ -611,7 +965,23 @@ export const StorePlugin = {
 
     // Override _mountComponents to ensure child components also get store context
     const originalMountComponents = eleva._mountComponents;
-    eleva._mountComponents = async (container, children, childInstances) => {
+
+    /**
+     * Overridden _mountComponents method that injects store context into child components.
+     * Wraps each child component's setup function to add `ctx.store` before mounting.
+     *
+     * @param {HTMLElement} container - The parent container element.
+     * @param {ChildrenMap} children - Map of selectors to component definitions.
+     * @param {MountResult[]} childInstances - Array to store mounted instances.
+     * @param {ComponentContext & SetupResult} context - Parent component context.
+     * @returns {Promise<void>}
+     */
+    eleva._mountComponents = async (
+      container,
+      children,
+      childInstances,
+      context
+    ) => {
       // Create wrapped children with store injection
       const wrappedChildren = {};
 
@@ -625,7 +995,7 @@ export const StorePlugin = {
           wrappedChildren[selector] = {
             ...componentDef,
             async setup(ctx) {
-              // Inject store into the context with enhanced API
+              /** @type {StoreApi} */
               ctx.store = {
                 // Core store functionality
                 state: store.state,
@@ -662,29 +1032,35 @@ export const StorePlugin = {
         eleva,
         container,
         wrappedChildren,
-        childInstances
+        childInstances,
+        context
       );
     };
 
     // Expose store instance and utilities on the Eleva instance
+    /** @type {StoreApi} */
     eleva.store = store;
 
     /**
-     * Expose utility methods on the Eleva instance
-     * @namespace eleva.store
+     * Expose utility methods on the Eleva instance.
+     * These are top-level helpers (e.g., `eleva.dispatch`) in addition to `eleva.store`.
      */
+    /** @type {(name: string, actionFn: ActionFunction) => void} */
     eleva.createAction = (name, actionFn) => {
-      store.actions[name] = actionFn;
+      store.createAction(name, actionFn);
     };
 
+    /** @type {DispatchFunction} */
     eleva.dispatch = (actionName, payload) => {
       return store.dispatch(actionName, payload);
     };
 
+    /** @type {() => Record<string, unknown>} */
     eleva.getState = () => {
       return store.getState();
     };
 
+    /** @type {(callback: SubscribeCallback) => () => void} */
     eleva.subscribe = (callback) => {
       return store.subscribe(callback);
     };
@@ -695,14 +1071,17 @@ export const StorePlugin = {
   },
 
   /**
-   * Uninstalls the plugin from the Eleva instance
-   *
-   * @param {Object} eleva - The Eleva instance
+   * Uninstalls the plugin from the Eleva instance.
    *
+   * @public
+   * @param {Eleva} eleva - The Eleva instance.
+   * @returns {void}
    * @description
    * Restores the original Eleva methods and removes all plugin-specific
    * functionality. This method should be called when the plugin is no
    * longer needed.
+   * Also removes `eleva.store` and top-level helpers (`eleva.dispatch`,
+   * `eleva.getState`, `eleva.subscribe`, `eleva.createAction`).
    *
    * @example
    * // Uninstall the plugin