feat(drag-drop): cancel an in-progress drag with Escape or cancelDrag()

CHANGELOG.md

@@ -14,6 +14,12 @@ All notable changes for each version of this project will be documented in this
 
 ### New Features
 
+- `IgxDragDirective`
+    - Added `cancelDrag()` method that cancels the drag in progress without dropping. The element returns to where it was before the drag, and a drop area under the dragged element receives only a `leave` event.
+    - Added `cancelOnEscape` input (default `false`). When set to `true`, pressing `Escape` while dragging cancels the drag.
+    - `IDragBaseEventArgs` has a new `cancelled` property, which is `true` for the `dragEnd` and `transitioned` events of a canceled drag. If your app moves or reorders items in a `dragEnd` or `transitioned` handler, check `cancelled` there and restore the original state instead. Call `transitionToOrigin()` in the `dragEnd` handler to animate the element back.
+- `IgxChipComponent`, `IgxChipsAreaComponent`
+    - For a canceled chip drag (e.g. with `chip.dragDirective.cancelDrag()`), `originalEvent.cancelled` of the `moveEnd` event is `true`.
 - `IgxPivotGridComponent`
     - `IgxPivotRowDimensionHeaderTemplateDirective` (`igxPivotRowDimensionHeader`) is now included in `IGX_PIVOT_GRID_DIRECTIVES` and `IgxPivotGridModule`, so the row dimension header template can be declared inside the pivot grid in standalone components.
 - `IgxTreeGridComponent`
@@ -36,6 +42,9 @@ All notable changes for each version of this project will be documented in this
 
 ### Bug Fixes
 
+- `IgxDragDirective`
+    - `transitionToOrigin()` with a start location equal to the origin location no longer animates. Previously the vertical start position was compared with the horizontal origin.
+    - `transitionToOrigin()` and `transitionTo()` now emit `transitioned` right away when the element is already at the target or there is no ghost to animate (e.g. its creation was canceled in `ghostCreate`). Previously no `transitioned` was emitted and the next drag did not start correctly.
 - `IgxGridComponent`, `IgxTreeGridComponent`, `IgxHierarchicalGridComponent`, `IgxPivotGridComponent`
     - Copying when only columns are selected now copies the selected columns' data. Previously the `gridCopy` event received only the first record, the clipboard stayed empty and an error was thrown.
     - `IgxColumnComponent.pin(index)` no longer throws when the target pinning area (start or end) has no pinned columns yet, and `unpin(index)` no longer throws when all columns are pinned.

projects/igniteui-angular/chips/README.md

@@ -158,7 +158,7 @@ The chips can be focused using the `Tab` key or by clicking on them. Chips can b
 | Name | Argument Type | Description |
 |:--:|:---|:---|
 | `moveStart` | `IBaseChipEventArgs` | Fired when the chip moving(dragging) starts. |
-| `moveEnd` | `IBaseChipEventArgs` | Fired when the chip moving(dragging) ends. |
+| `moveEnd` | `IBaseChipEventArgs` | Fired when the chip moving(dragging) ends. When the drag was canceled (e.g. with `dragDirective.cancelDrag()`), `originalEvent.cancelled` is `true`. |
 | `remove ` | `IBaseChipEventArgs` | Fired when the chip remove button is clicked. |
 | `chipClick ` | `IChipClickEventArgs` | Fired when the chip is clicked instead of dragged. |
 | `selectedChanging` | `IChipSelectEventArgs` | Fired when the chip is being selected/deselected. Cancellable |
@@ -184,7 +184,7 @@ The chips can be focused using the `Tab` key or by clicking on them. Chips can b
 | `reorder ` | `IChipsAreaReorderEventArgs` | Fired when the chips order should be changed(from dragging). Requires custom logic for actual reorder. |
 | `selectionChange ` | `IChipsAreaSelectEventArgs` | Fired for all initially selected chips and when chip is being selected/deselected. |
 | `moveStart  ` | `IBaseChipsAreaEventArgs` | Fired when any chip moving(dragging) starts. |
-| `moveEnd ` | `IBaseChipsAreaEventArgs` | Fired when any chip moving(dragging) ends. |
+| `moveEnd ` | `IBaseChipsAreaEventArgs` | Fired when any chip moving(dragging) ends. When the drag was canceled (e.g. with `dragDirective.cancelDrag()`), `originalEvent.cancelled` is `true`. |
 
 ### Properties
 | Name   | Return Type | Description |

projects/igniteui-angular/directives/src/directives/drag-drop/README.md

@@ -113,6 +113,34 @@ When the transition animation ends if a ghost is created it will be removed and
 
 If the user want to have other types of animations that involve element transformations he can do that like any other element either using the Angular Animations or straight CSS Animations to either the base `igxDrag` element or its ghost. If he wants to apply them to the ghost he would need to define a custom ghost and apply animations to that element.
 
