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

jac_client/docs/README.md

@@ -6,9 +6,39 @@ Welcome to the Todo App example! This guide will walk you through building a ful
 
 ## 📦 1. Creating the Application
 
+### Prerequisites
+
+Before installing Jac client, you need to have **Node.js** installed on your system.
+
+#### Installing Node.js
+
+**For Linux users:**
+
+Visit [https://nodejs.org/en/download](https://nodejs.org/en/download) and follow the instructions to install Node.js using **nvm** (Node Version Manager) with **npm**.
+
+Select:
+- **Platform**: Linux
+- **Package Manager**: nvm
+- **Package**: npm
+
+Then follow the installation commands provided on that page.
+
+**For macOS users:**
+
+Download and install Node.js from [https://nodejs.org/en/download](https://nodejs.org/en/download) by selecting your operating system.
+
+**Verify Installation:**
+
+After installation, verify Node.js and npm are installed correctly:
+
+```bash
+node -v
+npm -v
+```
+
 ### Installation
 
-First, install the Jac client package:
+Once Node.js is installed, install the Jac client package:
 
 ```bash
 pip install jac-client
@@ -57,48 +87,63 @@ You can access your app at `http://localhost:8000`
 
 Every Jac client application needs an entry point function. This is where your app starts rendering.
 
-### The `jac_app()` Function
+### The `app()` Function
 
-At the bottom of your `app.jac` file, you'll find the entry point:
+Inside your `cl` block, define a function called `app()`:
 
 ```jac
-cl {
-    def App() -> any {
-        # Your main app component with routing
-        return <div>Hello World</div>;
-    }
+cl import from react {useState}
 
-    def jac_app() -> any {
-        return App();
+cl {
+    def app() -> any {
+        let [count, setCount] = useState(0);
+        return <div>
+            <h1>Hello, World!</h1>
+            <p>Count: {count}</p>
+            <button onClick={lambda e: any -> None { setCount(count + 1); }}>
+                Increment
+            </button>
+        </div>;
     }
 }
 ```
 
 **Key Points:**
-- `jac_app()` is the **required entry point** that Jac looks for
-- It should return your root component (usually called `App`)
+- `app()` is the **required entry point** that Jac looks for
+- It must be defined inside a `cl { }` block (client-side code)
 - The `cl` (client) block indicates this code runs in the browser
 - This function gets called automatically when the page loads
+- You can define other components and helper functions in the same `cl` block
 
-**Example from Todo App:**
+**Example with Multiple Components:**
 ```jac
-def App() -> any {
-    login_route = {"path": "/login", "component": lambda -> any { return LoginForm(); }, "guard": None};
-    signup_route = {"path": "/signup", "component": lambda -> any { return SignupForm(); }, "guard": None};
-    todos_route  = {"path": "/todos", "component": lambda -> any { return TodoApp(); }, "guard": jacIsLoggedIn};
-
-    routes = [login_route, signup_route, todos_route];
-    router = initRouter(routes, "/login");
-
-    currentPath = router.path();
-    return <div>
-        {Nav(currentPath)}
-        {router.render()}
-    </div>;
-}
+cl import from react {useState, useEffect}
+
+cl {
+    def TodoList(todos: list) -> any {
+        return <ul>
+            {todos.map(lambda todo: any -> any {
+                return <li key={todo._jac_id}>{todo.text}</li>;
+            })}
+        </ul>;
+    }
 
-def jac_app() -> any {
-    return App();
+    def app() -> any {
+        let [todos, setTodos] = useState([]);
+
+        useEffect(lambda -> None {
+            async def loadTodos() -> None {
+                result = root spawn read_todos();
+                setTodos(result.reports if result.reports else []);
+            }
+            loadTodos();
+        }, []);
+
+        return <div>
+            <h1>My Todos</h1>
+            <TodoList todos={todos} />
+        </div>;
+    }
 }
 ```
 
@@ -179,112 +224,104 @@ def TodoItem(item: dict) -> any {
 
 ---
 
-## 🗄️ 4. Adding State
-
-State management in Jac uses `createState()`, which provides reactive state similar to React hooks but simpler.
+## 🗄️ 4. Adding State with React Hooks
 
-### Understanding `createState()`
+Jac uses React hooks for state management. You can use all standard React hooks by importing them:
 
 ```jac
-let [todoState, setTodoState] = createState({
-    "items": [],
-    "filter": "all",
-    "input": ""
-});
-```
-
-**How it works:**
-- `createState()` returns a tuple: `[getter, setter]`
-- **Getter** (`todoState`): A function that returns the current state value
-- **Setter** (`setTodoState`): A function that updates the state and triggers re-renders
+cl import from react { useState, useEffect }
 
-### Reading State
-
-Always call the getter as a function:
+cl {
+    def Counter() -> any {
+        let [count, setCount] = useState(0);
 
-```jac
-def TodoApp() -> any {
-    s = todoState();  # Call getter function
+        useEffect(lambda -> None {
+            console.log("Count changed:", count);
+        }, [count]);
 
-    return <div>
-        <p>Total todos: {s.items.length}</p>
-        <p>Current filter: {s.filter}</p>
-    </div>;
+        return <div>
+            <h1>Count: {count}</h1>
+            <button onClick={lambda e: any -> None {
+                setCount(count + 1);
+            }}>
+                Increment
+            </button>
+        </div>;
+    }
 }
 ```
 
-### Updating State
-
-The setter merges updates with existing state:
-
-```jac
-# Update single property
-setTodoState({"filter": "active"});
-
-# Update multiple properties
-setTodoState({
-    "filter": "completed",
-    "input": "New todo text"
-});
+**Available React Hooks:**
+- `useState` - For state management
+- `useEffect` - For side effects
+- `useRef` - For refs
+- `useContext` - For context
+- `useCallback`, `useMemo` - For performance optimization
+- And more...
 
-# Update arrays (create new array)
-s = todoState();
-setTodoState({"items": s.items.concat([newItem])});
-```
+### State Management Example
 
-**Important:** The setter performs a **shallow merge**, meaning:
-- Existing properties are preserved
-- Only specified properties are updated
-- Arrays and objects are replaced, not merged deeply
-
-### Complete State Example
+Here's a complete example showing state management in a todo app:
 
 ```jac
+cl import from react {useState, useEffect}
+
 cl {
-    # Initialize state
-    let [todoState, setTodoState] = createState({
-        "items": [],
-        "filter": "all",
-        "input": ""
-    });
-
-    # Read state in component
-    def TodoApp() -> any {
-        s = todoState();
-        itemsArr = s.items;
+    def app() -> any {
+        let [todos, setTodos] = useState([]);
+        let [input, setInput] = useState("");
+        let [filter, setFilter] = useState("all");
+
+        # Load todos on mount
+        useEffect(lambda -> None {
+            async def loadTodos() -> None {
+                result = root spawn read_todos();
+                setTodos(result.reports if result.reports else []);
+            }
+            loadTodos();
+        }, []);
+
+        # Add new todo
+        async def addTodo() -> None {
+            if not input.trim() { return; }
+            response = root spawn create_todo(text=input.trim());
+            new_todo = response.reports[0][0];
+            setTodos(todos.concat([new_todo]));
+            setInput("");
+        }
+
+        # Filter todos
+        def getFilteredTodos() -> list {
+            if filter == "active" {
+                return todos.filter(lambda todo: any -> bool { return not todo.done; });
+            } elif filter == "completed" {
+                return todos.filter(lambda todo: any -> bool { return todo.done; });
+            }
+            return todos;
+        }
+
+        filteredTodos = getFilteredTodos();
 
         return <div>
+            <h1>My Todos</h1>
             <input
-                value={s.input}
-                onChange={lambda e: any -> None {
-                    setTodoState({"input": e.target.value});
+                value={input}
+                onChange={lambda e: any -> None { setInput(e.target.value); }}
+                onKeyPress={lambda e: any -> None {
+                    if e.key == "Enter" { addTodo(); }
                 }}
             />
+            <button onClick={addTodo}>Add</button>
+
             <div>
-                {[TodoItem(item) for item in itemsArr]}
+                {filteredTodos.map(lambda todo: any -> any {
+                    return <div key={todo._jac_id}>
+                        <span>{todo.text}</span>
+                    </div>;
+                })}
             </div>
         </div>;
     }
-
-    # Update state in event handler
-    async def onAddTodo(e: any) -> None {
-        e.preventDefault();
-        text = document.getElementById("todo-input").value.trim();
-
-        if not text { return; }
-
-        # Create todo on backend
-        new_todo = await __jacSpawn("create_todo", {"text": text});
-
-        # Update frontend state
-        s = todoState();
-        newItem = {
-            "id": new_todo._jac_id,
-            "text": new_todo.text,
-            "done": new_todo.done
-        };
-        setTodoState({"items": s.items.concat([newItem])});
-    }
 }
 ```
 
@@ -310,11 +347,14 @@ def Button() -> any {
 
 ```jac
 def InputField() -> any {
+    let [value, setValue] = useState("");
+
     return <input
         type="text"
+        value={value}
         onChange={lambda e: any -> None {
             console.log("Input value:", e.target.value);
-            setTodoState({"input": e.target.value});
+            setValue(e.target.value);
         }}
     />;
 }
@@ -338,7 +378,8 @@ async def onAddTodo(e: any) -> None {
     if not text { return; }
 
     # Handle form submission
-    new_todo = await __jacSpawn("create_todo", {"text": text});
+    response = root spawn create_todo(text=text);
+    new_todo = response.reports[0][0];
     # ... update state
 }
 ```
@@ -355,13 +396,12 @@ async def onAddTodo(e: any) -> None {
 ### Advanced: Conditional Event Handlers
 
 ```jac
-def FilterButton(filterType: str) -> any {
-    s = todoState();
-    isActive = s.filter == filterType;
+def FilterButton(filterType: str, currentFilter: str, onFilterChange: any) -> any {
+    isActive = currentFilter == filterType;
 
     return <button
         onClick={lambda -> None {
-            setFilter(filterType);
+            onFilterChange(filterType);
         }}
         style={{
             "background": ("#7C3AED" if isActive else "#FFFFFF"),
@@ -379,7 +419,7 @@ def FilterButton(filterType: str) -> any {
 
 One of Jac's most powerful features is **seamless backend communication** without writing HTTP requests, fetch calls, or axios code.
 
-### The `__jacSpawn()` Function
+### The `spawn` Syntax
 
 Instead of writing:
 ```javascript
@@ -394,30 +434,32 @@ const data = await response.json();
 
 You simply write:
 ```jac
-new_todo = await __jacSpawn("create_todo", {"text": "New todo"});
+response = root spawn create_todo(text="New todo");
 ```
 
-### How `__jacSpawn()` Works
+### How `spawn` Works
 
 ```jac
-# Call a walker on the backend
-result = await __jacSpawn(
-    walker_name,    # Name of the walker to execute
-    fields,         # Dictionary of parameters to pass
-    node_id         # Optional: specific node ID (defaults to "root")
-);
+# Call a walker on a node
+result = node_reference spawn walker_name(parameters);
 ```
 
+**Syntax:**
+- `node_reference` - The node to spawn the walker on (commonly `root` for the root node, or a node ID)
+- `spawn` - The spawn keyword
+- `walker_name` - Name of the walker to execute
+- `parameters` - Parameters to pass to the walker (as function arguments)
+
 **Example from Todo App:**
 ```jac
-# Create a new todo
-new_todo = await __jacSpawn("create_todo", {"text": text});
+# Create a new todo (spawn on root node)
+response = root spawn create_todo(text=text);
 
-# Toggle todo status
-toggled_todo = await __jacSpawn("toggle_todo", {}, todo_id);
+# Toggle todo status (spawn on specific todo node)
+id spawn toggle_todo();
 
 # Read all todos
-todos = await __jacSpawn("read_todos");
+todos = root spawn read_todos();
 ```
 
 ### Backend Walkers
@@ -433,8 +475,9 @@ node Todo {
 
 # Walker: Create a new todo
 walker create_todo {
+    has text: str;
     can create with `root entry {
-        new_todo = here ++> Todo(text="Example Todo");
+        new_todo = here ++> Todo(text=self.text);
         report new_todo;
     }
 }
@@ -469,7 +512,8 @@ async def onAddTodo(e: any) -> None {
     if not text { return; }
 
     # Call backend walker - no fetch/axios needed!
-    new_todo = await __jacSpawn("create_todo", {"text": text});
+    response = root spawn create_todo(text=text);
+    new_todo = response.reports[0][0];
 
     # Update frontend state
     s = todoState();
@@ -485,16 +529,16 @@ async def onAddTodo(e: any) -> None {
 **Backend (outside `cl` block):**
 ```jac
 walker create_todo {
+    has text: str;
     can create with `root entry {
-        # 'text' comes from the fields dictionary passed to __jacSpawn
-        text = context.text;
-        new_todo = here ++> Todo(text=text);
+        # 'text' comes from the walker parameter
+        new_todo = here ++> Todo(text=self.text);
         report new_todo;
     }
 }
 ```
 
-### Benefits of `__jacSpawn()`
+### Benefits of `spawn`
 
 ✅ **No HTTP Configuration**: No need to set up API endpoints, CORS, or request/response formats
 ✅ **Type Safety**: Jac handles serialization automatically
@@ -502,6 +546,7 @@ walker create_todo {
 ✅ **Error Handling**: Exceptions are properly propagated
 ✅ **Graph Operations**: Direct access to graph-based data operations
 ✅ **Less Code**: Eliminates boilerplate HTTP client code
+✅ **Natural Syntax**: Call walkers on nodes using intuitive syntax
 
 ### Authentication Helpers
 
@@ -546,8 +591,9 @@ node Todo {
 }
 
 walker create_todo {
+    has text: str;
     can create with `root entry {
-        new_todo = here ++> Todo(text=context.text);
+        new_todo = here ++> Todo(text=self.text);
         report new_todo;
     }
 }
@@ -555,37 +601,41 @@ walker create_todo {
 # ============================================================================
 # FRONTEND: Components, State, and Events
 # ============================================================================
+cl import from react {useState}
+
 cl {
-    # State
-    let [todoState, setTodoState] = createState({
-        "items": [],
-        "filter": "all"
-    });
-
-    # Component
-    def TodoApp() -> any {
-        s = todoState();
+    def app() -> any {
+        let [todos, setTodos] = useState([]);
+        let [input, setInput] = useState("");
+
+        # Event Handler
+        async def addTodo() -> None {
+            if not input.trim() { return; }
+            response = root spawn create_todo(text=input.trim());
+            new_todo = response.reports[0][0];
+            setTodos(todos.concat([new_todo]));
+            setInput("");
+        }
+
         return <div>
             <h2>My Todos</h2>
-            <form onSubmit={onAddTodo}>
-                <input id="todo-input" type="text" />
-                <button type="submit">Add Todo</button>
-            </form>
-            {[TodoItem(item) for item in s.items]}
-        </div>;
-    }
-
-    # Event Handler
-    async def onAddTodo(e: any) -> None {
-        e.preventDefault();
-        text = document.getElementById("todo-input").value;
-        new_todo = await __jacSpawn("create_todo", {"text": text});
-        # Update state...
-    }
+            <input
+                value={input}
+                onChange={lambda e: any -> None { setInput(e.target.value); }}
+                onKeyPress={lambda e: any -> None {
+                    if e.key == "Enter" { addTodo(); }
+                }}
+            />
+            <button onClick={addTodo}>Add Todo</button>
 
-    # Entry Point
-    def jac_app() -> any {
-        return TodoApp();
+            <div>
+                {todos.map(lambda todo: any -> any {
+                    return <div key={todo._jac_id}>
+                        <span>{todo.text}</span>
+                    </div>;
+                })}
+            </div>
+        </div>;
     }
 }
 ```
@@ -609,19 +659,29 @@ Then visit `http://localhost:8000` in your browser.
 
 Ready to dive deeper? Explore these advanced topics:
 
-- **[Routing](routing.md)**: Learn about `initRouter()` for multi-page applications
-- **[Lifecycle Hooks](lifecycle-hooks.md)**: Use `onMount()` for initialization logic
-- **[Advanced State](advanced-state.md)**: Combine multiple `createState()` calls for complex apps
-- **[Imports](imports.md)**: Import third-party libraries, other Jac files, and JavaScript modules
+- **[Routing](routing.md)**: Build multi-page apps with declarative routing (`<Router>`, `<Routes>`, `<Route>`)
+- **[Lifecycle Hooks](lifecycle-hooks.md)**: Use `onMount()` and React hooks for initialization logic
+- **[Advanced State](advanced-state.md)**: Manage complex state with React hooks and context
+- **[Imports](imports.md)**: Import third-party libraries (React, Ant Design, Lodash), other Jac files, and JavaScript modules
 - **[Learn JAC](https://www.jac-lang.org)**: Explore Jac's graph-based data modeling
 
+## 🎓 Examples
+
+Check out the `examples/` directory for working applications:
+
+- **[basic](../../examples/basic/)**: Simple counter app using React hooks
+- **[with-router](../../examples/with-router/)**: Multi-page app with declarative routing
+- **[little-x](../../examples/little-x/)**: Social media app with third-party libraries
+- **[todo-app](../../examples/todo-app/)**: Full-featured todo app with authentication
+- **[basic-full-stack](../../examples/basic-full-stack/)**: Full-stack app with backend integration
+
 ---
 
 ## 💡 Key Takeaways
 
 1. **Single Language**: Write frontend and backend in Jac
-2. **No HTTP Client**: Use `__jacSpawn()` instead of fetch/axios
-3. **Reactive State**: `createState()` manages UI updates automatically
+2. **No HTTP Client**: Use `spawn` syntax instead of fetch/axios
+3. **Reactive State**: React hooks manage UI updates automatically
 4. **Component-Based**: Build reusable UI components with JSX
 5. **Type Safety**: Jac provides type checking across frontend and backend
 6. **Graph Database**: Built-in graph data model eliminates need for SQL/NoSQL