native-document 1.0.14 → 1.0.16-8.1

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

@@ -0,0 +1,292 @@
+import Anchor from '../anchor/anchor';
+import { ElementCreator } from '../../wrappers/ElementCreator';
+import NativeDocumentError from '../../errors/NativeDocumentError';
+
+
+const CREATE_AND_CACHE_ACTIONS = new Set(['clear', 'push', 'unshift', 'replace']);
+
+const SELF_RENDER = (item) => item;
+
+/**
+ * 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 {((item: *, index: null|ObservableItem) => NdChild)?} 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 = {}) {
+    callback = callback || SELF_RENDER;
+    const element = Anchor('ForEach Array', configs.isParentUniqueChild);
+    const blockEnd = element.endElement();
+
+    const cache = new Map();
+    let lastNumberOfItems = 0;
+    const isIndexRequired = callback.length >= 2;
+
+    const clear = (items) => {
+        element.removeChildren();
+        cleanCache(items);
+        lastNumberOfItems = 0;
+    };
+
+    const getItemChild = (item) => {
+        return cache.get(item)?.child;
+    };
+
+    const removeCacheItem = (item, removeChild = true) => {
+        const cacheItem = cache.get(item);
+        if(!cacheItem) {
+            return;
+        }
+        if(removeChild) {
+            const child = cacheItem.child;
+            child?.remove();
+            cache.delete(item);
+        }
+        cacheItem.indexObserver?.cleanup();
+    };
+
+    const createAndCache = (item) => {
+        const child = ElementCreator.getChild(callback(item, null));
+        if(process.env.NODE_ENV === 'development') {
+            if(!child) {
+                throw new NativeDocumentError('ForEachArray child can\'t be null or undefined!');
+            }
+        }
+        cache.set(item, { child, indexObserver: null });
+        return child;
+    };
+
+    let createWithIndexAndCache = (item, indexKey) => {
+        const indexObserver = data.transform((items) =>  items.indexOf(item));
+        const child = ElementCreator.getChild(callback(item, indexObserver));
+        if(process.env.NODE_ENV === 'development') {
+            if(!child) {
+                throw new NativeDocumentError('ForEachArray child can\'t be null or undefined!');
+            }
+        }
+        cache.set(item, { child, indexObserver  });
+        return child;
+    };
+    if(!data.__$Observable) {
+        createWithIndexAndCache = (item, indexKey) => {
+            const child = ElementCreator.getChild(callback(item, indexKey));
+            if(process.env.NODE_ENV === 'development') {
+                if(!child) {
+                    throw new NativeDocumentError('ForEachArray child can\'t be null or undefined!');
+                }
+            }
+            cache.set(item, { child, indexObserver: null  });
+            return child;
+        };
+    }
+
+    const getOrCreate = (item, indexKey) => {
+        const cacheItem = cache.get(item);
+        if(cacheItem) {
+            cacheItem.indexObserver?.set(indexKey);
+            return cacheItem.child;
+        }
+        return createAndCache(item, indexKey);
+    };
+
+    let buildItem = createAndCache;
+    const selectBuildStrategy = (action = null) => {
+        if(CREATE_AND_CACHE_ACTIONS.has(action)) {
+            buildItem = isIndexRequired ? createWithIndexAndCache : createAndCache;
+            return;
+        }
+        buildItem = cache.size ? getOrCreate : (isIndexRequired ? createWithIndexAndCache : createAndCache);
+    };
+
+
+    let cleanCache;
+
+    if(!isIndexRequired) {
+        cleanCache = cache.clear.bind(cache);
+    }
+    else if(configs.shouldKeepItemsInCache) {
+        cleanCache = () => {};
+    } else {
+        cleanCache = (items) => {
+            for (const [itemAsKey, _] of cache.entries()) {
+                if(items && items.includes(itemAsKey)) {
+                    continue;
+                }
+                removeCacheItem(itemAsKey, false);
+            }
+        };
+    }
+
+    const removeByItem = (item, fragment) => {
+        const cacheItem = cache.get(item);
+        if(!cacheItem) {
+            return null;
+        }
+        const child = cacheItem.child;
+        if(!child) {
+            return null;
+        }
+
+        if(fragment) {
+            fragment.appendChild(child);
+            return;
+        }
+        child.remove();
+    };
+
+    let set = null;
+    if(Array.isArray(data)) {
+        set = () => {
+            clear(data);
+            element.appendChildRaw(Actions.toFragment(data));
+        };
+    }
+    else {
+        set = () => {
+            const items = data.val();
+            clear(items);
+            element.appendChildRaw(Actions.toFragment(items));
+        };
+    }
+
+    const Actions = {
+        toFragment: (items) =>{
+            const fragment = document.createDocumentFragment();
+            for(let i = 0, length = items.length; i < length; i++) {
+                fragment.appendChild(buildItem(items[i], lastNumberOfItems));
+                lastNumberOfItems++;
+            }
+            return fragment;
+        },
+        add: (items) => {
+            element.appendChildRaw(Actions.toFragment(items));
+        },
+        replace: (items) => {
+            clear(items);
+            element.appendChildRaw(Actions.toFragment(items));
+        },
+        set,
+        reOrder: (items) => {
+            let child = null;
+            const fragment = document.createDocumentFragment();
+            for(const item of items) {
+                child = getItemChild(item);
+                if(child) {
+                    fragment.appendChild(child);
+                }
+            }
+            child = null;
+            element.appendChildRaw(fragment);
+        },
+        removeOne: (element, index) => {
+            removeCacheItem(element, true);
+        },
+        clear,
+        populate: ([target, iteration, callback]) => {
+            const fragment = document.createDocumentFragment();
+            for (let i = 0; i < iteration; i++) {
+                const data = callback(i);
+                target.push(data);
+                fragment.append(buildItem(data, i));
+                lastNumberOfItems++;
+            }
+            element.appendChildRaw(fragment);
+            fragment.replaceChildren();
+        },
+        unshift: (values) => {
+            element.insertAtStartRaw(Actions.toFragment(values));
+        },
+        splice: (args, deleted) => {
+            const [start, deleteCount, ...values] = args;
+            let elementBeforeFirst = null;
+            const garbageFragment = document.createDocumentFragment();
+
+            if(deleted.length > 0) {
+                const firstItem = deleted[0];
+                if(deleted.length === 1) {
+                    removeByItem(firstItem, garbageFragment);
+                } else if(deleted.length > 1) {
+                    const firstChildRemoved = getItemChild(deleted[0]);
+                    elementBeforeFirst = firstChildRemoved?.previousSibling;
+
+                    for(let i = 0; i < deleted.length; i++) {
+                        removeByItem(deleted[i], garbageFragment);
+                    }
+                }
+            } else {
+                const indexBefore =  (start - 1 >= 0) ? start - 1 : start;
+                const itemAtStart = data.at(indexBefore);
+                elementBeforeFirst = getItemChild(itemAtStart) || blockEnd.previousSibling;
+            }
+            garbageFragment.replaceChildren();
+
+            if(values && values.length && elementBeforeFirst) {
+                element.insertBeforeRaw(Actions.toFragment(values), elementBeforeFirst.nextSibling);
+            }
+
+        },
+        reverse: (_, reversed) => {
+            Actions.reOrder(reversed);
+        },
+        sort: (_, sorted) => {
+            Actions.reOrder(sorted);
+        },
+        remove: (_, deleted)=> {
+            Actions.removeOne(deleted);
+        },
+        pop: (_, deleted) => {
+            Actions.removeOne(deleted);
+        },
+        shift: (_, deleted) => {
+            Actions.removeOne(deleted);
+        },
+        swap: (args, elements) => {
+            const parent = element.getParent();
+
+            let childA = getItemChild(elements[0]);
+            let childB = getItemChild(elements[1]);
+            if(!childA || !childB) {
+                return;
+            }
+
+            const childBNext = childB.nextSibling;
+            parent.insertBefore(childB, childA);
+            parent.insertBefore(childA, childBNext);
+            childA = null;
+            childB = null;
+        },
+    };
+    Actions.merge = Actions.add;
+    Actions.push = Actions.add;
+
+    const buildContent = (items, _, operations = {}) => {
+        selectBuildStrategy(operations.action);
+
+        if(Actions[operations.action]) {
+            Actions[operations.action](operations.args, operations.result);
+        }
+    };
+
+    if(Array.isArray(data)) {
+        buildContent(data, null, { action: 'set' });
+        return element;
+    }
+
+    if(data.val().length) {
+        buildContent(data.val(), null, { action: 'set' });
+    }
+    data.subscribe(buildContent);
+    return element;
+}

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

@@ -0,0 +1,170 @@
+import {Observable} from '../../data/Observable';
+import Validator from '../../utils/validator';
+import Anchor from '../anchor/anchor';
+import DebugManager from '../../utils/debug-manager';
+import {getKey} from '../../utils/helpers';
+import { ElementCreator } from '../../wrappers/ElementCreator';
+import NativeDocumentError from '../../errors/NativeDocumentError';
+
+const SELF_RENDER = (item) => item;
+
+/**
+ * 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 {ObservableItem<Array|Object>} data - Observable containing array or object to iterate over
+ * @param {((item: *, index: null|ObservableItem) => NdChild)?} 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 } = {}) {
+    callback = callback || SELF_RENDER;
+    const element = Anchor('ForEach');
+    const blockEnd = element.endElement();
+    const blockStart = element.startElement();
+
+    const cache = new Map();
+    let lastKeyOrder = null;
+    const keyIds = new Set();
+
+    const clear = () => {
+        element.removeChildren();
+        cleanCache();
+    };
+
+    const cleanCache = (parent) => {
+        if(shouldKeepItemsInCache) {
+            return;
+        }
+        for(const [keyId, cacheItem] of cache.entries()) {
+            if(keyIds.has(keyId)) {
+                continue;
+            }
+            const child = cacheItem.child?.deref();
+            if(parent && child) {
+                child.remove();
+            }
+            cacheItem.indexObserver?.cleanup();
+            cacheItem.child = null;
+            cacheItem.indexObserver = null;
+            cache.delete(cacheItem.keyId);
+            lastKeyOrder && lastKeyOrder.delete(cacheItem.keyId);
+        }
+    };
+
+    const handleContentItem = (item, indexKey) => {
+        const keyId = getKey(item, indexKey, key);
+
+        if(cache.has(keyId)) {
+            const cacheItem = cache.get(keyId);
+            cacheItem.indexObserver?.set(indexKey);
+            cacheItem.isNew = false;
+            if(cacheItem.child?.deref()) {
+                return keyId;
+            }
+            cache.delete(keyId);
+        }
+
+        try {
+            const indexObserver = callback.length >= 2 ? Observable(indexKey) : null;
+            const child = ElementCreator.getChild(callback(item, indexObserver));
+            if(!child) {
+                throw new NativeDocumentError('ForEach child can\'t be null or undefined!');
+            }
+            cache.set(keyId, { keyId, isNew: true, child: new WeakRef(child), indexObserver});
+        } catch (e) {
+            DebugManager.error('ForEach', `Error creating element for key ${keyId}` , e);
+            throw e;
+        }
+        return keyId;
+    };
+
+    const batchDOMUpdates = (parent) => {
+        const fragment = document.createDocumentFragment();
+        for(const itemKey of keyIds) {
+            const cacheItem = cache.get(itemKey);
+            if(!cacheItem) {
+                continue;
+            }
+            const child = cacheItem.child?.deref();
+            child && fragment.appendChild(child);
+        }
+        parent.insertBefore(fragment, blockEnd);
+    };
+
+    const diffingDOMUpdates = (parent) => {
+        const operations = [];
+        const fragment = document.createDocumentFragment();
+        const newKeys = Array.from(keyIds);
+        const oldKeys = Array.from(lastKeyOrder);
+
+        const currentPosition = blockStart;
+
+        for(const index in newKeys) {
+            const itemKey = newKeys[index];
+            const cacheItem = cache.get(itemKey);
+            if(!cacheItem) {
+                continue;
+            }
+            const child = cacheItem.child.deref();
+            if(!child) {
+                continue;
+            }
+            fragment.appendChild(child);
+        }
+        element.replaceContent(fragment);
+    };
+
+    const buildContent = () => {
+        const parent = blockEnd.parentNode;
+        if(!parent) {
+            return;
+        }
+
+        const items = (Validator.isObservable(data)) ? data.val() : data;
+        keyIds.clear();
+        if(Array.isArray(items)) {
+            for(let i = 0, length = items.length; i < length; i++) {
+                const keyId = handleContentItem(items[i], i);
+                keyIds.add(keyId);
+            }
+        } else {
+            for(const indexKey in items) {
+                const keyId = handleContentItem(items[indexKey], indexKey);
+                keyIds.add(keyId);
+            }
+        }
+
+        if(keyIds.size === 0) {
+            clear();
+            lastKeyOrder?.clear();
+            return;
+        }
+
+        cleanCache(parent);
+        if(!lastKeyOrder || lastKeyOrder.size === 0) {
+            batchDOMUpdates(parent);
+        } else {
+            diffingDOMUpdates(parent);
+        }
+        lastKeyOrder?.clear();
+        lastKeyOrder = new Set([...keyIds]);
+    };
+
+    buildContent();
+    if(Validator.isObservable(data)) {
+        data.subscribe(buildContent);
+    }
+    return element;
+}

package/src/core/elements/control/show-if.js

@@ -0,0 +1,94 @@
+import { Observable } from '../../data/Observable';
+import Validator from '../../utils/validator';
+import DebugManager from '../../utils/debug-manager.js';
+import Anchor from '../anchor/anchor';
+import {ElementCreator} from '../../wrappers/ElementCreator';
+
+/**
+ * Conditionally shows an element based on an observable condition.
+ * The element is mounted/unmounted from the DOM as the condition changes.
+ *
+ * @param {ObservableItem<boolean>|ObservableChecker<boolean>|ObservableWhen} condition - Observable condition to watch
+ * @param {NdChild|(() => NdChild)} 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'));
+ */
+export const ShowIf = function(condition, child, { comment = null, shouldKeepInCache = true} = {}) {
+    if(!Validator.isObservable(condition)) {
+        if(typeof condition === 'boolean') {
+            return condition ? ElementCreator.getChild(child) : null;
+        }
+
+        return DebugManager.warn('ShowIf', 'ShowIf : condition must be an Observable or boolean / '+comment, condition);
+    }
+    const element = Anchor('Show if : '+(comment || ''));
+
+    let childElement = null;
+    const getChildElement = () => {
+        if(childElement && shouldKeepInCache) {
+            return childElement;
+        }
+        childElement = ElementCreator.getChild(child);
+        if(Validator.isFragment(childElement)) {
+            childElement = Array.from(childElement.childNodes);
+        }
+        return childElement;
+    };
+
+    const currentValue = condition.val();
+
+    if(currentValue) {
+        element.appendChild(getChildElement());
+    }
+
+    condition.subscribe((value) => {
+        if(value) {
+            element.appendChild(getChildElement());
+            return;
+        }
+        element.remove();
+    });
+
+    return element;
+};
+
+/**
+ * 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 {NdChild|(() => NdChild)} 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'));
+ */
+export const HideIf = function(condition, child, configs) {
+    const hideCondition = Observable(!condition.val());
+    condition.subscribe(value => hideCondition.set(!value));
+
+    return ShowIf(hideCondition, child, configs);
+};
+
+/**
+ * Conditionally hides an element when the observable condition is false.
+ * Same as ShowIf - element is shown when condition is true.
+ *
+ * @param {ObservableItem<boolean>|ObservableChecker<boolean>|ObservableWhen} condition - Observable condition to watch
+ * @param {NdChild|(() => NdChild)} 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
+ */
+export const HideIfNot = function(condition, child, configs) {
+    return ShowIf(condition, child, configs);
+};

