native-document 1.0.15 → 1.0.16-8.1

package/src/core/wrappers/NdPrototype.js

@@ -0,0 +1,233 @@
+import { NDElement } from './NDElement';
+import {EVENTS, EVENTS_WITH_PREVENT, EVENTS_WITH_STOP} from '../utils/events';
+
+const property = {
+    configurable: true,
+    get() {
+        return new NDElement(this);
+    },
+};
+
+Object.defineProperty(HTMLElement.prototype, 'nd', property);
+
+Object.defineProperty(DocumentFragment.prototype, 'nd', property);
+
+Object.defineProperty(NDElement.prototype, 'nd', {
+    configurable: true,
+    get: function() {
+        return this;
+    },
+});
+
+
+
+// ----------------------------------------------------------------
+// Events helpers
+// ----------------------------------------------------------------
+EVENTS.forEach(eventSourceName => {
+    const eventName = eventSourceName.toLowerCase();
+    NDElement.prototype['on'+eventSourceName] = function(callback = null, options = {}) {
+        this.$element.addEventListener(eventName, callback, {
+            signal: this.$getSignal(),
+            ...options,
+        });
+        return this;
+    };
+});
+
+EVENTS_WITH_STOP.forEach(eventSourceName => {
+    const eventName = eventSourceName.toLowerCase();
+    NDElement.prototype['onStop'+eventSourceName] = function(callback = null, options = {}) {
+        _stop(this.$element, eventName, callback, {
+            signal: this.$getSignal(),
+            ...options,
+        });
+        return this;
+    };
+    NDElement.prototype['onPreventStop'+eventSourceName] = function(callback = null, options = {}) {
+        _preventStop(this.$element, eventName, callback, {
+            signal: this.$getSignal(),
+            ...options,
+        });
+        return this;
+    };
+});
+
+EVENTS_WITH_PREVENT.forEach(eventSourceName => {
+    const eventName = eventSourceName.toLowerCase();
+    NDElement.prototype['onPrevent'+eventSourceName] = function(callback = null, options = {}) {
+        _prevent(this.$element, eventName, callback, {
+            signal: this.$getSignal(),
+            ...options,
+        });
+        return this;
+    };
+});
+
+/**
+ * Retrieves or creates an AbortController signal tied to this element's lifecycle.
+ * The signal is automatically aborted when the element is removed via .nd.remove().
+ * Used internally by all event listeners (onClick, onInput, etc.) to auto-cleanup on unmount.
+ *
+ * @internal
+ * @returns {AbortSignal} The signal for this element's AbortController
+ */
+NDElement.prototype.$getSignal = function() {
+    if(!this.$element.__$controller) {
+        this.$element.__$controller = new AbortController();
+    }
+    return this.$element.__$controller.signal;
+};
+
+
+/**
+ * Adds a native event listener to the underlying HTMLElement.
+ * The listener is automatically removed when the element is unmounted (via AbortSignal).
+ *
+ * @param {string} name - Event name (case-insensitive, e.g. 'click', 'input')
+ * @param {EventListener} callback - Handler to call when the event fires
+ * @param {boolean|AddEventListenerOptions} [options] - Listener options merged with the element's AbortSignal
+ * @returns {this}
+ */
+NDElement.prototype.on = function(name, callback, options) {
+    this.$element.addEventListener(name.toLowerCase(), callback, {
+        signal: this.$getSignal(),
+        ...options,
+    });
+    return this;
+};
+
+/**
+ * Removes a previously registered event listener from the underlying HTMLElement.
+ *
+ * @param {string} name - Event name (case-insensitive)
+ * @param {EventListener} callback - The exact handler reference to remove
+ * @returns {this}
+ */
+NDElement.prototype.off = function(name, callback) {
+    this.$element.removeEventListener(name.toLowerCase(), callback);
+    return this;
+};
+
+/**
+ * Adds a one-time event listener that removes itself after the first call.
+ * Uses the element's AbortSignal for lifecycle-safe cleanup.
+ *
+ * @param {string} name - Event name (case-insensitive)
+ * @param {EventListener} callback - Handler called once when the event fires
+ * @returns {this}
+ */
+NDElement.prototype.once = function(name, callback) {
+    this.$element.addEventListener(name.toLowerCase(), callback, {
+        signal: this.$getSignal(),
+        once: true,
+    });
+    return this;
+};
+
+/**
+ * Dispatches a custom event on the underlying HTMLElement.
+ * The event bubbles and is cancelable by default.
+ *
+ * @param {string} name - Custom event name
+ * @param {*} [detail=null] - Data passed in event.detail
+ * @returns {this}
+ * @example
+ * Button('Save').nd.emit('saved', { id: 42 });
+ * // Triggers: element.addEventListener('saved', e => console.log(e.detail.id))
+ */
+NDElement.prototype.emit = function(name, detail = null) {
+    const event = new CustomEvent(name, {
+        detail,
+        bubbles:    true,
+        cancelable: true,
+    });
+    this.$element.dispatchEvent(event);
+    return this;
+};
+
+const _prevent = function(element, eventName, callback, options) {
+    const handler = (event) => {
+        event.preventDefault();
+        callback && callback.call(element, event);
+    };
+    element.addEventListener(eventName, handler, options);
+    return this;
+};
+
+const _stop = function(element, eventName, callback, options) {
+    const handler = (event) => {
+        event.stopPropagation();
+        callback && callback.call(element, event);
+    };
+    element.addEventListener(eventName, handler, options);
+    return this;
+};
+
+const _preventStop = function(element, eventName, callback, options) {
+    const handler = (event) => {
+        event.stopPropagation();
+        event.preventDefault();
+        callback && callback.call(element, event);
+    };
+    element.addEventListener(eventName, handler, options);
+    return this;
+};
+
+
+
+// ----------------------------------------------------------------
+// Class attributes binder
+// ----------------------------------------------------------------
+const classListMethods = {
+    getClasses() {
+        return this.$element.className?.split(' ').filter(Boolean);
+    },
+    add(value) {
+        const classes = this.getClasses();
+        if(classes.indexOf(value) >= 0) {
+            return;
+        }
+        classes.push(value);
+        this.$element.className = classes.join(' ');
+    },
+    remove(value) {
+        const classes = this.getClasses();
+        const index = classes.indexOf(value);
+        if(index < 0) {
+            return;
+        }
+        classes.splice(index, 1);
+        this.$element.className = classes.join(' ');
+    },
+    toggle(value, force = undefined) {
+        const classes = this.getClasses();
+        const index = classes.indexOf(value);
+        if(index >= 0) {
+            if(force === true) {
+                return;
+            }
+            classes.splice(index, 1);
+        }
+        else {
+            if(force === false) {
+                return;
+            }
+            classes.push(value);
+        }
+        this.$element.className = classes.join(' ');
+    },
+    contains(value) {
+        return this.getClasses().indexOf(value) >= 0;
+    },
+};
+
+Object.defineProperty(HTMLElement.prototype, 'classes', {
+    configurable: true,
+    get() {
+        return {
+            $element: this,
+            ...classListMethods,
+        };
+    },
+});

