native-document 1.0.91 → 1.0.93

package/dist/native-document.dev.js

@@ -1,10 +1,10 @@
 var NativeDocument = (function (exports) {
     'use strict';
 
-    let DebugManager$1 = {};
+    let DebugManager = {};
 
     {
-        DebugManager$1 = {
+        DebugManager = {
             enabled: false,
 
             enable() {
@@ -35,7 +35,7 @@ var NativeDocument = (function (exports) {
         };
 
     }
-    var DebugManager = DebugManager$1;
+    var DebugManager$1 = DebugManager;
 
     const MemoryManager = (function() {
 
@@ -84,7 +84,7 @@ var NativeDocument = (function (exports) {
                     }
                 }
                 if (cleanedCount > 0) {
-                    DebugManager.log('Memory Auto Clean', `🧹 Cleaned ${cleanedCount} orphaned observables`);
+                    DebugManager$1.log('Memory Auto Clean', `🧹 Cleaned ${cleanedCount} orphaned observables`);
                 }
             }
         };
@@ -113,6 +113,16 @@ var NativeDocument = (function (exports) {
 
     ObservableChecker.prototype.__$isObservableChecker = true;
 
+    /**
+     * Subscribes to changes in the checked/transformed value.
+     *
+     * @param {Function} callback - Function called with the transformed value when observable changes
+     * @returns {Function} Unsubscribe function
+     * @example
+     * const count = Observable(5);
+     * const doubled = count.check(n => n * 2);
+     * doubled.subscribe(value => console.log(value)); // Logs: 10
+     */
     ObservableChecker.prototype.subscribe = function(callback) {
         const unSubscribe = this.observable.subscribe((value) => {
             callback && callback(this.checker(value));
@@ -121,30 +131,70 @@ var NativeDocument = (function (exports) {
         return unSubscribe;
     };
 
+    /**
+     * Creates a new ObservableChecker by applying another transformation.
+     * Allows chaining transformations.
+     *
+     * @param {(value: *) => *} callback - Transformation function to apply to the current checked value
+     * @returns {ObservableChecker} New ObservableChecker with chained transformation
+     * @example
+     * const count = Observable(5);
+     * const result = count.check(n => n * 2).check(n => n + 1);
+     * result.val(); // 11
+     */
     ObservableChecker.prototype.check = function(callback) {
         return this.observable.check(() => callback(this.val()));
     };
 
+    /**
+     * Gets the current transformed/checked value.
+     *
+     * @returns {*} The result of applying the checker function to the observable's current value
+     * @example
+     * const count = Observable(5);
+     * const doubled = count.check(n => n * 2);
+     * doubled.val(); // 10
+     */
     ObservableChecker.prototype.val = function() {
         return this.checker && this.checker(this.observable.val());
     };
 
+    /**
+     * Sets the value of the underlying observable (not the transformed value).
+     *
+     * @param {*} value - New value for the underlying observable
+     * @example
+     * const count = Observable(5);
+     * const doubled = count.check(n => n * 2);
+     * doubled.set(10); // Sets count to 10, doubled.val() returns 20
+     */
     ObservableChecker.prototype.set = function(value) {
         return this.observable.set(value);
     };
 
+    /**
+     * Manually triggers the underlying observable to notify subscribers.
+     *
+     * @example
+     * const count = Observable(5);
+     * const doubled = count.check(n => n * 2);
+     * doubled.trigger(); // Notifies all subscribers
+     */
     ObservableChecker.prototype.trigger = function() {
         return this.observable.trigger();
     };
 
+    /**
+     * Cleans up the underlying observable and all its subscriptions.
+     */
     ObservableChecker.prototype.cleanup = function() {
         return this.observable.cleanup();
     };
 
-    let PluginsManager$1 = null;
+    let PluginsManager = null;
 
     {
-        PluginsManager$1 = (function() {
+        PluginsManager = (function() {
 
             const $plugins = new Map();
             const $pluginByEvents = new Map();
@@ -210,7 +260,7 @@ var NativeDocument = (function (exports) {
                             try{
                                 callback.call(plugin, ...data);
                             } catch (error) {
-                                DebugManager.error('Plugin Manager', `Error in plugin ${plugin.$name} for event ${eventName}`, error);
+                                DebugManager$1.error('Plugin Manager', `Error in plugin ${plugin.$name} for event ${eventName}`, error);
                             }
                         }
                     }
@@ -219,8 +269,15 @@ var NativeDocument = (function (exports) {
         }());
     }
 
-    var PluginsManager = PluginsManager$1;
+    var PluginsManager$1 = PluginsManager;
 
+    /**
+     * Creates an ObservableWhen that tracks whether an observable equals a specific value.
+     *
+     * @param {ObservableItem} observer - The observable to watch
+     * @param {*} value - The value to compare against
+     * @class ObservableWhen
+     */
     const ObservableWhen = function(observer, value) {
         this.$target = value;
         this.$observer = observer;
@@ -228,21 +285,44 @@ var NativeDocument = (function (exports) {
 
     ObservableWhen.prototype.__$isObservableWhen = true;
 
+    /**
+     * Subscribes to changes in the match status (true when observable equals target value).
+     *
+     * @param {Function} callback - Function called with boolean indicating if values match
+     * @returns {Function} Unsubscribe function
+     * @example
+     * const status = Observable('idle');
+     * const isLoading = status.when('loading');
+     * isLoading.subscribe(active => console.log('Loading:', active));
+     */
     ObservableWhen.prototype.subscribe = function(callback) {
         return this.$observer.on(this.$target, callback);
     };
 
+    /**
+     * Returns true if the observable's current value equals the target value.
+     *
+     * @returns {boolean} True if observable value matches target value
+     */
     ObservableWhen.prototype.val = function() {
         return this.$observer.$currentValue === this.$target;
     };
 
-    ObservableWhen.prototype.isMath = function() {
-        return this.$observer.$currentValue === this.$target;
-    };
+    /**
+     * Returns true if the observable's current value equals the target value.
+     * Alias for val().
+     *
+     * @returns {boolean} True if observable value matches target value
+     */
+    ObservableWhen.prototype.isMatch = ObservableWhen.prototype.val;
 
-    ObservableWhen.prototype.isActive = function() {
-        return this.$observer.$currentValue === this.$target;
-    };
+    /**
+     * Returns true if the observable's current value equals the target value.
+     * Alias for val().
+     *
+     * @returns {boolean} True if observable value matches target value
+     */
+    ObservableWhen.prototype.isActive = ObservableWhen.prototype.val;
 
     const nextTick = function(fn) {
         let pending = false;
@@ -326,7 +406,9 @@ var NativeDocument = (function (exports) {
 
         this.$previousValue = null;
         this.$currentValue = value;
-        this.$isCleanedUp = false;
+        {
+            this.$isCleanedUp = false;
+        }
 
         this.$firstListener = null;
         this.$listeners = null;
@@ -341,7 +423,7 @@ var NativeDocument = (function (exports) {
             }
         }
         {
-            PluginsManager.emit('CreateObservable', this);
+            PluginsManager$1.emit('CreateObservable', this);
         }
     }
 
@@ -356,16 +438,26 @@ var NativeDocument = (function (exports) {
     });
 
     ObservableItem.prototype.__$isObservable = true;
-    const DEFAULT_OPERATIONS = {};
     const noneTrigger = function() {};
 
+    /**
+     * Intercepts and transforms values before they are set on the observable.
+     * The interceptor can modify the value or return undefined to use the original value.
+     *
+     * @param {(value) => any} callback - Interceptor function that receives (newValue, currentValue) and returns the transformed value or undefined
+     * @returns {ObservableItem} The observable instance for chaining
+     * @example
+     * const count = Observable(0);
+     * count.intercept((newVal, oldVal) => Math.max(0, newVal)); // Prevent negative values
+     */
     ObservableItem.prototype.intercept = function(callback) {
         this.$interceptor = callback;
+        this.set = this.$setWithInterceptor;
         return this;
     };
 
     ObservableItem.prototype.triggerFirstListener = function(operations) {
-        this.$firstListener(this.$currentValue, this.$previousValue, operations || {});
+        this.$firstListener(this.$currentValue, this.$previousValue, operations);
     };
 
     ObservableItem.prototype.triggerListeners = function(operations) {
@@ -373,33 +465,12 @@ var NativeDocument = (function (exports) {
         const $previousValue = this.$previousValue;
         const $currentValue = this.$currentValue;
 
-        operations = operations || DEFAULT_OPERATIONS;
         for(let i = 0, length = $listeners.length; i < length; i++) {
             $listeners[i]($currentValue, $previousValue, operations);
         }
     };
 
-    const handleWatcherCallback = function(callbacks, value) {
-        if(typeof callbacks === "function") {
-            callbacks(value);
-            return;
-        }
-        if (callbacks.set) {
-            callbacks.set(value);
-            return;
-        }
-        for(let i = 0, length = callbacks.length; i < length; i++) {
-            const callback = callbacks[i];
-            callback.set ? callback.set(value) : callback(value);
-
-        }
-    };
-
-    ObservableItem.prototype.triggerWatchers = function() {
-        if(!this.$watchers) {
-            return;
-        }
-
+    ObservableItem.prototype.triggerWatchers = function(operations) {
         const $watchers = this.$watchers;
         const $previousValue = this.$previousValue;
         const $currentValue = this.$currentValue;
@@ -407,20 +478,20 @@ var NativeDocument = (function (exports) {
         const $currentValueCallbacks = $watchers.get($currentValue);
         const $previousValueCallbacks = $watchers.get($previousValue);
         if($currentValueCallbacks) {
-            handleWatcherCallback($currentValueCallbacks, true);
+            $currentValueCallbacks(true, $previousValue, operations);
         }
         if($previousValueCallbacks) {
-            handleWatcherCallback($previousValueCallbacks, false);
+            $previousValueCallbacks(false, $currentValue, operations);
         }
     };
 
     ObservableItem.prototype.triggerAll = function(operations) {
-        this.triggerWatchers();
+        this.triggerWatchers(operations);
         this.triggerListeners(operations);
     };
 
     ObservableItem.prototype.triggerWatchersAndFirstListener = function(operations) {
-        this.triggerWatchers();
+        this.triggerWatchers(operations);
         this.triggerFirstListener(operations);
     };
 
@@ -448,36 +519,47 @@ var NativeDocument = (function (exports) {
     };
     ObservableItem.prototype.trigger = noneTrigger;
 
-    /**
-     * @param {*} data
-     */
-    ObservableItem.prototype.set = function(data) {
-        let newValue = (typeof data === 'function') ? data(this.$currentValue) : data;
-        newValue = Validator.isObservable(newValue) ? newValue.val() : newValue;
-
-        if (this.$interceptor) {
-            const result = this.$interceptor(newValue, this.$currentValue);
-
-            if (result !== undefined) {
-                newValue = result;
-            }
-        }
-
+    ObservableItem.prototype.$updateWithNewValue = function(newValue) {
+        newValue = newValue?.__$isObservable ? newValue.val() : newValue;
         if(this.$currentValue === newValue) {
             return;
         }
         this.$previousValue = this.$currentValue;
         this.$currentValue = newValue;
         {
-            PluginsManager.emit('ObservableBeforeChange', this);
+            PluginsManager$1.emit('ObservableBeforeChange', this);
         }
         this.trigger();
         this.$previousValue = null;
         {
-            PluginsManager.emit('ObservableAfterChange', this);
+            PluginsManager$1.emit('ObservableAfterChange', this);
         }
     };
 
+    /**
+     * @param {*} data
+     */
+    ObservableItem.prototype.$setWithInterceptor = function(data) {
+        let newValue = (typeof data === 'function') ? data(this.$currentValue) : data;
+        const result = this.$interceptor(newValue, this.$currentValue);
+
+        if (result !== undefined) {
+            newValue = result;
+        }
+
+        this.$updateWithNewValue(newValue);
+    };
+
+    /**
+     * @param {*} data
+     */
+    ObservableItem.prototype.$basicSet = function(data) {
+        let newValue = (typeof data === 'function') ? data(this.$currentValue) : data;
+        this.$updateWithNewValue(newValue);
+    };
+
+    ObservableItem.prototype.set = ObservableItem.prototype.$basicSet;
+
     ObservableItem.prototype.val = function() {
         return this.$currentValue;
     };
@@ -499,6 +581,16 @@ var NativeDocument = (function (exports) {
         this.trigger = noneTrigger;
     };
 
+    /**
+     * Registers a cleanup callback that will be executed when the observable is cleaned up.
+     * Useful for disposing resources, removing event listeners, or other cleanup tasks.
+     *
+     * @param {Function} callback - Cleanup function to execute on observable disposal
+     * @example
+     * const obs = Observable(0);
+     * obs.onCleanup(() => console.log('Cleaned up!'));
+     * obs.cleanup(); // Logs: "Cleaned up!"
+     */
     ObservableItem.prototype.onCleanup = function(callback) {
         this.$cleanupListeners = this.$cleanupListeners ?? [];
         this.$cleanupListeners.push(callback);
@@ -513,79 +605,129 @@ var NativeDocument = (function (exports) {
         }
         MemoryManager.unregister(this.$memoryId);
         this.disconnectAll();
-        this.$isCleanedUp = true;
+        {
+            this.$isCleanedUp = true;
+        }
         delete this.$value;
     };
 
     /**
      *
      * @param {Function} callback
-     * @param {any} target
      * @returns {(function(): void)}
      */
-    ObservableItem.prototype.subscribe = function(callback, target = null) {
-        this.$listeners = this.$listeners ?? [];
-        if (this.$isCleanedUp) {
-            DebugManager.warn('Observable subscription', '⚠️ Attempted to subscribe to a cleaned up observable.');
-            return () => {};
-        }
-        if (typeof callback !== 'function') {
-            throw new NativeDocumentError('Callback must be a function');
+    ObservableItem.prototype.subscribe = function(callback) {
+        {
+            if (this.$isCleanedUp) {
+                DebugManager$1.warn('Observable subscription', '⚠️ Attempted to subscribe to a cleaned up observable.');
+                return;
+            }
+            if (typeof callback !== 'function') {
+                throw new NativeDocumentError('Callback must be a function');
+            }
         }
+        this.$listeners = this.$listeners ?? [];
 
         this.$listeners.push(callback);
         this.assocTrigger();
         {
-            PluginsManager.emit('ObservableSubscribe', this, target);
+            PluginsManager$1.emit('ObservableSubscribe', this);
         }
-        return () => {
-            this.unsubscribe(callback);
-            this.assocTrigger();
-            {
-                PluginsManager.emit('ObservableUnsubscribe', this);
-            }
-        };
     };
 
+    /**
+     * Watches for a specific value and executes callback when the observable equals that value.
+     * Creates a watcher that only triggers when the observable changes to the specified value.
+     *
+     * @param {*} value - The value to watch for
+     * @param {(value) => void|ObservableItem} callback - Callback function or observable to set when value matches
+     * @example
+     * const status = Observable('idle');
+     * status.on('loading', () => console.log('Started loading'));
+     * status.on('error', isError); // Set another observable
+     */
     ObservableItem.prototype.on = function(value, callback) {
         this.$watchers = this.$watchers ?? new Map();
 
         let watchValueList = this.$watchers.get(value);
 
+        if(callback.__$isObservable) {
+            callback = callback.set.bind(callback);
+        }
+
         if(!watchValueList) {
+            watchValueList = callback;
             this.$watchers.set(value, callback);
-        } else if(!Validator.isArray(watchValueList)) {
+        } else if(!Validator.isArray(watchValueList.list)) {
             watchValueList = [watchValueList, callback];
-            this.$watchers.set(value, watchValueList);
+            callback = (value) => {
+                for(let i = 0, length = watchValueList.length; i < length; i++) {
+                    watchValueList[i](value);
+                }
+            };
+            callback.list = watchValueList;
+            this.$watchers.set(value, callback);
         } else {
-            watchValueList.push(callback);
+            watchValueList.list.push(callback);
         }
 
         this.assocTrigger();
-        return () => {
-            const index = watchValueList.indexOf(callback);
-            watchValueList?.splice(index, 1);
-            if(watchValueList.size === 1) {
-                this.$watchers.set(value, watchValueList[0]);
-            }
-            else if(watchValueList.size === 0) {
-                this.$watchers?.delete(value);
-                watchValueList = null;
-            }
+    };
+
+    /**
+     * Removes a watcher for a specific value. If no callback is provided, removes all watchers for that value.
+     *
+     * @param {*} value - The value to stop watching
+     * @param {Function} [callback] - Specific callback to remove. If omitted, removes all watchers for this value
+     * @example
+     * const status = Observable('idle');
+     * const handler = () => console.log('Loading');
+     * status.on('loading', handler);
+     * status.off('loading', handler); // Remove specific handler
+     * status.off('loading'); // Remove all handlers for 'loading'
+     */
+    ObservableItem.prototype.off = function(value, callback) {
+        if(!this.$watchers) return;
+
+        const watchValueList = this.$watchers.get(value);
+        if(!watchValueList) return;
+
+        if(!callback || !Array.isArray(watchValueList.list)) {
+            this.$watchers?.delete(value);
             this.assocTrigger();
-        };
+            return;
+        }
+        const index = watchValueList.indexOf(callback);
+        watchValueList?.splice(index, 1);
+        if(watchValueList.length === 1) {
+            this.$watchers.set(value, watchValueList[0]);
+        }
+        else if(watchValueList.length === 0) {
+            this.$watchers?.delete(value);
+        }
+        this.assocTrigger();
     };
 
+    /**
+     * Subscribes to the observable but automatically unsubscribes after the first time the predicate matches.
+     *
+     * @param {(value) => Boolean|any} predicate - Value to match or function that returns true when condition is met
+     * @param {(value) => void} callback - Callback to execute when predicate matches, receives the matched value
+     * @example
+     * const status = Observable('loading');
+     * status.once('ready', (val) => console.log('Ready!'));
+     * status.once(val => val === 'error', (val) => console.log('Error occurred'));
+     */
     ObservableItem.prototype.once = function(predicate, callback) {
         const fn = typeof predicate === 'function' ? predicate : (v) => v === predicate;
 
-        const unsub = this.subscribe((val) => {
+        const handler = (val) => {
             if (fn(val)) {
-                unsub();
+                this.unsubscribe(handler);
                 callback(val);
             }
-        });
-        return unsub;
+        };
+        this.subscribe(handler);
     };
 
     /**
@@ -593,11 +735,15 @@ var NativeDocument = (function (exports) {
      * @param {Function} callback
      */
     ObservableItem.prototype.unsubscribe = function(callback) {
+        if(!this.$listeners) return;
         const index = this.$listeners.indexOf(callback);
         if (index > -1) {
             this.$listeners.splice(index, 1);
         }
         this.assocTrigger();
+        {
+            PluginsManager$1.emit('ObservableUnsubscribe', this);
+        }
     };
 
     /**
@@ -609,15 +755,50 @@ var NativeDocument = (function (exports) {
         return new ObservableChecker(this, callback)
     };
 
+    /**
+     * Gets a property value from the observable's current value.
+     * If the property is an observable, returns its value.
+     *
+     * @param {string|number} key - Property key to retrieve
+     * @returns {*} The value of the property, unwrapped if it's an observable
+     * @example
+     * const user = Observable({ name: 'John', age: Observable(25) });
+     * user.get('name'); // 'John'
+     * user.get('age'); // 25 (unwrapped from observable)
+     */
     ObservableItem.prototype.get = function(key) {
         const item = this.$currentValue[key];
         return Validator.isObservable(item) ? item.val() : item;
     };
 
+    /**
+     * Creates an ObservableWhen that represents whether the observable equals a specific value.
+     * Returns an object that can be subscribed to and will emit true/false.
+     *
+     * @param {*} value - The value to compare against
+     * @returns {ObservableWhen} An ObservableWhen instance that tracks when the observable equals the value
+     * @example
+     * const status = Observable('idle');
+     * const isLoading = status.when('loading');
+     * isLoading.subscribe(active => console.log('Loading:', active));
+     * status.set('loading'); // Logs: "Loading: true"
+     */
     ObservableItem.prototype.when = function(value) {
         return new ObservableWhen(this, value);
     };
 
+    /**
+     * Compares the observable's current value with another value or observable.
+     *
+     * @param {*|ObservableItem} other - Value or observable to compare against
+     * @returns {boolean} True if values are equal
+     * @example
+     * const a = Observable(5);
+     * const b = Observable(5);
+     * a.equals(5);  // true
+     * a.equals(b);  // true
+     * a.equals(10); // false
+     */
     ObservableItem.prototype.equals = function(other) {
         if(Validator.isObservable(other)) {
             return this.$currentValue === other.$currentValue;
@@ -625,14 +806,41 @@ var NativeDocument = (function (exports) {
         return this.$currentValue === other;
     };
 
+    /**
+     * Converts the observable's current value to a boolean.
+     *
+     * @returns {boolean} The boolean representation of the current value
+     * @example
+     * const count = Observable(0);
+     * count.toBool(); // false
+     * count.set(5);
+     * count.toBool(); // true
+     */
     ObservableItem.prototype.toBool = function() {
         return !!this.$currentValue;
     };
 
+    /**
+     * Toggles the boolean value of the observable (false becomes true, true becomes false).
+     *
+     * @example
+     * const isOpen = Observable(false);
+     * isOpen.toggle(); // Now true
+     * isOpen.toggle(); // Now false
+     */
     ObservableItem.prototype.toggle = function() {
         this.set(!this.$currentValue);
     };
 
+    /**
+     * Resets the observable to its initial value.
+     * Only works if the observable was created with { reset: true } config.
+     *
+     * @example
+     * const count = Observable(0, { reset: true });
+     * count.set(10);
+     * count.reset(); // Back to 0
+     */
     ObservableItem.prototype.reset = function() {
         if(!this.configs?.reset) {
             return;
@@ -645,11 +853,25 @@ var NativeDocument = (function (exports) {
         this.set(resetValue);
     };
 
-
+    /**
+     * Returns a string representation of the observable's current value.
+     *
+     * @returns {string} String representation of the current value
+     */
     ObservableItem.prototype.toString = function() {
         return String(this.$currentValue);
     };
 
+    /**
+     * Returns the primitive value of the observable (its current value).
+     * Called automatically in type coercion contexts.
+     *
+     * @returns {*} The current value of the observable
+     */
+    ObservableItem.prototype.valueOf = function() {
+        return this.$currentValue;
+    };
+
     const DocumentObserver = {
         mounted: new WeakMap(),
         mountedSupposedSize: 0,
@@ -757,7 +979,7 @@ var NativeDocument = (function (exports) {
         this.$element = element;
         this.$observer = null;
         {
-            PluginsManager.emit('NDElementCreated', element, this);
+            PluginsManager$1.emit('NDElementCreated', element, this);
         }
     }
 
@@ -853,12 +1075,35 @@ var NativeDocument = (function (exports) {
         return this.shadow('closed', style);
     };
 
+    /**
+     * Attaches a template binding to the element by hydrating it with the specified method.
+     *
+     * @param {string} methodName - Name of the hydration method to call
+     * @param {BindingHydrator} bindingHydrator - Template binding with $hydrate method
+     * @returns {HTMLElement} The underlying HTML element
+     * @example
+     * const onClick = $binder.attach((event, data) => console.log(data));
+     * element.nd.attach('onClick', onClick);
+     */
     NDElement.prototype.attach = function(methodName, bindingHydrator) {
         bindingHydrator.$hydrate(this.$element, methodName);
         return this.$element;
     };
 
-
+    /**
+     * Extends the current NDElement instance with custom methods.
+     * Methods are bound to the instance and available for chaining.
+     *
+     * @param {Object} methods - Object containing method definitions
+     * @returns {this} The NDElement instance with added methods for chaining
+     * @example
+     * element.nd.with({
+     *   highlight() {
+     *     this.$element.style.background = 'yellow';
+     *     return this;
+     *   }
+     * }).highlight().onClick(() => console.log('Clicked'));
+     */
     NDElement.prototype.with = function(methods) {
         if (!methods || typeof methods !== 'object') {
             throw new NativeDocumentError('extend() requires an object of methods');
@@ -878,7 +1123,7 @@ var NativeDocument = (function (exports) {
             }
             {
                 if (this[name] && !this.$localExtensions.has(name)) {
-                    DebugManager.warn('NDElement.extend', `Method "${name}" already exists and will be overwritten`);
+                    DebugManager$1.warn('NDElement.extend', `Method "${name}" already exists and will be overwritten`);
                 }
                 this.$localExtensions.set(name, method);
             }
@@ -889,6 +1134,23 @@ var NativeDocument = (function (exports) {
         return this;
     };
 
+    /**
+     * Extends the NDElement prototype with new methods available to all NDElement instances.
+     * Use this to add global methods to all NDElements.
+     *
+     * @param {Object} methods - Object containing method definitions to add to prototype
+     * @returns {typeof NDElement} The NDElement constructor
+     * @throws {NativeDocumentError} If methods is not an object or contains non-function values
+     * @example
+     * NDElement.extend({
+     *   fadeIn() {
+     *     this.$element.style.opacity = '1';
+     *     return this;
+     *   }
+     * });
+     * // Now all NDElements have .fadeIn() method
+     * Div().nd.fadeIn();
+     */
     NDElement.extend = function(methods) {
         if (!methods || typeof methods !== 'object') {
             throw new NativeDocumentError('NDElement.extend() requires an object of methods');
@@ -912,23 +1174,23 @@ var NativeDocument = (function (exports) {
             const method = methods[name];
 
             if (typeof method !== 'function') {
-                DebugManager.warn('NDElement.extend', `"${name}" is not a function, skipping`);
+                DebugManager$1.warn('NDElement.extend', `"${name}" is not a function, skipping`);
                 continue;
             }
 
             if (protectedMethods.has(name)) {
-                DebugManager.error('NDElement.extend', `Cannot override protected method "${name}"`);
+                DebugManager$1.error('NDElement.extend', `Cannot override protected method "${name}"`);
                 throw new NativeDocumentError(`Cannot override protected method "${name}"`);
             }
 
             if (NDElement.prototype[name]) {
-                DebugManager.warn('NDElement.extend', `Overwriting existing prototype method "${name}"`);
+                DebugManager$1.warn('NDElement.extend', `Overwriting existing prototype method "${name}"`);
             }
 
             NDElement.prototype[name] = method;
         }
         {
-            PluginsManager.emit('NDElementExtended', methods);
+            PluginsManager$1.emit('NDElementExtended', methods);
         }
 
         return NDElement;
@@ -1081,7 +1343,7 @@ var NativeDocument = (function (exports) {
             const foundReserved = Object.keys(attributes).filter(key => reserved.includes(key));
 
             if (foundReserved.length > 0) {
-                DebugManager.warn('Validator', `Reserved attributes found: ${foundReserved.join(', ')}`);
+                DebugManager$1.warn('Validator', `Reserved attributes found: ${foundReserved.join(', ')}`);
             }
 
             return attributes;
@@ -1129,7 +1391,7 @@ var NativeDocument = (function (exports) {
         anchorFragment.appendChild = function(child, before = null) {
             const parent = anchorEnd.parentNode;
             if(!parent) {
-                DebugManager.error('Anchor', 'Anchor : parent not found', child);
+                DebugManager$1.error('Anchor', 'Anchor : parent not found', child);
                 return;
             }
             before = before ?? anchorEnd;
@@ -1357,7 +1619,7 @@ var NativeDocument = (function (exports) {
                 continue;
             }
             if(value.__$isObservableWhen) {
-                element.classes.toggle(className, value.isMath());
+                element.classes.toggle(className, value.isActive());
                 value.subscribe((shouldAdd) => element.classes.toggle(className, shouldAdd));
                 continue;
             }
@@ -1503,6 +1765,8 @@ var NativeDocument = (function (exports) {
         return ElementCreator.createObservableNode(null, this);
     };
 
+    ObservableChecker.prototype.toNdElement = ObservableItem.prototype.toNdElement;
+
     NDElement.prototype.toNdElement = function () {
         return this.$element ?? this.$build?.() ?? this.build?.() ?? null;
     };
@@ -1520,7 +1784,7 @@ var NativeDocument = (function (exports) {
     Function.prototype.toNdElement = function () {
         const child = this;
         {
-            PluginsManager.emit('BeforeProcessComponent', child);
+            PluginsManager$1.emit('BeforeProcessComponent', child);
         }
         return ElementCreator.getChild(child());
     };
@@ -1626,14 +1890,14 @@ var NativeDocument = (function (exports) {
         processChildren(children, parent) {
             if(children === null) return;
             {
-                PluginsManager.emit('BeforeProcessChildren', parent);
+                PluginsManager$1.emit('BeforeProcessChildren', parent);
             }
             let child = this.getChild(children);
             if(child) {
                 parent.appendChild(child);
             }
             {
-                PluginsManager.emit('AfterProcessChildren', parent);
+                PluginsManager$1.emit('AfterProcessChildren', parent);
             }
         },
         getChild(child) {
@@ -1849,6 +2113,10 @@ var NativeDocument = (function (exports) {
             _stop(this.$element, eventName, callback);
             return this;
         };
+        NDElement.prototype['onPreventStop'+eventSourceName] = function(callback = null) {
+            _preventStop(this.$element, eventName, callback);
+            return this;
+        };
     });
 
     EVENTS_WITH_PREVENT.forEach(eventSourceName => {
@@ -1882,6 +2150,16 @@ var NativeDocument = (function (exports) {
         return this;
     };
 
+    const _preventStop = function(element, eventName, callback) {
+        const handler = (event) => {
+            event.stopPropagation();
+            event.preventDefault();
+            callback && callback.call(element, event);
+        };
+        element.addEventListener(eventName, handler);
+        return this;
+    };
+
 
 
     // ----------------------------------------------------------------
@@ -2154,7 +2432,12 @@ var NativeDocument = (function (exports) {
 
     const applyBindingTreePath = (root, target, data, path) => {
         if(path.fn) {
-            path.fn(data, target, root);
+            if(typeof path.fn === 'string') {
+                ElementCreator.bindTextNode(target, data[0][path.fn]);
+            }
+            else {
+                path.fn(data, target, root);
+            }
         }
         if(path.children) {
             for(let i = 0, length = path.children.length; i < length; i++) {
@@ -2180,15 +2463,16 @@ var NativeDocument = (function (exports) {
                 if(bindDingData && bindDingData.value) {
                     currentPath.fn = bindDingData.value;
                     const textNode = node.cloneNode();
+                    if(typeof bindDingData.value === 'string') {
+                        ElementCreator.bindTextNode(textNode, data[0][bindDingData.value]);
+                        return textNode;
+                    }
                     bindDingData.value(data, textNode);
                     return textNode;
                 }
                 return node.cloneNode(true);
             }
-            const nodeCloned = node.cloneNode(node.fullCloneNode);
-            if(node.fullCloneNode) {
-                return nodeCloned;
-            }
+            const nodeCloned = node.cloneNode();
             if(bindDingData) {
                 bindAttributes(nodeCloned, bindDingData, data);
                 bindAttachMethods(nodeCloned, bindDingData, data);
@@ -2253,12 +2537,9 @@ var NativeDocument = (function (exports) {
         };
         this.value = (callbackOrProperty) => {
             if(typeof callbackOrProperty !== 'function') {
-                return createBinding(function(data, textNode) {
-                    const firstArgument = data[0];
-                    ElementCreator.bindTextNode(textNode, firstArgument[callbackOrProperty]);
-                }, 'value');
+                return createBinding(callbackOrProperty, 'value');
             }
-            return createBinding(function(data, textNode) {
+            return createBinding((data, textNode) => {
                 ElementCreator.bindTextNode(textNode, callbackOrProperty(...data));
             }, 'value');
         };
@@ -2360,13 +2641,14 @@ var NativeDocument = (function (exports) {
     };
 
     Function.prototype.errorBoundary = function(callback) {
-        return (...args)  => {
+        const handler = (...args)  => {
             try {
                 return this.apply(this, args);
             } catch(e) {
-                return callback(e);
+                return callback(e, {caller: handler, args: args });
             }
         };
+        return handler;
     };
 
     String.prototype.use = function(args) {
@@ -2438,12 +2720,13 @@ var NativeDocument = (function (exports) {
         };
     };
 
-    const once = (fn) => {
+    const once$1 = (fn) => {
         let result = null;
         return (...args) => {
-            if(result === null) {
-                result = fn(...args);
+            if(result) {
+                return result;
             }
+            result = fn(...args);
             return result;
         };
     };
@@ -2452,22 +2735,26 @@ var NativeDocument = (function (exports) {
         let target = null;
         return new Proxy({}, {
             get: (_, key) => {
-                if(target === null) {
-                    target = fn();
+                if(target) {
+                    return target[key];
                 }
+                target = fn();
                 return target[key];
             }
         });
     };
 
-    const memoize = (fn) => {
+    const memoize$1 = (fn) => {
         const cache = new Map();
         return (...args) => {
             const [key, ...rest] = args;
-            if(!cache.has(key)) {
-                cache.set(key, fn(...rest));
+            const cached = cache.get(key);
+            if(cached) {
+                return cached;
             }
-            return cache.get(key);
+            const result = fn(...rest);
+            cache.set(key, result);
+            return result;
         };
     };
 
@@ -2475,17 +2762,21 @@ var NativeDocument = (function (exports) {
         const cache = new Map();
         return new Proxy({}, {
             get: (_, key) => {
-                if(!cache.has(key)) {
-                    if(fn.length > 0) {
-                        return (...args) => {
-                            const result = fn(...args);
-                            cache.set(key, result);
-                            return result;
-                        }
+                const cached = cache.get(key);
+                if(cached) {
+                    return cached;
+                }
+
+                if(fn.length > 0) {
+                    return (...args) => {
+                        const result = fn(...args, key);
+                        cache.set(key, result);
+                        return result;
                     }
-                    cache.set(key, fn());
                 }
-                return cache.get(key);
+                const result = fn(key);
+                cache.set(key, result);
+                return result;
             }
         });
     };
@@ -2858,7 +3149,7 @@ var NativeDocument = (function (exports) {
 
         ObservableItem.call(this, target, configs);
         {
-            PluginsManager.emit('CreateObservableArray', this);
+            PluginsManager$1.emit('CreateObservableArray', this);
         }
     };
 
@@ -2887,6 +3178,14 @@ var NativeDocument = (function (exports) {
         };
     });
 
+    /**
+     * Removes all items from the array and triggers an update.
+     *
+     * @returns {boolean} True if array was cleared, false if it was already empty
+     * @example
+     * const items = Observable.array([1, 2, 3]);
+     * items.clear(); // []
+     */
     ObservableArray.prototype.clear = function() {
         if(this.$currentValue.length === 0) {
             return;
@@ -2896,19 +3195,42 @@ var NativeDocument = (function (exports) {
         return true;
     };
 
+    /**
+     * Returns the element at the specified index in the array.
+     *
+     * @param {number} index - Zero-based index of the element to retrieve
+     * @returns {*} The element at the specified index
+     * @example
+     * const items = Observable.array(['a', 'b', 'c']);
+     * items.at(1); // 'b'
+     */
     ObservableArray.prototype.at = function(index) {
         return this.$currentValue[index];
     };
 
+
+    /**
+     * Merges multiple values into the array and triggers an update.
+     * Similar to push but with a different operation name.
+     *
+     * @param {Array} values - Array of values to merge
+     * @example
+     * const items = Observable.array([1, 2]);
+     * items.merge([3, 4]); // [1, 2, 3, 4]
+     */
     ObservableArray.prototype.merge = function(values) {
         this.$currentValue.push.apply(this.$currentValue, values);
         this.trigger({ action: 'merge',  args: values });
     };
 
     /**
+     * Counts the number of elements that satisfy the provided condition.
      *
-     * @param {Function} condition
-     * @returns {number}
+     * @param {(value: *, index: number) => Boolean} condition - Function that tests each element (item, index) => boolean
+     * @returns {number} The count of elements that satisfy the condition
+     * @example
+     * const numbers = Observable.array([1, 2, 3, 4, 5]);
+     * numbers.count(n => n > 3); // 2
      */
     ObservableArray.prototype.count = function(condition) {
         let count = 0;
@@ -2920,6 +3242,16 @@ var NativeDocument = (function (exports) {
         return count;
     };
 
+    /**
+     * Swaps two elements at the specified indices and triggers an update.
+     *
+     * @param {number} indexA - Index of the first element
+     * @param {number} indexB - Index of the second element
+     * @returns {boolean} True if swap was successful, false if indices are out of bounds
+     * @example
+     * const items = Observable.array(['a', 'b', 'c']);
+     * items.swap(0, 2); // ['c', 'b', 'a']
+     */
     ObservableArray.prototype.swap = function(indexA, indexB) {
         const value = this.$currentValue;
         const length = value.length;
@@ -2940,6 +3272,15 @@ var NativeDocument = (function (exports) {
         return true;
     };
 
+    /**
+     * Removes the element at the specified index and triggers an update.
+     *
+     * @param {number} index - Index of the element to remove
+     * @returns {Array} Array containing the removed element, or empty array if index is invalid
+     * @example
+     * const items = Observable.array(['a', 'b', 'c']);
+     * items.remove(1); // ['b'] - Array is now ['a', 'c']
+     */
     ObservableArray.prototype.remove = function(index) {
         const deleted = this.$currentValue.splice(index, 1);
         if(deleted.length === 0) {
@@ -2949,20 +3290,60 @@ var NativeDocument = (function (exports) {
         return deleted;
     };
 
+    /**
+     * Removes the first occurrence of the specified item from the array.
+     *
+     * @param {*} item - The item to remove
+     * @returns {Array} Array containing the removed element, or empty array if item not found
+     * @example
+     * const items = Observable.array(['a', 'b', 'c']);
+     * items.removeItem('b'); // ['b'] - Array is now ['a', 'c']
+     */
     ObservableArray.prototype.removeItem = function(item) {
         const indexOfItem = this.$currentValue.indexOf(item);
+        if(indexOfItem === -1) {
+            return [];
+        }
         return this.remove(indexOfItem);
     };
 
+    /**
+     * Checks if the array is empty.
+     *
+     * @returns {boolean} True if array has no elements
+     * @example
+     * const items = Observable.array([]);
+     * items.isEmpty(); // true
+     */
     ObservableArray.prototype.isEmpty = function() {
         return this.$currentValue.length === 0;
     };
 
+    /**
+     * Triggers a populate operation with the current array, iteration count, and callback.
+     * Used internally for rendering optimizations.
+     *
+     * @param {number} iteration - Iteration count for rendering
+     * @param {Function} callback - Callback function for rendering items
+     */
     ObservableArray.prototype.populateAndRender = function(iteration, callback) {
         this.trigger({ action: 'populate', args: [this.$currentValue, iteration, callback] });
     };
 
 
+    /**
+     * Creates a filtered view of the array based on predicates.
+     * The filtered array updates automatically when source data or predicates change.
+     *
+     * @param {Object} predicates - Object mapping property names to filter conditions or functions
+     * @returns {ObservableArray} A new observable array containing filtered items
+     * @example
+     * const users = Observable.array([
+     *   { name: 'John', age: 25 },
+     *   { name: 'Jane', age: 30 }
+     * ]);
+     * const adults = users.where({ age: (val) => val >= 18 });
+     */
     ObservableArray.prototype.where = function(predicates) {
         const sourceArray = this;
         const observableDependencies = [sourceArray];
@@ -3011,6 +3392,20 @@ var NativeDocument = (function (exports) {
         return viewArray;
     };
 
+    /**
+     * Creates a filtered view where at least one of the specified fields matches the filter.
+     *
+     * @param {Array<string>} fields - Array of field names to check
+     * @param {FilterResult} filter - Filter condition with callback and dependencies
+     * @returns {ObservableArray} A new observable array containing filtered items
+     * @example
+     * const products = Observable.array([
+     *   { name: 'Apple', category: 'Fruit' },
+     *   { name: 'Carrot', category: 'Vegetable' }
+     * ]);
+     * const searchTerm = Observable('App');
+     * const filtered = products.whereSome(['name', 'category'], match(searchTerm));
+     */
     ObservableArray.prototype.whereSome = function(fields, filter) {
         return this.where({
             _: {
@@ -3020,6 +3415,20 @@ var NativeDocument = (function (exports) {
         });
     };
 
+    /**
+     * Creates a filtered view where all specified fields match the filter.
+     *
+     * @param {Array<string>} fields - Array of field names to check
+     * @param {FilterResult} filter - Filter condition with callback and dependencies
+     * @returns {ObservableArray} A new observable array containing filtered items
+     * @example
+     * const items = Observable.array([
+     *   { status: 'active', verified: true },
+     *   { status: 'active', verified: false }
+     * ]);
+     * const activeFilter = equals('active');
+     * const filtered = items.whereEvery(['status', 'verified'], activeFilter);
+     */
     ObservableArray.prototype.whereEvery = function(fields, filter) {
         return this.where({
             _: {
@@ -3030,10 +3439,19 @@ var NativeDocument = (function (exports) {
     };
 
     /**
+     * Creates an observable array with reactive array methods.
+     * All mutations trigger updates automatically.
      *
-     * @param {Array} target
-     * @param {{propagation: boolean, deep: boolean, reset: boolean}|null} configs
-     * @returns {ObservableArray}
+     * @param {Array} [target=[]] - Initial array value
+     * @param {Object|null} [configs=null] - Configuration options
+     * // @param {boolean} [configs.propagation=true] - Whether to propagate changes to parent observables
+     * // @param {boolean} [configs.deep=false] - Whether to make nested objects observable
+     * @param {boolean} [configs.reset=false] - Whether to store initial value for reset()
+     * @returns {ObservableArray} An observable array with reactive methods
+     * @example
+     * const items = Observable.array([1, 2, 3]);
+     * items.push(4); // Triggers update
+     * items.subscribe((arr) => console.log(arr));
      */
     Observable.array = function(target = [], configs = null) {
         return new ObservableArray(target, configs);
@@ -3098,10 +3516,26 @@ var NativeDocument = (function (exports) {
     };
 
     /**
+     * Creates an observable proxy for an object where each property becomes an observable.
+     * Properties can be accessed directly or via getter methods.
      *
-     * @param {Object} initialValue
-     * @param {{propagation: boolean, deep: boolean, reset: boolean}|null} configs
-     * @returns {Proxy}
+     * @param {Object} initialValue - Initial object value
+     * @param {Object|null} [configs=null] - Configuration options
+     * // @param {boolean} [configs.propagation=true] - Whether changes propagate to parent
+     * @param {boolean} [configs.deep=false] - Whether to make nested objects observable
+     * @param {boolean} [configs.reset=false] - Whether to enable reset() method
+     * @returns {ObservableProxy} A proxy where each property is an observable
+     * @example
+     * const user = Observable.init({
+     *   name: 'John',
+     *   age: 25,
+     *   address: { city: 'NYC' }
+     * }, { deep: true });
+     *
+     * user.name.val(); // 'John'
+     * user.name.set('Jane');
+     * user.name = 'Jane X'
+     * user.age.subscribe(val => console.log('Age:', val));
      */
     Observable.init = function(initialValue, configs = null) {
         const data = {};
@@ -3249,17 +3683,30 @@ var NativeDocument = (function (exports) {
     Observable.json = Observable.init;
 
     /**
+     * Creates a computed observable that automatically updates when its dependencies change.
+     * The callback is re-executed whenever any dependency observable changes.
      *
-     * @param {Function} callback
-     * @param {Array|Function} dependencies
-     * @returns {ObservableItem}
-     */
+     * @param {Function} callback - Function that returns the computed value
+     * @param {Array<ObservableItem|ObservableChecker|ObservableProxy>|Function} [dependencies=[]] - Array of observables to watch, or batch function
+     * @returns {ObservableItem} A new observable that updates automatically
+     * @example
+     * const firstName = Observable('John');
+     * const lastName = Observable('Doe');
+     * const fullName = Observable.computed(
+     *   () => `${firstName.val()} ${lastName.val()}`,
+     *   [firstName, lastName]
+     * );
+     *
+     * // With batch function
+     * const batch = Observable.batch(() => { ...  });
+     * const computed = Observable.computed(() => { ... }, batch);
+    */
     Observable.computed = function(callback, dependencies = []) {
         const initialValue = callback();
         const observable = new ObservableItem(initialValue);
         const updatedValue = nextTick(() => observable.set(callback()));
         {
-            PluginsManager.emit('CreateObservableComputed', observable, dependencies);
+            PluginsManager$1.emit('CreateObservableComputed', observable, dependencies);
         }
 
         if(Validator.isFunction(dependencies)) {
@@ -3357,12 +3804,24 @@ var NativeDocument = (function (exports) {
     }());
 
     /**
+     * Renders a list of items from an observable array or object, automatically updating when data changes.
+     * Efficiently manages DOM updates by tracking items with keys.
      *
-     * @param {Array|Object|ObservableItem} data
-     * @param {Function} callback
-     * @param {?Function|?string} key
-     * @param {{shouldKeepItemsInCache: boolean}?} configs
-     * @returns {DocumentFragment}
+     * @param {ObservableItem<Array|Object>} data - Observable containing array or object to iterate over
+     * @param {Function} callback - Function that renders each item (item, index) => ValidChild
+     * @param {string|Function} [key] - Property name or function to generate unique keys for items
+     * @param {Object} [options={}] - Configuration options
+     * @param {boolean} [options.shouldKeepItemsInCache=false] - Whether to cache rendered items
+     * @returns {AnchorDocumentFragment} Fragment managing the list rendering
+     * @example
+     * const users = Observable([
+     *   { id: 1, name: 'John' },
+     *   { id: 2, name: 'Jane' }
+     * ]);
+     * ForEach(users, (user) => Div({}, user.name), 'id');
+     *
+     * // With function key
+     * ForEach(items, (item) => Div({}, item), (item) => item.id);
      */
     function ForEach(data, callback, key, { shouldKeepItemsInCache = false } = {}) {
         const element = Anchor('ForEach');
@@ -3419,7 +3878,7 @@ var NativeDocument = (function (exports) {
                 }
                 cache.set(keyId, { keyId, isNew: true, child: new WeakRef(child), indexObserver});
             } catch (e) {
-                DebugManager.error('ForEach', `Error creating element for key ${keyId}` , e);
+                DebugManager$1.error('ForEach', `Error creating element for key ${keyId}` , e);
                 throw e;
             }
             return keyId;
@@ -3501,8 +3960,26 @@ var NativeDocument = (function (exports) {
         return element;
     }
 
+    /**
+     * Renders items from an ObservableArray with optimized array-specific updates.
+     * Provides index observables and handles array mutations efficiently.
+     *
+     * @param {ObservableArray} data - ObservableArray to iterate over
+     * @param {Function} callback - Function that renders each item (item, indexObservable) => ValidChild
+     * @param {Object} [configs={}] - Configuration options
+     * @param {boolean} [configs.shouldKeepItemsInCache] - Whether to cache rendered items
+     * @param {boolean} [configs.isParentUniqueChild] - When it's the only child of the parent
+     * @returns {AnchorDocumentFragment} Fragment managing the list rendering
+     * @example
+     * const items = Observable.array([1, 2, 3]);
+     * ForEachArray(items, (item, index) =>
+     *   Div({}, `Item ${item} at index ${index.val()}`)
+     * );
+     *
+     * items.push(4); // Automatically updates DOM
+     */
     function ForEachArray(data, callback, configs = {}) {
-        const element = Anchor('ForEach Array');
+        const element = Anchor('ForEach Array', configs.isParentUniqueChild);
         const blockEnd = element.endElement();
         const blockStart = element.startElement();
 
@@ -3677,7 +4154,7 @@ var NativeDocument = (function (exports) {
                         elementBeforeFirst = firstChildRemoved?.previousSibling;
 
                         for(let i = 0; i < deleted.length; i++) {
-                            firstItem(deleted[i], garbageFragment);
+                            removeByItem(deleted[i], garbageFragment);
                         }
                     }
                 } else {
@@ -3723,7 +4200,7 @@ var NativeDocument = (function (exports) {
         };
 
         const buildContent = (items, _, operations) => {
-            if(operations.action === 'clear' || !items.length) {
+            if(operations?.action === 'clear' || !items.length) {
                 if(lastNumberOfItems === 0) {
                     return;
                 }
@@ -3756,16 +4233,22 @@ var NativeDocument = (function (exports) {
     }
 
     /**
-     * Show the element if the condition is true
+     * Conditionally shows an element based on an observable condition.
+     * The element is mounted/unmounted from the DOM as the condition changes.
      *
-     * @param {ObservableItem|ObservableChecker} condition
-     * @param {*} child
-     * @param {{comment?: string|null, shouldKeepInCache?: Boolean}} configs
-     * @returns {DocumentFragment}
+     * @param {ObservableItem<boolean>|ObservableChecker<boolean>|ObservableWhen} condition - Observable condition to watch
+     * @param {ValidChild} child - Element or content to show/hide
+     * @param {Object} [options={}] - Configuration options
+     * @param {string|null} [options.comment=null] - Comment for debugging
+     * @param {boolean} [options.shouldKeepInCache=true] - Whether to cache the element when hidden
+     * @returns {AnchorDocumentFragment} Anchor fragment managing the conditional content
+     * @example
+     * const isVisible = Observable(false);
+     * ShowIf(isVisible, Div({}, 'Hello World'));
      */
     const ShowIf = function(condition, child, { comment = null, shouldKeepInCache = true} = {}) {
         if(!(Validator.isObservable(condition)) && !Validator.isObservableWhenResult(condition)) {
-            return DebugManager.warn('ShowIf', "ShowIf : condition must be an Observable / "+comment, condition);
+            return DebugManager$1.warn('ShowIf', "ShowIf : condition must be an Observable / "+comment, condition);
         }
         const element = Anchor('Show if : '+(comment || ''));
 
@@ -3798,11 +4281,18 @@ var NativeDocument = (function (exports) {
     };
 
     /**
-     * Hide the element if the condition is true
-     * @param {ObservableItem|ObservableChecker} condition
-     * @param child
-     * @param {{comment?: string|null, shouldKeepInCache?: Boolean}} configs
-     * @returns {DocumentFragment}
+     * Conditionally hides an element when the observable condition is true.
+     * Inverse of ShowIf - element is shown when condition is false.
+     *
+     * @param {ObservableItem<boolean>|ObservableChecker<boolean>} condition - Observable condition to watch
+     * @param {ValidChild} child - Element or content to show/hide
+     * @param {Object} [configs] - Configuration options
+     * @param {string|null} [configs.comment] - Comment for debugging
+     * @param {boolean} [configs.shouldKeepInCache] - Whether to cache element when hidden
+     * @returns {AnchorDocumentFragment} Anchor fragment managing the conditional content
+     * @example
+     * const hasError = Observable(false);
+     * HideIf(hasError, Div({}, 'Content'));
      */
     const HideIf = function(condition, child, configs) {
         const hideCondition = Observable(!condition.val());
@@ -3812,17 +4302,43 @@ var NativeDocument = (function (exports) {
     };
 
     /**
-     * Hide the element if the condition is false
+     * Conditionally hides an element when the observable condition is false.
+     * Same as ShowIf - element is shown when condition is true.
      *
-     * @param {ObservableItem|ObservableChecker} condition
-     * @param {*} child
-     * @param {{comment?: string|null, shouldKeepInCache?: Boolean}} configs
-     * @returns {DocumentFragment}
+     * @param {ObservableItem<boolean>|ObservableChecker<boolean>|ObservableWhen} condition - Observable condition to watch
+     * @param {ValidChild} child - Element or content to show/hide
+     * @param {Object} [configs] - Configuration options
+     * @param {string|null} [configs.comment] - Comment for debugging
+     * @param {boolean} [configs.shouldKeepInCache] - Whether to cache element when hidden
+     * @returns {AnchorDocumentFragment} Anchor fragment managing the conditional content
      */
     const HideIfNot = function(condition, child, configs) {
         return ShowIf(condition, child, configs);
     };
 
+    /**
+     * Shows content when an observable equals a specific value.
+     * Can be called with 2 or 3 arguments.
+     *
+     * @overload
+     * @param {ObservableWhen} observerWhenResult - Result from observable.when(value)
+     * @param {ValidChild} view - Content to show when condition matches
+     * @returns {AnchorDocumentFragment}
+     *
+     * @overload
+     * @param {ObservableItem} observer - Observable to watch
+     * @param {*} target - Value to match
+     * @param {ValidChild} view - Content to show when observable equals target
+     * @returns {AnchorDocumentFragment}
+     *
+     * @example
+     * // 2 arguments
+     * const status = Observable('idle');
+     * ShowWhen(status.when('loading'), LoadingSpinner());
+     *
+     * // 3 arguments
+     * ShowWhen(status, 'loading', LoadingSpinner());
+     */
     const ShowWhen = function() {
         if(arguments.length === 2) {
             const [observer, target] = arguments;
@@ -3852,11 +4368,24 @@ var NativeDocument = (function (exports) {
     };
 
     /**
+     * Displays different content based on the current value of an observable.
+     * Like a switch statement for UI - shows the content corresponding to current value.
      *
-     * @param {ObservableItem|ObservableChecker} $condition
-     * @param {{[key]: *}} values
-     * @param {Boolean} shouldKeepInCache
-     * @returns {DocumentFragment}
+     * @param {ObservableItem|ObservableChecker} $condition - Observable to watch
+     * @param {Object<string|number, ValidChild>} values - Map of values to their corresponding content
+     * @param {boolean} [shouldKeepInCache=true] - Whether to cache rendered views
+     * @returns {AnchorDocumentFragment & {add: Function, remove: Function}} Fragment with dynamic methods
+     * @example
+     * const status = Observable('idle');
+     * const view = Match(status, {
+     *   idle: Div({}, 'Ready'),
+     *   loading: Div({}, 'Loading...'),
+     *   error: Div({}, 'Error occurred')
+     * });
+     *
+     * // Dynamic addition
+     * view.add('success', Div({}, 'Success!'));
+     * view.remove('idle');
      */
     const Match = function($condition, values, shouldKeepInCache = true) {
 
@@ -3913,11 +4442,19 @@ var NativeDocument = (function (exports) {
 
 
     /**
+     * Displays one of two views based on a boolean observable condition.
+     * Simplified version of Match for true/false cases.
      *
-     * @param {ObservableItem|ObservableChecker} $condition
-     * @param {*} onTrue
-     * @param {*} onFalse
-     * @returns {DocumentFragment}
+     * @param {ObservableItem<boolean>|ObservableChecker<boolean>} $condition - Boolean observable to watch
+     * @param {ValidChild} onTrue - Content to show when condition is true
+     * @param {ValidChild} onFalse - Content to show when condition is false
+     * @returns {AnchorDocumentFragment} Fragment managing the conditional content
+     * @example
+     * const isLoggedIn = Observable(false);
+     * Switch(isLoggedIn,
+     *   Div({}, 'Welcome back!'),
+     *   Div({}, 'Please login')
+     * );
      */
     const Switch = function ($condition, onTrue, onFalse) {
         if(!Validator.isObservable($condition)) {
@@ -3931,9 +4468,15 @@ var NativeDocument = (function (exports) {
     };
 
     /**
+     * Provides a fluent API for conditional rendering with show/otherwise pattern.
      *
-     * @param {ObservableItem|ObservableChecker} $condition
-     * @returns {{show: Function, otherwise: (((*) => {}):DocumentFragment)}
+     * @param {ObservableItem<boolean>|ObservableChecker<boolean>} $condition - Boolean observable to watch
+     * @returns {{show: Function, otherwise: Function}} Object with fluent methods
+     * @example
+     * const isLoading = Observable(false);
+     * When(isLoading)
+     *   .show(LoadingSpinner())
+     *   .otherwise(Content());
      */
     const When = function($condition) {
         if(!Validator.isObservable($condition)) {
@@ -3951,6 +4494,9 @@ var NativeDocument = (function (exports) {
             otherwise(onFalse) {
                 $onFalse = onFalse;
                 return Switch($condition, $onTrue, $onFalse);
+            },
+            toNdElement() {
+                return Switch($condition, $onTrue, $onFalse);
             }
         }
     };
@@ -4290,11 +4836,16 @@ var NativeDocument = (function (exports) {
     };
 
     /**
+     * Creates a new Route instance.
      *
-     * @param {string} $path
-     * @param {Function} $component
-     * @param {{name:?string, middlewares:Function[], shouldRebuild:Boolean, with: Object }}$options
-     * @class
+     * @param {string} $path - URL pattern with optional parameters (e.g., '/user/{id:number}')
+     * @param {Function} $component - Component function that returns HTMLElement or DocumentFragment
+     * @param {Object} [$options={}] - Route configuration options
+     * @param {string} [$options.name] - Unique name for the route (used for navigation)
+     * @param {Function[]} [$options.middlewares] - Array of middleware functions
+     * @param {boolean} [$options.shouldRebuild] - Whether to rebuild component on each navigation
+     * @param {Object} [$options.with] - Custom parameter validation patterns
+     * @param {Function} [$options.layout] - Layout component wrapper function
      */
     function Route($path, $component, $options = {}) {
 
@@ -4393,7 +4944,6 @@ var NativeDocument = (function (exports) {
             super(message);
             this.context = context;
         }
-
     }
 
     const RouteGroupHelper = {
@@ -4552,7 +5102,7 @@ var NativeDocument = (function (exports) {
                 window.history.pushState({ name: route.name(), params, path}, route.name() || path , path);
                 this.handleRouteChange(route, params, query, path);
             } catch (e) {
-                DebugManager.error('HistoryRouter', 'Error in pushState', e);
+                DebugManager$1.error('HistoryRouter', 'Error in pushState', e);
             }
         };
         /**
@@ -4565,7 +5115,7 @@ var NativeDocument = (function (exports) {
                 window.history.replaceState({ name: route.name(), params, path}, route.name() || path , path);
                 this.handleRouteChange(route, params, {}, path);
             } catch(e) {
-                DebugManager.error('HistoryRouter', 'Error in replaceState', e);
+                DebugManager$1.error('HistoryRouter', 'Error in replaceState', e);
             }
         };
         this.forward = function() {
@@ -4592,7 +5142,7 @@ var NativeDocument = (function (exports) {
                     }
                     this.handleRouteChange(route, params, query, path);
                 } catch(e) {
-                    DebugManager.error('HistoryRouter', 'Error in popstate event', e);
+                    DebugManager$1.error('HistoryRouter', 'Error in popstate event', e);
                 }
             });
             const { route, params, query, path } = this.resolve(defaultPath || (window.location.pathname+window.location.search));
@@ -4789,7 +5339,7 @@ var NativeDocument = (function (exports) {
     /**
      *
      * @param {{mode: 'memory'|'history'|'hash'}} $options
-     * @constructor
+     * @class
      */
     function Router($options = {}) {
 
@@ -4817,7 +5367,7 @@ var NativeDocument = (function (exports) {
                     listener(request);
                     next && next(request);
                 } catch (e) {
-                    DebugManager.warn('Route Listener', 'Error in listener:', e);
+                    DebugManager$1.warn('Route Listener', 'Error in listener:', e);
                 }
             }
         };
@@ -4847,11 +5397,20 @@ var NativeDocument = (function (exports) {
         };
 
         /**
+         * Groups routes under a common path prefix with shared options.
          *
-         * @param {string} suffix
-         * @param {{ middlewares: Function[], name: string}} options
-         * @param {Function} callback
-         * @returns {this}
+         * @param {string} suffix - Path prefix to prepend to all routes in the group
+         * @param {Object} options - Group configuration options
+         * @param {Function[]} [options.middlewares] - Middlewares applied to all routes in group
+         * @param {string} [options.name] - Name prefix for all routes in group
+         * @param {Function} [options.layout] - Layout component for all routes in group
+         * @param {Function} callback - Function that defines routes within the group
+         * @returns {this} Router instance for chaining
+         * @example
+         * router.group('/admin', { middlewares: [authMiddleware], layout: AdminLayout }, () => {
+         *   router.add('/users', UsersPage, { name: 'users' });
+         *   router.add('/settings', SettingsPage, { name: 'settings' });
+         * });
          */
         this.group = function(suffix, options, callback) {
             if(!Validator.isFunction(callback)) {
@@ -4969,14 +5528,24 @@ var NativeDocument = (function (exports) {
     Router.routers = {};
 
     /**
+     * Creates and initializes a new router instance.
      *
-     * @param {{mode: 'memory'|'history'|'hash', name?:string, entry?: string}} options
-     * @param {Function} callback
-     * @param {Element} container
+     * @param {Object} options - Router configuration
+     * @param {'memory'|'history'|'hash'} options.mode - Routing mode
+     * @param {string} [options.name] - Router name for multi-router apps
+     * @param {string} [options.entry] - Initial route path
+     * @param {Function} callback - Setup function that receives the router instance
+     * @returns {Router} The configured router instance with mount() method
+     * @example
+     * const router = Router.create({ mode: 'history' }, (r) => {
+     *   r.add('/home', HomePage, { name: 'home' });
+     *   r.add('/about', AboutPage, { name: 'about' });
+     * });
+     * router.mount('#app');
      */
     Router.create = function(options, callback) {
         if(!Validator.isFunction(callback)) {
-            DebugManager.error('Router', 'Callback must be a function', e);
+            DebugManager$1.error('Router', 'Callback must be a function');
             throw new RouterError('Callback must be a function');
         }
         const router = new Router(options);
@@ -5143,16 +5712,22 @@ var NativeDocument = (function (exports) {
         };
     }
 
-    const Service = {
-        once: fn => autoOnce(fn),
-        memoize: fn => autoMemoize(fn)
-    };
+    const once = fn => autoOnce(fn);
+    const singleton = fn => once$1(fn);
+    const memoize = fn => autoMemoize(fn);
+
+    var cache = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        memoize: memoize,
+        once: once,
+        singleton: singleton
+    });
 
     var utils = /*#__PURE__*/Object.freeze({
         __proto__: null,
-        Filters: index,
+        Cache: cache,
         NativeFetch: NativeFetch,
-        Service: Service
+        filters: index
     });
 
     exports.$ = $;
@@ -5160,7 +5735,7 @@ var NativeDocument = (function (exports) {
     exports.HtmlElementWrapper = HtmlElementWrapper;
     exports.NDElement = NDElement;
     exports.Observable = Observable;
-    exports.PluginsManager = PluginsManager;
+    exports.PluginsManager = PluginsManager$1;
     exports.SingletonView = SingletonView;
     exports.Store = Store;
     exports.TemplateCloner = TemplateCloner;
@@ -5171,10 +5746,10 @@ var NativeDocument = (function (exports) {
     exports.createTextNode = createTextNode;
     exports.cssPropertyAccumulator = cssPropertyAccumulator;
     exports.elements = elements;
-    exports.memoize = memoize;
+    exports.memoize = memoize$1;
     exports.normalizeComponentArgs = normalizeComponentArgs;
     exports.obs = obs;
-    exports.once = once;
+    exports.once = once$1;
     exports.router = router;
     exports.useCache = useCache;
     exports.useSingleton = useSingleton;