Geolocation

[Artur-]

PRD: Geolocation

Tier: Free
License: Apache 2.0

Description

A Flow API that provides access to the browser's Geolocation API, enabling applications to request, track, and react to the user's geographic position with configurable accuracy, caching, and error handling.

Motivation

Background

Modern web applications frequently need access to the user's geographic location — from "find a store near me" to real-time courier tracking. The browser's Geolocation API provides this capability, but using it correctly requires handling permissions, errors, timeouts, accuracy trade-offs, and lifecycle management. Each application today must re-implement this boilerplate.

Problem

Developers building location-aware features must manually deal with:

• Requesting and tracking the user's position through raw browser APIs
• Querying and reacting to permission state (granted, denied, prompt)
• Handling errors gracefully (permission denied, position unavailable, timeout)
• Managing continuous tracking lifecycle (start, stop, cleanup on navigation)
• Configuring accuracy/battery/freshness trade-offs per use case
• Integrating location capture into forms with validation

There is no reusable Flow API that encapsulates these concerns and exposes them in a declarative, framework-friendly way.

Solution

Provide a geolocation Flow API that wraps the browser Geolocation API and exposes the following capabilities:

1. One-shot position retrieval — request the user's current position on demand and receive coordinates, accuracy, altitude, heading, speed, and timestamp.

2. Continuous tracking — start and stop watching the user's position over time, receiving updates as the user moves. Tracking must automatically clean up when the component that started it (e.g., a view) is detached.

3. Permission-aware behavior — query the current permission state (granted, prompt, denied) so applications can:

   • Silently fetch location for returning users who already granted permission
   • Show an explicit "use my location" control for first-time users
   • Display a fallback UI for users who denied permission, without nagging

4. Comprehensive error handling — surface distinct error conditions (permission denied, position unavailable, timeout, API not supported) so applications can show appropriate messages and fallbacks.

5. Full position data — expose all fields from the browser's GeolocationPosition: latitude, longitude, accuracy, altitude, altitude accuracy, heading, speed, and timestamp.

6. Configurable options per request — allow each position request or tracking session to specify:

   • Whether high accuracy is needed
   • Maximum acceptable age of a cached position
   • Timeout before giving up

7. Form integration — the captured position should be usable as a form field value, supporting reset, required validation, and accuracy-based validation.

Notes

This feature is new — there are no breaking changes or migration concerns.

Requirements

Once the PRD is approved, sub-issues are created in the appropriate repository. These items are checked once there are issues covering them and progress is tracked through the sub-issues.

• One-shot position retrieval: request current position and receive full coordinate data
• Continuous position tracking: start/stop watching with automatic cleanup when the owning component is detached
• Permission state querying: determine whether location permission is granted, prompt, or denied
• Permission-aware auto-resume: silently fetch position for returning users with granted permission
• Error handling: surface distinct errors for permission denied, position unavailable, timeout, and unsupported API
• Browser support detection: allow applications to check if geolocation is available before showing controls
• Full position data exposure: latitude, longitude, accuracy, altitude, altitude accuracy, heading, speed, timestamp
• Configurable options: high accuracy flag, maximum cache age, and timeout per request/tracking session
• Form integration: captured position usable as a form field with reset, required, and accuracy validation
• Documentation

Nice-to-haves

• Built-in "retry" support after timeout or transient failure
• Distance calculation utility (e.g. Haversine) for common "nearest X" patterns
• Speed/altitude formatting helpers (m/s to km/h, altitude display)

Browserless testing

Each requirement must be testable without a real browser (no Selenium, no Playwright). The implementation must provide the following testing affordances:

Position retrieval and tracking:

• A test API to simulate a successful position result with configurable values (latitude, longitude, accuracy, altitude, heading, speed, timestamp), so server-side position listeners and callbacks can be verified in a unit test.
• A test API to simulate position updates over time for continuous tracking scenarios — e.g., feeding a sequence of positions to verify that the tracking listener receives each update.
• A test API to simulate tracking stopping (user navigates away, explicit stop) to verify cleanup behavior.

Permission state:

• A test API to set the simulated permission state (granted, prompt, denied) so tests can verify that the application shows the correct UI for each state — e.g., auto-fetching when granted, showing a button when prompt, showing a fallback when denied.

Error handling:

• A test API to simulate each distinct error condition (permission denied, position unavailable, timeout, API not supported) so tests can verify that the correct error callback fires and the application responds appropriately.
• A test API to simulate the geolocation API being entirely unavailable (e.g., HTTP context, unsupported browser) so tests can verify that controls are hidden or disabled.

Configurable options:

• A way to assert that a position request was made with specific options (high accuracy, max age, timeout) without actually invoking the browser API — so tests can verify that per-use configuration is passed through correctly.

Form integration:

• A test API to simulate capturing a position into a form field, so tests can verify reset behavior, required validation, and accuracy-based validation without a browser.

Risks, limitations and breaking changes

Risks

• Browser Geolocation API behavior varies across devices and browsers, especially for accuracy, altitude, heading, and speed fields which may be null on many devices.
• Permission prompt UX is controlled by the browser and cannot be customized — documentation should guide developers on when to trigger it.

Limitations

• Geolocation is only available in secure contexts (HTTPS). The component cannot work on plain HTTP pages.
• Background tracking when the tab is not focused may be throttled or paused by the browser.
• Indoor positioning accuracy is highly variable and device-dependent.

Breaking changes

Out of scope

• Reverse geocoding (converting coordinates to addresses) — this requires a server-side service and is outside the scope of this API.
• Map rendering or integration — the API provides position data; displaying it on a map is the application's responsibility.
• Server-side location storage or transmission — the API bridges server-side Java code with the client-side browser Geolocation API.
• Geofencing (triggering actions when entering/leaving an area).

Materials

• Live use cases demo

Metrics

Pre-implementation checklist

• Product Manager sign-off
• Engineering Manager sign-off

Pre-release checklist

• Documented (link to documentation provided in sub-issue or comment)
• UX/DX tests conducted and blockers addressed
• Approved for release by Product Manager

Security review

• Not applicable
• Peer reviewed
• Security audit conducted (link to internal report)

[Legioth]

Tracking must automatically clean up when the UI is detached

I guess this isn't only when the UI is detached but more accurately when the component (e.g. a view) using the tracking is detached.

expose all fields from the browser's GeolocationPosition

Should it also be a requirement to get access to any newly added fields without requiring a Vaadin version update, i.e. to give direct access to the underlying JSON data?

Form integration

How is the location visualized in the field component? The approach in the demo seems quite opinionated.

[jouni]

Permission prompt UX is controlled by the browser and cannot be customized — documentation should guide developers on when to trigger it.

If we only do documentation regarding this (instead of a ready-made UI template, for example), the documentation should include a working example how to “prime” the user before the triggering the browser permission prompt, so that the user is aware of the reason why the app is asking for the location permission. It might not always be needed, but especially if the app asks for the permission on the first startup, the user needs to know how their location is being used.