From 2d3ab5eb851a6dd733d079aecbb7549d4ac93dcb Mon Sep 17 00:00:00 2001 From: Max Hoffmann Date: Fri, 6 Oct 2017 10:05:57 -0400 Subject: [PATCH] Restructure of Draggable --- config.json | 5 +- src/{draggable.js => Draggable/Draggable.js} | 24 ++--- src/Draggable/README.md | 95 +++++++++++++++++++ src/Draggable/index.js | 3 + .../Draggable/tests/Draggable.test.js | 0 src/droppable.js | 2 +- src/index.js | 2 +- src/sortable.js | 2 +- src/swappable.js | 2 +- 9 files changed, 118 insertions(+), 17 deletions(-) rename src/{draggable.js => Draggable/Draggable.js} (96%) create mode 100644 src/Draggable/README.md create mode 100644 src/Draggable/index.js rename test/src/draggable.test.js => src/Draggable/tests/Draggable.test.js (100%) diff --git a/config.json b/config.json index 328f66a..41322af 100644 --- a/config.json +++ b/config.json @@ -1,5 +1,8 @@ { - "testMatch": ["/test/src/**/*.js"], + "testMatch": [ + "/test/src/**/*.test.js", + "/src/**/*.test.js" + ], "setupFiles": ["/test/setup.js"], "transform": {".*": "/node_modules/babel-jest"}, "moduleFileExtensions": ["js"], diff --git a/src/draggable.js b/src/Draggable/Draggable.js similarity index 96% rename from src/draggable.js rename to src/Draggable/Draggable.js index 13a67da..381aefa 100644 --- a/src/draggable.js +++ b/src/Draggable/Draggable.js @@ -1,20 +1,20 @@ -import {closest} from './utils'; +import {closest} from './../utils'; -import Accessibility from './core/accessibility'; -import Mirror from './core/mirror'; +import Accessibility from './../core/accessibility'; +import Mirror from './../core/mirror'; -import Collidable from './behaviour/collidable'; -import Snappable from './behaviour/snappable'; +import Collidable from './../behaviour/collidable'; +import Snappable from './../behaviour/snappable'; -import DragSensor from './sensors/drag-sensor'; -import MouseSensor from './sensors/mouse-sensor'; -import TouchSensor from './sensors/touch-sensor'; -import ForceTouchSensor from './sensors/force-touch-sensor'; +import DragSensor from './../sensors/drag-sensor'; +import MouseSensor from './../sensors/mouse-sensor'; +import TouchSensor from './../sensors/touch-sensor'; +import ForceTouchSensor from './../sensors/force-touch-sensor'; import { DraggableInitializedEvent, DraggableDestroyEvent, -} from './events/draggable-event'; +} from './../events/draggable-event'; import { DragStartEvent, @@ -25,14 +25,14 @@ import { DragOverEvent, DragStopEvent, DragPressureEvent, -} from './events/drag-event'; +} from './../events/drag-event'; import { MirrorCreatedEvent, MirrorAttachedEvent, MirrorMoveEvent, MirrorDestroyEvent, -} from './events/mirror-event'; +} from './../events/mirror-event'; const defaults = { draggable: '.draggable-source', diff --git a/src/Draggable/README.md b/src/Draggable/README.md new file mode 100644 index 0000000..9bc6b7a --- /dev/null +++ b/src/Draggable/README.md @@ -0,0 +1,95 @@ +## Draggable + +### API + +**`new Draggable(containers: Array[HTMLElement]|NodeList, options: Object): Draggable`** +To create a draggable instance you need to specify the containers that hold draggable items, e.g. +`[document.body]` would work too. The second argument is an options object, which is described +below. + +**`draggable.on(eventName: String, listener: Function): Draggable`** +Draggable is an event emitter, so you can register callbacks for events. Draggable +also supports method chaining. + +**`draggable.off(eventName: String, listener: Function): Draggable`** +You can unregister listeners by using `.off()`, make sure to provide the same callback. + +**`draggable.trigger(eventName: String, event: AbstractEvent): Draggable`** +You can trigger events through draggable. This is used to fire events internally or by +extensions of Draggable. + +**`draggable.destroy(): void`** +Detaches all sensors and listeners, and cleans up after itself. + +### Options + +**`draggable {String}`** +A css selector for draggable elements within the `containers` specified. By default it will +look for an element with `.draggable-source` class. Default: `.draggable-source` + +**`handle {String}`** +Specify a css selector for a handle element if you don't want to allow drag action +on the entire element. Default: `null` + +**`delay {Number}`** +If you want to delay a drag start you can specify delay in milliseconds. This can be useful +for draggable elements within scrollable containers. Default: `0` + +**`native {Boolean}`** +If enabled Draggable will use the browsers native drag events to detect drag behaviour. By default +it will use mouse events to detect drag behaviour. You can only customize the mirror element when +using mouse events, otherwise mirror will be `null` in events. Default: `false` + +**`plugins {Array[Plugin]}`** +Plugins add behaviour to Draggable by hooking into its life cycle, e.g. one of the default +plugins controls the mirror movement. Default: `[Mirror, Accessibility]` + +**`appendTo {String|HTMLElement|Function}`** +Draggable allows you to specify where the mirror should be appended to. You can specify a css +selector, a HTMLElement or a function that returns a HTMLElement + +**`classes {Object}`** +Draggable adds classes to elements to indicate state. These classes can be used to add styling +on elements in certain states. + +### Events + +| Name | Description | Cancelable | Cancelable action | +| --------------------- | ---------------------------------------------------------- | ----------- | -------------------- | +| `drag:start` | Gets fired when drag action begins | true | Prevents drag start | +| `drag:move` | Gets fired when moving a draggable around | false | - | +| `drag:over` | Gets fired when dragging over other draggable | false | - | +| `drag:over:container` | Gets fired when dragging over other draggable container | false | - | +| `drag:out` | Gets fired when dragging out of other draggable | false | - | +| `drag:out:container` | Gets fired when dragging out of other draggable container | false | - | +| `drag:stop` | Gets fired when draggable has been released | false | - | +| `drag:pressure` | Gets fired when using force touch on draggable element | false | - | +| `mirror:created` | Gets fired when draggable mirror gets created | false | - | +| `mirror:attached` | Gets fired when draggable mirror gets attached to DOM | false | - | +| `mirror:move` | Gets fired when draggable mirror moves | true | Stop mirror movement | + +### Classes + +| Name | Description | Default | +| -------------------- | -------------------------------------------------------------------- | ---------------------------------- | +| `body:dragging` | Class added on the document body while dragging | `draggable--is-dragging` | +| `container:dragging` | Class added on the container where the draggable was picked up from | `draggable-container--is-dragging` | +| `source:dragging` | Class added on the draggable element that has been picked up | `draggable-source--is-dragging` | +| `source:placed` | Class added on the draggable element on `drag:stop` | `draggable-source--placed` | +| `container:placed` | Class added on the draggable container element on `drag:stop` | `draggable-container--placed` | +| `draggable:over` | Class added on draggable element you are dragging over | `draggable--over` | +| `container:over` | Class added on draggable container element you are dragging over | `draggable-container--over` | +| `mirror` | Class added on the mirror element | `draggable-mirror` | + +### Example + +This sample code will make list items draggable: + +```js +import {Draggable} from '@shopify/draggable'; + +new Draggable(document.querySelectorAll('ul')) + .on('drag:start', () => console.log('drag:start')) + .on('drag:move', () => console.log('drag:move')) + .on('drag:stop', () => console.log('drag:stop')); +``` diff --git a/src/Draggable/index.js b/src/Draggable/index.js new file mode 100644 index 0000000..d71596b --- /dev/null +++ b/src/Draggable/index.js @@ -0,0 +1,3 @@ +import Draggable from './Draggable'; + +export default Draggable; diff --git a/test/src/draggable.test.js b/src/Draggable/tests/Draggable.test.js similarity index 100% rename from test/src/draggable.test.js rename to src/Draggable/tests/Draggable.test.js diff --git a/src/droppable.js b/src/droppable.js index 7ceb65f..454217b 100644 --- a/src/droppable.js +++ b/src/droppable.js @@ -1,4 +1,4 @@ -import Draggable from './draggable'; +import Draggable from './Draggable'; import {closest} from './utils'; import { diff --git a/src/index.js b/src/index.js index 29ef6cb..43944a5 100644 --- a/src/index.js +++ b/src/index.js @@ -1,4 +1,4 @@ -import Draggable from './draggable'; +import Draggable from './Draggable'; import Sortable from './sortable'; import Swappable from './swappable'; import Droppable from './droppable'; diff --git a/src/sortable.js b/src/sortable.js index 3b6446b..fd47a8a 100644 --- a/src/sortable.js +++ b/src/sortable.js @@ -1,4 +1,4 @@ -import Draggable from './draggable'; +import Draggable from './Draggable'; import { SortableStartEvent, diff --git a/src/swappable.js b/src/swappable.js index cbbc545..49c4f11 100644 --- a/src/swappable.js +++ b/src/swappable.js @@ -1,4 +1,4 @@ -import Draggable from './draggable'; +import Draggable from './Draggable'; import { SwappableStartEvent,