ex4nicegui 0.6.9__py3-none-any.whl → 0.7.1__py3-none-any.whl

ex4nicegui/bi/dataSourceFacade.py

@@ -228,26 +228,26 @@ class DataSourceFacade(Generic[_TData]):
 
         Support pyecharts
 
-        ```py
-        import pandas as pd
-        from ex4nicegui import bi
-        from pyecharts.charts import Bar
-
-        df = pd.DataFrame({"name": list("abcdc"), "value": range(5)})
-        ds = bi.data_source(df)
-
-        @ds.ui_echarts
-        def bar(data: pd.DataFrame):
-            c = (
-                Bar()
-                .add_xaxis(data["name"].tolist())
-                .add_yaxis("value", data["value"].tolist())
-            )
-
-            return c
-
-        bar.classes("h-[20rem]")
-        ```
+        .. code-block:: python
+            import pandas as pd
+            from ex4nicegui import bi
+            from pyecharts.charts import Bar
+
+            df = pd.DataFrame({"name": list("abcdc"), "value": range(5)})
+            ds = bi.data_source(df)
+
+            @ds.ui_echarts
+            def bar(data: pd.DataFrame):
+                c = (
+                    Bar()
+                    .add_xaxis(data["name"].tolist())
+                    .add_yaxis("value", data["value"].tolist())
+                )
+
+                return c
+
+            bar.classes("h-[20rem]")
+
 
         """
         return ui_echarts(self, fn)

ex4nicegui/bi/index.py

@@ -24,43 +24,40 @@ def data_source(data: Union[Callable[..., _TData], _TData]) -> DataSourceFacade[
 
     ## Examples
 
-    ---
-
     pandas dataframe source:
-    ```python
-    df = pd.DataFrame({"name": list("abcdc"), "value": range(5)})
-    ds = bi.data_source(df)
-    ```
+
+    .. code-block:: python
+        df = pd.DataFrame({"name": list("abcdc"), "value": range(5)})
+        ds = bi.data_source(df)
+
 
     ---
 
     Link multiple data sources
 
-    ---
-    ```python
-    df = pd.DataFrame({"name": list("abcdc"), "value": range(5)})
-    ds = bi.data_source(df)
+    .. code-block:: python
+        df = pd.DataFrame({"name": list("abcdc"), "value": range(5)})
+        ds = bi.data_source(df)
 
-    @bi.data_source
-    def ds_other():
-        #  ds.filtered_data is DataFrame after filtering
-        where = ds.filtered_data[''].isin(['b','c','d'])
-        return ds.filtered_data[where]
+        @bi.data_source
+        def ds_other():
+            #  ds.filtered_data is DataFrame after filtering
+            where = ds.filtered_data[''].isin(['b','c','d'])
+            return ds.filtered_data[where]
 
-    ```
 
     ---
 
     Now, when `ds` changes, it will trigger changes to `ds_other` and thus drive the related interface components to change.
 
-    ```python
-    # select box of data source 'ds'
-    # it change will trigger changes to table
-    ds.ui_select('name')
+    .. code-block:: python
+        # select box of data source 'ds'
+        # it change will trigger changes to table
+        ds.ui_select('name')
+
+        # table of data 'ds_other'
+        ds_other.ui_aggrid()
 
-    # table of data 'ds_other'
-    ds_other.ui_aggrid()
-    ```
 
 
     """

ex4nicegui/reactive/EChartsComponent/ECharts.py

@@ -64,14 +64,15 @@ class echarts(Element, component="ECharts.js", libraries=libraries):  # type: ig
         Args:
             options (dict): chart setting options dict
             opts (Optional[dict], optional): update options. Defaults to None.
