native-document 1.0.15 → 1.0.16-8.2

package/docs/list-rendering.md

@@ -1,607 +1,387 @@
-# List Rendering
-
-List rendering in NativeDocument provides powerful utilities for efficiently displaying dynamic collections of data. The framework offers two specialized functions: `ForEach` for generic iteration over objects and arrays, and `ForEachArray` for high-performance array-specific operations with advanced optimization features.
+---
+title: List Rendering
+description: Efficiently render dynamic collections with ForEach and ForEachArray - automatic DOM updates, keyed diffing, and reactive filtering
+---
 
-## Understanding List Rendering
+# List Rendering
 
-List rendering automatically manages DOM updates when your data changes. Instead of manually manipulating the DOM, you define how each item should be rendered, and NativeDocument handles creation, updates, reordering, and cleanup efficiently.
+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, Observable, Li, Ul } from 'native-document';
-
-const items = Observable.array(['Apple', 'Banana', 'Cherry']);
+import { ForEach, ForEachArray } from 'native-document/elements';
+```
 
-// Automatically updates when items change
-const itemList = Ul([
-    ForEach(items, item => Li(item))
-]);
+---
 
-// Add items - DOM updates automatically
-items.push('Orange', 'Grape');
-```
+## `ForEach` - Generic Collection Rendering
 
-## ForEach - Generic Collection Rendering
+`ForEach` works with both observable arrays and observable objects.
 
-`ForEach` is the versatile option that works with both arrays and objects. It's perfect when you need flexibility or are working with mixed data types.
+```javascript
+ForEach(data, callback, key?, options?)
+```
 
-### Basic Array Iteration
+### Array iteration
 
 ```javascript
 const fruits = Observable.array(['Apple', 'Banana', 'Cherry']);
 
-const FruitList = Ul([
-    ForEach(fruits, fruit => 
-        Li({ class: 'fruit-item' }, fruit)
-    )
-]);
+Ul(
+    ForEach(fruits, fruit => Li(fruit))
+)
 
-// All array operations trigger updates
-fruits.push('Orange');          // Adds new item
-fruits.splice(1, 1);           // Removes 'Banana'
-fruits.sort();                 // Reorders items
+// All array operations trigger DOM updates
+fruits.push('Orange');
+fruits.splice(1, 1);
+fruits.sort();
 ```
 
-### Object Iteration
+### Object iteration
 
 ```javascript
-const userRoles = Observable({
-    admin: 'Administrator',
-    editor: 'Content Editor', 
+const roles = Observable({
+    admin:  'Administrator',
+    editor: 'Content Editor',
     viewer: 'Read Only'
 });
 
-const RolesList = Ul([
-    ForEach(userRoles, (roleName, roleKey) => 
-        Li([
-            Strong(roleKey), ': ', roleName
-        ])
+Ul(
+    ForEach(roles, (roleName, roleKey) =>
+        Li([Strong(roleKey), ': ', roleName])
     )
-]);
-
-// Update object - DOM reflects changes
-userRoles.set({
-    ...userRoles.val(),
-    moderator: 'Community Moderator'
-});
+)
 ```
 
-### Using Index Parameter
+### Index parameter
+
+The second callback argument is an **observable** tracking the item's current index:
 
 ```javascript
-const tasks = Observable.array([
-    'Review pull requests',
-    'Update documentation',
-    'Fix bug reports'
-]);
+const tasks = Observable.array(['Review PRs', 'Update docs', 'Fix bugs']);
 
-const TaskList = Ol([
-    ForEach(tasks, (task, indexObservable) =>
-        Li([
-            Strong(indexObservable.get(val => val + 1)),
-            ' ',
-            task,
-            Button('Remove').nd.onClick(() =>
-                tasks.remove(indexObservable.val())
-            )
-        ])
-    )
-]);
+Ol(ForEach(tasks, (task, index) =>
+    Li([
+        Strong(index.transform(i => i + 1)), '. ',
+        task,
+        Button('Remove').nd.onClick(() => tasks.remove(index.val()))
+    ])
+))
 ```
 
