eleva 1.0.1 → 1.1.0

package/src/core/Eleva.js

@@ -1,12 +1,18 @@
 "use strict";
 
+/**
+ * @module eleva
+ * @fileoverview Core Eleva framework providing signal-based component lifecycle management,
+ * reactive rendering, and plugin architecture.
+ */
+
 import { TemplateEngine } from "../modules/TemplateEngine.js";
 import { Signal } from "../modules/Signal.js";
 import { Emitter } from "../modules/Emitter.js";
 import { Renderer } from "../modules/Renderer.js";
 
 // ============================================================================
-// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// TYPE DEFINITIONS
 // ============================================================================
 
 // -----------------------------------------------------------------------------
@@ -14,13 +20,8 @@ import { Renderer } from "../modules/Renderer.js";
 // -----------------------------------------------------------------------------
 
 /**
- * @typedef {Object} ElevaConfig
- * @property {boolean} [debug=false]
- *           Enable debug mode for verbose logging
- * @property {string} [prefix='e']
- *           Prefix for component style scoping
- * @property {boolean} [async=true]
- *           Enable async component setup
+ * Configuration options for the Eleva instance (reserved for future use).
+ * @typedef {Record<string, unknown>} ElevaConfig
  */
 
 // -----------------------------------------------------------------------------
@@ -28,43 +29,54 @@ import { Renderer } from "../modules/Renderer.js";
 // -----------------------------------------------------------------------------
 
 /**
+ * Component definition object.
  * @typedef {Object} ComponentDefinition
  * @property {SetupFunction} [setup]
- *           Optional setup function that initializes the component's state and returns reactive data
- * @property {TemplateFunction|string} template
- *           Required function or string that defines the component's HTML structure
- * @property {StyleFunction|string} [style]
- *           Optional function or string that provides component-scoped CSS styles
+ *           Optional setup function that initializes the component's state and returns reactive data.
+ * @property {TemplateFunction | string} template
+ *           Required function or string that defines the component's HTML structure.
+ * @property {StyleFunction | string} [style]
+ *           Optional function or string that provides CSS styles for the component.
+ *           Styles are preserved across DOM diffs via data-e-style markers.
  * @property {ChildrenMap} [children]
- *           Optional object defining nested child components
+ *           Optional object defining nested child components.
  */
 
 /**
+ * Setup function that initializes component state.
  * @callback SetupFunction
- * @param {ComponentContext} ctx - The component context with props, emitter, and signal factory
- * @returns {SetupResult|Promise<SetupResult>} Reactive data and lifecycle hooks
+ * @param {ComponentContext} ctx
+ *        The component context with props, emitter, and signal factory.
+ * @returns {SetupResult | Promise<SetupResult>}
+ *          Reactive data and lifecycle hooks.
  */
 
 /**
+ * Data returned from setup function, may include lifecycle hooks.
  * @typedef {Record<string, unknown> & LifecycleHooks} SetupResult
- *           Data returned from setup function, may include lifecycle hooks
  */
 
 /**
+ * Template function that returns HTML markup.
  * @callback TemplateFunction
- * @param {ComponentContext} ctx - The component context
- * @returns {string|Promise<string>} HTML template string
+ * @param {ComponentContext & SetupResult} ctx
+ *        The merged component context and setup data.
+ * @returns {string | Promise<string>}
+ *          HTML template string.
  */
 
 /**
+ * Style function that returns CSS styles.
  * @callback StyleFunction
- * @param {ComponentContext} ctx - The component context
- * @returns {string} CSS styles string
+ * @param {ComponentContext & SetupResult} ctx
+ *        The merged component context and setup data.
+ * @returns {string}
+ *          CSS styles string.
  */
 
 /**
- * @typedef {Record<string, ComponentDefinition|string>} ChildrenMap
- *           Map of CSS selectors to component definitions or registered component names
+ * Map of CSS selectors to component definitions or registered component names.
+ * @typedef {Record<string, ComponentDefinition | string>} ChildrenMap
  */
 
 // -----------------------------------------------------------------------------
