native-document 1.0.93 → 1.0.95

package/src/core/elements/img.js

@@ -2,18 +2,30 @@ import HtmlElementWrapper from "../wrappers/HtmlElementWrapper"
 import Validator from "../utils/validator";
 import NativeDocumentError from "../errors/NativeDocumentError";
 
+/**
+ * Creates an `<img>` element.
+ * @type {function(ImgAttributes=): HTMLImageElement}
+ */
 export const BaseImage = HtmlElementWrapper('img');
+
+/**
+ * Creates an `<img>` element.
+ * @param {Observable<string>|string} src
+ * @param {Omit<ImgAttributes, 'src'>} [attributes]
+ * @returns {HTMLImageElement}
+ */
 export const Img = function(src, attributes) {
     return BaseImage({ src, ...attributes });
 };
 
 /**
- *
- * @param {string} src
- * @param {string|null} defaultImage
- * @param {Object} attributes
- * @param {?Function} callback
- * @returns {Image}
+ * Creates an `<img>` that loads asynchronously, showing a placeholder until the image is ready.
+ * Supports reactive `src` — automatically updates when the observable changes.
+ * @param {Observable<string>|string} src                                        - Final image URL
+ * @param {string|null}               defaultImage                               - Placeholder shown while loading
+ * @param {Omit<ImgAttributes, 'src'>} attributes
+ * @param {(error: NativeDocumentError|null, img: HTMLImageElement) => void} [callback]
+ * @returns {HTMLImageElement}
  */
 export const AsyncImg = function(src, defaultImage, attributes, callback) {
     const defaultSrc = Validator.isObservable(src) ? src.val() : src;
@@ -37,10 +49,10 @@ export const AsyncImg = function(src, defaultImage, attributes, callback) {
 };
 
 /**
- *
- * @param {string} src
- * @param {Object} attributes
- * @returns {Image}
+ * Creates an `<img loading="lazy">` element.
+ * @param {Observable<string>|string}          src
+ * @param {Omit<ImgAttributes, 'src'|'loading'>} [attributes]
+ * @returns {HTMLImageElement}
  */
 export const LazyImg = function(src, attributes) {
     return Img(src, { ...attributes, loading: 'lazy' });

package/src/core/elements/index.js

@@ -16,6 +16,11 @@ export * from './medias';
 export * from './meta-data';
 export * from './table';
 
+/**
+ * Creates an empty `DocumentFragment` wrapper.
+ * Useful for grouping elements without adding a DOM node.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): DocumentFragment}
+ */
 export const Fragment = HtmlElementWrapper('');
 
 

package/src/core/elements/interactive.js

@@ -1,7 +1,25 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
-
+/**
+ * Creates a `<details>` element.
+ * @type {function(DetailsAttributes=, NdChild|NdChild[]=): HTMLDetailsElement}
+ */
 export const Details = HtmlElementWrapper('details');
+
+/**
+ * Creates a `<summary>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Summary = HtmlElementWrapper('summary');
+
+/**
+ * Creates a `<dialog>` element.
+ * @type {function(DialogAttributes=, NdChild|NdChild[]=): HTMLDialogElement}
+ */
 export const Dialog = HtmlElementWrapper('dialog');
+
+/**
+ * Creates a `<menu>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLMenuElement}
+ */
 export const Menu = HtmlElementWrapper('menu');

package/src/core/elements/list.js

@@ -1,10 +1,37 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates an `<ol>` element.
+ * @type {function(OlAttributes=, NdChild|NdChild[]=): HTMLOListElement}
+ */
 export const OrderedList = HtmlElementWrapper('ol');
+
+/**
+ * Creates a `<ul>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLUListElement}
+ */
 export const UnorderedList = HtmlElementWrapper('ul');
+
+/**
+ * Creates a `<li>` element.
+ * @type {function(GlobalAttributes & { value?: number }=, NdChild|NdChild[]=): HTMLLIElement}
+ */
 export const ListItem = HtmlElementWrapper('li');
 
+/**
+ * Alias for {@link ListItem}.
+ * @type {typeof ListItem}
+ */
 export const Li = ListItem;
+
+/**
+ * Alias for {@link OrderedList}.
+ * @type {typeof OrderedList}
+ */
 export const Ol = OrderedList;
-export const Ul = UnorderedList;
 
+/**
+ * Alias for {@link UnorderedList}.
+ * @type {typeof UnorderedList}
+ */
+export const Ul = UnorderedList;

package/src/core/elements/medias.js

@@ -1,8 +1,37 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates an `<audio>` element.
+ * @type {function(AudioAttributes=, NdChild|NdChild[]=): HTMLAudioElement}
+ */
 export const Audio = HtmlElementWrapper('audio');
+
+/**
+ * Creates a `<video>` element.
+ * @type {function(VideoAttributes=, NdChild|NdChild[]=): HTMLVideoElement}
+ */
 export const Video = HtmlElementWrapper('video');
+
+/**
+ * Creates a `<source>` element.
+ * @type {function(SourceAttributes=): HTMLSourceElement}
+ */
 export const Source = HtmlElementWrapper('source');
+
+/**
+ * Creates a `<track>` element.
+ * @type {function(TrackAttributes=): HTMLTrackElement}
+ */
 export const Track = HtmlElementWrapper('track');
+
+/**
+ * Creates a `<canvas>` element.
+ * @type {function(CanvasAttributes=, NdChild|NdChild[]=): HTMLCanvasElement}
+ */
 export const Canvas = HtmlElementWrapper('canvas');
+
+/**
+ * Creates an `<svg>` element.
+ * @type {function(SvgAttributes=, NdChild|NdChild[]=): SVGSVGElement}
+ */
 export const Svg = HtmlElementWrapper('svg');

package/src/core/elements/meta-data.js

@@ -1,9 +1,43 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates a `<time>` element.
+ * @type {function(TimeAttributes=, NdChild|NdChild[]=): HTMLTimeElement}
+ */
 export const Time = HtmlElementWrapper('time');
+
+/**
+ * Creates a `<data>` element.
+ * @type {function(GlobalAttributes & { value?: Observable<string>|string }=, NdChild|NdChild[]=): HTMLDataElement}
+ */
 export const Data = HtmlElementWrapper('data');
+
+/**
+ * Creates an `<address>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Address = HtmlElementWrapper('address');
+
+/**
+ * Creates a `<kbd>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Kbd = HtmlElementWrapper('kbd');
+
+/**
+ * Creates a `<samp>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Samp = HtmlElementWrapper('samp');
+
+/**
+ * Creates a `<var>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Var = HtmlElementWrapper('var');
+
+/**
+ * Creates a `<wbr>` element.
+ * @type {function(GlobalAttributes=): HTMLElement}
+ */
 export const Wbr = HtmlElementWrapper('wbr');

package/src/core/elements/table.js

@@ -1,14 +1,73 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates a `<caption>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableCaptionElement}
+ */
 export const Caption = HtmlElementWrapper('caption');
+
+/**
+ * Creates a `<table>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableElement}
+ */
 export const Table = HtmlElementWrapper('table');
+
+/**
+ * Creates a `<thead>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableSectionElement}
+ */
 export const THead = HtmlElementWrapper('thead');
+
+/**
+ * Creates a `<tfoot>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableSectionElement}
+ */
 export const TFoot = HtmlElementWrapper('tfoot');
+
+/**
+ * Creates a `<tbody>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableSectionElement}
+ */
 export const TBody = HtmlElementWrapper('tbody');
+
+/**
+ * Creates a `<tr>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableRowElement}
+ */
 export const Tr = HtmlElementWrapper('tr');
+
+/**
+ * Alias for {@link Tr}.
+ * @type {typeof Tr}
+ */
 export const TRow = Tr;
+
+/**
+ * Creates a `<th>` element.
+ * @type {function(ThAttributes=, NdChild|NdChild[]=): HTMLTableCellElement}
+ */
 export const Th = HtmlElementWrapper('th');
+
+/**
+ * Alias for {@link Th}.
+ * @type {typeof Th}
+ */
 export const THeadCell = Th;
+
+/**
+ * Alias for {@link Th}.
+ * @type {typeof Th}
+ */
 export const TFootCell = Th;
+
+/**
+ * Creates a `<td>` element.
+ * @type {function(TdAttributes=, NdChild|NdChild[]=): HTMLTableCellElement}
+ */
 export const Td = HtmlElementWrapper('td');
+
+/**
+ * Alias for {@link Td}.
+ * @type {typeof Td}
+ */
 export const TBodyCell = Td;

package/src/core/utils/helpers.js

@@ -75,7 +75,12 @@ export const trim = function(str, char) {
 }
 
 export const deepClone = (value, onObservableFound) => {
-    // Primitives
+    try {
+        if(window.structuredClone !== undefined) {
+            return window.structuredClone(value);
+        }
+    } catch (e){}
+
     if (value === null || typeof value !== 'object') {
         return value;
     }
@@ -99,7 +104,7 @@ export const deepClone = (value, onObservableFound) => {
     // Objects
     const cloned = {};
     for (const key in value) {
-        if (value.hasOwnProperty(key)) {
+        if (Object.hasOwn(value, key)) {
             cloned[key] = deepClone(value[key]);
         }
     }

package/src/core/utils/memoize.js

@@ -3,7 +3,7 @@
 export const once = (fn) => {
     let result = null;
     return (...args) => {
-        if(result) {
+        if(result != null) {
             return result;
         }
         result = fn(...args);

package/src/core/wrappers/DocumentObserver.js

@@ -1,97 +1,167 @@
-
 const DocumentObserver = {
     mounted: new WeakMap(),
+    beforeUnmount: new WeakMap(),
     mountedSupposedSize: 0,
     unmounted: new WeakMap(),
     unmountedSupposedSize: 0,
     observer: null,
+
     executeMountedCallback(node) {
         const data = DocumentObserver.mounted.get(node);
         if(!data) {
             return;
         }
         data.inDom = true;
-        data.mounted && data.mounted(node);
+        if(!data.mounted) {
+            return;
+        }
+        if(Array.isArray(data.mounted)) {
+            for(const cb of data.mounted) {
+                cb(node);
+            }
+            return;
+        }
+        data.mounted(node);
     },
+
     executeUnmountedCallback(node) {
         const data = DocumentObserver.unmounted.get(node);
         if(!data) {
             return;
         }
-
         data.inDom = false;
-        if(data.unmounted && data.unmounted(node) === true) {
+        if(!data.unmounted) {
+            return;
+        }
+
+        let shouldRemove = false;
+        if(Array.isArray(data.unmounted)) {
+            for(const cb of data.unmounted) {
+                if(cb(node) === true) {
+                    shouldRemove = true;
+                }
+            }
+        } else {
+            shouldRemove = data.unmounted(node) === true;
+        }
+
+        if(shouldRemove) {
             data.disconnect();
             node.nd?.remove();
         }
     },
+
     checkMutation: function(mutationsList) {
-        let i = 0;
         for(const mutation of mutationsList) {
-            if(DocumentObserver.mountedSupposedSize > 0 ) {
+            if(DocumentObserver.mountedSupposedSize > 0) {
                 for(const node of mutation.addedNodes) {
                     DocumentObserver.executeMountedCallback(node);
                     if(!node.querySelectorAll) {
-                        return;
+                        continue;
                     }
                     const children = node.querySelectorAll('[data--nd-mounted]');
-                    if(!children.length) {
-                        return;
-                    }
-                    for(const node of children) {
-                        DocumentObserver.executeMountedCallback(node);
+                    for(const child of children) {
+                        DocumentObserver.executeMountedCallback(child);
                     }
                 }
             }
 
-            if(DocumentObserver.unmountedSupposedSize > 0 ) {
-                for(const node of mutation.removedNodes) {
+            if (DocumentObserver.unmountedSupposedSize > 0) {
+                for (const node of mutation.removedNodes) {
                     DocumentObserver.executeUnmountedCallback(node);
                     if(!node.querySelectorAll) {
-                        return;
+                        continue;
                     }
                     const children = node.querySelectorAll('[data--nd-unmounted]');
-                    if(!children.length) {
-                        return;
-                    }
-                    for(const node of children) {
-                        DocumentObserver.executeUnmountedCallback(node);
+                    for(const child of children) {
+                        DocumentObserver.executeUnmountedCallback(child);
                     }
                 }
             }
         }
     },
+
     /**
-     *
      * @param {HTMLElement} element
      * @param {boolean} inDom
-     * @returns {{watch: (function(): Map<any, any>), disconnect: (function(): boolean), mounted: (function(*): Set<any>), unmounted: (function(*): Set<any>)}}
+     * @returns {{ disconnect: Function, mounted: Function, unmounted: Function, off: Function }}
      */
     watch: function(element, inDom = false) {
+        let mountedRegistered   = false;
+        let unmountedRegistered = false;
+
         let data = {
             inDom,
             mounted: null,
             unmounted: null,
             disconnect: () => {
-                DocumentObserver.mounted.delete(element);
-                DocumentObserver.unmounted.delete(element);
-                DocumentObserver.mountedSupposedSize--;
-                DocumentObserver.unmountedSupposedSize--;
+                if (mountedRegistered) {
+                    DocumentObserver.mounted.delete(element);
+                    DocumentObserver.mountedSupposedSize--;
+                }
+                if (unmountedRegistered) {
+                    DocumentObserver.unmounted.delete(element);
+                    DocumentObserver.unmountedSupposedSize--;
+                }
                 data = null;
             }
         };
 
+        const addListener = (type, callback) => {
+            if (!data[type]) {
+                data[type] = callback;
+                return;
+            }
+            if (!Array.isArray(data[type])) {
+                data[type] = [data[type], callback];
+                return;
+            }
+            data[type].push(callback);
+        };
+
+        const removeListener = (type, callback) => {
+            if(!data?.[type]) {
+                return;
+            }
+            if(Array.isArray(data[type])) {
+                const index = data[type].indexOf(callback);
+                if(index > -1) {
+                    data[type].splice(index, 1);
+                }
+                if(data[type].length === 1) {
+                    data[type] = data[type][0];
+                }
+                if(data[type].length === 0) {
+                    data[type] = null;
+                }
+                return;
+            }
+            data[type] = null;
+        };
+
         return {
-            disconnect: data.disconnect,
+            disconnect: () => data?.disconnect(),
+
             mounted: (callback) => {
-                data.mounted = callback;
+                addListener('mounted', callback);
                 DocumentObserver.mounted.set(element, data);
-                DocumentObserver.mountedSupposedSize++;
+                if (!mountedRegistered) {
+                    DocumentObserver.mountedSupposedSize++;
+                    mountedRegistered = true;
+                }
             },
+
             unmounted: (callback) => {
-                data.unmounted = callback;
+                addListener('unmounted', callback);
                 DocumentObserver.unmounted.set(element, data);
-                DocumentObserver.unmountedSupposedSize++;
+                if (!unmountedRegistered) {
+                    DocumentObserver.unmountedSupposedSize++;
+                    unmountedRegistered = true;
+                }
+            },
+
+            off: (type, callback) => {
+                removeListener(type, callback);
             }
         };
     }
@@ -102,4 +172,5 @@ DocumentObserver.observer.observe(document.body, {
     childList: true,
     subtree: true,
 });
+
 export default DocumentObserver;

package/src/core/wrappers/ElementCreator.js

@@ -3,6 +3,7 @@ import Validator from "../utils/validator";
 import AttributesWrapper from "./AttributesWrapper";
 import PluginsManager from "../utils/plugins-manager";
 import './prototypes/nd-element-extensions';
+import './prototypes/nd-element.transition.extensions';
 import './prototypes/attributes-extensions';
 
 const $nodeCache = new Map();
@@ -95,6 +96,10 @@ export const ElementCreator = {
             PluginsManager.emit('AfterProcessChildren', parent);
         }
     },
+    async safeRemove(element) {
+        await element.remove();
+
+    },
     getChild(child) {
         if(child == null) {
             return null;

package/src/core/wrappers/HtmlElementWrapper.js

@@ -28,10 +28,10 @@ function createHtmlElement($tagName, customWrapper, _attributes, _children = nul
 /**
  *
  * @param {string} name
- * @param {?Function} customWrapper
+ * @param {?Function=} customWrapper
  * @returns {Function}
  */
-export default function HtmlElementWrapper(name, customWrapper) {
+export default function HtmlElementWrapper(name, customWrapper = null) {
     return createHtmlElement.bind(null, name, customWrapper);
 };
 

package/src/core/wrappers/NDElement.js

@@ -73,6 +73,37 @@ NDElement.prototype.unmounted = function(callback) {
     return this.lifecycle({ unmounted: callback });
 };
 
+NDElement.prototype.beforeUnmount = function(id, callback) {
+    const el = this.$element;
+
+    if(!DocumentObserver.beforeUnmount.has(el)) {
+        DocumentObserver.beforeUnmount.set(el, new Map());
+        const originalRemove = el.remove.bind(el);
+
+        let  $isUnmounting = false
+
+        el.remove = async () => {
+            if($isUnmounting) {
+                return;
+            }
+            $isUnmounting = true;
+
+            try {
+                const callbacks = DocumentObserver.beforeUnmount.get(el);
+                for (const cb of callbacks.values()) {
+                    await cb.call(this, el);
+                }
+            } finally {
+                originalRemove();
+                $isUnmounting = false;
+            }
+        };
+    }
+
+    DocumentObserver.beforeUnmount.get(el).set(id, callback);
+    return this;
+};
+
 NDElement.prototype.htmlElement = function() {
     return this.$element;
 };
@@ -160,7 +191,7 @@ NDElement.prototype.with = function(methods) {
     }
 
     return this;
-}
+};
 
 /**
  * Extends the NDElement prototype with new methods available to all NDElement instances.
@@ -195,7 +226,7 @@ NDElement.extend = function(methods) {
     ]);
 
     for (const name in methods) {
-        if (!methods.hasOwnProperty(name)) {
+        if (!Object.hasOwn(methods, name)) {
             continue;
         }
 

package/src/core/wrappers/TemplateCloner.js

@@ -51,7 +51,7 @@ const $hydrateFn = function(hydrateFunction, targetType, element, property) {
     hydrationState[targetType][property] = hydrateFunction;
 }
 
-const bindAttachMethods = function(node, bindDingData, data) {
+const bindAttachMethods = (node, bindDingData, data) => {
     if(!bindDingData.attach) {
         return null;
     }