native-document 1.0.19 → 1.0.21

package/docs/anchor.md

@@ -372,4 +372,7 @@ anchor.replaceContent(content2);
 - **[List Rendering](list-rendering.md)** - (ForEach | ForEachArray) and dynamic lists
 - **[Routing](routing.md)** - Navigation and URL management
 - **[State Management](state-management.md)** - Global state patterns
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management

package/docs/conditional-rendering.md

@@ -625,5 +625,8 @@ Now that you understand conditional rendering, explore these related topics:
 - **[Routing](routing.md)** - Navigation and URL management
 - **[State Management](state-management.md)** - Global state patterns
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
 - **[Anchor](anchor.md)** - Anchor

package/docs/core-concepts.md

@@ -510,5 +510,8 @@ Now that you understand NativeDocument's core concepts, explore these advanced t
 - **[Routing](routing.md)** - Navigation and URL management
 - **[State Management](state-management.md)** - Global state patterns
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
 - **[Anchor](anchor.md)** - Anchor

package/docs/elements.md

@@ -380,5 +380,8 @@ Now that you understand NativeDocument's elements, explore these advanced topics
 - **[Routing](routing.md)** - Navigation and URL management
 - **[State Management](state-management.md)** - Global state patterns
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
 - **[Anchor](anchor.md)** - Anchor

package/docs/extending-native-document-element.md