@@ -72,25 +84,28 @@ import { Renderer } from "../modules/Renderer.js";
 // -----------------------------------------------------------------------------
 
 /**
+ * Context passed to component setup function.
  * @typedef {Object} ComponentContext
  * @property {ComponentProps} props
- *           Component properties passed during mounting
+ *           Component properties passed during mounting.
  * @property {Emitter} emitter
- *           Event emitter instance for component event handling
+ *           Event emitter instance for component event handling.
  * @property {SignalFactory} signal
- *           Factory function to create reactive Signal instances
+ *           Factory function to create reactive Signal instances.
+ * @description
+ * Plugins may extend this context with additional properties (e.g., `ctx.router`, `ctx.store`).
+ * @see RouterContext - Router plugin injected context.
+ * @see StoreApi - Store plugin injected context.
  */
 
 /**
+ * Properties passed to a component during mounting.
  * @typedef {Record<string, unknown>} ComponentProps
- *           Properties passed to a component during mounting
  */
 
 /**
- * @callback SignalFactory
- * @template T
- * @param {T} initialValue - The initial value for the signal
- * @returns {Signal<T>} A new Signal instance
+ * Factory function to create reactive Signal instances.
+ * @typedef {<T>(initialValue: T) => Signal<T>} SignalFactory
  */
 
 // -----------------------------------------------------------------------------
@@ -98,57 +113,65 @@ import { Renderer } from "../modules/Renderer.js";
 // -----------------------------------------------------------------------------
 
 /**
+ * Lifecycle hooks that can be returned from setup function.
  * @typedef {Object} LifecycleHooks
  * @property {LifecycleHook} [onBeforeMount]
- *           Hook called before component mounting
+ *           Called before component mounting.
  * @property {LifecycleHook} [onMount]
- *           Hook called after component mounting
+ *           Called after component mounting.
  * @property {LifecycleHook} [onBeforeUpdate]
- *           Hook called before component update
+ *           Called before component update.
  * @property {LifecycleHook} [onUpdate]
- *           Hook called after component update
+ *           Called after component update.
  * @property {UnmountHook} [onUnmount]
- *           Hook called during component unmounting
+ *           Called during component unmounting.
  */
 
 /**
+ * Lifecycle hook function.
  * @callback LifecycleHook
- * @param {LifecycleHookContext} ctx - Context with container and component data
- * @returns {void|Promise<void>}
+ * @param {LifecycleHookContext} ctx
+ *        Context with container and component data.
+ * @returns {void | Promise<void>}
  */
 
 /**
+ * Unmount hook function with cleanup resources.
  * @callback UnmountHook
- * @param {UnmountHookContext} ctx - Context with cleanup resources
- * @returns {void|Promise<void>}
+ * @param {UnmountHookContext} ctx
+ *        Context with cleanup resources.
+ * @returns {void | Promise<void>}
  */
 
 /**
+ * Context passed to lifecycle hooks.
  * @typedef {Object} LifecycleHookContext
  * @property {HTMLElement} container
- *           The DOM element where the component is mounted
+ *           The DOM element where the component is mounted.
  * @property {ComponentContext & SetupResult} context
- *           The component's reactive state and context data
+ *           The component's reactive state and context data.
  */
 
 /**
+ * Context passed to unmount hook with cleanup resources.
  * @typedef {Object} UnmountHookContext
  * @property {HTMLElement} container
- *           The DOM element where the component is mounted
+ *           The DOM element where the component is mounted.
  * @property {ComponentContext & SetupResult} context
- *           The component's reactive state and context data
+ *           The component's reactive state and context data.
  * @property {CleanupResources} cleanup
- *           Object containing cleanup functions and instances
+ *           Object containing cleanup functions and instances.
  */
 
 /**
+ * Resources available for cleanup during unmount.
  * @typedef {Object} CleanupResources
- * @property {Array<UnsubscribeFunction>} watchers
- *           Signal watcher cleanup functions
- * @property {Array<UnsubscribeFunction>} listeners
- *           Event listener cleanup functions
- * @property {Array<MountResult>} children
- *           Child component instances
+ * @property {UnsubscribeFunction[]} watchers
+ *           Signal watcher cleanup functions.
+ * @property {UnsubscribeFunction[]} listeners
+ *           Event listener cleanup functions.
+ * @property {MountResult[]} children
+ *           Child component instances.
  */
 
 // -----------------------------------------------------------------------------
