Expanded events capability, addressing #69.

As mentioned in the issue, it is probably necessary to distinguish and expand upon different kinds of events (such as those from controls) in a separate capability or capabilities, but I think this gives us a starting point.

Author: NickFitz

index.html

@@ -5437,22 +5437,42 @@ <h5>Conclusion</h5>
 <section id="capability-map-events" data-ucr-role="capability">
 <h4>Subscribe to notifications of map events</h4>
 <p>
-A web application embedding a map will usually need to respond to changes in the state of the map as a result of
-user activity or from other causes,
+A web application embedding a map will commonly need to respond to changes in the state of the map,
+whether as a result of user activity or from other causes,
 so that it can update its own internal state and user interface as necessary to remain consistent with the map view.
 At a minimum, any change of the area displayed by the map needs to be notified to the application.
-In practice, it is usually desirable for the causes of changes to be distinguishable from each other,
-and for other high-level events within the map view to be exposed.
+In practice, it is usually desirable for other high-level events within the map view to be exposed as well.
 This allows an application fine-grained control of the level of detail of interactions it responds to,
-from a simple update when the map is moved or the zoom level is changed,
-to detailed feedback presented in its user interface during user interactions of longer duration
-such as continuous panning.
+from simple updates when the map is moved or the zoom level is changed,
+to detailed feedback during user interactions of longer duration such as continuous panning.
+</p>
+<p>
+In addition to events relating to the state of the map view itself,
+developers will expect to be able to receive notifications of events triggered by other components within the map
+such as controls, markers, and layers.
+</p>
+<p>
+A native HTML map element would be expected to support the existing DOM event binding interface,
+using the standard <code>addEventListener()</code> method to bind listener functions to map events,
+and receiving an object derived from the standard <code>Event</code> interface
+as the argument to such functions.
 </p>
 <p class="issue discussion" data-number="69">Discuss this section on GitHub.</p>
 
 <h5>Existing implementations</h5>
 <p>
-
+Implementations of map events vary widely in both the terminology used and the semantic richness of the events available.
+For example, the Google Maps API provides events named <code>center_changed</code>
+and <code>zoom_changed</code>, allowing a developer to provide discrete event handlers for such changes.
+The Leaflet API supports similar events, but named <code>moveend</code> and <code>zoomend</code>.
+The Bing Maps API, on the other hand, provides a more general <code>viewchangeend</code> event,
+and the handler for this event must examine the state of the map to determine what has changed.
+</p>
+<p>
+APIs generally also provide lower level events directly correlating to user interactions,
+such as <code>click</code> and <code>mouseover</code> in the Google Maps API, though again terminology varies.
+The event objects passed to handlers of such events have additional properties compared to their equivalents
+in normal DOM event handling, such as a property giving the position of the event in terms of latitude and longitude.
 </p>
 <dl data-ucr-role="implementation-notes">
 <!-- Use dt elements to name the implementation, using the id string to create an auto-link.
@@ -5467,9 +5487,16 @@ <h5>Existing implementations</h5>
 <dt>mapbox-gl-api</dt>
 <dt>leaflet-api</dt>
 <dt>open-layers-api</dt>
+<dt>tomtom</dt>
 <dt>d3-geographies-api</dt>
-<dd><a>not applicable</a>:
+<dd><a>supported, with limitations</a>:
 <!-- details about what is/isn't supported -->
+<p>
+Although all existing implementations support an events system capable of meeting the needs of developers,
+inconsistencies in terminology, semantic richness, and the interfaces provided for adding and removing
+event listeners mean that it is unclear whether any one of the existing APIs would be a suitable model
+for the various capabilities available across the entire range of them.
+</p>
 </dd>
 </dl>
 
@@ -5478,13 +5505,24 @@ <h5>Supported use cases</h5>
 
 <h5>Uses beyond mapping</h5>
 <p>
-ToDo
+As it is anticipated that standard DOM event interfaces would be the basis for an HTML map's event system,
+it is likely that further uses could arise for such capabilities.
+For example, an HTML text annotated with geographical microdata could allow DOM events arising from user interaction
+(such as clicking on the name of a city within the text) to be enhanced with the same kind of position property,
+specifying latitude and longitude, as would be present in an event object created by a similar interaction
+with a map element.
 </p>
 
 <h5>Related web specifications</h5>
 <p>
 <!-- Any existing/proposed specs that address similar needs or otherwise interact.
 Include links with proper ReSpec references. -->
