dragselect 2.5.5 → 2.6.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 +11 -0
- package/deployment.md +32 -0
- package/dist/DragSelect.d.ts +4 -0
- package/dist/DragSelect.es6m.js +204 -106
- package/dist/DragSelect.js +205 -107
- package/dist/ds.es6m.min.js +1 -1
- package/dist/ds.min.js +1 -1
- package/dist/modules/Selection.d.ts +14 -0
- package/package.json +15 -20
- package/rollup.config.js +1 -34
- package/src/DragSelect.js +4 -2
- package/src/methods/isCollision.js +3 -0
- package/src/modules/Selection.js +31 -13
- package/CODE_OF_CONDUCT.md +0 -128
- package/CONTRIBUTING.md +0 -48
- package/LICENSE +0 -21
- package/README.md +0 -478
- package/deploying.md +0 -36
package/README.md
DELETED
|
@@ -1,478 +0,0 @@
|
|
|
1
|
-
<p align="center" style="text-align: center" >
|
|
2
|
-
<a href="https://DragSelect.com/">
|
|
3
|
-
<picture>
|
|
4
|
-
<source media="(prefers-color-scheme: light)" srcset="https://dragselect.com/media/dragselect-logo.png">
|
|
5
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://dragselect.com/media/dragselect-logo-alt.png">
|
|
6
|
-
<img alt="The DragSelect logo: a selection symbol, a hand, a drop symbol and a mouse within a selection square." width="300" src="https://dragselect.com/media/dragselect-logo.png">
|
|
7
|
-
</picture>
|
|
8
|
-
</a>
|
|
9
|
-
</p>
|
|
10
|
-
<p align="center" style="text-align: center">
|
|
11
|
-
<a href="https://dragselect.com/">Project-Page</a> |
|
|
12
|
-
<a href="https://dragselect.com/docs/intro">Documentation</a> |
|
|
13
|
-
<a href="https://github.com/ThibaultJanBeyer/DragSelect/">Github</a> |
|
|
14
|
-
<a href="https://www.npmjs.com/package/dragselect">NPM</a> |
|
|
15
|
-
</p>
|
|
16
|
-
<p align="center" style="text-align: center; margin-bottom: 50px;">
|
|
17
|
-
<a href="https://github.com/ThibaultJanBeyer/DragSelect/actions"><img alt="Build Status" src="https://github.com/ThibaultJanBeyer/DragSelect/actions/workflows/github-actions-build.yml/badge.svg"></a>
|
|
18
|
-
<a href="https://dragselect.com/v2/ds.min.js"><img alt="gzip size" src="https://img.badgesize.io/https://dragselect.com/v2/ds.min.js?compression=gzip"></a>
|
|
19
|
-
<a href="https://www.npmjs.com/package/dragselect"><img alt="npm downloads count" src="https://img.shields.io/npm/dt/dragselect.svg"></a>
|
|
20
|
-
<a href="https://github.com/ThibaultJanBeyer/DragSelect/blob/master/package.json"><img alt="No Dependency" src="https://img.shields.io/badge/dependencies-none-informational"></a>
|
|
21
|
-
<a href="https://github.com/ThibaultJanBeyer/DragSelect/blob/master/CONTRIBUTING.md"><img alt="Contributors Welcome" src="https://img.shields.io/badge/contributors-welcome-blueviolet"></a>
|
|
22
|
-
<a href="https://github.com/sponsors/ThibaultJanBeyer"><img alt="Sponsors Welcome" src="https://img.shields.io/badge/sponsors-welcome-blueviolet"></a>
|
|
23
|
-
</p>
|
|
24
|
-
|
|
25
|
-
# DragSelect 
|
|
26
|
-
easily add a selection algorithm to your application/website.
|
|
27
|
-
|
|
28
|
-
# TOC
|
|
29
|
-
|
|
30
|
-
- [Project Page: Demo & Info](#project-page-demo--info)
|
|
31
|
-
- [Key-Features](#key-features)
|
|
32
|
-
- [Why?](#why)
|
|
33
|
-
- [Supporters](#supporters)
|
|
34
|
-
- [Thanks to:](#thanks-to)
|
|
35
|
-
- [Installation](#installation)
|
|
36
|
-
- [NPM](#npm)
|
|
37
|
-
- [Yarn](#yarn)
|
|
38
|
-
- [Global](#global)
|
|
39
|
-
- [Bower (deprecated)](#bower-deprecated)
|
|
40
|
-
- [That's it, you're ready to rock!](#thats-it-youre-ready-to-rock)
|
|
41
|
-
- [Usage](#usage)
|
|
42
|
-
- [Simple](#simple)
|
|
43
|
-
- [Within a scroll-able Area](#within-a-scroll-able-area)
|
|
44
|
-
- [With DropZones](#with-dropzones)
|
|
45
|
-
- [Extended](#extended)
|
|
46
|
-
- [Mobile/Touch usage](#mobiletouch-usage)
|
|
47
|
-
- [Accessibility (a11y)](#accessibility-a11y)
|
|
48
|
-
- [Use your own Drag And Drop](#use-your-own-drag-and-drop)
|
|
49
|
-
- [Using another plugin/tool (3rd party)](#using-another-plugintool-3rd-party)
|
|
50
|
-
- [Example](#example)
|
|
51
|
-
- [Writing a fully custom solution](#writing-a-fully-custom-solution)
|
|
52
|
-
- [Example](#example-1)
|
|
53
|
-
- [Constructor Properties (Settings)](#constructor-properties-settings)
|
|
54
|
-
- [Post-Initialization Setting-Updates](#post-initialization-setting-updates)
|
|
55
|
-
- [Event Callbacks](#event-callbacks)
|
|
56
|
-
- [Events](#events)
|
|
57
|
-
- [Callback Object Keys](#callback-object-keys)
|
|
58
|
-
- [Methods](#methods)
|
|
59
|
-
- [Classes](#classes)
|
|
60
|
-
- [Have Fun!](#have-fun)
|
|
61
|
-
|
|
62
|
-
# Project Page: Demo & Info
|
|
63
|
-
|
|
64
|
-
[https://dragselect.com/](https://dragselect.com/)
|
|
65
|
-
|
|
66
|
-
# Key-Features
|
|
67
|
-
|
|
68
|
-
- **No dependencies** [](https://github.com/ThibaultJanBeyer/DragSelect/blob/master/package.json)
|
|
69
|
-
- Hyper customizable
|
|
70
|
-
- Replicates operating system drag-selection in the browser
|
|
71
|
-
- Accessibility (a11y)
|
|
72
|
-
- Add drag selection
|
|
73
|
-
- Use modifier keys to make multiple independent selections
|
|
74
|
-
- Select, Drag and Drop also via keyboard
|
|
75
|
-
- Choose which elements can be selected
|
|
76
|
-
- Supports all major browsers
|
|
77
|
-
- Selected elements can be dragged and dropped
|
|
78
|
-
- Lightweight, only 
|
|
79
|
-
- Popular:  on npm
|
|
80
|
-
- DragSelect was written with Performance in mind (can easily select >15.000 Elements)
|
|
81
|
-
- Supports SVG
|
|
82
|
-
- Supports mobile (touch interaction)
|
|
83
|
-
- Free & open source under MIT License
|
|
84
|
-
- Ease of use
|
|
85
|
-
|
|
86
|
-

|
|
87
|
-
|
|
88
|
-
# Why?
|
|
89
|
-
|
|
90
|
-
Because apparently there was nothing that does not require jquery out there.
|
|
91
|
-
This is better than https://jqueryui.com/selectable/ or https://jqueryui.com/draggable/ and has no dependencies.
|
|
92
|
-
We use it currently in a professional rich interface application where we have a file management system. The user can select files to organize them and change their metadata, with this plugin our users are able to select multiple files and perform batch/bulk-operations (applying changes to multiple files at once). We also started using it in production for a huge, graphical cloud hosting manager with a lot of active users. Users can select multiple servers, storages, etc. on an artboard to perform multi-operations, re-organize them, move them on the UI or batch-delete. We’re running it since January 18' it’s super helpful and very stable, let’s keep it that way. I can easily think of dozens other use-cases. I’m really keen to know how you use it in your projects, please let me know.
|
|
93
|
-
|
|
94
|
-
# Supporters
|
|
95
|
-
|
|
96
|
-
Please donate to support the countless hours of hard work & support. Especially if your company makes money, then there is no excuse. Thank you :)
|
|
97
|
-
|
|
98
|
-
If you're too poor or broke you can still support us with your time instead by [contributing to the code](https://github.com/ThibaultJanBeyer/DragSelect/blob/master/CONTRIBUTING.md)!
|
|
99
|
-
|
|
100
|
-
## Thanks to:
|
|
101
|
-
|
|
102
|
-
| <a href="https://www.browserstack.com/"><img src="https://dragselect.com/media/browserstack.jpg" alt="Browserstack" width="150px"></a> | [You?](https://github.com/sponsors/ThibaultJanBeyer) |
|
|
103
|
-
|--- |--- |
|
|
104
|
-
|[BrowserStack](https://www.browserstack.com/) is a service for cross-browser testing. They support this open source projects by providing us with a [free account](https://www.browserstack.com/open-source)! | Thank and support us by making a [Direct Donation to DragSelect](https://www.blockchain.com/btc/address/1LdweSpjgSeJC8XxX3swrohBMBLUzg6cmC) (via Bitcoin: `1LdweSpjgSeJC8XxX3swrohBMBLUzg6cmC`). Or sponsor via [GitHub Sponsors](https://github.com/sponsors/ThibaultJanBeyer) or [Get in touch](mailto:thibault.beyer@gmail.com).
|
|
105
|
-
|
|
106
|
-
All donations are distributed with all project contributors proportionally to their involvement. We are grateful for any amount:
|
|
107
|
-
We have more than , imagine how much we'd have if everyone would have had donated only 1$ 🤩 (unfortunately this did not happen)
|
|
108
|
-
|
|
109
|
-
If you donate, we can display your logo here if you want, which will give you fame, fortune and help you recruit great talent and boosting your SEO.
|
|
110
|
-
|
|
111
|
-
# Installation
|
|
112
|
-
## NPM
|
|
113
|
-
```console
|
|
114
|
-
npm install --save dragselect
|
|
115
|
-
```
|
|
116
|
-
## Yarn
|
|
117
|
-
```console
|
|
118
|
-
yarn add dragselect
|
|
119
|
-
```
|
|
120
|
-
## Global
|
|
121
|
-
|
|
122
|
-
Just [download the file](https://dragselect.com/v2/DragSelect.js) ([minified](https://dragselect.com/v2/ds.min.js)) and add it to your document:
|
|
123
|
-
|
|
124
|
-
```html
|
|
125
|
-
<script src="https://dragselect.com/v2/ds.min.js"></script>
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
> Note: if you are using `<script type=module` you can use the `DragSelect.es6m.js` or `ds.es6m.min.js` files as they include `export default DragSelect`
|
|
129
|
-
|
|
130
|
-
> We don't recommend the direct linking for production set-up since you'll not benefit from versioning. Please use `npm` if you can.
|
|
131
|
-
## Bower (deprecated)
|
|
132
|
-
```console
|
|
133
|
-
bower install --save dragselect
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
*Note: the Bower project is deprecated. Please use npm instead. If you have to use bower, you'll have to build the project after installing it via `npm run rollup`*
|
|
137
|
-
|
|
138
|
-
## That's it, you're ready to rock!
|
|
139
|
-
Of course you can also just include the code within your code and bundle it to save a request.
|
|
140
|
-
|
|
141
|
-
DragSelect supports `module.exports`, `AMD Modules` with `define`, `es6 modules` with `.es6m` versions and has a fallback to global namespace for maximum out of the box support.
|
|
142
|
-
|
|
143
|
-
# Usage
|
|
144
|
-
Now in your JavaScript you can simply pass elements to the function like so:
|
|
145
|
-
|
|
146
|
-
## Simple
|
|
147
|
-
|
|
148
|
-
The simplest possible usage.
|
|
149
|
-
Choose which elements can be selected:
|
|
150
|
-
|
|
151
|
-
```javascript
|
|
152
|
-
new DragSelect({
|
|
153
|
-
selectables: document.getElementsByClassName('selectable-nodes')
|
|
154
|
-
});
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
<p data-height="350" data-theme-id="0" data-slug-hash="prpwYG" data-default-tab="js,result" data-user="ThibaultJanBeyer" data-embed-version="2" data-pen-title="prpwYG" class="codepen">See the Pen <a href="https://codepen.io/ThibaultJanBeyer/pen/prpwYG/">prpwYG</a> on CodePen.</p>
|
|
158
|
-
|
|
159
|
-
## Within a scroll-able Area
|
|
160
|
-
|
|
161
|
-
Here the selection is constrained. You can only use the selection/drag inside of the area container:
|
|
162
|
-
|
|
163
|
-
```javascript
|
|
164
|
-
new DragSelect({
|
|
165
|
-
selectables: document.getElementsByClassName('selectable-nodes'),
|
|
166
|
-
area: document.getElementById('area')
|
|
167
|
-
});
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
<p data-height="350" data-theme-id="0" data-slug-hash="Nvobgq" data-default-tab="js,result" data-user="ThibaultJanBeyer" data-embed-version="2" data-pen-title="DragSelect with Scrollable AREA" class="codepen">See the Pen <a href="https://codepen.io/ThibaultJanBeyer/pen/Nvobgq/">DragSelect with Scrollable AREA</a> on CodePen.</p>
|
|
171
|
-
|
|
172
|
-
## With DropZones
|
|
173
|
-
|
|
174
|
-
Example of DropZones. DropZones are areas where you can drop the selected elements into.
|
|
175
|
-
|
|
176
|
-
```javascript
|
|
177
|
-
const ds = new DragSelect({
|
|
178
|
-
selectables: document.querySelectorAll('.selectable-nodes'),
|
|
179
|
-
area: document.querySelector('#area'),
|
|
180
|
-
dropZones: [
|
|
181
|
-
{ element: document.querySelector('#zone-1'), id: 'zone-1' }, // all selectables can be dropped into zone 1
|
|
182
|
-
{ element: document.querySelector('#zone-2'), id: 'zone-2', droppables: document.querySelectorAll('#item-2,#item-4') }, // only items 2 and 4 are droppable
|
|
183
|
-
],
|
|
184
|
-
dropInsideThreshold: 1, // 1 = has to be 100% inside the dropzone, 0.5 = 50% inside, 0 = just touching is fine
|
|
185
|
-
});
|
|
186
|
-
|
|
187
|
-
ds.subscribe('callback', ({
|
|
188
|
-
dropTarget: {
|
|
189
|
-
id: "zone-1",
|
|
190
|
-
element: <node />,
|
|
191
|
-
droppables: [ <node />, … ],
|
|
192
|
-
itemsDropped: [ <node />, … ], // elements that were selected on drop
|
|
193
|
-
itemsInside: [ <node />, … ] // elements that are inside the bounds of the dropzone
|
|
194
|
-
}) => {
|
|
195
|
-
if(dropTarget?.itemsDropped?.length) {
|
|
196
|
-
// do something
|
|
197
|
-
console.log('Dropped', dropTarget.itemsDropped, 'into', dropTarget.id);
|
|
198
|
-
}
|
|
199
|
-
})
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
This will also add some respective [classes](#classes)
|
|
203
|
-
|
|
204
|
-
<p data-height="350" data-theme-id="0" data-slug-hash="bGKgVxp" data-default-tab="js,result" data-user="ThibaultJanBeyer" data-embed-version="2" data-pen-title="DragSelect with DropZones" class="codepen">See the Pen <a href="https://codepen.io/ThibaultJanBeyer/pen/bGKgVxp">DragSelect with DropZones</a> on CodePen.</p>
|
|
205
|
-
|
|
206
|
-
## Extended
|
|
207
|
-
|
|
208
|
-
All options are optional. You could also just initiate the Dragselect by `new DragSelect({});` without any option.
|
|
209
|
-
Find all possible properties and methods in **[the docs](https://dragselect.com/DragSelect.html)**
|
|
210
|
-
|
|
211
|
-
```javascript
|
|
212
|
-
// if you add the function to a variable like this, you have access to all its functions
|
|
213
|
-
const ds = new DragSelect({
|
|
214
|
-
// all settings are optional and can be added later
|
|
215
|
-
});
|
|
216
|
-
|
|
217
|
-
// this is how you add/update settings after initialization
|
|
218
|
-
ds.setSettings({
|
|
219
|
-
// node/nodes that can be selected. By default will never add elements twice:
|
|
220
|
-
selectables: document.querySelectorAll('.selectable-nodes'),
|
|
221
|
-
// area in which you can drag. If not provided it will be the whole document & body/documentElement.
|
|
222
|
-
area: document.getElementById('area'),
|
|
223
|
-
// and many more, see "properties" section in the docs
|
|
224
|
-
})
|
|
225
|
-
|
|
226
|
-
// fired once the user releases the mouse. (items) = selected nodes:
|
|
227
|
-
ds.subscribe('callback', ({ items, event }) => {})
|
|
228
|
-
// returns all currently selected nodes:
|
|
229
|
-
ds.getSelection();
|
|
230
|
-
// Teardown/stop the whole functionality:
|
|
231
|
-
ds.stop();
|
|
232
|
-
// Reset the functionality after a teardown:
|
|
233
|
-
ds.start();
|
|
234
|
-
|
|
235
|
-
// and many more, see "methods" section in documentation
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
> You can also use the "shift", "ctrl" or "command" key to make multiple independent selections.
|
|
239
|
-
|
|
240
|
-
## Mobile/Touch usage
|
|
241
|
-
|
|
242
|
-
Keep in mind that using DragSelect on a mobile/touch device will also turn off the default scroll behavior (on `click` + `drag` interaction).
|
|
243
|
-
In 99% of the use-cases, this is what you want. If DragSelect is only one part of a website, and you still want to be able to scroll the page on mobile, you can use an `area` [property](#constructor-properties). This way the default scroll behavior remains intact for the rest of the page.
|
|
244
|
-
|
|
245
|
-
## Accessibility (a11y)
|
|
246
|
-
|
|
247
|
-
**DragSelect is accessible by default**:
|
|
248
|
-
|
|
249
|
-
> TLDR;
|
|
250
|
-
> => Your `selectables` should be buttons: `<button type="button"></button>`.
|
|
251
|
-
> => <kbd>ArrowKeys</kbd> are used for keyboard dragging.
|
|
252
|
-
|
|
253
|
-
Obviously, keyboard users won’t get the full visual experience but it works similarly to the OS default behavior.
|
|
254
|
-
|
|
255
|
-
1. Selection: You can select items using the default select keys (usually space or enter) and also multi-select when using a modifier key at the same time. There is one little thing you have to do tho’: the `selectables` have to be pressable (clickable)! To achieve this, they should be of type `<button type="button"></button>`.
|
|
256
|
-
|
|
257
|
-
2. Drag: You can drag elements using the keyboard arrow keys, this will also scroll the area by default. You can press <kbd>Shift</kbd> in combination with an arrow i.e. <kbd>Shift</kbd>+<kbd>ArrowRight</kbd> to move the element 4x faster to the right and also not scroll the area
|
|
258
|
-
|
|
259
|
-
<p data-height="350" data-theme-id="0" data-slug-hash="prpwYG" data-default-tab="html,result" data-user="ThibaultJanBeyer" data-embed-version="2" data-pen-title="DragSelect" class="codepen">See the Pen <a href="https://codepen.io/ThibaultJanBeyer/pen/prpwYG/">DragSelect</a> on CodePen.</p>
|
|
260
|
-
|
|
261
|
-
## Use your own Drag And Drop
|
|
262
|
-
|
|
263
|
-
### Using another plugin/tool (3rd party)
|
|
264
|
-
|
|
265
|
-
DragSelect comes with a build-in dragNdrop. Before, `.break` was used for this. But with v2, using your own is now very simple: listen to any DragSelect event to `.stop` it. Then, re-`.start` it after your custom dragNdrop was performed. Check for `isDragging`, which indicates when the users drags (moving the element) and `isDraggingKeyboard` for the keyboard drag events. I.e. use `predragstart`.
|
|
266
|
-
|
|
267
|
-
#### Example
|
|
268
|
-
|
|
269
|
-
```JavaScript
|
|
270
|
-
const ds = new DragSelect({
|
|
271
|
-
keyboardDragSpeed: 0,
|
|
272
|
-
// keyboardDrag: false, // if your library can not handle keyboard dragging
|
|
273
|
-
/* …other settings… */
|
|
274
|
-
})
|
|
275
|
-
const myCustomDrag = new MyCustomDrag({/* …your settings… */})
|
|
276
|
-
|
|
277
|
-
ds.subscribe('predragstart', ({ isDragging, isDraggingKeyboard }) =>
|
|
278
|
-
isDragging && ds.stop(false, false))
|
|
279
|
-
myCustomDrag.subscribe('finished', () => ds.start())
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
Disabling then re-enabling directly can also work (i.e. when your library has no callback):
|
|
283
|
-
|
|
284
|
-
```JavaScript
|
|
285
|
-
ds.subscribe('predragstart', ({ isDragging, isDraggingKeyboard }) => {
|
|
286
|
-
if(isDragging) {
|
|
287
|
-
ds.stop(false, false)
|
|
288
|
-
setTimeout(ds.start)
|
|
289
|
-
}
|
|
290
|
-
})
|
|
291
|
-
```
|
|
292
|
-
|
|
293
|
-
Note: it is important to debounce (i.e. with `setTimeout(ds.start)`) the start function if it's called within a single subscriber so that all the scheduled callbacks finish triggering before we start again.
|
|
294
|
-
|
|
295
|
-
### Writing a fully custom solution
|
|
296
|
-
|
|
297
|
-
In case you want to build something completely custom on top of DragSelect, we got you covered! You can use `.break` for this. You heard right, break is back baby :)
|
|
298
|
-
|
|
299
|
-
This utility to override DragSelects internal functionality allows you to write it all yourself: You can write your own drag and drop but you can also write your own selection:
|
|
300
|
-
|
|
301
|
-
#### Example
|
|
302
|
-
|
|
303
|
-
> /!\ only use break when you know what you're doing. Support is limited /!\
|
|
304
|
-
|
|
305
|
-
```JavaScript
|
|
306
|
-
ds.subscribe('predragmove', ({ isDragging, isDraggingKeyboard }) => {
|
|
307
|
-
if(isDragging || isDraggingKeyboard) {
|
|
308
|
-
ds.break()
|
|
309
|
-
/* your custom logic for drag handling here. */
|
|
310
|
-
} else {
|
|
311
|
-
ds.break()
|
|
312
|
-
/* your custom logic for selection handling here. */
|
|
313
|
-
}
|
|
314
|
-
}
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
# Constructor Properties (Settings)
|
|
318
|
-
|
|
319
|
-
*DragSelect is hyper customizable*. Note, all properties are optional. See **[the docs](https://dragselect.com/DragSelect.html)** for more info.
|
|
320
|
-
|
|
321
|
-
Moreover any setting can also be updated or added after the initialization, see [post-initialization setting updates](#post-initialization-setting-updates).
|
|
322
|
-
|
|
323
|
-
Here is the full list:
|
|
324
|
-
|
|
325
|
-
| property | type | usage | default |
|
|
326
|
-
|--- |--- |--- |--- |
|
|
327
|
-
|area |single DOM element (node) |The square in which you are able to select |`document`
|
|
328
|
-
|selectables |DOM elements [nodes] |The elements that can be selected |`[]`
|
|
329
|
-
|autoScrollSpeed |number |The speed in which the area scrolls while selecting (if available). The unit is arbitrary (interval aims for 30fps). Set to `0.0001` to disable auto-scrolling. |`5`
|
|
330
|
-
|overflowTolerance |{ x:number, y:number } |Tolerance for autoScroll (how close one has to be near an edges for autoScroll to start) |`{x:25,y:25}`
|
|
331
|
-
|zoom |number |Zoom scale factor (in case of using CSS style transform: scale() which messes with real positions). Unit scale zoom. |`1`
|
|
332
|
-
|customStyles |boolean |If true, no styles will be automatically applied to the selector element (except position: absolute). |`false`
|
|
333
|
-
|multiSelectMode |boolean |Add newly selected elements to the selection instead of replacing them. |`false`
|
|
334
|
-
|multiSelectToggling |boolean |Whether or not to toggle already active elements while multi-selecting. |`true` (MacOS selection behavior)
|
|
335
|
-
|multiSelectKeys |array |Keys that allows switching to the multi-select mode (see the multiSelectMode option). Any key value is possible ([see MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)). Note that the best support is given for <kbd>Control</kbd>, <kbd>Shift</kbd> and <kbd>Meta</kbd>. Provide an empty array `[]` if you want to turn off the functionality. |`['Control', 'Shift', 'Meta']`
|
|
336
|
-
|selector |single DOM element (node) |The square that will be used to draw the selection. | Auto-created HTML Element
|
|
337
|
-
|selectionThreshold |number |How much % of the element has to be selected to be considered selected (0 = just touching, 1 = fully inside the selection) |`0`
|
|
338
|
-
|draggability |boolean |When a user is dragging on an already selected element, the selection is dragged. |`true`
|
|
339
|
-
|immediateDrag |boolean |Whether a selectable element is draggable before being selected or needs to be selected first |`true`
|
|
340
|
-
|keyboardDrag |boolean |Whether or not the user can drag with the keyboard (Accessibility). |`true`
|
|
341
|
-
|dragKeys |{ up:string[], down:string[], left:string[], righ:string[] } |The keys available to drag element using the keyboard. Any key value is possible ([see MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key)). |`{ up:['ArrowUp'], down: ['ArrowDown'], left: ['ArrowLeft'], righ: ['ArrowRight'] }`
|
|
342
|
-
|keyboardDragSpeed |number |The speed at which elements are dragged using the keyboard. In pixels per keyDown. |`10`
|
|
343
|
-
|useTransform |boolean |Whether to use the more performant hardware accelerated css transforms when dragging instead of the top/left positions. |`true`
|
|
344
|
-
|refreshMemoryRate |number |Refresh rate on memoization, higher numbers mean better performance but more lag if elements are moving, lower numbers mean less lag but worse performance. If none of your DOMNodes are moving, you can set it to a very high number to increase performance. Value in milliseconds. |`80`
|
|
345
|
-
|dropZones |[{ id: 'string', element: single DOM element (node), droppables?: DOM elements [nodes] }] |zones with association of droppable items that can be dropped into them. `id`: any unique identifying string. `element`: is the dropzone itself. `droppables`: the elements that can be dropped into that zone. This is optional, by default it is all selectables |`[]`
|
|
346
|
-
|dropInsideThreshold |number |How much % of the item has to be inside the dropzone to be considered inside (0 = barely touching, 1 = completely inside) |`1`
|
|
347
|
-
|dropTargetThreshold |number |How much % of the zone does the pointer has to be in to be considered a target (0 = anywhere in the zone, max: 0.5 = has to point at the center of the zone) |`0`
|
|
348
|
-
|usePointerEvents |boolean |Whether to use Pointer Events to replace traditional Mouse or Touch Events. Useful for tools like Google Blockly. |`false`
|
|
349
|
-
|selectedClass |string |The class name assigned to the selected items. |[see classes](#classes)
|
|
350
|
-
|hoverClass |string |The class name assigned to the mouse hovered items. |[see classes](#classes)
|
|
351
|
-
|selectorClass |string |The class name assigned to the square selector helper. |[see classes](#classes)
|
|
352
|
-
|selectableClass |string |The class name assigned to the elements that can be selected. |[see classes](#classes)
|
|
353
|
-
|selectorClass |string |The class assigned to the square selector helper |ds-selector
|
|
354
|
-
|selectorAreaClass |string |The class assigned to the square in which the selector resides. By default it's invisible |ds-selector-area
|
|
355
|
-
|droppedTargetClass |string |On an item corresponding the target dropzone. This is also the prefix for ds-dropped-target-${zone.id}. |ds-dropped-target & ds-dropped-target-${zone.id}
|
|
356
|
-
|droppedInsideClass |string |On an item that is within its dropzone bounds after a drop. This is also the prefix for ds-dropped-inside-${zone.id} |ds-dropped-inside & ds-dropped-inside-${zone.id}
|
|
357
|
-
|droppableClass |string |On element that can be dropped into at least one container. This is also the prefix for ds-droppable-${zone.id} |ds-droppable & ds-droppable-${zone.id}
|
|
358
|
-
|dropZoneClass |string |On each dropZone |ds-dropzone
|
|
359
|
-
|dropZoneReadyClass |string |On corresponding dropZone when element is dragged |ds-dropzone-ready
|
|
360
|
-
|dropZoneTargetClass |string |On dropZone that has elements from any successful target drop |ds-dropzone-target
|
|
361
|
-
|dropZoneInsideClass |string |On dropZone that has elements inside after any drop |ds-dropzone-inside
|
|
362
|
-
|
|
363
|
-
## Post-Initialization Setting-Updates
|
|
364
|
-
|
|
365
|
-
Any setting can be updated/added after initialization by using the `setSettings` method. Here is an example updating the `area` and the `selectables`:
|
|
366
|
-
|
|
367
|
-
```JavaScript
|
|
368
|
-
const ds = new DragSelect({})
|
|
369
|
-
ds.setSettings({
|
|
370
|
-
selectables: document.getElementsByClassName('selectable-nodes'),
|
|
371
|
-
area: document.getElementById('area')
|
|
372
|
-
})
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
# Event Callbacks
|
|
376
|
-
|
|
377
|
-
Event Callbacks are used like this:
|
|
378
|
-
|
|
379
|
-
```JavaScript
|
|
380
|
-
ds.subscribe('<event_name>', (callback_object) => {})
|
|
381
|
-
```
|
|
382
|
-
|
|
383
|
-
## Events
|
|
384
|
-
|
|
385
|
-
|event_name |callback_object |description |
|
|
386
|
-
|--- |--- |---
|
|
387
|
-
|callback |`{ items, event, isDragging, … }` |Fired after the selection (i.e. on mouse-up).
|
|
388
|
-
|dragstart |`{ items, event, isDragging, isDraggingKeyboard, … }` |Fired when the selection starts (i.e. on mouse-down).
|
|
389
|
-
|dragmove |`{ items, event, isDragging, isDraggingKeyboard, … }` |Fired when the mouse moves while dragging (i.e. on mouse-move).
|
|
390
|
-
|autoscroll |`{ items, isDragging, scroll_directions, scroll_multiplier, … }` |Fired when the area is auto-scrolled (i.e. cursor on a corner of the area).
|
|
391
|
-
|elementselect |`{ items, item, … }` |Fired when an element is added to the selection.
|
|
392
|
-
|elementunselect |`{ items, item, … }` |Fired when an element is removed from the selection.
|
|
393
|
-
|
|
394
|
-
> Note: all your callbacks subscribers will run happen after the internal code ran. If you want to run something before everything else, use the `pre` prefix. I.e. `predragstart` is an event that runs before any internal start logic.
|
|
395
|
-
|
|
396
|
-
### Callback Object Keys
|
|
397
|
-
|
|
398
|
-
|callback_object_keys |type |description |
|
|
399
|
-
|--- |--- |---
|
|
400
|
-
|event |`MouseEvent\|TouchEvent\|KeyboardEvent` |The native HTML Event, depending on the situational context
|
|
401
|
-
|items |`Array.<HTMLElement\|SVGElement\|*>` |Current selected elements
|
|
402
|
-
|isDragging |`boolean` |If true, the user is dragging the selected elements, if false the user is drawing a selection
|
|
403
|
-
|isDraggingKeyboard |`boolean` |If true, the user is dragging the selected elements with the keyboard
|
|
404
|
-
|scroll_directions |`Array.<'top'\|'bottom'\|'left'\|'right'\|undefined>` |The direction in which the event is happening (i.e. scroll direction)
|
|
405
|
-
|scroll_multiplier |`number` |Speed
|
|
406
|
-
|item |`HTMLElement\|SVGElement\|*` |The single element currently being interacted with if any
|
|
407
|
-
|dropTarget |`{ id: 'id', element: node, droppables: [node], itemsDropped: [node], itemsInside: [node] }` |dropZone in which the droppable elements were dropped into. `itemsDropped`: all items that were dropped on the target. `itemsInside`: all items that are within the bounds of the zone |
|
|
408
|
-
|
|
409
|
-
> Note: all object keys are optional and might not be available, depending on the event type. So make sure to check for availability first
|
|
410
|
-
|
|
411
|
-
# Methods
|
|
412
|
-
When the function is saved into a variable `var foo = new DragSelect()` you have access to all its inner functions.
|
|
413
|
-
Also check **[the docs](https://dragselect.com/DragSelect.html)** for more info.
|
|
414
|
-
|
|
415
|
-
| method | properties | usage |
|
|
416
|
-
|--- |--- |--- |
|
|
417
|
-
|stop |/ |Will teardown/stop the whole functionality
|
|
418
|
-
|start |/ |Reset the functionality after a teardown
|
|
419
|
-
|break |/ |Utility to override DragSelect internal functionality. Breaks out of current flow. Read [docs](#writing-a-fully-custom-solution) for more info.
|
|
420
|
-
|setSettings |`settings:Settings` |Update any setting dynamically, see [Settings](#constructor-properties-settings)
|
|
421
|
-
|getSelection |/ |Returns all currently selected nodes
|
|
422
|
-
|addSelection |`elements:DOM Elements, triggerCallback:boolean, dontAddToSelectables:boolean` |adds one or multiple elements to the selection. If boolean is set to true: callback will be called afterwards. Adds them to the selectables if they're not yet in the set (can be turned off by setting the last boolean to true)
|
|
423
|
-
|removeSelection |`elements:DOM Elements, triggerCallback:boolean, removeFromSelectables:boolean`|removes one or multiple elements to the selection. If boolean is set to true: callback will be called afterwards. If last boolean is set to true, it also removes them from the possible selectable nodes if they were.
|
|
424
|
-
|toggleSelection |`elements:DOM Elements, triggerCallback:boolean, alsoSelectables:boolean` |toggles one or multiple elements to the selection. If element is not in selection it will be added, if it is already selected, it will be removed. If boolean is set to true: callback will be called afterward. If last boolean is set to true, it also removes selected elements from possible selectable nodes & doesn’t add them to selectables if they are not (can be turned off by setting the last boolean to true).
|
|
425
|
-
|setSelection |`elements:DOM Elements, triggerCallback:boolean, dontAddToSelectables:boolean` |sets the selection to one or multiple elements. If boolean is set to true: callback will be called afterwards. Adds them to the selectables if they're not yet in the set (can be turned off by setting the last boolean to true)
|
|
426
|
-
|clearSelection |DOM elements [nodes], Boolean (callback) |remove all elements from the selection. If boolean is set to true: callback will be called afterwards. |
|
|
427
|
-
|clearSelection |`triggerCallback:boolean` |Unselect / Deselect all current selected Nodes |
|
|
428
|
-
|addSelectables |`elements:DOM Elements, addToSelection:boolean` |Adds elements that can be selected. Don’t worry, nodes are never added twice. If boolean is set to true: elements will also be added to current selection.
|
|
429
|
-
|removeSelectables |`elements:DOM Elements, removeFromSelection:boolean` |Remove elements from the set of elements that can be selected. If boolean is set to true: elements will also be removed from current selection.
|
|
430
|
-
|getSelectables |/ |Returns array with all nodes that can be selected.
|
|
431
|
-
|getInitialCursorPosition |/ |Returns the registered x, y coordinates the cursor had when first clicked
|
|
432
|
-
|getCurrentCursorPosition |/ |Returns current x, y coordinates of the cursor
|
|
433
|
-
|getPreviousCursorPosition |/ |Returns last registered x, y coordinates of the cursor (after last callback)
|
|
434
|
-
|getInitialCursorPositionArea |/ |Returns the registered x, y coordinates relative to the area the cursor had when first clicked
|
|
435
|
-
|getCurrentCursorPositionArea |/ |Returns current x, y coordinates of the cursor relative to the area
|
|
436
|
-
|getPreviousCursorPositionArea |/ |Returns last registered x, y coordinates of the cursor relative to the area (after last callback)
|
|
437
|
-
|isMultiSelect |`event:KeyboardEvent|MouseEvent|TouchEvent` (optional) |Whether the multi-select key is currently pressed
|
|
438
|
-
|isDragging |/ |Whether the user is currently drag n dropping elements (instead of selection)
|
|
439
|
-
|getZoneByCoordinates |Optional `{x: number, y: number}` |Returns the first drop target under the current mouse position, or, if provided at coordinates x/y
|
|
440
|
-
|getItemsDroppedByZoneId |`zoneId: string` |Returns the items dropped into a specific zone (by zone.id)
|
|
441
|
-
|getItemsInsideByZoneId |`zoneId: string`,`addClasses: boolean` |Returns the items that are visually inside a specific zone (by zone.id)
|
|
442
|
-
|
|
443
|
-
# Classes
|
|
444
|
-
| name | trigger |
|
|
445
|
-
|--- |--- |
|
|
446
|
-
|.ds-selected |On items that are selected
|
|
447
|
-
|.ds-hover |On items that are currently hovered
|
|
448
|
-
|.ds-selector |On the selector element
|
|
449
|
-
|.ds-selector-area |The overlay where the selector resides in
|
|
450
|
-
|.ds-selectable |On items that can be selected
|
|
451
|
-
|.ds-droppable |on item that can be dropped into at least one zone |
|
|
452
|
-
|.ds-droppable-${id} |on item that can be dropped into a zone with specific identifier, `${id}` will be replaced by the corresponding zone.id|
|
|
453
|
-
|.ds-dropped-target |on an item corresponding the target dropzone |
|
|
454
|
-
|.ds-dropped-target-${id} |on an item corresponding the target dropzone with specific identifier, `${id}` will be replaced by the corresponding zone.id |
|
|
455
|
-
|.ds-dropped-inside |on an item that is within its dropzone bounds after a drop |
|
|
456
|
-
|.ds-dropped-inside-${id} |on an item that is within its dropzone bounds after a drop with specific identifier, `${id}` will be replaced by the corresponding zone.id |
|
|
457
|
-
|.ds-dropzone |on each dropZone |
|
|
458
|
-
|.ds-dropzone-ready |on corresponding dropZone when corresponding item is being dragged |
|
|
459
|
-
|.ds-dropzone-target |on dropZone when it was target of a successful drop |
|
|
460
|
-
|.ds-dropzone-inside |on dropZone that has elements inside after any drop |
|
|
461
|
-
|
|
462
|
-
*note: you can change the class names setting the respective property on the constructor, see **[the docs](https://dragselect.com/DragSelect.html)** properties section.*
|
|
463
|
-
|
|
464
|
-
# Have Fun!
|
|
465
|
-
|
|
466
|
-
Creating and maintaining useful tools is a lot of work.
|
|
467
|
-
So don’t forget to give this repository a star if you find it useful.
|
|
468
|
-
Star this repo, tell all your friends and start contributing and/or [donating 1$](https://github.com/sponsors/ThibaultJanBeyer) to keep it running. Thank you :)
|
|
469
|
-
|
|
470
|
-
[](https://thibaultjanbeyer.com/)
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
|
|
474
|
-
<br>
|
|
475
|
-
<br>
|
|
476
|
-
<br>
|
|
477
|
-
|
|
478
|
-
[documentation](https://dragselect.com/DragSelect.html)
|
package/deploying.md
DELETED
|
@@ -1,36 +0,0 @@
|
|
|
1
|
-
# Don‘t do this if you are not project owner!
|
|
2
|
-
|
|
3
|
-
This information is just for reference for the project owner,
|
|
4
|
-
if you are a regular contributor, see [contibuting](CONTRIBUTING.md) and make a pull request instead.
|
|
5
|
-
|
|
6
|
-
-
|
|
7
|
-
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
|
|
12
|
-
## Deploying
|
|
13
|
-
|
|
14
|
-
Typically you don’t have to do this, since you most likely are not the project owner.
|
|
15
|
-
But if you are the project owner:
|
|
16
|
-
|
|
17
|
-
- Github Actions will take care of deployment to gh-pages when you push/merge to github main branch (gh-pages will be build by Github Actions)
|
|
18
|
-
|
|
19
|
-
If this was successful, the next step is to publish the new version on `npm`:
|
|
20
|
-
|
|
21
|
-
```
|
|
22
|
-
npm version patch
|
|
23
|
-
npm run rollup
|
|
24
|
-
```
|
|
25
|
-
Rollup is necessary for npm packages (since `dist` will be deployed to npm but is ignored in repo)
|
|
26
|
-
|
|
27
|
-
versions are either `patch` wich changes 0.0.x, `minor` wich changes 0.x.0 or `major` for x.0.0.
|
|
28
|
-
See [npm docs](https://docs.npmjs.com/getting-started/publishing-npm-packages)
|
|
29
|
-
|
|
30
|
-
Check if the `changelog` reflects the latest version
|
|
31
|
-
|
|
32
|
-
After that push again, just to make sure and then publish
|
|
33
|
-
|
|
34
|
-
```
|
|
35
|
-
npm publish
|
|
36
|
-
```
|