feat: add JsFunction value type for composable executeJs (#24374)

Lets server code build a JS function value with captured parameters
and pass it as an executeJs parameter, removing the need to
string-concatenate framework boilerplate around user-supplied JS.
Captures may themselves be Elements or other JsFunctions; the codec
encodes them recursively as @v-fn, and the client reifies the value
as a callable function with the captures pre-bound.

Fixes #24373

Author: Artur-

flow-client/src/main/java/com/vaadin/client/flow/util/ClientJsonCodec.java

@@ -129,6 +129,19 @@ public static Object decodeWithTypeInfo(StateTree tree, JsonValue json) {
                         tree.getRegistry().getServerConnector());
             }
 
+            // Check for @v-fn format
+            JsonValue fnValue = jsonObject.get("@v-fn");
+            if (fnValue != null) {
+                if (fnValue.getType() != JsonType.OBJECT) {
+                    throw new IllegalArgumentException(
+                            "@v-fn value must be an object, got "
+                                    + fnValue.getType() + " in "
+                                    + json.toJson());
+                }
+                return decodeJsFunction(tree, (JsonObject) fnValue,
+                        json.toJson());
+            }
+
             // Check for unknown @v- types
             for (String key : jsonObject.keys()) {
                 if (key.startsWith("@v-")) {
@@ -154,6 +167,75 @@ private static native NativeFunction createReturnChannelCallback(int nodeId,
         });
     }-*/;
 