@@ -156,23 +179,26 @@ import { Renderer } from "../modules/Renderer.js";
 // -----------------------------------------------------------------------------
 
 /**
+ * Result of mounting a component.
  * @typedef {Object} MountResult
  * @property {HTMLElement} container
- *           The DOM element where the component is mounted
+ *           The DOM element where the component is mounted.
  * @property {ComponentContext & SetupResult} data
- *           The component's reactive state and context data
+ *           The component's reactive state and context data.
  * @property {UnmountFunction} unmount
- *           Function to clean up and unmount the component
+ *           Function to clean up and unmount the component.
  */
 
 /**
+ * Function to unmount a component and clean up resources.
  * @callback UnmountFunction
  * @returns {Promise<void>}
  */
 
 /**
+ * Function to unsubscribe from events or watchers.
  * @callback UnsubscribeFunction
- * @returns {void|boolean}
+ * @returns {void | boolean}
  */
 
 // -----------------------------------------------------------------------------
@@ -180,31 +206,39 @@ import { Renderer } from "../modules/Renderer.js";
 // -----------------------------------------------------------------------------
 
 /**
+ * Plugin interface for extending Eleva.
  * @typedef {Object} ElevaPlugin
- * @property {PluginInstallFunction} install
- *           Function that installs the plugin into the Eleva instance
  * @property {string} name
- *           Unique identifier name for the plugin
+ *           Unique identifier name for the plugin.
+ * @property {string} [version]
+ *           Optional version string for the plugin.
+ * @property {PluginInstallFunction} install
+ *           Function that installs the plugin.
  * @property {PluginUninstallFunction} [uninstall]
- *           Optional function to uninstall the plugin
+ *           Optional function to uninstall the plugin.
  */
 
 /**
+ * Plugin install function.
  * @callback PluginInstallFunction
- * @param {Eleva} eleva - The Eleva instance
- * @param {PluginOptions} options - Plugin configuration options
- * @returns {void|Eleva|unknown} Optionally returns the Eleva instance or plugin result
+ * @param {Eleva} eleva
+ *        The Eleva instance.
+ * @param {PluginOptions} [options]
+ *        Plugin configuration options.
+ * @returns {void | Eleva | unknown}
  */
 
 /**
+ * Plugin uninstall function.
  * @callback PluginUninstallFunction
- * @param {Eleva} eleva - The Eleva instance
- * @returns {void}
+ * @param {Eleva} eleva
+ *        The Eleva instance.
+ * @returns {void | Promise<void>}
  */
 
 /**
+ * Configuration options passed to a plugin during installation.
  * @typedef {Record<string, unknown>} PluginOptions
- *           Configuration options passed to a plugin during installation
  */
 
 // -----------------------------------------------------------------------------
@@ -212,20 +246,19 @@ import { Renderer } from "../modules/Renderer.js";
 // -----------------------------------------------------------------------------
 
 /**
- * @callback EventHandler
- * @param {Event} event - The DOM event object
- * @returns {void}
+ * Handler function for DOM events (e.g., click, input, submit).
+ * @typedef {(event: Event) => void} DOMEventHandler
  */
 
 /**
+ * Common DOM event names (prefixed with @ in templates).
  * @typedef {'click'|'submit'|'input'|'change'|'focus'|'blur'|'keydown'|'keyup'|'keypress'|'mouseenter'|'mouseleave'|'mouseover'|'mouseout'|'mousedown'|'mouseup'|'touchstart'|'touchend'|'touchmove'|'scroll'|'resize'|'load'|'error'|string} DOMEventName
- *           Common DOM event names (prefixed with @ in templates)
  */
 
 /**
  * @class 🧩 Eleva
  * @classdesc A modern, signal-based component runtime framework that provides lifecycle hooks,
- * scoped styles, and plugin support. Eleva manages component registration, plugin integration,
+ * component styles, and plugin support. Eleva manages component registration, plugin integration,
  * event handling, and DOM rendering with a focus on performance and developer experience.
  *
  * @example
@@ -255,11 +288,10 @@ export class Eleva {
    * Creates a new Eleva instance with the specified name and configuration.
    *
    * @public
+   * @constructor
    * @param {string} name - The unique identifier name for this Eleva instance.
-   * @param {Record<string, unknown>} [config={}] - Optional configuration object for the instance.
-   *        May include framework-wide settings and default behaviors.
+   * @param {ElevaConfig} [config={}] - Optional configuration object for the instance.
    * @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");
@@ -274,17 +306,17 @@ export class Eleva {
     if (!name || typeof name !== "string") {
       throw new Error("Eleva: name must be a non-empty string");
     }
-    /** @public {string} The unique identifier name for this Eleva instance */
+    /** @public @readonly {string} The unique identifier name for this Eleva instance */
     this.name = name;
