dars-framework 1.2.3__tar.gz → 1.2.5__tar.gz

dars_framework-1.2.5/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: dars_framework
+Version: 1.2.5
+Summary: Dars is a Python UI framework for building modern, interactive web apps with only Python code. Write your interface in Python, export it to static HTML/CSS/JS, and deploy anywhere.
+Author-email: ztamdev <ztadevs@gmail.com>
+License-Expression: MIT
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich==14.2.0
+Requires-Dist: bs4==0.0.2
+Requires-Dist: uvicorn==0.35.0
+Requires-Dist: fastapi==0.116.1
+Requires-Dist: markdown2==2.5.4
+Requires-Dist: requests==2.32.5
+Requires-Dist: rjsmin==1.2.5
+Dynamic: license-file
+
+<h1 align="center">Dars Framework</h1>
+ 
+<p align="center">
+  <img src="./Dars-logo.png" alt="Dars Framework Logo" width="200" />
+</p>
+
+<p align="center">
+  <em>Dars is a Python UI framework for building modern, interactive web apps with Python code. Write your interface in Python, export it to static HTML/CSS/JS, and deploy anywhere.</em>
+</p>
+
+```bash
+pip install dars-framework
+```
+
+> Some Javascript or frontend stack required.
+
+Try dars without installing nothing just visit the [Dars Playground](https://dars-playground.vercel.app/)
+
+## How It Works
+- Build your UI using Python classes and components (like Text, Button, Container, Page, etc).
+- Preview instantly with hot-reload using `app.rTimeCompile()`.
+- Export your app to static web files with a single CLI command.
+- Use multipage, layouts, scripts, and more—see docs for advanced features.
+- For more information visit the [Documentation](https://ztamdev.github.io/Dars-Framework/documentation.html)
+
+## Quick Example: Your First App
+```python
+from dars.all import *
+
+app = App(title="Hello World", theme="dark")
+# Crear componentes
+index = Page(
+     Text(
+        text="Hello World",
+        style={
+            'font-size': '48px',
+            'color': '#2c3e50',
+            'margin-bottom': '20px',
+            'font-weight': 'bold',
+            'text-align': 'center'
+        }
+    ),
+    Text(
+        text="Hello World",
+        style={
+            'font-size': '20px',
+            'color': '#7f8c8d',
+            'margin-bottom': '40px',
+            'text-align': 'center'
+        }
+    ),
+
+    Button(
+        text="Click Me!",
+        on_click= dScript("alert('Hello World')"),
+        on_mouse_enter=dScript("this.style.backgroundColor = '#2980b9';"),
+        on_mouse_leave=dScript("this.style.backgroundColor = '#3498db';"),
+        style={
+            'background-color': '#3498db',
+            'color': 'white',
+            'padding': '15px 30px',
+            'border': 'none',
+            'border-radius': '8px',
+            'font-size': '18px',
+            'cursor': 'pointer',
+            'transition': 'background-color 0.3s'
+        }
+    ),
+    style={
+        'display': 'flex',
+        'flex-direction': 'column',
+        'align-items': 'center',
+        'justify-content': 'center',
+        'min-height': '100vh',
+        'background-color': '#f0f2f5',
+        'font-family': 'Arial, sans-serif'
+    }
+) 
+index.attr()
+app.add_page("index", index, title="Hello World", index=True)
+
+if __name__ == "__main__":
+    app.rTimeCompile()
+
+```
+
+---
+
+## Reactivity and State System
+
+**Dars Framework** includes a built-in **reactive state system** (`dState` / `cState`) that allows dynamic and modular DOM updates directly from Python.
+It enables fully event-driven interfaces without requiring manual JavaScript.
+
+### Key Concepts
+
+* **`dState(name, component, states)`**
+  Creates a reactive state controller bound to a specific component and a list of possible states.
+
+* **`cState(idx, mods=[...])`**
+  Defines rules (modifications) that are automatically applied when entering a specific state.
+
+* **`Mod` Helpers**
+  A compact way to modify DOM elements on state changes: `inc`, `dec`, `set`, `toggle_class`, `append_text`, `prepend_text`, `goto`, and more.
+
+* **Deferred Mutations**
+  Using `component.attr(..., defer=True)` or `component.mod(...)` inside a `cComp=True` state defers HTML updates until an event occurs, preventing authoring-time mutations.
+
+### Example Template
+
+A complete example demonstrating `dState`, `cState`, `Mod`, and deferred updates is available [here](https://github.com/ZtaMDev/Dars-Framework/blob/CrystalMain/dars/templates/examples/advanced/dState/state_mods_demo.py)
+
+<img width="384" height="187" alt="imagen" src="https://github.com/user-attachments/assets/7750ee7f-768f-48da-94df-2fa00339a99c" /> <img width="361" height="215" alt="imagen" src="https://github.com/user-attachments/assets/9b8a3e67-2424-49b4-aee0-9f1c0f747d66" />
+
+
+
+### Features
+
+* Reactive Mod system with compact `Mod` helpers
+* Unified event model — any component can use `on_*` props (`on_click`, `on_input`, `on_change`, etc.)
+* Deferred rendering for safer, predictable state transitions (`cComp=True`)
+* Navigation between states using `goto`, including relative moves (`'+1'`, `'-1'`)
+* Consistent, event-time mutation flow for reliable behavior
+* Secure minification for production bundles (strong JS/CSS minifier integrated into the build pipeline)
+
+---
+
+## CLI Usage
+| Command                                 | What it does                               |
+|-----------------------------------------|--------------------------------------------|
+| `dars export my_app.py --format html`   | Export app to HTML/CSS/JS in `./my_app_web` |
+| `dars preview ./my_app_web`             | Preview exported app locally                |
+| `dars init my_project`                  | Create a new Dars project (also creates dars.config.json) |
+| `dars init --update`                    | Create/Update dars.config.json in current dir |
+| `dars build`                            | Build using dars.config.json (entry/outdir/format) |
+| `dars config validate`                  | Validate dars.config.json and print report   |
+| `dars info my_app.py`                   | Show info about your app                    |
+| `dars formats`                          | List supported export formats               |
+| `dars --help`                           | Show help and all CLI options               |
+
+Tip: use `dars doctor` to review optional tooling that can enhance bundling/minification.
+
+## More
+
+- Visit dars [official website](https://ztamdev.github.io/Dars-Framework/)
+- Visit the dars official [Documentation](https://ztamdev.github.io/Dars-Framework/documentation.html) now on separate website.
+- Try dars without installing nothing just visit the [Dars Playground](https://dars-playground.vercel.app/)
+
+## Local Execution and Live Preview
+
+To test your app locally before exporting, use the hot-reload preview from any Python file that defines your app:
+
+```python
+if __name__ == "__main__":
+    app.rTimeCompile()
+```
+
+Then run your file directly:
+
+```bash
+python my_app.py
+```
+
+This will start a local server at http://localhost:8000 so you can view your app in the browser—no manual export needed. You can change the port with:
+
+```bash
+python my_app.py --port 8088
+```
+
+---
+
+You can also use the CLI preview command on an exported app:
+
+```bash
+dars preview ./my_exported_app
+```
+
+This will start a local server at http://localhost:8000 to view your exported app in the browser.
+
+---
+
+## Project Configuration (dars.config.json)
+
+Dars can read build/export settings from a `dars.config.json` at your project root. It is created automatically by `dars init`, and you can add it to existing projects with `dars init --update`.
+
+Example default:
+
+```json
+{
+  "entry": "main.py",
+  "format": "html",
+  "outdir": "dist",
+  "publicDir": null,
+  "include": [],
+  "exclude": ["**/__pycache__", ".git", ".venv", "node_modules"],
+  "bundle": true,
+  "viteMinify": true
+}
+```
+
+- `entry`: Python entry file. Used by `dars build` and `dars export config`.
+- `format`: Export format. Currently only `html` is supported.
+- `outdir`: Output directory. Used by `dars build` and default for `dars export` when not overridden.
+- `publicDir`: Folder (e.g., `public/` or `assets/`) copied into the output. If null, it is autodetected.
+- `include`/`exclude`: Basic filters for copying from `publicDir`.
+- `bundle`: Reserved for future use. CLI exports and build already bundle appropriately.
+- `viteMinify`: Toggle the Vite-based minifier for JS. When `false`, the build uses esbuild-based minification. If neither is available, a conservative Python fallback is used.
+
+Validate your config:
+
+```bash
+dars config validate
+```
+
+Build using config:
+
+```bash
+dars build
+```
+
+Export using the config entry and outdir:
+
+```bash
+dars export config --format html
+```
+
+---
+
+See LandingPage docs for details: state_management.md, events.md, scripts.md.

{dars_framework-1.2.3 → dars_framework-1.2.5}/README.md

@@ -120,6 +120,7 @@ A complete example demonstrating `dState`, `cState`, `Mod`, and deferred updates
 * Deferred rendering for safer, predictable state transitions (`cComp=True`)
 * Navigation between states using `goto`, including relative moves (`'+1'`, `'-1'`)
 * Consistent, event-time mutation flow for reliable behavior
+* Secure minification for production bundles (strong JS/CSS minifier integrated into the build pipeline)
 
 ---
 
@@ -136,6 +137,8 @@ A complete example demonstrating `dState`, `cState`, `Mod`, and deferred updates
 | `dars formats`                          | List supported export formats               |
 | `dars --help`                           | Show help and all CLI options               |
 
+Tip: use `dars doctor` to review optional tooling that can enhance bundling/minification.
+
 ## More
 
 - Visit dars [official website](https://ztamdev.github.io/Dars-Framework/)
@@ -189,7 +192,8 @@ Example default:
   "publicDir": null,
   "include": [],
   "exclude": ["**/__pycache__", ".git", ".venv", "node_modules"],
-  "bundle": false
+  "bundle": true,
+  "viteMinify": true
 }
 ```
 
@@ -199,6 +203,7 @@ Example default:
 - `publicDir`: Folder (e.g., `public/` or `assets/`) copied into the output. If null, it is autodetected.
 - `include`/`exclude`: Basic filters for copying from `publicDir`.
 - `bundle`: Reserved for future use. CLI exports and build already bundle appropriately.
+- `viteMinify`: Toggle the Vite-based minifier for JS. When `false`, the build uses esbuild-based minification. If neither is available, a conservative Python fallback is used.
 
 Validate your config:
 

{dars_framework-1.2.3 → dars_framework-1.2.5}/dars/cli/doctor/doctor.py

@@ -1,7 +1,7 @@
 import os, sys
 from typing import Dict, List
 from .detect import detect_node, detect_bun, detect_esbuild, detect_vite, read_pyproject_deps, check_python_deps
-from .installers import install_node, install_bun, install_esbuild, install_vite
+from .installers import install_bun
 from .persist import load_config, save_config
 from .ui import render_report, prompt_action, confirm_install
 from rich.console import Console
@@ -23,11 +23,13 @@ def run_doctor(check_only: bool = False, auto_yes: bool = False, install_all: bo
 
     render_report(node, bun, py, esb, vit)
 
+    # Mandatory only for doctor purposes: Python deps
     missing_items: List[str] = []
-    if not node.get('ok'): missing_items.append('Node.js LTS')
-    if not bun.get('ok'): missing_items.append('Bun stable')
     if py.get('missing'): missing_items.append('Python deps')
+    # Node, Bun, esbuild, vite treated as optional. Bun can be auto-installed if user wants.
     optional_missing: List[str] = []
+    if not node.get('ok'): optional_missing.append('Node.js (optional)')
+    if not bun.get('ok'): optional_missing.append('Bun (optional)')
     if not esb.get('ok'): optional_missing.append('esbuild (optional)')
     if not vit.get('ok'): optional_missing.append('vite (optional)')
 
@@ -73,37 +75,21 @@ def run_doctor(check_only: bool = False, auto_yes: bool = False, install_all: bo
 
     # choice == '1' => Install ALL missing
     summary: List[str] = []
-    if not node.get('ok'): summary.append('Node.js LTS (winget)')
-    if not bun.get('ok'): summary.append('Bun (winget)')
+    # Only Bun and Python deps are installable from doctor; Node/esbuild/vite show links in the report
+    if not bun.get('ok'): summary.append('Bun (winget/installer)')
     if py.get('missing'): summary.append(f"Python deps: {', '.join(py['missing'])}")
-    if optional_missing:
-        summary.extend(optional_missing)
+    # Do not include other optional tools in install summary
 
     if not auto_yes:
         if not confirm_install(summary):
             return 1
 
-    # Installers: always run Node then Bun sequentially (idempotent if already installed)
+    # Installers: only Bun, optionally Python deps
     with console.status("[cyan]Installing selected items...[/cyan]"):
-        try:
-            install_node()
-        except Exception:
-            pass
         try:
             install_bun()
         except Exception:
             pass
-        # Optional developer tools
-        try:
-            if not esb.get('ok'):
-                install_esbuild()
-        except Exception:
-            pass
-        try:
-            if not vit.get('ok'):
-                install_vite()
-        except Exception:
-            pass
 
     # Python deps via pip
     if py.get('missing'):
@@ -124,11 +110,12 @@ def run_doctor(check_only: bool = False, auto_yes: bool = False, install_all: bo
 
     render_report(node2, bun2, py2, esb2, vit2)
 
-    all_ok = node2.get('ok') and bun2.get('ok') and not py2.get('missing')
+    all_ok = not py2.get('missing')
 
     cfg['requirements']['node'].update({'ok': bool(node2.get('ok')), 'version': node2.get('version')})
     cfg['requirements']['bun'].update({'ok': bool(bun2.get('ok')), 'version': bun2.get('version')})
     cfg['python_deps'] = {'ok': not bool(py2.get('missing')), 'missing': py2.get('missing') or []}
+    # doctor satisfaction now tied only to Python deps
     cfg['satisfied'] = bool(all_ok)
     save_config(cfg)
 
@@ -137,16 +124,12 @@ def run_doctor(check_only: bool = False, auto_yes: bool = False, install_all: bo
 
 def run_forcedev() -> int:
     """Force-install everything without initial verification or prompts.
-    - Attempts Node LTS and Bun installers unconditionally (best-effort)
+    - Attempts Bun installer unconditionally (best-effort)
     - Installs/updates all Python deps from pyproject.toml
     - Re-checks and persists satisfied state
     Returns 0 if environment ends OK, else 1.
     """
     # Best-effort installs (no UI)
-    try:
-        install_node()
-    except Exception:
-        pass
     try:
         install_bun()
     except Exception:
@@ -163,11 +146,12 @@ def run_forcedev() -> int:
 
     # Re-check and persist
     cfg = load_config()
-    node2 = detect_node()
     bun2 = detect_bun()
     py2 = check_python_deps(read_pyproject_deps())
-    all_ok = node2.get('ok') and bun2.get('ok') and not py2.get('missing')
+    all_ok = bun2.get('ok') and not py2.get('missing')
 
+    # keep node state updated for UI even if not installed by forcedev
+    node2 = detect_node()
     cfg['requirements']['node'].update({'ok': bool(node2.get('ok')), 'version': node2.get('version')})
     cfg['requirements']['bun'].update({'ok': bool(bun2.get('ok')), 'version': bun2.get('version')})
     cfg['python_deps'] = {'ok': not bool(py2.get('missing')), 'missing': py2.get('missing') or []}

{dars_framework-1.2.3 → dars_framework-1.2.5}/dars/cli/doctor/ui.py

@@ -31,6 +31,19 @@ def render_report(node: Dict, bun: Dict, py: Dict, esb: Dict = None, vit: Dict =
         bullets = "\n".join([f" • {req}" for req in p_missing])
         console.print(Panel(bullets or "", title="Missing Python packages", border_style="yellow"))
 
+    # Helpful links for optional tools
+    tips: List[str] = []
+    if node is not None and not node.get("ok"):
+        tips.append("Node.js LTS (manual): https://nodejs.org/en/download")
+    if bun is not None and not bun.get("ok"):
+        tips.append("Bun (auto-install available) — Windows: winget / PS: irm bun.sh/install.ps1 | iex — macOS/Linux: curl -fsSL https://bun.sh/install | bash")
+    if esb is not None and not esb.get("ok"):
+        tips.append("esbuild (optional): https://esbuild.github.io/getting-started/")
+    if vit is not None and not vit.get("ok"):
+        tips.append("Vite (optional): https://vite.dev/guide/")
+    if tips:
+        console.print(Panel("\n".join([f" • {t}" for t in tips]), title="How to install (optional)", border_style="cyan"))
+
 
 def prompt_action(has_missing: bool) -> str:
     console.print(Panel("Select an action", border_style="cyan"))