eleva 1.2.6-alpha → 1.2.8-alpha

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"}

package/types/modules/Renderer.d.ts

@@ -1,33 +1,50 @@
 /**
  * @class 🎨 Renderer
- * @classdesc Handles DOM patching, diffing, and attribute updates.
- * Provides methods for efficient DOM updates by diffing the new and old DOM structures
- * and applying only the necessary changes.
+ * @classdesc A DOM renderer that handles efficient DOM updates through patching and diffing.
+ * Provides methods for updating the DOM by comparing new and old structures and applying
+ * only the necessary changes, minimizing layout thrashing and improving performance.
+ *
+ * @example
+ * const renderer = new Renderer();
+ * const container = document.getElementById("app");
+ * const newHtml = "<div>Updated content</div>";
+ * renderer.patchDOM(container, newHtml);
  */
 export class Renderer {
     /**
      * 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.
      *
+     * @public
      * @param {HTMLElement} container - The container element to patch.
      * @param {string} newHtml - The new HTML content to apply.
-     * @throws {Error} If container is not an HTMLElement or newHtml is not a string
+     * @returns {void}
+     * @throws {Error} If container is not an HTMLElement or newHtml is not a string.
      */
-    patchDOM(container: HTMLElement, newHtml: string): void;
+    public patchDOM(container: HTMLElement, newHtml: string): void;
     /**
      * Diffs two DOM trees (old and new) and applies updates to the old DOM.
+     * This method recursively compares nodes and their attributes, applying only
+     * the necessary changes to minimize DOM operations.
      *
+     * @private
      * @param {HTMLElement} oldParent - The original DOM element.
      * @param {HTMLElement} newParent - The new DOM element.
-     * @throws {Error} If either parent is not an HTMLElement
+     * @returns {void}
+     * @throws {Error} If either parent is not an HTMLElement.
      */
-    diff(oldParent: HTMLElement, newParent: HTMLElement): void;
+    private diff;
     /**
      * Updates the attributes of an element to match those of a new element.
+     * Handles special cases for ARIA attributes, data attributes, and boolean properties.
      *
+     * @private
      * @param {HTMLElement} oldEl - The element to update.
      * @param {HTMLElement} newEl - The element providing the updated attributes.
-     * @throws {Error} If either element is not an HTMLElement
+     * @returns {void}
+     * @throws {Error} If either element is not an HTMLElement.
      */
-    updateAttributes(oldEl: HTMLElement, newEl: HTMLElement): void;
+    private updateAttributes;
 }
 //# sourceMappingURL=Renderer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../src/modules/Renderer.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACE;;;;;;OAMG;IACH,oBAJW,WAAW,WACX,MAAM,QAehB;IAED;;;;;;OAMG;IACH,gBAJW,WAAW,aACX,WAAW,QAkErB;IAED;;;;;;OAMG;IACH,wBAJW,WAAW,SACX,WAAW,QA+DrB;CACF"}
+{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../src/modules/Renderer.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH;IACE;;;;;;;;;;OAUG;IACH,2BALW,WAAW,WACX,MAAM,GACJ,IAAI,CAehB;IAED;;;;;;;;;;OAUG;IACH,aA+DC;IAED;;;;;;;;;OASG;IACH,yBA4DC;CACF"}

package/types/modules/Signal.d.ts

@@ -1,41 +1,57 @@
 /**
  * @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: any);
-    /** @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 */
     private _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 */
     private _watchers;
     /** @private {boolean} Flag to prevent multiple synchronous watcher notifications and batch updates into microtasks */
     private _pending;
     /**
      * 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: any);
+    public set value(newVal: T);
     /**
      * 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(): any;
+    public get value(): T;
     /**
      * 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: (arg0: any) => void): () => boolean;
+    public watch(fn: (arg0: T) => void): () => boolean;
     /**
      * Notifies all registered watchers of a value change using microtask scheduling.
      * Uses a pending flag to batch multiple synchronous updates into a single notification.

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

@@ -1 +1 @@
-{"version":3,"file":"Signal.d.ts","sourceRoot":"","sources":["../../src/modules/Signal.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACE;;;;OAIG;IACH,mBAFW,GAAC,EASX;IANC,mEAAmE;IACnE,eAAmB;IACnB,kGAAkG;IAClG,kBAA0B;IAC1B,sHAAsH;IACtH,iBAAqB;IAYvB;;;;OAIG;IACH,kBAFW,GAAC,EAOX;IAnBD;;;;OAIG;IACH,aAFa,GAAC,CAIb;IAcD;;;;;OAKG;IACH,UAHW,CAAS,IAAG,EAAH,GAAG,KAAG,IAAI,GACjB,MAAY,OAAO,CAK/B;IAED;;;;;;;OAOG;IACH,wBAQC;CACF"}
+{"version":3,"file":"Signal.d.ts","sourceRoot":"","sources":["../../src/modules/Signal.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH;IACE;;;;;OAKG;IACH,mBAFW,GAAC,EASX;IANC,6GAA6G;IAC7G,eAAmB;IACnB,sIAAsI;IACtI,kBAA0B;IAC1B,sHAAsH;IACtH,iBAAqB;IAavB;;;;;;;OAOG;IACH,yBAHW,CAAC,EAQX;IAvBD;;;;;OAKG;IACH,oBAFa,CAAC,CAIb;IAiBD;;;;;;;;;;;OAWG;IACH,iBAPW,CAAS,IAAC,EAAD,CAAC,KAAG,IAAI,GACf,MAAY,OAAO,CAS/B;IAED;;;;;;;OAOG;IACH,wBAQC;CACF"}

package/types/modules/TemplateEngine.d.ts

@@ -1,29 +1,47 @@
 /**
  * @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 }}
+     */
+    private static expressionPattern;
+    /**
+     * 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: string, data: {
-        [x: string]: any;
-    }): string;
+    public static parse(template: string, data: Object): string;
     /**
-     * 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: string, data: {
-        [x: string]: any;
-    }): any;
+    public static evaluate(expression: string, data: Object): any;
 }
 //# sourceMappingURL=TemplateEngine.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"TemplateEngine.d.ts","sourceRoot":"","sources":["../../src/modules/TemplateEngine.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACE;;;;;;OAMG;IACH,uBAJW,MAAM;;QAEJ,MAAM,CAQlB;IAED;;;;;;OAMG;IACH,sBAJW,MAAM;;QAEJ,GAAG,CAgBf;CACF"}
+{"version":3,"file":"TemplateEngine.d.ts","sourceRoot":"","sources":["../../src/modules/TemplateEngine.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH;IACE;;OAEG;IACH,iCAAkD;IAElD;;;;;;;;;;;;;OAaG;IACH,8BARW,MAAM,QACN,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;;;;;;;;OAYG;IACH,mCAPW,MAAM,QACN,MAAM,GACJ,GAAC,CAYb;CACF"}