dars-framework 1.2.1__tar.gz → 1.2.2__tar.gz

{dars_framework-1.2.1/dars_framework.egg-info → dars_framework-1.2.2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: dars_framework
-Version: 1.2.1
+Version: 1.2.2
 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 <zondax2009@gmail.com>
-License: MIT
+License-Expression: MIT
 License-File: LICENSE
-Requires-Dist: rich==14.0.0
+Requires-Dist: rich==14.2.0
 Requires-Dist: bs4==0.0.2
 Requires-Dist: uvicorn==0.35.0
 Requires-Dist: fastapi==0.116.1

{dars_framework-1.2.1 → dars_framework-1.2.2}/README.md

@@ -14,207 +14,226 @@ 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 mor 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
-
----
-
-## 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               |
-
-## 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": false
-}
-```
-
-- `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.
-
-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
-```
-
+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 mor 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
+
+---
+
+## 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               |
+
+## 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": false
+}
+```
+
+- `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.
+
+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
+```
+
+
+---
+
+## What's new in v1.2.2
+
+Highlights:
+
+- Cross-dState calls with `Mod.call(...)` to trigger other states.
+- Immutable default state (index `0`) that restores the component's initial DOM when activated.
+- `Mod.set` accepts multiple attributes and `on_*` event arrays (mix InlineScript, FileScript, dScript, or JS strings), executed sequentially.
+- State bootstrap now serializes embedded scripts safely; runtime reconstitutes them.
+
+Upgrade:
+
+```bash
+pip install --upgrade dars-framework
+```
+
+See LandingPage docs for details: state_management.md, events.md, scripts.md.

{dars_framework-1.2.1 → dars_framework-1.2.2}/dars/core/state.py

@@ -20,6 +20,12 @@ class DarsState:
             "states": self.states,
             "isCustom": self.is_custom,
         }
+        try:
+            d["defaultIndex"] = 0
+            d["defaultValue"] = (self.states[0] if isinstance(self.states, list) and len(self.states) > 0 else None)
+        except Exception:
+            d["defaultIndex"] = 0
+            d["defaultValue"] = None
         if self.rules:
             d["rules"] = self.rules
         return d
@@ -96,6 +102,11 @@ class DarsState:
     # --- cState: define rules/mods for a given state index ---
     def cState(self, idx: int, mods: Optional[List[Dict[str, Any]]] = None) -> 'CStateRuleBuilder':
         key = str(idx)
+        if idx == 0:
+            raise ValueError(
+                "Default state (index 0) is immutable. Do not define cState(0). "
+                "Configure the component's default directly on the instance instead."
+            )
         if key not in self.rules:
             self.rules[key] = {}
         if mods:
@@ -154,6 +165,40 @@ class Mod:
         tid = getattr(target, 'id', None) or str(target)
         return {"op": "prependText", "target": tid, "value": value}
 
+    @staticmethod
+    def call(target: Any, state: Any = None, goto: Any = None) -> Dict[str, Any]:
+        """Invoke another dState's state change.
+        - target: DarsState instance or state name string; if a component is passed, use its id.
+        - state: target state index/value.
+        - goto: relative/absolute goto directive (e.g., '+1').
+        The runtime will resolve the state by name first (registry), falling back to id.
+        """
+        name: Optional[str] = None
+        sid: Optional[str] = None
+        try:
+            # DarsState instance
+            if hasattr(target, 'name') and hasattr(target, 'id'):
+                name = getattr(target, 'name', None)
+                sid = getattr(target, 'id', None)
+            elif isinstance(target, str):
+                name = target
+            else:
+                # Maybe a component; try id
+                sid = getattr(target, 'id', None) or str(target)
+        except Exception:
+            name = None
+            sid = None
+        d: Dict[str, Any] = {"op": "call"}
+        if name:
+            d['name'] = name
+        if sid:
+            d['id'] = sid
+        if state is not None:
+            d['state'] = state
+        if goto is not None:
+            d['goto'] = goto
+        return d
+
 
 class CStateRuleBuilder:
     def __init__(self, st: DarsState, key: str):
@@ -214,6 +259,15 @@ class CStateRuleBuilder:
             self.st._bootstrap_ref['rules'][self.key] = self.st.rules[self.key]
         return self
 
+    def call(self, target: Any, state: Any = None, goto: Any = None) -> 'CStateRuleBuilder':
+        """Append a cross-state call op to this rule."""
+        self._ensure()
+        self.st.rules[self.key]['mods'].append(Mod.call(target, state=state, goto=goto))
+        if self.st._bootstrap_ref is not None:
+            self.st._bootstrap_ref.setdefault('rules', {})
+            self.st._bootstrap_ref['rules'][self.key] = self.st.rules[self.key]
+        return self
+
     def goto(self, value: Any) -> 'CStateRuleBuilder':
         if self.key not in self.st.rules:
             self.st.rules[self.key] = {}

{dars_framework-1.2.1 → dars_framework-1.2.2}/dars/exporters/web/html_css_js.py

@@ -640,7 +640,26 @@ self.addEventListener('fetch', event => {
             from dars.core.state import STATE_BOOTSTRAP
             if STATE_BOOTSTRAP:
                 import json as _json
-                bootstrap_json = _json.dumps(STATE_BOOTSTRAP, ensure_ascii=False)
+                from copy import deepcopy as _deepcopy
+                try:
+                    from dars.scripts.script import Script as _Script
+                except Exception:
+                    _Script = None
+
+                def _ser(v):
+                    try:
+                        if _Script and isinstance(v, _Script):
+                            return {"code": v.get_code()}
+                        if isinstance(v, dict):
+                            return {k: _ser(val) for k, val in v.items()}
+                        if isinstance(v, list):
+                            return [_ser(x) for x in v]
+                        return v
+                    except Exception:
+                        return v
+
+                _clean = _ser(_deepcopy(STATE_BOOTSTRAP))
+                bootstrap_json = _json.dumps(_clean, ensure_ascii=False)
                 if bundle:
                     # Obfuscate: base64-encode the bootstrap JSON
                     import base64 as _b64
@@ -1798,6 +1817,10 @@ body {
         if(id && eventMap.has(id)){
           const handlers = eventMap.get(id);
           const h = handlers[eventName];
+          // If there is a dynamic handler attached on this node for the same event, let it handle and skip default
+          if(node && node.__darsEv && node.__darsEv[eventName]){
+            return;
+          }
           if(typeof h === 'function'){
             try { h.call(node, e); } catch(err){ console.error('[Dars] handler error', err); }
             return;