eleva 1.0.0-rc.1 → 1.0.0-rc.11

package/dist/eleva.esm.js

@@ -1,18 +1,76 @@
-/*! Eleva v1.0.0-rc.1 | MIT License | https://elevajs.com */
+/*! Eleva v1.0.0-rc.11 | MIT License | https://elevajs.com */
+// ============================================================================
+// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// ============================================================================
+
+/**
+ * @typedef {Record<string, unknown>} TemplateData
+ *           Data context for template interpolation
+ */
+
+/**
+ * @typedef {string} TemplateString
+ *           A string containing {{ expression }} interpolation markers
+ */
+
+/**
+ * @typedef {string} Expression
+ *           A JavaScript expression to be evaluated in the data context
+ */
+
+/**
+ * @typedef {unknown} EvaluationResult
+ *           The result of evaluating an expression (string, number, boolean, object, etc.)
+ */
+
 /**
  * @class 🔒 TemplateEngine
  * @classdesc A secure template engine that handles interpolation and dynamic attribute parsing.
- * Provides a safe way to evaluate expressions in templates while preventing XSS attacks.
+ * Provides a way to evaluate expressions in templates.
  * All methods are static and can be called directly on the class.
  *
+ * Template Syntax:
+ * - `{{ expression }}` - Interpolate any JavaScript expression
+ * - `{{ variable }}` - Access data properties directly
+ * - `{{ object.property }}` - Access nested properties
+ * - `{{ condition ? a : b }}` - Ternary expressions
+ * - `{{ func(arg) }}` - Call functions from data context
+ *
  * @example
+ * // Basic interpolation
  * const template = "Hello, {{name}}!";
  * const data = { name: "World" };
- * const result = TemplateEngine.parse(template, data); // Returns: "Hello, World!"
+ * const result = TemplateEngine.parse(template, data);
+ * // Result: "Hello, World!"
+ *
+ * @example
+ * // Nested properties
+ * const template = "Welcome, {{user.name}}!";
+ * const data = { user: { name: "John" } };
+ * const result = TemplateEngine.parse(template, data);
+ * // Result: "Welcome, John!"
+ *
+ * @example
+ * // Expressions
+ * const template = "Status: {{active ? 'Online' : 'Offline'}}";
+ * const data = { active: true };
+ * const result = TemplateEngine.parse(template, data);
+ * // Result: "Status: Online"
+ *
+ * @example
+ * // With Signal values
+ * const template = "Count: {{count.value}}";
+ * const data = { count: { value: 42 } };
+ * const result = TemplateEngine.parse(template, data);
+ * // Result: "Count: 42"
  */
 class TemplateEngine {
   /**
-   * @private {RegExp} Regular expression for matching template expressions in the format {{ expression }}
+   * Regular expression for matching template expressions in the format {{ expression }}
+   * Matches: {{ anything }} with optional whitespace inside braces
+   *
+   * @static
+   * @private
    * @type {RegExp}
    */
   static expressionPattern = /\{\{\s*(.*?)\s*\}\}/g;
@@ -23,13 +81,37 @@ class TemplateEngine {
    *
    * @public
    * @static
-   * @param {string} template - The template string to parse.
-   * @param {Record<string, unknown>} data - The data context for evaluating expressions.
+   * @param {TemplateString|unknown} template - The template string to parse.
+   * @param {TemplateData} 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", {
+   * // Simple variables
+   * TemplateEngine.parse("Hello, {{name}}!", { name: "World" });
+   * // Result: "Hello, World!"
+   *
+   * @example
+   * // Nested properties
+   * TemplateEngine.parse("{{user.name}} is {{user.age}} years old", {
    *   user: { name: "John", age: 30 }
-   * }); // Returns: "John is 30 years old"
+   * });
+   * // Result: "John is 30 years old"
+   *
+   * @example
+   * // Multiple expressions
+   * TemplateEngine.parse("{{greeting}}, {{name}}! You have {{count}} messages.", {
+   *   greeting: "Hello",
+   *   name: "User",
+   *   count: 5
+   * });
+   * // Result: "Hello, User! You have 5 messages."
+   *
+   * @example
+   * // With conditionals
+   * TemplateEngine.parse("Status: {{online ? 'Active' : 'Inactive'}}", {
+   *   online: true
+   * });
+   * // Result: "Status: Active"
    */
   static parse(template, data) {
     if (typeof template !== "string") return template;
@@ -38,18 +120,44 @@ class TemplateEngine {
 
   /**
    * 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.
+   * Only use with trusted templates. User input should never be directly interpolated.
    *
    * @public
    * @static
-   * @param {string} expression - The expression to evaluate.
-   * @param {Record<string, unknown>} data - The data context for evaluation.
-   * @returns {unknown} The result of the evaluation, or an empty string if evaluation fails.
+   * @param {Expression|unknown} expression - The expression to evaluate.
+   * @param {TemplateData} data - The data context for evaluation.
+   * @returns {EvaluationResult} The result of the evaluation, or an empty string if evaluation fails.
+   *
+   * @example
+   * // Property access
+   * TemplateEngine.evaluate("user.name", { user: { name: "John" } });
+   * // Result: "John"
+   *
+   * @example
+   * // Numeric values
+   * TemplateEngine.evaluate("user.age", { user: { age: 30 } });
+   * // Result: 30
+   *
    * @example
-   * const result = TemplateEngine.evaluate("user.name", { user: { name: "John" } }); // Returns: "John"
-   * const age = TemplateEngine.evaluate("user.age", { user: { age: 30 } }); // Returns: 30
+   * // Expressions
+   * TemplateEngine.evaluate("items.length > 0", { items: [1, 2, 3] });
+   * // Result: true
+   *
+   * @example
+   * // Function calls
+   * TemplateEngine.evaluate("formatDate(date)", {
+   *   date: new Date(),
+   *   formatDate: (d) => d.toISOString()
+   * });
+   * // Result: "2024-01-01T00:00:00.000Z"
+   *
+   * @example
+   * // Failed evaluation returns empty string
+   * TemplateEngine.evaluate("nonexistent.property", {});
+   * // Result: ""
    */
   static evaluate(expression, data) {
     if (typeof expression !== "string") return expression;
@@ -61,6 +169,29 @@ class TemplateEngine {
   }
 }
 
+// ============================================================================
+// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// ============================================================================
+
+/**
+ * @template T
+ * @callback SignalWatcher
+ * @param {T} value - The new value of the signal
+ * @returns {void}
+ */
+
+/**
+ * @callback SignalUnsubscribe
+ * @returns {boolean} True if the watcher was successfully removed
+ */
+
+/**
+ * @template T
+ * @typedef {Object} SignalLike
+ * @property {T} value - The current value
+ * @property {function(SignalWatcher<T>): SignalUnsubscribe} watch - Subscribe to changes
+ */
+
 /**
  * @class ⚡ Signal
  * @classdesc A reactive data holder that enables fine-grained reactivity in the Eleva framework.
@@ -69,11 +200,29 @@ class TemplateEngine {
  * Updates are batched using microtasks to prevent multiple synchronous notifications.
  * The class is generic, allowing type-safe handling of any value type T.
  *
+ * @template T The type of value held by this signal
+ *
  * @example
+ * // Basic usage
  * const count = new Signal(0);
  * count.watch((value) => console.log(`Count changed to: ${value}`));
  * count.value = 1; // Logs: "Count changed to: 1"
- * @template T
+ *
+ * @example
+ * // With unsubscribe
+ * const name = new Signal("John");
+ * const unsubscribe = name.watch((value) => console.log(value));
+ * name.value = "Jane"; // Logs: "Jane"
+ * unsubscribe(); // Stop watching
+ * name.value = "Bob"; // No log output
+ *
+ * @example
+ * // With objects
+ * /** @type {Signal<{x: number, y: number}>} *\/
+ * const position = new Signal({ x: 0, y: 0 });
+ * position.value = { x: 10, y: 20 }; // Triggers watchers
+ *
+ * @implements {SignalLike<T>}
  */
 class Signal {
   /**
@@ -81,13 +230,39 @@ class Signal {
    *
    * @public
    * @param {T} value - The initial value of the signal.
+   *
+   * @example
+   * // Primitive types
+   * const count = new Signal(0);        // Signal<number>
+   * const name = new Signal("John");    // Signal<string>
+   * const active = new Signal(true);    // Signal<boolean>
+   *
+   * @example
+   * // Complex types (use JSDoc for type inference)
+   * /** @type {Signal<string[]>} *\/
+   * const items = new Signal([]);
+   *
+   * /** @type {Signal<{id: number, name: string} | null>} *\/
+   * const user = new Signal(null);
    */
   constructor(value) {
-    /** @private {T} Internal storage for the signal's current value */
+    /**
+     * Internal storage for the signal's current value
+     * @private
+     * @type {T}
+     */
     this._value = value;
-    /** @private {Set<(value: T) => void>} Collection of callback functions to be notified when value changes */
+    /**
+     * Collection of callback functions to be notified when value changes
+     * @private
+     * @type {Set<SignalWatcher<T>>}
+     */
     this._watchers = new Set();
-    /** @private {boolean} Flag to prevent multiple synchronous watcher notifications and batch updates into microtasks */
+    /**
+     * Flag to prevent multiple synchronous watcher notifications
+     * @private
+     * @type {boolean}
+     */
     this._pending = false;
   }
 
@@ -120,12 +295,22 @@ class Signal {
    * The watcher will receive the new value as its argument.
    *
    * @public
-   * @param {(value: T) => void} fn - The callback function to invoke on value change.
-   * @returns {() => boolean} A function to unsubscribe the watcher.
+   * @param {SignalWatcher<T>} fn - The callback function to invoke on value change.
+   * @returns {SignalUnsubscribe} A function to unsubscribe the watcher.
+   *
    * @example
+   * // Basic watching
    * const unsubscribe = signal.watch((value) => console.log(value));
-   * // Later...
-   * unsubscribe(); // Stops watching for changes
+   *
+   * @example
+   * // Stop watching
+   * unsubscribe(); // Returns true if watcher was removed
+   *
+   * @example
+   * // Multiple watchers
+   * const unsub1 = signal.watch((v) => console.log("Watcher 1:", v));
+   * const unsub2 = signal.watch((v) => console.log("Watcher 2:", v));
+   * signal.value = "test"; // Both watchers are called
    */
   watch(fn) {
     this._watchers.add(fn);
@@ -151,6 +336,34 @@ class Signal {
   }
 }
 
+// ============================================================================
+// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// ============================================================================
+
+/**
+ * @template T
+ * @callback EventHandler
+ * @param {...T} args - Event arguments
+ * @returns {void|Promise<void>}
+ */
+
+/**
+ * @callback EventUnsubscribe
+ * @returns {void}
+ */
+
+/**
+ * @typedef {`${string}:${string}`} EventName
+ *           Event names follow the format 'namespace:action' (e.g., 'user:login', 'cart:update')
+ */
+
+/**
+ * @typedef {Object} EmitterLike
+ * @property {function(string, EventHandler<unknown>): EventUnsubscribe} on - Subscribe to an event
+ * @property {function(string, EventHandler<unknown>=): void} off - Unsubscribe from an event
+ * @property {function(string, ...unknown): void} emit - Emit an event
+ */
+
 /**
  * @class 📡 Emitter
  * @classdesc A robust event emitter that enables inter-component communication through a publish-subscribe pattern.
@@ -158,21 +371,58 @@ class Signal {
  * 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').
+ *
+ * Event names should follow the format 'namespace:action' for consistency and organization.
  *
  * @example
+ * // Basic usage
  * const emitter = new Emitter();
  * emitter.on('user:login', (user) => console.log(`User logged in: ${user.name}`));
  * emitter.emit('user:login', { name: 'John' }); // Logs: "User logged in: John"
+ *
+ * @example
+ * // With unsubscribe
+ * const unsub = emitter.on('cart:update', (items) => {
+ *   console.log(`Cart has ${items.length} items`);
+ * });
+ * emitter.emit('cart:update', [{ id: 1, name: 'Book' }]); // Logs: "Cart has 1 items"
+ * unsub(); // Stop listening
+ * emitter.emit('cart:update', []); // No log output
+ *
+ * @example
+ * // Multiple arguments
+ * emitter.on('order:placed', (orderId, amount, currency) => {
+ *   console.log(`Order ${orderId}: ${amount} ${currency}`);
+ * });
+ * emitter.emit('order:placed', 'ORD-123', 99.99, 'USD');
+ *
+ * @example
+ * // Common event patterns
+ * // Lifecycle events
+ * emitter.on('component:mount', (component) => {});
+ * emitter.on('component:unmount', (component) => {});
+ * // State events
+ * emitter.on('state:change', (newState, oldState) => {});
+ * // Navigation events
+ * emitter.on('router:navigate', (to, from) => {});
+ *
+ * @implements {EmitterLike}
  */
 class Emitter {
   /**
    * Creates a new Emitter instance.
    *
    * @public
+   *
+   * @example
+   * const emitter = new Emitter();
    */
   constructor() {
-    /** @private {Map<string, Set<(data: unknown) => void>>} Map of event names to their registered handler functions */
+    /**
+     * Map of event names to their registered handler functions
+     * @private
+     * @type {Map<string, Set<EventHandler<unknown>>>}
+     */
     this._events = new Map();
   }
 
@@ -182,12 +432,23 @@ class Emitter {
    * Event names should follow the format 'namespace:action' for consistency.
    *
    * @public
+   * @template T
    * @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.
+   * @param {EventHandler<T>} handler - The callback function to invoke when the event occurs.
+   * @returns {EventUnsubscribe} A function to unsubscribe the event handler.
+   *
    * @example
+   * // Basic subscription
    * const unsubscribe = emitter.on('user:login', (user) => console.log(user));
-   * // Later...
+   *
+   * @example
+   * // Typed handler
+   * emitter.on('user:update', (/** @type {{id: number, name: string}} *\/ user) => {
+   *   console.log(`User ${user.id}: ${user.name}`);
+   * });
+   *
+   * @example
+   * // Cleanup
    * unsubscribe(); // Stops listening for the event
    */
   on(event, handler) {
@@ -202,12 +463,18 @@ class Emitter {
    * Automatically cleans up empty event sets to prevent memory leaks.
    *
    * @public
+   * @template T
    * @param {string} event - The name of the event to remove handlers from.
-   * @param {(data: unknown) => void} [handler] - The specific handler function to remove.
+   * @param {EventHandler<T>} [handler] - The specific handler function to remove.
    * @returns {void}
+   *
    * @example
    * // Remove a specific handler
+   * const loginHandler = (user) => console.log(user);
+   * emitter.on('user:login', loginHandler);
    * emitter.off('user:login', loginHandler);
+   *
+   * @example
    * // Remove all handlers for an event
    * emitter.off('user:login');
    */
@@ -229,14 +496,22 @@ class Emitter {
    * If no handlers are registered for the event, the emission is silently ignored.
    *
    * @public
+   * @template T
    * @param {string} event - The name of the event to emit.
-   * @param {...unknown} args - Optional arguments to pass to the event handlers.
+   * @param {...T} 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' });
+   *
+   * @example
    * // Emit an event with multiple arguments
-   * emitter.emit('cart:update', { items: [] }, { total: 0 });
+   * emitter.emit('order:placed', 'ORD-123', 99.99, 'USD');
+   *
+   * @example
+   * // Emit without data
+   * emitter.emit('app:ready');
    */
   emit(event, ...args) {
     if (!this._events.has(event)) return;
@@ -244,12 +519,27 @@ class Emitter {
   }
 }
 
+// ============================================================================
+// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// ============================================================================
+
+/**
+ * @typedef {Object} PatchOptions
+ * @property {boolean} [preserveStyles=true]
+ *           Whether to preserve style elements with data-e-style attribute
+ * @property {boolean} [preserveInstances=true]
+ *           Whether to preserve elements with _eleva_instance property
+ */
+
+/**
+ * @typedef {Map<string, Node>} KeyMap
+ *           Map of key attribute values to their corresponding DOM nodes
+ */
+
 /**
- * A regular expression to match hyphenated lowercase letters.
- * @private
- * @type {RegExp}
+ * @typedef {'ELEMENT_NODE'|'TEXT_NODE'|'COMMENT_NODE'|'DOCUMENT_FRAGMENT_NODE'} NodeTypeName
+ *           Common DOM node type names
  */
-const CAMEL_RE = /-([a-z])/g;
 
 /**
  * @class 🎨 Renderer
@@ -267,27 +557,50 @@ const CAMEL_RE = /-([a-z])/g;
  * It's particularly optimized for frequent updates and complex DOM structures.
  *
  * @example
+ * // Basic usage
  * const renderer = new Renderer();
  * const container = document.getElementById("app");
  * const newHtml = "<div>Updated content</div>";
  * renderer.patchDOM(container, newHtml);
+ *
+ * @example
+ * // With keyed elements for optimal list updates
+ * const listHtml = `
+ *   <ul>
+ *     <li key="item-1">First</li>
+ *     <li key="item-2">Second</li>
+ *     <li key="item-3">Third</li>
+ *   </ul>
+ * `;
+ * renderer.patchDOM(container, listHtml);
+ *
+ * @example
+ * // The renderer preserves Eleva-managed elements
+ * // Elements with _eleva_instance are not replaced during diffing
+ * // Style elements with data-e-style are preserved
  */
 class Renderer {
   /**
    * Creates a new Renderer instance.
+   *
    * @public
+   *
+   * @example
+   * const renderer = new Renderer();
    */
   constructor() {
     /**
      * A temporary container to hold the new HTML content while diffing.
+     * Reused across patch operations to minimize memory allocation.
      * @private
-     * @type {HTMLElement}
+     * @type {HTMLDivElement}
      */
     this._tempContainer = document.createElement("div");
   }
 
   /**
    * Patches the DOM of the given container with the provided HTML string.
+   * Uses an optimized diffing algorithm to minimize DOM operations.
    *
    * @public
    * @param {HTMLElement} container - The container element to patch.
@@ -295,6 +608,18 @@ class Renderer {
    * @returns {void}
    * @throws {TypeError} If container is not an HTMLElement or newHtml is not a string.
    * @throws {Error} If DOM patching fails.
+   *
+   * @example
+   * // Update container content
+   * renderer.patchDOM(container, '<div class="updated">New content</div>');
+   *
+   * @example
+   * // Update list with keys for optimal diffing
+   * const items = ['a', 'b', 'c'];
+   * const html = items.map(item =>
+   *   `<li key="${item}">${item}</li>`
+   * ).join('');
+   * renderer.patchDOM(listContainer, `<ul>${html}</ul>`);
    */
   patchDOM(container, newHtml) {
     if (!(container instanceof HTMLElement)) {
@@ -412,35 +737,24 @@ class Renderer {
     const oldAttrs = oldEl.attributes;
     const newAttrs = newEl.attributes;
 
-    // Single pass for new/updated attributes
+    // Process new attributes
     for (let i = 0; i < newAttrs.length; i++) {
       const {
         name,
         value
       } = newAttrs[i];
+
+      // Skip event attributes (handled by event system)
       if (name.startsWith("@")) continue;
+
+      // Skip if attribute hasn't changed
       if (oldEl.getAttribute(name) === value) continue;
+
+      // Basic attribute setting
       oldEl.setAttribute(name, value);
-      if (name.startsWith("aria-")) {
-        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(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";
-          if (isBoolean) {
-            oldEl[prop] = value !== "false" && (value === "" || value === prop || value === "true");
-          } else {
-            oldEl[prop] = value;
-          }
-        }
-      }
     }
 
-    // Remove any attributes no longer present
+    // Remove old attributes that are no longer present
     for (let i = oldAttrs.length - 1; i >= 0; i--) {
       const name = oldAttrs[i].name;
       if (!newEl.hasAttribute(name)) {
@@ -467,12 +781,13 @@ class Renderer {
 
   /**
    * Creates a key map for the children of a parent node.
+   * Used for efficient O(1) lookup of keyed elements during diffing.
    *
    * @private
-   * @param {Array<Node>} children - The children of the parent node.
+   * @param {Array<ChildNode>} 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.
+   * @returns {KeyMap} A key map for the children.
    */
   _createKeyMap(children, start, end) {
     const map = new Map();
@@ -496,43 +811,129 @@ class Renderer {
   }
 }
 
+// ============================================================================
+// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// ============================================================================
+
+// -----------------------------------------------------------------------------
+// Configuration Types
+// -----------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} ElevaConfig
+ * @property {boolean} [debug=false]
+ *           Enable debug mode for verbose logging
+ * @property {string} [prefix='e']
+ *           Prefix for component style scoping
+ * @property {boolean} [async=true]
+ *           Enable async component setup
+ */
+
+// -----------------------------------------------------------------------------
+// Component Types
+// -----------------------------------------------------------------------------
+
 /**
  * @typedef {Object} ComponentDefinition
- * @property {function(ComponentContext): (Record<string, unknown>|Promise<Record<string, unknown>>)} [setup]
+ * @property {SetupFunction} [setup]
  *           Optional setup function that initializes the component's state and returns reactive data
- * @property {(function(ComponentContext): string|Promise<string>)} template
- *           Required function that defines the component's HTML structure
- * @property {(function(ComponentContext): string)|string} [style]
+ * @property {TemplateFunction|string} template
+ *           Required function or string that defines the component's HTML structure
+ * @property {StyleFunction|string} [style]
  *           Optional function or string that provides component-scoped CSS styles
- * @property {Record<string, ComponentDefinition>} [children]
+ * @property {ChildrenMap} [children]
  *           Optional object defining nested child components
  */
 
+/**
+ * @callback SetupFunction
+ * @param {ComponentContext} ctx - The component context with props, emitter, and signal factory
+ * @returns {SetupResult|Promise<SetupResult>} Reactive data and lifecycle hooks
+ */
+
+/**
+ * @typedef {Record<string, unknown> & LifecycleHooks} SetupResult
+ *           Data returned from setup function, may include lifecycle hooks
+ */
+
+/**
+ * @callback TemplateFunction
+ * @param {ComponentContext} ctx - The component context
+ * @returns {string|Promise<string>} HTML template string
+ */
+
+/**
+ * @callback StyleFunction
+ * @param {ComponentContext} ctx - The component context
+ * @returns {string} CSS styles string
+ */
+
+/**
+ * @typedef {Record<string, ComponentDefinition|string>} ChildrenMap
+ *           Map of CSS selectors to component definitions or registered component names
+ */
+
+// -----------------------------------------------------------------------------
+// Context Types
+// -----------------------------------------------------------------------------
+
 /**
  * @typedef {Object} ComponentContext
- * @property {Record<string, unknown>} props
+ * @property {ComponentProps} props
  *           Component properties passed during mounting
  * @property {Emitter} emitter
  *           Event emitter instance for component event handling
- * @property {function<T>(value: T): Signal<T>} signal
+ * @property {SignalFactory} signal
  *           Factory function to create reactive Signal instances
- * @property {function(LifecycleHookContext): Promise<void>} [onBeforeMount]
+ */
+
+/**
+ * @typedef {Record<string, unknown>} ComponentProps
+ *           Properties passed to a component during mounting
+ */
+
+/**
+ * @callback SignalFactory
+ * @template T
+ * @param {T} initialValue - The initial value for the signal
+ * @returns {Signal<T>} A new Signal instance
+ */
+
+// -----------------------------------------------------------------------------
+// Lifecycle Hook Types
+// -----------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} LifecycleHooks
+ * @property {LifecycleHook} [onBeforeMount]
  *           Hook called before component mounting
- * @property {function(LifecycleHookContext): Promise<void>} [onMount]
+ * @property {LifecycleHook} [onMount]
  *           Hook called after component mounting
- * @property {function(LifecycleHookContext): Promise<void>} [onBeforeUpdate]
+ * @property {LifecycleHook} [onBeforeUpdate]
  *           Hook called before component update
- * @property {function(LifecycleHookContext): Promise<void>} [onUpdate]
+ * @property {LifecycleHook} [onUpdate]
  *           Hook called after component update
- * @property {function(UnmountHookContext): Promise<void>} [onUnmount]
+ * @property {UnmountHook} [onUnmount]
  *           Hook called during component unmounting
  */
 
+/**
+ * @callback LifecycleHook
+ * @param {LifecycleHookContext} ctx - Context with container and component data
+ * @returns {void|Promise<void>}
+ */
+
+/**
+ * @callback UnmountHook
+ * @param {UnmountHookContext} ctx - Context with cleanup resources
+ * @returns {void|Promise<void>}
+ */
+
 /**
  * @typedef {Object} LifecycleHookContext
  * @property {HTMLElement} container
  *           The DOM element where the component is mounted
- * @property {ComponentContext} context
+ * @property {ComponentContext & SetupResult} context
  *           The component's reactive state and context data
  */
 
@@ -540,32 +941,91 @@ class Renderer {
  * @typedef {Object} UnmountHookContext
  * @property {HTMLElement} container
  *           The DOM element where the component is mounted
- * @property {ComponentContext} context
+ * @property {ComponentContext & SetupResult} 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
+ * @property {CleanupResources} cleanup
  *           Object containing cleanup functions and instances
  */
 
+/**
+ * @typedef {Object} CleanupResources
+ * @property {Array<UnsubscribeFunction>} watchers
+ *           Signal watcher cleanup functions
+ * @property {Array<UnsubscribeFunction>} listeners
+ *           Event listener cleanup functions
+ * @property {Array<MountResult>} children
+ *           Child component instances
+ */
+
+// -----------------------------------------------------------------------------
+// Mount Result Types
+// -----------------------------------------------------------------------------
+
 /**
  * @typedef {Object} MountResult
  * @property {HTMLElement} container
  *           The DOM element where the component is mounted
- * @property {ComponentContext} data
+ * @property {ComponentContext & SetupResult} data
  *           The component's reactive state and context data
- * @property {function(): Promise<void>} unmount
+ * @property {UnmountFunction} unmount
  *           Function to clean up and unmount the component
  */
 
+/**
+ * @callback UnmountFunction
+ * @returns {Promise<void>}
+ */
+
+/**
+ * @callback UnsubscribeFunction
+ * @returns {void|boolean}
+ */
+
+// -----------------------------------------------------------------------------
+// Plugin Types
+// -----------------------------------------------------------------------------
+
 /**
  * @typedef {Object} ElevaPlugin
- * @property {function(Eleva, Record<string, unknown>): void} install
+ * @property {PluginInstallFunction} install
  *           Function that installs the plugin into the Eleva instance
  * @property {string} name
  *           Unique identifier name for the plugin
+ * @property {PluginUninstallFunction} [uninstall]
+ *           Optional function to uninstall the plugin
+ */
+
+/**
+ * @callback PluginInstallFunction
+ * @param {Eleva} eleva - The Eleva instance
+ * @param {PluginOptions} options - Plugin configuration options
+ * @returns {void|Eleva|unknown} Optionally returns the Eleva instance or plugin result
+ */
+
+/**
+ * @callback PluginUninstallFunction
+ * @param {Eleva} eleva - The Eleva instance
+ * @returns {void}
+ */
+
+/**
+ * @typedef {Record<string, unknown>} PluginOptions
+ *           Configuration options passed to a plugin during installation
+ */
+
+// -----------------------------------------------------------------------------
+// Event Types
+// -----------------------------------------------------------------------------
+
+/**
+ * @callback EventHandler
+ * @param {Event} event - The DOM event object
+ * @returns {void}
+ */
+
+/**
+ * @typedef {'click'|'submit'|'input'|'change'|'focus'|'blur'|'keydown'|'keyup'|'keypress'|'mouseenter'|'mouseleave'|'mouseover'|'mouseout'|'mousedown'|'mouseup'|'touchstart'|'touchend'|'touchmove'|'scroll'|'resize'|'load'|'error'|string} DOMEventName
+ *           Common DOM event names (prefixed with @ in templates)
  */
 
 /**
@@ -625,6 +1085,8 @@ class Eleva {
     this.emitter = new Emitter();
     /** @public {typeof Signal} Static reference to the Signal class for creating reactive state */
     this.signal = Signal;
+    /** @public {typeof TemplateEngine} Static reference to the TemplateEngine class for template parsing */
+    this.templateEngine = TemplateEngine;
     /** @public {Renderer} Instance of the renderer for handling DOM updates and patching */
     this.renderer = new Renderer();
 
@@ -632,8 +1094,8 @@ class Eleva {
     this._components = new Map();
     /** @private {Map<string, ElevaPlugin>} Collection of installed plugin instances by name */
     this._plugins = new Map();
-    /** @private {boolean} Flag indicating if the root component is currently mounted */
-    this._isMounted = false;
+    /** @private {number} Counter for generating unique component IDs */
+    this._componentCounter = 0;
   }
 
   /**
@@ -641,17 +1103,28 @@ class Eleva {
    * The plugin's install function will be called with the Eleva instance and provided options.
    * After installation, the plugin will be available for use by components.
    *
+   * Note: Plugins that wrap core methods (e.g., mount) must be uninstalled in reverse order
+   * of installation (LIFO - Last In, First Out) to avoid conflicts.
+   *
    * @public
    * @param {ElevaPlugin} plugin - The plugin object which must have an `install` function.
    * @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" });
+   *
+   * @example
+   * // Correct uninstall order (LIFO)
+   * app.use(PluginA);
+   * app.use(PluginB);
+   * // Uninstall in reverse order:
+   * PluginB.uninstall(app);
+   * PluginA.uninstall(app);
    */
   use(plugin, options = {}) {
-    plugin.install(this, options);
     this._plugins.set(plugin.name, plugin);
-    return this;
+    const result = plugin.install(this, options);
+    return result !== undefined ? result : this;
   }
 
   /**
@@ -702,6 +1175,9 @@ class Eleva {
     const definition = typeof compName === "string" ? this._components.get(compName) : compName;
     if (!definition) throw new Error(`Component "${compName}" not registered.`);
 
+    /** @type {string} */
+    const compId = `c${++this._componentCounter}`;
+
     /**
      * Destructure the component definition to access core functionality.
      * - setup: Optional function for component initialization and state management
@@ -750,44 +1226,66 @@ class Eleva {
       const childInstances = [];
       /** @type {Array<() => void>} */
       const listeners = [];
+      /** @private {boolean} Local mounted state for this component instance */
+      let isMounted = false;
 
-      // Execute before hooks
-      if (!this._isMounted) {
-        /** @type {LifecycleHookContext} */
-        await mergedContext.onBeforeMount?.({
-          container,
-          context: mergedContext
-        });
-      } else {
-        /** @type {LifecycleHookContext} */
-        await mergedContext.onBeforeUpdate?.({
-          container,
-          context: mergedContext
+      // ========================================================================
+      // Render Batching
+      // ========================================================================
+
+      /** @private {boolean} Flag to prevent multiple queued renders */
+      let renderScheduled = false;
+
+      /**
+       * Schedules a batched render on the next microtask.
+       * Multiple signal changes within the same synchronous block are collapsed into one render.
+       * @private
+       */
+      const scheduleRender = () => {
+        if (renderScheduled) return;
+        renderScheduled = true;
+        queueMicrotask(async () => {
+          renderScheduled = false;
+          await render();
         });
-      }
+      };
 
       /**
        * Renders the component by:
-       * 1. Processing the template
-       * 2. Updating the DOM
-       * 3. Processing events, injecting styles, and mounting child components.
+       * 1. Executing lifecycle hooks
+       * 2. Processing the template
+       * 3. Updating the DOM
+       * 4. Processing events, injecting styles, and mounting child components.
        */
       const render = async () => {
         const templateResult = typeof template === "function" ? await template(mergedContext) : template;
-        const newHtml = TemplateEngine.parse(templateResult, mergedContext);
-        this.renderer.patchDOM(container, newHtml);
+        const html = this.templateEngine.parse(templateResult, mergedContext);
+
+        // Execute before hooks
+        if (!isMounted) {
+          await mergedContext.onBeforeMount?.({
+            container,
+            context: mergedContext
+          });
+        } else {
+          await mergedContext.onBeforeUpdate?.({
+            container,
+            context: mergedContext
+          });
+        }
+        this.renderer.patchDOM(container, html);
         this._processEvents(container, mergedContext, listeners);
-        if (style) this._injectStyles(container, compName, style, mergedContext);
+        if (style) this._injectStyles(container, compId, style, mergedContext);
         if (children) await this._mountComponents(container, children, childInstances);
-        if (!this._isMounted) {
-          /** @type {LifecycleHookContext} */
+
+        // Execute after hooks
+        if (!isMounted) {
           await mergedContext.onMount?.({
             container,
             context: mergedContext
           });
-          this._isMounted = true;
+          isMounted = true;
         } else {
-          /** @type {LifecycleHookContext} */
           await mergedContext.onUpdate?.({
             container,
             context: mergedContext
@@ -797,11 +1295,12 @@ class Eleva {
 
       /**
        * Sets up reactive watchers for all Signal instances in the component's data.
-       * When a Signal's value changes, the component will re-render to reflect the updates.
+       * When a Signal's value changes, a batched render is scheduled.
+       * Multiple changes within the same frame are collapsed into one render.
        * Stores unsubscribe functions to clean up watchers when component unmounts.
        */
       for (const val of Object.values(data)) {
-        if (val instanceof Signal) watchers.push(val.watch(render));
+        if (val instanceof Signal) watchers.push(val.watch(scheduleRender));
       }
       await render();
       const instance = {
@@ -865,7 +1364,7 @@ class Eleva {
         /** @type {string} */
         const handlerName = attr.value;
         /** @type {(event: Event) => void} */
-        const handler = context[handlerName] || TemplateEngine.evaluate(handlerName, context);
+        const handler = context[handlerName] || this.templateEngine.evaluate(handlerName, context);
         if (typeof handler === "function") {
           el.addEventListener(event, handler);
           el.removeAttribute(attr.name);
@@ -881,20 +1380,21 @@ class Eleva {
    *
    * @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 {string} compId - The component ID used to identify the style element.
    * @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) {
+  _injectStyles(container, compId, styleDef, context) {
     /** @type {string} */
-    const newStyle = typeof styleDef === "function" ? TemplateEngine.parse(styleDef(context), context) : styleDef;
+    const newStyle = typeof styleDef === "function" ? this.templateEngine.parse(styleDef(context), context) : styleDef;
+
     /** @type {HTMLStyleElement|null} */
-    let styleEl = container.querySelector(`style[data-e-style="${compName}"]`);
+    let styleEl = container.querySelector(`style[data-e-style="${compId}"]`);
     if (styleEl && styleEl.textContent === newStyle) return;
     if (!styleEl) {
       styleEl = document.createElement("style");
-      styleEl.setAttribute("data-e-style", compName);
+      styleEl.setAttribute("data-e-style", compId);
       container.appendChild(styleEl);
     }
     styleEl.textContent = newStyle;
@@ -906,21 +1406,20 @@ class Eleva {
    *
    * @private
    * @param {HTMLElement} element - The DOM element to extract props from
-   * @param {string} prefix - The prefix to look for in attributes
    * @returns {Record<string, string>} An object containing the extracted props
    * @example
    * // For an element with attributes:
    * // <div :name="John" :age="25">
    * // Returns: { name: "John", age: "25" }
    */
-  _extractProps(element, prefix) {
+  _extractProps(element) {
     if (!element.attributes) return {};
     const props = {};
     const attrs = element.attributes;
     for (let i = attrs.length - 1; i >= 0; i--) {
       const attr = attrs[i];
-      if (attr.name.startsWith(prefix)) {
-        const propName = attr.name.slice(prefix.length);
+      if (attr.name.startsWith(":")) {
+        const propName = attr.name.slice(1);
         props[propName] = attr.value;
         element.removeAttribute(attr.name);
       }
@@ -955,7 +1454,7 @@ class Eleva {
       for (const el of container.querySelectorAll(selector)) {
         if (!(el instanceof HTMLElement)) continue;
         /** @type {Record<string, string>} */
-        const props = this._extractProps(el, ":");
+        const props = this._extractProps(el);
         /** @type {MountResult} */
         const instance = await this.mount(el, component, props);
         if (instance && !childInstances.includes(instance)) {