ex4nicegui 0.5.2__py3-none-any.whl → 0.5.3__py3-none-any.whl

ex4nicegui/__init__.py

@@ -17,10 +17,12 @@ from ex4nicegui.utils.signals import (
     deep_ref,
     is_setter_ref,
     batch,
+    is_reactive,
 )
 
 
 __all__ = [
+    "is_reactive",
     "rxui",
     "ref_computed",
     "effect",
@@ -41,4 +43,4 @@ __all__ = [
     "is_setter_ref",
 ]
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"

ex4nicegui/gsap/__init__.py

@@ -1,4 +1,5 @@
 from .gsap import set_defaults, from_, to, new, run_script
+from .timeline import Timeline as timeline
 
 
 __all__ = [
@@ -7,4 +8,5 @@ __all__ = [
     "to",
     "new",
     "run_script",
+    "timeline",
 ]

ex4nicegui/gsap/timeline.js

@@ -0,0 +1,56 @@
+import { gsap } from "gsap";
+import { convertDynamicProperties } from "../../static/utils/dynamic_properties.js";
+
+
+export default {
+  template: `<template></template>`,
+  data() {
+
+    const tl = gsap.timeline(this.defaults)
+    this.tl = tl
+
+    return {
+    }
+
+  },
+  mounted() {
+    document.addEventListener('DOMContentLoaded', () => {
+      /**
+       * @type any[]
+       */
+      const tasks = this.tasks
+      tasks.forEach(t => {
+        this[t.method](t.targets, t.vars, t.position)
+      })
+
+      this.scriptTasks.forEach(script => {
+        const fn = new Function('return ' + script)()
+        fn(this.tl, gsap)
+      })
+
+    })
+  },
+
+  methods: {
+    from(targets, vars, position) {
+      convertDynamicProperties(vars, false)
+      this.tl.from(targets, vars, position)
+    },
+    to(targets, vars, position) {
+      convertDynamicProperties(vars, false)
+      this.tl.to(targets, vars, position)
+    },
+    runScript(script) {
+      const fn = new Function('return ' + script)()
+      fn(this.tl, gsap)
+    },
+    callTimeline(name, ...args) {
+      this.tl[name](...args)
+    }
+  },
+  props: {
+    defaults: Object,
+    tasks: Array,
+    scriptTasks: Array,
+  },
+};

ex4nicegui/gsap/timeline.py

@@ -0,0 +1,78 @@
+import os
+from pathlib import Path
+from typing import Dict, Optional, Union
+from nicegui.element import Element
+from nicegui import context as ng_context
+
+
+class Timeline(
+    Element,
+    component="timeline.js",
+    exposed_libraries=["../libs/gsap/gsap.mjs"],
+    extra_libraries=["../libs/gsap/*.js", "../libs/gsap/utils/*.js"],
+):
+    def __init__(
+        self,
+        defaults: Optional[Dict] = None,
+    ) -> None:
+        super().__init__()
+        self._props["defaults"] = defaults or {}
+        self._props["tasks"] = []
+        self._props["scriptTasks"] = []
+
+    def from_(self, targets: str, vars: Dict, position: Optional[str] = None):
+        self.__try_run_task("from", targets, vars, position)
+        return self
+
+    def to(self, targets: str, vars: Dict, position: Optional[str] = None):
+        self.__try_run_task("to", targets, vars, position)
+        return self
+
+    def run_script(self, script: Union[str, Path]):
+        if isinstance(script, Path):
+            script = script.read_text("utf8")
+
+        script = os.linesep.join([s for s in script.splitlines() if s])
+        self.__try_run_script_task(script)
+        return self
+
+    def __try_run_script_task(self, script: str):
+        def fn():
+            self.run_method("runScript", script)
+
+        if ng_context.get_client().has_socket_connection:
+            fn()
+        else:
+            tasks = self._props["scriptTasks"]
+            tasks.append(script)
+
+    def __try_run_task(
+        self, name: str, targets: str, vars: Dict, position: Optional[str] = None
+    ):
+        def fn():
+            self.run_method(name, targets, vars)
+
+        if ng_context.get_client().has_socket_connection:
+            fn()
+        else:
+            tasks = self._props["tasks"]
+            tasks.append(
+                {"method": name, "targets": targets, "vars": vars, "position": position}
+            )
+
+    def pause(self):
+        self.run_method("callTimeline", "pause")
+
+    def play(self):
+        self.run_method("callTimeline", "play")
+
+    def resume(
+        self,
+    ):
+        self.run_method("callTimeline", "resume")
+
+    def seek(self, position: Optional[str] = None, suppressEvents=True):
+        self.run_method("callTimeline", "seek", position, suppressEvents)
+
+    def reverse(self):
+        self.run_method("callTimeline", "reverse")

ex4nicegui/reactive/__init__.py

@@ -44,7 +44,8 @@ from .officials.number import NumberBindableUi as number
 from .officials.grid import GridBindableUi as grid
 from .officials.expansion import ExpansionBindableUi as expansion
 from .officials.linear_progress import LinearProgressBindableUi as linear_progress
-
+from .officials.knob import KnobBindableUi as knob
+from .officials.circular_progress import CircularProgressBindableUi as circular_progress
 from .q_pagination import PaginationBindableUi as q_pagination
 
 from .local_file_picker import local_file_picker
@@ -56,11 +57,14 @@ from .dropZone.dropZone import use_drag_zone
 from .fileWatcher import FilesWatcher
 from .mermaid.mermaid import Mermaid as mermaid
 from .vfor import vfor, VforStore
+from .vmodel import vmodel
 
 pagination = q_pagination
 
 
 __all__ = [
+    "circular_progress",
+    "knob",
     "UploadResult",
     "local_file_picker",
     "use_draggable",
@@ -70,6 +74,7 @@ __all__ = [
     "FilesWatcher",
     "vfor",
     "VforStore",
+    "vmodel",
     "html",
     "aggird",
     "button",

ex4nicegui/reactive/officials/circular_progress.py

@@ -0,0 +1,64 @@
+from typing import (
+    Optional,
+)
+from ex4nicegui.reactive.utils import ParameterClassifier
+from ex4nicegui.utils.apiEffect import ui_effect
+
+from ex4nicegui.utils.signals import (
+    ReadonlyRef,
+    _TMaybeRef as TMaybeRef,
+    to_value,
+)
+from nicegui import ui
+from .base import BindableUi, DisableableMixin
+
+
+class CircularProgressBindableUi(
+    BindableUi[ui.circular_progress],
+    DisableableMixin,
+):
+    def __init__(
+        self,
+        value: TMaybeRef[float] = 0.0,
+        *,
+        min: TMaybeRef[float] = 0.0,  # pylint: disable=redefined-builtin
+        max: TMaybeRef[float] = 1.0,  # pylint: disable=redefined-builtin
+        size: Optional[TMaybeRef[str]] = "xl",
+        show_value: TMaybeRef[bool] = True,
+        color: Optional[TMaybeRef[str]] = "primary",
+    ) -> None:
+        pc = ParameterClassifier(
+            locals(),
+            maybeRefs=[
+                "value",
+                "min",
+                "max",
+                "color",
+                "size",
+                "show_value",
+            ],
+        )
+
+        value_kws = pc.get_values_kws()
+        element = ui.circular_progress(**value_kws)
+        super().__init__(element)  # type: ignore
+
+        for key, value in pc.get_bindings().items():
+            self.bind_prop(key, value)  # type: ignore
+
+    @property
+    def value(self):
+        return self.element.value
+
+    def bind_prop(self, prop: str, ref_ui: ReadonlyRef):
+        if prop == "value":
+            return self.bind_value(ref_ui)
+
+        return super().bind_prop(prop, ref_ui)
+
+    def bind_value(self, ref_ui: ReadonlyRef[float]):
+        @ui_effect
+        def _():
+            self.element.set_value(to_value(ref_ui))
+
+        return self

ex4nicegui/reactive/officials/column.py

@@ -1,18 +1,33 @@
 from typing import (
     Any,
 )
+from ex4nicegui.reactive.utils import ParameterClassifier
+from ex4nicegui.utils.signals import (
+    _TMaybeRef as TMaybeRef,
+)
 from nicegui import ui
 from .base import BindableUi
 
 
 class ColumnBindableUi(BindableUi[ui.column]):
-    def __init__(
-        self,
-    ) -> None:
-        element = ui.column()
+    def __init__(self, *, wrap: TMaybeRef[bool] = True) -> None:
+        pc = ParameterClassifier(locals(), maybeRefs=["wrap"], events=[])
+        element = ui.column(**pc.get_values_kws())
 
         super().__init__(element)
 
+        for key, value in pc.get_bindings().items():
+            self.bind_prop(key, value)  # type: ignore
+
+    def bind_prop(self, prop: str, ref_ui: TMaybeRef):
+        if prop == "wrap":
+            return self.bind_wrap(ref_ui)
+
+        return super().bind_prop(prop, ref_ui)
+
+    def bind_wrap(self, ref_ui: TMaybeRef):
+        self.bind_classes({"wrap": ref_ui})
+
     def __enter__(self):
         self.element.__enter__()
         return self

ex4nicegui/reactive/officials/knob.py

@@ -0,0 +1,75 @@
+from typing import (
+    Any,
+    Callable,
+    Optional,
+)
+from ex4nicegui.reactive.utils import ParameterClassifier
+from ex4nicegui.utils.apiEffect import ui_effect
+
+from ex4nicegui.utils.signals import (
+    ReadonlyRef,
+    _TMaybeRef as TMaybeRef,
+    to_value,
+)
+from nicegui import ui
+from .base import BindableUi, DisableableMixin
+
+
+class KnobBindableUi(
+    BindableUi[ui.knob],
+    DisableableMixin,
+):
+    def __init__(
+        self,
+        value: TMaybeRef[float] = 0.0,
+        *,
+        min: TMaybeRef[float] = 0.0,  # pylint: disable=redefined-builtin
+        max: TMaybeRef[float] = 1.0,  # pylint: disable=redefined-builtin
+        step: TMaybeRef[float] = 0.01,
+        color: Optional[TMaybeRef[str]] = "primary",
+        center_color: Optional[TMaybeRef[str]] = None,
+        track_color: Optional[TMaybeRef[str]] = None,
+        size: Optional[TMaybeRef[str]] = None,
+        show_value: TMaybeRef[bool] = False,
+        on_change: Optional[Callable[..., Any]] = None,
+    ) -> None:
+        pc = ParameterClassifier(
+            locals(),
+            maybeRefs=[
+                "value",
+                "min",
+                "max",
+                "step",
+                "color",
+                "center_color",
+                "track_color",
+                "size",
+                "show_value",
+            ],
+            v_model=("value", "on_change"),
+            events=["on_change"],
+        )
+
+        value_kws = pc.get_values_kws()
+        element = ui.knob(**value_kws)
+        super().__init__(element)  # type: ignore
+
+        for key, value in pc.get_bindings().items():
+            self.bind_prop(key, value)  # type: ignore
+
+    @property
+    def value(self):
+        return self.element.value
+
+    def bind_prop(self, prop: str, ref_ui: ReadonlyRef):
+        if prop == "value":
+            return self.bind_value(ref_ui)
+
+        return super().bind_prop(prop, ref_ui)
+
+    def bind_value(self, ref_ui: ReadonlyRef[float]):
+        @ui_effect
+        def _():
+            self.element.set_value(to_value(ref_ui))
+
+        return self

ex4nicegui/reactive/officials/number.py

@@ -4,7 +4,6 @@ from typing import (
     Optional,
     TypeVar,
     Dict,
-    Union,
 )
 from ex4nicegui.reactive.utils import ParameterClassifier
 from ex4nicegui.utils.apiEffect import ui_effect
@@ -26,7 +25,7 @@ class NumberBindableUi(BindableUi[ui.number]):
         label: Optional[TMaybeRef[str]] = None,
         *,
         placeholder: Optional[TMaybeRef[str]] = None,
-        value: TMaybeRef[Union[float, None]] = None,
+        value: Optional[TMaybeRef[float]] = None,
         min: Optional[TMaybeRef[float]] = None,
         max: Optional[TMaybeRef[float]] = None,
         step: Optional[TMaybeRef[float]] = None,

ex4nicegui/reactive/officials/row.py

@@ -1,17 +1,31 @@
 from typing import (
     Any,
 )
+from ex4nicegui.reactive.utils import ParameterClassifier
+from ex4nicegui.utils.signals import (
+    _TMaybeRef as TMaybeRef,
+)
 from nicegui import ui
 from .base import BindableUi
 
 
 class RowBindableUi(BindableUi[ui.row]):
-    def __init__(
-        self,
-    ) -> None:
-        element = ui.row()
+    def __init__(self, *, wrap: TMaybeRef[bool] = True) -> None:
+        pc = ParameterClassifier(locals(), maybeRefs=["wrap"], events=[])
+        element = ui.row(**pc.get_values_kws())
 
         super().__init__(element)
+        for key, value in pc.get_bindings().items():
+            self.bind_prop(key, value)  # type: ignore
+
+    def bind_prop(self, prop: str, ref_ui: TMaybeRef):
+        if prop == "wrap":
+            return self.bind_wrap(ref_ui)
+
+        return super().bind_prop(prop, ref_ui)
+
+    def bind_wrap(self, ref_ui: TMaybeRef):
+        self.bind_classes({"wrap": ref_ui})
 
     def __enter__(self):
         self.element.__enter__()

ex4nicegui/reactive/utils.py

@@ -1,9 +1,33 @@
-from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple, cast
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Protocol,
+    Tuple,
+    cast,
+    runtime_checkable,
+    Union,
+)
 
 from ex4nicegui.utils.signals import is_ref, to_value, is_setter_ref
 from nicegui.events import handle_event
 
 
+@runtime_checkable
+class GetItemProtocol(Protocol):
+    def __getitem__(self, key):
+        ...
+
+
+@runtime_checkable
+class SetItemProtocol(Protocol):
+    def __setitem__(self, key, value):
+        ...
+
+
 def _convert_kws_ref2value(kws: Dict) -> Dict:
     return {key: to_value(value) for key, value in kws.items()}
 
@@ -74,3 +98,18 @@ class ParameterClassifier:
             for k, v in self._args.items()
             if (k in self.maybeRefs and (is_ref(v) or isinstance(v, Callable)))
         }
+
+
+def get_attribute(obj: Union[object, GetItemProtocol], name: Union[str, int]) -> Any:
+    if isinstance(obj, (GetItemProtocol)):
+        return obj[name]
+    return getattr(obj, name)  # type: ignore
+
+
+def set_attribute(
+    obj: Union[object, SetItemProtocol], name: Union[str, int], value: Any
+) -> None:
+    if isinstance(obj, SetItemProtocol):
+        obj[name] = value
+    else:
+        setattr(obj, name, value)  # type: ignore

ex4nicegui/reactive/vfor.py

@@ -2,13 +2,18 @@ from __future__ import annotations
 from nicegui.element import Element
 from nicegui import ui
 from ex4nicegui.utils.clientScope import _CLIENT_SCOPE_MANAGER
-from ex4nicegui.utils.signals import ReadonlyRef, on, to_ref, to_ref_wrapper
+from ex4nicegui.utils.signals import (
+    TReadonlyRef,
+    on,
+    to_ref,
+    to_ref_wrapper,
+    TGetterOrReadonlyRef,
+)
 from typing import (
     Any,
     Callable,
     Dict,
     List,
-    Mapping,
     Optional,
     TypeVar,
     Generic,
@@ -17,11 +22,11 @@ from typing import (
 )
 from functools import partial
 from dataclasses import dataclass
-from signe.core.reactive import DictProxy as signe_DictProxy
 from signe.core.scope import Scope
+from .utils import get_attribute
 
 _T = TypeVar("_T")
-_T_data = ReadonlyRef[List[Any]]
+_T_data = TGetterOrReadonlyRef[List[Any]]
 
 
 class VforStore(Generic[_T]):
@@ -33,29 +38,17 @@ class VforStore(Generic[_T]):
     def row_index(self):
         return self._data_index
 
-    def get(self, attr: Optional[str] = None) -> _T:
-        item = self._source.value[self._data_index.value]
-
-        if attr:
-            setter = None
-            if isinstance(item, signe_DictProxy):
-
-                def base_setter(value):
-                    item[attr] = value
+    def get(self) -> TReadonlyRef[_T]:
+        def base_setter(value):
+            self._source.value[self._data_index.value] = value
 
-                setter = base_setter
-            else:
-                setter = lambda x: _set_attribute(item, attr, x)  # noqa: E731
-
-            return cast(
-                _T,
-                to_ref_wrapper(
-                    lambda: _get_attribute(item, attr),
-                    setter,
-                ),
-            )
+        wrapper = to_ref_wrapper(
+            lambda: self._source.value[self._data_index.value],
+            base_setter,
+        )
+        wrapper._is_readonly = True
 
-        return item
+        return cast(TReadonlyRef, wrapper)
 
     def update(self, index: int):
         self._data_index.value = index
@@ -73,25 +66,12 @@ class VforContainer(Element, component="vfor.js"):
     pass
 
 
-def _get_attribute(obj: Union[object, Mapping], name: str) -> Any:
-    if isinstance(obj, Mapping):
-        return obj[name]
-    return getattr(obj, name)
-
-
-def _set_attribute(obj: Union[object, Mapping], name: str, value: Any) -> None:
-    if isinstance(obj, dict):
-        obj[name] = value
-    else:
-        setattr(obj, name, value)
-
-
 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)
+    return get_attribute(data, attr)
 
 
 class vfor(Generic[_T]):

ex4nicegui/reactive/vmodel.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+import inspect
+from io import BytesIO
+from ex4nicegui.utils.signals import (
+    RefWrapper,
+    TRef,
+    to_raw,
+    is_setter_ref,
+    to_ref_wrapper,
+    to_value,
+    is_reactive,
+    is_setter_ref,
+    to_ref_wrapper,
+    to_value,
+)
+from typing import (
+    Any,
+    Callable,
+    TypeVar,
+    Union,
+    cast,
+    Tuple,
+    NamedTuple,
+)
+
+from types import FrameType
+import tokenize
+import executing
+import ast
+import warnings
+from .utils import get_attribute, set_attribute
+
+_T = TypeVar("_T")
+
+
+def get_caller() -> FrameType:
+    return inspect.currentframe().f_back.f_back  # type: ignore
+
+
+def get_args_code(caller: FrameType) -> str:
+    node = executing.Source.executing(caller).node
+
+    assert isinstance(node, ast.Call)
+
+    source = inspect.getsource(inspect.getmodule(caller))  # type: ignore
+    key_code = ast.get_source_segment(source, node.args[0])
+    return key_code  # type: ignore
+
+
+class CodeInfo(NamedTuple):
+    model: str
+    is_ref: bool
+    keys: Tuple[Union[str, int], ...] = tuple()  # type: ignore
+
+
+def normalize(token: tokenize.TokenInfo):
+    if token.type == tokenize.NUMBER:
+        return int(token.string)
+
+    if token.type == tokenize.STRING:
+        return token.string[1:-1]
+
+    return token.string
+
+
+def parse_code(code: str) -> CodeInfo:
+    tokens = [
+        t
+        for t in tokenize.tokenize(BytesIO(code.encode("utf8")).readline)
+        if t.type in (tokenize.NAME, tokenize.NUMBER, tokenize.OP, tokenize.STRING)
+    ]
+
+    model = tokens[0].string
+    is_ref = (
+        len(tokens) >= 3
+        and tokens[1].type == tokenize.OP
+        and tokens[1].string == "."
+        and tokens[2].string == "value"
+    )
+
+    keys_search_start = 3 if is_ref else 1
+
+    keys = tuple(
+        normalize(token)
+        for token in tokens[keys_search_start:]
+        if token.type != tokenize.OP
+    )
+
+    return CodeInfo(model, is_ref, keys)
+
+
+def create_writeable_wrapper(expr, ref_data, attrs: Tuple[Union[str, int], ...]):
+    if not attrs:
+
+        def maybe_ref_getter():
+            return to_value(expr)
+
+        def reactive_getter():
+            return to_raw(expr)
+
+        def setter(value):
+            pass
+
+        wrapper = to_ref_wrapper(
+            reactive_getter if is_reactive(expr) else maybe_ref_getter,
+            setter,
+        )
+        wrapper._is_readonly = False
+        return wrapper
+
+    def getter():
+        obj = get_attribute(to_value(ref_data), attrs[0])
+        for attr in attrs[1:]:
+            obj = get_attribute(obj, attr)
+
+        return obj
+
+    def setter(value):
+        obj = to_value(ref_data)
+
+        for attr in attrs[:-1]:
+            obj = get_attribute(obj, attr)
+
+        set_attribute(obj, attrs[-1], value)
+
+    wrapper = to_ref_wrapper(
+        getter,
+        setter,
+    )
+    wrapper._is_readonly = False
+    return wrapper
+
+
+def vmodel(expr: Any, *attrs: Union[str, int]) -> TRef[Any]:
+    """Create a two-way binding on a form input element or a component.
+
+    @see - https://github.com/CrystalWindSnake/ex4nicegui/blob/main/README.en.md#vmodel
+    @中文文档 - https://gitee.com/carson_add/ex4nicegui/tree/main/#vmodel
+
+    Args:
+        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]})
+
+    rxui.label(lambda: f"{data.value=!s}")
+
+    # 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"]))
+    ```
+
+    """
+
+    assert not isinstance(expr, Callable), "argument expr cannot be a function"
+
+    if isinstance(expr, RefWrapper):
+        expr._is_readonly = False
+
+    if is_setter_ref(expr):
+        if attrs:
+            wrapper = create_writeable_wrapper(expr, expr, attrs)
+
+            return cast(
+                TRef,
+                wrapper,
+            )
+
+        return cast(
+            TRef,
+            expr,
+        )
+
+    caller = get_caller()
+    code = get_args_code(caller)
+
+    info = parse_code(code)
+    ref_data = caller.f_locals.get(info.model) or caller.f_globals.get(info.model)
+    assert ref_data is not None, f"{info.model} not found"
+    all_attrs = (*info.keys, *attrs)
+
+    if not all_attrs:
+        warn_mes = ""
+        if is_reactive(expr) or is_setter_ref(expr):
+            warn_mes = rf"""Expression missing the key,result is read-only binding.Maybe you meant `{code}['key']`"""
+        elif not info.is_ref:
+            warn_mes = """Maybe you don't need to use vmodel"""
+        else:
+            warn_mes = rf"""No binding.Maybe you meant `{info.model}`"""
+
+        warnings.warn(
+            warn_mes,
+            stacklevel=2,
+        )
+
+    wrapper = create_writeable_wrapper(expr, ref_data, all_attrs)
+
+    return cast(
+        TRef,
+        wrapper,
+    )

ex4nicegui/utils/signals.py

@@ -3,6 +3,7 @@ from functools import partial
 import types
 from weakref import WeakValueDictionary
 import signe
+from signe.core.protocols import ComputedResultProtocol
 from .clientScope import _CLIENT_SCOPE_MANAGER
 from typing import (
     Any,
@@ -20,23 +21,27 @@ from typing import (
 from nicegui import ui
 from .effect import effect
 from .scheduler import get_uiScheduler
+import warnings
 
 T = TypeVar("T")
 
 
-TReadonlyRef = signe.TGetterSignal[T]
+TReadonlyRef = ComputedResultProtocol[T]
 ReadonlyRef = TReadonlyRef[T]
 DescReadonlyRef = TReadonlyRef[T]
 
 TGetterOrReadonlyRef = signe.TGetter[T]
 
 
+is_reactive = signe.is_reactive
+
+
 def reactive(obj: T) -> T:
     return signe.reactive(obj, get_uiScheduler())
 
 
 class RefWrapper(Generic[T]):
-    __slot__ = ("_getter_fn", "_setter_fn")
+    __slot__ = ("_getter_fn", "_setter_fn", "")
 
     def __init__(
         self,
@@ -57,12 +62,17 @@ class RefWrapper(Generic[T]):
             self._getter_fn = lambda: getter_or_ref
             self._setter_fn = lambda x: None
 
+        self._is_readonly = False
+
     @property
     def value(self) -> T:
         return cast(T, self._getter_fn())
 
     @value.setter
     def value(self, new_value: T):
+        if self._is_readonly:
+            warnings.warn("readonly ref cannot be assigned.")
+            return
         return self._setter_fn(new_value)
 
 

{ex4nicegui-0.5.2.dist-info → ex4nicegui-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ex4nicegui
-Version: 0.5.2
+Version: 0.5.3
 Summary: Extension library based on nicegui, providing data responsive,BI functionality modules
 Home-page: 
 Author: carson_jia
@@ -14,9 +14,10 @@ Classifier: Programming Language :: Python :: 3.8
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: signe (>=0.4.8)
+Requires-Dist: signe (>=0.4.9)
 Requires-Dist: nicegui (>=1.4.0)
 Requires-Dist: typing-extensions
+Requires-Dist: executing
 
 # ex4nicegui
 [中文 README](./README.md)
@@ -389,16 +390,58 @@ ui.button("change b", on_click=change_b)
 
 ---
 
+## functionality
+
+### vmodel
+Create two-way bindings on form input elements or components.
+
+Bidirectional bindings are supported by default for `ref` simple value types
+```python
+from ex4nicegui import rxui, to_ref, deep_ref
+
+data = to_ref("init")
+
+rxui.label(lambda: f"{data.value=}")
+# two-way binding 
+rxui.input(value=data)
+```
+- Simple value types are generally immutable values such as `str`, `int`, etc.
+
+When using complex data structures, `deep_ref` is used to keep nested values responsive.
+```python
+data = deep_ref({"a": 1, "b": [1, 2, 3, 4]})
+
+rxui.label(lambda: f"{data.value=!s}")
+
+# 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"]))
+```
+
+- The first input box will be completely unresponsive because the code is equivalent to passing in a value `1` directly
+- The second input box will get read responsiveness due to the use of a function.
+- The third input box, wrapped in `rxui.vmodel`, can be bi-directionally bound.
+
+Most use `vmodel` with `vfor`, see [todo list examples](./examples/todomvc/)
+
+---
+
 ### vfor
 Render list components based on list responsive data. Each component is updated on demand. Data items support dictionaries or objects of any type
 
 ```python
 from nicegui import ui
 from ex4nicegui.reactive import rxui
-from ex4nicegui import to_ref, ref_computed
+from ex4nicegui import deep_ref, ref_computed
+from typing import Dict
 
 # refs
-items = to_ref(
+items = deep_ref(
     [
         {"id": 1, "message": "foo", "done": False},
         {"id": 2, "message": "bar", "done": True},
@@ -414,7 +457,6 @@ def done_count_info():
 def check():
     for item in items.value:
         item["done"] = not item["done"]
-    items.value = items.value
 
 
 # ui
@@ -423,54 +465,33 @@ ui.button("check", on_click=check)
 
 
 @rxui.vfor(items,key='id')
-def _(store: rxui.VforStore):
+def _(store: rxui.VforStore[Dict]):
     # function to build the interface for each row of data
-    msg_ref = store.get("message")  # Get responsive object with `store.get`
+    item = store.get()  # Get responsive object with `store.get`
+    mes = rxui.vmodel(item.value['message'])
 
     # Enter the content of the input box, 
     # you can see the title of the radio box changes synchronously
     with ui.card():
-        rxui.input(value=msg_ref) 
-        rxui.checkbox(text=msg_ref, value=store.get("done"))
+        with ui.row():
+            rxui.input(value=mes)
+            rxui.label(lambda: f"{mes.value=!s}")
+        rxui.checkbox(text=mes, value=rxui.vmodel(item.value['done']))
 
 ```
 
 - `rxui.vfor` decorator to custom function
     - The first argument is passed to the responsive list. Each item in the list can be a dictionary or other object (`dataclasses` etc.)
     - Second parameter `key`: In order to be able to keep track of the identity of each node, and thus reuse and reorder existing elements, you can provide a unique key for the block corresponding to each element. The default(`None`) is to use the list element index.
-- The custom function takes one argument. The current row's attribute can be retrieved via `store.get`, which is a responsive object.
+- The custom function takes one argument. The current row's  can be retrieved via `store.get`, which is a responsive object.
 
 
 > vfor are created only when new data is added.
 
-In the above example, you'll notice that when the checkbox is clicked, the text of the number of completed counts (`done_count_info`) doesn't change synchronously
-
-This is because responsive data changes in the `vfor` function do not affect the data source list. This is a restriction to prevent writing overly complex bi-directional data flow response logic.
-
-We should make changes to the data source list via events in the function
-
-```python
-...
-
-@rxui.vfor(items, key="id")
-def _(store: rxui.VforStore):
-    msg_ref = store.get("message")
-
-    def on_check_change(e):
-        items.value[store.row_index]["done"] = e.value
-        items.value = items.value
-
-    with ui.card():
-        rxui.input(value=msg_ref)
-        rxui.checkbox(text=msg_ref, value=store.get("done"),on_change=on_check_change)
-
-```
 
 ---
 
 
-## functionality
-
 ### Bind class names
 
 All component classes provide `bind_classes` for binding `class`, supporting three different data structures.

{ex4nicegui-0.5.2.dist-info → ex4nicegui-0.5.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-ex4nicegui/__init__.py,sha256=gp1J8Cq4-9IsL9kkzTskxFLXFLwFxp6qpYekJisFm8g,698
+ex4nicegui/__init__.py,sha256=sbp4UdZz1sLg5LIpMSt87LwclMQb13_IDD9mewNPRuE,736
 ex4nicegui/bi/__init__.py,sha256=eu-2CuzzrcHCyKQOfoo87v6C9nSwFDdeLhjY0cRV13M,315
 ex4nicegui/bi/dataSource.py,sha256=sQzuQvNWBf20n9cz--1OX5gxT6RUAhwrq_xTQEpSa0o,7691
 ex4nicegui/bi/dataSourceFacade.py,sha256=6NuAyrTIk_L2Tz9IRFpuHKRQY_OwJINDzxoM6JYOc14,8186
@@ -22,8 +22,10 @@ ex4nicegui/bi/elements/ui_table.py,sha256=aKL26xbiCIQG_-KFEozXjbB4G88FdOK25k2H0k
 ex4nicegui/experimental_/__init__.py,sha256=HODL0f70HUzVrfRwUzdCwxTp_9mYr4D1nnzd8jevlMw,69
 ex4nicegui/experimental_/gridLayout/__init__.py,sha256=c9k-zykhKW3Ol6QECUoKqJW9QEuhA9xPi8s4Dm4m7SU,125
 ex4nicegui/experimental_/gridLayout/index.py,sha256=zFXuvFroo5EC1CFjt-b4hMiEy67hGP5J1GYTKH6kpUU,4737
-ex4nicegui/gsap/__init__.py,sha256=k9JKpx3sv3k9CnohAMnBA5COKSevrs_p7IPbApGbBeM,157
+ex4nicegui/gsap/__init__.py,sha256=xBApQlq9st9exhgcSkqCzWeS6bc1eKiPJfYP25MSInw,218
 ex4nicegui/gsap/gsap.py,sha256=-1sncG2_37LYN6RosnHZAgYSI899HMj9FB6MQWUj8yw,4675
+ex4nicegui/gsap/timeline.js,sha256=CB300drH7UUSfy_WDeuWHSNh3WX-vwbRtKBLL1Ak43o,1241
+ex4nicegui/gsap/timeline.py,sha256=B3CvN83CzJMMFMVdZZC2UHR0l_I90amRQ0Sf-P623zo,2421
 ex4nicegui/gsap/wrapGsap.js,sha256=0Iz7qh8aA-h3svV7fW4U5k_pX7zXCcIdHDaG7NNvgLU,1045
 ex4nicegui/layout/__init__.py,sha256=YT76Ec7p4aFOGms6wc19207flBeyI6jrq7Kg_FQ2wnQ,278
 ex4nicegui/layout/gridFlex/GridFlex.js,sha256=ljkxGFucBUIPksMAT5w_35sxGogC7OzxzXnOw21Z3_k,4468
@@ -64,15 +66,16 @@ ex4nicegui/libs/gsap/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJ
 ex4nicegui/libs/gsap/utils/matrix.js,sha256=77scrxbQZXx4ex5HkvnT9IkhMG1rQoDNp4TSYgUeYVk,15235
 ex4nicegui/libs/gsap/utils/paths.js,sha256=2SPaRHQ7zgba9cH8hGhkTYPCZdrrEhE2qhh6ECAEvSA,49314
 ex4nicegui/libs/gsap/utils/strings.js,sha256=47G9slz5ltG9mDSwrfQDtWzzdV5QJ-AIMLRMNK0VSiM,10472
-ex4nicegui/reactive/__init__.py,sha256=07i_FuQx4Mv_RuME9jBqUUpcDJylq8tCH6m1cE6qduY,3117
+ex4nicegui/reactive/__init__.py,sha256=osdHgTwRTI2jOjHtbOpMjdQlvGiJW-1vaqcPPLhzbdQ,3339
 ex4nicegui/reactive/fileWatcher.py,sha256=gjeZhgar02f-qGQa47Tj5SMaCP_ftRtSU898XUmXl1U,1472
 ex4nicegui/reactive/local_file_picker.py,sha256=6kh7pW4RZk1gqYjxkOvTfJ-2T_KwZznr8AekcZoxthw,6171
 ex4nicegui/reactive/q_pagination.py,sha256=WcSYpB75NH3lffw3HXwZRcvnh0l6EA1Eqp5bcJKIJaw,1505
 ex4nicegui/reactive/rxui.py,sha256=gZ8ZEjGuJFKcedEZhcm4PIZguNkY-Wv5yQx80QnsBKI,31
 ex4nicegui/reactive/usePagination.py,sha256=Gop9KV780DcQK5bH4zQZ5sRpV3jOD2sRX_Bpmb1LTFI,2598
-ex4nicegui/reactive/utils.py,sha256=2lPWEA_Lx17J0I64TqYx6h3xKTZzmaJRgZcpKsgk1yw,2552
+ex4nicegui/reactive/utils.py,sha256=GSk_eUH-iNUi18Tg7MsBVnMK5basgX6EQgbSD1zxsZw,3315
 ex4nicegui/reactive/vfor.js,sha256=OmpeLZdjV_GiG5HdglMXGBKpgrKYh3UIeugpszAVdWw,52
-ex4nicegui/reactive/vfor.py,sha256=UnOsarN-sY7xKn-R5BXvVZyxTQLBv6RKR0HpVzVry24,6127
+ex4nicegui/reactive/vfor.py,sha256=hyvbmMJtC8usSYeq023bCL8kOrmnFw09YOS_r6GWBzk,5495
+ex4nicegui/reactive/vmodel.py,sha256=FH1rXjbzD6r0MeFdf-3GDvz8JJ_qgmI7rTo8itw_StY,5147
 ex4nicegui/reactive/EChartsComponent/ECharts.js,sha256=HMmgXlDl548H4JpozDSbLWv-opvPi3OdJz_XY_MHbnY,3326
 ex4nicegui/reactive/EChartsComponent/ECharts.py,sha256=hoUZ7h-KOUKNd-1BybSX4xxv33gYuTkky70yEzv-oIA,6344
 ex4nicegui/reactive/EChartsComponent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -91,8 +94,9 @@ ex4nicegui/reactive/officials/base.py,sha256=1d6ePyz4ZiOsZYLKtCr04Aw4_9YyYl2HpCN
 ex4nicegui/reactive/officials/button.py,sha256=12FZ2cQGFsTsivSHT9YfDD_wP_D4xrpHHfKmVNNKLJE,1660
 ex4nicegui/reactive/officials/card.py,sha256=8-tBwm3xfVybolQ87i8lAYUpBV6FdaVdeSH6xu0736U,1275
 ex4nicegui/reactive/officials/checkbox.py,sha256=BcSbWuMTA2UgwOeuBTtpvzqdOivb2xbkLazfGqwuboo,1562
+ex4nicegui/reactive/officials/circular_progress.py,sha256=BVLjCJtEcwa2pqGZ4nC-w-8FlkTS5IuqlL_tY6xOXNY,1787
 ex4nicegui/reactive/officials/color_picker.py,sha256=fSRICdzdH16w3BIGyAk3CtaauYqpPfUHCRc2kq-w-ZA,3402
-ex4nicegui/reactive/officials/column.py,sha256=3RLvVKNaDtOb8df4uS3xRfwJJPuH1ndXk_Y4Gry0Tjo,413
+ex4nicegui/reactive/officials/column.py,sha256=CfoJigEdpRoGaJTY_O7wbK8cp8ufX8mYUKNRUnPWUr0,1040
 ex4nicegui/reactive/officials/date.py,sha256=jp75WgZaICnCHLS_wpF3uJI2kaGeNqmRLj3qpn5IIyg,2681
 ex4nicegui/reactive/officials/drawer.py,sha256=y9_gbDDy_6Y7mRfSB8BGawM-_g6kECM1ieZXMX2YCQo,2370
 ex4nicegui/reactive/officials/echarts.py,sha256=rBYHL6K_uAp4A4r_qacXt_bFukOMPWxdN_9xjEXG4RY,9683
@@ -103,11 +107,12 @@ ex4nicegui/reactive/officials/html.py,sha256=yasDeGMJyyGmCpJoiwmG-QszfLSOsHLYWSh
 ex4nicegui/reactive/officials/icon.py,sha256=L0yHo4Ute7PNJw2R2vn8PJGhIjreqeoZnS4p6tijmg0,1559
 ex4nicegui/reactive/officials/image.py,sha256=qtdtrjZ2OPF1mmtrL-RSgH3hNcXbRdwH9oD-RyFYVJM,1120
 ex4nicegui/reactive/officials/input.py,sha256=d338LH7tYArhUQYXJleytIOXsDieXEm4yLxOrjRbxLM,4030
+ex4nicegui/reactive/officials/knob.py,sha256=ZCKXUbFQUhdsRoTADk2gqdEwmi1CeW9Jmc7AGJyV1Yg,2153
 ex4nicegui/reactive/officials/label.py,sha256=7xhvQIa-3Zm44xJIoKeMys1M6d6AMJTeE5l9THPICGo,1398
 ex4nicegui/reactive/officials/linear_progress.py,sha256=3ew4uqUIDrDH0PdX42K7rnKQL4khmZgxmJfmWX6qMDs,2128
-ex4nicegui/reactive/officials/number.py,sha256=DUb9mQy2KpVLKkdIOXqNHRz30WA48wWVip4zC_OXADQ,2216
+ex4nicegui/reactive/officials/number.py,sha256=Ro20LiSjzeLkcPM5oIe3phulLH5Gsw3YwYBCyRl9bqI,2201
 ex4nicegui/reactive/officials/radio.py,sha256=35KCAE0JhzBczaCGrlufZystgpzljobOoIw1H7js1KA,1929
-ex4nicegui/reactive/officials/row.py,sha256=ZBPITfHbJmAdAWuIZFl2H1XFS9pJam57PJ_zDZWhueE,404
+ex4nicegui/reactive/officials/row.py,sha256=pwFJBdv3_D5-E-oga-OG5t57ahHcYXGSI_-UofWg_j0,1029
 ex4nicegui/reactive/officials/select.py,sha256=Fj4V96ju2tpsP1ok0RFokN1K7TxzNS9YLVCz55O788Y,2980
 ex4nicegui/reactive/officials/slider.py,sha256=6E6UeyX_hXIDz_-0v6WEIfTM5oqzukonRyqDRJHT-PA,2954
 ex4nicegui/reactive/officials/switch.py,sha256=-QDXbOQllnWRE28pAH74qrgpN1TXs-1snLDqN6pdiVM,1605
@@ -126,9 +131,9 @@ ex4nicegui/utils/clientScope.py,sha256=-KJnrZGqdAQUNNbQbqMAqNzWHCVon-lC3aaQGuaTd
 ex4nicegui/utils/common.py,sha256=7P0vboDadLun6EMxNi3br9rKJgKt0QT4sy_66cHEwb4,994
 ex4nicegui/utils/effect.py,sha256=MgvWuAP3OFs2bR4ef6uXPwGCkKORUK-4hmx1oSwl04Y,2310
 ex4nicegui/utils/scheduler.py,sha256=Wa963Df3UDvWHjXXoVYGIBevIILzCFoz-yAWjvxeyfQ,1218
-ex4nicegui/utils/signals.py,sha256=nzjw0uy9fnUUc4aol1dzweH3F4uGhNSZspW1iTZ-TBw,10924
-ex4nicegui-0.5.2.dist-info/LICENSE,sha256=0KDDElS2dl-HIsWvbpy8ywbLzJMBFzXLev57LnMIZXs,1094
-ex4nicegui-0.5.2.dist-info/METADATA,sha256=2Me59obBt8Ee7791n8OU-jwwBVMrJT9s4JVbsfu6WW4,26040
-ex4nicegui-0.5.2.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-ex4nicegui-0.5.2.dist-info/top_level.txt,sha256=VFwMiO9AFjj5rfLMJwN1ipLRASk9fJXB8tM6DNrpvPQ,11
-ex4nicegui-0.5.2.dist-info/RECORD,,
+ex4nicegui/utils/signals.py,sha256=Eruq0WUH-G7dpnfHZ2y9Uf-mS6L_RBVcsaqbK8FKfvE,11193
+ex4nicegui-0.5.3.dist-info/LICENSE,sha256=0KDDElS2dl-HIsWvbpy8ywbLzJMBFzXLev57LnMIZXs,1094
+ex4nicegui-0.5.3.dist-info/METADATA,sha256=hGb8ZKAD6yb90SRQ6tALuCBNwsGaPwbJFK6rGsWboG0,26519
+ex4nicegui-0.5.3.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
+ex4nicegui-0.5.3.dist-info/top_level.txt,sha256=VFwMiO9AFjj5rfLMJwN1ipLRASk9fJXB8tM6DNrpvPQ,11
+ex4nicegui-0.5.3.dist-info/RECORD,,