native-document 1.0.164 → 1.0.166

package/src/core/wrappers/SingletonView.js

@@ -1,10 +1,33 @@
-import Anchor from "../elements/anchor/anchor";
-
+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);
@@ -22,6 +45,18 @@ export function SingletonView($viewCreator) {
         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);
@@ -39,6 +74,19 @@ export function SingletonView($viewCreator) {
 }
 
 
+/**
+ * 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;
 

package/src/core/wrappers/SvgElementWrapper.js

@@ -1,4 +1,4 @@
-import {createHtmlElement} from "./HtmlElementWrapper";
+import {createHtmlElement} from './HtmlElementWrapper';
 
 export default function SvgElementWrapper(name) {
     let node = null;

package/src/core/wrappers/constants.js

@@ -29,5 +29,38 @@ export const BOOLEAN_ATTRIBUTES = new Set([
     'itemscope',
     'allowfullscreen',
     'allowpaymentrequest',
-    'playsinline'
-]);
+    '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

@@ -1,11 +1,11 @@
 import {
     bindAttributeWithObservable,
-    bindBooleanAttribute
-} from "../AttributesWrapper";
-import ObservableItem from "../../data/ObservableItem";
-import TemplateBinding from "../TemplateBinding";
-import {BOOLEAN_ATTRIBUTES} from "../constants";
-import ObservableChecker from "../../data/ObservableChecker";
+    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) {
@@ -19,6 +19,6 @@ ObservableItem.prototype.handleNdAttribute = function(element, attributeName) {
 
 ObservableChecker.prototype.handleNdAttribute = ObservableItem.prototype.handleNdAttribute;
 
-    TemplateBinding.prototype.handleNdAttribute = function(element, attributeName) {
+TemplateBinding.prototype.handleNdAttribute = function(element, attributeName) {
     this.$hydrate(element, attributeName);
 };

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

@@ -1,43 +1,92 @@
-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 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';
 
 
 NDElement.$getChild = ElementCreator.getChild;
 
+/**
+ * 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) {
@@ -49,6 +98,12 @@ NDElement.prototype.toNdElement = function () {
     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++) {
@@ -59,6 +114,12 @@ Array.prototype.toNdElement = function () {
     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 child = this;
     if(process.env.NODE_ENV === 'development') {
@@ -67,6 +128,11 @@ Function.prototype.toNdElement = function () {
     return ElementCreator.getChild(child());
 };
 
+/**
+ * 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);
 };

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

@@ -1,4 +1,4 @@
-import {NDElement} from "../NDElement";
+import {NDElement} from '../NDElement';
 
 /**
  * @param {HTMLElement} el
@@ -34,6 +34,16 @@ const waitForVisualEnd = (el, timeout = 1000) => {
     });
 };
 
+/**
+ * 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;
@@ -45,6 +55,17 @@ NDElement.prototype.transitionOut = function(transitionName) {
     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';
@@ -68,13 +89,32 @@ NDElement.prototype.transitionIn = function(transitionName) {
     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);

package/src/core/wrappers/template-cloner/NodeCloner.js

@@ -1,7 +1,16 @@
-import {ElementCreator} from "../ElementCreator";
-import {createTextNode} from "../HtmlElementWrapper";
-import {NDElement} from "../NDElement";
+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;
@@ -41,6 +50,12 @@ const buildProperties = (cache, properties, 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;
@@ -127,26 +142,56 @@ NodeCloner.prototype.resolve = function() {
     };
 };
 
+/**
+ * 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;
 };
 
-NodeCloner.prototype.text = function(value) {
-    this.$content = value;
-    if(typeof value === 'function') {
-        this.cloneNode = (data) => createTextNode(value.apply(null, data));
+/**
+ * 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][value]);
+    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 || {};

package/src/core/wrappers/template-cloner/TemplateCloner.js

@@ -1,7 +1,24 @@
-import TemplateBinding from "../TemplateBinding";
+import TemplateBinding from '../TemplateBinding';
 import { $hydrateFn} from './utils';
-import NodeCloner from "./NodeCloner";
+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;
 
@@ -46,6 +63,14 @@ export function TemplateCloner($fn) {
         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);
@@ -60,29 +85,73 @@ export function TemplateCloner($fn) {
 
     const createBinding = (hydrateFunction, targetType) => {
         return new TemplateBinding((element, property) => {
-            $hydrateFn(hydrateFunction, targetType, 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;
 }
 
@@ -95,9 +164,9 @@ const createTemplateCloner = ($binder) => {
             }
             if (typeof prop === 'symbol') return target[prop];
             return target.value(prop);
-        }
+        },
     });
-}
+};
 
 export function useCache(fn) {
     let $cache = null;

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

@@ -1,5 +1,16 @@
-import {ElementCreator} from "../ElementCreator";
-
+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;
 
@@ -17,6 +28,16 @@ export const hydrateFull = (node, bindDingData, data) => {
     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;
 
@@ -30,6 +51,15 @@ export const hydrateDynamic = (node, bindDingData, data) => {
     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;
 
@@ -42,6 +72,15 @@ export const hydrateClassAttribute = (node, bindDingData, data) => {
     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;
 
@@ -54,6 +93,15 @@ export const hydrateStyleAttribute = (node, bindDingData, data) => {
     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;
 
@@ -66,6 +114,14 @@ export const hydrateAttributes = (node, bindDingData, data) => {
     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;