Provide access mouse/touch events in continuously-updating interaction handlers

[anandthakker]

As a consequence of integrating camera easing into the main render loop (#5743), we've changed (#6005 #6029) the way continuously-updating interaction handlers manage the camera so that, during dragging/scrolling action, we accumulate movement from multiple mouse events between one render frame and the next, and then in each frame, we synchronously update the camera and fire move (and rotate, etc.) events.

Right now, when DragPanHandler, DragRotateHandler, and ScrollZoomHandler fire 'move', etc., they attach the last mouse event as originalEvent, even though multiple mouse events may be responsible for this particular 'move'. Instead, we should either (a) omit originalEvent in these cases, or (b) include an originalEvents array with all of the contributing events.

[mourner]

One tricky thing to note is that this property was often used for things like stopPropagation, and accumulating events will no longer support the use case because most events will propagate by the time you process them in batch.

[anandthakker]

Shoot, good point @mourner. We will need to provide a new way to do that

[anandthakker]

Initial ideas for how we can expose a way for users to stopPropagation() on these events:

1. Add a stopEventPropagation: boolean option to the handler settings. Seems hacky, doesn't allow client code to decide on a per-event basis.
2. Fire a new type of event --move-input or gesture-received or something -- from within the event listener that carries the incoming event as originalEvent payload. Also seems hacky -- the difficulty of finding a good name suggests that may not be a great design choice.
3. Allow an onInputEvent: (MouseEvent | TouchEvent) => void callback. Inconsistent with our otherwise event-driven API.

[anandthakker]

I suppose for 2, we could also re-emit the event under its same name (mousemove, wheel, etc.). (It looks like we specifically avoid doing that right now.)

[jfirebaugh]

this property was often used for things like stopPropagation

Any concrete examples of this? I like to have a firmer idea how widespread/essential this is.

[jfirebaugh]

My thinking is that we shouldn't try to fix this, and in fact, secondary map events like move should never have an originalEvent property -- only map events that directly correspond to a triggering DOM event should (mousedown, etc.)

The use case of preventing default map handler behavior should be covered by #3290. If there are any other use cases, they should be handled by binding native DOM event handlers and stopping propagation of the DOM event before it even reaches the map code, either by using capture: true or binding via children of the canvas container and stopping the event before it bubbles.

[jfirebaugh]

Studio uses originalEvent only on click and mousemove events, so shouldn't be negatively affected by removing originalEvent from secondary events.

[jfirebaugh]

Thanks to @stepankuzmin to calling my attention to one important use of originalEvent in #6175 -- distinguishing user-initiated camera events so they can be debounced in a Reactive context, a use which we recommend in our blog post.

This case could instead be addressed by reversing the check -- looking for a property that's added to programmatically triggered events with the eventData parameter. For handler-triggered events, I think we could also have add an event property that indicate which handler triggered the camera event.

[anandthakker]

Yeah, good point. Maybe something like a cause: property -- for handler-triggered events, this could be { handler: Handler }, and for programmatically-triggered events, it could be set via an option to the camera methods (map.flyTo({ center: ..., cause: /* application-specific payload */))