eleva 1.2.17-beta → 1.2.19-beta

package/dist/eleva.umd.js

@@ -1,4 +1,4 @@
-/*! Eleva v1.2.17-beta | MIT License | https://elevajs.com */
+/*! Eleva v1.2.19-beta | MIT License | https://elevajs.com */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
   typeof define === 'function' && define.amd ? define(factory) :
@@ -19,6 +19,7 @@
   class TemplateEngine {
     /**
      * @private {RegExp} Regular expression for matching template expressions in the format {{ expression }}
+     * @type {RegExp}
      */
     static expressionPattern = /\{\{\s*(.*?)\s*\}\}/g;
 
@@ -29,7 +30,7 @@
      * @public
      * @static
      * @param {string} template - The template string to parse.
-     * @param {Object} data - The data context for evaluating expressions.
+     * @param {Record<string, unknown>} data - The data context for evaluating expressions.
      * @returns {string} The parsed template with expressions replaced by their values.
      * @example
      * const result = TemplateEngine.parse("{{user.name}} is {{user.age}} years old", {
@@ -44,12 +45,14 @@
     /**
      * Evaluates an expression in the context of the provided data object.
      * Note: This does not provide a true sandbox and evaluated expressions may access global scope.
+     * The use of the `with` statement is necessary for expression evaluation but has security implications.
+     * Expressions should be carefully validated before evaluation.
      *
      * @public
      * @static
      * @param {string} expression - The expression to evaluate.
-     * @param {Object} data - The data context for evaluation.
-     * @returns {*} The result of the evaluation, or an empty string if evaluation fails.
+     * @param {Record<string, unknown>} data - The data context for evaluation.
+     * @returns {unknown} The result of the evaluation, or an empty string if evaluation fails.
      * @example
      * const result = TemplateEngine.evaluate("user.name", { user: { name: "John" } }); // Returns: "John"
      * const age = TemplateEngine.evaluate("user.age", { user: { age: 30 } }); // Returns: 30
@@ -69,6 +72,8 @@
    * @classdesc A reactive data holder that enables fine-grained reactivity in the Eleva framework.
    * Signals notify registered watchers when their value changes, enabling efficient DOM updates
    * through targeted patching rather than full re-renders.
+   * Updates are batched using microtasks to prevent multiple synchronous notifications.
+   * The class is generic, allowing type-safe handling of any value type T.
    *
    * @example
    * const count = new Signal(0);
@@ -81,12 +86,12 @@
      * Creates a new Signal instance with the specified initial value.
      *
      * @public
-     * @param {*} value - The initial value of the signal.
+     * @param {T} value - The initial value of the signal.
      */
     constructor(value) {
-      /** @private {T} Internal storage for the signal's current value, where T is the type of the initial value */
+      /** @private {T} Internal storage for the signal's current value */
       this._value = value;
-      /** @private {Set<function(T): void>} Collection of callback functions to be notified when value changes, where T is the value type */
+      /** @private {Set<(value: T) => void>} Collection of callback functions to be notified when value changes */
       this._watchers = new Set();
       /** @private {boolean} Flag to prevent multiple synchronous watcher notifications and batch updates into microtasks */
       this._pending = false;
@@ -96,7 +101,7 @@
      * Gets the current value of the signal.
      *
      * @public
-     * @returns {T} The current value, where T is the type of the initial value.
+     * @returns {T} The current value.
      */
     get value() {
       return this._value;
@@ -107,7 +112,7 @@
      * The notification is batched using microtasks to prevent multiple synchronous updates.
      *
      * @public
-     * @param {T} newVal - The new value to set, where T is the type of the initial value.
+     * @param {T} newVal - The new value to set.
      * @returns {void}
      */
     set value(newVal) {
@@ -121,8 +126,8 @@
      * The watcher will receive the new value as its argument.
      *
      * @public
-     * @param {function(T): void} fn - The callback function to invoke on value change, where T is the value type.
-     * @returns {function(): boolean} A function to unsubscribe the watcher.
+     * @param {(value: T) => void} fn - The callback function to invoke on value change.
+     * @returns {() => boolean} A function to unsubscribe the watcher.
      * @example
      * const unsubscribe = signal.watch((value) => console.log(value));
      * // Later...
@@ -145,6 +150,7 @@
       if (this._pending) return;
       this._pending = true;
       queueMicrotask(() => {
+        /** @type {(fn: (value: T) => void) => void} */
         this._watchers.forEach(fn => fn(this._value));
         this._pending = false;
       });
@@ -156,6 +162,9 @@
    * @classdesc A robust event emitter that enables inter-component communication through a publish-subscribe pattern.
    * Components can emit events and listen for events from other components, facilitating loose coupling
    * and reactive updates across the application.
+   * Events are handled synchronously in the order they were registered, with proper cleanup
+   * of unsubscribed handlers.
+   * Event names should follow the format 'namespace:action' (e.g., 'user:login', 'cart:update').
    *
    * @example
    * const emitter = new Emitter();
@@ -169,18 +178,19 @@
      * @public
      */
     constructor() {
-      /** @private {Map<string, Set<function(any): void>>} Map of event names to their registered handler functions */
+      /** @private {Map<string, Set<(data: unknown) => void>>} Map of event names to their registered handler functions */
       this._events = new Map();
     }
 
     /**
      * Registers an event handler for the specified event name.
      * The handler will be called with the event data when the event is emitted.
+     * Event names should follow the format 'namespace:action' for consistency.
      *
      * @public
-     * @param {string} event - The name of the event to listen for.
-     * @param {function(any): void} handler - The callback function to invoke when the event occurs.
-     * @returns {function(): void} A function to unsubscribe the event handler.
+     * @param {string} event - The name of the event to listen for (e.g., 'user:login').
+     * @param {(data: unknown) => void} handler - The callback function to invoke when the event occurs.
+     * @returns {() => void} A function to unsubscribe the event handler.
      * @example
      * const unsubscribe = emitter.on('user:login', (user) => console.log(user));
      * // Later...
@@ -195,11 +205,17 @@
     /**
      * Removes an event handler for the specified event name.
      * If no handler is provided, all handlers for the event are removed.
+     * Automatically cleans up empty event sets to prevent memory leaks.
      *
      * @public
-     * @param {string} event - The name of the event.
-     * @param {function(any): void} [handler] - The specific handler function to remove.
+     * @param {string} event - The name of the event to remove handlers from.
+     * @param {(data: unknown) => void} [handler] - The specific handler function to remove.
      * @returns {void}
+     * @example
+     * // Remove a specific handler
+     * emitter.off('user:login', loginHandler);
+     * // Remove all handlers for an event
+     * emitter.off('user:login');
      */
     off(event, handler) {
       if (!this._events.has(event)) return;
@@ -216,11 +232,17 @@
     /**
      * Emits an event with the specified data to all registered handlers.
      * Handlers are called synchronously in the order they were registered.
+     * If no handlers are registered for the event, the emission is silently ignored.
      *
      * @public
      * @param {string} event - The name of the event to emit.
-     * @param {...any} args - Optional arguments to pass to the event handlers.
+     * @param {...unknown} args - Optional arguments to pass to the event handlers.
      * @returns {void}
+     * @example
+     * // Emit an event with data
+     * emitter.emit('user:login', { name: 'John', role: 'admin' });
+     * // Emit an event with multiple arguments
+     * emitter.emit('cart:update', { items: [] }, { total: 0 });
      */
     emit(event, ...args) {
       if (!this._events.has(event)) return;
@@ -228,11 +250,27 @@
     }
   }
 
+  /**
+   * A regular expression to match hyphenated lowercase letters.
+   * @private
+   * @type {RegExp}
+   */
+  const CAMEL_RE = /-([a-z])/g;
+
   /**
    * @class 🎨 Renderer
-   * @classdesc A DOM renderer that handles efficient DOM updates through patching and diffing.
-   * Provides methods for updating the DOM by comparing new and old structures and applying
-   * only the necessary changes, minimizing layout thrashing and improving performance.
+   * @classdesc A high-performance DOM renderer that implements an optimized direct DOM diffing algorithm.
+   *
+   * Key features:
+   * - Single-pass diffing algorithm for efficient DOM updates
+   * - Key-based node reconciliation for optimal performance
+   * - Intelligent attribute handling for ARIA, data attributes, and boolean properties
+   * - Preservation of special Eleva-managed instances and style elements
+   * - Memory-efficient with reusable temporary containers
+   *
+   * The renderer is designed to minimize DOM operations while maintaining
+   * exact attribute synchronization and proper node identity preservation.
+   * It's particularly optimized for frequent updates and complex DOM structures.
    *
    * @example
    * const renderer = new Renderer();
@@ -242,45 +280,45 @@
    */
   class Renderer {
     /**
-     * Creates a new Renderer instance with a reusable temporary container for parsing HTML.
+     * Creates a new Renderer instance.
      * @public
      */
     constructor() {
-      /** @private {HTMLElement} Reusable temporary container for parsing new HTML */
+      /**
+       * A temporary container to hold the new HTML content while diffing.
+       * @private
+       * @type {HTMLElement}
+       */
       this._tempContainer = document.createElement("div");
     }
 
     /**
-     * Patches the DOM of a container element with new HTML content.
-     * Efficiently updates the DOM by parsing new HTML into a reusable container
-     * and applying only the necessary changes.
+     * Patches the DOM of the given container with the provided HTML string.
      *
      * @public
      * @param {HTMLElement} container - The container element to patch.
-     * @param {string} newHtml - The new HTML content to apply.
+     * @param {string} newHtml - The new HTML string.
      * @returns {void}
-     * @throws {Error} If container is not an HTMLElement, newHtml is not a string, or patching fails.
+     * @throws {TypeError} If container is not an HTMLElement or newHtml is not a string.
+     * @throws {Error} If DOM patching fails.
      */
     patchDOM(container, newHtml) {
       if (!(container instanceof HTMLElement)) {
-        throw new Error("Container must be an HTMLElement");
+        throw new TypeError("Container must be an HTMLElement");
       }
       if (typeof newHtml !== "string") {
-        throw new Error("newHtml must be a string");
+        throw new TypeError("newHtml must be a string");
       }
       try {
-        // Directly set new HTML, replacing any existing content
         this._tempContainer.innerHTML = newHtml;
         this._diff(container, this._tempContainer);
-      } catch {
-        throw new Error("Failed to patch DOM");
+      } catch (error) {
+        throw new Error(`Failed to patch DOM: ${error.message}`);
       }
     }
 
     /**
-     * Diffs two DOM trees (old and new) and applies updates to the old DOM.
-     * This method recursively compares nodes and their attributes, applying only
-     * the necessary changes to minimize DOM operations.
+     * Performs a diff between two DOM nodes and patches the old node to match the new node.
      *
      * @private
      * @param {HTMLElement} oldParent - The original DOM element.
@@ -288,75 +326,114 @@
      * @returns {void}
      */
     _diff(oldParent, newParent) {
-      if (oldParent.isEqualNode(newParent)) return;
-      const oldChildren = oldParent.childNodes;
-      const newChildren = newParent.childNodes;
-      const maxLength = Math.max(oldChildren.length, newChildren.length);
-      for (let i = 0; i < maxLength; i++) {
-        const oldNode = oldChildren[i];
-        const newNode = newChildren[i];
-        if (oldNode?._eleva_instance) {
-          continue;
-        }
-        if (!oldNode && newNode) {
-          oldParent.appendChild(newNode.cloneNode(true));
-          continue;
-        }
-        if (oldNode && !newNode) {
-          if (oldNode.nodeName === "STYLE" && oldNode.hasAttribute("data-e-style")) {
-            continue;
+      if (oldParent === newParent || oldParent.isEqualNode?.(newParent)) return;
+      const oldChildren = Array.from(oldParent.childNodes);
+      const newChildren = Array.from(newParent.childNodes);
+      let oldStartIdx = 0,
+        newStartIdx = 0;
+      let oldEndIdx = oldChildren.length - 1;
+      let newEndIdx = newChildren.length - 1;
+      let oldKeyMap = null;
+      while (oldStartIdx <= oldEndIdx && newStartIdx <= newEndIdx) {
+        let oldStartNode = oldChildren[oldStartIdx];
+        let newStartNode = newChildren[newStartIdx];
+        if (!oldStartNode) {
+          oldStartNode = oldChildren[++oldStartIdx];
+        } else if (this._isSameNode(oldStartNode, newStartNode)) {
+          this._patchNode(oldStartNode, newStartNode);
+          oldStartIdx++;
+          newStartIdx++;
+        } else {
+          if (!oldKeyMap) {
+            oldKeyMap = this._createKeyMap(oldChildren, oldStartIdx, oldEndIdx);
+          }
+          const key = this._getNodeKey(newStartNode);
+          const oldNodeToMove = key ? oldKeyMap.get(key) : null;
+          if (oldNodeToMove) {
+            this._patchNode(oldNodeToMove, newStartNode);
+            oldParent.insertBefore(oldNodeToMove, oldStartNode);
+            oldChildren[oldChildren.indexOf(oldNodeToMove)] = null;
+          } else {
+            oldParent.insertBefore(newStartNode.cloneNode(true), oldStartNode);
           }
-          oldParent.removeChild(oldNode);
-          continue;
+          newStartIdx++;
         }
-        const isSameType = oldNode.nodeType === newNode.nodeType && oldNode.nodeName === newNode.nodeName;
-        if (!isSameType) {
-          oldParent.replaceChild(newNode.cloneNode(true), oldNode);
-          continue;
+      }
+      if (oldStartIdx > oldEndIdx) {
+        const refNode = newChildren[newEndIdx + 1] ? oldChildren[oldStartIdx] : null;
+        for (let i = newStartIdx; i <= newEndIdx; i++) {
+          if (newChildren[i]) oldParent.insertBefore(newChildren[i].cloneNode(true), refNode);
         }
-        if (oldNode.nodeType === Node.ELEMENT_NODE) {
-          const oldKey = oldNode.getAttribute("key");
-          const newKey = newNode.getAttribute("key");
-          if (oldKey !== newKey && (oldKey || newKey)) {
-            oldParent.replaceChild(newNode.cloneNode(true), oldNode);
-            continue;
-          }
-          this._updateAttributes(oldNode, newNode);
-          this._diff(oldNode, newNode);
-        } else if (oldNode.nodeType === Node.TEXT_NODE && oldNode.nodeValue !== newNode.nodeValue) {
-          oldNode.nodeValue = newNode.nodeValue;
+      } else if (newStartIdx > newEndIdx) {
+        for (let i = oldStartIdx; i <= oldEndIdx; i++) {
+          if (oldChildren[i]) this._removeNode(oldParent, oldChildren[i]);
         }
       }
     }
 
     /**
-     * Updates the attributes of an element to match those of a new element.
-     * Handles special cases for ARIA attributes, data attributes, and boolean properties.
+     * Patches a single node.
+     *
+     * @private
+     * @param {Node} oldNode - The original DOM node.
+     * @param {Node} newNode - The new DOM node.
+     * @returns {void}
+     */
+    _patchNode(oldNode, newNode) {
+      if (oldNode?._eleva_instance) return;
+      if (!this._isSameNode(oldNode, newNode)) {
+        oldNode.replaceWith(newNode.cloneNode(true));
+        return;
+      }
+      if (oldNode.nodeType === Node.ELEMENT_NODE) {
+        this._updateAttributes(oldNode, newNode);
+        this._diff(oldNode, newNode);
+      } else if (oldNode.nodeType === Node.TEXT_NODE && oldNode.nodeValue !== newNode.nodeValue) {
+        oldNode.nodeValue = newNode.nodeValue;
+      }
+    }
+
+    /**
+     * Removes a node from its parent.
+     *
+     * @private
+     * @param {HTMLElement} parent - The parent element containing the node to remove.
+     * @param {Node} node - The node to remove.
+     * @returns {void}
+     */
+    _removeNode(parent, node) {
+      if (node.nodeName === "STYLE" && node.hasAttribute("data-e-style")) return;
+      parent.removeChild(node);
+    }
+
+    /**
+     * Updates the attributes of an element to match a new element's attributes.
      *
      * @private
-     * @param {HTMLElement} oldEl - The element to update.
-     * @param {HTMLElement} newEl - The element providing the updated attributes.
+     * @param {HTMLElement} oldEl - The original element to update.
+     * @param {HTMLElement} newEl - The new element to update.
      * @returns {void}
      */
     _updateAttributes(oldEl, newEl) {
       const oldAttrs = oldEl.attributes;
       const newAttrs = newEl.attributes;
 
-      // Update/add new attributes
-      for (const {
-        name,
-        value
-      } of newAttrs) {
+      // Single pass for new/updated attributes
+      for (let i = 0; i < newAttrs.length; i++) {
+        const {
+          name,
+          value
+        } = newAttrs[i];
         if (name.startsWith("@")) continue;
         if (oldEl.getAttribute(name) === value) continue;
         oldEl.setAttribute(name, value);
         if (name.startsWith("aria-")) {
-          const prop = "aria" + name.slice(5).replace(/-([a-z])/g, (_, l) => l.toUpperCase());
+          const prop = "aria" + name.slice(5).replace(CAMEL_RE, (_, l) => l.toUpperCase());
           oldEl[prop] = value;
         } else if (name.startsWith("data-")) {
           oldEl.dataset[name.slice(5)] = value;
         } else {
-          const prop = name.replace(/-([a-z])/g, (_, l) => l.toUpperCase());
+          const prop = name.replace(CAMEL_RE, (_, l) => l.toUpperCase());
           if (prop in oldEl) {
             const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(oldEl), prop);
             const isBoolean = typeof oldEl[prop] === "boolean" || descriptor?.get && typeof descriptor.get.call(oldEl) === "boolean";
@@ -369,47 +446,134 @@
         }
       }
 
-      // Remove old attributes
-      for (const {
-        name
-      } of oldAttrs) {
+      // Remove any attributes no longer present
+      for (let i = oldAttrs.length - 1; i >= 0; i--) {
+        const name = oldAttrs[i].name;
         if (!newEl.hasAttribute(name)) {
           oldEl.removeAttribute(name);
         }
       }
     }
+
+    /**
+     * Determines if two nodes are the same based on their type, name, and key attributes.
+     *
+     * @private
+     * @param {Node} oldNode - The first node to compare.
+     * @param {Node} newNode - The second node to compare.
+     * @returns {boolean} True if the nodes are considered the same, false otherwise.
+     */
+    _isSameNode(oldNode, newNode) {
+      if (!oldNode || !newNode) return false;
+      const oldKey = oldNode.nodeType === Node.ELEMENT_NODE ? oldNode.getAttribute("key") : null;
+      const newKey = newNode.nodeType === Node.ELEMENT_NODE ? newNode.getAttribute("key") : null;
+      if (oldKey && newKey) return oldKey === newKey;
+      return !oldKey && !newKey && oldNode.nodeType === newNode.nodeType && oldNode.nodeName === newNode.nodeName;
+    }
+
+    /**
+     * Creates a key map for the children of a parent node.
+     *
+     * @private
+     * @param {Array<Node>} children - The children of the parent node.
+     * @param {number} start - The start index of the children.
+     * @param {number} end - The end index of the children.
+     * @returns {Map<string, Node>} A key map for the children.
+     */
+    _createKeyMap(children, start, end) {
+      const map = new Map();
+      for (let i = start; i <= end; i++) {
+        const child = children[i];
+        const key = this._getNodeKey(child);
+        if (key) map.set(key, child);
+      }
+      return map;
+    }
+
+    /**
+     * Extracts the key attribute from a node if it exists.
+     *
+     * @private
+     * @param {Node} node - The node to extract the key from.
+     * @returns {string|null} The key attribute value or null if not found.
+     */
+    _getNodeKey(node) {
+      return node?.nodeType === Node.ELEMENT_NODE ? node.getAttribute("key") : null;
+    }
   }
 
   /**
    * @typedef {Object} ComponentDefinition
-   * @property {function(Object<string, any>): (Object<string, any>|Promise<Object<string, any>>)} [setup]
+   * @property {function(ComponentContext): (Record<string, unknown>|Promise<Record<string, unknown>>)} [setup]
    *           Optional setup function that initializes the component's state and returns reactive data
-   * @property {(function(Object<string, any>): string|Promise<string>|string)} template
+   * @property {(function(ComponentContext): string|Promise<string>)} template
    *           Required function that defines the component's HTML structure
-   * @property {(function(Object<string, any>): string)|string} [style]
+   * @property {(function(ComponentContext): string)|string} [style]
    *           Optional function or string that provides component-scoped CSS styles
-   * @property {Object<string, ComponentDefinition>} [children]
+   * @property {Record<string, ComponentDefinition>} [children]
    *           Optional object defining nested child components
    */
 
   /**
-   * @typedef {Object} ElevaPlugin
-   * @property {function(Eleva, Object<string, any>): void} install
-   *           Function that installs the plugin into the Eleva instance
-   * @property {string} name
-   *           Unique identifier name for the plugin
+   * @typedef {Object} ComponentContext
+   * @property {Record<string, unknown>} props
+   *           Component properties passed during mounting
+   * @property {Emitter} emitter
+   *           Event emitter instance for component event handling
+   * @property {function<T>(value: T): Signal<T>} signal
+   *           Factory function to create reactive Signal instances
+   * @property {function(LifecycleHookContext): Promise<void>} [onBeforeMount]
+   *           Hook called before component mounting
+   * @property {function(LifecycleHookContext): Promise<void>} [onMount]
+   *           Hook called after component mounting
+   * @property {function(LifecycleHookContext): Promise<void>} [onBeforeUpdate]
+   *           Hook called before component update
+   * @property {function(LifecycleHookContext): Promise<void>} [onUpdate]
+   *           Hook called after component update
+   * @property {function(UnmountHookContext): Promise<void>} [onUnmount]
+   *           Hook called during component unmounting
+   */
+
+  /**
+   * @typedef {Object} LifecycleHookContext
+   * @property {HTMLElement} container
+   *           The DOM element where the component is mounted
+   * @property {ComponentContext} context
+   *           The component's reactive state and context data
+   */
+
+  /**
+   * @typedef {Object} UnmountHookContext
+   * @property {HTMLElement} container
+   *           The DOM element where the component is mounted
+   * @property {ComponentContext} context
+   *           The component's reactive state and context data
+   * @property {{
+   *   watchers: Array<() => void>,    // Signal watcher cleanup functions
+   *   listeners: Array<() => void>,   // Event listener cleanup functions
+   *   children: Array<MountResult>    // Child component instances
+   * }} cleanup
+   *           Object containing cleanup functions and instances
    */
 
   /**
    * @typedef {Object} MountResult
    * @property {HTMLElement} container
    *           The DOM element where the component is mounted
-   * @property {Object<string, any>} data
+   * @property {ComponentContext} data
    *           The component's reactive state and context data
-   * @property {function(): void} unmount
+   * @property {function(): Promise<void>} unmount
    *           Function to clean up and unmount the component
    */
 
+  /**
+   * @typedef {Object} ElevaPlugin
+   * @property {function(Eleva, Record<string, unknown>): void} install
+   *           Function that installs the plugin into the Eleva instance
+   * @property {string} name
+   *           Unique identifier name for the plugin
+   */
+
   /**
    * @class 🧩 Eleva
    * @classdesc A modern, signal-based component runtime framework that provides lifecycle hooks,
@@ -417,12 +581,26 @@
    * event handling, and DOM rendering with a focus on performance and developer experience.
    *
    * @example
+   * // Basic component creation and mounting
    * const app = new Eleva("myApp");
    * app.component("myComponent", {
-   *   template: (ctx) => `<div>Hello ${ctx.props.name}</div>`,
-   *   setup: (ctx) => ({ count: new Signal(0) })
+   *   setup: (ctx) => ({ count: ctx.signal(0) }),
+   *   template: (ctx) => `<div>Hello ${ctx.props.name}</div>`
    * });
    * app.mount(document.getElementById("app"), "myComponent", { name: "World" });
+   *
+   * @example
+   * // Using lifecycle hooks
+   * app.component("lifecycleDemo", {
+   *   setup: () => {
+   *     return {
+   *       onMount: ({ container, context }) => {
+   *         console.log('Component mounted!');
+   *       }
+   *     };
+   *   },
+   *   template: `<div>Lifecycle Demo</div>`
+   * });
    */
   class Eleva {
     /**
@@ -430,13 +608,24 @@
      *
      * @public
      * @param {string} name - The unique identifier name for this Eleva instance.
-     * @param {Object<string, any>} [config={}] - Optional configuration object for the instance.
+     * @param {Record<string, unknown>} [config={}] - Optional configuration object for the instance.
      *        May include framework-wide settings and default behaviors.
+     * @throws {Error} If the name is not provided or is not a string.
+     * @returns {Eleva} A new Eleva instance.
+     *
+     * @example
+     * const app = new Eleva("myApp");
+     * app.component("myComponent", {
+     *   setup: (ctx) => ({ count: ctx.signal(0) }),
+     *   template: (ctx) => `<div>Hello ${ctx.props.name}!</div>`
+     * });
+     * app.mount(document.getElementById("app"), "myComponent", { name: "World" });
+     *
      */
     constructor(name, config = {}) {
       /** @public {string} The unique identifier name for this Eleva instance */
       this.name = name;
-      /** @public {Object<string, any>} Optional configuration object for the Eleva instance */
+      /** @public {Object<string, unknown>} Optional configuration object for the Eleva instance */
       this.config = config;
       /** @public {Emitter} Instance of the event emitter for handling component events */
       this.emitter = new Emitter();
@@ -449,8 +638,6 @@
       this._components = new Map();
       /** @private {Map<string, ElevaPlugin>} Collection of installed plugin instances by name */
       this._plugins = new Map();
-      /** @private {string[]} Array of lifecycle hook names supported by components */
-      this._lifecycleHooks = ["onBeforeMount", "onMount", "onBeforeUpdate", "onUpdate", "onUnmount"];
       /** @private {boolean} Flag indicating if the root component is currently mounted */
       this._isMounted = false;
     }
@@ -462,7 +649,7 @@
      *
      * @public
      * @param {ElevaPlugin} plugin - The plugin object which must have an `install` function.
-     * @param {Object<string, any>} [options={}] - Optional configuration options for the plugin.
+     * @param {Object<string, unknown>} [options={}] - Optional configuration options for the plugin.
      * @returns {Eleva} The Eleva instance (for method chaining).
      * @example
      * app.use(myPlugin, { option1: "value1" });
@@ -501,7 +688,7 @@
      * @public
      * @param {HTMLElement} container - The DOM element where the component will be mounted.
      * @param {string|ComponentDefinition} compName - The name of the registered component or a direct component definition.
-     * @param {Object<string, any>} [props={}] - Optional properties to pass to the component.
+     * @param {Object<string, unknown>} [props={}] - Optional properties to pass to the component.
      * @returns {Promise<MountResult>}
      *          A Promise that resolves to an object containing:
      *          - container: The mounted component's container element
@@ -535,21 +722,12 @@
         children
       } = definition;
 
-      /**
-       * Creates the initial context object for the component instance.
-       * This context provides core functionality and will be merged with setup data.
-       * @type {Object<string, any>}
-       * @property {Object<string, any>} props - Component properties passed during mounting
-       * @property {Emitter} emitter - Event emitter instance for component event handling
-       * @property {function(any): Signal} signal - Factory function to create reactive Signal instances
-       * @property {Object<string, function(): void>} ...lifecycleHooks - Prepared lifecycle hook functions
-       */
+      /** @type {ComponentContext} */
       const context = {
         props,
         emitter: this.emitter,
-        /** @type {(v: any) => Signal<any>} */
-        signal: v => new this.signal(v),
-        ...this._prepareLifecycleHooks()
+        /** @type {(v: unknown) => Signal<unknown>} */
+        signal: v => new this.signal(v)
       };
 
       /**
@@ -560,30 +738,38 @@
        * 3. Rendering the component
        * 4. Managing component lifecycle
        *
-       * @param {Object<string, any>} data - Data returned from the component's setup function
+       * @param {Object<string, unknown>} data - Data returned from the component's setup function
        * @returns {Promise<MountResult>} An object containing:
        *   - container: The mounted component's container element
        *   - data: The component's reactive state and context
        *   - unmount: Function to clean up and unmount the component
        */
       const processMount = async data => {
-        /** @type {Object<string, any>} */
+        /** @type {ComponentContext} */
         const mergedContext = {
           ...context,
           ...data
         };
         /** @type {Array<() => void>} */
-        const watcherUnsubscribers = [];
+        const watchers = [];
         /** @type {Array<MountResult>} */
         const childInstances = [];
         /** @type {Array<() => void>} */
-        const cleanupListeners = [];
+        const listeners = [];
 
         // Execute before hooks
         if (!this._isMounted) {
-          mergedContext.onBeforeMount && mergedContext.onBeforeMount();
+          /** @type {LifecycleHookContext} */
+          await mergedContext.onBeforeMount?.({
+            container,
+            context: mergedContext
+          });
         } else {
-          mergedContext.onBeforeUpdate && mergedContext.onBeforeUpdate();
+          /** @type {LifecycleHookContext} */
+          await mergedContext.onBeforeUpdate?.({
+            container,
+            context: mergedContext
+          });
         }
 
         /**
@@ -596,14 +782,22 @@
           const templateResult = typeof template === "function" ? await template(mergedContext) : template;
           const newHtml = TemplateEngine.parse(templateResult, mergedContext);
           this.renderer.patchDOM(container, newHtml);
-          this._processEvents(container, mergedContext, cleanupListeners);
+          this._processEvents(container, mergedContext, listeners);
           if (style) this._injectStyles(container, compName, style, mergedContext);
           if (children) await this._mountComponents(container, children, childInstances);
           if (!this._isMounted) {
-            mergedContext.onMount && mergedContext.onMount();
+            /** @type {LifecycleHookContext} */
+            await mergedContext.onMount?.({
+              container,
+              context: mergedContext
+            });
             this._isMounted = true;
           } else {
-            mergedContext.onUpdate && mergedContext.onUpdate();
+            /** @type {LifecycleHookContext} */
+            await mergedContext.onUpdate?.({
+              container,
+              context: mergedContext
+            });
           }
         };
 
@@ -613,7 +807,7 @@
          * Stores unsubscribe functions to clean up watchers when component unmounts.
          */
         for (const val of Object.values(data)) {
-          if (val instanceof Signal) watcherUnsubscribers.push(val.watch(render));
+          if (val instanceof Signal) watchers.push(val.watch(render));
         }
         await render();
         const instance = {
@@ -624,11 +818,20 @@
            *
            * @returns {void}
            */
-          unmount: () => {
-            for (const fn of watcherUnsubscribers) fn();
-            for (const fn of cleanupListeners) fn();
-            for (const child of childInstances) child.unmount();
-            mergedContext.onUnmount && mergedContext.onUnmount();
+          unmount: async () => {
+            /** @type {UnmountHookContext} */
+            await mergedContext.onUnmount?.({
+              container,
+              context: mergedContext,
+              cleanup: {
+                watchers: watchers,
+                listeners: listeners,
+                children: childInstances
+              }
+            });
+            for (const fn of watchers) fn();
+            for (const fn of listeners) fn();
+            for (const child of childInstances) await child.unmount();
             container.innerHTML = "";
             delete container._eleva_instance;
           }
@@ -642,47 +845,37 @@
       return await processMount(setupResult);
     }
 
-    /**
-     * Prepares default no-operation lifecycle hook functions for a component.
-     * These hooks will be called at various stages of the component's lifecycle.
-     *
-     * @private
-     * @returns {Object<string, function(): void>} An object mapping lifecycle hook names to empty functions.
-     *         The returned object will be merged with the component's context.
-     */
-    _prepareLifecycleHooks() {
-      /** @type {Object<string, () => void>} */
-      const hooks = {};
-      for (const hook of this._lifecycleHooks) {
-        hooks[hook] = () => {};
-      }
-      return hooks;
-    }
-
     /**
      * Processes DOM elements for event binding based on attributes starting with "@".
      * This method handles the event delegation system and ensures proper cleanup of event listeners.
      *
      * @private
      * @param {HTMLElement} container - The container element in which to search for event attributes.
-     * @param {Object<string, any>} context - The current component context containing event handler definitions.
-     * @param {Array<Function>} cleanupListeners - Array to collect cleanup functions for each event listener.
+     * @param {ComponentContext} context - The current component context containing event handler definitions.
+     * @param {Array<() => void>} listeners - Array to collect cleanup functions for each event listener.
      * @returns {void}
      */
-    _processEvents(container, context, cleanupListeners) {
+    _processEvents(container, context, listeners) {
+      /** @type {NodeListOf<Element>} */
       const elements = container.querySelectorAll("*");
       for (const el of elements) {
+        /** @type {NamedNodeMap} */
         const attrs = el.attributes;
         for (let i = 0; i < attrs.length; i++) {
+          /** @type {Attr} */
           const attr = attrs[i];
           if (!attr.name.startsWith("@")) continue;
+
+          /** @type {keyof HTMLElementEventMap} */
           const event = attr.name.slice(1);
+          /** @type {string} */
           const handlerName = attr.value;
+          /** @type {(event: Event) => void} */
           const handler = context[handlerName] || TemplateEngine.evaluate(handlerName, context);
           if (typeof handler === "function") {
             el.addEventListener(event, handler);
             el.removeAttribute(attr.name);
-            cleanupListeners.push(() => el.removeEventListener(event, handler));
+            listeners.push(() => el.removeEventListener(event, handler));
           }
         }
       }
@@ -695,12 +888,14 @@
      * @private
      * @param {HTMLElement} container - The container element where styles should be injected.
      * @param {string} compName - The component name used to identify the style element.
-     * @param {(function(Object<string, any>): string)|string} styleDef - The component's style definition (function or string).
-     * @param {Object<string, any>} context - The current component context for style interpolation.
+     * @param {(function(ComponentContext): string)|string} styleDef - The component's style definition (function or string).
+     * @param {ComponentContext} context - The current component context for style interpolation.
      * @returns {void}
      */
     _injectStyles(container, compName, styleDef, context) {
+      /** @type {string} */
       const newStyle = typeof styleDef === "function" ? TemplateEngine.parse(styleDef(context), context) : styleDef;
+      /** @type {HTMLStyleElement|null} */
       let styleEl = container.querySelector(`style[data-e-style="${compName}"]`);
       if (styleEl && styleEl.textContent === newStyle) return;
       if (!styleEl) {
@@ -718,7 +913,7 @@
      * @private
      * @param {HTMLElement} element - The DOM element to extract props from
      * @param {string} prefix - The prefix to look for in attributes
-     * @returns {Object<string, any>} An object containing the extracted props
+     * @returns {Record<string, string>} An object containing the extracted props
      * @example
      * // For an element with attributes:
      * // <div :name="John" :age="25">
@@ -764,7 +959,9 @@
         if (!selector) continue;
         for (const el of container.querySelectorAll(selector)) {
           if (!(el instanceof HTMLElement)) continue;
+          /** @type {Record<string, string>} */
           const props = this._extractProps(el, ":");
+          /** @type {MountResult} */
           const instance = await this.mount(el, component, props);
           if (instance && !childInstances.includes(instance)) {
             childInstances.push(instance);