native-document 1.0.14 → 1.0.16-8.1

package/docs/list-rendering.md

@@ -0,0 +1,387 @@
+---
+title: List Rendering
+description: Efficiently render dynamic collections with ForEach and ForEachArray - automatic DOM updates, keyed diffing, and reactive filtering
+---
+
+# List Rendering
+
+NativeDocument provides two functions for rendering dynamic collections: `ForEach` for generic iteration over arrays and objects, and `ForEachArray` for high-performance array-specific operations.
+
+```javascript
+import { ForEach, ForEachArray } from 'native-document/elements';
+```
+
+---
+
+## `ForEach` - Generic Collection Rendering
+
+`ForEach` works with both observable arrays and observable objects.
+
+```javascript
+ForEach(data, callback, key?, options?)
+```
+
+### Array iteration
+
+```javascript
+const fruits = Observable.array(['Apple', 'Banana', 'Cherry']);
+
+Ul(
+    ForEach(fruits, fruit => Li(fruit))
+)
+
+// All array operations trigger DOM updates
+fruits.push('Orange');
+fruits.splice(1, 1);
+fruits.sort();
+```
+
+### Object iteration
+
+```javascript
+const roles = Observable({
+    admin:  'Administrator',
+    editor: 'Content Editor',
+    viewer: 'Read Only'
+});
+
+Ul(
+    ForEach(roles, (roleName, roleKey) =>
+        Li([Strong(roleKey), ': ', roleName])
+    )
+)
+```
+
+### Index parameter
+
+The second callback argument is an **observable** tracking the item's current index:
+
+```javascript
+const tasks = Observable.array(['Review PRs', 'Update docs', 'Fix bugs']);
+
+Ol(ForEach(tasks, (task, index) =>
+    Li([
+        Strong(index.transform(i => i + 1)), '. ',
+        task,
+        Button('Remove').nd.onClick(() => tasks.remove(index.val()))
+    ])
+))
+```
+
+### Key function
+
+Use a key to help NativeDocument identify items for efficient reordering. Pass a property name string or a function:
+
+```javascript
+const users = Observable.array([
+    { id: 1, name: 'Alice', role: 'admin' },
+    { id: 2, name: 'Bob',   role: 'user' }
+]);
+
+// Property name shorthand
+ForEach(users, user => Div(user.name), 'id')
+
+// Function
+ForEach(users, user => Div(user.name), item => item.id)
+```
+
+### Options
+
+```javascript
+ForEach(data, callback, key, { shouldKeepItemsInCache: true })
+```
+
+`shouldKeepItemsInCache` - when `true`, rendered items stay in cache even when removed. Useful when items toggle frequently:
+
+```javascript
+// Items are cached - re-adding won't re-render them
+ForEach(items, renderItem, 'id', { shouldKeepItemsInCache: true })
+```
+
+---
+
+## `ForEachArray` - High-Performance Array Rendering
+
+`ForEachArray` is specifically optimized for arrays of objects. Use it when performance matters.
+
+```javascript
+ForEachArray(data, callback, configs?)
+```
+
+```javascript
+const messages = Observable.array([
+    { id: 1, text: 'Hello!',    timestamp: Date.now() },
+    { id: 2, text: 'How are you?', timestamp: Date.now() + 1000 }
+]);
+
+Div({ class: 'chat' },
+    ForEachArray(messages, message =>
+        Div({ class: 'message' }, [
+            Div(message.text),
+            Div(new Date(message.timestamp).toLocaleTimeString())
+        ])
+    )
+)
+```
+
+### Index in `ForEachArray`
+
+The index is a **computed observable** derived from the array - always reactive, no need to call `.val()` to use it in the DOM:
+
+```javascript
+ForEachArray(playlist, (song, index) =>
+    Div([
+        index.transform(i => i + 1), '. ',
+        song.title,
+        Button('Up').nd.onClick(() => {
+            const i = index.$value;
+            if (i > 0) {
+                playlist.swap(i, i - 1);
+            }
+        }),
+        Button('Down').nd.onClick(() => {
+            const i = index.$value;
+            if (i < playlist.val().length - 1) {
+                playlist.swap(i, i + 1);
+            }
+        }),
+        Button('Remove').nd.onClick(() => playlist.remove(index.$value))
+    ])
+)
+```
+
+### Configs
+
+```javascript
+ForEachArray(data, callback, {
+    shouldKeepItemsInCache: false, // same as ForEach
+    pushDelay: (items) => items.length > 100 ? 50 : 0 // throttle large batch inserts
+})
+```
+
+---
+
+## Choosing Between `ForEach` and `ForEachArray`
+
+| | `ForEach` | `ForEachArray` |
+|---|---|---|
+| Arrays of objects | yes | yes (optimized) |
+| Arrays of primitives | yes | yes |
+| Object (non-array) iteration | yes | no |
+| Index is observable | yes | yes (computed) |
+| Key argument | third arg (string/fn) | inside configs |
+| Best for | objects, primitives, small lists | large or frequently updated arrays |
+
+---
+
+## Filtering with `.where()`
+
+`.where()` is available on `ObservableArray` only. It returns a new live `ObservableArray` that re-filters automatically. See [Observables](./observables.md) for the full `.where()` reference.
+
+```javascript
+import { equals, greaterThan, lessThan, between, includes, match,
+         startsWith, endsWith, inArray, notIn, custom,
+         and, or, not } from 'native-document/filters';
+
+const products = Observable.array([
+    { id: 1, name: 'Phone',  price: 599, inStock: true,  category: 'electronics' },
+    { id: 2, name: 'Laptop', price: 999, inStock: false, category: 'electronics' },
+    { id: 3, name: 'Book',   price: 29,  inStock: true,  category: 'books' }
+]);
+```
+
+### Comparison
+
+```javascript
+products.where({ price: greaterThan(500) })
+products.where({ price: lessThan(100) })
+products.where({ price: between(200, 800) })
+products.where({ inStock: equals(true) })
+products.where({ name: notEquals('Phone') })
+```
+
+### String
+
+```javascript
+products.where({ name: includes('phone') })     // case-insensitive by default
+products.where({ name: startsWith('P') })
+products.where({ name: endsWith('book') })
+products.where({ name: match(/^[A-Z]/) })        // regex
+products.where({ name: match('lap', false) })    // plain string, no regex
+```
+
+### Array membership
+
+```javascript
+const allowed = Observable.array(['electronics', 'books']);
+
+products.where({ category: inArray(allowed) })   // reactive
+products.where({ category: notIn(['clothing']) })
+```
+
+### Reactive filters
+
+Pass an observable as the filter value - re-filters automatically when it changes:
+
+```javascript
+const search   = Observable('');
+const minPrice = Observable(0);
+const maxPrice = Observable(1000);
+
+const filtered = products.where({
+    name:  includes(search),
+    price: between(minPrice, maxPrice)
+});
+```
+
+### Custom filter
+
+```javascript
+const minRating = Observable(4);
+
+products.where({
+    _: custom((product, min) => {
+        return product.rating >= min && product.reviews > 10;
+    }, minRating) // observables passed as extra args
+})
+```
+
+### Combining
+
+```javascript
+// and - field must pass ALL conditions
+products.where({ price: and(greaterThan(100), lessThan(500)) })
+
+// or - field must pass AT LEAST ONE
+products.where({ category: or(equals('electronics'), equals('books')) })
+
+// not - invert
+products.where({ inStock: not(equals(true)) })
+
+// cross-field - use _ key with plain function
+products.where({
+    _: item => item.inStock && item.price < 500
+})
+```
+
+### Date and time filters
+
+```javascript
+import { dateEquals, dateBefore, dateAfter, dateBetween,
+    timeBefore, timeBetween } from 'native-document/filters';
+
+const events = Observable.array([
+    { name: 'Meeting',    date: '2024-03-15' },
+    { name: 'Conference', date: '2024-06-20' }
+]);
+
+events.where({ date: dateAfter(new Date()) })
+events.where({ date: dateBetween('2024-06-01', '2024-08-31') })
+events.where({ date: timeBetween(
+        new Date('2024-01-01 09:00:00'),
+        new Date('2024-01-01 17:00:00')
+    )})
+```
+
+---
+
+## Common Patterns
+
+### Empty state
+
+```javascript
+const items = Observable.array([]);
+
+Div([
+    ShowIf(items.isEmpty(), Div({ class: 'empty' }, 'No items yet')),
+    ForEachArray(items, item => ItemComponent(item))
+])
+```
+
+### Search + filter
+
+```javascript
+const search   = Observable('');
+const category = Observable('all');
+
+const filtered = products.where({
+    name:     includes(search),
+    category: or(equals('all'), equals(category))
+});
+
+Div([
+    Input({ placeholder: 'Search...', value: search }),
+    ForEachArray(filtered, product => ProductCard(product))
+])
+```
+
+### Drag-and-drop reordering
+
+```javascript
+let draggedIndex = null;
+
+ForEachArray(items, (item, index) =>
+    Div({ class: 'item', draggable: true }, item.text)
+        .nd
+        .onDragStart(() => { draggedIndex = index.$value; })
+        .onDragOver(e => e.preventDefault())
+        .onDrop(e => {
+            e.preventDefault();
+            const dropIndex = index.$value;
+            if (draggedIndex !== null && draggedIndex !== dropIndex) {
+                items.swap(draggedIndex, dropIndex);
+            }
+            draggedIndex = null;
+        })
+)
+```
+
+### Infinite scroll
+
+```javascript
+const items     = Observable.array([]);
+const isLoading = Observable(false);
+const hasMore   = Observable(true);
+
+const loadMore = async () => {
+    if (isLoading.val()) return;
+    isLoading.set(true);
+    const next = await fetchItems(items.val().length);
+    next.length ? items.merge(next) : hasMore.set(false);
+    isLoading.set(false);
+};
+
+Div([
+    ForEachArray(items, item => ItemComponent(item)),
+    ShowIf(isLoading.isTruthy(), Div('Loading...')),
+    ShowIf(hasMore.isTruthy(),
+        Button('Load more').nd.onClick(loadMore)
+    )
+])
+```
+
+---
+
+## Best Practices
+
+1. Use `ForEachArray` for arrays of objects - it's optimized for that case
+2. Use `ForEach` for objects (non-array) and arrays of primitives
+3. Always pass a key when items can be reordered - avoids unnecessary re-rendering
+4. Use `.where()` for filtering instead of filtering inside the callback
+5. Use `shouldKeepItemsInCache: true` when items toggle in and out frequently
+6. Never mutate `.val()` directly - use observable array methods (`push`, `splice`, `swap`, etc.)
+
+---
+
+## Next Steps
+
+- **[Conditional Rendering](./conditional-rendering.md)** - ShowIf, Match, Switch
+- **[Observables](./observables.md)** - Observable arrays and `.where()` in depth
+- **[Advanced Components](./advanced-components.md)** - `ForEachArray` with `useCache`
+- **[Filters](./filters.md)** - Full filter reference
+
+## Utilities
+
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[Filters](./filters.md)** - Data filtering helpers

