adding per-feature event listeners

A list of questions about events and what I think might be the answers. What do you think?

Per-feature event listeners?

Currently you can only listen to events on layers. I think we agree that we should expand this to individual features. The clearest advantage of this is with mouseenter and mouseleave events. Without per-feature event listeners you would need to manually track the features under the pointer and diff them.

Dispatched once as a batch or once per feature?

We could dispatch a single click event with all the features under the pointer. We could dispatch a mouseenter event with all the features that were entered. But this seems weird.

I think we should dispatch a callback once per feature. I'm having trouble figuring out why, but maybe because it's closer to how platforms handle things.

What order should events be dispatched?

Top-down seems like the logical order. I think events on layers would be dispatched just below features in that layer.

register listener on all features in layerA
register listener on layerA
register listener on all features in layerB
click
dispatch click on feature1 in layerA
dispatch click on feature2 in layerA
dispatch click on layerA
dispatch click on feature5 in layerB

Open question: should we go in the rendered order or the layer order? Sometimes labels and 3d buildings are rendered out of order.

Dispatched once per source feature or once per rendered feature?

If a feature has both a rendered fill and a rendered symbol, and you click on a point covered by both, should two events be dispatched? I think so, because events are added to rendered features (layer ids can be part of the selector).

Stopping propagation

Should it be possible to prevent other listeners from being called from within an event listener? On the web you can do this with e.stopPropagation().

I think there are definitely use cases where you would want to do this. Like hovering on just the topmost feature:

map.on('mouseenter', 'layerid', filter, function(e) {
    // set 'hover' state of feature to true
    ...
    // prevent later mouseenter events from being called on lower features
    e.stopPropagation();
});
map.on('mouseleave', 'layerid', filter, function(e) {
    // set 'hover' state of feature to false
});

This adds complexity but seems like something that needs to be done somehow, and I don't have better ideas.

Summary

So I'm thinking: per-feature event listeners that get individually dispatched, once per rendered feature, in a top-down order with some way of stopping event propagation.

@mollymerp @asheemmamoowala @anandthakker @jfirebaugh @lucaswoj

No files, tests, or implementation entry points are named. Start by reviewing the proposed decisions in the issue—per-feature dispatch, ordering, rendered features, and propagation—and define the event behavior before identifying the relevant event-handling code and tests.