package/src/core/wrappers/SingletonView.js

@@ -0,0 +1,99 @@
+import Anchor from '../elements/anchor/anchor';
+
+/**
+ * Creates a singleton view — a component that is instantiated only once,
+ * then reused across multiple renders. Useful for performance-critical components
+ * that are frequently shown/hidden or repeated in lists.
+ *
+ * @constructor
+ * @param {(instance: SingletonView) => Node} $viewCreator - Function that builds the view once and returns the root node.
+ * Receives the SingletonView instance so it can call .createSection().
+ * @example
+ * const Card = useSingleton((view) => {
+ *   const nameSection = view.createSection('name');
+ *   return Div({ class: 'card' }, nameSection);
+ * });
+ * Card([{ name: 'John' }]); // Renders once, reused on subsequent calls
+ */
+export function SingletonView($viewCreator) {
+    let $cacheNode = null;
+    let $components = null;
+
+
+    /**
+     * Renders the singleton view with the given data.
+     * On the first call, create the view by calling $viewCreator.
+     * On later calls, updates registered sections via their update functions.
+     *
+     * @param {Array} data - Array where data[0] is an object mapping section names to new content
+     * @returns {Node} The cached root node
+     */
+    this.render = (data) => {
+        if(!$cacheNode) {
+            $cacheNode = $viewCreator(this);
+        }
+        if(!$components) return $cacheNode;
+
+        const updates = data[0];
+        if(updates && typeof updates === 'object') {
+            for(const key in updates) {
+                if($components[key]) {
+                    $components[key](updates[key]);
+                }
+            }
+        }
+        return $cacheNode;
+    };
+
+
+    /**
+     * Creates a named anchor section inside the singleton view.
+     * The section can be updated later by passing new content through .render().
+     *
+     * @param {string} name - Unique section name used as the update key
+     * @param {((content: *) => Node)?} [fn] - Optional transform function applied to new content before inserting
+     * @returns {AnchorDocumentFragment} Anchor fragment to place inside the view's DOM
+     * @example
+     * const nameSection = view.createSection('name');
+     * // Later: Card([{ name: 'Jane' }]); // replaces content in nameSection
+     */
+    this.createSection = (name, fn) => {
+        $components = $components || {};
+        const anchor = Anchor('Component ' + name);
+
+        $components[name] = function(content) {
+            anchor.removeChildren();
+            if(!fn) {
+                anchor.append(content);
+                return;
+            }
+            anchor.appendChild(fn(content));
+        };
+        return anchor;
+    };
+}
+
+
+/**
+ * Creates a memoized factory that returns a SingletonView instance.
+ * The singleton is created on the first call and reused for all subsequent calls.
+ *
+ * @param {(instance: SingletonView) => Node} fn - View creator function passed to SingletonView
+ * @returns {(...args: any[]) => Node} Function that renders the singleton with the given data
+ * @example
+ * const Card = useSingleton((view) => {
+ *   const title = view.createSection('title');
+ *   return Div({}, title);
+ * });
+ * Card([{ title: 'Hello' }]);
+ */
+export function useSingleton(fn) {
+    let $cache = null;
+
+    return function(...args) {
+        if(!$cache) {
+            $cache = new SingletonView(fn);
+        }
+        return $cache.render(args);
+    };
+}

