native-document 1.0.165 → 1.0.168

package/docs/conditional-rendering.md

@@ -1,722 +1,304 @@
-# Conditional Rendering
-
-Conditional rendering in NativeDocument allows you to dynamically show, hide, or switch between different pieces of content based on reactive state. Unlike traditional approaches that require manual DOM manipulation, NativeDocument's conditional rendering utilities automatically update the interface when observable values change.
+---
+title: Conditional Rendering
+description: Dynamically show, hide, or switch between content based on reactive state - ShowIf, Switch, Match, When, and more
+---
 
-## Understanding Conditional Rendering
+# Conditional Rendering
 
-All conditional rendering functions in NativeDocument work with Observables and automatically manage DOM updates. When the condition changes, content is efficiently added or removed from the DOM without affecting other elements.
+NativeDocument's conditional rendering utilities automatically update the DOM when observable values change. All functions work with observables and manage DOM updates for you.
 
 ```javascript
-import { ShowIf, Button, Div, Observable } from 'native-document';
-
-const isVisible = Observable(false);
-
-// Content automatically appears/disappears based on isVisible
-const conditionalContent = ShowIf(isVisible, 'This content toggles!');
+import { ShowIf, HideIf, ShowWhen, Switch, Match, When } from 'native-document/elements';
 ```
 
-## ShowIf - Basic Conditional Display
+---
 
-The `ShowIf` function renders content only when the Observable condition is truthy. When false, the content is completely removed from the DOM.
+## `ShowIf` - Basic Conditional Display
+
+Renders content only when the condition is truthy. When false, the content is removed from the DOM.
 
 ```javascript
-const user = Observable({ name: 'Alice', isLoggedIn: false });
+const isVisible = Observable(false);
 
-const App = Div([
-    Button('Login').nd.onClick(() => 
-        user.set({ ...user.val(), isLoggedIn: true })
-    ),
-    Button('Logout').nd.onClick(() => 
-        user.set({ ...user.val(), isLoggedIn: false })
-    ),
-    
-    // Shows only when user is logged in
-    ShowIf(user.check(u => u.isLoggedIn), 'Welcome back!')
-]);
+ShowIf(isVisible, Div('Hello!'))
+
+// With a boolean (non-reactive)
+ShowIf(true, Div('Always visible'))
 ```
 
-### Dynamic Content Generation
+### Function children
 
-Use functions to create content that reflects current observable values:
+Pass a function to create content that reflects current observable values:
 
 ```javascript
 const notifications = Observable.array([]);
 
-const notificationBadge = ShowIf(
-    notifications.check(list => list.length > 0),
-    () => Span({ class: 'badge' }, `${notifications.val().length} new`)
-);
-
-// When notifications change, the badge updates automatically
-notifications.push('New message');
+ShowIf(notifications.isNotEmpty(),
+    () => Span({ class: 'badge' }, notifications.toLength())
+)
 ```
 
-### Using Observable Checkers
-
-Observable checkers create derived conditions for cleaner code:
+### Options
 
 ```javascript
-const temperature = Observable(25);
-const isCold = temperature.check(temp => temp < 15);
-const isHot = temperature.check(temp => temp > 30);
-
-const WeatherApp = Div([
-    Div(['Current temperature: ', temperature, '°C']),
-    ShowIf(isCold, Div({ class: 'cold' }, '🧥 It\'s cold! Wear a jacket.')),
-    ShowIf(isHot, Div({ class: 'hot' }, '☀️ It\'s hot! Stay hydrated.')),
-    Div([
-        Button('-').nd.onClick(() => --temperature.$value),
-        Button('+').nd.onClick(() => ++temperature.$value),
-    ])
-]);
+ShowIf(condition, content, {
+    comment:          'my-component', // label visible in DOM comments (debug)
+    shouldKeepInCache: false          // default true - set to false to recreate on each show
+})
 ```
 
