eleva 1.0.0-alpha → 1.2.0-alpha

package/dist/eleva.d.ts

@@ -1,119 +1,95 @@
 /**
- * 🎙️ Emitter: Robust inter-component communication with event bubbling.
+ * 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.
  *
- * Implements a basic publish-subscribe pattern for event handling,
- * allowing components to communicate through custom events.
- */
-declare class Emitter {
-    /** @type {Object.<string, Function[]>} */
-    events: {
-        [x: string]: Function[];
-    };
-    /**
-     * 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.
-     */
-    on(event: string, handler: Function): void;
-    /**
-     * Removes a previously registered event handler.
-     *
-     * @param {string} event - The name of the event.
-     * @param {Function} handler - The handler function to remove.
-     */
-    off(event: string, handler: Function): 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.
-     */
-    emit(event: string, ...args: any[]): void;
-}
-
-/**
- * 🎨 Renderer: Handles DOM patching, diffing, and attribute updates.
+ * @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.
  *
- * Provides methods for efficient DOM updates by diffing the new and old DOM structures
- * and applying only the necessary changes.
+ * @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.
  */
-declare class Renderer {
-    /**
-     * Patches the DOM of a container element with new HTML content.
-     *
-     * @param {HTMLElement} container - The container element to patch.
-     * @param {string} newHtml - The new HTML content to apply.
-     */
-    patchDOM(container: HTMLElement, newHtml: string): void;
-    /**
-     * Diffs two DOM trees (old and new) and applies updates to the old DOM.
-     *
-     * @param {HTMLElement} oldParent - The original DOM element.
-     * @param {HTMLElement} newParent - The new DOM element.
-     */
-    diff(oldParent: HTMLElement, newParent: HTMLElement): void;
-    /**
-     * Updates the attributes of an element to match those of a new element.
-     *
-     * @param {HTMLElement} oldEl - The element to update.
-     * @param {HTMLElement} newEl - The element providing the updated attributes.
-     */
-    updateAttributes(oldEl: HTMLElement, newEl: HTMLElement): void;
-}
-
 /**
- * 🧩 Eleva Core: Signal-based component runtime framework with lifecycle, scoped styles, and plugins.
- *
- * The Eleva class is the core of the framework. It manages component registration,
- * plugin integration, lifecycle hooks, event handling, and DOM rendering.
+ * @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.
  */
 declare 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;
@@ -121,7 +97,7 @@ declare 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;
@@ -130,8 +106,8 @@ declare 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;
@@ -139,12 +115,53 @@ declare 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;
 }
+/**
+ * Defines the structure and behavior of a component.
+ */
+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=index.d.ts.map