@atlaskit/pragmatic-drag-and-drop 0.17.0

package/CHANGELOG.md

@@ -0,0 +1,209 @@
+# @atlaskit/pragmatic-drag-and-drop
+
+## 0.17.0
+
+### Minor Changes
+
+- [`34ed7b2ec63`](https://bitbucket.org/atlassian/atlassian-frontend/commits/34ed7b2ec63) - We have changed the name of our drag and drop packages to align on the single name of "Pragmatic drag and drop"
+
+  ```diff
+  - @atlaskit/drag-and-drop
+  + @atlaskit/pragmatic-drag-and-drop
+
+  - @atlaskit/drag-and-drop-autoscroll
+  + @atlaskit/pragmatic-drag-and-drop-autoscroll
+
+  - @atlaskit/drag-and-drop-hitbox
+  + @atlaskit/pragmatic-drag-and-drop-hitbox
+
+  - @atlaskit/drag-and-drop-indicator
+  + @atlaskit/pragmatic-drag-and-drop-react-indicator
+  # Note: `react` was added to this package name as our indicator package is designed for usage with `react`.
+
+  - @atlaskit/drag-and-drop-live-region
+  + @atlaskit/pragmatic-drag-and-drop-live-region
+
+  - @atlaskit/drag-and-drop-react-beautiful-dnd-migration
+  + @atlaskit/pragmatic-drag-and-drop-react-beautiful-dnd-migration
+
+  - @atlaskit/drag-and-drop-docs
+  + @atlaskit/pragmatic-drag-and-drop-docs
+  ```
+
+  The new `@atlaskit/pragmatic-drag-and-drop*` packages will start their initial versions from where the ``@atlaskit/drag-and-drop*` packages left off. Doing this will make it easier to look back on changelogs and see how the packages have progressed.
+
+## 0.16.0
+
+### Minor Changes
+
+- [`56507598609`](https://bitbucket.org/atlassian/atlassian-frontend/commits/56507598609) - Skip minor dependency bump
+
+## 0.15.1
+
+### Patch Changes
+
+- [`2e01c9c74b5`](https://bitbucket.org/atlassian/atlassian-frontend/commits/2e01c9c74b5) - DUMMY remove before merging to master; dupe adf-schema via adf-utils
+
+## 0.15.0
+
+### Minor Changes
+
+- [`ed028658f13`](https://bitbucket.org/atlassian/atlassian-frontend/commits/ed028658f13) - Minor internal refactor and adding additional tests
+
+## 0.14.0
+
+### Minor Changes
+
+- [`eab6d26451d`](https://bitbucket.org/atlassian/atlassian-frontend/commits/eab6d26451d) - Improving the resilience of our workaround for a [Browser bug](https://bugs.chromium.org/p/chromium/issues/detail?id=410328) where after a drag finishes, an unrelated element can be entered into.
+- [`ba7ea570aee`](https://bitbucket.org/atlassian/atlassian-frontend/commits/ba7ea570aee) - > Both of these changes should not impact most consumers as they are targeted at edge cases.
+
+  - **Fix**: We no longer extract user input (eg `clientX`) from native `"dragleave"` events due to a [Bug with Chrome we discovered](https://bugs.chromium.org/p/chromium/issues/detail?id=1429937). Due to this bug, it was possible for `location.current.input` to be incorrectly set in `onDropTargetChange` and `onDrop` when a user was cancelling a drag or dropping or no drop targets.
+
+  - **Fix**: `location.previous.dropTargets` _should_ always point to the `location.current.dropTargets` value from the previous event (exception: `onGenerateDragPreview` and `onDragStart` have the same `location.previous` and `location.current` values). Previously, the `location.previous.dropTargets` value did not match the last events `location.current.dropTargets` value in `onDrop`. `onDrop()` would incorrectly use the `location.current` and `location.previous` values from the last event rather than creating a new `location.current` entry. Now, `onDrop()`, `location.previous.dropTargets` points to the `location.current.dropTargets` from the last event (same as all other events) and `location.current.dropTargets` points to what the previous drop target was as well (no change)
+
+## 0.13.0
+
+### Minor Changes
+
+- [`2582df26509`](https://bitbucket.org/atlassian/atlassian-frontend/commits/2582df26509) - Fixing a browser bug where after a drag finishes, a unrelated element can be entered into by the browser
+
+  - [Visual explanation of bug](https://twitter.com/alexandereardon/status/1633614212873465856)
+  - [Chrome bug](https://bugs.chromium.org/p/chromium/issues/detail?id=410328)
+
+## 0.12.0
+
+### Minor Changes
+
+- [`90901f5bbe0`](https://bitbucket.org/atlassian/atlassian-frontend/commits/90901f5bbe0) - Replace default entry point of `undefined` with `{}`.
+
+  > **NOTE:** Importing from the default entry point isn't supported.
+  > _Please use individual entry points in order to always obtain minimum kbs._
+
+## 0.11.0
+
+### Minor Changes
+
+- [`1ecbb19d450`](https://bitbucket.org/atlassian/atlassian-frontend/commits/1ecbb19d450) - Adding a new function to make creating _custom_ native drag previews safe and easy: `setCustomNativeDragPreview`
+
+  ```tsx
+  import { setCustomNativeDragPreview } from '@atlaskit/drag-and-drop/util/set-custom-native-drag-preview';
+
+  draggable({
+    element: myElement,
+    onGenerateDragPreview: ({ nativeSetDragImage }) => {
+      setCustomNativeDragPreview({
+        render: function render({ container }) {
+          ReactDOM.render(<Preview item={item} />, container);
+          return function cleanup() {
+            ReactDOM.unmountComponentAtNode(container);
+          };
+        },
+        nativeSetDragImage,
+      });
+    },
+  });
+  ```
+
+  Please see our element adapter documentation for more detailed usage information
+
+## 0.10.0
+
+### Minor Changes
+
+- [`9c0975e2fab`](https://bitbucket.org/atlassian/atlassian-frontend/commits/9c0975e2fab) - Bug fix: A _monitor_ should not be called after it is removed. Previously, if a _monitor_ (monitor 1) removed another _monitor_ (monitor 2) for the same event, then the second monitor (monitor 2) would still be called. This has been fixed
+
+  ```ts
+  const cleanupMonitor1 = monitorForElements({
+    onDragStart: () => {
+      cleanupMonitor2();
+    },
+  });
+  const cleanupMonitor2 = monitorForElements({
+    // Previously this `onDragStart` would have been called during `onDragStart` even though it was unbound by the first monitor
+    onDragStart: () => {},
+  });
+  ```
+
+## 0.9.0
+
+### Minor Changes
+
+- [`03e0aa5ae85`](https://bitbucket.org/atlassian/atlassian-frontend/commits/03e0aa5ae85) - `@atlaskit/drag-and-drop` adds event listeners to the `window` during a drag operation. These drag operation event listeners were [`bubble` phase event listeners](https://domevents.dev/), but they are now `capture` phase event listeners to be more resliant against external code (incorrectly) stopping events.
+
+  This does not impact the ability of a consumer to have their own `draggable`s on a page not controlled by `@atlaskit/drag-and-drop`
+
+## 0.8.1
+
+### Patch Changes
+
+- [`6455cf006b3`](https://bitbucket.org/atlassian/atlassian-frontend/commits/6455cf006b3) - Builds for this package now pass through a tokens babel plugin, removing runtime invocations of the tokens() function and improving performance.
+
+## 0.8.0
+
+### Minor Changes
+
+- [`1e3f9743e57`](https://bitbucket.org/atlassian/atlassian-frontend/commits/1e3f9743e57) - A _monitor_ that is added during an event (eg `onDragStart`) will no longer be called for the current event. This is to prevent the accidental creation of infinite loops. This behaviour matches native [`EventTargets`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) where an event listener cannot add another event listener during an active event to the same event target in the same event phase.
+
+## 0.7.1
+
+### Patch Changes
+
+- [`8cc2f888c83`](https://bitbucket.org/atlassian/atlassian-frontend/commits/8cc2f888c83) - Upgrade Typescript from `4.3.5` to `4.5.5`
+
+## 0.7.0
+
+### Minor Changes
+
+- [`f2a7931d609`](https://bitbucket.org/atlassian/atlassian-frontend/commits/f2a7931d609) - Adding jsdoc to DragLocation type for better autocomplete
+
+## 0.6.0
+
+### Minor Changes
+
+- [`0f755214ee7`](https://bitbucket.org/atlassian/atlassian-frontend/commits/0f755214ee7) - Internal folder renaming. No API impact
+
+## 0.5.0
+
+### Minor Changes
+
+- [`17950433a70`](https://bitbucket.org/atlassian/atlassian-frontend/commits/17950433a70) - Touching package to release re-release previous version. The previous (now deprecated) version did not have it's entry points built correctly
+
+## 0.4.0
+
+### Minor Changes
+
+- [`4d739042b04`](https://bitbucket.org/atlassian/atlassian-frontend/commits/4d739042b04) - Improving jsdoc auto complete information for `GetFeedbackArgs`
+
+## 0.3.0
+
+### Minor Changes
+
+- [`52403a2c11f`](https://bitbucket.org/atlassian/atlassian-frontend/commits/52403a2c11f) - Adding a `canMonitor()` function to _monitors_ to allow a _monitor_ to conditionally apply to a drag operation.
+
+  ```ts
+  monitorForElements({
+    canMonitor: ({ source }) => source.data.type === 'card',
+    onDragStart: () =>
+      console.log('I will only be activated when dragging a card!'),
+  });
+  ```
+
+## 0.2.0
+
+### Minor Changes
+
+- [`1cf9e484b4b`](https://bitbucket.org/atlassian/atlassian-frontend/commits/1cf9e484b4b) - We have improved our naming consistency across our drag and drop packages.
+
+  - `@atlaskit/drag-and-drop/util/cancel-unhandled` has been renamed to `@atlaskit/drag-and-drop/addon/cancel-unhandled`
+
+## 0.1.0
+
+### Minor Changes
+
+- [`73427c38077`](https://bitbucket.org/atlassian/atlassian-frontend/commits/73427c38077) - Initial release of `@atlaskit/drag-and-drop` packages 🎉
+
+## 0.0.1
+
+### Patch Changes
+
+- [`8d4228767b0`](https://bitbucket.org/atlassian/atlassian-frontend/commits/8d4228767b0) - Upgrade Typescript from `4.2.4` to `4.3.5`.

package/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright 2022 Atlassian Pty Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,43 @@
+# Pragmatic drag and drop
+
+A performance optimized drag and drop framework
+
+> ℹ️ This package is in early access. We have not yet guaranteed API stability
+
+## 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/atlassian-drag-and-drop/).

package/__perf__/add-example.todo

@@ -0,0 +1 @@
+

package/adapter/element/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@atlaskit/pragmatic-drag-and-drop/adapter/element",
+  "main": "../../dist/cjs/entry-point/adapter/element.js",
+  "module": "../../dist/esm/entry-point/adapter/element.js",
+  "module:es2019": "../../dist/es2019/entry-point/adapter/element.js",
+  "sideEffects": false,
+  "types": "../../dist/types/entry-point/adapter/element.d.ts",
+  "typesVersions": {
+    ">=4.0 <4.5": {
+      "*": [
+        "../../dist/types-ts4.0/entry-point/adapter/element.d.ts"
+      ]
+    }
+  }
+}

package/adapter/file/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@atlaskit/pragmatic-drag-and-drop/adapter/file",
+  "main": "../../dist/cjs/entry-point/adapter/file.js",
+  "module": "../../dist/esm/entry-point/adapter/file.js",
+  "module:es2019": "../../dist/es2019/entry-point/adapter/file.js",
+  "sideEffects": false,
+  "types": "../../dist/types/entry-point/adapter/file.d.ts",
+  "typesVersions": {
+    ">=4.0 <4.5": {
+      "*": [
+        "../../dist/types-ts4.0/entry-point/adapter/file.d.ts"
+      ]
+    }
+  }
+}

package/addon/cancel-unhandled/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@atlaskit/pragmatic-drag-and-drop/addon/cancel-unhandled",
+  "main": "../../dist/cjs/entry-point/addon/cancel-unhandled.js",
+  "module": "../../dist/esm/entry-point/addon/cancel-unhandled.js",
+  "module:es2019": "../../dist/es2019/entry-point/addon/cancel-unhandled.js",
+  "sideEffects": false,
+  "types": "../../dist/types/entry-point/addon/cancel-unhandled.d.ts",
+  "typesVersions": {
+    ">=4.0 <4.5": {
+      "*": [
+        "../../dist/types-ts4.0/entry-point/addon/cancel-unhandled.d.ts"
+      ]
+    }
+  }
+}

package/constellation/index/about.mdx

@@ -0,0 +1,329 @@
+---
+order: 0
+---
+
+import SectionMessage from '@atlaskit/section-message';
+
+<!-- I'd like to change this section to be called Drag-and-drop or something, not Core, but still mulling it over. -->
+
+This package contains the essential pieces of the system, and is not tied to any JavaScript framework.
+
+- The [element adapter](/components/drag-and-drop/adapter/element-adapter) powers drag operations of elements.
+- The [file adapter](/components/drag-and-drop/adapter/file-adapter) powers drag operations of external files.
+- All of the base TypeScript types of Pragmatic drag and drop are in `@atlaskit/pragmatic-drag-and-drop/types`.
+
+## Addons
+
+### Cancel unhandled
+
+```ts
+import { cancelUnhandled } from '@atlaskit/pragmatic-drag-and-drop/addon/cancel-unhandled';
+```
+
+An _addon_ that absorbs unhandled drags. Using this function will mean that drops that don't occur in a _drop target_ will be _swallowed_ and the standard browser behaviour will not occur. This _addon_ is useful when disabling the native drag preview and for file drag operations
+
+```ts
+import { monitorForFiles } from '@atlaskit/pragmatic-drag-and-drop/adapter/file';
+import { cancelUnhandled } from '@atlaskit/pragmatic-drag-and-drop/addon/cancel-unhandled';
+
+monitorForFiles({
+  onDragStart: () => {
+    // when any drag starts for files block unhandled drags
+    cancelUnhandled.start();
+  },
+  onDrop: () => {
+    // resume standard behaviour when the drag is finished
+    cancelUnhandled.stop();
+  },
+});
+```
+
+## Utilities
+
+### Combine cleanup functions
+
+Combines the cleanup functions returned by _draggables_, _drop targets_ and _monitors_.
+
+```ts
+import { combine } from '@atlaskit/pragmatic-drag-and-drop/util/combine';
+```
+
+_Draggables_, _drop targets_ and _monitors_ return a cleanup function.
+
+```ts
+import { CleanupFn } from '@atlaskit/pragmatic-drag-and-drop/types';
+import { draggable } from '@atlaskit/pragmatic-drag-and-drop/adapter/element';
+
+const cleanup: CleanupFn = draggable({ element: myElement });
+
+// unbind functionality
+cleanup();
+```
+
+Sometimes you might be creating a whole lot of cleanup functions:
+
+```ts
+const cleanupDraggable: CleanupFn = draggable({ element: myElement });
+const cleanupDropTarget: CleanupFn = dropTargetForElements({
+  element: myElement,
+});
+const cleanupMonitor: CleanupFn = monitorForElements({ element: myElement });
+
+// unbind all functionality:
+cleanupDraggable();
+cleanupDropTarget();
+cleanupMonitor();
+```
+
+The `combine` utility smooshes multiple cleanup functions into a single cleanup function.
+
+```ts
+const cleanup: CleanupFn = combine(
+  draggable({ element: myElement }),
+  dropTargetForElements({
+    element: myElement,
+  }),
+  monitorForElements({ element: myElement }),
+);
+
+// unbind all functionality:
+cleanup();
+```
+
+Using `combine()` is helpful when working with `react` effects:
+
+```ts
+useEffect(() => {
+  const cleanup: CleanupFn = combine(
+    draggable({ element: myElement }),
+    dropTargetForElements({
+      element: myElement,
+    }),
+    monitorForElements({ element: myElement }),
+  );
+  return cleanup;
+}, []);
+
+// or even simpler:
+useEffect(() => {
+  return combine(
+    draggable({ element: myElement }),
+    dropTargetForElements({
+      element: myElement,
+    }),
+    monitorForElements({ element: myElement }),
+  );
+}, []);
+```
+
+### Once
+
+A function that will only allow the provided function to be called once.
+
+```ts
+import { once } from '@atlaskit/pragmatic-drag-and-drop/util/once';
+```
+
+This is useful if your drop target `getData()` is expensive to calculate.
+
+```ts
+dropTargetForFiles({
+  getData: once(getExpensiveData),
+});
+```
+
+```ts
+// calculate your data outside of get data
+const data = getExpensiveData();
+dropTargetForFiles({
+  getData: () => data,
+});
+```
+
+```ts
+// have expensive data along with updated addons
+const getDataOnce = once(getExpensiveData);
+dropTargetForFiles({
+  getData: ({ input, element }) => {
+    const data = getDataOnce();
+    return attachClosestEdge(data, { input, element, allowedEdges: ['top'] });
+  },
+});
+```
+
+### Reorder array
+
+A function to make common array reordering operations easier.
+
+```ts
+import { reorder } from '@atlaskit/pragmatic-drag-and-drop/util/reorder';
+```
+
+This is useful when you want to reorder items in a list. `reorder` returns a new array and does not modify the provided `list`.
+
+```ts
+const reordered = reorder({
+  list: [A, B, C],
+  startIndex: 0,
+  finishIndex: 1,
+});
+console.log(reordered); // [B, A, C]
+```
+
+### Set a custom native drag preview
+
+You can use `setCustomNativeDragPreview` to mount a new element to the page to be used as the drag preview. `setCustomNativeDragPreview` will call your `cleanup` function to remove the preview element from the page after the browser has taken a photo of the element. `setCustomNativeDragPreview` adds the `container` `Element` to the `document.body` and will remove the `container` `Element` after your `cleanup` function is called.
+
+`setCustomNativeDragPreview` has been designed to work with any view abstraction
+
+```ts
+import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/util/set-custom-native-drag-preview';
+```
+
+#### Usage example: `react` portals
+
+This technique requires your component to be re-rendered, but maintains the current `react` `context`
+
+```tsx
+type State =
+  | {
+      type: 'idle';
+    }
+  | {
+      type: 'preview';
+      container: HTMLElement;
+    };
+
+function Item() {
+  const [state, setState] = useState<State>({ type: 'idle' });
+  const ref = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    invariant(ref.current);
+
+    return draggable({
+      element: ref.current,
+      onGenerateDragPreview({ nativeSetDragImage }) {
+        setCustomNativeDragPreview({
+          render({ container }) {
+            // Cause a `react` re-render to create your portal synchronously
+            setState({ type: 'preview', container });
+            // In our cleanup function: cause a `react` re-render to create remove your portal
+            // Note: you can also remove the portal in `onDragStart`,
+            // which is when the cleanup function is called
+            return () => setState({ type: 'idle' });
+          },
+          nativeSetDragImage,
+        });
+      },
+    });
+  }, []);
+
+  return (
+    <>
+      <div ref={ref}>Drag Me</div>
+      {state.type === 'preview'
+        ? ReactDOM.createPortal(<Preview />, state.container)
+        : null}
+    </>
+  );
+}
+```
+
+#### Usage example: A new `react` application
+
+This technique requires no re-rendering of your component, but does not maintain the current `react` `context`
+
+
+```tsx
+import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/util/set-custom-native-drag-preview';
+
+draggable({
+  element: myElement,
+  onGenerateDragPreview: ({ nativeSetDragImage }) => {
+    setCustomNativeDragPreview({
+      render: function render({ container }) {
+        ReactDOM.render(<Preview item={item} />, container);
+        return function cleanup() {
+          ReactDOM.unmountComponentAtNode(container);
+        };
+      },
+      nativeSetDragImage,
+    });
+  },
+});
+```
+
+#### Placement
+
+You can control where the custom native drag preview is placed by using the `placement` argument:
+
+- `type: 'center'`: Place the center of the drag preview user the users pointer
+- `type: 'offset-from-pointer'`: Shift the drag preview away from the users pointer
+
+```tsx
+import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/util/set-custom-native-drag-preview';
+
+draggable({
+  element: myElement,
+  onGenerateDragPreview: ({ nativeSetDragImage }) => {
+    setCustomNativeDragPreview({
+      placement: { type: 'offset-from-pointer', x: '16px', y: '8px' },
+      render: function render({ container }) {
+        ReactDOM.render(<Preview item={item} />, container);
+        return function cleanup() {
+          ReactDOM.unmountComponentAtNode(container);
+        };
+      },
+      nativeSetDragImage,
+    });
+  },
+});
+```
+
+### Disable native drag preview
+
+In some situations, you might want to disable the native drag preview. The `disableNativeDragPreview` utility does this for all supported browsers and platforms.
+
+```ts
+import { disableNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/util/disable-native-drag-preview';
+```
+
+```ts
+import { disableNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/util/disable-native-drag-preview';
+
+draggable({
+  element: myElement,
+  onGenerateDragPreview({ setNativeDragPreview }) {
+    disableNativeDragPreview({ setNativeDragPreview });
+  },
+});
+```
+
+### Scroll just enough into view
+
+A function that scrolls a draggable element just enough into view so that the element becomes totally visible. If the element is already fully visible, then no scrolling will occur.
+
+```ts
+import { scrollJustEnoughIntoView } from '@atlaskit/pragmatic-drag-and-drop/util/scroll-just-enough-into-view';
+```
+
+Useful to avoid having drag previews cut off by scroll containers. See [element adapter](/components/drag-and-drop/adapter/element-adapter) for more information.
+
+```ts
+import { scrollJustEnoughIntoView } from '@atlaskit/pragmatic-drag-and-drop/util/scroll-just-enough-into-view';
+import { draggable } from '@atlaskit/pragmatic-drag-and-drop/adapter/element';
+
+draggable({
+  element: myElement,
+  onGenerateDragPreview: ({ source }) => {
+    scrollJustEnoughIntoView({ element: source.element });
+  },
+});
+```
+
+<SectionMessage>
+
+We don't bake `scrollJustEnoughIntoView` into Pragmatic drag and drop, as it may not be the best approach in all circumstances (for example, you might be making a small drag preview for a large draggable element, or you might be opting out of the native drag preview)
+
+</SectionMessage>

package/constellation/index/props.mdx

@@ -0,0 +1,3 @@
+---
+order: 3
+---