@atlaskit/pragmatic-drag-and-drop-docs
Version:
This package holds the documentation for Pragmatic drag and drop in one place. It is not intended to be consumed directly by consumers. The package is used by other tools for sharing examples
278 lines (206 loc) • 10.6 kB
text/mdx
---
order: 0
title: Upgrade guide
---
For `1.0` we have made a number of naming and path changes, but is otherwise a safe upgrade. We have
taken the opportunity with `1.0` to shift things around in response to how our outputs have
organically grown.
We have created a codemod (an automated code change tool) which will safely upgrade most usages.
People using the (old) _file adapter_ will need to perform some additional (minor) manual steps to
move to our new _external adapter_. The codemod will add the next steps as comments for _file
adapter_ consumers in the files that need to be updated.
## Step 0: A new adapter model
The big conceptual change for `1.0` is our new adapter setup. Previously, we had two adapters:
1. element adapter
2. file adapter
The original thinking was that there would be lots of adapters for different entity types (eg a
"text" adapter). However, that thinking did not pan out well, so we have moved in a different
direction.
There are now three adapters:
1. [element adapter](/components/pragmatic-drag-and-drop/core-package/adapters/element) → handling
the dragging of draggable elements
2. [text selection adapter](/components/pragmatic-drag-and-drop/core-package/adapters/text-selection)
**(new)** → handling the dragging of text selections
3. [external adapter](/components/pragmatic-drag-and-drop/core-package/adapters/external) **(new)**
→ handling drag operations that started outside of the current `window` (eg files and text from
other `window`s or applications)
The _external adapter_ can be used to handle file dropping (as the old _file adapter_ did), as well
as any other native data type (eg `"text/plain"`).
## Step 1: react-indicator → react-drop-indicator
We have renamed our drop indicator package to improve naming consistency across our outputs.
```diff
- /pragmatic-drag-and-drop-react-indicator
+ /pragmatic-drag-and-drop-react-drop-indicator
```
After running _step 1_ your application will be broken as your imports will not yet be updated in
your code. In _step 3_ your imports will be fixed.
```bash
# Using yarn
yarn remove /pragmatic-drag-and-drop-react-indicator
yarn add /pragmatic-drag-and-drop-react-drop-indicator
```
## Step 2: Upgrade to `1.x` packages
You will need to shift the following packages from `0.x` to `1.0` in your project:
- /pragmatic-drag-and-drop
- /pragmatic-drag-and-drop-hitbox
- /pragmatic-drag-and-drop-live-region
- /pragmatic-drag-and-drop-flourish
- /pragmatic-drag-and-drop-react-accessibility
- /pragmatic-drag-and-drop-react-beautiful-dnd-migration
- /pragmatic-drag-and-drop-react-beautiful-dnd-autoscroll
```bash
# Using yarn
yarn upgrade /pragmatic-drag-and-drop@^1.0.0
# Do for all packages you have installed,
# or use our bash script below
```
Here is an optional `bash` script that will upgrade all your installed Pragmatic drag and drop
packages with `yarn`
```bash
#!/bin/bash
PACKAGES=(
"@atlaskit/pragmatic-drag-and-drop"
"@atlaskit/pragmatic-drag-and-drop-auto-scroll"
"@atlaskit/pragmatic-drag-and-drop-hitbox"
"@atlaskit/pragmatic-drag-and-drop-live-region"
"@atlaskit/pragmatic-drag-and-drop-flourish"
"@atlaskit/pragmatic-drag-and-drop-react-accessibility"
"@atlaskit/pragmatic-drag-and-drop-react-beautiful-dnd-migration"
"@atlaskit/pragmatic-drag-and-drop-react-beautiful-dnd-autoscroll"
)
VERSION="^1.0.0"
for PACKAGE in "${PACKAGES[@]}"
do
if grep -q "\"${PACKAGE}\"" ./package.json; then
echo "${PACKAGE} is installed, upgrading to ${VERSION}..."
yarn upgrade ${PACKAGE}@${VERSION}
# for yarn@3, use:
# yarn up ${PACKAGE}@${VERSION}
else
echo "${PACKAGE} is not installed, skipping upgrade."
fi
done
```
## Step 3: Run our codemod
Use our [codemod-cli](https://www.npmjs.com/package/@atlaskit/codemod-cli) package to run our
`upgrade-pragmatic-drag-and-drop-to-stable` codemod. This will automatically shift over all usage to
our `1.0` API (except for the file adapter)
```bash
# Example usage
npx /codemod-cli@latest --preset upgrade-pragmatic-drag-and-drop-to-stable --extensions tsx,ts,js --parser tsx ./path/to/source
```
## Step 4: Add our `DragEvent` ponyfill for Jest
If you are doing testing of Pragmatic drag and drop using `[Jest](https://jestjs.io/)` (+
[`jsdom`](https://github.com/jsdom/jsdom)), then you will likely need to start ponyfiling
[`DragEvent`](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent). Unfortunately,
[jsdom does not ponyfill `DragEvent`](https://github.com/jsdom/jsdom/issues/2913). `0.x` got away
with not having `DragEvent` pollyfiled, but `1.x` requires `DragEvent` to be setup correctly. Trying
to rely on `DragEvent` not being setup would have required non-trival changes to the library code,
as well as a strange test experience where some things would work, but other things would not.
We plan on creating a package for easy consumption of our `DragEvent` polyfill, but in the meantime,
you can copy it from [Github](https://gist.github.com/alexreardon/cbc317ede2212d6db59ba5ff59dcf419)
## Full changes
Here is a list of all the `1.0` changes incase you are unable to run the automated changes:
We have renamed our drop indicator package to improve naming consistency across our outputs.
```diff
- /pragmatic-drag-and-drop-react-indicator
+ /pragmatic-drag-and-drop-react-drop-indicator
```
The following entry point paths have been changed, but their exports are unchanged:
```diff
- /pragmatic-drag-and-drop/adapter/element
+ /pragmatic-drag-and-drop/element/adapter
- /pragmatic-drag-and-drop/util/set-custom-native-drag-preview
+ /pragmatic-drag-and-drop/element/set-custom-native-drag-preview
- /pragmatic-drag-and-drop/util/offset-from-pointer
+ /pragmatic-drag-and-drop/element/offset-from-pointer
- /pragmatic-drag-and-drop/util/center-under-pointer
+ /pragmatic-drag-and-drop/element/center-under-pointer
- /pragmatic-drag-and-drop/util/disable-native-drag-preview
+ /pragmatic-drag-and-drop/element/disable-native-drag-preview
- /pragmatic-drag-and-drop/util/scroll-just-enough-into-view
+ /pragmatic-drag-and-drop/element/scroll-just-enough-into-view
- /pragmatic-drag-and-drop/util/combine
+ /pragmatic-drag-and-drop/combine
- /pragmatic-drag-and-drop/util/once
+ /pragmatic-drag-and-drop/once
- /pragmatic-drag-and-drop/util/reorder
+ /pragmatic-drag-and-drop/reorder
- /pragmatic-drag-and-drop-hitbox/addon/closest-edge
+ /pragmatic-drag-and-drop-hitbox/closest-edge
```
`cancelUnhandled` has been renamed to `preventUnhandled` to more accurately reflect what it is
achieving, and the entry point path changed too.
```diff
- import {cancelUnhandled} from '/pragmatic-drag-and-drop/addon/cancel-unhandled';
+ import {preventUnhandled} from '/pragmatic-drag-and-drop/prevent-unhandled';
```
`offsetFromPointer` has been renamed to `pointerOutsideOfPreview` as `offsetFromPointer` was found
to be misleading for folks. The entry point path has been changed too.
```diff
- import { offsetFromPointer } from '/pragmatic-drag-and-drop/util/offset-from-pointer';
+ import { pointerOutsideOfPreview } from '/pragmatic-drag-and-drop/element/pointer-outside-of-preview';
```
The `ElementMonitorCanMonitorArgs` type has been renamed to `ElementMonitorGetFeedbackArgs` to
improve naming consistency with other feedback types
```diff
- import type { ElementMonitorCanMonitorArgs } from '/pragmatic-drag-and-drop/adapter/element';
+ import type { ElementMonitorGetFeedbackArgs } from '/pragmatic-drag-and-drop/element/adapter';
```
The type `SourceCanStartArgs` is no longer being exported from
`'/pragmatic-drag-and-drop/types'` as the type was never being used and was incorrect.
Please use the appropriate `*GetFeedbackArgs` type instead.
```diff
- import type { SourceCanStartArgs } from '/pragmatic-drag-and-drop/type';
+ // use types from the appropriate adapter
+ import type { ElementMonitorGetFeedbackArgs } from '/pragmatic-drag-and-drop/element/adapter';
+ import type { DropTargetGetFeedbackArgs } from '/pragmatic-drag-and-drop/element/adapter';
```
The `/pragmatic-drag-and-drop-auto-scroll` named exports have been updated to reflect our
updated adapter names
```diff
- import {autoScrollForFiles} from '/pragmatic-drag-and-drop-auto-scroll/file';
+ import {autoScrollForExternal} from '/pragmatic-drag-and-drop-auto-scroll/external';
- import {unsafeOverflowAutoScrollForFiles} from '/pragmatic-drag-and-drop-auto-scroll/unsafe-overflow/file';
+ import {unsafeOverflowAutoScrollForExternal} from '/pragmatic-drag-and-drop-auto-scroll/unsafe-overflow/external';
```
Our _file adapter_ has been replaced by a new
[_external adapter_](/components/pragmatic-drag-and-drop/core-package/adapters/external).
```ts
/** 0.x API **/
import { dropTargetForFiles, monitorForFiles } from '/pragmatic-drag-and-drop/file';
dropTargetForFiles({
element: myElement,
onDrop({ source }) {
// 😬 Not to easy to get files!
if (!source.items) {
return;
}
const files: File[] = [...source.items]
.filter((item) => item.kind === 'file')
.map((item) => item.getAsFile())
.filter((file: File | null): file is File => file != null);
},
});
/** 1.0 API **/
import {
dropTargetForExternal,
monitorForExternal,
} from '/pragmatic-drag-and-drop/external';
import { containsFiles, getFiles } from '/pragmatic-drag-and-drop/external/file';
dropTargetForExternal({
canDrop: containsFiles,
onDrop({ source }) {
// 🤩 Easy to get files!
const files: File[] = getFiles({ source });
},
});
```
## Auto scrolling
While we are talking about changes, we encourage all consumers to move off our legacy auto scroller
packages, and onto our new, faster, more flexible and more delightful auto scroller package:
**Old:**
[`/pragmatic-drag-and-drop-react-beautiful-dnd-autoscroll`](/components/pragmatic-drag-and-drop/optional-packages/react-beautiful-dnd-autoscroll)
(previously called `/pragmatic-drag-and-drop-autoscroll`)
**New:**
[`/pragmatic-drag-and-drop-auto-scroll`](/components/pragmatic-drag-and-drop/optional-packages/auto-scroll)