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

jac_client/docs/README.md

@@ -4,11 +4,41 @@ Welcome to the Todo App example! This guide will walk you through building a ful
 
 ---
 
-## 📦 1. Creating the Application
+##  1. Creating the Application
+
+### Prerequisites
+
+Before installing Jac client, you need to have **Node.js** installed on your system.
+
+#### Installing Node.js
+
+**For Linux users:**
+
+Visit [https://nodejs.org/en/download](https://nodejs.org/en/download) and follow the instructions to install Node.js using **nvm** (Node Version Manager) with **npm**.
+
+Select:
+- **Platform**: Linux
+- **Package Manager**: nvm
+- **Package**: npm
+
+Then follow the installation commands provided on that page.
+
+**For macOS users:**
+
+Download and install Node.js from [https://nodejs.org/en/download](https://nodejs.org/en/download) by selecting your operating system.
+
+**Verify Installation:**
+
+After installation, verify Node.js and npm are installed correctly:
+
+```bash
+node -v
+npm -v
+```
 
 ### Installation
 
-First, install the Jac client package:
+Once Node.js is installed, install the Jac client package:
 
 ```bash
 pip install jac-client
@@ -53,7 +83,7 @@ You can access your app at `http://localhost:8000`
 
 ---
 
-## 🚪 2. Entry Point of the App
+##  2. Entry Point of the App
 
 Every Jac client application needs an entry point function. This is where your app starts rendering.
 
@@ -119,7 +149,7 @@ cl {
 
 ---
 
-## 🧩 3. Creating Components
+##  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.
 
@@ -194,7 +224,7 @@ def TodoItem(item: dict) -> any {
 
 ---
 
-## 🗄️ 4. Adding State with React Hooks
+##  4. Adding State with React Hooks
 
 Jac uses React hooks for state management. You can use all standard React hooks by importing them:
 
@@ -297,7 +327,7 @@ cl {
 
 ---
 
-## 🎯 5. Event Handling
+##  5. Event Handling
 
 Event handling in Jac works just like React, but with Jac's lambda syntax.
 
@@ -385,7 +415,7 @@ def FilterButton(filterType: str, currentFilter: str, onFilterChange: any) -> an
 
 ---
 
-## ✨ 6. Magic: No More Axios/Fetch!
+##  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.
 
@@ -510,13 +540,13 @@ walker create_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
+ **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
 
@@ -547,7 +577,7 @@ if jacIsLoggedIn() {
 
 ---
 
-## 🎨 Complete Example: Todo App Structure
+##  Complete Example: Todo App Structure
 
 Here's how all the pieces fit together:
 
@@ -612,7 +642,7 @@ cl {
 
 ---
 
-## 🚀 Running the Todo App
+##  Running the Todo App
 
 To run this example:
 
@@ -625,7 +655,7 @@ Then visit `http://localhost:8000` in your browser.
 
 ---
 
-## 📚 Next Steps
+##  Next Steps
 
 Ready to dive deeper? Explore these advanced topics:
 
@@ -635,7 +665,7 @@ Ready to dive deeper? Explore these advanced topics:
 - **[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
+##  Examples
 
 Check out the `examples/` directory for working applications:
 
@@ -647,7 +677,7 @@ Check out the `examples/` directory for working applications:
 
 ---
 
-## 💡 Key Takeaways
+##  Key Takeaways
 
 1. **Single Language**: Write frontend and backend in Jac
 2. **No HTTP Client**: Use `spawn` syntax instead of fetch/axios
@@ -656,4 +686,4 @@ Check out the `examples/` directory for working applications:
 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! 🎉
+Happy coding with Jac!

jac_client/docs/advanced-state.md

@@ -4,7 +4,7 @@ Learn how to manage complex state in Jac using React hooks, combining multiple s
 
 ---
 
-## 📚 Table of Contents
+##  Table of Contents
 
 - [React Hooks Overview](#react-hooks-overview)
 - [Multiple State Variables](#multiple-state-variables)
@@ -1091,7 +1091,7 @@ cl {
 ```jac
 cl import from react { useState }
 
-# ✅ Good: Separate state variables
+#  Good: Separate state variables
 def App() -> any {
     let [user, setUser] = useState(None);
     let [todos, setTodos] = useState([]);
@@ -1099,7 +1099,7 @@ def App() -> any {
     let [theme, setTheme] = useState("light");
 }
 
-# ❌ Avoid: One giant state object for unrelated data
+#  Avoid: One giant state object for unrelated data
 def App() -> any {
     let [appState, setAppState] = useState({
         "user": None,
@@ -1115,7 +1115,7 @@ def App() -> any {
 ```jac
 cl import from react { useState, useMemo }
 
-# ✅ Good: Memoize expensive calculations
+#  Good: Memoize expensive calculations
 def TodoApp() -> any {
     let [todos, setTodos] = useState([]);
 
@@ -1124,7 +1124,7 @@ def TodoApp() -> any {
     }, [todos]);
 }
 
-# ❌ Avoid: Computing on every render
+#  Avoid: Computing on every render
 def TodoApp() -> any {
     let [todos, setTodos] = useState([]);
 
@@ -1138,13 +1138,13 @@ def TodoApp() -> any {
 ```jac
 cl import from react { useState }
 
-# ✅ Good: Calculate derived values
+#  Good: Calculate derived values
 def TodoApp() -> any {
     let [todos, setTodos] = useState([]);
     activeCount = todos.filter(lambda t: any -> bool { return not t.done; }).length;
 }
 
-# ❌ Avoid: Storing derived values in state
+#  Avoid: Storing derived values in state
 def TodoApp() -> any {
     let [todos, setTodos] = useState([]);
     let [activeCount, setActiveCount] = useState(0);  # Redundant!
@@ -1156,7 +1156,7 @@ def TodoApp() -> any {
 ```jac
 cl import from react { useReducer }
 
-# ✅ Good: useReducer for complex interdependent state
+#  Good: useReducer for complex interdependent state
 def TodoApp() -> any {
     def reducer(state: dict, action: dict) -> dict {
         if action.type == "ADD" {
@@ -1168,7 +1168,7 @@ def TodoApp() -> any {
     let [state, dispatch] = useReducer(reducer, {"todos": [], "count": 0});
 }
 
-# ❌ Avoid: Multiple useState for interdependent state
+#  Avoid: Multiple useState for interdependent state
 def TodoApp() -> any {
     let [todos, setTodos] = useState([]);
     let [count, setCount] = useState(0);
@@ -1181,7 +1181,7 @@ def TodoApp() -> any {
 ```jac
 cl import from react { useState, useEffect }
 
-# ✅ Good: Comprehensive state management
+#  Good: Comprehensive state management
 def TodoApp() -> any {
     let [todos, setTodos] = useState([]);
     let [loading, setLoading] = useState(False);
@@ -1214,7 +1214,7 @@ def TodoApp() -> any {
 ```jac
 cl import from react { useState, useCallback }
 
-# ✅ Good: Memoized callbacks prevent unnecessary re-renders
+#  Good: Memoized callbacks prevent unnecessary re-renders
 def TodoApp() -> any {
     let [todos, setTodos] = useState([]);
 
@@ -1234,7 +1234,7 @@ def TodoApp() -> any {
 ```jac
 cl import from react { useState, useContext, createContext }
 
-# ✅ Good: Context avoids prop drilling
+#  Good: Context avoids prop drilling
 ThemeContext = createContext("light");
 
 def App() -> any {
@@ -1262,5 +1262,4 @@ def DeeplyNestedComponent() -> any {
 - **Custom Hooks**: Create reusable state logic
 - **Best Practices**: Separate concerns, avoid derived state, handle errors
 
-React hooks provide a powerful and flexible way to manage state in Jac applications! 🚀
-
+React hooks provide a powerful and flexible way to manage state in Jac applications!

jac_client/docs/asset-serving/intro.md

@@ -0,0 +1,209 @@
+# Asset Serving in Jac
+
+Static assets such as images, fonts, videos, and stylesheets are essential for web applications. Jac provides multiple approaches for serving these assets, each suited for different use cases.
+
+!!! tip "Important"
+    All local assets must be placed in the `assets/` folder at the root of your project. The server serves these files from the `/static/` path.
+
+## Overview
+
+Jac supports two primary approaches for asset serving:
+
+- **Remote Assets**: External URLs from CDNs or remote servers
+- **Local Assets**: Files stored in your project, served by the Jac server
+
+Local assets can be referenced using either **Static Path** (direct `/static/` URLs) or **Import Alias** (Vite-processed imports with optimization).
+
+## Remote Assets
+
+Use external URLs for assets hosted on CDNs or remote servers.
+
+### Usage
+
+```jac
+<img src="https://picsum.photos/400/300" alt="Image" />
+<img src="https://via.placeholder.com/400x300" alt="Placeholder" />
+```
+
+### When to Use
+
+- CDN-hosted production assets
+- Placeholder images during development
+- External resources managed outside your project
+- Dynamic or user-generated content
+
+## Local Assets
+
+> **Important**: All local assets must be placed in the `assets/` folder at the root of your project. .
+
+Local assets are stored in your project and served by the Jac server. Two methods are available:
+
+### Static Path
+
+Reference assets directly using the `/static/` path prefix.
+
+#### Usage
+
+```jac
+<img src="/static/assets/burger.png" alt="Burger" />
+<link rel="stylesheet" href="/static/styles.css" />
+```
+
+#### How It Works
+
+- Assets in the `assets/` folder are served at `/static/assets/` path
+- Assets in `dist/` are also accessible via `/static/`
+- Server automatically detects file type and sets correct MIME type
+- No build configuration required
+
+#### When to Use
+
+- Quick prototypes and simple applications
+- Assets that don't require optimization
+- Immediate results without build step
+
+### Import Alias
+
+Import assets using the `@jac-client/assets` alias for Vite-processed assets.
+
+#### Usage
+
+```jac
+cl import from "@jac-client/assets/burger.png" { default as burgerImage }
+
+<img src={burgerImage} alt="Burger" />
+```
+
+#### How It Works
+
+- Alias configured in `vite.config.js` points to `src/assets/`
+- Assets from root `assets/` folder are copied to `src/assets/` during build
+- Vite processes imports and generates optimized asset URLs
+- Automatic hash generation for cache busting
+
+#### When to Use
+
+- Production applications
+- Assets that benefit from optimization
+- Type-safe asset references
+- Automatic cache busting
+
+## Using Assets in CSS
+
+Assets can be referenced in CSS files using static paths.
+
+### Usage
+
+**CSS File (`styles.css`):**
+```css
+.container {
+    background-image: url('/static/assets/burger.png');
+    background-size: cover;
+    background-position: center;
+}
+
+.burgerImage {
+    width: 200px;
+    height: auto;
+    border-radius: 10px;
+}
+```
+
+**Jac File:**
+```jac
+cl import "./styles.css";
+
+<div className="container">
+    <img src="/static/assets/burger.png" className="burgerImage" alt="Burger" />
+</div>
+```
+
+### Notes
+
+- CSS files reference assets using `/static/` paths
+- Assets are resolved at runtime by the server
+- Works with both background images and regular image elements
+
+## Supported Asset Types
+
+Jac automatically serves and detects MIME types for:
+
+- **Images**: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.ico`, `.avif`
+- **Fonts**: `.woff`, `.woff2`, `.ttf`, `.otf`, `.eot`
+- **Media**: `.mp4`, `.webm`, `.ogg`, `.mov`, `.mp3`, `.wav`, `.m4a`
+- **Documents**: `.pdf`
+- **Stylesheets**: `.css`, `.scss`, `.sass`, `.less`
+
+## Project Structure
+
+```
+project/
+├── assets/              # Static assets (served via /static/)
+│   ├── images/
+│   ├── fonts/
+│   └── videos/
+├── src/
+│   └── assets/         # Assets for import alias (@jac-client/assets)
+└── dist/               # Vite output (auto-generated)
+```
+
+## Examples
+
+Complete working examples are available:
+
+- [`image-asset/`](../../examples/asset-serving/image-asset/) - Static path serving
+- [`import-alias/`](../../examples/asset-serving/import-alias/) - Import alias pattern
+- [`css-with-image/`](../../examples/asset-serving/css-with-image/) - Assets in CSS
+
+Run any example:
+
+```bash
+cd jac-client/jac_client/examples/asset-serving/<example-name>
+npm install
+jac serve app.jac
+```
+
+## Quick Reference
+
+### Remote URLs
+```jac
+<img src="https://example.com/image.jpg" alt="Image" />
+```
+
+### Static Path
+```jac
+<img src="/static/assets/logo.png" alt="Logo" />
+```
+
+### Import Alias
+```jac
+cl import from "@jac-client/assets/logo.png" { default as logo }
+<img src={logo} />
+```
+
+### CSS Assets
+```css
+.hero {
+    background-image: url('/static/assets/hero.jpg');
+}
+```
+
+## Troubleshooting
+
+**Asset not found (404)**
+- Verify file exists in `assets/` or `dist/` directory
+- Check path matches file location exactly
+
+**Import not resolving**
+- Ensure `vite.config.js` has `@jac-client/assets` alias configured
+- Verify assets are copied to `src/assets/` during build
+
+**CSS background image not showing**
+- Use `/static/` prefix in CSS `url()` paths
+- Verify asset file exists in `assets/` directory
+
+## Related Documentation
+
+- [Import System](../imports.md)
+- [Styling](../styling/intro.md)
+- [Routing](../routing.md)