eleva 1.2.17-beta → 1.2.19-beta

package/src/core/Eleva.js

@@ -7,34 +7,76 @@ import { Renderer } from "../modules/Renderer.js";
 
 /**
  * @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,
@@ -42,12 +84,26 @@ import { Renderer } from "../modules/Renderer.js";
  * 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>`
+ * });
  */
 export class Eleva {
   /**
@@ -55,13 +111,24 @@ export class Eleva {
    *
    * @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();
@@ -74,14 +141,6 @@ export class Eleva {
     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;
   }
@@ -93,7 +152,7 @@ export class Eleva {
    *
    * @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" });
@@ -133,7 +192,7 @@ export class Eleva {
    * @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
@@ -164,21 +223,12 @@ export class Eleva {
      */
     const { setup, template, style, 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>} */
+      /** @type {(v: unknown) => Signal<unknown>} */
       signal: (v) => new this.signal(v),
-      ...this._prepareLifecycleHooks(),
     };
 
     /**
@@ -189,27 +239,35 @@ export class Eleva {
      * 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,
+        });
       }
 
       /**
@@ -225,17 +283,25 @@ export class Eleva {
             : 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,
+          });
         }
       };
 
@@ -245,7 +311,7 @@ export class Eleva {
        * 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();
@@ -258,11 +324,20 @@ export class Eleva {
          *
          * @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;
         },
@@ -277,50 +352,39 @@ export class Eleva {
     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));
         }
       }
     }
@@ -333,15 +397,17 @@ export 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 {(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;
@@ -361,7 +427,7 @@ export class Eleva {
    * @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">
@@ -404,7 +470,9 @@ export class Eleva {
       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);

package/src/modules/Emitter.js

@@ -5,6 +5,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();
@@ -18,18 +21,19 @@ export class Emitter {
    * @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...
@@ -45,11 +49,17 @@ export class Emitter {
   /**
    * 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;
@@ -66,11 +76,17 @@ export class Emitter {
   /**
    * 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;