feat: eagerly load ExtendedClientDetails during UI initialization (#22719)

* feat: eagerly load ExtendedClientDetails during UI initialization

Browser details (ExtendedClientDetails) are now automatically fetched
during UI initialization and available immediately in the UI constructor,
eliminating the need for asynchronous callbacks in most cases.

API changes:
- Page.getExtendedClientDetails(): Now always returns a non-null instance
  (creates placeholder with default values if not yet fetched). Browser
  details are automatically populated during normal UI initialization.

- ExtendedClientDetails.refresh(Consumer): New method to refresh cached
  browser details with fresh values from the browser. Callback is invoked
  when refresh completes.

- Page.retrieveExtendedClientDetails(ExtendedClientDetailsReceiver):
  Deprecated. Use getExtendedClientDetails() to access cached details, or
  ExtendedClientDetails.refresh() to update them.

Migration guide:
  Before:
    page.retrieveExtendedClientDetails(details -> {
        int width = details.getScreenWidth();
    });

  After:
    ExtendedClientDetails details = page.getExtendedClientDetails();
    int width = details.getScreenWidth(); // Available immediately

    // Or refresh if needed:
    details.refresh(updated -> {
        int width = updated.getScreenWidth();
    });

Benefits:
- No null checks needed when accessing browser details
- Browser details available immediately in UI constructor/onAttach
- Simpler synchronous API for common use cases
- Full backward compatibility maintained

* Make browser details collection available before init request completes

The browser details collection function getBrowserDetailsParameters was
previously defined in FlowBootstrap.js, which was loaded after the init
request. This caused the function to be undefined when Flow.ts tried to
collect browser details to send with the ?v-r=init request.

This change moves the browser details collection logic from
FlowBootstrap.js into Flow.ts as a private method collectBrowserDetails(),
and registers it as window.Vaadin.Flow.getBrowserDetailsParameters in the
Flow constructor. This ensures the function is available when needed
during the init request, while maintaining backward compatibility for code
that calls the function via the global window object.

The TypeScript implementation uses ($wnd as any) casts to access window
properties like screen, document, navigator, etc., since the $wnd type
doesn't include all browser DOM APIs. Values are stringified before
returning to match the original JavaScript implementation.

Also adds integration test to verify browser details are available
immediately on page load without user interaction.

* Make getExtendedClientDetails() always return non-null

Browser details are now sent eagerly with the init request, but
getExtendedClientDetails() could still return null before the data
arrives. This changes the API to always return a non-null instance,
using a placeholder with default values (screenWidth = -1, windowName
= null) until actual browser details are available.

For PreserveOnRefresh functionality, the code now checks if windowName
is null rather than checking if the entire ExtendedClientDetails object
is null. This is necessary because:
- Screen dimensions are always sent with the init request
- But window.name may be empty/undefined in new browser windows
- This causes windowName = null even when other details are present
- Different windows with windowName = null would incorrectly share
  cached components

Changes:
- Made ExtendedClientDetails constructor public (marked as internal-only)
- UIInternals.getExtendedClientDetails() creates placeholder if null
- Page.getExtendedClientDetails() simplified to delegate to UIInternals
- Page.retrieveExtendedClientDetails() checks screenWidth == -1
- AbstractNavigationStateRenderer: Changed 3 locations to check
  windowName == null instead of details == null
- WebComponentUI: Changed to check windowName == null

This fixes PreserveOnRefreshIT.refreshInDifferentWindow_componentIsRecreated
test failure where components were incorrectly preserved across different
browser windows due to cache key collisions.

* Tweak details

Author: Artur-

flow-client/src/main/frontend/Flow.ts

@@ -120,6 +120,8 @@ export class Flow {
         isActive: () => this.isActive
       }
     };
+    // Set browser details collection function as global for use by refresh()
+    ($wnd.Vaadin.Flow as any).getBrowserDetailsParameters = this.collectBrowserDetails.bind(this);
 
     // Regular expression used to remove the app-context
     const elm = document.head.querySelector('base');
