native-document 1.0.182 → 1.0.183

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-document",
-  "version": "1.0.182",
+  "version": "1.0.183",
   "description": "A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features",
   "author": "AfroCodeur <https://github.com/afrocodeur>",
   "license": "MIT",

package/src/components/menu/types/Menu.d.ts

@@ -1,24 +1,30 @@
 import type { ValidChild } from '../../../../types/elements';
 import type { ObservableItem } from '../../../../types/observable';
 import type { BaseComponent } from '../../BaseComponent';
-import type { MenuItemInterface } from './MenuItem';
+import type { MenuItemInterface, MenuItemOptions } from './MenuItem';
 import type { MenuGroupInterface } from './MenuGroup';
-import type { MenuLinkInterface } from './MenuLink';
+import type { MenuLinkInterface, MenuLinkOptions } from './MenuLink';
 import type { MenuDividerInterface } from './MenuDivider';
 import type { GlobalAttributes } from '../../../../types/globals';
 
 export type MenuDescription = {
-        items: ObservableItem<Array<MenuItemInterface | MenuGroupInterface | MenuDividerInterface>>;
-        render: ((desc: MenuDescription, instance: MenuInterface) => ValidChild) | null;
-        orientation: 'horizontal' | 'vertical' | 'inline';
-        closeOnSelect: boolean;
-        keyboardLoop: boolean;
-        activeItem: ObservableItem<MenuItemInterface | null>;
-        active: ((item: MenuItemInterface) => boolean) | null;
-        compactThreshold: number;
-        clickFirst: boolean;
-        props: GlobalAttributes;
-    };
+    items: ObservableItem<Array<MenuItemInterface | MenuGroupInterface | MenuDividerInterface>>;
+    render: ((desc: MenuDescription, instance: MenuInterface) => ValidChild) | null;
+    orientation: 'horizontal' | 'vertical' | 'inline';
+    closeOnSelect: boolean;
+    keyboardLoop: boolean;
+    activeItem: ObservableItem<MenuItemInterface | null>;
+    /** Observable tracking which item currently has an open submenu. */
+    menuActive: ObservableItem<MenuItemInterface | null>;
+    /** True once the user has clicked to activate hover-open behaviour. */
+    isMenuActivated: ObservableItem<boolean>;
+    /** Null until ResizeObserver fires; then true when below compactThreshold. */
+    compact: ObservableItem<boolean | null>;
+    active: ((item: MenuItemInterface) => boolean) | null;
+    compactThreshold: number;
+    clickFirst: boolean;
+    props: GlobalAttributes;
+};
 
 export interface MenuInterface extends BaseComponent {
     dataResolver(resolver: (data: unknown) => unknown): this;
@@ -33,28 +39,40 @@ export interface MenuInterface extends BaseComponent {
     active(callback: (item: MenuItemInterface) => boolean): this;
     onItemClick(handler: (item: MenuItemInterface, event: MouseEvent) => void): this;
     onItemSelect(handler: (item: MenuItemInterface) => void): this;
-    group(label: ValidChild, icon: ValidChild, builder: (group: MenuGroupInterface) => void, props?: Record<string, unknown>): this;
+    group(label: ValidChild, icon: ValidChild, builder: (group: MenuGroupInterface) => void, props?: GlobalAttributes): this;
     getItem(key: string): MenuItemInterface | undefined;
     compactThreshold(width?: number): this;
     clickFirst(mode?: boolean): this;
-    item(label: ValidChild, ...args: unknown[]): this;
-    link(label: ValidChild, ...args: unknown[]): this;
+
+    item(label: ValidChild): this;
+    item(label: ValidChild, configBuilder: (item: MenuItemInterface) => void): this;
+    item(label: ValidChild, options: MenuItemOptions): this;
+    item(label: ValidChild, options: MenuItemOptions, configBuilder: (item: MenuItemInterface) => void): this;
+    item(label: ValidChild, options: MenuItemOptions, configBuilder: (item: MenuItemInterface) => void, props: GlobalAttributes): this;
+
+    link(label: ValidChild): this;
+    link(label: ValidChild, configBuilder: (item: MenuLinkInterface) => void): this;
+    link(label: ValidChild, options: MenuLinkOptions): this;
+    link(label: ValidChild, options: MenuLinkOptions, configBuilder: (item: MenuLinkInterface) => void): this;
+    link(label: ValidChild, options: MenuLinkOptions, configBuilder: (item: MenuLinkInterface) => void, props: GlobalAttributes): this;
+
+    linkTo(label: ValidChild): this;
+    linkTo(label: ValidChild, configBuilder: (item: MenuLinkInterface) => void): this;
+    linkTo(label: ValidChild, options: MenuLinkOptions): this;
+    linkTo(label: ValidChild, options: MenuLinkOptions, configBuilder: (item: MenuLinkInterface) => void): this;
+    linkTo(label: ValidChild, options: MenuLinkOptions, configBuilder: (item: MenuLinkInterface) => void, props: GlobalAttributes): this;
+
     separator(): this;
     divider(): this;
     add(item: MenuItemInterface | MenuGroupInterface | MenuLinkInterface | MenuDividerInterface): this;
     getDepth(): number;
-    getRoot(): unknown;
+    getRoot(): MenuInterface;
+    setParent(parent: MenuInterface | MenuGroupInterface): this;
     onClicked(): this;
     onHovered(): this;
-    render(template: (description: MenuDescription, instance: MenuInterface) => ValidChild): this;
 }
 
-
-export declare function Menu(props?: Record<string, unknown>): MenuInterface;
+export declare function Menu(props?: GlobalAttributes): MenuInterface;
 export declare namespace Menu {
-
-
     function use(template: (description: MenuDescription, instance: MenuInterface) => ValidChild): void;
-
-
-}
+}

