native-document 1.0.15 → 1.0.16-8.2

package/src/core/wrappers/prototypes/nd-element-extensions.js

@@ -0,0 +1,157 @@
+import ObservableItem from '../../data/ObservableItem';
+import { NDElement } from '../NDElement';
+import TemplateBinding from '../TemplateBinding';
+import { ElementCreator } from '../ElementCreator';
+import PluginsManager from '../../utils/plugins-manager';
+import ObservableChecker from '../../data/ObservableChecker';
+
+/**
+ * Extends a prototype with a non-enumerable, configurable, writable property.
+ *
+ * @param {Function} Constructor - The constructor whose prototype to extend
+ * @param {string}   name        - Property name
+ * @param {Function} fn          - Implementation
+ */
+function extendsPrototype(Constructor, name, fn) {
+    Object.defineProperty(Constructor.prototype, name, {
+        value:        fn,
+        enumerable:   false,
+        configurable: true,
+        writable:     true,
+    });
+}
+
+// -- Static assignment (not a prototype method) -------------------------------
+
+NDElement.$getChild = ElementCreator.getChild;
+
+// -- toNdElement --------------------------------------------------------------
+
+/**
+ * Converts a string to a static text node.
+ * @returns {Text}
+ */
+extendsPrototype(Object, 'toNdElement', function() {
+    return ElementCreator.createStaticTextNode(null, JSON.stringify(this));
+});
+
+/**
+ * Converts a string to a static text node.
+ * @returns {Text}
+ */
+extendsPrototype(String, 'toNdElement', function() {
+    return ElementCreator.createStaticTextNode(null, this);
+});
+
+/**
+ * Converts a number to a static text node.
+ * @returns {Text}
+ */
+extendsPrototype(Number, 'toNdElement', function() {
+    return ElementCreator.createStaticTextNode(null, this.toString());
+});
+
+/**
+ * Returns the element itself (identity for DOM compatibility).
+ * @returns {Element}
+ */
+extendsPrototype(Element, 'toNdElement', function() {
+    return this;
+});
+
+/**
+ * Returns the text node itself (identity for DOM compatibility).
+ * @returns {Text}
+ */
+extendsPrototype(Text, 'toNdElement', function() {
+    return this;
+});
+
+/**
+ * Returns the comment node itself (identity for DOM compatibility).
+ * @returns {Comment}
+ */
+extendsPrototype(Comment, 'toNdElement', function() {
+    return this;
+});
+
+/**
+ * Returns the document itself (identity for DOM compatibility).
+ * @returns {Document}
+ */
+extendsPrototype(Document, 'toNdElement', function() {
+    return this;
+});
+
+/**
+ * Returns the document fragment itself (identity for DOM compatibility).
+ * @returns {DocumentFragment}
+ */
+extendsPrototype(DocumentFragment, 'toNdElement', function() {
+    return this;
+});
+
+/**
+ * Converts the ObservableItem to a reactive text node that updates automatically when the value changes.
+ * @returns {Text}
+ */
+extendsPrototype(ObservableItem, 'toNdElement', function() {
+    return ElementCreator.createObservableNode(null, this);
+});
+
+/**
+ * ObservableChecker shares the same reactive text node behaviour as ObservableItem.
+ * @returns {Text}
+ */
+extendsPrototype(ObservableChecker, 'toNdElement', ObservableItem.prototype.toNdElement);
+
+/**
+ * Converts the NDElement to its underlying HTMLElement (or ghost DOM fragment if ghostDom was used).
+ * @returns {HTMLElement|DocumentFragment}
+ */
+extendsPrototype(NDElement, 'toNdElement', function() {
+    const element = this.$element ?? this.$build?.() ?? this.build?.() ?? null;
+    if (this.$attachements) {
+        if (!this.$attachements.contains(this.$element)) {
+            this.$attachements.append(this.$element);
+        }
+        return this.$attachements;
+    }
+    return element;
+});
+
+/**
+ * Converts the array to a DocumentFragment containing all child elements.
+ * Each item is processed through ElementCreator.getChild().
+ * @returns {DocumentFragment}
+ */
+extendsPrototype(Array, 'toNdElement', function() {
+    const fragment = document.createDocumentFragment();
+    for (let i = 0, length = this.length; i < length; i++) {
+        const child = ElementCreator.getChild(this[i]);
+        if (child === null) continue;
+        fragment.appendChild(child);
+    }
+    return fragment;
+});
+
+/**
+ * Calls the function and converts its return value to a DOM node.
+ * Used internally by ElementCreator to process function-based children.
+ * @returns {Node}
+ */
+extendsPrototype(Function, 'toNdElement', function() {
+    const child = this;
+    if (process.env.NODE_ENV === 'development') {
+        PluginsManager.emit('BeforeProcessComponent', child);
+    }
+    return ElementCreator.getChild(child());
+});
+
+/**
+ * Converts the TemplateBinding to a hydratable DOM node for use in TemplateCloner.
+ * @returns {Node}
+ */
+extendsPrototype(TemplateBinding, 'toNdElement', function() {
+    return ElementCreator.createHydratableNode(null, this);
+});

