@dragselect/react 3.1.5 → 3.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +10 -0
- package/README.md +54 -51
- package/dist/index.cjs +2 -4
- package/dist/index.mjs +2 -4
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 3.2.0
|
|
4
|
+
|
|
5
|
+
- Fix: an area from `useDragSelectArea` that grows (e.g. after your data loads) now works everywhere in it. Before, clicks in the new part were ignored.
|
|
6
|
+
- `useDropZone` adds and removes only its own zone now, so other zones keep what was dropped in them.
|
|
7
|
+
- Requires the matching `dragselect` version, which has the area fix and the new `addDropZones`/`removeDropZones`.
|
|
8
|
+
|
|
9
|
+
## 3.1.6
|
|
10
|
+
|
|
11
|
+
- No API changes. Requires `dragselect@^3.1.6` (scroll detection fixes, see the DragSelect changelog).
|
|
12
|
+
|
|
3
13
|
## 3.1.5
|
|
4
14
|
|
|
5
15
|
First release. Versions follow `dragselect`: `@dragselect/react@X.Y.Z` pairs with `dragselect@X.Y.Z`.
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @dragselect/react
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[DragSelect](https://DragSelect.com) for React. Select things by dragging a box around them, like on your desktop, then you can even drag and drop them.
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
6
|
npm i dragselect @dragselect/react
|
|
@@ -9,11 +9,7 @@ npm i dragselect @dragselect/react
|
|
|
9
9
|
## Quick start
|
|
10
10
|
|
|
11
11
|
```tsx
|
|
12
|
-
import {
|
|
13
|
-
DragSelectProvider,
|
|
14
|
-
useSelectable,
|
|
15
|
-
useSelection,
|
|
16
|
-
} from '@dragselect/react'
|
|
12
|
+
import { DragSelectProvider, useSelectable, useSelection } from '@dragselect/react'
|
|
17
13
|
|
|
18
14
|
function Gallery({ photos }) {
|
|
19
15
|
return (
|
|
@@ -28,21 +24,22 @@ function Gallery({ photos }) {
|
|
|
28
24
|
|
|
29
25
|
function Photo({ photo }) {
|
|
30
26
|
const ref = useSelectable()
|
|
31
|
-
return <img ref={ref} src={photo.url} data-id={photo.id} />
|
|
27
|
+
return <img ref={ref} src={photo.url} data-id={photo.id} />
|
|
32
28
|
}
|
|
33
29
|
|
|
34
30
|
function Toolbar() {
|
|
35
|
-
const selected = useSelection
|
|
36
|
-
|
|
37
|
-
return <span>{selectedIds.length} selected</span>
|
|
31
|
+
const selected = useSelection()
|
|
32
|
+
return <p>{selected.length} selected</p>
|
|
38
33
|
}
|
|
39
34
|
```
|
|
40
35
|
|
|
41
|
-
|
|
36
|
+
That's it. Drag over the photos and `Toolbar` shows how many are selected.
|
|
42
37
|
|
|
43
|
-
|
|
38
|
+
## How it works
|
|
44
39
|
|
|
45
|
-
|
|
40
|
+
### 1. `DragSelectProvider` goes around your list
|
|
41
|
+
|
|
42
|
+
Everything inside it shares one DragSelect. You can pass any of the [settings](https://dragselect.com/docs/API/Settings):
|
|
46
43
|
|
|
47
44
|
```tsx
|
|
48
45
|
<DragSelectProvider settings={{ selectedClass: 'is-selected', draggability: false }}>
|
|
@@ -50,9 +47,11 @@ Creates one DragSelect instance for everything inside it and stops it on unmount
|
|
|
50
47
|
</DragSelectProvider>
|
|
51
48
|
```
|
|
52
49
|
|
|
53
|
-
|
|
50
|
+
The settings are read once. To change them later, use `useDragSelect()?.setSettings({...})`.
|
|
51
|
+
|
|
52
|
+
### 2. `useSelectable` goes on each item
|
|
54
53
|
|
|
55
|
-
|
|
54
|
+
It gives you a ref. Put it on the element, and put whatever you need to find the item again on the element too, e.g. a `data-id`:
|
|
56
55
|
|
|
57
56
|
```tsx
|
|
58
57
|
function File({ file }) {
|
|
@@ -61,34 +60,48 @@ function File({ file }) {
|
|
|
61
60
|
}
|
|
62
61
|
```
|
|
63
62
|
|
|
64
|
-
|
|
63
|
+
Selecting doesn't re-render your items. Selected items get the `ds-selected` class, so style them with CSS.
|
|
64
|
+
|
|
65
|
+
### 3. The selection
|
|
65
66
|
|
|
66
|
-
|
|
67
|
+
`useSelection` gives you the selected elements. Only the component that calls it re-renders when the selection changes. Read your ids back with `el.dataset.id`:
|
|
67
68
|
|
|
68
69
|
```tsx
|
|
69
70
|
function DeleteButton({ onDelete }) {
|
|
70
71
|
const selected = useSelection<HTMLLIElement>()
|
|
71
72
|
return (
|
|
72
|
-
<button
|
|
73
|
+
<button
|
|
74
|
+
onMouseDownCapture={e => e.stopPropagation()}
|
|
75
|
+
onTouchStartCapture={e => e.stopPropagation()}
|
|
76
|
+
disabled={!selected.length}
|
|
77
|
+
onClick={() => onDelete(selected.map((el) => el.dataset.id))}
|
|
78
|
+
>
|
|
73
79
|
Delete {selected.length}
|
|
74
80
|
</button>
|
|
75
81
|
)
|
|
76
82
|
}
|
|
77
83
|
```
|
|
78
84
|
|
|
79
|
-
|
|
85
|
+
To change the selection, `useDragSelect()` gives you the DragSelect instance itself. It has all the [methods](https://dragselect.com/docs/API/Methods), like `setSelection`, `addSelection` or `clearSelection`. It's `undefined` on the first render and on the server:
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
function SelectAll() {
|
|
89
|
+
const ds = useDragSelect()
|
|
90
|
+
return <button onClick={() => ds?.setSelection(ds.getSelectables())}>Select all</button>
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### 4. Events
|
|
80
95
|
|
|
81
|
-
|
|
96
|
+
`useDragSelectEvent` listens to any [DragSelect event](https://dragselect.com/docs/API/Events). It stops listening when the component unmounts, and it always calls your latest callback, so you don't need `useCallback`:
|
|
82
97
|
|
|
83
98
|
```tsx
|
|
84
|
-
useDragSelectEvent('DS:start', ({ items }) =>
|
|
85
|
-
console.log('started with', items.length, 'selected')
|
|
86
|
-
})
|
|
99
|
+
useDragSelectEvent('DS:start', ({ items }) => console.log('started with', items.length))
|
|
87
100
|
```
|
|
88
101
|
|
|
89
|
-
###
|
|
102
|
+
### 5. Area and drop zones
|
|
90
103
|
|
|
91
|
-
|
|
104
|
+
By default you can start a selection anywhere on the page. `useDragSelectArea` limits it to one element:
|
|
92
105
|
|
|
93
106
|
```tsx
|
|
94
107
|
function FileList({ files }) {
|
|
@@ -101,51 +114,41 @@ function FileList({ files }) {
|
|
|
101
114
|
}
|
|
102
115
|
```
|
|
103
116
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
Registers the element as a drop zone. The `id` is DragSelect's name for the zone: it comes back as `dropTarget.id` in events, works with `ds.getItemsDroppedByZoneId(id)`, and suffixes the classes items get (e.g. `ds-dropped-target-archive`).
|
|
117
|
+
`useDropZone` turns an element into a place you can drop things on. Here is a folder that tells you which files were dropped on it:
|
|
107
118
|
|
|
108
119
|
```tsx
|
|
109
|
-
function Folder({ id, name,
|
|
120
|
+
function Folder({ id, name, onDrop }) {
|
|
110
121
|
const ref = useDropZone(id)
|
|
111
122
|
|
|
112
|
-
// `items` is everything that was dragged: one element or the whole selection
|
|
113
123
|
useDragSelectEvent('DS:end', ({ items, isDragging, dropTarget }) => {
|
|
114
|
-
if (
|
|
115
|
-
onMove(items.map((el) => el.dataset.id))
|
|
124
|
+
if (isDragging && dropTarget?.id === id) onDrop(items.map((el) => el.dataset.id))
|
|
116
125
|
})
|
|
117
126
|
|
|
118
127
|
return <div ref={ref}>📁 {name}</div>
|
|
119
128
|
}
|
|
120
|
-
|
|
121
|
-
// used as:
|
|
122
|
-
<Folder id="archive" name="Archive" onMove={(ids) => archive(ids)} />
|
|
123
129
|
```
|
|
124
130
|
|
|
131
|
+
The id also ends up in CSS classes, so you can style things:
|
|
132
|
+
|
|
125
133
|
```css
|
|
126
|
-
/*
|
|
134
|
+
/* zones while something is being dragged */
|
|
127
135
|
.ds-dropzone-ready { outline: 2px dashed }
|
|
128
|
-
/* items
|
|
136
|
+
/* items dropped on the "archive" zone */
|
|
129
137
|
.ds-dropped-target-archive { opacity: 0.5 }
|
|
130
138
|
```
|
|
131
139
|
|
|
132
|
-
###
|
|
140
|
+
### 6. Keyboard
|
|
133
141
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
```tsx
|
|
137
|
-
function SelectAll() {
|
|
138
|
-
const ds = useDragSelect()
|
|
139
|
-
return <button onClick={() => ds?.setSelection(ds.getSelectables())}>Select all</button>
|
|
140
|
-
}
|
|
141
|
-
```
|
|
142
|
+
If your items are `<button>`s, people can select them with Enter or Space and move them with the arrow keys.
|
|
142
143
|
|
|
143
|
-
##
|
|
144
|
+
## Good to know
|
|
144
145
|
|
|
145
|
-
-
|
|
146
|
-
-
|
|
147
|
-
-
|
|
146
|
+
- The version matches DragSelect. Use `@dragselect/react@X.Y.Z` with `dragselect@X.Y.Z`.
|
|
147
|
+
- Needs React 18 or newer.
|
|
148
|
+
- Works with the Next.js App Router (the package is marked `'use client'`) and with SSR.
|
|
149
|
+
- More than one `DragSelectProvider` on a page? Give each one a `useDragSelectArea`. Otherwise they all listen to the whole page and mess up each other's selection.
|
|
150
|
+
- The refs are plain functions, so you can also call them yourself, e.g. `ref(element)` once an animation is done.
|
|
148
151
|
|
|
149
152
|
## License
|
|
150
153
|
|
|
151
|
-
GPL-3.0 or [commercial license](https://dragselect.com/licenses),
|
|
154
|
+
GPL-3.0 or a [commercial license](https://dragselect.com/licenses), same as DragSelect.
|
package/dist/index.cjs
CHANGED
|
@@ -88,10 +88,8 @@ function useDropZone(id) {
|
|
|
88
88
|
react.useEffect(() => {
|
|
89
89
|
if (!ds || !element)
|
|
90
90
|
return;
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
return () => void (!ds.stopped &&
|
|
94
|
-
ds.setSettings({ dropZones: zones().filter((z) => z.element !== element) }));
|
|
91
|
+
ds.addDropZones({ id, element });
|
|
92
|
+
return () => void (!ds.stopped && ds.removeDropZones(element));
|
|
95
93
|
}, [ds, element, id]);
|
|
96
94
|
return ref;
|
|
97
95
|
}
|
package/dist/index.mjs
CHANGED
|
@@ -86,10 +86,8 @@ function useDropZone(id) {
|
|
|
86
86
|
useEffect(() => {
|
|
87
87
|
if (!ds || !element)
|
|
88
88
|
return;
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
return () => void (!ds.stopped &&
|
|
92
|
-
ds.setSettings({ dropZones: zones().filter((z) => z.element !== element) }));
|
|
89
|
+
ds.addDropZones({ id, element });
|
|
90
|
+
return () => void (!ds.stopped && ds.removeDropZones(element));
|
|
93
91
|
}, [ds, element, id]);
|
|
94
92
|
return ref;
|
|
95
93
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dragselect/react",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.2.0",
|
|
4
4
|
"description": "React hooks for DragSelect: drag-to-select and drag-and-drop for React components.",
|
|
5
5
|
"main": "./dist/index.cjs",
|
|
6
6
|
"module": "./dist/index.mjs",
|
|
@@ -22,14 +22,14 @@
|
|
|
22
22
|
"test:watch": "vitest"
|
|
23
23
|
},
|
|
24
24
|
"peerDependencies": {
|
|
25
|
-
"dragselect": "^3.
|
|
25
|
+
"dragselect": "^3.2.0",
|
|
26
26
|
"react": ">=18.0.0"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@rollup/plugin-typescript": "^11.1.3",
|
|
30
30
|
"@testing-library/react": "^14.3.1",
|
|
31
31
|
"@types/react": "18.2.22",
|
|
32
|
-
"dragselect": "^3.
|
|
32
|
+
"dragselect": "^3.2.0",
|
|
33
33
|
"jsdom": "^25.0.1",
|
|
34
34
|
"react": "^18.2.0",
|
|
35
35
|
"react-dom": "^18.2.0",
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"rollup-plugin-dts": "^6.0.2",
|
|
38
38
|
"tslib": "^2.6.2",
|
|
39
39
|
"typescript": "^5.2.2",
|
|
40
|
-
"vitest": "^
|
|
40
|
+
"vitest": "^4.1.11"
|
|
41
41
|
},
|
|
42
42
|
"files": [
|
|
43
43
|
"dist",
|