eleva 1.0.1 → 1.1.0

package/src/index.cjs

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * @module eleva
+ * @fileoverview CommonJS-only entry point for the Eleva framework.
+ */
+
+import { Eleva } from "./core/Eleva.js";
+
+export default Eleva;

package/src/index.js

@@ -1,5 +1,16 @@
 "use strict";
 
+/**
+ * @module eleva
+ * @fileoverview Main entry point for the Eleva framework.
+ */
+
 import { Eleva } from "./core/Eleva.js";
 
+export * from "./core/Eleva.js";
+export { Emitter } from "./modules/Emitter.js";
+export { Signal } from "./modules/Signal.js";
+export { TemplateEngine } from "./modules/TemplateEngine.js";
+export { Renderer } from "./modules/Renderer.js";
+
 export default Eleva;

package/src/modules/Emitter.js

@@ -1,31 +1,67 @@
 "use strict";
 
+/**
+ * @module eleva/emitter
+ * @fileoverview Event emitter for publish-subscribe communication between components.
+ */
+
 // ============================================================================
-// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// TYPE DEFINITIONS
 // ============================================================================
 
+// -----------------------------------------------------------------------------
+// Callback Types
+// -----------------------------------------------------------------------------
+
 /**
- * @template T
+ * Callback function invoked when an event is emitted.
  * @callback EventHandler
- * @param {...T} args - Event arguments
- * @returns {void|Promise<void>}
+ * @param {...any} args
+ *        Event arguments passed to the handler.
+ * @returns {void | Promise<void>}
  */
 
 /**
+ * Function to unsubscribe an event handler.
  * @callback EventUnsubscribe
  * @returns {void}
  */
 
+// -----------------------------------------------------------------------------
+// Event Types
+// -----------------------------------------------------------------------------
+
 /**
- * @typedef {`${string}:${string}`} EventName
- *           Event names follow the format 'namespace:action' (e.g., 'user:login', 'cart:update')
+ * Event name string identifier.
+ * @typedef {string} EventName
+ * @description
+ * Recommended convention: 'namespace:action' (e.g., 'user:login').
+ * This pattern prevents naming collisions and improves code readability.
+ *
+ * Common namespaces:
+ * - `user:` - User-related events (login, logout, update)
+ * - `component:` - Component lifecycle events (mount, unmount)
+ * - `router:` - Navigation events (beforeEach, afterEach)
+ * - `store:` - State management events (change, error)
+ * @example
+ * 'user:login'      // User logged in
+ * 'cart:update'     // Shopping cart updated
+ * 'component:mount' // Component was mounted
  */
 
+// -----------------------------------------------------------------------------
+// Interface Types
+// -----------------------------------------------------------------------------
+
 /**
+ * Interface describing the public API of an Emitter.
  * @typedef {Object} EmitterLike
- * @property {function(string, EventHandler<unknown>): EventUnsubscribe} on - Subscribe to an event
- * @property {function(string, EventHandler<unknown>=): void} off - Unsubscribe from an event
- * @property {function(string, ...unknown): void} emit - Emit an event
+ * @property {(event: string, handler: EventHandler) => EventUnsubscribe} on
+ *           Subscribe to an event.
+ * @property {(event: string, handler?: EventHandler) => void} off
+ *           Unsubscribe from an event.
+ * @property {(event: string, ...args: unknown[]) => void} emit
+ *           Emit an event with arguments.
  */
 
 /**
@@ -65,6 +101,7 @@
  * // Lifecycle events
  * emitter.on('component:mount', (component) => {});
  * emitter.on('component:unmount', (component) => {});
+ * // Note: These lifecycle names are conventions; Eleva core does not emit them by default.
  * // State events
  * emitter.on('state:change', (newState, oldState) => {});
  * // Navigation events
@@ -74,9 +111,10 @@
  */
 export class Emitter {
   /**
-   * Creates a new Emitter instance.
+   * Creates a new Emitter instance with an empty event registry.
    *
    * @public
+   * @constructor
    *
    * @example
    * const emitter = new Emitter();
@@ -85,7 +123,7 @@ export class Emitter {
     /**
      * Map of event names to their registered handler functions
      * @private
-     * @type {Map<string, Set<EventHandler<unknown>>>}
+     * @type {Map<string, Set<EventHandler>>}
      */
     this._events = new Map();
   }