+    private static Object decodeJsFunction(StateTree tree, JsonObject fnObject,
+            String originalJson) {
+        JsonValue bodyValue = fnObject.get("body");
+        if (bodyValue == null || bodyValue.getType() != JsonType.STRING) {
+            throw new IllegalArgumentException(
+                    "@v-fn 'body' must be a string in " + originalJson);
+        }
+        JsonValue capturesValue = fnObject.get("captures");
+        if (capturesValue == null
+                || capturesValue.getType() != JsonType.ARRAY) {
+            throw new IllegalArgumentException(
+                    "@v-fn 'captures' must be an array in " + originalJson);
+        }
+        String body = bodyValue.asString();
+        JsonArray capturesJson = (JsonArray) capturesValue;
+        int captureCount = capturesJson.length();
+        JsArray<Object> captures = JsCollections.array();
+        for (int i = 0; i < captureCount; i++) {
+            captures.push(decodeWithTypeInfo(tree, capturesJson.get(i)));
+        }
+        // Optional 'args' field: names of runtime parameters the manifested
+        // function should accept at call time, after the bound captures.
+        JsonArray argsJson;
+        JsonValue argsValue = fnObject.get("args");
+        if (argsValue == null) {
+            argsJson = null;
+        } else {
+            if (argsValue.getType() != JsonType.ARRAY) {
+                throw new IllegalArgumentException(
+                        "@v-fn 'args' must be an array in " + originalJson);
+            }
+            argsJson = (JsonArray) argsValue;
+        }
+        int argCount = argsJson == null ? 0 : argsJson.length();
+        String[] paramsAndCode = new String[captureCount + argCount + 1];
+        for (int i = 0; i < captureCount; i++) {
+            paramsAndCode[i] = "$" + i;
+        }
+        for (int i = 0; i < argCount; i++) {
+            paramsAndCode[captureCount + i] = argsJson.getString(i);
+        }
+        paramsAndCode[captureCount + argCount] = body;
+        NativeFunction fn = new NativeFunction(paramsAndCode);
+        return applyCaptures(fn, captures);
+    }
+
+    /**
+     * Wraps {@code fn} in a function that prepends {@code captures} to the
+     * runtime arguments before delegating, while leaving {@code this}
+     * controlled by the caller. {@code Function.prototype.bind} would also
+     * pre-bind {@code this} to {@code undefined}, which prevents callers from
+     * setting {@code this} via {@code .call()} or {@code .apply()} on the
+     * resulting function.
+     */
+    private static native Object applyCaptures(NativeFunction fn,
+            JsArray<Object> captures)
+    /*-{
+        return function() {
+            var args = new Array(captures.length + arguments.length);
+            for (var i = 0; i < captures.length; i++) {
+                args[i] = captures[i];
+            }
+            for (var j = 0; j < arguments.length; j++) {
+                args[captures.length + j] = arguments[j];
+            }
+            return fn.apply(this, args);
+        };
+    }-*/;
+
     /**
      * Decodes a value encoded on the server using
      * {@link JacksonCodec#encodeWithoutTypeInfo(Object)}. This is a no-op in

flow-server/src/main/java/com/vaadin/flow/component/page/Page.java

@@ -37,6 +37,7 @@
 import com.vaadin.flow.component.internal.UIInternals.JavaScriptInvocation;
 import com.vaadin.flow.dom.DomListenerRegistration;
 import com.vaadin.flow.dom.Element;
+import com.vaadin.flow.dom.JsFunction;
 import com.vaadin.flow.function.SerializableConsumer;
 import com.vaadin.flow.internal.UrlUtil;
 import com.vaadin.flow.shared.Registration;
@@ -338,6 +339,8 @@ public void addDynamicImport(String expression) {
      * attached)
      * <li>{@link tools.jackson.databind.node.BaseJsonNode} (sent as-is without
      * additional wrapping)
+     * <li>{@link JsFunction} (manifested as a callable JavaScript function with
+     * its captured parameters pre-bound)
      * </ul>
      * Note that the parameter variables can only be used in contexts where a
      * JavaScript variable can be used. You should for instance do

flow-server/src/main/java/com/vaadin/flow/dom/Element.java

@@ -1792,6 +1792,8 @@ public PendingJavaScriptResult callJsFunction(String functionName,
      * invocation is sent to the client, or as <code>null</code> if not
      * attached)
      * <li>{@link BaseJsonNode} (sent as-is without additional wrapping)
+     * <li>{@link JsFunction} (manifested as a callable JavaScript function with
+     * its captured parameters pre-bound)
      * </ul>
      * Note that the parameter variables can only be used in contexts where a
      * JavaScript variable can be used. You should for instance do

flow-server/src/main/java/com/vaadin/flow/dom/JsFunction.java

@@ -0,0 +1,156 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.dom;
+
+import java.io.Serializable;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+import org.jspecify.annotations.Nullable;
+
+import com.vaadin.flow.internal.JacksonCodec;
+
+/**
+ * A JavaScript function value with captured parameters that can be passed to
+ * {@link Element#executeJs(String, Object...)} as a parameter and reified on
+ * the client as an actual callable JS function.
+ * <p>
+ * The {@link #getBody() body} is a JavaScript function body. Captures are
+ * referenced positionally as {@code $0}, {@code $1}, &hellip; (the same naming
+ * convention as {@code executeJs} parameters). Additional named runtime
+ * arguments can be declared with {@link #withArguments(String...)}: the
+ * materialised function then accepts them positionally and the body references
+ * them by name. On the client the value materialises as a function with the
+ * captures pre-bound, so the parent {@code executeJs} can invoke it as
+ * {@code $N(arg1, arg2, ...)} without ever concatenating user-supplied
+ * JavaScript with framework boilerplate.
+ * <p>
+ * Captures may be any value accepted as a parameter to
+ * {@link Element#executeJs(String, Object...) executeJs}, including
+ * {@link Element} (attached elements arrive as DOM nodes, detached ones as
+ * {@code null}) and nested {@link JsFunction} instances. Capture types are
+ * validated when the value is created.
+ * <p>
+ * Inside the body, {@code this} is whatever the caller of the materialised
+ * function chooses (i.e. it follows normal JavaScript call semantics &ndash;
+ * not the host element). To use the host element from within the body, pass it
+ * as a capture.
+ *
+ * @author Vaadin Ltd
+ */
+public final class JsFunction implements Serializable {
+
+    private final String body;
+    private final List<@Nullable Object> captures;
+    private final List<String> argumentNames;
+
+    private JsFunction(String body, List<@Nullable Object> captures,
+            List<String> argumentNames) {
+        this.body = body;
+        this.captures = captures;
+        this.argumentNames = argumentNames;
+    }
+
+    /**
+     * Creates a JavaScript function value with the given body and captured
+     * parameters.
+     *
+     * @param body
+     *            the JavaScript function body, with captures referenced as
+     *            {@code $0}, {@code $1}, &hellip;; not {@code null}
+     * @param captures
+     *            the values to capture; each must be a type supported as a
+     *            parameter to {@link Element#executeJs(String, Object...)}
+     * @return a new {@code JsFunction} instance
+     * @throws IllegalArgumentException
+     *             if any capture has a type that cannot be sent to the client
+     */
+    public static JsFunction of(String body, @Nullable Object... captures) {
+        Objects.requireNonNull(body, "body");
+        Objects.requireNonNull(captures, "captures");
+        @Nullable
+        Object[] copy = captures.clone();
+        // Dry-run encode each capture so unsupported types fail fast. Mirrors
+        // the validation done by the JavaScriptInvocation constructor for
+        // executeJs parameters.
+        for (@Nullable
+        Object capture : copy) {
+            JacksonCodec.encodeWithTypeInfo(capture);
+        }
+        return new JsFunction(body,
+                Collections.unmodifiableList(Arrays.asList(copy)),
+                Collections.emptyList());
+    }
+
+    /**
+     * Returns a copy of this function that declares the given names as
+     * positional runtime arguments. The materialised function accepts these
+     * arguments at call time, and the body references them by name.
+     * <p>
+     * Example:
+     *
+     * <pre>
+     * JsFunction alerter = JsFunction.of("alert(message);")
+     *         .withArguments("message");
+     * element.executeJs("$0('Hello')", alerter);
+     * </pre>
+     *
+     * @param argumentNames
+     *            the names of runtime arguments, in positional order; each must
+     *            be a valid JavaScript identifier
+     * @return a new {@code JsFunction} with the given argument names
+     * @throws IllegalStateException
+     *             if argument names have already been set on this instance
+     */
+    public JsFunction withArguments(String... argumentNames) {
+        if (!this.argumentNames.isEmpty()) {
+            throw new IllegalStateException(
+                    "withArguments has already been called on this JsFunction");
+        }
+        return new JsFunction(body, captures, List.of(argumentNames));
+    }
+
+    /**
+     * The JavaScript function body.
+     *
+     * @return the body string
+     */
+    public String getBody() {
+        return body;
+    }
+
+    /**
+     * The captured values, in declaration order.
+     *
+     * @return an unmodifiable list of captures
+     */
+    public List<@Nullable Object> getCaptures() {
+        return captures;
+    }
+
+    /**
+     * The names of the runtime arguments declared via
+     * {@link #withArguments(String...)}, in positional order.
+     *
+     * @return an unmodifiable list of argument names; empty if none were
+     *         declared
+     */
+    public List<String> getArgumentNames() {
+        return argumentNames;
+    }
+}

