Make it easier to implement visual cues when using activation constraints.

[irobot]

Context

Activation constraints are used when we want to prevent accidental dragging or when pointer press can mean more than "start dragging".

A typical use case is a button that needs to respond to both "click" and "drag" gestures. Clicks can be distinguished from drags based on how long the pointer was held pressed.

The problem

A control that responds differently to a pointer press based on duration or distance can be confusing to use -- the user has to guess how long to keep holding or how far to keep dragging until their intent is acknowledged.

Implementing such cues is currently possible by attaching extra event listeners so that we know when a drag is pending. Furthermore, the listener needs to have access to the same constraints that were applied to the sensor initiating the drag. This can be made to work in simple cases, but it becomes error-prone and difficult to maintain in complex scenarios.

Solution

This PR proposes the addition of two new events: onDragPending and onDragAbort.

onDragPending

A drag is considered to be pending when the pointer has been pressed and there are activation constraints that need to be satisfied before a drag can start.

This event is initially fired on pointer press. At this time offset (see below) will be undefined.

It will subsequently be fired every time the pointer is moved. This is to enable visual cues for distance-based activation.

The event's payload contains all the information necessary for providing visual feedback:

export interface DragPendingEvent {
  id: UniqueIdentifier;
  constraint: PointerActivationConstraint;
  initialCoordinates: Coordinates;
  offset?: Coordinates | undefined;
}

onDragAbort

A drag is considered aborted when an activation constraint for a pending drag was violated. Useful as a prompt to cancel any visual cue animations currently in progress. Note that this event will not be fired when dragging ends or is canceled.

Demo

See Press Delay With Visual Cue and Minimum Distance With Visual Cue

[changeset-bot]

🦋 Changeset detected

Latest commit: 9175566

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@dnd-kit/core	Minor
@dnd-kit/modifiers	Major
@dnd-kit/sortable	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR