dars-framework 1.2.3__py3-none-any.whl

dars/docs/custom_components.md

@@ -0,0 +1,30 @@
+This is an example of how to create a custom component in Dars. The `Button` class inherits from `Component` and defines its own initialization and rendering logic. You can use `self.set_event` to attach event handlers to components.
+
+> Note: when you instance a CustomComponent you need to do it like this CustomComponent(id="") <-- with parentesis
+
+```python
+from dars.all import *
+from dars.core.component import Component
+from dars.exporters.web.html_css_js import *
+
+class CustomComponent(Component):
+    def __init__(self, title: str, id: str = None, **props):
+        super().__init__(**props)
+        
+        self.title = title
+        self.id = id
+        self.set_event(EventTypes.CLICK, dScript("console.log('click')"))
+    def render(self, exporter: 'Exporter') -> str:
+        # Use the exporter to consistently render children
+        children_html = self.render_children(exporter)
+        return f'''
+        <div class="my-component" id="{self.id}">
+            <h2>{self.title}</h2>
+            <div class="content">
+                {children_html}
+            </div>
+        </div>
+        '''
+```
+
+

dars/docs/events.md

@@ -0,0 +1,45 @@
+## Event Calling System
+
+Custom components in Dars can have events associated with them. You can set an event on a custom component using the `set_event` method.
+
+```python
+self.set_event(EventTypes.CLICK, dScript("console.log('click')"))
+```
+
+### Available Event Types
+
+To use the event types, you need to import them from `dars.core.events`:
+
+```python
+from dars.core.events import EventTypes
+```
+
+Here are the different event types available:
+
+- **Mouse Events:**
+    - `CLICK = "click"`
+    - `DOUBLE_CLICK = "dblclick"`
+    - `MOUSE_DOWN = "mousedown"`
+    - `MOUSE_UP = "mouseup"`
+    - `MOUSE_ENTER = "mouseenter"`
+    - `MOUSE_LEAVE = "mouseleave"`
+    - `MOUSE_MOVE = "mousemove"`
+
+- **Keyboard Events:**
+    - `KEY_DOWN = "keydown"`
+    - `KEY_UP = "keyup"`
+    - `KEY_PRESS = "keypress"`
+
+- **Form Events:**
+    - `CHANGE = "change"`
+    - `INPUT = "input"`
+    - `SUBMIT = "submit"`
+    - `FOCUS = "focus"`
+    - `BLUR = "blur"`
+
+- **Load Events:**
+    - `LOAD = "load"`
+    - `ERROR = "error"`
+    - `RESIZE = "resize"`
+
+

dars/docs/exporters.md

