feat: Use type-parameter-level nullability for Signal APIs (#23630)

Follow Java's List<E> pattern where nullability flows from the type argument rather than being hardcoded on method signatures. This makes Signal<String>.get() return non-null String while
Signal<@nullable String>.get() returns @nullable String.

Key changes:
- All signal type parameters use <T extends @nullable Object> bound
- Remove explicit @nullable from public method signatures (get, peek, set, replace, map, computed, etc.)

Author: Artur-

flow-server/pom.xml

@@ -224,6 +224,40 @@
               <fork>true</fork>
             </configuration>
           </execution>
+          <execution>
+            <id>default-testCompile</id>
+            <configuration>
+              <compilerArgs>
+                <arg>-XDcompilePolicy=simple</arg>
+                <arg>-XDaddTypeAnnotationsToSymbol=true</arg>
+                <arg>--should-stop=ifError=FLOW</arg>
+                <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</arg>
+                <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED</arg>
+                <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED</arg>
+                <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED</arg>
+                <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</arg>
+                <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED</arg>
+                <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED</arg>
+                <arg>-J--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED</arg>
+                <arg>-J--add-opens=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED</arg>
+                <arg>-J--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED</arg>
+                <arg>-Xplugin:ErrorProne -XepDisableAllChecks -Xep:NullAway:ERROR -XepOpt:NullAway:JSpecifyMode=true -XepOpt:NullAway:OnlyNullMarked=true</arg>
+              </compilerArgs>
+              <annotationProcessorPaths>
+                <path>
+                  <groupId>com.google.errorprone</groupId>
+                  <artifactId>error_prone_core</artifactId>
+                  <version>2.47.0</version>
+                </path>
+                <path>
+                  <groupId>com.uber.nullaway</groupId>
+                  <artifactId>nullaway</artifactId>
+                  <version>0.13.1</version>
+                </path>
+              </annotationProcessorPaths>
+              <fork>true</fork>
+            </configuration>
+          </execution>
         </executions>
       </plugin>
       <plugin>

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

@@ -22,6 +22,7 @@
 import java.util.Objects;
 import java.util.Optional;
 
+import org.jspecify.annotations.Nullable;
 import org.slf4j.LoggerFactory;
 
 import com.vaadin.flow.dom.Element;
@@ -245,7 +246,8 @@ default void addComponentAsFirst(Component component) {
      * @throws BindingActiveException
      *             thrown if a binding for children already exists
      */
-    default <T, S extends Signal<T>> void bindChildren(Signal<List<S>> list,
+    default <T extends @Nullable Object, S extends Signal<T>> void bindChildren(
+            Signal<List<S>> list,
             SerializableFunction<S, Component> childFactory) {
         var self = (Component & HasComponents) this;
         var node = self.getElement().getNode();

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

@@ -18,6 +18,8 @@
 import java.io.Serializable;
 import java.util.Objects;
 
+import org.jspecify.annotations.Nullable;
+
 import com.vaadin.flow.function.SerializableConsumer;
 import com.vaadin.flow.shared.Registration;
 import com.vaadin.flow.signals.BindingActiveException;
@@ -65,7 +67,8 @@
  * @param <T>
  *            the type of the property
  */
-public class SignalPropertySupport<T> implements Serializable {
+public class SignalPropertySupport<T extends @Nullable Object>
+        implements Serializable {
 
     private final SerializableConsumer<T> valueChangeConsumer;
 
@@ -104,8 +107,8 @@ private SignalPropertySupport(Component owner,
      * @return a new instance of SignalPropertySupport
      * @see #bind(Signal)
      */
-    public static <T> SignalPropertySupport<T> create(Component owner,
-            SerializableConsumer<T> valueChangeConsumer) {
+    public static <T extends @Nullable Object> SignalPropertySupport<T> create(
+            Component owner, SerializableConsumer<T> valueChangeConsumer) {
         return new SignalPropertySupport<>(owner, valueChangeConsumer);
     }
 

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

@@ -30,6 +30,7 @@
 import java.util.stream.Stream;
 
 import org.jsoup.nodes.Document;
+import org.jspecify.annotations.Nullable;
 import tools.jackson.core.type.TypeReference;
 import tools.jackson.databind.JsonNode;
 import tools.jackson.databind.node.BaseJsonNode;
@@ -899,8 +900,8 @@ public Element setPropertyMap(String name, Map<String, ?> value) {
      *             thrown when there is already an existing binding
      * @see #setProperty(String, String)
      */
-    public <T> void bindProperty(String name, Signal<T> signal,
-            SerializableConsumer<T> writeCallback) {
+    public <T extends @Nullable Object> void bindProperty(String name,
+            Signal<T> signal, SerializableConsumer<T> writeCallback) {
         verifySetPropertyName(name);
 
         getStateProvider().bindPropertySignal(this, name, signal,

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

@@ -23,6 +23,8 @@
 import java.util.Objects;
 import java.util.stream.Collectors;
 
+import org.jspecify.annotations.Nullable;
+
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.ComponentUtil;
 import com.vaadin.flow.component.UI;
@@ -145,8 +147,8 @@ public static Registration effect(Element owner,
      * @param <T>
      *            the type of the signal value
      */
-    public static <T> Registration bind(Element owner, Signal<T> signal,
-            SerializableBiConsumer<Element, T> setter) {
+    public static <T extends @Nullable Object> Registration bind(Element owner,
+            Signal<T> signal, SerializableBiConsumer<Element, T> setter) {
         return effect(owner, () -> {
             setter.accept(owner, signal.get());
         });
@@ -239,7 +241,7 @@ public void close() {
      * @throws IllegalStateException
      *             thrown if parent element isn't empty
      */
-    public static <T, S extends Signal<T>> Registration bindChildren(
+    public static <T extends @Nullable Object, S extends Signal<T>> Registration bindChildren(
             Element parentElement, Signal<List<S>> list,
             SerializableFunction<S, Element> childFactory) {
         Objects.requireNonNull(parentElement, "Parent element cannot be null");
@@ -263,7 +265,7 @@ public static <T, S extends Signal<T>> Registration bindChildren(
                         valueSignalToChildCache)))::close;
     }
 
-    private static <T, S extends Signal<T>> void runEffect(
+    private static <T extends @Nullable Object, S extends Signal<T>> void runEffect(
             BindChildrenEffectContext<T, S> context) {
         // Cache the children to avoid multiple traversals
         LinkedList<Element> remainingChildren = context
@@ -291,7 +293,7 @@ private static <T, S extends Signal<T>> void runEffect(
      * Validate that parent element has no children not belonging to the list of
      * child signals.
      */
-    private static <T, S extends Signal<T>> void validate(
+    private static <T extends @Nullable Object, S extends Signal<T>> void validate(
             BindChildrenEffectContext<T, S> context) {
         LinkedList<Element> children = context.parentChildrenToLinkedList();
         int index = 0;
@@ -321,7 +323,7 @@ private static <T, S extends Signal<T>> void validate(
      * Remove all existing children in valueSignalToChildCache map that are no
      * longer present in the list of child signals.
      */
-    private static <T, S extends Signal<T>> void removeNotPresentChildren(
+    private static <T extends @Nullable Object, S extends Signal<T>> void removeNotPresentChildren(
             BindChildrenEffectContext<T, S> context,
             HashSet<Element> remainingChildrenSet) {
         var toRemove = new HashSet<>(context.valueSignalToChildCache.keySet());
@@ -339,7 +341,7 @@ private static <T, S extends Signal<T>> void removeNotPresentChildren(
      * removing any existing elements. Creates new elements with the element
      * factory if not found from the cache.
      */
-    private static <T, S extends Signal<T>> void updateByChildSignals(
+    private static <T extends @Nullable Object, S extends Signal<T>> void updateByChildSignals(
             BindChildrenEffectContext<T, S> context,
             LinkedList<Element> remainingChildren,
             HashSet<Element> remainingChildrenSet) {
@@ -410,7 +412,7 @@ private static <T, S extends Signal<T>> void updateByChildSignals(
      * @param <S>
      *            the type of the signal in the list
      */
-    private record BindChildrenEffectContext<T, S extends Signal<T>>(
+    private record BindChildrenEffectContext<T extends @Nullable Object, S extends Signal<T>>(
             Element parentElement, List<S> childSignalsList,
             SerializableFunction<S, Element> childElementFactory,
             HashMap<S, Element> valueSignalToChildCache)

flow-server/src/main/java/com/vaadin/flow/internal/nodefeature/NodeMap.java

@@ -26,6 +26,8 @@
 import java.util.function.Consumer;
 import java.util.stream.Stream;
 
+import org.jspecify.annotations.Nullable;
+
 import com.vaadin.flow.dom.Element;
 import com.vaadin.flow.dom.ElementEffect;
 import com.vaadin.flow.function.SerializableBiConsumer;
@@ -565,7 +567,8 @@ boolean usesSingleMap() {
      *             given key
      *
      */
-    protected <T> void bindSignal(Element owner, String key, Signal<T> signal,
+    protected <T extends @Nullable Object> void bindSignal(Element owner,
+            String key, Signal<T> signal,
             SerializableBiConsumer<Element, T> setter,
             SerializableConsumer<?> writeCallback) {
         Objects.requireNonNull(signal, "Signal cannot be null");

flow-server/src/main/java/com/vaadin/flow/internal/nodefeature/SignalBindingFeature.java

@@ -19,6 +19,8 @@
 import java.util.HashMap;
 import java.util.Map;
 
+import org.jspecify.annotations.Nullable;
+
 import com.vaadin.flow.function.SerializableBiPredicate;
 import com.vaadin.flow.function.SerializableConsumer;
 import com.vaadin.flow.internal.StateNode;
@@ -174,7 +176,8 @@ public <T> SerializableConsumer<T> getWriteCallback(String key) {
      *            the type of the signal value
      * @return the signal bound to the given key, or null if no signal is bound
      */
-    public <T> Signal<T> getSignal(String key) {
+    @SuppressWarnings("unchecked")
+    public <T extends @Nullable Object> Signal<T> getSignal(String key) {
         if (values == null) {
             return null;
         }
@@ -208,8 +211,9 @@ public <T> Signal<T> getSignal(String key) {
      * @param <T>
      *            the type of the signal value
      */
-    public <T> boolean updateSignalByWriteCallback(String key, T oldValue,
-            T newValue, SerializableBiPredicate<T, T> valueEquals,
+    public <T extends @Nullable Object> boolean updateSignalByWriteCallback(
+            String key, T oldValue, T newValue,
+            SerializableBiPredicate<T, T> valueEquals,
             SerializableConsumer<T> revertCallback) {
         SerializableConsumer<T> callback = getWriteCallback(key);
         Signal<T> signal = getSignal(key);

flow-server/src/main/java/com/vaadin/flow/signals/Signal.java

@@ -54,7 +54,7 @@
  *            the signal value type
  */
 @FunctionalInterface
-public interface Signal<T> extends Serializable {
+public interface Signal<T extends @Nullable Object> extends Serializable {
     /**
      * Gets the current value of this signal. The value is read in a way that
      * takes the current transaction into account and in the case of clustering
@@ -81,7 +81,6 @@ public interface Signal<T> extends Serializable {
      * @throws IllegalStateException
      *             if called outside a reactive context
      */
-    @Nullable
     T get();
 
     /**
@@ -95,7 +94,7 @@ public interface Signal<T> extends Serializable {
      *
      * @return the signal value
      */
-    default @Nullable T peek() {
+    default T peek() {
         /*
          * Subclasses are encouraged to use an approach with less overhead than
          * what this very generic implementation can do.
@@ -121,7 +120,8 @@ public interface Signal<T> extends Serializable {
      *            the mapper function to use, not <code>null</code>
      * @return the computed signal, not <code>null</code>
      */
-    default <C> Signal<C> map(SignalMapper<T, C> mapper) {
+    default <C extends @Nullable Object> Signal<C> map(
+            SignalMapper<T, C> mapper) {
         return () -> mapper.map(get());
     }
 
@@ -210,22 +210,21 @@ static Registration unboundEffect(EffectAction action) {
      *            the computation callback, not <code>null</code>
      * @return the computed signal, not <code>null</code>
      */
-    static <T> Signal<T> computed(SignalComputation<T> computation) {
+    static <T extends @Nullable Object> Signal<T> computed(
+            SignalComputation<T> computation) {
         return new ComputedSignal<>(computation);
     }
 
     /**
-     * Crates a new computed signal containing the negation of the provided
-     * boolean-valued signal. <code>null</code> values are preserved as
-     * <code>null</code>.
-     * 
+     * Creates a new computed signal containing the negation of the provided
+     * boolean-valued signal.
+     *
      * @param signal
      *            the boolean-valued signal to negate, not <code>null</code>
      * @return the negated signal, not <code>null</code>
      */
     static Signal<Boolean> not(Signal<Boolean> signal) {
-        return Objects.requireNonNull(signal)
-                .map(value -> value == null ? null : !value);
+        return Objects.requireNonNull(signal).map(value -> !value);
     }
 
     /**
@@ -250,7 +249,7 @@ static Signal<Boolean> not(Signal<Boolean> signal) {
      * @return a transaction operation containing the supplier return value and
      *         the eventual result
      */
-    static <T> TransactionOperation<T> runInTransaction(
+    static <T extends @Nullable Object> TransactionOperation<T> runInTransaction(
             ValueSupplier<T> transactionTask) {
         return Transaction.runInTransaction(transactionTask);
     }
@@ -289,7 +288,8 @@ static TransactionOperation<Void> runInTransaction(
      *            the supplier to run, not <code>null</code>
      * @return the value returned from the supplier
      */
-    static <T> @Nullable T runWithoutTransaction(ValueSupplier<T> task) {
+    static <T extends @Nullable Object> T runWithoutTransaction(
+            ValueSupplier<T> task) {
         return Transaction.runWithoutTransaction(task);
     }
 
@@ -316,7 +316,7 @@ static void runWithoutTransaction(TransactionTask task) {
      *            the supplier task to run, not <code>null</code>
      * @return the value returned from the supplier
      */
-    static <T> @Nullable T untracked(ValueSupplier<T> task) {
+    static <T extends @Nullable Object> T untracked(ValueSupplier<T> task) {
         /*
          * Note that there's no Runnable overload since the whole point of
          * untracked is to read values.

flow-server/src/main/java/com/vaadin/flow/signals/function/SignalComputation.java

@@ -35,13 +35,13 @@
  * @see Signal#computed(SignalComputation)
  */
 @FunctionalInterface
-public interface SignalComputation<T> extends Serializable {
+public interface SignalComputation<T extends @Nullable Object>
+        extends Serializable {
     /**
      * Computes the signal value, automatically tracking dependencies on other
      * signals.
      *
-     * @return the computed value, may be <code>null</code>
+     * @return the computed value
      */
-    @Nullable
     T compute();
 }

flow-server/src/main/java/com/vaadin/flow/signals/function/SignalMapper.java

@@ -35,14 +35,14 @@
  * @see Signal#map(SignalMapper)
  */
 @FunctionalInterface
-public interface SignalMapper<T, R> extends Serializable {
+public interface SignalMapper<T extends @Nullable Object, R extends @Nullable Object>
+        extends Serializable {
     /**
      * Applies this mapper to transform a signal value.
      *
      * @param value
-     *            the input value, may be <code>null</code>
-     * @return the transformed value, may be <code>null</code>
+     *            the input value
+     * @return the transformed value
      */
-    @Nullable
-    R map(@Nullable T value);
+    R map(T value);
 }