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

jac_client/docs/guide-example/intro.md

@@ -0,0 +1,117 @@
+# Building a Full-Stack Todo App with Jac: Complete Walkthrough
+
+Welcome! This guide will teach you how to build a **complete full-stack Todo application** using Jac - perfect for **complete beginners**.
+
+## What is Full-Stack Development?
+
+Think of building a house:
+- **Frontend** = The interior design (what users see and interact with)
+- **Backend** = The plumbing and electricity (where data is stored and processed)
+- **Full-Stack** = Building both the interior AND the infrastructure
+
+Traditionally, you'd need:
+- **JavaScript/React** for frontend
+- **Python/Node.js** for backend
+- **SQL** for database
+- **REST APIs** to connect them
+
+With **Jac**, you write **everything in one language**, in **one file**! 🚀
+
+## What You'll Build
+
+By the end of this guide, you'll have a fully functional Todo app with:
+
+- ✅ **Beautiful UI** - Modern, responsive interface
+- ✅ **User Authentication** - Signup and login
+- ✅ **Protected Routes** - Private pages only for logged-in users
+- ✅ **Full CRUD** - Create, Read, Update, Delete todos
+- ✅ **Real Backend** - Data persists even after refresh
+- ✅ **Filtering** - View all, active, or completed todos
+- ✅ **Multiple Pages** - Routing without page reloads
+
+All of this in approximately **735 lines of Jac code**!
+
+## Prerequisites
+
+Before starting, you should have:
+
+- **Python 3.12 or higher** installed on your system
+  - Download: [https://www.python.org/downloads/](https://www.python.org/downloads/)
+- **Node.js 20 or higher** and npm installed (required for frontend dependencies)
+  - Download: [https://nodejs.org/](https://nodejs.org/) (npm is included with Node.js)
+- A code editor (VS Code recommended with Jac extension)
+  - Download: [https://code.visualstudio.com/](https://code.visualstudio.com/)
+- Basic Python knowledge
+- Basic understanding of HTML/CSS concepts (helpful but not required)
+
+### Quick Setup Check
+
+Verify your environment is ready by running:
+
+```bash
+python --version    # Should show Python 3.12+
+node --version      # Should show Node 20+
+npm --version       # Should show npm
+jac --version       # Should show Jac is installed
+```
+
+If Jac is not installed, run:
+
+```bash
+pip install jac-client
+```
+
+> **Note:** If you have previously installed `jaclang`, please uninstall it first using `pip uninstall jaclang`. The required version of `jaclang` will be installed automatically as a dependency of `jac-client`, so you do not need to install it separately.
+
+## How This Guide Works
+
+Each step builds on the previous one, gradually creating the complete app. Every step has **two parts**:
+
+1. **🏗️ Part 1: Building the App** - Hands-on coding, building the actual app
+2. **💡 Part 2: Understanding the Concepts** - Optional deeper knowledge
+
+**Want to just build?** Follow only Part 1 of each step and skip all Part 2 sections. You'll still have a working app!
+
+**Want to learn deeply?** Read both parts to understand *why* things work, not just *how*.
+
+## Learning Path
+
+We'll build the app in 11 progressive steps:
+
+1. **[Step 1: Project Setup](./step-01-setup.md)** - Create your first Jac project
+2. **[Step 2: First Component](./step-02-components.md)** - Create and organize components
+3. **[Step 3: Styling](./step-03-styling.md)** - Make your components beautiful
+4. **[Step 4: Todo UI](./step-04-todo-ui.md)** - Build the complete todo interface
+5. **[Step 5: Local State](./step-05-local-state.md)** - Add interactivity with state
+6. **[Step 6: Event Handlers](./step-06-events.md)** - Handle user clicks and input
+7. **[Step 7: Effects](./step-07-effects.md)** - Load data when the app starts
+8. **[Step 8: Walkers](./step-08-walkers.md)** - Create the backend with walkers
+9. **[Step 9: Authentication](./step-09-authentication.md)** - Add user signup and login
+10. **[Step 10: Routing](./step-10-routing.md)** - Add multiple pages
+11. **[Step 11: Final Integration](./step-11-final.md)** - Complete working app
+
+## Learning Tips
+
+- **Follow in order** - Each step builds on the previous one
+- **Type the code** - Don't just copy/paste. Typing helps you learn!
+- **Experiment** - Try changing things to see what happens
+- **Use the "Understanding" sections** - Read them when you want to know *why* something works
+
+## Time to Complete
+
+- **Just building**: 2-3 hours
+- **Building + learning**: 4-6 hours
+
+## Getting Help
+
+- Each step has a **"Common Issues"** section
+- Complete final code available in Step 11
+- Check the [Jac Documentation](https://www.jac-lang.org) for API details
+
+## Ready to Start?
+
+Let's build your first full-stack app!
+
+👉 **[Continue to Step 1: Project Setup](./step-01-setup.md)**
+
+

jac_client/docs/guide-example/step-01-setup.md

@@ -0,0 +1,260 @@
+# Step 1: Project Setup
+
+> **💡 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 first step, you'll create your Jac project and understand the basic file structure.
+
+---
+
+## 🏗️ Part 1: Building the App
+
+### Step 1.1: Create Your Project
+
+Open your terminal and run:
+
+```bash
+jac create_jac_app todo-app
+```
+
+This creates a new directory called `todo-app` with everything you need.
+
+### Step 1.2: Navigate to Your Project
+
+```bash
+cd todo-app
+```
+
+### Step 1.3: Understand the Structure
+
+Your project now has these files:
+
+```
+todo-app/
+├── app.jac           # Your main application file (we'll work here!)
+├── package.json      # Node.js dependencies (auto-managed)
+├── vite.config.js    # Build configuration (you can ignore this)
+└── README.md         # Basic instructions
+```
+
+**Important**: We'll write ALL our code in `app.jac` - that's it!
+
+### Step 1.4: Create Your First App
+
+Open `app.jac` in your code editor and replace everything with this:
+
+```jac
+cl {
+    def app() -> any {
+        return <div>
+            <h1>Hello, Jac!</h1>
+            <p>My first full-stack app</p>
+        </div>;
+    }
+}
+```
+
+### Step 1.5: Run Your App
+
+In your terminal, run:
+
+```bash
+jac serve app.jac
+```
+
+You'll see output like:
+
+```
+INFO:     Started server process [12345]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://127.0.0.1:8000
+```
+
+### Step 1.6: View in Browser
+
+Open your browser and go to:
+
+```
+http://localhost:8000/page/app
+```
+
+You should see "Hello, Jac!" and "My first full-stack app" 🎉
+
+---
+
+**⏭️ Want to skip the theory?** Jump to [Step 2: First Component](./step-02-components.md)
+
+---
+
+## 💡 Part 2: Understanding the Concepts
+
+### What is `cl { ... }`?
+
+`cl` stands for "client" - it means this code runs in the **browser** (frontend).
+
+```jac
+cl {
+    # Everything here runs on the client-side (browser)
+}
+```
+
+Think of it like this:
+- Code **inside** `cl { }` → Runs in the browser (frontend)
+- Code **outside** `cl { }` → Runs on the server (backend)
+
+### What is `def app() -> any`?
+
+This is your **main entry point** - the function that Jac calls first.
+
+```jac
+def app() -> any {
+    return <div>...</div>;
+}
+```
+
+**Requirements:**
+- Must be named `app` (by convention)
+- Must return JSX (HTML-like syntax)
+- Located inside `cl { }` block
+
+**Python analogy:**
+
+```python
+# Python
+if __name__ == "__main__":
+    run_app()
+
+# Jac
+def app() -> any {
+    # Start here
+}
+```
+
+### What is JSX?
+
+JSX lets you write HTML directly in your Jac code:
+
+```jac
+return <div>
+    <h1>This is HTML!</h1>
+    <p>But written in Jac code</p>
+</div>;
+```
+
+**Key rules:**
+1. Must have **one root element**
+   ```jac
+   # ✅ Correct
+   return <div><h1>Title</h1><p>Text</p></div>;
+
+   # ❌ Wrong (two root elements)
+   return <h1>Title</h1><p>Text</p>;
+   ```
+
+2. Self-closing tags need `/`
+   ```jac
+   <img src="photo.jpg" />    # ✅ Correct
+   <img src="photo.jpg">       # ❌ Wrong
+   ```
+
+3. Use `{}` to insert Jac code
+   ```jac
+   let name = "Alice";
+   return <h1>Hello, {name}!</h1>;  # Shows: Hello, Alice!
+   ```
+
+### How `jac serve` Works
+
+When you run `jac serve app.jac`:
+
+1. **Jac compiler** reads your `.jac` file
+2. **Frontend code** (inside `cl`) → Compiled to JavaScript
+3. **Backend code** (outside `cl`) → Stays as Python-like backend code
+4. **Single server** serves both on port 8000
+5. **Auto-reload** watches for file changes (coming soon...)
+
+It's like running a Flask/FastAPI server, but it ALSO compiles and serves your React frontend - all in one command!
+
+### File Organization
+
+For now, everything goes in `app.jac`. As your app grows, you can split into multiple files:
+
+```
+todo-app/
+├── app.jac           # Main app
+├── components.jac    # Reusable components
+└── walkers.jac       # Backend logic
+```
+
+But for this tutorial, we'll keep everything in one file for simplicity.
+
+---
+
+## ✅ What You've Learned
+
+- ✅ How to create a Jac project
+- ✅ Project structure basics
+- ✅ What `cl { }` means (client-side code)
+- ✅ The `def app()` entry point
+- ✅ JSX basics (HTML in code)
+- ✅ Running your app with `jac serve`
+
+---
+
+## 🐛 Common Issues
+
+### Issue: `jac: command not found`
+
+**Solution**: Install jac-client:
+```bash
+pip install jac-client
+```
+
+### Issue: Port 8000 already in use
+
+**Solution**: Use a different port:
+```bash
+jac serve app.jac --port 8080
+```
+Then visit `http://localhost:8080/page/app`
+
+### Issue: Blank page in browser
+
+**Check:**
+- Did you visit `/page/app` (not just `/`)?
+- Check terminal for errors
+- Make sure `app()` has a `return` statement
+
+### Issue: Changes not showing
+
+**Solution**:
+- Stop the server (Ctrl+C)
+- Restart: `jac serve app.jac`
+- Refresh browser
+
+---
+
+## 🎯 Quick Exercise
+
+Before moving on, try changing the text:
+
+```jac
+cl {
+    def app() -> any {
+        return <div>
+            <h1>My Todo App</h1>
+            <p>Built with Jac</p>
+        </div>;
+    }
+}
+```
+
+Save, refresh your browser, and see the changes!
+
+---
+
+## ➡️ Next Step
+
+Great! You have a running Jac app. Now let's learn about **components** - the building blocks of any UI.
+
+👉 **[Continue to Step 2: First Component](./step-02-components.md)**