@@ -0,0 +1,162 @@
+# Dars - Exporter Documentation
+
+## Introduction
+
+Exporters are the heart of Dars that allow transforming applications written in Python to different technologies and platforms. Each exporter translates Dars components, styles, and scripts to the native code of the target platform.
+
+## Exporter Architecture
+
+### Base Exporter Class
+
+All exporters inherit from the base `Exporter` class:
+
+```python
+from abc import ABC, abstractmethod
+
+class Exporter(ABC):
+    def __init__(self):
+        self.templates_path = "templates/"
+        
+    @abstractmethod
+    def export(self, app: App, output_path: str) -> bool:
+        """Exports the application to the specific format"""
+        pass
+        
+    @abstractmethod
+    def render_component(self, component: Component) -> str:
+        """Renders an individual component"""
+        pass
+        
+    @abstractmethod
+    def get_platform(self) -> str:
+        """Returns the name of the platform"""
+        pass
+```
+
+### Exportation Flow
+
+1. **Validation**: Verify that the application is valid
+2. **Preparation**: Create directory structure
+3. **Rendering**: Convert components to the target format
+4. **Generation**: Create configuration and dependency files
+5. **Finalization**: Write files to the system
+
+## Web Exporters
+
+### HTML/CSS/JavaScript
+
+The HTML exporter generates standard web applications that can run in any browser.
+
+#### Features
+
+- **Compatibility**: Works in all modern browsers
+- **Simplicity**: No requires build tools
+- **Performance**: Fast loading and efficient execution
+- **SEO**: Content indexable by search engines
+
+#### Usage
+
+```bash
+dars export my_app.py --format html --output ./dist
+```
+
+By default, the `dars export` command generates a production bundle (no hot-reload). See Bundling vs Dev Preview below.
+
+#### Generated Structure
+
+```
+dist/
+├── index.html      # Main page
+├── styles.css      # CSS styles
+├── script.js       # JavaScript logic
+└── runtime_dars.js # Dars runtime
+```
+
+#### Example Output
+
+**index.html**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>My Application</title>
+    <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+    <div id="container_123" class="dars-container" style="display: flex; flex-direction: column; padding: 20px;">
+        <span id="text_456" class="dars-text" style="font-size: 24px; color: #333;">Hello Dars!</span>
+        <button id="button_789" class="dars-button" style="background-color: #007bff; color: white;">Click</button>
+    </div>
+    <script src="script.js"></script>
+    <script src="runtime_dars.js"></script>
+</body>
+</html>
+```
+
+**styles.css**
+```css
+/* Base Dars styles */
+* {
+    box-sizing: border-box;
+}
+
+body {
+    margin: 0;
+    padding: 0;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
+}
+
+.dars-button {
+    display: inline-block;
+    padding: 8px 16px;
+    border: 1px solid #ccc;
+    background-color: #f8f9fa;
+    color: #333;
+    cursor: pointer;
+    border-radius: 4px;
+    font-size: 14px;
+}
+
+.dars-button:hover {
+    background-color: #e9ecef;
+}
+```
+
+#### Advantages
+
+- **Universality**: Works in any web server
+- **Debugging**: Easy to debug with browser tools
+- **Personalization**: CSS and JavaScript completely modifiable
+- **Hosting**: Can be hosted on any static hosting service
+
+#### Use Cases
+
+- Corporate websites
+- Landing pages
+- Simple web applications
+- Quick prototypes
+- Interactive documentation
+
+## Exporter Personalization
+
+### Extending Existing Exporters
+
+```python
+from dars.exporters.base import Exporter
+
+class MyCustomExporter(Exporter):
+    def get_platform(self):
+        return "my_custom_platform"
+    
+    def export(self, app, output_path):
+        # Implement custom export logic
+        return True
+    
+    def render_component(self, component):
+        # Implement custom component rendering
+        return "generated_code"
+```
+
+

dars/docs/getting_started.md

@@ -0,0 +1,79 @@
+The documentstion of dars is moving to the documentation official website please visit https://ztamdev.github.io/Dars-Framework/documentation.html because this documents will be deprecated in some time...
+# Getting Started with Dars
+
+Welcome to Dars, a modern Python framework for building web applications with reusable UI components.
+
+## Quick Start
+
+1. **Install Dars**  
+   See [INSTALL.md](../../INSTALL.md) for installation instructions.
+
+2. **Project Structure**  
+   Learn about the framework internal project layout in [STRUCTURE.md](../../STRUCTURE.md).
+
+3. **Explore Components**  
+   Discover all available UI components in [components.md](components.md).
+
+4. **Command-Line Usage**  
+   Find CLI commands, options, and workflows in [cli.md](cli.md).
+
+5. **App Class**
+   Learn how to create an app class in [App Documentation](app.md).
+
+6. **Component Search and Modification**
+   All components in Dars now support a powerful search and modification system:
+
+      ```python
+   from dars.all import *
+
+   app = App(title="Search Demo")
+
+   # Create a page with nested components
+   page = Page(
+       Container(
+           Text(text="Welcome!", id="welcome-text"),
+           Container(
+               Button(text="Click me", class_name="action-btn"),
+               Button(text="Cancel", class_name="action-btn"),
+               id="buttons-container"
+           ),
+           id="main-container"
+       )
+   )
+
+   # Find and modify components
+   page.find(id="welcome-text")\
+       .attr(text="Welcome to Dars!", style={"color": "blue"})
+
+   # Chain searches to find nested components
+   page.find(id="buttons-container")\
+       .find(class_name="action-btn")\
+       .attr(style={"padding": "10px"})
+
+   app.add_page(name="main", root=page)
+   ```
+
+7.  **Adding Custom File Types**
+
+```python
+app.rTimeCompile().add_file_types = ".js,.css"
+```
+
+* Include any extension your project uses beyond default Python files.
+
+## Need More Help?
+
+### Project Structure  
+   Learn about the recommended project layout in [STRUCTURE.md](../../STRUCTURE.md).
+
+### Explore Components  
+   Discover all available UI components in [components.md](components.md).
+
+### Command-Line Usage  
+   Find CLI commands, options, and workflows in [cli.md](cli.md).
+
+### Need More Help?
+- For advanced topics, see the full documentation and examples in the referenced files above.
+- If you have questions or need support, check the official repository or community channels.
+
+Start building with Dars...

dars/docs/index.md

@@ -0,0 +1,18 @@
+# Dars Framework Documentation
+
+The documentstion of dars is moving to the documentation official website please visit https://ztamdev.github.io/Dars-Framework/documentation.html because this documents will be deprecated in some time...
+
+Welcome to the official Dars Framework documentation. Here you will find detailed guides and references to help you build modern web applications with Python.
+
+## Main Guides
+
+- [Getting Started with Dars](getting_started.md)
+- [App class](app.md)
+- [Components](components.md)
+- [Custom Components](custom_components.md)
+- [Event Handling](events.md)
+- [Exporters](exporters.md)
+- [Scripts System](scripts.md)
+- [CLI Usage and Commands](cli.md)
+
+