Skip to content

feat(flow-client): port reactive core + node features to TypeScript - #24947

Merged
Artur- merged 48 commits into
mainfrom
flow-client-ts-reactive-nodefeature
Sep 1, 2026
Merged

Artur- merged 48 commits into
mainfrom
flow-client-ts-reactive-nodefeature

Conversation

@totally-not-ai

@totally-not-ai totally-not-ai Bot commented Jul 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Step 2 of the GWT→TypeScript flow-client migration series.

Ports the reactive dependency-tracking core and the node-feature layer — 22 modules, one per Java source file:

  • internal/client/flow/reactive/ (from com.vaadin.client.flow.reactive) — Reactive, Computation, ReactiveEventRouter, ReactiveValue, ReactiveValueChangeEvent, ReactiveValueChangeListener, InvalidateEvent, InvalidateListener, FlushListener
  • internal/client/flow/nodefeature/ (from com.vaadin.client.flow.nodefeature) — NodeFeature, NodeMap, NodeList, MapProperty, and the event/listener pairs ListSpliceEvent/ListSpliceListener, MapPropertyAddEvent/MapPropertyAddListener, MapPropertyChangeEvent/MapPropertyChangeListener
  • internal/flow/internal/nodefeature/NodeFeatures.ts, NodeProperties.ts — the constants shared with the server (com.vaadin.flow.internal.nodefeature). NodeFeatures is complete (all 26 ids); NodeProperties ports the keys the ported client needs so far, which the module Javadoc states explicitly
  • internal/EventRemover.ts — mirrors elemental.events.EventRemover, the one non-com.vaadin type this layer needs

