eleva 1.0.1 → 1.1.0

package/types/core/Eleva.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Eleva.d.ts","sourceRoot":"","sources":["../../src/core/Eleva.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Eleva.d.ts","sourceRoot":"","sources":["../../src/core/Eleva.js"],"names":[],"mappings":"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"}

package/types/index.d.cts

@@ -0,0 +1,3 @@
+export default Eleva;
+import { Eleva } from "./core/Eleva.js";
+//# sourceMappingURL=index.d.cts.map

package/types/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.cjs"],"names":[],"mappings":";sBAOsB,iBAAiB"}

package/types/index.d.ts

@@ -1,3 +1,8 @@
+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;
 import { Eleva } from "./core/Eleva.js";
 //# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":";sBAEsB,iBAAiB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":";;;;;;sBAOsB,iBAAiB"}

package/types/modules/Emitter.d.ts

@@ -1,22 +1,45 @@
 /**
- * @template T
+ * @module eleva/emitter
+ * @fileoverview Event emitter for publish-subscribe communication between components.
+ */
+/**
+ * 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}
  */
 /**
- * @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 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.
  */
 /**
  * @class 📡 Emitter
@@ -55,6 +78,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
@@ -66,7 +90,7 @@ export class Emitter implements EmitterLike {
     /**
      * Map of event names to their registered handler functions
      * @private
-     * @type {Map<string, Set<EventHandler<unknown>>>}
+     * @type {Map<string, Set<EventHandler>>}
      */
     private _events;
     /**
@@ -75,9 +99,10 @@ export class Emitter implements EmitterLike {
      * 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
@@ -85,8 +110,8 @@ export class Emitter implements EmitterLike {
      * 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}`);
      * });
      *
@@ -94,16 +119,18 @@ export class Emitter implements EmitterLike {
      * // Cleanup
      * unsubscribe(); // Stops listening for the event
      */
-    public on<T>(event: string, handler: EventHandler<T>): EventUnsubscribe;
+    public on(event: string, handler: EventHandler): EventUnsubscribe;
     /**
      * 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
@@ -116,17 +143,24 @@ export class Emitter implements EmitterLike {
      * // Remove all handlers for an event
      * emitter.off('user:login');
      */
-    public off<T>(event: string, handler?: EventHandler<T>): void;
+    public off(event: string, handler?: EventHandler): void;
     /**
      * 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
@@ -140,26 +174,35 @@ export class Emitter implements EmitterLike {
      * // Emit without data
      * emitter.emit('app:ready');
      */
-    public emit<T>(event: string, ...args: T[]): void;
+    public emit(event: string, ...args: any[]): void;
 }
-export type EventHandler<T> = (...args: T[]) => void | Promise<void>;
+/**
+ * Callback function invoked when an event is emitted.
+ */
+export type EventHandler = (...args: any[]) => void | Promise<void>;
+/**
+ * Function to unsubscribe an event handler.
+ */
 export type EventUnsubscribe = () => void;
 /**
- * Event names follow the format 'namespace:action' (e.g., 'user:login', 'cart:update')
+ * Event name string identifier.
+ */
+export type EventName = string;
+/**
+ * Interface describing the public API of an Emitter.
  */
