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

jac_client/examples/asset-serving/css-with-image/README.md

@@ -0,0 +1,91 @@
+# Relative Imports Example
+
+This example demonstrates how to import static assets using relative path imports.
+
+## Features
+
+- Imports image using relative path (`./assets/burger.png`)
+- Component-scoped asset organization
+- Vite processes and optimizes the asset
+- Familiar import syntax
+
+## Project Structure
+
+```
+relative-imports/
+├── app.jac          # Main application file
+├── assets/          # Static assets directory
+│   └── burger.png   # Burger image
+├── src/             # Source files (generated)
+├── build/           # Build output (generated)
+└── dist/            # Distribution output (generated)
+```
+
+## Running the Example
+
+1. Make sure node modules are installed:
+```bash
+npm install
+```
+
+2. Run the Jac server:
+```bash
+jac serve app.jac
+```
+
+3. Open your browser and navigate to:
+```
+http://localhost:8000/page/app
+```
+
+## How It Works
+
+### Import Syntax
+
+```jac
+cl import from "./assets/burger.png" { default as burgerImage }
+<img src={burgerImage} />
+```
+
+### Path Resolution
+
+- Relative paths are resolved from the current file location
+- `./assets/burger.png` resolves relative to `app.jac`
+- Vite processes the import during build
+- Assets are optimized and bundled
+
+### Use Cases
+
+**Component-Scoped Assets:**
+```jac
+# In a component file
+cl import from "./images/icon.svg" { default as icon }
+```
+
+**Parent Directory Assets:**
+```jac
+# Access assets from parent directory
+cl import from "../shared/assets/logo.png" { default as logo }
+```
+
+**Nested Assets:**
+```jac
+# Assets in subdirectories
+cl import from "./assets/images/hero.jpg" { default as hero }
+```
+
+### Benefits
+
+- **Familiar Syntax**: Standard relative import pattern
+- **Component Organization**: Assets organized by component/feature
+- **Flexibility**: Easy to reorganize without changing alias config
+- **Modular**: Works well with component-based architecture
+
+## Best Practices
+
+1. Use relative imports for component-specific assets
+2. Organize assets near the components that use them
+3. Keep relative paths simple and clear
+4. Use consistent naming conventions
+
+Happy coding with Jac! 🍔

jac_client/examples/asset-serving/css-with-image/app.jac

@@ -0,0 +1,67 @@
+# Pages
+cl import from react {useState, useEffect}
+cl import ".styles.css";
+
+cl {
+    def app() -> any {
+        let [count, setCount] = useState(0);
+        useEffect(lambda -> None {
+            console.log("Count: ", count);
+        }, [count]);
+        return <div style={{padding: "20px", textAlign: "center", fontFamily: "Arial, sans-serif"}}>
+            <h1>🍔 Burger Counter App</h1>
+            <img
+                src="/static/assets/burger.png"
+                alt="Delicious Burger"
+                style={{
+                    width: "200px",
+                    height: "auto",
+                    margin: "20px 0",
+                    borderRadius: "10px",
+                    boxShadow: "0 4px 8px rgba(0,0,0,0.2)"
+                }}
+            />
+            <p style={{fontSize: "18px", margin: "20px 0"}}>
+                You've clicked the burger <strong>{count}</strong> times!
+            </p>
+            <button
+                onClick={lambda e: any ->  None {setCount(count + 1);}}
+                style={{
+                    padding: "10px 20px",
+                    fontSize: "16px",
+                    backgroundColor: "#ff6b35",
+                    color: "white",
+                    border: "none",
+                    borderRadius: "5px",
+                    cursor: "pointer",
+                    boxShadow: "0 2px 4px rgba(0,0,0,0.2)"
+                }}
+            >
+                Click the Burger! 🍔
+            </button>
+
+            <h2 style={{marginTop: "40px", marginBottom: "20px"}}>CSS Asset Examples</h2>
+
+            <div className="container">
+                <h3 style={{color: "white", textShadow: "2px 2px 4px rgba(0,0,0,0.5)"}}>
+                    Background Image Example
+                </h3>
+                <p style={{color: "white", textShadow: "2px 2px 4px rgba(0,0,0,0.5)"}}>
+                    This container uses the burger image as a background via CSS
+                </p>
+            </div>
+
+            <div className="card">
+                <h3>Image in Card</h3>
+                <img
+                    src="/static/assets/burger.png"
+                    alt="Burger in Card"
+                    className="burgerImage"
+                />
+                <p style={{marginTop: "15px", color: "#666"}}>
+                    This image is displayed within a styled card using CSS classes
+                </p>
+            </div>
+        </div>;
+    }
+}