-## HideIf and HideIfNot - Inverse Conditions
-
-These functions provide convenient inverses to `ShowIf`:
+### Practical example
 
 ```javascript
-const isLoading = Observable(true);
-const hasData = Observable(false);
-
-const DataDisplay = Div([
-    // Hide content while loading
-    HideIf(isLoading, Div('Data is ready to display')),
-    
-    // Show loading message only while loading
-    // Equivalent to ShowIf()
-    HideIfNot(isLoading, Div({ class: 'spinner' }, 'Loading...')),
+const user = Observable({ name: 'Alice', isLoggedIn: false });
+
+Div([
+    Button('Login').nd.onClick(() =>
+        user.set({ ...user.val(), isLoggedIn: true })
+    ),
+    ShowIf(user.is(u => u.isLoggedIn),
+        () => Div(['Welcome back, ', user.select(u => u.name), '!'])
+    )
 ]);
 ```
 
-**Understanding the differences:**
-```javascript
-const condition = Observable(true);
-
-// These are equivalent:
-ShowIf(condition, content)
-HideIfNot(condition, content)
-
-// These are equivalent:
-HideIf(condition, content)
-ShowIf(condition.check(val => !val), content)
-```
+---
 
-## ShowWhen - Observable Value Matching
+## `HideIf` / `HideIfNot` - Inverse Conditions
 
-`ShowWhen` is a specialized conditional function that shows content when an Observable matches a specific value. It's particularly useful for state machines and enum-based conditions.
+Convenient inverses of `ShowIf`:
 
-### Basic Usage
 ```javascript
-const status = Observable('idle');
+const isLoading = Observable(true);
 
-// Show content when status equals 'loading'
-const loadingIndicator = ShowWhen(status, 'loading', 
-    Div({ class: 'spinner' }, 'Loading...')
-);
+// Hide content while loading
+HideIf(isLoading, Div('Data is ready'))
 
-// Show content when status equals 'success'
-const successMessage = ShowWhen(status, 'success',
-    Div({ class: 'success' }, '✅ Success!')
-);
+// Show content only while loading (equivalent to ShowIf)
+HideIfNot(isLoading, Div('Loading...'))
 ```
 
-### Two Syntax Options
+Equivalences:
 
-**Option 1: Three arguments (Observable, value, content)**
 ```javascript
-const theme = Observable('light');
-
-ShowWhen(theme, 'dark', 
-    Div({ class: 'dark-mode-indicator' }, '🌙 Dark Mode')
-);
+ShowIf(condition, content)    // same as HideIfNot(condition, content)
+HideIf(condition, content)    // same as ShowIf(condition.isFalsy(), content)
 ```
 
-**Option 2: Two arguments (ObservableWhen result, content)**
-```javascript
-const theme = Observable('light');
-const isDark = theme.when('dark'); // Returns ObservableWhen
+---
 
-ShowWhen(isDark,
-    Div({ class: 'dark-mode-indicator' }, '🌙 Dark Mode')
-);
-```
+## `ShowWhen` - Value Matching
 
-### Practical Example: Status-Based UI
-```javascript
-const connectionStatus = Observable('disconnected');
+Shows content when an observable matches a specific value.
 
-const StatusIndicator = Div({ class: 'status-bar' }, [
-    ShowWhen(connectionStatus, 'connecting',
-        Span({ class: 'status connecting' }, '🔄 Connecting...')
-    ),
-    ShowWhen(connectionStatus, 'connected',
-        Span({ class: 'status connected' }, '✅ Connected')
-    ),
-    ShowWhen(connectionStatus, 'disconnected',
-        Span({ class: 'status disconnected' }, '❌ Disconnected')
-    ),
-    ShowWhen(connectionStatus, 'error',
-        Span({ class: 'status error' }, '⚠️ Connection Error')
-    )
-]);
-
-// Update status
-setTimeout(() => connectionStatus.set('connecting'), 1000);
-setTimeout(() => connectionStatus.set('connected'), 3000);
-```
+**Two-argument form** - pass an `ObservableWhen` result from `.when()`:
 
-Both can handle multiple states, but they serve different purposes:
 ```javascript
-const phase = Observable('loading');
-
-// ShowWhen: Multiple independent conditions
-Div([
-    ShowWhen(phase, 'loading', LoadingSpinner()),
-    ShowWhen(phase, 'success', SuccessMessage()),
-    ShowWhen(phase, 'error', ErrorMessage())
-]);
+const theme = Observable('light');
+const isDark = theme.when('dark'); // ObservableWhen result
 
-// Match: Single content area that switches
-Match(phase, {
-    loading: LoadingSpinner(),
-    success: SuccessMessage(),
-    error: ErrorMessage()
-});
+ShowWhen(isDark, Div('Dark mode active'))
 ```
 