-export type EventName = `${string}:${string}`;
 export type EmitterLike = {
     /**
-     * - Subscribe to an event
+     *           Subscribe to an event.
      */
-    on: (arg0: string, arg1: EventHandler<unknown>) => EventUnsubscribe;
+    on: (event: string, handler: EventHandler) => EventUnsubscribe;
     /**
-     * - Unsubscribe from an event
+     *           Unsubscribe from an event.
      */
-    off: (arg0: string, arg1: EventHandler<unknown> | undefined) => void;
+    off: (event: string, handler?: EventHandler) => void;
     /**
-     * - Emit an event
+     *           Emit an event with arguments.
      */
-    emit: (arg0: string, ...args: unknown[]) => void;
+    emit: (event: string, ...args: unknown[]) => 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":"AAMA;;;;;GAKG;AAEH;;;GAGG;AAEH;;;GAGG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,gCAFgB,WAAW;IAYvB;;;;OAIG;IACH,gBAAwB;IAG1B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,UAnBa,CAAC,SACH,MAAM,WACN,YAAY,CAAC,CAAC,CAAC,GACb,gBAAgB,CAqB5B;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAfa,CAAC,SACH,MAAM,YACN,YAAY,CAAC,CAAC,CAAC,GACb,IAAI,CAqBhB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,YAjBa,CAAC,SACH,MAAM,WACH,CAAC,EAAA,GACF,IAAI,CAiBhB;CACF;yBAhLY,CAAC,cAEA,CAAC,EAAA,KACF,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC;qCAKlB,IAAI;;;;wBAIJ,GAAG,MAAM,IAAI,MAAM,EAAE;;;;;QAMpB,CAAS,IAAM,EAAN,MAAM,EAAE,IAAqB,EAArB,YAAY,CAAC,OAAO,CAAC,KAAG,gBAAgB;;;;SACzD,CAAS,IAAM,EAAN,MAAM,EAAE,IAAsB,EAAtB,YAAY,CAAC,OAAO,CAAC,YAAC,KAAG,IAAI;;;;UAC9C,CAAS,IAAM,EAAN,MAAM,KAAE,IAAU,EAAP,OAAO,EAAA,KAAG,IAAI"}
+{"version":3,"file":"Emitter.d.ts","sourceRoot":"","sources":["../../src/modules/Emitter.js"],"names":[],"mappings":"AAEA;;;GAGG;AAUH;;;;;;GAMG;AAEH;;;;GAIG;AAMH;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,gCAFgB,WAAW;IAavB;;;;OAIG;IACH,gBAAwB;IAG1B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,iBApBW,MAAM,WACN,YAAY,GAGV,gBAAgB,CAqB5B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,kBAdW,MAAM,YACN,YAAY,GACV,IAAI,CAqBhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,mBAjBW,MAAM,WACH,GAAG,EAAA,GACJ,IAAI,CAkBhB;CACF;;;;qCArNa,GAAG,EAAA,KAEJ,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;;;;qCAMpB,IAAI;;;;wBASJ,MAAM;;;;;;;;QAuBL,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,gBAAgB;;;;SAE1D,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,IAAI;;;;UAE/C,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI"}

package/types/modules/Renderer.d.ts

@@ -59,27 +59,41 @@ export class Renderer implements RendererLike {
      * @example
      * // Empty the container
      * renderer.patchDOM(container, '');
+     *
+     * @see _diff - Low-level diffing algorithm.
+     * @see _patchNode - Individual node patching.
      */
     public patchDOM(container: HTMLElement, newHtml: string): void;
     /**
      * 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}
      */
     private _diff;
     /**
      * 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
@@ -94,12 +108,20 @@ export class Renderer implements RendererLike {
     /**
      * 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.
      */
     private _removeNode;
     /**
@@ -107,12 +129,16 @@ export class Renderer implements RendererLike {
      * 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}
      */
     private _updateAttributes;
@@ -135,10 +161,11 @@ export class Renderer implements RendererLike {
     /**
      * 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.
      */
     private _getNodeKey;
     /**
@@ -146,7 +173,7 @@ export class Renderer implements RendererLike {
      * 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.
@@ -154,12 +181,15 @@ export class Renderer implements RendererLike {
     private _createKeyMap;
 }
 /**
- * Map of key attribute values to their corresponding DOM nodes for O(1) lookup
+ * Map of key attribute values to their corresponding DOM nodes.
  */
 export type KeyMap = Map<string, Node>;
+/**
+ * Interface describing the public API of a Renderer.
+ */
 export type RendererLike = {
     /**
-     * - Patches the DOM with new HTML
+     *           Patches the DOM with new HTML content.
      */
     patchDOM: (arg0: HTMLElement, arg1: string) => void;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../src/modules/Renderer.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,iCAFgB,YAAY;IAYxB;;;;;OAKG;IACH,uBAAmD;IAGrD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,2BAhBW,WAAW,WACX,MAAM,GACJ,IAAI,CAmBhB;IAED;;;;;;;;;;;;;;OAcG;IACH,cAgEC;IAED;;;;;;;;;;;;OAYG;IACH,mBAYC;IAED;;;;;;;;;OASG;IACH,oBAIC;IAED;;;;;;;;;;;;OAYG;IACH,0BAqCC;IAED;;;;;;;;;;;;;;OAcG;IACH,oBAkBC;IAED;;;;;;;OAOG;IACH,oBAEC;IAED;;;;;;;;;OASG;IACH,sBAOC;CACF;;;;qBAjVY,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;;;;;cAMhB,CAAS,IAAW,EAAX,WAAW,EAAE,IAAM,EAAN,MAAM,KAAG,IAAI"}
+{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../src/modules/Renderer.js"],"names":[],"mappings":"AAqDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,iCAFgB,YAAY;IAiBxB;;;;;OAKG;IACH,uBAAmD;IAGrD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,2BAnBW,WAAW,WACX,MAAM,GACJ,IAAI,CAsBhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,cAgEC;IAED;;;;;;;;;;;;;OAaG;IACH,mBAYC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAIC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,0BAqCC;IAED;;;;;;;;;;;;;;OAcG;IACH,oBAkBC;IAED;;;;;;;;OAQG;IACH,oBAEC;IAED;;;;;;;;;OASG;IACH,sBAOC;CACF;;;;qBArYY,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;;;;;;;;cAWhB,CAAS,IAAW,EAAX,WAAW,EAAE,IAAM,EAAN,MAAM,KAAG,IAAI"}

package/types/modules/Signal.d.ts

@@ -1,18 +1,30 @@
 /**
- * @template T
+ * @module eleva/signal
+ * @fileoverview Reactive Signal primitive for fine-grained state management and change notification.
+ */
+/**
+ * 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).
  */
 /**
- * @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.
  */
 /**
  * @class ⚡ Signal
@@ -23,7 +35,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
@@ -41,7 +53,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
  *
@@ -52,6 +63,7 @@ export class Signal<T> implements SignalLike<T> {
      * Creates a new Signal instance with the specified initial value.
      *
      * @public
+     * @constructor
      * @param {T} value - The initial value of the signal.
      *
      * @example
@@ -61,12 +73,9 @@ export class Signal<T> implements SignalLike<T> {
      * 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: T);
     /**
@@ -85,6 +94,10 @@ export class Signal<T> implements SignalLike<T> {
      * 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}
@@ -104,6 +117,8 @@ export class Signal<T> implements SignalLike<T> {
      * @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
@@ -112,6 +127,7 @@ export class Signal<T> implements SignalLike<T> {
      * @example
      * // Stop watching
      * unsubscribe(); // Returns true if watcher was removed
+     * unsubscribe(); // Returns false (already removed, safe to call again)
      *
      * @example
      * // Multiple watchers
@@ -125,20 +141,32 @@ export class Signal<T> implements SignalLike<T> {
      * 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}
      */
     private _notify;
 }
+/**
+ * Callback function invoked when a signal's value changes.
+ */
 export type SignalWatcher<T> = (value: T) => void;
+/**
+ * Function to unsubscribe a watcher from a signal.
+ */
 export type SignalUnsubscribe = () => boolean;
+/**
+ * Interface describing the public API of a Signal.
+ */
 export type SignalLike<T> = {
     /**
-     * - The current value
+     *           The current value of the signal.
      */
     value: T;
     /**
-     * - Subscribe to changes
+     *           Subscribe to value changes.
      */
     watch: (arg0: SignalWatcher<T>) => SignalUnsubscribe;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"Signal.d.ts","sourceRoot":"","sources":["../../src/modules/Signal.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH;;;GAGG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,oBAxBa,CAAC,aAsBE,UAAU,CAAC,CAAC;IAG1B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,mBAhBW,CAAC,EA6BX;IAZC;;;;OAIG;IACH,eAAmB;IACnB;;;;OAIG;IACH,kBAA0B;IAa5B;;;;;;;OAOG;IACH,yBAHW,CAAC,EAQX;IAvBD;;;;;OAKG;IACH,oBAFa,CAAC,CAIb;IAiBD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,iBAjBW,aAAa,CAAC,CAAC,CAAC,GACd,iBAAiB,CAmB7B;IAED;;;;;;;OAOG;IACH,gBAEC;CACF;0BAtJY,CAAC,YAEH,CAAC,KACC,IAAI;sCAKJ,OAAO;uBAIP,CAAC;;;;WAEA,CAAC;;;;WACD,CAAS,IAAgB,EAAhB,aAAa,CAAC,CAAC,CAAC,KAAG,iBAAiB"}
+{"version":3,"file":"Signal.d.ts","sourceRoot":"","sources":["../../src/modules/Signal.js"],"names":[],"mappings":"AAEA;;;GAGG;AAUH;;;;;;;GAOG;AAEH;;;;;;GAMG;AAMH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,oBAvBa,CAAC,aAqBE,UAAU,CAAC,CAAC;IAG1B;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAbW,CAAC,EA0BX;IAZC;;;;OAIG;IACH,eAAmB;IACnB;;;;OAIG;IACH,kBAA0B;IAa5B;;;;;;;;;;;OAWG;IACH,yBAHW,CAAC,EAQX;IA3BD;;;;;OAKG;IACH,oBAFa,CAAC,CAIb;IAqBD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,iBApBW,aAAa,CAAC,CAAC,CAAC,GACd,iBAAiB,CAsB7B;IAED;;;;;;;;;;OAUG;IACH,gBAEC;CACF;;;;0BAxKY,CAAC,YAEH,CAAC,KAEC,IAAI;;;;sCAMJ,OAAO;;;;uBAWP,CAAC;;;;WAEA,CAAC;;;;WAED,CAAS,IAAgB,EAAhB,aAAa,CAAC,CAAC,CAAC,KAAG,iBAAiB"}

package/types/modules/TemplateEngine.d.ts

@@ -1,14 +1,26 @@
 /**
+ * @module eleva/template-engine
+ * @fileoverview Expression evaluator for directive attributes and property bindings.
+ */
+/**
+ * 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.
+ */
+/**
+ * Compiled expression function cached for performance.
+ * @typedef {(data: ContextData) => EvaluationResult} CompiledExpressionFunction
+ * @description Pre-compiled function that evaluates an expression against context data.
  */
 /**
  * @class 🔒 TemplateEngine
@@ -42,25 +54,44 @@ 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>}
      */
     private static _functionCache;
     /**
      * 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.
      *
-     * 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.
+     * @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.
+     *
+     * 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
@@ -95,15 +126,19 @@ export class TemplateEngine {
     public static evaluate(expression: Expression | unknown, data: ContextData): EvaluationResult;
 }
 /**
- * Data context for expression evaluation
+ * Data context object for expression evaluation.
  */
 export type ContextData = Record<string, unknown>;
 /**
- * A JavaScript expression to be evaluated in the data context
+ * JavaScript expression string to be evaluated.
  */
 export type Expression = string;
 /**
- * The result of evaluating an expression (string, number, boolean, object, function, etc.)
+ * Result of evaluating an expression.
  */
 export type EvaluationResult = unknown;
+/**
+ * Compiled expression function cached for performance.
+ */
+export type CompiledExpressionFunction = (data: ContextData) => EvaluationResult;
 //# 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":"AAMA;;;GAGG;AAEH;;;GAGG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACE;;;;;;;OAOG;IACH,8BAAkC;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,mCAlCW,UAAU,GAAC,OAAO,QAClB,WAAW,GACT,gBAAgB,CAkD5B;CACF;;;;0BApHY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;yBAKvB,MAAM;;;;+BAKN,OAAO"}
+{"version":3,"file":"TemplateEngine.d.ts","sourceRoot":"","sources":["../../src/modules/TemplateEngine.js"],"names":[],"mappings":"AAEA;;;GAGG;AAUH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAMH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACE;;;;;;;;;;;;;OAaG;IACH,8BAAkC;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACH,mCAnCW,UAAU,GAAG,OAAO,QACpB,WAAW,GACT,gBAAgB,CAmD5B;CACF;;;;0BAnJY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;yBAMvB,MAAM;;;;+BAMN,OAAO;;;;yCAUP,CAAC,IAAI,EAAE,WAAW,KAAK,gBAAgB"}