Emit event when cooperative gestures blocks event

[tomhicks]

Launch Checklist

Fixes #4464

Adds the ability to subscribe to the case when the CooperativeGestures handler prevents a gesture from being handled by the map. This allows users to add custom logic in this case to put up custom UI, for instance.

The events emitted are of type cooperativegestureprevented and have a gestureType: "wheel_zoom" | "touch_pan" and originalEvent: Event properties, so the developer has as much detail as possible. Arguably, gestureType can be deduced from the originalEvent but it feels nice to explain the gesture type in MapLibre-ish terms.

This also refactors the way in which coop gesture preventions are detected and notified. It wasn't obvious to me when I was working on this how the coop gesture class was preventing the gestures from being handled/bubbled/whatever. It took a while to realise that the touchmove and wheel events in this are run in "parallel" to the other gesture handlers.

The refactor makes the coop gesture handler have two distinct responsibilities:

• answering questions about whether a gesture should be prevented
• notifying the user of a prevention, when requested

This avoids duplicate logic and makes it easy to find how this module is used elsewhere as it has no intrinsic abilities: it performs logic and actions when requested by other modules.

• Confirm your changes do not include backports from Mapbox projects (unless with compliant license) - if you are not sure about this, please ask!
• Briefly describe the changes in this PR.
• Link to related issues.
• Write tests for all new functionality.
• Document any changes to public APIs.
• Add an entry to CHANGELOG.md under the ## main section.

[tomhicks]

I have not been able to find where I should add this extra event to the documentation. If someone can tell me how to do that I would happily do it!

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 96.77419% with 1 line in your changes missing coverage. Please review.

Project coverage is 87.84%. Comparing base (bf008aa) to head (0c0e1ce).

Files	Patch %	Lines
src/ui/handler/cooperative_gestures.ts	87.50%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4470      +/-   ##
==========================================
+ Coverage   87.53%   87.84%   +0.31%     
==========================================
  Files         246      246              
  Lines       33446    33450       +4     
  Branches     2212     2218       +6     
==========================================
+ Hits        29276    29384     +108     
+ Misses       3153     3055      -98     
+ Partials     1017     1011       -6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[HarelM]

I still don't understand how raising these events will allow replacing the current UI.
I don't mind adding these events, but I'm lacking a proper motivation.

[tomhicks]

I still don't understand how raising these events will allow replacing the current UI.

.maplibre-cooperative-gestures-container {
  display: none !important;
}

map.on("cooperativegestureprevented", () => showToast("Press Ctrl"));
map.on("cooperativegestureprevented", () => someObservableState.gesturePrevented = Date.now());
map.on("cooperativegestureprevented", () => analytics.sendEvent("user_tried_to_scroll_map"));

I can do whatever I want with this event, including putting my own UI on top of MapLibre, in my host app, sending things to analytics, etc.

[HarelM]

I see, thanks for the info!
Can you please document this event in the handlers' doc comment?

[tomhicks]

OK, documented that and put the logic back to the individual handlers so things like touch counts, etc are all in the concerned handler.

[HarelM]

Hi, please note that the following was not updated with this logic:
https://github.com/tomhicks/maplibre-gl-js/blob/619773155b3126a453cfded634b35ae8d506fc8d/src/ui/handler/two_fingers_touch.ts#L289

I'm not sure what should be the solution there, but please make sure to test all scenarios to make sure nothing is broken.
I have a feeling not all gesture preventions is covered by tests considering the above "miss".

I have updated some small parts of the code, just small refactoring...

[tomhicks]

Hi, please note that the following was not updated with this logic

@HarelM I'm not sure what change you are expecting there. The logic has not and should not change.

[HarelM]

There's no event in that case, and since you remove the move event from cooperative gesture class you broke part of this logic.
Did you test this code with touch devices (dev tool mobile mode)?

[tomhicks]

There's no event in that case, and since you remove the move event from cooperative gesture class you broke part of this logic.

I'm not sure what part of the logic is broken. What I moved is the code that shows the message if the number of touches is exactly equal to 1, which is now in touch_pan, because it relates to touch panning. There was never any message shown (and now there should be no event emitted) when using 2 fingers in an upwards motion (which in non-coop mode means pitch, but in coop mode means pan) because although it's changing the nature of the gesture, it's not blocking it per se.

Did you test this code with touch devices (dev tool mobile mode)?

Yes, and it all seems to work exactly as on main, and using a real mobile device and multiple fingers, too.

The behaviour on touch devices is:

normal mode:

• 1 finger drag: pan
• 2 fingers spin: rotate
• 2 fingers vertical drag: pitch
• 2 fingers non-vertical pan: pan

coop mode:

• 1 finger drag: blocked -> show UI, emit event
• 2 fingers spin: rotate
• 2 fingers vertical drag: pan
• 2 fingers non-vertical drag: pan
• 3 fingers vertical drag: pitch

That's how it is on main and that's how it is on this branch.

[tomhicks]

One thing we could do would be to emit a cooperativegesturechanged and describe the change in that case, i.e. to convey "you might be expecting this two-finger vertical drag to result in a pitch gesture, but you actually need to use 3"

[HarelM]

Thanks for the clarification, I probably got it wrong, sorry.