.end api method

changelog.markdown

@@ -1,3 +1,7 @@
+# 1.3.0 Terror
+
+Introduced an `.end` instance API method that gracefully ends the drag event using the last known valid drop target.
+
 # 1.2.4 Brother in Arms
 
 - The `accepts` option now takes a fourth argument, `sibling`, giving us a hint of the precise position the item would be dropped in

dragula.js

@@ -25,6 +25,7 @@ function dragula (containers, options) {
   if (o.direction === void 0) { o.direction = 'vertical'; }
 
   var api = emitter({
+    end: end,
     cancel: cancel,
     remove: remove,
     destroy: destroy
@@ -103,6 +104,14 @@ function dragula (containers, options) {
     return el.tagName === 'A' || el.tagName === 'BUTTON';
   }
 
+  function end () {
+    if (!_dragging) {
+      return;
+    }
+    var item = _copy || _item;
+    drop(item, item.parentElement);
+  }
+
   function release (e) {
     if (!_dragging) {
       return;
@@ -114,21 +123,21 @@ function dragula (containers, options) {
     var elementBehindCursor = getElementBehindPoint(_mirror, clientX, clientY);
     var dropTarget = findDropTarget(elementBehindCursor, clientX, clientY);
     if (dropTarget && (o.copy === false || dropTarget !== _source)) {
-      drop();
+      drop(item, dropTarget);
     } else if (o.removeOnSpill) {
       remove();
     } else {
       cancel();
     }
+  }
 
-    function drop () {
-      if (isInitialPlacement(dropTarget)) {
-        api.emit('cancel', item, _source);
-      } else {
-        api.emit('drop', item, dropTarget, _source);
-      }
-      cleanup();
+  function drop (item, target) {
+    if (isInitialPlacement(target)) {
+      api.emit('cancel', item, _source);
+    } else {
+      api.emit('drop', item, target, _source);
     }
+    cleanup();
   }
 
   function remove () {

readme.markdown

@@ -87,6 +87,10 @@ When an element is dropped onto a container, it'll be placed near the point wher
 
 The `dragula` method returns a tiny object with a concise API. We'll refer to the API returned by `dragula` as `drake`.
 
+#### `drake.end()`
+
+Gracefully end the drag event as if using **the last position marked by the preview shadow** as the drop target. The proper `cancel` or `drop` event will be fired, depending on whether the item was dropped back where it was originally lifted from _(which is essentially a no-op that's treated as a `cancel` event)_.
+
 #### `drake.cancel(revert)`
 
 If an element managed by `drake` is currently being dragged, this method will gracefully cancel the drag action. You can also pass in `revert` at the method invocation level, effectively producing the same result as if `revertOnSpill` was `true`.