refactor!: Move component-bound effect to Signal public API (#23566)

* refactor: Move component-bound effect to Signal public API

Add Signal.effect(Component, SerializableRunnable) as the public API
for creating component-lifecycle-bound signal effects, delegating to the
internal Effect.effect(). Rename the existing unbound Signal.effect(EffectAction)
to Signal.unboundEffect(EffectAction) to steer users toward the
component-bound version. Migrate user-visible code from Effect.effect()
to Signal.effect().

* refactor: Remove Effect.effect(Component, ...) in favor of Signal.effect()

Signal.effect() now delegates directly to ElementEffect.effect() instead
of going through the redundant Effect.effect() intermediary. All callers
migrated to the public Signal.effect() API.

* fix: Update Javadoc references from Effect#effect to Signal#effect

Author: Artur-

flow-data/src/main/java/com/vaadin/flow/data/binder/Binder.java

@@ -64,7 +64,6 @@
 import com.vaadin.flow.internal.ReflectTools;
 import com.vaadin.flow.shared.Registration;
 import com.vaadin.flow.signals.Signal;
-import com.vaadin.flow.signals.impl.Effect;
 import com.vaadin.flow.signals.impl.UsageTracker;
 import com.vaadin.flow.signals.local.ValueSignal;
 
@@ -382,7 +381,7 @@ void setIsAppliedPredicate(
          * {@link BindingBuilder#withValidator(Validator)}.
          * <p>
          * The Binder automatically runs validators inside a
-         * {@link com.vaadin.flow.signals.impl.Effect#effect(Component, com.vaadin.flow.function.SerializableRunnable)}
+         * {@link Signal#effect(Component, com.vaadin.flow.function.SerializableRunnable)}
          * context. This makes validators reactive to signal changes - when you
          * call {@code value()} on another binding from within a validator, the
          * validator will automatically re-run whenever that other binding's
@@ -435,7 +434,7 @@ void setIsAppliedPredicate(
          *
          * @see BindingBuilder#withValidator(Validator)
          * @see com.vaadin.flow.component.HasValue#bindValue
-         * @see com.vaadin.flow.signals.impl.Effect#effect(Component,
+         * @see Signal#effect(Component,
          *      com.vaadin.flow.function.SerializableRunnable)
          *
          * @since 25.1
@@ -1711,7 +1710,7 @@ private FIELDVALUE convertToFieldType(TARGET target) {
         private void initInternalSignalEffectForValidators() {
             if (signalRegistration == null
                     && getField() instanceof Component component) {
-                signalRegistration = Effect.effect(component, () -> {
+                signalRegistration = Signal.effect(component, () -> {
                     if (valueInit) {
                         // start to track signal usage
                         doConversion();

flow-data/src/test/java/com/vaadin/flow/data/binder/BinderSignalTest.java

@@ -28,7 +28,6 @@
 import com.vaadin.flow.dom.SignalsUnitTest;
 import com.vaadin.flow.function.SerializablePredicate;
 import com.vaadin.flow.signals.Signal;
-import com.vaadin.flow.signals.impl.Effect;
 import com.vaadin.flow.signals.local.ValueSignal;
 import com.vaadin.flow.tests.data.bean.Person;
 
@@ -864,7 +863,7 @@ private void testStatusChangeRunEffects(Runnable binderSetup) {
 
         AtomicInteger effectCalled = new AtomicInteger(0);
         AtomicBoolean prevStatus = new AtomicBoolean(true);
-        Effect.effect(firstNameField, () -> {
+        Signal.effect(firstNameField, () -> {
             prevStatus.set(binder.getValidationStatus().get().isOk());
             effectCalled.incrementAndGet();
         });
@@ -910,7 +909,7 @@ private void testInitialStatusChangeRunEffects(
         binderSetup.accept(item);
 
         AtomicBoolean prevStatus = new AtomicBoolean(true);
-        Effect.effect(firstNameField, () -> {
+        Signal.effect(firstNameField, () -> {
             prevStatus.set(binder.getValidationStatus().get().isOk());
         });
 

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

@@ -22,7 +22,6 @@
 import com.vaadin.flow.shared.Registration;
 import com.vaadin.flow.signals.BindingActiveException;
 import com.vaadin.flow.signals.Signal;
-import com.vaadin.flow.signals.impl.Effect;
 
 /**
  * Helper class for binding a {@link Signal} to a property of a
@@ -131,7 +130,7 @@ public void bind(Signal<T> signal) {
             throw new BindingActiveException();
         }
         this.signal = signal;
-        registration = Effect.effect(owner, () -> {
+        registration = Signal.effect(owner, () -> {
             value = signal.get();
             valueChangeConsumer.accept(value);
         });

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

@@ -42,10 +42,10 @@
  * context of a given element's life-cycle.
  * <p>
  * It ultimately creates a Signal effect, i.e. a call to
- * {@link Signal#effect(EffectAction)}, that is automatically enabled when an
- * element is attached and disabled when the element is detached. Additionally,
- * it provides methods to bind signals to element according to a given value
- * setting function.
+ * {@link Signal#unboundEffect(EffectAction)}, that is automatically enabled
+ * when an element is attached and disabled when the element is detached.
+ * Additionally, it provides methods to bind signals to element according to a
+ * given value setting function.
  * <p>
  * For internal use only. May be renamed or removed in a future release.
  *
@@ -98,7 +98,7 @@ public ElementEffect(Element owner, SerializableRunnable effectFunction) {
      * effect.remove(); // to remove the effect when no longer needed
      * </pre>
      *
-     * @see Signal#effect(EffectAction)
+     * @see Signal#unboundEffect(EffectAction)
      * @param owner
      *            the owner element for which the effect is applied, must not be
      *            <code>null</code>
@@ -131,7 +131,7 @@ public static Registration effect(Element owner,
      *         Element::setVisible);
      * </pre>
      *
-     * @see Signal#effect(EffectAction)
+     * @see Signal#unboundEffect(EffectAction)
      * @param owner
      *            the owner element for which the effect is applied, must not be
      *            <code>null</code>

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

@@ -20,6 +20,10 @@
 
 import org.jspecify.annotations.Nullable;
 
+import com.vaadin.flow.component.Component;
+import com.vaadin.flow.dom.ElementEffect;
+import com.vaadin.flow.function.SerializableRunnable;
+import com.vaadin.flow.shared.Registration;
 import com.vaadin.flow.signals.function.CleanupCallback;
 import com.vaadin.flow.signals.function.EffectAction;
 import com.vaadin.flow.signals.function.SignalComputation;
@@ -37,10 +41,10 @@
  * A signal is a reactive value holder with automatic subscription and
  * unsubscription of listeners.
  * <p>
- * Reactivity is based on {@link Signal#effect(EffectAction)} callbacks that
- * detect the signals used during invocation. The callback will be run again
- * whenever there's a change to any of the signal instances used in the previous
- * invocation. Detection is based on running {@link #get()}.
+ * Reactivity is based on {@link Signal#unboundEffect(EffectAction)} callbacks
+ * that detect the signals used during invocation. The callback will be run
+ * again whenever there's a change to any of the signal instances used in the
+ * previous invocation. Detection is based on running {@link #get()}.
  * {@link #untracked(ValueSupplier)} can be used to read the value within an
  * effect without registering a dependency.
  * <p>
@@ -64,7 +68,7 @@ public interface Signal<T> extends Serializable {
      * transaction depend on the value so that the transaction fails in case the
      * signal value is changed concurrently.
      * <p>
-     * Reading the value inside an {@link #effect(EffectAction)} or
+     * Reading the value inside an {@link #unboundEffect(EffectAction)} or
      * {@link #computed(SignalComputation)} callback sets up that effect or
      * computed signal to depend on the signal.
      *
@@ -117,16 +121,50 @@ default <C> Signal<C> map(SignalMapper<T, C> mapper) {
      */
 
     /**
-     * Creates a signal effect with the given action. The action is run when the
-     * effect is created and is subsequently run again whenever there's a change
-     * to any signal value that was read during the last invocation.
+     * Creates a signal effect that is owned by a given component. The effect is
+     * enabled when the component is attached and automatically disabled when it
+     * is detached.
+     * <p>
+     * Example of usage:
+     *
+     * <pre>
+     * Registration effect = Signal.effect(myComponent, () -> {
+     *     Notification.show("Component is attached and signal value is "
+     *             + someSignal.get());
+     * });
+     * effect.remove(); // to remove the effect when no longer needed
+     * </pre>
+     *
+     * @param <C>
+     *            the type of the component
+     * @param owner
+     *            the owner component for which the effect is applied, must not
+     *            be <code>null</code>
+     * @param effectFunction
+     *            the effect function to be executed when any dependency is
+     *            changed, must not be <code>null</code>
+     * @return a {@link Registration} that can be used to remove the effect
+     *         function
+     */
+    static <C extends Component> Registration effect(C owner,
+            SerializableRunnable effectFunction) {
+        return ElementEffect.effect(owner.getElement(), effectFunction);
+    }
+
+    /**
+     * Creates an unbound signal effect with the given action. The action is run
+     * when the effect is created and is subsequently run again whenever there's
+     * a change to any signal value that was read during the last invocation.
+     * <p>
+     * Consider using {@link #effect(Component, SerializableRunnable)} instead
+     * to tie the effect lifecycle to a component.
      *
      * @param action
      *            the effect action to use, not <code>null</code>
      * @return a callback used to close the effect so that it no longer listens
      *         to signal changes, not <code>null</code>
      */
-    static CleanupCallback effect(EffectAction action) {
+    static CleanupCallback unboundEffect(EffectAction action) {
         Effect effect = new Effect(Objects.requireNonNull(action));
         return effect::dispose;
     }
@@ -140,10 +178,10 @@ static CleanupCallback effect(EffectAction action) {
      * and only if the previously computed value might have been invalidated by
      * dependent signal changes. If the computation callback throws a
      * {@link RuntimeException}, then that exception will be re-thrown when
-     * accessing the signal value. An {@link Signal#effect(EffectAction) effect}
-     * or computed signal that uses the value from a computed signal will not be
-     * invalidated if the computation is run again but produces the same value
-     * as before.
+     * accessing the signal value. An {@link Signal#unboundEffect(EffectAction)
+     * effect} or computed signal that uses the value from a computed signal
+     * will not be invalidated if the computation is run again but produces the
+     * same value as before.
      *
      * @param <T>
      *            the signal type

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

@@ -24,10 +24,10 @@
  * dispose of resources, or cancel an ongoing operation.
  * <p>
  * This is typically returned from registration methods such as
- * {@link Signal#effect(EffectAction)} to allow the caller to clean up the
- * registration when it's no longer needed.
+ * {@link Signal#unboundEffect(EffectAction)} to allow the caller to clean up
+ * the registration when it's no longer needed.
  *
- * @see Signal#effect(EffectAction)
+ * @see Signal#unboundEffect(EffectAction)
  */
 @FunctionalInterface
 public interface CleanupCallback extends Serializable {

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

@@ -28,7 +28,7 @@
  * during the action execution. When any of those signals change, the action is
  * re-run with updated dependencies.
  *
- * @see Signal#effect(EffectAction)
+ * @see Signal#unboundEffect(EffectAction)
  */
 @FunctionalInterface
 public interface EffectAction extends Serializable {

flow-server/src/main/java/com/vaadin/flow/signals/impl/ComputedSignal.java

@@ -41,9 +41,9 @@
  * changed for any of the signals that were used when computing the previous
  * value. If the computation callback throws a {@link RuntimeException}, then
  * that exception will be re-thrown when accessing the value of this signal. An
- * {@link Signal#effect(EffectAction) effect} or computed signal that uses the
- * value from a computed signal will not be invalidated if the computation is
- * run again but produces the same value as before.
+ * {@link Signal#unboundEffect(EffectAction) effect} or computed signal that
+ * uses the value from a computed signal will not be invalidated if the
+ * computation is run again but produces the same value as before.
  *
  * @param <T>
  *            the value type

flow-server/src/main/java/com/vaadin/flow/signals/impl/Effect.java

@@ -23,10 +23,7 @@
 
 import org.jspecify.annotations.Nullable;
 
-import com.vaadin.flow.component.Component;
-import com.vaadin.flow.dom.ElementEffect;
 import com.vaadin.flow.function.SerializableRunnable;
-import com.vaadin.flow.shared.Registration;
 import com.vaadin.flow.signals.SignalEnvironment;
 import com.vaadin.flow.signals.function.CleanupCallback;
 import com.vaadin.flow.signals.function.EffectAction;
@@ -191,35 +188,4 @@ public synchronized void dispose() {
         action = null;
     }
 
-    /**
-     * Creates a Signal effect that is owned by a given component. The effect is
-     * enabled when the component is attached and automatically disabled when it
-     * is detached.
-     * <p>
-     * Example of usage:
-     *
-     * <pre>
-     * Registration effect = Effect.effect(myComponent, () -> {
-     *     Notification.show("Component is attached and signal value is "
-     *             + someSignal.get());
-     * });
-     * effect.remove(); // to remove the effect when no longer needed
-     * </pre>
-     *
-     * @param <C>
-     *            the type of the component
-     * @param owner
-     *            the owner component for which the effect is applied, must not
-     *            be <code>null</code>
-     * @param effectFunction
-     *            the effect function to be executed when any dependency is
-     *            changed, must not be <code>null</code>
-     * @return a {@link Registration} that can be used to remove the effect
-     *         function
-     */
-    public static <C extends Component> Registration effect(C owner,
-            SerializableRunnable effectFunction) {
-        return ElementEffect.effect(owner.getElement(), effectFunction);
-    }
-
 }

flow-server/src/test/java/com/vaadin/flow/component/AbstractFieldBindValueTest.java

@@ -25,7 +25,6 @@
 import com.vaadin.flow.internal.nodefeature.SignalBindingFeature;
 import com.vaadin.flow.signals.BindingActiveException;
 import com.vaadin.flow.signals.Signal;
-import com.vaadin.flow.signals.impl.Effect;
 import com.vaadin.flow.signals.local.ValueSignal;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -232,7 +231,7 @@ public void bindValue_setValue_countEffectExecutions() {
         input.bindValue(signal, signal::set);
 
         AtomicInteger counter = new AtomicInteger(0);
-        Effect.effect(input, () -> {
+        Signal.effect(input, () -> {
             signal.get();
             counter.incrementAndGet();
         });