npm - native-document - Versions diffs - 1.0.9 → 1.0.11 - Mend

native-document 1.0.9 → 1.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/dist/native-document.dev.js +2671 -0
package/dist/native-document.min.js +1 -0
package/docs/anchor.md +208 -0
package/docs/conditional-rendering.md +628 -0
package/docs/contributing.md +51 -0
package/docs/core-concepts.md +513 -0
package/docs/elements.md +383 -0
package/docs/getting-started.md +403 -0
package/docs/lifecycle-events.md +106 -0
package/docs/memory-management.md +90 -0
package/docs/observables.md +265 -0
package/docs/routing.md +817 -0
package/docs/state-management.md +423 -0
package/docs/validation.md +193 -0
package/elements.js +3 -1
package/index.js +2 -0
package/package.json +1 -1
package/readme.md +189 -425
package/router.js +2 -0
package/src/data/MemoryManager.js +15 -5
package/src/data/Observable.js +35 -2
package/src/data/ObservableChecker.js +3 -0
package/src/data/ObservableItem.js +4 -0
package/src/data/Store.js +6 -6
package/src/router/Router.js +13 -13
package/src/router/link.js +8 -5
package/src/utils/plugins-manager.js +12 -0
package/src/utils/prototypes.js +13 -0
package/src/utils/validator.js +23 -1
package/src/wrappers/AttributesWrapper.js +11 -1
package/src/wrappers/HtmlElementWrapper.js +10 -1

package/docs/getting-started.md ADDED Viewed

