native-document 1.0.165 → 1.0.168

package/src/core/wrappers/NDElement.js

@@ -1,13 +1,20 @@
-import DocumentObserver from "./DocumentObserver";
-import PluginsManager from "../utils/plugins-manager";
-import NativeDocumentError from "../errors/NativeDocumentError.js";
-import DebugManager from "../utils/debug-manager.js";
+import DocumentObserver from './DocumentObserver';
+import PluginsManager from '../utils/plugins-manager';
+import NativeDocumentError from '../errors/NativeDocumentError.js';
+import DebugManager from '../utils/debug-manager.js';
 import attributesWrapper, {
     bindAttributeWithObservable,
     bindClassAttribute,
-    bindStyleAttribute
-} from "./AttributesWrapper";
+    bindStyleAttribute,
+} from './AttributesWrapper';
 
+/**
+ * Wraps an HTMLElement with NativeDocument's reactivity and lifecycle API.
+ * Created automatically by HtmlElementWrapper — not intended to be instantiated directly.
+ *
+ * @constructor
+ * @param {HTMLElement} element - The underlying HTML element to wrap
+ */
 export function NDElement(element) {
     this.$element = element;
     this.$attachements = null;
@@ -16,10 +23,18 @@ export function NDElement(element) {
     }
 }
 
+
 NDElement.prototype.__$isNDElement = true;
 
 NDElement.$getChild = (el) => el;
 
