Input Events - Implement 'capture' API for Mouse events

[bryphe]

Proposal: capture-like API for mouse events

Why?

Often for UI elements, after the initial mousedown, the component needs to track the mouse movement and actions exclusively. Some examples of this:

• <Button /> - for a click event, you don't want to dispatch it immediately on the mousedown - most UIs will wait for the mouseup before dispatching. If the mouseup occurs elsewhere, the UI does not fire a click event. While in this limbo-state between mousedown and mouseup, hovering over other elements is a no-op.
• <Slider /> and <Scrollbar /> - once a mousedown has occurred, we want to track the mouse movement, even if the mouse cursor moves away from the slider or scrollbar. We can still update the value of the slider / scrollbar, until the user releases via a mouseup event.
• Drag and Drop - for an element that supports drag-and-drop, we want to contain the mousemove and mouseup until the drag/drop gesture has completed.

Proposal

Add a Mouse.setCapture API that could be used as follows:

/* While capturing is active, events will _only_ be forwarded to these handlers */
Mouse.setCapture(~onMouseDown, ~onMouseUp, ~onMouseMove);
...
/* Release capture */
Mouse.releaseCapture();

Example usage

For a button element, we could add an onMouseDown handler that looks like this:

let onMouseDown = (evt) => {
    let noop = (_evt) => ();

    let releaseCapture = ref(None);
    let capturedMouseUp = (evt) => {
         dispatchClickEvent(evt);
         Mouse.releaseCapture();
    };
    Mouse.setCapture(~onMouseDown=noop, ~onMouseMove=noop, ~onMouseUp=capturedMouseUp);
};

The <Button /> could do extra validation - like verify the onMouseUp actually occurred over the element, or that it was within a certain distance, etc.