native-document 1.0.18 → 1.0.20

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/index.js

@@ -1,5 +1,6 @@
 export { default as HtmlElementWrapper } from './src/wrappers/HtmlElementWrapper'
 export { ElementCreator } from './src/wrappers/ElementCreator'
+export { NDElement } from './src/wrappers/NDElement'
 
 import './src/utils/prototypes.js';
 

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "native-document",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "build": "rollup --config rollup.config.js --watch"
+    "build": "rollup --config rollup.config.js --watch",
+    "lint": "eslint ."
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "description": "",
   "devDependencies": {
-    "@rollup/plugin-terser": "^0.4.4"
+    "@rollup/plugin-replace": "^6.0.2",
+    "@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/rollup.config.js

@@ -1,5 +1,7 @@
 import terser from '@rollup/plugin-terser';
+import replace from '@rollup/plugin-replace';
 
+const isProduction = process.env.NODE_ENV === 'production';
 export default [
     {
         input: {
@@ -9,8 +11,15 @@ export default [
             dir: 'dist',
             entryFileNames: 'native-document.dev.js',
             format: 'iife',
-            name: 'NativeDocument'
+            name: 'NativeDocument',
+            sourcemap: true
         },
+        plugins: [
+            replace({
+                'process.env.NODE_ENV': JSON.stringify('development'),
+                preventAssignment: true,
+            })
+        ]
     },
     {
         input: {
@@ -23,6 +32,10 @@ export default [
             name: 'NativeDocument'
         },
         plugins: [
+            replace({
+                'process.env.NODE_ENV': JSON.stringify('production'),
+                preventAssignment: true,
+            }),
             terser()
         ]
     }

package/src/data/ObservableChecker.js

@@ -10,6 +10,8 @@ export default function ObservableChecker($observable, $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

@@ -36,6 +36,8 @@ Object.defineProperty(ObservableItem.prototype, '$value', {
     configurable: true,
 });
 
+ObservableItem.prototype.__$isObservable = true;
+
 ObservableItem.prototype.triggerListeners = function(operations) {
     const $listeners = this.$listeners;
     const $previousValue = this.$previousValue;

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

@@ -77,9 +77,10 @@ Observable.value = function(data) {
     }
     if(Validator.isArray(data)) {
         const result = [];
-        data.forEach(item => {
+        for(let i = 0, length = data.length; i < length; i++) {
+            const item = data[i];
             result.push(Observable.value(item));
-        });
+        }
         return result;
     }
     return data;

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

@@ -264,7 +264,6 @@ export function ForEachArray(data, callback, key, configs = {}) {
         if(operations?.action === 'populate') {
             Actions.populate(operations.args, operations.result);
         } else  {
-            console.log(lastNumberOfItems);
             if(operations.action === 'clear' || !items.length) {
                 if(lastNumberOfItems === 0) {
                     return;
@@ -284,7 +283,6 @@ export function ForEachArray(data, callback, key, configs = {}) {
             }
         }
 
-        console.log(items)
         updateIndexObservers(items, 0);
     };
 

package/src/router/link.js

@@ -15,7 +15,6 @@ export function Link(options, children){
     }
     const routerName = target.router || DEFAULT_ROUTER_NAME;
     const router = Router.get(routerName);
-    console.log(routerName)
     if(!router) {
         throw new RouterError('Router not found "'+routerName+'" for link "'+target.name+'"');
     }

package/src/utils/debug-manager.js

@@ -1,31 +1,43 @@
-const DebugManager = {
-    enabled: false,
+let DebugManager = {};
 
-    enable() {
-        this.enabled = true;
-        console.log('🔍 NativeDocument Debug Mode enabled');
-    },
+if(process.env.NODE_ENV === 'development') {
+    DebugManager = {
+        enabled: false,
 
-    disable() {
-        this.enabled = false;
-    },
+        enable() {
+            this.enabled = true;
+            console.log('🔍 NativeDocument Debug Mode enabled');
+        },
 
-    log(category, message, data) {
-        if (!this.enabled) return;
-        console.group(`🔍 [${category}] ${message}`);
-        if (data) console.log(data);
-        console.trace();
-        console.groupEnd();
-    },
+        disable() {
+            this.enabled = false;
+        },
 
-    warn(category, message, data) {
-        if (!this.enabled) return;
-        console.warn(`⚠️ [${category}] ${message}`, data);
-    },
+        log(category, message, data) {
+            if (!this.enabled) return;
+            console.group(`🔍 [${category}] ${message}`);
+            if (data) console.log(data);
+            console.trace();
+            console.groupEnd();
+        },
 
-    error(category, message, error) {
-        console.error(`❌ [${category}] ${message}`, error);
-    }
-};
+        warn(category, message, data) {
+            if (!this.enabled) return;
+            console.warn(`⚠️ [${category}] ${message}`, data);
+        },
 
+        error(category, message, error) {
+            console.error(`❌ [${category}] ${message}`, error);
+        }
+    };
+
+}
+if(process.env.NODE_ENV === 'production') {
+    DebugManager = {
+        log() {},
+        warn() {},
+        error() {},
+        disable() {}
+    };
+}
 export default DebugManager;

package/src/utils/validator.js

@@ -6,13 +6,13 @@ import {NDElement} from "../wrappers/NDElement";
 
 const Validator = {
     isObservable(value) {
-        return value instanceof ObservableItem || value instanceof ObservableChecker;
+        return value instanceof ObservableItem || value instanceof ObservableChecker || value?.__$isObservable;
     },
     isProxy(value) {
         return value?.__isProxy__
     },
     isObservableChecker(value) {
-        return value instanceof ObservableChecker;
+        return value instanceof ObservableChecker || value?.__$isObservableChecker;
     },
     isArray(value) {
         return Array.isArray(value);
@@ -55,7 +55,7 @@ const Validator = {
             ['string', 'number', 'boolean'].includes(typeof child);
     },
     isNDElement(child) {
-        return child instanceof NDElement;
+        return child instanceof NDElement || child?.constructor?.__$isNDElement;
     },
     isValidChildren(children) {
         if (!Array.isArray(children)) {

package/src/wrappers/NDElement.js

@@ -5,6 +5,7 @@ export function NDElement(element) {
     this.$element = element;
     this.$observer = null;
 }
+NDElement.prototype.__$isNDElement = true;
 
 for(const event of EVENTS) {
     const eventName = event.toLowerCase();
@@ -37,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;
@@ -76,6 +77,12 @@ 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 });
-};
+};
+
+NDElement.prototype.htmlElement = function() {
+    return this.$element;
+};
+
+NDElement.prototype.node = NDElement.prototype.htmlElement;

package/src/wrappers/NdPrototype.js

@@ -1,6 +1,7 @@
 import { NDElement } from "./NDElement";
 
 Object.defineProperty(HTMLElement.prototype, 'nd', {
+    configurable: true,
     get() {
         if(this.$nd) {
             return this.$nd;