Configurable debounce

Author: Archmonger

CHANGELOG.md

@@ -62,6 +62,7 @@ Don't forget to remove deprecated code on each major release!
 - `reactpy.types.VdomDictConstructor` has been renamed to `reactpy.types.VdomConstructor`.
 - `REACTPY_ASYNC_RENDERING` can now de-duplicate and cascade renders where necessary.
 - `REACTPY_ASYNC_RENDERING` is now defaulted to `True` for up to 40x performance improvements in environments with high concurrency.
+- Events now support debounce, which can now be configured per event with `event.debounce = <milliseconds>`. Note that `input`, `select`, and `textarea` elements default to 200ms debounce.
 
 ### Deprecated
 

src/js/packages/@reactpy/client/src/components.tsx

@@ -18,6 +18,34 @@ import type { ReactPyClient } from "./client";
 
 const ClientContext = createContext<ReactPyClient>(null as any);
 
+const DEFAULT_INPUT_DEBOUNCE = 200;
+
+type ReactPyInputHandler = ((event: TargetedEvent<any>) => void) & {
+  debounce?: number;
+  isHandler?: boolean;
+};
+
+type UserInputTarget = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+function trackUserInput(
+  event: TargetedEvent<any>,
+  setValue: (value: any) => void,
+  lastUserValue: MutableRefObject<any>,
+  lastChangeTime: MutableRefObject<number>,
+  lastInputDebounce: MutableRefObject<number>,
+  debounce: number,
+): void {
+  if (!event.target) {
+    return;
+  }
+
+  const newValue = (event.target as UserInputTarget).value;
+  setValue(newValue);
+  lastUserValue.current = newValue;
+  lastChangeTime.current = Date.now();
+  lastInputDebounce.current = debounce;
+}
+
 export function Layout(props: { client: ReactPyClient }): JSX.Element {
   const currentModel: ReactPyVdom = useState({ tagName: "" })[0];
   const forceUpdate = useForceUpdate();
@@ -84,6 +112,7 @@ function UserInputElement({ model }: { model: ReactPyVdom }): JSX.Element {
   const [value, setValue] = useState(props.value);
   const lastUserValue = useRef(props.value);
   const lastChangeTime = useRef(0);
+  const lastInputDebounce = useRef(DEFAULT_INPUT_DEBOUNCE);
 
   // honor changes to value from the client via props
   useEffect(() => {
@@ -93,24 +122,34 @@ function UserInputElement({ model }: { model: ReactPyVdom }): JSX.Element {
     const now = Date.now();
     if (
       props.value === lastUserValue.current ||
-      now - lastChangeTime.current > 200
+      now - lastChangeTime.current >= lastInputDebounce.current
     ) {
       setValue(props.value);
     }
   }, [props.value]);
 
-  const givenOnChange = props.onChange;
-  if (typeof givenOnChange === "function") {
-    props.onChange = (event: TargetedEvent<any>) => {
-      // immediately update the value to give the user feedback
-      if (event.target) {
-        const newValue = (event.target as HTMLInputElement).value;
-        setValue(newValue);
-        lastUserValue.current = newValue;
-        lastChangeTime.current = Date.now();
-      }
-      // allow the client to respond (and possibly change the value)
-      givenOnChange(event);
+  for (const [name, prop] of Object.entries(props)) {
+    if (typeof prop !== "function") {
+      continue;
+    }
+
+    const givenHandler = prop as ReactPyInputHandler;
+    if (!givenHandler.isHandler) {
+      continue;
+    }
+
+    props[name] = (event: TargetedEvent<any>) => {
+      trackUserInput(
+        event,
+        setValue,
+        lastUserValue,
+        lastChangeTime,
+        lastInputDebounce,
+        typeof givenHandler.debounce === "number"
+          ? givenHandler.debounce
+          : DEFAULT_INPUT_DEBOUNCE,
+      );
+      givenHandler(event);
     };
   }
 

src/js/packages/@reactpy/client/src/types.ts

@@ -60,6 +60,7 @@ export type ReactPyVdomEventHandler = {
   target: string;
   preventDefault?: boolean;
   stopPropagation?: boolean;
+  debounce?: number;
 };
 
 export type ReactPyVdomImportSource = {

src/js/packages/@reactpy/client/src/vdom.tsx

@@ -206,7 +206,7 @@ export function createAttributes(
 function createEventHandler(
   client: ReactPyClient,
   name: string,
-  { target, preventDefault, stopPropagation }: ReactPyVdomEventHandler,
+  { target, preventDefault, stopPropagation, debounce }: ReactPyVdomEventHandler,
 ): [string, () => void] {
   const eventHandler = function (...args: any[]) {
     const data = Array.from(args).map((value) => {
@@ -227,7 +227,19 @@ function createEventHandler(
     });
     client.sendMessage({ type: "layout-event", data, target });
   };
-  eventHandler.isHandler = true;
+  (
+    eventHandler as typeof eventHandler & {
+      debounce?: number;
+      isHandler: boolean;
+    }
+  ).isHandler = true;
+  if (typeof debounce === "number") {
+    (
+      eventHandler as typeof eventHandler & {
+        debounce?: number;
+      }
+    ).debounce = debounce;
+  }
   return [name, eventHandler];
 }
 

src/reactpy/core/events.py

@@ -18,6 +18,7 @@ def event(
     *,
     stop_propagation: bool = ...,
     prevent_default: bool = ...,
+    debounce: int | None = ...,
 ) -> EventHandler: ...
 
 
@@ -27,6 +28,7 @@ def event(
     *,
     stop_propagation: bool = ...,
     prevent_default: bool = ...,
+    debounce: int | None = ...,
 ) -> Callable[[Callable[..., Any]], EventHandler]: ...
 
 
@@ -35,6 +37,7 @@ def event(
     *,
     stop_propagation: bool = False,
     prevent_default: bool = False,
+    debounce: int | None = None,
 ) -> EventHandler | Callable[[Callable[..., Any]], EventHandler]:
     """A decorator for constructing an :class:`EventHandler`.
 
@@ -63,13 +66,17 @@ def my_callback(*data): ...
             Block the event from propagating further up the DOM.
         prevent_default:
             Stops the default actional associate with the event from taking place.
+        debounce:
+            Preserve client-side user input state for the given number of milliseconds
+            before applying conflicting server updates.
     """
 
     def setup(function: Callable[..., Any]) -> EventHandler:
         return EventHandler(
             to_event_handler_function(function, positional_args=True),
             stop_propagation,
             prevent_default,
+            debounce=debounce,
         )
 
     return setup(function) if function is not None else setup
@@ -95,10 +102,12 @@ def __init__(
         stop_propagation: bool = False,
         prevent_default: bool = False,
         target: str | None = None,
+        debounce: int | None = None,
     ) -> None:
         self.function = to_event_handler_function(function, positional_args=False)
         self.prevent_default = prevent_default
         self.stop_propagation = stop_propagation
+        self.debounce = debounce
         self.target = target
 
         # Check if our `preventDefault` or `stopPropagation` methods were called
@@ -110,14 +119,16 @@ def __init__(
         if isinstance(func_to_inspect, partial):
             func_to_inspect = func_to_inspect.func
 
-        found_prevent_default, found_stop_propagation = _inspect_event_handler_code(
-            func_to_inspect.__code__
+        found_prevent_default, found_stop_propagation, found_debounce = (
+            _inspect_event_handler_code(func_to_inspect.__code__)
         )
 
         if found_prevent_default:
             self.prevent_default = True
         if found_stop_propagation:
             self.stop_propagation = True
+        if found_debounce is not None:
+            self.debounce = found_debounce
 
     __hash__ = None  # type: ignore
 
@@ -130,6 +141,7 @@ def __eq__(self, other: object) -> bool:
                 "function",
                 "prevent_default",
                 "stop_propagation",
+                "debounce",
                 "target",
             )
         )
@@ -184,8 +196,9 @@ def merge_event_handlers(
     """Merge multiple event handlers into one
 
     Raises a ValueError if any handlers have conflicting
-    :attr:`~reactpy.core.proto.EventHandlerType.stop_propagation` or
-    :attr:`~reactpy.core.proto.EventHandlerType.prevent_default` attributes.
+    :attr:`~reactpy.core.proto.EventHandlerType.stop_propagation`,
+    :attr:`~reactpy.core.proto.EventHandlerType.prevent_default`, or
+    :attr:`~reactpy.core.proto.EventHandlerType.debounce` attributes.
     """
     if not event_handlers:
         msg = "No event handlers to merge"
@@ -197,22 +210,28 @@ def merge_event_handlers(
 
     stop_propagation = first_handler.stop_propagation
     prevent_default = first_handler.prevent_default
+    debounce = first_handler.debounce
     target = first_handler.target
 
     for handler in event_handlers:
         if (
             handler.stop_propagation != stop_propagation
             or handler.prevent_default != prevent_default
+            or handler.debounce != debounce
             or handler.target != target
         ):
-            msg = "Cannot merge handlers - 'stop_propagation', 'prevent_default' or 'target' mismatch."
+            msg = (
+                "Cannot merge handlers - 'stop_propagation', 'prevent_default', "
+                "'debounce' or 'target' mismatch."
+            )
             raise ValueError(msg)
 
     return EventHandler(
         merge_event_handler_funcs([h.function for h in event_handlers]),
         stop_propagation,
         prevent_default,
         target,
+        debounce,
     )
 
 
@@ -235,43 +254,54 @@ async def await_all_event_handlers(data: Sequence[Any]) -> None:
 
 
 @lru_cache(maxsize=4096)
-def _inspect_event_handler_code(code: CodeType) -> tuple[bool, bool]:
+def _inspect_event_handler_code(code: CodeType) -> tuple[bool, bool, int | None]:
     prevent_default = False
     stop_propagation = False
+    debounce = None
 
     if code.co_argcount > 0:
         names = code.co_names
         check_prevent_default = "preventDefault" in names
         check_stop_propagation = "stopPropagation" in names
+        check_debounce = "debounce" in names
 
-        if not (check_prevent_default or check_stop_propagation):
-            return False, False
+        if not (check_prevent_default or check_stop_propagation or check_debounce):
+            return False, False, None
 
         event_arg_name = code.co_varnames[0]
         last_was_event = False
+        instructions = list(dis.get_instructions(code))
 
-        for instr in dis.get_instructions(code):
+        for index, instr in enumerate(instructions):
             if (
                 instr.opname in ("LOAD_FAST", "LOAD_FAST_BORROW")
                 and instr.argval == event_arg_name
             ):
                 last_was_event = True
                 continue
 
-            if last_was_event and instr.opname in (
-                "LOAD_METHOD",
-                "LOAD_ATTR",
-            ):
-                if check_prevent_default and instr.argval == "preventDefault":
-                    prevent_default = True
-                    check_prevent_default = False
-                elif check_stop_propagation and instr.argval == "stopPropagation":
-                    stop_propagation = True
-                    check_stop_propagation = False
-
-                if not (check_prevent_default or check_stop_propagation):
+            if last_was_event:
+                if instr.opname in ("LOAD_METHOD", "LOAD_ATTR"):
+                    if check_prevent_default and instr.argval == "preventDefault":
+                        prevent_default = True
+                        check_prevent_default = False
+                    elif check_stop_propagation and instr.argval == "stopPropagation":
+                        stop_propagation = True
+                        check_stop_propagation = False
+                elif check_debounce and instr.opname == "STORE_ATTR":
+                    if instr.argval == "debounce" and index > 1:
+                        candidate = instructions[index - 2].argval
+                        if isinstance(candidate, int) and not isinstance(
+                            candidate, bool
+                        ):
+                            debounce = candidate
+                            check_debounce = False
+
+                if not (
+                    check_prevent_default or check_stop_propagation or check_debounce
+                ):
                     break
 
             last_was_event = False
 
-    return prevent_default, stop_propagation
+    return prevent_default, stop_propagation, debounce

src/reactpy/core/layout.py

@@ -401,6 +401,11 @@ def _render_model_attributes(
                 "target": target,
                 "preventDefault": handler.prevent_default,
                 "stopPropagation": handler.stop_propagation,
+                **(
+                    {"debounce": handler.debounce}
+                    if handler.debounce is not None
+                    else {}
+                ),
             }
 
         return None
@@ -426,6 +431,11 @@ def _render_model_event_handlers_without_old_state(
                 "target": target,
                 "preventDefault": handler.prevent_default,
                 "stopPropagation": handler.stop_propagation,
+                **(
+                    {"debounce": handler.debounce}
+                    if handler.debounce is not None
+                    else {}
+                ),
             }
 
         return None

src/reactpy/core/vdom.py

@@ -72,6 +72,7 @@
                 "target": {"type": "string"},
                 "preventDefault": {"type": "boolean"},
                 "stopPropagation": {"type": "boolean"},
+                "debounce": {"type": "integer", "minimum": 0},
             },
             "required": ["target"],
         },

src/reactpy/types.py

@@ -915,6 +915,7 @@ class JsonEventTarget(TypedDict):
     target: str
     preventDefault: bool
     stopPropagation: bool
+    debounce: NotRequired[int]
 
 
 class JsonImportSource(TypedDict):
@@ -939,6 +940,7 @@ class BaseEventHandler:
 
     __slots__ = (
         "__weakref__",
+        "debounce",
         "function",
         "prevent_default",
         "stop_propagation",
@@ -954,6 +956,9 @@ class BaseEventHandler:
     stop_propagation: bool
     """Stops the default action associate with the event from taking place."""
 
+    debounce: int | None
+    """How long, in milliseconds, client-side user input state should be preserved."""
+
     target: str | None
     """Typically left as ``None`` except when a static target is useful.
 
@@ -1124,6 +1129,8 @@ class Event(dict):
     A light `dict` wrapper for event data passed to event handler functions.
     """
 
+    debounce: int | None
+
     def __getattr__(self, name: str) -> Any:
         value = self.get(name)
         return Event(value) if isinstance(value, dict) else value