jac-client 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

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

@@ -1,270 +0,0 @@
-# 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)**

jac_client/docs/guide-example/step-02-components.md

@@ -1,416 +0,0 @@
-# Step 2: First Component
-
-> ** 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 create your first reusable component - a **TodoItem** that displays a single todo.
-
----
-
-##  Part 1: Building the App
-
-### Step 2.1: Create a TodoItem Component
-
-Update your `app.jac`:
-
-```jac
-cl {
-    # A component to display a single todo
-    def TodoItem(props: any) -> any {
-        return <div>
-            <input type="checkbox" />
-            <span>Learn Jac basics</span>
-            <button>Delete</button>
-        </div>;
-    }
-
-    def app() -> any {
-        return <div>
-            <h1>My Todos</h1>
-            <TodoItem />
-        </div>;
-    }
-}
-```
-
-**Try it!** Save and refresh your browser. You should see a todo item with a checkbox, text, and delete button.
-
-### Step 2.2: Make It Reusable with Props
-
-Now let's make the TodoItem display different text:
-
-```jac
-cl {
-    # Component that accepts data via props
-    def TodoItem(props: any) -> any {
-        return <div>
-            <input type="checkbox" checked={props.done} />
-            <span>{props.text}</span>
-            <button>Delete</button>
-        </div>;
-    }
-
-    def app() -> any {
-        return <div>
-            <h1>My Todos</h1>
-            <TodoItem text="Learn Jac basics" done={false} />
-            <TodoItem text="Build a todo app" done={false} />
-            <TodoItem text="Deploy to production" done={true} />
-        </div>;
-    }
-}
-```
-
-**Try it!** You should now see three different todos. Notice how the third one has the checkbox checked!
-
-### Step 2.3: Create Multiple Components
-
-Let's add more components to organize our app:
-
-```jac
-cl {
-    # Component 1: TodoInput (input field + Add button)
-    def TodoInput(props: any) -> any {
-        return <div>
-            <input type="text" placeholder="What needs to be done?" />
-            <button>Add</button>
-        </div>;
-    }
-
-    # Component 2: TodoFilters (filter buttons)
-    def TodoFilters(props: any) -> any {
-        return <div>
-            <button>All</button>
-            <button>Active</button>
-            <button>Completed</button>
-        </div>;
-    }
-
-    # Component 3: TodoItem (single todo)
-    def TodoItem(props: any) -> any {
-        return <div>
-            <input type="checkbox" checked={props.done} />
-            <span>{props.text}</span>
-            <button>Delete</button>
-        </div>;
-    }
-
-    # Component 4: TodoList (list of todos)
-    def TodoList(props: any) -> any {
-        return <div>
-            <TodoItem text="Learn Jac basics" done={true} />
-            <TodoItem text="Build a todo app" done={false} />
-            <TodoItem text="Deploy to production" done={false} />
-        </div>;
-    }
-
-    # Main app - combines all components
-    def app() -> any {
-        return <div>
-            <h1>My Todos</h1>
-            <TodoInput />
-            <TodoFilters />
-            <TodoList />
-        </div>;
-    }
-}
-```
-
-**Try it!** Your app now has a clear structure with separate components.
-
----
-
-**⏭ Want to skip the theory?** Jump to [Step 3: Styling](./step-03-styling.md)
-
----
-
-##  Part 2: Understanding the Concepts
-
-### What is a Component?
-
-A component is a **function that returns UI (JSX)**.
-
-Think of components like Python functions:
-
-```python
-# Python - returns text
-def greet_user(name):
-    return f"Hello, {name}!"
-
-print(greet_user("Alice"))  # Hello, Alice!
-print(greet_user("Bob"))    # Hello, Bob!
-```
-
-```jac
-# Jac - returns UI
-def TodoItem(props: any) -> any {
-    return <div>{props.text}</div>;
-}
-
-# Usage
-<TodoItem text="Learn Jac" />
-<TodoItem text="Build app" />
-```
-
-### Why Use Components?
-
-**1. Reusability** - Write once, use many times
-
-```jac
-<TodoItem text="Task 1" done={false} />
-<TodoItem text="Task 2" done={true} />
-<TodoItem text="Task 3" done={false} />
-```
-
-**2. Organization** - Break complex UI into manageable pieces
-
-```jac
-app
-├── TodoInput
-├── TodoFilters
-└── TodoList
-    ├── TodoItem
-    ├── TodoItem
-    └── TodoItem
-```
-
-**3. Maintainability** - Easy to find and fix bugs
-
-If there's a bug in how todos display, you know to check `TodoItem`.
-
-### Component Naming Rules
-
-**1. Use PascalCase** (first letter capitalized)
-
-```jac
-#  Correct
-def TodoItem() -> any { ... }
-def UserProfile() -> any { ... }
-def NavigationBar() -> any { ... }
-
-#  Wrong
-def todoItem() -> any { ... }      # camelCase
-def user_profile() -> any { ... }  # snake_case
-def navigation-bar() -> any { ... } # kebab-case
-```
-
-**2. Name describes what it does**
-
-```jac
-#  Good names
-def TodoItem() -> any { ... }
-def LoginForm() -> any { ... }
-def ProductCard() -> any { ... }
-
-#  Bad names
-def Component1() -> any { ... }
-def Thing() -> any { ... }
-def X() -> any { ... }
-```
-
-### Understanding Props
-
-**Props** = "Properties" = Data passed to a component
-
-```jac
-# Passing props (like function arguments)
-<TodoItem text="Learn Jac" done={false} />
-
-# Receiving props (in the component)
-def TodoItem(props: any) -> any {
-    let text = props.text;      # "Learn Jac"
-    let done = props.done;      # false
-    return <div>{text}</div>;
-}
-```
-
-**Important**: In React (which Jac uses), components receive props as a **single object**, not individual parameters.
-
-```jac
-#  Correct way
-def TodoItem(props: any) -> any {
-    let text = props.text;
-    let done = props.done;
-    # ...
-}
-
-#  Wrong way (won't work)
-def TodoItem(text: str, done: bool) -> any {
-    # This doesn't work in React!
-}
-```
-
-### Accessing Props
-
-Three ways to access props:
-
-**Method 1: Direct access**
-
-```jac
-def TodoItem(props: any) -> any {
-    return <span>{props.text}</span>;
-}
-```
-
-**Method 2: Extract to variables**
-
-```jac
-def TodoItem(props: any) -> any {
-    let text = props.text;
-    let done = props.done;
-    return <span>{text}</span>;
-}
-```
-
-**Method 3: Dictionary access (explicit)**
-
-```jac
-def TodoItem(props: any) -> any {
-    let text = props["text"];
-    let done = props["done"];
-    return <span>{text}</span>;
-}
-```
-
-All three ways work! Use whichever feels clearest to you.
-
-### Composing Components
-
-You can nest components inside other components:
-
-```jac
-# TodoList uses TodoItem
-def TodoList() -> any {
-    return <div>
-        <TodoItem text="Task 1" done={false} />
-        <TodoItem text="Task 2" done={true} />
-    </div>;
-}
-
-# App uses TodoList
-def app() -> any {
-    return <div>
-        <h1>My Todos</h1>
-        <TodoList />
-    </div>;
-}
-```
-
-This creates a hierarchy:
-
-```
-app
-└── TodoList
-    ├── TodoItem
-    └── TodoItem
-```
-
-### Using JSX in Props
-
-You can pass any value as props:
-
-```jac
-# String
-<TodoItem text="Hello" />
-
-# Number
-<TodoItem count={42} />
-
-# Boolean
-<TodoItem done={true} />
-
-# Variable
-let myText = "Learn Jac";
-<TodoItem text={myText} />
-
-# Expression
-<TodoItem priority={5 + 3} />
-```
-
----
-
-##  What You've Learned
-
--  Components are functions that return UI
--  How to create a component
--  PascalCase naming convention
--  Passing data to components with props
--  Receiving props as a single object
--  Composing components (nesting)
--  Organizing app into multiple components
-
----
-
-##  Common Issues
-
-### Issue: Component not showing up
-
-**Check:**
-- Is the name in PascalCase? `TodoItem` not `todoItem`
-- Did you use `<TodoItem />` (with angle brackets)?
-- Does it have a `return` statement?
-
-### Issue: "object with keys {text, done}"
-
-**Cause**: Using individual parameters instead of props object
-
-```jac
-#  Wrong
-def TodoItem(text: str, done: bool) -> any {
-    # ...
-}
-
-#  Correct
-def TodoItem(props: any) -> any {
-    let text = props.text;
-    # ...
-}
-```
-
-### Issue: Props are undefined
-
-**Check:**
-- Did you pass the props when using the component?
-- Are the prop names spelled the same in both places?
-
-```jac
-# Passing props
-<TodoItem text="Learn" done={false} />
-
-# Receiving props (names must match!)
-def TodoItem(props: any) -> any {
-    props.text  # "Learn"
-    props.done  # false
-}
-```
-
----
-
-##  Quick Exercise
-
-Try adding a new component:
-
-```jac
-def TodoStats(props: any) -> any {
-    return <div>
-        <p>Total: {props.total}</p>
-        <p>Completed: {props.completed}</p>
-    </div>;
-}
-
-# Use it in app
-def app() -> any {
-    return <div>
-        <h1>My Todos</h1>
-        <TodoStats total={3} completed={1} />
-        # ... rest of your components
-    </div>;
-}
-```
-
----
-
-##  Next Step
-
-Great! You can now create and organize components. But they look plain. Let's make them beautiful with **styling**!
-
- **[Continue to Step 3: Styling](./step-03-styling.md)**