@atlaskit/pragmatic-drag-and-drop 1.7.2 → 1.7.4

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @atlaskit/pragmatic-drag-and-drop
 
+## 1.7.4
+
+### Patch Changes
+
+- [#174472](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/pull-requests/174472)
+  [`fda983a832f81`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/fda983a832f81) -
+  On Android `pointerOutsideOfPreview` will now also center the drag preview under the users
+  pointer. Technically this was already existing observed behaviour as Android always centers the
+  drag preview under the users pointer. We now make this behaviour explicit in the code, and call
+  this out behaviour in jsdoc and documentation.
+
+## 1.7.3
+
+### Patch Changes
+
+- [#173859](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/pull-requests/173859)
+  [`d6f17206f8859`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/d6f17206f8859) -
+  In order to provide the best experience for iOS, the optional function `pointerOutsideOfPreview`
+  will now center the drag preview under the users pointer on iOS.
+
+  Some more detail (in case you are interested):
+
+  **Borders**
+
+  _(Existing behaviour)_
+
+  In `pointerOutsideOfPreview` we use transparent borders to push the preview away from the users
+  pointer. On iOS these borders will always be black. So we don't use transparent border on iOS.
+
+  **Placement**
+
+  _(Improvement)_
+
+  During a drag on iOS the drag preview will shift under the center of the users pointer, even if we
+  start the drag with the users pointer on the top left or top right corner of the drag preview. So
+  now `pointerOutsideOfPreview` will always put the preview under the center of the users pointer in
+  order to avoid the drag preview position shifting as the drag is starting.
+
 ## 1.7.2
 
 ### Patch Changes

package/dist/cjs/public-utils/element/custom-native-drag-preview/pointer-outside-of-preview.js

@@ -4,7 +4,9 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.pointerOutsideOfPreview = pointerOutsideOfPreview;
+var _android = require("../../../util/android");
 var _isSafariOnIos = require("../../../util/is-safari-on-ios");
+var _centerUnderPointer = require("./center-under-pointer");
 /** Any valid CSS string value
  * @example `calc(var(--grid) * 2)
  */
@@ -26,15 +28,13 @@ var _isSafariOnIos = require("../../../util/is-safari-on-ios");
  * The direction will be calculated based on the direction (`dir`) being applied to the `container`
  * element (which will be a child of the `body` element).
  *
- * **iOS**
+ * **iOS, iPadOS and Android**
  *
- * This function will not push the preview away from the users pointer on iOS due to platform limitations.
- * On iOS the preview will start the drag on the top left corner (or top right corner for right to left interfaces).
- * While dragging, iOS will shift the drag preview under the center of the users pointer, so the "pushing away"
- * is short lived on iOS.
+ * The drag preview will be centered under the users pointer rather than
+ * pushed away on iOS due to platform limitations.
  */
 function pointerOutsideOfPreview(point) {
-  return function (_ref) {
+  return function getOffset(_ref) {
     var container = _ref.container;
     /**
      * **Approach: transparent borders.**
@@ -42,27 +42,55 @@ function pointerOutsideOfPreview(point) {
      * The only reliable cross browser technique found to push a
      * drag preview away from the cursor is to use transparent borders on the container.
      *
-     * **🙅📱 Not pushing the preview away on iOS**
+     * **🙅📱 Not pushing the preview away on touch devices**
      *
-     * On iOS, the browser will set the transparent border color to be black. We can provide a
-     * more polished experience not using the transparent border on iOS.
+     * _On iOS_
      *
-     * While dragging, iOS will shift the drag preview under the center of the users pointer,
-     * so the "pushing away" of the preview is short lived on iOS anyway.
+     * Safari will set the transparent border color to be black
      *
-     * Notes:
-     *
-     * - Tested on `iOS@18.4.1` on May 7th 2025
+     * `iOS@18.4.1` on May 7th 2025:
      * - If you set the background color on the `container` the border color will be that
-     * - Setting a transparent background color on the `container` still results in a black border
+     * - Setting a transparent background color on the `container` still results in a
+     *   black border
      * - The `<body>` text or background color does not change the black border color
+     *
+     * While dragging, the drag preview will shift under the center of the users pointer.
+     * So if you start at {x: 0, y: 0} (top left), almost immediately the preview will move
+     * to be under the middle of the users pointer.
+     *
+     * _On Android_
+     *
+     * Chrome will put the center of the drag preview under the users pointer immediately.
+     *
+     * Tested on `Chrome@137` on `Android 14` on June 20th 2025
+     *
+     * _What we do_
+     *
+     * We don't add the transparent border
+     *
+     * - Avoid the black color on iOS
+     * - It isn't needed on Android anyway as the preview will be under the center
+     *   of the users pointer
+     *
+     * We put the center of the drag preview under the users pointer
+     *
+     * - Avoids the drag preview quickly moving from a top corner to be centered under
+     *   the users pointer on iOS
+     * - It will be under the center on Android no matter what we do
+     *
+     * We previously had a isTouchDevice() check, but it felt safer for now
+     * to have a more targeted check, as these are the devices that have been
+     * tested on.
      */
-    if (!(0, _isSafariOnIos.isSafariOnIOS)()) {
-      Object.assign(container.style, {
-        borderInlineStart: "".concat(point.x, " solid transparent"),
-        borderTop: "".concat(point.y, " solid transparent")
+    if ((0, _isSafariOnIos.isSafariOnIOS)() || (0, _android.isAndroid)()) {
+      return (0, _centerUnderPointer.centerUnderPointer)({
+        container: container
       });
     }
+    Object.assign(container.style, {
+      borderInlineStart: "".concat(point.x, " solid transparent"),
+      borderTop: "".concat(point.y, " solid transparent")
+    });
 
     // Unfortunate that we need to use `getComputedStyle`,
     // but it's only a single call when the drag is starting.

package/dist/cjs/public-utils/element/custom-native-drag-preview/preserve-offset-on-source.js

@@ -7,8 +7,25 @@ exports.preserveOffsetOnSource = preserveOffsetOnSource;
 function preserveOffsetOnSource(_ref) {
   var element = _ref.element,
     input = _ref.input;
-  return function (_ref2) {
+  return function getOffset(_ref2) {
     var container = _ref2.container;
+    /**
+     * **Android**
+     *
+     * This function won't do anything 😅.
+     * The drag preview will _always_ be under the center of the users pointer.
+     * There is no harm in calling this function though 🧘.
+     *
+     * **iOS and iPadOS**
+     *
+     * The drag preview is lifted in the expected position and then slides under
+     * the users pointer.
+     * This is more pleasing than immediately putting the center of the drag preview
+     * under the users pointer.
+     * With this function the drag preview looks like it is popping out
+     * of the UI and then it shifts under the users pointer as the drag is occurring ✨
+     */
+
     var sourceRect = element.getBoundingClientRect();
     var containerRect = container.getBoundingClientRect();
     var offsetX = Math.min(

package/dist/cjs/util/android.js

@@ -5,7 +5,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.isAndroid = exports.androidFallbackText = void 0;
 var _once = require("../public-utils/once");
-// using `cache` as our `isAndroid()` result will not change in a browser
+// Using `once` as the value won't change in a browser
+
 var isAndroid = exports.isAndroid = (0, _once.once)(function isAndroid() {
   return navigator.userAgent.toLocaleLowerCase().includes('android');
 });

package/dist/cjs/util/is-safari-on-ios.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.isSafariOnIOS = void 0;
 var _once = require("../public-utils/once");
 var _isSafari = require("./is-safari");
-// Using `cache` as our `isIOS()` result will not change in a browser
+// Using `once` as the value won't change in a browser
 
 /**
  * **Notes**

package/dist/es2019/public-utils/element/custom-native-drag-preview/pointer-outside-of-preview.js

@@ -1,4 +1,6 @@
+import { isAndroid } from '../../../util/android';
 import { isSafariOnIOS } from '../../../util/is-safari-on-ios';
+import { centerUnderPointer } from './center-under-pointer';
 
 /** Any valid CSS string value
  * @example `calc(var(--grid) * 2)
@@ -21,44 +23,70 @@ import { isSafariOnIOS } from '../../../util/is-safari-on-ios';
  * The direction will be calculated based on the direction (`dir`) being applied to the `container`
  * element (which will be a child of the `body` element).
  *
- * **iOS**
+ * **iOS, iPadOS and Android**
  *
- * This function will not push the preview away from the users pointer on iOS due to platform limitations.
- * On iOS the preview will start the drag on the top left corner (or top right corner for right to left interfaces).
- * While dragging, iOS will shift the drag preview under the center of the users pointer, so the "pushing away"
- * is short lived on iOS.
+ * The drag preview will be centered under the users pointer rather than
+ * pushed away on iOS due to platform limitations.
  */
 export function pointerOutsideOfPreview(point) {
-  return ({
+  return function getOffset({
     container
-  }) => {
+  }) {
     /**
      * **Approach: transparent borders.**
      *
      * The only reliable cross browser technique found to push a
      * drag preview away from the cursor is to use transparent borders on the container.
      *
-     * **🙅📱 Not pushing the preview away on iOS**
+     * **🙅📱 Not pushing the preview away on touch devices**
      *
-     * On iOS, the browser will set the transparent border color to be black. We can provide a
-     * more polished experience not using the transparent border on iOS.
+     * _On iOS_
      *
-     * While dragging, iOS will shift the drag preview under the center of the users pointer,
-     * so the "pushing away" of the preview is short lived on iOS anyway.
+     * Safari will set the transparent border color to be black
      *
-     * Notes:
-     *
-     * - Tested on `iOS@18.4.1` on May 7th 2025
+     * `iOS@18.4.1` on May 7th 2025:
      * - If you set the background color on the `container` the border color will be that
-     * - Setting a transparent background color on the `container` still results in a black border
+     * - Setting a transparent background color on the `container` still results in a
+     *   black border
      * - The `<body>` text or background color does not change the black border color
+     *
+     * While dragging, the drag preview will shift under the center of the users pointer.
+     * So if you start at {x: 0, y: 0} (top left), almost immediately the preview will move
+     * to be under the middle of the users pointer.
+     *
+     * _On Android_
+     *
+     * Chrome will put the center of the drag preview under the users pointer immediately.
+     *
+     * Tested on `Chrome@137` on `Android 14` on June 20th 2025
+     *
+     * _What we do_
+     *
+     * We don't add the transparent border
+     *
+     * - Avoid the black color on iOS
+     * - It isn't needed on Android anyway as the preview will be under the center
+     *   of the users pointer
+     *
+     * We put the center of the drag preview under the users pointer
+     *
+     * - Avoids the drag preview quickly moving from a top corner to be centered under
+     *   the users pointer on iOS
+     * - It will be under the center on Android no matter what we do
+     *
+     * We previously had a isTouchDevice() check, but it felt safer for now
+     * to have a more targeted check, as these are the devices that have been
+     * tested on.
      */
-    if (!isSafariOnIOS()) {
-      Object.assign(container.style, {
-        borderInlineStart: `${point.x} solid transparent`,
-        borderTop: `${point.y} solid transparent`
+    if (isSafariOnIOS() || isAndroid()) {
+      return centerUnderPointer({
+        container
       });
     }
+    Object.assign(container.style, {
+      borderInlineStart: `${point.x} solid transparent`,
+      borderTop: `${point.y} solid transparent`
+    });
 
     // Unfortunate that we need to use `getComputedStyle`,
     // but it's only a single call when the drag is starting.

package/dist/es2019/public-utils/element/custom-native-drag-preview/preserve-offset-on-source.js

@@ -2,9 +2,26 @@ export function preserveOffsetOnSource({
   element,
   input
 }) {
-  return ({
+  return function getOffset({
     container
-  }) => {
+  }) {
+    /**
+     * **Android**
+     *
+     * This function won't do anything 😅.
+     * The drag preview will _always_ be under the center of the users pointer.
+     * There is no harm in calling this function though 🧘.
+     *
+     * **iOS and iPadOS**
+     *
+     * The drag preview is lifted in the expected position and then slides under
+     * the users pointer.
+     * This is more pleasing than immediately putting the center of the drag preview
+     * under the users pointer.
+     * With this function the drag preview looks like it is popping out
+     * of the UI and then it shifts under the users pointer as the drag is occurring ✨
+     */
+
     const sourceRect = element.getBoundingClientRect();
     const containerRect = container.getBoundingClientRect();
     const offsetX = Math.min(

package/dist/es2019/util/android.js

@@ -1,6 +1,7 @@
 import { once } from '../public-utils/once';
 
-// using `cache` as our `isAndroid()` result will not change in a browser
+// Using `once` as the value won't change in a browser
+
 export const isAndroid = once(function isAndroid() {
   return navigator.userAgent.toLocaleLowerCase().includes('android');
 });

package/dist/es2019/util/is-safari-on-ios.js

@@ -1,7 +1,7 @@
 import { once } from '../public-utils/once';
 import { isSafari } from './is-safari';
 
-// Using `cache` as our `isIOS()` result will not change in a browser
+// Using `once` as the value won't change in a browser
 
 /**
  * **Notes**

package/dist/esm/public-utils/element/custom-native-drag-preview/pointer-outside-of-preview.js

@@ -1,4 +1,6 @@
+import { isAndroid } from '../../../util/android';
 import { isSafariOnIOS } from '../../../util/is-safari-on-ios';
+import { centerUnderPointer } from './center-under-pointer';
 
 /** Any valid CSS string value
  * @example `calc(var(--grid) * 2)
@@ -21,15 +23,13 @@ import { isSafariOnIOS } from '../../../util/is-safari-on-ios';
  * The direction will be calculated based on the direction (`dir`) being applied to the `container`
  * element (which will be a child of the `body` element).
  *
- * **iOS**
+ * **iOS, iPadOS and Android**
  *
- * This function will not push the preview away from the users pointer on iOS due to platform limitations.
- * On iOS the preview will start the drag on the top left corner (or top right corner for right to left interfaces).
- * While dragging, iOS will shift the drag preview under the center of the users pointer, so the "pushing away"
- * is short lived on iOS.
+ * The drag preview will be centered under the users pointer rather than
+ * pushed away on iOS due to platform limitations.
  */
 export function pointerOutsideOfPreview(point) {
-  return function (_ref) {
+  return function getOffset(_ref) {
     var container = _ref.container;
     /**
      * **Approach: transparent borders.**
@@ -37,27 +37,55 @@ export function pointerOutsideOfPreview(point) {
      * The only reliable cross browser technique found to push a
      * drag preview away from the cursor is to use transparent borders on the container.
      *
-     * **🙅📱 Not pushing the preview away on iOS**
+     * **🙅📱 Not pushing the preview away on touch devices**
      *
-     * On iOS, the browser will set the transparent border color to be black. We can provide a
-     * more polished experience not using the transparent border on iOS.
+     * _On iOS_
      *
-     * While dragging, iOS will shift the drag preview under the center of the users pointer,
-     * so the "pushing away" of the preview is short lived on iOS anyway.
+     * Safari will set the transparent border color to be black
      *
-     * Notes:
-     *
-     * - Tested on `iOS@18.4.1` on May 7th 2025
+     * `iOS@18.4.1` on May 7th 2025:
      * - If you set the background color on the `container` the border color will be that
-     * - Setting a transparent background color on the `container` still results in a black border
+     * - Setting a transparent background color on the `container` still results in a
+     *   black border
      * - The `<body>` text or background color does not change the black border color
+     *
+     * While dragging, the drag preview will shift under the center of the users pointer.
+     * So if you start at {x: 0, y: 0} (top left), almost immediately the preview will move
+     * to be under the middle of the users pointer.
+     *
+     * _On Android_
+     *
+     * Chrome will put the center of the drag preview under the users pointer immediately.
+     *
+     * Tested on `Chrome@137` on `Android 14` on June 20th 2025
+     *
+     * _What we do_
+     *
+     * We don't add the transparent border
+     *
+     * - Avoid the black color on iOS
+     * - It isn't needed on Android anyway as the preview will be under the center
+     *   of the users pointer
+     *
+     * We put the center of the drag preview under the users pointer
+     *
+     * - Avoids the drag preview quickly moving from a top corner to be centered under
+     *   the users pointer on iOS
+     * - It will be under the center on Android no matter what we do
+     *
+     * We previously had a isTouchDevice() check, but it felt safer for now
+     * to have a more targeted check, as these are the devices that have been
+     * tested on.
      */
-    if (!isSafariOnIOS()) {
-      Object.assign(container.style, {
-        borderInlineStart: "".concat(point.x, " solid transparent"),
-        borderTop: "".concat(point.y, " solid transparent")
+    if (isSafariOnIOS() || isAndroid()) {
+      return centerUnderPointer({
+        container: container
       });
     }
+    Object.assign(container.style, {
+      borderInlineStart: "".concat(point.x, " solid transparent"),
+      borderTop: "".concat(point.y, " solid transparent")
+    });
 
     // Unfortunate that we need to use `getComputedStyle`,
     // but it's only a single call when the drag is starting.

package/dist/esm/public-utils/element/custom-native-drag-preview/preserve-offset-on-source.js

@@ -1,8 +1,25 @@
 export function preserveOffsetOnSource(_ref) {
   var element = _ref.element,
     input = _ref.input;
-  return function (_ref2) {
+  return function getOffset(_ref2) {
     var container = _ref2.container;
+    /**
+     * **Android**
+     *
+     * This function won't do anything 😅.
+     * The drag preview will _always_ be under the center of the users pointer.
+     * There is no harm in calling this function though 🧘.
+     *
+     * **iOS and iPadOS**
+     *
+     * The drag preview is lifted in the expected position and then slides under
+     * the users pointer.
+     * This is more pleasing than immediately putting the center of the drag preview
+     * under the users pointer.
+     * With this function the drag preview looks like it is popping out
+     * of the UI and then it shifts under the users pointer as the drag is occurring ✨
+     */
+
     var sourceRect = element.getBoundingClientRect();
     var containerRect = container.getBoundingClientRect();
     var offsetX = Math.min(

package/dist/esm/util/android.js

@@ -1,6 +1,7 @@
 import { once } from '../public-utils/once';
 
-// using `cache` as our `isAndroid()` result will not change in a browser
+// Using `once` as the value won't change in a browser
+
 export var isAndroid = once(function isAndroid() {
   return navigator.userAgent.toLocaleLowerCase().includes('android');
 });

package/dist/esm/util/is-safari-on-ios.js

@@ -1,7 +1,7 @@
 import { once } from '../public-utils/once';
 import { isSafari } from './is-safari';
 
-// Using `cache` as our `isIOS()` result will not change in a browser
+// Using `once` as the value won't change in a browser
 
 /**
  * **Notes**

package/dist/types/public-utils/element/custom-native-drag-preview/pointer-outside-of-preview.d.ts

@@ -20,12 +20,10 @@ type CSSValue = string;
  * The direction will be calculated based on the direction (`dir`) being applied to the `container`
  * element (which will be a child of the `body` element).
  *
- * **iOS**
+ * **iOS, iPadOS and Android**
  *
- * This function will not push the preview away from the users pointer on iOS due to platform limitations.
- * On iOS the preview will start the drag on the top left corner (or top right corner for right to left interfaces).
- * While dragging, iOS will shift the drag preview under the center of the users pointer, so the "pushing away"
- * is short lived on iOS.
+ * The drag preview will be centered under the users pointer rather than
+ * pushed away on iOS due to platform limitations.
  */
 export declare function pointerOutsideOfPreview(point: {
     x: CSSValue;

package/dist/types-ts4.5/public-utils/element/custom-native-drag-preview/pointer-outside-of-preview.d.ts

@@ -20,12 +20,10 @@ type CSSValue = string;
  * The direction will be calculated based on the direction (`dir`) being applied to the `container`
  * element (which will be a child of the `body` element).
  *
- * **iOS**
+ * **iOS, iPadOS and Android**
  *
- * This function will not push the preview away from the users pointer on iOS due to platform limitations.
- * On iOS the preview will start the drag on the top left corner (or top right corner for right to left interfaces).
- * While dragging, iOS will shift the drag preview under the center of the users pointer, so the "pushing away"
- * is short lived on iOS.
+ * The drag preview will be centered under the users pointer rather than
+ * pushed away on iOS due to platform limitations.
  */
 export declare function pointerOutsideOfPreview(point: {
     x: CSSValue;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/pragmatic-drag-and-drop",
-	"version": "1.7.2",
+	"version": "1.7.4",
 	"description": "The core package for Pragmatic drag and drop - enabling fast drag and drop for any experience on any tech stack",
 	"repository": "https://github.com/atlassian/pragmatic-drag-and-drop",
 	"author": "Atlassian Pty Ltd",