native-document 1.0.14 → 1.0.16-8.1

package/docs/anchor.md

@@ -1,212 +1,299 @@
+---
+title: Anchor
+description: Anchors enable dynamic DOM manipulation without wrapper elements using invisible comment node boundaries
+---
+
 # Anchor
 
-Anchors are a NativeDocument class that enables dynamic DOM manipulation without wrapper elements. They create two invisible comment nodes that act as boundaries, allowing you to insert, remove, and replace content between them.
+Anchors enable dynamic DOM manipulation without wrapper elements. They use two invisible comment nodes as boundaries, allowing you to insert, remove, and replace content between them while keeping your DOM clean.
 
-## What are Anchors?
+All conditional rendering and list rendering utilities in NativeDocument (`ShowIf`, `ForEach`, `Match`, etc.) are built on top of `Anchor`.
 
-Anchors are instances of the Anchor class that use two comment nodes as invisible markers:
+## What is an Anchor?
 
- `NativeDocumentFragment is Anchor alias`
+An `Anchor` creates two invisible comment nodes as markers in the DOM:
 
 ```javascript
-// Create an anchor instance
-const anchor = new Anchor("My Content");
-// Or
-// const anchor = new NativeDocumentFragment("My Content");
+import { Anchor } from 'native-document/elements';
+
+const anchor = Anchor('My Section');
 
-// In the DOM, this creates:
-// <!-- Anchor Start : My Content -->
-// <!-- / Anchor End My Content -->
+// Once in the DOM, creates:
+// <!-- Anchor Start : My Section -->
+// <!-- / Anchor End My Section -->
 
-// Content can be inserted between these markers
-anchor.appendChild(Div("Dynamic content"));
-// <!-- Anchor Start : My Content -->
+anchor.appendChild(Div('Dynamic content'));
+// <!-- Anchor Start : My Section -->
 // <div>Dynamic content</div>
-// <!-- / Anchor End My Content -->
+// <!-- / Anchor End My Section -->
 ```
 
+> `NativeDocumentFragment` is a valid alias for `Anchor` - both create the same system.
+
+> Anchors must be appended to a parent element before their methods work. The comment markers only exist once the anchor is in the DOM.
+
+---
+
 ## Fragment vs Anchor
 
-**Fragment** is a wrapper around `document.createDocumentFragment()`:
+**`Fragment`** wraps `document.createDocumentFragment()` - for one-time static content grouping:
 
 ```javascript
-// Fragment is standard DOM DocumentFragment
-const fragment = Fragment(); // Wraps document.createDocumentFragment()
-fragment.appendChild(Div("Standard fragment content"));
+const fragment = Fragment(
+    H1('Static Title'),
+    P('Static content')
+);
+// Replaced entirely when appended to parent
 ```
 
-**Anchor** is a NativeDocument class for dynamic content management:
+**`Anchor`** is for dynamic content that updates over time:
 
 ```javascript
-// Anchor is a NativeDocument class
-const anchor = new Anchor("Dynamic Area");
-anchor.appendChild(Div("Dynamic content")); // Uses comment markers system
+const anchor = Anchor('Dynamic Area');
+anchor.appendChild(Div('Initial content'));
+anchor.replaceContent(Div('Updated content')); // markers stay, content swaps
 ```
 
-## Dynamic Content Insertion
+---
 
-### Creating Anchors
+## Why Use Anchors?
 
-```javascript
-// Create anchor with custom identifier
-const contentAnchor = new Anchor("Content Area");
-const listAnchor = new Anchor("Todo List");
+Without an anchor you need a wrapper element:
 
-// Anchor needs to be added to parent container
-const container = Div();
-container.appendChild(contentAnchor);
+```javascript
+// Extra div in the DOM
+const wrapper = Div({ class: 'wrapper' });
+wrapper.appendChild(Div('Content'));
 ```
 
-### appendChild() - Add Content Between Markers
+With an anchor, no wrapper is needed:
 
 ```javascript