@@ -0,0 +1,268 @@
+# Extending NDElement - Custom Methods Guide
+
+NDElement is designed to be extensible, allowing developers to add custom methods that make their code more readable and maintainable. This guide shows how to create custom NDElement extensions for common patterns.
+
+## Why Extend NDElement?
+
+Extending NDElement allows you to:
+- **Encapsulate common patterns** into reusable methods
+- **Improve code readability** with domain-specific method names
+- **Reduce boilerplate** by abstracting complex event handling
+- **Create a consistent API** across your application
+
+## Basic Extension Pattern
+
+The simplest way to extend NDElement is by adding methods to its prototype:
+
+```javascript
+// Basic extension
+NDElement.prototype.customMethod = function(/* parameters */) {
+    // Your logic here
+    return this; // Return 'this' for method chaining
+};
+```
+
+## Common Extension Examples
+
+### 1. Keyboard Event Shortcuts
+
+Instead of writing complex keyboard event handlers, create semantic shortcuts:
+
+```javascript
+// Enter key handler
+NDElement.prototype.onEnter = function(callback) {
+    this.$element.addEventListener('keyup', e => {
+        if (e.key === 'Enter') {
+            callback(e);
+        }
+    });
+    return this;
+};
+
+// Escape key handler
+NDElement.prototype.onEscape = function(callback) {
+    this.$element.addEventListener('keyup', e => {
+        if (e.key === 'Escape') {
+            callback(e);
+        }
+    });
+    return this;
+};
+
+// Arrow keys handler
+NDElement.prototype.onArrowKey = function(callback) {
+    this.$element.addEventListener('keydown', e => {
+        if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(e.key)) {
+            callback(e, e.key);
+        }
+    });
+    return this;
+};
+
+// Usage
+Input({ type: 'text' })
+    .nd.onEnter(e => console.log('Form submitted'))
+    .onEscape(e => e.target.blur())
+    .onArrowKey((e, direction) => console.log('Arrow pressed:', direction));
+```
+
+### 2. Form Validation Extensions
+
+Create semantic validation methods:
+
+```javascript
+// Required field validation
+NDElement.prototype.required = function(message = 'This field is required') {
+    this.$element.addEventListener('blur', e => {
+        const value = e.target.value.trim();
+        if (!value) {
+            this.showError(message);
+        } else {
+            this.clearError();
+        }
+    });
+    return this;
+};
+
+// Email validation
+NDElement.prototype.email = function(message = 'Please enter a valid email') {
+    this.$element.addEventListener('blur', e => {
+        const email = e.target.value.trim();
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        if (email && !emailRegex.test(email)) {
+            this.showError(message);
+        } else {
+            this.clearError();
+        }
+    });
+    return this;
+};
+
+// Min length validation
+NDElement.prototype.minLength = function(length, message) {
+    message = message || `Minimum ${length} characters required`;
+    this.$element.addEventListener('input', e => {
+        if (e.target.value.length < length && e.target.value.length > 0) {
+            this.showError(message);
+        } else {
+            this.clearError();
+        }
+    });
+    return this;
+};
+
+// Error display helpers
+NDElement.prototype.showError = function(message) {
+    this.clearError();
+    const errorElement = Span({
+        class: 'error-message',
+        style: 'color: red; font-size: 0.8rem'
+    }, message);
+
+    this.$element.parentNode.appendChild(errorElement);
+    this.$element.classList.add('error');
+    return this;
+};
+
+NDElement.prototype.clearError = function() {
+    const parent = this.$element.parentNode;
+    const existingError = parent.querySelector('.error-message');
+    if (existingError) {
+        existingError.remove();
+    }
+    this.$element.classList.remove('error');
+    return this;
+};
+
+// Usage
+Input({ type: 'email', placeholder: 'Email' })
+    .nd.required()
+    .email();
+
+Input({ type: 'password', placeholder: 'Password' })
+    .nd.required()
+    .minLength(8, 'Password must be at least 8 characters');
+```
+
+### 3. Animation Extensions
+
+Create smooth animation helpers:
+
+```javascript
+// Fade in animation
+NDElement.prototype.fadeIn = function(duration = 300) {
+    this.$element.style.opacity = '0';
+    this.$element.style.transition = `opacity ${duration}ms ease-in-out`;
+    
+    requestAnimationFrame(() => {
+        this.$element.style.opacity = '1';
+    });
+    
+    return this;
+};
+
+// Fade out animation
+NDElement.prototype.fadeOut = function(duration = 300, callback) {
+    this.$element.style.transition = `opacity ${duration}ms ease-in-out`;
+    this.$element.style.opacity = '0';
+    
+    setTimeout(() => {
+        if (callback) callback();
+    }, duration);
+    
+    return this;
+};
+
+// Slide down animation
+NDElement.prototype.slideDown = function(duration = 300) {
+    const element = this.$element;
+    element.style.maxHeight = '0';
+    element.style.overflow = 'hidden';
+    element.style.transition = `max-height ${duration}ms ease-in-out`;
+    
+    requestAnimationFrame(() => {
+        element.style.maxHeight = element.scrollHeight + 'px';
+    });
+    
+    return this;
+};
+
+// Usage
+Div("Animated content")
+    .nd.onClick(function() {
+        this.nd.fadeOut(300, () => this.remove());
+    });
+```
+
+## Best Practices
+
+### 1. Always Return `this`
+Enable method chaining by returning the NDElement instance:
+
+```javascript
+NDElement.prototype.myMethod = function() {
+    // Your logic here
+    return this; // Enable chaining
+};
+```
+
+### 2. Use Descriptive Method Names
+Choose names that clearly describe what the method does:
+
+```javascript
+// Good
+NDElement.prototype.onEnter = function(callback) { /* ... */ };
+NDElement.prototype.fadeIn = function(duration) { /* ... */ };
+
+// Avoid
+NDElement.prototype.ke = function(callback) { /* ... */ }; // Unclear
+NDElement.prototype.doStuff = function() { /* ... */ }; // Too vague
+```
+
+### 3. Handle Edge Cases
+Always consider edge cases and provide sensible defaults:
+
+```javascript
+NDElement.prototype.fadeIn = function(duration = 300) {
+    // Ensure duration is valid
+    duration = Math.max(0, parseInt(duration) || 300);
+    
+    // Check if element exists
+    if (!this.$element) return this;
+    
+    // Your animation logic
+    return this;
+};
+```
+
+### 4. Document Your Extensions
+
+Always document your custom methods:
+
+```javascript
+/**
+ * Handles Enter key press events
+ * @param {Function} callback - Function to call when Enter is pressed
+ * @returns {NDElement} Returns this for method chaining
+ * @example
+ * Input().nd.onEnter(e => console.log('Enter pressed'));
+ */
+NDElement.prototype.onEnter = function(callback) {
+    this.$element.addEventListener('keyup', e => {
+        if (e.key === 'Enter') {
+            callback(e);
+        }
+    });
+    return this;
+};
+```
+
+By extending NDElement thoughtfully, you can create a powerful, domain-specific API that makes your code more readable, maintainable, and enjoyable to work with.
+
+## Next Steps
+
+Explore these related topics to build complete applications:
+
+- **[Args Validation](validation.md)** - Function Argument Validation
+- **[Memory Management](memory-management.md)** - Memory management
+- **[Anchor](anchor.md)** - Anchor

package/docs/getting-started.md

