native-document 1.0.16 → 1.0.17-1.10

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

@@ -0,0 +1,284 @@
+import Anchor from '../anchor/anchor';
+import { ElementCreator } from '../../wrappers/ElementCreator';
+import NativeDocumentError from '../../errors/NativeDocumentError';
+import ForEachArrayCache from './for-each-array-cache';
+
+
+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();
+
+    let lastNumberOfItems = 0;
+    const isIndexRequired = callback.length >= 2;
+    const cache = new ForEachArrayCache(isIndexRequired);
+
+    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);
+        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);
+            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);
+            Actions.appendToElement(data);
+        };
+    }
+    else {
+        set = () => {
+            const items = data.val();
+            clear(items);
+            Actions.appendToElement(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));
+            }
+            return fragment;
+        },
+        appendToElement: (items) => {
+            for(let i = 0, length = items.length; i < length; i++) {
+                element.appendChild(buildItem(items[i], i));
+            }
+        },
+        add: (items) => {
+            Actions.appendToElement(items);
+        },
+        replace: (items) => {
+            clear(items);
+            Actions.appendToElement(items);
+        },
+        set,
+        reOrder: (items) => {
+            let child = null;
+            for(const item of items) {
+                child = getItemChild(item);
+                if(child) {
+                    element.appendChild(child);
+                }
+            }
+            child = null;
+        },
+        removeOne: (element, index) => {
+            removeCacheItem(element, true);
+        },
+        clear,
+        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/{elements → core/elements}/control/for-each.js

@@ -1,24 +1,40 @@
-import ObservableItem from "../../data/ObservableItem";
-import {Observable} from "../../data/Observable";
-import {createTextNode} from "../../wrappers/HtmlElementWrapper";
-import Validator from "../../utils/validator";
-import Anchor from "../anchor";
-import DebugManager from "../../utils/debug-manager";
-import {getKey} from "../../utils/helpers";
+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');
  *
- * @param {Array|Object|ObservableItem} data
- * @param {Function} callback
- * @param {?Function} key
- * @returns {DocumentFragment}
+ * // With function key
+ * ForEach(items, (item) => Div({}, item), (item) => item.id);
  */
-export function ForEach(data, callback, key) {
-    const element = new Anchor('ForEach');
+export function ForEach(data, callback, key, { shouldKeepItemsInCache = false } = {}) {
+    callback = callback || SELF_RENDER;
+    const element = Anchor('ForEach');
     const blockEnd = element.endElement();
     const blockStart = element.startElement();
 
-    let cache = new Map();
+    const cache = new Map();
     let lastKeyOrder = null;
     const keyIds = new Set();
 
@@ -28,13 +44,16 @@ export function ForEach(data, callback, key) {
     };
 
     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) {
-                parent.removeChild(child);
+                child.remove();
             }
             cacheItem.indexObserver?.cleanup();
             cacheItem.child = null;
@@ -59,9 +78,9 @@ export function ForEach(data, callback, key) {
 
         try {
             const indexObserver = callback.length >= 2 ? Observable(indexKey) : null;
-            let child = callback(item, indexObserver);
-            if(Validator.isStringOrObservable(child)) {
-                child = createTextNode(child);
+            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) {
@@ -82,15 +101,15 @@ export function ForEach(data, callback, key) {
             child && fragment.appendChild(child);
         }
         parent.insertBefore(fragment, blockEnd);
-    }
+    };
 
     const diffingDOMUpdates = (parent) => {
         const operations = [];
-        let fragment = document.createDocumentFragment();
+        const fragment = document.createDocumentFragment();
         const newKeys = Array.from(keyIds);
         const oldKeys = Array.from(lastKeyOrder);
 
-        let currentPosition = blockStart;
+        const currentPosition = blockStart;
 
         for(const index in newKeys) {
             const itemKey = newKeys[index];
@@ -117,7 +136,7 @@ export function ForEach(data, callback, key) {
         keyIds.clear();
         if(Array.isArray(items)) {
             for(let i = 0, length = items.length; i < length; i++) {
-                const keyId= handleContentItem(items[i], i);
+                const keyId = handleContentItem(items[i], i);
                 keyIds.add(keyId);
             }
         } else {
@@ -145,7 +164,7 @@ export function ForEach(data, callback, key) {
 
     buildContent();
     if(Validator.isObservable(data)) {
-        data.subscribe(buildContent)
+        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)',
+        ],
+    });
+};

package/src/core/elements/control/switch.js

@@ -0,0 +1,141 @@
+import NativeDocumentError from '../../errors/NativeDocumentError';
+import Validator from '../../utils/validator';
+import Anchor from '../anchor/anchor';
+import {ElementCreator} from '../../wrappers/ElementCreator';
+
+
+
+/**
+ * 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 - Observable to watch
+ * @param {Object<string|number, NdChild|(() => NdChild)>} 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');
+ */
+export const Match = function($condition, values, shouldKeepInCache = true) {
+
+    if(!Validator.isObservable($condition)) {
+        throw new NativeDocumentError('Toggle : condition must be an Observable');
+    }
+
+    const anchor = Anchor('Match');
+    const cache = new Map();
+
+    const getItem = function(key) {
+        if(shouldKeepInCache && cache.has(key)) {
+            return cache.get(key);
+        }
+        let item = values[key];
+        if(!item) {
+            return null;
+        }
+        item = ElementCreator.getChild(item);
+        if(Validator.isFragment(item)) {
+            item = Array.from(item.children);
+        }
+        shouldKeepInCache && cache.set(key, item);
+        return item;
+    };
+
+    const defaultValue = $condition.val();
+    const defaultContent = getItem(defaultValue);
+    if(defaultContent) {
+        anchor.appendChild(defaultContent);
+    }
+
+    $condition.subscribe(value => {
+        const content = getItem(value);
+        anchor.remove();
+        if(content) {
+            anchor.appendChild(content);
+        }
+    });
+
+    return anchor.nd.with({
+        add(key, view, shouldFocusOn = false) {
+            values[key] = view;
+            if(shouldFocusOn) {
+                $condition.set(key);
+            }
+        },
+        remove(key) {
+            shouldKeepInCache && cache.delete(key);
+            $condition.set([...cache.keys()].at(-1) ?? '');
+            delete values[key];
+        },
+    });
+};
+
+
+/**
+ * Displays one of two views based on a boolean observable condition.
+ * Simplified version of Match for true/false cases.
+ *
+ * @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')
+ * );
+ */
+export const Switch = function ($condition, onTrue, onFalse) {
+    if(!Validator.isObservable($condition)) {
+        throw new NativeDocumentError('Toggle : condition must be an Observable');
+    }
+
+    return Match($condition.toBoolean(), {
+        true: onTrue,
+        false: onFalse,
+    });
+};
+
+/**
+ * Provides a fluent API for conditional rendering with show/otherwise pattern.
+ *
+ * @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());
+ */
+export const When = function($condition) {
+    if(!Validator.isObservable($condition)) {
+        throw new NativeDocumentError('When : condition must be an Observable');
+    }
+
+    let $onTrue = null;
+    let $onFalse = null;
+
+    return {
+        show(onTrue) {
+            $onTrue = onTrue;
+            return this;
+        },
+        otherwise(onFalse) {
+            $onFalse = onFalse;
+            return Switch($condition, $onTrue, $onFalse);
+        },
+        toNdElement() {
+            return Switch($condition, $onTrue, $onFalse);
+        },
+    };
+};