Document value change modes for supported components

articles/components/_input-field-common-features.adoc

@@ -272,3 +272,22 @@ The following style variants can be applied:
 // tag::styles-end[]
 |===
 // end::styles-end[]
+
+
+// tag::value-change-modes[]
+== Value Change Modes [badge-flow]#Flow#
+
+With the Flow Java API, you can define when client-side value changes are synchronized to the server. The [classname]`ValueChangeMode` enum provides the following modes:
+
+[options="header", cols="1,4,1"]
+|===
+|Mode |Synchronization timing |Custom timeout interval
+|`EAGER`|Synchronizes the value whenever it changes on the client side, for example on each keystroke.|No
+|`LAZY`|Synchronizes the value after a defined interval has passed without further changes. If another change occurs before the interval ends, the timeout is restarted.|Yes
+|`TIMEOUT`|Synchronizes the value at defined intervals while the value continues to change.|Yes
+|`ON_BLUR`|Synchronizes the value on the `blur` event, when the component loses focus.|No
+|`ON_CHANGE` (default)|Synchronizes the value on the `change` event, when the component value is committed.|No
+|===
+
+For the modes that support a custom timeout interval, you can change the interval with the [methodname]`setValueChangeTimeout()` method. The default interval is 400 milliseconds.
+// end::value-change-modes[]

articles/components/email-field/index.adoc

@@ -152,4 +152,19 @@ include::{root}/frontend/demo/component/emailfield/react/email-field-readonly-an
 endif::[]
 --
 
+include::{articles}/components/_input-field-common-features.adoc[tags=value-change-modes]
+
+[.example]
+--
+[source,typescript]
+----
+include::{root}/frontend/demo/component/emailfield/email-field-value-change-mode.ts[preimport,hidden]
+----
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/emailfield/EmailFieldValueChangeMode.java[render,tags=snippet,indent=0,group=Flow]
+----
+--
+
 [discussion-id]`CC0AAD7F-3E1C-4A8E-A331-52F2AEDDD907`

articles/components/number-field/index.adoc

@@ -273,6 +273,21 @@ include::{root}/frontend/demo/component/numberfield/react/number-field-readonly-
 endif::[]
 --
 
+include::{articles}/components/_input-field-common-features.adoc[tags=value-change-modes]
+
+[.example]
+--
+[source,typescript]
+----
+include::{root}/frontend/demo/component/numberfield/number-field-value-change-mode.ts[preimport,hidden]
+----
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/numberfield/NumberFieldValueChangeMode.java[render,tags=snippet,indent=0,group=Flow]
+----
+--
+
 
 == Best Practices
 

articles/components/password-field/index.adoc

@@ -165,6 +165,20 @@ include::{root}/frontend/demo/component/passwordfield/react/password-field-reado
 endif::[]
 --
 
+include::{articles}/components/_input-field-common-features.adoc[tags=value-change-modes]
+
+[.example]
+--
+[source,typescript]
+----
+include::{root}/frontend/demo/component/passwordfield/password-field-value-change-mode.ts[preimport,hidden]
+----
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/passwordfield/PasswordFieldValueChangeMode.java[render,tags=snippet,indent=0,group=Flow]
+----
+--
 
 == Best Practices
 

articles/components/rich-text-editor/index.adoc

@@ -279,6 +279,21 @@ include::{root}/frontend/demo/component/richtexteditor/react/rich-text-editor-mi
 endif::[]
 --
 
+include::{articles}/components/_input-field-common-features.adoc[tags=value-change-modes]
+
+[.example]
+--
+[source,typescript]
+----
+include::{root}/frontend/demo/component/richtexteditor/rich-text-editor-value-change-mode.ts[preimport,hidden]
+----
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/richtexteditor/RichTextEditorValueChangeMode.java[render,tags=snippet,indent=0,group=Flow]
+----
+--
+
 == Toolbar Actions
 
 

articles/components/slider/index.adoc

@@ -278,6 +278,20 @@ include::{root}/frontend/demo/component/slider/react/range-slider-custom-validat
 endif::[]
 --
 
+include::{articles}/components/_input-field-common-features.adoc[tags=value-change-modes]
+
+[.example]
+--
+[source,typescript]
+----
+include::{root}/frontend/demo/component/slider/slider-value-change-mode.ts[preimport,hidden]
+----
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/slider/SliderValueChangeMode.java[render,tags=snippet,indent=0,group=Flow]
+----
+--
 
 == Best Practices
 

articles/components/text-area/index.adoc

