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

ex4nicegui/reactive/vfor.py

@@ -3,7 +3,7 @@ from nicegui.element import Element
 from nicegui import ui
 from ex4nicegui.utils.clientScope import _CLIENT_SCOPE_MANAGER
 from ex4nicegui.utils.signals import (
-    TReadonlyRef,
+    Ref,
     on,
     to_ref,
     to_ref_wrapper,
@@ -21,7 +21,7 @@ from typing import (
     TypeVar,
     Generic,
     Union,
-    cast,
+    Literal,
 )
 from functools import partial
 from dataclasses import dataclass
@@ -38,35 +38,90 @@ class VforItem(Empty):
 
 
 class VforContainer(Element, component="vfor.js"):
-    def __init__(self) -> None:
+    def __init__(self, transition_props: Optional[Dict[str, Any]] = None) -> None:
         super().__init__()
         self._props["itemIds"] = []
 
+        if transition_props:
+            self._props["transitionProps"] = transition_props
+
     def update_items(self, item_ids: List[Dict]):
         self._props["itemIds"] = item_ids
         self.update()
 
 
+def wrapper_getter_setter(ref: Ref, index: Ref[int], *keys: Union[str, int]):
+    proxy = ref.value
+
+    def getter():
+        item = proxy[index.value]
+        result = item
+
+        for k in keys:
+            result = result[k]
+        return result
+
+    def setter(value):
+        item = proxy[index.value]
+
+        if len(keys) == 0:
+            proxy[index.value] = value
+
+        if len(keys) == 1:
+            item[keys[0]] = value
+            return
+
+        obj = item[keys[0]]
+        for k in keys[1:-1]:
+            obj = obj[k]
+        obj[keys[-1]] = value
+
+    return getter, setter
+
+
+class VforStoreItem(Generic[_T], RefWrapper[_T]):
+    def __init__(
+        self,
+        source: _T_data,
+        index: Ref[int],
+        keys: Optional[List[Union[str, int]]] = None,
+    ) -> None:
+        self._source = source
+        self._data_index = index
+        self._keys = keys or []
+
+        getter, setter = wrapper_getter_setter(source, index, *self._keys)
+        super().__init__(getter, setter)
+
+    def __getitem__(self, key: Union[str, int]):
+        return VforStoreItem(self._source, self._data_index, self._keys + [key])
+
+
 class VforStore(Generic[_T]):
     def __init__(self, source: _T_data, index: int) -> None:
         self._source = source
+        self._raw_index = index
         self._data_index = to_ref(index)
 
     @property
     def row_index(self):
+        """Returns the responsive index of the current row."""
         return self._data_index
 
-    def get(self) -> TReadonlyRef[_T]:
-        def base_setter(value):
-            to_value(self._source)[self._data_index.value] = value
+    @property
+    def raw_index(self):
+        """Returns the index of the current row."""
+        return self._raw_index
 
-        wrapper = to_ref_wrapper(
-            lambda: to_value(self._source)[self._data_index.value],
-            base_setter,
-        )
-        wrapper._is_readonly = True
+    def get_item(self) -> _T:
+        """Returns the current item."""
+        return to_value(self._source)[self.raw_index]  # type: ignore
 
-        return cast(TReadonlyRef, wrapper)
+    def get(self) -> Ref[_T]:
+        """Returns a ref object of the current item.
+        Suitable for immutable types such as `int`, `str`, `float`, etc.
+        """
+        return VforStoreItem(self._source, self._data_index)  # type: ignore
 
     def update(self, index: int):
         self._data_index.value = index
@@ -80,10 +135,6 @@ class StoreItem:
     scope: Scope
 
 
-def _get_key_with_index(idx: int, data: Any):
-    return idx
-
-
 def _get_key_with_getter(attr: str, idx: int, data: Any):
     return get_attribute(data, attr)
 
@@ -97,28 +148,27 @@ class vfor(Generic[_T]):
 
 
     ## Examples
-    ```python
-    from ex4nicegui.reactive import rxui
-    from ex4nicegui import to_ref
-    items = to_ref(
-        [
-            {"message": "foo", "done": False},
-            {"message": "bar", "done": True},
-        ]
-    )
 
+    .. code-block:: python
+        from ex4nicegui.reactive import rxui
+        from ex4nicegui import to_ref
+        items = to_ref(
+            [
+                {"message": "foo", "done": False},
+                {"message": "bar", "done": True},
+            ]
+        )
 
-    @rxui.vfor(items,key='message')
-    def _(store: rxui.VforStore):
-        msg_ref = store.get("message")  # this is ref object
 
-        # type text into the input box and
-        # the title of the checkbox changes sync
-        with ui.card():
-            rxui.input(value=msg_ref)
-            rxui.checkbox(text=msg_ref, value=store.get("done"))
+        @rxui.vfor(items,key='message')
+        def _(store: rxui.VforStore):
+            msg_ref = store.get("message")  # this is ref object
 
-    ```
+            # type text into the input box and
+            # the title of the checkbox changes sync
+            with ui.card():
+                rxui.input(value=msg_ref)
+                rxui.checkbox(text=msg_ref, value=store.get("done"))
 
     """
 
@@ -128,9 +178,9 @@ class vfor(Generic[_T]):
         *,
         key: Optional[Union[str, Callable[[int, Any], Any]]] = None,
     ) -> None:
-        self._vfor_container = VforContainer()
         self._data = to_ref_wrapper(lambda: data) if is_reactive(data) else data
-        self._get_key = _get_key_with_index
+        self._get_key = vfor.index_key
+        self._transition_props = {}
 
         if isinstance(key, str):
             self._get_key = partial(_get_key_with_getter, key)
@@ -139,11 +189,27 @@ class vfor(Generic[_T]):
 
         self._store_map: Dict[Union[Any, int], StoreItem] = {}
 
+    def transition_group(
+        self,
+        css=True,
+        name: Optional[str] = "list",
+        duration: Optional[float] = None,
+        type: Optional[Literal["transition", "animation"]] = None,
+        mode: Optional[Literal["in-out", "out-in", "default"]] = None,
+        appear=False,
+    ):
+        kws = {k: v for k, v in locals().items() if k != "self" and v is not None}
+        self._transition_props.update(**kws)
+
+        return self
+
     def __call__(self, fn: Callable[[Any], None]):
+        _vfor_container = VforContainer(self._transition_props)
+
         def build_element(index: int, value):
             key = self._get_key(index, value)
 
-            with self._vfor_container, VforItem() as element:
+            with _vfor_container, VforItem() as element:
                 store = VforStore(self._data, index)  # type: ignore
                 scope = _CLIENT_SCOPE_MANAGER.new_scope()
 
@@ -153,18 +219,27 @@ class vfor(Generic[_T]):
 
             return key, element, store, scope
 
-        for idx, value in enumerate(to_value(self._data)):  # type: ignore
-            key, element, store, scope = build_element(idx, value)
-            self._store_map[key] = StoreItem(store, element.id, scope)
-
         ng_client = ui.context.client
 
-        @on(self._data, deep=True)
+        @on(self._data, deep=True, priority_level=-1)
         def _():
             data_map = {
                 self._get_key(idx, d): d for idx, d in enumerate(to_value(self._data))
             }
 
+            # remove item if it's not in the new data
+            remove_items = [
+                (key, value)
+                for key, value in self._store_map.items()
+                if key not in data_map
+            ]
+
+            for key, item in remove_items:
+                target = ng_client.elements.get(item.elementId)
+                _vfor_container.remove(target)  # type: ignore
+                item.scope.dispose()
+                del self._store_map[key]
+
             for idx, (key, value) in enumerate(data_map.items()):
                 store_item = self._store_map.get(key)
                 if store_item:
@@ -177,22 +252,17 @@ class vfor(Generic[_T]):
                     key, element, store, score = build_element(idx, value)
                     self._store_map[key] = StoreItem(store, element.id, score)
 
-            # remove item
-            remove_items = [
-                (key, value)
-                for key, value in self._store_map.items()
-                if key not in data_map
+            item_ids = [
+                {"key": key, "elementId": self._store_map.get(key).elementId}  # type: ignore
+                for key in data_map.keys()
             ]
 
-            for key, item in remove_items:
-                target = ng_client.elements.get(item.elementId)
-                self._vfor_container.remove(target)  # type: ignore
-                item.scope.dispose()
-                del self._store_map[key]
+            _vfor_container.update_items(item_ids)
+
+    @staticmethod
+    def value_key(_, data):
+        return data
 
-            self._vfor_container.update_items(
-                [
-                    {"key": key, "elementId": self._store_map.get(key).elementId}  # type: ignore
-                    for key in data_map.keys()
-                ]
-            )
+    @staticmethod
+    def index_key(idx, _):
+        return idx

ex4nicegui/reactive/view_model.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+from typing import Callable, Union, Type, TypeVar
+from ex4nicegui.utils.signals import (
+    deep_ref,
+    is_ref,
+    to_value,
+    to_ref,
+    on,
+    to_raw,
+    ref_computed as computed,
+    Ref,
+)
+from ex4nicegui.utils.types import ReadonlyRef
+from functools import partial
+from signe.core.reactive import NoProxy
+
+_CACHED_VARS_FLAG = "__vm_cached__"
+
+_T = TypeVar("_T")
+
+
+class ViewModel(NoProxy):
+    """A base class for reactive view models.
+
+    @see - https://github.com/CrystalWindSnake/ex4nicegui/blob/main/README.en.md#ViewModel
+
+    @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#viewmodel
+
+    Example:
+    .. code-block:: python
+        from ex4nicegui import rxui
+
+        class MyVm(rxui.ViewModel):
+            count = rxui.var(0)
+            data = rxui.var(lambda: [1,2,3])
+
+        vm = MyVm()
+
+        rxui.label(vm.count)
+        rxui.number(value=vm.count)
+
+
+    """
+
+    def __init__(self):
+        for name, value in self.__class__.__dict__.items():
+            if is_ref(value):
+                setattr(self, name, deep_ref(to_value(value)))
+            if callable(value) and hasattr(value, _CACHED_VARS_FLAG):
+                setattr(self, name, computed(partial(value, self)))
+
+    @staticmethod
+    def display(model: Union[ViewModel, Type]):
+        result = to_ref("")
+
+        watch_refs = _recursive_to_refs(model)
+
+        all_refs = {
+            key: value for key, value in model.__dict__.items() if is_ref(value)
+        }
+
+        @on(watch_refs)
+        def _():
+            result.value = str(
+                {key: _recursive_to_value(value) for key, value in all_refs.items()}
+            )
+
+        return result
+
+
+def _recursive_to_value(value_or_model):
+    value = to_raw(to_value(value_or_model))
+
+    if isinstance(value, ViewModel):
+        all_refs = {
+            key: value for key, value in value.__dict__.items() if is_ref(value)
+        }
+        return {key: _recursive_to_value(value) for key, value in all_refs.items()}
+    elif isinstance(value, dict):
+        return {key: _recursive_to_value(val) for key, val in value.items()}
+    elif isinstance(value, list):
+        return [_recursive_to_value(val) for val in value]
+    else:
+        return value
+
+
+def _recursive_to_refs(model):
+    result = []
+    stack = [model]
+
+    def handle_ref(value):
+        if is_ref(value):
+            stack.append(value.value)
+            result.append(value)
+
+        elif isinstance(value, (ViewModel, Type)):
+            stack.append(value)
+        elif isinstance(value, dict):
+            stack.append(value)
+
+    while stack:
+        current = stack.pop()
+
+        if isinstance(current, (ViewModel, Type)):
+            for key, value in current.__dict__.items():
+                handle_ref(value)
+
+        elif isinstance(current, dict):
+            for key, value in current.items():
+                handle_ref(value)
+
+        elif isinstance(current, list):
+            for value in current:
+                handle_ref(value)
+
+    return result
+
+
+_T_Var_Value = TypeVar("_T_Var_Value")
+
+
+def var(value: Union[_T_Var_Value, Callable[[], _T_Var_Value]]) -> Ref[_T_Var_Value]:
+    """Create a reactive variable. Only use within rxui.ViewModel.
+
+    Args:
+        value (Union[_T_Var_Value, Callable[[], _T_Var_Value]]): The initial value or a function to generate the initial value.
+
+    Example:
+    .. code-block:: python
+        from ex4nicegui import rxui
+        class MyVm(rxui.ViewModel):
+            count = rxui.var(0)
+            data = rxui.var(lambda: [1,2,3])
+
+
+    """
+    if callable(value):
+        return deep_ref(value())
+    return deep_ref(value)
+
+
+def cached_var(func: Callable[..., _T]) -> ReadonlyRef[_T]:
+    """A decorator to cache the result of a function. Only use within rxui.ViewModel.
+
+    Args:
+        func (Callable): The function to cache.
+
+    Example:
+    .. code-block:: python
+        from ex4nicegui import rxui
+        class MyVm(rxui.ViewModel):
+            name = rxui.var("John")
+
+            @rxui.cached_var
+            def uppper_name(self):
+                return self.name.value.upper()
+
+    """
+    setattr(func, _CACHED_VARS_FLAG, None)
+    return func  # type: ignore

ex4nicegui/reactive/vmodel.py

@@ -26,6 +26,7 @@ import executing
 import ast
 import warnings
 from ex4nicegui.reactive.systems.object_system import get_attribute, set_attribute
+from ex4nicegui.utils.types import _TMaybeRef as TMaybeRef, Ref
 
 _T = TypeVar("_T")
 
@@ -138,23 +139,24 @@ def vmodel(expr: Any, *attrs: Union[str, int]) -> TRef[Any]:
         expr (Any): _description_
 
     ## Examples
-    ```python
-    from ex4nicegui.reactive import rxui
-    from ex4nicegui import deep_ref
 
-    data = deep_ref({"a": 1, "b": [1, 2, 3, 4]})
+    .. code-block:: python
+        from ex4nicegui.reactive import rxui
+        from ex4nicegui import deep_ref
 
-    rxui.label(lambda: f"{data.value=!s}")
+        data = deep_ref({"a": 1, "b": [1, 2, 3, 4]})
 
-    # No binding effect
-    rxui.input(value=data.value["a"])
+        rxui.label(lambda: f"{data.value=!s}")
 
-    # readonly binding
-    rxui.input(value=lambda: data.value["a"])
+        # No binding effect
+        rxui.input(value=data.value["a"])
+
+        # readonly binding
+        rxui.input(value=lambda: data.value["a"])
+
+        # two-way binding
+        rxui.input(value=rxui.vmodel(data.value,'a'))
 
-    # two-way binding
-    rxui.input(value=rxui.vmodel(data.value["a"]))
-    ```
 
     """
 
@@ -205,3 +207,31 @@ def vmodel(expr: Any, *attrs: Union[str, int]) -> TRef[Any]:
         TRef,
         wrapper,
     )