-const anchor = new Anchor("Dynamic Section");
-const container = Div();
-container.appendChild(anchor);
+const anchor = Anchor('Content');
+anchor.appendChild(Div('Content'));
+// DOM: just the div between two comment nodes
+```
 
-// Add content between the markers
-anchor.appendChild(Div("Dynamic content 1"));
-anchor.appendChild(Div("Dynamic content 2"));
+Benefits: no extra DOM nodes, cleaner HTML, no CSS interference from wrapper elements.
 
-// DOM structure:
-// <div>
-//   <!-- Anchor Start : Dynamic Section -->
-//   <div>Dynamic content 1</div>
-//   <div>Dynamic content 2</div>
-//   <!-- / Anchor End Dynamic Section -->
-// </div>
-```
+---
 
-### remove() - Clear Content Between Markers
+## API Reference
 
-```javascript
-// Remove all content between markers (markers remain)
-anchor.remove(); // Content cleared, anchor can be reused
+### `appendChild(child)` / `append(child)`
+
+Inserts content before the end marker. Accepts an element, array, or any valid child:
 
-// Remove markers and all content permanently  
-anchor.remove(true); // Destroys the entire anchor system
+```javascript
+anchor.appendChild(Div('Content'));
+anchor.appendChild([H1('Title'), P('Body'), Button('Action')]);
+anchor.append(Div('Same as appendChild'));
 ```
 
-### clear() - Empty Content
+### `insertAtStart(child)`
+
+Inserts content inside the anchor, immediately after the start marker - the opposite of `appendChild` which inserts before the end marker:
 
 ```javascript
-// Alias for remove() - clears content but keeps anchor
-anchor.clear();
+anchor.insertAtStart(Div('Just before the anchor start'));
+// DOM:
+// <!-- Anchor Start : My Section -->
+// <div>Just before the anchor start</div>  <- inserted here
+// ... anchor content ...
+// <!-- / Anchor End My Section -->
 ```
 
-## Anchor Methods
+### `replaceContent(child)` / `setContent(child)`
 
-### insertBefore() - Positioned Insertion
+Removes all current content and inserts new content in one operation:
 
 ```javascript
-const anchor = Fragment();
-const element1 = Div("First");
-const element2 = Div("Second");
-
-anchor.appendChild(element1);
-anchor.insertBefore(element2, element1); // Inserts before element1
-// Result: element2, element1
+anchor.replaceContent(Div('New content'));
+anchor.setContent(Div('Same as replaceContent'));
 ```
 
-### Access Markers
+Prefer `replaceContent()` over `remove()` + `appendChild()` - it's a single DOM operation.
 
-```javascript
-const anchor = Fragment();
+### `removeChildren()`
 
-// Get the start and end comment nodes
-const start = anchor.startElement();
-const end = anchor.endElement();
+Removes all content between the markers. The markers stay in place and the anchor can be reused. Children are **destroyed**:
 
-console.log(start.textContent); // "Anchor Start : Fragment"
-console.log(end.textContent);   // "/ Anchor End Fragment"
+```javascript
+anchor.removeChildren(); // content gone, markers remain
+anchor.appendChild(Div('Fresh content')); // reuse the anchor
 ```
 
-## Practical Usage with Conditionals
+### `remove()`
 
-### ShowIf with Anchors
+Moves all content out of the DOM back into the internal fragment - content is **preserved** but detached. The markers stay in place:
 
 ```javascript
-const isVisible = Observable(false);
+anchor.remove(); // content detached but kept internally
+anchor.appendChild(previousContent); // can be re-attached
+```
 
-// ShowIf returns an anchor, not a wrapper element
-const content = ShowIf(isVisible, () =>
-    Div("This content appears/disappears dynamically")
-);
+> **Difference:** `removeChildren()` destroys children. `remove()` moves them back into the fragment, preserving them for potential re-use.
 
