ex4nicegui 0.5.1__tar.gz → 0.5.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ex4nicegui
-Version: 0.5.1
+Version: 0.5.3
 Summary: Extension library based on nicegui, providing data responsive,BI functionality modules
 Home-page: 
 Author: carson_jia
@@ -32,6 +32,11 @@ An extension library for [nicegui](https://github.com/zauberzeug/nicegui). It ha
 pip install ex4nicegui -U
 ```
 
+## examples
+- [basic](./examples/basic/)
+- [todo list mvc](./examples/todomvc/)
+
+
 ## 🦄 Usage
 
 ```python
@@ -381,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},
@@ -406,7 +453,6 @@ def done_count_info():
 def check():
     for item in items.value:
         item["done"] = not item["done"]
-    items.value = items.value
 
 
 # ui
@@ -415,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.1 → ex4nicegui-0.5.3}/README.md

@@ -25,7 +25,8 @@ pip install ex4nicegui -U
 
 
 ## 示例项目
-- [todo list mvc](./examples/todomvc/README.md)
+- [入门](./examples/basic/)
+- [todo list mvc](./examples/todomvc/)
 
 ---
 
@@ -382,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},
@@ -407,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.1 → ex4nicegui-0.5.3}/ex4nicegui/__init__.py

@@ -17,15 +17,12 @@ from ex4nicegui.utils.signals import (
     deep_ref,
     is_setter_ref,
     batch,
-)
-from ex4nicegui import tools
-from signe import batch
-from ex4nicegui.experimental_ import (
-    gridLayout as exp_ui,
+    is_reactive,
 )
 
 
 __all__ = [
+    "is_reactive",
     "rxui",
     "ref_computed",
     "effect",
@@ -46,4 +43,4 @@ __all__ = [
     "is_setter_ref",
 ]
 
-__version__ = "0.5.1"
+__version__ = "0.5.3"

{ex4nicegui-0.5.1 → ex4nicegui-0.5.3}/ex4nicegui/bi/dataSourceFacade.py

@@ -21,7 +21,6 @@ from .elements.ui_range import ui_range
 from .elements.ui_echarts import ui_echarts
 from .elements.ui_aggrid import ui_aggrid
 from .elements.ui_table import ui_table
-from ex4nicegui.bi import types as bi_types
 
 if TYPE_CHECKING:
     from ex4nicegui.bi.elements.models import (
@@ -43,9 +42,7 @@ class DataSourceFacade(Generic[_TData]):
     @property
     def filtered_data(self) -> _TData:
         """Data after filtering"""
-        return cast(
-            _TData, self._dataSource.filtered_data
-        )
+        return cast(_TData, self._dataSource.filtered_data)
 
     def reload(self, data, reset_filters=True):
         """Reload the data source with the provided new data.
@@ -59,9 +56,7 @@ class DataSourceFacade(Generic[_TData]):
         if reset_filters:
             self.remove_filters()
 
-    def remove_filters(
-        self, *components: UiResult
-    ):
+    def remove_filters(self, *components: UiResult):
         """Remove the filter from the data source"""
         if len(components) == 0:
             # remove all
@@ -73,9 +68,7 @@ class DataSourceFacade(Generic[_TData]):
         self,
         column: str,
         *,
-        sort_options: Optional[
-            bi_types._TDuplicates_column_values_sort_options
-        ] = None,
+        sort_options: Optional[bi_types._TDuplicates_column_values_sort_options] = None,
         exclude_null_value=False,
         clearable=True,
         multiple=True,
@@ -97,11 +90,7 @@ class DataSourceFacade(Generic[_TData]):
         Returns:
             SelectResult: An instance of a user interface select box.
         """
-        kws = {
-            key: value
-            for key, value in locals().items()
-            if key not in ("kwargs")
-        }
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
         kws.update(kwargs)
         return ui_select(**kws)
 
@@ -124,11 +113,7 @@ class DataSourceFacade(Generic[_TData]):
         Returns:
             ui.aggrid: aggrid table.
         """
-        kws = {
-            key: value
-            for key, value in locals().items()
-            if key not in ("kwargs")
-        }
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
         kws.update(kwargs)
         return ui_aggrid(**kws)
 
@@ -152,11 +137,7 @@ class DataSourceFacade(Generic[_TData]):
         Returns:
             ui.table: ui.table.
         """
-        kws = {
-            key: value
-            for key, value in locals().items()
-            if key not in ("kwargs")
-        }
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
         kws.update(kwargs)
         return ui_table(**kws)
 
@@ -164,14 +145,10 @@ class DataSourceFacade(Generic[_TData]):
         self,
         column: str,
         *,
-        sort_options: Optional[
-            bi_types._TDuplicates_column_values_sort_options
-        ] = None,
+        sort_options: Optional[bi_types._TDuplicates_column_values_sort_options] = None,
         exclude_null_value=False,
         hide_filtered=True,
-        custom_options_map: Optional[
-            Union[Dict, Callable[[Any], Any]]
-        ] = None,
+        custom_options_map: Optional[Union[Dict, Callable[[Any], Any]]] = None,
         **kwargs,
     ):
         """
@@ -189,11 +166,7 @@ class DataSourceFacade(Generic[_TData]):
         Returns:
             RadioResult: An radio Selection.
         """
-        kws = {
-            key: value
-            for key, value in locals().items()
-            if key not in ("kwargs")
-        }
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
         kws.update(kwargs)
         return ui_radio(**kws)
 
@@ -213,11 +186,7 @@ class DataSourceFacade(Generic[_TData]):
         Returns:
             ui.radio: An Slider.
         """
-        kws = {
-            key: value
-            for key, value in locals().items()
-            if key not in ("kwargs")
-        }
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
         kws.update(kwargs)
         return ui_slider(**kws)
 
@@ -237,19 +206,13 @@ class DataSourceFacade(Generic[_TData]):
         Returns:
             QRange: An Range.
         """
-        kws = {
-            key: value
-            for key, value in locals().items()
-            if key not in ("kwargs")
-        }
+        kws = {key: value for key, value in locals().items() if key not in ("kwargs")}
         kws.update(kwargs)
         return ui_range(**kws)
 
     def ui_echarts(
         self,
-        fn: Callable[
-            [Any], Union[Dict, "pyecharts.Base"]
-        ],  # pyright: ignore
+        fn: Callable[[Any], Union[Dict, "pyecharts.Base"]],  # pyright: ignore  # noqa: F821
     ):
         """Create charts
 
@@ -295,15 +258,7 @@ class DataSourceFacade(Generic[_TData]):
         filter: bi_types._TFilterCallback[_TData],
     ):
         ele_id = element.id
-        key = self._dataSource.get_component_info_key(
-            ele_id
-        )
-        if not self._dataSource._component_map.has_record(
-            key
-        ):
-            self._dataSource._register_component(
-                ele_id
-            )
-        self._dataSource.send_filter(
-            ele_id, Filter(filter)
-        )
+        key = self._dataSource.get_component_info_key(ele_id)
+        if not self._dataSource._component_map.has_record(key):
+            self._dataSource._register_component(ele_id)
+        self._dataSource.send_filter(ele_id, Filter(filter))

{ex4nicegui-0.5.1 → ex4nicegui-0.5.3}/ex4nicegui/bi/elements/text.py

@@ -1,4 +1,4 @@
-from typing import Callable, Any, Union
+from typing import Callable, Any
 from nicegui import ui
 from ex4nicegui.utils.signals import effect
 

{ex4nicegui-0.5.1 → ex4nicegui-0.5.3}/ex4nicegui/bi/elements/ui_aggrid.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Union
+from typing import TYPE_CHECKING, Callable, Dict, Optional, Union
 from nicegui import ui
 from ex4nicegui.bi.dataSource import DataSource
 from .models import UiResult
@@ -60,7 +60,7 @@ def ui_aggrid(
         cp._props["options"] = options
         cp.update()
 
-    info = self._dataSource._register_component(cp.id, on_source_update)
+    self._dataSource._register_component(cp.id, on_source_update)
 
     on_source_update()
 

{ex4nicegui-0.5.1 → ex4nicegui-0.5.3}/ex4nicegui/bi/elements/ui_echarts.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Callable, Dict, Union, cast
 from nicegui.events import UiEventArguments
 from ex4nicegui.reactive import rxui
 from ex4nicegui.reactive.EChartsComponent.ECharts import (
@@ -36,7 +36,7 @@ class EChartsResult(UiResult[echarts]):
 
 def ui_echarts(
     self: DataSourceFacade,
-    fn: Callable[[Any], Union[Dict, "pyecharts.Base"]],  # pyright: ignore
+    fn: Callable[[Any], Union[Dict, "pyecharts.Base"]],  # pyright: ignore  # noqa: F821
     **kwargs,
 ):
     def create_options(data):
@@ -60,7 +60,7 @@ def ui_echarts(
         options = create_options(data)
         cp.element.update_options(options)
 
-    info = self._dataSource._register_component(ele_id, on_source_update)
+    self._dataSource._register_component(ele_id, on_source_update)
 
     cp.element.update_options(
         create_options(self._dataSource.get_filtered_data(cp.element))

{ex4nicegui-0.5.1 → ex4nicegui-0.5.3}/ex4nicegui/bi/elements/ui_slider.py

@@ -28,7 +28,7 @@ class SliderResult(UiResult[ui.slider]):
 
     def _reset_state(self):
         min = self._init_data["min"]
-        max = self._init_data["max"]
+        max = self._init_data["max"]  # noqa: F841
         self._ref_value.value = min
         self.element.set_value(min)
 

{ex4nicegui-0.5.1 → ex4nicegui-0.5.3}/ex4nicegui/bi/elements/ui_table.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, Union
 from nicegui import ui
 from ex4nicegui.bi.dataSource import DataSource
 from .models import UiResult
@@ -52,7 +52,7 @@ def ui_table(
         cp.columns = _merge_columns(fixed_columns, opts["columns"])
         cp.update()
 
-    info = self._dataSource._register_component(cp.id, on_source_update)
+    self._dataSource._register_component(cp.id, on_source_update)
 
     on_source_update()
 

{ex4nicegui-0.5.1 → ex4nicegui-0.5.3}/ex4nicegui/bi/protocols.py

@@ -5,7 +5,6 @@ from ex4nicegui.bi.types import (
     _TFilterCallback,
     _TDuplicates_column_values_sort_options,
 )
-from .types import _TFilterCallback
 from ex4nicegui.utils import common as utils_common
 
 

{ex4nicegui-0.5.1 → ex4nicegui-0.5.3}/ex4nicegui/bi/types.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 from typing import Callable, Dict, Literal, TypeVar
-from typing import TYPE_CHECKING
 
 
 _TData = TypeVar("_TData")

{ex4nicegui-0.5.1 → ex4nicegui-0.5.3}/ex4nicegui/experimental_/__init__.py

@@ -1 +1,5 @@
 from . import gridLayout as exp_ui
+
+__all__ = [
+    "exp_ui",
+]

ex4nicegui-0.5.3/ex4nicegui/experimental_/gridLayout/__init__.py

@@ -0,0 +1,8 @@
+from .index import column, row, item, grid_flex
+
+__all__ = [
+    "column",
+    "row",
+    "item",
+    "grid_flex",
+]

ex4nicegui-0.5.3/ex4nicegui/gsap/__init__.py

@@ -0,0 +1,12 @@
+from .gsap import set_defaults, from_, to, new, run_script
+from .timeline import Timeline as timeline
+
+
+__all__ = [
+    "set_defaults",
+    "from_",
+    "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,
+  },
+};