package/src/core/wrappers/SvgElementWrapper.js

@@ -0,0 +1,15 @@
+import {createHtmlElement} from './HtmlElementWrapper';
+
+export default function SvgElementWrapper(name) {
+    let node = null;
+
+    let createElement = (attr, children) => {
+        node = document.createElementNS('http://www.w3.org/2000/svg', name);
+        createElement = (attr, children) => {
+            return createHtmlElement(node.cloneNode(), attr, children);
+        };
+        return createHtmlElement(node.cloneNode(), attr, children);
+    };
+
+    return (attr, children) => createElement(attr, children);
+}

package/src/core/wrappers/TemplateBinding.js

@@ -0,0 +1,7 @@
+
+
+export default function TemplateBinding(hydrate) {
+    this.$hydrate = hydrate;
+}
+
+TemplateBinding.prototype.__$isTemplateBinding = true;

package/src/core/wrappers/constants.js

@@ -0,0 +1,66 @@
+
+export const BOOLEAN_ATTRIBUTES = new Set([
+    'checked',
+    'selected',
+    'disabled',
+    'readonly',
+    'required',
+    'autofocus',
+    'multiple',
+    'autocomplete',
+    'hidden',
+    'contenteditable',
+    'spellcheck',
+    'translate',
+    'draggable',
+    'async',
+    'defer',
+    'autoplay',
+    'controls',
+    'loop',
+    'muted',
+    'download',
+    'reversed',
+    'open',
+    'default',
+    'formnovalidate',
+    'novalidate',
+    'scoped',
+    'itemscope',
+    'allowfullscreen',
+    'allowpaymentrequest',
+    'playsinline',
+]);
+
+export const BOOL_ATTRIBUTES_NAME = {
+    'allowfullscreen': 'allowFullscreen',
+    'allowpaymentrequest': 'allowPaymentRequest',
+    'async': 'async',
+    'autocomplete': 'autocomplete',
+    'autofocus': 'autofocus',
+    'autoplay': 'autoplay',
+    'checked': 'checked',
+    'controls': 'controls',
+    'default': 'default',
+    'defer': 'defer',
+    'disabled': 'disabled',
+    'download': 'download',
+    'draggable': 'draggable',
+    'formnovalidate': 'formNoValidate',
+    'contenteditable': 'contentEditable',
+    'hidden': 'hidden',
+    'itemscope': 'itemScope',
+    'loop': 'loop',
+    'multiple': 'multiple',
+    'muted': 'muted',
+    'novalidate': 'noValidate',
+    'open': 'open',
+    'playsinline': 'playsInline',
+    'readonly': 'readOnly',
+    'required': 'required',
+    'reversed': 'reversed',
+    'scoped': 'scoped',
+    'selected': 'selected',
+    'spellcheck': 'spellcheck',
+    'translate': 'translate',
+};