package/docs/memory-management.md

@@ -1,90 +1,179 @@
-# Memory Management
+---
+title: Memory Management
+description: NativeDocument's automatic memory management system using WeakRef and FinalizationRegistry - how it works and how to control it
+---
 
-NativeDocument includes an advanced automatic memory management system that prevents memory leaks and optimizes performance using modern browser APIs like FinalizationRegistry.
+# Memory Management
 
-## Automatic Observable Cleanup
+NativeDocument includes an automatic memory management system that prevents memory leaks using modern browser APIs - `WeakRef` and `FinalizationRegistry`. In most cases you don't need to think about this at all.
 
-### How It Works
+---
 
-```javascript
-const data = Observable("test");
+## How It Works
 
-// When 'data' goes out of scope and is garbage collected,
-// NativeDocument automatically cleans up its internal listeners
-// No manual cleanup required!
+Every observable is registered in the `MemoryManager` using a `WeakRef`. When an observable goes out of scope and is garbage collected, the `FinalizationRegistry` notifies the system and the entry is cleaned up automatically.
 
+```javascript
 function createComponent() {
     const localObservable = Observable(42);
-    return Div(localObservable); // Observable auto-cleaned when component is GC'd
+    return Div(localObservable);
+    // When the component is removed and localObservable goes out of scope,
+    // MemoryManager cleans up its entry automatically via FinalizationRegistry
 }
 ```
 
-### Memory Registry System
+Each observable gets an internal numeric ID on creation, accessible via `Observable.getById()`. Note that `.toString()` now returns the current value as a string, not the internal ID:
 
 ```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