@@ -358,6 +358,9 @@ Now that you've built your first NativeDocument applications, explore these topi
 - **[Routing](routing.md)** - Navigation and URL management
 - **[State Management](state-management.md)** - Global state patterns
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
 - **[Anchor](anchor.md)** - Anchor
 

package/docs/lifecycle-events.md

@@ -98,6 +98,9 @@ document.body.appendChild(reusableComponent);
 
 Now that you understand lifecycle events, explore these related topics:
 
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
 - **[Anchor](anchor.md)** - Anchor
 

package/docs/list-rendering.md

@@ -603,5 +603,11 @@ const DebugList = ForEachArray(items, (item, index) => {
 Now that you understand list rendering, explore these related topics:
 
 - **[Conditional Rendering](conditional-rendering.md)** - Show/hide content dynamically
+- **[Routing](routing.md)** - Navigation and URL management
+- **[State Management](state-management.md)** - Global state patterns
+- **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[State Management](state-management.md)** - Managing application state
 - **[Memory Management](memory-management.md)** - Understanding cleanup and memory

package/docs/native-document-element.md

@@ -0,0 +1,279 @@
+# NDElement
+
+`NDElement` is a wrapper class that enhances native HTML elements with utility methods and simplified event handlers. It enables fluent DOM manipulation while preserving access to the underlying HTML element.
+
+## Accessing NDElement
+
+Every HTML element created with NativeDocument automatically has an `nd` property that returns an `NDElement` instance:
+
+```javascript
+const element = Div("Hello World");
+const ndElement = element.nd; // NDElement instance
+
+// Or directly with method chaining
+Div("Hello").nd.onClick(() => console.log("Clicked!"));
+```
+
+## Constructor
+
+```javascript
+new NDElement(element)
+```
+
+**Parameters:**
+- `element`: The HTML element to wrap
+
+## Properties
+
+### `$element`
+The encapsulated native HTML element.
+
+```javascript
+const div = Div("Content");
+const htmlElement = div.nd.$element; // Native HTMLDivElement
+```
+
+### `$observer`
+Lifecycle observer (used internally for DOM monitoring).
+
+## Event Handling Methods
+
+NDElement automatically generates methods for all standard DOM events with multiple variants:
+
+### Basic Events
+
+```javascript
+// Standard event
+element.nd.onClick(callback)
+element.nd.onMouseOver(callback)
+element.nd.onKeyDown(callback)
+
+// Examples
+Button("Click me").nd.onClick(e => console.log("Button clicked!"));
+Input().nd.onInput(e => console.log("Input changed:", e.target.value));
+```
+
+### Prevention Variants
+
+```javascript
+// Prevents default behavior
+element.nd.onPreventClick(callback) // preventDefault()
+element.nd.onPreventSubmit(callback)
+
+// Example
+Link({ href: "/page" }).nd.onPreventClick(e => {
+    // Link won't navigate, custom behavior
+    router.push("/page");
+});
+```
+
+### Propagation Stop Variants
+
+```javascript
+// Stops event propagation
+element.nd.onStopClick(callback) // stopPropagation()
+element.nd.onStopKeyDown(callback)
+
+// Example
+Div([
+    Button("Child").nd.onStopClick(e => {
+        console.log("Child clicked - won't bubble up");
+    })
+]).nd.onClick(() => console.log("This won't be called"));
+```
+
+### Combined Variants
+
+```javascript
+// Combines preventDefault() and stopPropagation()
+element.nd.onPreventStopSubmit(callback)
+element.nd.onPreventStopClick(callback)
+
+// Example
+Form().nd.onPreventStopSubmit(e => {
+    // Prevents submission AND stops propagation
+    handleFormSubmit(e);
+});
+```
+
+### Supported Events List
+
+All standard DOM events are supported with the 4 variants:
+
+**Mouse:** Click, DblClick, MouseDown, MouseEnter, MouseLeave, MouseMove, MouseOut, MouseOver, MouseUp, Wheel
+
+**Keyboard:** KeyDown, KeyPress, KeyUp
+
+**Form:** Blur, Change, Focus, Input, Invalid, Reset, Search, Select, Submit
+
+**Drag & Drop:** Drag, DragEnd, DragEnter, DragLeave, DragOver, DragStart, Drop
+
+**Media:** Abort, CanPlay, CanPlayThrough, DurationChange, Emptied, Ended, LoadedData, LoadedMetadata, LoadStart, Pause, Play, Playing, Progress, RateChange, Seeked, Seeking, Stalled, Suspend, TimeUpdate, VolumeChange, Waiting
+
+**Window:** AfterPrint, BeforePrint, BeforeUnload, Error, HashChange, Load, Offline, Online, PageHide, PageShow, Resize, Scroll, Unload
+
+## Utility Methods
+
+### `ref(target, name)`
+Assigns the HTML element to a property of a target object.
+
+```javascript
+const refs = {};
+Div("Content").nd.ref(refs, 'contentDiv');
+console.log(refs.contentDiv); // HTMLDivElement
+```
+
+### `htmlElement()` / `node()`
+Returns the native HTML element (alias for `$element`).
+
+```javascript
+const div = Div("Hello");
+const htmlElement = div.nd.htmlElement(); // HTMLDivElement
+const node = div.nd.node(); // Same thing, alias
+```
+
+### `remove()`
+Removes the element and cleans up its internal references.
+
+```javascript
+const element = Div("To be removed");
+element.nd.remove(); // Element removed and cleaned
+```
+
+### `unmountChildren()`
+Unmounts all child elements and cleans up their references.
+
+```javascript
+const container = Div([
+    Div("Child 1"),
+    Div("Child 2")
+]);
+container.nd.unmountChildren(); // Children cleaned up
+```
+
+## Lifecycle Management
+
+### `lifecycle(states)`
+Configures lifecycle callbacks.
+
+```javascript
+element.nd.lifecycle({
+    mounted: (element) => console.log("Element added to DOM"),
+    unmounted: (element) => console.log("Element removed from DOM")
+});
+```
+
+### `mounted(callback)`
+Shortcut to define only the mount callback.
+
+```javascript
+Div("Content").nd.mounted(element => {
+    console.log("Element is now in the DOM!");
+});
+```
+
+## Practical Examples
+
+### Custom Event Handler
+
+```javascript
+// Extending NDElement with a custom handler
+NDElement.prototype.onEnter = function(callback) {
+    this.$element.addEventListener('keyup', e => {
+        if (e.key === 'Enter') {
+            callback(e);
+        }
+    });
+    return this;
+};
+
+// Usage
+Input({ type: 'text' })
+    .nd.onEnter(e => console.log("Enter pressed!"));
+```
+
+### Fluent Chaining
+
+```javascript
+const interactiveButton = Button("Interactive")
+    .nd.onClick(e => console.log("Clicked"))
+    .nd.onMouseEnter(e => e.target.style.background = "blue")
+    .nd.onMouseLeave(e => e.target.style.background = "")
+    .nd.mounted(el => console.log("Button mounted"));
+
+// OR 
+
+const interactiveButton = Button("Interactive")
+    .nd.onClick(e => console.log("Clicked"))
+    .onMouseEnter(e => e.target.style.background = "blue")
+    .onMouseLeave(e => e.target.style.background = "")
+    .mounted(el => console.log("Button mounted"));
+
+```
+
+### Form with Event Handling
+
+```javascript
+const todoForm = Form([
+    Input({ type: 'text', value: newTodo })
+        .nd.onEnter(addTodo),
+    
+    Button('Add', { type: 'submit' })
+]).nd.onPreventSubmit(addTodo);
+```
+
+### Reference Management
+
+```javascript
+const components = {};
+
+const app = Div([
+    Input().nd.ref(components, 'input'),
+    Button('Focus Input').nd.onClick(() => {
+        components.input.focus();
+    })
+]);
+```
+
+## Integration with Observables
+
+NDElement works seamlessly with NativeDocument's Observable system:
+
+```javascript
+const isVisible = Observable(false);
+const message = Observable("Hello");
+
+Div([
+    Button("Toggle").nd.onClick(() => isVisible.set(!isVisible.val())),
+    ShowIf(isVisible, () => 
+        P(message).nd.onClick(() => 
+            message.set("Clicked!")
+        )
+    )
+]);
+```
+
+## Best Practices
+
+1. **Fluent chaining**: Use method chaining for concise syntax
+2. **Cleanup**: Call `remove()` to clean up dynamic elements
+3. **Extensions**: Add your own methods to the prototype for specific needs
+4. **Lifecycle**: Use `mounted`/`unmounted` for initialization/cleanup
+5. **References**: Use `ref()` for direct element access when needed
+
+## Limitations
+
+- Event handlers are not automatically removed (manual management required if needed)
+- Access to native HTML element is still necessary for advanced APIs
+
+NDElement thus provides a practical abstraction layer while preserving the power and performance of native DOM.
+
+
+## Next Steps
+
+Explore these related topics to build complete applications:
+
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
+- **[Memory Management](memory-management.md)** - Memory management
+- **[Anchor](anchor.md)** - Anchor

package/docs/observables.md

@@ -542,5 +542,8 @@ Now that you understand NativeDocument's observable, explore these advanced topi
 - **[Routing](routing.md)** - Navigation and URL management
 - **[State Management](state-management.md)** - Global state patterns
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
 - **[Anchor](anchor.md)** - Anchor

package/docs/routing.md

@@ -813,5 +813,8 @@ Explore these related topics to build complete applications:
 
 - **[State Management](state-management.md)** - Global state patterns
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
 - **[Anchor](anchor.md)** - Anchor

package/docs/state-management.md

@@ -419,5 +419,8 @@ const createAppState = () => {
 Now that you understand state management, explore these related topics:
 
 - **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](validation.md)** - Function Argument Validation
 - **[Memory Management](memory-management.md)** - Memory management
 - **[Anchor](anchor.md)** - Anchor

package/docs/validation.md

@@ -187,5 +187,7 @@ registerUser.args(
 
 ## Next Steps
 
-- **[Memory Management](memory-management.md)** - Debugging memory issues with validation
-- **[Lifecycle Events](lifecycle-events.md)** - Validate lifecycle callback arguments
+- **[Lifecycle Events](lifecycle-events.md)** - Validate lifecycle callback arguments
+- **[NDElement](native-document-element.md)** - Native Document Element
+- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
+- **[Memory Management](memory-management.md)** - Debugging memory issues with validation

package/eslint.config.js

@@ -0,0 +1,22 @@
+import js from '@eslint/js'
+import globals from 'globals'
+
+export default [
+  { ignores: ['dist'] },
+  {
+    files: ['**/*.{js}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+    },
+    plugins: {
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+    },
+  },
+]

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "native-document",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "build": "rollup --config rollup.config.js --watch"
+    "build": "rollup --config rollup.config.js --watch",
+    "lint": "eslint ."
   },
   "keywords": [],
   "author": "",
@@ -12,6 +13,7 @@
   "description": "",
   "devDependencies": {
     "@rollup/plugin-replace": "^6.0.2",
-    "@rollup/plugin-terser": "^0.4.4"
+    "@rollup/plugin-terser": "^0.4.4",
+    "eslint": "^9.33.0"
   }
 }

package/readme.md

@@ -60,7 +60,7 @@ document.body.appendChild(App);
 npx degit afrocodeur/native-document-vite my-app
 cd my-app
 npm install
-npm run dev
+npm run start
 ```
 
 ### Option 3: NPM/Yarn
@@ -195,29 +195,12 @@ When(condition)
 - **[Routing](docs/routing.md)** - Navigation and URL management
 - **[State Management](docs/state-management.md)** - Global state patterns
 - **[Lifecycle Events](docs/lifecycle-events.md)** - Lifecycle events
+- **[NDElement](docs/native-document-element.md)** - Native Document Element
+- **[Extending NDElement](docs/extending-native-document-element.md)** - Custom Methods Guide
+- **[Args Validation](docs/validation.md)** - Function Argument Validation
 - **[Memory Management](docs/memory-management.md)** - Memory management
 - **[Anchor](docs/anchor.md)** - Anchor
 
-## Examples
-
-### Todo App
-```bash
-# Complete todo application with local storage
-git clone https://github.com/afrocodeur/native-document-examples
-cd examples/todo-app
-```
-
-### SPA Router
-```bash
-# Single Page Application with routing
-cd examples/routing-spa
-```
-
-### Reusable Components
-```bash
-# Component library patterns
-cd examples/components
-```
 
 ## Key Features Deep Dive
 

package/src/data/ObservableChecker.js

@@ -5,12 +5,13 @@
  * @class ObservableChecker
  */
 export default function ObservableChecker($observable, $checker) {
-    this.__$isObservableChecker = true;
     this.observable = $observable;
     this.checker = $checker;
     this.unSubscriptions = [];
 }
 
+ObservableChecker.prototype.__$isObservableChecker = true;
+
 ObservableChecker.prototype.subscribe = function(callback) {
     const unSubscribe = this.observable.subscribe((value) => {
         callback && callback(this.checker(value));

package/src/data/ObservableItem.js

@@ -9,14 +9,6 @@ import ObservableChecker from "./ObservableChecker";
  * @class ObservableItem
  */
 export default function ObservableItem(value) {
-    if (value === undefined) {
-        throw new NativeDocumentError('ObservableItem requires an initial value');
-    }
-    if(value instanceof ObservableItem) {
-        throw new NativeDocumentError('ObservableItem cannot be an Observable');
-    }
-
-    this.__$isObservable = true;
     this.$previousValue = value;
     this.$currentValue = value;
     this.$isCleanedUp = false;
@@ -24,7 +16,7 @@ export default function ObservableItem(value) {
     this.$listeners = null;
     this.$watchers = null;
 
-    this.$memoryId = MemoryManager.register(this);
+    this.$memoryId = null;
 }
 
 Object.defineProperty(ObservableItem.prototype, '$value', {
@@ -37,6 +29,9 @@ Object.defineProperty(ObservableItem.prototype, '$value', {
     configurable: true,
 });
 
+ObservableItem.prototype.__$isObservable = true;
+
+const noneTrigger = function() {};
 ObservableItem.prototype.triggerListeners = function(operations) {
     const $listeners = this.$listeners;
     const $previousValue = this.$previousValue;
@@ -60,31 +55,38 @@ ObservableItem.prototype.triggerWatchers = function() {
     const $currentValue = this.$currentValue;
 
     if($watchers.has($currentValue)) {
-        const watchValueList = $watchers.get($currentValue);
-        watchValueList.forEach(itemValue => {
-            if(itemValue.ifTrue.called) {
-                return;
-            }
-            itemValue.ifTrue.callback();
-            itemValue.else.called = false;
-        })
+        $watchers.get($currentValue).forEach(callback => {
+            callback(true);
+        });
     }
     if($watchers.has($previousValue)) {
-        const watchValueList = $watchers.get($previousValue);
-        watchValueList.forEach(itemValue => {
-            if(itemValue.else.called) {
-                return;
-            }
-            itemValue.else.callback();
-            itemValue.ifTrue.called = false;
+        $watchers.get($previousValue).forEach(callback => {
+            callback(false);
         });
     }
 };
 
-ObservableItem.prototype.trigger = function(operations) {
+ObservableItem.prototype.triggerAll = function(operations) {
     this.triggerListeners(operations);
     this.triggerWatchers();
+};
+
+ObservableItem.prototype.assocTrigger = function() {
+    if(this.$watchers?.size && this.$listeners?.length) {
+        this.trigger = this.triggerAll;
+        return;
+    }
+    if(this.$listeners?.length) {
+        this.trigger = this.triggerListeners;
+        return;
+    }
+    if(this.$watchers?.size) {
+        this.trigger = this.triggerWatchers;
+        return;
+    }
+    this.trigger = noneTrigger;
 }
+ObservableItem.prototype.trigger = noneTrigger;
 
 /**
  * @param {*} data
@@ -109,16 +111,13 @@ ObservableItem.prototype.disconnectAll = function() {
     this.$currentValue = null;
     if(this.$watchers) {
         for (const [_, watchValueList] of this.$watchers) {
-            for (const itemValue of watchValueList) {
-                itemValue.ifTrue.callback = null;
-                itemValue.else.callback = null;
-            }
-            watchValueList.clear();
+            watchValueList.splice(0);
         }
     }
     this.$watchers?.clear();
     this.$listeners = null;
     this.$watchers = null;
+    this.trigger = noneTrigger;
 }
 ObservableItem.prototype.cleanup = function() {
     MemoryManager.unregister(this.$memoryId);
@@ -143,30 +142,32 @@ ObservableItem.prototype.subscribe = function(callback) {
     }
 
     this.$listeners.push(callback);
-    return () => this.unsubscribe(callback);
+    this.assocTrigger();
+    return () => {
+        this.unsubscribe(callback);
+        this.assocTrigger();
+    };
 };
 
-ObservableItem.prototype.on = function(value, callback, elseCallback) {
+ObservableItem.prototype.on = function(value, callback) {
     this.$watchers = this.$watchers ?? new Map();
 
     let watchValueList = this.$watchers.get(value);
     if(!watchValueList) {
-        watchValueList = new Set();
+        watchValueList = [];
         this.$watchers.set(value, watchValueList);
     }
 
-    let itemValue = {
-        ifTrue: { callback, called: false },
-        else: { callback: elseCallback, called: false }
-    };
-    watchValueList.add(itemValue);
+    watchValueList.push(callback);
+    this.assocTrigger();
     return () => {
-        watchValueList?.delete(itemValue);
+        const index = watchValueList.indexOf(callback);
+        watchValueList?.splice(index, 1);
         if(watchValueList.size === 0) {
             this.$watchers?.delete(value);
+            watchValueList = null;
         }
-        watchValueList = null;
-        itemValue = null;
+        this.assocTrigger();
     };
 };
 
@@ -179,6 +180,7 @@ ObservableItem.prototype.unsubscribe = function(callback) {
     if (index > -1) {
         this.$listeners.splice(index, 1);
     }
+    this.assocTrigger();
 };
 
 /**
@@ -191,6 +193,9 @@ ObservableItem.prototype.check = function(callback) {
 };
 ObservableItem.prototype.get = ObservableItem.prototype.check;
 
-    ObservableItem.prototype.toString = function() {
+ObservableItem.prototype.toString = function() {
+    if(!this.$memoryId) {
+        MemoryManager.register(this);
+    }
     return '{{#ObItem::(' +this.$memoryId+ ')}}';
 }

package/src/data/observable-helpers/array.js

@@ -24,20 +24,20 @@ Observable.array = function(target) {
     });
 
     observer.clear = function() {
-        observer.$value.length = 0;
+        observer.val().length = 0;
         observer.trigger({ action: 'clear' });
         return true;
     };
 
     observer.merge = function(values) {
-        observer.$value = [...observer.$value, ...values];
+        observer.set([...observer.val(), ...values]);
     };
 
     observer.populateAndRender = function(iteration, callback) {
-        observer.trigger({ action: 'populate', args: [observer.$value, iteration, callback] });
+        observer.trigger({ action: 'populate', args: [observer.val(), iteration, callback] });
     };
     observer.remove = function(index) {
-        const deleted = observer.$value.splice(index, 1);
+        const deleted = observer.val().splice(index, 1);
         if(deleted.length === 0) {
             return [];
         }
@@ -46,7 +46,7 @@ Observable.array = function(target) {
     };
 
     observer.swap = function(indexA, indexB) {
-        const value = observer.$value;
+        const value = observer.val();
         const length = value.length;
         if(length < indexA || length < indexB) {
             return false;
@@ -66,7 +66,7 @@ Observable.array = function(target) {
     };
 
     observer.length = function() {
-        return observer.$value.length;
+        return observer.val().length;
     }
 
     const overrideMethods = ['map', 'filter', 'reduce', 'some', 'every', 'find', 'findIndex', 'concat'];

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

@@ -11,7 +11,6 @@ export function ForEachArray(data, callback, key, configs = {}) {
     const blockStart = element.startElement();
 
     let cache = new Map();
-    let nodeCacheByElement = new WeakMap();
     let lastNumberOfItems = 0;
 
     const keysCache = new WeakMap();
@@ -26,7 +25,10 @@ export function ForEachArray(data, callback, key, configs = {}) {
             return keysCache.get(item);
         }
         return getKey(item, indexKey, key);
-    }
+    };
+    const getItemChild = (item) => {
+        return getChildByKey(getItemKey(item));
+    };
 
     const updateIndexObservers = (items, startFrom = 0) => {
         if(callback.length < 2) {
@@ -47,13 +49,10 @@ export function ForEachArray(data, callback, key, configs = {}) {
         if(!cacheItem) {
             return;
         }
-        const child = cacheItem.child?.deref();
+        const child = cacheItem.child;
         cacheItem.indexObserver?.deref()?.cleanup();
         cacheItem.child = null;
         cacheItem.indexObserver = null;
-        nodeCacheByElement.delete(cacheItem.item);
-        keysCache.delete(cacheItem.item);
-        cacheItem.item = null;
         if(removeChild) {
             child?.remove();
             cache.delete(cacheItem.keyId);
@@ -77,8 +76,7 @@ export function ForEachArray(data, callback, key, configs = {}) {
         if(cache.has(keyId)) {
             const cacheItem = cache.get(keyId);
             cacheItem.indexObserver?.deref()?.set(indexKey);
-            cacheItem.isNew = false;
-            const child = cacheItem.child?.deref();
+            const child = cacheItem.child;
             if(child) {
                 return child;
             }
@@ -90,27 +88,22 @@ export function ForEachArray(data, callback, key, configs = {}) {
             let child = ElementCreator.getChild(callback(item, indexObserver));
             cache.set(keyId, {
                 keyId,
-                isNew: true,
-                item,
-                child: new WeakRef(child),
+                child: child,
                 indexObserver: (indexObserver ? new WeakRef(indexObserver) : null)
             });
             keysCache.set(item, keyId);
-            if(Validator.isObject(item)) {
-                nodeCacheByElement.set(item, child);
-            }
             return child;
         } catch (e) {
             DebugManager.error('ForEach', `Error creating element for key ${keyId}` , e);
             throw e;
         }
     };
-    const getChildByKey = function(keyId, fragment) {
+    const getChildByKey = function(keyId) {
         const cacheItem = cache.get(keyId);
         if(!cacheItem) {
             return null;
         }
-        const child = cacheItem.child?.deref();
+        const child = cacheItem.child;
         if(!child) {
             removeCacheItem(cacheItem, false);
             return null;
@@ -123,7 +116,7 @@ export function ForEachArray(data, callback, key, configs = {}) {
         if(!cacheItem) {
             return null;
         }
-        const child = cacheItem.child?.deref();
+        const child = cacheItem.child;
         if(!child) {
             return null;
         }
@@ -157,7 +150,7 @@ export function ForEachArray(data, callback, key, configs = {}) {
             let child = null;
             const fragment = document.createDocumentFragment();
             for(const item of items) {
-                child = nodeCacheByElement.get(item);
+                child = getItemChild(item);
                 if(child) {
                     fragment.appendChild(child);
                 }
@@ -166,11 +159,9 @@ export function ForEachArray(data, callback, key, configs = {}) {
             element.appendElement(fragment, blockEnd);
         },
         removeOne(element, index) {
-            let child = nodeCacheByElement.get(element);
+            let child = getItemChild(element);
             if(child) {
-                child.remove();
-                nodeCacheByElement.delete(element);
-                removeCacheItemByKey(getItemKey(element, index));
+                removeCacheItemByKey(getItemKey(element, index), true);
             }
             child = null;
         },
@@ -246,8 +237,8 @@ export function ForEachArray(data, callback, key, configs = {}) {
         swap(args, elements) {
             const parent = blockEnd.parentNode;
 
-            let childA = nodeCacheByElement.get(elements[0]);
-            let childB = nodeCacheByElement.get(elements[1]);
+            let childA = getItemChild(elements[0]);
+            let childB = getItemChild(elements[1]);
             if(!childA || !childB) {
                 return;
             }

package/src/wrappers/ElementCreator.js

@@ -96,7 +96,7 @@ export const ElementCreator = {
             return child;
         }
         if(Validator.isNDElement(child)) {
-            return child.$element;
+            return child.$element ?? child.$build?.() ?? null;
         }
         return ElementCreator.createStaticTextNode(null, child);
     },

package/src/wrappers/NDElement.js

@@ -2,10 +2,10 @@ import DocumentObserver from "./DocumentObserver";
 import { EVENTS } from "../utils/events";
 
 export function NDElement(element) {
-    this.__$isNDElement = true;
     this.$element = element;
     this.$observer = null;
 }
+NDElement.prototype.__$isNDElement = true;
 
 for(const event of EVENTS) {
     const eventName = event.toLowerCase();
@@ -38,18 +38,18 @@ for(const event of EVENTS) {
 }
 
 NDElement.prototype.ref = function(target, name) {
-    target[name] = element;
+    target[name] = this.$element;
     return this;
 };
 
 NDElement.prototype.unmountChildren = function() {
     let element = this.$element;
     for(let i = 0, length = element.children.length; i < length; i++) {
-        let elementchildren = element.children[i];
-        if(!elementchildren.$ndProx) {
-            elementchildren.nd?.remove();
+        let elementChildren = element.children[i];
+        if(!elementChildren.$ndProx) {
+            elementChildren.nd?.remove();
         }
-        elementchildren = null;
+        elementChildren = null;
     }
     element = null;
     return this;
@@ -77,7 +77,7 @@ NDElement.prototype.mounted = function(callback) {
     return this.lifecycle({ mounted: callback });
 };
 
-NDElement.prototype.mounted = function(callback) {
+NDElement.prototype.unmounted = function(callback) {
     return this.lifecycle({ unmounted: callback });
 };