instaui 0.1.15__py2.py3-none-any.whl

instaui/watch/js_watch.py

@@ -0,0 +1,110 @@
+import typing
+from . import _types
+from . import _utils
+
+from instaui.common.jsonable import Jsonable
+from instaui.runtime._app import get_current_scope
+
+from instaui.vars.mixin_types.py_binding import CanOutputMixin
+from instaui.vars.mixin_types.common_type import TObservableInput
+from instaui._helper import observable_helper
+
+
+class JsWatch(Jsonable):
+    def __init__(
+        self,
+        code: str,
+        inputs: typing.Optional[typing.Sequence[TObservableInput]] = None,
+        outputs: typing.Optional[typing.Sequence[CanOutputMixin]] = None,
+        immediate: bool = True,
+        deep: typing.Union[bool, int] = False,
+        once: bool = False,
+        flush: typing.Optional[_types.TFlush] = None,
+    ) -> None:
+        inputs = observable_helper.auto_made_inputs_to_slient(inputs, outputs)
+
+        get_current_scope().register_js_watch(self)
+
+        self.code = code
+
+        self._inputs, self._is_slient_inputs, self._is_data = (
+            observable_helper.analyze_observable_inputs(list(inputs or []))
+        )
+        self._outputs = [output._to_output_config() for output in outputs or []]
+
+        if immediate is not True:
+            self.immediate = immediate
+
+        if deep is not False:
+            _utils.assert_deep(deep)
+            self.deep = deep
+
+        if once is not False:
+            self.once = once
+
+        if flush is not None:
+            self.flush = flush
+
+    def _to_json_dict(self):
+        data = super()._to_json_dict()
+
+        if self._inputs:
+            data["inputs"] = self._inputs
+
+        if sum(self._is_slient_inputs) > 0:
+            data["slient"] = self._is_slient_inputs
+
+        if sum(self._is_data) > 0:
+            data["data"] = self._is_data
+
+        if self._outputs:
+            data["outputs"] = self._outputs
+
+        return data
+
+
+def js_watch(
+    *,
+    inputs: typing.Optional[typing.Sequence] = None,
+    outputs: typing.Optional[typing.Sequence] = None,
+    code: str,
+    immediate: bool = True,
+    deep: typing.Union[bool, int] = False,
+    once: bool = False,
+    flush: typing.Optional[_types.TFlush] = None,
+):
+    """
+    Creates a client-side observer that executes JavaScript code in response to reactive source changes.
+
+    Args:
+        inputs (typing.Optional[typing.Sequence], optional): Reactive sources to observe. Changes to these sources
+                                   trigger the watcher's JavaScript execution.
+        outputs (typing.Optional[typing.Sequence], optional): Output targets associated with this watcher. Used for
+                                    coordination with other observers.
+        code (str, optional): JavaScript code to execute when changes are detected. The code has access
+                  to the current values of observed inputs through the `args` parameter.
+        immediate (bool, optional):If True, executes the watcher immediately after creation with current values. Defaults to True.
+        deep (typing.Union[bool, int], optional): Controls depth of change detection:
+                               - True: Recursively tracks nested properties
+                               - False: Shallow comparison only
+                               - int: Maximum depth level to track (for complex objects).
+                               Defaults to False.
+        once (bool, optional): If True, automatically stops observation after first trigger. Defaults to False.
+        flush (typing.Optional[_types.TFlush], optional): Controls when to flush updates:
+                                      - 'sync': Execute immediately on change
+                                      - 'post': Batch updates and execute after current tick
+                                      - 'pre': Execute before render phase (if applicable)
+
+    # Example:
+    .. code-block:: python
+        from instaui import ui, html
+
+        num = ui.state(0)
+        msg = ui.state('')
+        ui.js_watch(inputs=[num], outputs=[msg], code="num => `The number is ${num}`")
+
+        html.number(num)
+        ui.label(msg)
+    """
+
+    return JsWatch(code, inputs, outputs, immediate, deep, once, flush)

