instaui 0.1.9__py3-none-any.whl → 0.1.10__py3-none-any.whl

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/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/components/echarts/echarts.js

@@ -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/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/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/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/components/html/paragraph.py

@@ -7,6 +7,16 @@ if TYPE_CHECKING:
 
 
 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]],

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/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/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

instaui/event/web_event.py

@@ -20,8 +20,8 @@ class WebEvent(Jsonable, EventMixin, typing.Generic[P, R]):
     def __init__(
         self,
         fn: typing.Callable[P, R],
-        inputs: typing.List[CanInputMixin],
-        outputs: typing.List[CanOutputMixin],
+        inputs: typing.Sequence[CanInputMixin],
+        outputs: typing.Sequence[CanOutputMixin],
     ):
         self._inputs = inputs
         self._outputs = outputs
@@ -36,7 +36,7 @@ class WebEvent(Jsonable, EventMixin, typing.Generic[P, R]):
     def copy_with_extends(self, extends: typing.Sequence[CanInputMixin]):
         return WebEvent(
             fn=self._fn,
-            inputs=self._inputs + list(extends),
+            inputs=list(self._inputs) + list(extends),
             outputs=self._outputs,
         )
 
@@ -76,32 +76,43 @@ class WebEvent(Jsonable, EventMixin, typing.Generic[P, R]):
         return data
 
 
-@typing.overload
-def ui_event(fn: typing.Callable[P, R]) -> WebEvent[P, R]: ...
+def event(
+    *,
+    inputs: typing.Optional[typing.Sequence] = None,
+    outputs: typing.Optional[typing.Sequence] = None,
+):
+    """
+    Creates an event handler decorator for binding reactive logic to component events.
 
+    Args:
+        inputs (typing.Optional[typing.Sequence], optional): Reactive sources (state objects, computed properties)
+                                   that should be accessible during event handling.
+                                   These values will be passed to the decorated function
+                                   when the event fires.
+        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.
 
-@typing.overload
-def ui_event(
-    *,
-    inputs: typing.Optional[typing.Union[_T_input, typing.Sequence[_T_input]]] = None,
-    outputs: typing.Optional[
-        typing.Union[_T_output, typing.Sequence[_T_output]]
-    ] = None,
-) -> typing.Callable[[typing.Callable[P, R]], WebEvent[P, R]]: ...
+    # Example:
+    .. code-block:: python
+        from instaui import ui, html
+
+        a = ui.state(0)
 
+        @ui.event(inputs=[a], outputs=[a])
+        def plus_one(a):
+            return a + 1
 
-def ui_event(
-    fn: typing.Optional[typing.Callable[P, R]] = None, *, inputs=None, outputs=None
-) -> typing.Union[
-    WebEvent[P, R], typing.Callable[[typing.Callable[P, R]], WebEvent[P, R]]
-]:
-    inputs = [inputs] if isinstance(inputs, CanInputMixin) else inputs
-    outputs = [outputs] if isinstance(outputs, CanOutputMixin) else outputs
-    if fn is None:
+        html.button("click me").on_click(plus_one)
+        html.paragraph(a)
 
-        def wrapper(fn: typing.Callable[P, R]):
-            return WebEvent(fn, inputs=inputs or [], outputs=outputs or [])
+    """
 
-        return wrapper
+    def wrapper(func: typing.Callable[P, R]):
+        return WebEvent(
+            func,
+            inputs or [],
+            outputs=outputs or [],
+        )
 
-    return WebEvent(fn, inputs=inputs or [], outputs=outputs or [])
+    return wrapper

instaui/handlers/_utils.py

@@ -23,17 +23,20 @@ class HandlerInfo:
     fn: Callable
     fn_location_info: str
     outputs_binding_count: int = 0
-    hanlder_param_converters: List[pydantic_system.TypeAdapterProtocol] = field(
+    handler_param_converters: List[pydantic_system.TypeAdapterProtocol] = field(
         default_factory=list
     )
+    is_last_param_args: bool = False
 
     def get_handler_args(self, input_values: List):
+        real_param_converters = _try_expand_params_converters(
+            self.handler_param_converters, input_values, self.is_last_param_args
+        )
+
         try:
             return [
                 param_converter.to_python_value(value)
-                for param_converter, value in zip(
-                    self.hanlder_param_converters, input_values
-                )
+                for param_converter, value in zip(real_param_converters, input_values)
             ]
         except pydantic_core._pydantic_core.ValidationError as e:
             raise ValueError(f"invalid input[{self.fn_location_info}]: {e}") from None
@@ -49,6 +52,7 @@ class HandlerInfo:
     ):
         custom_type_adapter_map = custom_type_adapter_map or {}
         params_infos = func_system.get_fn_params_infos(handler)
+        is_last_param_args = func_system.is_last_param_args(handler)
         param_converters = [
             custom_type_adapter_map.get(
                 idx, pydantic_system.create_type_adapter(param_type)
@@ -62,5 +66,23 @@ class HandlerInfo:
             handler,
             f'File "{file}", line {lineno}',
             outputs_binding_count,
-            hanlder_param_converters=param_converters,
+            handler_param_converters=param_converters,
+            is_last_param_args=is_last_param_args,
         )
+
+
+def _try_expand_params_converters(
+    old_param_converters: List[pydantic_system.TypeAdapterProtocol],
+    input_values: List,
+    is_last_param_args: bool,
+):
+    if not is_last_param_args:
+        return old_param_converters
+
+    diff = len(input_values) - len(old_param_converters)
+    if diff == 0:
+        return old_param_converters
+
+    arg_param_converters = [old_param_converters[-1]] * diff
+
+    return [*old_param_converters[:], *arg_param_converters]

instaui/static/insta-ui.css

@@ -1 +1 @@
-:root{color-scheme:light dark}:where(body){--insta-column-gap: 1rem;height:100vh}:where(*){box-sizing:border-box}:where(#app){height:100%}:where(.app-box,.insta-main){height:100%;overflow-y:auto}:where(.insta-main){--insta-padding: 16px;padding:var(--insta-padding, 16px)}
+:root{color-scheme:light dark}:where(body){--insta-column-gap: 1rem;height:100vh}:where(*){box-sizing:border-box;margin:0;padding:0}:where(#app){height:100%}:where(.app-box,.insta-main){height:100%;overflow-y:auto}:where(.insta-main){--insta-padding: 16px;padding:var(--insta-padding, 16px)}