native-document 1.0.91 → 1.0.93

package/src/core/data/ObservableItem.js

@@ -18,7 +18,9 @@ export default function ObservableItem(value, configs = null) {
 
     this.$previousValue = null;
     this.$currentValue = value;
-    this.$isCleanedUp = false;
+    if(process.env.NODE_ENV === 'development') {
+        this.$isCleanedUp = false;
+    }
 
     this.$firstListener = null;
     this.$listeners = null;
@@ -51,13 +53,24 @@ 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) {
@@ -65,33 +78,12 @@ ObservableItem.prototype.triggerListeners = function(operations) {
     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;
@@ -99,20 +91,20 @@ ObservableItem.prototype.triggerWatchers = function() {
     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);
 };
 
@@ -140,21 +132,8 @@ ObservableItem.prototype.assocTrigger = function() {
 };
 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;
     }
@@ -170,6 +149,30 @@ ObservableItem.prototype.set = function(data) {
     }
 };
 
+/**
+ * @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;
 };
@@ -191,6 +194,16 @@ ObservableItem.prototype.disconnectAll = function() {
     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);
@@ -205,79 +218,129 @@ ObservableItem.prototype.cleanup = function() {
     }
     MemoryManager.unregister(this.$memoryId);
     this.disconnectAll();
-    this.$isCleanedUp = true;
+    if(process.env.NODE_ENV === 'development') {
+        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(process.env.NODE_ENV === 'development') {
+        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');
+        }
     }
+    this.$listeners = this.$listeners ?? [];
 
     this.$listeners.push(callback);
     this.assocTrigger();
     if(process.env.NODE_ENV === 'development') {
-        PluginsManager.emit('ObservableSubscribe', this, target);
+        PluginsManager.emit('ObservableSubscribe', this);
     }
-    return () => {
-        this.unsubscribe(callback);
-        this.assocTrigger();
-        if(process.env.NODE_ENV === 'development') {
-            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);
 };
 
 /**
@@ -285,11 +348,15 @@ ObservableItem.prototype.once = function(predicate, callback) {
  * @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();
+    if(process.env.NODE_ENV === 'development') {
+        PluginsManager.emit('ObservableUnsubscribe', this);
+    }
 };
 
 /**
@@ -301,15 +368,50 @@ ObservableItem.prototype.check = function(callback) {
     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;
@@ -317,14 +419,41 @@ ObservableItem.prototype.equals = function(other) {
     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;
@@ -337,7 +466,21 @@ ObservableItem.prototype.reset = function() {
     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;
 };

package/src/core/data/ObservableWhen.js

@@ -1,4 +1,11 @@
 
+/**
+ * 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
+ */
 export const ObservableWhen = function(observer, value) {
     this.$target = value;
     this.$observer = observer;
@@ -6,18 +13,41 @@ export const ObservableWhen = function(observer, value) {
 
 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;

package/src/core/data/observable-helpers/array.js

@@ -3,10 +3,19 @@ import ObservableArray from "../ObservableArray";
 
 
 /**
+ * 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);

package/src/core/data/observable-helpers/computed.js

@@ -6,11 +6,24 @@ import PluginsManager from "../../utils/plugins-manager";
 import {nextTick} from "../../utils/helpers";
 
 /**
+ * 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);

package/src/core/data/observable-helpers/object.js

@@ -40,10 +40,26 @@ const ObservableGet = function(target, property) {
 };
 
 /**
+ * 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 = {};

package/src/core/elements/control/for-each-array.js

@@ -4,8 +4,26 @@ import Validator from "../../utils/validator";
 import { ElementCreator } from "../../wrappers/ElementCreator";
 import NativeDocumentError from "../../errors/NativeDocumentError";
 
+/**
+ * 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
+ */
 export 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();
 
@@ -180,7 +198,7 @@ export function ForEachArray(data, callback, configs = {}) {
                     elementBeforeFirst = firstChildRemoved?.previousSibling;
 
                     for(let i = 0; i < deleted.length; i++) {
-                        firstItem(deleted[i], garbageFragment);
+                        removeByItem(deleted[i], garbageFragment);
                     }
                 }
             } else {
@@ -226,7 +244,7 @@ export function ForEachArray(data, callback, configs = {}) {
     };
 
     const buildContent = (items, _, operations) => {
-        if(operations.action === 'clear' || !items.length) {
+        if(operations?.action === 'clear' || !items.length) {
             if(lastNumberOfItems === 0) {
                 return;
             }

package/src/core/elements/control/for-each.js

@@ -7,12 +7,24 @@ import { ElementCreator } from "../../wrappers/ElementCreator";
 import NativeDocumentError from "../../errors/NativeDocumentError";
 
 /**
+ * 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);
  */
 export function ForEach(data, callback, key, { shouldKeepItemsInCache = false } = {}) {
     const element = Anchor('ForEach');