package/src/core/wrappers/prototypes/attributes-extensions.js

@@ -0,0 +1,24 @@
+import {
+    bindAttributeWithObservable,
+    bindBooleanAttribute,
+} from '../AttributesWrapper';
+import ObservableItem from '../../data/ObservableItem';
+import TemplateBinding from '../TemplateBinding';
+import {BOOLEAN_ATTRIBUTES} from '../constants';
+import ObservableChecker from '../../data/ObservableChecker';
+
+
+ObservableItem.prototype.handleNdAttribute = function(element, attributeName) {
+    if(BOOLEAN_ATTRIBUTES.has(attributeName)) {
+        bindBooleanAttribute(element, attributeName, this);
+        return;
+    }
+
+    bindAttributeWithObservable(element, attributeName, this);
+};
+
+ObservableChecker.prototype.handleNdAttribute = ObservableItem.prototype.handleNdAttribute;
+
+TemplateBinding.prototype.handleNdAttribute = function(element, attributeName) {
+    this.$hydrate(element, attributeName);
+};

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

@@ -0,0 +1,149 @@
+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';
+import Validator from '../../utils/validator';
+
+
+NDElement.$getChild = ElementCreator.getChild;
+
+Object.prototype.toNdElement = function () {
+    return ElementCreator.createStaticTextNode(null, this.toString());
+};
+
+/**
+ * Converts a string to a reactive text node.
+ *
+ * @returns {Text} Static text node containing the string value
+ */
+String.prototype.toNdElement = function () {
+    return ElementCreator.createStaticTextNode(null, this);
+};
+
+/**
+ * Converts a number to a static text node.
+ *
+ * @returns {Text} Static text node containing the number as a string
+ */
+Number.prototype.toNdElement = function () {
+    return ElementCreator.createStaticTextNode(null, this.toString());
+};
+
+/**
+ * Returns the element itself (identity for DOM compatibility).
+ *
+ * @returns {Element} this
+ */
+Element.prototype.toNdElement = function () {
+    return this;
+};
+
+/**
+ * Returns the text node itself (identity for DOM compatibility).
+ *
+ * @returns {Text} this
+ */
+Text.prototype.toNdElement = function () {
+    return this;
+};
+
+/**
+ * Returns the comment node itself (identity for DOM compatibility).
+ *
+ * @returns {Comment} this
+ */
+Comment.prototype.toNdElement = function () {
+    return this;
+};
+
+/**
+ * Returns the document itself (identity for DOM compatibility).
+ *
+ * @returns {Document} this
+ */
+Document.prototype.toNdElement = function () {
+    return this;
+};
+
+/**
+ * Returns the document fragment itself (identity for DOM compatibility).
+ *
+ * @returns {DocumentFragment} this
+ */
+DocumentFragment.prototype.toNdElement = function () {
+    return this;
+};
+
+/**
+ * Converts the ObservableItem to a reactive text node that updates automatically when the value changes.
+ *
+ * @returns {Text} Reactive text node bound to this observable
+ */
+ObservableItem.prototype.toNdElement = function () {
+    return ElementCreator.createObservableNode(null, this);
+};
+
+ObservableChecker.prototype.toNdElement = ObservableItem.prototype.toNdElement;
+
+/**
+ * Converts the NDElement to its underlying HTMLElement (or ghost DOM fragment if ghostDom was used).
+ *
+ * @returns {HTMLElement|DocumentFragment} The underlying DOM node
+ */
+NDElement.prototype.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 elements.
+ * Each item is processed through ElementCreator.getChild().
+ *
+ * @returns {DocumentFragment} Fragment containing all array children
+ */
+Array.prototype.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} The DOM node returned by the function
+ */
+Function.prototype.toNdElement = function () {
+    const callback = this;
+    if(process.env.NODE_ENV === 'development') {
+        PluginsManager.emit('BeforeProcessComponent', callback);
+    }
+    const child = callback();
+    if(Validator.isElement(child)) {
+        return child;
+    }
+    return child.toNdElement();
+};
+
+/**
+ * Converts the TemplateBinding to a hydratable DOM node for use in TemplateCloner.
+ *
+ * @returns {Node} Hydratable node
+ */
+TemplateBinding.prototype.toNdElement = function () {
+    return ElementCreator.createHydratableNode(null, this);
+};