native-document 1.0.15 → 1.0.16-8.1

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;

package/src/core/wrappers/template-cloner/attributes-hydrator.js

@@ -0,0 +1,142 @@
+import {ElementCreator} from '../ElementCreator';
+
+/**
+ * Hydrates a cloned node with all attribute, class, style, and attachment bindings
+ * from a compiled BindingData object. Full update path — applies both static attributes
+ * and dynamic class/style maps.
+ *
+ * @internal
+ * @param {HTMLElement} node - Cloned DOM node to hydrate
+ * @param {BindingData} bindDingData - Pre-compiled binding metadata
+ * @param {Array} data - Data array passed to each binding callback
+ * @returns {true}
+ */
+export const hydrateFull = (node, bindDingData, data) => {
+    const cacheAttributes = bindDingData._cache;
+
+    for(let i = 0, length = bindDingData._flatAttributesLength; i < length; i++) {
+        const attr = bindDingData._flatAttributes[i];
+        cacheAttributes[attr.name] = attr.value.apply(null, data);
+    }
+
+    for(let i = 0, length = bindDingData._flatDynamiqueLength; i < length; i++) {
+        const dyn = bindDingData._flatDynamique[i];
+        cacheAttributes[dyn.name][dyn.key] = dyn.value.apply(null, data);
+    }
+
+    ElementCreator.processAttributesDirect(node, cacheAttributes);
+    return true;
+};
+
+/**
+ * Hydrates only the dynamic class and style bindings on a cloned node.
+ * Used when there are no static attribute bindings.
+ *
+ * @internal
+ * @param {HTMLElement} node - Cloned DOM node to hydrate
+ * @param {BindingData} bindDingData - Pre-compiled binding metadata
+ * @param {Array} data - Data array passed to each binding callback
+ * @returns {true}
+ */
+export const hydrateDynamic = (node, bindDingData, data) => {
+    const cacheAttributes = bindDingData._cache;
+
+    for(let i = 0, length = bindDingData._flatDynamiqueLength; i < length; i++) {
+        const dyn = bindDingData._flatDynamique[i];
+        cacheAttributes[dyn.name][dyn.key] = dyn.value.apply(null, data);
+    }
+
+    ElementCreator.processClassAttribute(node, cacheAttributes.class);
+    ElementCreator.processStyleAttribute(node, cacheAttributes.style);
+    return true;
+};
+
+/**
+ * Hydrates only the dynamic class bindings on a cloned node.
+ *
+ * @internal
+ * @param {HTMLElement} node - Cloned DOM node to hydrate
+ * @param {BindingData} bindDingData - Pre-compiled binding metadata
+ * @param {Array} data - Data array passed to each binding callback
+ * @returns {true}
+ */
+export const hydrateClassAttribute = (node, bindDingData, data) => {
+    const classAttributes = bindDingData._cache.class;
+
+    for(let i = 0, length = bindDingData._flatDynamiqueLength; i < length; i++) {
+        const dyn = bindDingData._flatDynamique[i];
+        classAttributes[dyn.key] = dyn.value.apply(null, data);
+    }
+
+    ElementCreator.processClassAttribute(node, classAttributes);
+    return true;
+};
+
+/**
+ * Hydrates only the dynamic style bindings on a cloned node.
+ *
+ * @internal
+ * @param {HTMLElement} node - Cloned DOM node to hydrate
+ * @param {BindingData} bindDingData - Pre-compiled binding metadata
+ * @param {Array} data - Data array passed to each binding callback
+ * @returns {true}
+ */
+export const hydrateStyleAttribute = (node, bindDingData, data) => {
+    const styleAttributes = bindDingData._cache;
+
+    for(let i = 0, length = bindDingData._flatDynamiqueLength; i < length; i++) {
+        const dyn = bindDingData._flatDynamique[i];
+        styleAttributes[dyn.key] = dyn.value.apply(null, data);
+    }
+
+    ElementCreator.processStyleAttribute(node, styleAttributes);
+    return true;
+};
+
+/**
+ * Hydrates only the static attribute bindings on a cloned node.
+ *
+ * @internal
+ * @param {HTMLElement} node - Cloned DOM node to hydrate
+ * @param {BindingData} bindDingData - Pre-compiled binding metadata
+ * @param {Array} data - Data array passed to each binding callback
+ * @returns {true}
+ */
+export const hydrateAttributes = (node, bindDingData, data) => {
+    const cacheAttributes = bindDingData._cache;
+
+    for(let i = 0, length = bindDingData._flatAttributesLength; i < length; i++) {
+        const attr = bindDingData._flatAttributes[i];
+        cacheAttributes[attr.name] = attr.value.apply(null, data);
+    }
+
+    ElementCreator.processAttributesDirect(node, cacheAttributes);
+    return true;
+};
+
+/**
+ * Selects and returns the most efficient hydration function for the given BindingData.
+ * Called once during template compilation to assign the optimal update path.
+ *
+ * @internal
+ * @param {BindingData} bindDingData - Pre-compiled binding metadata
+ * @returns {Function} One of: hydrateFull, hydrateDynamic, hydrateClassAttribute, hydrateStyleAttribute, hydrateAttributes, or noUpdate
+ */
+export const getHydrator = (bindDingData) => {
+    if(!bindDingData._cache) {
+        return noUpdate;
+    }
+    if(bindDingData._flatAttributesLength && bindDingData._flatDynamiqueLength) {
+        return hydrateFull;
+    }
+    if(bindDingData._flatAttributesLength) {
+        return hydrateAttributes;
+    }
+    if(bindDingData._hasClassAttribute && bindDingData._hasStyleAttribute) {
+        return hydrateDynamic;
+    }
+    if(bindDingData._hasClassAttribute) {
+        return hydrateClassAttribute;
+    }
+    return hydrateStyleAttribute;
+};