feat(cdk/drag-drop): support immediate drag with preview snapped to cursor on mousedown

[matthewerwin]

The existing implementation of the CDK drag-drop is restricted such that there is no workaround for situations where the drag object should be snapped to the cursor.

1. Even when dragStartDelay = 0 and dragStartThreshold = 0 (indicating no mouse movement is required to start) the existing implementation will not start actually dragging (and rendering preview) until after movement by >= 1px.
2. There is no existing way to center the preview under the cursor b/c of hardcoded translate3d( ) calls with pre-computed offsets designed to fix the initial preview location to an offset position to mirror the undragged location of the draggable element.
3. Using cdkDragConstrainPosition does not retain the dragEntered/dragExited behavior of the existing droplist and so is unusable for these purposes as well.

For an example use case:

Consider the chess-boards that are present on Lichess/Chess.com -- clicking on a chess piece to drag immediately snaps the piece centered on the cursor immediately after the mouse is pressed. Waiting until the mouse is moved 1px is problematic for speed, for visible immediate visible selection, and for accuracy based on touch/mouse movement for high-speed games.

This PR is simple - it introduces a new input snapToCursor that places the preview directly in the center of the cursor and hooks 'mousedown' event in to immediate trigger an initial drag state when dragStartDelay = 0 and dragStartThreshold = 0 & a preview is available.

Thanks for your support

[crisbeto]

I'm not sure I follow this. So the only behavior difference here is that the preview will show up on the mousedown rather than the next mousemove?

[matthewerwin]

See this chessboard for example:

Chess.com Explorer

Click on any piece to move it and you will see the drag immediately starts. This is the effect of the snapToCursor combined with immediate preview rendering (on mousedown/touchstart).

[crisbeto]

I think in that case a better way to approach it would be to check that threshold/delay are at 0 and then call _startDragSequence from the "down" handler. It might be necessary to move some logic out of _pointerMove so it can be reused.

[matthewerwin]

@crisbeto I had looked at that -- however the entirety of the _pointerMove function must be executed in this case especially around the constrainPosition and other logic executed in that method in addition to _startDragSequence as a setup step being called.

I had tried to limit it to just a few calls but that either breaks functionality or results in excess redundant code where this version cleanly was backwards-compatible.

[crisbeto]

My thinking was that we can move the whole block that's guarded by !this._hasStartedDragging() out into a separate function. The rest shouldn't be executed before dragging has started anyways.

[crisbeto]

I'm not sure if centering the element under the cursor is common enough that it should be a default behavior. Also couldn't you get the same result by offsetting it using a margin?

[matthewerwin]

Hey @crisbeto -- this won't affect default behavior, it's fenced off to only occur when snapToCursor input is set on cdkDragPreview.

Margin/etc. won't work because the transform is applied internally. As I wrote in the PR notes, the CDK dragdrop transform is fixed and automatically calculated transform on _pointerMove. So there are several issues with margin -- one is that it would have to be calculated in an attempt to override the transform by implementor using (cdkDragMoved) event which then defeats the ability to start preview on mousedown (since cdkDragMoved isn't fired until movement), and secondarily the shift in the container position would change location calculations that are used internally on CDK dragdrop for determining entered/exited events, lastly you cannot access the preview containers boundaries until it is rendered and it's all private members so even then requires a class DOM selector to get to it from handler in the first place.

I explored a lot of different options to get around the limitations of the CDK Dragdrop (DOM access to the preview inside a template, controlling/recalc position of the preview dynamically externally that messed up the entered/exited, and the separate issue of having drag behavior correctly computed immediately on mousedown/touchstart). This PR elegantly handles those scenarios while maintaining existing behavior of the dragdrop.

[crisbeto]

Sure the behavior is fenced off, but it's still a public API that we have to support and document. We also have to ensure that it works correctly with other APIs (e.g. constrainPosition). It doesn't mean that we shouldn't do it, but we should come up with something that is a bit more flexible.

[matthewerwin]

@crisbeto I'm not opposed to that & happy to do some more coding around that. I'm not sure what the additional use-case requirements would be though -- did you have a specific alternate scenarios in mind?

[crisbeto]

Off the top of my head, it could be a function that lets you determine the offset of the preview.