diff --git a/flow-server/src/main/java/com/vaadin/flow/component/geolocation/Geolocation.java b/flow-server/src/main/java/com/vaadin/flow/component/geolocation/Geolocation.java index 101a86403a3..2aed99d38a4 100644 --- a/flow-server/src/main/java/com/vaadin/flow/component/geolocation/Geolocation.java +++ b/flow-server/src/main/java/com/vaadin/flow/component/geolocation/Geolocation.java @@ -60,10 +60,8 @@ * * Availability check: * * *

@@ -268,9 +266,10 @@ public void getPosition(SerializableConsumer onSuccess, * {@link GeolocationWatcher#stop()} followed by * {@link GeolocationWatcher#resume()}, which installs a fresh browser * watch. Applications that want this to happen automatically can subscribe - * to {@link #availabilitySignal()} with {@code Signal.effect(owner, ...)} - * and trigger the stop/resume when the availability transitions back to - * {@link GeolocationAvailability#GRANTED GRANTED}. + * to {@link #availabilityHintSignal()} with + * {@code Signal.effect(owner, ...)} and trigger the stop/resume when the + * availability transitions back to {@link GeolocationAvailability#GRANTED + * GRANTED}. * * @param owner * the component that owns this watching session; detaching the @@ -306,51 +305,29 @@ public GeolocationWatcher watchPosition(Component owner, } /** - * Returns a read-only signal holding the current geolocation availability — - * whether the Geolocation API is usable in this context and, if so, what - * permission state the origin has. + * Returns a read-only signal hinting at whether geolocation is usable for + * this UI. Useful for pre-rendering decisions like hiding a "Locate me" + * button on insecure contexts or auto-fetching on return visits when + * permission is already granted. *

- * Subscribe with {@code Signal.effect(owner, ...)} to react to availability - * changes (e.g. disabling a location button when the user revokes - * permission). For a snapshot read, call - * {@code availabilitySignal().peek()}; in an effect or reactive context, - * call {@code availabilitySignal().get()}. - *

- * The signal starts as {@link GeolocationAvailability#UNKNOWN UNKNOWN}, - * transitions to the value reported during the initial client bootstrap, - * and updates on every {@link #getPosition} / {@link #watchPosition} - * outcome and on browser permission-change events where supported. - *

- * Reliability caveats. The value is best-effort, not authoritative — - * it reflects what the browser last reported, and can be briefly stale in - * these cases: + * The value is best-effort and can be briefly stale: *

- * Treat the value as a hint for pre-rendering decisions (e.g. auto-fetching - * on return visits, hiding controls in unsupported contexts). For critical - * paths, call {@link #getPosition} and handle the authoritative result in - * the callback. + * For authoritative results, call {@link #getPosition} and inspect the + * outcome. * - * @return the availability signal + * @return the availability hint signal */ - public Signal availabilitySignal() { + public Signal availabilityHintSignal() { return availabilityReadOnly; } diff --git a/flow-server/src/main/java/com/vaadin/flow/component/geolocation/GeolocationAvailability.java b/flow-server/src/main/java/com/vaadin/flow/component/geolocation/GeolocationAvailability.java index ce280a21133..9c604f97ed6 100644 --- a/flow-server/src/main/java/com/vaadin/flow/component/geolocation/GeolocationAvailability.java +++ b/flow-server/src/main/java/com/vaadin/flow/component/geolocation/GeolocationAvailability.java @@ -19,7 +19,7 @@ * Whether the browser can read the user's location right now, and if so what * permission state the origin has. *

- * Returned by {@link Geolocation#availabilitySignal()}. Reading the value does + * Held by {@link Geolocation#availabilityHintSignal()}. Reading the value does * not show a permission dialog — it reports whether a dialog would * appear on the next {@link Geolocation#getPosition} or * {@link Geolocation#watchPosition} call, or whether the call would fail @@ -62,7 +62,7 @@ public enum GeolocationAvailability { /** * The browser did not report a permission state. Treat this as "do not * auto-fetch; wait for the user to take an explicit action". Safari always - * returns this value because it does not implement permission querying for + * surfaces this value because it does not implement permission querying for * geolocation. */ UNKNOWN, diff --git a/flow-server/src/main/java/com/vaadin/flow/component/internal/UIInternals.java b/flow-server/src/main/java/com/vaadin/flow/component/internal/UIInternals.java index df866975a04..b29877d4bd0 100644 --- a/flow-server/src/main/java/com/vaadin/flow/component/internal/UIInternals.java +++ b/flow-server/src/main/java/com/vaadin/flow/component/internal/UIInternals.java @@ -1445,7 +1445,7 @@ public void setExtendedClientDetails(ExtendedClientDetails details) { * UI. Starts as {@link GeolocationAvailability#UNKNOWN} before the first * client bootstrap report, then transitions to the value the browser * reports and reflects subsequent updates. Application code reads it via - * {@link com.vaadin.flow.component.geolocation.Geolocation#availabilitySignal()}. + * {@link com.vaadin.flow.component.geolocation.Geolocation#availabilityHintSignal()}. * * @return the availability signal */ diff --git a/flow-server/src/test/java/com/vaadin/flow/component/geolocation/GeolocationTest.java b/flow-server/src/test/java/com/vaadin/flow/component/geolocation/GeolocationTest.java index 93afb00353d..9f8f4f9f18f 100644 --- a/flow-server/src/test/java/com/vaadin/flow/component/geolocation/GeolocationTest.java +++ b/flow-server/src/test/java/com/vaadin/flow/component/geolocation/GeolocationTest.java @@ -637,7 +637,7 @@ void addPositionListener_pendingIsSilent() { @Test void availability_unknownBeforeAnyReport() { assertEquals(GeolocationAvailability.UNKNOWN, - ui.getGeolocation().availabilitySignal().peek()); + ui.getGeolocation().availabilityHintSignal().peek()); } @Test @@ -646,7 +646,7 @@ void availability_reflectsUIInternalsSignal() { .setGeolocationAvailability(GeolocationAvailability.GRANTED); assertEquals(GeolocationAvailability.GRANTED, - ui.getGeolocation().availabilitySignal().peek()); + ui.getGeolocation().availabilityHintSignal().peek()); } @Test