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?).

[JaffaKetchup]

This doesn't match the default value in the constructor (5.0).

Suggested change

	/// Defaults to 2.0.
	/// Defaults to 5.0.