jac_client/examples/asset-serving/css-with-image/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "relative-imports",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "build": "npm run compile && vite build",
+    "dev": "vite dev",
+    "preview": "vite preview",
+    "compile": "babel src --out-dir build --extensions \".jsx,.js\" --out-file-extension .js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "Jac application: relative-imports",
+  "type": "module",
+  "devDependencies": {
+    "vite": "^6.4.1",
+    "@babel/cli": "^7.28.3",
+    "@babel/core": "^7.28.5",
+    "@babel/preset-env": "^7.28.5",
+    "@babel/preset-react": "^7.28.5"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^6.30.1"
+  }
+}

jac_client/examples/asset-serving/css-with-image/styles.css

@@ -0,0 +1,27 @@
+.container {
+    background-image: url('/static/assets/burger.png');
+    background-size: cover;
+    background-position: center;
+    min-height: 300px;
+    border-radius: 10px;
+    padding: 20px;
+    margin: 20px 0;
+}
+
+.card {
+    background: white;
+    border-radius: 10px;
+    padding: 20px;
+    box-shadow: 0 4px 8px rgba(0,0,0,0.2);
+    max-width: 400px;
+    margin: 20px auto;
+}
+
+.burgerImage {
+    width: 200px;
+    height: auto;
+    border-radius: 10px;
+    display: block;
+    margin: 0 auto;
+}
+

jac_client/examples/asset-serving/css-with-image/vite.config.js

@@ -0,0 +1,29 @@
+
+import { defineConfig } from "vite";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  root: ".", // base folder
+  build: {
+    rollupOptions: {
+      input: "build/main.js", // your compiled entry file
+      output: {
+        entryFileNames: "client.[hash].js", // name of the final js file
+        assetFileNames: "[name].[ext]",
+      },
+    },
+    outDir: "dist", // final bundled output
+    emptyOutDir: true,
+  },
+  publicDir: false,
+  resolve: {
+    alias: {
+      "@jac-client/utils": path.resolve(__dirname, "src/client_runtime.js"),
+      "@jac-client/assets": path.resolve(__dirname, "src/assets"),
+    },
+  },
+});
+

jac_client/examples/asset-serving/image-asset/.babelrc

@@ -0,0 +1,9 @@
+
+{
+    "presets": [[
+        "@babel/preset-env",
+        {
+            "modules": false
+        }
+    ], "@babel/preset-react"]
+}

jac_client/examples/asset-serving/image-asset/README.md

@@ -0,0 +1,119 @@
+# Static Path Example
+
+This example demonstrates how to serve static assets using direct `/static/` path references.
+
+## Features
+
+- Direct path references using `/static/assets/` URLs
+- Simple and straightforward approach
+- No build configuration required
+- Works immediately without imports
+
+## Project Structure
+
+```
+image-asset/
+├── app.jac          # Main application file
+├── assets/          # Static assets directory
+│   └── burger.png   # Burger image
+├── src/             # Source files (generated)
+├── build/           # Build output (generated)
+└── dist/            # Distribution output (generated)
+```
+
+## Running the Example
+
+1. Make sure node modules are installed:
+```bash
+npm install
+```
+
+2. Run the Jac server:
+```bash
+jac serve app.jac
+```
+
+3. Open your browser and navigate to:
+```
+http://localhost:8000/page/app
+```
+
+## How It Works
+
+### Static Path Syntax
+
+```jac
+<img src="/static/assets/burger.png" alt="Burger" />
+```
+
+### Server Configuration
+
+The server automatically serves files from:
+- `dist/` directory (Vite-bundled assets)
+- `assets/` directory (user-provided static assets)
+
+Both directories are checked when serving `/static/*` requests.
+
+### Path Resolution
+
+1. Request: `/static/assets/burger.png`
+2. Server checks `dist/assets/burger.png` first
+3. If not found, checks `assets/burger.png`
+4. Serves file with appropriate MIME type
+5. Sets cache headers for optimal performance
+
+### Benefits
+
+- **Simplicity**: No imports or build configuration needed
+- **Immediate**: Works right away without build step
+- **Flexible**: Easy to reference assets from anywhere
+- **Quick Prototyping**: Perfect for rapid development
+
+### Use Cases
+
+**Direct Image References:**
+```jac
+<img src="/static/assets/logo.png" alt="Logo" />
+```
+
+**CSS Background Images:**
+```jac
+<div style={{backgroundImage: "url('/static/assets/hero.jpg')"}} />
+```
+
+**Dynamic Asset Paths:**
+```jac
+let imagePath = `/static/assets/${imageName}.png`;
+<img src={imagePath} />
+```
+
+## Best Practices
+
+1. Use this method for quick prototypes
+2. Organize assets in the `assets/` folder
+3. Use descriptive file names
+4. Keep assets reasonably sized
+5. Consider using imports for production apps
+
+## Limitations
+
+- No automatic optimization
+- No hash-based cache busting
+- Manual cache control required
+- No type safety for asset paths
+
+## When to Use
+
+**Choose Static Path if:**
+- Building a quick prototype
+- Assets don't need optimization
+- Want immediate results
+- Working with simple, small assets
+
+**Consider Import Methods if:**
+- Building for production
+- Need automatic optimization
+- Want cache busting
+- Prefer type-safe references
+
+Happy coding with Jac! 🍔

