Merge branch 'latest' into docs/848/control-center-troubleshooting

Author: heruan

articles/_vaadin-version.adoc

@@ -1,4 +1,4 @@
-:vaadin-version: 24.7.0
+:vaadin-version: 24.7.1
 :vaadin-flow-version: 24.7.0
 :vaadin-seven-version: 7.7.38
 :vaadin-eight-version: 8.20.0

articles/building-apps/views/add-view/flow.adoc

@@ -186,7 +186,7 @@ com.example.application
             └── CUstomerDetailsView.java
 ----
 <1> The example feature is "customer relationship management".
-<2> All the views are in the same `view.ui` package.
+<2> All the views are in the same `ui.view` package.
 
 If the view consists of more than one class, consider creating a separate package for it, like this:
 
@@ -203,7 +203,7 @@ com.example.application
             └── CustomerDetailsView.java
 ----
 <1> The onboarding view consists of multiple classes and has its own package.
-<2> The other views remain in the `view.ui` package.
+<2> The other views remain in the `ui.view` package.
 
 If you don't know whether your new view is going to be small or large, start by putting it in the `ui.view` package. You can always refactor it into its own package later.
 
@@ -330,4 +330,4 @@ Now you've explored how to define and organize Flow views in a Vaadin applicatio
 * Work with multi-segment routes to create more readable and meaningful URLs.
 
 Next, see the <<../navigate#,Navigate to a View>> guide to learn how to navigate from one view to another.
-====
+====

articles/components/card/index.adoc

@@ -186,6 +186,7 @@ include::{root}/frontend/demo/component/card/react/card-header.tsx[render,tags=s
 endif::[]
 --
 
+You should add the title before the subtitle in the DOM order to make it the first announced element for screen reader users. You can use flexbox and the `order` CSS property to visually place the subtitle before the title without affecting the DOM order.
 
 === Header Prefix
 

articles/contributing/docs/types.adoc

@@ -0,0 +1,63 @@
+---
+title: Types of Documentation
+page-title: Types of Documentation | How to contribute to Vaadin Documentation
+description: Learn about the different types of Vaadin documentation - how-to guides, reference manuals, and deep dives - and understand best practices for writing each type effectively.
+meta-description: Learn about the different types of Vaadin documentation - how-to guides, reference manuals, and deep dives - and understand best practices for writing each type effectively.
+order: 5
+---
+
+= Types of Documentation
+
+In the Vaadin documentation, you'll find different types of guides and articles. Each serves a distinct purpose, so it's important to avoid mixing different types of content in the same guide to maintain clarity and usability.
+
+
+== How-to Guides
+
+A how-to guide helps the reader *perform a specific task* by offering practical, step-by-step instructions.
+
+When writing a how-to guide:
+
+* *Choose the best approach*: While multiple solutions may exist for a given task, present the one that works best in most scenarios. How-to guides should represent current best practices.
+* *Include just enough theory*: Provide sufficient background information for readers to understand the context, but reserve deeper explanations for deep dives or reference manuals.
+* *Ensure production readiness*: All instructions must be applicable in production environments. If you need to use mocks to keep the article focused, clearly identify these sections and provide resources explaining how to implement real-world solutions.
+* *Maintain appropriate scope*: If a guide becomes too lengthy, split it into smaller, interconnected guides with clear links between them.
+* *Add practical examples*: When possible, include a mini-tutorial at the end that applies the concepts to a <<{articles}/getting-started/start#,Walking Skeleton>> application. These tutorials can span multiple guides, with each building upon the previous one.
+
+Most how-to guides belong in the <<{articles}/building-apps#,Building Apps>> section, but you can place them elsewhere if more appropriate.
+
+[IMPORTANT]
+A new user should be able to become productive with Vaadin by reading the how-to guides alone, without needing to consult other documentation types.
+
+
+== Reference Manuals
+
+A reference manual provides factual explanations of *what features a product has* and *how they work*. How-to guides often build upon reference manuals and refer to them for detailed information.
+
+When writing a reference manual:
+
+* *Maintain neutrality*: Be less opinionated than in how-to guides. Avoid comparing features unless highlighting a deprecated feature and its replacement.
+* *Balance technical depth*: Include as much technical detail as benefits the reader, but consider moving design motivations and reasoning to deep dive articles or blog posts.
+* *Focus on completeness*: Ensure all product features are documented thoroughly and accurately.
+
+Every Vaadin product has its own dedicated reference manual.
+
+[IMPORTANT]
+When updating a reference manual, always review related how-to guides to ensure consistency across documentation.
+
+
+== Deep Dives
+
+Deep dives offer more abstract and comprehensive content than how-to guides and reference manuals. They are the *most opinionated* yet *least prescriptive* type of documentation.
+
+Deep dives can:
+
+* Explore reasoning behind design decisions or best practices
+* Offer insights, opinions, and alternative approaches
+* Provide architectural guidance and design philosophy
+* Discuss trade-offs and considerations when making complex decisions
+
+Consider deep dives as thought-provoking content rather than explicit instructions. They should enhance understanding but shouldn't be required reading for getting started with Vaadin.
+
+Deep dives need not directly relate to Vaadin products, but should align with Vaadin's mission of making Java-based application development and modernization faster and easier.
+
+Most deep dives appear in the <<{articles}/building-apps/deep-dives#,Building Apps>> section, but product-specific deep dives can be placed within their respective product documentation.

articles/control-center/application-deployment/index.adoc

@@ -46,7 +46,7 @@ To deploy the application to a Kubernetes cluster, you'll need to create a Docke
 
 [source,docker]
 ----
-FROM eclipse-temurin:17-jre
+FROM eclipse-temurin:21-jre
 COPY target/*.jar app.jar
 EXPOSE 8080
 ENTRYPOINT ["java", "-jar", "/app.jar"]

articles/control-center/identity-management/index.adoc

@@ -6,7 +6,6 @@ meta-description: Learn how to configure identity management in Vaadin Control C
 order: 30
 ---
 
-
 = Identity Management
 
 Control Center provides powerful tools to manage users, groups, roles, and identity providers for Vaadin applications deployed in a Kubernetes cluster. These features are essential for controlling access to various parts of an application and providing secure authentication and authorization for users.
@@ -43,14 +42,17 @@ Once you're in the user creation form, fill in the required fields:
 - *First Name* & **Last Name**: The user's display name.
 - *Email Address*: This is used for the user's login.
 - *Password*: Set an initial password for the user. You can also enable the [guilabel]*Request password change* option to force the user to change this password at the next login.
-- *Multi-Factor Authentication*: Enable MFA to require the user to verify their identity with an additional factor, such as an authenticator application.
-- *Password-less authentication*: Allow the user to authenticate using a passkey instead of their password. When enabled, the user must register a passkey on their next login.
+- [.commercial]*Multi-Factor Authentication*: Enable MFA to require the user to verify their identity with an additional factor, such as an authenticator application.
+- [.commercial]*Password-less authentication*: Allow the user to authenticate using a passkey instead of their password. When enabled, the user must register a passkey on their next login.
 
 Once all of the information has been entered, click [guibutton]*Create* to finalize the process. The new user account should appear in the list of users for the application.
 
 
 == Alternative Authentication Methods
 
+:commercial-feature: MFA & Password-less authentication
+include::{articles}/_commercial-banner.adoc[opts=optional]
+
 Control Center offers a couple of alternatives to password-only authentication for deployed applications.
 These alternative authentication methods can be enabled on a per user basis.
 Applications deployed with Control Center can enable two-factor authentication using One-Time Passcode.
@@ -60,6 +62,7 @@ Password-less authentication is available through the use of Passkeys.
 image::images/authentication-selector.png[Authentication Selector]
 
 
+[.commercial]
 === One-Time Passcode
 
 One-Time Passcodes can only be used as a second factor of authentication, and not on their own as single factor of authentication.
@@ -72,6 +75,7 @@ If OTP is then disabled and re-enabled for a user, they will have to register th
 image::images/otp-config.png[OTP Configuration]
 
 
+[.commercial]
 === Authenticating with Passkeys
 
 Each user of any deployed application in Control Center can have an alternative authentication method that lets them authenticate using a passkey instead of a password.
@@ -136,6 +140,9 @@ After creating an identity provider, you can find it in the *Identity Providers*
 [.device]
 image::images/provider-detail.png[Identity Provider Detail Form]
 
+[.commercial]
+=== Custom Identity Provider
+
 When you want to create a custom OpenID Connect 1.0 provider, you'll also need to specify the `Discovery Endpoint`. This is used during the provider creation to get relevant metadata from the external provider. The endpoint URL has a specific format: It always ends with the `.well-known/openid-configuration` path. (e.g., `https://1234-admin.okta.com/.well-known/openid-configuration`). Usually, you can find the discovery endpoint in the client details after you create it with the external provider. As an example, creating an Okta provider looks like this:
 
 [.device]

articles/control-center/index.adoc

@@ -35,7 +35,8 @@ Key capabilities include the following:
 - *Authentication Enforcement*: Configure your applications to require user authentication seamlessly, enhancing security.
 - *Intuitive Management Interface*: Use Control Center's user-friendly UI to create and manage users, groups, and roles, efficiently.
 - *External Identity Provider Integration*: Connect to external identity providers, such as social accounts (e.g., Google, Facebook) or other OpenID Connect providers, offering flexible authentication options to your users.
-- *Multi-Factor Authentication*: Increase security by enabling MFA, allowing users to authenticate using an authenticator application for an additional layer of protection.
+- [.commercial]*Multi-Factor Authentication*: Increase security by enabling MFA, allowing users to authenticate using an authenticator application for an additional layer of protection.
+- [.commercial]*Password-less Authentication*: Effortless login with passkeys, allowing users to authenticate without having to remember a password or running the risk of using an insecure or repeated password.
 
 Implementing MFA can significantly reduce the risk of unauthorized access, safeguarding sensitive data within your applications.
 

articles/flow/advanced/server-client-communication.adoc

@@ -27,7 +27,7 @@ The `syncId` is always incremented by 1 after a new UIDL response is generated.
 
 === clientId
 
-The `clientId` holds the latest communication state identifier given by the client. The client token is incremented on the client after sending the message. The server increments the value in the response to match the next expected `clientId` (i.e., client updated after message sent).
+The `clientId` holds the latest communication state identifier given by the client. The client token is incremented on the client after sending the message, but only if the client has already received a response from the server to the previously sent message. Until this response has been received, the client attempts to resend the message until some kind of response is received, and the messages generated during that time are placed in a queue to wait. Once the server has received the message from the client, it increments the token value in the response to match the next expected `clientId` (i.e., client updated after message sent).
 
 On the client, pending messages are removed from the queue as handled when `clientId` from server matches the next expected value. If the id is less than expected, the client waits since the server has not yet seen all messages. The response should arrive later. Otherwise, the client trusts the server and updates the id to the server's expectations.
 

articles/flow/configuration/live-reload/index.adoc

@@ -45,6 +45,7 @@ In general, JRebel and HotswapAgent are faster as they only patch one class in m
 
 The user session is also handled differently: as JRebel and HotswapAgent do not restart the server, the user session is preserved. With Spring Developer Tools, you lose the user session unless you ensure all parts are serializable and you turn on session serialization for development mode (see <<{articles}/flow/configuration/properties#,Configuration Properties>>).
 
+When Vaadin is notified about a class change that affects a view currently displayed in the browser, it determines the best strategy to refresh the contents; in most cases the page is refreshed without a full page reload. However, if needed, Vaadin can be forced to always trigger a full page reload by setting the `vaadin.hotswap.forcePageReload` system property (`-Dvaadin.hotswap.forcePageReload=true`).
 
 == Automatic Server Restart
 

articles/flow/configuration/maven.adoc

@@ -119,6 +119,9 @@ Clears the generated frontend files after building a project for production. It
 `frontendExtraFileExtensions`::
 Parameter for adding file extensions to a handle when generating bundles.
 
+`frontendIgnoreVersionChecks`::
+Makes Flow skip node and npm/pnpm/bun version checks during bundle build and development server startup. Note that disabling frontend tools version checking can cause failing builds and other issues that are difficult to debug.
+
 
 === Build Frontend Goal Parameters
 

articles/flow/configuration/properties.adoc

@@ -225,6 +225,14 @@ Bundle parameter controls parts of frontend bundle creation.
 |`false`
 |Development
 
+|`frontend.hotdeploy.dependencies`
+|`vaadin.frontend.hotdeploy.dependencies`
+|A comma-separated list of module directories to watch for frontend file changes when detecting hot-deployable resources. Entries need to point to directories relative to the module that starts the Vaadin application, and can point to the module itself as well, in case it provides frontend files as resources. The value could be for example "./,./component-module-1,./component-module-2". Flow will watch for changes in both `src/main/resources/META-INF/resources/frontend` and the legacy `src/main/resources/META-INF/frontend` directories under the given three directory entries.
+
+Do note that if this parameter is not defined, Vaadin wathes for changes under `src/main/resources/META-INF/` in the module that starts the Vaadin application, but when you provide a custom value for the parameter you need to add "./" to the list of directories to watch for the same effect.
+|``
+|Development
+
 |`heartbeatInterval`
 |`vaadin.heartbeatInterval`
 |Sets the heartbeat interval time. UIs that are open on the client-side send a regular heartbeat to the server indicating that they're still active even without ongoing user interaction. When the server doesn't receive a valid heartbeat from a given UI within a certain amount of time, it removes that UI from the session. The interval value is expressed in `seconds`. See also `closeIdleSessions`.
@@ -401,6 +409,12 @@ The following table contains the properties that are used only by the Vaadin Mav
 |`null`
 |Build
 
+|`frontendIgnoreVersionChecks`
+|`vaadin.ignoreVersionChecks`
+|Makes Flow skip node and npm/pnpm/bun version checks during bundle build and development server startup. Note that disabling frontend tools version checking can cause failing builds and other issues that are difficult to debug.
+|
+|Development, Bundle
+
 |`javaSourceFolder`
 |
 |Source folder used for component scanning during development mode.

articles/flow/routing/layout.adoc

@@ -8,10 +8,11 @@ order: 40
 
 
 = Router Layouts & Nested Router Targets
+:toclevels: 2
 
 All parent layouts of a navigation target component have to implement the [interfacename]`RouterLayout` interface. You can define a parent layout by adding the [annotationname]`@Layout` annotation to the class, or by using the optional element `layout` from the `@Route` annotation.
 
-[interfacename]`RouterLayout` interface appends and removes child route content during navigation. For more in depth information, see <<#Router Layout,Router Layout>>.
+[interfacename]`RouterLayout` interface appends and removes child route content during navigation. For more in depth information, see the <<#router-layout,Router Layout>> section below.
 
 
 [role="since:com.vaadin:[email protected]"]

articles/flow/security/enabling-security.adoc

@@ -517,6 +517,50 @@ For more information about navigation access control consult the <<{articles}/fl
 
 Vaadin strongly recommends not to mix Spring's URL-pattern-based HTTP security and this view-based access control mechanism targeting the same views. Doing so might cause unwanted access configurations, and would be an unnecessary complication in the authorization of views.
 
+== Spring Concurrency Support with Vaadin
+
+Spring Security provides built-in https://docs.spring.io/spring-security/reference/servlet/integrations/concurrency.html[concurrency support] to propagate security contexts across asynchronous operations. One of the key components for this is [classname]`DelegatingSecurityContextExecutor`, which wraps an [classname]`Executor` and ensures that the [classname]`SecurityContext` is properly propagated to background tasks.
+
+In a Vaadin application, [classname]`VaadinSecurityContextHolderStrategy` should be initialized before any custom [classname]`DelegatingSecurityContextExecutor` bean is created. This ensures that the correct security context holder is used, preventing potential issues with authentication propagation in async tasks.
+
+To guarantee that [classname]`VaadinSecurityContextHolderStrategy` is set before the [classname]`DelegatingSecurityContextExecutor` bean is instantiated, consider the following approaches:
+
+* add `@DependsOn("VaadinSecurityContextHolderStrategy")` to the custom [classname]`DelegatingSecurityContextExecutor` bean definition to explicitly enforce the initialization order
+* instead of relying on implicit ordering, have [classname]`VaadinSecurityContextHolderStrategy` directly injected into the bean method definition and manually wire it into the [classname]`DelegatingSecurityContextExecutor` instance.
+
+
+[source,java]
+.Using @DependsOn
+----
+@Bean
+@DependsOn("VaadinSecurityContextHolderStrategy")
+public DelegatingSecurityContextAsyncTaskExecutor taskExecutor() {
+    var delegate = new ThreadPoolTaskExecutor();
+    //configure the executor
+    delegate.initialize();
+
+    return new DelegatingSecurityContextAsyncTaskExecutor(delegate);
+}
+----
+
+[source,java]
+.Injecting VaadinSecurityContextHolderStrategy Manually
+----
+@Bean
+public DelegatingSecurityContextAsyncTaskExecutor taskExecutor(
+    VaadinAwareSecurityContextHolderStrategy strategy) {
+    var delegate = new ThreadPoolTaskExecutor();
+    //configure the executor
+    delegate.initialize();
+
+    var executor = new DelegatingSecurityContextAsyncTaskExecutor(delegate);
+    executor.setSecurityContextHolderStrategy(strategy);
+    return executor;
+}
+----
+
+By applying either of these solutions, you ensure that the correct security context holder is used for asynchronous task execution in a Vaadin application.
+
 
 == Spring Impersonation with Vaadin