Wrapping NumberField within CustomField ignores ValueChangeMode

[DarioViva42]

Describe the bug

Using the methods setValueChangeMode and setValueChangeTimeout do work as expected on a Numberfield. But when the NumberField is wrapped within a CustomField the event handling is suddenly always Eager. Why? What do we need to change to achieve the expected behaviour.
The same bug probably happens with other fields as well, but we just happened to notice it with the NumberField.
Is our approach to this completly wrong and this is the expected behaviour? If so, we did not find the relevant section in the docs that specifies how to mitigate this. Is there maybe a way to turn the complete CustomField lazy (so all Fields wrapped in the CustomField become lazy)?

Expected-behavior

The behaviour of the change listeners for the NumberField does not change when wrapped within a CustomField.

Reproduction

Add the following View to your Project. Then change the value of the NumberField and see that the action (printing “hello” in this example) defined in the listener is executed after 2 seconds. Changing the number with the keyboard also changes the value after 2 seconds.
But changing the value of the NumberField wrapped in a CustomField instantly triggers the event instead of after the specified timeout. But only when using the step buttons or on blur. When using the keyboard to change the number in the wrapped NumberField nothing happens at all.

Note

This example might seem a little silly, but of course it’s just for demonstrating purposes. Normally we would have multiple fields within one CustomField, just as one would expect.
We are aware that the documentation for CustomField states the following.

Custom Field is a component for wrapping multiple components as a single field.

import com.vaadin.flow.component.customfield.CustomField;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.component.textfield.NumberField;
import com.vaadin.flow.data.value.ValueChangeMode;
import com.vaadin.flow.router.Route;

@Route
public class NumberView extends VerticalLayout {
	public NumberView() {
		NumberField numberField = new NumberField();
		numberField.setLabel("NumberField");

		numberField.setStepButtonsVisible(true);
		numberField.setValueChangeMode(ValueChangeMode.LAZY);
		numberField.setValueChangeTimeout(2000);

		numberField.addValueChangeListener(e -> {
			System.out.println("hello");
		});
		add(numberField);

		CustomNumberField customNumberField = new CustomNumberField();
		customNumberField.setLabel("CustomNumberField");
		customNumberField.addValueChangeListener(e -> {
			System.out.println("hello");
		});
		add(customNumberField);
	}

	static class CustomNumberField extends CustomField<Double> {

		NumberField numberField = new NumberField();

		public CustomNumberField() {
			numberField.setStepButtonsVisible(true);
			numberField.setValueChangeMode(ValueChangeMode.LAZY);
			numberField.setValueChangeTimeout(2000);

			add(numberField);
		}

		@Override
		protected Double generateModelValue() {
			return numberField.getValue();
		}

		@Override
		protected void setPresentationValue(Double aDouble) {
			numberField.setValue(aDouble);
		}
	}
}

System Info

Vaadin Version:

• 24.7.15 with SpringBoot 3.5.11
• 24.8.17 with SpringBoot 3.5.11
• 24.9.12 with SpringBoot 3.5.11
• 25.0.6 with SpringBoot 4.0.3

OS does not matter. Browser does not matter.

[DarioViva42]

For everyone wishing a more sensible demonstration.

import com.vaadin.flow.component.Text;
import com.vaadin.flow.component.customfield.CustomField;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.component.textfield.IntegerField;
import com.vaadin.flow.data.value.ValueChangeMode;
import com.vaadin.flow.router.Route;
import org.apache.commons.lang3.Range;

@Route
public class NumberView extends VerticalLayout {
	public NumberView() {
		IntegerField normalField = new IntegerField();
		normalField.setStepButtonsVisible(true);
		normalField.setValueChangeMode(ValueChangeMode.LAZY);
		normalField.setValueChangeTimeout(2000);
		normalField.setLabel("NormalField");

		normalField.addValueChangeListener(e -> {
			System.out.println("hello");
		});
		add(normalField);

		IntegerRangeField customField = new IntegerRangeField();
		customField.setLabel("CustomField");
		customField.addValueChangeListener(e -> {
			System.out.println("hello");
		});
		add(customField);
	}

	static class IntegerRangeField extends CustomField<Range<Integer>> {

		private final IntegerField from;
		private final IntegerField to;

		public IntegerRangeField() {
			from = new IntegerField();
			from.setStepButtonsVisible(true);
			from.setValueChangeMode(ValueChangeMode.LAZY);
			from.setValueChangeTimeout(2000);
			from.setPlaceholder("from");

			to = new IntegerField();
			to.setStepButtonsVisible(true);
			to.setValueChangeMode(ValueChangeMode.LAZY);
			to.setValueChangeTimeout(2000);
			to.setPlaceholder("to");

			add(from, new Text(" – "), to);
		}