+#### Canceling a drag
+
+A drag that is in progress can be canceled by calling the `cancelDrag` method, or by pressing `Escape` when `cancelOnEscape` is set to `true`. When canceled, no drop is performed: an `igxDrop` area under the dragged element receives only a `leave` event, and `dragEnd` is emitted with `cancelled` set to `true`. The element then returns to where it was before the drag: the ghost element is removed, or, when `ghost` is `false`, the base element is moved back to its position before the drag. Any following pointer move or release is ignored until a new drag starts. The `transitioned` event that follows also has `cancelled` set to `true`, so logic that runs when the movement ends can skip any changes made during the drag. If your app moves or reorders items in a `dragEnd` or `transitioned` handler, check `cancelled` there and restore the original state instead.
+
+`Escape` is handled on the document, because focus is usually not on the dragged element during a pointer drag. While a drag is canceled with `Escape`, the key event is not propagated further, so it does not also close a dialog or an overlay.
+
+```html
+<div igxDrag [cancelOnEscape]="true">
+    <span>Drag Me!</span>
+</div>
+```
+
+To animate the element back to its origin instead, call `transitionToOrigin` in the `dragEnd` handler:
+
+```html
+<div igxDrag [cancelOnEscape]="true" (dragEnd)="onDragEnd($event)">
+    <span>Drag Me!</span>
+</div>
+```
+
+```typescript
+public onDragEnd(event: IDragBaseEventArgs) {
+    if (event.cancelled) {
+        event.owner.transitionToOrigin();
+    }
+}
+```
+
 ## API
 
 ### Inputs
@@ -123,16 +151,17 @@ If the user want to have other types of animations that involve element transfor
 | `dragTolerance`    | number | 5 | Indicates when the drag should start (in pixels). By default the drag starts after the draggable element is moved by 5px |
 | `ghostHost` | any | null | Sets the element to which the dragged element will be appended.
 | `ghostClass`  | string | '' | Sets a custom class that will be added to the `igxDrag` element. |
+| `cancelOnEscape` | boolean | false | Sets whether pressing `Escape` while dragging cancels the drag. |
 
 ### Outputs
 
 | Name | Description | Cancelable | Parameters |
 |------|-------------|------------|------------|
 | `dragStart` | Event triggered when any movement starts. | true | `IDragBaseEventArgs` |
 | `dragMove` | Event triggered for every frame where the `igxDrag` element has been dragged. | true | `IDragMoveEventArgs` |
-| `dragEnd` | Event triggered when the user releases the element area that is not inside an `igxDrop`. This is triggered before any animation starts. | false | `IDragBaseEventArgs` |
+| `dragEnd` | Event triggered when the user releases the element area that is not inside an `igxDrop`, or when the drag is canceled. In that case its `cancelled` argument is `true`. This is triggered before any animation starts. | false | `IDragBaseEventArgs` |
 | `click` | Even triggered when the user performs a click and not dragging. This is the native event. | false | MouseEvent |
-| `transitioned` | Event triggered after any movement of the drag element has ended. This is triggered after all animations have ended and before the ghost is removed. | false | `IDragBaseEventArgs` |
+| `transitioned` | Event triggered after any movement of the drag element has ended. This is triggered after all animations have ended and before the ghost is removed. When the drag was canceled, its `cancelled` argument is `true`. | false | `IDragBaseEventArgs` |
 | `ghostCreate` | Event triggered right before the ghost element is created | false | `IDragGhostBaseEventArgs` |
 | `ghostDestroy` | Event triggered right before the ghost element is destroyed | false | `IDragGhostBaseEventArgs` |
 
@@ -149,6 +178,7 @@ If the user want to have other types of animations that involve element transfor
 
 | Name | Description | Parameters | Return Type |
 |------|-------------|------------|-------------|
+| `cancelDrag` | Cancels the drag that is in progress without dropping. `dragEnd` is emitted with `cancelled` set to `true` and the element returns to where it was before the drag. Does nothing when no drag is in progress. | - | void |
 | `setLocation` | Sets new location for the igxDrag directive. When ghost is enable and it is not rendered it will be ignored. | `newLocation?:` [`IgxDragLocation`](#IgxDragLocation) | void |
 | `transitionToOrigin` | Animates the element from its current location to its initial position. If it was not moved or no start location is specified nothing would happen . | customTransitionArgs?: [`IDragCustomTransitionArgs`](#IDragCustomTransitionArgs), `startLocation?:` [`IgxDragLocation`](#IgxDragLocation), | void |
 | `transitionTo` | Animates the element from its current location to specific location or DOM element. If it was not moved or no start location is specified nothing would happen. | `target:` [`IgxDragLocation`](#IgxDragLocation)\|ElementRef, customTransitionArgs?: [`IDragCustomTransitionArgs`](#IDragCustomTransitionArgs), `startLocation?:` [`IgxDragLocation`](#IgxDragLocation) | void |