-// No wrapper div created - content inserted directly between markers
-isVisible.set(true);  // Content appears between comment nodes
-isVisible.set(false); // Content disappears, markers remain for reuse
-```
+### `removeWithAnchors()` / `delete()`
 
-### ForEach with Anchors
+Destroys the content **and** removes the comment markers from the DOM. The anchor becomes unusable:
 
 ```javascript
-const items = Observable.array(["Item 1", "Item 2"]);
+anchor.removeWithAnchors(); // or anchor.delete()
+// anchor is now permanently gone
+```
 
-// ForEach returns an anchor managing multiple elements
-const list = ForEach(items, (item) => 
-    Div(item)
-);
+### `getParent()`
 
-// Multiple divs managed between the same anchor markers
-items.push("Item 3"); // New div inserted at anchor position
-items.splice(0, 1);   // First div removed, others shift within markers
+Returns the current parent node:
+
+```javascript
+const parent = anchor.getParent();
 ```
-:m
-### Multiple Elements Without Wrapper
+
+### `startElement()` / `endElement()`
+
+Returns the start or end comment node:
 
 ```javascript
-const anchor = new Anchor("Multi Content");
-const container = Div();
-container.appendChild(anchor);
+const start = anchor.startElement();
+const end   = anchor.endElement();
+
+console.log(start.textContent); // "Anchor Start : My Section"
+console.log(end.textContent);   // "/ Anchor End My Section"
+```
+
+---
+
+## Method Aliases
+
+| Primary | Aliases |
+|---|---|
+| `appendChild(child)` | `append(child)` |
+| `replaceContent(child)` | `setContent(child)` |
+| `removeWithAnchors()` | `delete()` |
+
+---
 
-// Insert multiple elements without a containing wrapper
-anchor.appendChild([
-    H1("Title"),
-    P("Paragraph"),
-    Button("Action")
-]);
+## Practical Examples
 
-// DOM: No wrapper element, just the three elements between markers
+### Dynamic content updates
+
+```javascript
+const anchor = Anchor('Status');
+const isLoading = Observable(true);
+const data      = Observable(null);
+
+anchor.appendChild(Div('Loading...'));
+
+isLoading.subscribe(loading => {
+    if (loading) {
+        anchor.replaceContent(Div('Loading...'));
+    } else {
+        anchor.replaceContent(
+            data.val()
+                ? Div(['Data: ', data.select(d => d.name)])
+                : Div('No data')
+        );
+    }
+});
 ```
 
-## Why Use Anchors vs Fragment?
+### Custom anchor-based component
+
+```javascript
+function ConditionalList(condition, items) {
+    const anchor = Anchor('ConditionalList');
+
+    const update = () => {
+        if (condition.val() && items.val().length) {
+            anchor.replaceContent(
+                Ul(items.val().map(item => Li(item)))
+            );
+        } else {
+            anchor.removeChildren();
+        }
+    };
+
+    condition.subscribe(update);
+    items.subscribe(update);
+    update();
+
+    return anchor;
+}
+
+const condition = Observable(true);
+const items     = Observable.array([]);
+let id = 0;
+
+document.body.appendChild(Div([
+    ConditionalList(condition, items),
+    Button('Toggle').nd.onClick(() => condition.toggle()),
+    Button('Add').nd.onClick(() => items.push('Item ' + (++id)))
+]));
+```
 
-**Use Fragment** for standard DOM operations:
+### Layout manager
 
 ```javascript
-// Standard DocumentFragment behavior
-const fragment = Fragment();
-fragment.appendChild(Div("Content"));
-// Gets replaced entirely when appended to parent
+function LayoutManager() {
+    const header  = Anchor('Header');
+    const content = Anchor('Content');
+    const footer  = Anchor('Footer');
+
+    return {
+        setHeader:  component => header.replaceContent(component),
+        setContent: component => content.replaceContent(component),
+        setFooter:  component => footer.replaceContent(component),
+        render:     () => Div([header, content, footer])
+    };
+}
 ```
 
-**Use Anchor (NativeDocumentFragment)** for dynamic content management:
+---
+
+## How Conditional Rendering Uses Anchors
+
+Every conditional and list rendering utility returns an anchor:
 
 ```javascript