-### Custom Key Functions
+### Key function
 
-Use custom key functions
+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' },
-    { id: 3, name: 'Carol', role: 'editor' }
+    { id: 2, name: 'Bob',   role: 'user' }
 ]);
 
-// Use 'id' field as the key for efficient updates
-const UserList = Div([
-    ForEach(users, 
-        user => Div({ class: 'user-card' }, [
-            H3(user.name),
-            Span({ class: 'role' }, user.role)
-        ]),
-        'id' // Key function - uses user.id
-        // Or (item) => item.id
-    )
-]);
+// Property name shorthand
+ForEach(users, user => Div(user.name), 'id')
 
-// When users reorder, DOM nodes are moved, not recreated
-users.set((items) => items.sort((a, b) => a.name.localeCompare(b.name)));
+// Function
+ForEach(users, user => Div(user.name), item => item.id)
 ```
 
-## ForEachArray - High-Performance Array Rendering
+### Options
 
-`ForEachArray` is specifically optimized for **arrays of complex objects** and provides superior performance. **Use ForEachArray for object arrays** - it's designed for array-specific operations.
+```javascript
+ForEach(data, callback, key, { shouldKeepItemsInCache: true })
+```
+
+`shouldKeepItemsInCache` - when `true`, rendered items stay in cache even when removed. Useful when items toggle frequently:
 
-### Why ForEachArray for Complex Arrays?
+```javascript
+// Items are cached - re-adding won't re-render them
+ForEach(items, renderItem, 'id', { shouldKeepItemsInCache: true })
+```
 
-`ForEachArray` includes optimizations that generic `ForEach` not provide:
+---
 
-- **Specialized diffing algorithm** optimized for array operations
-- **Batch DOM updates** for better performance
-- **Memory-efficient caching** with WeakMap references
-- **Array method detection** for targeted updates (push, splice, sort, etc.)
+## `ForEachArray` - High-Performance Array Rendering
 
-### Basic Usage
+`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 world!', timestamp: Date.now() },
+    { id: 1, text: 'Hello!',    timestamp: Date.now() },
     { id: 2, text: 'How are you?', timestamp: Date.now() + 1000 }
 ]);
 