+const count = Observable(42);
+console.log(count.toString()); // "42" - current value as string
 ```
 
-## Manual Memory Management
+---
 
-### Force Cleanup
+## Manual Cleanup
+
+### `observable.cleanup()`
+
+Removes all listeners from an observable immediately and prevents new subscriptions:
 
 ```javascript
-const obs = Observable("data");
+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
+obs.cleanup(); // removes all listeners
+// obs is now unusable
+```
+
+### `observable.onCleanup(callback)`
+
+Register a callback that runs when the observable is cleaned up:
+
+```javascript
+const obs = Observable('data');
+
+obs.onCleanup(() => {
+    console.log('Observable cleaned up');
+});
+
+obs.cleanup(); // triggers the callback
 ```
 
-### Global Cleanup
+### `Observable.cleanup(observable)`
+
+Static alias for `observable.cleanup()`:
 
 ```javascript
-// Clean all orphaned observables
-Observable.cleanup(); // Force cleanup of all registered observables
+Observable.cleanup(myObservable);
+```
 
-// Auto-cleanup configuration
+---
+
+## Auto-Cleanup
+
+### `Observable.autoCleanup(enable, options?)`
+
+Enables automatic periodic cleanup of orphaned observables (those that have been garbage collected but whose `WeakRef` entries remain in the registry):
+
+```javascript
 Observable.autoCleanup(true, {
-    interval: 60000,    // Check every minute
-    threshold: 100      // Clean when 100+ orphaned observables
+    interval:  60000, // run cleanup every 60 seconds (default)
+    threshold: 100    // only run when more than 100 entries exist (default)
 });
 ```
 
-## Performance Monitoring
+Use this in long-running applications to prevent the registry from growing unbounded.
+
+---
 
-### Debug Mode
+## MemoryManager API
+
+`MemoryManager` is the internal registry that tracks all observables via `WeakRef`. It is not exported but its behavior is exposed through `Observable` static methods.
+
+| Method | Description |
+|---|---|
+| `MemoryManager.register(observable)` | Registers an observable, returns its internal ID |
+| `MemoryManager.unregister(id)` | Removes an observable from the registry |
+| `MemoryManager.getObservableById(id)` | Retrieves an observable by ID (via `Observable.getById()`) |
+| `MemoryManager.cleanup()` | Calls `.cleanup()` on all registered observables and clears the registry |
+| `MemoryManager.cleanObservables(threshold)` | Removes entries for GC'd observables when registry size exceeds threshold |
+
+Access `getObservableById` via the public API:
+
+```javascript
+// getById is useful for debugging - the ID is the internal MemoryManager key
+// Access it via Observable.debug tools or the MemoryManager directly
+Observable.getById(1); // returns the first observable registered
+```
+
+---
+
+## Manual Subscriptions
+
+The most common source of memory leaks is forgetting to clean up manual subscriptions. `.subscribe()` does not return an unsubscribe function - use `.cleanup()` to remove all listeners, or `.off()` to remove a specific watcher registered via `.on()`:
 
 ```javascript
