feat: add TypeReference support for generic type deserialization across all JSON APIs (#22442)

Add TypeReference<T> parameter overloads to enable proper deserialization of
generic collections like List<Bean> and Map<String, Bean> across all Flow JSON APIs.
This eliminates the need for unsafe casting when working with generic return types
from JavaScript execution, property access, and event data handling.
Key changes:
- Add JacksonCodec.decodeAs(JsonNode, TypeReference<T>) for core deserialization
  with full generic type information preservation
- Add PendingJavaScriptResult.then/toCompletableFuture TypeReference overloads
  for executeJs() return value handling
- Add Element.getProperty(String, TypeReference<T>) for typed property access
  with generic collections
- Add DomEvent.getEventData(TypeReference<T>) for typed event data extraction
- Add DomListenerRegistration.addEventData(Class/TypeReference) overloads that
  automatically introspect bean/record structures and register all properties
- Add BeanUtil.getBeanPropertyPaths() utility for extracting property paths
  from beans/records using Java Bean introspection
- Update @eventdata javadoc to document existing bean/record support

Author: Artur-

flow-server/src/main/java/com/vaadin/flow/component/EventData.java

@@ -37,10 +37,37 @@
  * expression is passed back to the server and injected into the annotated
  * {@link ComponentEvent} constructor parameter.
  * <p>
- * Supported parameter types are {@link String},
- * {@link elemental.json.JsonValue}, {@link tools.jackson.databind.JsonNode},
- * {@link Integer}, {@link Double}, {@link Boolean} and their respective
- * primitive types.
+ * Supported parameter types include:
+ * <ul>
+ * <li>Primitives and their wrappers: {@link Integer}, {@link Double},
+ * {@link Boolean}, int, double, boolean, etc.</li>
+ * <li>String values: {@link String}</li>
+ * <li>JSON types: {@link tools.jackson.databind.JsonNode},
+ * {@link elemental.json.JsonValue}</li>
+ * <li>Bean/DTO types: Any Java bean or record that can be deserialized from
+ * JSON using Jackson</li>
+ * <li>Collections: {@link java.util.List}, {@link java.util.Map}, etc. (when
+ * using generic types with proper bean definitions)</li>
+ * </ul>
+ * <p>
+ * Example with a bean type:
+ *
+ * <pre>
+ * public class MouseDetails {
+ *     private int clientX;
+ *     private int clientY;
+ *     // getters and setters
+ * }
+ *
+ * &#64;DomEvent("custom-click")
+ * public class CustomClickEvent extends ComponentEvent&lt;Component&gt; {
+ *     public CustomClickEvent(Component source, boolean fromClient,
+ *             &#64;EventData("event.detail") MouseDetails details) {
+ *         super(source, fromClient);
+ *         // details is automatically deserialized from the event data
+ *     }
+ * }
+ * </pre>
  *
  * @see DomEvent
  * @see DomListenerRegistration#addEventData(String)

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

@@ -18,6 +18,7 @@
 import java.io.Serializable;
 import java.util.concurrent.CompletableFuture;
 
+import tools.jackson.core.type.TypeReference;
 import tools.jackson.databind.JsonNode;
 
 import com.vaadin.flow.component.internal.DeadlockDetectingCompletableFuture;
@@ -195,6 +196,123 @@ default <T> CompletableFuture<T> toCompletableFuture(Class<T> targetType) {
         return completableFuture;
     }
 
+    /**
+     * Adds a typed handler that will be run for a successful execution and a
+     * handler that will be run for a failed execution. One of the handlers will
+     * be invoked asynchronously when the result of the execution is sent back
+     * to the server.
+     * <p>
+     * The JavaScript return value will be automatically converted to the type
+     * specified by the {@link TypeReference}. This method supports generic
+     * types such as {@code List<MyBean>} and {@code Map<String, MyBean>}.
+     * <p>
+     * Example usage:
+     *
+     * <pre>
+     * element.executeJs("return [{name: 'Alice', age: 30}]")
+     *         .then(new TypeReference&lt;List&lt;Person&gt;&gt;() {
+     *         }, list -&gt; System.out.println(list.get(0).name));
+     * </pre>
+     * <p>
+     * Handlers can only be added before the execution has been sent to the
+     * browser.
+     *
+     * @param <T>
+     *            the type to convert the result to
+     * @param typeReference
+     *            the type reference describing the target type, not
+     *            <code>null</code>
+     * @param resultHandler
+     *            a handler for the return value from a successful execution,
+     *            not <code>null</code>
+     * @param errorHandler
+     *            a handler for an error message in case the execution failed,
+     *            or <code>null</code> to ignore errors
+     */
+    default <T> void then(TypeReference<T> typeReference,
+            SerializableConsumer<T> resultHandler,
+            SerializableConsumer<String> errorHandler) {
+        if (typeReference == null) {
+            throw new IllegalArgumentException("Type reference cannot be null");
+        }
+        if (resultHandler == null) {
+            throw new IllegalArgumentException("Result handler cannot be null");
+        }
+
+        SerializableConsumer<JsonNode> convertingResultHandler = value -> resultHandler
+                .accept(JacksonCodec.decodeAs(value, typeReference));
+
+        then(convertingResultHandler, errorHandler);
+    }
+
+    /**
+     * Adds a typed handler that will be run for a successful execution. The
+     * handler will be invoked asynchronously if the execution was successful.
+     * In case of a failure, no handler will be run.
+     * <p>
+     * The JavaScript return value will be automatically converted to the type
+     * specified by the {@link TypeReference}. This method supports generic
+     * types such as {@code List<MyBean>} and {@code Map<String, MyBean>}.
+     * <p>
+     * A handler can only be added before the execution has been sent to the
+     * browser.
+     *
+     * @param <T>
+     *            the type to convert the result to
+     * @param typeReference
+     *            the type reference describing the target type, not
+     *            <code>null</code>
+     * @param resultHandler
+     *            a handler for the return value from a successful execution,
+     *            not <code>null</code>
+     */
+    default <T> void then(TypeReference<T> typeReference,
+            SerializableConsumer<T> resultHandler) {
+        then(typeReference, resultHandler, null);
+    }
+
+    /**
+     * Creates a typed completable future that will be completed with the result
+     * of the execution. It will be completed asynchronously when the result of
+     * the execution is sent back to the server.
+     * <p>
+     * The JavaScript return value will be automatically converted to the type
+     * specified by the {@link TypeReference}. This method supports generic
+     * types such as {@code List<MyBean>} and {@code Map<String, MyBean>}.
+     * <p>
+     * A completable future can only be created before the execution has been
+     * sent to the browser.
+     *
+     * @param <T>
+     *            the type to convert the result to
+     * @param typeReference
+     *            the type reference describing the target type, not
+     *            <code>null</code>
+     * @return a completable future that will be completed based on the
+     *         execution results, not <code>null</code>
+     */
+    default <T> CompletableFuture<T> toCompletableFuture(
+            TypeReference<T> typeReference) {
+        if (typeReference == null) {
+            throw new IllegalArgumentException("Type reference cannot be null");
+        }
+
+        VaadinSession session = VaadinSession.getCurrent();
+
+        CompletableFuture<T> completableFuture = new DeadlockDetectingCompletableFuture<>(
+                session);
+
+        then(value -> {
+            T convertedValue = JacksonCodec.decodeAs(value, typeReference);
+            completableFuture.complete(convertedValue);
+        }, errorValue -> {
+            JavaScriptException exception = new JavaScriptException(errorValue);
+            completableFuture.completeExceptionally(exception);
+        });
+
+        return completableFuture;
+    }
+
     /**
      * Adds an untyped handler that will be run for a successful execution and a
      * handler that will be run for a failed execution. One of the handlers will

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

@@ -21,8 +21,10 @@
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Consumer;
 
+import tools.jackson.core.type.TypeReference;
 import tools.jackson.databind.JsonNode;
 
+import com.vaadin.flow.internal.JacksonCodec;
 import com.vaadin.flow.internal.NodeOwner;
 import com.vaadin.flow.internal.StateNode;
 import com.vaadin.flow.internal.StateTree;
@@ -157,6 +159,54 @@ public JsonNode getEventData() {
         return eventData;
     }
 
+    /**
+     * Gets the event data deserialized as the given type. This method supports
+     * arbitrary bean types through Jackson deserialization.
+     * <p>
+     * Example usage:
+     *
+     * <pre>
+     * MyDto dto = domEvent.getEventData(MyDto.class);
+     * </pre>
+     *
+     * @param <T>
+     *            the type to deserialize to
+     * @param type
+     *            the class to deserialize the event data to, not
+     *            <code>null</code>
+     * @return the event data deserialized as the given type
+     * @see DomListenerRegistration#addEventData(String)
+     */
+    public <T> T getEventData(Class<T> type) {
+        return JacksonCodec.decodeAs(eventData, type);
+    }
+
+    /**
+     * Gets the event data deserialized as the type specified by the
+     * {@link TypeReference}. This method supports generic types such as
+     * {@code List<MyBean>} and {@code Map<String, MyBean>} through Jackson's
+     * TypeReference mechanism.
+     * <p>
+     * Example usage:
+     *
+     * <pre>
+     * TypeReference&lt;List&lt;MyDto&gt;&gt; typeRef = new TypeReference&lt;List&lt;MyDto&gt;&gt;() {
+     * };
+     * List&lt;MyDto&gt; dtos = domEvent.getEventData(typeRef);
+     * </pre>
+     *
+     * @param <T>
+     *            the type to deserialize to
+     * @param typeReference
+     *            the type reference describing the target type, not
+     *            <code>null</code>
+     * @return the event data deserialized as the given type
+     * @see DomListenerRegistration#addEventData(String)
+     */
+    public <T> T getEventData(TypeReference<T> typeReference) {
+        return JacksonCodec.decodeAs(eventData, typeReference);
+    }
+
     /**
      * Gets the debounce phase for which this event is fired. This is used
      * internally to only deliver the event to the appropriate listener in cases

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

@@ -15,10 +15,15 @@
  */
 package com.vaadin.flow.dom;
 
+import java.beans.IntrospectionException;
+import java.util.List;
 import java.util.Objects;
 import java.util.Set;
 
+import tools.jackson.core.type.TypeReference;
+
 import com.vaadin.flow.function.SerializableRunnable;
+import com.vaadin.flow.internal.BeanUtil;
 import com.vaadin.flow.shared.JsonConstants;
 import com.vaadin.flow.shared.Registration;
 
@@ -399,6 +404,103 @@ default public DomListenerRegistration preventDefault() {
         return this;
     }
 
+    /**
+     * Automatically adds event data expressions for all properties of the given
+     * class. This method uses Java Bean introspection to discover the
+     * properties of the class and adds event data expressions for each field
+     * path.
+     * <p>
+     * This is particularly useful with Java records that mirror the JavaScript
+     * event structure. For example:
+     *
+     * <pre>
+     * record MouseEventData(EventDetails event) {
+     *     record EventDetails(int button, int clientX, int clientY) {
+     *     }
+     * }
+     *
+     * element.addEventListener("click", e -&gt; {
+     *     MouseEventData data = e.getEventData(MouseEventData.class);
+     *     System.out.println("Button: " + data.event().button());
+     * }).addEventData(MouseEventData.class);
+     * </pre>
+     *
+     * The above will automatically add event data expressions for
+     * {@code event.button}, {@code event.clientX}, {@code event.clientY}, and
+     * {@code type}.
+     *
+     * @param type
+     *            the class whose properties should be captured from the event
+     *            data, not <code>null</code>
+     * @return this registration, for chaining
+     * @see #addEventData(String)
+     */
+    default DomListenerRegistration addEventData(Class<?> type) {
+        if (type == null) {
+            throw new IllegalArgumentException("Type cannot be null");
+        }
+        try {
+            List<String> propertyPaths = BeanUtil.getBeanPropertyPaths(type);
+            for (String path : propertyPaths) {
+                addEventData(path);
+            }
+        } catch (IntrospectionException e) {
+            throw new IllegalArgumentException(
+                    "Failed to introspect type: " + type.getName(), e);
+        }
+        return this;
+    }
+
+    /**
+     * Automatically adds event data expressions for all properties of the type
+     * specified by the given type reference. This method uses Java Bean
+     * introspection to discover the properties and adds event data expressions
+     * for each field path.
+     * <p>
+     * For generic types like {@code List<MyBean>}, this method will attempt to
+     * extract the raw class type for introspection.
+     *
+     * @param typeReference
+     *            the type reference whose properties should be captured from
+     *            the event data, not <code>null</code>
+     * @return this registration, for chaining
+     * @see #addEventData(String)
+     */
+    default DomListenerRegistration addEventData(
+            TypeReference<?> typeReference) {
+        if (typeReference == null) {
+            throw new IllegalArgumentException("Type reference cannot be null");
+        }
+        // Extract raw class from TypeReference
+        Class<?> rawType = extractRawType(typeReference);
+
+        if (rawType != null) {
+            addEventData(rawType);
+        }
+        return this;
+    }
+
+    /**
+     * Helper method to extract the raw class from a TypeReference.
+     *
+     * @param typeReference
+     *            the type reference to extract from
+     * @return the raw class, or null if it cannot be extracted
+     */
+    private static Class<?> extractRawType(TypeReference<?> typeReference) {
+        if (typeReference.getType() instanceof Class) {
+            return (Class<?>) typeReference.getType();
+        } else if (typeReference
+                .getType() instanceof java.lang.reflect.ParameterizedType) {
+            java.lang.reflect.ParameterizedType paramType = (java.lang.reflect.ParameterizedType) typeReference
+                    .getType();
+            if (paramType.getRawType() instanceof Class) {
+                return (Class<?>) paramType.getRawType();
+            }
+        }
+        return null;
+    }
+
     /**
      * Configures the event listener to bypass the server side security checks
      * for modality. Handle with care! Can be ok when transferring data from