Proposal for a <geolocation> element

The goal is to define a <geolocation> element instead of the generic <permission> element, specifically to facilitate use cases that currently use the Geolocation API.

My guiding principles based on discussions with various parties:

1. Replacing the JS API call will likely be useful in some scenarios, but oftentimes developers need to have more precise control. This means that while the permission elements should allow sites to seamlessly integrate without needing to call the JS APIs, they should also have the flexibility to allow for independent API calls.
2. Usage of the capability cannot always be gated by further interaction with the permission element, there are too many cases where this does not work. But there are still sufficient use cases where it does work e.g. a “get my location” button in an address form or a bank branch locator. Both types of use cases are worth supporting.

Proposal sketch:

• The <geolocation> element inherits from the <permission> element, including all restrictions, checks, events and attributes. The <permission> element is no longer directly usable (though first we'll also need a similar <usermedia> element for camera/microphone).
  * Constraints mirroring the getCurrentPosition options field can be set via https://github.com/WICG/PEPC/blob/main/explainer.md#constraints. Importantly the preciselocation attribute can be removed from the explainer and instead its current functionality is replicated by whether the enableHighAccuracy constraint is present or not. Another approach could be to simply define attributes matching the relatively simple structure of the options dictionary. Or perhaps, to make it more generic, we can define a mechanism that automatically maps attributes with constraints provided that the constraints have a simple structure/type.
• location locationposition attribute on the element is populated with a GeolocationPosition position when said position is available (name changed so it does not clash with the location event from below)
• locationerror attribute on the element is populated with a GeolocationPositionError error if an error has occurred while trying to retrieve the location
• onlocationready onlocation event handler (associated with a newlocation event) is raised when the user has approved the site to get location and the location call has been resolved internally. The site should look at the locationposition or locationerror attributes to see whether there was a successful location retrieval or there was some error.
  * By default the element will be treated as a “one-time” location retrieval element, the user clicks on it and it retrieves the position and raises the onlocationready event. On subsequent visits, the user still has to click on it first, though probably less friction is needed (a single click rather than also a confirmation dialog) - ultimately the exact details about the friction on subsequent interactions are an user-agent implementation detail. The permission status stays unmodified during the entire process.
  * A persistent attribute can be used on the element to more closely match the behavior of the <permission> element today: it will result in a permission prompt and potentially alter the permission status.
  * The user agent should take great consideration to distinguish between persistent and not-persistent elements in such a way where there is a clear advantage for users (and sites) when the non-persistent variation is used. Otherwise we might end up with only the persistent version being used.
• (optional) A watch attribute which would alter the behavior of the element to match the watchPosition API rather than the getCurrentPosition API. Effectively this means that onlocationready is raised every time the position changes, instead of just once.
• Make the element submittable via form: alter the form serialization algorithm.
  • Adjust https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#constructing-the-form-data-set to handle parsing a <geolocation> element
  • Make the <geolocation> element a submittable element https://html.spec.whatwg.org/multipage/forms.html#category-submit
  • The <geolocation> element will submit some sensible serialization of its locationposition attribute
• The exact details of the scope of the grant after the user interacts with the permission prompt are left to the user agent (to decide which options to put in front of the user), and the user themselves (to pick out of the presented options). Broadly speaking there are 5 possible choices that user agents could consider putting in front of users when presenting a <geolocation> element-initiated permission prompt:
  • A one-shot grant which does not include separate API usage. Next interaction on the element triggers a prompt. (Added for completeness, though it does not appear that any user agent is considering this option)
  • A one-shot grant which does not include separate API usage. Next interaction on the element does not trigger a prompt (one-click location share). (Added for completeness, though it does not appear that any user agent is considering this option)
  • A one-time grant which also includes separate API usage for its duration. Next interaction on the element triggers a prompt.
  • A one-time grant which also includes separate API usage for its duration. Next interaction on the element does not trigger a prompt.
  • A permanent grant which also includes separate API usage for its duration (presumably until the permission is manually revoked).
• Ultimately it's up to the user agent which of these choices to put in front of the user. However if the site could hint that they actually make use of permanent grants, it would allow the user agent to better tailor the options they present to users based on this hint. Whether and how much of this should be spec'ed and the exact details are currently under discussion, Chrome's proposal is that an attribute be added which, when present, indicates that the site's use case benefits from the permission being granted in a permanent (not one-time) manner (this only means that the user agent presents this choice, not that the user is forced to pick this option). This would be used by sites which have user journeys that involve using the geolocation API without starting with the user interaction with the <geolocation> element.

Start by reading the proposal and the linked PEPC explainer, then review the HTML Standard's form-control categories and form-data-set construction algorithm. Done means reaching agreement on the geolocation element's permission behavior, attributes, events, and form serialization; the issue does not name implementation files or tests.