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

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/html/select.py

@@ -1,14 +1,9 @@
 from __future__ import annotations
 from typing import (
-    TYPE_CHECKING,
-    Callable,
-    Dict,
     List,
     Optional,
     Union,
-    overload,
 )
-from typing_extensions import Self
 from instaui.components.value_element import ValueElement
 from instaui.components.element import Element
 from instaui.event.event_mixin import EventMixin

instaui/components/html/table.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING, Any, List, Optional, Union
+from typing import TYPE_CHECKING, Any, List, Union
 from instaui.components.element import Element
 from instaui.components.content import Content
 from instaui.components.vfor import VFor

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/components/row.py

@@ -1,7 +1,4 @@
 from __future__ import annotations
-from typing import (
-    TypeVar,
-)
 from instaui.components.element import Element
 from instaui.vars.types import TMaybeRef
 from instaui.vars.js_computed import JsComputed

instaui/components/shiki_code/static/shiki-style.css

@@ -1,179 +1,179 @@
-:root {
-  --shiki-font-family-mono: ui-monospace, "Menlo", "Monaco", "Consolas", "Liberation Mono", "Courier New", monospace;
-  --shiki-code-line-height: 1.5;
-  --shiki-code-font-size: 0.875em;
-  --shiki-code-block-color: #67676c;
-  --shiki-icon-copy: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='rgba(128,128,128,1)' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' viewBox='0 0 24 24'%3E%3Crect width='8' height='4' x='8' y='2' rx='1' ry='1'/%3E%3Cpath d='M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2'/%3E%3C/svg%3E");
-  --shiki-icon-copied: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='rgba(128,128,128,1)' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' viewBox='0 0 24 24'%3E%3Crect width='8' height='4' x='8' y='2' rx='1' ry='1'/%3E%3Cpath d='M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2'/%3E%3Cpath d='m9 14 2 2 4-4'/%3E%3C/svg%3E");
-  --shiki-code-copy-code-border-color: #e2e2e3;
-  --shiki-code-copy-code-bg: #f6f6f7;
-  --shiki-code-copy-code-hover-border-color: #e2e2e3;
-  --shiki-code-copy-code-hover-bg: #ffffff;
-  --shiki-code-copy-code-active-text: #67676c;
-  --shiki-code-copy-copied-text-content: "Copied";
-  --shiki-code-lang-color: #929295;
-}
-@media (min-width: 640px) {
-  .shiki-code[class*=language-] {
-    border-radius: 8px;
-    margin: 15px 0;
-  }
-}
-.shiki-code[class*=language-] {
-  position: relative;
-  margin: 16px 0;
-  background-color: #f9f9f9;
-  overflow-x: auto;
-  transition: background-color 0.5s;
-  /* line numbers */
-}
-.shiki-code[class*=language-] pre,
-.shiki-code[class*=language-] code {
-  font-family: var(--shiki-font-family-mono);
-}
-.shiki-code[class*=language-] pre {
-  position: relative;
-  z-index: 1;
-  margin: 0;
-  padding: 20px 0;
-  background: transparent;
-  overflow-x: auto;
-}
-.shiki-code[class*=language-] code {
-  display: block;
-  padding: 0 24px 0 0;
-  width: fit-content;
-  min-width: 100%;
-  line-height: var(--shiki-code-line-height);
-  font-size: var(--shiki-code-font-size);
-  color: var(--shiki-code-block-color);
-  transition: color 0.5s;
-}
-.shiki-code[class*=language-] code > .line:before {
-  content: ' ';
-  padding: 0 5px;
-}
-.shiki-code[class*=language-] > button.copy {
-  direction: ltr;
-  position: absolute;
-  top: 12px;
-  right: 12px;
-  z-index: 3;
-  border: 1px solid var(--shiki-code-copy-code-border-color);
-  border-radius: 4px;
-  width: 40px;
-  height: 40px;
-  background-color: var(--shiki-code-copy-code-bg);
-  opacity: 0;
-  cursor: pointer;
-  background-image: var(--shiki-icon-copy);
-  background-position: 50%;
-  background-size: 20px;
-  background-repeat: no-repeat;
-  transition: border-color 0.25s, background-color 0.25s, opacity 0.25s;
-}
-.shiki-code[class*=language-]:hover > button.copy,
-.shiki-code[class*=language-] > button.copy:focus {
-  opacity: 1;
-}
-.shiki-code[class*=language-] > button.copy:hover,
-.shiki-code[class*=language-] > button.copy.copied {
-  border-color: var(--shiki-code-copy-code-hover-border-color);
-  background-color: var(--shiki-code-copy-code-hover-bg);
-}
-.shiki-code[class*=language-] > button.copy.copied,
-.shiki-code[class*=language-] > button.copy:hover.copied {
-  border-radius: 0 4px 4px 0;
-  background-color: var(--shiki-code-copy-code-hover-bg);
-  background-image: var(--shiki-icon-copied);
-}
-.shiki-code[class*=language-] > button.copy.copied:before,
-.shiki-code[class*=language-] > button.copy:hover.copied:before {
-  position: relative;
-  top: -1px;
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  border: 1px solid var(--shiki-code-copy-code-hover-border-color);
-  border-right: 0;
-  border-radius: 4px 0 0 4px;
-  padding: 0 10px;
-  width: fit-content;
-  height: 40px;
-  text-align: center;
-  font-size: 12px;
-  font-weight: 500;
-  color: var(--shiki-code-copy-code-active-text);
-  background-color: var(--shiki-code-copy-code-hover-bg);
-  white-space: nowrap;
-  content: var(--shiki-code-copy-copied-text-content);
-  transform: translate(calc(-100% - 1px));
-}
-.shiki-code[class*=language-] > span.lang {
-  position: absolute;
-  top: 2px;
-  right: 8px;
-  z-index: 2;
-  font-size: 12px;
-  font-weight: 500;
-  -webkit-user-select: none;
-  user-select: none;
-  color: var(--shiki-code-lang-color);
-  transition: color 0.4s, opacity 0.4s;
-}
-.shiki-code[class*=language-]:hover > button.copy + span.lang,
-.shiki-code[class*=language-] > button.copy:focus + span.lang {
-  opacity: 0;
-}
-.shiki-code[class*=language-].theme-dark {
-  --shiki-code-line-diff-add-color: #3dd68c;
-  --shiki-code-line-diff-add-symbol-color: #3dd68c;
-  --shiki-code-line-diff-remove-color: hsla(349.72, 89.16%, 60.2%, 0.16);
-  --shiki-code-line-diff-remove-symbol-color: hsl(357.62, 39.92%, 50.39%);
-  --shiki-code-line-line-number-color: hsla(198.18, 13.36%, 80%, 0.7);
-}
-.shiki-code[class*=language-] pre.shiki .diff {
-  all: unset;
-}
-.shiki-code[class*=language-] pre.shiki code .diff.remove {
-  background-color: var(--shiki-code-line-diff-remove-color, rgba(244, 63, 94, 0.14));
-  opacity: 0.7;
-}
-.shiki-code[class*=language-] pre.shiki code .diff.add {
-  background-color: rgba(16, 185, 129, 0.14);
-}
-.shiki-code[class*=language-] pre.shiki code .diff.add:before {
-  content: "+";
-  color: var(--shiki-code-line-diff-add-symbol-color, #18794e);
-}
-.shiki-code[class*=language-] pre.shiki code .diff.remove:before {
-  content: "-";
-  color: var(--shiki-code-line-diff-remove-symbol-color, hsl(357.62, 39.92%, 50.39%));
-}
-.shiki-code[class*=language-] pre.shiki code .diff:before {
-  width: 2.5em;
-  text-align: left;
-  padding-left: 10px;
-}
-.shiki-code[class*=language-] pre.shiki code .diff {
-  box-sizing: border-box;
-  transition: background-color 0.5s;
-  margin: 0 -24px;
-  padding: 0 24px;
-  width: calc(100% + 48px);
-  display: inline-block;
-}
-.shiki-code[class*=language-].line-numbers code {
-  counter-reset: step;
-  counter-increment: step 0;
-}
-.shiki-code[class*=language-].line-numbers code .line::before {
-  content: counter(step);
-  counter-increment: step;
-  display: inline-block;
-  text-align: right;
-  color: var(--shiki-code-line-line-number-color, hsla(198.18, 13.36%, 51.57%, 0.7));
-  width: 2.5em;
-  text-align: left;
-  padding-left: 10px;
-}
+:root {
+  --shiki-font-family-mono: ui-monospace, "Menlo", "Monaco", "Consolas", "Liberation Mono", "Courier New", monospace;
+  --shiki-code-line-height: 1.5;
+  --shiki-code-font-size: 0.875em;
+  --shiki-code-block-color: #67676c;
+  --shiki-icon-copy: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='rgba(128,128,128,1)' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' viewBox='0 0 24 24'%3E%3Crect width='8' height='4' x='8' y='2' rx='1' ry='1'/%3E%3Cpath d='M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2'/%3E%3C/svg%3E");
+  --shiki-icon-copied: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='none' stroke='rgba(128,128,128,1)' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' viewBox='0 0 24 24'%3E%3Crect width='8' height='4' x='8' y='2' rx='1' ry='1'/%3E%3Cpath d='M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2'/%3E%3Cpath d='m9 14 2 2 4-4'/%3E%3C/svg%3E");
+  --shiki-code-copy-code-border-color: #e2e2e3;
+  --shiki-code-copy-code-bg: #f6f6f7;
+  --shiki-code-copy-code-hover-border-color: #e2e2e3;
+  --shiki-code-copy-code-hover-bg: #ffffff;
+  --shiki-code-copy-code-active-text: #67676c;
+  --shiki-code-copy-copied-text-content: "Copied";
+  --shiki-code-lang-color: #929295;
+}
+@media (min-width: 640px) {
+  .shiki-code[class*=language-] {
+    border-radius: 8px;
+    margin: 15px 0;
+  }
+}
+.shiki-code[class*=language-] {
+  position: relative;
+  margin: 16px 0;
+  background-color: #f9f9f9;
+  overflow-x: auto;
+  transition: background-color 0.5s;
+  /* line numbers */
+}
+.shiki-code[class*=language-] pre,
+.shiki-code[class*=language-] code {
+  font-family: var(--shiki-font-family-mono);
+}
+.shiki-code[class*=language-] pre {
+  position: relative;
+  z-index: 1;
+  margin: 0;
+  padding: 20px 0;
+  background: transparent;
+  overflow-x: auto;
+}
+.shiki-code[class*=language-] code {
+  display: block;
+  padding: 0 24px 0 0;
+  width: fit-content;
+  min-width: 100%;
+  line-height: var(--shiki-code-line-height);
+  font-size: var(--shiki-code-font-size);
+  color: var(--shiki-code-block-color);
+  transition: color 0.5s;
+}
+.shiki-code[class*=language-] code > .line:before {
+  content: ' ';
+  padding: 0 5px;
+}
+.shiki-code[class*=language-] > button.copy {
+  direction: ltr;
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  z-index: 3;
+  border: 1px solid var(--shiki-code-copy-code-border-color);
+  border-radius: 4px;
+  width: 40px;
+  height: 40px;
+  background-color: var(--shiki-code-copy-code-bg);
+  opacity: 0;
+  cursor: pointer;
+  background-image: var(--shiki-icon-copy);
+  background-position: 50%;
+  background-size: 20px;
+  background-repeat: no-repeat;
+  transition: border-color 0.25s, background-color 0.25s, opacity 0.25s;
+}
+.shiki-code[class*=language-]:hover > button.copy,
+.shiki-code[class*=language-] > button.copy:focus {
+  opacity: 1;
+}
+.shiki-code[class*=language-] > button.copy:hover,
+.shiki-code[class*=language-] > button.copy.copied {
+  border-color: var(--shiki-code-copy-code-hover-border-color);
+  background-color: var(--shiki-code-copy-code-hover-bg);
+}
+.shiki-code[class*=language-] > button.copy.copied,
+.shiki-code[class*=language-] > button.copy:hover.copied {
+  border-radius: 0 4px 4px 0;
+  background-color: var(--shiki-code-copy-code-hover-bg);
+  background-image: var(--shiki-icon-copied);
+}
+.shiki-code[class*=language-] > button.copy.copied:before,
+.shiki-code[class*=language-] > button.copy:hover.copied:before {
+  position: relative;
+  top: -1px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  border: 1px solid var(--shiki-code-copy-code-hover-border-color);
+  border-right: 0;
+  border-radius: 4px 0 0 4px;
+  padding: 0 10px;
+  width: fit-content;
+  height: 40px;
+  text-align: center;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--shiki-code-copy-code-active-text);
+  background-color: var(--shiki-code-copy-code-hover-bg);
+  white-space: nowrap;
+  content: var(--shiki-code-copy-copied-text-content);
+  transform: translate(calc(-100% - 1px));
+}
+.shiki-code[class*=language-] > span.lang {
+  position: absolute;
+  top: 2px;
+  right: 8px;
+  z-index: 2;
+  font-size: 12px;
+  font-weight: 500;
+  -webkit-user-select: none;
+  user-select: none;
+  color: var(--shiki-code-lang-color);
+  transition: color 0.4s, opacity 0.4s;
+}
+.shiki-code[class*=language-]:hover > button.copy + span.lang,
+.shiki-code[class*=language-] > button.copy:focus + span.lang {
+  opacity: 0;
+}
+.shiki-code[class*=language-].theme-dark {
+  --shiki-code-line-diff-add-color: #3dd68c;
+  --shiki-code-line-diff-add-symbol-color: #3dd68c;
+  --shiki-code-line-diff-remove-color: hsla(349.72, 89.16%, 60.2%, 0.16);
+  --shiki-code-line-diff-remove-symbol-color: hsl(357.62, 39.92%, 50.39%);
+  --shiki-code-line-line-number-color: hsla(198.18, 13.36%, 80%, 0.7);
+}
+.shiki-code[class*=language-] pre.shiki .diff {
+  all: unset;
+}
+.shiki-code[class*=language-] pre.shiki code .diff.remove {
+  background-color: var(--shiki-code-line-diff-remove-color, rgba(244, 63, 94, 0.14));
+  opacity: 0.7;
+}
+.shiki-code[class*=language-] pre.shiki code .diff.add {
+  background-color: rgba(16, 185, 129, 0.14);
+}
+.shiki-code[class*=language-] pre.shiki code .diff.add:before {
+  content: "+";
+  color: var(--shiki-code-line-diff-add-symbol-color, #18794e);
+}
+.shiki-code[class*=language-] pre.shiki code .diff.remove:before {
+  content: "-";
+  color: var(--shiki-code-line-diff-remove-symbol-color, hsl(357.62, 39.92%, 50.39%));
+}
+.shiki-code[class*=language-] pre.shiki code .diff:before {
+  width: 2.5em;
+  text-align: left;
+  padding-left: 10px;
+}
+.shiki-code[class*=language-] pre.shiki code .diff {
+  box-sizing: border-box;
+  transition: background-color 0.5s;
+  margin: 0 -24px;
+  padding: 0 24px;
+  width: calc(100% + 48px);
+  display: inline-block;
+}
+.shiki-code[class*=language-].line-numbers code {
+  counter-reset: step;
+  counter-increment: step 0;
+}
+.shiki-code[class*=language-].line-numbers code .line::before {
+  content: counter(step);
+  counter-increment: step;
+  display: inline-block;
+  text-align: right;
+  color: var(--shiki-code-line-line-number-color, hsla(198.18, 13.36%, 51.57%, 0.7));
+  width: 2.5em;
+  text-align: left;
+  padding-left: 10px;
+}

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)