instaui/watch/vue_watch.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+from typing import (
+    Any,
+    Dict,
+    Optional,
+    Sequence,
+    Union,
+    cast,
+)
+
+from instaui.vars.mixin_types.observable import ObservableMixin
+
+from . import _types
+from . import _utils
+
+from instaui.common.jsonable import Jsonable
+from instaui.runtime._app import get_current_scope
+
+
+class VueWatch(Jsonable):
+    def __init__(
+        self,
+        sources: Union[Any, Sequence],
+        callback: str,
+        *,
+        bindings: Optional[Dict[str, Any]] = None,
+        immediate: bool = False,
+        deep: Union[bool, int] = False,
+        once: bool = False,
+        flush: Optional[_types.TFlush] = None,
+    ) -> None:
+        get_current_scope().register_vue_watch(self)
+
+        self.code = callback
+
+        if not isinstance(sources, Sequence):
+            sources = [sources]
+
+        onData = [int(not isinstance(varObj, ObservableMixin)) for varObj in sources]
+
+        if sum(onData) > 0:
+            self.onData = onData
+
+        self.on = [
+            cast(ObservableMixin, varObj)._to_observable_config()
+            if isinstance(varObj, ObservableMixin)
+            else varObj
+            for varObj in sources
+        ]
+
+        if bindings:
+            bindData = [
+                int(not isinstance(v, ObservableMixin)) for v in bindings.values()
+            ]
+
+            if sum(bindData) > 0:
+                self.bindData = bindData
+
+            self.bind = {
+                k: cast(ObservableMixin, v)._to_observable_config()
+                if isinstance(v, ObservableMixin)
+                else v
+                for k, v in bindings.items()
+            }
+
+        if immediate is not False:
+            self.immediate = immediate
+
+        if deep is not False:
+            _utils.assert_deep(deep)
+            self.deep = deep
+
+        if once is not False:
+            self.once = once
+
+        if flush is not None:
+            self.flush = flush