-## Switch - Binary Content Switching
-
-`Switch` efficiently toggles between exactly two pieces of content based on a boolean condition:
+**Three-argument form** - pass the observable, the target value, and the content:
 
 ```javascript
-const isDarkMode = Observable(false);
-
-const ThemeToggle = Div([
-    Button('Toggle Theme').nd.onClick(() => isDarkMode.set(!isDarkMode.val())),
-    
-    Switch(isDarkMode,
-        Div({ class: 'dark-indicator' }, '🌙 Dark Mode'),    // when true
-        Div({ class: 'light-indicator' }, '☀️ Light Mode')   // when false
-    )
-]);
+ShowWhen(theme, 'dark', Div('Dark mode active'))
 ```
 
-### Dynamic Switch Content
-
-Functions allow for reactive content that updates with current values:
+### Practical example
 
 ```javascript
-const user = Observable({ name: 'Guest', isAuthenticated: false });
+const status = Observable('disconnected');
 
-const UserGreeting = Switch(
-    user.check(u => u.isAuthenticated),
-    () => Div({ class: 'welcome' }, `Welcome back, ${user.val().name}!`),
-    () => Div({ class: 'login-prompt' }, 'Please sign in to continue')
-);
+Div({ class: 'status-bar' }, [
+    ShowWhen(status, 'connecting',   Span('Connecting...')),
+    ShowWhen(status, 'connected',    Span('Connected')),
+    ShowWhen(status, 'disconnected', Span('Disconnected')),
+    ShowWhen(status, 'error',        Span('Connection Error'))
+]);
 ```
 
-## Match - Multiple Condition Handling
-
-`Match` provides switch-case like functionality for handling multiple states:
-
-```javascript
-const requestStatus = Observable('idle');
-
-const StatusDisplay = Match(requestStatus, {
-    idle: Div({ class: 'status-idle' }, 'Ready to make request'),
-    loading: Div({ class: 'status-loading' }, [
-        Span({ class: 'spinner' }),
-        ' Loading...'
-    ]),
-    success: Div({ class: 'status-success' }, '✅ Request completed'),
-    error: Div({ class: 'status-error' }, '❌ Request failed'),
-    timeout: Div({ class: 'status-timeout' }, '⏰ Request timed out')
-});
-```
+---
 
-### Dynamic Match Content
+## `Switch` - Binary Content
 
-Functions in Match provide access to current observable values:
+Toggles between exactly two pieces of content based on a boolean observable:
 
 ```javascript
-const gameState = Observable({ 
-    phase: 'menu', 
-    score: 0, 
-    level: 1 
-});
-
-const GameDisplay = Match(gameState.check(state => state.phase), {
-    menu: () => Div({ class: 'game-menu' }, [
-        H1('Welcome to the Game'),
-        Button('Start Game').nd.onClick(() => 
-            gameState.set({ ...gameState.val(), phase: 'playing' })
-        )
-    ]),
-    
-    playing: () => Div({ class: 'game-ui' }, [
-        Div(['Score: ', gameState.check(s => s.score)]),
-        Div(['Level: ', gameState.check(s => s.level)]),
-        Button('Pause').nd.onClick(() => 
-            gameState.set({ ...gameState.val(), phase: 'paused' })
-        ),
-        Button('Game Over').nd.onClick(() =>
-            gameState.set({ ...gameState.val(), phase: 'gameOver' })
-        )
-    ]),
-    
-    paused: () => Div({ class: 'game-paused' }, [
-        H2('Game Paused'),
-        Button('Resume').nd.onClick(() => 
-            gameState.set({ ...gameState.val(), phase: 'playing' })
-        )
-    ]),
-    
-    gameOver: () => Div({ class: 'game-over' }, [
-        H2('Game Over'),
-        Div(['Final Score: ', gameState.check(s => s.score)]),
-        Button('Play Again').nd.onClick(() => 
-            gameState.set({ phase: 'menu', score: 0, level: 1 })
-        )
-    ])
-});
-```
-
-### Match with Default Cases
-
-Handle unexpected values with default cases:
+const isDarkMode = Observable(false);
 
