eleva 1.2.14-beta → 1.2.16-beta

package/dist/eleva.d.ts

@@ -19,13 +19,13 @@ declare class Emitter {
      * @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(): boolean} A function to unsubscribe the event handler.
+     * @returns {function(): void} A function to unsubscribe the event handler.
      * @example
      * const unsubscribe = emitter.on('user:login', (user) => console.log(user));
      * // Later...
      * unsubscribe(); // Stops listening for the event
      */
-    public on(event: string, handler: (arg0: any) => void): () => boolean;
+    public on(event: string, handler: (arg0: any) => void): () => void;
     /**
      * Removes an event handler for the specified event name.
      * If no handler is provided, all handlers for the event are removed.
@@ -58,8 +58,9 @@ declare class Emitter {
  * const count = new Signal(0);
  * count.watch((value) => console.log(`Count changed to: ${value}`));
  * count.value = 1; // Logs: "Count changed to: 1"
+ * @template T
  */
-declare class Signal {
+declare class Signal<T> {
     /**
      * Creates a new Signal instance with the specified initial value.
      *
@@ -126,16 +127,18 @@ declare class Signal {
  * renderer.patchDOM(container, newHtml);
  */
 declare class Renderer {
+    /** @private {HTMLElement} Reusable temporary container for parsing new HTML */
+    private _tempContainer;
     /**
      * Patches the DOM of a container element with new HTML content.
-     * This method efficiently updates the DOM by comparing the new content with the existing
-     * content and applying only the necessary changes.
+     * Efficiently updates the DOM by parsing new HTML into a reusable container
+     * and applying only the necessary changes.
      *
      * @public
      * @param {HTMLElement} container - The container element to patch.
      * @param {string} newHtml - The new HTML content to apply.
      * @returns {void}
-     * @throws {Error} If container is not an HTMLElement or newHtml is not a string.
+     * @throws {Error} If container is not an HTMLElement, newHtml is not a string, or patching fails.
      */
     public patchDOM(container: HTMLElement, newHtml: string): void;
     /**
@@ -147,7 +150,6 @@ declare class Renderer {
      * @param {HTMLElement} oldParent - The original DOM element.
      * @param {HTMLElement} newParent - The new DOM element.
      * @returns {void}
-     * @throws {Error} If either parent is not an HTMLElement.
      */
     private _diff;
     /**
@@ -158,7 +160,6 @@ declare class Renderer {
      * @param {HTMLElement} oldEl - The element to update.
      * @param {HTMLElement} newEl - The element providing the updated attributes.
      * @returns {void}
-     * @throws {Error} If either element is not an HTMLElement.
      */
     private _updateAttributes;
 }
@@ -167,7 +168,7 @@ declare class Renderer {
  * @typedef {Object} ComponentDefinition
  * @property {function(Object<string, any>): (Object<string, any>|Promise<Object<string, any>>)} [setup]
  *           Optional setup function that initializes the component's state and returns reactive data
- * @property {function(Object<string, any>): string} template
+ * @property {function(Object<string, any>): string|Promise<string>} template
  *           Required function that defines the component's HTML structure
  * @property {function(Object<string, any>): string} [style]
  *           Optional function that provides component-scoped CSS styles
@@ -335,30 +336,6 @@ declare class Eleva {
      * // Returns: { name: "John", age: "25" }
      */
     private _extractProps;
-    /**
-     * Mounts a single component instance to a container element.
-     * This method handles the actual mounting of a component with its props.
-     *
-     * @private
-     * @param {HTMLElement} container - The container element to mount the component to
-     * @param {string|ComponentDefinition} component - The component to mount, either as a name or definition
-     * @param {Object<string, any>} props - The props to pass to the component
-     * @returns {Promise<MountResult>} A promise that resolves to the mounted component instance
-     * @throws {Error} If the container is not a valid HTMLElement
-     */
-    private _mountComponentInstance;
-    /**
-     * Mounts components found by a selector in the container.
-     * This method handles mounting multiple instances of the same component type.
-     *
-     * @private
-     * @param {HTMLElement} container - The container to search for components
-     * @param {string} selector - The CSS selector to find components
-     * @param {string|ComponentDefinition} component - The component to mount
-     * @param {Array<MountResult>} instances - Array to store the mounted component instances
-     * @returns {Promise<void>}
-     */
-    private _mountComponentsBySelector;
     /**
      * Mounts all components within the parent component's container.
      * This method handles mounting of explicitly defined children components.
@@ -398,7 +375,7 @@ type ComponentDefinition = {
      */
     template: (arg0: {
         [x: string]: any;
-    }) => string;
+    }) => string | Promise<string>;
     /**
      * Optional function that provides component-scoped CSS styles
      */

package/dist/eleva.esm.js

@@ -1,4 +1,4 @@
-/*! Eleva v1.2.14-beta | MIT License | https://elevajs.com */
+/*! Eleva v1.2.16-beta | MIT License | https://elevajs.com */
 /**
  * @class 🔒 TemplateEngine
  * @classdesc A secure template engine that handles interpolation and dynamic attribute parsing.
@@ -68,6 +68,7 @@ class TemplateEngine {
  * const count = new Signal(0);
  * count.watch((value) => console.log(`Count changed to: ${value}`));
  * count.value = 1; // Logs: "Count changed to: 1"
+ * @template T
  */
 class Signal {
   /**
@@ -173,7 +174,7 @@ class Emitter {
    * @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(): boolean} A function to unsubscribe the event handler.
+   * @returns {function(): void} A function to unsubscribe the event handler.
    * @example
    * const unsubscribe = emitter.on('user:login', (user) => console.log(user));
    * // Later...
@@ -234,16 +235,25 @@ class Emitter {
  * renderer.patchDOM(container, newHtml);
  */
 class Renderer {
+  /**
+   * Creates a new Renderer instance with a reusable temporary container for parsing HTML.
+   * @public
+   */
+  constructor() {
+    /** @private {HTMLElement} Reusable temporary container for parsing new HTML */
+    this._tempContainer = document.createElement("div");
+  }
+
   /**
    * Patches the DOM of a container element with new HTML content.
-   * This method efficiently updates the DOM by comparing the new content with the existing
-   * content and applying only the necessary changes.
+   * Efficiently updates the DOM by parsing new HTML into a reusable container
+   * and applying only the necessary changes.
    *
    * @public
    * @param {HTMLElement} container - The container element to patch.
    * @param {string} newHtml - The new HTML content to apply.
    * @returns {void}
-   * @throws {Error} If container is not an HTMLElement or newHtml is not a string.
+   * @throws {Error} If container is not an HTMLElement, newHtml is not a string, or patching fails.
    */
   patchDOM(container, newHtml) {
     if (!(container instanceof HTMLElement)) {
@@ -252,10 +262,13 @@ class Renderer {
     if (typeof newHtml !== "string") {
       throw new Error("newHtml must be a string");
     }
-    const temp = document.createElement("div");
-    temp.innerHTML = newHtml;
-    this._diff(container, temp);
-    temp.innerHTML = "";
+    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");
+    }
   }
 
   /**
@@ -267,12 +280,8 @@ class Renderer {
    * @param {HTMLElement} oldParent - The original DOM element.
    * @param {HTMLElement} newParent - The new DOM element.
    * @returns {void}
-   * @throws {Error} If either parent is not an HTMLElement.
    */
   _diff(oldParent, newParent) {
-    if (!(oldParent instanceof HTMLElement) || !(newParent instanceof HTMLElement)) {
-      throw new Error("Both parents must be HTMLElements");
-    }
     if (oldParent.isEqualNode(newParent)) return;
     const oldChildren = oldParent.childNodes;
     const newChildren = newParent.childNodes;
@@ -280,7 +289,9 @@ class Renderer {
     for (let i = 0; i < maxLength; i++) {
       const oldNode = oldChildren[i];
       const newNode = newChildren[i];
-      if (!oldNode && !newNode) continue;
+      if (oldNode?._eleva_instance) {
+        continue;
+      }
       if (!oldNode && newNode) {
         oldParent.appendChild(newNode.cloneNode(true));
         continue;
@@ -317,12 +328,8 @@ class Renderer {
    * @param {HTMLElement} oldEl - The element to update.
    * @param {HTMLElement} newEl - The element providing the updated attributes.
    * @returns {void}
-   * @throws {Error} If either element is not an HTMLElement.
    */
   _updateAttributes(oldEl, newEl) {
-    if (!(oldEl instanceof HTMLElement) || !(newEl instanceof HTMLElement)) {
-      throw new Error("Both elements must be HTMLElements");
-    }
     const oldAttrs = oldEl.attributes;
     const newAttrs = newEl.attributes;
 
@@ -369,7 +376,7 @@ class Renderer {
  * @typedef {Object} ComponentDefinition
  * @property {function(Object<string, any>): (Object<string, any>|Promise<Object<string, any>>)} [setup]
  *           Optional setup function that initializes the component's state and returns reactive data
- * @property {function(Object<string, any>): string} template
+ * @property {function(Object<string, any>): string|Promise<string>} template
  *           Required function that defines the component's HTML structure
  * @property {function(Object<string, any>): string} [style]
  *           Optional function that provides component-scoped CSS styles
@@ -500,6 +507,9 @@ class Eleva {
    */
   async mount(container, compName, props = {}) {
     if (!container) throw new Error(`Container not found: ${container}`);
+    if (container._eleva_instance) {
+      return container._eleva_instance;
+    }
 
     /** @type {ComponentDefinition} */
     const definition = typeof compName === "string" ? this._components.get(compName) : compName;
@@ -532,7 +542,7 @@ class Eleva {
     const context = {
       props,
       emitter: this.emitter,
-      /** @type {(v: any) => Signal} */
+      /** @type {(v: any) => Signal<any>} */
       signal: v => new this.signal(v),
       ...this._prepareLifecycleHooks()
     };
@@ -546,12 +556,13 @@ class Eleva {
      * 4. Managing component lifecycle
      *
      * @param {Object<string, any>} data - Data returned from the component's setup function
-     * @returns {MountResult} An object containing:
+     * @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>} */
       const mergedContext = {
         ...context,
         ...data
@@ -571,15 +582,18 @@ class Eleva {
       }
 
       /**
-       * Renders the component by parsing the template, patching the DOM,
-       * processing events, injecting styles, and mounting child components.
+       * Renders the component by:
+       * 1. Processing the template
+       * 2. Updating the DOM
+       * 3. Processing events, injecting styles, and mounting child components.
        */
       const render = async () => {
-        const newHtml = TemplateEngine.parse(template(mergedContext), mergedContext);
+        const templateResult = await template(mergedContext);
+        const newHtml = TemplateEngine.parse(templateResult, mergedContext);
         this.renderer.patchDOM(container, newHtml);
         this._processEvents(container, mergedContext, cleanupListeners);
-        this._injectStyles(container, compName, style, mergedContext);
-        await this._mountComponents(container, children, childInstances);
+        if (style) this._injectStyles(container, compName, style, mergedContext);
+        if (children) await this._mountComponents(container, children, childInstances);
         if (!this._isMounted) {
           mergedContext.onMount && mergedContext.onMount();
           this._isMounted = true;
@@ -597,7 +611,7 @@ class Eleva {
         if (val instanceof Signal) watcherUnsubscribers.push(val.watch(render));
       }
       await render();
-      return {
+      const instance = {
         container,
         data: mergedContext,
         /**
@@ -611,8 +625,11 @@ class Eleva {
           for (const child of childInstances) child.unmount();
           mergedContext.onUnmount && mergedContext.onUnmount();
           container.innerHTML = "";
+          delete container._eleva_instance;
         }
       };
+      container._eleva_instance = instance;
+      return instance;
     };
 
     // Handle asynchronous setup.
@@ -653,14 +670,14 @@ class Eleva {
       const attrs = el.attributes;
       for (let i = 0; i < attrs.length; i++) {
         const attr = attrs[i];
-        if (attr.name.startsWith("@")) {
-          const event = attr.name.slice(1);
-          const handler = TemplateEngine.evaluate(attr.value, context);
-          if (typeof handler === "function") {
-            el.addEventListener(event, handler);
-            el.removeAttribute(attr.name);
-            cleanupListeners.push(() => el.removeEventListener(event, handler));
-          }
+        if (!attr.name.startsWith("@")) continue;
+        const event = attr.name.slice(1);
+        const handlerName = attr.value;
+        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));
         }
       }
     }
@@ -678,7 +695,6 @@ class Eleva {
    * @returns {void}
    */
   _injectStyles(container, compName, styleFn, context) {
-    if (!styleFn) return;
     let styleEl = container.querySelector(`style[data-eleva-style="${compName}"]`);
     if (!styleEl) {
       styleEl = document.createElement("style");
@@ -702,6 +718,7 @@ class Eleva {
    * // Returns: { name: "John", age: "25" }
    */
   _extractProps(element, prefix) {
+    /** @type {Record<string, string>} */
     const props = {};
     for (const {
       name,
@@ -714,41 +731,6 @@ class Eleva {
     return props;
   }
 
-  /**
-   * Mounts a single component instance to a container element.
-   * This method handles the actual mounting of a component with its props.
-   *
-   * @private
-   * @param {HTMLElement} container - The container element to mount the component to
-   * @param {string|ComponentDefinition} component - The component to mount, either as a name or definition
-   * @param {Object<string, any>} props - The props to pass to the component
-   * @returns {Promise<MountResult>} A promise that resolves to the mounted component instance
-   * @throws {Error} If the container is not a valid HTMLElement
-   */
-  async _mountComponentInstance(container, component, props) {
-    if (!(container instanceof HTMLElement)) return null;
-    return await this.mount(container, component, props);
-  }
-
-  /**
-   * Mounts components found by a selector in the container.
-   * This method handles mounting multiple instances of the same component type.
-   *
-   * @private
-   * @param {HTMLElement} container - The container to search for components
-   * @param {string} selector - The CSS selector to find components
-   * @param {string|ComponentDefinition} component - The component to mount
-   * @param {Array<MountResult>} instances - Array to store the mounted component instances
-   * @returns {Promise<void>}
-   */
-  async _mountComponentsBySelector(container, selector, component, instances) {
-    for (const el of container.querySelectorAll(selector)) {
-      const props = this._extractProps(el, ":");
-      const instance = await this._mountComponentInstance(el, component, props);
-      if (instance) instances.push(instance);
-    }
-  }
-
   /**
    * Mounts all components within the parent component's container.
    * This method handles mounting of explicitly defined children components.
@@ -771,15 +753,15 @@ class Eleva {
    * };
    */
   async _mountComponents(container, children, childInstances) {
-    // Clean up existing instances
-    for (const child of childInstances) child.unmount();
-    childInstances.length = 0;
-
-    // Mount explicitly defined children components
-    if (children) {
-      for (const [selector, component] of Object.entries(children)) {
-        if (!selector) continue;
-        await this._mountComponentsBySelector(container, selector, component, childInstances);
+    for (const [selector, component] of Object.entries(children)) {
+      if (!selector) continue;
+      for (const el of container.querySelectorAll(selector)) {
+        if (!(el instanceof HTMLElement)) continue;
+        const props = this._extractProps(el, ":");
+        const instance = await this.mount(el, component, props);
+        if (instance && !childInstances.includes(instance)) {
+          childInstances.push(instance);
+        }
       }
     }
   }