package/src/components/menu/types/MenuGroup.d.ts

@@ -1,44 +1,68 @@
 import type { ValidChild } from '../../../../types/elements';
 import type { ObservableItem } from '../../../../types/observable';
 import type { BaseComponent } from '../../BaseComponent';
-import type { MenuItemInterface } from './MenuItem';
+import type { MenuItemInterface, MenuItemOptions } from './MenuItem';
+import type { MenuLinkInterface, MenuLinkOptions } from './MenuLink';
 import type { MenuDividerInterface } from './MenuDivider';
 import type { GlobalAttributes } from '../../../../types/globals';
 
 export type MenuGroupDescription = {
-        icon: ValidChild | null;
-        label: ValidChild;
-        data: unknown | null;
-        items: ObservableItem<Array<MenuItemInterface | MenuDividerInterface>>;
-        render: ((desc: MenuGroupDescription, instance: MenuGroupInterface) => ValidChild) | null;
-        collapsable: boolean;
-        collapsed: boolean | null;
-        visibility: ObservableItem<boolean>;
-        collapsableOpenedIcon: ValidChild | null;
-        collapsableClosedIcon: ValidChild | null;
-        props: GlobalAttributes;
-    };
+    icon: ValidChild | null;
+    label: ValidChild;
+    data: unknown | null;
+    items: ObservableItem<Array<MenuItemInterface | MenuDividerInterface>>;
+    render: ((desc: MenuGroupDescription, instance: MenuGroupInterface) => ValidChild) | null;
+    collapsable: boolean;
+    /**
+     * Null until .collapsable() is called — then an ObservableItem<boolean>.
+     * The render uses .toggle() and .transform() on this value; it is never
+     * a plain boolean at runtime.
+     */
+    collapsed: ObservableItem<boolean> | null;
+    visibility: ObservableItem<boolean>;
+    collapsableOpenedIcon: ValidChild | null;
+    collapsableClosedIcon: ValidChild | null;
+    props: GlobalAttributes;
+};
 
 export interface MenuGroupInterface extends BaseComponent {
     data(data: unknown): this;
     icon(icon: ValidChild): this;
     collapsable(mode?: boolean, openedIcon?: ValidChild, closedIcon?: ValidChild): this;
     collapsed(mode?: boolean): this;
-    divider(): this;
     visibility(mode: boolean | ObservableItem<boolean>): this;
-    item(label: ValidChild, ...args: unknown[]): this;
-    link(label: ValidChild, ...args: unknown[]): this;
+
+    item(label: ValidChild): this;
+    item(label: ValidChild, configBuilder: (item: MenuItemInterface) => void): this;
+    item(label: ValidChild, options: MenuItemOptions): this;
+    item(label: ValidChild, options: MenuItemOptions, configBuilder: (item: MenuItemInterface) => void): this;
+    item(label: ValidChild, options: MenuItemOptions, configBuilder: (item: MenuItemInterface) => void, props: GlobalAttributes): this;
+
+    link(label: ValidChild): this;
+    link(label: ValidChild, configBuilder: (item: MenuLinkInterface) => void): this;
+    link(label: ValidChild, options: MenuLinkOptions): this;
+    link(label: ValidChild, options: MenuLinkOptions, configBuilder: (item: MenuLinkInterface) => void): this;
+    link(label: ValidChild, options: MenuLinkOptions, configBuilder: (item: MenuLinkInterface) => void, props: GlobalAttributes): this;
+
+    linkTo(label: ValidChild): this;
+    linkTo(label: ValidChild, configBuilder: (item: MenuLinkInterface) => void): this;
+    linkTo(label: ValidChild, options: MenuLinkOptions): this;
+    linkTo(label: ValidChild, options: MenuLinkOptions, configBuilder: (item: MenuLinkInterface) => void): this;
+    linkTo(label: ValidChild, options: MenuLinkOptions, configBuilder: (item: MenuLinkInterface) => void, props: GlobalAttributes): this;
+
+    group(label: ValidChild, builder: (group: MenuGroupInterface) => void): this;
     separator(): this;
-    add(item: MenuItemInterface | MenuDividerInterface): this;
+    divider(): this;
+    add(item: MenuItemInterface | MenuGroupInterface | MenuLinkInterface | MenuDividerInterface): this;
+    getDepth(): number;
+    getRoot(): unknown;
+    setParent(parent: unknown): this;
+    onClicked(): this;
+    onHovered(): this;
     render(template: (description: MenuGroupDescription, instance: MenuGroupInterface) => ValidChild): this;
 }
 
