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

jac_client/docs/file-system/nested-imports.md

@@ -0,0 +1,348 @@
+# Nested Folder Imports
+
+Jac preserves folder structure during compilation, similar to TypeScript transpilation. This allows you to organize code in nested folders and use relative imports across multiple directory levels.
+
+## Folder Structure Preservation
+
+When Jac compiles your files, it preserves the folder structure in the `src/` directory:
+
+```
+Source Structure:              Compiled Structure:
+my-app/                        src/
+├── app.jac        →          ├── app.js
+├── ButtonRoot.jac  →          ├── ButtonRoot.js
+└── level1/                    └── level1/
+    ├── ButtonSecondL.jac →        ├── ButtonSecondL.js
+    ├── Card.jac          →        ├── Card.js
+    └── level2/                    └── level2/
+        └── ButtonThirdL.jac →         └── ButtonThirdL.js
+```
+
+## Relative Import Syntax
+
+Jac uses dot notation for relative imports:
+
+- **Single dot (`.`)** - Current directory
+- **Double dot (`..`)** - Parent directory (one level up)
+- **Triple dot (`...`)** - Two levels up
+- **Multiple dots** - Continue going up the directory tree
+- **Dot notation after dots** - Go down into subdirectories (e.g., `.level2`)
+
+## Import Patterns by Directory Level
+
+### Root Level Imports
+
+From the root directory, you can import from nested folders:
+
+```jac
+# app.jac (root level)
+
+# Import from root
+cl import from .ButtonRoot {
+    ButtonRoot
+}
+
+# Import from level1
+cl import from .level1.ButtonSecondL {
+    ButtonSecondL
+}
+
+# Import from level1/level2
+cl import from .level1.level2.ButtonThirdL {
+    ButtonThirdL
+}
+
+# Import from level1
+cl import from .level1.Card {
+    Card
+}
+```
+
+### Second Level Imports
+
+From `level1/`, you can import from root (up) or level2 (down):
+
+```jac
+# level1/ButtonSecondL.jac
+
+# Import from root (go up one level with ..)
+cl import from ..ButtonRoot {
+    ButtonRoot
+}
+```
+
+```jac
+# level1/Card.jac
+
+# Import from root (go up two levels with ..)
+cl import from ..ButtonRoot {
+    ButtonRoot
+}
+
+# Import from level2 (go down one level with .level2)
+cl import from .level2.ButtonThirdL {
+    ButtonThirdL
+}
+```
+
+### Third Level Imports
+
+From `level1/level2/`, you can import from root or parent levels:
+
+```jac
+# level1/level2/ButtonThirdL.jac
+
+# Import from root (go up three levels with ...)
+cl import from ...ButtonRoot {
+    ButtonRoot
+}
+
+# Import from second level (go up one level with ..)
+cl import from ..ButtonSecondL {
+    ButtonSecondL
+}
+```
+
+## Complete Example
+
+Here's a complete example demonstrating nested folder imports:
+
+**Project Structure:**
+```
+nested-advance/
+├── app.jac                    # Root entry point
+├── ButtonRoot.jac            # Root level button
+└── level1/
+    ├── ButtonSecondL.jac     # Second level button
+    ├── Card.jac              # Card component (imports from root and level2)
+    └── level2/
+        └── ButtonThirdL.jac  # Third level button
+```
+
+**app.jac:**
+```jac
+cl import from .ButtonRoot {
+    ButtonRoot
+}
+cl import from .level1.ButtonSecondL {
+    ButtonSecondL
+}
+cl import from .level1.level2.ButtonThirdL {
+    ButtonThirdL
+}
+cl import from .level1.Card {
+    Card
+}
+
+cl def app() -> any {
+    return <div>
+        <ButtonRoot />
+        <ButtonSecondL />
+        <ButtonThirdL />
+        <Card />
+    </div>;
+}
+```
+
+**level1/ButtonSecondL.jac:**
+```jac
+cl import from ..ButtonRoot {
+    ButtonRoot
+}
+
+cl def ButtonSecondL() -> any {
+    return <div>
+        <Button>Second Level</Button>
+        <ButtonRoot />
+    </div>;
+}
+```
+
+**level1/Card.jac:**
+```jac
+# Imports from both above (root) and below (level2)
+cl import from ..ButtonRoot {
+    ButtonRoot
+}
+cl import from .level2.ButtonThirdL {
+    ButtonThirdL
+}
+
+cl def Card() -> any {
+    return <div>
+        <ButtonRoot />
+        <ButtonThirdL />
+    </div>;
+}
+```
+
+**level1/level2/ButtonThirdL.jac:**
+```jac
+cl import from ...ButtonRoot {
+    ButtonRoot
+}
+cl import from ..ButtonSecondL {
+    ButtonSecondL
+}
+
+cl def ButtonThirdL() -> any {
+    return <div>
+        <Button>Third Level</Button>
+        <ButtonRoot />
+        <ButtonSecondL />
+    </div>;
+}
+```
+
+## Import Path Reference
+
+| Your Location | Target Location | Import Path |
+|--------------|----------------|-------------|
+| `app.jac` (root) | `ButtonRoot.jac` (root) | `.ButtonRoot` |
+| `app.jac` (root) | `level1/ButtonSecondL.jac` | `.level1.ButtonSecondL` |
+| `app.jac` (root) | `level1/level2/ButtonThirdL.jac` | `.level1.level2.ButtonThirdL` |
+| `level1/ButtonSecondL.jac` | `ButtonRoot.jac` (root) | `..ButtonRoot` |
+| `level1/Card.jac` | `ButtonRoot.jac` (root) | `..ButtonRoot` |
+| `level1/Card.jac` | `level2/ButtonThirdL.jac` | `.level2.ButtonThirdL` |
+| `level1/level2/ButtonThirdL.jac` | `ButtonRoot.jac` (root) | `...ButtonRoot` |
+| `level1/level2/ButtonThirdL.jac` | `level1/ButtonSecondL.jac` | `..ButtonSecondL` |
+
+## Benefits of Nested Folder Structure
+
+1. **Relative imports work correctly**: Folder structure is preserved, so imports resolve properly
+2. **No file name conflicts**: Files with the same name in different folders don't overwrite each other
+3. **Familiar structure**: Organize code in nested folders just like in TypeScript/JavaScript projects
+4. **Consistent with modern tooling**: Matches the behavior of TypeScript, Babel, and other transpilers
+5. **Scalable organization**: Organize large applications into logical folder hierarchies
+
+## Best Practices for Nested Folders
+
+1. **Organize by feature or component type**: Group related files together
+   ```
+   components/
+   ├── ui/
+   │   ├── Button.jac
+   │   └── Card.jac
+   ├── layout/
+   │   ├── Header.jac
+   │   └── Footer.jac
+   └── features/
+       ├── TodoList.jac
+       └── TodoItem.jac
+   ```
+
+2. **Use consistent naming**: Keep file names descriptive and consistent
+3. **Limit nesting depth**: Avoid going too deep (3-4 levels is usually sufficient)
+4. **Document import patterns**: Comment complex import relationships
+
+## Common Patterns
+
+### Pattern 1: Component Library Structure
+```
+components/
+├── ui/
+│   ├── Button.jac
+│   └── Input.jac
+├── forms/
+│   ├── LoginForm.jac
+│   └── SignupForm.jac
+└── layout/
+    ├── Header.jac
+    └── Sidebar.jac
+```
+
+**Usage:**
+```jac
+# From root
+cl import from .components.ui.Button { Button }
+cl import from .components.forms.LoginForm { LoginForm }
+
+# From components/ui/Button.jac importing from forms
+cl import from ..forms.LoginForm { LoginForm }
+```
+
+### Pattern 2: Feature-Based Structure
+```
+features/
+├── auth/
+│   ├── Login.jac
+│   └── Signup.jac
+├── todos/
+│   ├── TodoList.jac
+│   └── TodoItem.jac
+└── dashboard/
+    ├── Dashboard.jac
+    └── Stats.jac
+```
+
+**Usage:**
+```jac
+# From root
+cl import from .features.auth.Login { Login }
+cl import from .features.todos.TodoList { TodoList }
+
+# From features/auth/Login.jac importing from todos
+cl import from ..todos.TodoList { TodoList }
+```
+
+### Pattern 3: Mixed Structure
+```
+app.jac                    # Root entry
+components/
+├── ui/
+│   └── Button.jac
+utils/
+├── helpers/
+│   └── format.jac
+hooks/
+└── useCounter.jac
+```
+
+**Usage:**
+```jac
+# From app.jac
+cl import from .components.ui.Button { Button }
+cl import from .utils.helpers.format { capitalize }
+cl import from .hooks.useCounter { useCounter }
+
+# From components/ui/Button.jac
+cl import from ...utils.helpers.format { capitalize }
+```
+
+## Troubleshooting
+
+### Import Not Found
+- Verify the file exists at the expected path
+- Check that the relative path matches the folder structure
+- Ensure file extension is `.jac` (not `.cl.jac` for imports)
+
+### Wrong Import Path
+- Count the directory levels between source and target
+- Use `..` for each level up, `.folder` for each level down
+- Start with `.` for current directory imports
+
+### File Name Conflicts
+- Use nested folders to avoid conflicts
+- Files with the same name in different folders won't conflict
+- Folder structure is preserved in compiled output
+
+## Examples
+
+Complete working examples demonstrating nested folder imports:
+
+- [`nested-basic/`](../../examples/nested-folders/nested-basic/) - Simple nested folder structure
+- [`nested-advance/`](../../examples/nested-folders/nested-advance/) - Advanced multi-level nesting
+
+Run any example:
+
+```bash
+cd jac-client/jac_client/examples/nested-folders/<example-name>
+npm install
+jac serve app.jac
+```
+
+## Related Documentation
+
+- [Backend/Frontend Separation](backend-frontend.md)
+- [Import System](../imports.md)
+- [File System Organization](intro.md)

