native-document 1.0.165 → 1.0.166

package/src/core/utils/property-accumulator.js

@@ -1,7 +1,7 @@
-import Validator from "./validator";
+import Validator from './validator';
 
 export const cssPropertyAccumulator = function(initialValue = {}) {
-    let data = Validator.isString(initialValue) ? initialValue.split(';').filter(Boolean) : initialValue;
+    const data = Validator.isString(initialValue) ? initialValue.split(';').filter(Boolean) : initialValue;
 
     return {
         add(key, value) {
@@ -25,10 +25,10 @@ export const cssPropertyAccumulator = function(initialValue = {}) {
             return { ...data };
         },
     };
-}
+};
 
 export const classPropertyAccumulator = function(initialValue = []) {
-    let data = Validator.isString(initialValue) ? initialValue.split(" ").filter(Boolean) : initialValue;
+    let data = Validator.isString(initialValue) ? initialValue.split(' ').filter(Boolean) : initialValue;
 
     return {
         add(key, value = true) {
@@ -48,7 +48,7 @@ export const classPropertyAccumulator = function(initialValue = []) {
                     }, {});
                 }
                 if(key.__$Observable) {
-                    const uniqueId = `obs-${Math.random().toString(36).substr(2, 9)}`
+                    const uniqueId = `obs-${Math.random().toString(36).substr(2, 9)}`;
                     data[uniqueId] = key;
                 }
                 else {
@@ -69,4 +69,4 @@ export const classPropertyAccumulator = function(initialValue = []) {
             return { ...data };
         },
     };
-}
+};

package/src/core/utils/prototypes.js

@@ -1,12 +1,37 @@
-import {withValidation} from "./args-types.js";
+import {withValidation} from './args-types.js';
 
 
 DocumentFragment.prototype.__IS_FRAGMENT = true;
 
+/**
+ * Wraps a function with argument validation based on an ArgTypes schema.
+ * Throws an ArgTypesError if the arguments don't match the schema.
+ *
+ * @param {...ArgType} args - ArgType descriptors defining expected argument types
+ * @returns {Function} Wrapped function that validates its arguments before executing
+ * @example
+ * function greet(name, age) { ... }
+ * const safeGreet = greet.args(ArgTypes.string('name'), ArgTypes.number('age'));
+ * safeGreet('John', 25); // OK
+ * safeGreet('John', 'old'); // throws ArgTypesError
+ */
 Function.prototype.args = function(...args) {
     return withValidation(this, args);
 };
 
