native-document 1.0.15 → 1.0.16-8.1

package/docs/anchor.md

@@ -1,375 +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 an 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 using the alias
-const anchor = new NativeDocumentFragment("My Content");
-
-// In the DOM, this creates:
-// <!-- Anchor Start : My Content -->
-// <!-- / Anchor End My Content -->
-
-// Content can be inserted between these markers
-anchor.appendChild(Div("Dynamic content"));
-// <!-- Anchor Start : My Content -->
-// <div>Dynamic content</div>
-// <!-- / Anchor End My Content -->
-```
+import { Anchor } from 'native-document/elements';
 
-## Fragment vs Anchor
+const anchor = Anchor('My Section');
 
-**Fragment** is a wrapper around `document.createDocumentFragment()`:
+// Once in the DOM, creates:
+// <!-- Anchor Start : My Section -->
+// <!-- / Anchor End My Section -->
 
-```javascript
-// Fragment is standard DOM DocumentFragment
-const fragment = Fragment(); // Wraps document.createDocumentFragment()
-fragment.appendChild(Div("Standard fragment content"));
+anchor.appendChild(Div('Dynamic content'));
+// <!-- Anchor Start : My Section -->
+// <div>Dynamic content</div>
+// <!-- / Anchor End My Section -->
 ```
 
-**Anchor** is a NativeDocument class for dynamic content management:
+> `NativeDocumentFragment` is a valid alias for `Anchor` - both create the same system.
 
-```javascript
-// Anchor is a NativeDocument class
-const anchor = new Anchor("Dynamic Area");
-anchor.appendChild(Div("Dynamic content")); // Uses comment markers 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.
+
+---
 
-## Creating and Using Anchors
+## Fragment vs Anchor
 
-### Creating Anchors
+**`Fragment`** wraps `document.createDocumentFragment()` - for one-time static content grouping:
 
 ```javascript
-// Create anchor with custom identifier
-const contentAnchor = new Anchor("Content Area");
-const listAnchor = new Anchor("Todo List");
-
-// Anchor needs to be added to parent container
-const container = Div();
-container.appendChild(contentAnchor);
+const fragment = Fragment(
+    H1('Static Title'),
+    P('Static content')
+);
+// Replaced entirely when appended to parent
 ```
 
-### appendChild() - Add Content Between Markers
+**`Anchor`** is for dynamic content that updates over time:
 
 ```javascript
-const anchor = new Anchor("Dynamic Section");
-const container = Div();
-container.appendChild(anchor);
-
-// Add content between the markers
-anchor.appendChild(Div("Dynamic content 1"));
-anchor.appendChild(Div("Dynamic content 2"));
-
-// DOM structure:
-// <div>
-//   <!-- Anchor Start : Dynamic Section -->
-//   <div>Dynamic content 1</div>
-//   <div>Dynamic content 2</div>
-//   <!-- / Anchor End Dynamic Section -->
-// </div>
+const anchor = Anchor('Dynamic Area');
+anchor.appendChild(Div('Initial content'));
+anchor.replaceContent(Div('Updated content')); // markers stay, content swaps
 ```
 
-### insertBefore() - Positioned Insertion
+---
 
-```javascript
-const anchor = new Anchor("Ordered Content");
-const element1 = Div("First");
-const element2 = Div("Second");
+## Why Use Anchors?
 
-anchor.appendChild(element1);
-anchor.insertBefore(element2, element1); // Inserts before element1
-// Result: element2, element1
+Without an anchor you need a wrapper element:
+
+```javascript
+// Extra div in the DOM
+const wrapper = Div({ class: 'wrapper' });
+wrapper.appendChild(Div('Content'));
 ```
 
-### replaceContent() - Replace All Content
+With an anchor, no wrapper is needed:
 
 ```javascript
-const anchor = new Anchor("Replaceable");
-anchor.appendChild(Div("Old content"));
-
-// Replace all content between markers with new content
-anchor.replaceContent(Div("New content"));
+const anchor = Anchor('Content');
+anchor.appendChild(Div('Content'));
+// DOM: just the div between two comment nodes
 ```
 
-## Content Management Methods
+Benefits: no extra DOM nodes, cleaner HTML, no CSS interference from wrapper elements.
 
-### remove() vs removeChildren() vs clear()
+---
 
-```javascript
-const anchor = new Anchor("Content Management");
+## API Reference
 
-// Remove all content between markers (markers remain)
-anchor.remove(); // Content cleared, anchor can be reused
-anchor.removeChildren(); // Same as remove() - more explicit name
+### `appendChild(child)` / `append(child)`
 
