ex4nicegui 0.5.2__tar.gz → 0.5.3__tar.gz

{ex4nicegui-0.5.2 → ex4nicegui-0.5.3}/PKG-INFO

@@ -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
@@ -386,16 +386,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},
@@ -411,7 +453,6 @@ def done_count_info():
 def check():
     for item in items.value:
         item["done"] = not item["done"]
-    items.value = items.value
 
 
 # ui
@@ -420,54 +461,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 → ex4nicegui-0.5.3}/README.md

@@ -383,16 +383,56 @@ ui.button("change b", on_click=change_b)
 
 ## 组件功能
 
+### vmodel
+在表单输入元素或组件上创建双向绑定。
+
+简单值类型的 `ref` 默认支持双向绑定
+```python
+from ex4nicegui import rxui, to_ref, deep_ref
+
+data = to_ref("init")
+
+rxui.label(lambda: f"{data.value=}")
+# 默认就是双向绑定
+rxui.input(value=data)
+```
+
+- 简单值类型一般是 `str`,`int` 等不可变值类型
+
+当使用复杂数据结构时，会使用 `deep_ref` 保持嵌套值的响应性
+```python
+data = deep_ref({"a": 1, "b": [1, 2, 3, 4]})
+
+rxui.label(lambda: f"{data.value=!s}")
+
+# 当前版本没有任何绑定效果.或许未来的版本可以解决
+rxui.input(value=data.value["a"])
+
+# 只读绑定.其他途径修改了 `data.value["a"]` ，此输入框会同步，但反过来不行
+rxui.input(value=lambda: data.value["a"])
+
+# 要使用 vmodel 才能双向绑定
+rxui.input(value=rxui.vmodel(data.value["a"]))
+```
+
+- 第一个输入框将完全失去响应性，因为代码等价于直接传入一个数值`1`
+- 第二个输入框由于使用函数，将得到读取响应性(第三个输入框输入值，将得到同步)
+- 第三个输入框，使用 `rxui.vmodel` 包裹，即可实现双向绑定
+
+多数在配合 `vfor` 时使用 `vmodel`,可参考 [todo list 案例](./examples/todomvc/)
+
+
 ### vfor
 基于列表响应式数据，渲染列表组件。每项组件按需更新。数据项支持字典或任意类型对象
 
 ```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},
@@ -408,55 +448,35 @@ def done_count_info():
 def check():
     for item in items.value:
         item["done"] = not item["done"]
-    items.value = items.value
 
 
 # ui
 rxui.label(done_count_info)
 ui.button("check", on_click=check)
 
-@rxui.vfor(items, key="id")
-def _(store: rxui.VforStore):
+
+@rxui.vfor(items,key='id')
+def _(store: rxui.VforStore[Dict]):
     # 函数中构建每一行数据的界面
-    msg_ref = store.get("message")  # 通过 store.get 获取对应行的属性响应式对象
+    item = store.get()  # 通过 store.get 获取对应行的响应式对象(相当于每行的数据 to_ref(...))
+    mes = rxui.vmodel(item.value['message']) # 复杂结构默认没有双向绑定，需要使用 `vmodel`
 
     # 输入框输入内容，可以看到单选框的标题同步变化
     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` 装饰器到自定义函数
     - 第一个参数传入响应式列表。列表中每一项可以是字典或其他对象(`dataclasses` 等等)
     - 第二个参数 `key`: 为了可以跟踪每个节点的标识，从而重用和重新排序现有的元素，你可以为每个元素对应的块提供一个唯一的 key 。默认情况使用列表元素索引。
-- 自定义函数带有一个参数。通过 `store.get` 可以获取当前行对应的属性，此为响应式对象
+- 自定义函数带有一个参数。通过 `store.get` 可以获取当前行的响应式对象
 
 > vfor 渲染的项目，只有在新增数据时，才会创建
 
-上述的例子中，你会发现，当点击 checkbox 时，完成数量的文本(`done_count_info`)并没有同步变化
-
-因为 `vfor` 函数中对响应式数据修改，不会影响数据源列表。这是为了防止写出过于复杂的双向数据流响应逻辑而限制。
-
-我们应该在函数中通过事件，对数据源列表做修改
-
-```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)
-
-```
-
 
 ---
 

{ex4nicegui-0.5.2 → ex4nicegui-0.5.3}/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-0.5.2 → ex4nicegui-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-0.5.3/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-0.5.3/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-0.5.2 → ex4nicegui-0.5.3}/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-0.5.3/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-0.5.3/ex4nicegui/reactive/officials/column.py

@@ -0,0 +1,36 @@
+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, *, 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
+
+    def __exit__(self, *_: Any):
+        self.element.__exit__(*_)

ex4nicegui-0.5.3/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-0.5.2 → ex4nicegui-0.5.3}/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-0.5.3/ex4nicegui/reactive/officials/row.py

@@ -0,0 +1,35 @@
+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, *, 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__()
+        return self
+
+    def __exit__(self, *_: Any):
+        self.element.__exit__(*_)