feat: Add signal binding for style property (#22752)

Allows a string signal binding for style properties, e.g.:

ValueSignal<String> backgroundColor = new ValueSignal<>("red");
textField.getStyle().bind("background-color", backgroundColor);

Fixes #22671

Author: mshabarov

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

@@ -19,6 +19,8 @@
 import java.util.stream.Stream;
 
 import com.vaadin.flow.component.page.ColorScheme;
+import com.vaadin.signals.BindingActiveException;
+import com.vaadin.signals.Signal;
 
 import static com.vaadin.flow.dom.ElementConstants.STYLE_ALIGN_ITEMS;
 import static com.vaadin.flow.dom.ElementConstants.STYLE_ALIGN_SELF;
@@ -100,13 +102,19 @@ public interface Style extends Serializable {
     /**
      * Gets the value of the given style property.
      * <p>
-     * Note that the name should be in camelCase and not dash-separated, i.e.
-     * use "fontFamily" and not "font-family"
+     * Note that the name should be in camelCase and not dash-separated, i.e.,
+     * use "fontFamily" and not "font-family".
+     * <p>
+     * When a style property is bound to a signal with
+     * {@link #bind(String, Signal)}, this method returns the value of the
+     * latest signal applied for the given style property name while the element
+     * was in the attached state.
      *
      * @param name
      *            the style property name as camelCase, not <code>null</code>
      * @return the style property value, or <code>null</code> if the style
      *         property has not been set
+     * @see #bind(String, Signal)
      */
     String get(String name);
 
@@ -115,13 +123,17 @@ public interface Style extends Serializable {
      * <p>
      * Both camelCased (e.g. <code>fontFamily</code>) and dash-separated (e.g.
      * <code>font-family</code> versions are supported.
+     * <p>
+     * While a signal binding for a specific style name is active, any attempt
+     * to manually set that same style throws a {@link BindingActiveException}.
      *
      * @param name
      *            the style property name as camelCase, not <code>null</code>
      * @param value
      *            the style property value (if <code>null</code>, the property
      *            will be removed)
      * @return this style instance
+     * @see #bind(String, Signal)
      */
     Style set(String name, String value);
 
@@ -130,17 +142,26 @@ public interface Style extends Serializable {
      * <p>
      * Both camelCased (e.g. <code>fontFamily</code>) and dash-separated (e.g.
      * <code>font-family</code> versions are supported.
+     * <p>
+     * While a signal binding for a specific style name is active, any attempt
+     * to manually remove that same style throws a
+     * {@link BindingActiveException}.
      *
      * @param name
      *            the style property name as camelCase, not <code>null</code>
      * @return this style instance
+     * @see #bind(String, Signal)
      */
     Style remove(String name);
 
     /**
      * Removes all set style properties.
+     * <p>
+     * This method silently clears all style signal bindings (unsubscribe and
+     * forget recorded values) in addition to clearing style values.
      *
      * @return this style instance
+     * @see #bind(String, Signal)
      */
     Style clear();
 
@@ -164,11 +185,56 @@ public interface Style extends Serializable {
      * Note that this always returns the name as camelCased, e.g.
      * <code>fontFamily</code> even if it has been set as dash-separated
      * (<code>font-family</code>).
+     * <p>
+     * Includes names of the style properties bound with the signals while the
+     * element was in the attached state.
      *
      * @return a stream of defined style property names
+     * @see #bind(String, Signal)
      */
     Stream<String> getNames();
 
+    /**
+     * Binds the given style property to the provided string signal and keeps
+     * the style property value synchronized with the signal.
+     * <p>
+     * Passing {@code null} as the {@code signal} removes any existing binding
+     * for the given style property. When unbinding, the current presence of the
+     * style property is left unchanged.
+     * <p>
+     * When a binding is in place, the style signal mirrors
+     * {@code signal.value()}. If the signal value is {@code null}, the style
+     * property is removed; otherwise it is set to the string value.
+     * <p>
+     * The binding effect is active only while the owner element is in the
+     * attached state. While the owner is in the detached state, updates from
+     * the signal have no effect.
+     * <p>
+     * While a binding for a specific style name is active, any attempt to bind
+     * another signal for the same name throws a {@link BindingActiveException}.
+     * <p>
+     * Name handling follows the same rules as {@link #set(String, String)}:
+     * both camelCase and dash-separated names are supported and normalized in
+     * the same way.
+     *
+     * @param name
+     *            the style property name, not {@code null}
+     * @param signal
+     *            the signal that provides the style signal; {@code null}
+     *            removes an existing binding for the given name
+     * @return this style instance
+     * @throws BindingActiveException
+     *             thrown when there is already an existing binding
+     * @see #set(String, String)
+     * @see #remove(String)
+     * @see #clear()
+     * @see #get(String)
+     * @see #getNames()
+     *
+     * @since 25.0
+     */
+    Style bind(String name, Signal<String> signal);
+
     /**
      * Sets the <code>background</code> property.
      *

flow-server/src/main/java/com/vaadin/flow/dom/impl/BasicElementStyle.java

@@ -17,10 +17,13 @@
 
 import java.util.stream.Stream;
 
+import com.vaadin.flow.dom.Element;
 import com.vaadin.flow.dom.ElementUtil;
 import com.vaadin.flow.dom.Style;
 import com.vaadin.flow.dom.StyleUtil;
 import com.vaadin.flow.internal.nodefeature.ElementStylePropertyMap;
+import com.vaadin.signals.BindingActiveException;
+import com.vaadin.signals.Signal;
 
 /**
  * Implementation of {@link Style} for {@link BasicElementStateProvider}.
@@ -32,7 +35,7 @@
  */
 public class BasicElementStyle implements Style {
 
-    private ElementStylePropertyMap propertyMap;
+    private final ElementStylePropertyMap propertyMap;
 
     /**
      * Creates an instance connected to the given map.
@@ -47,22 +50,30 @@ public BasicElementStyle(ElementStylePropertyMap propertyMap) {
     @Override
     public Style set(String name, String value) {
         ElementUtil.validateStylePropertyName(name);
+        String attribute = StyleUtil.stylePropertyToAttribute(name);
+        if (propertyMap.hasSignal(attribute)) {
+            throw new BindingActiveException(
+                    "Style '" + name + "' is already bound to a signal");
+        }
         if (value == null) {
             return this.remove(name);
         }
         String trimmedValue = value.trim();
         ElementUtil.validateStylePropertyValue(trimmedValue);
 
-        propertyMap.setProperty(StyleUtil.stylePropertyToAttribute(name),
-                trimmedValue, true);
+        propertyMap.setProperty(attribute, trimmedValue, true);
         return this;
     }
 
     @Override
     public Style remove(String name) {
         ElementUtil.validateStylePropertyName(name);
-
-        propertyMap.removeProperty(StyleUtil.stylePropertyToAttribute(name));
+        String attribute = StyleUtil.stylePropertyToAttribute(name);
+        if (propertyMap.hasSignal(attribute)) {
+            throw new BindingActiveException(
+                    "Style '" + name + "' is already bound to a signal");
+        }
+        propertyMap.removeProperty(attribute);
         return this;
     }
 
@@ -85,6 +96,15 @@ public Stream<String> getNames() {
         return propertyMap.getPropertyNames();
     }
 
+    @Override
+    public Style bind(String name, Signal<String> signal) {
+        ElementUtil.validateStylePropertyName(name);
+        String attribute = StyleUtil.stylePropertyToAttribute(name);
+        Element owner = Element.get(propertyMap.getNode());
+        propertyMap.bindSignal(owner, attribute, signal);
+        return this;
+    }
+
     @Override
     public boolean has(String name) {
         return propertyMap

flow-server/src/main/java/com/vaadin/flow/dom/impl/ImmutableEmptyStyle.java

@@ -18,6 +18,7 @@
 import java.util.stream.Stream;
 
 import com.vaadin.flow.dom.Style;
+import com.vaadin.signals.Signal;
 
 /**
  * A style implementation which is empty and immutable.
@@ -60,4 +61,15 @@ public boolean has(String name) {
     public Stream<String> getNames() {
         return Stream.empty();
     }
+
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Immutable style implementation does not support binding a {@link Signal}
+     * to a style property,
+     */
+    @Override
+    public Style bind(String name, Signal<String> signal) {
+        throw new UnsupportedOperationException(CANT_MODIFY_MESSAGE);
+    }
 }

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

@@ -18,9 +18,14 @@
 import java.io.Serializable;
 import java.util.stream.Stream;
 
+import com.vaadin.flow.dom.Element;
+import com.vaadin.flow.dom.ElementEffect;
 import com.vaadin.flow.internal.JacksonCodec;
 import com.vaadin.flow.internal.ReflectTools;
 import com.vaadin.flow.internal.StateNode;
+import com.vaadin.flow.shared.Registration;
+import com.vaadin.signals.BindingActiveException;
+import com.vaadin.signals.Signal;
 
 /**
  * Abstract class to be used as a parent for node maps which supports setting
@@ -151,4 +156,58 @@ public void updateFromClient(String key, Serializable value) {
             super.updateFromClient(key, value);
         }
     }
+
+    /**
+     * Binds the given signal to the given property. <code>null</code> signal
+     * unbinds existing binding.
+     *
+     * @param owner
+     *            the element owning the property, not <code>null</code>
+     * @param name
+     *            the name of the property
+     * @param signal
+     *            the signal to bind or <code>null</code> to unbind any existing
+     *            binding
+     * @throws com.vaadin.signals.BindingActiveException
+     *             thrown when there is already an existing binding for the
+     *             given property
+     */
+    public void bindSignal(Element owner, String name, Signal<?> signal) {
+        SignalBinding previousSignalBinding;
+        if (super.get(name) instanceof SignalBinding binding) {
+            previousSignalBinding = binding;
+        } else {
+            previousSignalBinding = null;
+        }
+        if (signal != null && hasSignal(name)) {
+            throw new BindingActiveException();
+        }
+        Registration registration = signal != null
+                ? ElementEffect.bind(owner, signal,
+                        (element, value) -> setPropertyFromSignal(name, value))
+                : null;
+        if (signal == null && previousSignalBinding != null) {
+            if (previousSignalBinding.registration() != null) {
+                previousSignalBinding.registration().remove();
+            }
+            // revert to plain stored value (may be null)
+            put(name, get(name), false);
+        } else {
+            put(name, new SignalBinding(signal, registration, get(name)),
+                    false);
+        }
+    }
+
+    /**
+     * Applies a value coming from a signal to the property while preserving an
+     * existing binding.
+     *
+     * @param name
+     *            the property name
+     * @param value
+     *            the value to apply; <code>null</code> removes the property on
+     *            the client but keeps the binding and last-applied value as
+     *            <code>null</code>
+     */
+    protected abstract void setPropertyFromSignal(String name, Object value);
 }

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

@@ -32,15 +32,12 @@
 import tools.jackson.databind.node.BaseJsonNode;
 
 import com.vaadin.flow.dom.Element;
-import com.vaadin.flow.dom.ElementEffect;
 import com.vaadin.flow.dom.PropertyChangeEvent;
 import com.vaadin.flow.dom.PropertyChangeListener;
 import com.vaadin.flow.function.SerializablePredicate;
 import com.vaadin.flow.internal.JacksonUtils;
 import com.vaadin.flow.internal.StateNode;
 import com.vaadin.flow.shared.Registration;
-import com.vaadin.signals.BindingActiveException;
-import com.vaadin.signals.Signal;
 import com.vaadin.signals.ValueSignal;
 
 /**
@@ -120,46 +117,6 @@ public void setProperty(String name, Serializable value) {
         setProperty(name, value, true);
     }
 
-    /**
-     * Binds the given signal to the given property. <code>null</code> signal
-     * unbinds existing binding.
-     *
-     * @param owner
-     *            the element owning the property, not <code>null</code>
-     * @param name
-     *            the name of the property
-     * @param signal
-     *            the signal to bind or <code>null</code> to unbind any existing
-     *            binding
-     * @throws com.vaadin.signals.BindingActiveException
-     *             thrown when there is already an existing binding for the
-     *             given property
-     */
-    public void bindSignal(Element owner, String name, Signal<?> signal) {
-        SignalBinding previousSignalBinding;
-        if (super.get(name) instanceof SignalBinding binding) {
-            previousSignalBinding = binding;
-        } else {
-            previousSignalBinding = null;
-        }
-        if (signal != null && hasSignal(name)) {
-            throw new BindingActiveException();
-        }
-        Registration registration = signal != null
-                ? ElementEffect.bind(owner, signal,
-                        (element, value) -> setPropertyFromSignal(name, value))
-                : null;
-        if (signal == null && previousSignalBinding != null) {
-            if (previousSignalBinding.registration() != null) {
-                previousSignalBinding.registration().remove();
-            }
-            put(name, get(name), false);
-        } else {
-            put(name, new SignalBinding(signal, registration, get(name)),
-                    false);
-        }
-    }
-
     @Override
     protected Serializable get(String key) {
         Serializable value = super.get(key);
@@ -170,6 +127,7 @@ protected Serializable get(String key) {
         }
     }
 
+    @Override
     public void setPropertyFromSignal(String name, Object value) {
         assert !forbiddenProperties.contains(name)
                 : "Forbidden property name: " + name;