ex4nicegui 0.6.6__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/libs/gsap/gsap.mjs

@@ -0,0 +1,6 @@
+import { gsap, Power0, Power1, Power2, Power3, Power4, Linear, Quad, Cubic, Quart, Quint, Strong, Elastic, Back, SteppedEase, Bounce, Sine, Expo, Circ, TweenLite, TimelineLite, TimelineMax } from "./gsap-core.js";
+import { CSSPlugin } from "./CSSPlugin.js";
+var gsapWithCSS = gsap.registerPlugin(CSSPlugin) || gsap,
+    // to protect from tree shaking
+TweenMaxWithCSS = gsapWithCSS.core.Tween;
+export { gsapWithCSS as gsap, gsapWithCSS as default, CSSPlugin, TweenMaxWithCSS as TweenMax, TweenLite, TimelineMax, TimelineLite, Power0, Power1, Power2, Power3, Power4, Linear, Quad, Cubic, Quart, Quint, Strong, Elastic, Back, SteppedEase, Bounce, Sine, Expo, Circ };

ex4nicegui/reactive/EChartsComponent/ECharts.js

@@ -5,13 +5,23 @@ function collectMapRegisterTask() {
 
   if (typeof window.ex4ngEchartsMapTasks !== "undefined") {
 
-    for (const [mapName, src] of window.ex4ngEchartsMapTasks.entries()) {
-
+    for (const [mapName, opt] of window.ex4ngEchartsMapTasks.entries()) {
+      const { src, type: mapDataType, specialAreas } = opt;
       const registerPromise = new Promise((resolve, reject) => {
         fetch(src)
-          .then((response) => response.json())
+          .then((response) => {
+            if (mapDataType === "genJSON") {
+              return response.json();
+            }
+
+            return response.text();
+          })
           .then((data) => {
-            echarts.registerMap(mapName, data);
+            if (mapDataType === "svg") {
+              data = { svg: data }
+            }
+
+            echarts.registerMap(mapName, data, specialAreas);
             resolve();
           });
 
@@ -46,10 +56,6 @@ export default {
   async mounted() {
     await this.$nextTick(); // wait for Tailwind classes to be applied
 
-    if (hasMapOrGeo(this.options)) {
-      await Promise.all(Array.from(mapRegisterTasks.values()));
-    }
-
     this.chart = echarts.init(this.$el, this.theme);
 
     this.resizeObs = new ResizeObserver(this.chart.resize)
@@ -63,10 +69,14 @@ export default {
     this.chart.on("finished", createResizeObserver);
 
     if (this.options) {
+      if (hasMapOrGeo(this.options)) {
+        await Promise.all(Array.from(mapRegisterTasks.values()));
+      }
       this.update_chart();
     } else {
       const fn = new Function('return ' + this.code)()
-      fn(this.chart)
+      await Promise.all(Array.from(mapRegisterTasks.values()));
+      fn(this.chart, echarts)
       this.$emit("__update_options_from_client", this.chart.getOption())
     }
     this.chart.getZr().on("click", (e) => {

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

@@ -6,16 +6,16 @@ from typing import (
     Optional,
 )
 from ex4nicegui.utils.signals import (
-    ReadonlyRef,
     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]):
@@ -78,14 +78,14 @@ class AggridBindableUi(BindableUi[ui.aggrid]):
         options = {"columnDefs": columnDefs, "rowData": rowData}
         return cls(options, **org_kws)
 
-    def bind_prop(self, prop: str, ref_ui: ReadonlyRef[Any]):
+    def bind_prop(self, prop: str, ref_ui: TGetterOrReadonlyRef[Any]):
         if prop == "options":
             return self.bind_options(ref_ui)
 
         return super().bind_prop(prop, ref_ui)
 
-    def bind_options(self, ref_ui: ReadonlyRef[List[Dict]]):
-        @ui_effect
+    def bind_options(self, ref_ui: TGetterOrReadonlyRef[List[Dict]]):
+        @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.
@@ -128,6 +143,16 @@ class BindableUi(Generic[TWidget]):
         return self.element.remove(element)
 
     def bind_prop(self, prop: str, ref_ui: 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
+            ref_ui (TGetterOrReadonlyRef[Any]): a reference to the value to bind to
+
+        """
         if prop == "visible":
             return self.bind_visible(ref_ui)
 
@@ -182,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
 
@@ -189,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():
@@ -203,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)
+
+        return self
 
-                    @on(ref_name)
-                    def _(state: WatchedState):
-                        self.classes(add=state.current, remove=state.previous)
-                else:
-                    self.classes(ref_name)  # type: ignore
+    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
 
@@ -231,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():
@@ -244,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)
@@ -296,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,9 +3,9 @@ from typing import (
     Callable,
     Optional,
 )
-from ex4nicegui.reactive.utils import ParameterClassifier
+from ex4nicegui.reactive.services.reactive_service import ParameterClassifier
 from ex4nicegui.utils.signals import (
-    ReadonlyRef,
+    TGetterOrReadonlyRef,
     _TMaybeRef as TMaybeRef,
     to_value,
 )
@@ -33,7 +33,7 @@ class ButtonBindableUi(BindableUi[ui.button], DisableableMixin):
         for key, value in pc.get_bindings().items():
             self.bind_prop(key, value)  # type: ignore
 
-    def bind_prop(self, prop: str, ref_ui: ReadonlyRef):
+    def bind_prop(self, prop: str, ref_ui: TGetterOrReadonlyRef):
         if prop == "text":
             return self.bind_text(ref_ui)
         if prop == "icon":
@@ -41,7 +41,7 @@ class ButtonBindableUi(BindableUi[ui.button], DisableableMixin):
 
         return super().bind_prop(prop, ref_ui)
 
-    def bind_text(self, ref_ui: ReadonlyRef):
+    def bind_text(self, ref_ui: TGetterOrReadonlyRef):
         @self._ui_effect
         def _():
             ele = self.element
@@ -50,7 +50,7 @@ class ButtonBindableUi(BindableUi[ui.button], DisableableMixin):
 
         return self
 
-    def bind_icon(self, ref_ui: ReadonlyRef):
+    def bind_icon(self, ref_ui: TGetterOrReadonlyRef[str]):
         @self._ui_effect
         def _():
             ele = self.element