Enable Multi-MouseButton Support for dragPan

[gottesman]

This PR enhances the functionality of dragPan in MapLibre GL JS, addressing feature request #5341.
It introduces the ability to configure one or multiple mouse buttons for the dragPan interaction using the MouseEvent.button property.

Previously, dragPan was limited to left mouse button, restricting user interaction and personalization. This improvement provides greater flexibility for users who want to customize the drag behavior of the map.

Examples

1. Configuring on Map Initialization:

const map = maplibregl.Map({
    container: 'map',
    dragPan: {
        buttons: [0,1]  // Enable left button (0) and middle button (1)
    }
});

2. Updating on DragPan Enable:

map.dragPan.enable({
    buttons: [1]  // Enable only middle button (1)
})

Launch Checklist

• 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.
• Include before/after visuals or gifs if this PR includes visual changes.
• Write tests for all new functionality.
• Document any changes to public APIs.
• Post benchmark scores.
• Add an entry to CHANGELOG.md under the ## main section.

[codecov]

Codecov Report

❌ Patch coverage is 86.11111% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.83%. Comparing base (f1d58f2) to head (921a48c).
⚠️ Report is 569 commits behind head on main.

Files with missing lines	Patch %	Lines
src/ui/handler/drag_handler.ts	62.50%	3 Missing ⚠️
src/ui/handler/drag_move_state_manager.ts	91.66%	1 Missing ⚠️
src/ui/handler/mouse.ts	92.30%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5354      +/-   ##
==========================================
- Coverage   91.84%   91.83%   -0.02%     
==========================================
  Files         282      282              
  Lines       38908    38930      +22     
  Branches     6827     6831       +4     
==========================================
+ Hits        35735    35750      +15     
- Misses       3046     3052       +6     
- Partials      127      128       +1     

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

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[HarelM]

How will this behave when rotating with right click (default behavior) and setting drag pan to right click?

[HarelM]

Instead of passing buttons it might be better to pass a predicate to override the default one - what happens if someone wants to have right click with control button for panning?

[gottesman]

Good to point that out! I've tried setting the right click for panning and it looks like if dragRotate is enabled it will not pan the map. So it is safe for now?.
I would gladly accept any help with a better approach since I'm not good with typescript and have not much experience in large projects in general.

[HarelM]

_correctEvent is basically what you want to override.
I would try and find a way to pass it down instead if adding a buttons parameter and pass that down...

[HarelM]

Any updates on the feedback and questions I asked?

[jiacona]

Hi @HarelM, I also need this functionality and am most of the way to an implementation that addresses your comments here. Should I just open a new PR?

[HarelM]

My main concern about this feature is button collision when you override one gesture and "cancel" other gesture.

[jiacona]

Yes, I can see how you could run into problems if the predicate you use conflicts with another handler. Is it rotate, pitch, and roll you are concerned about?

I was thinking it would be simple enough to allow specifying a checkCorrectEvent predicate for each of the different handlers. That way if you want to customise one, you can also customise any others that might conflict with your new predicate.

[HarelM]

There's a few more handlers: zoom, context menu, scroll, two finger gesture/block.
I think adding configuration for all of those might be complicated, but it's possible to add a map from handler to predicate as part of the map options, similar to localization (to some extent).
I'm not sure it would be very useful, but I guess it's an option...

[jiacona]

I'm wondering if we're making this all more complicated than it needs to be. I really only need dragPan on middle mouse (in addition to the existing buttons), and I suspect that is all the original issue author wanted as well. What would you think about dropping the idea of button configuration and just make dragPan handled on middle-mouse by default?

[HarelM]