Nature of the change

  • Additive only — nothing is wired into the running client. The GWT client remains the live engine; these modules are exercised by web-test-runner only.

  • internal/PORTING.md is new — it consolidates the conventions settled in the feat(flow-client): port leaf client utilities to TypeScript #24933 review so follow-up PRs stay consistent: module layout (one Java source file → one TypeScript module, mirrored package paths), visibility parity (#-private, never the TypeScript private keyword), complete public API and Java member order, Javadoc carried verbatim (@param/@returns/@see {@link …}, no @since/@author, <p> → blank lines, {@code} → backticks), constants referenced by name rather than hard-coded, TODO(flow-client-ts) notes where a doc reference points at a not-yet-ported class, and the test 1:1 rules below.

  • Port deviations, each documented at the site where it occurs:

    • MapPropertyTree / MapPropertyNode / MapPropertyOwner and NodeFeatureNode are minimal contracts for the slices of StateTree/StateNode this layer touches; the ported state tree will satisfy them at cutover. isStateNode() stands in for value instanceof StateNode.
    • Computation and ReactiveEventRouter take callbacks where Java uses protected abstract methods (doRecompute, wrap, dispatchEvent).
    • NodeList.splice(index, remove, add?) merges the two Java splice overloads.
    • Value comparisons use strict === where Java uses Objects.equals. This is a deliberate choice, not an oversight: undefined and null stay distinct on the TypeScript side.
  • Tests mirror the Java cases 1:1 — same set, same granularity, same assertions, same order. 50 tests across five suites, one per Java test class, each at the mirrored path under src/test/frontend/internal/:

    TypeScript suite Java original Cases
    MapPropertyTests.ts MapPropertyTest.java 19
    NodeMapTests.ts NodeMapTest.java 9
    ReactiveTests.ts ReactiveTest.java 9
    ComputationTests.ts ComputationTest.java 8
    NodeListTests.ts NodeListTest.java 5

    CountingComputation.ts and TestReactiveEventRouter.ts port the Java test helpers of the same names; the runner treats any non-*Tests.ts file under src/test/frontend as a helper rather than a suite.

  • Config changes are layout-only — web-test-runner.config.mjs discovers suites recursively (src/test/frontend/**/*Tests.ts) now that tests are nested, and eslint.config.mjs lists the new test directories in projectService.allowDefaultProject (its globs do not support **). tsconfig already covers src/main/frontend/**, and the lint rules added in feat(flow-client): port leaf client utilities to TypeScript #24933 (tsdoc/syntax and no-console over src/main/frontend/internal/**) apply to these modules as they stand.

Verification

CI runs tsc --noEmit, eslint (including tsdoc/syntax and no-console) and web-test-runner on every push; the 50 frontend tests are reported through the same JUnit collection as the Java tests.

Series context

Stacked on #24933 (base flow-client-ts-leaf-utils) — merge after it. The diff is only this PR's own new files, so it can be reviewed independently of the merge order. Later PRs (state tree, binding, communication, …) stack on top of this layer and follow the same conventions.

⚠️ Non-draft, but please review before merging.

@totally-not-ai

totally-not-ai Bot commented Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

Review — 1:1 Java→TS port fidelity

Reviewed the TS ports in this PR against their Java counterparts in com.vaadin.client.flow.reactive and com.vaadin.client.flow.nodefeature, method-by-method, plus test coverage.

Production code — faithful ✅

reactive.ts, MapProperty.ts, NodeMap.ts, NodeList.ts, NodeFeature.ts, NodeFeatures.ts are all faithful 1:1 ports. Spot checks that pass:

  • Reactive.flush() — same double-loop, flush-then-single-post-flush ordering, flushing guard and splice(0, index) cleanup as Reactive.java.
  • Computation invalidate/recompute/stop ordering preserved.
  • MapProperty.getSyncToServerCommand — the isServerUpdate lock, the equal-value early unlock, the compound !(equal && hasValue) && !isServerUpdate guard, and the active vs inactive branches all match MapProperty.java.
  • All 27 NodeFeatures int constants and the NodeProperties string values match the Java (NodeProperties is a documented subset of only what the ported client needs — fine).

Tests — MapPropertyTests.ts has reduced coverage ⚠️ (please fix)

MapPropertyTest.java has 19 @Test methods; MapPropertyTests.ts ports only 10. The 9 missing cases are exactly the syncToServer / server-update-lifecycle tests — i.e. the coverage for the most intricate ported logic (getSyncToServerCommand's isServerUpdate state machine):

  • setValue_updateFromServerIsNoCompleted_syncToServerDoesntUpdateValue
  • setValue_updateFromServerIsApplied_syncToServerUpdatesValue
  • setValue_updateFromServerIsAppliedViaSyncToServer_syncToServerUpdatesValue
  • removeValue_updateFromServerIsNoCompleted_syncToServerDoesntUpdateValue
  • removeValue_updateFromServerIsApplied_syncToServerUpdatesValue
  • removeValue_updateFromServerIsAppliedViaSyncToServer_syncToServerUpdatesValue
  • syncToServer_propertyHasNoValue_propertyIsSync
  • setValue_alwaysUpdateValue_eventIsAlwaysFired
  • setValue_defaultUpdateValueStrategy_eventIsFiredOnlyOnce

In addition, the one inactive-node test that was ported under-asserts. Java's syncToServer_nodeIsInactive_propertyIsNotSent_eventIsFiredAndFlushed asserts four things — property not sent, a change event is fired, getNewValue() is null, and a registered flush listener ran (proving Reactive.flush() was called). The TS syncToServer does not send when the node is inactive asserts only that nothing was sent, so it doesn't cover the fake-event-fired + flush behavior that the production port specifically implements.

The other three test files (ReactiveCoreTests.ts, NodeListTests.ts, NodeMapTests.ts) are full 1:1 coverage.

Recommendation: port the 9 missing MapPropertyTest cases and strengthen the inactive-node test to assert the event-fired + flush behavior. Production code looks good to go.

@Artur-
Artur- marked this pull request as ready for review July 31, 2026 14:12
@Artur-
Artur- force-pushed the flow-client-ts-reactive-nodefeature branch from 41f9169 to 54ba363 Compare July 31, 2026 15:46
@Artur-
Artur- force-pushed the flow-client-ts-reactive-nodefeature branch from b33d2a2 to bc8a00e Compare August 14, 2026 06:17
@github-actions github-actions Bot added +0.0.1 and removed +1.0.0 labels Aug 14, 2026
@github-actions

github-actions Bot commented Aug 14, 2026 •

Copy link
Copy Markdown
Contributor

Test Results

 1 389 files  ± 0   1 403 suites  +5   1h 26m 51s ⏱️ - 2m 46s
10 849 tests +50  10 782 ✅ +50  67 💤 ±0  0 ❌ ±0 
11 168 runs  +50  11 100 ✅ +50  68 💤 ±0  0 ❌ ±0 

Results for commit dd22bc1. ± Comparison against base commit 9aebdc5.

♻️ This comment has been updated with latest results.

@Artur-
Artur- force-pushed the flow-client-ts-reactive-nodefeature branch from bc8a00e to 3452868 Compare August 14, 2026 07:59
@vaadin-bot vaadin-bot added +1.0.0 and removed +0.0.1 labels Aug 14, 2026
@github-actions github-actions Bot added +0.0.1 and removed +1.0.0 labels Aug 14, 2026
@totally-not-ai
totally-not-ai Bot force-pushed the flow-client-ts-reactive-nodefeature branch from 3452868 to 1a3afac Compare August 16, 2026 09:48
@vaadin-bot vaadin-bot added +1.0.0 and removed +0.0.1 labels Aug 16, 2026
@totally-not-ai
totally-not-ai Bot force-pushed the flow-client-ts-reactive-nodefeature branch from 1a3afac to d924efc Compare August 16, 2026 18:17
@github-actions github-actions Bot added +0.0.1 and removed +1.0.0 labels Aug 16, 2026
@Artur-
Artur- force-pushed the flow-client-ts-reactive-nodefeature branch from d924efc to 5205388 Compare August 17, 2026 10:47
@vaadin-bot vaadin-bot added +1.0.0 and removed +0.0.1 labels Aug 17, 2026
@github-actions github-actions Bot removed the +1.0.0 label Aug 17, 2026
totally-not-ai Bot and others added 26 commits September 1, 2026 18:22
PORTING.md rule 13.6 asks for the ported-vs-added split to be visible so
the 13.1 floor stays checkable. None of the eight suites showed it.

BrowserInfo, Console, Profiler and StorageUtil have no Java test at all,
so each carries a note that every case in it is additional. JsArray and
WidgetUtil group their extras under a 'beyond the Java suite' describe --
GwtJsArrayTest covers the type while the port also exposes @JsOverlay
helpers, and GwtWidgetUtilTest covers only getAbsoluteUrl. BrowserDetails
and SharedUtil have their extras scattered, so those are marked
individually.

Also splits the trailing-slash case, which merged five Java @test methods
(trailingSlashIsTrimmed, noTrailingSlashForTrimming,
trailingSlashesAreTrimmed, emptyStringIsHandled, rootSlashIsTrimmed) into
one it(), contrary to rule 13.3.
Console moved to internal/client/ with the package-path restructure, so
the eslint exemption that lets it call the browser console needed the
new path.
Tests mirror their sources, which live under src/main/frontend/internal/,
so the suites belong under src/test/frontend/internal/ rather than
directly under src/test/frontend/. The Flow.ts suites stay at the root
because their source is not under internal/.
…rder

The capitalize case carries the two assertions of
SharedUtilTests.methodUppercaseWithTurkishLocale, so it is a ported case
rather than an addition; the "beyond the Java suite" marker made it look
as if that Java case had been dropped. Its remaining assertions are the
ones that go beyond the Java case.

The ported cases now also follow the Java declaration order (PORTING.md
13.7), with the added cases after them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Ports the reactive dependency-tracking core and the node-feature layer:
reactive, NodeFeature, NodeFeatures, NodeMap, NodeList, MapProperty.

Depends only on the leaf utilities (PR1); the nodefeature layer is decoupled
from the state tree via the MapPropertyOwner interface. Additive only -- not
wired into the running client. Exercised by mocha (38 tests).
Follow-up to the review of #24933: privacy is enforced at runtime with
the JS-native # prefix rather than only at compile time by the
TypeScript-only private modifier. Non-exported module-local functions
keep their plain style, and protected members stay protected to match
the visibility of their Java originals.
…re modules

Applies the #24933 review's Javadoc-carryover convention to the reactive
core and node-feature ports: class descriptions, @param/@returns and @see
(as {@link ...}) are carried verbatim from the com.vaadin.client.flow
.{reactive,nodefeature} originals, preserving source wording (including
typos), converting <p> to blank lines and <code>/{@code} to backticks, and
omitting @since/@author. Port deviations (decoupling interfaces, the merged
NodeList.splice overloads, the callback-form reactive classes) are noted at
their sites. Comment-only change; no runtime behavior is affected.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…adoc

Maintain 1 Java class -> 1 TS module parity: move NodeProperties out of
NodeFeatures.ts into its own NodeProperties.ts, ordered as in the Java
source. Carry over the per-member Javadoc for both NodeFeatures and
NodeProperties that was lost in the initial port; references to not-yet-
ported server classes are kept as code spans with a TODO to restore them
as {@link ...} links in follow-up PRs, and intra-module references are
cross-linked ({@link NodeProperties.VISIBLE}).

Cross-reference feature ids instead of hard-coding them: NodeMap uses
NodeFeatures.ELEMENT_PROPERTIES (dropping the local = 1), and the NodeMap
test uses the constant, mirroring the Java test.

Document the porting conventions for the migration stack in a PORTING.md.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
Split the ported reactive core and node-feature event/listener classes so
each Java source file maps to its own TypeScript module, matching the
one-class-one-module convention. reactive.ts is split into the nine modules
of com.vaadin.client.flow.reactive; the change/add/splice event and listener
classes move out of their owner features into their own modules; the elemental
EventRemover primitive gets a standalone module. ReactiveCoreTests is split
into ComputationTests and ReactiveTests with shared CountingComputation and
TestReactiveEventRouter helper modules. Clarifies the PORTING.md module-layout
rule so the split follows the Java file boundary rather than logical grouping.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
Split merged test cases that collapsed several Java @test methods into a
single TypeScript it(), per PORTING.md rule 13.

NodeMapTests: one it() covered hasPropertyValueForExistingPropertyWithoutValue,
hasPropertyValueForExistingPropertyWithValue and hasPropertyValueAfterRemovingValue.
ReactiveTests: one it() covered testPostFlushListenerInvokedDuringFlush and
testPostFlushListenerRemovedAfterFlush.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
Spell out what 1:1 Java->TS test parity means (no dropping, no
merging, no splitting, matching assertion strength, matching count/
name/order) to prevent the test mismatches raised in this PR review.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
The ListSpliceEvent port bundled the Java constructor's positional
index/remove/add/clear parameters into a single details object and left
the constructor undocumented, dropping the per-parameter Javadoc. Restore
it: document source and the bundled details object, carrying each original
@PARAM's wording as a field entry and noting the deviation. Make the
PORTING.md Javadoc rule explicit that constructor @PARAM docs must be
carried over, including the bundled-object case.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
…stSpliceEvent

The port bundled ListSpliceEvent's four positional Java constructor
parameters (index, remove, add, clear) into a single details object.
Restore the positional signature to match the Java API and update the two
callsites in NodeList. Rewrite the PORTING.md deviation rule to forbid
bundling constructor params and require matching the Java parameter list.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
The five positional constructor parameters deliberately mirror the Java
ListSpliceEvent constructor, so suppress @typescript-eslint/max-params at
that line with an explanatory note rather than reshaping the API. Record
the convention in PORTING.md.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
Move the ported reactive / node-feature test suites and helpers into
package-path subdirectories under src/test/frontend that mirror the
modules under test:

- internal/reactive/{ComputationTests,ReactiveTests,CountingComputation,
  TestReactiveEventRouter}.ts
- internal/nodefeature/{MapPropertyTests,NodeListTests,NodeMapTests}.ts

Discover suites recursively in web-test-runner, list the new test
subdirectories in eslint allowDefaultProject (its globs do not support
the ** wildcard), and document the mirrored test layout in PORTING.md.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The base branch flow-client-ts-leaf-utils adopted the Java-package-mirrored
nested layout (BrowserDetails under internal/shared/, SharedUtil under
internal/shared/util/, and the leaf-utility test suites under
src/test/frontend/internal/...) after this branch forked, which is the source
of the merge conflict.

Adopt the same nested layout for the leaf utilities and their tests, pick up
the base branch's BrowserInfo import path, and merge the eslint config so
allowDefaultProject covers both the leaf-utility test directories (from the
base) and this PR's reactive/nodefeature test directories, with the recursive
mocha-globals glob. The reactive/nodefeature modules already mirror the nested
layout, so no changes were needed there.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
Move the ported reactive / node-feature test suites and helpers into
package-path subdirectories under src/test/frontend that mirror the
modules under test:

- internal/reactive/{ComputationTests,ReactiveTests,CountingComputation,
  TestReactiveEventRouter}.ts
- internal/nodefeature/{MapPropertyTests,NodeListTests,NodeMapTests}.ts

Discover suites recursively in web-test-runner, list the new test
subdirectories in eslint allowDefaultProject (its globs do not support
the ** wildcard), and document the mirrored test layout in PORTING.md.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rule 13.1 required the it() count to equal the Java @test count, which
reads as a cap as well as a minimum. Several ported modules have thin or
absent Java coverage -- GwtWidgetUtilTest has one case for all of
WidgetUtil, and BrowserInfo, Console, Profiler and StorageUtil have no
Java test at all -- so complying literally would mean deleting working
tests.

State that every Java case must be accounted for (the omission the rule
was written to prevent) while allowing extra cases where Java has none,
grouped so the ported-vs-added split stays visible and the floor stays
checkable. The never-drop, never-merge and assertion-strength rules are
unchanged.
Rule 2 now strips only the com.vaadin. prefix and keeps every remaining
package segment, so com.vaadin.client.flow.reactive.Reactive lands in
internal/client/flow/reactive/ rather than internal/reactive/, and the
shared and internal packages get their own paths. Modules, tests, the
eslint allowDefaultProject list and the no-console exemption for Console
follow the same layout.

Modules with no com.vaadin counterpart (the elemental EventRemover and
the local assert helper) stay at the internal/ root, and a TypeScript-only
split lives in the package of the class it was split from; both are
written into the rule.
Tests mirror their sources under src/main/frontend/internal/, so the
suites move under src/test/frontend/internal/ and the eslint
test-directory list follows.
…uites

CountingComputation and TestReactiveEventRouter stayed behind in
src/test/frontend/internal/reactive/ when the suites moved to the
package-mirroring path, so the suites reached them by climbing out of
their own tree. Their Java originals live in
com.vaadin.client.flow.reactive, and PORTING.md requires a suite's helper
modules to sit at the mirrored path too.

Removes the last src/test/frontend/internal/reactive/ entry from
allowDefaultProject with them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The test tree keeps the internal/ prefix, but the PORTING.md examples and
the web-test-runner comment still showed the paths without it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
MapPropertyTests, NodeMapTests and NodeListTests each declared their own
countingComputation copy. Import the shared reactive/CountingComputation
helper instead, mirroring the Java tests, which all import
com.vaadin.client.flow.reactive.CountingComputation.

Co-authored-by: Anton Platonov <247998+platosha@users.noreply.github.com>
@sonarqubecloud

sonarqubecloud Bot commented Sep 1, 2026

Copy link
Copy Markdown

@vaadin-bot

Copy link
Copy Markdown
Collaborator

This ticket/PR has been released with Vaadin 25.3.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Development

Successfully merging this pull request may close these issues.

4 participants