State Management

State management in WildflowerJS is built around reactive data that automatically updates the UI when changed. Learn how to manage component state, computed properties, and cross-component communication.

Basic State Management

Defining Component State

State is defined in the component's state property and becomes automatically reactive:

wildflower.component('user-profile', {
    state: {
        // Primitive values
        name: 'John Doe',
        age: 30,
        isActive: true,
        
        // Objects
        address: {
            street: '123 Main St',
            city: 'Springfield',
            zipCode: '12345'
        },
        
        // Arrays
        hobbies: ['reading', 'hiking', 'cooking'],
        
        // Complex nested data
        settings: {
            notifications: {
                email: true,
                push: false
            }
        }
    }
})

Reading State

Access state values directly via this in component methods. The framework's context proxy resolves this.count to the underlying state.count, and this.count = 5 writes to it reactively:

wildflower.component('counter', {
    state: {
        count: 0,
        step: 1
    },

    getCurrentCount() {
        return this.count  // Resolves to state.count
    },

    increment() {
        this.count += this.step  // Read and modify
    }
})

Updating State

State updates automatically trigger UI re-renders:

<div data-component="state-demo">
    <div class="my-3">
        <p><strong>Count:</strong> <span data-bind="count">0</span></p>
        <p><strong>Status:</strong> <span data-bind="message">System ready.</span></p>
        <p><strong>User:</strong> <span data-bind="user.name">John</span> (<span data-bind="user.age">25</span>)</p>
    </div>
    
    <div class="my-3">
        <button class="btn btn-primary btn-sm me-2 mb-2" data-action="incrementCount">
            Increment Count
        </button>
        <button class="btn btn-success btn-sm me-2 mb-2" data-action="updateMessage">
            Trigger Event
        </button>
        <button class="btn btn-info btn-sm me-2 mb-2" data-action="updateUser">
            Update User
        </button>
        <button class="btn btn-danger btn-sm mb-2" data-action="resetAll">
            Reset All
        </button>
    </div>
    
    <div class="my-3">
        <h5>Update History:</h5>
        <div data-list="history" class="border rounded p-2" style="max-height: 150px; overflow-y: auto;">
            <template>
                <div class="border-bottom pb-1 mb-1 small">
                    <span data-bind="timestamp"></span> - <span data-bind="action"></span>
                </div>
            </template>
        </div>
    </div>
</div>

wildflower.component('state-demo', {
    state: {
        count: 0,
        message: 'System ready.',
        user: {
            name: 'John',
            age: 25
        },
        history: []
    },
    
    addToHistory(action) {
        this.history.unshift({
            timestamp: new Date().toLocaleTimeString(),
            action: action
        })

        // Keep only last 10 items
        if (this.history.length > 10) {
            this.history = this.history.slice(0, 10)
        }
    },

    incrementCount() {
        this.count++
        this.addToHistory(`Count incremented to ${this.count}`)
    },

    updateMessage() {
        const messages = [
            'User logged in.',
            'Settings saved.',
            'Data synchronized.',
            'Cache cleared.',
            'Session refreshed.'
        ]
        this.message = messages[Math.floor(Math.random() * messages.length)]
        this.addToHistory(`Status: ${this.message}`)
    },

    updateUser() {
        const names = ['Alice', 'Bob', 'Carol', 'David', 'Eve']
        const ages = [22, 25, 28, 31, 35]

        this.user.name = names[Math.floor(Math.random() * names.length)]
        this.user.age = ages[Math.floor(Math.random() * ages.length)]
        this.addToHistory(`User updated to: ${this.user.name}, age ${this.user.age}`)
    },

    resetAll() {
        this.count = 0
        this.message = 'System ready.'
        this.user = { name: 'John', age: 25 }
        this.history = []
        this.addToHistory('System reset complete.')
    }
})

Computed Properties

Defining Computed Properties

Computed properties derive values from state and are automatically cached and updated:

<div data-component="shopping-cart">
    <div class="my-3">
        <button class="btn btn-success btn-sm me-2" data-action="addRandomItem">
            Add Random Item
        </button>
        <button class="btn btn-danger btn-sm" data-action="clearCart">
            Clear Cart
        </button>
    </div>
    
    <div data-show="hasItems">
        <h5>Cart Items:</h5>
        <div data-list="items" class="my-3">
            <template>
                <div class="d-flex justify-content-between p-2 border-bottom">
                    <span>
                        <span data-bind="name"></span> × <span data-bind="quantity"></span>
                        @ $<span data-bind="price"></span>
                    </span>
                    <span>$<span data-bind="(price * quantity).toFixed(2)"></span></span>
                </div>
            </template>
        </div>
        
        <div class="border-top pt-3 fw-bold">
            <div class="d-flex justify-content-between">
                <span>Items:</span>
                <span data-bind="itemCount"></span>
            </div>
            <div class="d-flex justify-content-between">
                <span>Subtotal:</span>
                <span>$<span data-bind="subtotal"></span></span>
            </div>
            <div class="d-flex justify-content-between">
                <span>Tax (8%):</span>
                <span>$<span data-bind="tax"></span></span>
            </div>
            <div class="d-flex justify-content-between fs-5 text-success">
                <span>Total:</span>
                <span data-bind="formattedTotal"></span>
            </div>
        </div>
    </div>
    
    <div data-show="!hasItems" class="text-center text-muted py-5">
        Your cart is empty. Add some items!
    </div>
</div>

wildflower.component('shopping-cart', {
    state: {
        items: [],
        taxRate: 0.08
    },
    
    computed: {
        // Simple computed property
        itemCount() {
            return this.items.length
        },

        // Complex calculation
        subtotal() {
            return this.items.reduce((sum, item) =>
                sum + (item.price * item.quantity), 0
            ).toFixed(2)
        },

        // Computed using other computeds (this.subtotal resolves to computed)
        tax() {
            return (parseFloat(this.subtotal) * this.taxRate).toFixed(2)
        },

        total() {
            return (parseFloat(this.subtotal) + parseFloat(this.tax)).toFixed(2)
        },

        // Formatted output
        formattedTotal() {
            return '$' + this.total
        },

        // Boolean computed property
        hasItems() {
            return this.items.length > 0
        }
    },

    addRandomItem() {
        const products = [
            { name: 'Laptop', price: 999 },
            { name: 'Mouse', price: 25 },
            { name: 'Keyboard', price: 75 },
            { name: 'Monitor', price: 299 },
            { name: 'Headphones', price: 149 }
        ]

        const product = products[Math.floor(Math.random() * products.length)]

        this.items.push({
            ...product,
            quantity: Math.floor(Math.random() * 3) + 1
        })
    },

    clearCart() {
        this.items = []
    }
})

Computed Property Benefits

Item-Level Computed Properties

For per-item calculations in lists, use item-level computed properties. The framework automatically detects these by checking if the function has parameters (fn.length > 0).

wildflower.component('product-list', {
    state: {
        products: [{ id: 1, name: 'Widget', price: 10 }],
        taxRate: 0.1
    },

    subscribe: {
        'cart': ['items']
    },

    computed: {
        // Component-level (no parameters)
        totalProducts() {
            return this.products.length;
        },

        // Item-level (has parameters) - evaluated per list item
        priceWithTax(item) {
            return '$' + (item.price * (1 + this.taxRate)).toFixed(2);
        },

        // Can access store state - automatically reactive!
        inCartQty(item) {
            return this.stores.cart.items.find(i => i.id === item.id)?.qty || 0;
        },

        // Can call other item-level computeds
        isInCart(item) {
            return this.computed.inCartQty(item) > 0;
        },

        // Index is available as second parameter
        rowClass(item, index) {
            return index % 2 === 0 ? 'even' : 'odd';
        }
    }
});

<div data-list="products" data-key="id">
    <template>
        <div data-bind-class="rowClass">
            <span data-bind="name"></span>
            <span data-bind="priceWithTax"></span>
            <span data-show="isInCart">IN CART</span>
        </div>
    </template>
</div>

Key features:

• Store reactivity: When store state changes, only affected list item bindings update
• Full context: State, props, and stores are all available via this
• Chaining: Item-level computeds can call other item-level computeds via this.computed.name(item) (the computed prefix is required here to pass the item argument)
• Resolves at every binding site: data-bind, data-bind-class, data-bind-style, data-bind-attr, data-show, data-render, and as the source array of a nested data-list. The framework reads item[path] first and falls back to evaluating the item-level computed of the same name when the field is undefined. See the lists guide for the nested-list pattern.

Cross-Component State

External State Access

For HTML bindings, use the $ accessor directly: data-bind="$user-service.currentUser.name". For JavaScript access, use subscribe with this.stores for stores, or wildflower.getComponent() for components:

// User service store
wildflower.store('user-service', {
    state: {
        currentUser: { name: 'John Doe', role: 'admin' },
        isAuthenticated: true
    }
})