jac_client/examples/asset-serving/image-asset/app.jac

@@ -0,0 +1,43 @@
+# Pages
+cl import from react {useState, useEffect}
+
+cl {
+    def app() -> any {
+        let [count, setCount] = useState(0);
+        useEffect(lambda -> None {
+            console.log("Count: ", count);
+        }, [count]);
+        return <div style={{padding: "20px", textAlign: "center", fontFamily: "Arial, sans-serif"}}>
+            <h1>🍔 Burger Counter App</h1>
+            <img
+                src="/static/assets/burger.png"
+                alt="Delicious Burger"
+                style={{
+                    width: "200px",
+                    height: "auto",
+                    margin: "20px 0",
+                    borderRadius: "10px",
+                    boxShadow: "0 4px 8px rgba(0,0,0,0.2)"
+                }}
+            />
+            <p style={{fontSize: "18px", margin: "20px 0"}}>
+                You've clicked the burger <strong>{count}</strong> times!
+            </p>
+            <button
+                onClick={lambda e: any ->  None {setCount(count + 1);}}
+                style={{
+                    padding: "10px 20px",
+                    fontSize: "16px",
+                    backgroundColor: "#ff6b35",
+                    color: "white",
+                    border: "none",
+                    borderRadius: "5px",
+                    cursor: "pointer",
+                    boxShadow: "0 2px 4px rgba(0,0,0,0.2)"
+                }}
+            >
+                Click the Burger! 🍔
+            </button>
+        </div>;
+    }
+}

jac_client/examples/asset-serving/image-asset/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "image-asset",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "build": "npm run compile && vite build",
+    "dev": "vite dev",
+    "preview": "vite preview",
+    "compile": "babel src --out-dir build --extensions \".jsx,.js\" --out-file-extension .js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "Jac application: image-asset",
+  "type": "module",
+  "devDependencies": {
+    "vite": "^6.4.1",
+    "@babel/cli": "^7.28.3",
+    "@babel/core": "^7.28.5",
+    "@babel/preset-env": "^7.28.5",
+    "@babel/preset-react": "^7.28.5"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^6.30.1"
+  }
+}

jac_client/examples/asset-serving/image-asset/styles.css

@@ -0,0 +1,27 @@
+.container {
+    background-image: url('/static/assets/burger.png');
+    background-size: cover;
+    background-position: center;
+    min-height: 300px;
+    border-radius: 10px;
+    padding: 20px;
+    margin: 20px 0;
+}
+
+.card {
+    background: white;
+    border-radius: 10px;
+    padding: 20px;
+    box-shadow: 0 4px 8px rgba(0,0,0,0.2);
+    max-width: 400px;
+    margin: 20px auto;
+}
+
+.burgerImage {
+    width: 200px;
+    height: auto;
+    border-radius: 10px;
+    display: block;
+    margin: 0 auto;
+}
+

jac_client/examples/asset-serving/image-asset/vite.config.js

@@ -0,0 +1,29 @@
+
+import { defineConfig } from "vite";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  root: ".", // base folder
+  build: {
+    rollupOptions: {
+      input: "build/main.js", // your compiled entry file
+      output: {
+        entryFileNames: "client.[hash].js", // name of the final js file
+        assetFileNames: "[name].[ext]",
+      },
+    },
+    outDir: "dist", // final bundled output
+    emptyOutDir: true,
+  },
+  publicDir: false,
+  resolve: {
+    alias: {
+      "@jac-client/utils": path.resolve(__dirname, "src/client_runtime.js"),
+      "@jac-client/assets": path.resolve(__dirname, "src/assets"),
+    },
+  },
+});
+

jac_client/examples/asset-serving/import-alias/.babelrc

@@ -0,0 +1,9 @@
+
+{
+    "presets": [[
+        "@babel/preset-env",
+        {
+            "modules": false
+        }
+    ], "@babel/preset-react"]
+}