-const ChatMessages = Div({ class: 'chat-container' }, [
-    ForEachArray(messages, message => 
+Div({ class: 'chat' },
+    ForEachArray(messages, message =>
         Div({ class: 'message' }, [
-            Div({ class: 'message-text' }, message.text),
-            Div({ class: 'timestamp' }, new Date(message.timestamp).toLocaleTimeString())
+            Div(message.text),
+            Div(new Date(message.timestamp).toLocaleTimeString())
         ])
     )
-]);
-
-// Optimized array operations
-messages.push({ id: 3, text: 'New message!', timestamp: Date.now() });
+)
 ```
 
-### Advanced Array Operations
+### Index in `ForEachArray`
 
-`ForEachArray` efficiently handles all array mutations:
+The index is a **computed observable** derived from the array - always reactive, no need to call `.val()` to use it in the DOM:
 
 ```javascript
-const playlist = Observable.array([
-    { id: 1, title: 'Song One', artist: 'Artist A' },
-    { id: 2, title: 'Song Two', artist: 'Artist B' },
-    { id: 3, title: 'Song Three', artist: 'Artist C' }
-]);
-
-const PlaylistView = Div({ class: 'playlist' }, [
-    ForEachArray(playlist, (song, indexObservable) => {
-
-        return Div({ class: 'song-item', style: 'display: flex; align-items: center; column-gap: 10px;' }, [
-            Div({ class: 'song-info' }, [
-                Strong(indexObservable.get((value) => value + 1)),
-                ' - ',
-                Strong(song.title),
-                Span({ class: 'artist' }, ` by ${song.artist}`)
-            ]),
-            Div({ class: 'song-controls' }, [
-                Button('↑').nd.onClick(() => {
-                    const index = indexObservable.$value;
-                    if(index > 0) {
-                        playlist.swap(index, index-1);
-                    }
-                }),
-                Button('↓').nd.onClick(() => {
-                    const index = indexObservable.$value;
-                    if(index < playlist.length()-1) {
-                        playlist.swap(index, index+1);
-                    }
-                }),
-                Button('Remove').nd.onClick(() =>{
-                    playlist.remove(indexObservable.$value);
-                })
-            ])
-        ])
-    }, 'id'),
-    Br,
+ForEachArray(playlist, (song, index) =>
     Div([
-        Button('Push ').nd.onClick(() => {
-            playlist.push({ id: 4, title: 'New Song', artist: 'New Artist' });
-        }),
-        Button('Unshift').nd.onClick(() => {
-            playlist.unshift({ id: 0, title: 'First Song', artist: 'First' })
+        index.transform(i => i + 1), '. ',
+        song.title,
+        Button('Up').nd.onClick(() => {
+            const i = index.$value;
+            if (i > 0) {
+                playlist.swap(i, i - 1);
+            }
         }),
-        Button('Reverse').nd.onClick(() => {
-            playlist.reverse()
+        Button('Down').nd.onClick(() => {
+            const i = index.$value;
+            if (i < playlist.val().length - 1) {
+                playlist.swap(i, i + 1);
+            }
         }),
-        Button('Sort').nd.onClick(() => {
-            playlist.sort((a, b) => a.title.localeCompare(b.title))
-        })
+        Button('Remove').nd.onClick(() => playlist.remove(index.$value))
     ])
-]);
-```
-
-### Custom Key Functions with ForEachArray
-
-Key functions are crucial for optimal performance with complex objects:
-
-```javascript
-const products = Observable.array([
-    { sku: 'PHONE-001', name: 'Smartphone', price: 599 },
-    { sku: 'LAPTOP-001', name: 'Laptop', price: 999 },
-    { sku: 'TABLET-001', name: 'Tablet', price: 399 }
-]);
-
-const ProductCatalog = Div({ class: 'catalog' }, [
-    ForEachArray(products,
-        product => Div({ class: 'product-card' }, [
-            H3(product.name),
-            Div({ class: 'price' }, `$${product.price}`),
-            Div({ class: 'sku' }, `SKU: ${product.sku}`)
-        ]),
-        'sku'  // Use SKU as key for efficient tracking
-    )
-]);
-
+)
 ```
 
-### Performance Configuration
-
-`ForEachArray` supports performance tuning for large datasets:
+### Configs
 
 ```javascript
-const bigDataset = Observable.array([...Array(10000)].map((_, i) => ({
-    id: i,
-    value: `Item ${i}`,
-    category: Math.floor(i / 100)
-})));
-
-const BigList = Div([
-    ForEachArray(bigDataset,
-        item => Div({ class: 'list-item' }, [
-            Strong(`#${item.id}`), ' - ', item.value
-        ]),
-        'id', // Key function
-        {
-            pushDelay: (items) => items.length > 100 ? 50 : 0  // Delay for large additions
-        }
-    )
-]);
-
-// Large additions are automatically throttled
-bigDataset.push(...[...Array(500)].map((_, i) => ({
-    id: 10000 + i,
-    value: `New Item ${i}`,
-    category: 999
-})));
+ForEachArray(data, callback, {
+    shouldKeepItemsInCache: false, // same as ForEach
+    pushDelay: (items) => items.length > 100 ? 50 : 0 // throttle large batch inserts
+})
 ```
 
-## Choosing Between ForEach and ForEachArray
-
-### Use ForEachArray When:
-
-✅ **Working with arrays of complex objects**  
-✅ **Performance is critical** - Large lists, frequent updates  
-✅ **Using array methods** - push, pop, splice, sort, reverse, etc.
-
-```javascript
-// Perfect for ForEachArray
-const comments = Observable.array([...]);
-const CommentList = ForEachArray(comments, comment => CommentComponent(comment));
-
-// Array operations work optimally
-comments.push(newComment);
-
-comments.splice(index, 1);
+---
 
-comments.sort((a, b) => b.timestamp - a.timestamp);
-```
+## Choosing Between `ForEach` and `ForEachArray`
 
-### Use ForEach When:
+| | `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 |
 
-✅ **Working with objects** - ForEach is required for object iteration  
-✅ **Mixed data types** - When data might be array or object  
-✅ **Arrays of primitive values** - string, number, boolean  
-✅ **Simple use cases** - Small lists with infrequent updates
+---
 
-## Real-World Examples
+## Filtering with `.where()`
 
-### Nested Lists with Mixed Rendering
+`.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
-const categories = Observable.array([
-    {
-        id: 1,
-        name: 'Electronics',
-        items: Observable.array([
-            { id: 101, name: 'Smartphone', price: 599 },
-            { id: 102, name: 'Laptop', price: 999 }
-        ])
-    },
-    {
-        id: 2, 
-        name: 'Books',
-        items: Observable.array([
-            { id: 201, name: 'JavaScript Guide', price: 29.99 },
-            { id: 202, name: 'Design Patterns', price: 39.99 }
-        ])
-    }
-]);
+import { equals, greaterThan, lessThan, between, includes, match,
+         startsWith, endsWith, inArray, notIn, custom,
+         and, or, not } from 'native-document/filters';
 
-const CategorizedProducts = Div({ class: 'product-categories' }, [
-    // Categories use ForEachArray (it's an array)
-    ForEachArray(categories, category => 
-        Div({ class: 'category' }, [
-            H3({ class: 'category-title' }, category.name),
-            
-            // Items within each category also use ForEachArray
-            ForEachArray(category.items,
-                item => Div({ class: 'product-item' }, [
-                    Span({ class: 'product-name' }, item.name),
-                    Span({ class: 'product-price' }, `$${item.price}`),
-                    Button('Add to Cart').nd.onClick(() => addToCart(item))
-                ]),
-                'id'
-            ),
-            
-            Button('Add Item').nd.onClick(() => {
-                const newItem = {
-                    id: Date.now(),
-                    name: `New ${category.name} Item`,
-                    price: Math.floor(Math.random() * 100) + 10
-                };
-                category.items.push(newItem);
-            })
-        ]),
-        'id'
-    )
+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' }
 ]);
 ```
 
-## Performance Best Practices
-
-### 1. Always Use Keys for Complex Objects
+### Comparison
 
 ```javascript
-// ✅ Good: Efficient updates and reordering
-ForEachArray(users, user => UserCard(user), 'id')
-ForEach(tags, tag => TagComponent(tag), 'index')
-
-// ❌ Poor: Inefficient, may cause unnecessary re-renders  
-ForEachArray(users, user => UserCard(user))
+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') })
 ```
 
-### 2. Choose the Right Function
+### String
 
 ```javascript
-// ✅ Perfect: ForEachArray for complex objects
-const users = Observable.array([{id: 1, name: 'Alice'}]);
-ForEachArray(users, renderUser, 'id')
-
-// ✅ Correct: ForEach for primitives
-const tags = Observable.array(['js', 'css']);
-ForEach(tags, renderTag)
-
-// ✅ Correct: ForEach for objects
-const config = Observable({theme: 'dark'});
-ForEach(config, renderSetting, (item, key) => key)
+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
 ```
 
-### 3. Use Computed Values for Derived Lists
+### Array membership
 
 ```javascript
-// ✅ Efficient: Computed filtered list
-const searchTerm = Observable('');
-const filteredItems = Observable.computed(() => 
-    allItems.val().filter(item => 
-        item.name.toLowerCase().includes(searchTerm.val().toLowerCase())
-    ),
-    [allItems, searchTerm]
-);
-
-ForEachArray(filteredItems, renderItem, 'id')
-
-// ❌ Inefficient: Filtering in render
-ForEachArray(allItems, item => {
-    if (item.name.includes(searchTerm.val())) {
-        return renderItem(item);
-    }
-    return null;
-})
+const allowed = Observable.array(['electronics', 'books']);
+
+products.where({ category: inArray(allowed) })   // reactive
+products.where({ category: notIn(['clothing']) })
 ```
 
-## Memory Management
+### Reactive filters
 
-Both `ForEach` and `ForEachArray` automatically manage memory:
+Pass an observable as the filter value - re-filters automatically when it changes:
 
 ```javascript
-// Cleanup is automatic when observables are garbage collected
-let myList = Observable.array([1, 2, 3]);
-let listComponent = ForEachArray(myList, item => Div(item));
+const search   = Observable('');
+const minPrice = Observable(0);
+const maxPrice = Observable(1000);
 
-// When references are lost, cleanup happens automatically
-myList = null;
-listComponent = null; // Memory will be freed
+const filtered = products.where({
+    name:  includes(search),
+    price: between(minPrice, maxPrice)
+});
 ```
 
-For explicit cleanup:
+### Custom filter
 
 ```javascript
-const items = Observable.array([...]);
-const listComponent = ForEachArray(items, renderItem);
+const minRating = Observable(4);
 
-// Manual cleanup when needed
-items.cleanup();
+products.where({
+    _: custom((product, min) => {
+        return product.rating >= min && product.reviews > 10;
+    }, minRating) // observables passed as extra args
+})
 ```
 
-## Common Pitfalls and Solutions
-
-### 1. Missing Keys with Complex Objects
+### Combining
 
 ```javascript
-// ❌ Problem: No key, inefficient updates
-ForEachArray(users, user => UserProfile(user))
-
-// ✅ Solution: Use unique key
-ForEachArray(users, user => UserProfile(user), 'id')
-```
+// and - field must pass ALL conditions
+products.where({ price: and(greaterThan(100), lessThan(500)) })
 
-### 2. Using ForEach for Complex Arrays
+// or - field must pass AT LEAST ONE
+products.where({ category: or(equals('electronics'), equals('books')) })
 
-```javascript
-// ❌ Suboptimal: Generic ForEach for arrays
-ForEach(genericObject, renderItem)
+// not - invert
+products.where({ inStock: not(equals(true)) })
 
-// ✅ Optimal: Specialized ForEachArray for arrays
-ForEachArray(arrayData, renderItem)
+// cross-field - use _ key with plain function
+products.where({
+    _: item => item.inStock && item.price < 500
+})
 ```
 
-### 3. Modifying Arrays Directly
+### Date and time filters
 
 ```javascript
-// ❌ Wrong: Direct mutation doesn't trigger updates
-items.val().push(newItem);
+import { dateEquals, dateBefore, dateAfter, dateBetween,
+    timeBefore, timeBetween } from 'native-document/filters';
 
-// ✅ Correct: Use Observable array methods
-items.push(newItem);
+const events = Observable.array([
+    { name: 'Meeting',    date: '2024-03-15' },
+    { name: 'Conference', date: '2024-06-20' }
+]);
 
-// ✅ Also correct: Set new array
-items.set([...items.val(), newItem]);
+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')
+    )})
 ```
 
-## Integration with Other Features
+---
 
-### With Conditional Rendering
+## Common Patterns
 
-```javascript
-const items = Observable.array([]);
-const showEmptyState = items.check(arr => arr.length === 0);
-
-const ItemList = Div([
-    ShowIf(showEmptyState, 
-        Div({ class: 'empty-state' }, 'No items found')
-    ),
-    HideIf(showEmptyState,
-        ForEachArray(items, item => ItemComponent(item), 'id')
-    )
-]);
-```
-
-### With Forms and Validation
+### Empty state
 
 ```javascript
-const formFields = Observable.array([
-    { name: 'firstName', label: 'First Name', value: '', required: true },
-    { name: 'lastName', label: 'Last Name', value: '', required: true },
-    { name: 'email', label: 'Email', value: '', required: true }
-]);
+const items = Observable.array([]);
 
-const DynamicForm = Form([
-    ForEachArray(formFields, field => 
-        Div({ class: 'form-group' }, [
-            Label(field.label + (field.required ? ' *' : '')),
-            Input({ 
-                name: field.name,
-                value: field.value,
-                required: field.required
-            }),
-            ShowIf(field.error, 
-                Div({ class: 'error' }, field.error)
-            )
-        ]),
-        'name'
-    ),
-    Button({ type: 'submit' }, 'Submit')
-]);
+Div([
+    ShowIf(items.isEmpty(), Div({ class: 'empty' }, 'No items yet')),
+    ForEachArray(items, item => ItemComponent(item))
+])
 ```
 
-## Advanced Patterns
-
-### Infinite Scrolling
+### Search + filter
 
 ```javascript
-const items = Observable.array([]);
-const isLoading = Observable(false);
-const hasMore = Observable(true);
-
-const loadMoreItems = async () => {
-    if (isLoading.val()) return;
-    
-    isLoading.set(true);
-    try {
-        const newItems = await fetchItems(items.val().length);
-        if (newItems.length === 0) {
-            hasMore.set(false);
-        } else {
-            items.push(...newItems);
-        }
-    } finally {
-        isLoading.set(false);
-    }
-};
+const search   = Observable('');
+const category = Observable('all');
 
-const InfiniteList = Div([
-    ForEachArray(items, item => ItemComponent(item), 'id'),
-    ShowIf(isLoading, LoadingSpinner()),
-    ShowIf(hasMore.check(more => more && !isLoading.val()),
-        Button('Load More').nd.onClick(loadMoreItems)
-    )
-]);
+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
+### Drag-and-drop reordering
 
 ```javascript
-const draggableItems = Observable.array([
-    { id: 1, text: 'Item 1' },
-    { id: 2, text: 'Item 2' },
-    { id: 3, text: 'Item 3' }
-]);
-
 let draggedIndex = null;
 
-const DraggableList = Div([
-    ForEachArray(draggableItems, (item, indexObservable) => 
-        Div({ 
-            class: 'draggable-item',
-            draggable: true
-        }, item.text)
-        .nd.onDragStart((e) => {
-            draggedIndex = indexObservable.val();
-        })
-        .nd.onDragOver((e) => e.preventDefault())
-        .nd.onDrop((e) => {
+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 = indexObservable.val();
+            const dropIndex = index.$value;
             if (draggedIndex !== null && draggedIndex !== dropIndex) {
-                const items = draggableItems.val();
-                const draggedItem = items[draggedIndex];
-                
-                // Remove from old position
-                items.splice(draggedIndex, 1);
-                // Insert at new position
-                items.splice(dropIndex, 0, draggedItem);
-                
-                draggableItems.set([...items]);
+                items.swap(draggedIndex, dropIndex);
             }
             draggedIndex = null;
-        }),
-        'id'
-    )
-]);
+        })
+)
 ```
 
-## Debugging List Rendering
-
-### Logging Updates
+### Infinite scroll
 
 ```javascript
-const items = Observable.array([]);
+const items     = Observable.array([]);
+const isLoading = Observable(false);
+const hasMore   = Observable(true);
 
-// Log all array operations
-items.subscribe((newItems, oldItems, operations) => {
-    console.log('Array operation:', operations);
-    console.log('Old items:', oldItems);
-    console.log('New items:', newItems);
-});
+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);
+};
 
-const DebugList = ForEachArray(items, (item, index) => {
-    console.log('Rendering item:', item, 'at index:', index?.val());
-    return ItemComponent(item);
-}, 'id');
+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
 
-Now that you understand list rendering, explore these related topics:
+- **[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
 
-- **[Conditional Rendering](conditional-rendering.md)** - Show/hide content dynamically
-- **[State Management](state-management.md)** - Managing application state
-- **[Memory Management](memory-management.md)** - Understanding cleanup and memory
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[Filters](./filters.md)** - Data filtering helpers