native-document 1.0.92 → 1.0.93

package/src/core/data/ObservableArray.js

@@ -51,6 +51,14 @@ noMutationMethods.forEach((method) => {
     };
 });
 
+/**
+ * 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;
@@ -60,19 +68,42 @@ ObservableArray.prototype.clear = function() {
     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;
@@ -84,6 +115,16 @@ ObservableArray.prototype.count = function(condition) {
     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;
@@ -104,6 +145,15 @@ ObservableArray.prototype.swap = function(indexA, indexB) {
     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) {
@@ -113,20 +163,60 @@ ObservableArray.prototype.remove = function(index) {
     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];
@@ -175,6 +265,20 @@ ObservableArray.prototype.where = function(predicates) {
     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({
         _: {
@@ -184,6 +288,20 @@ ObservableArray.prototype.whereSome = function(fields, filter) {
     });
 };
 
+/**
+ * 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({
         _: {

package/src/core/data/ObservableChecker.js

@@ -12,6 +12,16 @@ export default function ObservableChecker($observable, $checker) {
 
 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));
@@ -20,22 +30,62 @@ ObservableChecker.prototype.subscribe = function(callback) {
     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();
 };

package/src/core/data/ObservableItem.js

@@ -53,6 +53,16 @@ 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;
@@ -184,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);
@@ -228,6 +248,17 @@ ObservableItem.prototype.subscribe = function(callback) {
     }
 };
 
+/**
+ * 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();
 
@@ -257,8 +288,16 @@ ObservableItem.prototype.on = function(value, callback) {
 };
 
 /**
- * @param {*} value
- * @param {Function} callback - if omitted, removes all watchers for this value
+ * 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;
@@ -278,11 +317,20 @@ ObservableItem.prototype.off = function(value, callback) {
     }
     else if(watchValueList.length === 0) {
         this.$watchers?.delete(value);
-        watchValueList = null;
     }
     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;
 
@@ -320,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;
@@ -336,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;
@@ -356,11 +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 {