API mouse support

[jerch]

There are several ideas floating around how mouse support in the API could be utilized - #2323 (comment) and #2323 (comment).

So lets discuss whether we want mouse primitives in the public API and how it could look like.

[jerch]

It seems we will end up with a browser and a common part for mouse related stuff. While the browser part is yet to come the common part already took shape in #2323.

In general I see two interesting use cases for public API regarding the mouse:

• intercept/handle mouse events from the browser at grid level
  This could happen in the browser part, lets say it creates a custom mouse event with grid metrics. A custom handler could attach to it and do its business. If we want to go that route, CoreMouseService.triggerMouseEvent would just be a handler for that. The big advantage I see here is the fact that ppl dont have to deal with the low level stuff like registering browser mouse event listener and tracking their states. Instead they can announce what events they are interested in and get those readily delivered in col/row metrics.
• creating backend mouse reports
  Thats where triggerMouseEvent would be useful. If ppl wish to automate the pty app, they can simply create mouse events on their own with grid metrics.

API Proposal:

// mouse event types we offer
enum MouseEventType {
  // no mouse events
  NONE = 0,
  // mousedown gets reported in viewport
  DOWN = 1,
  // mouseup gets reported in viewport
  // + globally if DOWN is also registered
  UP = 2,
  // reports mousemove events if a button is held
  DRAG = 4,
  // reports mousemove if no button is held
  MOVE = 8,
  // any wheel events (up/down only)
  WHEEL = 16
}

// for button and action we could either go with synthetized types
// or an enum (const enum would not work for pure JS)
interface IMouseEvent {
  col: number;
  row: number;
  button: 'left' | 'middle' | ... ;
  action: 'up' | 'down' | ... ;
}

// fired by the browser mouse service
onMouseEvent((e: IMouseEvent) => boolean): IDisposable;
// tell the browser mouse service to install needed listener
requestMouseEventType(type: MouseEventType): void;

// to create a mouse report to the pty
triggerMouseEvent(e: IMouseEvent): boolean;

This kinda resembles what currently CoreMouseService implements. The usage would be pretty straight forward.

Example: A local REPL wants to catch simple button clicks within the terminal viewport.

// request down events to be enabled
term.requestMouseEventType(MouseEventType.DOWN);
// register some click handler
term.onMouseEvent(e => console.log(`xy: [${e.col}, ${e.row}], button: ${e.button}`));
...
// when done reset listeners
term.requestMouseEventType(MouseEventType.NONE);

Example: Some app at the pty registered some mouse protocol and waits for mouse input.

// fake a click - sends automatically the correct report to the backend
term.triggerMouseEvent({col: 10, row: 5, button: 'left', action: 'down'});

Thats just a rough outline atm, questions like correct lifecycling and multiple handlers at once are not covered yet.

[Tyriar]

I don't think we should go in this direction as it feels like we're just implementing puppeteer or something. Consumers can already built their own helpers for doing this provided they have the cell dimensions (which we should expose #702), this is the case for a regular renderer and a monaco-based one.