-
-export declare function MenuGroup(label: ValidChild, props?: Record<string, unknown>): MenuGroupInterface;
+export declare function MenuGroup(label: ValidChild, props?: GlobalAttributes): MenuGroupInterface;
 export declare namespace MenuGroup {
-
-
     function use(template: (description: MenuGroupDescription, instance: MenuGroupInterface) => ValidChild): void;
-
-
-}
+}

package/src/components/menu/types/MenuItem.d.ts

@@ -3,21 +3,30 @@ import type { ObservableItem } from '../../../../types/observable';
 import type { BaseComponent } from '../../BaseComponent';
 import type { GlobalAttributes } from '../../../../types/globals';
 
+export type MenuItemOptions = {
+    icon?: ValidChild;
+    action?: string | Record<string, unknown> | ((data?: unknown) => void);
+    shortcut?: ValidChild;
+    disabled?: boolean | ObservableItem<boolean>;
+};
+
 export type MenuItemDescription = {
-        key: string | null;
-        action: string | Record<string, unknown> | null;
-        label: ValidChild | null;
-        icon: ValidChild | null;
-        shortcut: ValidChild | null;
-        disabled: ObservableItem<boolean> | boolean | null;
-        selected: ObservableItem<boolean> | boolean | null;
-        value: unknown;
-        data: unknown | null;
-        render: ((desc: MenuItemDescription, instance: MenuItemInterface) => ValidChild) | null;
-        trailing: ValidChild | null;
-        visibility: ObservableItem<boolean> | null;
-        props: GlobalAttributes;
-    };
+    key: string | null;
+    action: string | Record<string, unknown> | ((data?: unknown) => void) | null;
+    label: ValidChild | null;
+    icon: ValidChild | null;
+    shortcut: ValidChild | null;
+    disabled: ObservableItem<boolean> | boolean | null;
+    selected: ObservableItem<boolean> | boolean | null;
+    value: unknown;
+    data: unknown | null;
+    render: ((desc: MenuItemDescription, instance: MenuItemInterface) => ValidChild) | null;
+    trailing: ValidChild | null;
+    visibility: ObservableItem<boolean> | null;
+    dataResolver: (() => unknown) | null;
+    interaction: 'click' | 'hover' | null;
+    props: GlobalAttributes;
+};
 
 export interface MenuItemInterface extends BaseComponent {
     label(label: ValidChild): this;
@@ -27,20 +36,43 @@ export interface MenuItemInterface extends BaseComponent {
     disabled(disabled?: boolean | ObservableItem<boolean>): this;
     selected(selected?: boolean | ObservableItem<boolean>): this;
     value(value: unknown): this;
-    action(action: string | Record<string, unknown>): this;
+    action(action: string | Record<string, unknown> | ((data?: unknown) => void)): this;
     data(data: unknown): this;
-    divider(): this;
     key(key: string): this;
     visibility(mode: boolean | ObservableItem<boolean>): this;
-    render(template: (description: MenuItemDescription, instance: MenuItemInterface) => ValidChild): this;
-}
 
+    item(label: ValidChild): this;
+    item(label: ValidChild, configBuilder: (item: MenuItemInterface) => void): this;
+    item(label: ValidChild, options: MenuItemOptions): this;
+    item(label: ValidChild, options: MenuItemOptions, configBuilder: (item: MenuItemInterface) => void): this;
+    item(label: ValidChild, options: MenuItemOptions, configBuilder: (item: MenuItemInterface) => void, props: GlobalAttributes): this;
 
-export declare function MenuItem(props?: Record<string, unknown>): MenuItemInterface;
-export declare namespace MenuItem {
-
-
-    function use(template: (description: MenuItemDescription, instance: MenuItemInterface) => ValidChild): void;
+    link(label: ValidChild): this;
+    link(label: ValidChild, configBuilder: (item: import('./MenuLink').MenuLinkInterface) => void): this;
+    link(label: ValidChild, options: import('./MenuLink').MenuLinkOptions): this;
+    link(label: ValidChild, options: import('./MenuLink').MenuLinkOptions, configBuilder: (item: import('./MenuLink').MenuLinkInterface) => void): this;
+    link(label: ValidChild, options: import('./MenuLink').MenuLinkOptions, configBuilder: (item: import('./MenuLink').MenuLinkInterface) => void, props: GlobalAttributes): this;
 
+    linkTo(label: ValidChild): this;
+    linkTo(label: ValidChild, configBuilder: (item: import('./MenuLink').MenuLinkInterface) => void): this;
+    linkTo(label: ValidChild, options: import('./MenuLink').MenuLinkOptions): this;
+    linkTo(label: ValidChild, options: import('./MenuLink').MenuLinkOptions, configBuilder: (item: import('./MenuLink').MenuLinkInterface) => void): this;
+    linkTo(label: ValidChild, options: import('./MenuLink').MenuLinkOptions, configBuilder: (item: import('./MenuLink').MenuLinkInterface) => void, props: GlobalAttributes): this;
 
+    group(label: ValidChild, builder: (group: unknown) => void): this;
+    separator(): this;
+    divider(): this;
+    add(item: unknown): this;
+    getDepth(): number;
+    getRoot(): unknown;
+    setParent(parent: unknown): this;
+    onClicked(): this;
+    onHovered(): this;
+    emit(eventName: string, ...args: unknown[]): void;
+    render(template: (description: MenuItemDescription, instance: MenuItemInterface) => ValidChild): this;
 }
+
+export declare function MenuItem(props?: GlobalAttributes): MenuItemInterface;
+export declare namespace MenuItem {
+    function use(template: (description: MenuItemDescription, instance: MenuItemInterface) => ValidChild): void;
+}

package/src/components/menu/types/MenuLink.d.ts

@@ -1,16 +1,26 @@
 import type { ValidChild } from '../../../../types/elements';
+import type { ObservableItem } from '../../../../types/observable';
 import type { MenuItemInterface, MenuItemDescription } from './MenuItem';
+import type { GlobalAttributes } from '../../../../types/globals';
+
+export type MenuLinkOptions = {
+    icon?: ValidChild;
+    /** URL string or named route name. Used as-is for link(), wrapped in { isRoute: true } for linkTo(). */
+    href?: string;
+    target?: '_blank' | '_self' | '_parent' | '_top' | string;
+    shortcut?: ValidChild;
+    disabled?: boolean | ObservableItem<boolean>;
+};
+
+export type MenuLinkDescription = MenuItemDescription & {
+    target: '_blank' | '_self' | '_parent' | '_top' | string | null;
+};
 
 export interface MenuLinkInterface extends MenuItemInterface {
     target(target: '_blank' | '_self' | '_parent' | '_top' | string): this;
 }
 
-
-export declare function MenuLink(props?: Record<string, unknown>): MenuLinkInterface;
+export declare function MenuLink(props?: GlobalAttributes): MenuLinkInterface;
 export declare namespace MenuLink {
-
-
-    function use(template: (description: MenuItemDescription, instance: MenuLinkInterface) => ValidChild): void;
-
-
-}
+    function use(template: (description: MenuLinkDescription, instance: MenuLinkInterface) => ValidChild): void;
+}