-// Alias for remove() - clears content but keeps anchor
-anchor.clear();
-```
-
-### removeWithAnchors() - Complete Removal
+Inserts content before the end marker. Accepts an element, array, or any valid child:
 
 ```javascript
-// Remove markers AND all content permanently  
-anchor.removeWithAnchors(); // Destroys the entire anchor system
+anchor.appendChild(Div('Content'));
+anchor.appendChild([H1('Title'), P('Body'), Button('Action')]);
+anchor.append(Div('Same as appendChild'));
 ```
 
-## Anchor Access Methods
+### `insertAtStart(child)`
 
-### Access Markers
+Inserts content inside the anchor, immediately after the start marker - the opposite of `appendChild` which inserts before the end marker:
 
 ```javascript
-const anchor = new Anchor("My Anchor");
-
-// Get the start and end comment nodes
-const start = anchor.startElement();
-const end = anchor.endElement();
-
-console.log(start.textContent); // "Anchor Start : My Anchor"
-console.log(end.textContent);   // "/ Anchor End My Anchor"
+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 -->
 ```
 
-## Practical Usage Examples
+### `replaceContent(child)` / `setContent(child)`
 
-### Working with Arrays of Content
+Removes all current content and inserts new content in one operation:
 
 ```javascript
-const anchor = new Anchor("Multi Content");
-const container = Div();
-container.appendChild(anchor);
-
-// Insert multiple elements without a containing wrapper
-anchor.appendChild([
-    H1("Title"),
-    P("Paragraph"),
-    Button("Action")
-]);
-
-// DOM: No wrapper element, just the three elements between markers
+anchor.replaceContent(Div('New content'));
+anchor.setContent(Div('Same as replaceContent'));
 ```
 
-### Dynamic Content Updates
+Prefer `replaceContent()` over `remove()` + `appendChild()` - it's a single DOM operation.
 
-```javascript
-const contentAnchor = new Anchor("Dynamic Updates");
-const isLoading = Observable(true);
-const data = Observable(null);
+### `removeChildren()`
 
-// Initial loading state
-contentAnchor.appendChild(Div("Loading..."));
+Removes all content between the markers. The markers stay in place and the anchor can be reused. Children are **destroyed**:
 
-// Update content based on state changes
-isLoading.subscribe(loading => {
-    if (loading) {
-        contentAnchor.replaceContent(Div("Loading..."));
-    } else if (data.val()) {
-        contentAnchor.replaceContent(
-            Div(`Data: ${data.val()}`)
-        );
-    }
-});
+```javascript
+anchor.removeChildren(); // content gone, markers remain
+anchor.appendChild(Div('Fresh content')); // reuse the anchor
 ```
 
-## Built-in Components Using Anchors
+### `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()`
+
+Returns the current parent node:
 
-// 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
+```javascript
+const parent = anchor.getParent();
 ```
 
-### Match/Switch Components
+### `startElement()` / `endElement()`
 
-```javascript
-const currentView = Observable('loading');
+Returns the start or end comment node:
 
-// Match returns an anchor managing different content states
-const content = Match(currentView, {
-    loading: () => Div("Loading..."),
-    success: () => Div("Data loaded!"),
-    error: () => Div("Error occurred")
-});
+```javascript
+const start = anchor.startElement();
+const end   = anchor.endElement();
 
-currentView.set('success'); // Content switches without wrapper changes
+console.log(start.textContent); // "Anchor Start : My Section"
+console.log(end.textContent);   // "/ Anchor End My Section"
 ```
 
-## When to Use Fragment vs Anchor
+---
 
-### Use Fragment for:
-- **One-time content creation** that won't change
-- **Standard DOM operations** following web standards
-- **Static content grouping** before insertion
+## Method Aliases
 
-```javascript
-// Standard DocumentFragment behavior
-const fragment = Fragment(
-    H1("Static Title"),
-    P("Static content")
-);
-// Gets replaced entirely when appended to parent
-```
+| Primary | Aliases |
+|---|---|
+| `appendChild(child)` | `append(child)` |
+| `replaceContent(child)` | `setContent(child)` |
+| `removeWithAnchors()` | `delete()` |
 
-### Use Anchor for:
-- **Dynamic content management** that updates frequently
-- **Conditional rendering** systems
-- **List management** with add/remove operations
-- **Custom rendering patterns**
+---
 
-```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
-```
+## Practical Examples
 
-## Performance Considerations
+### Dynamic content updates
 
-### Memory Management
 ```javascript