@@ -425,9 +427,16 @@ export class Flow {
     return new Promise((resolve, reject) => {
       const xhr = new XMLHttpRequest();
       const httpRequest = xhr as any;
+
+      // Collect browser details to send with init request as JSON
+      const browserDetails = this.collectBrowserDetails();
+      const browserDetailsParam = browserDetails
+        ? `&v-browserDetails=${encodeURIComponent(JSON.stringify(browserDetails))}`
+        : '';
+
       const requestPath = `?v-r=init&location=${encodeURIComponent(
         this.getFlowRoutePath(location)
-      )}&query=${encodeURIComponent(this.getFlowRouteQuery(location))}`;
+      )}&query=${encodeURIComponent(this.getFlowRouteQuery(location))}${browserDetailsParam}`;
 
       httpRequest.open('GET', requestPath);
 
@@ -452,6 +461,95 @@ export class Flow {
     });
   }
 
+  // Collects browser details parameters
+  private collectBrowserDetails(): Record<string, string> {
+    const params: Record<string, any> = {};
+
+    /* Screen height and width */
+    params['v-sh'] = ($wnd as any).screen.height;
+    params['v-sw'] = ($wnd as any).screen.width;
+    /* Browser window dimensions */
+    params['v-wh'] = ($wnd as any).innerHeight;
+    params['v-ww'] = ($wnd as any).innerWidth;
+    /* Body element dimensions */
+    params['v-bh'] = ($wnd as any).document.body.clientHeight;
+    params['v-bw'] = ($wnd as any).document.body.clientWidth;
+
+    /* Current time */
+    const date = new Date();
+    params['v-curdate'] = date.getTime();
+
+    /* Current timezone offset (including DST shift) */
+    const tzo1 = date.getTimezoneOffset();
+
+    /* Compare the current tz offset with the first offset from the end
+       of the year that differs --- if less that, we are in DST, otherwise
+       we are in normal time */
+    let dstDiff = 0;
+    let rawTzo = tzo1;
+    for (let m = 12; m > 0; m -= 1) {
+      date.setUTCMonth(m);
+      const tzo2 = date.getTimezoneOffset();
+      if (tzo1 !== tzo2) {
+        dstDiff = tzo1 > tzo2 ? tzo1 - tzo2 : tzo2 - tzo1;
+        rawTzo = tzo1 > tzo2 ? tzo1 : tzo2;
+        break;
+      }
+    }
+
+    /* Time zone offset */
+    params['v-tzo'] = tzo1;
+
+    /* DST difference */
+    params['v-dstd'] = dstDiff;
+
+    /* Time zone offset without DST */
+    params['v-rtzo'] = rawTzo;
+
+    /* DST in effect? */
+    params['v-dston'] = tzo1 !== rawTzo;
+
+    /* Time zone id (if available) */
+    try {
+      params['v-tzid'] = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    } catch (err) {
+      params['v-tzid'] = '';
+    }
+
+    /* Window name */
+    if (($wnd as any).name) {
+      params['v-wn'] = ($wnd as any).name;
+    }
+
+    /* Detect touch device support */
+    let supportsTouch = false;
+    try {
+      ($wnd as any).document.createEvent('TouchEvent');
+      supportsTouch = true;
+    } catch (e) {
+      /* Chrome and IE10 touch detection */
+      supportsTouch = 'ontouchstart' in $wnd || typeof ($wnd as any).navigator.msMaxTouchPoints !== 'undefined';
+    }
+    params['v-td'] = supportsTouch;
+
+    /* Device Pixel Ratio */
+    params['v-pr'] = ($wnd as any).devicePixelRatio;
+
+    if (($wnd as any).navigator.platform) {
+      params['v-np'] = ($wnd as any).navigator.platform;
+    }
+
+    /* Stringify each value (they are parsed on the server side) */
+    const stringParams: Record<string, string> = {};
+    Object.keys(params).forEach((key) => {
+      const value = params[key];
+      if (typeof value !== 'undefined') {
+        stringParams[key] = value.toString();
+      }
+    });
+    return stringParams;
+  }
+
   // Create shared connection state store and connection indicator
   private addConnectionIndicator() {
     // add connection indicator to DOM

flow-client/src/main/frontend/FlowBootstrap.js

@@ -183,92 +183,6 @@ Please submit an issue to https://github.com/vaadin/flow-components/issues/new/c
         ws.pendingApps = null;
       }
     };
-    window.Vaadin.Flow.getBrowserDetailsParameters = function () {
-      var params = {};
-
-      /* Screen height and width */
-      params['v-sh'] = window.screen.height;
-      params['v-sw'] = window.screen.width;
-      /* Browser window dimensions */
-      params['v-wh'] = window.innerHeight;
-      params['v-ww'] = window.innerWidth;
-      /* Body element dimensions */
-      params['v-bh'] = document.body.clientHeight;
-      params['v-bw'] = document.body.clientWidth;
-
-      /* Current time */
-      var date = new Date();
-      params['v-curdate'] = date.getTime();
-
-      /* Current timezone offset (including DST shift) */
-      var tzo1 = date.getTimezoneOffset();
-
-      /* Compare the current tz offset with the first offset from the end
-         of the year that differs --- if less that, we are in DST, otherwise
-         we are in normal time */
-      var dstDiff = 0;
-      var rawTzo = tzo1;
-      for (var m = 12; m > 0; m--) {
-        date.setUTCMonth(m);
-        var tzo2 = date.getTimezoneOffset();
-        if (tzo1 != tzo2) {
-          dstDiff = tzo1 > tzo2 ? tzo1 - tzo2 : tzo2 - tzo1;
-          rawTzo = tzo1 > tzo2 ? tzo1 : tzo2;
-          break;
-        }
-      }
-
-      /* Time zone offset */
-      params['v-tzo'] = tzo1;
-
-      /* DST difference */
-      params['v-dstd'] = dstDiff;
-
-      /* Time zone offset without DST */
-      params['v-rtzo'] = rawTzo;
-
-      /* DST in effect? */
-      params['v-dston'] = tzo1 != rawTzo;
-
-      /* Time zone id (if available) */
-      try {
-        params['v-tzid'] = Intl.DateTimeFormat().resolvedOptions().timeZone;
-      } catch (err) {
-        params['v-tzid'] = '';
-      }
-
-      /* Window name */
-      if (window.name) {
-        params['v-wn'] = window.name;
-      }
-
-      /* Detect touch device support */
-      var supportsTouch = false;
-      try {
-        document.createEvent('TouchEvent');
-        supportsTouch = true;
-      } catch (e) {
-        /* Chrome and IE10 touch detection */
-        supportsTouch = 'ontouchstart' in window || typeof navigator.msMaxTouchPoints !== 'undefined';
-      }
-      params['v-td'] = supportsTouch;
-
-      /* Device Pixel Ratio */
-      params['v-pr'] = window.devicePixelRatio;
-
-      if (navigator.platform) {
-        params['v-np'] = navigator.platform;
-      }
-
-      /* Stringify each value (they are parsed on the server side) */
-      Object.keys(params).forEach(function (key) {
-        var value = params[key];
-        if (typeof value !== 'undefined') {
-          params[key] = value.toString();
-        }
-      });
-      return params;
-    };
   }
 
   log('Flow bootstrap loaded');

flow-server/src/main/java/com/vaadin/flow/component/internal/UIInternals.java

@@ -1347,12 +1347,20 @@ public UI getUI() {
     }
 
     /**
-     * The extended client details, if obtained, are cached in this field.
+     * Returns the extended client details. If browser details have not been
+     * received yet, returns a placeholder instance with default values (all
+     * dimensions set to -1). The placeholder will be updated with actual values
+     * when the browser details are received.
      *
-     * @return the extended client details, or {@literal null} if not yet
-     *         received.
+     * @return the extended client details (never {@code null})
      */
     public ExtendedClientDetails getExtendedClientDetails() {
+        if (extendedClientDetails == null) {
+            // Create placeholder with default values
+            extendedClientDetails = new ExtendedClientDetails(ui, null, null,
+                    null, null, null, null, null, null, null, null, null, null,
+                    null, null, null, null);
+        }
         return extendedClientDetails;
     }
 

flow-server/src/main/java/com/vaadin/flow/component/page/ExtendedClientDetails.java

@@ -18,21 +18,32 @@
 import java.io.Serializable;
 import java.util.Date;
 import java.util.TimeZone;
+import java.util.function.Consumer;
+import java.util.function.Function;
 
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.node.JsonNodeType;
+import tools.jackson.databind.node.ObjectNode;
+
+import com.vaadin.flow.component.UI;
+import com.vaadin.flow.function.SerializableConsumer;
 import com.vaadin.flow.server.VaadinSession;
 
 /**
  * Provides extended information about the web browser, such as screen
  * resolution and time zone.
  * <p>
- * Please note that all information is fetched only once, and <em>not updated
- * automatically</em>. To retrieve updated values, you can execute JS with
- * {@link Page#executeJs(String, Object...)} and get the current value back.
+ * Browser details are automatically fetched on the first call to
+ * {@link Page#getExtendedClientDetails()} and cached for the lifetime of the
+ * UI. The fetch happens asynchronously, so the first call may return
+ * {@code null} while the data is being retrieved. To update the cached values
+ * with fresh data from the browser, use {@link #refresh(Consumer)}.
  *
  * @author Vaadin Ltd
  * @since 2.0
  */
 public class ExtendedClientDetails implements Serializable {
+    private final UI ui;
     private int screenWidth = -1;
     private int screenHeight = -1;
     private int windowInnerWidth = -1;
@@ -54,6 +65,8 @@ public class ExtendedClientDetails implements Serializable {
      * For internal use only. Updates all properties in the class according to
      * the given information.
      *
+     * @param ui
+     *            the UI instance that owns this ExtendedClientDetails
      * @param screenWidth
      *            Screen width
      * @param screenHeight
@@ -88,13 +101,14 @@ public class ExtendedClientDetails implements Serializable {
      * @param navigatorPlatform
      *            navigation platform received from the browser
      */
-    ExtendedClientDetails(String screenWidth, String screenHeight,
+    public ExtendedClientDetails(UI ui, String screenWidth, String screenHeight,
             String windowInnerWidth, String windowInnerHeight,
             String bodyClientWidth, String bodyClientHeight, String tzOffset,
             String rawTzOffset, String dstShift, String dstInEffect,
             String tzId, String curDate, String touchDevice,
             String devicePixelRatio, String windowName,
             String navigatorPlatform) {
+        this.ui = ui;
         if (screenWidth != null) {
             try {
                 this.screenWidth = Integer.parseInt(screenWidth);
@@ -382,4 +396,82 @@ public boolean isIOS() {
                 || (navigatorPlatform != null
                         && navigatorPlatform.startsWith("iPod"));
     }
+
+    /**
+     * Creates an ExtendedClientDetails instance from browser details JSON
+     * object. This is intended for internal use when browser details are
+     * provided as JSON (e.g., during UI initialization or refresh).
+     * <p>
+     * For internal use only.
+     *
+     * @param ui
+     *            the UI instance that owns this ExtendedClientDetails
+     * @param json
+     *            the JSON object containing browser details parameters
+     * @return a new ExtendedClientDetails instance
+     * @throws RuntimeException
+     *             if the JSON is not a valid object
+     */
+    public static ExtendedClientDetails fromJson(UI ui, JsonNode json) {
+        if (!(json instanceof ObjectNode)) {
+            throw new RuntimeException("Expected a JSON object");
+        }
+        final ObjectNode jsonObj = (ObjectNode) json;
+
+        // Note that JSON returned is a plain string -> string map, the actual
+        // parsing of the fields happens in ExtendedClient's constructor. If a
+        // field is missing or the wrong type, pass on null for default.
+        final Function<String, String> getStringElseNull = key -> {
+            final JsonNode jsValue = jsonObj.get(key);
+            if (jsValue != null
+                    && JsonNodeType.STRING.equals(jsValue.getNodeType())) {
+                return jsValue.asString();
+            } else {
+                return null;
+            }
+        };
+
+        return new ExtendedClientDetails(ui, getStringElseNull.apply("v-sw"),
+                getStringElseNull.apply("v-sh"),
+                getStringElseNull.apply("v-ww"),
+                getStringElseNull.apply("v-wh"),
+                getStringElseNull.apply("v-bw"),
+                getStringElseNull.apply("v-bh"),
+                getStringElseNull.apply("v-tzo"),
+                getStringElseNull.apply("v-rtzo"),
+                getStringElseNull.apply("v-dstd"),
+                getStringElseNull.apply("v-dston"),
+                getStringElseNull.apply("v-tzid"),
+                getStringElseNull.apply("v-curdate"),
+                getStringElseNull.apply("v-td"),
+                getStringElseNull.apply("v-pr"),
+                getStringElseNull.apply("v-wn"),
+                getStringElseNull.apply("v-np"));
+    }
+
+    /**
+     * Refreshes the browser details by fetching updated values from the
+     * browser. The refresh happens asynchronously. The cached values in this
+     * instance will be updated when the browser responds, and then the provided
+     * callback will be invoked with the updated details.
+     *
+     * @param callback
+     *            a callback that will be invoked with the updated
+     *            ExtendedClientDetails when the refresh is complete
+     */
+    public void refresh(Consumer<ExtendedClientDetails> callback) {
+        final String js = "return Vaadin.Flow.getBrowserDetailsParameters();";
+        final SerializableConsumer<JsonNode> resultHandler = json -> {
+            ExtendedClientDetails details = fromJson(ui, json);
+            ui.getInternals().setExtendedClientDetails(details);
+            if (callback != null) {
+                callback.accept(details);
+            }
+        };
+        final SerializableConsumer<String> errorHandler = err -> {
+            throw new RuntimeException("Unable to retrieve extended "
+                    + "client details. JS error is '" + err + "'");
+        };
+        ui.getPage().executeJs(js).then(resultHandler, errorHandler);
+    }
 }