Support FunctionVar handlers in EventChain rendering (#6188)

* Support FunctionVar handlers in EventChain rendering

Allow EventChain to accept frontend FunctionVar handlers alongside
EventSpec, EventVar, and EventCallback values.

When a chain contains FunctionVars, keep backend events grouped through
addEvents(...) and invoke frontend functions inline with the trigger
arguments so mixed chains preserve execution order and DOM event
actions like preventDefault and stopPropagation.

Wrap inline arrow functions before emitting VarOperationCall JS so
direct invocation renders valid JavaScript, add unit coverage for
pure/mixed event-chain formatting and creation, and move upload
exception docs to the helper that actually raises them to satisfy
darglint.

* fix: forward non-DOM event actions to queued events and improve arrow function detection

Event actions like `throttle` were dropped when rendering mixed EventChains
containing both backend handlers and FunctionVars. Non-DOM actions are now
correctly forwarded to the queueEvents call. Also fixes false-positive arrow
function detection for expressions like `factory(() => 1)` that contain `=>`
but are not themselves arrow functions, and adds warnings when event_chain_kwargs
are silently ignored for EventChainVar/FunctionVar values.

* refactor: extract applyEventActions helper and simplify EventChain rendering

Move event action handling (preventDefault, stopPropagation, throttle,
debounce, temporal) into a shared applyEventActions JS function used by
both addEvents and Python-generated event chains. This eliminates the
complex queueable-group batching logic in LiteralEventChainVar and the
arrow function detection heuristic in FunctionVar.

* fix: avoid wrapping JS operators as callable expressions

Restore selective arrow-function wrapping in FunctionVar calls so
operator-like expressions such as `typeof` keep compiling correctly.
This fixes the generated JSX regression that broke form integration tests
by emitting invalid code like `((typeof)(value))`.

Also update unit expectations for the corrected rendering behavior.

* test: fix test regression

* perf: fast-path backend-only EventChains to skip applyEventActions wrapper

* test: simplify test

* fix: allow EventChain-typed FunctionVars to compose with event_chain_kwargs

* fix: remove EventChain fast path to preserve per-spec event actions

The fast path grouped backend-only EventSpecs into a single addEvents
call, which lost per-spec event actions like individual debounce values.
Each EventSpec now renders its own addEvents call, and chain-level actions
use applyEventActions consistently.

* use Var.equals for var equality checking

Without this, using `==` in an assertion with Var values ends up creating a new
truthy Var instead of actually checking python-side equality. Var equality
assertions have to be made explicitly with `.equals` to actually determine if
the values are the same.

* Handle args_spec partial args for FunctionVar

When a FunctionVar is passed to an event trigger with a given args_spec,
transform it into a partial function that applies the transformed arguments
when called. This allows FunctionVar handlers to work with on_blur and
on_submit, which, by default, use the args_spec to transform the value before
passing it off to the handler.

Some escape hatches:
  * The behavior for EventChainVar is unchanged, so previous code that was
    explicitly casting functions to EventChain will continue to work without
    modification.
  * If the FunctionVar is returned through a lambda, no partial application is
    applied, because that happens at the point the lambda is called, so the
    return value of the lambda is responsible for mapping the arguments if
    desired.

This change also allows event handler lambda functions to return a
heterogeneous mix of EventSpec/EventHandler/FunctionVar (and EventChain
returned from lambda are treated as FunctionVar, allowing arbitrary nesting).

Update FunctionVar.partial such that passing no args does NOT create a new
useless function.

* treat outer lambda and lambda in list equivalently

* test: add count

* add EventVar to allowed event lambda return types

this allows rx.cond to continue to be used for conditional events

* fix: hoist empty event literals and drop redundant _get_all_var_data in statement block

Cache empty event/action literals as module-level constants to avoid
repeated allocations. Remove the manual _get_all_var_data merge on
the statement block Var so nested var data propagates naturally through
the f-string interpolation.

* test: Addded more tests

---------

Co-authored-by: Masen Furer <m_github@0x26.net>

Author: FarhanAliRaza

reflex/.templates/web/utils/state.js

@@ -726,6 +726,53 @@ export const ReflexEvent = (
   return { name, payload, handler, event_actions };
 };
 
+/**
+ * Apply event actions before invoking a target function.
+ * @param {Function} target The function to invoke after applying event actions.
+ * @param {Object.<string, (number|boolean)>} event_actions The actions to apply.
+ * @param {Array<any>|any} args The event args.
+ * @param {string|null} action_key A stable key for debounce/throttle tracking.
+ * @param {Function|null} temporal_handler Returns whether temporal actions may run.
+ * @returns The target result, if it runs immediately.
+ */
+export const applyEventActions = (
+  target,
+  event_actions = {},
+  args = [],
+  action_key = null,
+  temporal_handler = null,
+) => {
+  if (!(args instanceof Array)) {
+    args = [args];
+  }
+
+  const _e = args.find((o) => o?.preventDefault !== undefined);
+
+  if (event_actions?.preventDefault && _e?.preventDefault) {
+    _e.preventDefault();
+  }
+  if (event_actions?.stopPropagation && _e?.stopPropagation) {
+    _e.stopPropagation();
+  }
+  if (event_actions?.temporal && temporal_handler && !temporal_handler()) {
+    return;
+  }
+
+  const invokeTarget = () => target(...args);
+  const resolved_action_key = action_key ?? target.toString();
+
+  if (event_actions?.throttle) {
+    if (!throttle(resolved_action_key, event_actions.throttle)) {
+      return;
+    }
+  }
+  if (event_actions?.debounce) {
+    debounce(resolved_action_key, invokeTarget, event_actions.debounce);
+    return;
+  }
+  return invokeTarget();
+};
+
 /**
  * Package client-side storage values as payload to send to the
  * backend with the hydrate event
@@ -898,51 +945,24 @@ export const useEventLoop = (
   // Function to add new events to the event queue.
   const addEvents = useCallback((events, args, event_actions) => {
     const _events = events.filter((e) => e !== undefined && e !== null);
-    if (!event_actions?.temporal) {
-      // Reconnect socket if needed for non-temporal events.
-      ensureSocketConnected();
-    }
-
-    if (!(args instanceof Array)) {
-      args = [args];
-    }
 
     event_actions = _events.reduce(
       (acc, e) => ({ ...acc, ...e.event_actions }),
       event_actions ?? {},
     );
 
-    const _e = args.filter((o) => o?.preventDefault !== undefined)[0];
-
-    if (event_actions?.preventDefault && _e?.preventDefault) {
-      _e.preventDefault();
-    }
-    if (event_actions?.stopPropagation && _e?.stopPropagation) {
-      _e.stopPropagation();
-    }
-    const combined_name = _events.map((e) => e.name).join("+++");
-    if (event_actions?.temporal) {
-      if (!socket.current || !socket.current.connected) {
-        return; // don't queue when the backend is not connected
-      }
-    }
-    if (event_actions?.throttle) {
-      // If throttle returns false, the events are not added to the queue.
-      if (!throttle(combined_name, event_actions.throttle)) {
-        return;
-      }
-    }
-    if (event_actions?.debounce) {
-      // If debounce is used, queue the events after some delay
-      debounce(
-        combined_name,
-        () =>
-          queueEvents(_events, socket, false, navigate, () => params.current),
-        event_actions.debounce,
-      );
-    } else {
-      queueEvents(_events, socket, false, navigate, () => params.current);
+    if (!event_actions?.temporal) {
+      // Reconnect socket if needed for non-temporal events.
+      ensureSocketConnected();
     }
+
+    return applyEventActions(
+      () => queueEvents(_events, socket, false, navigate, () => params.current),
+      event_actions,
+      args,
+      _events.map((e) => e.name).join("+++"),
+      () => !!socket.current?.connected,
+    );
   }, []);
 
   const sentHydrate = useRef(false); // Avoid double-hydrate due to React strict-mode

reflex/app.py

@@ -1936,11 +1936,6 @@ async def upload_file(request: Request):
         Returns:
             StreamingResponse yielding newline-delimited JSON of StateUpdate
             emitted by the upload handler.
-
-        Raises:
-            UploadValueError: if there are no args with supported annotation.
-            UploadTypeError: if a background task is used as the handler.
-            HTTPException: when the request does not include token / handler headers.
         """
         from reflex.utils.exceptions import UploadTypeError, UploadValueError
 
@@ -1965,6 +1960,11 @@ async def _create_upload_event() -> Event:
 
             Returns:
                 The upload event backed by the original temp files.
+
+            Raises:
+                UploadValueError: If there are no uploaded files or supported annotations.
+                UploadTypeError: If a background task is used as the handler.
+                HTTPException: If the request is missing token or handler headers.
             """
             files = form_data.getlist("files")
             if not files:

reflex/constants/compiler.py

@@ -61,6 +61,8 @@ class CompileVars(SimpleNamespace):
     IS_HYDRATED = "is_hydrated"
     # The name of the function to add events to the queue.
     ADD_EVENTS = "addEvents"
+    # The name of the function to apply event actions before invoking a target.
+    APPLY_EVENT_ACTIONS = "applyEventActions"
     # The name of the var storing any connection error.
     CONNECT_ERROR = "connectErrors"
     # The name of the function for converting a dict to an event.
@@ -128,7 +130,10 @@ class Imports(SimpleNamespace):
     EVENTS = {
         "react": [ImportVar(tag="useContext")],
         f"$/{Dirs.CONTEXTS_PATH}": [ImportVar(tag="EventLoopContext")],
-        f"$/{Dirs.STATE_PATH}": [ImportVar(tag=CompileVars.TO_EVENT)],
+        f"$/{Dirs.STATE_PATH}": [
+            ImportVar(tag=CompileVars.TO_EVENT),
+            ImportVar(tag=CompileVars.APPLY_EVENT_ACTIONS),
+        ],
     }