dars-framework 1.9.2__tar.gz → 1.9.5__tar.gz

{dars_framework-1.9.2/dars_framework.egg-info → dars_framework-1.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dars-framework
-Version: 1.9.2
+Version: 1.9.5
 Summary: Dars is a Full-Stack multiplatform Python UI framework for building modern, interactive web and desktop apps with Python code. Seamlessly integrated with FastAPI, it allows you to build complete applications with Server-Side Rendering (SSR) and reactive SPA capabilities also classic multipage html and desktop apps in a single codebase.
 Author-email: ztamdev <ztadevs@gmail.com>
 Maintainer-email: ztamdev <ztadevs@gmail.com>
@@ -52,7 +52,6 @@ Dynamic: license-file
   <a href="https://deepwiki.com/ZtaMDev/Dars-Framework"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
-
 <p align="center">
   <em>Dars is a Full-Stack multiplatform Python UI framework for building modern, interactive web and desktop apps with Python code. Seamlessly integrated with FastAPI, it allows you to build complete applications with Server-Side Rendering (SSR) and reactive SPA capabilities also classic multipage html and desktop apps in a single codebase.</em>
 
@@ -60,8 +59,9 @@ Dynamic: license-file
 
 <div align="center">
 
-Official [Website](https://ztamdev.github.io/Dars-Framework/) | 
-Documentation [Docs](https://ztamdev.github.io/Dars-Framework/docs.html) | 
+Official [Website](https://ztamdev.github.io/Dars-Framework/) |
+Documentation [Docs](https://ztamdev.github.io/Dars-Framework/docs.html) |
+Official [Roadmap](https://ztamdev.github.io/Dars-Framework/roadmap.html) |
 Extension for VSCode [here](https://marketplace.visualstudio.com/items?itemName=ZtaMDev.dars-framework) and OpenVSX version [here](https://open-vsx.org/extension/ztamdev/dars-framework)
 
 </div>
@@ -73,6 +73,7 @@ pip install dars-framework
 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/dynamic/ssr web files with a single CLI command.
@@ -81,6 +82,7 @@ Try dars without installing nothing just visit the [Dars Playground](https://dar
 - For more information visit the [Documentation](https://ztamdev.github.io/Dars-Framework/docs.html)
 
 ## Quick Example: Your First App
+
 ```python
 from dars.all import *
 
@@ -91,7 +93,7 @@ state = State("app", title_val="Simple Counter", count=0)
 
 # 2. Define Route
 @route("/")
-def index(): 
+def index():
     return Page(
         # 3. Use useValue for app text
         Text(
@@ -131,7 +133,7 @@ def index():
         ),
         style="flex flex-col items-center justify-center h-[100vh] ffam-[Arial] bg-[#f0f2f5]",
 
-    ) 
+    )
 
 # 8. Add page
 app.add_page("index", index(), title="index")
@@ -148,9 +150,11 @@ if __name__ == "__main__":
 Dars Framework features **powerful state management system**, designed for different use cases.
 
 ### State V2
+
 Modern, Pythonic state management for reactive updates. Best for counters, timers, and component interactions using hooks.
 
 **Hooks System:**
+
 - `useDynamic()`: Reactive state binding for automatic UI updates.
 - `useValue()`: Set initial values from state (non-reactive).
 - `useWatch()`: Monitor state changes and trigger side effects.
@@ -168,7 +172,7 @@ def index():
     return Page(
         # Bind to state with useDynamic
         Text(text=useDynamic("counter.count"), style={"font-size": "24px"}),
-        
+
         # Update state on click
         Button("Increment", on_click=state.count.increment(1)),
         Button("Decrement", on_click=state.count.decrement(1)),
@@ -181,7 +185,7 @@ if __name__ == "__main__":
     app.rTimeCompile()
 ```
 
-**String ID Support:** `State()` can accept a string ID (e.g., `State("my-state", ...)`). 
+**String ID Support:** `State()` can accept a string ID (e.g., `State("my-state", ...)`).
 
 > [!WARNING]
 > **Important:** When using hooks, the State ID is used for binding. **Do not use an ID that belongs to another unrelated component**, as hooks use this ID as the State ID. Using a conflicting ID may cause unexpected behavior or state collisions.
@@ -215,6 +219,7 @@ button.on_click = sequence(
 ```
 
 **Available Animations:**
+
 - **Opacity:** `fadeIn`, `fadeOut`
 - **Movement:** `slideIn`, `slideOut` (up, down, left, right)
 - **Scaling:** `scaleIn`, `scaleOut`, `pulse`
@@ -257,7 +262,6 @@ button.on_click = sequence(
 
 ---
 
-
 ## Routing System (SPA & SSR)
 
 Dars Framework offers a flexible routing system that supports both Client-Side Routing (SPA) and Server-Side Rendering (SSR).
@@ -321,7 +325,7 @@ def dashboard():
             Link("Settings", href="/dashboard/settings"),
             Link("Profile", href="/dashboard/profile"),
             id="nav",
-            
+
         ),
         Outlet(),  # Child routes render here
         style={"padding": "20px"}
@@ -356,6 +360,7 @@ app.set_404_page(custom_404)
 ### Hot Reload for SPAs
 
 The development preview server includes intelligent hot reload:
+
 - Detects changes and reloads automatically
 - Stops polling after 10 errors to prevent browser lag
 - Clean console output without spam
@@ -458,10 +463,10 @@ callback=(
 
 ### Available HTTP Methods
 
-- **`get(id, url, **options)`** - GET request
-- **`post(id, url, body, **options)`** - POST request  
-- **`put(id, url, body, **options)`** - PUT request
-- **`delete(id, url, **options)`** - DELETE request
+- **`get(id, url, **options)`\*\* - GET request
+- **`post(id, url, body, **options)`\*\* - POST request
+- **`put(id, url, body, **options)`\*\* - PUT request
+- **`delete(id, url, **options)`\*\* - DELETE request
 
 For complete documentation, see the [Backend API Guide](https://ztamdev.github.io/Dars-Framework/docs.html#backend-http-utilities).
 
@@ -469,22 +474,23 @@ For complete documentation, see the [Backend API Guide](https://ztamdev.github.i
 
 ## CLI Usage
 
-| Command                                   | What it does                                 |
-|-------------------------------------------|----------------------------------------------|
-| `dars export my_app.py --format html`     | Export app to HTML/CSS/JS in `./my_app_web`   |
-| `dars init --type desktop`               | Scaffold desktop-capable project (BETA)       |
-| `dars init --type ssr`                   | Scaffold full-stack SSR project (SSR + API)   |
-| `dars build` (desktop config)            | Build desktop app artifacts (BETA)            |
-| `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 dev`                               | Run the configured entry file with hot preview (app.rTimeCompile) |
-| `dars dev --backend`                     | Run only the configured backendEntry (FastAPI/SSR backend) |
-| `dars --help`                            | Show help and all CLI options                 |
+| Command                               | What it does                                                      |
+| ------------------------------------- | ----------------------------------------------------------------- |
+| `dars export my_app.py --format html` | Export app to HTML/CSS/JS in `./my_app_web`                       |
+| `dars init --type desktop`            | Scaffold desktop-capable project (BETA)                           |
+| `dars init --type ssr`                | Scaffold full-stack SSR project (SSR + API)                       |
+| `dars build` (desktop config)         | Build desktop app artifacts (BETA)                                |
+| `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 dev`                            | Run the configured entry file with hot preview (app.rTimeCompile) |
+| `dars dev --port 9000`                | Run dev server on a custom port (overrides config)                |
+| `dars dev --backend`                  | Run only the configured backendEntry (FastAPI/SSR backend)        |
+| `dars --help`                         | Show help and all CLI options                                     |
 
 Tip: use `dars doctor` to review optional tooling that can enhance bundling/minification.
 
@@ -516,7 +522,7 @@ Then run your file directly:
 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:
+This will start a local server at the port specified in your `dars.config.json` (defaults to http://localhost:8000) so you can view your app in the browser—no manual export needed. You can override the port with:
 
 ```bash
 python my_app.py --port 8088
@@ -554,6 +560,7 @@ Example default:
   "utility_styles": {},
   "markdownHighlight": true,
   "markdownHighlightTheme": "auto",
+  "port": 8000,
   "backendEntry": "backend.api:app"
 }
 ```
@@ -568,7 +575,8 @@ Example default:
 - `viteMinify`: Toggle the Vite/esbuild minifier for JS/CSS. Default `true`.
 - `utility_styles`: Dictionary defining custom utility classes. Keys are class names, values are lists of utility strings or raw CSS properties.
 - `markdownHighlight`: Auto-inject a client-side syntax highlighter for fenced code blocks in Markdown. Default `true`.
- - `backendEntry`: Python import path for your SSR/backend app (e.g. `"backend.api:app"`). Required when your app uses `RouteType.SSR` routes. Used by `dars dev --backend`.
+- `backendEntry`: Python import path for your SSR/backend app (e.g. `"backend.api:app"`). Required when your app uses `RouteType.SSR` routes. Used by `dars dev --backend`.
+- `port`: The port for the development preview server. Default `8000`.
 
 Validate your config:
 

{dars_framework-1.9.2 → dars_framework-1.9.5}/README.md

@@ -11,7 +11,6 @@
   <a href="https://deepwiki.com/ZtaMDev/Dars-Framework"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
-
 <p align="center">
   <em>Dars is a Full-Stack multiplatform Python UI framework for building modern, interactive web and desktop apps with Python code. Seamlessly integrated with FastAPI, it allows you to build complete applications with Server-Side Rendering (SSR) and reactive SPA capabilities also classic multipage html and desktop apps in a single codebase.</em>
 
@@ -19,8 +18,9 @@
 
 <div align="center">
 
-Official [Website](https://ztamdev.github.io/Dars-Framework/) | 
-Documentation [Docs](https://ztamdev.github.io/Dars-Framework/docs.html) | 
+Official [Website](https://ztamdev.github.io/Dars-Framework/) |
+Documentation [Docs](https://ztamdev.github.io/Dars-Framework/docs.html) |
+Official [Roadmap](https://ztamdev.github.io/Dars-Framework/roadmap.html) |
 Extension for VSCode [here](https://marketplace.visualstudio.com/items?itemName=ZtaMDev.dars-framework) and OpenVSX version [here](https://open-vsx.org/extension/ztamdev/dars-framework)
 
 </div>
@@ -32,6 +32,7 @@ pip install dars-framework
 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/dynamic/ssr web files with a single CLI command.
@@ -40,6 +41,7 @@ Try dars without installing nothing just visit the [Dars Playground](https://dar
 - For more information visit the [Documentation](https://ztamdev.github.io/Dars-Framework/docs.html)
 
 ## Quick Example: Your First App
+
 ```python
 from dars.all import *
 
@@ -50,7 +52,7 @@ state = State("app", title_val="Simple Counter", count=0)
 
 # 2. Define Route
 @route("/")
-def index(): 
+def index():
     return Page(
         # 3. Use useValue for app text
         Text(
@@ -90,7 +92,7 @@ def index():
         ),
         style="flex flex-col items-center justify-center h-[100vh] ffam-[Arial] bg-[#f0f2f5]",
 
-    ) 
+    )
 
 # 8. Add page
 app.add_page("index", index(), title="index")
@@ -107,9 +109,11 @@ if __name__ == "__main__":
 Dars Framework features **powerful state management system**, designed for different use cases.
 
 ### State V2
+
 Modern, Pythonic state management for reactive updates. Best for counters, timers, and component interactions using hooks.
 
 **Hooks System:**
+
 - `useDynamic()`: Reactive state binding for automatic UI updates.
 - `useValue()`: Set initial values from state (non-reactive).
 - `useWatch()`: Monitor state changes and trigger side effects.
@@ -127,7 +131,7 @@ def index():
     return Page(
         # Bind to state with useDynamic
         Text(text=useDynamic("counter.count"), style={"font-size": "24px"}),
-        
+
         # Update state on click
         Button("Increment", on_click=state.count.increment(1)),
         Button("Decrement", on_click=state.count.decrement(1)),
@@ -140,7 +144,7 @@ if __name__ == "__main__":
     app.rTimeCompile()
 ```
 
-**String ID Support:** `State()` can accept a string ID (e.g., `State("my-state", ...)`). 
+**String ID Support:** `State()` can accept a string ID (e.g., `State("my-state", ...)`).
 
 > [!WARNING]
 > **Important:** When using hooks, the State ID is used for binding. **Do not use an ID that belongs to another unrelated component**, as hooks use this ID as the State ID. Using a conflicting ID may cause unexpected behavior or state collisions.
@@ -174,6 +178,7 @@ button.on_click = sequence(
 ```
 
 **Available Animations:**
+
 - **Opacity:** `fadeIn`, `fadeOut`
 - **Movement:** `slideIn`, `slideOut` (up, down, left, right)
 - **Scaling:** `scaleIn`, `scaleOut`, `pulse`
@@ -216,7 +221,6 @@ button.on_click = sequence(
 
 ---
 
-
 ## Routing System (SPA & SSR)
 
 Dars Framework offers a flexible routing system that supports both Client-Side Routing (SPA) and Server-Side Rendering (SSR).
@@ -280,7 +284,7 @@ def dashboard():
             Link("Settings", href="/dashboard/settings"),
             Link("Profile", href="/dashboard/profile"),
             id="nav",
-            
+
         ),
         Outlet(),  # Child routes render here
         style={"padding": "20px"}
@@ -315,6 +319,7 @@ app.set_404_page(custom_404)
 ### Hot Reload for SPAs
 
 The development preview server includes intelligent hot reload:
+
 - Detects changes and reloads automatically
 - Stops polling after 10 errors to prevent browser lag
 - Clean console output without spam
@@ -417,10 +422,10 @@ callback=(
 
 ### Available HTTP Methods
 
-- **`get(id, url, **options)`** - GET request
-- **`post(id, url, body, **options)`** - POST request  
-- **`put(id, url, body, **options)`** - PUT request
-- **`delete(id, url, **options)`** - DELETE request
+- **`get(id, url, **options)`\*\* - GET request
+- **`post(id, url, body, **options)`\*\* - POST request
+- **`put(id, url, body, **options)`\*\* - PUT request
+- **`delete(id, url, **options)`\*\* - DELETE request
 
 For complete documentation, see the [Backend API Guide](https://ztamdev.github.io/Dars-Framework/docs.html#backend-http-utilities).
 
@@ -428,22 +433,23 @@ For complete documentation, see the [Backend API Guide](https://ztamdev.github.i
 
 ## CLI Usage
 
-| Command                                   | What it does                                 |
-|-------------------------------------------|----------------------------------------------|
-| `dars export my_app.py --format html`     | Export app to HTML/CSS/JS in `./my_app_web`   |
-| `dars init --type desktop`               | Scaffold desktop-capable project (BETA)       |
-| `dars init --type ssr`                   | Scaffold full-stack SSR project (SSR + API)   |
-| `dars build` (desktop config)            | Build desktop app artifacts (BETA)            |
-| `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 dev`                               | Run the configured entry file with hot preview (app.rTimeCompile) |
-| `dars dev --backend`                     | Run only the configured backendEntry (FastAPI/SSR backend) |
-| `dars --help`                            | Show help and all CLI options                 |
+| Command                               | What it does                                                      |
+| ------------------------------------- | ----------------------------------------------------------------- |
+| `dars export my_app.py --format html` | Export app to HTML/CSS/JS in `./my_app_web`                       |
+| `dars init --type desktop`            | Scaffold desktop-capable project (BETA)                           |
+| `dars init --type ssr`                | Scaffold full-stack SSR project (SSR + API)                       |
+| `dars build` (desktop config)         | Build desktop app artifacts (BETA)                                |
+| `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 dev`                            | Run the configured entry file with hot preview (app.rTimeCompile) |
+| `dars dev --port 9000`                | Run dev server on a custom port (overrides config)                |
+| `dars dev --backend`                  | Run only the configured backendEntry (FastAPI/SSR backend)        |
+| `dars --help`                         | Show help and all CLI options                                     |
 
 Tip: use `dars doctor` to review optional tooling that can enhance bundling/minification.
 
@@ -475,7 +481,7 @@ Then run your file directly:
 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:
+This will start a local server at the port specified in your `dars.config.json` (defaults to http://localhost:8000) so you can view your app in the browser—no manual export needed. You can override the port with:
 
 ```bash
 python my_app.py --port 8088
@@ -513,6 +519,7 @@ Example default:
   "utility_styles": {},
   "markdownHighlight": true,
   "markdownHighlightTheme": "auto",
+  "port": 8000,
   "backendEntry": "backend.api:app"
 }
 ```
@@ -527,7 +534,8 @@ Example default:
 - `viteMinify`: Toggle the Vite/esbuild minifier for JS/CSS. Default `true`.
 - `utility_styles`: Dictionary defining custom utility classes. Keys are class names, values are lists of utility strings or raw CSS properties.
 - `markdownHighlight`: Auto-inject a client-side syntax highlighter for fenced code blocks in Markdown. Default `true`.
- - `backendEntry`: Python import path for your SSR/backend app (e.g. `"backend.api:app"`). Required when your app uses `RouteType.SSR` routes. Used by `dars dev --backend`.
+- `backendEntry`: Python import path for your SSR/backend app (e.g. `"backend.api:app"`). Required when your app uses `RouteType.SSR` routes. Used by `dars dev --backend`.
+- `port`: The port for the development preview server. Default `8000`.
 
 Validate your config:
 

{dars_framework-1.9.2 → dars_framework-1.9.5}/dars/all.py

@@ -65,6 +65,7 @@ from dars.exporters.web.html_css_js import HTMLCSSJSExporter
 # Script utilities
 from dars.scripts.dscript import dScript, RawJS, Arg
 from dars.scripts.utils_ds import showModal, hideModal, goTo, goToNew, reload, goBack, goForward, alert, confirm, log, getDateTime, show, hide, toggle, addClass, removeClass, toggleClass, scrollTo, scrollToTop, scrollToBottom, scrollToElement, submitForm, resetForm, getValue, clearInput, saveToLocal, loadFromLocal, removeFromLocal, clearLocalStorage, copyToClipboard, copyElementText, focus, blur, setText, setTimeout, getInputValue, switch
+from dars.scripts.utils_ds import onViewport, classOnView, runOnView, animateOnView, staggerOnView, scrollProgress, animate, timeline, stagger  # Viewport & Scroll Animation Utilities
 from dars.scripts.animations import fadeIn, fadeOut, slideIn, slideOut, scaleIn, scaleOut, shake, bounce, pulse, rotate, flip, colorChange, morphSize, popIn, popOut, sequence  # Animation System
 from dars.scripts.script import *
 # Hooks
@@ -128,8 +129,7 @@ __all__ = [
     # Storage utilities
     'saveToLocal', 'loadFromLocal', 'removeFromLocal', 'clearLocalStorage',
     # Clipboard utilities
-    'copyToClipboard', 'copyElementText',
-    # Focus utilities
+    'copyToClipboard', 'copyElementText',    # Focus utilities
     'focus', 'blur',
     # Timer utilities
     'setTimeout',
@@ -137,6 +137,9 @@ __all__ = [
     'fadeIn', 'fadeOut', 'slideIn', 'slideOut', 'scaleIn', 'scaleOut',
     'shake', 'bounce', 'pulse', 'rotate', 'flip',
     'colorChange', 'morphSize', 'popIn', 'popOut', 'sequence',
+    # Viewport & Scroll Animation Engine
+    'onViewport', 'classOnView', 'runOnView', 'animateOnView',
+    'staggerOnView', 'scrollProgress', 'animate', 'timeline', 'stagger',
     # Input utilities
     'getInputValue',
     # Hooks

{dars_framework-1.9.2 → dars_framework-1.9.5}/dars/cli/main.py

@@ -1206,6 +1206,7 @@ def create_parser(include_hidden: bool = True) -> argparse.ArgumentParser:
     # Dev command (run entry in dev mode)
     dev_parser = subparsers.add_parser('dev', help='Run the configured entry file in development mode')
     dev_parser.add_argument('--project', '-p', default='.', help='Project root where dars.config.json resides (default: .)')
+    dev_parser.add_argument('--port', '-P', type=int, help='Port to run the dev server on (overrides config)')
     dev_parser.add_argument('--backend', action='store_true', help='Run only the configured backendEntry (SSR/API) instead of the frontend entry')
     # English-only: no language option on subparsers
     
@@ -2296,7 +2297,16 @@ def main():
         # Backend/SSR server can be started in a separate terminal with `dars dev --backend` if needed.
         process = None
         try:
-            process = subprocess.Popen([sys.executable, entry], cwd=os.path.dirname(entry))
+            cmd = [sys.executable, entry]
+            # Prioritize CLI arg, then config, then fallback to 8000
+            port_to_pass = getattr(args, 'port', None)
+            if port_to_pass is None and found and "port" in cfg:
+                port_to_pass = cfg["port"]
+            
+            if port_to_pass:
+                cmd.extend(['--port', str(port_to_pass)])
+            
+            process = subprocess.Popen(cmd, cwd=os.path.dirname(entry))
             process.wait()
             sys.exit(process.returncode or 0)
         except KeyboardInterrupt:

{dars_framework-1.9.2 → dars_framework-1.9.5}/dars/components/basic/markdown.py

@@ -18,12 +18,14 @@ class Markdown(Component):
     - **Events**: Handlers like `on_click`, `on_mouse_enter`, etc.
     
     Example:
+
     ```python
     Markdown(
         content="# Hello Dars\nThis is **markdown** content.",
         class_name="p-6 bg-white rounded-xl shadow-sm border border-slate-200"
     )
     ```
+    
     """
     def __init__(
         self,

{dars_framework-1.9.2 → dars_framework-1.9.5}/dars/components/basic/page.py

@@ -39,6 +39,73 @@ class Page(Component):
             self.add_child(child)
 
     def add_script(self, script):
+        """
+        Adds a script to this page.
+        
+        Supports multiple script types:
+        
+        - **DScript**: Direct Python function compilation to JavaScript
+        - **String**: Inline JavaScript code
+        - **Dictionary**: Raw script object (fallback)
+        - **Utility Chains**: DAP utility functions with promise-based chaining
+        
+        **Script Types:**
+        
+        1. **DScript** - Compile Python to JavaScript:
+           ```python
+           page.add_script(dScript(file_path="script.js"))
+           ```
+        
+        2. **Inline JavaScript**:
+           ```python
+           page.add_script("console.log('Page loaded');")
+           ```
+        
+        3. **Utility Functions** - Chain DAP commands:
+           ```python
+           from dars.scripts.utils_ds import setTimeout, addClass, log
+           
+           # Sequential animations with promise chaining
+           page.add_script(
+               setTimeout(5, addClass("logo", "show"))
+               .then(setTimeout(350, addClass("title", "show")))
+               .then(setTimeout(650, addClass("description", "show")))
+           )
+           ```
+        
+        4. **useWatch** - React to state changes:
+           ```python
+           page.add_script(
+               useWatch("user.name", log("Name changed!"))
+           )
+           ```
+        
+        **Common Utilities:**
+        
+        - **setTimeout(ms, action)**: Execute action after delay (returns Promise)
+        - **addClass(id, class)**: Add CSS class to element
+        - **removeClass(id, class)**: Remove CSS class
+        - **toggleClass(id, class)**: Toggle CSS class
+        - **log(msg)**: Log to console
+        - **navigate(url)**: Navigate to URL
+        - **createComp(target, root)**: Dynamically create components
+        - **updateComp(id, props)**: Update component properties
+        - **deleteComp(id)**: Remove component from DOM
+        
+        **Promise Chaining:**
+        
+        All timeout/async utilities return Promises, allowing sequential execution:
+        
+        ```python
+        page.add_script(
+            setTimeout(100, log("Step 1"))
+            .then(setTimeout(200, log("Step 2")))
+            .then(setTimeout(300, log("Step 3")))
+        )
+        ```
+        
+        Returns self to allow method chaining.
+        """
         self.scripts.append(script)
 
     def useWatch(self, state_path: str, *js_helpers):

{dars_framework-1.9.2 → dars_framework-1.9.5}/dars/config.py

@@ -22,6 +22,7 @@ DEFAULT_CONFIG = {
     "markdownHighlight": True,
     "markdownHighlightTheme": "auto",
     "targetPlatform": "auto",  # Desktop-only option: platform target for Electron build (auto|windows|linux|macos)
+    "port": 8000,
     # Optional: backend entry for SSR projects (module or file path). Disabled by default.
     "backendEntry": None,
     # Optional: custom utility styles map consumed by register_custom_utilities