instaui/watch/web_watch.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+import inspect
+import typing
+from typing_extensions import ParamSpec
+from . import _types
+from . import _utils
+
+from instaui.common.jsonable import Jsonable
+from instaui.runtime._app import get_app_slot, get_current_scope
+from instaui.handlers import watch_handler
+
+from instaui.vars.mixin_types.py_binding import CanOutputMixin
+from instaui.vars.mixin_types.element_binding import ElementBindingMixin
+from instaui.vars.mixin_types.common_type import TObservableInput
+from instaui._helper import observable_helper
+
+_SYNC_TYPE = "sync"
+_ASYNC_TYPE = "async"
+
+P = ParamSpec("P")
+R = typing.TypeVar("R")
+
+
+class WebWatch(Jsonable, typing.Generic[P, R]):
+    def __init__(
+        self,
+        func: typing.Callable[P, R],
+        inputs: typing.Optional[typing.Sequence[TObservableInput]] = None,
+        outputs: typing.Optional[typing.Sequence[CanOutputMixin]] = None,
+        immediate: bool = True,
+        deep: typing.Union[bool, int] = True,
+        once: bool = False,
+        flush: typing.Optional[_types.TFlush] = None,
+        _debug: typing.Optional[typing.Any] = None,
+    ) -> None:
+        self.__org_inputs = inputs or []
+        inputs = observable_helper.auto_made_inputs_to_slient(inputs, outputs)
+
+        get_current_scope().register_web_watch(self)
+
+        self._inputs, self._is_slient_inputs, self._is_data = (
+            observable_helper.analyze_observable_inputs(list(inputs or []))
+        )
+
+        self._outputs = [output._to_output_config() for output in outputs or []]
+        self._fn = func
+        self._immediate = immediate
+        self._deep = deep
+        self._once = once
+        self._flush = flush
+        self._debug = _debug
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        return self._fn(*args, **kwargs)
+
+    def _to_json_dict(self):
+        data = super()._to_json_dict()
+
+        app = get_app_slot()
+
+        for _input in self.__org_inputs:
+            if isinstance(_input, ElementBindingMixin):
+                _input._mark_used()
+
+        if app.mode == "web":
+            hkey = watch_handler.create_handler_key(
+                page_path=app.page_path,
+                handler=self._fn,
+            )
+
+            watch_handler.register_handler(hkey, self._fn, len(self._outputs))
+
+            data["fType"] = (
+                _ASYNC_TYPE if inspect.iscoroutinefunction(self._fn) else _SYNC_TYPE
+            )
+            data["key"] = hkey
+            if self._inputs:
+                data["inputs"] = self._inputs
+
+            if sum(self._is_slient_inputs) > 0:
+                data["slient"] = self._is_slient_inputs
+
+            if sum(self._is_data) > 0:
+                data["data"] = self._is_data
+
+            if self._debug:
+                data["debug"] = self._debug
+
+            if self._outputs:
+                data["outputs"] = self._outputs
+
+            if self._immediate is not True:
+                data["immediate"] = self._immediate
+
+            if self._deep is not True:
+                _utils.assert_deep(self._deep)
+                data["deep"] = self._deep
+            if self._once is not False:
+                data["once"] = self._once
+            if self._flush is not None:
+                data["flush"] = self._flush
+
+            return data
+
+        return {}
+
+
+def watch(
+    *,
+    inputs: typing.Optional[typing.Sequence] = None,
+    outputs: typing.Optional[typing.Sequence] = None,
+    immediate: bool = True,
+    deep: typing.Union[bool, int] = True,
+    once: bool = False,
+    flush: typing.Optional[_types.TFlush] = None,
+    _debug: typing.Optional[typing.Any] = None,
+):
+    """
+    Creates an observer that tracks changes in reactive sources and triggers callbacks.
+
+    Args:
+        inputs (typing.Optional[typing.Sequence], optional): Reactive sources to observe (state objects or computed properties).
+                                   Changes to these sources trigger the watcher callback.
+        outputs (typing.Optional[typing.Sequence], optional): Output targets associated with this watcher.
+                                    Used for coordination with computed properties or other observers.
+        immediate (bool, optional): If True, executes callback immediately after creation with current values. Defaults to True.
+        deep (typing.Union[bool, int], optional): Controls depth of change detection:
+                               - True: Recursively tracks nested properties
+                               - False: Shallow comparison only
+                               - int: Maximum depth level to track (for complex objects).
+                               Defaults to True.
+        once (bool, optional):  If True, automatically stops observation after first trigger. Defaults to False.
+        flush (typing.Optional[_types.TFlush], optional): Controls when to flush updates:
+                                      - 'sync': Execute immediately on change
+                                      - 'post': Batch updates and execute after current tick
+                                      - 'pre': Execute before render phase (if applicable)
+
+    # Example:
+    .. code-block:: python
+        from instaui import ui, html
+
+        num = ui.state(0)
+        msg = ui.state('')
+
+        @ui.watch(inputs=[num], outputs=[msg])
+        def when_num_change(num):
+            return f"The number is {num}"
+
+        html.number(num)
+        ui.label(msg)
+
+    list append:
+    .. code-block:: python
+        from instaui import ui, html
+
+        num = ui.state(0)
+        msg = ui.state([])
+
+        @ui.watch(inputs=[num, msg], outputs=[msg])
+        def when_num_change(num, msg:list):
+            msg.append(f"The number changed to {num}")
+            return msg
+
+        html.number(num)
+        ui.label(msg)
+
+    """
+
+    def wrapper(func: typing.Callable[P, R]):
+        return WebWatch(
+            func,
+            inputs,
+            outputs=outputs,
+            immediate=immediate,
+            deep=deep,
+            once=once,
+            flush=flush,
+            _debug=_debug,
+        )
+
+    return wrapper

instaui/webview/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["WebviewWrapper"]
+from .index import WebviewWrapper

instaui/webview/_utils.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+import shutil
+
+
+def reset_dir(dir_path: Path):
+    if dir_path.exists():
+        shutil.rmtree(dir_path)
+    dir_path.mkdir(exist_ok=True)

instaui/webview/api.py