flow-server/src/main/java/com/vaadin/flow/internal/JacksonCodec.java

@@ -28,6 +28,7 @@
 
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.dom.Element;
+import com.vaadin.flow.dom.JsFunction;
 import com.vaadin.flow.internal.nodefeature.ReturnChannelRegistration;
 
 /**
@@ -43,6 +44,8 @@
  * <li>{@link JsonNode} and all its sub types
  * <li>{@link Element} (encoded as a reference to the element)
  * <li>{@link Component} (encoded as a reference to the root element)
+ * <li>{@link JsFunction} (encoded as a JS function literal that closes over its
+ * captured parameters on the client)
  * </ul>
  *
  * <p>
@@ -76,6 +79,8 @@ public static JsonNode encodeWithTypeInfo(Object value) {
             return encodeWithoutTypeInfo(value);
         } else if (value instanceof ReturnChannelRegistration) {
             return encodeReturnChannel((ReturnChannelRegistration) value);
+        } else if (value instanceof JsFunction) {
+            return encodeJsFunction((JsFunction) value);
         } else if (canEncodeWithoutTypeInfo(value.getClass())) {
             // Native JSON types - no wrapping needed
             return encodeWithoutTypeInfo(value);
@@ -98,6 +103,25 @@ private static JsonNode encodeReturnChannel(
         return obj;
     }
 
+    private static JsonNode encodeJsFunction(JsFunction value) {
+        ObjectMapper mapper = JacksonUtils.getMapper();
+        ObjectNode obj = mapper.createObjectNode();
+        ObjectNode payload = mapper.createObjectNode();
+        payload.put("body", value.getBody());
+        ArrayNode captures = mapper.createArrayNode();
+        for (Object capture : value.getCaptures()) {
+            captures.add(encodeWithTypeInfo(capture));
+        }
+        payload.set("captures", captures);
+        ArrayNode args = mapper.createArrayNode();
+        for (String name : value.getArgumentNames()) {
+            args.add(name);
+        }
+        payload.set("args", args);
+        obj.set("@v-fn", payload);
+        return obj;
+    }
+
     /**
      * Helper for checking whether the type is supported by
      * {@link #encodeWithoutTypeInfo(Object)}. Supported value types are

flow-server/src/test/java/com/vaadin/flow/dom/JsFunctionTest.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.dom;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class JsFunctionTest {
+
+    @Test
+    void withArguments_alreadySet_throws() {
+        JsFunction fn = JsFunction.of("return a;").withArguments("a");
+        assertThrows(IllegalStateException.class, () -> fn.withArguments("b"));
+    }
+}