Mouse drag behaviour and fling damping

[ben-milanko]

This PR makes some minor changes to the drag behaviour aimed at improving the experience on web and desktop.

First, if the cursor leaves the screen while dragging, the fling drag behaviour will send the map camera moving in the opposite direction.

Before:

Screen.Recording.2025-10-18.at.14.11.15.mov

After:

Screen.Recording.2025-10-18.at.14.09.54.mov

Secondly, I would like to modify the damping behaviour of the fling for desktop users. This has been made part of the public API via InteractionOptions the default has been left per the current.

I've found a value of 2 is closer to the behaviour of Google Maps on web.

[JaffaKetchup]

Hey, thanks for submitting a PR! These look like good improvements.

It would be great if the new behaviour of reversing the direction of movement of the cursor leaves the edge of the screen was also toggleable. Does Google Maps and/or Leaflet on web behave the same way (sorry, I can't check right now)?

I'm not able to test any changes right now, but I'll review and hopefully merge once I return.

[ben-milanko]

Hey @JaffaKetchup ,
The current behaviour is that the fling reverses direction as the cursor leaves the screen. The new behaviour proposed in this PR is that the fling maintains its direction. This new behaviour matches what I can see in Leaflet and Google Maps.

[JaffaKetchup]

Ah sorry, misread! Ok, I'll have a look :)

[JaffaKetchup]

Hey @ben-milanko, thanks, and sorry it's taken so long to get to this!

The feature addition of flingAnimationDampingRatio looks good to me (bar the quick documentation fix).

However, it looks like the fix part of the PR has introduced a regression.

I will say that I found it difficult to reproduce the original issue on my computer, but I could in a few cases. This appears to have been fixed from what I can see.

However, when the user now has a curved fling before release, the direction of the fling is incorrect. The direction should be the last direction of the pointer, not the overall direction of the preceding gesture.

Correct behaviour on master:

Screenrecorder-2025-11-23-15-32-11-589.mp4

Incorrect behaviour on touchscreen:

Screenrecorder-2025-11-23-15-31-17-780.mp4

Incorrect behaviour on desktop:

Recording.2025-11-23.153740.mp4

Do you think it makes sense to split out the fix part from this PR so we can merge the feature, and merge the fix later (if you're still willing to work on it?).

[ben-milanko]

Hey thanks for looking at the PR @JaffaKetchup. I can see the issue from your videos.

The original issue with the rebound behaviour seems to still be there as well on the base branch, I don't think this was fixed.
It's easier to replicate with the window moved to the edge of the screen.

I've added an additional tracked point so the fling can correctly use the last swiped direction for the fling rather than the direction from the start to end point. Are you okay with this change?