feat: Add Flow Signal documentation #4353

mshabarov · 2025-05-30T13:00:10Z

No description provided.

github-actions · 2025-05-30T13:00:37Z

AI Language Review

The provided documentation appears to be comprehensive and well-structured. It effectively explains the concepts of signals, their types, and usage within a Vaadin application. The examples are clear and the code snippets seem to accurately demonstrate the described features. The tone and style align well with technical documentation standards. Thus, there are no significant issues needing correction.

However, there is a minor typographical error noted: "soltuion" should be corrected to "solution". Other than this, the document is well-crafted.

Legioth · 2025-06-18T09:53:20Z

articles/flow/advanced/signals.adoc

@@ -0,0 +1,393 @@
+---
+title: Reactive UI with Signals
+page-title: How to create reactive UIs with the Flow Signals library


I assume most readers don't know what a "reactive UI" is. The page title could instead be about "How to manage UI state".

Legioth · 2025-06-18T09:54:44Z

articles/flow/advanced/signals.adoc

+---
+title: Reactive UI with Signals
+page-title: How to create reactive UIs with the Flow Signals library
+description: Using the Flow Signals library to manage UI state reactively in Vaadin applications.


There's an inconsistency between "the Flow Signals library" and "the Flow Signal library".

At the same time, I don't think it's relevant to give the name or emphasize that it's a library. From the user's point of view, it's just part of Flow just like the view router or the form binder (which are capitalized mainly when referring to the specific class but not when referring to the concept as a whole). I would thus prefer to use "signals in Flow" or just "signal".

Yes. Always be conservative when thinking about introducing new named concepts to the products. First try to describe/document them with common language, and if that becomes unwieldy or hard to comprehend, then you can try introducing a new named concept, that you very clearly define somewhere in the documentation.

Legioth · 2025-06-19T06:23:52Z

articles/flow/advanced/signals.adoc

+== Introduction
+
+The Flow Signal library provides a reactive state management solution for Vaadin Flow applications.
+Its ultimate goal is to enable sharing state between multiple clients and the server in a thread-safe manner.


The ultimate goal in the context of Flow is to make it easier to handle UI state regardless of whether it's shared. Thread-safe sharing and collaboration are just cherries on the top.

Legioth · 2025-06-19T06:25:47Z

articles/flow/advanced/signals.adoc

+Vaadin Flow Signals library is a preview feature in Vaadin 24.8 and may change in future releases.
+Signals integration into components API is planned in future releases but not yet included, thus you need to add listeners to components and effect functions manually.
+
+=== Key Features


Same as in some comments above, I think the emphasis here could be shifted more towards "regular" state management.

Legioth · 2025-06-19T06:26:51Z

articles/flow/advanced/signals.adoc

+
+=== Effects
+
+Effects are callbacks that automatically re-run when any signal value they depend on changes. They are used to update the UI in response to signal changes.


Could emphasize that dependency tracking is automatic.

Legioth · 2025-06-19T07:00:10Z

articles/flow/advanced/signals.adoc

+[source,java]
+----
+Runnable cleanup = Signal.effect(() -> {
+    // Update UI


Same about avoiding examples that "use" effect together with anything related to the UI

Legioth · 2025-06-19T07:02:44Z

articles/flow/advanced/signals.adoc

+
+== Advanced Topics
+
+=== Computed Signals


Doesn't seem like this belongs in the "advanced" section since it shows exactly the same thing that was already shown in the very beginning of the page.

Legioth · 2025-06-19T07:03:24Z

articles/flow/advanced/signals.adoc

+
+=== Signal Mapping
+
+You can transform a signal's value using the map() method.


Could mention that this is just a shorthand for creating a computed signal

Legioth · 2025-06-19T07:04:06Z

articles/flow/advanced/signals.adoc

+----
+ValueSignal<String> name = SignalFactory.IN_MEMORY_SHARED.value("name", String.class);
+ValueSignal<String> readOnlyName = name.asReadonly();
+----


Could clarify that changes can still be made through name and that such changes will also be visible through readOnlyName

Legioth · 2025-06-19T07:04:42Z

articles/flow/advanced/signals.adoc

+
+[source,java]
+----
+String name = nameSignal.peek(); // Won't trigger Signal.effect()


Might be easier to understand how this works if the code would be inside an actual effect callback.

Make the bot happier

mshabarov

These additions look good to me. Eager to merge 👍

mshabarov · 2025-06-19T09:44:23Z

articles/flow/advanced/signals.adoc

+    private final ValueSignal<String> value =
+            SignalFactory.IN_MEMORY_SHARED.value("value", "");

-    public UserForm() {
-        TextField nameField = new TextField("Name");
-        NumberField ageField = new NumberField("Age");
-
-        Signal.effect(() -> {
-            User currentUser = user.value();
-            nameField.setValue(currentUser.getName());
-            ageField.setValue(currentUser.getAge());
-        });
+    public SharedText() {
+        TextField field = new TextField("Value");

-        nameField.addValueChangeListener(event ->
-            user.update(u -> new User(event.getValue(), u.getAge())));
+        ComponentEffect.bind(field, value, TextField::setValue);

-        ageField.addValueChangeListener(event ->
-            user.update(u -> new User(u.getName(), event.getValue())));
+        field.addValueChangeListener(event -> {
+            // Only update signal if value has changed to avoid triggering infinite loop detection
+            if (!event.getValue().equals(value.peek())) {
+               value.value(event.getValue());
+            }
+        });

-        add(nameField, ageField);
+        add(field);


Now looking at this (and older) example I'm thinking about adding one more component which value depends on the text input. Otherwise the code looks very synthetic: you input a value, it updates the signal and then it updates the value back to the same value, so visually Ui looks like as you just type a text. But from the other side, the example is anyway extremely simple, and rather should show the principle.

feat: Add Flow Signal documentation

2a27c76

mshabarov requested review from Legioth and taefi June 2, 2025 11:46

add ComponentEffect

eab7bd8

mshabarov marked this pull request as ready for review June 18, 2025 17:24

Merge branch 'latest' into flow-signals

a22f5f9

Legioth requested changes Jun 19, 2025

View reviewed changes

Legioth added 2 commits June 19, 2025 11:52

Update signals.adoc

e1e1b43

Update signals.adoc

75858ba

Make the bot happier

mshabarov commented Jun 19, 2025

View reviewed changes

Legioth approved these changes Jun 19, 2025

View reviewed changes

mshabarov merged commit 33095d0 into latest Jun 19, 2025
3 of 5 checks passed

mshabarov deleted the flow-signals branch June 19, 2025 10:02


		=== Effects

		Effects are callbacks that automatically re-run when any signal value they depend on changes. They are used to update the UI in response to signal changes.


		=== Signal Mapping

		You can transform a signal's value using the map() method.

feat: Add Flow Signal documentation #4353

feat: Add Flow Signal documentation #4353

Uh oh!

Conversation

mshabarov commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

AI Language Review

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mshabarov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mshabarov commented May 30, 2025 •

edited

Loading

github-actions bot commented May 30, 2025 •

edited

Loading