ex4nicegui 0.6.9__py3-none-any.whl → 0.7.0__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,7 @@ 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 .local_file_picker import local_file_picker
 from .UseDraggable.UseDraggable import use_draggable
@@ -63,8 +64,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 +91,9 @@ __all__ = [
     "vfor",
     "VforStore",
     "vmodel",
+    "ViewModel",
+    "var",
+    "cached_var",
     "html",
     "aggrid",
     "button",
@@ -124,4 +130,6 @@ __all__ = [
     "pagination",
     "mermaid",
     "chip",
+    "dialog",
+    "tooltip",
 ]

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
@@ -105,8 +106,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 +148,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 +156,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 +214,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 +242,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 +321,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 +356,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)  # 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)  # 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/button.py

@@ -44,50 +44,50 @@ class ButtonBindableUi(
         for key, value in pc.get_bindings().items():
             self.bind_prop(key, value)  # type: ignore
 
-    def bind_prop(self, prop: str, ref_ui: TGetterOrReadonlyRef):
+    def bind_prop(self, prop: str, value: TGetterOrReadonlyRef):
         if prop == "text":
-            return self.bind_text(ref_ui)
+            return self.bind_text(value)
         if prop == "icon":
-            return self.bind_icon(ref_ui)
+            return self.bind_icon(value)
         if prop == "color":
-            return self.bind_color(ref_ui)
+            return self.bind_color(value)
 
-        return super().bind_prop(prop, ref_ui)
+        return super().bind_prop(prop, value)
 
-    def bind_color(self, ref_ui: TGetterOrReadonlyRef[str]):
+    def bind_color(self, color: TGetterOrReadonlyRef[str]):
         """Binds the background color of the button.
 
         Args:
-            ref_ui (TGetterOrReadonlyRef[str]): Getter or readonly reference to the color.
+            color (TGetterOrReadonlyRef[str]): Getter or readonly reference to the color.
 
         """
-        BackgroundColorableMixin.bind_color(self, ref_ui)
+        BackgroundColorableMixin.bind_color(self, color)
         return self
 
-    def bind_text_color(self, ref_ui: TGetterOrReadonlyRef[str]):
+    def bind_text_color(self, text_color: TGetterOrReadonlyRef[str]):
         """Binds the text color of the button.
 
         Args:
-            ref_ui (TGetterOrReadonlyRef[str]):  Getter or readonly reference to the color.
+            text_color (TGetterOrReadonlyRef[str]):  Getter or readonly reference to the color.
 
         """
-        TextColorableMixin.bind_color(self, ref_ui)
+        TextColorableMixin.bind_color(self, text_color)
         return self
 
-    def bind_text(self, ref_ui: TGetterOrReadonlyRef):
+    def bind_text(self, text: TGetterOrReadonlyRef):
         @self._ui_effect
         def _():
             ele = self.element
-            ele._props["label"] = to_value(ref_ui)
+            ele._props["label"] = to_value(text)
             ele.update()
 
         return self
 
-    def bind_icon(self, ref_ui: TGetterOrReadonlyRef[str]):
+    def bind_icon(self, icon: TGetterOrReadonlyRef[str]):
         @self._ui_effect
         def _():
             ele = self.element
-            ele._props["icon"] = to_value(ref_ui)
+            ele._props["icon"] = to_value(icon)
             ele.update()
 
         return self

ex4nicegui/reactive/officials/checkbox.py

@@ -43,16 +43,16 @@ class CheckboxBindableUi(BindableUi[ui.checkbox], DisableableMixin):
     def value(self):
         return self.element.value
 
-    def bind_prop(self, prop: str, ref_ui: TGetterOrReadonlyRef):
+    def bind_prop(self, prop: str, value: TGetterOrReadonlyRef):
         if prop == "value":
-            return self.bind_value(ref_ui)
+            return self.bind_value(value)
 
-        return super().bind_prop(prop, ref_ui)
+        return super().bind_prop(prop, value)
 
-    def bind_value(self, ref_ui: TGetterOrReadonlyRef[bool]):
+    def bind_value(self, value: TGetterOrReadonlyRef[bool]):
         @self._ui_effect
         def _():
-            self.element.set_value(to_value(ref_ui))
+            self.element.set_value(to_value(value))
             self.element.update()
 
         return self

ex4nicegui/reactive/officials/chip.py

@@ -54,16 +54,16 @@ class ChipBindableUi(
     def text(self):
         return self.element.text
 
-    def bind_prop(self, prop: str, ref_ui: TGetterOrReadonlyRef):
+    def bind_prop(self, prop: str, value: TGetterOrReadonlyRef):
         if prop == "text":
-            return self.bind_text(ref_ui)
+            return self.bind_text(value)
 
         if prop == "color":
-            return self.bind_color(ref_ui)
+            return self.bind_color(value)
         if prop == "text-color":
-            return self.bind_text_color(ref_ui)
+            return self.bind_text_color(value)
 
-        return super().bind_prop(prop, ref_ui)
+        return super().bind_prop(prop, value)
 
     def bind_color(self, color: TGetterOrReadonlyRef):
         """Binds the background color property of the chip to a ui element.

ex4nicegui/reactive/officials/circular_progress.py

@@ -49,17 +49,17 @@ class CircularProgressBindableUi(
     def value(self):
         return self.element.value
 
-    def bind_prop(self, prop: str, ref_ui: TGetterOrReadonlyRef):
+    def bind_prop(self, prop: str, value: TGetterOrReadonlyRef):
         if prop == "value":
-            return self.bind_value(ref_ui)
+            return self.bind_value(value)
         if prop == "color":
-            return self.bind_color(ref_ui)
+            return self.bind_color(value)
 
-        return super().bind_prop(prop, ref_ui)
+        return super().bind_prop(prop, value)
 
-    def bind_value(self, ref_ui: TGetterOrReadonlyRef[float]):
+    def bind_value(self, value: TGetterOrReadonlyRef[float]):
         @self._ui_effect
         def _():
-            self.element.set_value(to_value(ref_ui))
+            self.element.set_value(to_value(value))
 
         return self