Guides for docs

docs/guides/states.md

@@ -0,0 +1,93 @@
+# State Management in Basalt
+
+States provide a powerful way to manage data and UI synchronization in your Basalt applications.
+
+## Core Concepts
+
+- **States**: Named values stored in frames
+- **Computed States**: States that depend on other states
+- **State Changes**: Automatic UI updates when states change
+- **State Listeners**: React to state changes
+
+## Basic State Methods
+
+```lua
+-- Initialize states
+frame:initializeState("name", defaultValue, triggerRender)
+frame:setState("name", newValue)
+frame:getState("name")
+
+-- Computed states
+frame:computed("name", function(self)
+    -- Calculate and return value based on other states
+end)
+
+-- Listen to changes
+frame:onStateChange("name", function(self, newValue)
+    -- React to state changes
+end)
+```
+
+## Complete Form Example
+
+Here's a comprehensive example showing state management in a form:
+
+```lua
+local main = basalt.getMainFrame()
+local form = main:addFrame()
+    :setSize("{parent.width - 4}", "{parent.height - 4}")
+    -- Initialize multiple states
+    :initializeState("username", "")
+    :initializeState("email", "")
+    :initializeState("age", 0)
+    :initializeState("submitted", false)
+    -- Add computed validation state
+    :computed("isValid", function(self)
+        local username = self:getState("username")
+        local email = self:getState("email")
+        local age = self:getState("age")
+        return #username > 0 and email:match(".+@.+") and age > 0
+    end)
+
+-- Input with state binding
+form:addInput()
+    :onChange(function(self, value)
+        form:setState("username", value)
+    end)
+
+-- Button reacting to computed state
+form:addButton()
+    :onStateChange("isValid", function(self, isValid)
+        self:setBackground(isValid and colors.lime or colors.gray)
+    end)
+```
+
+## Best Practices
+
+1. **State Initialization**
+   - Initialize all states at component creation
+   - Use meaningful default values
+   - Consider whether state changes should trigger renders
+
+2. **Computed States**
+   - Use for values that depend on multiple states
+   - Keep computations simple and efficient
+   - Avoid circular dependencies
+
+3. **State Updates**
+   - Update states through setState, not directly
+   - Use onStateChange for side effects
+   - Consider batching multiple state updates
+
+4. **Form Validation**
+   - Use computed states for form validation
+   - Update UI elements based on validation state
+   - Trigger actions only when validation passes
+
+## Tips
+
+- Use states for data that affects multiple components
+- Consider using tables for complex state
+- Keep state updates minimal and efficient
+- Use meaningful state names
+- Document state dependencies