@dragselect/react 3.1.6 → 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 CHANGED
@@ -1,5 +1,11 @@
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
+
3
9
  ## 3.1.6
4
10
 
5
11
  - No API changes. Requires `dragselect@^3.1.6` (scroll detection fixes, see the DragSelect changelog).
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @dragselect/react
2
2
 
3
- React hooks for [DragSelect](https://DragSelect.com): drag-to-select and drag-and-drop for your components. No refs to juggle, no manual subscribe/unsubscribe.
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} /> // selected ones get the .ds-selected class
27
+ return <img ref={ref} src={photo.url} data-id={photo.id} />
32
28
  }
33
29
 
34
30
  function Toolbar() {
35
- const selected = useSelection<HTMLImageElement>()
36
- const selectedIds = selected.map((el) => el.dataset.id)
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
- ## API
36
+ That's it. Drag over the photos and `Toolbar` shows how many are selected.
42
37
 
43
- ### `<DragSelectProvider settings?>`
38
+ ## How it works
44
39
 
45
- Creates one DragSelect instance for everything inside it and stops it on unmount. Accepts any [DragSelect setting](https://dragselect.com/docs/API/Settings). Settings are read once; change them later with `useDragSelect()?.setSettings({...})`.
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
- ### `useSelectable()` → `ref`
50
+ The settings are read once. To change them later, use `useDragSelect()?.setSettings({...})`.
51
+
52
+ ### 2. `useSelectable` goes on each item
54
53
 
55
- Makes the element selectable while the component is mounted. Selecting does not re-render the item: style it with the `ds-selected` class (or your `selectedClass`).
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
- ### `useSelection<E>()` → `E[]`
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
- The selected elements, as DragSelect holds them. Only the component calling it re-renders when the selection changes. To get your ids back, put them on the element (`data-id={id}`) and read `el.dataset.id`.
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 disabled={!selected.length} onClick={() => onDelete(selected.map((el) => el.dataset.id))}>
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
- ### `useDragSelectEvent(eventName, callback)`
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
- Subscribes to any [DragSelect event](https://dragselect.com/docs/API/Events) for the component's lifetime. The latest callback is always called, so you don't need `useCallback`.
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
- ### `useDragSelectArea()` → `ref`
102
+ ### 5. Area and drop zones
90
103
 
91
- Restricts selecting and dragging to this element. Without it, the whole document is the area.
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
- ### `useDropZone(id)` → `ref`
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, onMove }) {
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 (!isDragging || dropTarget?.id !== id) return
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
- /* the zone while a drag is in progress */
134
+ /* zones while something is being dragged */
127
135
  .ds-dropzone-ready { outline: 2px dashed }
128
- /* items that were dropped into the "archive" zone */
136
+ /* items dropped on the "archive" zone */
129
137
  .ds-dropped-target-archive { opacity: 0.5 }
130
138
  ```
131
139
 
132
- ### `useDragSelect()` → `DragSelect | undefined`
140
+ ### 6. Keyboard
133
141
 
134
- The raw instance, for anything the hooks don't cover. It is `undefined` on the first render and during SSR.
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
- ## Notes
144
+ ## Good to know
144
145
 
145
- - Versions follow DragSelect: use `@dragselect/react@X.Y.Z` with `dragselect@X.Y.Z`.
146
- - Works with React 18+, Next.js App Router (the bundle ships `'use client'`), and SSR.
147
- - The returned refs are plain functions: you can also call them yourself, e.g. `ref(element)` once an animation is done.
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), the same as DragSelect.
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
- const zones = () => { var _a; return (_a = ds.stores.SettingsStore.s.dropZones) !== null && _a !== void 0 ? _a : []; };
92
- ds.setSettings({ dropZones: [...zones(), { id, element }] });
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
- const zones = () => { var _a; return (_a = ds.stores.SettingsStore.s.dropZones) !== null && _a !== void 0 ? _a : []; };
90
- ds.setSettings({ dropZones: [...zones(), { id, element }] });
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.1.6",
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.1.6",
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.1.6",
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": "^2.1.9"
40
+ "vitest": "^4.1.11"
41
41
  },
42
42
  "files": [
43
43
  "dist",