Document value change modes for supported components

articles/components/email-field/index.adoc

@@ -152,4 +152,38 @@ include::{root}/frontend/demo/component/emailfield/react/email-field-readonly-an
 endif::[]
 --
 
+== 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 [classes]`ValueChangeMode` enum provides several modes for different use cases.
+
+These modes are described below.
+
+
+[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 modes that support a custom timeout interval, use the `setValueChangeTimeout(int ms)` method.
+
+
+[.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,40 @@ include::{root}/frontend/demo/component/numberfield/react/number-field-readonly-
 endif::[]
 --
 
+== 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 [classes]`ValueChangeMode` enum provides several modes for different use cases.
+
+These modes are described below.
+
+
+[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 modes that support a custom timeout interval, use the `setValueChangeTimeout(int ms)` method.
+
+
+[.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

@@ -166,6 +166,40 @@ endif::[]
 --
 
 
+== 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 [classes]`ValueChangeMode` enum provides several modes for different use cases.
+
+These modes are described below.
+
+
+[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 modes that support a custom timeout interval, use the `setValueChangeTimeout(int ms)` method.
+
+
+[.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
 
 Express clearly your password requirements to the user, so that they don't have to guess. The <<helper,Helper>> feature is appropriate for this purpose.

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

@@ -279,6 +279,40 @@ include::{root}/frontend/demo/component/richtexteditor/react/rich-text-editor-mi
 endif::[]
 --
 
+== 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 [classes]`ValueChangeMode` enum provides several modes for different use cases.
+
+These modes are described below.
+
+
+[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 modes that support a custom timeout interval, use the `setValueChangeTimeout(int ms)` method.
+
+
+[.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

@@ -279,6 +279,40 @@ endif::[]
 --
 
 
+== 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 [classes]`ValueChangeMode` enum provides several modes for different use cases.
+
+These modes are described below.
+
+
+[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 modes that support a custom timeout interval, use the `setValueChangeTimeout(int ms)` method.
+
+
+[.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
 
 Slider is best suited for settings where the user benefits from immediate visual feedback, such as adjusting volume or brightness. Range Slider is best suited for filtering or selecting a subset of a continuous range, such as a price range or date span.

articles/components/text-area/index.adoc

@@ -257,6 +257,40 @@ include::{root}/frontend/demo/component/textarea/react/text-area-helper.tsx[rend
 endif::[]
 --
 
+== 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 [classes]`ValueChangeMode` enum provides several modes for different use cases.
+
+These modes are described below.
+
+
+[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 modes that support a custom timeout interval, use the `setValueChangeTimeout(int ms)` method.
+
+
+[.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,39 @@ 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.]
 |===
 
+== 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 [classes]`ValueChangeMode` enum provides several modes for different use cases.
+
+These modes are described below.
+
+
+[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 modes that support a custom timeout interval, use the `setValueChangeTimeout(int ms)` method.
+
+
+[.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/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

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-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/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/emailfield/EmailFieldValueChangeMode.java

@@ -0,0 +1,45 @@
+package com.vaadin.demo.component.emailfield;
+
+import com.vaadin.demo.DemoExporter;
+import com.vaadin.demo.flow.routing.Route;
+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;
+
+@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",
+                ValueChangeMode.values());
+        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
+}