-            ```python
-                {
-                    'notMerge':False,
-                    'lazyUpdate':False,
-                    'silent':False,
-                    'replaceMerge': None,
-                }
-            ```
+
+         .. code-block:: python
+            {
+                'notMerge':False,
+                'lazyUpdate':False,
+                'silent':False,
+                'replaceMerge': None,
+            }
+
             [open echarts setOption docs](https://echarts.apache.org/zh/api.html#echartsInstance.setOption)
 
         """

ex4nicegui/reactive/__init__.py

@@ -54,6 +54,10 @@ from .officials.element import ElementBindableUi as element
 from .officials.tab_panels import LazyTabPanelsBindableUi as lazy_tab_panels
 from .q_pagination import PaginationBindableUi as q_pagination
 from .officials.chip import ChipBindableUi as chip
+from .officials.tooltip import TooltipBindableUi as tooltip
+from .officials.toggle import ToggleBindableUi as toggle
+from .officials.avatar import AvatarBindableUi as avatar
+from .officials.badge import BadgeBindableUi as badge
 
 from .local_file_picker import local_file_picker
 from .UseDraggable.UseDraggable import use_draggable
@@ -63,8 +67,10 @@ from .usePagination import PaginationRef as use_pagination
 from .dropZone.dropZone import use_drag_zone
 from .fileWatcher import FilesWatcher
 from .mermaid.mermaid import Mermaid as mermaid
+from .officials.dialog import DialogBindableUi as dialog
 from .vfor import vfor, VforStore
 from .vmodel import vmodel
+from .view_model import ViewModel, var, cached_var
 
 pagination = q_pagination
 
@@ -88,6 +94,9 @@ __all__ = [
     "vfor",
     "VforStore",
     "vmodel",
+    "ViewModel",
+    "var",
+    "cached_var",
     "html",
     "aggrid",
     "button",
@@ -124,4 +133,9 @@ __all__ = [
     "pagination",
     "mermaid",
     "chip",
+    "dialog",
+    "tooltip",
+    "toggle",
+    "avatar",
+    "badge",
 ]

ex4nicegui/reactive/base.py

@@ -24,6 +24,7 @@ from ex4nicegui.utils.signals import (
     on,
 )
 from ex4nicegui.utils.clientScope import new_scope
+from ex4nicegui.utils.types import _TMaybeRef as TMaybeRef
 from nicegui import Tailwind, ui
 from nicegui.elements.mixins.text_element import TextElement
 from ex4nicegui.reactive.services.reactive_service import inject_handle_delete
@@ -72,7 +73,9 @@ class BindableUi(Generic[TWidget]):
 
     @property
     def _ui_signal_on(self):
-        return partial(on, scope=self._effect_scope)
+        """equivalent to `on`, but with the effect scope,and with `onchanges`=True and `deep` = False"""
+
+        return partial(on, scope=self._effect_scope, onchanges=True, deep=False)
 
     def props(self, add: Optional[str] = None, *, remove: Optional[str] = None):
         cast(ui.element, self.element).props(add, remove=remove)
@@ -105,8 +108,12 @@ class BindableUi(Generic[TWidget]):
     def __exit__(self, *_):
         self.element.default_slot.__exit__(*_)
 
-    def tooltip(self, text: str) -> Self:
-        cast(ui.element, self.element).tooltip(text)
+    def tooltip(self, text: TMaybeRef[str]) -> Self:
+        from ex4nicegui.reactive.officials.tooltip import TooltipBindableUi
+
+        with self:
+            TooltipBindableUi(text)
+
         return self
 
     def add_slot(self, name: str, template: Optional[str] = None):
@@ -143,7 +150,7 @@ class BindableUi(Generic[TWidget]):
         """
         return self.element.remove(element)
 
-    def bind_prop(self, prop: str, ref_ui: TGetterOrReadonlyRef[Any]):
+    def bind_prop(self, prop: str, value: TGetterOrReadonlyRef[Any]):
         """data binding is manipulating an element's property
 
         @see - https://github.com/CrystalWindSnake/ex4nicegui/blob/main/README.en.md#bind_prop
@@ -151,37 +158,37 @@ class BindableUi(Generic[TWidget]):
 
         Args:
             prop (str): property name
-            ref_ui (TGetterOrReadonlyRef[Any]): a reference to the value to bind to
+            value (TGetterOrReadonlyRef[Any]): a reference to the value to bind to
 
         """
         if prop == "visible":
-            return self.bind_visible(ref_ui)
+            return self.bind_visible(value)
 
         if prop == "text" and isinstance(self.element, TextElement):
 
             @self._ui_effect
             def _():
-                cast(TextElement, self.element).set_text(to_value(ref_ui))
+                cast(TextElement, self.element).set_text(to_value(value))
                 self.element.update()
 
         @self._ui_effect
         def _():
             element = cast(ui.element, self.element)
-            element._props[prop] = to_value(ref_ui)
+            element._props[prop] = to_value(value)
             element.update()
 
         return self
 
-    def bind_visible(self, ref_ui: TGetterOrReadonlyRef[bool]):
+    def bind_visible(self, value: TGetterOrReadonlyRef[bool]):
         @self._ui_effect
         def _():
             element = cast(ui.element, self.element)
-            element.set_visibility(to_value(ref_ui))
+            element.set_visibility(to_value(value))
 
         return self
 
-    def bind_not_visible(self, ref_ui: TGetterOrReadonlyRef[bool]):
-        return self.bind_visible(lambda: not to_value(ref_ui))
+    def bind_not_visible(self, value: TGetterOrReadonlyRef[bool]):
+        return self.bind_visible(lambda: not to_value(value))
 
     def on(
         self,
@@ -209,22 +216,22 @@ class BindableUi(Generic[TWidget]):
         cast(ui.element, self.element).clear()
 
     @overload
-    def bind_classes(self, classes: Dict[str, TGetterOrReadonlyRef[bool]]):
+    def bind_classes(self, classes: Dict[str, TGetterOrReadonlyRef[bool]]) -> Self:
         ...
 
     @overload
-    def bind_classes(self, classes: TGetterOrReadonlyRef[Dict[str, bool]]):
+    def bind_classes(self, classes: TGetterOrReadonlyRef[Dict[str, bool]]) -> Self:
         ...
 
     @overload
-    def bind_classes(self, classes: List[TGetterOrReadonlyRef[str]]):
+    def bind_classes(self, classes: List[TGetterOrReadonlyRef[str]]) -> Self:
         ...
 
     @overload
-    def bind_classes(self, classes: TGetterOrReadonlyRef[str]):
+    def bind_classes(self, classes: TGetterOrReadonlyRef[str]) -> Self:
         ...
 
-    def bind_classes(self, classes: _T_bind_classes_type):
+    def bind_classes(self, classes: _T_bind_classes_type) -> Self:
         """data binding is manipulating an element's class list
 
         @see - https://github.com/CrystalWindSnake/ex4nicegui/blob/main/README.en.md#bind-class-names
@@ -237,30 +244,30 @@ class BindableUi(Generic[TWidget]):
 
         bind class names with dict,value is bool ref, for example:
 
-            ```python
+        .. code-block:: python
             bg_color = to_ref(True)
             has_error = to_ref(False)
 
             rxui.label('Hello').bind_classes({'bg-blue':bg_color, 'text-red':has_error})
-            ```
+
 
         bind list of class names with ref
 
-            ```python
+        .. code-block:: python
             color = to_ref('red')
             bg_color = lambda: f"bg-{color.value}"
 
             rxui.label('Hello').bind_classes([bg_color])
-            ```
+
 
         bind single class name with ref
 
-            ```python
+        .. code-block:: python
             color = to_ref('red')
             bg_color = lambda: f"bg-{color.value}"
 
             rxui.label('Hello').bind_classes(bg_color)
-            ```
+
 
         """
         if isinstance(classes, dict):
@@ -316,17 +323,18 @@ class BindableUi(Generic[TWidget]):
 
 
         ## usage
-        ```python
-        bg_color = to_ref("blue")
-        text_color = to_ref("red")
-
-        rxui.label("test").bind_style(
-            {
-                "background-color": bg_color,
-                "color": text_color,
-            }
-        )
-        ```
+
+        .. code-block:: python
+            bg_color = to_ref("blue")
+            text_color = to_ref("red")
+
+            rxui.label("test").bind_style(
+                {
+                    "background-color": bg_color,
+                    "color": text_color,
+                }
+            )
+
         """
         if isinstance(style, dict):
             for name, ref_obj in style.items():
@@ -350,27 +358,28 @@ class BindableUi(Generic[TWidget]):
             style (Union[str, Path]): path to css file or inline style string
 
         ## usage
-        ```python
-        # all children of the element will have red outline, excluding itself
-        with rxui.row().scoped_style("*", "outline: 1px solid red;") as row:
-            ui.label("Hello")
-            ui.label("World")
-
-        # all children of the element will have red outline, including the element itself
-        with rxui.row().scoped_style(":self *", "outline: 1px solid red;") as row:
-            ui.label("Hello")
-            ui.label("World")
-
-        # all children of the element will have red outline when element is hovered
-        with rxui.row().scoped_style(":hover *", "outline: 1px solid red;") as row:
-            ui.label("Hello")
-            ui.label("World")
-
-        # all children of the element and itself will have red outline when element is hovered
-        with rxui.row().scoped_style(":self:hover *", "outline: 1px solid red;") as row:
-            ui.label("Hello")
-            ui.label("World")
-        ```
+
+        .. code-block:: python
+            # all children of the element will have red outline, excluding itself
+            with rxui.row().scoped_style("*", "outline: 1px solid red;") as row:
+                ui.label("Hello")
+                ui.label("World")
+
+            # all children of the element will have red outline, including the element itself
+            with rxui.row().scoped_style(":self *", "outline: 1px solid red;") as row:
+                ui.label("Hello")
+                ui.label("World")
+
+            # all children of the element will have red outline when element is hovered
+            with rxui.row().scoped_style(":hover *", "outline: 1px solid red;") as row:
+                ui.label("Hello")
+                ui.label("World")
+
+            # all children of the element and itself will have red outline when element is hovered
+            with rxui.row().scoped_style(":self:hover *", "outline: 1px solid red;") as row:
+                ui.label("Hello")
+                ui.label("World")
+
         """
 
         is_css_file = isinstance(style, Path)

ex4nicegui/reactive/mixins/backgroundColor.py

@@ -20,8 +20,8 @@ class BackgroundColorableMixin(Protocol):
     def element(self) -> ui.element:
         ...
 
-    def _bind_background_color(self, ref_ui: TGetterOrReadonlyRef[str]):
-        @self._ui_signal_on(ref_ui)  # type: ignore
+    def _bind_background_color(self, value: TGetterOrReadonlyRef[str]):
+        @self._ui_signal_on(value, onchanges=False)  # type: ignore
         def _(state: WatchedState):
             if state.previous is not None:
                 color_system.remove_background_color(self.element, state.previous)
@@ -30,12 +30,12 @@ class BackgroundColorableMixin(Protocol):
 
             self.element.update()
 
-    def bind_color(self, ref_ui: TGetterOrReadonlyRef[str]):
+    def bind_color(self, color: TGetterOrReadonlyRef[str]):
         """bind color to the element
 
         Args:
-            ref_ui (TGetterOrReadonlyRef[str]): a reference to the color value
+            color (TGetterOrReadonlyRef[str]): a reference to the color value
 
         """
-        self._bind_background_color(ref_ui)
+        self._bind_background_color(color)
         return self

ex4nicegui/reactive/mixins/disableable.py

@@ -25,20 +25,20 @@ class DisableableMixin(Protocol):
     def element(self) -> DisableableElement:
         ...
 
-    def bind_enabled(self, ref_ui: TGetterOrReadonlyRef[bool]):
+    def bind_enabled(self, value: TGetterOrReadonlyRef[bool]):
         @self._ui_effect
         def _():
-            value = to_value(ref_ui)
-            self.element.set_enabled(value)
-            self.element._handle_enabled_change(value)
+            raw_value = to_value(value)
+            self.element.set_enabled(raw_value)
+            self.element._handle_enabled_change(raw_value)
 
         return self
 
-    def bind_disable(self, ref_ui: TGetterOrReadonlyRef[bool]):
+    def bind_disable(self, value: TGetterOrReadonlyRef[bool]):
         @self._ui_effect
         def _():
-            value = not to_value(ref_ui)
-            self.element.set_enabled(value)
-            self.element._handle_enabled_change(value)
+            raw_value = not to_value(value)
+            self.element.set_enabled(raw_value)
+            self.element._handle_enabled_change(raw_value)
 
         return self

ex4nicegui/reactive/mixins/textColor.py

@@ -21,8 +21,8 @@ class TextColorableMixin(Protocol):
     def element(self) -> ui.element:
         ...
 
-    def _bind_text_color(self, ref_ui: TGetterOrReadonlyRef[str]):
-        @self._ui_signal_on(ref_ui)  # type: ignore
+    def _bind_text_color(self, color: TGetterOrReadonlyRef[str]):
+        @self._ui_signal_on(color, onchanges=False)  # type: ignore
         def _(state: WatchedState):
             if state.previous is not None:
                 color_system.remove_text_color(self.element, state.previous)
@@ -31,14 +31,14 @@ class TextColorableMixin(Protocol):
 
             self.element.update()
 
-    def bind_color(self, ref_ui: TGetterOrReadonlyRef[str]):
+    def bind_color(self, color: TGetterOrReadonlyRef[str]):
         """bind text color to the element
 
         Args:
-            ref_ui (TGetterOrReadonlyRef[str]): a reference to the color value
+            color (TGetterOrReadonlyRef[str]): a reference to the color value
 
         """
-        self._bind_text_color(ref_ui)
+        self._bind_text_color(color)
         return self
 
 
@@ -52,15 +52,15 @@ class HtmlTextColorableMixin(Protocol):
     def bind_style(self, style: Dict[str, TGetterOrReadonlyRef[Any]]):
         ...
 
-    def _bind_text_color(self, ref_ui: TGetterOrReadonlyRef[str]):
-        return self.bind_style({"color": ref_ui})
+    def _bind_text_color(self, value: TGetterOrReadonlyRef[str]):
+        return self.bind_style({"color": value})
 
-    def bind_color(self, ref_ui: TGetterOrReadonlyRef[str]):
+    def bind_color(self, color: TGetterOrReadonlyRef[str]):
         """bind text color to the element
 
         Args:
-            ref_ui (TGetterOrReadonlyRef[str]): a reference to the color value
+            color (TGetterOrReadonlyRef[str]): a reference to the color value
 
         """
-        self._bind_text_color(ref_ui)
+        self._bind_text_color(color)
         return self

ex4nicegui/reactive/officials/aggrid.py

@@ -78,17 +78,17 @@ class AggridBindableUi(BindableUi[ui.aggrid]):
         options = {"columnDefs": columnDefs, "rowData": rowData}
         return cls(options, **org_kws)
 
-    def bind_prop(self, prop: str, ref_ui: TGetterOrReadonlyRef[Any]):
+    def bind_prop(self, prop: str, value: TGetterOrReadonlyRef[Any]):
         if prop == "options":
-            return self.bind_options(ref_ui)
+            return self.bind_options(value)
 
-        return super().bind_prop(prop, ref_ui)
+        return super().bind_prop(prop, value)
 
-    def bind_options(self, ref_ui: TGetterOrReadonlyRef[List[Dict]]):
+    def bind_options(self, options: TGetterOrReadonlyRef[List[Dict]]):
         @self._ui_effect
         def _():
             ele = self.element
-            data = to_value(ref_ui)
+            data = to_value(options)
             ele._props["options"].update(data)
             ele.update()
 

ex4nicegui/reactive/officials/avatar.py

@@ -0,0 +1,86 @@
+from typing import Optional
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
+from ex4nicegui.utils.signals import (
+    TGetterOrReadonlyRef,
+    _TMaybeRef as TMaybeRef,
+)
+from nicegui import ui
+from .base import BindableUi
+from ex4nicegui.reactive.mixins.backgroundColor import BackgroundColorableMixin
+from ex4nicegui.reactive.mixins.textColor import TextColorableMixin
+
+
+class AvatarBindableUi(
+    BindableUi[ui.avatar], TextColorableMixin, BackgroundColorableMixin
+):
+    def __init__(
+        self,
+        icon: Optional[TMaybeRef[str]] = None,
+        *,
+        color: Optional[TMaybeRef[str]] = "primary",
+        text_color: Optional[TMaybeRef[str]] = None,
+        size: Optional[TMaybeRef[str]] = None,
+        font_size: Optional[TMaybeRef[str]] = None,
+        square: TMaybeRef[bool] = False,
+        rounded: TMaybeRef[bool] = False,
+    ) -> None:
+        """Avatar
+
+        A avatar element wrapping Quasar's
+        `QAvatar <https://quasar.dev/vue-components/avatar>`_ component.
+
+        :param icon: name of the icon or image path with "img:" prefix (e.g. "map", "img:path/to/image.png")
+        :param color: background color (either a Quasar, Tailwind, or CSS color or `None`, default: "primary")
+        :param text_color: color name from the Quasar Color Palette (e.g. "primary", "teal-10")
+        :param size: size in CSS units, including unit name or standard size name (xs|sm|md|lg|xl) (e.g. "16px", "2rem")
+        :param font_size: size in CSS units, including unit name, of the content (icon, text) (e.g. "18px", "2rem")
+        :param square: removes border-radius so borders are squared (default: False)
+        :param rounded: applies a small standard border-radius for a squared shape of the component (default: False)
+        """
+        pc = ParameterClassifier(
+            locals(),
+            maybeRefs=[
+                "icon",
+                "color",
+                "text_color",
+                "size",
+                "font_size",
+                "square",
+                "rounded",
+            ],
+            events=[],
+        )
+
+        init_kws = pc.get_values_kws()
+        element = ui.avatar(**init_kws)
+        super().__init__(element)
+
+        for key, value in pc.get_bindings().items():
+            self.bind_prop(key, value)  # type: ignore
+
+    def bind_prop(self, prop: str, value: TGetterOrReadonlyRef):
+        if prop == "color":
+            return self.bind_color(value)
+        if prop == "text-color":
+            return self.bind_text_color(value)
+
+        return super().bind_prop(prop, value)
+
+    def bind_color(self, color: TGetterOrReadonlyRef):
+        """Binds the background color property of the chip to a ui element.
+
+        Args:
+            color (TGetterOrReadonlyRef): background color ui element or getter function
+
+        """
+        BackgroundColorableMixin.bind_color(self, color)
+        return self
+
+    def bind_text_color(self, color: TGetterOrReadonlyRef):
+        """Binds the text color property of the chip to a ui element.
+
+        Args:
+            color (TGetterOrReadonlyRef):  text color ui element or getter function
+        """
+        TextColorableMixin.bind_color(self, color)
+        return self