-// Enable memory debugging
-NativeDocument.debug.enable();
+const count = Observable(0);
+
+// Remove all listeners at once
+count.subscribe(value => console.log('Count:', value));
+count.cleanup();
 
-// Monitor cleanup events in console
-const obs = Observable("test");
-obs = null; // Will log cleanup when GC runs
+// Remove a specific .on() watcher
+const handler = isActive => console.log('Loading:', isActive);
+count.on('loading', handler);
+count.off('loading', handler);
 ```
 
-### Memory Leak Detection
+In element lifecycle hooks, only clean up **external resources**. Do not clean up observables unless the element is permanently destroyed:
 
 ```javascript
-// Check for potential leaks
-window.addEventListener('beforeunload', () => {
-    // Force cleanup on page unload
-});
+Div('Content')
+    .nd
+    .mounted(el => {
+        el.intervalId = setInterval(() => doWork(), 1000);
+    })
+    .unmounted(el => {
+        clearInterval(el.intervalId); // external resource - clean up
+        // do NOT call observable.cleanup() here unless permanently destroying
+    });
 ```
 
+---
+
+## Debug Mode
+
+Enable debug mode during development to log memory-related events:
+
+```javascript
+Observable.debug.enable();
+
+// MemoryManager will log when orphaned observables are cleaned:
+// "🧹 Cleaned 3 orphaned observables"
+```
+
+---
+
 ## 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
+1. Trust the automatic system - `WeakRef` + `FinalizationRegistry` handles most cases
+2. Always store and call the unsubscribe function for manual subscriptions
+3. Use `Observable.autoCleanup(true)` in long-running SPAs
+4. Only call `.cleanup()` manually when you need immediate release of resources
+5. In `unmounted()` hooks, only clean up external resources (timers, websockets) - not observables
+6. Use `Observable.resource()` for async data - it handles its own cleanup via `AbortController`
+
+---
 
 ## Next Steps
 
-- **[Anchor](docs/anchor.md)** - Anchor
+- **[Observables](./observables.md)** - `cleanup()`, `onCleanup()`, `autoCleanup()`
+- **[Lifecycle Events](./lifecycle-events.md)** - When to clean up in `unmounted()`
+- **[Observable Resource](./observable-resource.md)** - Async data with built-in cleanup
+- **[Anchor](./anchor.md)** - Anchor cleanup
+
+## Utilities
+
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[Filters](./filters.md)** - Data filtering helpers