dara-components 1.8.5__py3-none-any.whl → 1.22.1__py3-none-any.whl

dara/components/common/checkbox_group.py

@@ -15,14 +15,14 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Any, List, Optional, Union
+from typing import Any
 
-from pydantic import validator
+from pydantic import field_validator
 
 from dara.components.common.base_component import FormComponent
 from dara.components.common.utils import Item
 from dara.core.base_definitions import Action
-from dara.core.interactivity import NonDataVariable, UrlVariable, Variable
+from dara.core.interactivity import ClientVariable, Variable
 
 
 class CheckboxGroup(FormComponent):
@@ -37,7 +37,7 @@ class CheckboxGroup(FormComponent):
 
     ```python
     from dara.core import Variable
-    from dara.components.common import CheckboxGroup
+    from dara.components import CheckboxGroup
 
 
     CheckboxGroup(
@@ -46,17 +46,26 @@ class CheckboxGroup(FormComponent):
     )
     ```
 
-    CheckboxGroup component with at most two values selectable at a time:
+    CheckboxGroup with items with custom labels and values:
 
     ```python
     from dara.core import Variable
-    from dara.components.common import CheckboxGroup
+    from dara.components import CheckboxGroup, Item
 
-    var_to_update = Variable()
+    CheckboxGroup(
+        items=[Item(label='first',value=1), Item(label='second',value=2)],
+        value=Variable([1]),
+    )
+    ```
+
+    CheckboxGroup component with at most two values selectable at a time:
+
+    ```python
+    from dara.core import Variable
+    from dara.components import CheckboxGroup
 
     CheckboxGroup(
         items=['first', 'second', 'third', 'fourth', 'fifth'],
-        onchange=var_to_update.sync(),
         value=Variable(),
         select_max=2,
     )
@@ -69,11 +78,9 @@ class CheckboxGroup(FormComponent):
     from dara.components.common import CheckboxGroup
 
     var = Variable()
-    var_to_update = Variable()
 
     CheckboxGroup(
         items=['first', 'second', 'third', 'fourth', 'fifth'],
-        onchange=var_to_update.sync(),
         value=var,
         select_min=2,
         list_styling=True,
@@ -90,18 +97,18 @@ class CheckboxGroup(FormComponent):
     :param id: the key to be used if this component is within a form
     """
 
-    items: Union[List[Item], NonDataVariable]
-    select_max: Optional[int] = None
-    select_min: Optional[int] = None
+    items: list[Item] | ClientVariable
+    select_max: int | None = None
+    select_min: int | None = None
     list_styling: bool = False
-    value: Optional[Union[Variable[Any], UrlVariable[Any]]] = None
-    onchange: Optional[Action] = None
-    id: Optional[str] = None
+    value: Variable[Any] | None = None
+    onchange: Action | None = None
+    id: str | None = None
 
-    @validator('items', pre=True)
+    @field_validator('items', mode='before')
     @classmethod
-    def validate_items(cls, items: Any) -> Union[List[Item], NonDataVariable]:
-        if isinstance(items, NonDataVariable):
+    def validate_items(cls, items: Any) -> list[Item] | ClientVariable:
+        if isinstance(items, ClientVariable):
             return items
         if not isinstance(items, list):
             raise ValueError('Items must be passed as a list to the CheckboxGroup component')

dara/components/common/code.py

@@ -16,10 +16,10 @@ limitations under the License.
 """
 
 from enum import Enum
-from typing import Optional, Union
+from typing import ClassVar
 
 from dara.components.common.base_component import ContentComponent
-from dara.core.interactivity import NonDataVariable
+from dara.core.interactivity import ClientVariable
 
 
 class Themes(str, Enum):
@@ -29,6 +29,9 @@ class Themes(str, Enum):
     DARK = 'dark'
 
 
+ThemesType = type[Themes]
+
+
 class Code(ContentComponent):
     """
     ![Code](../../../../docs/packages/dara-components/common/assets/Code.png)
@@ -64,8 +67,8 @@ class Code(ContentComponent):
     :param language: The language to use for code highlighting
     """
 
-    code: Union[str, NonDataVariable]
-    theme: Optional[Themes] = None
+    code: str | ClientVariable
+    theme: Themes | None = None
     language: str = 'python'
 
-    Themes = Themes
+    Themes: ClassVar[ThemesType] = Themes

dara/components/common/component_select_list.py

@@ -15,23 +15,19 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import List, Optional, Union
-
-from pydantic import BaseModel
-
 from dara.components.common.base_component import LayoutComponent
 from dara.core.base_definitions import Action
+from dara.core.base_definitions import DaraBaseModel as BaseModel
 from dara.core.definitions import ComponentInstanceType
 from dara.core.interactivity import Variable
 
 
 class ComponentItem(BaseModel):
     title: str
-    subtitle: Optional[str]
+    subtitle: str | None = None
     component: ComponentInstanceType
 
 
-# TODO: update docs with examples once component is fixed
 class ComponentSelectList(LayoutComponent):
     """
     ![ComponentSelectList](../../../../docs/packages/dara-components/common/assets/ComponentSelectList.png)
@@ -41,11 +37,11 @@ class ComponentSelectList(LayoutComponent):
      A ComponentSelectList can be created via:
      ```python
      from dara.core import Variable