-```javascript
-const userRole = Observable('guest');
-
-const RoleBasedMenu = Match(userRole, {
-    admin: AdminMenu(),
-    moderator: ModeratorMenu(),
-    user: UserMenu(),
-    // Default case for unknown roles
-    default: GuestMenu()
-});
+Switch(isDarkMode,
+    Div('Dark mode'),   // when true
+    Div('Light mode')   // when false
+)
 ```
 
-## When - Fluent Builder Pattern
-
-`When` provides a chainable interface for conditional rendering:
+With function children:
 
 ```javascript
-const score = Observable(85);
+const user = Observable({ name: 'Guest', isLoggedIn: false });
 
-const GradeDisplay = When(score.check(s => s >= 90))
-    .show(() => Div({ class: 'grade-a' }, `Excellent! Score: ${score.val()}`))
-    .otherwise(() => Div({ class: 'grade-b' }, `Score: ${score.val()}`));
+Switch(user.is(u => u.isLoggedIn),
+    () => Div(['Welcome back, ', user.select(u => u.name)]),
+    () => Div('Please sign in')
+)
 ```
 
-### Complex Conditions with When
+> `Switch` is built on top of `Match` using `.toBoolean()`.
 
-```javascript
-const user = Observable({ 
-    age: 25, 
-    hasLicense: true, 
-    hasInsurance: false 
-});
-
-const DrivingEligibility = When(user.check(u => 
-    u.age >= 18 && u.hasLicense && u.hasInsurance
-))
-.show(() => Div({ class: 'eligible' }, [
-    '✅ You can drive legally',
-    Div(`Age: ${user.val().age}, License: Yes, Insurance: Yes`)
-]))
-.otherwise(() => {
-    const u = user.val();
-    const issues = [];
-    if (u.age < 18) issues.push('Must be 18 or older');
-    if (!u.hasLicense) issues.push('Need a valid license');
-    if (!u.hasInsurance) issues.push('Need insurance coverage');
-    
-    return Div({ class: 'not-eligible' }, [
-        '❌ Cannot drive legally',
-        Div(['Issues: ', issues.join(', ')])
-    ]);
-});
-```
+---
 
-## Practical Examples
+## `Match` - Multiple States
 
-### Form Validation with Progressive Disclosure
+Handles multiple states like a switch-case. Each key maps to a content value or function:
 
 ```javascript
-const formData = Observable.object({
-    email: '',
-    password: '',
-    confirmPassword: ''
-});
-
-const isValidEmail = formData.email.check(e => 
-    e.includes('@') && e.includes('.') && e.length > 5
-);
-
-const isValidPassword = formData.password.check(p => p.length >= 8);
-
-const passwordsMatch = Observable.computed(() => {
-    const data = formData.$value;
-    return data.password === data.confirmPassword && data.password.length > 0;
-}, [formData.password, formData.confirmPassword]);
-
-const canSubmit = Observable.computed(() => 
-    isValidEmail.val() && isValidPassword.val() && passwordsMatch.val(),
-    [isValidEmail, isValidPassword, passwordsMatch]
-);
+const status = Observable('idle');
 
-const RegistrationForm = Div({ class: 'registration-form' }, [
-    // Email field with validation
-    Input({ 
-        type: 'email', 
-        placeholder: 'Email', 
-        value: formData.email 
-    }),
-    ShowIf(formData.email.check(e => e.length > 0 && !isValidEmail.val()),
-        Div({ class: 'error' }, 'Please enter a valid email address')
-    ),
-    
-    // Password field
-    Input({ 
-        type: 'password', 
-        placeholder: 'Password', 
-        value: formData.password 
-    }),
-    ShowIf(formData.password.check(p => p.length > 0 && p.length < 8),
-        Div({ class: 'error' }, 'Password must be at least 8 characters')
-    ),
-    
-    // Confirm password (only show after password is valid)
-    ShowIf(isValidPassword, [
-        Input({ 
-            type: 'password', 
-            placeholder: 'Confirm Password', 
-            value: formData.confirmPassword 
-        }),
-        ShowIf(formData.confirmPassword.check(p => p.length > 0 && !passwordsMatch.val()),
-            Div({ class: 'error' }, 'Passwords do not match')
-        )
-    ]),
-    
-    // Submit button
-    Switch(canSubmit,
-        Button('Create Account').nd.onClick(() => {
-            console.log('Creating account...', formData.$value);
-        }),
-        Button({ disabled: true, class: 'disabled' }, 'Create Account')
-    )
-]);
+Match(status, {
+    idle:    Div('Ready'),
+    loading: Div('Loading...'),
+    success: Div('Done!'),
+    error:   Div('Something went wrong'),
+    default: Div('Unknown state')
+})
 ```
 