		@Override
		protected Range<Integer> generateModelValue() {
			return Range.of(from.getOptionalValue().orElse(Integer.MIN_VALUE), to.getOptionalValue().orElse(Integer.MAX_VALUE));
		}

		@Override
		protected void setPresentationValue(Range<Integer> range) {
			from.setValue(range.getMinimum());
			to.setValue(range.getMaximum());
		}
	}
}

[ZheSun88]

@DarioViva42 Thanks for the issue, I will transfer it to flow-component repo and our experts will investigate the cause and find a solution for that.

[jcgueriaud1]

By default the CustomField is automatically updating the value on change. Which works well if you're using the default TextChangeMode of the NumberField but that doesn't work in some cases, for example in your case.
You can disable it: https://github.com/vaadin/flow-components/blob/main/vaadin-custom-field-flow-parent/vaadin-custom-field-flow/src/main/java/com/vaadin/flow/component/customfield/CustomField.java#L90

Once it's disabled you have to manually trigger the update using updateValue().

In your case, I think you need to trigger it on the valuechangelistener of your NumberField.

You can read more here (it was done before the fix I mentioned, so now you can disable it): https://vaadin.com/blog/creating-well-behaving-form-fields-using-customfield

It's unfortunately not well documented.

[jcgueriaud1]

That should work as expected.

public class NumberView extends VerticalLayout {
	public NumberView() {
		IntegerField normalField = new IntegerField();
		normalField.setStepButtonsVisible(true);
		normalField.setValueChangeMode(ValueChangeMode.LAZY);
		normalField.setValueChangeTimeout(2000);
		normalField.setLabel("NormalField");

		normalField.addValueChangeListener(e -> {
			System.out.println(e.getValue());
		});
		add(normalField);

		IntegerRangeField customField = new IntegerRangeField();
		customField.setLabel("CustomField");
		customField.addValueChangeListener(e -> {
			System.out.println(e.getValue());
		});
		add(customField);
	}

	static class IntegerRangeField extends CustomField<Range<Integer>> {

		private final IntegerField from;
		private final IntegerField to;

		public IntegerRangeField() {
			super(null, true);
			from = new IntegerField();
			from.setStepButtonsVisible(true);
			from.setValueChangeMode(ValueChangeMode.LAZY);
			from.setValueChangeTimeout(2000);
			from.setPlaceholder("from");
			from.addValueChangeListener(e -> updateValue());

			to = new IntegerField();
			to.setStepButtonsVisible(true);
			to.setValueChangeMode(ValueChangeMode.LAZY);
			to.setValueChangeTimeout(2000);
			to.setPlaceholder("to");
			to.addValueChangeListener(e -> updateValue());

			add(from, new Text(" – "), to);
		}

		@Override
		protected Range<Integer> generateModelValue() {
			return Range.of(from.getOptionalValue().orElse(Integer.MIN_VALUE), to.getOptionalValue().orElse(Integer.MAX_VALUE));
		}

		@Override
		protected void setPresentationValue(Range<Integer> range) {
			from.setValue(range.getMinimum());
			to.setValue(range.getMaximum());
		}
	}
}

[yuriy-fix]

The documentation should be updated to reflect the possibility to manually updateValue.
The CustomField itself is not utilising the AbstractField value handling, so it can also be considered as a bug.

[DarioViva42]

@jcgueriaud1 this is almost perfect. but what if someone happens to update the value of multiple fields within the CustomField within the specified timeout. then one would expect that a single value change event is triggered after the last user–input. but with this solution it happens multiple times. Also, this manual solution is nice to have of course, but IMHO its complexity is not needed in such a use case. A clean API for setting the value change mode (and timeout) on the CustomField level would surely be of great use.

[jcgueriaud1]

A clean API for setting the value change mode (and timeout) on the CustomField level would surely be of great use.

If you're using a timeout on a NumberField, currently the CustomField will notice it at the end of the timeout. That won't work well with a value change mode on the CustomField.
I don't know if you can have a good API for this. (There are a lot of cases and I don't think they could work together).

If you want only one trigger after 2 seconds you might need to add some code on the server side to deal with the timeout. (and switch the inner fields to eager). For now, it's mostly a manual work depending on your need. (At least the change event won't be triggered on the CustomField).