@@ -96,9 +134,10 @@ export class Emitter {
    * Event names should follow the format 'namespace:action' for consistency.
    *
    * @public
-   * @template T
    * @param {string} event - The name of the event to listen for (e.g., 'user:login').
-   * @param {EventHandler<T>} handler - The callback function to invoke when the event occurs.
+   * @param {EventHandler} handler - The callback function to invoke when the event occurs.
+   *        Note: Handlers returning Promises are NOT awaited. For async operations,
+   *        handle promise resolution within your handler.
    * @returns {EventUnsubscribe} A function to unsubscribe the event handler.
    *
    * @example
@@ -106,8 +145,8 @@ export class Emitter {
    * const unsubscribe = emitter.on('user:login', (user) => console.log(user));
    *
    * @example
-   * // Typed handler
-   * emitter.on('user:update', (/** @type {{id: number, name: string}} *\/ user) => {
+   * // Handler with typed parameter
+   * emitter.on('user:update', (user) => {
    *   console.log(`User ${user.id}: ${user.name}`);
    * });
    *
@@ -124,13 +163,15 @@ export class Emitter {
 
   /**
    * Removes an event handler for the specified event name.
-   * If no handler is provided, all handlers for the event are removed.
    * Automatically cleans up empty event sets to prevent memory leaks.
    *
+   * Behavior varies based on whether handler is provided:
+   * - With handler: Removes only that specific handler function (O(1) Set deletion)
+   * - Without handler: Removes ALL handlers for the event (O(1) Map deletion)
+   *
    * @public
-   * @template T
    * @param {string} event - The name of the event to remove handlers from.
-   * @param {EventHandler<T>} [handler] - The specific handler function to remove.
+   * @param {EventHandler} [handler] - The specific handler to remove. If omitted, all handlers are removed.
    * @returns {void}
    *
    * @example
@@ -158,12 +199,19 @@ export class Emitter {
    * Emits an event with the specified data to all registered handlers.
    * Handlers are called synchronously in the order they were registered.
    * If no handlers are registered for the event, the emission is silently ignored.
+   * Handlers that return promises are not awaited.
+   *
+   * Error propagation behavior:
+   * - If a handler throws synchronously, the error propagates immediately
+   * - Remaining handlers in the iteration are NOT called after an error
+   * - For error-resilient emission, wrap your emit call in try/catch
+   * - Async handler rejections are not caught (fire-and-forget)
    *
    * @public
-   * @template T
    * @param {string} event - The name of the event to emit.
-   * @param {...T} args - Optional arguments to pass to the event handlers.
+   * @param {...any} args - Optional arguments to pass to the event handlers.
    * @returns {void}
+   * @throws {Error} If a handler throws synchronously, the error propagates to the caller.
    *
    * @example
    * // Emit an event with data

package/src/modules/Renderer.js

@@ -1,21 +1,51 @@
 "use strict";
 
+/**
+ * @module eleva/renderer
+ * @fileoverview High-performance DOM renderer with two-pointer diffing and keyed reconciliation.
+ */
+
 // ============================================================================
-// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// TYPE DEFINITIONS
 // ============================================================================
 
+// -----------------------------------------------------------------------------
+// Data Types
+// -----------------------------------------------------------------------------
+
 /**
+ * Map of key attribute values to their corresponding DOM nodes.
  * @typedef {Map<string, Node>} KeyMap
- *          Map of key attribute values to their corresponding DOM nodes for O(1) lookup
+ * @description Enables O(1) lookup for keyed element reconciliation.
  */
 
+// -----------------------------------------------------------------------------
+// Interface Types
+// -----------------------------------------------------------------------------
+
 /**
+ * Interface describing the public API of a Renderer.
  * @typedef {Object} RendererLike
- * @property {function(HTMLElement, string): void} patchDOM - Patches the DOM with new HTML
+ * @property {function(HTMLElement, string): void} patchDOM
+ *           Patches the DOM with new HTML content.
+ * @description
+ * Plugins may extend renderer behavior by wrapping private methods (e.g., `_patchNode`),
+ * but those hooks are not part of the public API.
  */
 
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
 /**
- * Properties that can diverge from attributes via user interaction.
+ * Properties that can diverge from attributes after user interaction.
+ * These are synchronized during DOM patching to ensure element state
+ * matches the rendered HTML attributes.
+ *
+ * - `value`: Text input, textarea, select element values
+ * - `checked`: Checkbox and radio button states
+ * - `selected`: Option element selection states
+ *
  * @private
  * @type {string[]}
  */
@@ -55,8 +85,13 @@ const SYNC_PROPS = ["value", "checked", "selected"];
 export class Renderer {
   /**
    * Creates a new Renderer instance.
+   * Initializes a reusable temporary container for HTML parsing.
+   *
+   * Performance: The temp container is reused across all patch operations,
+   * minimizing memory allocation overhead (O(1) memory per Renderer instance).
    *
    * @public
+   * @constructor
    *
    * @example
    * const renderer = new Renderer();
@@ -93,6 +128,9 @@ export class Renderer {
    * @example
    * // Empty the container
    * renderer.patchDOM(container, '');
+   *
+   * @see _diff - Low-level diffing algorithm.
+   * @see _patchNode - Individual node patching.
    */
   patchDOM(container, newHtml) {
     this._tempContainer.innerHTML = newHtml;
@@ -104,16 +142,26 @@ export class Renderer {
   /**
    * Performs a diff between two DOM nodes and patches the old node to match the new node.
    * Uses a two-pointer algorithm with key-based reconciliation for optimal performance.
+   * This method modifies oldParent in-place - it is not a pure function.
+   *
+   * Algorithm details:
+   * 1. Early exit if both nodes have no children (O(1) leaf node optimization)
+   * 2. Convert NodeLists to arrays for indexed access
+   * 3. Initialize two-pointer indices (oldStart/oldEnd, newStart/newEnd)
+   * 4. While pointers haven't crossed:
+   *    a. Skip null entries (from previous moves)
+   *    b. If nodes match (same key+tag or same type+name): patch and advance
+   *    c. On mismatch: lazily build key→node map for O(1) lookup
+   *    d. If keyed match found: move existing node (preserves DOM identity)
+   *    e. Otherwise: clone and insert new node
+   * 5. After loop: append remaining new nodes or remove remaining old nodes
    *
-   * Algorithm overview:
-   * 1. Compare children from start using two pointers
-   * 2. For mismatches, build a key map lazily for O(1) lookup
-   * 3. Move or insert nodes as needed
-   * 4. Clean up remaining nodes at the end
+   * Complexity: O(n) for most cases, O(n²) worst case with no keys.
+   * Non-keyed elements are matched by position and tag name.
    *
    * @private
-   * @param {HTMLElement} oldParent - The original DOM element to update.
-   * @param {HTMLElement} newParent - The new DOM element with desired state.
+   * @param {Element} oldParent - The original DOM element to update (modified in-place).
+   * @param {Element} newParent - The new DOM element with desired state.
    * @returns {void}
    */
   _diff(oldParent, newParent) {
@@ -184,7 +232,8 @@ export class Renderer {
 
   /**
    * Patches a single node, updating its content and attributes to match the new node.
-   * Handles text nodes by updating nodeValue, and element nodes by updating attributes
+   * Handles text nodes (nodeType 3 / Node.TEXT_NODE) by updating nodeValue,
+   * and element nodes (nodeType 1 / Node.ELEMENT_NODE) by updating attributes
    * and recursively diffing children.
    *
    * Skips nodes that are managed by Eleva component instances to prevent interference
@@ -212,12 +261,20 @@ export class Renderer {
   /**
    * Removes a node from its parent, with special handling for Eleva-managed elements.
    * Style elements with the `data-e-style` attribute are preserved to maintain
-   * component-scoped styles across re-renders.
+   * component styles across re-renders. Without this protection, component styles
+   * would be removed during DOM diffing and lost until the next full re-render.
+   *
+   * @note Style tags persist for the component's entire lifecycle. If the template
+   * conditionally removes elements that the CSS rules target (e.g., `.foo` elements),
+   * the style rules remain but simply have no matching elements. This is expected
+   * behavior - styles are cleaned up when the component unmounts, not when individual
+   * elements are removed.
    *
    * @private
    * @param {HTMLElement} parent - The parent element containing the node.
    * @param {Node} node - The node to remove.
    * @returns {void}
+   * @see _injectStyles - Where data-e-style elements are created.
    */
   _removeNode(parent, node) {
     // Preserve Eleva-managed style elements
@@ -230,12 +287,16 @@ export class Renderer {
    * Adds new attributes, updates changed values, and removes attributes no longer present.
    * Also syncs DOM properties that can diverge from attributes after user interaction.
    *
-   * Event attributes (prefixed with `@`) are skipped as they are handled separately
-   * by Eleva's event binding system.
+   * Processing order:
+   * 1. Iterate new attributes, skip @ prefixed (event) attributes
+   * 2. Update attribute if value changed
+   * 3. Sync corresponding DOM property if writable (handles boolean conversion)
+   * 4. Iterate old attributes in reverse, remove if not in new element
+   * 5. Sync SYNC_PROPS (value, checked, selected) from new to old element
    *
    * @private
-   * @param {HTMLElement} oldEl - The original element to update.
-   * @param {HTMLElement} newEl - The new element with target attributes.
+   * @param {Element} oldEl - The original element to update.
+   * @param {Element} newEl - The new element with target attributes.
    * @returns {void}
    */
   _updateAttributes(oldEl, newEl) {
@@ -315,10 +376,11 @@ export class Renderer {
   /**
    * Extracts the key attribute from a node if it exists.
    * Only element nodes (nodeType === 1) can have key attributes.
+   * Uses optional chaining for null-safe access.
    *
    * @private
-   * @param {Node|null|undefined} node - The node to extract the key from.
-   * @returns {string|null} The key attribute value, or null if not an element or no key.
+   * @param {Node | null | undefined} node - The node to extract the key from.
+   * @returns {string | null} The key attribute value, or null if not an element or no key.
    */
   _getNodeKey(node) {
     return node?.nodeType === 1 ? node.getAttribute("key") : null;
@@ -329,7 +391,7 @@ export class Renderer {
    * The map is built lazily only when needed (when a mismatch occurs during diffing).
    *
    * @private
-   * @param {Array<ChildNode>} children - The array of child nodes to map.
+   * @param {ChildNode[]} children - The array of child nodes to map.
    * @param {number} start - The start index (inclusive) for mapping.
    * @param {number} end - The end index (inclusive) for mapping.
    * @returns {KeyMap} A Map of key strings to their corresponding DOM nodes.

package/src/modules/Signal.js

@@ -1,26 +1,47 @@
 "use strict";
 
+/**
+ * @module eleva/signal
+ * @fileoverview Reactive Signal primitive for fine-grained state management and change notification.
+ */
+
 // ============================================================================
-// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// TYPE DEFINITIONS
 // ============================================================================
 
+// -----------------------------------------------------------------------------
+// Callback Types
+// -----------------------------------------------------------------------------
+
 /**
- * @template T
+ * Callback function invoked when a signal's value changes.
+ * @template T The type of value held by the signal.
  * @callback SignalWatcher
- * @param {T} value - The new value of the signal
+ * @param {T} value
+ *        The new value of the signal.
  * @returns {void}
  */
 
 /**
+ * Function to unsubscribe a watcher from a signal.
  * @callback SignalUnsubscribe
- * @returns {boolean} True if the watcher was successfully removed
+ * @returns {boolean}
+ *          True if the watcher was successfully removed, false if already removed.
+ *          Safe to call multiple times (idempotent).
  */
 
+// -----------------------------------------------------------------------------
+// Interface Types
+// -----------------------------------------------------------------------------
+
 /**
- * @template T
+ * Interface describing the public API of a Signal.
+ * @template T The type of value held by the signal.
  * @typedef {Object} SignalLike
- * @property {T} value - The current value
- * @property {function(SignalWatcher<T>): SignalUnsubscribe} watch - Subscribe to changes
+ * @property {T} value
+ *           The current value of the signal.
+ * @property {function(SignalWatcher<T>): SignalUnsubscribe} watch
+ *           Subscribe to value changes.
  */
 
 /**
@@ -32,7 +53,7 @@
  * Render batching is handled at the component level, not the signal level.
  * The class is generic, allowing type-safe handling of any value type T.
  *
- * @template T The type of value held by this signal
+ * @template T The type of value held by the signal.
  *
  * @example
  * // Basic usage
@@ -50,7 +71,6 @@
  *
  * @example
  * // With objects
- * /** @type {Signal<{x: number, y: number}>} *\/
  * const position = new Signal({ x: 0, y: 0 });
  * position.value = { x: 10, y: 20 }; // Triggers watchers
  *
@@ -61,6 +81,7 @@ export class Signal {
    * Creates a new Signal instance with the specified initial value.
    *
    * @public
+   * @constructor
    * @param {T} value - The initial value of the signal.
    *
    * @example
@@ -70,12 +91,9 @@ export class Signal {
    * const active = new Signal(true);    // Signal<boolean>
    *
    * @example
-   * // Complex types (use JSDoc for type inference)
-   * /** @type {Signal<string[]>} *\/
-   * const items = new Signal([]);
-   *
-   * /** @type {Signal<{id: number, name: string} | null>} *\/
-   * const user = new Signal(null);
+   * // Complex types
+   * const items = new Signal([]);          // Signal holding an array
+   * const user = new Signal(null);         // Signal holding nullable object
    */
   constructor(value) {
     /**
@@ -106,6 +124,10 @@ export class Signal {
    * Sets a new value for the signal and synchronously notifies all registered watchers if the value has changed.
    * Synchronous notification preserves stack traces and ensures immediate value consistency.
    *
+   * Uses strict equality (===) for comparison. For objects/arrays, watchers are only notified
+   * if the reference changes, not if properties are mutated. To trigger updates with objects,
+   * assign a new reference: `signal.value = { ...signal.value, updated: true }`.
+   *
    * @public
    * @param {T} newVal - The new value to set.
    * @returns {void}
@@ -124,6 +146,8 @@ export class Signal {
    * @public
    * @param {SignalWatcher<T>} fn - The callback function to invoke on value change.
    * @returns {SignalUnsubscribe} A function to unsubscribe the watcher.
+   *          Returns true if watcher was removed, false if it wasn't registered.
+   *          Safe to call multiple times (idempotent after first call).
    *
    * @example
    * // Basic watching
@@ -132,6 +156,7 @@ export class Signal {
    * @example
    * // Stop watching
    * unsubscribe(); // Returns true if watcher was removed
+   * unsubscribe(); // Returns false (already removed, safe to call again)
    *
    * @example
    * // Multiple watchers
@@ -149,6 +174,9 @@ export class Signal {
    * This preserves stack traces for debugging and ensures immediate
    * value consistency. Render batching is handled at the component level.
    *
+   * @note If a watcher throws, subsequent watchers are NOT called.
+   * The error propagates to the caller (the setter).
+   *
    * @private
    * @returns {void}
    */

package/src/modules/TemplateEngine.js

@@ -1,22 +1,44 @@
 "use strict";
 
+/**
+ * @module eleva/template-engine
+ * @fileoverview Expression evaluator for directive attributes and property bindings.
+ */
+
 // ============================================================================
-// TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+// TYPE DEFINITIONS
 // ============================================================================
 
+// -----------------------------------------------------------------------------
+// Data Types
+// -----------------------------------------------------------------------------
+
 /**
+ * Data context object for expression evaluation.
  * @typedef {Record<string, unknown>} ContextData
- *           Data context for expression evaluation
+ * @description Contains variables and functions available during template evaluation.
  */
 
 /**
+ * JavaScript expression string to be evaluated.
  * @typedef {string} Expression
- *           A JavaScript expression to be evaluated in the data context
+ * @description A JavaScript expression evaluated against a ContextData object.
  */
 
 /**
+ * Result of evaluating an expression.
  * @typedef {unknown} EvaluationResult
- *           The result of evaluating an expression (string, number, boolean, object, function, etc.)
+ * @description Can be string, number, boolean, object, function, or any JavaScript value.
+ */
+
+// -----------------------------------------------------------------------------
+// Function Types
+// -----------------------------------------------------------------------------
+
+/**
+ * Compiled expression function cached for performance.
+ * @typedef {(data: ContextData) => EvaluationResult} CompiledExpressionFunction
+ * @description Pre-compiled function that evaluates an expression against context data.
  */
 
 /**
@@ -51,26 +73,45 @@ export class TemplateEngine {
   /**
    * Cache for compiled expression functions.
    * Stores compiled Function objects keyed by expression string for O(1) lookup.
+   * The cache persists for the application lifetime and is never cleared.
+   * This improves performance for repeated evaluations of the same expression.
+   *
+   * Memory consideration: For applications with highly dynamic expressions
+   * (e.g., user-generated), memory usage grows unbounded. This is typically
+   * not an issue for static templates where expressions are finite.
    *
    * @static
    * @private
-   * @type {Map<string, Function>}
+   * @type {Map<string, CompiledExpressionFunction>}
    */
   static _functionCache = new Map();
 
   /**
    * Evaluates an expression in the context of the provided data object.
    * Used for resolving `@event` handlers and `:prop` bindings.
+   * Non-string expressions are returned as-is.
+   *
+   * @security CRITICAL SECURITY WARNING
+   * This method is NOT sandboxed. It uses `new Function()` and `with` statement,
+   * allowing full access to the global scope. Potential attack vectors include:
+   * - Code injection via malicious expressions
+   * - XSS attacks if user input is used as expressions
+   * - Access to sensitive globals (window, document, fetch, etc.)
+   *
+   * ONLY use with developer-defined template strings.
+   * NEVER use with user-provided input or untrusted data.
    *
-   * Note: This does not provide a true sandbox and evaluated expressions may access global scope.
-   * The use of the `with` statement is necessary for expression evaluation but has security implications.
-   * Only use with trusted templates. User input should never be directly interpolated.
+   * Mitigation strategies:
+   * - Always sanitize any user-generated content before rendering in templates
+   * - Use Content Security Policy (CSP) headers to restrict script execution
+   * - Keep expressions simple (property access, method calls) - avoid complex logic
    *
    * @public
    * @static
-   * @param {Expression|unknown} expression - The expression to evaluate.
+   * @param {Expression | unknown} expression - The expression to evaluate.
    * @param {ContextData} data - The data context for evaluation.
    * @returns {EvaluationResult} The result of the evaluation, or empty string if evaluation fails.
+   * @note Evaluation failures return an empty string without throwing.
    *
    * @example
    * // Property access