feat: add signal binding to element text (#22406) (#22543)

Implements signal binding to element text.

Fixes #22406

Author: tepi

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

@@ -49,13 +49,16 @@
 import com.vaadin.flow.internal.JacksonUtils;
 import com.vaadin.flow.internal.JavaScriptSemantics;
 import com.vaadin.flow.internal.StateNode;
+import com.vaadin.flow.internal.nodefeature.TextBindingFeature;
 import com.vaadin.flow.internal.nodefeature.VirtualChildrenList;
 import com.vaadin.flow.server.AbstractStreamResource;
 import com.vaadin.flow.server.Command;
 import com.vaadin.flow.server.StreamResource;
 import com.vaadin.flow.server.StreamResourceRegistry;
 import com.vaadin.flow.server.streams.ElementRequestHandler;
 import com.vaadin.flow.shared.Registration;
+import com.vaadin.signals.BindingActiveException;
+import com.vaadin.signals.Signal;
 
 /**
  * Represents an element in the DOM.
@@ -1172,35 +1175,91 @@ public boolean isTextNode() {
      *            the text content to set, <code>null</code> is interpreted as
      *            an empty string
      * @return this element
+     * @throws BindingActiveException
+     *             if a binding has been set on the text content of this element
      */
     public Element setText(String textContent) {
+        TextBindingFeature feature = getNode()
+                .getFeature(TextBindingFeature.class);
+        if (feature.hasBinding()) {
+            throw new BindingActiveException(
+                    "setText is not allowed while a binding for text exists.");
+        }
+
         if (textContent == null) {
             // Browsers work this way
             textContent = "";
         }
+        setTextContent(textContent);
+
+        return this;
+    }
 
+    private void setTextContent(String textContent) {
         if (isTextNode()) {
             getStateProvider().setTextContent(getNode(), textContent);
         } else {
             if (textContent.isEmpty()) {
                 removeAllChildren();
             } else {
-                setTextContent(textContent);
+                Element child;
+                if (getChildCount() == 1 && getChild(0).isTextNode()) {
+                    child = getChild(0).setText(textContent);
+                } else {
+                    child = createText(textContent);
+                }
+                removeAllChildren();
+                appendChild(child);
             }
         }
-
-        return this;
     }
 
-    private void setTextContent(String textContent) {
-        Element child;
-        if (getChildCount() == 1 && getChild(0).isTextNode()) {
-            child = getChild(0).setText(textContent);
+    /**
+     * Binds a {@link Signal}'s value to the text content of this element and
+     * creates a Signal effect function executing the setter whenever the signal
+     * value changes. <code>null</code> signal unbinds the existing binding.
+     * <p>
+     * Text content is synchronized with the signal value whenever the element
+     * is attached. When the element is detached, signal value changes have no
+     * effect.
+     * <p>
+     * While a Signal is bound to an attribute, any attempt to set the text
+     * content manually throws
+     * {@link com.vaadin.signals.BindingActiveException}. Same happens when
+     * trying to bind a new Signal while one is already bound.
+     * <p>
+     * Example of usage:
+     *
+     * <pre>
+     * ValueSignal&lt;String&gt; signal = new ValueSignal&lt;&gt;("");
+     * Element element = new Element("span");
+     * getElement().appendChild(element);
+     * element.bindText(signal);
+     * signal.value("text"); // The element text content is set to "text"
+     * </pre>
+     *
+     * @param signal
+     *            the signal to bind or <code>null</code> to unbind any existing
+     *            binding
+     * @throws BindingActiveException
+     *             thrown when there is already an existing binding
+     * @see #setText(String)
+     */
+    public void bindText(Signal<String> signal) {
+        TextBindingFeature feature = getNode()
+                .getFeature(TextBindingFeature.class);
+
+        if (signal == null) {
+            feature.removeBinding();
         } else {
-            child = createText(textContent);
+            if (feature.hasBinding() && getNode().isAttached()) {
+                throw new BindingActiveException();
+            }
+
+            Registration registration = ElementEffect.bind(this, signal,
+                    (element, value) -> setTextContent(value));
+            feature.setBinding(registration, signal);
         }
-        removeAllChildren();
-        appendChild(child);
     }
 
     /**

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

@@ -53,6 +53,7 @@
 import com.vaadin.flow.internal.nodefeature.PolymerServerEventHandlers;
 import com.vaadin.flow.internal.nodefeature.ReturnChannelMap;
 import com.vaadin.flow.internal.nodefeature.ShadowRootData;
+import com.vaadin.flow.internal.nodefeature.TextBindingFeature;
 import com.vaadin.flow.internal.nodefeature.VirtualChildrenList;
 import com.vaadin.flow.server.AbstractStreamResource;
 import com.vaadin.flow.shared.Registration;
@@ -85,7 +86,7 @@ public class BasicElementStateProvider extends AbstractNodeStateProvider {
             PolymerServerEventHandlers.class, ClientCallableHandlers.class,
             PolymerEventListenerMap.class, ShadowRootData.class,
             AttachExistingElementFeature.class, VirtualChildrenList.class,
-            ReturnChannelMap.class, InertData.class };
+            ReturnChannelMap.class, InertData.class, TextBindingFeature.class };
 
     private BasicElementStateProvider() {
         // Not meant to be sub classed and only once instance should ever exist

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

@@ -16,12 +16,13 @@
 package com.vaadin.flow.dom.impl;
 
 import java.io.ObjectStreamException;
-import java.util.Collections;
+import java.util.List;
 
 import com.vaadin.flow.dom.Node;
 import com.vaadin.flow.internal.StateNode;
 import com.vaadin.flow.internal.nodefeature.ComponentMapping;
 import com.vaadin.flow.internal.nodefeature.ReturnChannelMap;
+import com.vaadin.flow.internal.nodefeature.TextBindingFeature;
 import com.vaadin.flow.internal.nodefeature.TextNodeMap;
 
 /**
@@ -52,7 +53,7 @@ public static StateNode createStateNode(String text) {
         assert text != null;
 
         StateNode node = new StateNode(
-                Collections.singletonList(TextNodeMap.class),
+                List.of(TextNodeMap.class, TextBindingFeature.class),
                 ComponentMapping.class, ReturnChannelMap.class);
         node.getFeature(TextNodeMap.class).setText(text);
 

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

@@ -66,6 +66,8 @@ private <T extends NodeFeature> NodeFeatureData(
                 NodeFeatures.ELEMENT_DATA);
         registerFeature(TextNodeMap.class, TextNodeMap::new,
                 NodeFeatures.TEXT_NODE);
+        registerFeature(TextBindingFeature.class, TextBindingFeature::new,
+                NodeFeatures.TEXT_BINDING);
         registerFeature(ModelList.class, ModelList::new,
                 NodeFeatures.TEMPLATE_MODELLIST);
         registerFeature(BasicTypeValue.class, BasicTypeValue::new,

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

@@ -142,6 +142,11 @@ public final class NodeFeatures {
      */
     public static final int INERT_DATA = 26;
 
+    /**
+     * Id for {@link TextBindingFeature}.
+     */
+    public static final int TEXT_BINDING = 27;
+
     private NodeFeatures() {
         // Only static
     }

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

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2000-2025 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.internal.nodefeature;
+
+import com.vaadin.flow.internal.StateNode;
+import com.vaadin.flow.shared.Registration;
+import com.vaadin.signals.Signal;
+
+/**
+ * Node feature for binding a {@link Signal} to the text content of a node.
+ * <p>
+ * For internal use only. May be renamed or removed in a future release.
+ */
+public class TextBindingFeature extends ServerSideFeature {
+    /**
+     * Creates a TextBindingFeature for the given node.
+     *
+     * @param node
+     *            the node which supports the feature
+     */
+    public TextBindingFeature(StateNode node) {
+        super(node);
+    }
+
+    private Registration registration;
+    private Signal<String> textSignal;
+
+    public void setBinding(Registration registration,
+            Signal<String> textSignal) {
+        this.registration = registration;
+        this.textSignal = textSignal;
+    }
+
+    public boolean hasBinding() {
+        return textSignal != null && registration != null;
+    }
+
+    public void removeBinding() {
+        if (registration != null) {
+            registration.remove();
+        }
+        registration = null;
+        textSignal = null;
+    }
+}