jac_client/docs/guide-example/intro.md

@@ -15,19 +15,19 @@ Traditionally, you'd need:
 - **SQL** for database
 - **REST APIs** to connect them
 
-With **Jac**, you write **everything in one language**, in **one file**! 🚀
+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
+-  **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**!
 
@@ -67,8 +67,8 @@ pip install jac-client
 
 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
+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!
 
@@ -112,6 +112,4 @@ We'll build the app in 11 progressive steps:
 
 Let's build your first full-stack app!
 
-👉 **[Continue to Step 1: Project Setup](./step-01-setup.md)**
-
-
+ **[Continue to Step 1: Project Setup](./step-01-setup.md)**

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

@@ -1,12 +1,12 @@
 # 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!
+> ** 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
+## Part 1: Building the App
 
 ### Step 1.1: Create Your Project
 
@@ -78,15 +78,15 @@ Open your browser and go to:
 http://localhost:8000/page/app
 ```
 
-You should see "Hello, Jac!" and "My first full-stack 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)
+**⏭ Want to skip the theory?** Jump to [Step 2: First Component](./step-02-components.md)
 
 ---
 
-## 💡 Part 2: Understanding the Concepts
+## Part 2: Understanding the Concepts
 
 ### What is `cl { ... }`?
 
@@ -99,6 +99,7 @@ cl {
 ```
 
 Think of it like this:
+
 - Code **inside** `cl { }` → Runs in the browser (frontend)
 - Code **outside** `cl { }` → Runs on the server (backend)
 
@@ -113,6 +114,7 @@ def app() -> any {
 ```
 
 **Requirements:**
+
 - Must be named `app` (by convention)
 - Must return JSX (HTML-like syntax)
 - Located inside `cl { }` block
@@ -142,19 +144,22 @@ return <div>
 ```
 
 **Key rules:**
+
 1. Must have **one root element**
+
    ```jac
-   # ✅ Correct
+   #  Correct
    return <div><h1>Title</h1><p>Text</p></div>;
 
-   # ❌ Wrong (two root elements)
+   #  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
+   <img src="photo.jpg" />    #  Correct
+   <img src="photo.jpg">       #  Wrong
    ```
 
 3. Use `{}` to insert Jac code
@@ -190,22 +195,23 @@ But for this tutorial, we'll keep everything in one file for simplicity.
 
 ---
 
-## ✅ What You've Learned
+## 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`
+- 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
+## Common Issues
 
 ### Issue: `jac: command not found`
 
 **Solution**: Install jac-client:
+
 ```bash
 pip install jac-client
 ```
@@ -213,14 +219,17 @@ 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
@@ -228,13 +237,14 @@ Then visit `http://localhost:8080/page/app`
 ### Issue: Changes not showing
 
 **Solution**:
+
 - Stop the server (Ctrl+C)
 - Restart: `jac serve app.jac`
 - Refresh browser
 
 ---
 
-## 🎯 Quick Exercise
+## Quick Exercise
 
 Before moving on, try changing the text:
 
@@ -253,8 +263,8 @@ Save, refresh your browser, and see the changes!
 
 ---
 
-## ➡️ Next Step
+## 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)**
+**[Continue to Step 2: First Component](./step-02-components.md)**

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

@@ -1,12 +1,12 @@
 # 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!
+> ** 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
+##  Part 1: Building the App
 
 ### Step 2.1: Create a TodoItem Component
 
@@ -119,11 +119,11 @@ cl {
 
 ---
 
-**⏭️ Want to skip the theory?** Jump to [Step 3: Styling](./step-03-styling.md)
+**⏭ Want to skip the theory?** Jump to [Step 3: Styling](./step-03-styling.md)
 
 ---
 
-## 💡 Part 2: Understanding the Concepts
+##  Part 2: Understanding the Concepts
 
 ### What is a Component?
 
@@ -182,12 +182,12 @@ If there's a bug in how todos display, you know to check `TodoItem`.
 **1. Use PascalCase** (first letter capitalized)
 
 ```jac
-# ✅ Correct
+#  Correct
 def TodoItem() -> any { ... }
 def UserProfile() -> any { ... }
 def NavigationBar() -> any { ... }
 
-# ❌ Wrong
+#  Wrong
 def todoItem() -> any { ... }      # camelCase
 def user_profile() -> any { ... }  # snake_case
 def navigation-bar() -> any { ... } # kebab-case
@@ -196,12 +196,12 @@ def navigation-bar() -> any { ... } # kebab-case
 **2. Name describes what it does**
 
 ```jac
-# ✅ Good names
+#  Good names
 def TodoItem() -> any { ... }
 def LoginForm() -> any { ... }
 def ProductCard() -> any { ... }
 
-# ❌ Bad names
+#  Bad names
 def Component1() -> any { ... }
 def Thing() -> any { ... }
 def X() -> any { ... }
@@ -226,14 +226,14 @@ def TodoItem(props: any) -> any {
 **Important**: In React (which Jac uses), components receive props as a **single object**, not individual parameters.
 
 ```jac
-# ✅ Correct way
+#  Correct way
 def TodoItem(props: any) -> any {
     let text = props.text;
     let done = props.done;
     # ...
 }
 
-# ❌ Wrong way (won't work)
+#  Wrong way (won't work)
 def TodoItem(text: str, done: bool) -> any {
     # This doesn't work in React!
 }
@@ -328,19 +328,19 @@ let myText = "Learn Jac";
 
 ---
 
-## ✅ What You've Learned
+##  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
+-  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
+##  Common Issues
 
 ### Issue: Component not showing up
 
@@ -354,12 +354,12 @@ let myText = "Learn Jac";
 **Cause**: Using individual parameters instead of props object
 
 ```jac
-# ❌ Wrong
+#  Wrong
 def TodoItem(text: str, done: bool) -> any {
     # ...
 }
 
-# ✅ Correct
+#  Correct
 def TodoItem(props: any) -> any {
     let text = props.text;
     # ...
@@ -385,7 +385,7 @@ def TodoItem(props: any) -> any {
 
 ---
 
-## 🎯 Quick Exercise
+##  Quick Exercise
 
 Try adding a new component:
 
@@ -409,8 +409,8 @@ def app() -> any {
 
 ---
 
-## ➡️ Next Step
+##  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)**
+ **[Continue to Step 3: Styling](./step-03-styling.md)**