refactor!: redesign Geolocation as static utility with watcher handle (#24279)

Redesigns the Geolocation API as a static utility class with a watcher
handle, replacing the previous per-UI facade.
*API surface*
Geolocation.getPosition() and Geolocation.watchPosition() are static. UI
is implicit (UI.getCurrent()), with explicit-UI overloads for background
threads. watchPosition() returns a GeolocationWatcher handle that
exposes both a callback API (addPositionListener) and a reactive
Signal<GeolocationResult>.
The owner component drives the watcher's lifecycle: watchPosition()
accepts an unattached owner and starts the underlying browser watch on
first attach (so it's safe from a view constructor); the watch
auto-stops on detach; stop() and resume() work explicitly. Per-UI state
(the GeolocationClient and the availability signal) lives in
UIInternals; static methods resolve the client there or install a
default one through the GeolocationClientFactory Lookup SPI.
options is now a non-null parameter — callers who want browser defaults
use the no-options overloads, or pass an empty GeolocationOptions
explicitly. The fields inside GeolocationOptions remain independently
optional.
 
*Error model*
                                                                
Callback exceptions thrown from onSuccess/onError in getPosition and
from watcher position listeners are routed to
VaadinSession.getErrorHandler() instead of being silently swallowed by
CompletableFuture.whenComplete or aborting the listener loop.
GeolocationError.message() is renamed to debugInfo() to make it clear
the value is a free-form, non-localised string suitable for logs and bug
reports — not for UI display.
*Test seam*

GeolocationClient and WatchHandle become public so external test drivers
and native bridges can replace the production client through Lookup.
GeolocationOutcome becomes package-private since the public API no
longer exposes it. The watcher's bridge-failure error path is unchanged.

Author: Artur-

DESIGN_GUIDELINES.md

@@ -31,10 +31,9 @@ holds `private final UI ui`, and all `executeJs` calls go through
 `ui.getElement()` or `ui.getPage()`. Follow the `Page` / `History`
 pattern. Enforce single-instance creation in the constructor if needed.
 
-If the facade hands out a stateful handle (e.g.
-`Geolocation.watchPosition()` returning a `GeolocationWatcher`), make the
-handle's constructor **package-private** so application code cannot bypass
-the facade.
+If a feature hands out a stateful handle (e.g. `Geolocation.watchPosition()`
+returning a `GeolocationWatcher`), make the handle's constructor
+**package-private** so application code cannot bypass the entry point.
 
 ### Keep internal mutators off user-facing classes
 

flow-server/src/main/java/com/vaadin/flow/component/UI.java

@@ -32,7 +32,6 @@
 import tools.jackson.databind.node.BaseJsonNode;
 
 import com.vaadin.flow.component.dependency.JsModule;
-import com.vaadin.flow.component.geolocation.Geolocation;
 import com.vaadin.flow.component.internal.JavaScriptNavigationStateRenderer;
 import com.vaadin.flow.component.internal.UIInternalUpdater;
 import com.vaadin.flow.component.internal.UIInternals;
@@ -136,8 +135,6 @@ public class UI extends Component
 
     private final Page page;
 
-    private final Geolocation geolocation;
-
     /*
      * Despite section 6 of RFC 4122, this particular use of UUID *is* adequate
      * for security capabilities. Type 4 UUIDs contain 122 bits of random data,
@@ -168,7 +165,6 @@ protected UI(UIInternalUpdater internalsHandler) {
         Component.setElement(this, Element.get(getNode()));
         pushConfiguration = new PushConfigurationImpl(this);
         page = new Page(this);
-        geolocation = new Geolocation(this);
     }
 
     /**
@@ -951,16 +947,6 @@ public Page getPage() {
         return page;
     }
 
-    /**
-     * Returns the {@link Geolocation} facade for this UI, used to read the end
-     * user's physical location from the browser.
-     *
-     * @return the Geolocation facade
-     */
-    public Geolocation getGeolocation() {
-        return geolocation;
-    }
-
     /**
      * Updates this UI to show the view corresponding to the given navigation
      * target.

flow-server/src/main/java/com/vaadin/flow/component/geolocation/BrowserGeolocationClient.java

@@ -77,7 +77,7 @@ private record AvailabilityDetail(
 
     @Override
     public CompletableFuture<GeolocationOutcome> get(
-            @Nullable GeolocationOptions options) {
+            GeolocationOptions options) {
         CompletableFuture<GeolocationOutcome> future = new CompletableFuture<>();
         ui.getElement()
                 .executeJs("return window.Vaadin.Flow.geolocation.get($0)",
@@ -98,8 +98,7 @@ public CompletableFuture<GeolocationOutcome> get(
     }
 
     @Override
-    public WatchHandle startWatch(Component owner,
-            @Nullable GeolocationOptions options,
+    public WatchHandle startWatch(Component owner, GeolocationOptions options,
             SerializableConsumer<GeolocationResult> onUpdate) {
         return new BrowserWatchHandle(owner, options, onUpdate);
     }
@@ -154,8 +153,7 @@ private final class BrowserWatchHandle implements WatchHandle {
         private @Nullable DomListenerRegistration errorListener;
         private boolean active = true;
 
-        BrowserWatchHandle(Component owner,
-                @Nullable GeolocationOptions options,
+        BrowserWatchHandle(Component owner, GeolocationOptions options,
                 SerializableConsumer<GeolocationResult> onUpdate) {
             this.owner = owner;
             Element el = owner.getElement();