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

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

@@ -1,348 +0,0 @@
-# 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

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