-### Progressive User Interface
+With function values for access to current observable state:
 
 ```javascript
-const appState = Observable.object({
-    user: null,
-    currentView: 'welcome',
-    settings: { theme: 'light', notifications: true }
-});
+const phase = Observable('menu');
 
-const isLoggedIn = appState.user.check(user => user !== null);
-const isGuest = appState.user.check(user => user === null);
-
-const App = Div({ class: 'app' }, [
-    // Header - changes based on auth state
-    Header({ class: 'app-header' }, [
-        H1('My App'),
-        Switch(isLoggedIn,
-            // Authenticated header
-            () => Div({ class: 'user-menu' }, [
-                Span(['Welcome, ', appState.user.val().name]),
-                Button('Settings').nd.onClick(() => 
-                    appState.currentView.set('settings')
-                ),
-                Button('Logout').nd.onClick(() => {
-                    appState.user.set(null);
-                    appState.currentView.set('welcome');
-                })
-            ]),
-            // Guest header
-            Div({ class: 'auth-buttons' }, [
-                Button('Sign In').nd.onClick(() => 
-                    appState.currentView.set('login')
-                ),
-                Button('Sign Up').nd.onClick(() => 
-                    appState.currentView.set('register')
-                )
-            ])
-        )
+Match(phase, {
+    menu: () => Div([
+        H1('Welcome'),
+        Button('Start').nd.onClick(() => phase.set('playing'))
     ]),
-    
-    // Main content area
-    Match(appState.currentView, {
-        welcome: WelcomeView(),
-        login: LoginView(appState),
-        register: RegisterView(appState),
-        dashboard: When(isLoggedIn)
-            .show(() => DashboardView(appState.user.val()))
-            .otherwise(() => {
-                appState.currentView.set('welcome');
-                return Div('Redirecting...');
-            }),
-        settings: When(isLoggedIn)
-            .show(() => SettingsView(appState))
-            .otherwise(() => {
-                appState.currentView.set('welcome');
-                return Div('Please log in to access settings');
-            })
-    })
-]);
-```
-
-## Performance Considerations
-
-### Efficient Content Updates
-
-NativeDocument optimizes conditional rendering by only updating the DOM when conditions actually change:
-
-```javascript
-const isVisible = Observable(true);
-
-// This content is created once and reused
-const expensiveContent = ShowIf(isVisible, () => {
-    console.log('Creating expensive content'); // Only called when becoming visible
-    return createComplexComponent();
-});
-
-// Toggling rapidly won't recreate content unnecessarily
-isVisible.set(false);
-isVisible.set(true); // Content is recreated
-isVisible.set(true); // No recreation, already visible
+    playing: () => Div([
+        Div(['Score: ', score]),
+        Button('Pause').nd.onClick(() => phase.set('paused'))
+    ]),
+    paused: () => Div([
+        H2('Paused'),
+        Button('Resume').nd.onClick(() => phase.set('playing'))
+    ])
+})
 ```
 
-### Memory Management
+### Dynamic add / remove
 
-Functions in conditional rendering are called only when needed, preventing memory waste:
+`Match` exposes `.add()` and `.remove()` methods to update the available states at runtime:
 
 ```javascript
-const currentTab = Observable('home');
-
-// Heavy components only created when their tab is active
-const TabContent = Match(currentTab, {
-    home: () => {
-        console.log('Creating home tab');
-        return HomeTabComponent(); // Only created when needed
-    },
-    profile: () => {
-        console.log('Creating profile tab');
-        return ProfileTabComponent(); // Only created when needed
-    },
-    settings: () => {
-        console.log('Creating settings tab');
-        return SettingsTabComponent(); // Only created when needed
-    }
+const view = Match(status, {
+    idle:    Div('Ready'),
+    loading: Div('Loading...')
 });
-```
-
-### Avoiding Unnecessary Computations
-
-Use Observable.computed for expensive condition calculations:
 