-     from dara.components.common import (
+     from dara.components import (
          ComponentSelectList,
+         ComponentItem,
          Text,
      )
-     from dara.components.common.component_select_list.component_select_list import ComponentItem
 
     ComponentSelectList(
          items=[
@@ -64,8 +60,8 @@ class ComponentSelectList(LayoutComponent):
      :param selected_items: The initial selected items, can be an list if multiSelect is true otherwise a string. This takes the titles of the items as value.
     """
 
-    items: List[ComponentItem]
-    items_per_row: Optional[int] = None
-    multi_select: Optional[bool] = None
-    on_select: Optional[Action] = None
-    selected_items: Optional[Variable[Union[str, List[str]]]] = None
+    items: list[ComponentItem]
+    items_per_row: int | None = None
+    multi_select: bool | None = None
+    on_select: Action | None = None
+    selected_items: Variable[str | list[str]] | None = None

dara/components/common/datepicker.py

@@ -16,11 +16,11 @@ limitations under the License.
 """
 
 from datetime import datetime
-from typing import Any, Optional, Union
+from typing import Any
 
 from dara.components.common.base_component import FormComponent
 from dara.core.base_definitions import Action
-from dara.core.interactivity import UrlVariable, Variable
+from dara.core.interactivity import Variable
 
 
 class Datepicker(FormComponent):
@@ -37,48 +37,48 @@ class Datepicker(FormComponent):
     A single Datepicker component that tracks the chosen value is created via:
 
     ```python
-
     from dara.core import Variable
     from dara.components.common import Datepicker
 
+    date_var = Variable()
+
     Datepicker(
-        value=Variable()
+        value=date_var
     )
-
     ```
 
     A Datepicker component that allows to choose between a date range is created via:
 
     ```python
-
     from dara.core import Variable
     from dara.components.common import Datepicker
 
+    date_var = Variable()
+
     Datepicker(
-        value=Variable()
+        value=date_var,
         range=True,
     )
-
     ```
 
     A more complicated example with an initial date, has a custom
     format, and does not close on selection is created via:
 
     ```python
-
     from datetime import datetime
     from dara.core import Variable
     from dara.components.common import Datepicker
 
+    date_var = Variable(datetime(2021, 9, 18))
+
     Datepicker(
-        value=Variable(datetime(2021, 9, 18)),
+        value=date_var,
         date_format='MM/dd/yyyy',
         enable_time=True,
         max_date=datetime(2023, 12, 21),
         min_date=datetime(2020, 3, 20),
         select_close=False,
     ),
-
     ```
 
     :param value: A Variable with the initial date value
@@ -93,12 +93,12 @@ class Datepicker(FormComponent):
     :param id: the key to be used if this component is within a form
     """
 
-    value: Optional[Union[Variable[Any], UrlVariable[Any]]] = None
+    value: Variable[Any] | None = None
     date_format: str = 'dd/MM/yyyy'
     enable_time: bool = False
-    max_date: Optional[datetime] = None
-    min_date: Optional[datetime] = None
+    max_date: datetime | None = None
+    min_date: datetime | None = None
     range: bool = False
     select_close: bool = True
-    onchange: Optional[Action] = None
-    id: Optional[str] = None
+    onchange: Action | None = None
+    id: str | None = None

dara/components/common/dropdown_menu.py

@@ -0,0 +1,161 @@
+from typing import Any
+
+from typing_extensions import TypedDict
+
+from dara.components.common.base_component import BaseDashboardComponent
+from dara.components.common.button import Button
+from dara.core import Action, ClientVariable, ComponentInstance
+
+
+class MenuItem(TypedDict, total=False):
+    label: str | ComponentInstance
+    """the label of the menu item"""
+
+    icon: str | None
+    """optional icon to show next to the label, use get_icon() helper"""
+
+    style: dict[str, Any] | None
+    """optional style to apply to the menu item"""
+
+    prevent_close: bool | None
+    """optional flag to prevent the menu from closing when the item is clicked"""
+
+    before: ComponentInstance | None
+    """optional component to show before the label"""
+
+    after: ComponentInstance | None
+    """optional component to show after the label"""
+
+
+class DropdownMenu(BaseDashboardComponent):
+    """
+    A DropdownMenu component that displays a button which opens a dropdown menu with configurable menu items.
+    Menu items can be organized into sections and support icons, custom styling, and custom components.
+
+    A basic dropdown menu with simple text items:
+
+    ```python
+    from dara.core import action, ActionCtx
+    from dara.components import Button, DropdownMenu
+
+    @action
+    async def handle_menu_click(ctx: ActionCtx):
+        print(f"Clicked: {ctx.input['label']}")
+
+    DropdownMenu(
+        button=Button('Options'),
+        onclick=handle_menu_click(),
+        menu_items=[
+            [
+                MenuItem(label='Edit'),
+                MenuItem(label='Delete'),
+            ]
+        ]
+    )
+    ```
+
+    A dropdown menu with icons and custom styling:
+
+    ```python
+    from dara.core import action, ActionCtx, get_icon
+    from dara.components import Button, DropdownMenu
+
+    @action
+    async def handle_menu_click(ctx: ActionCtx):
+        print(f"Clicked: {ctx.input['label']}")
+
+    DropdownMenu(
+        button=Button('Actions', icon=get_icon('chevron-down')),
+        onclick=handle_menu_click(),
+        menu_items=[
+            [
+                MenuItem(
+                    label='Edit',
+                    icon=get_icon('pen'),
+                    style={'color': 'blue'}
+                ),
+                MenuItem(
+                    label='Delete',
+                    icon=get_icon('trash'),
+                    style={'color': 'red'}
+                ),
+            ],
+            [
+                MenuItem(label='Settings', icon=get_icon('gear'))
+            ]
+        ]
+    )
+    ```
+
+    A dropdown menu with custom components and prevent close behavior:
+
+    ```python
+    from dara.core import action, ActionCtx, Variable
+    from dara.components import Button, DropdownMenu, Text, Stack
+
+    counter = Variable(0)
+
+    @action
+    async def handle_menu_click(ctx: ActionCtx, counter_value: int):
+        print(f"Clicked: {ctx.input['label']}")
+
+        if ctx.input['label'] == 'Increment':
+            await ctx.update(counter, counter_value + 1)
+
+    DropdownMenu(
+        button=Button('Custom Menu'),
+        onclick=handle_menu_click(counter),
+        menu_items=[
+            [
+                MenuItem(
+                    label=Stack(Text('Counter: '), Text(counter)),
+                    prevent_close=True
+                ),
+                MenuItem(
+                    label='Increment',
+                    before=Text('→'),
+                    after=Text('↑')
+                )
+            ]
+        ]
+    )
+    ```
+
+    A dropdown menu with footer content at the bottom:
+
+    ```python
+    from dara.core import action, ActionCtx
+    from dara.components import Button, DropdownMenu, Text, Stack
+
+    @action
+    async def handle_menu_click(ctx: ActionCtx):
+        print(f"Clicked: {ctx.input['label']}")
+
+    DropdownMenu(
+        button=Button('Menu with Footer'),
+        onclick=handle_menu_click(),
+        menu_items=[
+            [
+                MenuItem(label='Option 1'),
+                MenuItem(label='Option 2'),
+            ]
+        ],
+        footer=Stack(
+            Text(
+                'Additional info or controls can go here',
+                raw_css={'padding': '8px', 'font-size': '0.8rem', 'color': 'gray'},
+            )
+        )
+    )
+    ```
+
+    :param button: The button component that triggers the dropdown menu
+    :param onclick: Action triggered when a menu item is clicked, receives the clicked item as parameter
+    :param menu_items: List of menu item sections, where each section is a list of MenuItem objects
+    :param footer: Optional component to display at the bottom of the dropdown menu
+    """
+
+    button: Button
+    onclick: Action
+    menu_items: list[list[MenuItem]] | ClientVariable
+    footer: ComponentInstance | None = None

dara/components/common/dropzone.py

@@ -15,62 +15,71 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Callable, Optional, Union
+from collections.abc import Callable
 from uuid import uuid4
 
 from pandas import DataFrame
+from pydantic import ConfigDict
 
 from dara.core.base_definitions import Action, UploadResolverDef
 from dara.core.definitions import StyledComponentInstance
-from dara.core.interactivity import DataVariable
+from dara.core.interactivity import ServerVariable
 
-DropzoneResolver = Union[
-    Callable[[bytes, str], DataFrame],
-    Callable[[bytes, str], None],
-]
+DropzoneResolver = Callable[[bytes, str], DataFrame] | Callable[[bytes, str], None]
 
 
 class UploadDropzone(StyledComponentInstance):
     """
-    A component that exposes a dropzone for uploading files. Takes a DataVariable instance
+    ![UploadDropzone](../../../../docs/packages/dara-components/common/assets/UploadDropzone.png)
+
+    A component that exposes a dropzone for uploading files. Takes a ServerVariable instance
     that will store the dataset uploaded and an on_drop action that is triggered when
     a file is successfully uploaded after being dropped or pasted.
+
+    ```python
+    import os
+    from dara.components import UploadDropzone
+
+    def handle_file_uploaded(file_data: bytes, file_name: str):
+        os.makedirs('data', exist_ok=True)
+        with open(os.path.join('data', file_name), 'wb') as f:
+            f.write(file_data)
+
+    UploadDropzone(
+        accept="image/png, image/jpeg",
+        resolver=handle_file_uploaded
+    )
+    ```
+
+    :param accept: optional comma-separated list of MIME-types or filename extensions accepted by the frontend; see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#unique_file_type_specifiers for detail.
+        When not specified, defaults to accepting csv/xlsx; more specifically: `.csv, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/csv, text/x-csv, application/x-csv, text/comma-separated-values, text/x-comma-separated-values`
+    :param target: server variable storing the data
+    :param resolver: optional resolver accepting `bytes` and filename as a string
+        - if a target is specified, can be used to customise how the `bytes` received are turned into a `DataFrame`
+        - if a target is not specified, can be treated as a side effect function to run on the `bytes` received (to i.e. store on disk)
+    :param on_drop: optional action triggered when a file is successfully uploaded
+    :param enable_paste: determines if the component should listen for and handle paste events (e.g., CTRL+V or right-click and paste). When set to True, the component allows text to be pasted directly, creating a file from the pasted content. This feature is disabled by default to accommodate scenarios where pasting text is not intended or could interfere with the component's primary functionality.
     """
 
     js_module = '@darajs/components'
 
-    accept: Optional[str] = None
-    target: Optional[DataVariable] = None
-    resolver: Optional[DropzoneResolver]
-    on_drop: Optional[Action] = None
+    accept: str | None = None
+    target: ServerVariable | None = None
+    resolver: DropzoneResolver | None = None
+    on_drop: Action | None = None
     enable_paste: bool = False
 
-    class Config:
-        extra = 'allow'
+    model_config = ConfigDict(extra='allow')
 
     def __init__(
         self,
-        target: Optional[DataVariable] = None,
-        resolver: Optional[DropzoneResolver] = None,
-        on_drop: Optional[Action] = None,
-        accept: Optional[str] = None,
-        enable_paste: Optional[bool] = False,
-        **kwargs
+        target: ServerVariable | None = None,
+        resolver: DropzoneResolver | None = None,
+        on_drop: Action | None = None,
+        accept: str | None = None,
+        enable_paste: bool | None = False,
+        **kwargs,
     ):
-        """
-        A component that exposes a dropzone for uploading files. Takes a DataVariable instance
-        that will store the dataset uploaded and an on_drop action that is triggered when
-        a file is successfully uploaded after being dropped or pasted.
-
-        :param accept: optional comma-separated list of MIME-types or filename extensions accepted by the frontend; see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#unique_file_type_specifiers for detail.
-            When not specified, defaults to accepting csv/xlsx; more specifically: `.csv, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/csv, text/x-csv, application/x-csv, text/comma-separated-values, text/x-comma-separated-values`
-        :param target: data variable storing the data
-        :param resolver: optional resolver accepting `bytes` and filename as a string
-            - if a target is specified, can be used to customise how the `bytes` received are turned into a `DataFrame`
-            - if a target is not specified, can be treated as a side effect function to run on the `bytes` received (to i.e. store on disk)
-        :param on_drop: optional action triggered when a file is successfully uploaded
-        :param enable_paste: determines if the component should listen for and handle paste events (e.g., CTRL+V or right-click and paste). When set to True, the component allows text to be pasted directly, creating a file from the pasted content. This feature is disabled by default to accommodate scenarios where pasting text is not intended or could interfere with the component's primary functionality.
-        """
         from dara.core.interactivity.any_data_variable import upload
         from dara.core.internal.registries import upload_resolver_registry
 

dara/components/common/form.py

@@ -15,9 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import List, Optional
-
-from pydantic import validator
+from pydantic import field_validator
 
 from dara.components.common.base_component import LayoutComponent
 from dara.core.base_definitions import Action
@@ -82,12 +80,12 @@ class Form(LayoutComponent):
     :param align: How to align the content of the form, accepts any flexbox alignments
     """
 
-    value: Optional[Variable[dict]] = None
-    onsubmit: Optional[Action] = None
+    value: Variable[dict] | None = None
+    onsubmit: Action | None = None
 
-    @validator('children')
+    @field_validator('children')
     @classmethod
-    def validate_children_pages(cls, children: List[ComponentInstance]) -> List[ComponentInstance]:
+    def validate_children_pages(cls, children: list[ComponentInstance]) -> list[ComponentInstance]:
         # Make sure if FormPage is included, non-pages are not direct children of the Form
         page_found = False
         non_page_found = False

dara/components/common/form_page.py

@@ -15,9 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import List, Optional
-
-from pydantic import validator
+from pydantic import field_validator
 
 from dara.components.common.base_component import FormComponent
 from dara.core.definitions import ComponentInstance
@@ -50,11 +48,11 @@ class FormPage(FormComponent):
     :param title: The title of the form page
     """
 
-    title: Optional[str] = None
+    title: str | None = None
 
-    @validator('children')
+    @field_validator('children')
     @classmethod
-    def validate_children(cls, children: List[ComponentInstance]) -> List[ComponentInstance]:
+    def validate_children(cls, children: list[ComponentInstance]) -> list[ComponentInstance]:
         for c in children:
             if isinstance(c, FormPage):
                 raise TypeError('FormPage detected inside another FormPage, nesting is disallowed')

dara/components/common/grid.py

@@ -15,21 +15,20 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Optional, Union
-
-from pydantic import BaseModel
+from typing import ClassVar
 
 from dara.components.common.base_component import LayoutComponent
+from dara.core.base_definitions import DaraBaseModel as BaseModel
 from dara.core.definitions import ComponentInstance, discover
 from dara.core.visual.components.types import Direction
 
 
 class ScreenBreakpoints(BaseModel):
-    xs: Optional[int] = None
-    sm: Optional[int] = None
-    md: Optional[int] = None
-    lg: Optional[int] = None
-    xl: Optional[int] = None
+    xs: int | None = None
+    sm: int | None = None
+    md: int | None = None
+    lg: int | None = None
+    xl: int | None = None
 
 
 class Column(LayoutComponent):
@@ -68,11 +67,11 @@ class Column(LayoutComponent):
 
     # TODO: :param order: optional number denoting the order of priority of the columns, with 1 being first to appear, and 12 the last to be added.
 
-    span: Optional[Union[int, ScreenBreakpoints]] = None
-    offset: Optional[Union[int, ScreenBreakpoints]]
+    span: int | ScreenBreakpoints | None = None
+    offset: int | ScreenBreakpoints | None = None
     direction: Direction = Direction.HORIZONTAL
 
-    def __init__(self, *args: ComponentInstance, **kwargs):
+    def __init__(self, *args: ComponentInstance | None, **kwargs):
         super().__init__(*args, **kwargs)
 
 
@@ -100,12 +99,16 @@ class Row(LayoutComponent):
     :param align: How to align the content of the row, accepts any flexbox alignments
     """
 
-    column_gap: Optional[int] = None
+    column_gap: int | None = None
 
-    def __init__(self, *args: ComponentInstance, **kwargs):
+    def __init__(self, *args: ComponentInstance | None, **kwargs):
         super().__init__(*args, **kwargs)
 
 
+ColumnType = type[Column]
+RowType = type[Row]
+
+
 @discover
 class Grid(LayoutComponent):
     """
@@ -117,14 +120,14 @@ class Grid(LayoutComponent):
     """
 
     row_gap: str = '0.75rem'
-    breakpoints: Optional[ScreenBreakpoints] = ScreenBreakpoints()
+    breakpoints: ScreenBreakpoints | None = ScreenBreakpoints()
 
-    Column = Column
-    Row = Row
-    Breakpoints = ScreenBreakpoints
+    Column: ClassVar[ColumnType] = Column
+    Row: ClassVar[RowType] = Row
+    Breakpoints: ClassVar[type[ScreenBreakpoints]] = ScreenBreakpoints
 
     # Dummy init that just passes through arguments to superclass, fixes Pylance complaining about types
-    def __init__(self, *args: ComponentInstance, **kwargs):
+    def __init__(self, *args: ComponentInstance | None, **kwargs):
         """
         Grid Layout provides a flexbox grid with a twelve column system.
         Rows will automatically calculate their widths and wrap on the page as needed.