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

ex4nicegui/__init__.py

@@ -1,6 +1,12 @@
 from ex4nicegui import reactive as rxui
+from ex4nicegui.utils.refComputed import ref_computed
+from ex4nicegui.utils.types import (
+    _TMaybeRef as TMaybeRef,
+    Ref,
+    ReadonlyRef,
+    TGetterOrReadonlyRef,
+)
 from ex4nicegui.utils.signals import (
-    ref_computed,
     effect,
     effect_refreshable,
     to_raw,
@@ -10,9 +16,6 @@ from ex4nicegui.utils.signals import (
     ref,
     on,
     event_batch,
-    _TMaybeRef as TMaybeRef,
-    Ref,
-    ReadonlyRef,
     reactive,
     deep_ref,
     is_setter_ref,
@@ -21,6 +24,7 @@ from ex4nicegui.utils.signals import (
 )
 from ex4nicegui.utils.asyncComputed import async_computed
 from ex4nicegui.utils.clientScope import new_scope
+from .version import __version__
 
 __all__ = [
     "async_computed",
@@ -36,6 +40,7 @@ __all__ = [
     "on",
     "event_batch",
     "TMaybeRef",
+    "TGetterOrReadonlyRef",
     "Ref",
     "ReadonlyRef",
     "reactive",
@@ -44,6 +49,5 @@ __all__ = [
     "to_raw",
     "is_setter_ref",
     "new_scope",
+    "__version__",
 ]
-
-__version__ = "0.6.6"

ex4nicegui/gsap/__init__.py

@@ -2,6 +2,17 @@ from .gsap import set_defaults, from_, to, new, run_script
 from .timeline import Timeline as timeline
 
 
+import warnings
+
+RED = "\033[91m"
+RESET = "\033[0m"
+
+warnings.warn(
+    f"{RED}The gsap module is deprecated and will be removed in the next major version.{RESET}",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
 __all__ = [
     "set_defaults",
     "from_",

ex4nicegui/helper/__init__.py

@@ -0,0 +1,4 @@
+from .client_instance_locker import ClientInstanceLocker
+
+
+__all__ = ["ClientInstanceLocker"]

ex4nicegui/helper/client_instance_locker.py

@@ -0,0 +1,31 @@
+from typing import Callable, TypeVar, Generic
+from nicegui import ui, Client
+from weakref import WeakKeyDictionary
+
+
+_T = TypeVar("_T")
+
+
+class ClientInstanceLocker(Generic[_T]):
+    def __init__(self, factory: Callable[[], _T]):
+        """Creates a new instance locker that creates a new instance for each client.
+
+        Args:
+            factory (Callable[[], _T]):  A factory function that creates a new instance.
+        """
+        self._client_instances: WeakKeyDictionary[Client, _T] = WeakKeyDictionary()
+        self._factory = factory
+
+    def get_object(self):
+        if not ui.context.slot_stack:
+            return None
+
+        client = 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]
+
+        return self._client_instances[client]

ex4nicegui/reactive/local_file_picker.py

@@ -6,7 +6,6 @@ from pathlib import Path
 from ex4nicegui.utils.signals import (
     Ref,
     effect_refreshable,
-    ReadonlyRef,
     effect,
     ref_computed as computed,
     to_ref,
@@ -17,7 +16,7 @@ SelectMode = Literal["dir", "file"]
 
 
 class LocalFilePickerResult:
-    def __init__(self, ref: ReadonlyRef[str], open_fn: Callable[..., None]) -> None:
+    def __init__(self, ref: Ref[str], open_fn: Callable[..., None]) -> None:
         self.__open_fn = open_fn
         self._ref = ref
 

ex4nicegui/reactive/officials/aggrid.py

@@ -9,13 +9,13 @@ from ex4nicegui.utils.signals import (
     is_ref,
     ref_computed,
     to_value,
-    _TMaybeRef as TMaybeRef,
+    TMaybeRef,
     TGetterOrReadonlyRef,
 )
-from ex4nicegui.utils.apiEffect import ui_effect
 from nicegui import ui
 from .base import BindableUi
-from ex4nicegui.reactive.utils import ParameterClassifier, dataframe2col_str
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
+from ex4nicegui.reactive.services.pandas_service import dataframe2col_str
 
 
 class AggridBindableUi(BindableUi[ui.aggrid]):
@@ -85,7 +85,7 @@ class AggridBindableUi(BindableUi[ui.aggrid]):
         return super().bind_prop(prop, ref_ui)
 
     def bind_options(self, ref_ui: TGetterOrReadonlyRef[List[Dict]]):
-        @ui_effect
+        @self._ui_effect
         def _():
             ele = self.element
             data = to_value(ref_ui)

ex4nicegui/reactive/officials/base.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from pathlib import Path
 from typing import (
     Any,
     Callable,
@@ -11,7 +12,7 @@ from typing import (
     Generic,
     Union,
     cast,
-    Literal,
+    overload,
 )
 
 from typing_extensions import Self
@@ -19,21 +20,18 @@ from ex4nicegui.utils.apiEffect import ui_effect
 import signe
 from ex4nicegui.utils.signals import (
     TGetterOrReadonlyRef,
-    effect,
     to_value,
     is_ref,
     WatchedState,
     on,
 )
+from ex4nicegui.utils.clientScope import new_scope
 from nicegui import Tailwind, ui
-from nicegui.elements.mixins.color_elements import (
-    TextColorElement,
-    QUASAR_COLORS,
-    TAILWIND_COLORS,
-)
 from nicegui.elements.mixins.text_element import TextElement
 from nicegui.elements.mixins.disableable_element import DisableableElement
-
+from ex4nicegui.reactive.services.reactive_service import inject_handle_delete
+from ex4nicegui.reactive.scopedStyle import ScopedStyle
+from functools import partial
 
 T = TypeVar("T")
 
@@ -42,21 +40,38 @@ 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_array = List[TGetterOrReadonlyRef[str]]
+_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_array
+    _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()
 
-    def _ui_effect(self, fn: Callable):
-        return ui_effect(fn)
+    def _on_element_delete(self):
+        self._effect_scope.dispose()
+        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)
@@ -108,7 +123,7 @@ class BindableUi(Generic[TWidget]):
 
     def delete(self) -> None:
         """Delete the element."""
-        self.delete()
+        self.element.delete()
 
     def move(
         self, target_container: Optional[ui.element] = None, target_index: int = -1
@@ -118,7 +133,7 @@ class BindableUi(Generic[TWidget]):
         :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.move(target_container, target_index)
+        return self.element.move(target_container, target_index)
 
     def remove(self, element: Union[ui.element, int]) -> None:
         """Remove a child element.
@@ -192,6 +207,22 @@ class BindableUi(Generic[TWidget]):
     def clear(self) -> None:
         cast(ui.element, self.element).clear()
 
+    @overload
+    def bind_classes(self, classes: Dict[str, TGetterOrReadonlyRef[bool]]):
+        ...
+
+    @overload
+    def bind_classes(self, classes: TGetterOrReadonlyRef[Dict[str, bool]]):
+        ...
+
+    @overload
+    def bind_classes(self, classes: List[TGetterOrReadonlyRef[str]]):
+        ...
+
+    @overload
+    def bind_classes(self, classes: TGetterOrReadonlyRef[str]):
+        ...
+
     def bind_classes(self, classes: _T_bind_classes_type):
         """data binding is manipulating an element's class list
 
@@ -199,7 +230,37 @@ class BindableUi(Generic[TWidget]):
         @中文文档 - 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):
+            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:
+
+            ```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
+            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
+            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():
@@ -213,24 +274,33 @@ class BindableUi(Generic[TWidget]):
 
         elif is_ref(classes) or isinstance(classes, Callable):
             ref_obj = to_value(classes)  # type: ignore
-            assert isinstance(ref_obj, dict)
 
-            @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)
+            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:
-                if is_ref(ref_name) or isinstance(ref_name, Callable):
+                self._bind_single_class(ref_name)
 
-                    @on(ref_name)
-                    def _(state: WatchedState):
-                        self.classes(add=state.current, remove=state.previous)
-                else:
-                    self.classes(ref_name)  # type: ignore
+        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
 
@@ -241,7 +311,21 @@ class BindableUi(Generic[TWidget]):
         @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#bind-style
 
         Args:
-            style (Dict[str, Union[ReadonlyRef[str], Ref[str]]]): _description_
+            style (Dict[str, Union[ReadonlyRef[str], Ref[str]]]): dict of style name and ref value
+
+
+        ## usage
+        ```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():
@@ -254,26 +338,88 @@ class BindableUi(Generic[TWidget]):
 
         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
+        ```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)
+
+        return self
+
     def update(self):
         """Update the element on the client side."""
         self.element.update()
 
 
-# class SingleValueBindableUi(BindableUi[TWidget], Generic[T, TWidget]):
-#     def __init__(self, value: TMaybeRef[T], element: TWidget) -> None:
-#         super().__init__(element)
-#         self._ref = to_ref(value)
+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]}"
 
-#     @property
-#     def value(self) -> T:
-#         return self._ref.value  # type: ignore
+            selector_with_self = f"{parent_selector},{selector_with_self}"
 
-#     def bind_ref(self, ref: TRef[T]):
-#         @effect
-#         def _():
-#             ref.value = self._ref.value  # type: ignore
+        if not selector.startswith(":"):
+            selector_with_self = selector_with_self + " "
 
-#         return self
+        selector_with_self = selector_with_self + selector
+        return selector_with_self
 
 
 _T_DisableableBinder = TypeVar("_T_DisableableBinder", bound=DisableableElement)
@@ -306,47 +452,3 @@ class DisableableMixin(Protocol):
 
 
 DisableableBindableUi = DisableableMixin
-
-
-_color_sys_type = Literal["QUASAR", "TAILWIND", "STYLE"]
-_color_attr_name = "data-ex4ng-color"
-
-
-def _bind_color(bindable_ui: BindableUi, ref_ui: TGetterOrReadonlyRef):
-    @effect
-    def _():
-        ele = cast(TextColorElement, bindable_ui.element)
-        color = to_value(ref_ui)
-
-        # get exists color
-        # e.g 'QUASAR:red'
-        pre_color = ele._props.get(_color_attr_name)  # type: str | None
-        if pre_color:
-            color_sys, value = pre_color.split(":")  # type: ignore
-            color_sys: _color_sys_type
-
-            if color_sys == "QUASAR":
-                del ele._props[ele.TEXT_COLOR_PROP]
-            elif color_sys == "TAILWIND":
-                ele.classes(remove=value)
-            else:
-                del ele._style["color"]
-
-        cur_sys: _color_sys_type = "STYLE"
-        cur_color = color
-
-        if color in QUASAR_COLORS:
-            ele._props[ele.TEXT_COLOR_PROP] = color
-            cur_sys = "QUASAR"
-        elif color in TAILWIND_COLORS:
-            cur_color = f"text-{color}"
-            ele.classes(replace=cur_color)
-            cur_sys = "TAILWIND"
-        elif color is not None:
-            ele._style["color"] = color
-
-        ele._props[_color_attr_name] = f"{cur_sys}:{color}"
-
-        ele.update()
-
-    return bindable_ui

ex4nicegui/reactive/officials/button.py

@@ -3,7 +3,7 @@ from typing import (
     Callable,
     Optional,
 )
-from ex4nicegui.reactive.utils import ParameterClassifier
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
 from ex4nicegui.utils.signals import (
     TGetterOrReadonlyRef,
     _TMaybeRef as TMaybeRef,

ex4nicegui/reactive/officials/checkbox.py

@@ -4,8 +4,7 @@ from typing import (
     Optional,
     TypeVar,
 )
-from ex4nicegui.reactive.utils import ParameterClassifier
-from ex4nicegui.utils.apiEffect import ui_effect
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
 from ex4nicegui.utils.signals import (
     TGetterOrReadonlyRef,
     _TMaybeRef as TMaybeRef,
@@ -51,7 +50,7 @@ class CheckboxBindableUi(BindableUi[ui.checkbox], DisableableMixin):
         return super().bind_prop(prop, ref_ui)
 
     def bind_value(self, ref_ui: TGetterOrReadonlyRef[bool]):
-        @ui_effect
+        @self._ui_effect
         def _():
             self.element.set_value(to_value(ref_ui))
             self.element.update()

ex4nicegui/reactive/officials/circular_progress.py

@@ -1,8 +1,7 @@
 from typing import (
     Optional,
 )
-from ex4nicegui.reactive.utils import ParameterClassifier
-from ex4nicegui.utils.apiEffect import ui_effect
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
 
 from ex4nicegui.utils.signals import (
     TGetterOrReadonlyRef,
@@ -57,7 +56,7 @@ class CircularProgressBindableUi(
         return super().bind_prop(prop, ref_ui)
 
     def bind_value(self, ref_ui: TGetterOrReadonlyRef[float]):
-        @ui_effect
+        @self._ui_effect
         def _():
             self.element.set_value(to_value(ref_ui))
 

ex4nicegui/reactive/officials/color_picker.py

@@ -4,8 +4,7 @@ from typing import (
     Optional,
     cast,
 )
-from ex4nicegui.reactive.utils import ParameterClassifier
-from ex4nicegui.utils.apiEffect import ui_effect
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
 
 from ex4nicegui.utils.signals import (
     TGetterOrReadonlyRef,
@@ -76,14 +75,14 @@ class ColorPickerBindableUi(BindableUi[ui.color_picker]):
         return super().bind_prop(prop, ref_ui)
 
     def bind_color(self, ref_ui: TGetterOrReadonlyRef[str]):
-        @ui_effect
+        @self._ui_effect
         def _():
             self.element.set_color(to_value(ref_ui))
 
         return self
 
     def bind_value(self, ref_ui: TGetterOrReadonlyRef[bool]):
-        @ui_effect
+        @self._ui_effect
         def _():
             self.element.set_value(to_value(ref_ui))
 

ex4nicegui/reactive/officials/column.py

@@ -1,7 +1,7 @@
 from typing import (
     Any,
 )
-from ex4nicegui.reactive.utils import ParameterClassifier
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
 from ex4nicegui.utils.signals import (
     TGetterOrReadonlyRef,
     _TMaybeRef as TMaybeRef,

ex4nicegui/reactive/officials/date.py

@@ -1,7 +1,6 @@
 from typing import Any, Callable, List, Optional, TypeVar
 from typing_extensions import TypedDict
-from ex4nicegui.reactive.utils import ParameterClassifier
-from ex4nicegui.utils.apiEffect import ui_effect
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
 
 from ex4nicegui.utils.signals import (
     TGetterOrReadonlyRef,
@@ -70,7 +69,7 @@ class DateBindableUi(BindableUi[ui.date]):
         return super().bind_prop(prop, ref_ui)
 
     def bind_value(self, ref_ui: TGetterOrReadonlyRef[bool]):
-        @ui_effect
+        @self._ui_effect
         def _():
             self.element.set_value(to_value(ref_ui))
 

ex4nicegui/reactive/officials/drawer.py

@@ -2,8 +2,7 @@ from typing import (
     Any,
 )
 from typing_extensions import Literal
-from ex4nicegui.reactive.utils import ParameterClassifier
-from ex4nicegui.utils.apiEffect import ui_effect
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
 
 from ex4nicegui.utils.signals import (
     is_setter_ref,
@@ -61,7 +60,7 @@ class DrawerBindableUi(BindableUi[Drawer]):
 
         super().__init__(element)  # type: ignore
 
-        @ui_effect
+        @self._ui_effect
         def _():
             mvalue = "true" if to_value(value) else "false"
             element.props(f":model-value={mvalue}")

ex4nicegui/reactive/officials/echarts.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Union, cast, Optional, Literal
-from ex4nicegui.reactive.utils import ParameterClassifier
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
 from ex4nicegui.utils.signals import (
     TGetterOrReadonlyRef,
     is_ref,
@@ -8,7 +8,6 @@ from ex4nicegui.utils.signals import (
     _TMaybeRef as TMaybeRef,
     to_value,
     to_raw,
-    on,
 )
 from .base import BindableUi
 from ex4nicegui.reactive.EChartsComponent.ECharts import echarts
@@ -141,7 +140,7 @@ class EChartsBindableUi(BindableUi[echarts]):
         return super().bind_prop(prop, ref_ui)
 
     def bind_options(self, ref_ui: TGetterOrReadonlyRef[Dict]):
-        @on(ref_ui)
+        @self._ui_signal_on(ref_ui)
         def _():
             ele = self.element
             ele.update_options(to_raw(to_value(ref_ui)), self.__update_setting)