package/src/core/wrappers/prototypes/nd-element.transition.extensions.js

@@ -0,0 +1,127 @@
+import {NDElement} from '../NDElement';
+
+/**
+ * @param {HTMLElement} el
+ * @param {number} timeout
+ */
+const waitForVisualEnd = (el, timeout = 1000) => {
+    return new Promise((resolve) => {
+        let isResolved = false;
+
+        const cleanupAndResolve = (e) => {
+            if (e && e.target !== el) return;
+            if (isResolved) return;
+
+            isResolved = true;
+            el.removeEventListener('transitionend', cleanupAndResolve);
+            el.removeEventListener('animationend', cleanupAndResolve);
+            clearTimeout(timer);
+            resolve();
+        };
+
+        el.addEventListener('transitionend', cleanupAndResolve);
+        el.addEventListener('animationend', cleanupAndResolve);
+
+        const timer = setTimeout(cleanupAndResolve, timeout);
+
+        const style = window.getComputedStyle(el);
+        const hasTransition = style.transitionDuration !== '0s';
+        const hasAnimation = style.animationDuration !== '0s';
+
+        if (!hasTransition && !hasAnimation) {
+            cleanupAndResolve();
+        }
+    });
+};
+
+/**
+ * Registers a beforeUnmount hook that plays an exit CSS transition before the element is removed.
+ * Adds the class `{transitionName}-exit`, waits for the transition/animation to end, then removes it.
+ *
+ * @param {string} transitionName - CSS class prefix for the exit transition
+ * @returns {this}
+ * @example
+ * Div({ class: 'modal' }).nd.transitionOut('fade');
+ * // Adds 'fade-exit' before removal, waits for transitionend/animationend
+ */
+NDElement.prototype.transitionOut = function(transitionName) {
+    const exitClass = transitionName + '-exit';
+    const el = this.$element;
+    this.beforeUnmount('transition-exit', async function() {
+        el.classes.add(exitClass);
+        await waitForVisualEnd(el);
+        el.classes.remove(exitClass);
+    });
+    return this;
+};
+
+/**
+ * Plays an enter CSS transition when the element is mounted into the DOM.
+ * Adds `{transitionName}-enter-from` immediately, then swaps to `{transitionName}-enter-to`
+ * on the next animation frame, and cleans up after the transition ends.
+ *
+ * @param {string} transitionName - CSS class prefix for the enter transition
+ * @returns {this}
+ * @example
+ * Div({ class: 'modal' }).nd.transitionIn('fade');
+ * // On mount: adds 'fade-enter-from', then swaps to 'fade-enter-to'
+ */
+NDElement.prototype.transitionIn = function(transitionName) {
+    const startClass = transitionName + '-enter-from';
+    const endClass = transitionName + '-enter-to';
+
+    const el = this.$element;
+
+    el.classes.add(startClass);
+
+    this.mounted(() => {
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+                el.classes.remove(startClass);
+                el.classes.add(endClass);
+
+                waitForVisualEnd(el).then(() => {
+                    el.classes.remove(endClass);
+                });
+            });
+        });
+    });
+    return this;
+};
+
+/**
+ * Applies both enter and exit transitions to the element.
+ * Shorthand for calling .transitionIn(name) and .transitionOut(name).
+ *
+ * @param {string} transitionName - CSS class prefix for both enter and exit transitions
+ * @returns {this}
+ * @example
+ * Div({}).nd.transition('slide');
+ * // On mount: enter transition; on unmount: exit transition
+ */
+NDElement.prototype.transition = function (transitionName) {
+    this.transitionIn(transitionName);
+    this.transitionOut(transitionName);
+    return this;
+};
+
+/**
+ * Immediately applies a CSS animation class to the element.
+ * Removes the class automatically once the animation ends.
+ *
+ * @param {string} animationName - CSS animation class name to add
+ * @returns {this}
+ * @example
+ * Button('Click me').nd.animate('shake');
+ * // Adds 'shake' class, removes it when animationend fires
+ */
+NDElement.prototype.animate = function(animationName) {
+    const el = this.$element;
+    el.classes.add(animationName);
+
+    waitForVisualEnd(el).then(() => {
+        el.classes.remove(animationName);
+    });
+
+    return this;
+};