-```javascript
-const items = Observable.array([...largeDataset]);
-const searchTerm = Observable('');
-
-// Computed once, reused in multiple places
-const filteredItems = Observable.computed(() => {
-    return items.val().filter(item => 
-        item.name.toLowerCase().includes(searchTerm.val().toLowerCase())
-    );
-}, [items, searchTerm]);
-
-const hasResults = filteredItems.check(results => results.length > 0);
+// Add a new state
+view.nd.add('success', Div('Done!'));
+view.nd.add('success', Div('Done!'), true); // third arg: immediately switch to this state
 
-const SearchResults = Div([
-    ShowIf(hasResults, () => 
-        ForEach(filteredItems, item => ItemComponent(item))
-    ),
-    HideIf(hasResults, 'No results found')
-]);
+// Remove a state
+view.nd.remove('idle');
 ```
 
-## Best Practices
+### `shouldKeepInCache`
 
-### 1. Choose the Right Tool
+By default, `Match` caches each rendered state. Pass `false` to recreate content on every switch:
 
 ```javascript
-// Good: Use ShowIf for simple boolean conditions
-ShowIf(isVisible, content)
-
-// Good: Use Switch for binary choices
-Switch(isLoggedIn, welcomeMessage, loginPrompt)
-
-// Good: Use Match for multiple states
-Match(status, { loading: '...', success: '...', error: '...' })
-
-// Less ideal: Using Match for simple boolean
-Match(isVisible, { true: content, false: null })
+Match(status, { loading: Div('...'), success: Div('Done') }, false)
 ```
 
-### 2. Use Functions for Dynamic Content
+---
 
-```javascript
-// Good: Function creates fresh content with current values
-ShowIf(user.check(u => u.isAdmin), 
-    () => Div(`Admin: ${user.val().name}`)
-)
+## `When` - Fluent Builder
 
-// Problematic: Static content won't update
-ShowIf(user.check(u => u.isAdmin), 
-    Div(`Admin: ${user.val().name}`) // Name won't update if user changes
-)
-```
-
-### 3. Combine Conditions Logically
+A chainable interface for conditional rendering:
 
 ```javascript
-// Good: Use computed observables for complex conditions
-const canEdit = Observable.computed(() => {
-    const u = user.val();
-    const p = post.val();
-    return u.isLoggedIn && (u.role === 'admin' || u.id === p.authorId);
-}, [user, post]);
-
-ShowIf(canEdit, editButton)
+const score = Observable(85);
 
-// Less maintainable: Inline complex logic
-ShowIf(user.check(u => u.isLoggedIn && u.role === 'admin'), editButton)
+When(score.isGreaterThanOrEqualTo(90))
+    .show(() => Div('Excellent!'))
+    .otherwise(() => Div('Keep going'))
 ```
 
-### 4. Handle Edge Cases Gracefully
+Convert to a DOM element explicitly with `.toNdElement()`:
 
 ```javascript
-// Good: Defensive programming
-ShowIf(data.check(d => d && d.items && d.items.length > 0),
-    () => ForEach(data.val().items, renderItem)
-)
+const greeting = When(isLoggedIn)
+    .show(() => Div('Welcome back!'))
+    .otherwise(() => Div('Please sign in'));
 
-// Risky: Might throw errors on null/undefined
-ShowIf(data.check(d => d.items.length > 0), content)
+// .otherwise() already returns the element
+// .toNdElement() is available if you build the chain without calling .otherwise()
+const el = greeting.toNdElement();
 ```
 
-### 5. Use Meaningful Variable Names
+---
 
-```javascript
-// Good: Clear intent
-const isUserAuthenticated = user.check(u => u.token !== null);
-const hasUnreadMessages = messages.check(m => m.some(msg => !msg.read));
+## Choosing the Right Tool
 
-ShowIf(hasUnreadMessages, notificationBadge)
+| Situation | Use |
+|---|---|
+| Simple show / hide | `ShowIf` |
+| Inverse show / hide | `HideIf` / `HideIfNot` |
+| Show when value matches | `ShowWhen` |
+| Two options (true / false) | `Switch` |
+| Multiple named states | `Match` |
+| Fluent chaining style | `When` |
 
-// Less clear: Generic names
-const check1 = user.check(u => u.token !== null);
-const check2 = messages.check(m => m.some(msg => !msg.read));
-```
+---
 
