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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dars-framework
-Version: 1.9.0
+Version: 1.9.2
 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>

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/advanced/accordion.py

@@ -3,9 +3,28 @@ from typing import List, Optional
 
 class Accordion(Component):
     """
-    Accordion component to display collapsible sections.
-    sections: List of tuples (title, content)
-    open_indices: List of open indices (optional)
+    Accordion component for displaying collapsible content sections.
+    
+    Props:
+    - **sections** (list): List of tuples containing `(title, content)`.
+    - **open_indices** (list): Optional list of indices that should be open by default.
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers like `on_click`, etc.
+    
+    Example:
+    ```python
+    Accordion(
+        sections=[
+            ("Section 1", Text("Content for section 1")),
+            ("Section 2", Text("Content for section 2")),
+        ],
+        open_indices=[0],
+        class_name="bg-white shadow-sm"
+    )
+    ```
     """
 
     def __init__(self, sections: List[tuple], open_indices: Optional[List[int]]=None, minimum_logic: bool = True, **props):

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/advanced/card.py

@@ -2,7 +2,26 @@ from dars.core.component import Component
 from typing import Optional, Dict, Any, List
 
 class Card(Component):
-    """Component to display content in a card."""
+    """
+    Card component for grouping related information in a visually distinct container.
+    
+    Props:
+    - **children** (list): List of child components to render inside the card.
+    - **title** (str): Optional title displayed at the top of the card.
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **Events**: Handlers like `on_click`, `on_mouse_enter`, etc.
+    
+    Example:
+    ```python
+    Card(
+        Text("Card content goes here..."),
+        title="Featured Post",
+        class_name="max-w-sm border border-slate-100 bg-gradient-to-br from-white to-slate-50"
+    )
+    ```
+    """
     def __init__(
         self,
         children: Optional[List[Component]] = None,

dars_framework-1.9.2/dars/components/advanced/file_upload.py

@@ -0,0 +1,59 @@
+
+from dars.core.component import Component
+from dars.core.events import EventTypes
+from typing import Optional, Dict, Any, Callable, Union
+
+class FileUpload(Component):
+    """
+    Component for selecting and uploading files with support for filters and size limits.
+    
+    Props:
+    - **accept** (str): Allowed file types (e.g., `"image/*"`, `".pdf"`, `"audio/*"`).
+    - **multiple** (bool): If True, allows selecting multiple files.
+    - **disabled** (bool): If True, the component is not interactive.
+    - **required** (bool): If True, a file must be selected.
+    - **max_size** (int): Maximum file size allowed in bytes.
+    - **label** (str): Text label for the upload button (defaults to "Choose File").
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers like `on_change` (triggered when files are selected).
+    
+    Example:
+    ```python
+    FileUpload(
+        accept="image/*",
+        multiple=True,
+        label="Upload Images",
+        class_name="bg-indigo-600 text-white px-6 py-3 rounded-full cursor-pointer hover:bg-indigo-700 transition-all shadow-lg"
+    )
+    ```
+    """
+    def __init__(
+        self,
+        accept: Optional[str] = None,
+        multiple: bool = False,
+        disabled: bool = False,
+        required: bool = False,
+        max_size: Optional[int] = None,  # In bytes
+        id: Optional[str] = None,
+        class_name: Optional[str] = None,
+        style: Optional[Dict[str, Any]] = None,
+        on_change: Optional[Callable] = None,
+        label: Optional[str] = "Choose File",
+        **props
+    ):
+        super().__init__(id=id, class_name=class_name, style=style, **props)
+        self.accept = accept
+        self.multiple = multiple
+        self.disabled = disabled
+        self.required = required
+        self.max_size = max_size
+        self.label = label
+        
+        if on_change:
+            self.set_event(EventTypes.CHANGE, on_change)
+
+    def render(self, exporter: Any) -> str:
+        raise NotImplementedError("render method must be implemented by exporter")

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/advanced/head.py

@@ -12,44 +12,37 @@ from dars.core.component import Component
 
 class Head(Component):
     """
-    Define SEO metadata for a page. This component does not render visible content.
+    Component for managing document metadata in the HTML `<head>` section, essential for SEO and social sharing.
     
-    The Head component allows you to customize HTML <head> metadata on a per-page basis,
-    which is essential for SEO, social sharing, and proper page indexing.
-    
-    Features:
-    - Basic SEO (title, description, keywords, author)
-    - Open Graph tags for social sharing (Facebook, LinkedIn)
-    - Twitter Card tags
-    - Canonical URLs
-    - Robots directives
-    - Custom meta and link tags
-    - JSON-LD structured data
-    - Per-page favicon override
+    Props:
+    - **title** (str): Page title displayed in the browser tab.
+    - **description** (str): Meta description for search engines.
+    - **keywords** (list): List of keywords for indexing.
+    - **author** (str): Metadata for the page author.
+    - **robots** (str): Robots directive (e.g., `"index, follow"`, `"noindex, nofollow"`).
+    - **canonical** (str): Canonical URL for the page to avoid duplicate content.
+    - **favicon** (str): URL to override the site-wide favicon.
+    - **og_*** (str): Open Graph metadata for social media sharing (title, description, image, etc.).
+    - **twitter_*** (str): Twitter Card metadata.
+    - **meta** (list): List of dictionaries for custom `<meta>` tags.
+    - **links** (list): List of dictionaries for custom `<link>` tags.
+    - **structured_data** (dict): JSON-LD dictionary for structured data.
+    - **id** (str): Unique identifier for the component (not rendered).
+    - **class_name** (str): String containing regular CSS class names (not rendered).
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`) (not rendered).
+    - **children** (list): List of child components (not rendered).
+    - **Events**: Handlers (not typical for Head).
     
     Example:
-        ```python
-        from dars.all import *
-        
-        @route("/blog/post", route_type=RouteType.SSR)
-        def blog_post():
-            return Page(
-                Head(
-                    title="My Blog Post - My Site",
-                    description="An amazing blog post about Python",
-                    keywords=["python", "web", "framework"],
-                    og_image="https://example.com/image.jpg",
-                    og_type="article"
-                ),
-                Heading("My Blog Post", level=1),
-                Text("Content here...")
-            )
-        ```
-    
-    Note:
-        - This component does NOT handle CSS or JavaScript (handled by exporter)
-        - It only manages metadata in the HTML <head> section
-        - Multiple Head components: last one wins (or merge strategy)
+    ```python
+    Head(
+        title="Dars Framework - Python Web Development",
+        description="Build premium web applications with Python and modern design.",
+        og_image="https://dars.dev/og-image.png",
+        twitter_card="summary_large_image",
+        keywords=["python", "framework", "web", "frontend"]
+    )
+    ```
     """
     
     def __init__(

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/advanced/modal.py

@@ -2,7 +2,28 @@ from dars.core.component import Component
 from typing import Optional, Dict, Any, List
 
 class Modal(Component):
-    """Component to display content in a modal."""
+    """
+    Dialog component that appears on top of the main content, used for important actions or information.
+    
+    Props:
+    - **children** (list): List of child components to be displayed inside the modal content area.
+    - **title** (str): Optional title displayed in the modal header.
+    - **is_open** (bool): Whether the modal is currently visible (defaults to False).
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names for the modal overlay.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **Events**: Handlers like `on_click` (can be used to close the modal by clicking the backdrop).
+    
+    Example:
+    ```python
+    Modal(
+        Text("Your changes have been saved successfully."),
+        title="Success",
+        is_open=True,
+        class_name="bg-white rounded-3xl shadow-2xl p-10 max-w-lg"
+    )
+    ```
+    """
     def __init__(
         self,
         children: Optional[List[Component]] = None,

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/advanced/navbar.py

@@ -2,7 +2,28 @@ from dars.core.component import Component
 from typing import Optional, Dict, Any, List
 
 class Navbar(Component):
-    """Component to create navigation bars."""
+    """
+    Navigation bar component for page headers, supporting branding and navigation links.
+    
+    Props:
+    - ***children** (Component): Positional arguments for navigation links or other components.
+    - **brand** (str): Text or logo component for the site branding area.
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers like `on_click`, `on_mouse_enter`, etc.
+    
+    Example:
+    ```python
+    Navbar(
+        Link("Home", href="/", class_name="px-4 py-2 hover:text-indigo-600"),
+        Link("Services", href="/services", class_name="px-4 py-2 hover:text-indigo-600"),
+        brand="Dars Framework",
+        class_name="px-8 py-4 shadow-sm flex items-center justify-between"
+    )
+    ```
+    """
     def __init__(
         self,
         *children,

dars_framework-1.9.2/dars/components/advanced/outlet.py

@@ -0,0 +1,43 @@
+from dars.components.basic.container import Container
+
+class Outlet(Container):
+    """
+    Routing placeholder component for Single Page Applications (SPA).
+    Acts as the target where child routes will be dynamically rendered based on the URL.
+    
+    Props:
+    - **outlet_id** (str): Unique identifier for the outlet (defaults to `"main"`).
+    - **placeholder** (Component): Component to display while the route content is being loaded.
+    - ***children** (Component): Initial content for the outlet if no route is matched.
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **Events**: Handlers for navigation and lifecycle events.
+    
+    Example:
+    ```python
+    Outlet(
+        outlet_id="main-view",
+        placeholder=Spinner(class_name="m-auto"),
+        class_name="w-full h-full"
+    )
+    ```
+    """
+    def __init__(self, outlet_id: str = "main", placeholder=None, *children, **props):
+        if placeholder is None and ('loading' in props):
+            placeholder = props.pop('loading')
+
+        if (not children) and (placeholder is not None):
+            if isinstance(placeholder, list):
+                children = tuple(placeholder)
+            else:
+                children = (placeholder,)
+
+        super().__init__(*children, **props)
+        self.props["data-dars-outlet"] = "true"
+        try:
+            self.props["data-dars-outlet-id"] = str(outlet_id or "main")
+        except Exception:
+            self.props["data-dars-outlet-id"] = "main"
+        base_cls = (getattr(self, "class_name", "") or "").strip()
+        self.class_name = ("dars-outlet " + base_cls).strip()

dars_framework-1.9.2/dars/components/advanced/table.py

@@ -0,0 +1,48 @@
+from dars.core.component import Component
+from typing import List, Dict, Any, Optional
+
+class Table(Component):
+    """
+    Component for displaying structured data in a tabular format with support for sorting and pagination.
+    
+    Props:
+    - **columns** (list): List of dictionaries defining columns (e.g., `[{"title": "Name", "field": "name", "sortable": True}]`).
+    - **data** (list): List of row dictionaries where keys match the `field` defined in `columns`.
+    - **page_size** (int): Number of rows to display per page (optional).
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers for sorting, filtering, and row clicks.
+    
+    Example:
+    ```python
+    Table(
+        columns=[
+            {"title": "User", "field": "user"},
+            {"title": "Status", "field": "status"}
+        ],
+        data=[
+            {"user": "John Doe", "status": "Active"},
+            {"user": "Jane Smith", "status": "Pending"}
+        ],
+        page_size=10,
+        class_name="min-w-full divide-y divide-slate-200 shadow-sm rounded-lg overflow-hidden"
+    )
+    ```
+    """
+
+    def __init__(self, columns: List[Dict[str, Any]], data: List[Dict[str, Any]], page_size: Optional[int]=None, **props):
+        super().__init__(**props)
+        self.columns = columns
+        self.data = data
+        self.page_size = page_size
+
+    def render(self) -> str:
+        # Renderiza la tabla en HTML (solo vista simple, sin JS avanzado todavía)
+        thead = '<thead><tr>' + ''.join(f'<th>{col["title"]}</th>' for col in self.columns) + '</tr></thead>'
+        rows = self.data[:self.page_size] if self.page_size else self.data
+        tbody = '<tbody>' + ''.join(
+            '<tr>' + ''.join(f'<td>{row.get(col["field"], "")}</td>' for col in self.columns) + '</tr>'
+            for row in rows) + '</tbody>'
+        return f'<table class="dars-table">{thead}{tbody}</table>'

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/advanced/tabs.py

@@ -3,10 +3,31 @@ from typing import List, Optional
 
 class Tabs(Component):
     """
-    Tab navigation component.
-    tabs: List of tab titles
-    panels: List of components or strings (content of each tab)
-    selected: Index of the active tab (optional)
+    Tabbed navigation component for switching between multiple content panels in the same space.
+    
+    Props:
+    - **tabs** (list): List of strings for the tab headers.
+    - **panels** (list): List of components or strings representing the content of each tab.
+    - **selected** (int): Index of the initially active tab (defaults to 0).
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers like `on_change` when the active tab is switched.
+    
+    Example:
+    ```python
+    Tabs(
+        tabs=["General", "Security", "Notifications"],
+        panels=[
+            Container(Text("General settings...")),
+            Container(Text("Security settings...")),
+            Container(Text("Notification settings..."))
+        ],
+        selected=0,
+        class_name="bg-white rounded-xl shadow-sm border border-slate-100"
+    )
+    ```
     """
 
     def __init__(self, tabs: List[str], panels: List[Component], selected: Optional[int]=0, minimum_logic: bool = True, **props):

dars_framework-1.9.2/dars/components/basic/audio.py

@@ -0,0 +1,56 @@
+from typing import Optional, Dict, Any
+
+from dars.core.component import Component
+
+
+class Audio(Component):
+    """
+    Advanced HTML5 audio component for playing sound files.
+    
+    Props:
+    - **src** (str): URL or path to the audio source.
+    - **controls** (bool): Whether to display audio controls (play/pause, volume, etc.).
+    - **autoplay** (bool): If True, the audio will start playing automatically.
+    - **loop** (bool): If True, the audio will play in a loop.
+    - **muted** (bool): If True, the audio will be muted by default.
+    - **preload** (str): Strategy for preloading ('auto', 'metadata', 'none').
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers like `on_play`, `on_pause`, `on_ended`, etc.
+    
+    Example:
+    ```python
+    Audio(
+        src="https://example.com/podcast.mp3",
+        controls=True,
+        class_name="w-full max-w-md"
+    )
+    ```
+    """
+
+    def __init__(
+        self,
+        src: str,
+        controls: bool = True,
+        autoplay: bool = False,
+        loop: bool = False,
+        muted: bool = False,
+        preload: Optional[str] = None,
+        class_name: Optional[str] = None,
+        style: Optional[Dict[str, Any]] = None,
+        attrs: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(class_name=class_name, style=style, **kwargs)
+        self.src = src
+        self.controls = controls
+        self.autoplay = autoplay
+        self.loop = loop
+        self.muted = muted
+        self.preload = preload
+        self.extra_attrs = attrs or {}
+
+    def render(self) -> str:
+        raise NotImplementedError("El método render debe ser implementado por el exportador")

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/basic/button.py

@@ -5,6 +5,28 @@ from dars.scripts.script import Script
 from typing import Optional, Union, Dict, Any, Callable
 
 class Button(Component):
+    """
+    Interactive button component that triggers actions when clicked.
+    
+    Props:
+    - **text** (str): The label text displayed on the button.
+    - **disabled** (bool): Whether the button is interactive or not.
+    - **button_type** (str): HTML type of the button ('button', 'submit', 'reset').
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components to render inside the button.
+    - **Events**: Handlers like `on_click`, `on_double_click`, `on_mouse_enter`, `on_mouse_leave`, `on_mouse_down`, `on_mouse_up`, `on_key_down`, `on_key_up`.
+    
+    Example:
+    ```python
+    Button(
+        text="Click me!",
+        class_name="bg-indigo-600 text-white px-4 py-2 rounded shadow-md hover:shadow-lg transition-all",
+        on_click=lambda: print("Button clicked!")
+    )
+    ```
+    """
     def __init__(
         self, 
         text: str = "Button", 

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/basic/checkbox.py

@@ -4,6 +4,31 @@ from dars.core.events import EventTypes
 from typing import Optional, Union, Dict, Any, Callable
 
 class Checkbox(Component):
+    """
+    Interactive checkbox component for boolean input.
+    
+    Props:
+    - **label** (str): Text label to display next to the checkbox.
+    - **checked** (bool): Current state of the checkbox.
+    - **value** (str): Value associated with the checkbox.
+    - **name** (str): Name attribute for form submission.
+    - **disabled** (bool): If True, the checkbox is not interactive.
+    - **required** (bool): If True, the checkbox must be checked.
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers like `on_change`, `on_click`, etc.
+    
+    Example:
+    ```python
+    Checkbox(
+        label="Accept terms and conditions",
+        on_change=lambda val: print(f"Checked: {val}"),
+        class_name="text-slate-700 font-medium cursor-pointer"
+    )
+    ```
+    """
     def __init__(
         self,
         label: str = "",

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/basic/container.py

@@ -3,6 +3,26 @@ from dars.core.properties import StyleProps
 from typing import Optional, Union, Dict, Any, List
 
 class Container(Component):
+    """
+    Versatile container component (div) to wrap and organize other components.
+    
+    Props:
+    - ***children** (Component): Positional arguments for child components.
+    - **additional_children** (list): Optional list of additional child components.
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **Events**: Handlers like `on_click`, `on_mouse_enter`, etc.
+    
+    Example:
+    ```python
+    Container(
+        Text("Title"),
+        Button("Click me"),
+        class_name="flex flex-col gap-4 p-6 bg-slate-50 rounded-2xl"
+    )
+    ```
+    """
     def __init__(
         self,
         *children: Component,

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/basic/datepicker.py

@@ -5,6 +5,38 @@ from typing import Optional, Union, Dict, Any, Callable
 from datetime import datetime, date
 
 class DatePicker(Component):
+    """
+    Advanced date and time picker component for selecting dates with custom formats.
+    
+    Props:
+    - **value** (str/date/datetime): Initial date value.
+    - **min_date** (str/date/datetime): Minimum selectable date.
+    - **max_date** (str/date/datetime): Maximum selectable date.
+    - **placeholder** (str): Hint text when no date is selected.
+    - **format** (str): Date format (e.g., `"YYYY-MM-DD"`, `"DD/MM/YYYY"`, `"MM/DD/YYYY"`, `"DD-MM-YYYY"`).
+    - **locale** (str): Language for the picker (e.g., `"es"`, `"en"`, `"fr"`, `"de"`, `"it"`, `"pt"`).
+    - **show_time** (bool): Whether to include a time selector.
+    - **inline** (bool): If True, shows the picker inline instead of a popup.
+    - **disabled_dates** (list): List of dates to be disabled.
+    - **disabled** (bool): If True, the component is not interactive.
+    - **required** (bool): If True, a date must be selected.
+    - **readonly** (bool): If True, the field is read-only.
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers like `on_change`, `on_open`, `on_close`.
+    
+    Example:
+    ```python
+    DatePicker(
+        placeholder="Select your birthday",
+        format="DD/MM/YYYY",
+        locale="es",
+        class_name="border p-2 rounded shadow-sm focus:ring-2 focus:ring-indigo-500"
+    )
+    ```
+    """
     def __init__(
         self,
         value: Optional[Union[str, date, datetime]] = None,

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/basic/image.py

@@ -2,7 +2,29 @@ from dars.core.component import Component
 from typing import Optional, Dict, Any
 
 class Image(Component):
-    """Component to display images."""
+    """
+    Component for displaying images with support for dimensions and styling.
+    
+    Props:
+    - **src** (str): URL or path to the image source.
+    - **alt** (str): Alternative text for accessibility.
+    - **width** (str): Width of the image (e.g., `"100px"`, `"50%"`).
+    - **height** (str): Height of the image.
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers like `on_click`, `on_load`, etc.
+    
+    Example:
+    ```python
+    Image(
+        src="https://example.com/logo.png",
+        alt="Dars Logo",
+        class_name="w-32 h-32 rounded-xl"
+    )
+    ```
+    """
     def __init__(
         self,
         src: str,

{dars_framework-1.9.0 → dars_framework-1.9.2}/dars/components/basic/input.py

@@ -4,6 +4,32 @@ from dars.core.events import EventTypes
 from typing import Optional, Union, Dict, Any, Callable
 
 class Input(Component):
+    """
+    Interactive input field for user data entry.
+    
+    Props:
+    - **value** (str): Current value of the input.
+    - **placeholder** (str): Hint text displayed when empty.
+    - **input_type** (str): HTML input type (e.g., `"text"`, `"password"`, `"email"`, `"number"`).
+    - **disabled** (bool): If True, the input is not interactive.
+    - **readonly** (bool): If True, the value cannot be modified.
+    - **required** (bool): If True, the field must be filled.
+    - **max_length** (int): Maximum number of characters allowed.
+    - **id** (str): Unique identifier for the component.
+    - **class_name** (str): String containing regular CSS class names.
+    - **style** (dict): Optional dictionary for CSS utility classes (prefer `style`).
+    - **children** (list): List of child components.
+    - **Events**: Handlers like `on_change`, `on_input`, `on_focus`, `on_blur`, `on_key_down`, `on_key_up`.
+    
+    Example:
+    ```python
+    Input(
+        placeholder="Enter your email...",
+        input_type="email",
+        class_name="w-full px-4 py-2 border rounded-lg focus:ring-2 focus:ring-indigo-500 outline-none"
+    )
+    ```
+    """
     def __init__(
         self, 
         value: str = "",