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

ex4nicegui/__init__.py

@@ -1,6 +1,13 @@
 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.scheduler import next_tick
 from ex4nicegui.utils.signals import (
-    ref_computed,
     effect,
     effect_refreshable,
     to_raw,
@@ -10,9 +17,6 @@ from ex4nicegui.utils.signals import (
     ref,
     on,
     event_batch,
-    _TMaybeRef as TMaybeRef,
-    Ref,
-    ReadonlyRef,
     reactive,
     deep_ref,
     is_setter_ref,
@@ -21,6 +25,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 +41,7 @@ __all__ = [
     "on",
     "event_batch",
     "TMaybeRef",
+    "TGetterOrReadonlyRef",
     "Ref",
     "ReadonlyRef",
     "reactive",
@@ -44,6 +50,6 @@ __all__ = [
     "to_raw",
     "is_setter_ref",
     "new_scope",
+    "next_tick",
+    "__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, Optional, 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, client: Optional[Client] = None):
+        if not ui.context.slot_stack:
+            return None
+
+        client = client or ui.context.client
+        if client not in self._client_instances:
+            self._client_instances[client] = self._factory()
+
+            @client.on_disconnect
+            def _():
+                self._client_instances.pop(client, None)
+
+        return self._client_instances[client]

ex4nicegui/reactive/__init__.py

@@ -51,7 +51,9 @@ 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 .local_file_picker import local_file_picker
 from .UseDraggable.UseDraggable import use_draggable
@@ -70,6 +72,7 @@ pagination = q_pagination
 __all__ = [
     "element",
     "tab_panels",
+    "lazy_tab_panels",
     "tab_panel",
     "tabs",
     "tab",
@@ -120,4 +123,5 @@ __all__ = [
     "q_pagination",
     "pagination",
     "mermaid",
+    "chip",
 ]

ex4nicegui/reactive/base.py

@@ -0,0 +1,426 @@
+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 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: str) -> Self:
+        cast(ui.element, self.element).tooltip(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, 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)
+
+        if prop == "text" and isinstance(self.element, TextElement):
+
+            @self._ui_effect
+            def _():
+                cast(TextElement, self.element).set_text(to_value(ref_ui))
+                self.element.update()
+
+        @self._ui_effect
+        def _():
+            element = cast(ui.element, self.element)
+            element._props[prop] = to_value(ref_ui)
+            element.update()
+
+        return self
+
+    def bind_visible(self, ref_ui: TGetterOrReadonlyRef[bool]):
+        @self._ui_effect
+        def _():
+            element = cast(ui.element, self.element)
+            element.set_visibility(to_value(ref_ui))
+
+        return self
+
+    def bind_not_visible(self, ref_ui: TGetterOrReadonlyRef[bool]):
+        return self.bind_visible(lambda: not to_value(ref_ui))
+
+    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]]):
+        ...
+
+    @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
+
+        @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:
+
+            ```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():
+
+                @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
+        ```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
+        ```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)

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/mixins/backgroundColor.py

@@ -0,0 +1,41 @@
+from typing import (
+    Any,
+    Callable,
+    Protocol,
+)
+
+import signe
+from ex4nicegui.utils.signals import (
+    TGetterOrReadonlyRef,
+    WatchedState,
+)
+from nicegui import ui
+from ex4nicegui.reactive.systems import color_system
+
+
+class BackgroundColorableMixin(Protocol):
+    _ui_signal_on: Callable[[Callable[..., Any]], signe.Effect[None]]
+
+    @property
+    def element(self) -> ui.element:
+        ...
+
+    def _bind_background_color(self, ref_ui: TGetterOrReadonlyRef[str]):
+        @self._ui_signal_on(ref_ui)  # type: ignore
+        def _(state: WatchedState):
+            if state.previous is not None:
+                color_system.remove_background_color(self.element, state.previous)
+
+            color_system.add_background_color(self.element, state.current)
+
+            self.element.update()
+
+    def bind_color(self, ref_ui: TGetterOrReadonlyRef[str]):
+        """bind color to the element
+
+        Args:
+            ref_ui (TGetterOrReadonlyRef[str]): a reference to the color value
+
+        """
+        self._bind_background_color(ref_ui)
+        return self

ex4nicegui/reactive/mixins/disableable.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Callable,
+    Protocol,
+    TypeVar,
+)
+
+import signe
+from ex4nicegui.utils.signals import (
+    TGetterOrReadonlyRef,
+    to_value,
+)
+from nicegui.elements.mixins.disableable_element import DisableableElement
+
+
+_T_DisableableBinder = TypeVar("_T_DisableableBinder", bound=DisableableElement)
+
+
+class DisableableMixin(Protocol):
+    _ui_effect: Callable[[Callable[..., Any]], signe.Effect[None]]
+
+    @property
+    def element(self) -> DisableableElement:
+        ...
+
+    def bind_enabled(self, ref_ui: TGetterOrReadonlyRef[bool]):
+        @self._ui_effect
+        def _():
+            value = to_value(ref_ui)
+            self.element.set_enabled(value)
+            self.element._handle_enabled_change(value)
+
+        return self
+
+    def bind_disable(self, ref_ui: TGetterOrReadonlyRef[bool]):
+        @self._ui_effect
+        def _():
+            value = not to_value(ref_ui)
+            self.element.set_enabled(value)
+            self.element._handle_enabled_change(value)
+
+        return self