feat: add Geolocation API (#23527)

## Summary

- Adds a per-UI `Geolocation` facade (`UI.getGeolocation()`) that wraps
the browser's Geolocation API with a one-shot `get(...)` request, a
reactive `track(Component)` session, and an `availabilitySignal()`
reporting capability/permission state.
- Results use sealed types designed for exhaustive pattern matching:
`GeolocationOutcome` (`GeolocationPosition` | `GeolocationError`) for
one-shot reads, and `GeolocationResult` (adds `GeolocationPending`) for
the tracker's signal before the first fix arrives.
- Availability is delivered synchronously — seeded in the bootstrap
handshake and kept in sync via a
`vaadin-geolocation-availability-change` DOM event — so application code
can read it (or bind to it) without an extra round-trip.

## Details

`Geolocation.get(callback)` and `Geolocation.get(options, callback)`
enqueue a single position request; the callback receives a
`GeolocationOutcome` on the UI thread.

`Geolocation.track(Component)` / `track(Component, GeolocationOptions)`
returns a `GeolocationTracker`:
- `valueSignal()` — `Signal<GeolocationResult>` carrying
`GeolocationPending` until the first fix, then successive
`GeolocationPosition` / `GeolocationError` values.
- `activeSignal()` — `Signal<Boolean>` for binding a start/stop button
without tracking a separate flag.
- `stop()` / `resume()` — cancel or resume the browser watch; the
tracker handle is reusable and bound effects keep working.
- The watch is cancelled automatically when the owning component
detaches. Javadoc documents the cross-browser caveat that a watch goes
silent if the user revokes and re-grants permission, and recommends
`stop()` + `resume()` (or driving it off `availabilitySignal()`) as
recovery.

`GeolocationOptions` is a record with a serializable builder, `Duration`
overloads, and validation that rejects negative `timeout` /
`maximumAge`.

`GeolocationError.errorCode()` returns a `GeolocationErrorCode` enum
(`PERMISSION_DENIED`, `POSITION_UNAVAILABLE`, `TIMEOUT`, `UNKNOWN`) so
switches are exhaustive without a `null` arm.

`availabilitySignal()` yields a `GeolocationAvailability` enum
(`GRANTED` / `DENIED` / `PROMPT` / `UNKNOWN` / `UNSUPPORTED`). Javadoc
spells out the reliability caveats (Safari always reports `UNKNOWN`,
Firefox does not always propagate settings changes, a small propagation
delay on Chromium) and recommends `get(...)` in the callback for
critical paths.

The client bridge lives in
`flow-client/src/main/frontend/Geolocation.ts`, loaded as a side-effect
import from `Flow.ts` (the entry point Vite actually bundles).
`collectBrowserDetails()` awaits `queryAvailability()` so the initial
value is present in the first server request. k

The package is `@NullMarked` (JSpecify) with `@Nullable` on the
genuinely optional spots (`options`, boxed coordinate fields, internal
wire records). Read-only signal wrappers are cached so callers observe
stable identities. Accompanied by unit tests in `GeolocationTest` and an
integration test (`GeolocationIT` + `GeolocationView`)
covering granted/denied/error paths and the "no updates after stop()"
invariant.

---------

Co-authored-by: Marco Collovati <marco@vaadin.com>

Author: Artur-

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

@@ -4,6 +4,7 @@ import {
   type ConnectionStateChangeListener,
   type ConnectionStateStore
 } from '@vaadin/common-frontend';
+import './Geolocation';
 
 export interface FlowConfig {
   imports?: () => Promise<any>;
@@ -420,13 +421,13 @@ export class Flow {
       return Promise.resolve(initial);
     }
 
+    const browserDetails = await this.collectBrowserDetails();
+
     // send a request to the `JavaScriptBootstrapHandler`
     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))}`
         : '';
@@ -459,7 +460,7 @@ export class Flow {
   }
 
   // Collects browser details parameters
-  private collectBrowserDetails(): Record<string, string> {
+  private async collectBrowserDetails(): Promise<Record<string, string>> {
     const params: Record<string, any> = {};
 
     /* Screen height and width */
@@ -550,6 +551,14 @@ export class Flow {
     }
     params['v-tn'] = themeName;
 
+    /* Geolocation availability — guarded because tests may reset
+       window.Vaadin between runs, removing the namespace that
+       Geolocation.ts installs at import time. */
+    const geolocation = ($wnd.Vaadin.Flow as any)?.geolocation;
+    if (geolocation) {
+      params['v-ga'] = await geolocation.queryAvailability();
+    }
+
     /* Stringify each value (they are parsed on the server side) */
     const stringParams: Record<string, string> = {};
     Object.keys(params).forEach((key) => {

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

@@ -0,0 +1,234 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+type VaadinGeolocationAvailability = 'GRANTED' | 'DENIED' | 'PROMPT' | 'UNKNOWN' | 'UNSUPPORTED';
+
+/**
+ * Coordinates data sent to the server, matching the Java GeolocationCoordinates record.
+ */
+interface VaadinGeolocationCoordinates {
+  latitude: number;
+  longitude: number;
+  accuracy: number;
+  altitude: number | null;
+  altitudeAccuracy: number | null;
+  heading: number | null;
+  speed: number | null;
+}
+
+/**
+ * Position data sent to the server, matching the Java GeolocationPosition record.
+ */
+interface VaadinGeolocationPosition {
+  coords: VaadinGeolocationCoordinates;
+  timestamp: number;
+}
+
+/**
+ * Error data sent to the server, matching the Java GeolocationError record.
+ */
+interface VaadinGeolocationError {
+  code: number;
+  message: string;
+}
+
+/**
+ * Result of a one-shot geolocation request. Contains either a position or an error,
+ * plus the availability state updated by this response.
+ */
+interface VaadinGeolocationGetResult {
+  position?: VaadinGeolocationPosition;
+  error?: VaadinGeolocationError;
+  availability: VaadinGeolocationAvailability;
+}
+
+/**
+ * Options for geolocation requests, matching the standard PositionOptions.
+ */
+interface VaadinGeolocationOptions {
+  enableHighAccuracy?: boolean;
+  timeout?: number;
+  maximumAge?: number;
+}
+
+function copyCoords(c: GeolocationCoordinates): VaadinGeolocationCoordinates {
+  return {
+    latitude: c.latitude,
+    longitude: c.longitude,
+    accuracy: c.accuracy,
+    altitude: c.altitude,
+    altitudeAccuracy: c.altitudeAccuracy,
+    heading: c.heading,
+    speed: c.speed
+  };
+}
+
+const watches = new Map<string, number>();
+
+// The cached availability for the current page. Populated on first
+// queryAvailability() call, refreshed from each get()/watch() outcome, and
+// kept current by a permissionchange listener (where supported).
+let cachedAvailability: VaadinGeolocationAvailability | null = null;
+let permissionChangeListenerInstalled = false;
+
+function publishAvailability(next: VaadinGeolocationAvailability): void {
+  if (cachedAvailability === next) {
+    return;
+  }
+  cachedAvailability = next;
+  // Dispatch on document.body so the server-side Geolocation facade (listening
+  // on the UI element, which is body) can update its cached value.
+  document.body.dispatchEvent(
+    new CustomEvent('vaadin-geolocation-availability-change', {
+      detail: { availability: next }
+    })
+  );
+}
+
+// Applies a single get()/watch() outcome to the cached availability and
+// returns the value to report in the response. Never overwrites
+// UNSUPPORTED, which is session-stable. TIMEOUT and POSITION_UNAVAILABLE
+// don't reveal the permission state, so the previous cached value is
+// returned unchanged.
+function getAndCacheAvailabilityFromResult(
+  position: VaadinGeolocationPosition | undefined,
+  error: VaadinGeolocationError | undefined
+): VaadinGeolocationAvailability {
+  if (cachedAvailability !== 'UNSUPPORTED') {
+    if (position) {
+      publishAvailability('GRANTED');
+    } else if (error?.code === 1) {
+      publishAvailability('DENIED');
+    }
+  }
+  return cachedAvailability ?? 'UNKNOWN';
+}
+
+async function resolveAvailability(): Promise<VaadinGeolocationAvailability> {
+  if (!window.isSecureContext) {
+    return 'UNSUPPORTED';
+  }
+  // Chromium exposes document.featurePolicy; Firefox and Safari do not
+  // expose any feature-policy introspection API, so the check is only
+  // possible on Chromium. When absent, assume geolocation is allowed.
+  const doc = document as any;
+  if (doc.featurePolicy && typeof doc.featurePolicy.allowsFeature === 'function') {
+    try {
+      if (!doc.featurePolicy.allowsFeature('geolocation')) {
+        return 'UNSUPPORTED';
+      }
+    } catch (_e) {
+      // Ignore and assume allowed
+    }
+  }
+  try {
+    const status = await navigator.permissions.query({ name: 'geolocation' as PermissionName });
+    if (!permissionChangeListenerInstalled) {
+      permissionChangeListenerInstalled = true;
+      status.addEventListener('change', () => {
+        publishAvailability(stateToAvailability(status.state));
+      });
+    }
+    return stateToAvailability(status.state);
+  } catch (_e) {
+    // Safari rejects the 'geolocation' permission name with a TypeError
+    return 'UNKNOWN';
+  }
+}
+
+function stateToAvailability(state: string): VaadinGeolocationAvailability {
+  switch (state) {
+    case 'granted':
+      return 'GRANTED';
+    case 'denied':
+      return 'DENIED';
+    case 'prompt':
+      return 'PROMPT';
+    default:
+      return 'UNKNOWN';
+  }
+}
+
+const $wnd = window as any;
+$wnd.Vaadin ??= {};
+$wnd.Vaadin.Flow ??= {};
+$wnd.Vaadin.Flow.geolocation = {
+  get(options?: VaadinGeolocationOptions): Promise<VaadinGeolocationGetResult> {
+    return new Promise((resolve) => {
+      navigator.geolocation.getCurrentPosition(
+        (p) => {
+          const position = { coords: copyCoords(p.coords), timestamp: p.timestamp };
+          resolve({ position, availability: getAndCacheAvailabilityFromResult(position, undefined) });
+        },
+        (e) => {
+          const error = { code: e.code, message: e.message };
+          resolve({ error, availability: getAndCacheAvailabilityFromResult(undefined, error) });
+        },
+        options || undefined
+      );
+    });
+  },
+
+  watch(element: HTMLElement, options: VaadinGeolocationOptions | undefined, watchKey: string): void {
+    if (watches.has(watchKey)) {
+      navigator.geolocation.clearWatch(watches.get(watchKey)!);
+    }
+    watches.set(
+      watchKey,
+      navigator.geolocation.watchPosition(
+        (p) => {
+          const position = { coords: copyCoords(p.coords), timestamp: p.timestamp };
+          getAndCacheAvailabilityFromResult(position, undefined);
+          element.dispatchEvent(
+            new CustomEvent('vaadin-geolocation-position', {
+              detail: position
+            })
+          );
+        },
+        (e) => {
+          const error = { code: e.code, message: e.message };
+          getAndCacheAvailabilityFromResult(undefined, error);
+          element.dispatchEvent(
+            new CustomEvent('vaadin-geolocation-error', {
+              detail: error
+            })
+          );
+        },
+        options || undefined
+      )
+    );
+  },
+
+  clearWatch(watchKey: string): void {
+    if (watches.has(watchKey)) {
+      navigator.geolocation.clearWatch(watches.get(watchKey)!);
+      watches.delete(watchKey);
+    }
+  },
+
+  async queryAvailability(): Promise<VaadinGeolocationAvailability> {
+    const value = await resolveAvailability();
+    // publish without dispatching a change event — there is no previous
+    // cached value to compare against when cachedAvailability is null and
+    // the bootstrap consumer just wants the initial answer.
+    cachedAvailability = value;
+    return value;
+  }
+};
+
+// Empty export to ensure TypeScript emits this as an ES module,
+// which is required for Vite to load it via import.
+export {};

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

@@ -32,6 +32,7 @@
 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;
@@ -134,6 +135,8 @@ public class UI extends Component
 
     private final Page page = new Page(this);
 
+    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,
@@ -163,6 +166,7 @@ protected UI(UIInternalUpdater internalsHandler) {
         getNode().getFeature(ElementData.class).setTag("body");
         Component.setElement(this, Element.get(getNode()));
         pushConfiguration = new PushConfigurationImpl(this);
+        geolocation = new Geolocation(this);
     }
 
     /**
@@ -914,6 +918,16 @@ 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.