package/src/core/elements/anchor/anchor.js

@@ -35,7 +35,7 @@ export default function Anchor(name, isUniqueChild = false) {
         ? () => true: (parent) => (parent.firstChild === anchorStart && parent.lastChild === anchorEnd);
 
     const insertBefore = (parent, child, target) => {
-        const childElement = child.__$isNativeNode ? child : ElementCreator.getChild(child);
+        const childElement = ElementCreator.getChild(child);
         insertBeforeRaw(parent, childElement, target);
     };
 

package/src/core/elements/control/for-each-array-cache.js

@@ -10,6 +10,8 @@ export default function ForEachArrayCache(isIndexesRequired) {
         return Array.from(this.$nodes.keys());
     };
 
+    this.entries = this.$nodes.entries.bind(this.$nodes);
+
     if(isIndexesRequired) {
         this.delete = function(item) {
             this.$nodes.get(item)?.nd.destroy();

package/src/core/wrappers/AttributesWrapper.js

@@ -35,7 +35,7 @@ export const bindClassAttribute = (element, data) => {
         }
 
         if (value.$hydrate) {
-            value.$hydrate(element, className);
+            value.$hydrate(element, className, 'class');
             return;
         }
 
@@ -85,6 +85,10 @@ export const bindStyleAttribute = (element, data) => {
             continue;
         }
 
+        if(value.$hydrate) {
+            value.$hydrate(element, styleName, 'style');
+        }
+
         element.style[styleName] = value;
     }
 };
@@ -167,6 +171,10 @@ const AttributesWrapper = (element, attributes = {}) => {
             element.setAttribute(attributeName, value);
             continue;
         }
+        if(value.$hydrate) {
+            value.$hydrate(element,  attributeName, 'attribute');
+            continue;
+        }
         // const attributeName = originalAttributeName.toLowerCase();
         if(value.__$Observable) {
             if(BOOLEAN_ATTRIBUTES.has(attributeName)) {
@@ -190,9 +198,10 @@ const AttributesWrapper = (element, attributes = {}) => {
             bindBooleanAttribute(element, attributeName, value);
             continue;
         }
-        if(value.__$isTemplateBinding) {
-            value.$hydrate(element, attributeName);
-        }
+
+        // if(value.__$isTemplateBinding) {
+        //     // value.$hydrate(element, attributeName, 'attribute');
+        // }
 
         element.setAttribute(attributeName, value);
     }

package/src/core/wrappers/ElementCreator.js

@@ -41,7 +41,7 @@ export const ElementCreator = {
      */
     createHydratableNode: (parent, item) => {
         const text = ElementCreator.createTextNode();
-        item.$hydrate(text);
+        item.$hydrate(text, null, 'value');
         return text;
     },
 

package/src/core/wrappers/NdPrototype.js

@@ -28,6 +28,10 @@ EVENTS.forEach(eventSourceName => {
     const inlineHandler = 'on'+eventName;
     const fnName = 'on'+eventSourceName;
     NDElement.prototype[fnName] = function(callback = null, options = null) {
+        if(callback.__$isTemplateBinding) {
+            this.attach(fnName, callback);
+            return this;
+        }
         if(!this.$element[inlineHandler] && !options) {
             this.$element[inlineHandler] = callback;
             return this;
@@ -37,37 +41,58 @@ EVENTS.forEach(eventSourceName => {
     };
     if(!HTMLElement.prototype[fnName]) {
         HTMLElement.prototype[fnName] = function(callback, options) {
+            if(callback.__$isTemplateBinding) {
+                this.nd.attach(fnName, callback);
+                return this;
+            }
             if(!this[inlineHandler] && !options) {
                 this[inlineHandler] = callback;
                 return this;
             }
             this.addEventListener(eventName, callback, options);
             return this;
-        }
+        };
     }
 });
 
 EVENTS_WITH_STOP.forEach(eventSourceName => {
     const eventName = eventSourceName.toLowerCase();
     const stopFnName = 'onStop'+eventSourceName;
-    const preventStopFnName = 'onPreventStop'+eventSourceName;
 
     NDElement.prototype[stopFnName] = function(callback = null, options = null) {
+        if(callback.__$isTemplateBinding) {
+            this.attach(stopFnName, callback);
+            return this;
+        }
         _stop(this.$element, eventName, callback, options);
         return this;
     };
-    NDElement.prototype[preventStopFnName] = function(callback = null, options = null) {
-        _preventStop(this.$element, eventName, callback, options);
-        return this;
-    };
-    if(HTMLElement.prototype[stopFnName]) {
+    if(!HTMLElement.prototype[stopFnName]) {
         HTMLElement.prototype[stopFnName] = function(callback = null, options = null) {
+            if(callback.__$isTemplateBinding) {
+                this.nd.attach(stopFnName, callback);
+                return this;
+            }
             _stop(this, eventName, callback, options);
             return this;
         };
     }
+    // ------
+    const preventStopFnName = 'onPreventStop'+eventSourceName;
+    NDElement.prototype[preventStopFnName] = function(callback = null, options = null) {
+        if(callback.__$isTemplateBinding) {
+            this.attach(preventStopFnName, callback);
+            return this;
+        }
+        _preventStop(this.$element, eventName, callback, options);
+        return this;
+    };
     if(!HTMLElement.prototype[preventStopFnName]) {
         HTMLElement.prototype[preventStopFnName] = function(callback = null, options = null) {
+            if(callback.__$isTemplateBinding) {
+                this.nd.attach(preventStopFnName, callback);
+                return this;
+            }
             _preventStop(this, eventName, callback, options);
             return this;
         };
@@ -78,11 +103,19 @@ EVENTS_WITH_PREVENT.forEach(eventSourceName => {
     const eventName = eventSourceName.toLowerCase();
     const preventFnName = 'onPrevent'+eventSourceName;
     NDElement.prototype[preventFnName] = function(callback = null, options = null) {
+        if(callback.__$isTemplateBinding) {
+            this.attach(preventFnName, callback);
+            return this;
+        }
         _prevent(this.$element, eventName, callback, options);
         return this;
     };
-    if(HTMLElement.prototype[preventFnName]) {
+    if(!HTMLElement.prototype[preventFnName]) {
         HTMLElement.prototype[preventFnName] = function(callback = null, options = null) {
+            if(callback.__$isTemplateBinding) {
+                this.nd.attach(preventFnName, callback);
+                return this;
+            }
             _prevent(this, eventName, callback, options);
             return this;
         };

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

@@ -1,6 +1,7 @@
 import {ElementCreator} from '../ElementCreator';
 import {createTextNode} from '../HtmlElementWrapper';
 import {NDElement} from '../NDElement';
+import {call} from '@babel/traverse/lib/path/context';
 
 /**
  * Stores deferred attribute, class, style, and event bindings for a cloneable element.
@@ -49,11 +50,17 @@ NodeCloner.prototype.__$isNodeCloner = true;
 
 const buildProperties = (cache, properties, data) => {
     for(const key in properties) {
-        cache[key] = properties[key].apply(null, data);
+        const value = properties[key];
+        cache[key] = getPropertyValue(value, data);
     }
     return cache;
 };
 
+const getPropertyValue = (callbackOrProperty, data) => {
+    const value = (typeof callbackOrProperty ==='string') ? data[0][callbackOrProperty] :  callbackOrProperty;
+    return (typeof value === 'function') ? value.apply(this, data) : value;
+};
+
 /**
  * Pre-compiles all registered bindings into a sequence of optimised steps.
  * Called once before the first clone operation. Subsequent calls are no-ops.
@@ -71,13 +78,14 @@ NodeCloner.prototype.resolve = function() {
             const methodName = methods[0];
             const callback = this.$ndMethods[methodName];
             steps.push((clonedNode, data) => {
-                clonedNode.nd[methodName](callback.bind(clonedNode, ...data));
+                clonedNode.nd[methodName](callback.length === 0 ? callback : callback.bind(clonedNode, ...data));
             });
         } else {
             steps.push((clonedNode, data) => {
                 const nd = clonedNode.nd;
                 for(const methodName in this.$ndMethods) {
-                    nd[methodName](this.$ndMethods[methodName].bind(clonedNode, ...data));
+                    const callback  = this.$ndMethods[methodName];
+                    nd[methodName](callback.length === 0 ? callback : this.$ndMethods[methodName].bind(clonedNode, ...data));
                 }
             });
         }
@@ -90,7 +98,7 @@ NodeCloner.prototype.resolve = function() {
             const key = keys[0];
             const callback = this.$classes[key];
             steps.push((clonedNode, data) => {
-                cache[key] = callback.apply(null, data);
+                cache[key] = getPropertyValue(callback, data);
                 ElementCreator.processClassAttribute(clonedNode, cache);
             });
         } else {
@@ -107,7 +115,7 @@ NodeCloner.prototype.resolve = function() {
             const key = keys[0];
             const callback = this.$styles[key];
             steps.push((clonedNode, data) => {
-                cache[key] = callback.apply(null, data);
+                cache[key] = getPropertyValue(callback, data);
                 ElementCreator.processStyleAttribute(clonedNode, cache);
             });
         } else {
@@ -124,7 +132,7 @@ NodeCloner.prototype.resolve = function() {
             const key = keys[0];
             const callback = this.$attrs[key];
             steps.push((clonedNode, data) => {
-                cache[key] = callback.apply(null, data);
+                cache[key] = getPropertyValue(callback, data);
                 ElementCreator.processAttributes(clonedNode, cache);
             });
         } else {
@@ -207,7 +215,8 @@ NodeCloner.prototype.attr = function(attrName, value) {
         this.$styles[value.property] = value.value;
         return this;
     }
+
     this.$attrs = this.$attrs || {};
-    this.$attrs[attrName] = value.value;
+    this.$attrs[value.property] = value.value;
     return this;
 };

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

@@ -1,6 +1,8 @@
 import TemplateBinding from '../TemplateBinding';
 import { $hydrateFn} from './utils';
 import NodeCloner from './NodeCloner';
+import {ElementCreator} from '../ElementCreator';
+import NativeDocumentError from '../../errors/NativeDocumentError';
 
 /**
  * Creates a high-performance template cloner for repeated rendering of the same structure.
@@ -22,7 +24,10 @@ import NodeCloner from './NodeCloner';
 export function TemplateCloner($fn) {
     let $node = null;
 
+    this.$scopeDataBuilder = null;
+
     const assignClonerToNode = ($node) => {
+        $node = ElementCreator.getChild($node);
         const childNodes = $node.childNodes;
         let containDynamicNode = $node.nodeCloner?.shouldBeHydrate();
         const childNodesLength = childNodes.length;
@@ -73,20 +78,45 @@ export function TemplateCloner($fn) {
      */
     this.clone = (data) => {
         const binder = createTemplateCloner(this);
-        $node = $fn(binder);
+        const helpers = {
+            useCallback: binder.attach.bind(binder),
+            useCallbacks: (callbacks) => {
+                for(const key in callbacks) {
+                    callbacks[key] = binder.attach(callbacks[key]);
+                }
+                return callbacks;
+            },
+            useData: (callback) => {
+                this.$scopeDataBuilder = callback;
+            },
+            use: binder.freeProps.bind(binder),
+        };
+        $node = ElementCreator.getChild($fn(binder, helpers));
         if(!$node.nodeCloner) {
             $node.nodeCloner = new NodeCloner($node);
         }
         assignClonerToNode($node);
+        if(this.$scopeDataBuilder) {
+            this.clone = (data) => {
+                const scopeData = this.scopeData();
+                return $node.dynamicCloneNode([...data, scopeData]);
+            };
+            return $node.dynamicCloneNode([...data, this.scopeData()]);
+        }
+
         this.clone = $node.dynamicCloneNode;
         return $node.dynamicCloneNode(data);
     };
 
+    this.scopeData = () => {
+        return this.$scopeDataBuilder?.() || {};
+    };
+
 
     const createBinding = (hydrateFunction, targetType) => {
         return new TemplateBinding((element, property) => {
             $hydrateFn(hydrateFunction, targetType, element, property);
-        });
+        }, this);
     };
 
     /**
@@ -113,6 +143,18 @@ export function TemplateCloner($fn) {
         return this.value(propertyName);
     };
 
+    this.data = (property) => {
+        return this.freeProps((...Args) => {
+            const data = Args.at(-1);
+            if(process.env.NODE_ENV === 'development') {
+                if(!data[property]) {
+                    throw new NativeDocumentError(property + ' is not defined in useData');
+                }
+            }
+            return data[property];
+        });
+    };
+
     /**
      * Creates a text/value binding — the result is set as text content or input value.
      * Alias: .text()
@@ -142,6 +184,16 @@ export function TemplateCloner($fn) {
         return createBinding(fn, 'attributes');
     };
 
+    this.freeProps = (callbackOrProperty) => {
+        return new TemplateBinding((element, property, type) => {
+            let targetType = type;
+            if(type === 'attribute') {
+                targetType = 'attributes';
+            }
+            $hydrateFn(callbackOrProperty, targetType, element, property);
+        });
+    };
+
     /**
      * Creates an event binding — fn(data) returns the event handler to attach.
      *
@@ -155,6 +207,13 @@ export function TemplateCloner($fn) {
     this.callback = this.attach;
 }
 
+const createDataProxy = ($binder) => {
+    return new Proxy($binder, {
+        get(target, key) {
+            return target.data(key);
+        },
+    });
+};
 
 const createTemplateCloner = ($binder) => {
     return new Proxy($binder, {
@@ -162,18 +221,98 @@ const createTemplateCloner = ($binder) => {
             if(prop in target) {
                 return target[prop];
             }
-            if (typeof prop === 'symbol') return target[prop];
-            return target.value(prop);
+            if (typeof prop === 'symbol') {
+                return target[prop];
+            }
+            if(prop === '$data') {
+                return createDataProxy($binder);
+            }
+            return target.freeProps(prop);
         },
     });
 };
 
+/**
+ * Creates a high-performance template factory that compiles once and clones efficiently.
+ * The template function is called only on the first render to build and optimise the DOM
+ * structure. Subsequent calls clone the compiled result and hydrate it with new data.
+ *
+ * Execution happens in three distinct phases:
+ *
+ * **Phase 1 — Compilation** (runs once, on first call)
+ * The template function receives `$scope` — a binding proxy. Accessing `$scope.name`,
+ * `$scope.color` etc. declares bindings on the template node without reading values yet.
+ * `$scope.$data` provides direct bindings to local state properties declared via `useData`.
+ * The DOM structure is built and optimised during this phase.
+ *
+ * **Phase 2 — Hydration** (runs once per clone)
+ * `useData(() => ({ ... }))` creates isolated local state for each cloned instance.
+ * The factory is called once per item — every clone gets its own independent state object.
+ *
+ * **Phase 3 — Runtime** (runs on each interaction or reactive update)
+ * `useCallback`, `useCallbacks` and `use` callbacks receive the same arguments as the
+ * template function, plus the local state object as the last argument:
+ * - `item`  — the actual item data at the time of execution
+ * - `index` — position in the list (when used with ForEachArray)
+ * - `data`  — the local state for this specific clone (from useData)
+ *
+ * @template T
+ * @param {(
+ *   $scope: T & { $data: Record<string, any> },
+ *   helpers: {
+ *     useData: (factory: () => Record<string, any>) => void,
+ *     useCallback: (fn: (item: T, index: number, data: Record<string, any>) => EventListener) => TemplateBinding,
+ *     useCallbacks: (callbacks: Record<string, (item: T, index: number, data: Record<string, any>) => EventListener>) => Record<string, TemplateBinding>,
+ *     use: (fn: (item: T, index: number, data: Record<string, any>) => any) => TemplateBinding,
+ *   }
+ * ) => HTMLElement} fn - Template builder function called once during compilation
+ * @returns {(item: T, index?: number) => HTMLElement} Factory function — pass directly to ForEachArray or call manually
+ *
+ * @example
+ * const UserRow = useCache(($scope, { useData, useCallback, useCallbacks, use }) => {
+ *
+ *     // Phase 1 — declare bindings (runs once)
+ *     const color = $scope.color;
+ *     // Bind directly from local state via $scope.$data
+ *     const selectedClass = $scope.$data.selected;
+ *
+ *     // Phase 2 — local state per clone (runs once per item)
+ *     useData(() => ({
+ *         selected: $(false),
+ *     }));
+ *
+ *     // Phase 3 — runtime callbacks (run on interaction)
+ *
+ *     // Single callback
+ *     const toggle = useCallback((item, index, data) => {
+ *         data.selected.toggle();
+ *     });
+ *
+ *     // Multiple callbacks at once
+ *     const { select, deselect } = useCallbacks({
+ *         select:   (item, index, data) => data.selected.set(true),
+ *         deselect: (item, index, data) => data.selected.set(false),
+ *     });
+ *
+ *     const isSelected = use((item, index, data) => {
+ *         return data.selected.val() ? 'is-selected' : '';
+ *     });
+ *
+ *     return Div({ class: isSelected, style: { color } }, Strong($scope.name))
+ *         .onClick(toggle);
+ * });
+ *
+ * // Pass directly to ForEachArray
+ * ForEachArray($users, UserRow)
+ *
+ * // Or call manually
+ * UserRow(item, index)
+ */
 export function useCache(fn) {
     let $cache = null;
 
     let wrapper = (args) => {
         $cache = new TemplateCloner(fn);
-
         const node = $cache.clone(args);
         wrapper = $cache.clone;
         return node;

package/src/ui/components/form/fields/SelectFieldRender.js

@@ -120,7 +120,12 @@ const buildSelectedLabel = ($desc) => {
         return $desc.selectedLabelRender($desc);
     }
 
-    return $desc.value.transform((val) => {
+    const dependencies = [$desc.value];
+    if(!Array.isArray($desc.options)) {
+        dependencies.push($desc.options);
+    }
+
+    return $.computed((val) => {
         if(!val || (Array.isArray(val) && val.length === 0)) {
             return $desc.placeholder || 'Select...';
         }
@@ -156,7 +161,7 @@ const buildSelectedLabel = ($desc) => {
         }
 
         return labels.join(', ');
-    });
+    }, dependencies);
 };
 
 const buildNativeSelect = ($desc) => {