feat: add signal binding for attribute in Element (#22525)

Introduces bindAttribute(String attribute, Signal<String> signal) method in Element to bind a Signal to attribute.

fixes: #22407

Author: tltv

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

@@ -244,6 +244,56 @@ public String getTag() {
         return getStateProvider().getTag(getNode());
     }
 
+    /**
+     * Binds a {@link Signal}'s value to a given attribute and keeps the
+     * attribute value synchronized with the signal value while the element is
+     * in attached state. When the element is in detached state, signal value
+     * changes have no effect. <code>null</code> signal unbinds existing
+     * binding.
+     * <p>
+     * Same rules applies for the attribute name and value from the bound Signal
+     * as in {@link #setAttribute(String, String)}.
+     * <p>
+     * While a Signal is bound to an attribute, any attempt to set or remove
+     * attribute value manually throws
+     * {@link com.vaadin.signals.BindingActiveException}. Same happens when
+     * trying to bind a new Signal while one is already bound.
+     * <p>
+     * Binding style or class attribute to a Signal is not supported.
+     * <p>
+     * Example of usage:
+     *
+     * <pre>
+     * ValueSignal&lt;String&gt; signal = new ValueSignal&lt;&gt;("");
+     * Element element = new Element("span");
+     * getElement().appendChild(element);
+     * element.bindAttribute("mol", signal);
+     * signal.value("42"); // The element now has attribute mol="42"
+     * </pre>
+     *
+     * @param attribute
+     *            the name of the attribute
+     * @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
+     * @see #setAttribute(String, String)
+     */
+    public void bindAttribute(String attribute, Signal<String> signal) {
+        String validAttribute = validateAttribute(attribute);
+
+        Optional<CustomAttribute> customAttribute = CustomAttribute
+                .get(validAttribute);
+        if (customAttribute.isPresent()) {
+            throw new UnsupportedOperationException(
+                    "Binding style or class attribute to a Signal is not supported.");
+        } else {
+            getStateProvider().bindAttributeSignal(this, validAttribute,
+                    signal);
+        }
+    }
+
     /**
      * Sets the given attribute to the given value.
      * <p>
@@ -272,7 +322,10 @@ public String getTag() {
      * @return this element
      */
     public Element setAttribute(String attribute, String value) {
-        String lowerCaseAttribute = validateAttribute(attribute, value);
+        if (value == null) {
+            throw new IllegalArgumentException("Value cannot be null");
+        }
+        String lowerCaseAttribute = validateAttribute(attribute);
 
         Optional<CustomAttribute> customAttribute = CustomAttribute
                 .get(lowerCaseAttribute);
@@ -334,7 +387,10 @@ public Element setAttribute(String attribute, boolean value) {
      */
     public Element setAttribute(String attribute,
             AbstractStreamResource resource) {
-        String lowerCaseAttribute = validateAttribute(attribute, resource);
+        String lowerCaseAttribute = validateAttribute(attribute);
+        if (resource == null) {
+            throw new IllegalArgumentException("Value cannot be null");
+        }
 
         Optional<CustomAttribute> customAttribute = CustomAttribute
                 .get(lowerCaseAttribute);
@@ -1367,7 +1423,7 @@ public Optional<Component> getComponent() {
         return getStateProvider().getComponent(getNode());
     }
 
-    private String validateAttribute(String attribute, Object value) {
+    private String validateAttribute(String attribute) {
         if (attribute == null) {
             throw new IllegalArgumentException(ATTRIBUTE_NAME_CANNOT_BE_NULL);
         }
@@ -1378,10 +1434,6 @@ private String validateAttribute(String attribute, Object value) {
                     "Attribute \"%s\" is not a valid attribute name",
                     lowerCaseAttribute));
         }
-
-        if (value == null) {
-            throw new IllegalArgumentException("Value cannot be null");
-        }
         return lowerCaseAttribute;
     }
 

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

@@ -25,6 +25,7 @@
 import com.vaadin.flow.server.AbstractStreamResource;
 import com.vaadin.flow.server.StreamResource;
 import com.vaadin.flow.shared.Registration;
+import com.vaadin.signals.Signal;
 
 /**
  * Handles storing and retrieval of the state information for an element using a
@@ -66,6 +67,22 @@ public interface ElementStateProvider extends Serializable {
      */
     void setAttribute(StateNode node, String attribute, String value);
 
+    /**
+     * Binds the given signal to the given attribute. <code>null</code> signal
+     * unbinds existing binding.
+     *
+     * @param owner
+     *            the owner element for which the signal is bound, not
+     *            <code>null</code>
+     * @param attribute
+     *            the name of the attribute
+     * @param signal
+     *            the signal to bind or <code>null</code> to unbind any existing
+     *            binding
+     */
+    void bindAttributeSignal(Element owner, String attribute,
+            Signal<String> signal);
+
     /**
      * Sets the given attribute to the given {@link StreamResource} value.
      *

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

@@ -32,6 +32,7 @@
 import com.vaadin.flow.internal.StateNode;
 import com.vaadin.flow.server.AbstractStreamResource;
 import com.vaadin.flow.shared.Registration;
+import com.vaadin.signals.Signal;
 
 /**
  * Abstract element state provider for text nodes. Operations that are not
@@ -60,6 +61,12 @@ public void setAttribute(StateNode node, String attribute, String value) {
         throw new UnsupportedOperationException();
     }
 
+    @Override
+    public void bindAttributeSignal(Element owner, String attribute,
+            Signal<String> signal) {
+        throw new UnsupportedOperationException();
+    }
+
     @Override
     public String getAttribute(StateNode node, String attribute) {
         return null;

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

@@ -57,6 +57,7 @@
 import com.vaadin.flow.internal.nodefeature.VirtualChildrenList;
 import com.vaadin.flow.server.AbstractStreamResource;
 import com.vaadin.flow.shared.Registration;
+import com.vaadin.signals.Signal;
 
 /**
  * Implementation which stores data for basic elements, i.e. elements which are
@@ -190,7 +191,16 @@ public void setAttribute(StateNode node, String attribute, String value) {
         assert attribute.equals(attribute.toLowerCase(Locale.ENGLISH));
 
         getAttributeFeature(node).set(attribute, value);
+    }
+
+    @Override
+    public void bindAttributeSignal(Element owner, String attribute,
+            Signal<String> signal) {
+        assert attribute != null;
+        assert attribute.equals(attribute.toLowerCase(Locale.ENGLISH));
 
+        getAttributeFeature(owner.getNode()).bindSignal(owner, attribute,
+                signal);
     }
 
     @Override

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

@@ -22,6 +22,7 @@
 import com.vaadin.flow.dom.ClassList;
 import com.vaadin.flow.dom.DomEventListener;
 import com.vaadin.flow.dom.DomListenerRegistration;
+import com.vaadin.flow.dom.Element;
 import com.vaadin.flow.dom.Node;
 import com.vaadin.flow.dom.NodeVisitor;
 import com.vaadin.flow.dom.PropertyChangeListener;
@@ -37,6 +38,7 @@
 import com.vaadin.flow.internal.nodefeature.VirtualChildrenList;
 import com.vaadin.flow.server.AbstractStreamResource;
 import com.vaadin.flow.shared.Registration;
+import com.vaadin.signals.Signal;
 
 /**
  * Implementation which handles shadow root nodes.
@@ -95,6 +97,12 @@ public void setAttribute(StateNode node, String attribute, String value) {
         throw new UnsupportedOperationException();
     }
 
+    @Override
+    public void bindAttributeSignal(Element owner, String attribute,
+            Signal<String> signal) {
+        throw new UnsupportedOperationException();
+    }
+
     @Override
     public void setAttribute(StateNode node, String attribute,
             AbstractStreamResource resource) {

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

@@ -25,6 +25,8 @@
 import tools.jackson.databind.JsonNode;
 import tools.jackson.databind.node.ObjectNode;
 
+import com.vaadin.flow.dom.Element;
+import com.vaadin.flow.dom.ElementEffect;
 import com.vaadin.flow.internal.JacksonUtils;
 import com.vaadin.flow.internal.NodeOwner;
 import com.vaadin.flow.internal.StateNode;
@@ -36,6 +38,8 @@
 import com.vaadin.flow.server.StreamResourceRegistry;
 import com.vaadin.flow.server.VaadinSession;
 import com.vaadin.flow.shared.Registration;
+import com.vaadin.signals.BindingActiveException;
+import com.vaadin.signals.Signal;
 
 /**
  * Map for element attribute values.
@@ -51,6 +55,10 @@ public class ElementAttributeMap extends NodeMap {
 
     private Map<String, Registration> pendingRegistrations;
 
+    private Map<String, Signal<String>> attributeToSignalCache;
+
+    private Map<Signal<String>, Registration> attributeSignalToRegistrationCache;
+
     /**
      * Creates a new element attribute map for the given node.
      *
@@ -70,9 +78,47 @@ public ElementAttributeMap(StateNode node) {
      *            the value
      */
     public void set(String attribute, String value) {
+        if (hasSignal(attribute)) {
+            throw new BindingActiveException(
+                    "setAttribute is not allowed while a binding for the given attribute exists.");
+        }
         doSet(attribute, value);
     }
 
+    /**
+     * Binds the given signal to the given attribute. <code>null</code> signal
+     * unbinds existing binding.
+     *
+     * @param owner
+     *            the element owning the attribute, not <code>null</code>
+     * @param attribute
+     *            the name of the attribute
+     * @param signal
+     *            the signal to bind or <code>null</code> to unbind any existing
+     *            binding
+     */
+    public void bindSignal(Element owner, String attribute,
+            Signal<String> signal) {
+        ensureSignalCache();
+        var previousSignal = attributeToSignalCache.get(attribute);
+        if (signal != null && previousSignal != null) {
+            throw new BindingActiveException();
+        }
+
+        Registration registration = signal != null ? ElementEffect.bind(owner,
+                signal, (element, value) -> doSet(attribute, value)) : null;
+        if (registration != null) {
+            attributeSignalToRegistrationCache.put(signal, registration);
+        }
+        if (signal == null && attributeSignalToRegistrationCache
+                .containsKey(previousSignal)) {
+            attributeSignalToRegistrationCache.remove(previousSignal).remove();
+            attributeToSignalCache.remove(attribute);
+        } else {
+            attributeToSignalCache.put(attribute, signal);
+        }
+    }
+
     /**
      * Checks whether an attribute with the given name has been set.
      *
@@ -85,6 +131,11 @@ public boolean has(String attribute) {
         return contains(attribute);
     }
 
+    private boolean hasSignal(String attribute) {
+        return attributeToSignalCache != null
+                && attributeToSignalCache.get(attribute) != null;
+    }
+
     /**
      * Removes the named attribute.
      *
@@ -93,6 +144,10 @@ public boolean has(String attribute) {
      */
     @Override
     public Serializable remove(String attribute) {
+        if (hasSignal(attribute)) {
+            throw new BindingActiveException(
+                    "removeAttribute is not allowed while a binding for the given attribute exists.");
+        }
         unregisterResource(attribute);
         return super.remove(attribute);
     }
@@ -247,7 +302,11 @@ public void execute() {
 
     private void doSet(String attribute, Serializable value) {
         unregisterResource(attribute);
-        put(attribute, value);
+        if (value == null) {
+            super.remove(attribute);
+        } else {
+            put(attribute, value);
+        }
     }
 
     private void unsetResource(String attribute) {
@@ -267,4 +326,12 @@ private VaadinSession getSession() {
         return ((StateTree) owner).getUI().getSession();
     }
 
+    private void ensureSignalCache() {
+        if (attributeToSignalCache == null) {
+            attributeToSignalCache = new HashMap<>();
+        }
+        if (attributeSignalToRegistrationCache == null) {
+            attributeSignalToRegistrationCache = new HashMap<>();
+        }
+    }
 }