instaui 0.1.9__tar.gz → 0.1.11__tar.gz

instaui-0.1.11/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: instaui
+Version: 0.1.11
+Summary: insta-ui is a Python-based UI library for rapidly building user interfaces.
+Author-email: CrystalWindSnake <568166495@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gui,ui,web
+Requires-Python: <3.13,>=3.8
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: orjson>=3.10.15
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: typing-extensions>=4.13.2
+Provides-Extra: all
+Requires-Dist: fastapi[standard]; extra == 'all'
+Requires-Dist: pywebview; extra == 'all'
+Requires-Dist: uvicorn; extra == 'all'
+Provides-Extra: web
+Requires-Dist: fastapi[standard]; extra == 'web'
+Requires-Dist: pydantic<3.0.0,>=2.10.6; extra == 'web'
+Requires-Dist: uvicorn; extra == 'web'
+Provides-Extra: webview
+Requires-Dist: pydantic<3.0.0,>=2.10.6; extra == 'webview'
+Requires-Dist: pywebview; extra == 'webview'
+Description-Content-Type: text/markdown
+
+# insta-ui
+
+<div align="center">
+
+English| [简体中文](./README.md)
+
+</div>
+
+## 📖 Introduction
+insta-ui is a Python-based UI library for quickly building user interfaces.
+
+## ⚙️ Features
+Three modes:
+
+- Web mode: Generate web (stateless) applications.
+- Web View mode: Generate web view applications that can be packaged as native apps (no need to start a web server).
+- Zero mode: Generate pure HTML files that run directly in browsers without any dependencies.
+
+ 
+## 📦 Installation
+
+Zero mode:
+
+```
+pip install instaui -U
+```
+
+web mode
+
+```
+pip install instaui[web] -U
+```
+
+Web View mode
+```
+pip install instaui[webview] -U
+```
+
+
+## 🖥️ Quick Start
+Below is a simple example of number summation. The result color changes dynamically based on the sum:
+
+```python
+from instaui import ui, arco
+arco.use()
+
+@ui.page('/')
+def home():
+    num1 = ui.state(0)
+    num2 = ui.state(0)
+
+    # Automatically recalculates result when num1 or num2 changes 
+    @ui.computed(inputs=[num1, num2])
+    def result(num1: int, num2: int):
+        return num1 + num2
+
+    # Automatically updates text_color when result changes
+    @ui.computed(inputs=[result])
+    def text_color(result: int):
+        return "red" if result % 2 == 0 else "blue"
+
+    # UI components  
+    arco.input_number(num1)
+    ui.label("+")
+    arco.input_number(num2)
+    ui.label("=")
+    ui.label(result).style({"color": text_color})
+
+ui.server().run()
+```
+
+Replace `ui.server().run()` with `ui.webview().run()` to switch to Web View mode:
+
+```python
+...
+
+# ui.server().run()
+ui.webview().run()
+```
+
+To execute computations on the client side instead of the server, use `ui.js_computed` instead of `ui.computed`:
+
+```python
+from instaui import ui, arco
+arco.use()
+
+@ui.page('/')
+def home():
+    num1 = ui.state(0)
+    num2 = ui.state(0)
+
+    result = ui.js_computed(inputs=[num1, num2], code="(num1, num2) => num1 + num2")
+    text_color = ui.js_computed(inputs=[result], code="(result) => result % 2 === 0? 'red' : 'blue'")
+
+    # UI components
+    ...
+
+...
+
+```
+
+In this case, all interactions will run on the client side. Use `Zero mode` to generate a standalone HTML file:
+
+```python
+from instaui import ui, arco,zero
+arco.use()
+
+@ui.page('/')
+def home():
+    num1 = ui.state(0)
+    num2 = ui.state(0)
+
+    result = ui.js_computed(inputs=[num1, num2], code="(num1, num2) => num1 + num2")
+    text_color = ui.js_computed(inputs=[result], code="(result) => result % 2 === 0? 'red' : 'blue'")
+
+    # UI components
+    arco.input_number(num1)
+    ui.label("+")
+    arco.input_number(num2)
+    ui.label("=")
+    ui.label(result).style({"color": text_color})
+
+with zero() as z:
+    home()
+    z.to_html('index.html')
+
+```

instaui-0.1.11/README.md

