dragselect 2.4.4 → 2.5.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.
Files changed (40) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +84 -21
  3. package/dist/DragSelect.d.ts +26 -4
  4. package/dist/DragSelect.es6m.js +835 -781
  5. package/dist/DragSelect.js +835 -781
  6. package/dist/ds.es6m.min.js +1 -1
  7. package/dist/ds.min.js +1 -1
  8. package/dist/methods/addModificationObservers.d.ts +9 -1
  9. package/dist/methods/getAllParentNodes.d.ts +0 -43
  10. package/dist/methods/index.d.ts +1 -0
  11. package/dist/methods/isCollision.d.ts +1 -1
  12. package/dist/methods/subscriberAliases.d.ts +3 -1
  13. package/dist/modules/Area.d.ts +2 -12
  14. package/dist/modules/DropZone.d.ts +0 -43
  15. package/dist/modules/DropZones.d.ts +0 -43
  16. package/dist/modules/SelectableSet.d.ts +11 -0
  17. package/dist/modules/Selection.d.ts +1 -0
  18. package/dist/modules/index.d.ts +1 -0
  19. package/dist/types.d.ts +72 -2
  20. package/jest-puppeteer.config.js +1 -0
  21. package/package.json +5 -4
  22. package/src/DragSelect.js +29 -5
  23. package/src/methods/addModificationObservers.js +26 -5
  24. package/src/methods/canScroll.js +1 -1
  25. package/src/methods/getAllParentNodes.js +18 -0
  26. package/src/methods/handleElementPositionAttribute.js +1 -1
  27. package/src/methods/hydrateSettings.js +16 -0
  28. package/src/methods/index.js +1 -0
  29. package/src/methods/isCollision.js +24 -5
  30. package/src/methods/scrollElement.js +1 -1
  31. package/src/methods/subscriberAliases.js +16 -5
  32. package/src/methods/toArray.js +3 -2
  33. package/src/modules/Area.js +12 -44
  34. package/src/modules/DropZone.js +224 -0
  35. package/src/modules/DropZones.js +153 -0
  36. package/src/modules/SelectableSet.js +22 -0
  37. package/src/modules/Selection.js +9 -11
  38. package/src/modules/index.js +1 -0
  39. package/src/stores/SettingsStore.js +0 -1
  40. package/src/types.js +30 -2
package/CHANGELOG.md CHANGED
@@ -1,3 +1,9 @@
1
+ # 2.5.0
2
+
3
+ - Add dropZones! Solves #115
4
+ - Add a `selectionThreshold` settings, solves #130
5
+ - Add a `refreshMemoryRate` settings, to increase/decrease performance as necessary
6
+
1
7
  # 2.4.4
2
8
 