+As outlined above, it is expected that events as defined in [[[DOM]]] would form the basis for a map element's
+event system.
+</p>
+<p>
+[[[HTML]]] media objects provide an existing example of extending the basic event system to support
+particular capabilities of embedded content.
 </p>
 
 <h5>Conclusion</h5>
@@ -5494,13 +5532,62 @@ <h5>Conclusion</h5>
 See examples.
 -->
 <p>
-Based on the limited data, we are <a data-ucr-role="conclusion">undecided</a> about whether this should be a requirement.
+This capability is a <a data-ucr-role="conclusion">requirement</a> for the scripting API of a native HTML map element.
+Responding to changes in the state of a map, or user interactions with elements of the map such as markers,
+is necessary for a web application to usefully modify its own state so as to reflect the results of such interactions.
 </p>
 <ul data-ucr-role="conclusion-notes">
 <!-- bullet-point notes summarizing implementation details / blocking issues.
 Add tags to the start of a point with an empty `<a data-ucr-role="tag"></a>` where the text content or href matches a tag `id` value. -->
-<li><a data-ucr-role="tag" href=""></a>
-<!-- short summary of how the tag applies -->
+<li><a data-ucr-role="tag">privacy-fingerprinting</a>
+As scripts may be loaded from arbitrary origins (depending on cross-rigin restrictions),
+an event object including information about a map might allow deductions to be made about a viewer's device.
+For example, the bounds of a map in a responsive design could vary depending on the device on which it is viewed,
+allowing a third-party script to determine that a user is on a handheld device such as a phone.
+</li>
+<li><a data-ucr-role="tag" href="">security-ui</a>
+Use of the event system's <code>stopPropagation()</code> and <code>preventDefault()</code> methods
+could allow a third-party script to prevent a user from viewing particular areas, or more generally
+interfere with correct operation of the map's UI.
+</li>
+<li><a data-ucr-role="tag" href="">privacy-sensitive-data-revealed</a>
+Collating the positions on which a user centres the map could allow a script to infer an interest
+in a particular region and, for example, target advertising accordingly.
+</li>
+<li><a data-ucr-role="tag" href="">security-potential</a>
+By appropriately restricting scripted access to event properties, a built-in browser map implementation
+could prevent leakage to cross-origin scripts of the kind of information outlined in the above points,
+in a way not achievable by existing implementations.
+</li>
+<li><a data-ucr-role="tag" href="">accessibility-potential</a>
+If events from maps and map interface elements are exposed to assistive technologies via the browser's
+existing accessibility mechanisms, it would be easier for those technologies to present them in a way
+consistent with other browser interactions.
+</li>
+<li><a data-ucr-role="tag" href="">performance-potential</a>
+Existing implementations must perform complex tasks such as transforming browser coordinates to map coordinates
+in order to provide such data in enhanced event objects.
+Native implementations could be expected to provide significantly better performance.
+</li>
+<li><a data-ucr-role="tag" href="">author-simplicity</a>
+Consistency of the event interface with other HTML elements would simplify coding.
+</li>
+<li><a data-ucr-role="tag" href="">author-extensibility</a>
+The abilty to respond to user interaction is crucial in building rich application interfaces that include embedded maps.
+</li>
+<li><a data-ucr-role="tag" href="">author-cost-cutting</a>
+A standard interface against which to write event-driven mapping applications reduces the amount of time developers
+need to spend becoming competent and productive.
+</li>
+<li><a data-ucr-role="tag" href="">consistency-match</a>
+Current implementations already seek to either extend or mimic the existing event mechanism.
+</li>
+<li><a data-ucr-role="tag" href="">consistency-progressive</a>
+An application can determine which event-driven enhancements it is capable of supporting in a given environment.
+</li>
+<li><a data-ucr-role="tag" href="">consistency-fallbacks</a>
+An application can choose not to subscribe to a given event or events if it determines that it cannot usefully
+provide an enhancement in its current environment.
 </li>
 </ul>
 </section>