@@ -0,0 +1,127 @@
+# insta-ui
+
+<div align="center">
+
+English| [简体中文](./README.md)
+
+</div>
+
+## 📖 Introduction
+insta-ui is a Python-based UI library for quickly building user interfaces.
+
+## ⚙️ Features
+Three modes:
+
+- Web mode: Generate web (stateless) applications.
+- Web View mode: Generate web view applications that can be packaged as native apps (no need to start a web server).
+- Zero mode: Generate pure HTML files that run directly in browsers without any dependencies.
+
+ 
+## 📦 Installation
+
+Zero mode:
+
+```
+pip install instaui -U
+```
+
+web mode
+
+```
+pip install instaui[web] -U
+```
+
+Web View mode
+```
+pip install instaui[webview] -U
+```
+
+
+## 🖥️ Quick Start
+Below is a simple example of number summation. The result color changes dynamically based on the sum:
+
+```python
+from instaui import ui, arco
+arco.use()
+
+@ui.page('/')
+def home():
+    num1 = ui.state(0)
+    num2 = ui.state(0)
+
+    # Automatically recalculates result when num1 or num2 changes 
+    @ui.computed(inputs=[num1, num2])
+    def result(num1: int, num2: int):
+        return num1 + num2
+
+    # Automatically updates text_color when result changes
+    @ui.computed(inputs=[result])
+    def text_color(result: int):
+        return "red" if result % 2 == 0 else "blue"
+
+    # UI components  
+    arco.input_number(num1)
+    ui.label("+")
+    arco.input_number(num2)
+    ui.label("=")
+    ui.label(result).style({"color": text_color})
+
+ui.server().run()
+```
+
+Replace `ui.server().run()` with `ui.webview().run()` to switch to Web View mode:
+
+```python
+...
+
+# ui.server().run()
+ui.webview().run()
+```
+
+To execute computations on the client side instead of the server, use `ui.js_computed` instead of `ui.computed`:
+
+```python
+from instaui import ui, arco
+arco.use()
+
+@ui.page('/')
+def home():
+    num1 = ui.state(0)
+    num2 = ui.state(0)
+
+    result = ui.js_computed(inputs=[num1, num2], code="(num1, num2) => num1 + num2")
+    text_color = ui.js_computed(inputs=[result], code="(result) => result % 2 === 0? 'red' : 'blue'")
+
+    # UI components
+    ...
+
+...
+
+```
+
+In this case, all interactions will run on the client side. Use `Zero mode` to generate a standalone HTML file:
+
+```python
+from instaui import ui, arco,zero
+arco.use()
+
+@ui.page('/')
+def home():
+    num1 = ui.state(0)
+    num2 = ui.state(0)
+
+    result = ui.js_computed(inputs=[num1, num2], code="(num1, num2) => num1 + num2")
+    text_color = ui.js_computed(inputs=[result], code="(result) => result % 2 === 0? 'red' : 'blue'")
+
+    # UI components
+    arco.input_number(num1)
+    ui.label("+")
+    arco.input_number(num2)
+    ui.label("=")
+    ui.label(result).style({"color": text_color})
+
+with zero() as z:
+    home()
+    z.to_html('index.html')
+
+```

{instaui-0.1.9 → instaui-0.1.11}/instaui/_helper/observable_helper.py

@@ -1,6 +1,6 @@
 import typing
 from instaui.vars.mixin_types.observable import ObservableMixin
-from instaui.vars.mixin_types.py_binding import CanInputMixin
+from instaui.vars.mixin_types.py_binding import CanInputMixin, CanOutputMixin
 from instaui.ui_functions.input_slient_data import InputSilentData
 
 from instaui.vars.mixin_types.common_type import TObservableInput
@@ -33,3 +33,13 @@ def analyze_observable_inputs(inputs: typing.List[TObservableInput]):
             result_inputs.append(input)
 
     return result_inputs, slients, datas
+
+
+def auto_made_inputs_to_slient(
+    inputs: typing.Optional[typing.Sequence[TObservableInput]],
+    outputs: typing.Optional[typing.Sequence[CanOutputMixin]],
+):
+    if inputs is None or outputs is None:
+        return inputs
+
+    return [InputSilentData(input) if input in outputs else input for input in inputs]

{instaui-0.1.9 → instaui-0.1.11}/instaui/arco/components/radio.py

