fix!: withStatusLabel now sets field invalid state for consistent visual feedback (#22575)

Fixes #21707

Previously, withStatusLabel() only updated the status label but did not
set the field's invalid state, resulting in inconsistent visual feedback
where fields would not show the red background indicator for validation
errors.

This fix ensures that withStatusLabel() also delegates to the binder's
handleValidationStatus() method, which properly sets/clears the field's
invalid state through handleError()/clearError(). This provides
consistent visual feedback (red background + status label) across all
validation scenarios:
- Required field validation
- Custom validator failures
- Conversion errors
- Multiple validators

Author: Artur-

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

@@ -845,10 +845,11 @@ default BindingBuilder<BEAN, TARGET> withNullRepresentation(
          * fails.
          * <p>
          * The validation state of each field is updated whenever the user
-         * modifies the value of that field.
-         * <p>
-         * This method allows to customize the way a binder displays error
-         * messages.
+         * modifies the value of that field. With this method, possible
+         * validation error message will be shown in the {@code label} provided.
+         * Additionally, the field's invalid state will be updated to provide
+         * visual feedback (e.g., red background) for fields implementing
+         * {@link com.vaadin.flow.component.HasValidation}.
          * <p>
          * This is just a shorthand for
          * {@link #withValidationStatusHandler(BindingValidationStatusHandler)}
@@ -870,6 +871,17 @@ default BindingBuilder<BEAN, TARGET> withStatusLabel(HasText label) {
                 label.setText(status.getMessage().orElse(""));
                 // Only show the label when validation has failed
                 setVisible(label, status.isError());
+
+                // Update the field's invalid state for consistent visual
+                // feedback. Delegates to the binder's error handler which sets
+                // the field invalid and applies error styling.
+                if (status.getBinding() instanceof BindingImpl) {
+                    @SuppressWarnings("unchecked")
+                    BindingImpl<BEAN, ?, TARGET> binding = (BindingImpl<BEAN, ?, TARGET>) status
+                            .getBinding();
+                    Binder<BEAN> binder = binding.getBinder();
+                    binder.handleValidationStatus(status);
+                }
             });
         }
 

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

@@ -29,6 +29,8 @@
 import com.vaadin.flow.data.binder.Binder.BindingBuilder;
 import com.vaadin.flow.data.binder.BindingValidationStatus.Status;
 import com.vaadin.flow.data.binder.testcomponents.TestLabel;
+import com.vaadin.flow.data.binder.testcomponents.TestTextField;
+import com.vaadin.flow.data.converter.StringToIntegerConverter;
 import com.vaadin.flow.tests.data.bean.Person;
 
 public class BinderValidationStatusTest
@@ -44,6 +46,7 @@ public void setUp() {
             @Override
             protected void handleError(HasValue<?, ?> field,
                     ValidationResult result) {
+                super.handleError(field, result);
                 componentErrors.put(field, result.getErrorMessage());
             }
 
@@ -127,7 +130,7 @@ public void bindingWithStatusLabel_labelIsUpdatedAccordingStatus() {
     }
 
     @Test
-    public void bindingWithStatusLabel_defaultStatusHandlerIsReplaced() {
+    public void bindingWithStatusLabel_fieldInvalidStateIsSet() {
         TestLabel label = new TestLabel();
 
         Binding<Person, String> binding = binder.forField(nameField)
@@ -142,8 +145,9 @@ public void bindingWithStatusLabel_defaultStatusHandlerIsReplaced() {
         // message
         binding.validate();
 
-        // default behavior should update component error for the nameField
-        Assert.assertNull(componentErrors.get(nameField));
+        // withStatusLabel updates both the label and the field's invalid state
+        Assert.assertEquals(EMPTY_ERROR_MESSAGE,
+                componentErrors.get(nameField));
     }
 
     @Test(expected = IllegalStateException.class)
@@ -480,4 +484,179 @@ private void assertVisible(TestLabel label, boolean visible) {
         }
     }
 
+    // Tests for issue #21707: withStatusLabel should set field invalid state
+    @Test
+    public void withStatusLabel_validationError_setsFieldInvalidAndUpdatesLabel() {
+        TestLabel label = new TestLabel();
+
+        binder.forField(nameField).withValidator(notEmpty)
+                .withStatusLabel(label)
+                .bind(Person::getFirstName, Person::setFirstName);
+
+        nameField.setValue("");
+        binder.validate();
+
+        // Both label and field invalid state should be updated
+        assertVisible(label, true);
+        Assert.assertEquals(EMPTY_ERROR_MESSAGE, label.getText());
+        Assert.assertTrue(nameField.isInvalid());
+        Assert.assertEquals(EMPTY_ERROR_MESSAGE,
+                componentErrors.get(nameField));
+    }
+
+    @Test
+    public void withStatusLabel_validValue_clearsFieldInvalidAndLabel() {
+        TestLabel label = new TestLabel();
+
+        binder.forField(nameField).withValidator(notEmpty)
+                .withStatusLabel(label)
+                .bind(Person::getFirstName, Person::setFirstName);
+
+        // First set invalid
+        nameField.setValue("");
+        binder.validate();
+        Assert.assertTrue(nameField.isInvalid());
+
+        // Then set valid
+        nameField.setValue("Valid");
+        binder.validate();
+
+        // Both label and field invalid state should be cleared
+        assertVisible(label, false);
+        Assert.assertEquals("", label.getText());
+        Assert.assertFalse(nameField.isInvalid());
+        Assert.assertNull(componentErrors.get(nameField));
+    }
+
+    @Test
+    public void withStatusLabel_customValidator_setsFieldInvalid() {
+        TestLabel label = new TestLabel();
+        String customError = "Must start with uppercase";
+
+        binder.forField(nameField)
+                .withValidator(value -> Character.isUpperCase(value.charAt(0)),
+                        customError)
+                .withStatusLabel(label)
+                .bind(Person::getFirstName, Person::setFirstName);
+
+        nameField.setValue("lowercase");
+        binder.validate();
+
+        // Field should be marked invalid with custom validator
+        Assert.assertTrue(nameField.isInvalid());
+        Assert.assertEquals(customError, componentErrors.get(nameField));
+        assertVisible(label, true);
+        Assert.assertEquals(customError, label.getText());
+    }
+
+    @Test
+    public void withStatusLabel_requiredField_setsFieldInvalid() {
+        TestLabel label = new TestLabel();
+
+        binder.forField(nameField).asRequired(EMPTY_ERROR_MESSAGE)
+                .withStatusLabel(label)
+                .bind(Person::getFirstName, Person::setFirstName);
+
+        nameField.setValue("");
+        binder.validate();
+
+        // Required field validation should set field invalid
+        Assert.assertTrue(nameField.isInvalid());
+        Assert.assertEquals(EMPTY_ERROR_MESSAGE,
+                componentErrors.get(nameField));
+        assertVisible(label, true);
+        Assert.assertEquals(EMPTY_ERROR_MESSAGE, label.getText());
+    }
+
+    @Test
+    public void withStatusLabel_conversionError_setsFieldInvalid() {
+        TestLabel label = new TestLabel();
+        TestTextField ageField = new TestTextField();
+        String conversionError = "Must be a number";
+
+        binder.forField(ageField)
+                .withConverter(new StringToIntegerConverter(conversionError))
+                .withStatusLabel(label).bind(Person::getAge, Person::setAge);
+
+        ageField.setValue("not a number");
+        binder.validate();
+
+        // Conversion error should set field invalid
+        Assert.assertTrue(ageField.isInvalid());
+        assertVisible(label, true);
+        Assert.assertEquals(conversionError, label.getText());
+    }
+
+    @Test
+    public void withStatusLabel_multipleValidators_setsFieldInvalid() {
+        TestLabel label = new TestLabel();
+        String lengthError = "Must be at least 3 characters";
+
+        binder.forField(nameField).withValidator(notEmpty)
+                .withValidator(value -> value.length() >= 3, lengthError)
+                .withStatusLabel(label)
+                .bind(Person::getFirstName, Person::setFirstName);
+
+        nameField.setValue("ab");
+        binder.validate();
+
+        // Multiple validators should still set field invalid
+        Assert.assertTrue(nameField.isInvalid());
+        Assert.assertEquals(lengthError, componentErrors.get(nameField));
+        assertVisible(label, true);
+        Assert.assertEquals(lengthError, label.getText());
+    }
+
+    @Test
+    public void withValidationStatusHandler_customHandler_fieldInvalidNotSetAutomatically() {
+        AtomicReference<BindingValidationStatus<?>> statusCapture = new AtomicReference<>();
+
+        binder.forField(nameField).withValidator(notEmpty)
+                .withValidationStatusHandler(statusCapture::set)
+                .bind(Person::getFirstName, Person::setFirstName);
+
+        nameField.setValue("");
+        binder.validate();
+
+        // Custom handler gives full control - field invalid state should NOT
+        // be set automatically
+        Assert.assertFalse(nameField.isInvalid());
+        Assert.assertNull(componentErrors.get(nameField));
+
+        // But the handler should still receive the validation status
+        Assert.assertNotNull(statusCapture.get());
+        Assert.assertEquals(Status.ERROR, statusCapture.get().getStatus());
+        Assert.assertEquals(EMPTY_ERROR_MESSAGE,
+                statusCapture.get().getMessage().get());
+    }
+
+    @Test
+    public void withValidationStatusHandler_customHandler_canManuallySetFieldInvalid() {
+        binder.forField(nameField).withValidator(notEmpty)
+                .withValidationStatusHandler(status -> {
+                    // Custom handler that manually controls field invalid state
+                    if (status.isError()) {
+                        nameField.setInvalid(true);
+                    } else {
+                        nameField.setInvalid(false);
+                    }
+                }).bind(Person::getFirstName, Person::setFirstName);
+
+        nameField.setValue("");
+        binder.validate();
+
+        // Custom handler manually set the invalid state
+        Assert.assertTrue(nameField.isInvalid());
+        // But componentErrors should still be null because we're using custom
+        // handler
+        Assert.assertNull(componentErrors.get(nameField));
+
+        // Clear the error
+        nameField.setValue("Valid");
+        binder.validate();
+
+        // Custom handler should clear the invalid state
+        Assert.assertFalse(nameField.isInvalid());
+    }
+
 }