eleva 1.0.0-alpha → 1.2.0-alpha

package/types/core/Eleva.d.ts

@@ -1,55 +1,95 @@
 /**
- * 🧩 Eleva Core: Signal-based component runtime framework with lifecycle, scoped styles, and plugins.
+ * 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.
  *
- * The Eleva class is the core of the framework. It manages component registration,
- * plugin integration, lifecycle hooks, event handling, and DOM rendering.
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ */
+/**
+ * @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.
  */
 export class Eleva {
     /**
      * Creates a new Eleva instance.
      *
      * @param {string} name - The name of the Eleva instance.
-     * @param {object} [config={}] - Optional configuration for the instance.
+     * @param {Object<string, any>} [config={}] - Optional configuration for the instance.
      */
-    constructor(name: string, config?: object);
+    constructor(name: string, config?: {
+        [x: string]: any;
+    });
+    /** @type {string} The unique identifier name for this Eleva instance */
     name: string;
-    config: object;
-    _components: {};
-    _plugins: any[];
-    _lifecycleHooks: string[];
-    _isMounted: boolean;
-    emitter: Emitter;
-    renderer: Renderer;
+    /** @type {Object<string, any>} Optional configuration object for the Eleva instance */
+    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 */
+    private _plugins;
+    /** @private {string[]} Array of lifecycle hook names supported by the component */
+    private _lifecycleHooks;
+    /** @private {boolean} Flag indicating if component is currently mounted */
+    private _isMounted;
+    /** @private {Emitter} Instance of the event emitter for handling component events */
+    private emitter;
+    /** @private {Renderer} Instance of the renderer for handling DOM updates and patching */
+    private renderer;
     /**
      * Integrates a plugin with the Eleva framework.
      *
-     * @param {object} [plugin] - The plugin object which should have an install function.
-     * @param {object} [options={}] - Optional options to pass to the plugin.
+     * @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).
      */
-    use(plugin?: object, options?: object): Eleva;
+    use(plugin: Object, options?: {
+        [x: string]: any;
+    }): Eleva;
     /**
      * Registers a component with the Eleva instance.
      *
      * @param {string} name - The name of the component.
-     * @param {object} definition - The component definition including setup, template, style, and children.
+     * @param {ComponentDefinition} definition - The component definition including setup, template, style, and children.
      * @returns {Eleva} The Eleva instance (for chaining).
      */
-    component(name: string, definition: object): Eleva;
+    component(name: string, definition: ComponentDefinition): Eleva;
     /**
      * Mounts a registered component to a DOM element.
      *
-     * @param {string|HTMLElement} selectorOrElement - A CSS selector string or DOM element where the component will be mounted.
-     * @param {string} compName - The name of the component to mount.
-     * @param {object} [props={}] - Optional properties to pass to the component.
+     * @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.
+     * @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 Will throw an error if the container or component is not found.
+     * @throws {Error} If the container is not found or if the component is not registered.
      */
-    mount(selectorOrElement: string | HTMLElement, compName: string, props?: object): object | Promise<object>;
+    mount(container: HTMLElement, compName: string | ComponentDefinition, props?: {
+        [x: string]: any;
+    }): object | Promise<object>;
     /**
      * Prepares default no-operation lifecycle hook functions.
      *
-     * @returns {object} An object with keys for lifecycle hooks mapped to empty functions.
+     * @returns {Object<string, function(): void>} An object with keys for lifecycle hooks mapped to empty functions.
      * @private
      */
     private _prepareLifecycleHooks;
@@ -57,7 +97,7 @@ export class Eleva {
      * Processes DOM elements for event binding based on attributes starting with "@".
      *
      * @param {HTMLElement} container - The container element in which to search for events.
-     * @param {object} context - The current context containing event handler definitions.
+     * @param {Object<string, any>} context - The current context containing event handler definitions.
      * @private
      */
     private _processEvents;
@@ -66,8 +106,8 @@ export class Eleva {
      *
      * @param {HTMLElement} container - The container element.
      * @param {string} compName - The component name used to identify the style element.
-     * @param {Function} styleFn - A function that returns CSS styles as a string.
-     * @param {object} context - The current context for style interpolation.
+     * @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
      */
     private _injectStyles;
@@ -75,12 +115,51 @@ export class Eleva {
      * Mounts child components within the parent component's container.
      *
      * @param {HTMLElement} container - The parent container element.
-     * @param {object} children - An object mapping child component selectors to their definitions.
-     * @param {Array} childInstances - An array to store the mounted child component instances.
+     * @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
      */
     private _mountChildren;
 }
-import { Emitter } from "../modules/Emitter.js";
-import { Renderer } from "../modules/Renderer.js";
+/**
+ * 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.
+     */
+    setup?: ((arg0: {
+        [x: string]: any;
+    }) => ({
+        [x: string]: any;
+    } | Promise<{
+        [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.
+     */
+    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.
+     */
+    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.
+     */
+    children?: {
+        [x: string]: ComponentDefinition;
+    } | undefined;
+};
 //# 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;;;;;GAKG;AACH;IACE;;;;;OAKG;IACH,kBAHW,MAAM,WACN,MAAM,EAiBhB;IAdC,aAAgB;IAChB,eAAoB;IACpB,gBAAqB;IACrB,gBAAkB;IAClB,0BAMC;IACD,oBAAuB;IACvB,iBAA4B;IAC5B,mBAA8B;IAGhC;;;;;;OAMG;IACH,aAJW,MAAM,YACN,MAAM,GACJ,KAAK,CAQjB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,cACN,MAAM,GACJ,KAAK,CAKjB;IAED;;;;;;;;OAQG;IACH,yBANW,MAAM,GAAC,WAAW,YAClB,MAAM,UACN,MAAM,GACJ,MAAM,GAAC,OAAO,CAAC,MAAM,CAAC,CA0FlC;IAED;;;;;OAKG;IACH,+BAKC;IAED;;;;;;OAMG;IACH,uBAaC;IAED;;;;;;;;OAQG;IACH,sBAYC;IAED;;;;;;;OAOG;IACH,uBAgBC;CACF;wBAjPuB,uBAAuB;yBACtB,wBAAwB"}
+{"version":3,"file":"Eleva.d.ts","sourceRoot":"","sources":["../../src/core/Eleva.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;GAIG;AACH;IACE;;;;;OAKG;IACH,kBAHW,MAAM;;OA0BhB;IAtBC,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,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;;;;;;OAMG;IACH,uBAaC;IAED;;;;;;;;OAQG;IACH,sBAYC;IAED;;;;;;;OAOG;IACH,uBAgBC;CACF;;;;;;;;;;;;UAhS4C,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"}

package/types/modules/Emitter.d.ts

@@ -1,11 +1,11 @@
 /**
- * 🎙️ Emitter: 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 Robust inter-component communication with event bubbling.
+ * Implements a basic publish-subscribe pattern for event handling, allowing components
+ * to communicate through custom events.
  */
 export class Emitter {
-    /** @type {Object.<string, Function[]>} */
+    /** @type {Object.<string, Function[]>} Storage for event handlers mapped by event name */
     events: {
         [x: string]: Function[];
     };
@@ -13,21 +13,21 @@ export class Emitter {
      * Registers an event handler for the specified event.
      *
      * @param {string} event - The name of the event.
-     * @param {Function} handler - The function to call when the event is emitted.
+     * @param {function(...any): void} handler - The function to call when the event is emitted.
      */
-    on(event: string, handler: Function): void;
+    on(event: string, handler: (...args: any[]) => void): void;
     /**
      * Removes a previously registered event handler.
      *
      * @param {string} event - The name of the event.
-     * @param {Function} handler - The handler function to remove.
+     * @param {function(...any): void} handler - The handler function to remove.
      */
-    off(event: string, handler: Function): void;
+    off(event: string, handler: (...args: any[]) => void): void;
     /**
      * Emits an event, invoking all handlers registered for that event.
      *
      * @param {string} event - The event name.
-     * @param {...*} args - Additional arguments to pass to the event handlers.
+     * @param {...any} args - Additional arguments to pass to the event handlers.
      */
     emit(event: string, ...args: any[]): void;
 }

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,0CAA0C;IAC1C;;MAAgB;IAGlB;;;;;OAKG;IACH,UAHW,MAAM,2BAKhB;IAED;;;;;OAKG;IACH,WAHW,MAAM,2BAOhB;IAED;;;;;OAKG;IACH,YAHW,MAAM,WACH,GAAC,EAAA,QAId;CACF"}
+{"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"}

package/types/modules/Renderer.d.ts

@@ -1,6 +1,6 @@
 /**
- * 🎨 Renderer: Handles DOM patching, diffing, and attribute updates.
- *
+ * @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.
  */

package/types/modules/Signal.d.ts

@@ -1,8 +1,8 @@
 /**
- * ⚡ Signal: Fine-grained reactivity.
- *
+ * @class ⚡ Signal
+ * @classdesc Fine-grained reactivity.
  * A reactive data holder that notifies registered watchers when its value changes,
- * allowing for fine-grained DOM patching rather than full re-renders.
+ * enabling fine-grained DOM patching rather than full re-renders.
  */
 export class Signal {
     /**
@@ -11,8 +11,10 @@ export class Signal {
      * @param {*} value - The initial value of the signal.
      */
     constructor(value: any);
-    _value: any;
-    _watchers: Set<any>;
+    /** @private {*} Internal storage for the signal's current value */
+    private _value;
+    /** @private {Set<function>} Collection of callback functions to be notified when value changes */
+    private _watchers;
     /**
      * Sets a new value for the signal and notifies all registered watchers if the value has changed.
      *
@@ -28,9 +30,9 @@ export class Signal {
     /**
      * Registers a watcher function that will be called whenever the signal's value changes.
      *
-     * @param {Function} fn - The callback function to invoke on value change.
-     * @returns {Function} A function to unsubscribe the watcher.
+     * @param {function(any): void} fn - The callback function to invoke on value change.
+     * @returns {function(): boolean} A function to unsubscribe the watcher.
      */
-    watch(fn: Function): Function;
+    watch(fn: (arg0: any) => void): () => boolean;
 }
 //# sourceMappingURL=Signal.d.ts.map

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,EAKX;IAFC,YAAmB;IACnB,oBAA0B;IAY5B;;;;OAIG;IACH,kBAFW,GAAC,EAOX;IAnBD;;;;OAIG;IACH,aAFa,GAAC,CAIb;IAcD;;;;;OAKG;IACH,8BAGC;CACF"}
+{"version":3,"file":"Signal.d.ts","sourceRoot":"","sources":["../../src/modules/Signal.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACE;;;;OAIG;IACH,mBAFW,GAAC,EAOX;IAJC,mEAAmE;IACnE,eAAmB;IACnB,kGAAkG;IAClG,kBAA0B;IAY5B;;;;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;CACF"}

package/types/modules/TemplateEngine.d.ts

@@ -1,26 +1,29 @@
 /**
- * 🔒 TemplateEngine: Secure interpolation & dynamic attribute parsing.
- *
- * This class provides methods to parse template strings by replacing
- * interpolation expressions with dynamic data values and to evaluate expressions
- * within a given data context.
+ * @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.
  */
 export class TemplateEngine {
     /**
      * Parses a template string and replaces interpolation expressions with corresponding values.
      *
-     * @param {string} template - The template string containing expressions in the format {{ expression }}.
-     * @param {object} data - The data object to use for evaluating expressions.
+     * @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.
      */
-    static parse(template: string, data: object): string;
+    static parse(template: string, data: {
+        [x: string]: any;
+    }): string;
     /**
-     * Evaluates an expression using the provided data context.
+     * Evaluates a JavaScript expression using the provided data context.
      *
      * @param {string} expr - The JavaScript expression to evaluate.
-     * @param {object} data - The data context for evaluating the expression.
-     * @returns {*} The result of the evaluated expression, or an empty string if undefined or on error.
+     * @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.
      */
-    static evaluate(expr: string, data: object): any;
+    static evaluate(expr: string, data: {
+        [x: string]: any;
+    }): 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;;;;;;GAMG;AACH;IACE;;;;;;OAMG;IACH,uBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAOlB;IAED;;;;;;OAMG;IACH,sBAJW,MAAM,QACN,MAAM,GACJ,GAAC,CAgBb;CACF"}
+{"version":3,"file":"TemplateEngine.d.ts","sourceRoot":"","sources":["../../src/modules/TemplateEngine.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACE;;;;;;OAMG;IACH,uBAJW,MAAM;;QAEJ,MAAM,CAOlB;IAED;;;;;;OAMG;IACH,sBAJW,MAAM;;QAEJ,GAAG,CAgBf;CACF"}