// Navigation component subscribing to the store
wildflower.component('app-navigation', {
    subscribe: {
        'user-service': ['currentUser', 'isAuthenticated']
    },

    computed: {
        userDisplayName() {
            const user = this.stores['user-service'].currentUser
            return user ? user.name : 'Guest'
        },

        showAdminMenu() {
            const user = this.stores['user-service'].currentUser
            return user && user.role === 'admin'
        },

        isLoggedIn() {
            return this.stores['user-service'].isAuthenticated
        }
    }
})

Store-Based State Management

For global application state, use the store system:

// Create a global store
wildflower.store('app-state', {
    state: {
        theme: 'light',
        user: null,
        notifications: []
    },

    computed: {
        isDarkMode() {
            return this.theme === 'dark'
        },

        unreadCount() {
            return this.notifications.filter(n => !n.read).length
        }
    },

    // Methods go at top level (not in an actions block)
    setTheme(newTheme) {
        this.theme = newTheme
    },

    addNotification(notification) {
        this.notifications.push({
            ...notification,
            id: Date.now(),
            read: false
        })
    }
})

// Use store in components
wildflower.component('theme-toggle', {
    subscribe: {
        'app-state': ['theme']
    },

    computed: {
        currentTheme() {
            return this.stores['app-state'].theme
        }
    },

    toggleTheme() {
        const newTheme = this.currentTheme === 'light' ? 'dark' : 'light'
        this.stores['app-state'].setTheme(newTheme)
    }
})

State Update Patterns

Batch Updates

Multiple state changes in the same method are automatically batched:

wildflower.component('form-handler', {
    state: {
        user: { name: '', email: '', age: 0 },
        errors: {},
        isValid: false
    },
    
    updateUser(userData) {
        // All these updates are batched into a single UI update
        this.user.name = userData.name
        this.user.email = userData.email
        this.user.age = userData.age
        this.isValid = this.validateUser()
        this.errors = this.getValidationErrors()
        
        // UI updates once after all changes
    }
})

Immutable Updates

For complex objects, consider immutable update patterns:

wildflower.component('todo-manager', {
    state: {
        todos: [
            { id: 1, text: 'Learn WildflowerJS', completed: false }
        ]
    },
    
    // Immutable array update
    addTodo(text) {
        this.todos = [
            ...this.todos,
            { id: Date.now(), text, completed: false }
        ]
    },

    // Immutable object update
    updateTodo(id, updates) {
        this.todos = this.todos.map(todo =>
            todo.id === id ? { ...todo, ...updates } : todo
        )
    },

    // Direct mutation (also works)
    toggleTodo(id) {
        const todo = this.todos.find(t => t.id === id)
        if (todo) {
            todo.completed = !todo.completed
        }
    }
})

State Best Practices

Serializing reactive state (wildflower.toRaw)

Reactive state is wrapped in Proxy objects so the framework can track reads and intercept writes. Most of the time the proxy is invisible: it stringifies, iterates, and JSON-serializes like a plain object. There is one class of API that rejects it: anything that uses the browser's structured-clone algorithm.

Structured-clone APIs throw DataCloneError on a reactive proxy:

• indexedDB reads and writes
• postMessage (window, worker, iframe)
• Web Workers and SharedWorker message channels
• BroadcastChannel.postMessage
• Cache.put / Cache.add (the Service Worker Cache API)
• history.pushState / history.replaceState state objects

wildflower.toRaw(value) returns a deep plain-JS snapshot of any reactive value, ready to cross those boundaries:

// in a component or store method
async save() {
    var raw = wildflower.toRaw(this.state.items);
    var db = await openDB();
    var tx = db.transaction('items', 'readwrite');
    await tx.objectStore('items').put(raw);
}

// postMessage to a worker
worker.postMessage({
    type: 'compute',
    payload: wildflower.toRaw(this.state.config)
});

// history state
wildflower.router.navigate('/results', {
    state: wildflower.toRaw(this.state.filters)
});

The snapshot is a one-time copy. Mutations to the snapshot do not flow back into the reactive state, and subsequent state changes do not show up in the snapshot. Re-call toRaw when you need a fresh copy.

Only reach for toRaw when the proxy is the actual problem. Plain reads (x.y.z), iteration (for...of), JSON.stringify, and most third-party libraries work directly on the proxy. fetch with a JSON body works directly. The structured-clone APIs above are the exceptions that need the unwrap.

Performance Considerations

State Update Optimization

• Batching: Multiple state changes in one method trigger only one UI update
• Dependency Tracking: Only components that use changed state are updated
• Computed Caching: Computed properties are cached until their dependencies change
• Pattern Trie: Efficient dependency lookup for large applications

Memory Management

• Components automatically clean up their state when destroyed
• Store subscriptions are automatically tracked and cleaned
• Use the destroy() hook for manual cleanup of timers, subscriptions, etc.