ex4nicegui 0.6.7__tar.gz → 0.6.8__tar.gz

{ex4nicegui-0.6.7 → ex4nicegui-0.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ex4nicegui
-Version: 0.6.7
+Version: 0.6.8
 Summary: Extension library based on nicegui, providing data responsive,BI functionality modules
 Home-page: https://github.com/CrystalWindSnake/ex4nicegui
 License: MIT
@@ -604,7 +604,7 @@ rxui.label("bind to ref_computed").bind_classes(
 
 ---
 
-绑定为列表
+绑定为列表或单个字符串的响应式变量
 
 ```python
 bg_color = to_ref("red")
@@ -617,10 +617,11 @@ rxui.select(["red", "green", "yellow"], label="bg color", value=bg_color)
 rxui.select(["red", "green", "yellow"], label="text color", value=text_color)
 
 rxui.label("binding to arrays").bind_classes([bg_color_class, text_color_class])
-
+rxui.label("binding to single string").bind_classes(bg_color_class)
 ```
 
-列表中每个元素为返回类名的响应式变量
+- 列表中每个元素为返回类名的响应式变量
+
 
 ---
 
@@ -887,6 +888,34 @@ rxui.radio(names, value=current_tab).props("inline")
 
 rxui.label(lambda: f"当前 tab 为:{current_tab.value}")
 ```
+---
+
+### scoped_style
+
+`scoped_style` 方法允许你创建限定在组件内部的样式。
+
+```python
+# 所有子元素都会有红色轮廓，但排除自身
+with rxui.row().scoped_style("*", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+
+
+# 所有子元素都会有红色轮廓，包括自身
+with rxui.row().scoped_style(":self *", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+
+# 当鼠标悬停在 row 组件时,所有子元素都会有红色轮廓，但排除自身
+with rxui.row().scoped_style(":hover *", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+
+# 当鼠标悬停在 row 组件时,所有子元素都会有红色轮廓，包括自身
+with rxui.row().scoped_style(":self:hover *", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+```
 
 
 ---

{ex4nicegui-0.6.7 → ex4nicegui-0.6.8}/README.md

@@ -581,7 +581,7 @@ rxui.label("bind to ref_computed").bind_classes(
 
 ---
 
-绑定为列表
+绑定为列表或单个字符串的响应式变量
 
 ```python
 bg_color = to_ref("red")
@@ -594,10 +594,11 @@ rxui.select(["red", "green", "yellow"], label="bg color", value=bg_color)
 rxui.select(["red", "green", "yellow"], label="text color", value=text_color)
 
 rxui.label("binding to arrays").bind_classes([bg_color_class, text_color_class])
-
+rxui.label("binding to single string").bind_classes(bg_color_class)
 ```
 
-列表中每个元素为返回类名的响应式变量
+- 列表中每个元素为返回类名的响应式变量
+
 
 ---
 
@@ -864,6 +865,34 @@ rxui.radio(names, value=current_tab).props("inline")
 
 rxui.label(lambda: f"当前 tab 为:{current_tab.value}")
 ```
+---
+
+### scoped_style
+
+`scoped_style` 方法允许你创建限定在组件内部的样式。
+
+```python
+# 所有子元素都会有红色轮廓，但排除自身
+with rxui.row().scoped_style("*", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+
+
+# 所有子元素都会有红色轮廓，包括自身
+with rxui.row().scoped_style(":self *", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+
+# 当鼠标悬停在 row 组件时,所有子元素都会有红色轮廓，但排除自身
+with rxui.row().scoped_style(":hover *", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+
+# 当鼠标悬停在 row 组件时,所有子元素都会有红色轮廓，包括自身
+with rxui.row().scoped_style(":self:hover *", "outline: 1px solid red;") as row:
+    ui.label("Hello")
+    ui.label("World")
+```
 
 
 ---

{ex4nicegui-0.6.7 → ex4nicegui-0.6.8}/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-0.6.8/ex4nicegui/gsap/__init__.py

@@ -0,0 +1,23 @@
+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_",
+    "to",
+    "new",
+    "run_script",
+    "timeline",
+]

ex4nicegui-0.6.8/ex4nicegui/helper/__init__.py

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

ex4nicegui-0.6.8/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-0.6.7 → ex4nicegui-0.6.8}/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-0.6.7 → ex4nicegui-0.6.8}/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-0.6.7 → ex4nicegui-0.6.8}/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-0.6.7 → ex4nicegui-0.6.8}/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-0.6.7 → ex4nicegui-0.6.8}/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()