@@ -0,0 +1,403 @@
+# Getting Started
+Welcome to NativeDocument! This guide will help you set up and create your first application with NativeDocument.
+## Installation
+NativeDocument offers multiple installation methods to fit your development workflow.
+### Method 1: CDN (Recommended for beginners)
+The fastest way to get started is using our CDN. Simply add this script tag to your HTML:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>My NativeDocument App</title>
+</head>
+<body>
+<script src="https://cdn.jsdelivr.net/gh/afrocodeur/native-document@latest/dist/native-document.min.js"></script>
+<script>
+    const { Div, Button } = NativeDocument.elements;
+    const { Observable } = NativeDocument;
+    // Your code here
+    const count = Observable(0);
+    const App = Div({ class: 'app' }, [
+        Div(['Count: ', count]),
+        Button('Increment').nd.on.click(() => count.set(count.val() + 1))
+    ]);
+    document.body.appendChild(App);
+</script>
+</body>
+</html>
+```
+### Method 2: Vite Template (Recommended for projects)
+For a complete development setup with Vite, use our official template:
+```bash
+npx degit afrocodeur/native-document-vite my-app
+cd my-app
+npm install
+npm run dev
+```
+This template includes:
+- Pre-configured Vite setup
+- Development server with auto reload
+- Build optimization
+- Example components
+### Method 3: NPM/Yarn Package
+Install NativeDocument as a dependency in your existing project:
+```bash
+npm install native-document
+# or
+yarn add native-document
+```
+Then import what you need:
+```javascript
+import { Div, Button } from 'native-document/src/elements'
+import { Observable } from 'native-document'
+const count = Observable(0);
+const App = Div({ class: 'app' }, [
+    Div(['Count: ', count]),
+    Button('Increment').nd.on.click(() => count.set(count.val() + 1))
+]);
+document.body.appendChild(App);
+```
+## Your First Application
+Let's build a simple counter application to understand NativeDocument basics.
+### Step 1: Create the HTML Structure
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Counter App</title>
+    <style>
+        .counter-app {
+            max-width: 400px;
+            margin: 50px auto;
+            padding: 20px;
+            text-align: center;
+            font-family: Arial, sans-serif;
+        }
+        .count-display {
+            font-size: 2rem;
+            margin: 20px 0;
+            color: #333;
+        }
+        button {
+            margin: 0 10px;
+            padding: 10px 20px;
+            font-size: 1rem;
+            cursor: pointer;
+        }
+    </style>
+</head>
+<body>
+<script src="https://cdn.jsdelivr.net/gh/afrocodeur/native-document@latest/dist/native-document.min.js"></script>
+<script>
+    // Your JavaScript code will go here
+</script>
+</body>
+</html>
+```
+### Step 2: Add the JavaScript Logic
+```javascript
+const { Div, Button, H1 } = NativeDocument.elements;
+const { Observable } = NativeDocument;
+// Create reactive state
+const count = Observable(0);
+// Create the application
+const CounterApp = Div({ class: 'counter-app' }, [
+    H1('Counter Application'),
+    Div({ class: 'count-display' }, [
+        'Current count: ', count
+    ]),
+    Div([
+        Button('Decrease').nd.on.click(() => {
+            count.set(count.val() - 1);
+        }),
+        Button('Reset').nd.on.click(() => {
+            count.set(0);
+        }),
+        Button('Increase').nd.on.click(() => {
+            count.set(count.val() + 1);
+        })
+    ])
+]);
+// Mount the application
+document.body.appendChild(CounterApp);
+```
+### Step 3: Understanding What Happened
+1. **Imported Components**: We used `Div`, `Button`, and `H1` from `NativeDocument.elements`
+2. **Created Reactive State**: `Observable(0)` creates a reactive value that starts at 0
+3. **Built the UI**: Elements are created with attributes and children
+4. **Added Event Handlers**: `.nd.on.click()` attaches click event listeners
+5. **Automatic Updates**: When `count` changes, the UI updates automatically
+## Todo List Application
+Let's build something more complex - a todo list with add, delete, and filter functionality:
+```javascript
+const { Div, Input, Button, ShowIf, ForEach } = NativeDocument.elements;
+const { Observable } = NativeDocument;
+// Reactive state
+const todos = Observable.array([]);
+const newTodo = Observable('');
+const filter = Observable('all'); // 'all', 'active', 'completed'
+// Computed values
+const filteredTodos = Observable.computed(() => {
+    const allTodos = todos.val();
+    const currentFilter = filter.val();
+    if (currentFilter === 'active') {
+        return allTodos.filter(todo => !todo.done);
+    }
+    if (currentFilter === 'completed') {
+        return allTodos.filter(todo => todo.done);
+    }
+    return [...allTodos];
+}, [todos, filter]);
+const addTodo = () => {
+    if (!newTodo.val().trim()) {
+        return;
+    }
+    todos.push({
+        id: Date.now(),
+        text: newTodo.val().trim(),
+        done: false
+    });
+    newTodo.set('');
+};
+// Todo application
+const TodoApp = Div({ class: 'todo-app' }, [
+    // Header
+    Div({ class: 'header' }, [
+        Input({
+            placeholder: 'What needs to be done?',
+            value: newTodo
+        }),
+        Button('Add').nd.on.click(addTodo)
+    ]),
+    // Todo list container
+    Div({ class: 'todos-list'}, [
+        ShowIf(todos.check(list => list.length === 0),
+            Div({ class: 'empty' }, 'No todos yet! Add one above.')), // Empty state
+        // List of todos
+        ForEach(filteredTodos, (todo, index) => // Todo list
+                Div({ class: 'todo-item' }, [
+                    Input({
+                        type: 'checkbox',
+                        checked: Observable(todo.done)
+                    }).nd.on.change((e) => {
+                        const todoList = todos.val();
+                        todoList[index.val()].done = e.target.checked;
+                        todos.set([...todoList]);
+                    }),
+                    Div(['Task: ', todo.text]),
+                    Button('Delete').nd.on.click(() => {
+                        todos.splice(index.val(), 1);
+                    })
+                ]),
+            // Key function for efficient updates
+            (item) => item.id
+        )
+    ]),
+    // Filters
+    Div({ class: 'filters' }, [
+        Button('All').nd.on.click(() => filter.set('all')),
+        Button('Active').nd.on.click(() => filter.set('active')),
+        Button('Completed').nd.on.click(() => filter.set('completed'))
+    ])
+]);
+document.body.appendChild(TodoApp);
+```
+## Key Concepts Demonstrated
+### Observables
+- `Observable(value)` - Creates reactive primitive values
+- `Observable.array([])` - Creates reactive arrays with array methods
+- `Observable.computed(() => {}, [deps])` - Creates computed values
+### Elements
+- Elements are functions that return DOM nodes
+- First parameter is attributes object (optional)
+- Second parameter is children array or single child
+- Children can be strings, numbers, elements, or observables
+### Event Handling
+- `.nd.on.click()` - Add click event listener
+- `.nd.on.change()` - Add change event listener
+- Event handlers receive the native event object
+### Conditional Rendering
+- `ShowIf(condition, content)` - Show content when condition is true
+- `ForEach(array, callback, propertyKey || keyFn)` - Render lists efficiently
+## Project Structure
+For larger applications, organize your code like this:
+```
+my-app/
+├── index.html
+├── src/
+│   ├── main.js          # Application entry point
+│   ├── components/      # Reusable components
+│   │   ├── TodoItem.js
+│   │   └── Header.js
+│   ├── stores/          # Global state
+│   │   └── TodoStore.js
+│   └── utils/           # Helper functions
+│       └── validators.js
+├── styles/
+│   └── main.css
+└── package.json
+```
+### Example Component (components/TodoItem.js)
+```javascript
+import { Div, Input, Button } from 'native-document/src/elements';
+export function TodoItem(todo, onToggle, onDelete) {
+    return Div({ class: 'todo-item' }, [
+        Input({
+            type: 'checkbox',
+            checked: todo.done
+        }).nd.on.change(onToggle),
+        Div(['Task: ', todo.text]),
+        Button('Delete').nd.on.click(onDelete)
+    ]);
+}
+```
+## Development Workflow
+### Auto Reload with Vite
+When using the Vite template, your development server automatically reloads when you make changes:
+```bash
+npm run dev  # Start development server
+npm run build  # Build for production
+npm run preview  # Preview production build
+```
+## Browser Support
+NativeDocument works in all modern browsers that support:
+- ES6 Modules
+- Proxy objects
+- FinalizationRegistry (for automatic memory management)
+**Supported browsers:**
+- Chrome 84+
+- Firefox 79+
+- Safari 14.1+
+- Edge 84+
+## Next Steps
+Now that you've built your first NativeDocument applications, explore these topics:
+- **[Core Concepts](docs/core-concepts.md)** - Understanding the fundamentals
+- **[Observables](docs/observables.md)** - Reactive state management
+- **[Elements](docs/elements.md)** - Creating and composing UI
+- **[Conditional Rendering](docs/conditional-rendering.md)** - Dynamic content
+- **[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
+- **[Memory Management](docs/memory-management.md)** - Memory management
+- **[Anchor](docs/anchor.md)** - Anchor
+## Common Issues
+### Import Errors
+**Problem**: `Cannot resolve module 'native-document'`
+**Solution**: Make sure you're using the correct import path:
+```javascript
+// Correct
+import { Div } from 'native-document/src/elements'
+import { Observable } from 'native-document'
+// CDN
+const { Div } = NativeDocument.elements;
+const { Observable } = NativeDocument;
+```
+### Observable Not Updating
+**Problem**: UI doesn't update when you change observable values
+**Solution**: Make sure you're using `.set()` method:
+```javascript
+// Wrong
+count = 5;
+// Correct
+count.set(5);
+// Correct
+count.$value = 5;
+```
+### Memory Leaks
+**Problem**: Application slows down over time
+**Solution**: NativeDocument has automatic memory management, but you can help by cleaning up manual subscriptions:
+```javascript
+const unsubscribe = observable.subscribe(callback);
+// Later...
+unsubscribe(); // Clean up manually if needed
+```
+Ready to dive deeper? Continue with [Core Concepts](core-concepts.md)!

package/docs/lifecycle-events.md ADDED Viewed

@@ -0,0 +1,106 @@
+# Lifecycle Events
+NativeDocument provides lifecycle hooks that let you execute code when elements are added to or removed from the DOM. This is essential for setup, cleanup, and managing resources.
+## Basic Lifecycle Hooks
+### mounted() - Element Added to DOM
+```javascript
+const myComponent = Div("Hello World")
+  .nd.mounted(element => {
+    console.log("Element is now in the DOM!", element);
+    // Setup code here
+  });
+document.body.appendChild(myComponent); // Triggers mounted callback
+```
+### unmounted() - Element Removed from DOM
+```javascript
+const myComponent = Div("Temporary content")
+  .nd.unmounted(element => {
+    console.log("Element removed from DOM!", element);
+    // Cleanup external resources only
+    // Element can be re-injected later
+  });
+// Later, when element is removed
+myComponent.remove(); // Triggers unmounted callback
+```
+## Combined Lifecycle Management
+```javascript
+const timer = Div("Timer: 0")
+  .nd.lifecycle({
+    mounted(element) {
+      console.log("Timer started");
+      element.intervalId = setInterval(() => {
+        element.textContent = `Timer: ${Date.now()}`;
+      }, 1000);
+    },
+    unmounted(element) {
+      console.log("Timer stopped");
+      clearInterval(element.intervalId);
+    }
+  });
+```
+## Practical Examples
+### Auto-focus Input Field
+```javascript
+const focusInput = Input({ placeholder: "Auto-focused" })
+  .nd.mounted(input => {
+    input.focus();
+  });
+```
+### Event Listener Cleanup
+```javascript
+const MyButton = function() {
+    const handler = () => console.log("Global click detected");
+    return Button("Click me")
+        .nd.mounted(button => {
+            document.addEventListener('click', handler);
+        })
+        .nd.unmounted(button => {
+            // Clean up external listeners, but keep observables intact
+            document.removeEventListener('click', handler);
+            // DON'T cleanup observables unless element won't be reused
+        });
+}
+```
+### Observable Management Warning
+```javascript
+const reusableComponent = Div()
+  .nd.unmounted(element => {
+    // AVOID: Don't cleanup observables if element might be re-injected
+    // myObservable.cleanup(); // Only do this if element is permanently destroyed
+    // GOOD: Only cleanup external resources
+    clearInterval(element.timerId);
+    element.websocket?.close();
+  });
+// Element can be safely re-appended later
+document.body.appendChild(reusableComponent);
+```
+## Next Steps
+Now that you understand lifecycle events, explore these related topics:
+- **[Memory Management](docs/memory-management.md)** - Memory management
+- **[Anchor](docs/anchor.md)** - Anchor

package/docs/memory-management.md ADDED Viewed

@@ -0,0 +1,90 @@
+# Memory Management
+NativeDocument includes an advanced automatic memory management system that prevents memory leaks and optimizes performance using modern browser APIs like FinalizationRegistry.
+## Automatic Observable Cleanup
+### How It Works
+```javascript
+const data = Observable("test");
+// When 'data' goes out of scope and is garbage collected,
+// NativeDocument automatically cleans up its internal listeners
+// No manual cleanup required!
+function createComponent() {
+    const localObservable = Observable(42);
+    return Div(localObservable); // Observable auto-cleaned when component is GC'd
+}
+```
+### Memory Registry System
+```javascript
+// Each observable is automatically registered for cleanup
+const count = Observable(0);
+console.log(count.toString()); // "{{#ObItem::(1)}}" - Shows internal ID
+// When count becomes unreachable, cleanup happens automatically
+// via FinalizationRegistry
+```
+## Manual Memory Management
+### Force Cleanup
+```javascript
+const obs = Observable("data");
+const unsubscribe = obs.subscribe(console.log);
+// Manual cleanup if needed
+obs.cleanup(); // Removes all listeners immediately
+// obs is now unusable - will warn on new subscriptions
+```
+### Global Cleanup
+```javascript
+// Clean all orphaned observables
+Observable.cleanup(); // Force cleanup of all registered observables
+// Auto-cleanup configuration
+Observable.autoCleanup(true, {
+    interval: 60000,    // Check every minute
+    threshold: 100      // Clean when 100+ orphaned observables
+});
+```
+## Performance Monitoring
+### Debug Mode
+```javascript
+// Enable memory debugging
+NativeDocument.debug.enable();
+// Monitor cleanup events in console
+const obs = Observable("test");
+obs = null; // Will log cleanup when GC runs
+```
+### Memory Leak Detection
+```javascript
+// Check for potential leaks
+window.addEventListener('beforeunload', () => {
+    // Force cleanup on page unload
+});
+```
+## Best Practices
+1. **Trust the system** - Let automatic cleanup handle most cases
+2. **Manual cleanup** only for critical resources or immediate needs
+3. **Enable auto-cleanup** in long-running applications
+4. **Use debug mode** during development to monitor memory usage
+## Next Steps
+- **[Anchor](docs/anchor.md)** - Anchor