@@ -0,0 +1,72 @@
+from typing import Any, Dict
+
+
+from instaui.runtime._app import get_app_slot
+from instaui.handlers import watch_handler
+from instaui.handlers import event_handler
+from instaui.skip import is_skip_output
+
+
+class Api:
+    def watch_call(self, data: Dict):
+        hkey = data.pop("key")
+        handler_info = watch_handler.get_handler_info(hkey)
+        if handler_info is None:
+            return {"error": "watch handler not found"}
+
+        update_app_page_info(data)
+
+        result = handler_info.fn(
+            *handler_info.get_handler_args(_get_binds_from_data(data))
+        )
+        return response_data(handler_info.outputs_binding_count, result)
+
+    def event_call(self, data: Dict):
+        handler = event_handler.get_handler(data["hKey"])
+        if handler is None:
+            raise ValueError("event handler not found")
+
+        update_app_page_info(data)
+
+
+        args = [bind for bind in data.get("bind", [])]
+
+        result = handler.fn(*handler.get_handler_args(args))
+        return response_data(handler.outputs_binding_count, result)
+
+
+def update_app_page_info(data: Dict):
+    app = get_app_slot()
+
+    page_info = data.get("page", {})
+    app._page_path = page_info["path"]
+
+    if "params" in page_info:
+        app._page_params = page_info["params"]
+
+    if "queryParams" in page_info:
+        app._query_params = page_info["queryParams"]
+
+
+def _get_binds_from_data(data: Dict):
+    return data.get("input", [])
+
+
+def response_data(outputs_binding_count: int, result: Any):
+    data = {}
+    if outputs_binding_count > 0:
+        if not isinstance(result, tuple):
+            result = [result]
+
+        result_infos = [(r, int(is_skip_output(r))) for r in result]
+
+        if len(result_infos) == 1 and result_infos[0][1] == 1:
+            return data
+
+        data["values"] = [0 if info[1] == 1 else info[0] for info in result_infos]
+        skips = [info[1] for info in result_infos]
+
+        if sum(skips) > 0:
+            data["skips"] = skips
+
+    return data

instaui/webview/func.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+import itertools
+from pathlib import Path
+import instaui.consts as consts
+from instaui.runtime._app import get_app_slot, get_default_app_slot
+from instaui.template import render_zero_html
+from instaui.template import zero_template
+from instaui.html_tools import to_config_data
+from instaui.runtime.dataclass import JsLink
+from instaui.runtime.resource import HtmlResource
+
+
+def get_template_model():
+    system_slot = get_app_slot()
+
+    merge_global_resources = (system_slot.meta or {}).get(
+        "merge_global_resources", True
+    )
+
+    default_app_slot = get_default_app_slot()
+    html_resource = system_slot._html_resource
+    default_html_resource = (
+        default_app_slot._html_resource
+        if merge_global_resources
+        else _empty_html_resource()
+    )
+
+    config_data = to_config_data()
+
+    model = zero_template.ZeroTemplateModel(
+        vue_js_code=consts.VUE_ES_JS_PATH,
+        instaui_js_code=consts.APP_ES_JS_PATH,
+        css_links=[
+            consts.APP_CSS_PATH,
+        ],
+        config_dict=config_data,
+        favicon=html_resource.favicon
+        or default_html_resource.favicon
+        or consts.FAVICON_PATH,
+        title=html_resource.title or default_html_resource.title or consts.PAGE_TITLE,
+    )
+
+    # register custom components
+    for component in system_slot._component_dependencies:
+        if not component.esm:
+            continue
+
+        model.vue_app_component.append(
+            zero_template.ZeroVueAppComponent(
+                name=component.tag_name,
+                url=component.esm,
+            )
+        )
+
+        if component.css:
+            for css_link in component.css:
+                model.css_links.append(css_link)
+
+        if component.externals:
+            for name, url in component.externals.items():
+                if url.is_file():
+                    model.add_extra_import_map(name, url)
+
+    # register custom plugins
+    for plugin in set(
+        itertools.chain(
+            system_slot._plugin_dependencies, default_app_slot._plugin_dependencies
+        )
+    ):
+        if not plugin.esm:
+            continue
+
+        model.vue_app_use.append(plugin.name)
+
+        model.add_extra_import_map(plugin.name, plugin.esm)
+
+        if plugin.css:
+            for css_link in plugin.css:
+                model.css_links.append(css_link)
+
+    # css file link to web static link
+    for link in html_resource.get_valid_css_links(
+        default_html_resource._css_links_manager
+    ):
+        if isinstance(link, Path):
+            model.css_links.append(link)
+
+    # js file link to web static link
+    for info in html_resource.get_valid_js_links(
+        default_html_resource._js_links_manager
+    ):
+        if isinstance(info.link, Path):
+            model.js_links.append(JsLink(info.link))
+
+    for js_code in itertools.chain(
+        html_resource._script_tags, default_html_resource._script_tags
+    ):
+        model.script_tags.append(js_code)
+
+    for sylte_code in itertools.chain(
+        html_resource._style_tags, default_html_resource._style_tags
+    ):
+        model.style_tags.append(sylte_code)
+
+    return model
+
+
+def to_html_str():
+    model = get_template_model()
+    return render_zero_html(model)
+
+
+def _empty_html_resource():
+    return HtmlResource()