ex4nicegui 0.6.8__py3-none-any.whl → 0.7.0__py3-none-any.whl

ex4nicegui/__init__.py

@@ -6,6 +6,7 @@ from ex4nicegui.utils.types import (
     ReadonlyRef,
     TGetterOrReadonlyRef,
 )
+from ex4nicegui.utils.scheduler import next_tick
 from ex4nicegui.utils.signals import (
     effect,
     effect_refreshable,
@@ -49,5 +50,6 @@ __all__ = [
     "to_raw",
     "is_setter_ref",
     "new_scope",
+    "next_tick",
     "__version__",
 ]

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/helper/client_instance_locker.py

@@ -1,4 +1,4 @@
-from typing import Callable, TypeVar, Generic
+from typing import Callable, Optional, TypeVar, Generic
 from nicegui import ui, Client
 from weakref import WeakKeyDictionary
 
@@ -16,16 +16,16 @@ class ClientInstanceLocker(Generic[_T]):
         self._client_instances: WeakKeyDictionary[Client, _T] = WeakKeyDictionary()
         self._factory = factory
 
-    def get_object(self):
+    def get_object(self, client: Optional[Client] = None):
         if not ui.context.slot_stack:
             return None
 
-        client = ui.context.client
+        client = client or ui.context.client
         if client not in self._client_instances:
             self._client_instances[client] = self._factory()
 
             @client.on_disconnect
             def _():
-                del self._client_instances[client]
+                self._client_instances.pop(client, None)
 
         return self._client_instances[client]

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

@@ -51,7 +51,10 @@ from .officials.tab import TabBindableUi as tab
 from .officials.tab_panels import TabPanelsBindableUi as tab_panels
 from .officials.tab_panel import TabPanelBindableUi as tab_panel
 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
@@ -61,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
 
@@ -70,6 +75,7 @@ pagination = q_pagination
 __all__ = [
     "element",
     "tab_panels",
+    "lazy_tab_panels",
     "tab_panel",
     "tabs",
     "tab",
@@ -85,6 +91,9 @@ __all__ = [
     "vfor",
     "VforStore",
     "vmodel",
+    "ViewModel",
+    "var",
+    "cached_var",
     "html",
     "aggrid",
     "button",
@@ -120,4 +129,7 @@ __all__ = [
     "q_pagination",
     "pagination",
     "mermaid",
+    "chip",
+    "dialog",
+    "tooltip",
 ]

ex4nicegui/reactive/base.py

@@ -0,0 +1,433 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    TypeVar,
+    Generic,
+    Union,
+    cast,
+    overload,
+)
+
+from typing_extensions import Self
+from ex4nicegui.utils.apiEffect import ui_effect
+from ex4nicegui.utils.signals import (
+    TGetterOrReadonlyRef,
+    to_value,
+    is_ref,
+    WatchedState,
+    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
+from ex4nicegui.reactive.scopedStyle import ScopedStyle
+from ex4nicegui.reactive.mixins.disableable import DisableableMixin
+from functools import partial
+
+T = TypeVar("T")
+
+
+TWidget = TypeVar("TWidget", bound=ui.element)
+
+_T_bind_classes_type_dict = Dict[str, TGetterOrReadonlyRef[bool]]
+_T_bind_classes_type_ref_dict = TGetterOrReadonlyRef[Dict[str, bool]]
+_T_bind_classes_type_single = TGetterOrReadonlyRef[str]
+_T_bind_classes_type_array = List[_T_bind_classes_type_single]
+
+
+_T_bind_classes_type = Union[
+    _T_bind_classes_type_dict,
+    _T_bind_classes_type_ref_dict,
+    _T_bind_classes_type_single,
+    _T_bind_classes_type_array,
+]
+
+
+class BindableUi(Generic[TWidget]):
+    def __init__(self, element: TWidget) -> None:
+        self._element = element
+        inject_handle_delete(self.element, self._on_element_delete)
+        self.tailwind = Tailwind(cast(ui.element, self._element))
+        self._effect_scope = new_scope()
+        self.__used_scope_style = False
+
+    def _on_element_delete(self):
+        self._effect_scope.dispose()
+
+        if self.__used_scope_style:
+            scope_style = ScopedStyle.get()
+            if scope_style:
+                scope_style.remove_style(self.element)
+
+    @property
+    def _ui_effect(self):
+        return partial(ui_effect, scope=self._effect_scope)
+
+    @property
+    def _ui_signal_on(self):
+        return partial(on, scope=self._effect_scope)
+
+    def props(self, add: Optional[str] = None, *, remove: Optional[str] = None):
+        cast(ui.element, self.element).props(add, remove=remove)
+        return self
+
+    def classes(
+        self,
+        add: Optional[str] = None,
+        *,
+        remove: Optional[str] = None,
+        replace: Optional[str] = None,
+    ):
+        cast(ui.element, self.element).classes(add, remove=remove, replace=replace)
+        return self
+
+    def style(
+        self,
+        add: Optional[str] = None,
+        *,
+        remove: Optional[str] = None,
+        replace: Optional[str] = None,
+    ):
+        cast(ui.element, self.element).style(add, remove=remove, replace=replace)
+        return self
+
+    def __enter__(self) -> Self:
+        self.element.__enter__()
+        return self
+
+    def __exit__(self, *_):
+        self.element.default_slot.__exit__(*_)
+
+    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):
+        """Add a slot to the element.
+
+        :param name: name of the slot
+        :param template: Vue template of the slot
+        :return: the slot
+        """
+        return cast(ui.element, self.element).add_slot(name, template)
+
+    @property
+    def element(self):
+        return self._element
+
+    def delete(self) -> None:
+        """Delete the element."""
+        self.element.delete()
+
+    def move(
+        self, target_container: Optional[ui.element] = None, target_index: int = -1
+    ):
+        """Move the element to another container.
+
+        :param target_container: container to move the element to (default: the parent container)
+        :param target_index: index within the target slot (default: append to the end)
+        """
+        return self.element.move(target_container, target_index)
+
+    def remove(self, element: Union[ui.element, int]) -> None:
+        """Remove a child element.
+
+        :param element: either the element instance or its ID
+        """
+        return self.element.remove(element)
+
+    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
+        @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#bind_prop
+
+        Args:
+            prop (str): property name
+            value (TGetterOrReadonlyRef[Any]): a reference to the value to bind to
+
+        """
+        if prop == "visible":
+            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(value))
+                self.element.update()
+
+        @self._ui_effect
+        def _():
+            element = cast(ui.element, self.element)
+            element._props[prop] = to_value(value)
+            element.update()
+
+        return self
+
+    def bind_visible(self, value: TGetterOrReadonlyRef[bool]):
+        @self._ui_effect
+        def _():
+            element = cast(ui.element, self.element)
+            element.set_visibility(to_value(value))
+
+        return self
+
+    def bind_not_visible(self, value: TGetterOrReadonlyRef[bool]):
+        return self.bind_visible(lambda: not to_value(value))
+
+    def on(
+        self,
+        type: str,
+        handler: Optional[Callable[..., Any]] = None,
+        args: Optional[List[str]] = None,
+        *,
+        throttle: float = 0.0,
+        leading_events: bool = True,
+        trailing_events: bool = True,
+    ):
+        ele = cast(ui.element, self.element)
+        ele.on(
+            type,
+            handler,
+            args,
+            throttle=throttle,
+            leading_events=leading_events,
+            trailing_events=trailing_events,
+        )
+
+        return self
+
+    def clear(self) -> None:
+        cast(ui.element, self.element).clear()
+
+    @overload
+    def bind_classes(self, classes: Dict[str, TGetterOrReadonlyRef[bool]]) -> Self:
+        ...
+
+    @overload
+    def bind_classes(self, classes: TGetterOrReadonlyRef[Dict[str, bool]]) -> Self:
+        ...
+
+    @overload
+    def bind_classes(self, classes: List[TGetterOrReadonlyRef[str]]) -> Self:
+        ...
+
+    @overload
+    def bind_classes(self, classes: TGetterOrReadonlyRef[str]) -> Self:
+        ...
+
+    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
+        @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#%E7%BB%91%E5%AE%9A%E7%B1%BB%E5%90%8D
+
+        Args:
+            classes (_T_bind_classes_type): dict of refs | ref to dict | str ref | list of refs
+
+        ## usage
+
+        bind class names with dict,value is bool ref, for example:
+
+        .. 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
+
+        .. 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
+
+        .. 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):
+            for name, ref_obj in classes.items():
+
+                @self._ui_effect
+                def _(name=name, ref_obj=ref_obj):
+                    if to_value(ref_obj):
+                        self.classes(add=name)
+                    else:
+                        self.classes(remove=name)
+
+        elif is_ref(classes) or isinstance(classes, Callable):
+            ref_obj = to_value(classes)  # type: ignore
+
+            if isinstance(ref_obj, dict):
+
+                @self._ui_effect
+                def _():
+                    for name, value in cast(Dict, to_value(classes)).items():  # type: ignore
+                        if value:
+                            self.classes(add=name)
+                        else:
+                            self.classes(remove=name)
+            else:
+                self._bind_single_class(cast(_T_bind_classes_type_single, classes))
+
+        elif isinstance(classes, list):
+            for ref_name in classes:
+                self._bind_single_class(ref_name)
+
+        return self
+
+    def _bind_single_class(self, class_name: _T_bind_classes_type_single):
+        if is_ref(class_name) or isinstance(class_name, Callable):
+
+            @on(class_name)
+            def _(state: WatchedState):
+                self.classes(add=state.current, remove=state.previous)
+        else:
+            self.classes(class_name)  # type: ignore
+
+        return self
+
+    def bind_style(self, style: Dict[str, TGetterOrReadonlyRef[Any]]):
+        """data binding is manipulating an element's style
+
+        @see - https://github.com/CrystalWindSnake/ex4nicegui/blob/main/README.en.md#bind-style
+        @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#bind-style
+
+        Args:
+            style (Dict[str, Union[ReadonlyRef[str], Ref[str]]]): dict of style name and ref value
+
+
+        ## usage
+
+        .. 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():
+                if is_ref(ref_obj) or isinstance(ref_obj, Callable):
+
+                    @self._ui_effect
+                    def _(name=name, ref_obj=ref_obj):
+                        self.element._style[name] = str(to_value(ref_obj))
+                        self.element.update()
+
+        return self
+
+    def scoped_style(self, selector: str, style: Union[str, Path]):
+        """add scoped style to the element
+
+        @see - https://github.com/CrystalWindSnake/ex4nicegui/blob/main/README.en.md#scoped_style
+        @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#scoped_style
+
+        Args:
+            selector (str): css selector
+            style (Union[str, Path]): path to css file or inline style string
+
+        ## usage
+
+        .. 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)
+
+        if is_css_file:
+            style = style.read_text(encoding="utf-8")
+
+        id = f"c{self.element.id}"
+        selector_with_self = _utils._parent_id_with_selector(id, selector, is_css_file)
+        css = ""
+        if is_css_file:
+            css = f"{selector_with_self} {style}"
+        else:
+            css = f"{selector_with_self}{{{style}}}"
+
+        scope_style = ScopedStyle.get()
+        assert scope_style, "can not find scope style"
+        scope_style.create_style(self.element, css)
+        self.__used_scope_style = True
+        return self
+
+    def update(self):
+        """Update the element on the client side."""
+        self.element.update()
+
+
+class _utils:
+    @staticmethod
+    def _parent_id_with_selector(
+        parent_id: str, selector: str, is_css_file=False
+    ) -> str:
+        selector_with_self = f"#{parent_id}"
+
+        selector = selector.strip()
+        if (not selector) and (not is_css_file):
+            selector = "* "
+
+        if selector.startswith(":self"):
+            selector = selector[5:].lstrip()
+            parent_selector = f"#{parent_id}"
+            if selector.startswith(":"):
+                parent_selector = f"{parent_selector}{selector.split()[0]}"
+
+            selector_with_self = f"{parent_selector},{selector_with_self}"
+
+        if not selector.startswith(":"):
+            selector_with_self = selector_with_self + " "
+
+        selector_with_self = selector_with_self + selector
+        return selector_with_self
+
+
+DisableableBindableUi = DisableableMixin

ex4nicegui/reactive/deferredTask.py

@@ -14,10 +14,11 @@ class DeferredTask:
             for task in self._tasks:
                 task()
 
-            self._tasks.clear()
-
             # Avoid events becoming ineffective due to page refresh when sharing the client.
             if not client.shared:
+                # In a shared page, execution is required with every refresh.
+                # note:https://github.com/CrystalWindSnake/ex4nicegui/issues/227
+                self._tasks.clear()
                 client.connect_handlers.remove(on_client_connect)  # type: ignore
 
         ui.context.client.on_connect(on_client_connect)