-## Common Patterns
+## Best Practices
 
-### Loading States with Error Handling
+**Use functions for dynamic content** - static values are evaluated once at creation time:
 
 ```javascript
-const requestState = Observable.object({
-    status: 'idle', // idle, loading, success, error
-    data: null,
-    error: null
-});
+// Good - content reflects current value when shown
+ShowIf(isAdmin, () => Div(user.select(u => u.name)))
 
-const DataView = Match(requestState.status, {
-    idle: Button('Load Data').nd.onClick(loadData),
-    loading: Div({ class: 'loading' }, 'Loading...'),
-    success: () => DataDisplay(requestState.data.val()),
-    error: () => Div({ class: 'error' }, [
-        'Error: ', requestState.error,
-        Button('Retry').nd.onClick(loadData)
-    ])
-});
+// Risky - name captured at creation, won't update
+ShowIf(isAdmin, Div(user.val().name))
 ```
 
-### Feature Flags and Progressive Enhancement
+**Use `Observable.computed()` for complex conditions:**
 
 ```javascript
-const features = Observable.object({
-    darkMode: true,
-    newDashboard: false,
-    betaFeatures: false
-});
+const canEdit = Observable.computed((u, p) =>
+    u.isLoggedIn && (u.role === 'admin' || u.id === p.authorId),
+    [user, post]
+);
 
-const App = Div([
-    // Theme switching
-    Switch(features.darkMode,
-        Div({ class: 'app dark-theme' }, content),
-        Div({ class: 'app light-theme' }, content)
-    ),
-    
-    // Beta features for power users
-    ShowIf(features.betaFeatures, BetaPanel()),
-    
-    // A/B testing new dashboard
-    Switch(features.newDashboard,
-        NewDashboard(),
-        LegacyDashboard()
-    )
-]);
+ShowIf(canEdit, editButton)
 ```
 
-## Debugging Conditional Rendering
-
-### Using Console Logs in Conditions
+**Use shorthand checkers instead of manual conditions:**
 
 ```javascript
-const debugCondition = condition.check(value => {
-    console.log('Condition evaluated:', value);
-    return value > 10;
-});
+// Good
+ShowIf(list.isEmpty(), Div('No items'))
+ShowIf(name.isTruthy(), Div(['Hello, ', name]))
 
-ShowIf(debugCondition, content);
+// Avoid
+ShowIf(list.check(l => l.length === 0), Div('No items'))
 ```
 
-### Tracking State Changes
-
-```javascript
-const status = Observable('idle');
-
-// Log all status changes
-status.subscribe(newStatus => {
-    console.log('Status changed to:', newStatus);
-});
-
-// Debug what content is being rendered
-const StatusContent = Match(status, {
-    idle: () => {
-        console.log('Rendering idle state');
-        return IdleComponent();
-    },
-    loading: () => {
-        console.log('Rendering loading state');
-        return LoadingComponent();
-    }
-});
-```
+---
 
 ## Next Steps
 
-Now that you understand conditional rendering, explore these related topics:
-
-- **[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
-- **[Lifecycle Events](lifecycle-events.md)** - Lifecycle events
-- **[NDElement](native-document-element.md)** - Native Document Element
-- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
-- **[Advanced Components](advanced-components.md)** - Template caching and singleton views
-- **[Args Validation](validation.md)** - Function Argument Validation
-- **[Memory Management](memory-management.md)** - Memory management
-- **[Anchor](anchor.md)** - Anchor
+- **[List Rendering](./list-rendering.md)** - ForEach and dynamic lists
+- **[Observables](./observables.md)** - Reactive state management
+- **[Elements](./elements.md)** - Creating and composing UI
+- **[State Management](./state-management.md)** - Global state patterns
+- **[Anchor](./anchor.md)** - How conditional rendering works under the hood
 
 ## Utilities
 
-- **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
-- **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
-- **[Filters](docs/utils/filters.md)** - Data filtering helpers
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[Filters](./filters.md)** - Data filtering helpers