-    /** @public {Object<string, unknown>} Optional configuration object for the Eleva instance */
+    /** @public @readonly {Record<string, unknown>} Configuration object for the Eleva instance */
     this.config = config;
-    /** @public {Emitter} Instance of the event emitter for handling component events */
+    /** @public @readonly {Emitter} Event emitter for handling component events */
     this.emitter = new Emitter();
-    /** @public {typeof Signal} Static reference to the Signal class for creating reactive state */
+    /** @public @readonly {typeof Signal} Signal class for creating reactive state */
     this.signal = Signal;
-    /** @public {typeof TemplateEngine} Static reference to the TemplateEngine class for template parsing */
+    /** @public @readonly {typeof TemplateEngine} TemplateEngine class for template parsing */
     this.templateEngine = TemplateEngine;
-    /** @public {Renderer} Instance of the renderer for handling DOM updates and patching */
+    /** @public @readonly {Renderer} Renderer for handling DOM updates and patching */
     this.renderer = new Renderer();
 
     /** @private {Map<string, ComponentDefinition>} Registry of all component definitions by name */
@@ -300,14 +332,16 @@ export class Eleva {
    * 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.
    *
-   * Note: Plugins that wrap core methods (e.g., mount) must be uninstalled in reverse order
+   * @note Plugins that wrap core methods (e.g., mount) must be uninstalled in reverse order
    * of installation (LIFO - Last In, First Out) to avoid conflicts.
    *
    * @public
    * @param {ElevaPlugin} plugin - The plugin object which must have an `install` function.
-   * @param {Object<string, unknown>} [options={}] - Optional configuration options for the plugin.
-   * @returns {Eleva} The Eleva instance (for method chaining).
+   * @param {PluginOptions} [options={}] - Optional configuration options for the plugin.
+   * @returns {Eleva | unknown} The Eleva instance (for method chaining) or the result returned by the plugin.
    * @throws {Error} If plugin does not have an install function.
+   * @see component - Register components after installing plugins.
+   * @see mount - Mount components to the DOM.
    * @example
    * app.use(myPlugin, { option1: "value1" });
    *
@@ -338,6 +372,7 @@ export class Eleva {
    * @param {ComponentDefinition} definition - The component definition including setup, template, style, and children.
    * @returns {Eleva} The Eleva instance (for method chaining).
    * @throws {Error} If name is not a non-empty string or definition has no template.
+   * @see mount - Mount this component to the DOM.
    * @example
    * app.component("myButton", {
    *   template: (ctx) => `<button>${ctx.props.text}</button>`,
@@ -359,21 +394,25 @@ export class 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.
+   * If the container already has a mounted Eleva instance, it is returned as-is.
+   * Unmount clears the container contents and removes the internal instance marker.
    *
    * @public
+   * @async
    * @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, unknown>} [props={}] - Optional properties to pass to the component.
+   * @param {string | ComponentDefinition} compName - The name of the registered component or a direct component definition.
+   * @param {ComponentProps} [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
    *          - data: The component's reactive state and context
    *          - unmount: Function to clean up and unmount the component
    * @throws {Error} If container is not a DOM element or component is not registered.
+   * @throws {Error} If setup function, template function, or style function throws.
    * @example
    * const instance = await app.mount(document.getElementById("app"), "myComponent", { text: "Click me" });
    * // Later...
-   * instance.unmount();
+   * await instance.unmount();
    */
   async mount(container, compName, props = {}) {
     if (!container?.nodeType) {
@@ -394,7 +433,7 @@ export class Eleva {
      * Destructure the component definition to access core functionality.
      * - setup: Optional function for component initialization and state management
      * - template: Required function or string that returns the component's HTML structure
-     * - style: Optional function or string for component-scoped CSS styles
+     * - style: Optional function or string for component CSS styles (not auto-scoped)
      * - children: Optional object defining nested child components
      */
     const { setup, template, style, children } = definition;
@@ -403,7 +442,7 @@ export class Eleva {
     const context = {
       props,
       emitter: this.emitter,
-      /** @type {(v: unknown) => Signal<unknown>} */
+      /** @type {SignalFactory} */
       signal: (v) => new this.signal(v),
     };
 
@@ -415,20 +454,21 @@ export class Eleva {
      * 3. Rendering the component
      * 4. Managing component lifecycle
      *
-     * @param {Object<string, unknown>} data - Data returned from the component's setup function
+     * @inner
+     * @param {Record<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 {ComponentContext} */
+      /** @type {ComponentContext & SetupResult} */
       const mergedContext = { ...context, ...data };
-      /** @type {Array<() => void>} */
+      /** @type {UnsubscribeFunction[]} */
       const watchers = [];
-      /** @type {Array<MountResult>} */
+      /** @type {MountResult[]} */
       const childInstances = [];
-      /** @type {Array<() => void>} */
+      /** @type {UnsubscribeFunction[]} */
       const listeners = [];
       /** @private {boolean} Local mounted state for this component instance */
       let isMounted = false;
@@ -446,7 +486,10 @@ export class Eleva {
        * changes in the same synchronous block will each call this function,
        * but only one render will be scheduled via queueMicrotask.
        * This separates concerns: signals handle state, components handle scheduling.
+       *
+       * @inner
        * @private
+       * @returns {void}
        */
       const scheduleRender = () => {
         if (renderScheduled) return;
@@ -463,6 +506,10 @@ export class Eleva {
        * 2. Processing the template
        * 3. Updating the DOM
        * 4. Processing events, injecting styles, and mounting child components.
+       *
+       * @inner
+       * @private
+       * @returns {Promise<void>}
        */
       const render = async () => {
         const html =
@@ -484,6 +531,22 @@ export class Eleva {
         }
 
         this.renderer.patchDOM(container, html);
+
+        // Unmount child components whose host elements were removed by patching.
+        const childrenToUnmount = [];
+        for (let i = childInstances.length - 1; i >= 0; i--) {
+          const child = childInstances[i];
+          if (!container.contains(child.container)) {
+            childInstances.splice(i, 1);
+            childrenToUnmount.push(child);
+          }
+        }
+        if (childrenToUnmount.length) {
+          await Promise.allSettled(
+            childrenToUnmount.map((child) => child.unmount())
+          );
+        }
+
         this._processEvents(container, mergedContext, listeners);
         if (style) this._injectStyles(container, compId, style, mergedContext);
         if (children)
@@ -514,6 +577,10 @@ export class Eleva {
        * When a Signal's value changes, a batched render is scheduled.
        * Multiple changes within the same frame are collapsed into one render.
        * Stores unsubscribe functions to clean up watchers when component unmounts.
+       *
+       * @note Signal watchers are invoked synchronously when values change.
+       * Render batching is handled at the component level via queueMicrotask,
+       * not at the signal level. This preserves stack traces for debugging.
        */
       for (const val of Object.values(data)) {
         if (val instanceof Signal) watchers.push(val.watch(scheduleRender));
@@ -526,17 +593,17 @@ export class Eleva {
         data: mergedContext,
         /**
          * Unmounts the component, cleaning up watchers and listeners, child components, and clearing the container.
+         * Removes the internal instance marker from the container when complete.
          *
-         * @returns {void}
+         * @returns {Promise<void>}
          */
         unmount: async () => {
-          /** @type {UnmountHookContext} */
           await mergedContext.onUnmount?.({
             container,
             context: mergedContext,
             cleanup: {
-              watchers: watchers,
-              listeners: listeners,
+              watchers,
+              listeners,
               children: childInstances,
             },
           });
@@ -559,13 +626,19 @@ export class Eleva {
 
   /**
    * 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.
+   * This method attaches event listeners directly to elements and ensures proper cleanup.
+   * Bound `@event` attributes are removed after listeners are attached.
+   *
+   * Handler resolution order:
+   * 1. Direct context property lookup (e.g., context["handleClick"])
+   * 2. Template expression evaluation via TemplateEngine (e.g., "increment()")
    *
    * @private
    * @param {HTMLElement} container - The container element in which to search for event attributes.
-   * @param {ComponentContext} context - The current component context containing event handler definitions.
-   * @param {Array<() => void>} listeners - Array to collect cleanup functions for each event listener.
+   * @param {ComponentContext & SetupResult} context - The merged component context and setup data.
+   * @param {UnsubscribeFunction[]} listeners - Array to collect cleanup functions for each event listener.
    * @returns {void}
+   * @see TemplateEngine.evaluate - Expression evaluation. fallback.
    */
   _processEvents(container, context, listeners) {
     /** @type {NodeListOf<Element>} */
@@ -583,7 +656,7 @@ export class Eleva {
         const event = attr.name.slice(1);
         /** @type {string} */
         const handlerName = attr.value;
-        /** @type {(event: Event) => void} */
+        /** @type {DOMEventHandler} */
         const handler =
           context[handlerName] ||
           this.templateEngine.evaluate(handlerName, context);
@@ -597,14 +670,18 @@ export class Eleva {
   }
 
   /**
-   * Injects scoped styles into the component's container.
-   * The styles are automatically prefixed to prevent style leakage to other components.
+   * Injects styles into the component's container.
+   * Styles are placed in a `<style>` element with a `data-e-style` attribute for identification.
+   *
+   * @note Styles are not automatically scoped - use unique class names or CSS nesting for isolation.
+   *
+   * Optimization: Skips DOM update if style content hasn't changed.
    *
    * @private
    * @param {HTMLElement} container - The container element where styles should be injected.
    * @param {string} compId - The component ID used to identify the style element.
-   * @param {(function(ComponentContext): string)|string} styleDef - The component's style definition (function or string).
-   * @param {ComponentContext} context - The current component context for style interpolation.
+   * @param {StyleFunction | string} styleDef - The component's style definition (function or string).
+   * @param {ComponentContext & SetupResult} context - The merged component context and setup data.
    * @returns {void}
    */
   _injectStyles(container, compId, styleDef, context) {
@@ -612,7 +689,7 @@ export class Eleva {
     const newStyle =
       typeof styleDef === "function" ? styleDef(context) : styleDef;
 
-    /** @type {HTMLStyleElement|null} */
+    /** @type {HTMLStyleElement | null} */
     let styleEl = container.querySelector(`style[data-e-style="${compId}"]`);
 
     if (styleEl && styleEl.textContent === newStyle) return;
@@ -629,11 +706,13 @@ export class Eleva {
    * Extracts and evaluates props from an element's attributes that start with `:`.
    * Prop values are evaluated as expressions against the component context,
    * allowing direct passing of objects, arrays, and other complex types.
+   * Processed attributes are removed from the element after extraction.
    *
    * @private
-   * @param {HTMLElement} element - The DOM element to extract props from
-   * @param {ComponentContext} context - The component context for evaluating prop expressions
-   * @returns {Record<string, string>} An object containing the evaluated props
+   * @param {HTMLElement} element - The DOM element to extract props from.
+   * @param {ComponentContext & SetupResult} context - The merged component context and setup data.
+   * @returns {ComponentProps} An object containing the evaluated props.
+   * @see TemplateEngine.evaluate - Expression evaluation.
    * @example
    * // For an element with attributes:
    * // <div :name="user.name" :data="items">
@@ -662,20 +741,21 @@ export class Eleva {
    * This method handles mounting of explicitly defined children components.
    *
    * The mounting process follows these steps:
-   * 1. Cleans up any existing component instances
+   * 1. Finds matching DOM nodes within the container
    * 2. Mounts explicitly defined children components
    *
    * @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
-   * @param {ComponentContext} context - The parent component context for evaluating prop expressions
+   * @async
+   * @param {HTMLElement} container - The container element to mount components in.
+   * @param {ChildrenMap} children - Map of selectors to component definitions for explicit children.
+   * @param {MountResult[]} childInstances - Array to store all mounted component instances.
+   * @param {ComponentContext & SetupResult} context - The merged component context and setup data.
    * @returns {Promise<void>}
    *
    * @example
    * // Explicit children mounting:
    * const children = {
-   *   'UserProfile': UserProfileComponent,
+   *   'user-profile': UserProfileComponent,
    *   '#settings-panel': "settings-panel"
    * };
    */
@@ -684,7 +764,7 @@ export class Eleva {
       if (!selector) continue;
       for (const el of container.querySelectorAll(selector)) {
         if (!(el instanceof HTMLElement)) continue;
-        /** @type {Record<string, string>} */
+        /** @type {ComponentProps} */
         const props = this._extractProps(el, context);
         /** @type {MountResult} */
         const instance = await this.mount(el, component, props);