I think that you can hack the following in theory (I haven't fully tested it):
(map.dragPan._mousePan as any)._moveStateManager._correctEvent =...
It is very specific to how maplibre is currently structured, but it might just work.
Making a patch that only support this use case without defining a proper API to support this will introduce backward compatibility issues in the future I believe.

[jiacona]

I think that you can hack the following in theory (I haven't fully tested it): (map.dragPan._mousePan as any)._moveStateManager._correctEvent =... It is very specific to how maplibre is currently structured, but it might just work.

Ah yes, interesting. I would be pretty hesitant to reach into the internals like that without a proper API.

Making a patch that only support this use case without defining a proper API to support this will introduce backward compatibility issues in the future I believe.

This is the minimal change I am proposing. Are there reasons not to want to support drag pan with middle mouse by default?

diff --git a/src/ui/handler/drag_move_state_manager.ts b/src/ui/handler/drag_move_state_manager.ts
index 5ef48fb72..a8b5b0097 100644
--- a/src/ui/handler/drag_move_state_manager.ts
+++ b/src/ui/handler/drag_move_state_manager.ts
@@ -1,12 +1,14 @@
 import {DOM} from '../../util/dom';

 const LEFT_BUTTON = 0;
+const MIDDLE_BUTTON = 1;
 const RIGHT_BUTTON = 2;

 // the values for each button in MouseEvent.buttons
 const BUTTONS_FLAGS = {
     [LEFT_BUTTON]: 1,
-    [RIGHT_BUTTON]: 2
+    [RIGHT_BUTTON]: 2,
+    [MIDDLE_BUTTON]: 4,
 };

 function buttonNoLongerPressed(e: MouseEvent, button: number) {
diff --git a/src/ui/handler/mouse.ts b/src/ui/handler/mouse.ts
index 30dd66471..1e712a6cd 100644
--- a/src/ui/handler/mouse.ts
+++ b/src/ui/handler/mouse.ts
@@ -23,6 +23,7 @@ export interface MousePitchHandler extends DragMoveHandler<DragPitchResult, Mous
 export interface MouseRollHandler extends DragMoveHandler<DragRollResult, MouseEvent> {}

 const LEFT_BUTTON = 0;
+const MIDDLE_BUTTON = 1;
 const RIGHT_BUTTON = 2;

 const assignEvents = (handler: DragHandler<DragPanResult, MouseEvent>) => {
@@ -39,7 +40,9 @@ export function generateMousePanHandler({enable, clickTolerance}: {
     enable?: boolean;
 }): MousePanHandler {
     const mouseMoveStateManager = new MouseMoveStateManager({
-        checkCorrectEvent: (e: MouseEvent) => DOM.mouseButton(e) === LEFT_BUTTON && !e.ctrlKey,
+        checkCorrectEvent: (e: MouseEvent) =>
+            (DOM.mouseButton(e) === LEFT_BUTTON && !e.ctrlKey) ||
+            (DOM.mouseButton(e) === MIDDLE_BUTTON),
     });
     return new DragHandler<DragPanResult, MouseEvent>({
         clickTolerance,

[HarelM]

I don't think this is the same as the original issue, I'm also not sure why you'd need to support both left click and middle click to drag...

[jiacona]

Yes, you are correct. And as I've been exploring this more for our own use I've run into the issue you were worried about with conflicting handlers.

For now I'm using your suggestion to do this

(map.dragPan._mousePan as any)._moveStateManager._correctEvent =...

It doesn't quite work on it's own if you want middle mouse support because middle mouse is not considered valid by MoveStateManager.isValidMoveEvent so I had to patch that as well:

export const LEFT_BUTTON = 0
export const MIDDLE_BUTTON = 1
export const RIGHT_BUTTON = 2

export const BUTTONS_FLAGS = {
  [LEFT_BUTTON]: 1,
  [MIDDLE_BUTTON]: 4,
  [RIGHT_BUTTON]: 2,
}

const manager = (map.dragPan as any)._mousePan._moveStateManager
manager.isValidMoveEvent = function (e: MouseEvent): boolean {
  if (this._eventButton === undefined) return false

  const flag = BUTTONS_FLAGS[this._eventButton]
  if (flag === undefined) return false

  return valid = e.buttons !== undefined && (e.buttons & flag) === flag
}

I'll see if a reasonable pattern emerges for setting groups of handlers in a coherent way as I'm implementing it for our use case.