@@ -257,6 +257,21 @@ include::{root}/frontend/demo/component/textarea/react/text-area-helper.tsx[rend
 endif::[]
 --
 
+include::{articles}/components/_input-field-common-features.adoc[tags=value-change-modes]
+
+[.example]
+--
+[source,typescript]
+----
+include::{root}/frontend/demo/component/textarea/text-area-value-change-mode.ts[preimport,hidden]
+----
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/textarea/TextAreaValueChangeMode.java[render,tags=snippet,indent=0,group=Flow]
+----
+--
+
 == Related Components
 
 [cols="1,2"]

articles/components/text-field/index.adoc

@@ -155,7 +155,20 @@ kbd:[Tab]|Cursor at the end of the input value.
 kbd:[Shift+Tab]|Contents selectedfootnote:[Consequent keyboard navigation results in the contents being selected until the selection is changed, by either arrow navigation or mouse click.]
 |===
 
+include::{articles}/components/_input-field-common-features.adoc[tags=value-change-modes]
 
+[.example]
+--
+[source,typescript]
+----
+include::{root}/frontend/demo/component/textfield/text-field-value-change-mode.ts[preimport,hidden]
+----
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/textfield/TextFieldValueChangeMode.java[render,tags=snippet,indent=0,group=Flow]
+----
+--
 
 == Related Components
 

frontend/demo/component/emailfield/email-field-value-change-mode.ts

@@ -0,0 +1,7 @@
+import 'Frontend/demo/init';
+import '@vaadin/email-field';
+import '@vaadin/select';
+import '@vaadin/horizontal-layout';
+import '@vaadin/vertical-layout';
+
+// This file only has the required imports for the Java-only example

frontend/demo/component/numberfield/number-field-value-change-mode.ts

@@ -0,0 +1,7 @@
+import 'Frontend/demo/init';
+import '@vaadin/number-field';
+import '@vaadin/select';
+import '@vaadin/horizontal-layout';
+import '@vaadin/vertical-layout';
+
+// This file only has the required imports for the Java-only example

frontend/demo/component/passwordfield/password-field-value-change-mode.ts

@@ -0,0 +1,7 @@
+import 'Frontend/demo/init';
+import '@vaadin/password-field';
+import '@vaadin/select';
+import '@vaadin/horizontal-layout';
+import '@vaadin/vertical-layout';
+
+// This file only has the required imports for the Java-only example

frontend/demo/component/richtexteditor/rich-text-editor-value-change-mode.ts

@@ -0,0 +1,7 @@
+import 'Frontend/demo/init';
+import '@vaadin/rich-text-editor';
+import '@vaadin/select';
+import '@vaadin/horizontal-layout';
+import '@vaadin/vertical-layout';
+
+// This file only has the required imports for the Java-only example

frontend/demo/component/slider/slider-value-change-mode.ts

@@ -0,0 +1,7 @@
+import 'Frontend/demo/init';
+import '@vaadin/slider';
+import '@vaadin/select';
+import '@vaadin/horizontal-layout';
+import '@vaadin/vertical-layout';
+
+// This file only has the required imports for the Java-only example

frontend/demo/component/textarea/text-area-value-change-mode.ts

@@ -0,0 +1,7 @@
+import 'Frontend/demo/init';
+import '@vaadin/text-area';
+import '@vaadin/select';
+import '@vaadin/horizontal-layout';
+import '@vaadin/vertical-layout';
+
+// This file only has the required imports for the Java-only example

frontend/demo/component/textfield/text-field-value-change-mode.ts

@@ -0,0 +1,7 @@
+import 'Frontend/demo/init';
+import '@vaadin/text-field';
+import '@vaadin/select';
+import '@vaadin/horizontal-layout';
+import '@vaadin/vertical-layout';
+
+// This file only has the required imports for the Java-only example

src/main/java/com/vaadin/demo/component/Constants.java

@@ -0,0 +1,16 @@
+package com.vaadin.demo.component;
+
+import com.vaadin.flow.data.value.ValueChangeMode;
+
+import java.util.List;
+
+public class Constants {
+    private Constants() {
+
+    }
+
+    public static final List<ValueChangeMode> valueChangeModes = List.of(
+            ValueChangeMode.EAGER, ValueChangeMode.LAZY,
+            ValueChangeMode.TIMEOUT, ValueChangeMode.ON_BLUR,
+            ValueChangeMode.ON_CHANGE);
+}

src/main/java/com/vaadin/demo/component/emailfield/EmailFieldValueChangeMode.java

@@ -0,0 +1,46 @@
+package com.vaadin.demo.component.emailfield;
+
+import com.vaadin.demo.DemoExporter;
+import com.vaadin.flow.component.html.Span;
+import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
+import com.vaadin.flow.component.orderedlayout.VerticalLayout;
+import com.vaadin.flow.component.select.Select;
+import com.vaadin.flow.component.textfield.EmailField;
+import com.vaadin.flow.data.value.ValueChangeMode;
+import com.vaadin.flow.router.Route;
+
+import static com.vaadin.demo.component.Constants.valueChangeModes;
+
+@Route("email-field-value-change-mode")
+public class EmailFieldValueChangeMode extends VerticalLayout {
+
+    public EmailFieldValueChangeMode() {
+        setPadding(false);
+        // tag::snippet[]
+        var emailField = new EmailField("Email Field");
+        var modeSelector = new Select<>("Value Change Mode", valueChangeModes);
+        modeSelector.setValue(emailField.getValueChangeMode());
+        modeSelector.addValueChangeListener(e -> {
+            emailField.clear();
+            emailField.setValueChangeMode(e.getValue());
+        });
+        var serverSideContent = new Span();
+        emailField.addValueChangeListener(
+                e -> serverSideContent.setText(e.getValue()));
+        // end::snippet[]
+
+        modeSelector.setItemLabelGenerator(ValueChangeMode::name);
+
+        var horizontalLayout = new HorizontalLayout(emailField, modeSelector);
+        horizontalLayout.setAlignItems(Alignment.BASELINE);
+
+        var serverSideLayout = new HorizontalLayout(new Span("Server side:"),
+                serverSideContent);
+
+        add(horizontalLayout, serverSideLayout);
+    }
+
+    public static class Exporter
+            extends DemoExporter<EmailFieldValueChangeMode> { // hidden-source-line
+    } // hidden-source-line
+}

src/main/java/com/vaadin/demo/component/numberfield/NumberFieldValueChangeMode.java

@@ -0,0 +1,46 @@
+package com.vaadin.demo.component.numberfield;
+
+import com.vaadin.demo.DemoExporter;
+import com.vaadin.flow.component.html.Span;
+import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
+import com.vaadin.flow.component.orderedlayout.VerticalLayout;
+import com.vaadin.flow.component.select.Select;
+import com.vaadin.flow.component.textfield.NumberField;
+import com.vaadin.flow.data.value.ValueChangeMode;
+import com.vaadin.flow.router.Route;
+
+import static com.vaadin.demo.component.Constants.valueChangeModes;
+
+@Route("number-field-value-change-mode")
+public class NumberFieldValueChangeMode extends VerticalLayout {
+
+    public NumberFieldValueChangeMode() {
+        setPadding(false);
+        // tag::snippet[]
+        var numberField = new NumberField("Number Field");
+        var modeSelector = new Select<>("Value Change Mode", valueChangeModes);
+        modeSelector.setValue(numberField.getValueChangeMode());
+        modeSelector.addValueChangeListener(e -> {
+            numberField.clear();
+            numberField.setValueChangeMode(e.getValue());
+        });
+        var serverSideContent = new Span();
+        numberField.addValueChangeListener(e -> serverSideContent
+                .setText(e.getValue() == null ? "" : e.getValue().toString()));
+        // end::snippet[]
+
+        modeSelector.setItemLabelGenerator(ValueChangeMode::name);
+
+        var horizontalLayout = new HorizontalLayout(numberField, modeSelector);
+        horizontalLayout.setAlignItems(Alignment.BASELINE);
+
+        var serverSideLayout = new HorizontalLayout(new Span("Server side:"),
+                serverSideContent);
+
+        add(horizontalLayout, serverSideLayout);
+    }
+
+    public static class Exporter
+            extends DemoExporter<NumberFieldValueChangeMode> { // hidden-source-line
+    } // hidden-source-line
+}

src/main/java/com/vaadin/demo/component/passwordfield/PasswordFieldValueChangeMode.java

@@ -0,0 +1,48 @@
+package com.vaadin.demo.component.passwordfield;
+
+import com.vaadin.demo.DemoExporter;
+import com.vaadin.flow.component.html.Span;
+import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
+import com.vaadin.flow.component.orderedlayout.VerticalLayout;
+import com.vaadin.flow.component.select.Select;
+import com.vaadin.flow.component.textfield.PasswordField;
+import com.vaadin.flow.data.value.ValueChangeMode;
+import com.vaadin.flow.router.Route;
+
+import static com.vaadin.demo.component.Constants.valueChangeModes;
+
+@Route("password-field-value-change-mode")
+public class PasswordFieldValueChangeMode extends VerticalLayout {
+
+    public PasswordFieldValueChangeMode() {
+        setPadding(false);
+
+        // tag::snippet[]
+        var passwordField = new PasswordField("Password Field");
+        var modeSelector = new Select<>("Value Change Mode", valueChangeModes);
+        modeSelector.setValue(passwordField.getValueChangeMode());
+        modeSelector.addValueChangeListener(e -> {
+            passwordField.clear();
+            passwordField.setValueChangeMode(e.getValue());
+        });
+        var serverSideContent = new Span();
+        passwordField.addValueChangeListener(
+                e -> serverSideContent.setText(e.getValue()));
+        // end::snippet[]
+
+        modeSelector.setItemLabelGenerator(ValueChangeMode::name);
+
+        var horizontalLayout = new HorizontalLayout(passwordField,
+                modeSelector);
+        horizontalLayout.setAlignItems(Alignment.BASELINE);
+
+        var serverSideLayout = new HorizontalLayout(new Span("Server side:"),
+                serverSideContent);
+
+        add(horizontalLayout, serverSideLayout);
+    }
+
+    public static class Exporter
+            extends DemoExporter<PasswordFieldValueChangeMode> { // hidden-source-line
+    } // hidden-source-line
+}