-// Anchors are automatically cleaned up when removed from DOM
-const anchor = new Anchor("Temporary");
+const anchor = Anchor('Status');
+const isLoading = Observable(true);
+const data      = Observable(null);
 
-// Manual cleanup if needed
-anchor.removeWithAnchors(); // Fully destroys anchor and frees memory
-```
+anchor.appendChild(Div('Loading...'));
 
-### Batch Operations
-```javascript
-// Efficient: batch multiple updates
-const fragment = document.createDocumentFragment();
-fragment.appendChild(Div("Item 1"));
-fragment.appendChild(Div("Item 2"));
-anchor.appendChild(fragment);
-
-// Less efficient: individual appendChild calls
-anchor.appendChild(Div("Item 1"));
-anchor.appendChild(Div("Item 2"));
+isLoading.subscribe(loading => {
+    if (loading) {
+        anchor.replaceContent(Div('Loading...'));
+    } else {
+        anchor.replaceContent(
+            data.val()
+                ? Div(['Data: ', data.select(d => d.name)])
+                : Div('No data')
+        );
+    }
+});
 ```
 
-## Advanced Patterns
-
-### Creating Custom Anchor-Based Components
+### Custom anchor-based component
 
 ```javascript
-
 function ConditionalList(condition, items) {
-    const anchor = new Anchor("ConditionalList");
+    const anchor = Anchor('ConditionalList');
 
-    const updateContent = (value) => {
-        console.log(value);
-        if (value) {
-            const listItems = items.val().map(item => Li(item));
-            anchor.replaceContent(Ul(listItems));
+    const update = () => {
+        if (condition.val() && items.val().length) {
+            anchor.replaceContent(
+                Ul(items.val().map(item => Li(item)))
+            );
         } else {
-            anchor.remove();
+            anchor.removeChildren();
         }
     };
 
-    condition.subscribe(updateContent);
-    items.subscribe(updateContent);
-    updateContent(condition.val()); // Initial render
+    condition.subscribe(update);
+    items.subscribe(update);
+    update();
 
     return anchor;
 }
 
-// use ConditionalList
-const condition = new Observable(true);
+const condition = Observable(true);
+const items     = Observable.array([]);
 let id = 0;
-const items = new Observable.array([]);
 
 document.body.appendChild(Div([
     ConditionalList(condition, items),
-    Button("Toggle").nd.onClick(() => condition.set(!condition.val())),
-    Button("Add").nd.onClick(() => items.push('Item '+(++id))),
+    Button('Toggle').nd.onClick(() => condition.toggle()),
+    Button('Add').nd.onClick(() => items.push('Item ' + (++id)))
 ]));
 ```
 
-### Anchor-Based Layout Manager
+### Layout manager
 
 ```javascript
 function LayoutManager() {
-    const header = new Anchor("Header");
-    const content = new Anchor("Content");
-    const footer = new Anchor("Footer");
-    
+    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])
+        setHeader:  component => header.replaceContent(component),
+        setContent: component => content.replaceContent(component),
+        setFooter:  component => footer.replaceContent(component),
+        render:     () => Div([header, content, footer])
     };
 }
 ```
 
-## Best Practices
+---
 
-1. **Use descriptive anchor names** for easier debugging
-2. **Anchors are reusable** - Content can be added/removed multiple times
-3. **Use `removeWithAnchors()` only when permanently destroying** the anchor
-4. **Anchors are invisible** - They don't affect layout or styling
-5. **Prefer `replaceContent()` over `remove()` + `appendChild()`** for better performance
-6. **Create custom patterns** - Anchors enable custom rendering solutions
-7. **Consider memory implications** when creating many anchors
-8. **Use batch operations** for multiple content updates
+## How Conditional Rendering Uses Anchors
 
-## Common Pitfalls
+Every conditional and list rendering utility returns an anchor:
 
-❌ **Don't do this:**
 ```javascript
-// Inefficient - creates unnecessary DOM manipulations
-anchor.remove();
-anchor.appendChild(content1);
-anchor.remove();
-anchor.appendChild(content2);
+// 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
 ```
 
-✅ **Do this instead:**
-```javascript
-// Efficient - direct replacement
-anchor.replaceContent(content1);
-anchor.replaceContent(content2);
-```
+---
+
+## Best Practices
+
+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](getting-started.md)** - Installation and first steps
-- **[Core Concepts](core-concepts.md)** - Understanding the fundamentals
-- **[Observables](observables.md)** - Reactive state management
-- **[Elements](elements.md)** - Creating and composing UI
-- **[Conditional Rendering](conditional-rendering.md)** - Dynamic content
-- **[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
-- **[Memory Management](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