+/**
+ * Appends a child element to an internal DocumentFragment (ghost DOM),
+ * keeping it detached from the main document until explicitly mounted.
+ *
+ * @param {HTMLElement|DocumentFragment|NDElement} element - Element to append
+ * @returns {this}
+ */
 NDElement.prototype.ghostDom = function(element) {
     if(!this.$attachements) {
         this.$attachements = document.createDocumentFragment();
@@ -28,15 +43,47 @@ NDElement.prototype.ghostDom = function(element) {
     return this;
 };
 
+/**
+ * Returns the underlying HTMLElement. Used internally for type coercion.
+ *
+ * @returns {HTMLElement}
+ */
 NDElement.prototype.valueOf = function() {
     return this.$element;
 };
 
+/**
+ * Stores the underlying HTMLElement in target[name].
+ * Use this to keep a reference to the raw DOM node.
+ *
+ * @param {Record<string, any>} target - Object to store the reference in
+ * @param {string} name - Property name to assign on the target object
+ * @returns {this}
+ * @example
+ * const refs = {};
+ * Input({ type: 'text' }).nd.ref(refs, 'emailInput');
+ * refs.emailInput.focus();
+ */
 NDElement.prototype.ref = function(target, name) {
     target[name] = this.$element;
     return this;
 };
 
+/**
+ * Stores the NDElement instance itself in target[name].
+ * Use this to expose a component's public API to a parent (via .with()).
+ *
+ * @param {Record<string, any>} target - Object to store the reference in
+ * @param {string} name - Property name to assign on the target object
+ * @returns {this}
+ * @example
+ * const refs = {};
+ * Counter()
+ *   .nd.with({ increment() { count.$value++; return this; } })
+ *   .refSelf(refs, 'counter');
+ *
+ * refs.counter.increment();
+ */
 NDElement.prototype.refSelf = function(target, name) {
     target[name] = this;
     // TODO: @DIM to check
@@ -44,6 +91,12 @@ NDElement.prototype.refSelf = function(target, name) {
     return this;
 };
 
+/**
+ * Calls .nd.remove() on all child NDElements before removing this element.
+ * Used to propagate lifecycle cleanup through the component tree.
+ *
+ * @returns {this}
+ */
 NDElement.prototype.unmountChildren = function() {
     let element = this.$element;
     for(let i = 0, length = element.children.length; i < length; i++) {
@@ -57,6 +110,12 @@ NDElement.prototype.unmountChildren = function() {
     return this;
 };
 
+/**
+ * Removes the element from the DOM and cleans up its lifecycle observers.
+ * Also calls unmountChildren() recursively.
+ *
+ * @returns {this}
+ */
 NDElement.prototype.remove = function() {
     let element = this.$element;
     element.nd.unmountChildren();
@@ -69,6 +128,19 @@ NDElement.prototype.remove = function() {
 };
 
 const $lifeCycleObservers = new WeakMap();
+
+/**
+ * Registers mounted and/or unmounted lifecycle callbacks for this element.
+ * Uses MutationObserver internally to detect DOM insertion and removal.
+ *
+ * @param {{ mounted?: (el: HTMLElement) => void, unmounted?: (el: HTMLElement) => boolean|void }} states - Lifecycle hooks
+ * @returns {this}
+ * @example
+ * Div({}).nd.lifecycle({
+ *   mounted: (el) => console.log('mounted', el),
+ *   unmounted: (el) => console.log('unmounted', el),
+ * });
+ */
 NDElement.prototype.lifecycle = function(states) {
     const el = this.$element;
     if (!$lifeCycleObservers.has(el)) {
@@ -87,31 +159,68 @@ NDElement.prototype.lifecycle = function(states) {
     return this;
 };
 
+/**
+ * Registers an unmounted callback that cleans up all beforeUnmount handlers
+ * and aborts any pending async operations on this element and its children.
+ *
+ * @returns {this}
+ */
 NDElement.prototype.destroyOnUnmount = function() {
-    this.unmounted(() => {
-        this.$element?.querySelectorAll('[data--nd-before-unmount]').forEach(child => {
-            child.remove();
-            child.__$controller?.abort();
-            child.__$controller = null;
-            $lifeCycleObservers.delete(child);
-        });
+    this.unmounted(() => this.destroy());
+    return this;
+};
 
-        this.$element.__$controller?.abort();
-        this.$element.__$controller = null;
-        $lifeCycleObservers.delete(this.$element);
-        this.$element = null;
+/**
+ * aborts any pending async operations on this element and its children.
+ *
+ * @returns {this}
+ */
+NDElement.prototype.destroy = function() {
+    this.$element?.querySelectorAll('[data--nd-before-unmount]').forEach(child => {
+        child.remove();
+        child.__$controller?.abort();
+        child.__$controller = null;
+        $lifeCycleObservers.delete(child);
     });
-    return this;
+
+    this.$element.__$controller?.abort();
+    this.$element.__$controller = null;
+    $lifeCycleObservers.delete(this.$element);
+    this.$element = null;
 };
 
+/**
+ * Shorthand for lifecycle({ mounted: callback }).
+ *
+ * @param {(el: HTMLElement) => void} callback - Called when element is inserted into the DOM
+ * @returns {this}
+ */
 NDElement.prototype.mounted = function(callback) {
     return this.lifecycle({ mounted: callback });
 };
 
+/**
+ * Shorthand for lifecycle({ unmounted: callback }).
+ *
+ * @param {(el: HTMLElement) => boolean|void} callback - Called when element is removed from the DOM
+ * @returns {this}
+ */
 NDElement.prototype.unmounted = function(callback) {
     return this.lifecycle({ unmounted: callback });
 };
 
+/**
+ * Registers an async callback to run before this element is removed from the DOM.
+ * The element's .remove() is delayed until all beforeUnmount callbacks resolve.
+ *
+ * @param {string} id - Unique identifier for this callback (allows overwriting)
+ * @param {(this: NDElement, el: HTMLElement) => void|Promise<void>} callback - Async-compatible callback
+ * @returns {this}
+ * @example
+ * Div({}).nd.beforeUnmount('fade-out', async (el) => {
+ *   await el.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 300 }).finished;
+ * });
+ */
 NDElement.prototype.beforeUnmount = function(id, callback) {
     const el = this.$element;
 
@@ -144,18 +253,31 @@ NDElement.prototype.beforeUnmount = function(id, callback) {
     return this;
 };
 
+/**
+ * Returns the underlying HTMLElement.
+ * Alias: .node()
+ *
+ * @returns {HTMLElement}
+ */
 NDElement.prototype.htmlElement = function() {
     return this.$element;
 };
 
 NDElement.prototype.node = NDElement.prototype.htmlElement;
 
+/**
+ * Attaches a Shadow DOM to this element, redirecting all child appends to the shadow root.
+ *
+ * @param {'open'|'closed'} mode - Shadow DOM encapsulation mode
+ * @param {string|null} [style=null] - Optional CSS string to inject into the shadow root
+ * @returns {this}
+ */
 NDElement.prototype.shadow = function(mode, style = null) {
     const $element = this.$element;
-    const children = Array.from($element.childNodes)
+    const children = Array.from($element.childNodes);
     const shadowRoot = $element.attachShadow({ mode });
     if(style) {
-        const styleNode = document.createElement("style");
+        const styleNode = document.createElement('style');
         styleNode.textContent = style;
         shadowRoot.appendChild(styleNode);
     }
@@ -166,10 +288,22 @@ NDElement.prototype.shadow = function(mode, style = null) {
     return this;
 };
 
+/**
+ * Shorthand for .shadow('open', style).
+ *
+ * @param {string|null} [style=null] - Optional CSS string to inject into the shadow root
+ * @returns {this}
+ */
 NDElement.prototype.openShadow = function(style = null) {
     return this.shadow('open', style);
 };
 
+/**
+ * Shorthand for .shadow('closed', style).
+ *
+ * @param {string|null} [style=null] - Optional CSS string to inject into the shadow root
+ * @returns {this}
+ */
 NDElement.prototype.closedShadow = function(style = null) {
     return this.shadow('closed', style);
 };
@@ -218,7 +352,16 @@ NDElement.prototype.with = function(methods) {
     return this;
 };
 
-
+/**
+ * Sets a single attribute on the element.
+ * If value is an ObservableItem, the attribute is updated reactively.
+ *
+ * @param {string} name - Attribute name
+ * @param {string|ObservableItem<string>} value - Attribute value, static or reactive
+ * @returns {this}
+ * @example
+ * Input({}).nd.attr('placeholder', label); // reactive placeholder
+ */
 NDElement.prototype.attr = function(name, value) {
     if(value?.__$Observable) {
         bindAttributeWithObservable(this.$element, name, value);
@@ -228,16 +371,37 @@ NDElement.prototype.attr = function(name, value) {
     return this;
 };
 
+/**
+ * Applies a batch of attributes to the element via AttributesWrapper.
+ * Supports reactive values, class maps, and style maps.
+ *
+ * @param {Object} attrs - Attributes object (same format as HtmlElementWrapper props)
+ * @returns {this}
+ */
 NDElement.prototype.attrs = function(attrs) {
     attributesWrapper(this.$element, attrs);
     return this;
 };
 
+/**
+ * Applies a reactive class map to the element.
+ * Each key is a class name; each value is a boolean or ObservableItem<boolean>.
+ *
+ * @param {Record<string, boolean|ObservableItem<boolean>>} classes - Class map
+ * @returns {this}
+ */
 NDElement.prototype.class = function(classes) {
     bindClassAttribute(this.$element, classes);
     return this;
 };
 
+/**
+ * Applies a reactive style map to the element.
+ * Each key is a CSS property; each value is a string or ObservableItem<string>.
+ *
+ * @param {Record<string, string|ObservableItem<string>>} style - Style map
+ * @returns {this}
+ */
 NDElement.prototype.style = function(style) {
     bindStyleAttribute(this.$element, style);
     return this;
@@ -273,7 +437,7 @@ NDElement.extend = function(methods) {
     const protectedMethods = new Set([
         'constructor', 'valueOf', '$element', '$observer',
         'ref', 'remove', 'cleanup', 'with', 'extend', 'attach',
-        'lifecycle', 'mounted', 'unmounted', 'unmountChildren'
+        'lifecycle', 'mounted', 'unmounted', 'unmountChildren',
     ]);
 
     for (const name in methods) {
@@ -304,4 +468,146 @@ NDElement.extend = function(methods) {
     }
 
     return NDElement;
+};
+
+
+/**
+ * The global sanitizer function used by nd.html() when sanitize option is enabled.
+ * Must be set via NDElement.setSanitizer() before using {sanitize: true}.
+ *
+ * @type {Function|null}
+ */
+NDElement.$sanitizer = null;
+
+/**
+ * Configures the global sanitizer for nd.html().
+ * The sanitizer function receives the HTML string and an optional config object.
+ * Designed to be decoupled from any specific sanitizer library.
+ *
+ * @param {Function} sanitizerFn - Sanitizer function (html, config) => string
+ * @returns {typeof NDElement}
+ * @throws {NativeDocumentError} If sanitizerFn is not a function
+ * @example
+ * import DOMPurify from 'dompurify';
+ * NDElement.setSanitizer((html, config) => DOMPurify.sanitize(html, config));
+ */
+NDElement.setSanitizer = function(sanitizerFn) {
+    if(typeof sanitizerFn !== 'function') {
+        throw new NativeDocumentError('NDElement.setSanitizer() expects a function');
+    }
+    NDElement.$sanitizer = sanitizerFn;
+    return NDElement;
+};
+
+/**
+ * Sets the inner HTML of the element.
+ * Requires either {unsafe: true} to bypass security checks,
+ * or {sanitize: true|Object|Function} to sanitize the content.
+ * Supports Observable values for reactive HTML updates.
+ *
+ * @param {string|ObservableItem} content - HTML string or Observable<string>
+ * @param {Object} [options={}]
+ * @param {boolean} [options.unsafe=false] - Bypass security check. Use only with trusted content.
+ * @param {boolean|Object|Function} [options.sanitize=false] - Sanitize strategy:
+ *   - true: use global sanitizer with default config
+ *   - Object: use global sanitizer with custom config
+ *   - Function: use this function directly as sanitizer (html) => string
+ * @returns {this}
+ * @throws {NativeDocumentError} If sanitize is true/Object but no global sanitizer is configured
+ * @example
+ * // Unsafe — trusted content only
+ * el.nd.html('<strong>Hello</strong>', {unsafe: true})
+ *
+ * // Global sanitizer with default config
+ * el.nd.html($userContent, {sanitize: true})
+ *
+ * // Global sanitizer with custom config
+ * el.nd.html($userContent, {sanitize: {
+ *     ALLOWED_TAGS: ['b', 'i', 'strong', 'a'],
+ *     ALLOWED_ATTR: ['href'],
+ * }})
+ *
+ * // Custom sanitizer function for this specific case
+ * el.nd.html($userContent, {sanitize: (html) => myCustomSanitizer(html)})
+ *
+ * // Reactive with sanitize
+ * el.nd.html($content, {sanitize: true})
+ */
+NDElement.prototype.html = function(content, {unsafe = false, sanitize = false} = {}) {
+    const $element = this.$element;
+    const apply = (value) => {
+        if(sanitize) {
+            if(typeof sanitize === 'function') {
+                $element.innerHTML = sanitize(value);
+                return;
+            }
+
+            if(!NDElement.$sanitizer) {
+                throw new NativeDocumentError('nd.html() — no sanitizer configured. Call NDElement.setSanitizer() first.');
+            }
+            const config = sanitize === true ? {} : sanitize;
+            $element.innerHTML = NDElement.$sanitizer(value, config);
+            return;
+        }
+
+        if(!unsafe) {
+            console.warn('nd.html() — use {unsafe: true} or {sanitize: true|Object|Function}');
+            return;
+        }
+
+        $element.innerHTML = value;
+    };
+
+    if(content?.__$Observable) {
+        content.subscribe(apply);
+        apply(content.val());
+        return this;
+    }
+
+    apply(content);
+    return this;
+};
+
+/**
+ * Makes the element content editable and binds it to an Observable.
+ * Changes in the DOM update the Observable, and changes to the Observable
+ * update the DOM (only when the element is not focused to avoid cursor issues).
+ *
+ * @param {ObservableItem} $obs - Observable to bind to the element content
+ * @param {Object} [options={}]
+ * @param {string} [options.format='html'] - 'html' uses innerHTML, 'text' uses innerText
+ * @returns {this}
+ * @example
+ * // Basic usage
+ * const $content = $('<b>Hello</b>');
+ * Div({}).nd.contentEditable($content)
+ *
+ * // Text only
+ * Div({}).nd.contentEditable($content, {format: 'text'})
+ */
+NDElement.prototype.contentEditable = function($obs, {format = 'html'} = {}) {
+    this.$element.contentEditable = true;
+
+    const getValue = format === 'text'
+        ? () => this.$element.innerText
+        : () => this.$element.innerHTML;
+
+    const setValue = format === 'text'
+        ? (value) => { this.$element.innerText  = value; }
+        : (value) => { this.$element.innerHTML = value; };
+
+    if($obs?.__$Observable) {
+        $obs.subscribe((value) => {
+            if(document.activeElement !== this.$element) {
+                setValue(value);
+            }
+        });
+        setValue($obs.val() || '');
+    }
+
+    this.$element.addEventListener('input', () => {
+        $obs?.set(getValue());
+    }, { signal: this.$getSignal() });
+
+    return this;
 };

package/src/core/wrappers/NdPrototype.js

@@ -1,11 +1,11 @@
-import { NDElement } from "./NDElement";
-import {EVENTS, EVENTS_WITH_PREVENT, EVENTS_WITH_STOP} from "../utils/events";
+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);
@@ -16,7 +16,7 @@ Object.defineProperty(NDElement.prototype, 'nd', {
     configurable: true,
     get: function() {
         return this;
-    }
+    },
 });
 
 
@@ -29,25 +29,25 @@ EVENTS.forEach(eventSourceName => {
     NDElement.prototype['on'+eventSourceName] = function(callback = null, options = {}) {
         this.$element.addEventListener(eventName, callback, {
             signal: this.$getSignal(),
-            ...options
+            ...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
+            ...options,
         });
         return this;
     };
     NDElement.prototype['onPreventStop'+eventSourceName] = function(callback = null, options = {}) {
         _preventStop(this.$element, eventName, callback, {
             signal: this.$getSignal(),
-            ...options
+            ...options,
         });
         return this;
     };
@@ -58,12 +58,20 @@ EVENTS_WITH_PREVENT.forEach(eventSourceName => {
     NDElement.prototype['onPrevent'+eventSourceName] = function(callback = null, options = {}) {
         _prevent(this.$element, eventName, callback, {
             signal: this.$getSignal(),
-            ...options
+            ...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();
@@ -71,27 +79,63 @@ NDElement.prototype.$getSignal = function() {
     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
+        ...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
+        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,
@@ -109,7 +153,7 @@ const _prevent = function(element, eventName, callback, options) {
     };
     element.addEventListener(eventName, handler, options);
     return this;
-}
+};
 
 const _stop = function(element, eventName, callback, options) {
     const handler = (event) => {
@@ -175,15 +219,15 @@ const classListMethods = {
     },
     contains(value) {
         return this.getClasses().indexOf(value) >= 0;
-    }
-}
+    },
+};
 
 Object.defineProperty(HTMLElement.prototype, 'classes', {
     configurable: true,
     get() {
         return {
             $element: this,
-            ...classListMethods
+            ...classListMethods,
         };
-    }
+    },
 });