eleva 1.2.7-alpha → 1.2.9-alpha

package/src/modules/Signal.js

@@ -2,20 +2,26 @@
 
 /**
  * @class ⚡ Signal
- * @classdesc Fine-grained reactivity.
- * A reactive data holder that notifies registered watchers when its value changes,
- * enabling fine-grained DOM patching rather than full re-renders.
+ * @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.
+ *
+ * @example
+ * const count = new Signal(0);
+ * count.watch((value) => console.log(`Count changed to: ${value}`));
+ * count.value = 1; // Logs: "Count changed to: 1"
  */
 export class Signal {
   /**
-   * Creates a new Signal instance.
+   * Creates a new Signal instance with the specified initial value.
    *
+   * @public
    * @param {*} value - The initial value of the signal.
    */
   constructor(value) {
-    /** @private {*} Internal storage for the signal's current value */
+    /** @private {T} Internal storage for the signal's current value, where T is the type of the initial value */
     this._value = value;
-    /** @private {Set<function>} Collection of callback functions to be notified when value changes */
+    /** @private {Set<function(T): void>} Collection of callback functions to be notified when value changes, where T is the value type */
     this._watchers = new Set();
     /** @private {boolean} Flag to prevent multiple synchronous watcher notifications and batch updates into microtasks */
     this._pending = false;
@@ -24,7 +30,8 @@ export class Signal {
   /**
    * Gets the current value of the signal.
    *
-   * @returns {*} The current value.
+   * @public
+   * @returns {T} The current value, where T is the type of the initial value.
    */
   get value() {
     return this._value;
@@ -32,21 +39,30 @@ export class Signal {
 
   /**
    * Sets a new value for the signal and notifies all registered watchers if the value has changed.
+   * The notification is batched using microtasks to prevent multiple synchronous updates.
    *
-   * @param {*} newVal - The new value to set.
+   * @public
+   * @param {T} newVal - The new value to set, where T is the type of the initial value.
+   * @returns {void}
    */
   set value(newVal) {
-    if (newVal !== this._value) {
-      this._value = newVal;
-      this._notifyWatchers();
-    }
+    if (this._value === newVal) return;
+
+    this._value = newVal;
+    this._notify();
   }
 
   /**
    * Registers a watcher function that will be called whenever the signal's value changes.
+   * The watcher will receive the new value as its argument.
    *
-   * @param {function(any): void} fn - The callback function to invoke on value change.
+   * @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.
+   * @example
+   * const unsubscribe = signal.watch((value) => console.log(value));
+   * // Later...
+   * unsubscribe(); // Stops watching for changes
    */
   watch(fn) {
     this._watchers.add(fn);
@@ -61,13 +77,13 @@ export class Signal {
    * @private
    * @returns {void}
    */
-  _notifyWatchers() {
-    if (!this._pending) {
-      this._pending = true;
-      queueMicrotask(() => {
-        this._pending = false;
-        this._watchers.forEach((fn) => fn(this._value));
-      });
-    }
+  _notify() {
+    if (this._pending) return;
+
+    this._pending = true;
+    queueMicrotask(() => {
+      this._watchers.forEach((fn) => fn(this._value));
+      this._pending = false;
+    });
   }
 }

package/src/modules/TemplateEngine.js

@@ -2,45 +2,60 @@
 
 /**
  * @class 🔒 TemplateEngine
- * @classdesc Secure interpolation & dynamic attribute parsing.
- * Provides methods to parse template strings by replacing interpolation expressions
- * with dynamic data values and to evaluate expressions within a given data context.
+ * @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.
+ * All methods are static and can be called directly on the class.
+ *
+ * @example
+ * const template = "Hello, {{name}}!";
+ * const data = { name: "World" };
+ * const result = TemplateEngine.parse(template, data); // Returns: "Hello, World!"
  */
 export class TemplateEngine {
   /**
-   * Parses a template string and replaces interpolation expressions with corresponding values.
+   * @private {RegExp} Regular expression for matching template expressions in the format {{ expression }}
+   */
+  static expressionPattern = /\{\{\s*(.*?)\s*\}\}/g;
+
+  /**
+   * Parses a template string, replacing expressions with their evaluated values.
+   * Expressions are evaluated in the provided data context.
    *
-   * @param {string} template - The template string containing expressions in the format `{{ expression }}`.
-   * @param {Object<string, any>} data - The data object to use for evaluating expressions.
-   * @returns {string} The resulting string with evaluated values.
+   * @public
+   * @static
+   * @param {string} template - The template string to parse.
+   * @param {Object} 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", {
+   *   user: { name: "John", age: 30 }
+   * }); // Returns: "John is 30 years old"
    */
   static parse(template, data) {
-    if (!template || typeof template !== "string") return template;
-
-    return template.replace(/\{\{\s*(.*?)\s*\}\}/g, (_, expr) => {
-      return this.evaluate(expr, data);
-    });
+    if (typeof template !== "string") return template;
+    return template.replace(this.expressionPattern, (_, expression) =>
+      this.evaluate(expression, data)
+    );
   }
 
   /**
-   * Evaluates a JavaScript expression using the provided data context.
+   * 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.
    *
-   * @param {string} expr - The JavaScript expression to evaluate.
-   * @param {Object<string, any>} data - The data context for evaluating the expression.
-   * @returns {any} The result of the evaluated expression, or an empty string if undefined or on error.
+   * @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.
+   * @example
+   * const result = TemplateEngine.evaluate("user.name", { user: { name: "John" } }); // Returns: "John"
+   * const age = TemplateEngine.evaluate("user.age", { user: { age: 30 } }); // Returns: 30
    */
-  static evaluate(expr, data) {
-    if (!expr || typeof expr !== "string") return expr;
-
+  static evaluate(expression, data) {
+    if (typeof expression !== "string") return expression;
     try {
-      const compiledFn = new Function("data", `with(data) { return ${expr} }`);
-      return compiledFn(data);
-    } catch (error) {
-      console.error(`Template evaluation error:`, {
-        expression: expr,
-        data,
-        error: error.message,
-      });
+      return new Function("data", `with(data) { return ${expression}; }`)(data);
+    } catch {
       return "";
     }
   }

package/types/core/Eleva.d.ts

@@ -1,138 +1,233 @@
 /**
- * Defines the structure and behavior of a component.
  * @typedef {Object} ComponentDefinition
  * @property {function(Object<string, any>): (Object<string, any>|Promise<Object<string, any>>)} [setup]
- *           Optional setup function that initializes the component's reactive state and lifecycle.
- *           Receives props and context as an argument and should return an object containing the component's state.
- *           Can return either a synchronous object or a Promise that resolves to an object for async initialization.
- *
+ *           Optional setup function that initializes the component's state and returns reactive data
  * @property {function(Object<string, any>): string} template
- *           Required function that defines the component's HTML structure.
- *           Receives the merged context (props + setup data) and must return an HTML template string.
- *           Supports dynamic expressions using {{ }} syntax for reactive data binding.
- *
+ *           Required function that defines the component's HTML structure
  * @property {function(Object<string, any>): string} [style]
- *           Optional function that defines component-scoped CSS styles.
- *           Receives the merged context and returns a CSS string that will be automatically scoped to the component.
- *           Styles are injected into the component's container and only affect elements within it.
- *
+ *           Optional function that provides component-scoped CSS styles
  * @property {Object<string, ComponentDefinition>} [children]
- *           Optional object that defines nested child components.
- *           Keys are CSS selectors that match elements in the template where child components should be mounted.
- *           Values are ComponentDefinition objects that define the structure and behavior of each child component.
+ *           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} MountResult
+ * @property {HTMLElement} container
+ *           The DOM element where the component is mounted
+ * @property {Object<string, any>} data
+ *           The component's reactive state and context data
+ * @property {function(): void} unmount
+ *           Function to clean up and unmount the component
  */
 /**
  * @class 🧩 Eleva
- * @classdesc Signal-based component runtime framework with lifecycle hooks, scoped styles, and plugin support.
- * Manages component registration, plugin integration, event handling, and DOM rendering.
+ * @classdesc A modern, signal-based component runtime framework that provides lifecycle hooks,
+ * scoped styles, and plugin support. Eleva manages component registration, plugin integration,
+ * event handling, and DOM rendering with a focus on performance and developer experience.
+ *
+ * @example
+ * const app = new Eleva("myApp");
+ * app.component("myComponent", {
+ *   template: (ctx) => `<div>Hello ${ctx.props.name}</div>`,
+ *   setup: (ctx) => ({ count: new Signal(0) })
+ * });
+ * app.mount(document.getElementById("app"), "myComponent", { name: "World" });
  */
 export class Eleva {
     /**
-     * Creates a new Eleva instance.
+     * Creates a new Eleva instance with the specified name and configuration.
      *
-     * @param {string} name - The name of the Eleva instance.
-     * @param {Object<string, any>} [config={}] - Optional configuration for the instance.
+     * @public
+     * @param {string} name - The unique identifier name for this Eleva instance.
+     * @param {Object<string, any>} [config={}] - Optional configuration object for the instance.
+     *        May include framework-wide settings and default behaviors.
      */
     constructor(name: string, config?: {
         [x: string]: any;
     });
-    /** @type {string} The unique identifier name for this Eleva instance */
-    name: string;
-    /** @type {Object<string, any>} Optional configuration object for the Eleva instance */
-    config: {
+    /** @public {string} The unique identifier name for this Eleva instance */
+    public name: string;
+    /** @public {Object<string, any>} Optional configuration object for the Eleva instance */
+    public config: {
         [x: string]: any;
     };
-    /** @type {Object<string, ComponentDefinition>} Object storing registered component definitions by name */
-    _components: {
-        [x: string]: ComponentDefinition;
-    };
-    /** @private {Array<Object>} Collection of installed plugin instances */
+    /** @public {Emitter} Instance of the event emitter for handling component events */
+    public emitter: Emitter;
+    /** @public {typeof Signal} Static reference to the Signal class for creating reactive state */
+    public signal: typeof Signal;
+    /** @public {Renderer} Instance of the renderer for handling DOM updates and patching */
+    public renderer: Renderer;
+    /** @private {Map<string, ComponentDefinition>} Registry of all component definitions by name */
+    private _components;
+    /** @private {Map<string, ElevaPlugin>} Collection of installed plugin instances by name */
     private _plugins;
-    /** @private {string[]} Array of lifecycle hook names supported by the component */
+    /** @private {string[]} Array of lifecycle hook names supported by components */
     private _lifecycleHooks;
-    /** @private {boolean} Flag indicating if component is currently mounted */
+    /** @private {boolean} Flag indicating if the root component is currently mounted */
     private _isMounted;
-    /** @private {Emitter} Instance of the event emitter for handling component events */
-    private emitter;
-    /** @private {Signal} Instance of the signal for handling plugin and component signals */
-    private signal;
-    /** @private {Renderer} Instance of the renderer for handling DOM updates and patching */
-    private renderer;
     /**
      * Integrates a plugin with the Eleva framework.
+     * 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.
      *
-     * @param {Object} plugin - The plugin object which should have an `install` function.
-     * @param {Object<string, any>} [options={}] - Optional options to pass to the plugin.
-     * @returns {Eleva} The Eleva instance (for chaining).
+     * @public
+     * @param {ElevaPlugin} plugin - The plugin object which must have an `install` function.
+     * @param {Object<string, any>} [options={}] - Optional configuration options for the plugin.
+     * @returns {Eleva} The Eleva instance (for method chaining).
+     * @example
+     * app.use(myPlugin, { option1: "value1" });
      */
-    use(plugin: Object, options?: {
+    public use(plugin: ElevaPlugin, options?: {
         [x: string]: any;
     }): Eleva;
     /**
-     * Registers a component with the Eleva instance.
+     * Registers a new component with the Eleva instance.
+     * The component will be available for mounting using its registered name.
      *
-     * @param {string} name - The name of the component.
+     * @public
+     * @param {string} name - The unique name of the component to register.
      * @param {ComponentDefinition} definition - The component definition including setup, template, style, and children.
-     * @returns {Eleva} The Eleva instance (for chaining).
+     * @returns {Eleva} The Eleva instance (for method chaining).
+     * @throws {Error} If the component name is already registered.
+     * @example
+     * app.component("myButton", {
+     *   template: (ctx) => `<button>${ctx.props.text}</button>`,
+     *   style: () => "button { color: blue; }"
+     * });
      */
-    component(name: string, definition: ComponentDefinition): Eleva;
+    public component(name: string, definition: ComponentDefinition): Eleva;
     /**
      * Mounts a registered component to a DOM element.
+     * This will initialize the component, set up its reactive state, and render it to the DOM.
      *
-     * @param {HTMLElement} container - A DOM element where the component will be mounted.
-     * @param {string|ComponentDefinition} compName - The name of the component to mount or a component definition.
+     * @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.
-     * @returns {object|Promise<object>} An object representing the mounted component instance, or a Promise that resolves to it for asynchronous setups.
-     * @throws {Error} If the container is not found or if the component is not registered.
+     * @returns {Promise<MountResult>}
+     *          A Promise that resolves to 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
+     * @throws {Error} If the container is not found, or component is not registered.
+     * @example
+     * const instance = await app.mount(document.getElementById("app"), "myComponent", { text: "Click me" });
+     * // Later...
+     * instance.unmount();
      */
-    mount(container: HTMLElement, compName: string | ComponentDefinition, props?: {
+    public mount(container: HTMLElement, compName: string | ComponentDefinition, props?: {
         [x: string]: any;
-    }): object | Promise<object>;
+    }): Promise<MountResult>;
     /**
-     * Prepares default no-operation lifecycle hook functions.
+     * Prepares default no-operation lifecycle hook functions for a component.
+     * These hooks will be called at various stages of the component's lifecycle.
      *
-     * @returns {Object<string, function(): void>} An object with keys for lifecycle hooks mapped to empty functions.
      * @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.
      */
     private _prepareLifecycleHooks;
     /**
      * Processes DOM elements for event binding based on attributes starting with "@".
-     * Tracks listeners for cleanup during unmount.
+     * This method handles the event delegation system and ensures proper cleanup of event listeners.
      *
-     * @param {HTMLElement} container - The container element in which to search for events.
-     * @param {Object<string, any>} context - The current context containing event handler definitions.
-     * @param {Array<Function>} cleanupListeners - Array to collect cleanup functions for each event listener.
      * @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.
+     * @returns {void}
      */
     private _processEvents;
     /**
      * Injects scoped styles into the component's container.
+     * The styles are automatically prefixed to prevent style leakage to other components.
      *
-     * @param {HTMLElement} container - The container element.
-     * @param {string} compName - The component name used to identify the style element.
-     * @param {function(Object<string, any>): string} [styleFn] - A function that returns CSS styles as a string.
-     * @param {Object<string, any>} context - The current context for style interpolation.
      * @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} [styleFn] - Optional function that returns CSS styles as a string.
+     * @param {Object<string, any>} context - The current component context for style interpolation.
+     * @returns {void}
      */
     private _injectStyles;
     /**
-     * Mounts child components within the parent component's container.
+     * Extracts props from an element's attributes that start with 'eleva-prop-'.
+     * This method is used to collect component properties from DOM elements.
+     *
+     * @private
+     * @param {HTMLElement} element - The DOM element to extract props from
+     * @returns {Object<string, any>} An object containing the extracted props
+     * @example
+     * // For an element with attributes:
+     * // <div eleva-prop-name="John" eleva-prop-age="25">
+     * // 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 implements a dual mounting system that handles both:
+     * 1. Explicitly defined children components (passed through the children parameter)
+     * 2. Template-referenced components (found in the template using component names)
+     *
+     * The mounting process follows these steps:
+     * 1. Cleans up any existing component instances
+     * 2. Mounts explicitly defined children components
+     * 3. Mounts template-referenced components
      *
-     * @param {HTMLElement} container - The parent container element.
-     * @param {Object<string, ComponentDefinition>} [children] - An object mapping child component selectors to their definitions.
-     * @param {Array<object>} childInstances - An array to store the mounted child component instances.
      * @private
+     * @param {HTMLElement} container - The container element to mount components in
+     * @param {Object<string, ComponentDefinition>} children - Map of selectors to component definitions for explicit children
+     * @param {Array<MountResult>} childInstances - Array to store all mounted component instances
+     * @returns {Promise<void>}
+     *
+     * @example
+     * // Explicit children mounting:
+     * const children = {
+     *   '.user-profile': UserProfileComponent,
+     *   '.settings-panel': SettingsComponent
+     * };
+     *
+     * // Template-referenced components:
+     * // <div>
+     * //   <user-profile eleva-prop-name="John"></user-profile>
+     * //   <settings-panel eleva-prop-theme="dark"></settings-panel>
+     * // </div>
      */
-    private _mountChildren;
+    private _mountComponents;
 }
-/**
- * Defines the structure and behavior of a component.
- */
 export type ComponentDefinition = {
     /**
-     * Optional setup function that initializes the component's reactive state and lifecycle.
-     * Receives props and context as an argument and should return an object containing the component's state.
-     * Can return either a synchronous object or a Promise that resolves to an object for async initialization.
+     * Optional setup function that initializes the component's state and returns reactive data
      */
     setup?: ((arg0: {
         [x: string]: any;
@@ -142,28 +237,53 @@ export type ComponentDefinition = {
         [x: string]: any;
     }>)) | undefined;
     /**
-     *           Required function that defines the component's HTML structure.
-     *           Receives the merged context (props + setup data) and must return an HTML template string.
-     *           Supports dynamic expressions using {{ }} syntax for reactive data binding.
+     *           Required function that defines the component's HTML structure
      */
     template: (arg0: {
         [x: string]: any;
     }) => string;
     /**
-     * Optional function that defines component-scoped CSS styles.
-     * Receives the merged context and returns a CSS string that will be automatically scoped to the component.
-     * Styles are injected into the component's container and only affect elements within it.
+     * Optional function that provides component-scoped CSS styles
      */
     style?: ((arg0: {
         [x: string]: any;
     }) => string) | undefined;
     /**
-     * Optional object that defines nested child components.
-     * Keys are CSS selectors that match elements in the template where child components should be mounted.
-     * Values are ComponentDefinition objects that define the structure and behavior of each child component.
+     * Optional object defining nested child components
      */
     children?: {
         [x: string]: ComponentDefinition;
     } | undefined;
 };
+export type ElevaPlugin = {
+    /**
+     *           Function that installs the plugin into the Eleva instance
+     */
+    install: (arg0: Eleva, arg1: {
+        [x: string]: any;
+    }) => void;
+    /**
+     *           Unique identifier name for the plugin
+     */
+    name: string;
+};
+export type MountResult = {
+    /**
+     *           The DOM element where the component is mounted
+     */
+    container: HTMLElement;
+    /**
+     *           The component's reactive state and context data
+     */
+    data: {
+        [x: string]: any;
+    };
+    /**
+     *           Function to clean up and unmount the component
+     */
+    unmount: () => void;
+};
+import { Emitter } from "../modules/Emitter.js";
+import { Signal } from "../modules/Signal.js";
+import { Renderer } from "../modules/Renderer.js";
 //# sourceMappingURL=Eleva.d.ts.map

package/types/core/Eleva.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Eleva.d.ts","sourceRoot":"","sources":["../../src/core/Eleva.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;GAIG;AACH;IACE;;;;;OAKG;IACH,kBAHW,MAAM;;OA4BhB;IAxBC,wEAAwE;IACxE,MADW,MAAM,CACD;IAChB,uFAAuF;IACvF;;MAAoB;IACpB,0GAA0G;IAC1G;;MAAqB;IACrB,wEAAwE;IACxE,iBAAkB;IAClB,mFAAmF;IACnF,wBAMC;IACD,2EAA2E;IAC3E,mBAAuB;IACvB,qFAAqF;IACrF,gBAA4B;IAC5B,yFAAyF;IACzF,eAAoB;IACpB,yFAAyF;IACzF,iBAA8B;IAGhC;;;;;;OAMG;IACH,YAJW,MAAM;;QAEJ,KAAK,CAQjB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,cACN,mBAAmB,GACjB,KAAK,CAKjB;IAED;;;;;;;;OAQG;IACH,iBANW,WAAW,YACX,MAAM,GAAC,mBAAmB;;QAExB,MAAM,GAAC,OAAO,CAAC,MAAM,CAAC,CAgHlC;IAED;;;;;OAKG;IACH,+BAKC;IAED;;;;;;;;OAQG;IACH,uBAiBC;IAED;;;;;;;;OAQG;IACH,sBAYC;IAED;;;;;;;OAOG;IACH,uBAgBC;CACF;;;;;;;;;;;;UAxS4C,CAAC;YAAO,MAAM,GAAE,GAAG;KAAC,GAAC,OAAO,CAAC;YAAO,MAAM,GAAE,GAAG;KAAC,CAAC,CAAC;;;;;;cAKjF,CAAS,IAAmB,EAAnB;YAAO,MAAM,GAAE,GAAG;KAAC,KAAG,MAAM;;;;;;;;UAKN,MAAM"}
+{"version":3,"file":"Eleva.d.ts","sourceRoot":"","sources":["../../src/core/Eleva.js"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;GAaG;AACH;IACE;;;;;;;OAOG;IACH,kBAJW,MAAM;;OA8BhB;IAzBC,0EAA0E;IAC1E,oBAAgB;IAChB,yFAAyF;IACzF;;MAAoB;IACpB,oFAAoF;IACpF,wBAA4B;IAC5B,+FAA+F;IAC/F,6BAAoB;IACpB,wFAAwF;IACxF,0BAA8B;IAE9B,gGAAgG;IAChG,oBAA4B;IAC5B,2FAA2F;IAC3F,iBAAyB;IACzB,gFAAgF;IAChF,wBAMC;IACD,oFAAoF;IACpF,mBAAuB;IAGzB;;;;;;;;;;;OAWG;IACH,mBANW,WAAW;;QAET,KAAK,CASjB;IAED;;;;;;;;;;;;;;OAcG;IACH,uBAVW,MAAM,cACN,mBAAmB,GACjB,KAAK,CAYjB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAdW,WAAW,YACX,MAAM,GAAC,mBAAmB;;QAExB,OAAO,CAAC,WAAW,CAAC,CAqIhC;IAED;;;;;;;OAOG;IACH,+BAOC;IAED;;;;;;;;;OASG;IACH,uBAiBC;IAED;;;;;;;;;;OAUG;IACH,sBAYC;IAED;;;;;;;;;;;OAWG;IACH,sBAQC;IAED;;;;;;;;;;OAUG;IACH,gCAGC;IAED;;;;;;;;;;OAUG;IACH,mCAMC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,yBA2BC;CACF;;;;;;;UAhc4C,CAAC;YAAO,MAAM,GAAE,GAAG;KAAC,GAAC,OAAO,CAAC;YAAO,MAAM,GAAE,GAAG;KAAC,CAAC,CAAC;;;;cAEjF,CAAS,IAAmB,EAAnB;YAAO,MAAM,GAAE,GAAG;KAAC,KAAG,MAAM;;;;;;UAEN,MAAM;;;;;;;;;;;;aAQrC,CAAS,IAAK,EAAL,KAAK,EAAE,IAAmB,EAAnB;YAAO,MAAM,GAAE,GAAG;KAAC,KAAG,IAAI;;;;UAE1C,MAAM;;;;;;eAMN,WAAW;;;;;;;;;;aAIX,MAAY,IAAI;;wBA7BN,uBAAuB;uBADxB,sBAAsB;yBAEpB,wBAAwB"}

package/types/modules/Emitter.d.ts

@@ -1,34 +1,50 @@
 /**
- * @class 🎙️ Emitter
- * @classdesc Robust inter-component communication with event bubbling.
- * Implements a basic publish-subscribe pattern for event handling, allowing components
- * to communicate through custom events.
+ * @class 📡 Emitter
+ * @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.
+ *
+ * @example
+ * 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"
  */
 export class Emitter {
-    /** @type {Object.<string, Function[]>} Storage for event handlers mapped by event name */
-    events: {
-        [x: string]: Function[];
-    };
+    /** @private {Map<string, Set<function(any): void>>} Map of event names to their registered handler functions */
+    private _events;
     /**
-     * Registers an event handler for the specified event.
+     * Registers an event handler for the specified event name.
+     * The handler will be called with the event data when the event is emitted.
      *
-     * @param {string} event - The name of the event.
-     * @param {function(...any): void} handler - The function to call when the event is emitted.
+     * @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.
+     * @example
+     * const unsubscribe = emitter.on('user:login', (user) => console.log(user));
+     * // Later...
+     * unsubscribe(); // Stops listening for the event
      */
-    on(event: string, handler: (...args: any[]) => void): void;
+    public on(event: string, handler: (arg0: any) => void): () => boolean;
     /**
-     * Removes a previously registered event handler.
+     * Removes an event handler for the specified event name.
+     * If no handler is provided, all handlers for the event are removed.
      *
+     * @public
      * @param {string} event - The name of the event.
-     * @param {function(...any): void} handler - The handler function to remove.
+     * @param {function(any): void} [handler] - The specific handler function to remove.
+     * @returns {void}
      */
-    off(event: string, handler: (...args: any[]) => void): void;
+    public off(event: string, handler?: (arg0: any) => void): void;
     /**
-     * Emits an event, invoking all handlers registered for that event.
+     * Emits an event with the specified data to all registered handlers.
+     * Handlers are called synchronously in the order they were registered.
      *
-     * @param {string} event - The event name.
-     * @param {...any} args - Additional arguments to pass to the event handlers.
+     * @public
+     * @param {string} event - The name of the event to emit.
+     * @param {...any} args - Optional arguments to pass to the event handlers.
+     * @returns {void}
      */
-    emit(event: string, ...args: any[]): void;
+    public emit(event: string, ...args: any[]): void;
 }
 //# sourceMappingURL=Emitter.d.ts.map

package/types/modules/Emitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Emitter.d.ts","sourceRoot":"","sources":["../../src/modules/Emitter.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IAKI,0FAA0F;IAC1F;;MAAgB;IAGlB;;;;;OAKG;IACH,UAHW,MAAM,WACN,IAAS,IAAM,EAAH,GAAG,EAAA,KAAG,IAAI,QAIhC;IAED;;;;;OAKG;IACH,WAHW,MAAM,WACN,IAAS,IAAM,EAAH,GAAG,EAAA,KAAG,IAAI,QAMhC;IAED;;;;;OAKG;IACH,YAHW,MAAM,WACH,GAAG,EAAA,QAIhB;CACF"}
+{"version":3,"file":"Emitter.d.ts","sourceRoot":"","sources":["../../src/modules/Emitter.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH;IAOI,gHAAgH;IAChH,gBAAwB;IAG1B;;;;;;;;;;;;OAYG;IACH,iBARW,MAAM,WACN,CAAS,IAAG,EAAH,GAAG,KAAG,IAAI,GACjB,MAAY,OAAO,CAW/B;IAED;;;;;;;;OAQG;IACH,kBAJW,MAAM,YACN,CAAS,IAAG,EAAH,GAAG,KAAG,IAAI,GACjB,IAAI,CAYhB;IAED;;;;;;;;OAQG;IACH,mBAJW,MAAM,WACH,GAAG,EAAA,GACJ,IAAI,CAKhB;CACF"}