jac_client/examples/asset-serving/import-alias/README.md

@@ -0,0 +1,83 @@
+# Import Alias Example
+
+This example demonstrates how to import static assets using the `@jac-client/assets` alias pattern.
+
+## Features
+
+- Imports image using `@jac-client/assets` alias
+- Vite processes and optimizes the asset
+- Automatic hash generation for cache busting
+- Type-safe asset references
+
+## Project Structure
+
+```
+import-alias/
+├── app.jac          # Main application file
+├── assets/          # Static assets directory
+│   └── burger.png   # Burger image
+├── src/             # Source files (generated)
+├── build/           # Build output (generated)
+└── dist/            # Distribution output (generated)
+```
+
+## Running the Example
+
+1. Make sure node modules are installed:
+```bash
+npm install
+```
+
+2. Run the Jac server:
+```bash
+jac serve app.jac
+```
+
+3. Open your browser and navigate to:
+```
+http://localhost:8000/page/app
+```
+
+## How It Works
+
+### Import Syntax
+
+```jac
+cl import from "@jac-client/assets/burger.png" { default as burgerImage }
+<img src={burgerImage} />
+```
+
+### Configuration
+
+The alias is configured in `vite.config.js`:
+
+```javascript
+resolve: {
+  alias: {
+    "@jac-client/assets": path.resolve(__dirname, "src/assets"),
+  },
+}
+```
+
+### Build Process
+
+1. Assets from root `assets/` folder are copied to `src/assets/` during build
+2. Vite processes the import and generates optimized asset URLs
+3. Assets are bundled with hash-based filenames for cache invalidation
+4. The imported variable contains the processed asset URL
+
+### Benefits
+
+- **Type Safety**: Import errors caught at build time
+- **Optimization**: Vite automatically optimizes assets
+- **Cache Busting**: Hash-based filenames prevent stale cache
+- **Code Splitting**: Assets can be code-split automatically
+
+## Best Practices
+
+1. Use this method for production applications
+2. Organize assets in the `assets/` folder
+3. Let Vite handle optimization and caching
+4. Use descriptive variable names for imported assets
+
+Happy coding with Jac! 🍔

jac_client/examples/asset-serving/import-alias/app.jac

@@ -0,0 +1,57 @@
+# Pages
+cl import from react {useState, useEffect}
+# Import image using the @jac-client/assets alias
+cl import from "@jac-client/assets/burger.png" { default as burgerImage }
+
+cl {
+    def app() -> any {
+        let [count, setCount] = useState(0);
+        useEffect(lambda -> None {
+            console.log("Count: ", count);
+        }, [count]);
+        return <div style={{padding: "20px", textAlign: "center", fontFamily: "Arial, sans-serif"}}>
+            <h1>🍔 Import Alias Example</h1>
+            <p style={{color: "#666", marginBottom: "20px"}}>
+                Using <code>@jac-client/assets</code> alias to import assets
+            </p>
+            <img
+                src={burgerImage}
+                alt="Delicious Burger"
+                style={{
+                    width: "200px",
+                    height: "auto",
+                    margin: "20px 0",
+                    borderRadius: "10px",
+                    boxShadow: "0 4px 8px rgba(0,0,0,0.2)"
+                }}
+            />
+            <p style={{fontSize: "18px", margin: "20px 0"}}>
+                You've clicked the burger <strong>{count}</strong> times!
+            </p>
+            <button
+                onClick={lambda e: any ->  None {setCount(count + 1);}}
+                style={{
+                    padding: "10px 20px",
+                    fontSize: "16px",
+                    backgroundColor: "#ff6b35",
+                    color: "white",
+                    border: "none",
+                    borderRadius: "5px",
+                    cursor: "pointer",
+                    boxShadow: "0 2px 4px rgba(0,0,0,0.2)"
+                }}
+            >
+                Click the Burger! 🍔
+            </button>
+            <div style={{marginTop: "30px", padding: "15px", backgroundColor: "#f5f5f5", borderRadius: "5px", fontSize: "12px", textAlign: "left", maxWidth: "600px", margin: "30px auto"}}>
+                <strong>How it works:</strong>
+                <ul style={{marginTop: "10px", paddingLeft: "20px"}}>
+                    <li>Import using: <code>cl import from '@jac-client/assets/burger.png'</code></li>
+                    <li>Vite processes the import and generates optimized URLs</li>
+                    <li>Assets are automatically copied from <code>assets/</code> to <code>src/assets/</code> during build</li>
+                    <li>Automatic hash generation for cache busting</li>
+                </ul>
+            </div>
+        </div>;
+    }
+}