+
+/**
+ * Wraps a function with a try/catch error boundary.
+ * If the function throws, the callback is called with the error and context instead.
+ *
+ * @param {(error: Error, context: { caller: Function, args: any[] }) => *} callback - Error handler
+ * @returns {Function} Wrapped function with error boundary
+ * @example
+ * const safeRender = render.errorBoundary((err, { args }) => {
+ *   console.error('Render failed:', err.message);
+ *   return Div({}, 'Error');
+ * });
+ */
 Function.prototype.errorBoundary = function(callback) {
     const handler = (...args)  => {
         try {

package/src/core/utils/shortcut-manager.js

@@ -121,7 +121,7 @@ const displayOnWindows = (shortcut) => {
     parts.push(parsed.key);
 
     return parts.join('+');
-}
+};
 
 /**
  * Display a shortcut string for the current OS.
@@ -154,7 +154,7 @@ const ShortcutManager = {
         if($registry.has(mapKey) && !options.force) {
             const existing = $registry.get(mapKey);
             DebugManager.warn(
-                `ShortcutManager: "${shortcut}" is already registered by "${existing.source}" in context "${context}". Use { force: true } to override.`
+                `ShortcutManager: "${shortcut}" is already registered by "${existing.source}" in context "${context}". Use { force: true } to override.`,
             );
             return this;
         }

package/src/core/utils/validator.js

@@ -1,12 +1,12 @@
-import DebugManager from "./debug-manager";
-import NativeDocumentError from "../errors/NativeDocumentError";
+import DebugManager from './debug-manager';
+import NativeDocumentError from '../errors/NativeDocumentError';
 
 const COMMON_NODE_TYPES = {
     ELEMENT: 1,
     TEXT: 3,
     COMMENT: 8,
     DOCUMENT: 9,
-    DOCUMENT_FRAGMENT: 11
+    DOCUMENT_FRAGMENT: 11,
 };
 
 export const VALID_TYPES = [];
@@ -29,13 +29,13 @@ const Validator = {
         return  value?.__$isObservableArray;
     },
     isProxy(value) {
-        return value?.__isProxy__
+        return value?.__isProxy__;
     },
     isObservableOrProxy(value) {
-        return Validator.isObservable(value) || Validator.isProxy(value);
+        return value?.__$Observable;
     },
     isAnchor(value) {
-        return value?.__Anchor__
+        return value?.__Anchor__;
     },
     isObservableChecker(value) {
         return value?.__$isObservableChecker;
@@ -62,7 +62,7 @@ const Validator = {
         return typeof value === 'object' && value !== null;
     },
     isJson(value) {
-        return !(typeof value !== 'object' || value === null || Array.isArray(value) || value.constructor.name !== 'Object')
+        return !(typeof value !== 'object' || value === null || Array.isArray(value) || value.constructor.name !== 'Object');
     },
     isElement(value) {
         return value && VALID_TYPES[value.nodeType];
@@ -135,7 +135,7 @@ const Validator = {
         if (typeof callback !== 'function') {
             throw new NativeDocumentError('Event callback must be a function');
         }
-    }
+    },
 };
 if(process.env.NODE_ENV === 'development') {
     Validator.validateAttributes = function(attributes) {

package/src/core/wrappers/AttributesWrapper.js

@@ -1,12 +1,15 @@
-import Validator from "../utils/validator";
-import NativeDocumentError from "../errors/NativeDocumentError";
-import {BOOLEAN_ATTRIBUTES} from "./constants.js";
-import {Observable} from "../data/Observable";
+import Validator from '../utils/validator';
+import NativeDocumentError from '../errors/NativeDocumentError';
+import {BOOL_ATTRIBUTES_NAME, BOOLEAN_ATTRIBUTES} from './constants.js';
+import {Observable} from '../data/Observable';
 
 /**
+ * Applies a reactive class map to an HTMLElement.
+ * Each key is a CSS class name; each value is a boolean or ObservableItem<boolean>.
+ * If the value is an ObservableChecker emitting a string, toggles the class name dynamically.
  *
- * @param {HTMLElement} element
- * @param {Object} data
+ * @param {HTMLElement} element - Target element
+ * @param {Record<string, boolean|ObservableItem<boolean>|ObservableChecker<boolean|string>>} data - Class map
  */
 export const bindClassAttribute = (element, data) => {
     for(const className in data) {
@@ -14,7 +17,7 @@ export const bindClassAttribute = (element, data) => {
         if(value.__$Observable) {
             if(value.__$isObservableChecker) {
                 let lastClass = value.val();
-                if(typeof lastClass === "string") {
+                if(typeof lastClass === 'string') {
                     element.classes.toggle(lastClass, true);
                     value.subscribe((currentValue) => {
                         element.classes.remove(lastClass);
@@ -32,14 +35,18 @@ export const bindClassAttribute = (element, data) => {
             value.$hydrate(element, className);
             continue;
         }
-        element.classes.toggle(className, value)
+        element.classes.toggle(className, value);
     }
-}
+};
 
 /**
+ * Applies a reactive style map to an HTMLElement.
+ * Each key is a CSS property name (camelCase or CSS custom property `--var`);
+ * each value is a string or ObservableItem<string>.
+ * CSS custom properties are set via element.style.setProperty().
  *
- * @param {HTMLElement} element
- * @param {Object} data
+ * @param {HTMLElement} element - Target element
+ * @param {Record<string, string|ObservableItem<string>>} data - Style map
  */
 export const bindStyleAttribute = (element, data) => {
     for(const styleName in data) {
@@ -54,7 +61,7 @@ export const bindStyleAttribute = (element, data) => {
                         element.style.removeProperty(styleName);
                         return;
                     }
-                    element.style.setProperty(styleName, newValue)
+                    element.style.setProperty(styleName, newValue);
                 });
             } else {
                 element.style[styleName] = value.val();
@@ -63,7 +70,7 @@ export const bindStyleAttribute = (element, data) => {
                         element.style.removeProperty(styleName);
                         return;
                     }
-                    element.style[styleName] = newValue
+                    element.style[styleName] = newValue;
                 });
             }
             continue;
@@ -87,24 +94,27 @@ export const bindStyleAttribute = (element, data) => {
 export const bindBooleanAttribute = (element, attributeName, value) => {
     const isObservable = value.__$isObservable;
     const defaultValue = isObservable? value.val() : value;
+
+    const attributeRealName = BOOL_ATTRIBUTES_NAME[attributeName];
+
     if(Validator.isBoolean(defaultValue)) {
-        element[attributeName] = defaultValue;
+        element[attributeRealName] = defaultValue;
     }
     else {
-        element[attributeName] = defaultValue === element.value;
+        element[attributeRealName] = defaultValue === element.value;
     }
     if(isObservable) {
         if(attributeName === 'checked') {
             if(typeof defaultValue === 'boolean') {
-                element.addEventListener('input', () => value.set(element[attributeName]));
+                element.addEventListener('input', () => value.set(element[attributeRealName]));
             }
             else {
                 element.addEventListener('input', () => value.set(element.value));
             }
-            value.subscribe((newValue) => element[attributeName] = newValue);
+            value.subscribe((newValue) => element[attributeRealName] = newValue);
             return;
         }
-        value.subscribe((newValue) => element[attributeName] = (newValue === element.value));
+        value.subscribe((newValue) => element[attributeRealName] = (newValue === element.value));
     }
 };
 
@@ -125,7 +135,7 @@ export const bindAttributeWithObservable = (element, attributeName, value) => {
         return;
     }
     element.setAttribute(attributeName, value.val());
-}
+};
 
 /**
  *
@@ -140,12 +150,12 @@ const AttributesWrapper = (element, attributes) => {
 
     for(const originalAttributeName in attributes) {
         const attributeName = originalAttributeName.toLowerCase();
-        let value = attributes[originalAttributeName];
+        const value = attributes[originalAttributeName];
         if(value == null) {
             continue;
         }
         if(value.handleNdAttribute) {
-            value.handleNdAttribute(element, attributeName, value)
+            value.handleNdAttribute(element, attributeName, value);
             continue;
         }
         if(typeof value ===  'object') {
@@ -166,6 +176,6 @@ const AttributesWrapper = (element, attributes) => {
         element.setAttribute(attributeName, value);
     }
     return element;
-}
+};
 
 export default AttributesWrapper;

package/src/core/wrappers/DocumentObserver.js

@@ -116,7 +116,7 @@ const DocumentObserver = {
                     DocumentObserver.unmountedSupposedSize--;
                 }
                 data = null;
-            }
+            },
         };
 
         const addListener = (type, callback) => {
@@ -174,9 +174,9 @@ const DocumentObserver = {
 
             off: (type, callback) => {
                 removeListener(type, callback);
-            }
+            },
         };
-    }
+    },
 };
 
 export default DocumentObserver;

package/src/core/wrappers/ElementCreator.js

@@ -1,6 +1,6 @@
-import Validator from "../utils/validator";
-import AttributesWrapper, { bindClassAttribute, bindStyleAttribute } from "./AttributesWrapper";
-import PluginsManager from "../utils/plugins-manager";
+import Validator from '../utils/validator';
+import AttributesWrapper, { bindClassAttribute, bindStyleAttribute } from './AttributesWrapper';
+import PluginsManager from '../utils/plugins-manager';
 
 let $textNodeCache = null;
 
@@ -44,7 +44,7 @@ export const ElementCreator = {
      * @returns {Text}
      */
     createStaticTextNode: (parent, value) => {
-        let text = ElementCreator.createTextNode();
+        const text = ElementCreator.createTextNode();
         text.nodeValue = value;
         parent && parent.appendChild(text);
         return text;
@@ -76,7 +76,7 @@ export const ElementCreator = {
         if(process.env.NODE_ENV === 'development') {
             PluginsManager.emit('BeforeProcessChildren', parent);
         }
-        let child = ElementCreator.getChild(children);
+        const child = ElementCreator.getChild(children);
         if(child) {
             parent.appendChild(child);
         }

package/src/core/wrappers/HtmlElementWrapper.js

@@ -1,6 +1,6 @@
-import Anchor from "../elements/anchor/anchor";
-import {ElementCreator} from "./ElementCreator";
-import {normalizeComponentArgs} from "../utils/args-types";
+import Anchor from '../elements/anchor/anchor';
+import {ElementCreator} from './ElementCreator';
+import {normalizeComponentArgs} from '../utils/args-types';
 import './NdPrototype';
 
 import './NdPrototype';
@@ -10,10 +10,14 @@ import '../wrappers/prototypes/bind-class-extensions';
 import '../wrappers/prototypes/nd-element.transition.extensions';
 import '../wrappers/prototypes/attributes-extensions';
 
+
 /**
+ * Creates a reactive or static text node from the given value.
+ * If the value has a .toNdElement() method, delegates to it.
+ * Otherwise creates an empty text node.
  *
- * @param {*} value
- * @returns {Text}
+ * @param {string|number|ObservableItem|*} value - Value to convert to a text node
+ * @returns {Text} Text node, reactive if value is an ObservableItem
  */
 export const createTextNode = (value) => {
     if(value) {
@@ -23,19 +27,41 @@ export const createTextNode = (value) => {
 };
 
 
+/**
+ * Applies attributes and children to an existing HTMLElement.
+ * Used internally by HtmlElementWrapper on each cloned node.
+ *
+ * @internal
+ * @param {HTMLElement} element - Element to configure
+ * @param {Object|null} _attributes - Attributes object or children if no attrs provided
+ * @param {ValidChild|null} [_children=null] - Children to append
+ * @returns {HTMLElement} The configured element
+ */
 export const createHtmlElement = (element, _attributes, _children = null) => {
-    let { props: attributes, children = null } = normalizeComponentArgs(_attributes, _children);
+    const { props: attributes, children = null } = normalizeComponentArgs(_attributes, _children);
 
     ElementCreator.processAttributes(element, attributes);
     ElementCreator.processChildren(children, element);
     return element;
-}
+};
 
 /**
+ * Creates a reusable element factory function for the given HTML tag.
+ * The factory clones a cached template node on each call for performance.
+ * Optionally wraps the created element with a custom wrapper function.
+ *
+ * @param {string} name - HTML tag name (e.g. 'div', 'button', 'input'). Pass empty string to create a Fragment.
+ * @param {((element: HTMLElement) => HTMLElement)|null} [customWrapper=null] - Optional function to augment the element before returning
+ * @returns {(attr?: Object, children?: ValidChild) => HTMLElement} Element factory function
+ * @example
+ * const Div = HtmlElementWrapper('div');
+ * Div({ class: 'container' }, 'Hello');
  *
- * @param {string} name
- * @param {?Function=} customWrapper
- * @returns {Function}
+ * // With custom wrapper
+ * const Form = HtmlElementWrapper('form', (el) => {
+ *   el.submit = (action) => { ... };
+ *   return el;
+ * });
  */
 export default function  HtmlElementWrapper(name, customWrapper = null) {
     if(name) {
@@ -49,7 +75,7 @@ export default function  HtmlElementWrapper(name, customWrapper = null) {
                 return createHtmlElement(customWrapper(node.cloneNode()), attr, children);;
             };
 
-            return (attr, children) => createElement(attr, children)
+            return (attr, children) => createElement(attr, children);
         }
 
         let node = null;
@@ -61,7 +87,7 @@ export default function  HtmlElementWrapper(name, customWrapper = null) {
             return createHtmlElement(node.cloneNode(), attr, children);
         };
 
-        return (attr, children) => createElement(attr, children)
+        return (attr, children) => createElement(attr, children);
     }
     return (children, name = '') => {
         const anchor = Anchor(name);