Repository navigation
docs: move React form binding to Flow - #6621
Merged
Merged
Conversation
Rewrite the Hilla forms pages for 25.4 as six pages under flow/react-views/forms: Forms, Validation, Form State, Nested Objects & Arrays, Field Components and Form API. The generated form models are now @vaadin/hilla-models builder constants, and the model classes that the old pages showed no longer exist. Add compiled person and sign-up examples, rewrite the company office example to set the city with setValue() instead of mutating the form value, and remove the unused Contact example and the Lit-era images. Every example ran in a 25.4.0-alpha5 application. Add redirects for the removed pages, point the Lit redirects at the new pages, and update the links, including a Domain Primitives link to an anchor that didn't exist. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
vaadin-review-bot
left a comment
vaadin-review-bot
left a comment
There was a problem hiding this comment.
Reviewed the changes — left 3 comments.
| Finding | |
|---|---|
| 💬 | "Also when the submit fails" can be read as covering a failed browser validation, but in that case the default value doesn't change. |
| 💬 | Custom Field and Rich Text Editor are no longer listed, so the table suggests they can't be bound. |
| 📐 | Several new pages have a page-title or meta-description outside the lengths that the conventions give. |
Contributor
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-6621.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Other changed files
Built from fc01ef4 |
List Custom Field and Rich Text Editor among the components that field() binds, with their String value formats. Say that only a failed onSubmit callback, not a failed browser validation, changes the default value. Bring the page titles and meta descriptions of the forms pages within the lengths of the conventions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The colon made the front matter invalid YAML, so Vale failed on the page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
peholmst
added a commit
that referenced
this pull request
Nov 11, 2026
**Review risk:** two-way door. Docs and examples only: five new reference pages, ten removed pages with redirects, merges into three Flow security pages, and link updates. Reverting brings the old pages back. ## Summary Moves the security reference for React views from the Hilla section to the Flow security reference. The new pages are under `articles/flow/security/react-views/`, including stateless authentication. This is the sixth step of dissolving the Hilla section, after #6611, #6616, #6618, #6620 and #6621. Full-stack signals follow in the next pull request. The new pages are reference only: what the access rules are, how Vaadin checks them, and what the APIs do. They link to other reference pages. The step-by-step setup stays in Building Apps > Secure React Views, which now links to the reference instead of the reference linking to it. Every statement is checked against `main` of vaadin/flow and vaadin/hilla. The behavior is also checked in a scratch 25.4.0-alpha5 application with Spring Security, using curl and a browser. This pull request targets `main` only, so it gets no `target/v25.3` label. ## What changed - **New pages** in `flow/security/react-views/`: - `index.adoc`: the security model, the default access of services, React views and Flow views, what `VaadinSecurityConfigurer` does for React views and services, and data kept in the browser. - `service-access-control.adoc`: the access annotations and their precedence, role checks, `401` versus `403`, the current user, auditing denied calls, and CSRF. - `authentication.adoc`: the React login view, the user information method, `configureAuth()`, `useAuth()`, `login()` and `logout()`, and expired sessions. - `view-access-control.adoc`: the three places where `loginRequired` and `rolesAllowed` are checked (the router, the menu, page loads), role names, `hasAccess()`, `protectRoutes()`, and Flow and React views together. - **Moved page:** `flow/security/react-views/stateless-authentication.adoc`, rewritten as a reference for `VaadinStatelessSecurityConfigurer`, its cookies, and the contents of the token. It states that stateless authentication is intended for React views only, and that its behavior with Flow views is undefined. - **Merges:** - `spring/security-configuration.adoc`: the static `getDefaultHttpSecurityPermitMatcher()` and `getDefaultWebSecurityIgnoreMatcher()` matchers. - `protections/vulnerabilities.adoc`: the double-submit cookie check that services use without Spring Security's CSRF protection, and its relation to `disable-xsrf-protection`. - **Examples:** the user information service now allows anonymous calls and returns `null` when nobody is logged in, using `AuthenticationContext`. Its record has a `roles` property, which `configureAuth()` reads by default. A new `ProjectService` shows the access annotations. The login view, the session-expiration overlay and the connect client are rewritten. The examples that only the removed pages used are deleted. - **Corrections and additions** compared with the old pages, each confirmed in the scratch application: - A service without annotations is denied to everyone. Controlling Service Access and Best Practices also said that it needs only a logged-in user. - The session-expiration example said that the failed call continues after the login. It doesn't: `login()` returns no `token`, so `InvalidSessionMiddleware` doesn't send the call again, and `login()` reloads the page at `/`. The new example reloads the current page. A user information method that allows only logged-in users also opened the overlay for every visitor who isn't logged in. - After a session expires, calls to anonymous methods fail with `401` as well, because the CSRF token belonged to the old session. - When Spring Security has already rejected an anonymous call, no `EndpointInvocation` event is published. Spring Security publishes its own event, with the request as its object. The Auditing section said that the anonymous user arrives in the `EndpointInvocation` event. - The old role example used `rolesAllowed: ['ROLE_USER']` with roles that never contained that name. - The old pages showed the removed `useRouteMetadata`, the deprecated `requiresLogin`, and `VaadinRequest.getCurrent().getUserPrincipal()`. - **Removed pages, each with a redirect:** the ten `hilla/guides/security` pages. Offline authentication, which was built on Lit-era APIs, and the best-practices, introduction and vulnerabilities pages go to the matching Flow pages. The nine Lit redirects that led to these pages now point straight at the new pages. - **Links:** Routing, Browser-Callable Services, Client and Security Configuration now link to the new reference pages instead of the Building Apps guide. Secure React Views links to the reference. The full-stack signals page linked to the removed introduction. ## Test summary - `npm run check-redirects` passes. - `mvn spotless:apply` and `mvn compile` pass. `npx eslint frontend/demo/auth` passes. - The frontend examples type-check in the scratch 25.4.0-alpha5 application against the generated services. The login view and the session-expiration overlay ran there. - Checked with curl and in the browser in the scratch application: - service calls as an anonymous user, a user, and an administrator; - page loads, client-side navigation and menus; - expired sessions; - audit events; - stateless authentication across a server restart; - the double-submit cookie without Spring Security. - Every cross reference in the new and changed lines resolves to an existing page and anchor. - Vale: no errors or warnings on the added and changed lines. - Asciidoctor renders the new and changed pages, with all includes and tags resolved. - I didn't run a full dspublisher build locally. Stateless authentication is documented as intended for applications whose views are all React views, with undefined behavior for Flow views. Flow views keep their UI state in the HTTP session in any case. Behaviors that came up during testing, which the pages describe as they are: - On a page load of a React view with `loginRequired: true`, Spring Security compares `rolesAllowed` with the granted authorities exactly. The menu and the browser compare differently. `rolesAllowed: ['ADMIN']` therefore answers `403` to an administrator who reloads the page. View Access Control documents the three comparisons, and recommends writing the full authority names, such as `ROLE_ADMIN` (vaadin/flow#26962). - `InvalidSessionMiddleware` retries a call only when the `LoginResult` has a `token`, which `login()` never returns (vaadin/hilla#7048). Not changed here: the role example in Building Apps > Secure React Views hits the `403` above on reload, and its `getRoles` code doesn't type-check. That guide gets a separate pull request. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
peholmst
added a commit
that referenced
this pull request
Nov 11, 2026
**Review risk:** two-way door. Docs and examples only: one new reference page, one removed page with a redirect, a new section on Shared Signals, and link updates. Reverting brings the old page back. ## Summary Moves full-stack signals from the Hilla guides to the Flow UI State section, as the new page Shared Signals in React Views (`flow/ui-state/full-stack-signals`). This is the seventh step of dissolving the Hilla section, after #6611, #6616, #6618, #6620, #6621 and #6622. The page is a reference: which shared signal types a service can return, the client API of the signals, how they connect and synchronize, and how the access annotations apply. It's rewritten for 25.4, because most of the old page described an API that no longer exists. Every statement is checked against `main` of vaadin/hilla and vaadin/flow, and the behavior is checked in a scratch 25.4.0-alpha5 application with two browser tabs. This pull request targets `main` only, so it gets no `target/v25.3` label. ## What changed - **New page** `flow/ui-state/full-stack-signals.adoc`, marked as a preview feature behind the `fullstackSignals` feature flag: - the supported types (`SharedValueSignal`, `SharedNumberSignal`, `SharedListSignal`) and their TypeScript counterparts; - returning one instance from the service, and service methods with parameters; - creating, connecting and reading the signals in a view, and default values; - the members of `ValueSignal`, `NumberSignal` and `ListSignal`, and operation results; - changes made on the server; - access control. - **Shared Signals:** a new Validating Changes section for `withValidator()` and `CommandValidator`, which the Flow page didn't cover. The UI State index links to the new page. - **Feature Flags:** `fullstackSignals` moves to the list of experimental flags, and the Hilla Feature Flags heading goes away. - **Examples:** a compiled `MeetingService` and a view that uses a value, number and list signal, replacing the inline examples. - **Removed page, with a redirect:** `hilla/guides/full-stack-signals` → `flow/ui-state/full-stack-signals`. - **Links:** Type Conversion now links to the new page. - **Corrections** compared with the old page, each checked in the scratch application: - `ValueSignal` has no `replace()` or `update()` anymore (vaadin/hilla#3500), and `ListSignal` has `insertFirst()` as well. - The operation-validator API (`withOperationValidator`, `ValidationResult`, `IncrementOperation`, …) no longer exists. Flow's shared signals use `withValidator(CommandValidator)`, which is now on the Shared Signals page. - `new SharedValueSignal<>(false, Boolean.class)` doesn't compile. The constructors take an initial value, a type, or both as a `TypeReference`. - The list example used the index as the React `key`. Each item signal has a stable `id`. - `SharedMapSignal` and `SharedNodeSignal` aren't supported. The generator produces a plain method for them. ## Test summary - `npm run check-redirects` passes. - `mvn spotless:apply` and `mvn compile` pass. `npx eslint frontend/demo/fusion/signals` passes. - The example service and view type-check in the scratch 25.4.0-alpha5 application. Two tabs share the topic, the votes, and the agenda items: adding, checking and removing items all sync. - Checked with the browser and the generated client: - the generated types and default values; - write before read; - access denied on connecting and on changing; - `result` and `error` of a failed change; - a server-side change, which the connected browsers don't get and a new connection does (vaadin/hilla#5722); - assigning the value of a list signal. - `withValidator()`, chained validators, child signals, transactions and `asReadonly()` checked with a small program against the 25.4.0-alpha5 classpath. - Every cross reference in the new and changed lines resolves. - Vale: no errors or warnings on the added and changed lines with the pull request configuration. - Asciidoctor renders the new and changed pages, with all includes and tags resolved. - I didn't run a full dspublisher build locally. Behaviors that came up during testing, which the page describes as they are: - Changes that server-side code makes to a shared signal don't reach the connected browsers, only new connections (vaadin/hilla#5722). - When a change fails, its `result` promise doesn't settle; the signal's `error` holds the error. Related to vaadin/hilla#3967. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
peholmst
added a commit
that referenced
this pull request
Nov 11, 2026
**Review risk:** two-way door. Docs and examples only: one new page, two rewritten or extended pages, five removed pages with redirects, and link and guideline updates. Reverting brings the old pages back. ## Summary Moves React i18n, the connection indicator and React styling from the Hilla section to the Flow Reference and the Styling section. This is the eighth step of dissolving the Hilla section, after #6611, #6616, #6618, #6620, #6621, #6622 and #6624. Every statement is checked against `main` of vaadin/hilla and vaadin/flow, and the behavior is checked in a scratch application on 25.4.0-alpha5 with Flow 25.4.0-alpha6, the first Flow release with vaadin/flow#26714. This pull request targets `main` only, so it gets no `target/v25.3` label. ## What changed - **New page** `flow/i18n/react-views.adoc`, Localization in React Views, rewritten from the Hilla i18n guide with compiled examples: - loading translations with `i18n.configure()`, and how the initial language is chosen; - `translate()` and the `key` tag, the missing-translation marker, and ICU parameters compared with Flow's `MessageFormat`; - translating view titles and menu items with `translateDynamic()`, including the `@Menu` titles of Flow views; - changing the language, the file fallback, and that the React language is separate from the Flow `UI` locale; - development and production loading, and what a custom `I18NProvider` must implement. - **Loading and Connection Indicator** (`flow/advanced/loading-indicator.adoc`) now also covers what the Hilla connection indicator page covered: - it covers Flow and React views, the loading bar stages, and the connection status messages; - configuration from Java, including `ReconnectDialogConfiguration`, which no page documented, with a compiled example; - configuration from TypeScript, with the `jar-resources` import that replaces `@vaadin/common-frontend` after vaadin/flow#26714; - styling, with the element structure and states. - **Stylesheets:** a new Stylesheets in React Views section: global `@StyleSheet` styles, importing CSS files and CSS modules from a view, and the type declarations these imports need. - **Localization and Custom I18N Provider** link to the new page. - **Removed pages, with redirects:** - `hilla/guides/i18n` → `flow/i18n/react-views` - `hilla/reference/connection-indicator` → `flow/advanced/loading-indicator` (the Lit redirect points there too) - `hilla/guides/styling` → `styling/stylesheets#react-views` - `hilla/reference`, now empty → `flow/react-views` (the Lit redirect points there too). This was planned for the last step. - The last partial in `articles/hilla/_shared` is removed. - **Links:** the Routing page links to the new i18n page. - **Guidelines:** the Hilla paragraph no longer mentions the `_shared` partials, and the feature flag guideline no longer names the Hilla Feature Flags section that #6624 removed. - **Corrections** compared with the old pages, each checked in the scratch application: - A missing translation shows as `!de: key`, not as the key. - The old guide wrapped `i18n.configure()` in an effect. It returns a `Promise`, and the page awaits it once in the layout. - The default first delay of the loading bar is 450 ms, not 300 ms. - The old CSS examples didn't show anything with the default theme turned off: the indicator's functional style, which is always present, comes after the application's stylesheets and sets `opacity: 0` and `pointer-events: none`. The examples now use `vaadin-connection-indicator .v-loading-indicator` and set `opacity`. - The `@vaadin/common-frontend` import no longer works after vaadin/flow#26714. ## Test summary - `npm run check-redirects` passes. - `mvn spotless:apply` and `mvn compile` pass. `npx eslint frontend/demo/fusion/i18n` passes. - The two TypeScript examples type-check and run in the scratch application, in English and German. - Checked with the browser: - translations, the ICU plural form, `{0}` placeholders, the missing-key marker, on-demand keys and their warning; - the cookie, the fallback from `de-DE` to `de` and the root file, and the separate Flow locale; - a custom provider without `getAllTranslations()` in development mode (no translations; `initialized` stays `false`); - the loading bar stages during a slow service call, the offline message after a failed call and after the browser's `offline` event, and the online message afterwards; - the reconnecting message of a Flow view with the server stopped; - the TypeScript configuration, the Java configuration overriding only the properties it sets, and the corrected curtain CSS; - global styles, a plain CSS import that stays loaded after navigating away, and a CSS module. - Every cross reference in the new and changed lines resolves. - Vale: no errors or warnings on the added and changed lines with the pull request configuration. - Asciidoctor renders the changed pages, with all includes and tags resolved. - I didn't run a full dspublisher build locally. The TypeScript configuration snippet for the indicator is inline: the docs build is on 25.4.0-alpha5, whose `Flow.js` still uses `@vaadin/common-frontend`, so a compiled example importing the new module wouldn't build yet. Product bugs found during testing, reported separately: - vaadin/flow#26970: `types.d.ts` doesn't declare CSS imports, so with TypeScript 6 the imports in React views fail the type check. The Stylesheets section documents the declarations to add. - vaadin/hilla#7050: after `setLanguage()`, a key that `translateDynamic()` loaded on demand stays empty. The page doesn't describe this behavior. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Review risk: two-way door. Docs and examples only: six new pages, nine removed pages with redirects, new and rewritten form examples, and link updates. Reverting brings the old pages back.
Summary
Moves the React form binding reference from the Hilla section to the React Views section of the Flow Reference (
articles/flow/react-views/forms/). This is the fifth step of dissolving the Hilla section, after #6611, #6616, #6618 and #6620. Security follows in the next pull request.The pages are rewritten for 25.4, where the generated form models are
@vaadin/hilla-modelsbuilder constants (vaadin/hilla#6249) and the model classes are gone (vaadin/hilla#6635). The old pages showedAbstractModel,ObjectModelsubclasses andcreateEmptyValue(), which no longer exist. Every statement is checked againstmainof vaadin/hilla, and every example ran in a scratch 25.4.0-alpha5 application with the models that the generator wrote for the example classes. This pull request targetsmainonly, so it gets notarget/v25.3label.What changed
flow/react-views/forms/:index.adoc: form models, binding fields, loading a value, submitting, and server-side validation.validation.adoc: the constraints that the browser checks, required fields, error messages, field and form validators, and errors that a service reports.form-state.adoc: the state properties, and changing values from code.nested-objects-arrays.adoc: nested objects withuseFormPart(), and lists withuseFormArrayPart().field-components.adoc: which Vaadin componentsfield()binds, and the Java types they edit.api.adoc: the hooks, their results, the validation types, and$defaultValue.fusion/forms/person(a person with an address and phone numbers) andfusion/forms/signup(field, form and server validators). The company office example now sets the city withsetValue()of its part, instead of changingform.valuedirectly, which the form doesn't notice. Its package uses@NullMarkedinstead of the deprecated@NonNullApi. The unusedContactexample and the Lit-era GIFs are removed.submit()rejects with aValidationErrorwhen the validation fails, soonClick={submit}gives an unhandled rejection. The examples catch it.@PastOrPresent,@FutureOrPresentand custom constraints are checked only on the server, and their errors appear after a submit.{min}placeholders are shown literally unlessBinderRoot.interpolateMessageCallbackis set.ValidationError.List Boxcan't be bound:field()throws.Switchdoesn't update the form value. The old page listed List Box as supported.useFormArrayPart()needs a non-nullable list, and new items come fromItemModel[$defaultValue].hilla/guides/formspages go to the matching new pages.binderandbinder-loadboth go to the forms index.form-imagesgoes to the current uploads page, which pull request 9 replaces. The ten Lit redirects that led to these pages now point straight at the new pages.Test summary
npm run check-redirectspasses.mvn spotless:applyandmvn compilepass.npm run lintpasses on the new and changed examples.Three Hilla behaviors came up during testing, and the pages describe them as they are:
field()doesn't read the state of aSwitch, because there's no field strategy forvaadin-switch(field() doesn't update the form value from a Switch hilla#7043).useFormArrayPart()doesn't accept the model of a nullable list (useFormArrayPart() doesn't accept the model of a nullable list hilla#7044).field()rejectsList Box, although lit-form has a strategy for it (field() throws for a ListBox although lit-form has a strategy for it hilla#7045).🤖 Generated with Claude Code