-// Dynamic content area that can be updated multiple times
-const anchor = new Anchor("Updates");
-anchor.appendChild(Div("Initial content"));
-anchor.remove(); // Clear content
-anchor.appendChild(Div("New content")); // Add different content - markers remain
+// ShowIf returns an anchor
+const content = ShowIf(isVisible, () => Div('Hello'));
+isVisible.toggle(); // anchor replaces content between its markers
+
+// ForEach returns an anchor
+const list = ForEach(items, item => Div(item));
+items.push('New'); // anchor inserts new div before end marker
+
+// Match returns an anchor
+const view = Match(status, {
+    loading: Div('Loading...'),
+    success: Div('Done!')
+});
+status.set('success'); // anchor swaps content
 ```
 
+---
+
 ## Best Practices
 
-1. **Use anchors for custom rendering systems** - Build optimized conditional logic
-2. **Anchors are reusable** - Content can be added/removed multiple times
-3. **Use remove(true)** only when permanently destroying the anchor
-4. **Anchors are invisible** - They don't affect layout or styling
-5. **Create your own patterns** - Anchors enable custom rendering solutions that can outperform built-in functions
+1. Use descriptive names - they appear in DOM comments and help debugging
+2. Prefer `replaceContent()` over `remove()` + `appendChild()` - it's one DOM operation
+3. Use `removeChildren()` when you want to clear and reuse the anchor
+4. Use `removeWithAnchors()` / `delete()` only when permanently destroying the anchor
+5. Anchors must be in the DOM before their methods work - always append to a parent first
+
+---
 
 ## Next Steps
 
-- **[Getting Started](docs/getting-started.md)** - Installation and first steps
-- **[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
+- **[Conditional Rendering](./conditional-rendering.md)** - ShowIf, Match, Switch built on Anchor
+- **[List Rendering](./list-rendering.md)** - ForEach and ForEachArray built on Anchor
+- **[Elements](./elements.md)** - Creating and composing UI
+- **[Memory Management](./memory-management.md)** - Cleanup and memory management
+
+## 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/cache.md

@@ -0,0 +1,180 @@
+---
+title: Cache
+description: Lazy initialization, singleton patterns, and key-based memoization utilities
+---
+
+# Cache
+
+NativeDocument provides three caching utilities for optimizing function execution: lazy initialization, eager singletons, and key-based memoization.
+
+```javascript
+import { utils } from 'native-document';
+const { Cache } = utils;
+
+// Or
+import { Cache } from 'native-document/utils';
+```
+
+---
+
+## `Cache.once(fn)` - Lazy Initialization
+
+The function is **not executed immediately**. It runs only when you access a property on the returned Proxy object. The result is cached after the first access.
+
+```javascript
+const Config = Cache.once(() => {
+    console.log('Loading config...');
+    return {
+        apiUrl:     'https://api.example.com',
+        timeout:    5000,
+        maxRetries: 3
+    };
+});
+
+// Function not executed yet
+Config.apiUrl; // "Loading config..." -> "https://api.example.com"
+Config.timeout; // no log -> 5000 (cached)
+```
+
+Use for optional features or heavy modules that may not always be needed:
+
+```javascript
+const API = Cache.once(() => {
+    const client = new NativeFetch('https://api.example.com');
+    client.interceptors.request(config => {
+        config.headers['Authorization'] = `Bearer ${getToken()}`;
+        return config;
+    });
+    return {
+        users: {
+            list: ()   => client.get('/users'),
+            get:  (id) => client.get(`/users/${id}`)
+        }
+    };
+});
+
+// Client created only on first use
+const users = await API.users.list();
+```
+
+---
+
+## `Cache.singleton(fn)` - Eager Singleton
+
+The function executes on the **first call** and caches the result. All subsequent calls return the same instance.
+
+```javascript
+const getLogger = Cache.singleton(() => {
+    console.log('Creating logger...');
+    return {
+        log:   msg => console.log(`[LOG] ${msg}`),
+        error: msg => console.error(`[ERROR] ${msg}`)
+    };
+});
+
+const logger  = getLogger(); // "Creating logger..."
+const logger2 = getLogger(); // no log
+console.log(logger === logger2); // true
+```
+
+Use for core services that must exist exactly once:
+
+```javascript
+const getConfig = Cache.singleton(() => ({
+    apiUrl:  import.meta.env.VITE_API_URL,
+    debug:   import.meta.env.DEV,
+    version: '1.0.0'
+}));
+
+const getAPI = Cache.singleton(() => {
+    const config = getConfig();
+    const client = new NativeFetch(config.apiUrl);
+    client.interceptors.request(req => {
+        const token = localStorage.getItem('token');
+        if (token) {
+            req.headers['Authorization'] = `Bearer ${token}`;
+        }
+        return req;
+    });
+    return client;
+});
+```
+
+---
+
+## `Cache.memoize(fn)` - Key-Based Memoization
+
+Each property access creates and caches a **separate instance** using the property name as the key argument.
+
+```javascript
+const Endpoints = Cache.memoize((resource) => {
+    console.log(`Creating endpoint: ${resource}`);
+    const api = getAPI();
+    return {
+        list:   (params = {}) => api.get(`/${resource}`, params),
+        get:    (id)          => api.get(`/${resource}/${id}`),
+        create: (data)        => api.post(`/${resource}`, data),
+        update: (id, data)    => api.put(`/${resource}/${id}`, data),
+        delete: (id)          => api.delete(`/${resource}/${id}`)
+    };
+});
+
+await Endpoints.users.list();    // "Creating endpoint: users"
+await Endpoints.users.get('1');  // no log - cached
+await Endpoints.posts.list();    // "Creating endpoint: posts"
+```
+
+Use for resources that share the same structure but need separate instances per key:
+
+```javascript
+// Namespaced localStorage
+const Storage = Cache.memoize((namespace) => ({
+    get:    (key) => JSON.parse(localStorage.getItem(`${namespace}:${key}`)),
+    
+    set:    (key, val) => localStorage.setItem(`${namespace}:${key}`, JSON.stringify(val)),
+    
+    remove: (key) => localStorage.removeItem(`${namespace}:${key}`)
+}));
+
+Storage.user.set('theme', 'dark');
+Storage.app.set('version', '1.0.0');
+
+// Form fields with observables
+const Fields = Cache.memoize(name => ({
+    value:  Observable(''),
+    error:  Observable(null),
+    reset:  () => { Fields[name].value.set(''); Fields[name].error.set(null); }
+}));
+
+Fields.email.value.set('alice@example.com');
+Fields.password.value.set('secret');
+```
+
+---
+
+## Comparison
+
+| | `Cache.once()` | `Cache.singleton()` | `Cache.memoize()` |
+|---|---|---|---|
+| **Execution** | Lazy - on property access | Eager - on first call | Lazy - per key on property access |
+| **Access** | `obj.property` | `fn()` | `obj.key.method()` |
+| **Instances** | 1 | 1 | 1 per key |
+| **Best for** | Optional modules | Core services | Resources by type |
+
+---
+
+## Best Practices
+
+1. Use `Cache.singleton()` for core services (API client, config, logger)
+2. Use `Cache.once()` for optional or heavy modules that may not be needed
+3. Use `Cache.memoize()` for resources that share structure but need separate instances
+4. Keep memoize keys simple and predictable - avoid dynamic or timestamp-based keys
+5. Be aware that `Cache.memoize()` instances stay in memory - use only for a finite set of keys
+
+---
+
+## Next Steps
+
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[State Management](./state-management.md)** - Global state with Store
+- **[Observables](./observables.md)** - Reactive state management