@@ -17,7 +17,7 @@ class Radio(Element):
     ):
         super().__init__("a-radio")
 
-        try_setup_vmodel(self, value)
+        self.props({"value": value})
         self.props(handle_props(kwargs))  # type: ignore
 
     def on_change(

{instaui-0.1.9 → instaui-0.1.11}/instaui/arco/components/select.py

@@ -10,6 +10,9 @@ from instaui.arco import component_types
 from instaui.event.event_mixin import EventMixin
 from ._utils import handle_props, try_setup_vmodel
 
+
+_TSelectValue = typing.Union[str, int, typing.Sequence[str], typing.Sequence[int]]
+
 _OPTIONS_TRANSLATE_JS: typing.Final = r"""(options)=>{
     if (Array.isArray(options)){
         const obj = {};
@@ -27,7 +30,7 @@ class Select(Element):
     def __init__(
         self,
         options: TMaybeRef[typing.Union[typing.Sequence, typing.Dict]],
-        value: typing.Optional[TMaybeRef[typing.Union[str, int]]] = None,
+        value: typing.Optional[TMaybeRef[_TSelectValue]] = None,
         **kwargs: Unpack[component_types.TSelect],
     ):
         super().__init__("a-select")

{instaui-0.1.9 → instaui-0.1.11}/instaui/components/echarts/echarts.js

@@ -48,7 +48,7 @@ function setOption(root, chartIns, props) {
   if (!chartIns.value) {
     init(root, chartIns, props);
   } else {
-    chartIns.value.setOption(props.option, props.updateOptions || {});
+    chartIns.value.setOption(props.option || {}, props.updateOptions || {});
   }
 }
 
@@ -74,8 +74,8 @@ function autoResize(root, chartIns, props) {
         if (!isInitialResize) {
           isInitialResize = true;
           if (
-            root.offsetWidth === offsetWidth &&
-            root.offsetHeight === offsetHeight
+            root.value.offsetWidth === offsetWidth &&
+            root.value.offsetHeight === offsetHeight
           ) {
             return;
           }
@@ -105,9 +105,11 @@ function setChartEvents(root, chartIns, emit, props) {
   if (chartEvents) {
     chartEvents.forEach(event => {
       chartIns.value.on(event, (...args) => {
-        const eventArgs = args[0]
-        delete eventArgs['event']
-        delete eventArgs['$vars']
+        if (args.length > 0) {
+          const eventArgs = args[0]
+          delete eventArgs['event']
+          delete eventArgs['$vars']
+        }
 
         emit(`chart:${event}`, ...args)
       });

{instaui-0.1.9 → instaui-0.1.11}/instaui/components/echarts/echarts.py

@@ -153,7 +153,7 @@ class ECharts(
         self._zr_events: Set[str] = set()
         self.props({"option": option})
 
-        if init_options:
+        if init_options is not None:
             self.props({"initOptions": init_options})
 
         if update_options:

{instaui-0.1.9 → instaui-0.1.11}/instaui/components/element.py

@@ -96,8 +96,11 @@ class Element(Component):
         self._props.update(self._default_props)
         self._proxy_props: List[ElementBindingMixin] = []
 
-        self._js_events: defaultdict[str, List[EventMixin]] = defaultdict(list)
-        self._web_events: defaultdict[str, List[EventMixin]] = defaultdict(list)
+        self._events: defaultdict[str, List[EventMixin]] = defaultdict(list)
+
+        # self._js_events: defaultdict[str, List[EventMixin]] = defaultdict(list)
+        # self._web_events: defaultdict[str, List[EventMixin]] = defaultdict(list)
+        # self._vue_events: defaultdict[str, List[EventMixin]] = defaultdict(list)
         self._directives: Dict[Directive, None] = {}
 
         self._slot_manager = SlotManager()
@@ -328,11 +331,7 @@ class Element(Component):
         if extends:
             handler = handler.copy_with_extends(extends)
 
-        if handler.event_type() == "js":
-            self._js_events[event_name].append(handler)
-
-        if handler.event_type() == "web":
-            self._web_events[event_name].append(handler)
+        self._events[event_name].append(handler)
 
         return self
 
@@ -452,8 +451,8 @@ class Element(Component):
                 v._to_element_binding_config() for v in self._proxy_props
             ]
 
-        if self._js_events or self._web_events:
-            data["events"] = _normalize_events(self._js_events, self._web_events)
+        if self._events:
+            data["events"] = _normalize_events(self._events)
 
         if self._slot_manager.has_slot():
             data["slots"] = self._slot_manager
@@ -477,20 +476,11 @@ class Element(Component):
 
 
 def _normalize_events(
-    js_events: defaultdict[str, List[EventMixin]],
-    web_events: defaultdict[str, List[EventMixin]],
+    events: defaultdict[str, List[EventMixin]],
 ):
-    merged: defaultdict[str, List[EventMixin]] = defaultdict(list)
-
-    for name, events in js_events.items():
-        name = _normalize_event_name(name)
-        merged[name].extend(events)
-
-    for name, events in web_events.items():
-        name = _normalize_event_name(name)
-        merged[name].extend(events)
-
-    return dict(merged)
+    return {
+        _normalize_event_name(name): event_list for name, event_list in events.items()
+    }
 
 
 def _normalize_event_name(event_name: str):

{instaui-0.1.9 → instaui-0.1.11}/instaui/components/grid.py

@@ -121,23 +121,75 @@ class Grid(Element):
         area = f"{real_row} / {real_column} / {real_row_span} / {real_column_span}"
         return self.mark_area(area)
 
-    @classmethod
+    @staticmethod
     def auto_columns(
-        cls,
         *,
         min_width: TMaybeRef[str],
         mode: TMaybeRef[Literal["auto-fill", "auto-fit"]] = "auto-fit",
-    ) -> Grid:
-        if isinstance(min_width, ObservableMixin) or isinstance(mode, ObservableMixin):
-            template = JsComputed(
-                inputs=[min_width, mode],
-                code=r"(min_width, mode)=> `repeat(${mode}, minmax(min(${min_width},100%), 1fr))`",
-            )
+    ):
+        """
+        Generate a dynamic grid column configuration for responsive layout systems.
+
+        Creates a computed layout specification that calculates column dimensions
+        based on minimum width requirements and auto-sizing behavior. Retu
+
+        Args:
+            min_width (TMaybeRef[str]):
+                Minimum width constraint for columns as a CSS length string (e.g., "300px").
+                Accepts reactive references for dynamic updates.
+            mode (TMaybeRef[Literal["auto, optional):
+                Auto-sizing behavior strategy:
+                - "auto-fill": Preserves container space by creating additional columns
+                - "auto-fit": Adjusts columns to fit available space.
+                Defaults to "auto-fit".
+
+        Example:
+        .. code-block:: python
+
+            with ui.grid(columns=ui.grid.auto_columns(min_width="300px")):
+                ...
+        """
+        template = JsComputed(
+            inputs=[min_width, mode],
+            code=r"(min_width, mode)=> `repeat(${mode}, minmax(min(${min_width},100%), 1fr))`",
+        )
+
+        return template
+
+    @staticmethod
+    def auto_rows(
+        *,
+        min_height: TMaybeRef[str],
+        mode: TMaybeRef[Literal["auto-fill", "auto-fit"]] = "auto-fit",
+    ):
+        """
+        Generate a dynamic grid row configuration for responsive layout systems.
+
+        Creates a computed layout specification that calculates row dimensions
+        based on minimum height requirements and auto-sizing behavior.
+
+        Args:
+            min_height (TMaybeRef[str]):
+                Minimum height constraint for rows as a CSS length string (e.g., "300px").
+            mode (TMaybeRef[Literal["auto, optional):
+                Auto-sizing behavior strategy:
+                - "auto-fill": Preserves container space by creating additional rows
+                - "auto-fit": Adjusts rows to fit available space.
+                Defaults to "auto-fit".
+
+        Example:
+        .. code-block:: python
+
+            with ui.grid(rows=ui.grid.auto_rows(min_height="300px")):
+                ...
+        """
 
-        else:
-            template = f"repeat({mode}, minmax(min({min_width},100%), 1fr))"
+        template = JsComputed(
+            inputs=[min_height, mode],
+            code=r"(min_height, mode)=> `repeat(${mode}, minmax(min(${min_height},100%), 1fr))`",
+        )
 
-        return cls(columns=template)
+        return template
 
     def row_gap(self, gap: TMaybeRef[str]) -> Grid:
         return self.style({"row-gap": gap})

instaui-0.1.11/instaui/components/html/paragraph.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any, Union
+from instaui.components.element import Element
+
+if TYPE_CHECKING:
+    from instaui.vars.types import TMaybeRef
+
+
+class Paragraph(Element):
+    """
+    A component class representing an HTML `<p>` (paragraph) element.
+
+    Args:
+        text (Union[str, TMaybeRef[Any]]):The text content of the paragraph.
+                                          - If a string is provided, the content is static.
+                                          - If a `TMaybeRef` object is provided, the content
+                                            will reactively update when the referenced value changes.
+    """
+
+    def __init__(
+        self,
+        text: Union[str, TMaybeRef[Any]],
+    ):
+        super().__init__("p")
+        self.props(
+            {
+                "innerText": text,
+            }
+        )

instaui-0.1.11/instaui/components/label.py

@@ -0,0 +1,5 @@
+from instaui.components.html.span import Span
+
+
+label = Span
+""" A label element. Equivalent to `html.span`. """

{instaui-0.1.9 → instaui-0.1.11}/instaui/event/js_event.py

@@ -55,4 +55,28 @@ def js_event(
     outputs: typing.Optional[typing.Sequence] = None,
     code: str,
 ):
+    """
+    Creates a client-side event handler decorator for binding JavaScript logic to UI component events.
+
+    Args:
+        inputs (typing.Optional[typing.Sequence], optional):Reactive sources (state variables, computed values)
+                                   that should be passed to the event handler. These values
+                                   will be available in the JavaScript context through the `args` array.
+        outputs (typing.Optional[typing.Sequence], optional): Targets (state variables, UI elements) that should
+                                    update when this handler executes. Used for coordinating
+                                    interface updates after the event is processed.
+        code (str): JavaScript code to execute when the event is triggered.
+
+    # Example:
+    .. code-block:: python
+        from instaui import ui, html
+
+        a = ui.state(0)
+
+        plus_one = ui.js_event(inputs=[a], outputs=[a], code="a =>a + 1")
+
+        html.button("click me").on_click(plus_one)
+        html.paragraph(a)
+
+    """
     return JsEvent(inputs=inputs, outputs=outputs, code=code)

instaui-0.1.11/instaui/event/vue_event.py

@@ -0,0 +1,66 @@
+import typing
+from instaui.common.jsonable import Jsonable
+from instaui.vars.mixin_types.observable import ObservableMixin
+from .event_mixin import EventMixin
+
+
+class VueEvent(Jsonable, EventMixin):
+    """
+    Create an event object that can be bound to a UI component's event listener.
+
+    This function generates a callable event handler with optional contextual bindings.
+    The event logic is defined via a code string, which can reference bound variables.
+
+    Args:
+        code (str): A string containing the executable logic for the event handler.
+                    Typically contains a function body or expression that utilizes bound variables.
+        bindings (typing.Optional[typing.Dict[str, typing.Any]], optional): A dictionary mapping variable names to values that should be available in the
+            event handler's context. If None, no additional bindings are created.. Defaults to None.
+
+    Example:
+    .. code-block:: python
+        a = ui.state(1)
+
+        event = ui.vue_event(bindings={"a": a}, code=r'''()=> { a.value +=1}''')
+
+        html.span(a)
+        html.button("plus").on("click", event)
+    """
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        bindings: typing.Optional[typing.Dict[str, typing.Any]] = None,
+    ):
+        self.code = code
+        self._bindings = bindings
+
+        if bindings:
+            bindData = [
+                int(not isinstance(v, ObservableMixin)) for v in bindings.values()
+            ]
+
+            if sum(bindData) > 0:
+                self.bindData = bindData
+
+            self.bind = {
+                k: typing.cast(ObservableMixin, v)._to_observable_config()
+                if isinstance(v, ObservableMixin)
+                else v
+                for k, v in bindings.items()
+            }
+
+    def copy_with_extends(self, extends: typing.Dict):
+        raise NotImplementedError("VueEvent does not support extends")
+
+    def event_type(self):
+        return "vue"
+
+    def _to_json_dict(self):
+        data = super()._to_json_dict()
+        data["type"] = self.event_type()
+        return data
+
+
+vue_event = VueEvent