jac-client 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

jac_client/docs/guide-example/step-05-local-state.md

@@ -0,0 +1,530 @@
+# Step 5: Local State
+
+> **💡 Quick Tip:** Each step has two parts. **Part 1** shows you what to build. **Part 2** explains why it works. Want to just build? Skip all Part 2 sections!
+
+In this step, you'll learn about **state** - the data that makes your app interactive and dynamic!
+
+---
+
+## 🏗️ Part 1: Building the App
+
+### Step 5.1: First, Let's See Why Normal Variables Don't Work
+
+Let's try using a normal variable to track todos:
+
+```jac
+cl {
+    # ... (keep all your components from Step 4)
+
+    def app() -> any {
+        # Try using a normal variable
+        let todos = [
+            {"text": "Learn Jac", "done": false},
+            {"text": "Build app", "done": false}
+        ];
+
+        return <div style={{
+            "maxWidth": "600px",
+            "margin": "20px auto",
+            "padding": "20px"
+        }}>
+            <h1>My Todos ({todos.length})</h1>
+            <p>Todos: {todos.length}</p>
+        </div>;
+    }
+}
+```
+
+This works for displaying data, but **what if we want to change it?** Normal variables can't trigger UI updates!
+
+### Step 5.2: Introducing `useState`
+
+To make data interactive, we need `useState`. First, import it:
+
+```jac
+cl import from react {useState}
+
+cl {
+    def app() -> any {
+        # Create state with useState
+        let [todos, setTodos] = useState([]);
+
+        return <div style={{"padding": "20px"}}>
+            <h1>My Todos</h1>
+            <p>Total: {todos.length}</p>
+        </div>;
+    }
+}
+```
+
+**What's happening:**
+- `useState([])` creates state with initial value `[]` (empty array)
+- Returns two things:
+  - `todos` - The current value (read-only)
+  - `setTodos` - Function to update the value
+
+### Step 5.3: Add State for Input Field
+
+Let's make the input field work:
+
+```jac
+cl import from react {useState}
+
+cl {
+    def TodoInput(props: any) -> any {
+        return <div style={{
+            "display": "flex",
+            "gap": "8px",
+            "marginBottom": "16px"
+        }}>
+            <input
+                type="text"
+                value={props.input}
+                placeholder="What needs to be done?"
+                style={{
+                    "flex": "1",
+                    "padding": "8px",
+                    "border": "1px solid #ddd",
+                    "borderRadius": "4px"
+                }}
+            />
+            <button style={{
+                "padding": "8px 16px",
+                "background": "#3b82f6",
+                "color": "#ffffff",
+                "border": "none",
+                "borderRadius": "4px",
+                "cursor": "pointer"
+            }}>
+                Add
+            </button>
+        </div>;
+    }
+
+    def app() -> any {
+        # State for input field
+        let [input, setInput] = useState("");
+
+        return <div style={{
+            "maxWidth": "600px",
+            "margin": "20px auto",
+            "padding": "20px"
+        }}>
+            <h1>My Todos</h1>
+            <TodoInput input={input} />
+            <p>You typed: {input}</p>
+        </div>;
+    }
+}
+```
+
+**Try typing in the input!** Nothing happens yet because we haven't connected the onChange event (we'll do that in the next step).
+
+### Step 5.4: Add State for Todos List
+
+Now let's track our todos list with state:
+
+```jac
+cl import from react {useState}
+
+cl {
+    def TodoItem(props: any) -> any {
+        return <div style={{
+            "display": "flex",
+            "alignItems": "center",
+            "gap": "10px",
+            "padding": "10px",
+            "borderBottom": "1px solid #e5e7eb"
+        }}>
+            <input type="checkbox" checked={props.done} />
+            <span style={{
+                "flex": "1",
+                "textDecoration": ("line-through" if props.done else "none"),
+                "color": ("#999" if props.done else "#000")
+            }}>
+                {props.text}
+            </span>
+            <button style={{
+                "padding": "4px 8px",
+                "background": "#ef4444",
+                "color": "white",
+                "border": "none",
+                "borderRadius": "4px",
+                "cursor": "pointer"
+            }}>
+                Delete
+            </button>
+        </div>;
+    }
+
+    def app() -> any {
+        # State for todos
+        let [todos, setTodos] = useState([
+            {"text": "Learn Jac basics", "done": false},
+            {"text": "Build a todo app", "done": false}
+        ]);
+
+        return <div style={{
+            "maxWidth": "600px",
+            "margin": "20px auto",
+            "padding": "20px",
+            "background": "#ffffff",
+            "borderRadius": "8px"
+        }}>
+            <h1>My Todos</h1>
+
+            # Display todos
+            <div>
+                {todos.map(lambda todo: any -> any {
+                    return <TodoItem
+                        text={todo.text}
+                        done={todo.done}
+                    />;
+                })}
+            </div>
+
+            # Stats
+            <div style={{"marginTop": "16px", "color": "#666"}}>
+                {todos.length} items total
+            </div>
+        </div>;
+    }
+}
+```
+
+### Step 5.5: Add State for Filter
+
+Let's add filter state:
+
+```jac
+cl import from react {useState}
+
+cl {
+    # ... (keep all previous components)
+
+    def TodoFilters(props: any) -> any {
+        return <div style={{
+            "display": "flex",
+            "gap": "8px",
+            "marginBottom": "16px"
+        }}>
+            <button style={{
+                "padding": "6px 12px",
+                "background": ("#3b82f6" if props.filter == "all" else "#e5e7eb"),
+                "color": ("#ffffff" if props.filter == "all" else "#000000"),
+                "border": "none",
+                "borderRadius": "4px",
+                "cursor": "pointer"
+            }}>
+                All
+            </button>
+            <button style={{
+                "padding": "6px 12px",
+                "background": ("#3b82f6" if props.filter == "active" else "#e5e7eb"),
+                "color": ("#ffffff" if props.filter == "active" else "#000000"),
+                "border": "none",
+                "borderRadius": "4px",
+                "cursor": "pointer"
+            }}>
+                Active
+            </button>
+            <button style={{
+                "padding": "6px 12px",
+                "background": ("#3b82f6" if props.filter == "completed" else "#e5e7eb"),
+                "color": ("#ffffff" if props.filter == "completed" else "#000000"),
+                "border": "none",
+                "borderRadius": "4px",
+                "cursor": "pointer"
+            }}>
+                Completed
+            </button>
+        </div>;
+    }
+
+    def app() -> any {
+        let [todos, setTodos] = useState([
+            {"text": "Learn Jac basics", "done": false},
+            {"text": "Build a todo app", "done": true}
+        ]);
+        let [filter, setFilter] = useState("all");
+
+        return <div style={{
+            "maxWidth": "600px",
+            "margin": "20px auto",
+            "padding": "20px"
+        }}>
+            <h1>My Todos</h1>
+            <TodoFilters filter={filter} />
+
+            # Show current filter
+            <p>Current filter: {filter}</p>
+        </div>;
+    }
+}
+```
+
+**Notice:** The filter buttons now highlight based on the current filter! But clicking them doesn't work yet (we'll add that in Step 6).
+
+---
+
+**⏭️ Want to skip the theory?** Jump to [Step 6: Event Handlers](./step-06-events.md)
+
+---
+
+## 💡 Part 2: Understanding the Concepts
+
+### What is State?
+
+**State** is data that can change over time and causes your UI to update when it changes.
+
+**Python analogy:**
+
+```python
+# Python class with state
+class TodoApp:
+    def __init__(self):
+        self.todos = []  # This is state
+
+    def add_todo(self, text):
+        self.todos.append(text)  # Changing state
+        self.render()  # Manually update UI
+```
+
+```jac
+# Jac with React
+def app() -> any {
+    let [todos, setTodos] = useState([]);  # This is state
+
+    # When you call setTodos(), React automatically updates the UI!
+}
+```
+
+### The `useState` Hook
+
+```jac
+let [value, setValue] = useState(initialValue);
+```
+
+**Returns a pair:**
+1. `value` - Current state value (read-only, don't modify directly!)
+2. `setValue` - Function to update state
+
+**Examples:**
+
+```jac
+# String state
+let [name, setName] = useState("Alice");
+
+# Number state
+let [count, setCount] = useState(0);
+
+# Boolean state
+let [isOpen, setIsOpen] = useState(false);
+
+# Array state
+let [todos, setTodos] = useState([]);
+
+# Object state
+let [user, setUser] = useState({"name": "Alice", "age": 30});
+```
+
+### Why Use `useState`?
+
+**Without useState (doesn't work):**
+
+```jac
+def app() -> any {
+    let count = 0;  # Normal variable
+
+    # Button click would change count, but UI won't update!
+    return <button>Count: {count}</button>;
+}
+```
+
+**With useState (works!):**
+
+```jac
+def app() -> any {
+    let [count, setCount] = useState(0);  # State
+
+    # When setCount is called, React re-renders the component!
+    return <button>Count: {count}</button>;
+}
+```
+
+### Multiple State Variables
+
+You can have multiple pieces of state:
+
+```jac
+def app() -> any {
+    let [todos, setTodos] = useState([]);
+    let [input, setInput] = useState("");
+    let [filter, setFilter] = useState("all");
+    let [loading, setLoading] = useState(false);
+
+    # Use them independently
+}
+```
+
+Each state variable is independent and has its own update function.
+
+### State Naming Convention
+
+Follow this pattern:
+
+```jac
+# Pattern: [thing, setThing]
+let [count, setCount] = useState(0);
+let [name, setName] = useState("");
+let [isOpen, setIsOpen] = useState(false);
+let [todos, setTodos] = useState([]);
+
+# ❌ Bad names
+let [count, updateCount] = useState(0);  # Inconsistent
+let [x, y] = useState(0);                 # Not descriptive
+```
+
+### The `.map()` Method for Lists
+
+To render a list of items, use `.map()`:
+
+```jac
+{todos.map(lambda todo: any -> any {
+    return <TodoItem text={todo.text} done={todo.done} />;
+})}
+```
+
+**How it works:**
+
+```python
+# Python equivalent
+todos = [{"text": "Task 1"}, {"text": "Task 2"}]
+items = [TodoItem(text=todo["text"]) for todo in todos]
+```
+
+**Breakdown:**
+- `todos.map(...)` - Loop through each todo
+- `lambda todo: any -> any { ... }` - Function that runs for each item
+- `return <TodoItem ... />` - Returns a component for each item
+
+### State is Immutable
+
+**Never modify state directly:**
+
+```jac
+# ❌ WRONG - Never do this!
+let [todos, setTodos] = useState([]);
+todos.push(newTodo);  # DON'T modify directly!
+
+# ✅ CORRECT - Create new array
+let [todos, setTodos] = useState([]);
+setTodos(todos.concat([newTodo]));  # Create new array
+```
+
+Why? Because React needs to detect changes to update the UI. If you modify directly, React won't know it changed!
+
+### Passing State to Children
+
+State flows down through props:
+
+```jac
+def Parent() -> any {
+    let [name, setName] = useState("Alice");
+
+    # Pass state down as props
+    return <Child name={name} />;
+}
+
+def Child(props: any) -> any {
+    # Access state via props
+    return <div>Hello, {props.name}!</div>;
+}
+```
+
+The child receives state but **cannot modify** the parent's state directly (we'll learn how to do that with callbacks in the next step).
+
+---
+
+## ✅ What You've Learned
+
+- ✅ What state is and why we need it
+- ✅ How to use the `useState` hook
+- ✅ Creating multiple state variables
+- ✅ State naming conventions
+- ✅ Using `.map()` to render lists
+- ✅ State is immutable (don't modify directly)
+- ✅ Passing state to child components via props
+
+---
+
+## 🐛 Common Issues
+
+### Issue: UI not updating when state changes
+
+**Check:** Are you modifying state directly?
+
+```jac
+# ❌ Wrong
+todos.push(newTodo);
+
+# ✅ Correct
+setTodos(todos.concat([newTodo]));
+```
+
+### Issue: "todos is not iterable"
+
+**Check:** Did you initialize state as an array?
+
+```jac
+# ❌ Wrong
+let [todos, setTodos] = useState();  # undefined
+
+# ✅ Correct
+let [todos, setTodos] = useState([]);  # empty array
+```
+
+### Issue: useState is not defined
+
+**Check:** Did you import it?
+
+```jac
+cl import from react {useState}
+```
+
+---
+
+## 🎯 Quick Exercise
+
+Try adding more initial todos:
+
+```jac
+let [todos, setTodos] = useState([
+    {"text": "Learn Jac basics", "done": true},
+    {"text": "Build a todo app", "done": false},
+    {"text": "Deploy to production", "done": false},
+    {"text": "Celebrate!", "done": false}
+]);
+```
+
+And display the count of completed todos:
+
+```jac
+let completedCount = todos.filter(lambda todo: any -> bool {
+    return todo.done;
+}).length;
+
+return <div>
+    <p>{completedCount} completed out of {todos.length}</p>
+</div>;
+```
+
+---
+
+## ➡️ Next Step
+
+Great! You now have state in your app, but you can't change it yet. Clicking buttons does nothing!
+
+In the next step, we'll add **event handlers** to make your app fully interactive!
+
+👉 **[Continue to Step 6: Event Handlers](./step-06-events.md)**