+
+
+def vmodel_with_index(ref: Ref, index: TMaybeRef[int], *keys: Union[str, int]) -> Ref:
+    proxy = ref.value
+
+    def getter():
+        item = proxy[to_value(index)]
+        result = item
+
+        for k in keys:
+            result = get_attribute(result, k)
+        return result
+
+    def setter(value):
+        item = proxy[to_value(index)]
+
+        if len(keys) == 1:
+            set_attribute(item, keys[0], value)
+            return
+
+        obj = get_attribute(item, keys[0])
+
+        for k in keys[1:-1]:
+            set_attribute(obj, k, get_attribute(obj, k))
+
+        set_attribute(obj, keys[-1], value)
+
+    return RefWrapper(getter, setter)  # type: ignore

ex4nicegui/utils/signals.py

@@ -54,11 +54,12 @@ def to_value(obj: Union[_TMaybeRef[T], RefWrapper]) -> T:
         obj (Union[_TMaybeRef[T], RefWrapper]): A getter function, an existing ref, or a non-function value.
 
     ## Example
-    ```python
-    to_value(1)  # 1
-    to_value(lambda: 1)  # 1
-    to_value(to_ref(1))  # 1
-    ```
+
+    .. code-block:: python
+        to_value(1)  # 1
+        to_value(lambda: 1)  # 1
+        to_value(to_ref(1))  # 1
+
     """
     if is_ref(obj):
         return obj.value  # type: ignore
@@ -239,26 +240,27 @@ def event_batch(event_fn: Callable[..., None]):
     Args:
         event_fn (Callable[..., None]): event callback
 
-    @Example
-    ```python
-    from nicegui import ui
-    from ex4nicegui import on, to_ref, effect, ref_computed, batch
+    ## Example
+
+    .. code-block:: python
+        from nicegui import ui
+        from ex4nicegui import on, to_ref, effect, ref_computed, batch
+
+        a = to_ref(0)
+        b = to_ref(0)
+        text = ref_computed(lambda: f"a={a.value};b={b.value}")
 
-    a = to_ref(0)
-    b = to_ref(0)
-    text = ref_computed(lambda: f"a={a.value};b={b.value}")
+        @on([a, b, text])
+        def when_vars_changed():
+            ui.notify(f"a:{a.value};b:{b.value};text={text.value}")
 
-    @on([a, b, text])
-    def when_vars_changed():
-        ui.notify(f"a:{a.value};b:{b.value};text={text.value}")
+        @event_batch
+        def when_click():
+            a.value += 1
+            b.value += 1
 
-    @event_batch
-    def when_click():
-        a.value += 1
-        b.value += 1
+        ui.button("change all values", on_click=when_click)
 
-    ui.button("change all values", on_click=when_click)
-    ```
     """
 
     def wrap(*args, **kwargs):