jac-client 0.2.0__py3-none-any.whl

jac_client/docs/README.md

@@ -0,0 +1,659 @@
+# Todo App - Beginner's Guide to Building with Jac
+
+Welcome to the Todo App example! This guide will walk you through building a full-stack web application with Jac, from setup to deployment. Jac simplifies web development by eliminating the need for separate frontend and backend technologies, HTTP clients, and complex build configurations.
+
+---
+
+## 📦 1. Creating the Application
+
+### Installation
+
+First, install the Jac client package:
+
+```bash
+pip install jac-client
+```
+
+### Create a New Jac App
+
+Use the `jac create_jac_app` command to scaffold a new application: (* we can name our app however we want, here we are using `todo-app)
+
+```bash
+jac create_jac_app todo-app
+```
+
+This command will:
+- Create a new directory with your project name
+- Set up the basic project structure
+- Initialize npm and install Vite (for development server)
+- Create a starter `app.jac` file with a sample component
+
+**What gets created:**
+```
+my-app/
+├── app.jac          # Your main application file
+├── package.json      # Node.js dependencies
+└── node_modules/    # Dependencies (after npm install)
+```
+
+### Running Your App
+
+Navigate to your project directory and start the development server:
+
+```bash
+cd todo-app
+jac serve app.jac
+```
+
+This starts both:
+- **Backend server**: Handles your Jac graph operations and walkers
+- **Frontend development server**: Serves your React components
+
+You can access your app at `http://localhost:8000`
+
+---
+
+## 🚪 2. Entry Point of the App
+
+Every Jac client application needs an entry point function. This is where your app starts rendering.
+
+### The `app()` Function
+
+Inside your `cl` block, define a function called `app()`:
+
+```jac
+cl import from react {useState}
+
+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:**
+- `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 with Multiple Components:**
+```jac
+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 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>;
+    }
+}
+```
+
+---
+
+## 🧩 3. Creating Components
+
+Components in Jac are functions that return JSX (JavaScript XML). They're similar to React components but written in pure Jac syntax.
+
+### Basic Component Structure
+
+```jac
+cl {
+    def MyComponent() -> any {
+        return <div>
+            <h1>Hello from Jac!</h1>
+        </div>;
+    }
+}
+```
+
+### Component with Props
+
+Components can accept parameters (props):
+
+```jac
+def TodoItem(item: dict) -> any {
+    return <li key={item.id}>
+        <span>{item.text}</span>
+        <button onClick={lambda -> None { removeTodo(item.id); }}>
+            Remove
+        </button>
+    </li>;
+}
+```
+
+**Component Features:**
+- **JSX Syntax**: Write HTML-like syntax directly in Jac
+- **Inline Styles**: Use JavaScript objects for styling
+- **Event Handlers**: Attach functions to user interactions
+- **Reusability**: Components can call other components
+
+### Example: TodoItem Component
+
+```jac
+def TodoItem(item: dict) -> any {
+    return <li key={item.id} style={{
+        "display": "flex",
+        "gap": "12px",
+        "alignItems": "center",
+        "padding": "12px",
+        "background": "#FFFFFF",
+        "borderRadius": "10px"
+    }}>
+        <input
+            type="checkbox"
+            checked={item.done}
+            onChange={lambda -> None { toggleTodo(item.id); }}
+        />
+        <span style={{
+            "textDecoration": ("line-through" if item.done else "none")
+        }}>
+            {item.text}
+        </span>
+        <button onClick={lambda -> None { removeTodo(item.id); }}>
+            Remove
+        </button>
+    </li>;
+}
+```
+
+**Breaking it down:**
+- `item: dict` - Component receives a dictionary (todo item) as a prop
+- `style={{...}}` - Inline styles using JavaScript objects
+- `checked={item.done}` - Dynamic attribute binding
+- `onChange={lambda -> None {...}}` - Event handler using lambda
+- `{item.text}` - Interpolation of JavaScript expressions in JSX
+
+---
+
+## 🗄️ 4. Adding State with React Hooks
+
+Jac uses React hooks for state management. You can use all standard React hooks by importing them:
+
+```jac
+cl import from react { useState, useEffect }
+
+cl {
+    def Counter() -> any {
+        let [count, setCount] = useState(0);
+
+        useEffect(lambda -> None {
+            console.log("Count changed:", count);
+        }, [count]);
+
+        return <div>
+            <h1>Count: {count}</h1>
+            <button onClick={lambda e: any -> None {
+                setCount(count + 1);
+            }}>
+                Increment
+            </button>
+        </div>;
+    }
+}
+```
+
+**Available React Hooks:**
+- `useState` - For state management
+- `useEffect` - For side effects
+- `useRef` - For refs
+- `useContext` - For context
+- `useCallback`, `useMemo` - For performance optimization
+- And more...
+
+### State Management Example
+
+Here's a complete example showing state management in a todo app:
+
+```jac
+cl import from react {useState, useEffect}
+
+cl {
+    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={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>
+                {filteredTodos.map(lambda todo: any -> any {
+                    return <div key={todo._jac_id}>
+                        <span>{todo.text}</span>
+                    </div>;
+                })}
+            </div>
+        </div>;
+    }
+}
+```
+
+---
+
+## 🎯 5. Event Handling
+
+Event handling in Jac works just like React, but with Jac's lambda syntax.
+
+### Basic Event Handlers
+
+```jac
+def Button() -> any {
+    return <button onClick={lambda -> None {
+        console.log("Button clicked!");
+    }}>
+        Click Me
+    </button>;
+}
+```
+
+### Event Handlers with Event Object
+
+```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);
+            setValue(e.target.value);
+        }}
+    />;
+}
+```
+
+### Form Submission
+
+```jac
+def TodoForm() -> any {
+    return <form onSubmit={onAddTodo}>
+        <input id="todo-input" type="text" />
+        <button type="submit">Add Todo</button>
+    </form>;
+}
+
+async def onAddTodo(e: any) -> None {
+    e.preventDefault();  # Prevent page refresh
+    inputEl = document.getElementById("todo-input");
+    text = inputEl.value.trim();
+
+    if not text { return; }
+
+    # Handle form submission
+    response = root spawn create_todo(text=text);
+    new_todo = response.reports[0][0];
+    # ... update state
+}
+```
+
+### Common Event Types
+
+| Event | Syntax | Use Case |
+|-------|--------|----------|
+| `onClick` | `onClick={lambda -> None {...}}` | Button clicks |
+| `onChange` | `onChange={lambda e: any -> None {...}}` | Input changes |
+| `onSubmit` | `onSubmit={lambda e: any -> None {...}}` | Form submission |
+| `onKeyPress` | `onKeyPress={lambda e: any -> None {...}}` | Keyboard input |
+
+### Advanced: Conditional Event Handlers
+
+```jac
+def FilterButton(filterType: str, currentFilter: str, onFilterChange: any) -> any {
+    isActive = currentFilter == filterType;
+
+    return <button
+        onClick={lambda -> None {
+            onFilterChange(filterType);
+        }}
+        style={{
+            "background": ("#7C3AED" if isActive else "#FFFFFF"),
+            "color": ("#FFFFFF" if isActive else "#7C3AED")
+        }}
+    >
+        {filterType}
+    </button>;
+}
+```
+
+---
+
+## ✨ 6. Magic: No More Axios/Fetch!
+
+One of Jac's most powerful features is **seamless backend communication** without writing HTTP requests, fetch calls, or axios code.
+
+### The `spawn` Syntax
+
+Instead of writing:
+```javascript
+// Traditional approach
+const response = await fetch('/api/todos', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ text: 'New todo' })
+});
+const data = await response.json();
+```
+
+You simply write:
+```jac
+response = root spawn create_todo(text="New todo");
+```
+
+### How `spawn` Works
+
+```jac
+# 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 (spawn on root node)
+response = root spawn create_todo(text=text);
+
+# Toggle todo status (spawn on specific todo node)
+id spawn toggle_todo();
+
+# Read all todos
+todos = root spawn read_todos();
+```
+
+### Backend Walkers
+
+Walkers are defined in the same `app.jac` file (outside the `cl` block):
+
+```jac
+# Node definition (data model)
+node Todo {
+    has text: str;
+    has done: bool = False;
+}
+
+# Walker: Create a new todo
+walker create_todo {
+    has text: str;
+    can create with `root entry {
+        new_todo = here ++> Todo(text=self.text);
+        report new_todo;
+    }
+}
+
+# Walker: Toggle todo status
+walker toggle_todo {
+    can toggle with Todo entry {
+        here.done = not here.done;
+        report here;
+    }
+}
+
+# Walker: Read all todos
+walker read_todos {
+    can read with `root entry {
+        visit [-->(`?Todo)];
+    }
+
+    can report_todos with exit {
+        report here;
+    }
+}
+```
+
+### Complete Example: Creating a Todo
+
+**Frontend (in `cl` block):**
+```jac
+async def onAddTodo(e: any) -> None {
+    e.preventDefault();
+    text = document.getElementById("todo-input").value.trim();
+    if not text { return; }
+
+    # Call backend walker - no fetch/axios needed!
+    response = root spawn create_todo(text=text);
+    new_todo = response.reports[0][0];
+
+    # 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])});
+}
+```
+
+**Backend (outside `cl` block):**
+```jac
+walker create_todo {
+    has text: str;
+    can create with `root entry {
+        # 'text' comes from the walker parameter
+        new_todo = here ++> Todo(text=self.text);
+        report new_todo;
+    }
+}
+```
+
+### Benefits of `spawn`
+
+✅ **No HTTP Configuration**: No need to set up API endpoints, CORS, or request/response formats
+✅ **Type Safety**: Jac handles serialization automatically
+✅ **Authentication**: Built-in token management via `jacLogin()` / `jacLogout()`
+✅ **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
+
+Jac also provides built-in auth functions:
+
+```jac
+# Sign up
+result = await jacSignup(username, password);
+if result["success"] {
+    navigate("/todos");
+}
+
+# Log in
+success = await jacLogin(username, password);
+if success {
+    navigate("/todos");
+}
+
+# Log out
+jacLogout();
+navigate("/login");
+
+# Check if logged in
+if jacIsLoggedIn() {
+    return <div>Welcome!</div>;
+}
+```
+
+---
+
+## 🎨 Complete Example: Todo App Structure
+
+Here's how all the pieces fit together:
+
+```jac
+# ============================================================================
+# BACKEND: Data Models and Walkers
+# ============================================================================
+node Todo {
+    has text: str;
+    has done: bool = False;
+}
+
+walker create_todo {
+    has text: str;
+    can create with `root entry {
+        new_todo = here ++> Todo(text=self.text);
+        report new_todo;
+    }
+}
+
+# ============================================================================
+# FRONTEND: Components, State, and Events
+# ============================================================================
+cl import from react {useState}
+
+cl {
+    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>
+            <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>
+
+            <div>
+                {todos.map(lambda todo: any -> any {
+                    return <div key={todo._jac_id}>
+                        <span>{todo.text}</span>
+                    </div>;
+                })}
+            </div>
+        </div>;
+    }
+}
+```
+
+---
+
+## 🚀 Running the Todo App
+
+To run this example:
+
+```bash
+# From the todo-app directory
+jac serve app.jac
+```
+
+Then visit `http://localhost:8000` in your browser.
+
+---
+
+## 📚 Next Steps
+
+Ready to dive deeper? Explore these advanced topics:
+
+- **[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 `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
+
+Happy coding with Jac! 🎉