package/src/core/elements/control/show-when.js

@@ -0,0 +1,54 @@
+import Validator from '../../utils/validator.js';
+import NativeDocumentError from '../../errors/NativeDocumentError.js';
+import {ShowIf} from './show-if.js';
+
+/**
+ * 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 {NdChild|(() => NdChild)} view - Content to show when condition matches
+ * @returns {AnchorDocumentFragment}
+ *
+ * @overload
+ * @param {ObservableItem} observer - Observable to watch
+ * @param {*} target - Value to match
+ * @param {NdChild|(() => NdChild)} 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());
+ */
+export const ShowWhen = function() {
+    if(arguments.length === 2) {
+        const [observer, target] = arguments;
+        if(!Validator.isObservableWhenResult(observer)) {
+            throw new NativeDocumentError('showWhen observer must be an ObservableWhenResult', {
+                data: observer,
+                'help': 'Use observer.when(target) to create an ObservableWhenResult',
+            });
+        }
+        return ShowIf(observer, target);
+    }
+    if(arguments.length === 3) {
+        const [observer, target, view] = arguments;
+        if(!Validator.isObservable(observer)) {
+            throw new NativeDocumentError('showWhen observer must be an Observable', {
+                data: observer,
+            });
+        }
+        return ShowIf(observer.when(target), view);
+    }
+    throw new NativeDocumentError('showWhen must have 2 or 3 arguments', {
+        data: [
+            'showWhen(observer, target, view)',
+            'showWhen(observerWhenResult, view)',
+        ],
+    });
+};