native-document 1.0.92 → 1.0.94

package/src/core/elements/html5-semantics.js

@@ -1,12 +1,55 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates a `<main>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Main = HtmlElementWrapper('main');
+
+/**
+ * Creates a `<section>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Section = HtmlElementWrapper('section');
+
+/**
+ * Creates an `<article>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Article = HtmlElementWrapper('article');
+
+/**
+ * Creates an `<aside>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Aside = HtmlElementWrapper('aside');
+
+/**
+ * Creates a `<nav>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Nav = HtmlElementWrapper('nav');
+
+/**
+ * Creates a `<figure>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Figure = HtmlElementWrapper('figure');
+
+/**
+ * Creates a `<figcaption>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const FigCaption = HtmlElementWrapper('figcaption');
 
+/**
+ * Creates a `<header>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Header = HtmlElementWrapper('header');
-export const Footer = HtmlElementWrapper('footer');
+
+/**
+ * Creates a `<footer>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
+export const Footer = HtmlElementWrapper('footer');

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/cache.js

@@ -0,0 +1,5 @@
+import { once as _once, autoMemoize, autoOnce } from "./memoize.js";
+
+export const once = fn => autoOnce(fn);
+export const singleton = fn => _once(fn);
+export const memoize = fn => autoMemoize(fn);

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,9 +3,10 @@
 export const once = (fn) => {
     let result = null;
     return (...args) => {
-        if(result === null) {
-            result = fn(...args);
+        if(result != null) {
+            return result;
         }
+        result = fn(...args);
         return result;
     };
 };
@@ -14,9 +15,10 @@ export const autoOnce = (fn) => {
     let target = null;
     return new Proxy({}, {
         get: (_, key) => {
-            if(target === null) {
-                target = fn();
+            if(target) {
+                return target[key];
             }
+            target = fn();
             return target[key];
         }
     });
@@ -26,10 +28,13 @@ export const memoize = (fn) => {
     const cache = new Map();
     return (...args) => {
         const [key, ...rest] = args;
-        if(!cache.has(key)) {
-            cache.set(key, fn(...rest));
+        const cached = cache.get(key);
+        if(cached) {
+            return cached;
         }
-        return cache.get(key);
+        const result = fn(...rest);
+        cache.set(key, result);
+        return result;
     };
 };
 
@@ -37,17 +42,21 @@ export const autoMemoize = (fn) => {
     const cache = new Map();
     return new Proxy({}, {
         get: (_, key) => {
-            if(!cache.has(key)) {
-                if(fn.length > 0) {
-                    return (...args) => {
-                        const result = fn(...args);
-                        cache.set(key, result);
-                        return result;
-                    }
+            const cached = cache.get(key);
+            if(cached) {
+                return cached;
+            }
+
+            if(fn.length > 0) {
+                return (...args) => {
+                    const result = fn(...args, key);
+                    cache.set(key, result);
+                    return result;
                 }
-                cache.set(key, fn());
             }
-            return cache.get(key);
+            const result = fn(key);
+            cache.set(key, result);
+            return result;
         }
     });
 };

package/src/core/utils/prototypes.js

@@ -27,13 +27,14 @@ Function.prototype.cached = function(...args) {
 };
 
 Function.prototype.errorBoundary = function(callback) {
-    return (...args)  => {
+    const handler = (...args)  => {
         try {
             return this.apply(this, args);
         } catch(e) {
-            return callback(e);
+            return callback(e, {caller: handler, args: args });
         }
     };
+    return handler;
 };
 
 String.prototype.use = function(args) {

package/src/core/wrappers/AttributesWrapper.js

@@ -17,7 +17,7 @@ export function bindClassAttribute(element, data) {
             continue;
         }
         if(value.__$isObservableWhen) {
-            element.classes.toggle(className, value.isMath());
+            element.classes.toggle(className, value.isActive());
             value.subscribe((shouldAdd) => element.classes.toggle(className, shouldAdd));
             continue;
         }

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

@@ -103,12 +103,35 @@ NDElement.prototype.closedShadow = function(style = null) {
     return this.shadow('closed', style);
 };
 
+/**
+ * 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) {
     bindingHydrator.$hydrate(this.$element, methodName);
     return this.$element;
 };
 
-
+/**
+ * Extends the current NDElement instance with custom methods.
+ * Methods are bound to the instance and available for chaining.
+ *
+ * @param {Object} methods - Object containing method definitions
+ * @returns {this} The NDElement instance with added methods for chaining
+ * @example
+ * element.nd.with({
+ *   highlight() {
+ *     this.$element.style.background = 'yellow';
+ *     return this;
+ *   }
+ * }).highlight().onClick(() => console.log('Clicked'));
+ */
 NDElement.prototype.with = function(methods) {
     if (!methods || typeof methods !== 'object') {
         throw new NativeDocumentError('extend() requires an object of methods');
@@ -139,6 +162,23 @@ NDElement.prototype.with = function(methods) {
     return this;
 }
 
+/**
+ * Extends the NDElement prototype with new methods available to all NDElement instances.
+ * Use this to add global methods to all NDElements.
+ *
+ * @param {Object} methods - Object containing method definitions to add to prototype
+ * @returns {typeof NDElement} The NDElement constructor
+ * @throws {NativeDocumentError} If methods is not an object or contains non-function values
+ * @example
+ * NDElement.extend({
+ *   fadeIn() {
+ *     this.$element.style.opacity = '1';
+ *     return this;
+ *   }
+ * });
+ * // Now all NDElements have .fadeIn() method
+ * Div().nd.fadeIn();
+ */
 NDElement.extend = function(methods) {
     if (!methods || typeof methods !== 'object') {
         throw new NativeDocumentError('NDElement.extend() requires an object of methods');
@@ -155,7 +195,7 @@ NDElement.extend = function(methods) {
     ]);
 
     for (const name in methods) {
-        if (!methods.hasOwnProperty(name)) {
+        if (!Object.hasOwn(methods, name)) {
             continue;
         }
 

package/src/core/wrappers/NdPrototype.js

@@ -38,6 +38,10 @@ EVENTS_WITH_STOP.forEach(eventSourceName => {
         _stop(this.$element, eventName, callback);
         return this;
     };
+    NDElement.prototype['onPreventStop'+eventSourceName] = function(callback = null) {
+        _preventStop(this.$element, eventName, callback);
+        return this;
+    };
 });
 
 EVENTS_WITH_PREVENT.forEach(eventSourceName => {

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;
     }
@@ -65,7 +65,12 @@ const bindAttachMethods = function(node, bindDingData, data) {
 
 const applyBindingTreePath = (root, target, data, path) => {
     if(path.fn) {
-        path.fn(data, target, root);
+        if(typeof path.fn === 'string') {
+            ElementCreator.bindTextNode(target, data[0][path.fn]);
+        }
+        else {
+            path.fn(data, target, root);
+        }
     }
     if(path.children) {
         for(let i = 0, length = path.children.length; i < length; i++) {
@@ -91,15 +96,16 @@ export function TemplateCloner($fn) {
             if(bindDingData && bindDingData.value) {
                 currentPath.fn = bindDingData.value;
                 const textNode = node.cloneNode();
+                if(typeof bindDingData.value === 'string') {
+                    ElementCreator.bindTextNode(textNode, data[0][bindDingData.value]);
+                    return textNode;
+                }
                 bindDingData.value(data, textNode);
                 return textNode;
             }
             return node.cloneNode(true);
         }
-        const nodeCloned = node.cloneNode(node.fullCloneNode);
-        if(node.fullCloneNode) {
-            return nodeCloned;
-        }
+        const nodeCloned = node.cloneNode();
         if(bindDingData) {
             bindAttributes(nodeCloned, bindDingData, data);
             bindAttachMethods(nodeCloned, bindDingData, data);
@@ -164,12 +170,9 @@ export function TemplateCloner($fn) {
     }
     this.value = (callbackOrProperty) => {
         if(typeof callbackOrProperty !== 'function') {
-            return createBinding(function(data, textNode) {
-                const firstArgument = data[0];
-                ElementCreator.bindTextNode(textNode, firstArgument[callbackOrProperty]);
-            }, 'value');
+            return createBinding(callbackOrProperty, 'value');
         }
-        return createBinding(function(data, textNode) {
+        return createBinding((data, textNode) => {
             ElementCreator.bindTextNode(textNode, callbackOrProperty(...data));
         }, 'value');
     };

package/src/core/wrappers/prototypes/bind-class-extensions.js

@@ -9,7 +9,7 @@ ObservableItem.prototype.bindNdClass = function(element, className) {
 };
 
 ObservableWhen.prototype.bindNdClass = function(element, className) {
-    element.classes.toggle(className, this.isMath());
+    element.classes.toggle(className, this.isMatch());
     this.subscribe((shouldAdd) => element.classes.toggle(className, shouldAdd));
 };
 

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

@@ -4,6 +4,7 @@ import TemplateBinding from "../TemplateBinding";
 import {ElementCreator} from "../ElementCreator";
 import PluginsManager from "../../utils/plugins-manager";
 import Validator from "../../utils/validator";
+import ObservableChecker from "../../data/ObservableChecker";
 
 String.prototype.toNdElement = function () {
     const formattedChild = this.resolveObservableTemplate ? this.resolveObservableTemplate() : this;
@@ -33,6 +34,8 @@ ObservableItem.prototype.toNdElement = function () {
     return ElementCreator.createObservableNode(null, this);
 };
 
+ObservableChecker.prototype.toNdElement = ObservableItem.prototype.toNdElement;
+
 NDElement.prototype.toNdElement = function () {
     return this.$element ?? this.$build?.() ?? this.build?.() ?? null;
 };