@atlaskit/pragmatic-drag-and-drop 1.0.2 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @atlaskit/pragmatic-drag-and-drop
 
+## 1.1.1
+
+### Patch Changes
+
+- [#83702](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/83702) [`4d9e25ab4eaa`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/4d9e25ab4eaa) - Updating the descriptions of Pragmatic drag and drop packages, so they each provide a consistent description to various consumers, and so they are consistently formed amongst each other.
+
+  - `package.json` `description`
+  - `README.md`
+  - Website documentation
+
+## 1.1.0
+
+### Minor Changes
+
+- [#82653](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/82653) [`136d8da5542d`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/136d8da5542d) - Adding additional information to `onDrop()` events to expose what the final `dropEffect` was for a drag operation.
+
+  ```ts
+  type DropData = {
+    dropEffect: DataTransfer['dropEffect'];
+  };
+
+  monitorForElements({
+    onDrop(payload) {
+      const drop: DropData = payload.drop;
+    },
+  });
+  ```
+
+  Fixing a bug where `preventUnhandled.start()` would prevent unhandled drag operations forever. It now only prevents unhandled drag operations for the current drag operation. `preventUnhandled.stop()` is now optional, as `preventUnhandled.start()` now tidies up itself. You can still leverage `preventUnhandled.stop()` to stop preventing unhandled drag operations during a drag.
+
+  Tightening the `getDropEffect()` function on drop targets slightly so that `"none"` cannot be provided. Using `"none"` as the drop effect would break the expected behaviour for nested drop targets.
+
 ## 1.0.2
 
 ### Patch Changes

package/README.md

@@ -1,43 +1,7 @@
 # Pragmatic drag and drop
 
-A performance optimized drag and drop framework
+> Fast drag and drop for any experience on any tech stack
 
-> ℹ️ This package is in early access. We have not yet guaranteed API stability
+The core package for Pragmatic drag and drop.
 
-## Background
-
-There are a wealth of existing drag and drop libraries for the web. Some drag and drop libraries are general purpose (e.g. `@shopify/draggable`, `react-dnd`), and some are for specific experiences (e.g. `react-beautiful-dnd` is for lists and connected lists). Some libraries leverage the platform's built in drag and drop capabilities, and some rebuild the drag and drop operation from scratch.
-
-Every drag and drop solution will make tradeoffs regarding feature sets, user experience, startup performance and runtime performance.
-
-The goals of `@atlaskit/pragmatic-drag-and-drop` are:
-
-- 🚀 Speed: Best of class startup and runtime performance
-- 🤸 Flexibility: Can be used to power any interaction
-- 🧑‍🦽 Accessibility\*: Ensuring that all users have a good experience
-
-> \*Accessible experiences are achieved through alternative keyboard and screen reader flows. Unfortunately, the browsers drag and drop behaviour is not accessible (yet). But don't worry, we have a comprehensive guide and toolchain to help you be successful here
-
-## Core characteristics
-
-- 🌎 Platform powered: leverages the browsers drag and drop capabilities
-- 🐁 Tiny: ~`4.5kB` base
-- 🪡 Incremental: only pay for what you use
-- ⏳ Deferred compatible: consumers can delay the loading of `@atlaskit/pragmatic-drag-and-drop` (and related packages) in order to improve page load speeds
-- 🎨 Headless: full rendering and style control
-- 🦊 Cross browser support: full feature support in Firefox, Safari and Chrome
-- 📱 Touch device compatible
-- 🎁 Addons: patterns that allow sharing small pieces of functionality that can be added together
-- 🎄 Framework agnostic: works with any frontend framework
-- 👾 Virtualization support
-- 🧑‍🦽 Accessible: comprehensive toolchain and patterns for creating highly accessible experiences
-
-## Installation
-
-```sh
-yarn add @atlaskit/pragmatic-drag-and-drop
-```
-
-## Usage
-
-Detailed docs and example usage can be found on [atlassian.design](https://atlassian.design/components/pragmatic-drag-and-drop/).
+[📖 Documentation](https://atlassian.design/components/pragmatic-drag-and-drop/)

package/dist/cjs/ledger/dispatch-consumer-event.js

@@ -112,12 +112,14 @@ function makeDispatch(_ref) {
     },
     drop: function drop(_ref5) {
       var current = _ref5.current,
+        drop = _ref5.drop,
         updatedSourcePayload = _ref5.updatedSourcePayload;
       dragStart.flush();
       scheduleOnDrag.cancel();
       safeDispatch({
         eventName: 'onDrop',
         payload: {
+          drop: drop,
           source: updatedSourcePayload !== null && updatedSourcePayload !== void 0 ? updatedSourcePayload : source,
           location: {
             current: current,

package/dist/cjs/ledger/lifecycle-manager.js

@@ -12,9 +12,11 @@ var _detectBrokenDrag = require("../util/detect-broken-drag");
 var _fixPostDragPointerBug = require("../util/fix-post-drag-pointer-bug");
 var _getInput = require("../util/get-input");
 var _dispatchConsumerEvent = require("./dispatch-consumer-event");
-var isActive = false;
+var globalState = {
+  isActive: false
+};
 function canStart() {
-  return !isActive;
+  return !globalState.isActive;
 }
 function getNativeSetDragImage(event) {
   if (event.dataTransfer) {
@@ -47,15 +49,18 @@ function start(_ref2) {
   if (!canStart()) {
     return;
   }
-  isActive = true;
   var initial = getStartLocation({
     event: event,
     dragType: dragType,
     getDropTargetsOver: getDropTargetsOver
   });
-  var current = initial;
+  globalState.isActive = true;
+  var state = {
+    current: initial
+  };
+
   // Setting initial drop effect for the drag
-  setDropEffect({
+  setDropEffectOnEvent({
     event: event,
     current: initial.dropTargets
   });
@@ -67,17 +72,17 @@ function start(_ref2) {
   function updateDropTargets(next) {
     // only looking at whether hierarchy has changed to determine whether something as 'changed'
     var hasChanged = hasHierarchyChanged({
-      current: current.dropTargets,
+      current: state.current.dropTargets,
       next: next.dropTargets
     });
 
     // Always updating the state to include latest data, dropEffect and stickiness
     // Only updating consumers if the hierarchy has changed in some way
     // Consumers can get the latest data by using `onDrag`
-    current = next;
+    state.current = next;
     if (hasChanged) {
       dispatch.dragUpdate({
-        current: current
+        current: state.current
       });
     }
   }
@@ -87,12 +92,12 @@ function start(_ref2) {
       target: event.target,
       input: input,
       source: dragType.payload,
-      current: current.dropTargets
+      current: state.current.dropTargets
     });
     if (nextDropTargets.length) {
       // 🩸 must call `event.preventDefault()` to allow a browser drop to occur
       event.preventDefault();
-      setDropEffect({
+      setDropEffectOnEvent({
         event: event,
         current: nextDropTargets
       });
@@ -102,22 +107,7 @@ function start(_ref2) {
       input: input
     });
   }
-  function onDrop(args) {
-    // When dropping something native, we need to extract the latest
-    // `.items` from the "drop" event as it is now accessible
-    if (args.type === 'success' && dragType.type === 'external') {
-      dispatch.drop({
-        current: current,
-        updatedSourcePayload: dragType.getDropPayload(args.event)
-      });
-      return;
-    }
-    dispatch.drop({
-      current: current,
-      updatedSourcePayload: null
-    });
-  }
-  function cancel() {
+  function cancel(drop) {
     // The spec behaviour is that when a drag is cancelled, or when dropping on no drop targets,
     // a "dragleave" event is fired on the active drop target before a "dragend" event.
     // We are replicating that behaviour in `cancel` if there are any active drop targets to
@@ -126,19 +116,21 @@ function start(_ref2) {
     // Note: When cancelling, or dropping on no drop targets, a "dragleave" event
     // will have already cleared the dropTargets to `[]` (as that particular "dragleave" has a `relatedTarget` of `null`)
 
-    if (current.dropTargets.length) {
+    if (state.current.dropTargets.length) {
       updateDropTargets({
         dropTargets: [],
-        input: current.input
+        input: state.current.input
       });
     }
-    onDrop({
-      type: 'cancel'
+    dispatch.drop({
+      current: state.current,
+      drop: drop,
+      updatedSourcePayload: null
     });
     finish();
   }
   function finish() {
-    isActive = false;
+    globalState.isActive = false;
     unbindEvents();
   }
   var unbindEvents = (0, _bindEventListener.bindAll)(window, [{
@@ -163,20 +155,13 @@ function start(_ref2) {
       // 2. let consumers know a move has occurred
       // This will include the latest 'input' values
       dispatch.drag({
-        current: current
+        current: state.current
       });
     }
   }, {
     type: 'dragenter',
     listener: onUpdateEvent
   }, {
-    // This was the only reliable cross browser way I found to detect
-    // when the user is leaving the `window`.
-    // Internal drags: when we leave the `window` we want to clear any active drop targets,
-    // but the drag is not yet over. The user could drag back into the window.
-    // We only need to do this because of stickiness
-    // External drags: when we leave the `window` the drag operation is over,
-    // we will start another drag operation
     type: 'dragleave',
     listener: function listener(event) {
       if (!(0, _isLeavingWindow.isLeavingWindow)({
@@ -185,45 +170,82 @@ function start(_ref2) {
         return;
       }
 
-      // When a drag is ending without a drop target (or when the drag is cancelled),
-      // All browsers fire:
-      // 1. "drag"
-      // 2. "dragleave"
-      // These events have `event.relatedTarget == null` so this code path is also hit in those cases.
-      // This is all good! We would be clearing the dropTargets in `cancel()` after the "dragend"
+      /**
+       * At this point we don't know if a drag is being cancelled,
+       * or if a drag is leaving the `window`.
+       *
+       * Both have:
+       *   1. "dragleave" (with `relatedTarget: null`)
+       *   2. "dragend" (a "dragend" can occur when outside the `window`)
+       *
+       * **Clearing drop targets**
+       *
+       * For either case we are clearing the the drop targets
+       *
+       * - cancelling: we clear drop targets in `"dragend"` anyway
+       * - leaving the `window`: we clear the drop targets (to clear stickiness)
+       *
+       * **Leaving the window and finishing the drag**
+       *
+       * _internal drags_
+       *
+       * - The drag continues when the user is outside the `window`
+       *   and can resume if the user drags back over the `window`,
+       *   or end when the user drops in an external `window`.
+       * - We will get a `"dragend"`, or we can listen for other
+       *   events to determine the drag is finished when the user re-enters the `window`).
+       *
+       * _external drags_
+       *
+       * - We conclude the drag operation.
+       * - We have no idea if the user will drag back over the `window`,
+       *   or if the drag ends elsewhere.
+       * - We will create a new drag if the user re-enters the `window`.
+       *
+       * **Not updating `input`**
+       *
+       * 🐛 Bug[Chrome] the final `"dragleave"` has default input values (eg `clientX == 0`)
+       * Workaround: intentionally not updating `input` in "dragleave"
+       * rather than the users current input values
+       * - [Conversation](https://twitter.com/alexandereardon/status/1642697633864241152)
+       * - [Bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1429937)
+       **/
 
-      // 🐛 Bug workaround: intentionally not updating `input` in "dragleave"
-      // In Chrome, this final "dragleave" has default input values (eg clientX == 0)
-      // rather than the users current input values
-      //
-      // - [Conversation](https://twitter.com/alexandereardon/status/1642697633864241152)
-      // - [Bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1429937)
       updateDropTargets({
-        input: current.input,
+        input: state.current.input,
         dropTargets: []
       });
-
-      // End the drag operation if a native drag is leaving the window
       if (dragType.startedFrom === 'external') {
-        cancel();
+        cancel({
+          dropEffect: 'none'
+        });
       }
     }
   }, {
     type: 'drop',
     listener: function listener(event) {
+      var _event$dataTransfer$d, _event$dataTransfer;
       // A "drop" can only happen if the browser allowed the drop
 
-      // Opting out of standard browser drop behaviour for the drag
+      // Accepting drop operation.
+      // Also: opting out of standard browser drop behaviour for the drag
       event.preventDefault();
 
       // applying the latest drop effect to the event
-      setDropEffect({
+      setDropEffectOnEvent({
         event: event,
-        current: current.dropTargets
+        current: state.current.dropTargets
       });
-      onDrop({
-        type: 'success',
-        event: event
+      dispatch.drop({
+        current: state.current,
+        drop: {
+          // At this point the dropEffect has been set on the event
+          // (if we have set it), so we can read it from there
+          dropEffect: (_event$dataTransfer$d = (_event$dataTransfer = event.dataTransfer) === null || _event$dataTransfer === void 0 ? void 0 : _event$dataTransfer.dropEffect) !== null && _event$dataTransfer$d !== void 0 ? _event$dataTransfer$d : 'none'
+        },
+        // When dropping something native, we need to extract the latest
+        // `.items` from the "drop" event as it is now accessible
+        updatedSourcePayload: dragType.type === 'external' ? dragType.getDropPayload(event) : null
       });
       finish();
 
@@ -231,30 +253,46 @@ function start(_ref2) {
       // to update UI in response to a "onDrop".
       if (dragType.startedFrom === 'internal') {
         (0, _fixPostDragPointerBug.fixPostDragPointerBug)({
-          current: current
+          current: state.current
         });
       }
     }
   }, {
     // "dragend" fires when on the drag source (eg a draggable element)
     // when the drag is finished.
-    // "dragend" will fire after "drop"(if there was a successful drop)
+    // "dragend" will fire after "drop" (if there was a successful drop)
     // "dragend" does not fire if the draggable source has been removed during the drag
     // or for external drag sources (eg files)
+
+    // This "dragend" listener will not fire if there was a successful drop
+    // as we will have already removed the event listener
     type: 'dragend',
-    listener: function listener() {
-      cancel();
+    listener: function listener(event) {
+      var _event$dataTransfer$d2, _event$dataTransfer2;
+      // The `dropEffect` will be:
+      // - "none" if dropped on no drop targets
+      // - "none" if cancelled locally
+      // - "none" if cancelled externally
+      // - "none" if `preventUnhandled` is used (and there is no drop target)
+      // - [not "none"] if accepted externally
+      cancel({
+        dropEffect: (_event$dataTransfer$d2 = (_event$dataTransfer2 = event.dataTransfer) === null || _event$dataTransfer2 === void 0 ? void 0 : _event$dataTransfer2.dropEffect) !== null && _event$dataTransfer$d2 !== void 0 ? _event$dataTransfer$d2 : 'none'
+      });
 
       // Applying this fix after `dispatch.drop` so that frameworks have the opportunity
       // to update UI in response to a "onDrop".
       if (dragType.startedFrom === 'internal') {
         (0, _fixPostDragPointerBug.fixPostDragPointerBug)({
-          current: current
+          current: state.current
         });
       }
     }
   }].concat((0, _toConsumableArray2.default)((0, _detectBrokenDrag.getBindingsForBrokenDrags)({
-    onDragEnd: cancel
+    onDragEnd: function onDragEnd() {
+      return cancel({
+        dropEffect: 'none'
+      });
+    }
   }))),
   // Once we have started a managed drag operation it is important that we see / own all drag events
   // We got one adoption bug pop up where some code was stopping (`event.stopPropagation()`)
@@ -267,7 +305,7 @@ function start(_ref2) {
     nativeSetDragImage: getNativeSetDragImage(event)
   });
 }
-function setDropEffect(_ref3) {
+function setDropEffectOnEvent(_ref3) {
   var _current$;
   var event = _ref3.event,
     current = _ref3.current;

package/dist/cjs/public-utils/prevent-unhandled.js

@@ -1,20 +1,22 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.preventUnhandled = void 0;
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
 var _bindEventListener = require("bind-event-listener");
-function cancel(event) {
-  // if `@atlaskit/pragmatic-drag-and-drop` has already prevented the event
-  // we don't need to do anything
+var _detectBrokenDrag = require("../util/detect-broken-drag");
+function acceptDrop(event) {
+  // if the event is already prevented the event we don't need to do anything
   if (event.defaultPrevented) {
     return;
   }
   // Using "move" as the drop effect as that uses the standard
   // cursor. Doing this so the user doesn't think they are dropping
   // on the page
-  // Note: using "none" will not allow a drop to occur, so we are using "move"
+  // Note: using "none" will not allow a "drop" to occur, so we are using "move"
   if (event.dataTransfer) {
     event.dataTransfer.dropEffect = 'move';
   }
@@ -26,24 +28,55 @@ var unbindEvents = null;
 /**
  * Block drag operations outside of `@atlaskit/pragmatic-drag-and-drop`
  */
+function start() {
+  cleanup();
+  unbindEvents = (0, _bindEventListener.bindAll)(window, [{
+    type: 'dragover',
+    listener: acceptDrop
+  }, {
+    type: 'dragenter',
+    listener: acceptDrop
+  }, {
+    type: 'drop',
+    listener: function listener(event) {
+      // our lifecycle manager already prevents events, but just being super safe
+      event.preventDefault();
+
+      // not setting dropEffect, as `drop.dropEffect` has already been published to the user
+      // (lifecycle-manager binds events in the capture phase)
+
+      // we don't need to wait for "dragend", and "dragend" might not even happen,
+      // such as when the draggable has been removed during a drag.
+      cleanup();
+    }
+  }, {
+    type: 'dragend',
+    listener: cleanup
+  }].concat((0, _toConsumableArray2.default)((0, _detectBrokenDrag.getBindingsForBrokenDrags)({
+    onDragEnd: cleanup
+  }))),
+  // being clear that these are added in the bubble phase
+  {
+    capture: false
+  });
+}
+function cleanup() {
+  var _unbindEvents;
+  (_unbindEvents = unbindEvents) === null || _unbindEvents === void 0 || _unbindEvents();
+  unbindEvents = null;
+}
+
+/**
+ * TODO: for next major, we could look at do the following:
+ *
+ * ```diff
+ * - preventUnhandled.start();
+ * - preventUnhandled.stop();
+ * + const stop = preventUnhandled();
+ * ```
+ */
+
 var preventUnhandled = exports.preventUnhandled = {
-  start: function start() {
-    var _unbindEvents;
-    (_unbindEvents = unbindEvents) === null || _unbindEvents === void 0 || _unbindEvents();
-    unbindEvents = (0, _bindEventListener.bindAll)(window, [{
-      type: 'dragover',
-      listener: cancel
-    }, {
-      type: 'dragenter',
-      listener: cancel
-    }, {
-      type: 'drop',
-      listener: cancel
-    }]);
-  },
-  stop: function stop() {
-    var _unbindEvents2;
-    (_unbindEvents2 = unbindEvents) === null || _unbindEvents2 === void 0 || _unbindEvents2();
-    unbindEvents = null;
-  }
+  start: start,
+  stop: cleanup
 };

package/dist/es2019/ledger/dispatch-consumer-event.js

@@ -107,6 +107,7 @@ export function makeDispatch({
     },
     drop({
       current,
+      drop,
       updatedSourcePayload
     }) {
       dragStart.flush();
@@ -114,6 +115,7 @@ export function makeDispatch({
       safeDispatch({
         eventName: 'onDrop',
         payload: {
+          drop,
           source: updatedSourcePayload !== null && updatedSourcePayload !== void 0 ? updatedSourcePayload : source,
           location: {
             current,