package/src/core/wrappers/template-cloner/NodeCloner.js

@@ -0,0 +1,209 @@
+import {ElementCreator} from '../ElementCreator';
+import {createTextNode} from '../HtmlElementWrapper';
+import {NDElement} from '../NDElement';
+
+/**
+ * Stores deferred attribute, class, style, and event bindings for a cloneable element.
+ * Used internally by TemplateCloner to apply per-instance data to cloned DOM nodes.
+ * Not intended for direct use in application code.
+ *
+ * @internal
+ * @constructor
+ * @param {HTMLElement} $element - The template element to clone
+ */
+export default function NodeCloner($element) {
+    this.$element = $element;
+    this.$classes = null;
+    this.$styles = null;
+    this.$attrs = null;
+    this.$ndMethods = null;
+}
+
+
+/**
+ * Attaches a template binding to the element by hydrating it with the specified method.
+ *
+ * @param {string} methodName - Name of the hydration method to call
+ * @param {BindingHydrator} bindingHydrator - Template binding with $hydrate method
+ * @returns {HTMLElement} The underlying HTML element
+ * @example
+ * const onClick = $binder.attach((event, data) => console.log(data));
+ * element.nd.attach('onClick', onClick);
+ */
+NDElement.prototype.attach = function(methodName, bindingHydrator) {
+    if(typeof bindingHydrator === 'function') {
+        const element = this.$element;
+        element.nodeCloner = element.nodeCloner || new NodeCloner(element);
+        element.nodeCloner.attach(methodName, bindingHydrator);
+        return element;
+    }
+    bindingHydrator.$hydrate(this.$element, methodName);
+    return this.$element;
+};
+
+NodeCloner.prototype.__$isNodeCloner = true;
+
+const buildProperties = (cache, properties, data) => {
+    for(const key in properties) {
+        cache[key] = properties[key].apply(null, data);
+    }
+    return cache;
+};
+
+/**
+ * Pre-compiles all registered bindings into a sequence of optimised steps.
+ * Called once before the first clone operation. Subsequent calls are no-ops.
+ *
+ * @internal
+ */
+NodeCloner.prototype.resolve = function() {
+    if(this.$content) {
+        return;
+    }
+    const steps = [];
+    if(this.$ndMethods) {
+        const methods = Object.keys(this.$ndMethods);
+        if(methods.length === 1) {
+            const methodName = methods[0];
+            const callback = this.$ndMethods[methodName];
+            steps.push((clonedNode, data) => {
+                clonedNode.nd[methodName](callback.bind(clonedNode, ...data));
+            });
+        } else {
+            steps.push((clonedNode, data) => {
+                const nd = clonedNode.nd;
+                for(const methodName in this.$ndMethods) {
+                    nd[methodName](this.$ndMethods[methodName].bind(clonedNode, ...data));
+                }
+            });
+        }
+    }
+    if(this.$classes) {
+        const cache = {};
+        const keys = Object.keys(this.$classes);
+
+        if(keys.length === 1) {
+            const key = keys[0];
+            const callback = this.$classes[key];
+            steps.push((clonedNode, data) => {
+                cache[key] = callback.apply(null, data);
+                ElementCreator.processClassAttribute(clonedNode, cache);
+            });
+        } else {
+            steps.push((clonedNode, data) => {
+                ElementCreator.processClassAttribute(clonedNode, buildProperties(cache, this.$classes, data));
+            });
+        }
+    }
+    if(this.$styles) {
+        const cache = {};
+        const keys = Object.keys(this.$styles);
+
+        if(keys.length === 1) {
+            const key = keys[0];
+            const callback = this.$styles[key];
+            steps.push((clonedNode, data) => {
+                cache[key] = callback.apply(null, data);
+                ElementCreator.processStyleAttribute(clonedNode, cache);
+            });
+        } else {
+            steps.push((clonedNode, data) => {
+                ElementCreator.processStyleAttribute(clonedNode, buildProperties(cache, this.$styles, data));
+            });
+        }
+    }
+    if(this.$attrs) {
+        const cache = {};
+        const keys = Object.keys(this.$attrs);
+
+        if(keys.length === 1) {
+            const key = keys[0];
+            const callback = this.$attrs[key];
+            steps.push((clonedNode, data) => {
+                cache[key] = callback.apply(null, data);
+                ElementCreator.processAttributes(clonedNode, cache);
+            });
+        } else {
+            steps.push((clonedNode, data) => {
+                ElementCreator.processAttributes(clonedNode, buildProperties(cache, this.$attrs, data));
+            });
+        }
+    }
+
+    const stepsCount = steps.length;
+    const $element = this.$element;
+
+    this.cloneNode = (data) => {
+        const clonedNode = $element.cloneNode(false);
+        for(let i = 0; i < stepsCount; i++) {
+            steps[i](clonedNode, data);
+        }
+        return clonedNode;
+    };
+};
+
+/**
+ * Clones the template element and applies all compiled binding steps with the given data.
+ *
+ * @internal
+ * @param {Array} data - Data array passed to each binding callback
+ * @returns {HTMLElement} The cloned and hydrated element
+ */
+NodeCloner.prototype.cloneNode = function(data) {
+    return this.$element.cloneNode(false);
+};
+
+/**
+ * Registers an NDElement method binding (e.g. onClick, onInput) to be applied on each clone.
+ *
+ * @internal
+ * @param {string} methodName - Name of the NDElement method to call (e.g. 'onClick')
+ * @param {Function} callback - Callback function to pass to the method
+ * @returns {NodeCloner} this
+ */
+NodeCloner.prototype.attach = function(methodName, callback) {
+    this.$ndMethods = this.$ndMethods || {};
+    this.$ndMethods[methodName] = callback;
+    return this;
+};
+
+/**
+ * Registers a reactive text content binding for the element.
+ *
+ * @internal
+ * @param {Function} valueorProperty - Function receiving data and returning the text content
+ * @returns {NodeCloner} this
+ */
+NodeCloner.prototype.text = function(valueorProperty) {
+    this.$content = valueorProperty;
+    if(typeof valueorProperty === 'function') {
+        this.cloneNode = (data) => createTextNode(valueorProperty.apply(null, data));
+        return this;
+    }
+    this.cloneNode = (data) => createTextNode(data[0][valueorProperty]);
+    return this;
+};
+
+/**
+ * Registers an attribute binding to be applied on each clone.
+ *
+ * @internal
+ * @param {string} attrName - Attribute name
+ * @param {{property: string, value: *}} value - Function receiving data and returning the attribute value
+ * @returns {NodeCloner} this
+ */
+NodeCloner.prototype.attr = function(attrName, value) {
+    if(attrName === 'class') {
+        this.$classes = this.$classes || {};
+        this.$classes[value.property] = value.value;
+        return this;
+    }
+    if(attrName === 'style') {
+        this.$styles = this.$styles || {};
+        this.$styles[value.property] = value.value;
+        return this;
+    }
+    this.$attrs = this.$attrs || {};
+    this.$attrs[attrName] = value.value;
+    return this;
+};

package/src/core/wrappers/template-cloner/TemplateCloner.js

@@ -0,0 +1,192 @@
+import TemplateBinding from '../TemplateBinding';
+import { $hydrateFn} from './utils';
+import NodeCloner from './NodeCloner';
+
+/**
+ * Creates a high-performance template cloner for repeated rendering of the same structure.
+ * On the first call, builds the template by calling $fn with a binder object.
+ * On subsequent calls, clones the compiled template and hydrates it with new data.
+ * Used internally by ForEachArray and other list renderers.
+ *
+ * @constructor
+ * @param {(binder: TemplateCloner) => HTMLElement} $fn - Function that builds the template using binder methods
+ * @example
+ * const cloner = new TemplateCloner((t) =>
+ *   Div({},
+ *     Span(t.text((item) => item.name)),
+ *     Button({}, 'Delete').nd.onClick(t.event((item) => () => list.removeItem(item)))
+ *   )
+ * );
+ * cloner.clone([item]); // returns a hydrated clone
+ */
+export function TemplateCloner($fn) {
+    let $node = null;
+
+    const assignClonerToNode = ($node) => {
+        const childNodes = $node.childNodes;
+        let containDynamicNode = !!$node.nodeCloner;
+        const childNodesLength = childNodes.length;
+        for(let i = 0; i < childNodesLength; i++) {
+            const child = childNodes[i];
+            if(child.nodeCloner) {
+                containDynamicNode = true;
+            }
+            const localContainDynamicNode = assignClonerToNode(child);
+            if(localContainDynamicNode) {
+                containDynamicNode = true;
+            }
+        }
+
+        if(!containDynamicNode) {
+            $node.dynamicCloneNode = $node.cloneNode.bind($node, true);
+        } else {
+            if($node.nodeCloner) {
+                $node.nodeCloner.resolve();
+                $node.dynamicCloneNode = (data) => {
+                    const clonedNode = $node.nodeCloner.cloneNode(data);
+                    for(let i = 0; i < childNodesLength; i++) {
+                        clonedNode.appendChild(childNodes[i].dynamicCloneNode(data));
+                    }
+                    return clonedNode;
+                };
+            } else {
+                $node.dynamicCloneNode = (data) => {
+                    const clonedNode = $node.cloneNode();
+                    for(let i = 0; i < childNodesLength; i++) {
+                        clonedNode.appendChild(childNodes[i].dynamicCloneNode(data));
+                    }
+                    return clonedNode;
+                };
+            }
+        }
+
+        return containDynamicNode;
+    };
+
+
+    /**
+     * Clones the compiled template and hydrates it with the given data.
+     * On the first call, also compiles the template (builds and optimizes binding steps).
+     *
+     * @param {Array} data - Data array passed to all binding callbacks
+     * @returns {HTMLElement} Cloned and hydrated DOM node
+     */
+    this.clone = (data) => {
+        const binder = createTemplateCloner(this);
+        $node = $fn(binder);
+        if(!$node.nodeCloner) {
+            $node.nodeCloner = new NodeCloner($node);
+        }
+        assignClonerToNode($node);
+        this.clone = $node.dynamicCloneNode;
+        return $node.dynamicCloneNode(data);
+    };
+
+
+    const createBinding = (hydrateFunction, targetType) => {
+        return new TemplateBinding((element, property) => {
+            $hydrateFn(hydrateFunction, targetType, element, property);
+        });
+    };
+
+    /**
+     * Creates a style binding — the result of fn(data) is applied as inline styles.
+     *
+     * @param {((...data: any[]) => Record<string, string>)} fn - Function returning a style object
+     * @returns {TemplateBinding}
+     */
+    this.style = (fn) => {
+        return createBinding(fn, 'style');
+    };
+
+    /**
+     * Creates a class binding — the result of fn(data) is applied as a class map.
+     *
+     * @param {((...data: any[]) => Record<string, boolean>)} fn - Function returning a class map
+     * @returns {TemplateBinding}
+     */
+    this.class = (fn) => {
+        return createBinding(fn, 'class');
+    };
+
+    this.property = (propertyName) => {
+        return this.value(propertyName);
+    };
+
+    /**
+     * Creates a text/value binding — the result is set as text content or input value.
+     * Alias: .text()
+     *
+     * @param {string|(((...data: any[]) => string))} callbackOrProperty - Property name (string) or callback returning the value
+     * @returns {TemplateBinding}
+     */
+    this.value = (callbackOrProperty) => {
+        return createBinding(callbackOrProperty, 'value');
+    };
+
+    /**
+     * Alias for .value() — creates a text content binding.
+     *
+     * @param {string|(((...data: any[]) => string))} callbackOrProperty
+     * @returns {TemplateBinding}
+     */
+    this.text = this.value;
+
+    /**
+     * Creates an attribute binding — the result of fn(data) is set as an attribute value.
+     *
+     * @param {((...data: any[]) => string)} fn - Function returning the attribute value
+     * @returns {TemplateBinding}
+     */
+    this.attr = (fn) => {
+        return createBinding(fn, 'attributes');
+    };
+
+    /**
+     * Creates an event binding — fn(data) returns the event handler to attach.
+     *
+     * @param {((...data: any[]) => EventListener)} fn - Function returning the event callback
+     * @returns {TemplateBinding}
+     */
+    this.attach = (fn) => {
+        return createBinding(fn, 'attach');
+    };
+
+    this.callback = this.attach;
+}
+
+
+const createTemplateCloner = ($binder) => {
+    return new Proxy($binder, {
+        get(target, prop) {
+            if(prop in target) {
+                return target[prop];
+            }
+            if (typeof prop === 'symbol') return target[prop];
+            return target.value(prop);
+        },
+    });
+};
+
+export function useCache(fn) {
+    let $cache = null;
+
+    let wrapper = (args) => {
+        $cache = new TemplateCloner(fn);
+
+        const node = $cache.clone(args);
+        wrapper = $cache.clone;
+        return node;
+    };
+
+    if(fn.length < 2) {
+        return (...args) => {
+            return wrapper(args);
+        };
+    }
+    return (_, __, ...args) => {
+        return wrapper([_, __, ...args]);
+    };
+}
+
+export const template = useCache;