3
9
  - Add support for `pointerEvents` (from @HollowMan6) [#143](https://github.com/ThibaultJanBeyer/DragSelect/pull/143) & [#128](https://github.com/ThibaultJanBeyer/DragSelect/pull/128)
package/README.md CHANGED
@@ -30,6 +30,7 @@ easily add a selection algorithm to your application/website.
30
30
  - [Usage](#usage)
31
31
  - [Simple](#simple)
32
32
  - [Within a scroll-able Area](#within-a-scroll-able-area)
33
+ - [With DropZones](#with-dropzones)
33
34
  - [Extended](#extended)
34
35
  - [Mobile/Touch usage](#mobiletouch-usage)
35
36
  - [Accessibility (a11y)](#accessibility-a11y)
@@ -38,12 +39,12 @@ easily add a selection algorithm to your application/website.
38
39
  - [Example](#example)
39
40
  - [Writing a fully custom solution](#writing-a-fully-custom-solution)
40
41
  - [Example](#example-1)
41
- - [Constructor Properties (Settings):](#constructor-properties-settings)
42
+ - [Constructor Properties (Settings)](#constructor-properties-settings)
42
43
  - [Post-Initialization Setting-Updates](#post-initialization-setting-updates)
43
44
  - [Event Callbacks](#event-callbacks)
44
45
  - [Events](#events)
45
46
  - [Callback Object Keys](#callback-object-keys)
46
- - [Methods:](#methods)
47
+ - [Methods](#methods)
47
48
  - [Classes](#classes)
48
49
  - [Have Fun!](#have-fun)
49
50
 
@@ -160,6 +161,40 @@ new DragSelect({
160
161
 
161
162
  <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>
162
163
 
164
+ ## With DropZones
165
+
166
+ Example of DropZones. DropZones are areas where you can drop the selected elements into.
167
+
168
+ ```javascript
169
+ const ds = new DragSelect({
170
+ selectables: document.querySelectorAll('.selectable-nodes'),
171
+ area: document.querySelector('#area'),
172
+ dropZones: [
173
+ { element: document.querySelector('#zone-1'), id: 'zone-1', droppables: document.querySelectorAll('.selectable-nodes') },
174
+ { element: document.querySelector('#zone-2'), id: 'zone-2', droppables: document.querySelectorAll('#item-2,#item-4') },
175
+ ],
176
+ dropInsideThreshold: 1, // 1 = has to be 100% inside the dropzone, 0.5 = 50% inside, 0 = just touching is fine
177
+ });
178
+
179
+ ds.subscribe('callback', ({
180
+ dropTarget: {
181
+ id: "zone-1",
182
+ element: <node />,
183
+ droppables: [ <node />, … ],
184
+ itemsDropped: [ <node />, … ], // elements that were selected on drop
185
+ itemsInside: [ <node />, … ] // elements that are inside the bounds of the dropzone
186
+ }) => {
187
+ if(dropTarget?.itemsDropped?.length) {
188
+ // do something
189
+ console.log('Dropped', dropTarget.itemsDropped, 'into', dropTarget.id);
190
+ }
191
+ })
192
+ ```
193
+
194
+ This will also add some respective [classes](#classes)
195
+
196
+ <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>
197
+
163
198
  ## Extended
164
199
 
165
200
  All options are optional. You could also just initiate the Dragselect by `new DragSelect({});` without any option.
@@ -271,7 +306,7 @@ ds.subscribe('predragmove', ({ isDragging, isDraggingKeyboard }) => {
271
306
  }
272
307
  ```
273
308
 
274
- # Constructor Properties (Settings):
309
+ # Constructor Properties (Settings)
275
310
 
276
311
  *DragSelect is hyper customizable*. Note, all properties are optional. See **[the docs](https://dragselect.com/DragSelect.html)** for more info.
277
312
 
@@ -281,8 +316,8 @@ Here is the full list:
281
316
 
282
317
  | property | type | usage | default |
283
318
  |--- |--- |--- |--- |
284
- |area |single DOM element (node) |The square in which you are able to select |document
285
- |selectables |DOM elements (nodes) |The elements that can be selected | []
319
+ |area |single DOM element (node) |The square in which you are able to select |`document`
320
+ |selectables |DOM elements [nodes] |The elements that can be selected |`[]`
286
321
  |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`
287
322
  |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}`
288
323
  |zoom |number |Zoom scale factor (in case of using CSS style transform: scale() which messes with real positions). Unit scale zoom. |`1`
@@ -291,17 +326,31 @@ Here is the full list:
291
326
  |multiSelectToggling |boolean |Whether or not to toggle already active elements while multi-selecting. |`true` (MacOS selection behavior)
292
327
  |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']`
293
328
  |selector |single DOM element (node) |The square that will be used to draw the selection. | Auto-created HTML Element
329
+ |selectionThreshold |number |How much % of the element has to be selected to be considered selected (0 = just touching, 1 = fully inside the selection) |`0`
294
330
  |draggability |boolean |When a user is dragging on an already selected element, the selection is dragged. |`true`
295
331
  |immediateDrag |boolean |Whether a selectable element is draggable before being selected or needs to be selected first |`true`
296
332
  |keyboardDrag |boolean |Whether or not the user can drag with the keyboard (Accessibility). |`true`
297
333
  |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'] }`
298
334
  |keyboardDragSpeed |number |The speed at which elements are dragged using the keyboard. In pixels per keyDown. |`10`
299
335
  |useTransform |boolean |Whether to use the more performant hardware accelerated css transforms when dragging instead of the top/left positions. |`true`
336
+ |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`
337
+ |dropZones |[{ id: 'string', element: single DOM element (node), droppables: DOM elements [nodes] }] |zones with association of droppable items that can be dropped into them |`[]`
338
+ |dropInsideThreshold |number |How much % of the item has to be inside the dropzone to be considered inside (0 = barely touching, 1 = completely inside) |`1`
339
+ |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`
340
+ |usePointerEvents |boolean |Whether to use Pointer Events to replace traditional Mouse or Touch Events. Useful for tools like Google Blockly. |`false`
300
341
  |selectedClass |string |The class name assigned to the selected items. |[see classes](#classes)
301
342
  |hoverClass |string |The class name assigned to the mouse hovered items. |[see classes](#classes)
302
343
  |selectorClass |string |The class name assigned to the square selector helper. |[see classes](#classes)
303
344
  |selectableClass |string |The class name assigned to the elements that can be selected. |[see classes](#classes)
304
- |usePointerEvents |boolean |Whether to use Pointer Events to replace traditional Mouse or Touch Events. Useful for tools like Google Blockly. |`false`
345
+ |selectorClass |string |The class assigned to the square selector helper |ds-selector
346
+ |selectorAreaClass |string |The class assigned to the square in which the selector resides. By default it's invisible |ds-selector-area
347
+ |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}
348
+ |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}
349
+ |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}
350
+ |dropZoneClass |string |On each dropZone |ds-dropzone
351
+ |dropZoneReadyClass |string |On corresponding dropZone when element is dragged |ds-dropzone-ready
352
+ |dropZoneTargetClass |string |On dropZone that has elements from any successful target drop |ds-dropzone-target
353
+ |dropZoneInsideClass |string |On dropZone that has elements inside after any drop |ds-dropzone-inside
305
354
 
306
355
  ## Post-Initialization Setting-Updates
307
356
 
@@ -347,10 +396,11 @@ ds.subscribe('<event_name>', (callback_object) => {})
347
396
  |scroll_directions |`Array.<'top'\|'bottom'\|'left'\|'right'\|undefined>` |The direction in which the event is happening (i.e. scroll direction)
348
397
  |scroll_multiplier |`number` |Speed
349
398
  |item |`HTMLElement\|SVGElement\|*` |The single element currently being interacted with if any
399
+ |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 |
350
400
 
351
401
  > Note: all object keys are optional and might not be available, depending on the event type. So make sure to check for availability first
352
402
 
353
- # Methods:
403
+ # Methods
354
404
  When the function is saved into a variable `var foo = new DragSelect()` you have access to all its inner functions.
355
405
  Also check **[the docs](https://dragselect.com/DragSelect.html)** for more info.
356
406
 
@@ -358,35 +408,48 @@ Also check **[the docs](https://dragselect.com/DragSelect.html)** for more info.
358
408
  |--- |--- |--- |
359
409
  |stop |/ |Will teardown/stop the whole functionality
360
410
  |start |/ |Reset the functionality after a teardown
411
+ |break |/ |Utility to override DragSelect internal functionality. Breaks out of current flow. Read [docs](#writing-a-fully-custom-solution) for more info.
412
+ |setSettings |`settings:Settings` |Update any setting dynamically, see [Settings](#constructor-properties-settings)
361
413
  |getSelection |/ |Returns all currently selected nodes
362
- |addSelection |DOM elements (nodes), Boolean (callback), Boolean (dontAddToSelectables) |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)
363
- |removeSelection |DOM elements (nodes), Boolean (callback), Boolean (removeFromSelectables) |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.
364
- |toggleSelection |DOM elements (nodes), Boolean (callback), Boolean (alsoSelectables) |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).
365
- |setSelection |DOM elements (nodes), Boolean (callback), Boolean (dontAddToSelectables) |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)
366
- |clearSelection |DOM elements (nodes), Boolean (callback) |remove all elements from the selection. If boolean is set to true: callback will be called afterwards. |
367
- |addSelectables |DOM elements (nodes), Boolean (addToSelection) |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.
368
- |removeSelectables |DOM elements (nodes), Boolean (removeFromSelection) |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.
414
+ |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)
415
+ |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.
416
+ |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).
417
+ |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)
418
+ |clearSelection |DOM elements [nodes], Boolean (callback) |remove all elements from the selection. If boolean is set to true: callback will be called afterwards. |
419
+ |clearSelection |`triggerCallback:boolean` |Unselect / Deselect all current selected Nodes |
420
+ |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.
421
+ |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.
369
422
  |getSelectables |/ |Returns array with all nodes that can be selected.
370
- |setSelectables |DOM elements (nodes), Boolean (removeFromSelection), Boolean (addToSelection) |Sets all elements that can be selected. Removes all current selectables (& their respective applied classes). Adds the new set to the selectables set. Thus, replacing the original set. First boolean if old elements should be removed from the selection. Second boolean if new elements should be added to the selection.
371
423
  |getInitialCursorPosition |/ |Returns the registered x, y coordinates the cursor had when first clicked
372
424
  |getCurrentCursorPosition |/ |Returns current x, y coordinates of the cursor
373
425
  |getPreviousCursorPosition |/ |Returns last registered x, y coordinates of the cursor (after last callback)
374
426
  |getInitialCursorPositionArea |/ |Returns the registered x, y coordinates relative to the area the cursor had when first clicked
375
427
  |getCurrentCursorPositionArea |/ |Returns current x, y coordinates of the cursor relative to the area
376
428
  |getPreviousCursorPositionArea |/ |Returns last registered x, y coordinates of the cursor relative to the area (after last callback)
377
- |getCursorPositionDifference |Boolean (usePreviousCursorDifference) |Returns object with the x, y difference between the initial and the last cursor position. If the argument is set to true, it will instead return the x, y difference to the previous coordinates |
378
- |isMultiSelect |\[event:KeyboardEvent|MouseEvent|TouchEvent\] (optional) |Whether the multi-select key is currently pressed
429
+ |isMultiSelect |`event:KeyboardEvent|MouseEvent|TouchEvent` (optional) |Whether the multi-select key is currently pressed
379
430
  |isDragging |/ |Whether the user is currently drag n dropping elements (instead of selection)
380
- |break |/ |Utility to override DragSelect internal functionality. Breaks out of current flow. Read [docs](#writing-a-fully-custom-solution) for more info.
431
+ |getZoneByCoordinates |Optional `{x: number, y: number}` |Returns the first drop target under the current mouse position, or, if provided at coordinates x/y
432
+ |getItemsDroppedByZoneId |`zoneId: string` |Returns the items dropped into a specific zone (by zone.id)
433
+ |getItemsInsideByZoneId |`zoneId: string`,`addClasses: boolean` |Returns the items that are visually inside a specific zone (by zone.id)
381
434
 
382
435
  # Classes
383
436
  | name | trigger |
384
437
  |--- |--- |
385
- |.ds-selected |On elements that are selected
386
- |.ds-hover |On elements that are currently hovered
438
+ |.ds-selected |On items that are selected
439
+ |.ds-hover |On items that are currently hovered
387
440
  |.ds-selector |On the selector element
388
441
  |.ds-selector-area |The overlay where the selector resides in
389
- |.ds-selectable |On elements that can be selected
442
+ |.ds-selectable |On items that can be selected
443
+ |.ds-droppable |on item that can be dropped into at least one zone |
444
+ |.ds-droppable-${id} |on item that can be dropped into a zone with specific identifier, `${id}` will be replaced by the corresponding zone.id|
445
+ |.ds-dropped-target |on an item corresponding the target dropzone |
446
+ |.ds-dropped-target-${id} |on an item corresponding the target dropzone with specific identifier, `${id}` will be replaced by the corresponding zone.id |
447
+ |.ds-dropped-inside |on an item that is within its dropzone bounds after a drop |
448
+ |.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 |
449
+ |.ds-dropzone |on each dropZone |
450
+ |.ds-dropzone-ready |on corresponding dropZone when corresponding item is being dragged |
451
+ |.ds-dropzone-target |on dropZone when it was target of a successful drop |
452
+ |.ds-dropzone-inside |on dropZone that has elements inside after any drop |
390
453
 
391
454
  *note: you can change the class names setting the respective property on the constructor, see **[the docs](https://dragselect.com/DragSelect.html)** properties section.*
392
455
 
@@ -28,6 +28,7 @@ declare class DragSelect {
28
28
  SelectedSet: SelectedSet;
29
29
  Selection: Selection;
30
30
  Drag: Drag;
31
+ DropZones: DropZones;
31
32
  Interaction: Interaction;
32
33
  /**
33
34
  * Initializes the functionality. Automatically triggered when created.
@@ -49,6 +50,12 @@ declare class DragSelect {
49
50
  * Useful utility to write your own functionality/move/dragNdrop based on DragSelect pointer positions.
50
51
  */
51
52
  break: () => boolean;
53
+ /**
54
+ * Update any setting dynamically
55
+ * @param {Settings} settings
56
+ * @return {void}
57
+ */
58
+ setSettings: (settings: Settings) => void;
52
59
  /**
53
60
  * Returns the current selected nodes
54
61
  * @return {DSElements}
@@ -152,11 +159,25 @@ declare class DragSelect {
152
159
  */
153
160
  isDragging: () => boolean;
154
161
  /**
155
- * Update any setting dynamically
156
- * @param {Settings} settings
157
- * @return {void}
162
+ * Returns first DropsZone under coordinates,
163
+ * if no coordinated provided current pointer coordinates are used
164
+ * @param {Vect2} [coordinates]
165
+ * @returns {DSDropZone | undefined}
158
166
  */
159
- setSettings: (settings: Settings) => void;
167
+ getZoneByCoordinates: (coordinates?: Vect2) => DSDropZone | undefined;
168
+ /**
169
+ * Returns itemsDropped into zone by zone id
170
+ * @param {string} zoneId
171
+ * @returns {DSElements|void}
172
+ */
173
+ getItemsDroppedByZoneId: (zoneId: string) => DSElements | void;
174
+ /**
175
+ * Returns itemsInside by zone id
176
+ * @param {string} zoneId
177
+ * @param {boolean} addClasses whether or not to add/remove the "inside" classes to the items
178
+ * @returns {DSElements|void}
179
+ */
180
+ getItemsInsideByZoneId: (zoneId: string, addClasses: boolean) => DSElements | void;
160
181
  }
161
182
  import { PubSub } from "./modules";
162
183
  import { SettingsStore } from "./stores";
@@ -170,5 +191,6 @@ import { SelectableSet } from "./modules";
170
191
  import { SelectedSet } from "./modules";
171
192
  import { Selection } from "./modules";
172
193
  import { Drag } from "./modules";
194
+ import { DropZones } from "./modules";
173
195
  import { Interaction } from "./modules";
174
196
  import "./types"