Add a geo.event.feature.mouseclick_order event.

One event is generate per feature that is under the mouse when a mouse
click is generated on features.  By reordering them, this affects the
order those events are generated and tags a different event as the top
element.

This also fixes some documentation.

src/event.js

@@ -324,10 +324,10 @@ geo_event.feature = {
    */
   mouseover:  'geo_feature_mouseover',
   /**
-   * The event contains the `feature`, the `previous` record of data elements
-   * that were under the mouse, and `over`, the new record of data elements that
-   * are unrder the mouse.
-   * @event geo.event.feature.mouseover.order
+   * The event contains the `feature`, the `mouse` record, the `previous`
+   * record of data elements that were under the mouse, and `over`, the new
+   * record of data elements that are unrder the mouse.
+   * @event geo.event.feature.mouseover_order
   */
   mouseover_order: 'geo_feature_mouseover_order',
   /**
@@ -350,6 +350,12 @@ geo_event.feature = {
    * @event geo.event.feature.mouseclick
    */
   mouseclick: 'geo_feature_mouseclick',
+  /**
+   * The event contains the `feature`, the `mouse` record, and `over`, the
+   * record of data elements that are unrder the mouse.
+   * @event geo.event.feature.mouseclick_order
+  */
+  mouseclick_order: 'geo_feature_mouseclick_order',
   /**
    * The event is the feature version of {@link geo.event.brushend}.
    * @event geo.event.feature.brushend

src/feature.js

@@ -211,7 +211,7 @@ var feature = function (arg) {
 
     // if we are over more than one item, trigger an event that is allowed to
     // reorder the values in evt.over.index.  Event handlers don't have to
-    // maintain evt.over.data.  Handlers should not modify evt.over.extra or
+    // maintain evt.over.found.  Handlers should not modify evt.over.extra or
     // evt.previous.
     if (over.index.length > 1) {
       m_this.geoTrigger(geo_event.feature.mouseover_order, {
@@ -326,6 +326,16 @@ var feature = function (arg) {
         over = m_this.pointSearch(mouse.geo),
         extra = over.extra || {};
 
+    // if we are over more than one item, trigger an event that is allowed to
+    // reorder the values in evt.over.index.  Event handlers don't have to
+    // maintain evt.over.found.  Handlers should not modify evt.over.extra.
+    if (over.index.length > 1) {
+      m_this.geoTrigger(geo_event.feature.mouseclick_order, {
+        feature: this,
+        mouse: mouse,
+        over: over
+      });
+    }
     mouse.buttonsDown = evt.buttonsDown;
     feature.eventID += 1;
     over.index.forEach(function (i, idx) {

tests/cases/feature.js

@@ -90,6 +90,11 @@ describe('geo.feature', function () {
       feat.geoOn(geo.event.feature.brushend, function (evt) { events.brushend = evt; });
       map.interactor().simulateEvent('mousemove', {map: {x: 20, y: 20}});
       expect(events.mouseover.index).toBe(1);
+      points.index = [1, 2];
+      map.interactor().simulateEvent('mousedown', {map: {x: 20, y: 20}, button: 'left'});
+      map.interactor().simulateEvent('mouseup', {map: {x: 20, y: 20}, button: 'left'});
+      expect(events.mouseclick.index).toBe(2);
+      expect(events.mouseclick.top).toBe(true);
     });
     it('_unbindMouseHandlers', function () {
       feat._unbindMouseHandlers();