From 78f5ac0b4f402f28511d627a2de13eba81da71bb Mon Sep 17 00:00:00 2001 From: Max Hoffmann Date: Fri, 13 Oct 2017 14:37:06 -0400 Subject: [PATCH] Added more base documentation --- README.md | 416 ++---------------- src/Draggable/DragEvent/DragEvent.js | 158 ++++++- src/Draggable/DragEvent/README.md | 173 +++++++- .../DragEvent/tests/DragEvent.test.js | 2 +- src/Draggable/Draggable.js | 2 +- .../DraggableEvent/DraggableEvent.js | 24 + src/Draggable/DraggableEvent/README.md | 40 +- src/Draggable/MirrorEvent/MirrorEvent.js | 77 ++++ src/Draggable/MirrorEvent/README.md | 87 +++- .../Plugins/Accessibility/Accessibility.js | 35 ++ src/Draggable/Plugins/Accessibility/README.md | 2 + src/Draggable/Plugins/README.md | 5 + src/Draggable/README.md | 60 ++- .../Sensors/ForceTouchSensor/README.md | 4 +- src/Draggable/Sensors/README.md | 10 + src/Draggable/Sensors/SensorEvent/README.md | 80 +++- .../Sensors/SensorEvent/SensorEvent.js | 38 -- src/Droppable/Droppable.js | 6 +- .../DroppableEvent/DroppableEvent.js | 50 ++- src/Droppable/DroppableEvent/README.md | 50 ++- src/Droppable/README.md | 22 +- .../CollidableEvent/CollidableEvent.js | 36 ++ .../Collidable/CollidableEvent/README.md | 49 +++ src/Plugins/Collidable/README.md | 50 +++ src/Plugins/Snappable/README.md | 48 ++ src/Plugins/Snappable/Snappable.js | 1 + .../Snappable/SnappableEvent/README.md | 39 ++ .../SnappableEvent/SnappableEvent.js | 28 ++ src/Plugins/SwapAnimation/README.md | 12 +- src/Sortable/README.md | 20 +- src/Sortable/Sortable.js | 4 +- src/Sortable/SortableEvent/README.md | 114 ++++- src/Sortable/SortableEvent/SortableEvent.js | 130 +++++- src/Swappable/README.md | 20 +- src/Swappable/SwappableEvent/README.md | 77 +++- .../SwappableEvent/SwappableEvent.js | 58 +++ src/shared/AbstractEvent/AbstractEvent.js | 35 +- src/shared/AbstractEvent/README.md | 27 +- webpack.config.js | 1 + 39 files changed, 1616 insertions(+), 474 deletions(-) diff --git a/README.md b/README.md index 8da561ac..7d1faf21 100644 --- a/README.md +++ b/README.md @@ -31,34 +31,7 @@ interface, for more information read the documentation below. ## Table of Contents * [Install](#install) -* [Draggable](#draggable) - * [API](#api) - * [Options](#options) - * [Events](#events) - * [Classes](#classes) - * [Example](#example) -* [Sortable](#sortable) - * [API](#api-1) - * [Options](#options-1) - * [Events](#events-1) - * [Classes](#classes-1) - * [Example](#example-1) -* [Droppable](#droppable) - * [API](#api-2) - * [Options](#options-2) - * [Events](#events-2) - * [Classes](#classes-2) - * [Example](#example-2) -* [Swappable](#swappable) - * [API](#api-3) - * [Options](#options-3) - * [Events](#events-3) - * [Classes](#classes-3) - * [Example](#example-3) -* [Plugins](#plugins) - * [Collidable](#collidable) - * [Snappable](#snappable) -* [Known issues](#known-issues) +* [Documentation](#documentation) * [Contributing](#contributing) * [Roadmap](#roadmap) * [Copyright](#copyright) @@ -79,352 +52,51 @@ yarn add @shopify/draggable or via CDN +```html + + + + + + + + + + + + + + ``` - -``` - -## 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: `100` - -**`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: `[]` - -**`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')); -``` - -## Sortable - -Sortable allows you to reorder elements. It maintains the order internally and fires -three events on top of the draggable events: `sortable:start`, `sortable:sorted` and `sortable:stop`. - -### API - -**`new Sortable(containers: Array[HTMLElement]|NodeList, options: Object): Sortable`** -To create a sortable 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. - -**`sortable.on(eventName: String, listener: Function): Sortable`** -Sortable uses Draggables event emitter, so you can register callbacks for events. Sortable -also supports method chaining. - -**`sortable.off(eventName: String, listener: Function): Sortable`** -You can unregister listeners by using `.off()`, make sure to provide the same callback. - -**`sortable.trigger(eventName: String, event: AbstractEvent): Sortable`** -You can trigger events through sortable. This is used to fire events internally or by -extensions of Draggable. - -**`sortable.destroy(): void`** -Detaches all sensors and listeners, and cleans up after itself. - -### Options - -__Same as Draggable__ - -### Events - -| Name | Description | Cancelable | Cancelable action | -| --------------------- | ---------------------------------------------------------- | ----------- | -------------------- | -| `sortable:start` | Gets fired when drag action begins | true | Prevents drag start | -| `sortable:sorted` | Gets fired when the source gets sorted in the DOM | false | - | -| `sortable:stop` | Gets fired when dragging over other draggable | false | - | - -### Classes - -__Same as Draggable__ - -### Example - -This sample code will make list items sortable: - -```js -import {Sortable} from '@shopify/draggable'; - -new Sortable(document.querySelectorAll('ul')) - .on('sortable:start', () => console.log('sortable:start')) - .on('sortable:sorted', () => console.log('sortable:sorted')) - .on('sortable:stop', () => console.log('sortable:stop')); -``` - -## Droppable - -Droppable allows you to declare draggable and droppable elements via options. -Droppable fires two events on top of the draggable events: `droppable:over` and `droppable:out`. - -### API - -**`new Droppable(containers: Array[HTMLElement]|NodeList, options: Object): Droppable`** -To create a droppable 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. - -**`droppable.on(eventName: String, listener: Function): Droppable`** -Droppable uses Draggables event emitter, so you can register callbacks for events. Droppable -also supports method chaining. - -**`droppable.off(eventName: String, listener: Function): Droppable`** -You can unregister listeners by using `.off()`, make sure to provide the same callback. - -**`droppable.trigger(eventName: String, event: AbstractEvent): Droppable`** -You can trigger events through droppable. This is used to fire events internally or by -extensions of Draggable. - -**`droppable.destroy(): void`** -Detaches all sensors and listeners, and cleans up after itself. - -### Options - -**`droppable {String|Array[HTMLElement]|NodeList|Function}`** -A css selector string, an array of elements, a NodeList or a function returning elements for droppable -elements within the `containers` specified. - -### Events - -| Name | Description | Cancelable | Cancelable action | -| --------------------- | ---------------------------------------------------------- | ----------- | -------------------- | -| `droppable:over` | Gets fired when dragging over droppable element | true | Prevents drop | -| `droppable:out` | Gets fired when dragging out of a droppable element | true | Prevents release | - -### Classes - -| Name | Description | Default | -| -------------------- | -------------------------------------------------------------------- | ---------------------------------- | -| `droppable:active` | Class added on droppables when drag starts | `draggable-droppable--active` | -| `droppable:occupied` | Class added on droppable element, when it contains a draggable | `draggable-droppable--occupied` | - -### Example - -This sample code will make list items draggable and allows to drop them inside another element: - -```js -import {Droppable} from '@shopify/draggable'; - -const droppable = new Droppable(document.querySelectorAll('ul'), { - draggable: 'li', - droppable: '#dropzone', -}); - -droppable.on('droppable:over', () => console.log('droppable:over')) -droppable.on('droppable:out', () => console.log('droppable:out')); -``` - -## Swappable - -Swappable allows you to swap elements by dragging over them. No order will be maintained (unlike Sortable), -so any draggable element that gets dragged over will be swapped with the source element. - -### API - -**`new Swappable(containers: Array[HTMLElement]|NodeList, options: Object): Swappable`** -To create a swappable 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. - -**`swappable.on(eventName: String, listener: Function): Swappable`** -Swappable uses Draggables event emitter, so you can register callbacks for events. Swappable -also supports method chaining. - -**`swappable.off(eventName: String, listener: Function): Swappable`** -You can unregister listeners by using `.off()`, make sure to provide the same callback. - -**`swappable.trigger(eventName: String, event: AbstractEvent): Swappable`** -You can trigger events through swappable. This is used to fire events internally or by -extensions of Draggable. - -**`droppable.destroy(): void`** -Detaches all sensors and listeners, and cleans up after itself. - -### Options - -__Same as Draggable__ - -### Events - -| Name | Description | Cancelable | Cancelable action | -| --------------------- | ---------------------------------------------------------- | ----------- | -------------------- | -| `swappable:start` | Gets fired when starting to drag | true | Prevents drag | -| `swappable:swapped` | Gets fired before the source gets swapped | true | Prevents swap | -| `swappable:stop` | Gets fired when dragging out of a droppable element | false | - | - -### Classes - -__Same as Draggable__ - -### Example - -This sample code will make list items draggable and allows to drop them inside another element: - -```js -import {Swappable} from '@shopify/draggable'; - -const swappable = new Swappable(document.querySelectorAll('ul'), { - draggable: 'li', -}); - -swappable.on('swappable:start', () => console.log('swappable:start')) -swappable.on('swappable:swapped', () => console.log('swappable:swapped')); -swappable.on('swappable:stop', () => console.log('swappable:stop')); -``` - -## Plugins - -Draggables ships with two optional plugins: `Collidable` & `Snappable` - -### Collidable - -When you use the collidable plugin you can specify which elements you **can't** drag over -and it will freeze the mirror movement for you. These currently only work with `Sortable`, `Swappable` and `Droppable`. - -#### Options - -**`collidables {String|Array[HTMLElement]|NodeList|HTMLElement|Function}`** -A css selector string, an array of elements, a NodeList, a HTMLElement or a function returning elements for collidable -elements. - -#### Events - -| Name | Description | Cancelable | Cancelable action | -| --------------------- | ---------------------------------------------------------- | ----------- | -------------------- | -| `collidable:in` | Gets fired when dragging near a collidable element | false | - | -| `collidable:out` | Gets fired when dragging away from a collidable element | false | - | - -#### Example - -```js -import {Sortable, Collidable} from '@shopify/draggable'; - -const sortable = new Sortable(document.querySelectorAll('ul'), { - draggable: 'li', - collidables: '.other-list', - plugins: [Collidable] -}); - -sortable.on('collidable:in', () => console.log('collidable:in')); -sortable.on('collidable:out', () => console.log('collidable:out')); -``` - -### Snappable - -Snappable simulates a "snap" by hiding the mirror and removing the `'source:dragging'` class from the source. -It also sets the `'source:placed'` class for potential drop animations. - -#### Options - -_No options_ - -#### Events - -| Name | Description | Cancelable | Cancelable action | -| --------------------- | ---------------------------------------------------------- | ----------- | --------------------- | -| `snap:in` | Gets fired when just before snapping in | true | Prevents snapping | -| `snap:out` | Gets fired when snapping out | false | Prevents snapping out | - -#### Example - -```js -import {Sortable, Snappable} from '@shopify/draggable'; - -const sortable = new Sortable(document.querySelectorAll('ul'), { - draggable: 'li', - plugins: [Snappable] -}); - -sortable.on('snap:in', () => console.log('snap:in')); -sortable.on('snap:out', () => console.log('snap:out')); -``` - -## Known issues -- Touch events freeze sometimes while dragging -- Safari 11 uses force touch, but there are no visual guidelines on the website +## Documentation + +You can find the documentation for each module within their respective directories. + +- [Draggable](src/Draggable) + - [DragEvent](src/Draggable/DragEvent) + - [DraggableEvent](src/Draggable/DraggableEvent) + - [MirrorEvent](src/Draggable/MirrorEvent) + - [Plugins](src/Draggable/Plugins) + - [Accessibility](src/Draggable/Plugins/Accessibility) + - [Mirror](src/Draggable/Plugins/Mirror) + - [Sensors](src/Draggable/Sensors) + - [DragSensor](src/Draggable/Sensors/DragSensor) + - [ForceTouchSensor](src/Draggable/Sensors/ForceTouchSensor) + - [MouseSensor](src/Draggable/Sensors/MouseSensor) + - [Sensor](src/Draggable/Sensors/Sensor) + - [SensorEvent](src/Draggable/Sensors/SensorEvent) + - [TouchSensor](src/Draggable/Sensors/TouchSensor) +- [Droppable](src/Droppable) + - [DroppableEvent](src/Droppable/DroppableEvent) +- [Plugins](src/Plugins) + - [Collidable](src/Plugins/Collidable) + - [Snappable](src/Plugins/Snappable) + - [SwapAnimation](src/Plugins/SwapAnimation) +- [Sortable](src/Sortable) + - [SortableEvent](src/Sortable/SortableEvent) +- [Swappable](src/Swappable) + - [SwappableEvent](src/Swappable/SwappableEvent) ## Contributing diff --git a/src/Draggable/DragEvent/DragEvent.js b/src/Draggable/DragEvent/DragEvent.js index a7e7366e..22c23c9a 100644 --- a/src/Draggable/DragEvent/DragEvent.js +++ b/src/Draggable/DragEvent/DragEvent.js @@ -1,26 +1,70 @@ import AbstractEvent from 'shared/AbstractEvent'; +/** + * Base drag event + * @class DragEvent + * @module DragEvent + * @extends AbstractEvent + */ export class DragEvent extends AbstractEvent { + static type = 'drag'; + + /** + * Draggables source element + * @property source + * @type {HTMLElement} + * @readonly + */ get source() { return this.data.source; } + /** + * Draggables original source element + * @property originalSource + * @type {HTMLElement} + * @readonly + */ get originalSource() { return this.data.originalSource; } + /** + * Draggables mirror element + * @property mirror + * @type {HTMLElement} + * @readonly + */ get mirror() { return this.data.mirror; } + /** + * Draggables source container element + * @property sourceContainer + * @type {HTMLElement} + * @readonly + */ get sourceContainer() { return this.data.sourceContainer; } + /** + * Sensor event + * @property sensorEvent + * @type {SensorEvent} + * @readonly + */ get sensorEvent() { return this.data.sensorEvent; } + /** + * Original event that triggered sensor event + * @property originalEvent + * @type {Event} + * @readonly + */ get originalEvent() { if (this.sensorEvent) { return this.sensorEvent.originalEvent; @@ -29,67 +73,163 @@ export class DragEvent extends AbstractEvent { return null; } + /** + * Checks if mirror has been created + * @return {Boolean} + */ hasMirror() { return Boolean(this.mirror); } } +/** + * Drag start event + * @class DragStartEvent + * @module DragStartEvent + * @extends DragEvent + */ export class DragStartEvent extends DragEvent { static type = 'drag:start'; + static cancelable = true; } +/** + * Drag move event + * @class DragMoveEvent + * @module DragMoveEvent + * @extends DragEvent + */ export class DragMoveEvent extends DragEvent { static type = 'drag:move'; } -export class DragOutContainerEvent extends DragEvent { - static type = 'drag:out:container'; - +/** + * Drag over event + * @class DragOverEvent + * @module DragOverEvent + * @extends DragEvent + */ +export class DragOverEvent extends DragEvent { + static type = 'drag:over'; + static cancelable = true; + + /** + * Draggable container you are over + * @property overContainer + * @type {HTMLElement} + * @readonly + */ get overContainer() { return this.data.overContainer; } + + /** + * Draggable element you are over + * @property over + * @type {HTMLElement} + * @readonly + */ + get over() { + return this.data.over; + } } +/** + * Drag out event + * @class DragOutEvent + * @module DragOutEvent + * @extends DragEvent + */ export class DragOutEvent extends DragEvent { static type = 'drag:out'; + /** + * Draggable container you are over + * @property overContainer + * @type {HTMLElement} + * @readonly + */ get overContainer() { return this.data.overContainer; } + /** + * Draggable element you left + * @property over + * @type {HTMLElement} + * @readonly + */ get over() { return this.data.over; } } +/** + * Drag over container event + * @class DragOverContainerEvent + * @module DragOverContainerEvent + * @extends DragEvent + */ export class DragOverContainerEvent extends DragEvent { static type = 'drag:over:container'; + /** + * Draggable container you are over + * @property overContainer + * @type {HTMLElement} + * @readonly + */ get overContainer() { return this.data.overContainer; } } -export class DragOverEvent extends DragEvent { - static type = 'drag:over'; +/** + * Drag out container event + * @class DragOutContainerEvent + * @module DragOutContainerEvent + * @extends DragEvent + */ +export class DragOutContainerEvent extends DragEvent { + static type = 'drag:out:container'; + /** + * Draggable container you left + * @property overContainer + * @type {HTMLElement} + * @readonly + */ get overContainer() { return this.data.overContainer; } - - get over() { - return this.data.over; - } } +/** + * Drag pressure event + * @class DragPressureEvent + * @module DragPressureEvent + * @extends DragEvent + */ export class DragPressureEvent extends DragEvent { static type = 'drag:pressure'; + /** + * Pressure applied on draggable element + * @property pressure + * @type {Number} + * @readonly + */ get pressure() { return this.data.pressure; } } +/** + * Drag stop event + * @class DragStopEvent + * @module DragStopEvent + * @extends DragEvent + */ export class DragStopEvent extends DragEvent { static type = 'drag:stop'; } diff --git a/src/Draggable/DragEvent/README.md b/src/Draggable/DragEvent/README.md index a08c76a2..277582d8 100644 --- a/src/Draggable/DragEvent/README.md +++ b/src/Draggable/DragEvent/README.md @@ -1 +1,172 @@ -## Drag event +# Drag event + +## DragEvent + +The base event for all Drag events that `Draggable` emits. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DragEvent` | +| **Interface** | `DragEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag` | + +### API + +**`dragEvent.source: HTMLElement`** +Read-only property for the source element. This is a straight copy of the `originalSource` +element, which can be moved around in the DOM. + +**`dragEvent.originalSource: String`** +Read-only property for the original source element that was picked up. This element never +moves in the DOM and gets hidden on `drag:start`. + +**`dragEvent.mirror: String`** +Read-only property for the mirror element, which is also a copy of the `originalSource` element. +The mirror follows your mouse/touch movements. + +**`dragEvent.sourceContainer: String`** +Read-only property for the source elements container. This would be one of the containers that +was passed into Draggable. + +**`dragEvent.sensorEvent: SensorEvent`** +Read-only property for the original sensor event that triggered this event. + +**`dragEvent.originalEvent: SensorEvent`** +Read-only property for the original event that triggered the sensor event. + +**`dragEvent.hasMirror(): Boolean`** +Checks if a mirror has been created. The mirror does not get created for `DragSensor` or `KeyboardSensor` events + +## DragStartEvent + +`DragStartEvent` gets triggered by `Draggable` when drag interaction has started. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DragEvent` | +| **Interface** | `DragStartEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents drag start | +| **type** | `drag:start` | + +## DragMoveEvent + +`DragMoveEvent` gets triggered while moving the mouse after the `DragStartEvent` has triggered. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DragEvent` | +| **Interface** | `DragMoveEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag:move` | + +## DragOverEvent + +`DragOverEvent` gets triggered when hovering over another draggable element during a drag +interaction. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DragEvent` | +| **Interface** | `DragOverEvent` | +| **Cancelable** | true | +| **Cancel action** | Cancels default actions in `Sortable` and `Swappable` | +| **type** | `drag:over` | + +### API + +**`dragOverEvent.over: HTMLElement`** +Read-only property for the draggable element that you are hovering over. + +**`dragOverEvent.overContainer: HTMLElement`** +Read-only property for the draggable container element that you are hovering over. + +## DragOutEvent + +`DragOutEvent` gets triggered after a `DragOverEvent` and indicates that you are leaving +a draggable element. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DragEvent` | +| **Interface** | `DragOutEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag:out` | + +### API + +**`dragOutEvent.over: HTMLElement`** +Read-only property for the draggable element that you are leaving. + +**`dragOutEvent.overContainer: HTMLElement`** +Read-only property for the draggable container element that you are hovering over. + +## DragOverContainerEvent + +`DragOverContainerEvent` gets triggered when hovering over a container, other than the `sourceContainer` in `DragStartEvent`. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DragEvent` | +| **Interface** | `DragOverContainerEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag:over:container` | + +### API + +**`dragOverContainerEvent.overContainer: HTMLElement`** +Read-only property for the draggable container element that you are hovering over. + +## DragOutContainerEvent + +`DragOutContainerEvent` gets triggered after a `DragOverContainerEvent` and indicates that +you are leaving a draggable container element. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DragEvent` | +| **Interface** | `DragOutContainerEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag:out:container` | + +### API + +**`dragOutContainerEvent.overContainer: HTMLElement`** +Read-only property for the draggable container element that you are leaving. + +## DragPressureEvent + +`DragPressureEvent` gets triggered before and during drag interactions. This event +only fires when the `ForceTouchSensor` is included as a Sensor and a Force Touch trackpad +is used with Safari. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DragEvent` | +| **Interface** | `DragPressureEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag:pressure` | + +### API + +**`dragPressureEvent.pressure: HTMLElement`** +Read-only property for pressure applied on a draggable element. Value ranges from `0.0` (no pressure) to `1.0` (maximum pressure). + +## DragStopEvent + +`DragStopEvent` gets triggered after `DragStartEvent`, once drag interactions have completed. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DragEvent` | +| **Interface** | `DragStopEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag:stop` | diff --git a/src/Draggable/DragEvent/tests/DragEvent.test.js b/src/Draggable/DragEvent/tests/DragEvent.test.js index 4ccf66e9..d9723e13 100644 --- a/src/Draggable/DragEvent/tests/DragEvent.test.js +++ b/src/Draggable/DragEvent/tests/DragEvent.test.js @@ -21,7 +21,7 @@ describe('DragEvent', () => { test('should initialize with `type` of `event`', () => { const event = new DragEvent(); - expect(event.type).toBe('event'); + expect(event.type).toBe('drag'); }); test('should initialize with source', () => { diff --git a/src/Draggable/Draggable.js b/src/Draggable/Draggable.js index b62a288a..84385bf9 100644 --- a/src/Draggable/Draggable.js +++ b/src/Draggable/Draggable.js @@ -276,7 +276,7 @@ export default class Draggable { /** * Returns class name for class identifier * @param {String} name - Name of class identifier - * @return {String} + * @return {String|null} */ getClassNameFor(name) { return this.options.classes[name] || defaults.classes[name]; diff --git a/src/Draggable/DraggableEvent/DraggableEvent.js b/src/Draggable/DraggableEvent/DraggableEvent.js index 3b9a8b43..0e58a046 100644 --- a/src/Draggable/DraggableEvent/DraggableEvent.js +++ b/src/Draggable/DraggableEvent/DraggableEvent.js @@ -1,17 +1,41 @@ import AbstractEvent from 'shared/AbstractEvent'; +/** + * Base draggable event + * @class DraggableEvent + * @module DraggableEvent + * @extends AbstractEvent + */ export class DraggableEvent extends AbstractEvent { static type = 'draggable'; + /** + * Draggable instance + * @property draggable + * @type {Draggable} + * @readonly + */ get draggable() { return this.data.draggable; } } +/** + * Draggable initialized event + * @class DraggableInitializedEvent + * @module DraggableInitializedEvent + * @extends DraggableEvent + */ export class DraggableInitializedEvent extends DraggableEvent { static type = 'draggable:initialize'; } +/** + * Draggable destory event + * @class DraggableInitializedEvent + * @module DraggableDestroyEvent + * @extends DraggableDestroyEvent + */ export class DraggableDestroyEvent extends DraggableEvent { static type = 'draggable:destroy'; } diff --git a/src/Draggable/DraggableEvent/README.md b/src/Draggable/DraggableEvent/README.md index 03b50760..3cd3a3f5 100644 --- a/src/Draggable/DraggableEvent/README.md +++ b/src/Draggable/DraggableEvent/README.md @@ -1 +1,39 @@ -## Draggable event +## DraggableEvent + +The base draggable event for all Draggable events that `Draggable` emits. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Interface** | `DraggableEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `draggable` | + +### API + +**`draggableEvent.draggable: Draggable`** +Read-only property for the current draggable instance + +## DraggableInitializedEvent + +`DraggableInitializedEvent` gets triggered by `Draggable` when initialized. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DraggableEvent` | +| **Interface** | `DraggableInitializedEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `draggable:initialized` | + +## DraggableDestroyEvent + +`DraggableDestroyEvent` gets triggered by `Draggable` when destroyed. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DraggableEvent` | +| **Interface** | `DraggableDestroyEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `draggable:destroy` | diff --git a/src/Draggable/MirrorEvent/MirrorEvent.js b/src/Draggable/MirrorEvent/MirrorEvent.js index 7d168a67..efc313dd 100644 --- a/src/Draggable/MirrorEvent/MirrorEvent.js +++ b/src/Draggable/MirrorEvent/MirrorEvent.js @@ -1,26 +1,69 @@ import AbstractEvent from 'shared/AbstractEvent'; +/** + * Base mirror event + * @class MirrorEvent + * @module MirrorEvent + * @extends AbstractEvent + */ export class MirrorEvent extends AbstractEvent { + + /** + * Draggables source element + * @property source + * @type {HTMLElement} + * @readonly + */ get source() { return this.data.source; } + /** + * Draggables original source element + * @property originalSource + * @type {HTMLElement} + * @readonly + */ get originalSource() { return this.data.originalSource; } + /** + * Draggables mirror element + * @property mirror + * @type {HTMLElement} + * @readonly + */ get mirror() { return this.data.mirror; } + /** + * Draggables source container element + * @property sourceContainer + * @type {HTMLElement} + * @readonly + */ get sourceContainer() { return this.data.sourceContainer; } + /** + * Sensor event + * @property sensorEvent + * @type {SensorEvent} + * @readonly + */ get sensorEvent() { return this.data.sensorEvent; } + /** + * Original event that triggered sensor event + * @property originalEvent + * @type {Event} + * @readonly + */ get originalEvent() { if (this.sensorEvent) { return this.sensorEvent.originalEvent; @@ -28,20 +71,54 @@ export class MirrorEvent extends AbstractEvent { return null; } + + /** + * Checks if mirror has been created + * @return {Boolean} + */ + hasMirror() { + return Boolean(this.mirror); + } } +/** + * Mirror created event + * @class MirrorCreatedEvent + * @module MirrorCreatedEvent + * @extends MirrorEvent + */ export class MirrorCreatedEvent extends MirrorEvent { static type = 'mirror:created'; } +/** + * Mirror attached event + * @class MirrorAttachedEvent + * @module MirrorAttachedEvent + * @extends MirrorEvent + */ export class MirrorAttachedEvent extends MirrorEvent { static type = 'mirror:attached'; } +/** + * Mirror move event + * @class MirrorMoveEvent + * @module MirrorMoveEvent + * @extends MirrorEvent + */ export class MirrorMoveEvent extends MirrorEvent { static type = 'mirror:move'; + static cancelable = true; } +/** + * Mirror destroy event + * @class MirrorDestroyEvent + * @module MirrorDestroyEvent + * @extends MirrorEvent + */ export class MirrorDestroyEvent extends MirrorEvent { static type = 'mirror:destroy'; + static cancelable = true; } diff --git a/src/Draggable/MirrorEvent/README.md b/src/Draggable/MirrorEvent/README.md index 791133c4..5ea179bf 100644 --- a/src/Draggable/MirrorEvent/README.md +++ b/src/Draggable/MirrorEvent/README.md @@ -1 +1,86 @@ -## Mirror event +## MirrorEvent + +The base mirror event for all Mirror events that `Draggable` emits. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Interface** | `MirrorEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `mirror` | + +### API + +**`mirrorEvent.source: HTMLElement`** +Read-only property for the source element. This is a straight copy of the `originalSource` +element, which can be moved around in the DOM. + +**`mirrorEvent.originalSource: String`** +Read-only property for the original source element that was picked up. This element never +moves in the DOM and gets hidden on `drag:start`. + +**`mirrorEvent.mirror: String`** +Read-only property for the mirror element, which is also a copy of the `originalSource` element. +The mirror follows your mouse/touch movements. + +**`mirrorEvent.sourceContainer: String`** +Read-only property for the source elements container. This would be one of the containers that +was passed into Draggable. + +**`mirrorEvent.sensorEvent: SensorEvent`** +Read-only property for the original sensor event that triggered this event. + +**`mirrorEvent.originalEvent: SensorEvent`** +Read-only property for the original event that triggered the sensor event. + +**`mirrorEvent.hasMirror(): Boolean`** +Checks if a mirror has been created. The mirror does not get created for `DragSensor` or `KeyboardSensor` events + +## MirrorCreatedEvent + +`MirrorCreatedEvent` gets triggered by `Draggable` when the mirror element has +been created. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `MirrorEvent` | +| **Interface** | `MirrorCreatedEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `mirror:created` | + +## MirrorAttachedEvent + +`MirrorAttachedEvent` gets triggered when the mirror has been appended to the DOM. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `MirrorEvent` | +| **Interface** | `MirrorAttachedEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `mirror:attached` | + +## MirrorMoveEvent + +`MirrorMoveEvent` gets triggered when moving the mirror around. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `MirrorEvent` | +| **Interface** | `MirrorMoveEvent` | +| **Cancelable** | true | +| **Cancel action** | Stops mirror movement | +| **type** | `drag:over` | + +## MirrorDestroyEvent + +`MirrorDestroyEvent` gets triggered before the mirror gets removed from the DOM. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `MirrorEvent` | +| **Interface** | `MirrorDestroyEvent` | +| **Cancelable** | true | +| **Cancel action** | Cancels the removal of the mirror from the DOM | +| **type** | `mirror:destroy` | diff --git a/src/Draggable/Plugins/Accessibility/Accessibility.js b/src/Draggable/Plugins/Accessibility/Accessibility.js index 3c5af48d..e3efdfdb 100644 --- a/src/Draggable/Plugins/Accessibility/Accessibility.js +++ b/src/Draggable/Plugins/Accessibility/Accessibility.js @@ -2,14 +2,34 @@ const ARIA_GRABBED = 'aria-grabbed'; const ARIA_DROPEFFECT = 'aria-dropeffect'; const TABINDEX = 'tabindex'; +/** + * __WIP__ Accessibility plugin + * @class Accessibility + * @module Accessibility + */ export default class Accessibility { + + /** + * Accessibility constructor. + * @constructs Accessibility + * @param {Draggable} draggable - Draggable instance + */ constructor(draggable) { + + /** + * Draggable instance + * @property draggable + * @type {Draggable} + */ this.draggable = draggable; this._onInit = this._onInit.bind(this); this._onDestroy = this._onDestroy.bind(this); } + /** + * Attaches listeners to draggable + */ attach() { this.draggable .on('init', this._onInit) @@ -18,6 +38,9 @@ export default class Accessibility { .on('drag:stop', _onDragStop); } + /** + * Detaches listeners from draggable + */ detach() { this.draggable .off('init', this._onInit) @@ -26,6 +49,12 @@ export default class Accessibility { .off('drag:stop', _onDragStop); } + /** + * Intialize handler + * @private + * @param {Object} param + * @param {HTMLElement[]} param.containers + */ _onInit({containers}) { for (const container of containers) { container.setAttribute(ARIA_DROPEFFECT, this.draggable.options.type); @@ -37,6 +66,12 @@ export default class Accessibility { } } + /** + * Destroy handler handler + * @private + * @param {Object} param + * @param {HTMLElement[]} param.containers + */ _onDestroy({containers}) { for (const container of containers) { container.removeAttribute(ARIA_DROPEFFECT); diff --git a/src/Draggable/Plugins/Accessibility/README.md b/src/Draggable/Plugins/Accessibility/README.md index f6593a1e..2fd2b1e8 100644 --- a/src/Draggable/Plugins/Accessibility/README.md +++ b/src/Draggable/Plugins/Accessibility/README.md @@ -1 +1,3 @@ ## Accessibility + +__WIP__ diff --git a/src/Draggable/Plugins/README.md b/src/Draggable/Plugins/README.md index 852b9b8f..3e6c495c 100644 --- a/src/Draggable/Plugins/README.md +++ b/src/Draggable/Plugins/README.md @@ -1 +1,6 @@ ## Draggable plugins + +These plugins are included by draggable by default + +- (Accessibility)[Accessibility] +- (Mirror)[Mirror] diff --git a/src/Draggable/README.md b/src/Draggable/README.md index 48554f12..460431aa 100644 --- a/src/Draggable/README.md +++ b/src/Draggable/README.md @@ -1,5 +1,23 @@ ## Draggable +### Import + +```js +import {Draggable} from '@shopify/draggable'; +``` + +```js +import Draggable from '@shopify/draggable/draggable'; +``` + +```html + +``` + +```html + +``` + ### API **`new Draggable(containers: HTMLElement[]|NodeList|HTMLElement, options: Object): Draggable`** @@ -77,20 +95,34 @@ 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 | -| `mirror:destroy` | Gets fired when draggable mirror gets removed | true | Stop mirror removal | +| Name | Description | Cancelable | Cancelable action | +| -------------------------------------------- | ---------------------------------------------------------- | ----------- | -------------------- | +| [`drag:start`][dragstart] | Gets fired when drag action begins | true | Prevents drag start | +| [`drag:move`][dragmove] | Gets fired when moving a draggable around | false | - | +| [`drag:over`][dragover] | Gets fired when dragging over other draggable | false | - | +| [`drag:over:container`][dragovercontainer] | Gets fired when dragging over other draggable container | false | - | +| [`drag:out`][dragout] | Gets fired when dragging out of other draggable | false | - | +| [`drag:out:container`][dragoutcontainer] | Gets fired when dragging out of other draggable container | false | - | +| [`drag:stop`][dragstop] | Gets fired when draggable has been released | false | - | +| [`drag:pressure`][dragpressure] | Gets fired when using force touch on draggable element | false | - | +| [`mirror:created`][mirrorcreated] | Gets fired when draggable mirror gets created | false | - | +| [`mirror:attached`][mirrorattached] | Gets fired when draggable mirror gets attached to DOM | false | - | +| [`mirror:move`][mirrormove] | Gets fired when draggable mirror moves | true | Stop mirror movement | +| [`mirror:destroy`][mirrordestroy] | Gets fired when draggable mirror gets removed | true | Stop mirror removal | + +[dragstart]: DragEvent#dragstartevent +[dragmove]: DragEvent#dragmoveevent +[dragover]: DragEvent#dragoverevent +[dragovercontainer]: DragEvent#dragovercontainer +[dragout]: DragEvent#dragoutevent +[dragoutcontainer]: DragEvent#dragoutcontainerevent +[dragstop]: DragEvent#dragstopevent +[dragpressure]: DragEvent#dragpressureevent + +[mirrorcreated]: MirrorEvent#mirrorcreatedevent +[mirrorattached]: MirrorEvent#mirrorattachedevent +[mirrormove]: MirrorEvent#mirrormoveevent +[mirrordestroy]: MirrorEvent#mirrordestroyevent ### Classes diff --git a/src/Draggable/Sensors/ForceTouchSensor/README.md b/src/Draggable/Sensors/ForceTouchSensor/README.md index 701d5389..7276abdd 100644 --- a/src/Draggable/Sensors/ForceTouchSensor/README.md +++ b/src/Draggable/Sensors/ForceTouchSensor/README.md @@ -18,10 +18,10 @@ This sensor only works for Macbook Pros with force touch trackpads To create a force touch sensor, specify the containers it should pay attention to. Sensors will always trigger sensor events on container element. -**`touchSensor.attach(): void`** +**`forceTouchSensor.attach(): void`** Attaches sensors to the DOM -**`touchSensor.detach(): void`** +**`forceTouchSensor.detach(): void`** Detaches sensors to the DOM ### Options diff --git a/src/Draggable/Sensors/README.md b/src/Draggable/Sensors/README.md index 760a8e54..20980604 100644 --- a/src/Draggable/Sensors/README.md +++ b/src/Draggable/Sensors/README.md @@ -1 +1,11 @@ ## Sensors + +Sensors pick up native browser events and translates them to `drag:start`, `drag:move` and `drag:stop` +events. Sensors abstract the browser API away for Draggable, so it's easier to focus on DnD operations. + +### Sensors + +- [DragSensor](DragSensor) +- [ForceTouchSensor](ForceTouchSensor) +- [MouseSensor](MouseSensor) +- [TouchSensor](TouchSensor) diff --git a/src/Draggable/Sensors/SensorEvent/README.md b/src/Draggable/Sensors/SensorEvent/README.md index dff9a432..a0224cb3 100644 --- a/src/Draggable/Sensors/SensorEvent/README.md +++ b/src/Draggable/Sensors/SensorEvent/README.md @@ -1 +1,79 @@ -## Sensor event +## SensorEvent + +The base sensor event for all Sensor events that sensors emits. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Interface** | `SensorEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `sensor` | + +### API + +**`sensorEvent.originalEvent: Event`** +Read-only property for the original event that triggered the sensor event. + +**`sensorEvent.clientX: Number`** +Read-only property for current X coordinates. + +**`sensorEvent.clientY: Number`** +Read-only property for current Y coordinates. + +**`sensorEvent.target: HTMLElement`** +Read-only property for the normalized target for both touch and mouse events. +Returns the element that is behind cursor or touch pointer. + +**`sensorEvent.container: Number`** +Read-only property for the container that fired the sensor event + +**`sensorEvent.pressure: Number`** +Read-only property for the pressure applied + +## DragStartSensorEvent + +`DragStartSensorEvent` gets triggered by sensors for drag start. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SensorEvent` | +| **Interface** | `DragStartSensorEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents drag start | +| **type** | `drag:start` | + +## DragMoveSensorEvent + +`DragMoveSensorEvent` gets triggered by sensors for drag move. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SensorEvent` | +| **Interface** | `DragMoveSensorEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag:move` | + +## DragStopSensorEvent + +`DragStopSensorEvent` gets triggered by sensors for drag stop. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SensorEvent` | +| **Interface** | `DragStopSensorEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag:stop` | + +## DragPressureSensorEvent + +`DragPressureSensorEvent` gets triggered by sensors for drag pressure. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SensorEvent` | +| **Interface** | `DragPressureSensorEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `drag:pressure` | diff --git a/src/Draggable/Sensors/SensorEvent/SensorEvent.js b/src/Draggable/Sensors/SensorEvent/SensorEvent.js index 4a9a78b9..01f07d6a 100644 --- a/src/Draggable/Sensors/SensorEvent/SensorEvent.js +++ b/src/Draggable/Sensors/SensorEvent/SensorEvent.js @@ -59,16 +59,6 @@ export class SensorEvent extends AbstractEvent { return this.data.container; } - /** - * Container that initiated the sensor - * @property overContainer - * @type {HTMLElement} - * @readonly - */ - get overContainer() { - return this.data.overContainer; - } - /** * Trackpad pressure * @property pressure @@ -87,13 +77,6 @@ export class SensorEvent extends AbstractEvent { * @extends SensorEvent */ export class DragStartSensorEvent extends SensorEvent { - - /** - * Event type - * @property type - * @type {String} - * @static - */ static type = 'drag:start'; } @@ -104,13 +87,6 @@ export class DragStartSensorEvent extends SensorEvent { * @extends SensorEvent */ export class DragMoveSensorEvent extends SensorEvent { - - /** - * Event type - * @property type - * @type {String} - * @static - */ static type = 'drag:move'; } @@ -121,13 +97,6 @@ export class DragMoveSensorEvent extends SensorEvent { * @extends SensorEvent */ export class DragStopSensorEvent extends SensorEvent { - - /** - * Event type - * @property type - * @type {String} - * @static - */ static type = 'drag:stop'; } @@ -138,12 +107,5 @@ export class DragStopSensorEvent extends SensorEvent { * @extends SensorEvent */ export class DragPressureSensorEvent extends SensorEvent { - - /** - * Event type - * @property type - * @type {String} - * @static - */ static type = 'drag:pressure'; } diff --git a/src/Droppable/Droppable.js b/src/Droppable/Droppable.js index 04e1e33a..e73df7dd 100644 --- a/src/Droppable/Droppable.js +++ b/src/Droppable/Droppable.js @@ -89,7 +89,7 @@ export default class Droppable extends Draggable { /** * Returns class name for class identifier * @param {String} name - Name of class identifier - * @return {String} + * @return {String|null} */ getClassNameFor(name) { return super.getClassNameFor(name) || classes[name]; @@ -221,7 +221,7 @@ export default class Droppable extends Draggable { * Returns closest droppable element for even target * @private * @param {HTMLElement} target - Event target - * @return {HTMLElement} + * @return {HTMLElement|null} */ [closestDroppable](target) { if (!this.droppables) { @@ -234,7 +234,7 @@ export default class Droppable extends Draggable { /** * Returns all current droppable elements for this draggable instance * @private - * @return {NodeList|HTMLElement[]} + * @return {NodeList|HTMLElement[]|Array} */ [getDroppables]() { const droppables = this.options.droppable; diff --git a/src/Droppable/DroppableEvent/DroppableEvent.js b/src/Droppable/DroppableEvent/DroppableEvent.js index 792f2a34..6dfd3dd0 100644 --- a/src/Droppable/DroppableEvent/DroppableEvent.js +++ b/src/Droppable/DroppableEvent/DroppableEvent.js @@ -1,21 +1,63 @@ import AbstractEvent from 'shared/AbstractEvent'; +/** + * Base droppable event + * @class DroppableEvent + * @module DroppableEvent + * @extends AbstractEvent + */ export class DroppableEvent extends AbstractEvent { static type = 'droppable'; + /** + * Original drag event that triggered this droppable event + * @property dragEvent + * @type {DragEvent} + * @readonly + */ get dragEvent() { return this.data.dragEvent; } - - get droppable() { - return this.data.droppable; - } } +/** + * Droppable over event + * @class DroppableOverEvent + * @module DroppableOverEvent + * @extends DroppableEvent + */ export class DroppableOverEvent extends DroppableEvent { static type = 'droppable:over'; + static cancelable = true; + + /** + * The droppable element you are over + * @property droppable + * @type {HTMLElement} + * @readonly + */ + get droppable() { + return this.data.droppable; + } } +/** + * Droppable out event + * @class DroppableOutEvent + * @module DroppableOutEvent + * @extends DroppableEvent + */ export class DroppableOutEvent extends DroppableEvent { static type = 'droppable:out'; + static cancelable = true; + + /** + * The droppable element you _were_ over + * @property droppable + * @type {HTMLElement} + * @readonly + */ + get droppable() { + return this.data.droppable; + } } diff --git a/src/Droppable/DroppableEvent/README.md b/src/Droppable/DroppableEvent/README.md index 5967303a..a643af79 100644 --- a/src/Droppable/DroppableEvent/README.md +++ b/src/Droppable/DroppableEvent/README.md @@ -1 +1,49 @@ -## Droppable event +## DroppableEvent + +The base droppable event for all Droppable events that `Droppable` emits. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Interface** | `DroppableEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `droppable` | + +### API + +**`droppableEvent.dragEvent: DragEvent`** +Read-only property for the original drag event that triggered the droppable event. + +## DroppableOverEvent + +`DroppableOverEvent` gets triggered by `Droppable` before dropping the draggable element into a droppable element. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DroppableEvent` | +| **Interface** | `DroppableOverEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents drop | +| **type** | `droppable:over` | + +### API + +**`droppableEvent.droppable: HTMLElement`** +Read-only property for the droppable element you are over. + +## DroppableOutEvent + +`DroppableOutEvent` gets triggered by `Droppable` before moving the draggable element to its original position. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `DroppableEvent` | +| **Interface** | `DroppableOutEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents release | +| **type** | `droppable:out` | + +### API + +**`droppableEvent.droppable: HTMLElement`** +Read-only property for the droppable element you were over. diff --git a/src/Droppable/README.md b/src/Droppable/README.md index 951c2f2c..7a06e3a8 100644 --- a/src/Droppable/README.md +++ b/src/Droppable/README.md @@ -3,13 +3,31 @@ Droppable is built on top of Draggable and allows you to declare draggable and droppable elements via options. Droppable fires two events on top of the draggable events: `droppable:over` and `droppable:out`. +### Import + +```js +import {Droppable} from '@shopify/draggable'; +``` + +```js +import Droppable from '@shopify/draggable/droppable'; +``` + +```html + +``` + +```html + +``` + ### API -Check out Draggables API for the base API +Check out [Draggables API](../Draggable#api) for the base API ### Options -**`droppable {String|Array[HTMLElement]|NodeList|Function}`** +**`droppable {String|HTMLElement[]|NodeList|Function}`** A css selector string, an array of elements, a NodeList or a function returning elements for droppable elements within the `containers` specified. diff --git a/src/Plugins/Collidable/CollidableEvent/CollidableEvent.js b/src/Plugins/Collidable/CollidableEvent/CollidableEvent.js index da915e81..1f5e68ea 100644 --- a/src/Plugins/Collidable/CollidableEvent/CollidableEvent.js +++ b/src/Plugins/Collidable/CollidableEvent/CollidableEvent.js @@ -1,24 +1,60 @@ import AbstractEvent from 'shared/AbstractEvent'; +/** + * Base collidable event + * @class CollidableEvent + * @module CollidableEvent + * @extends AbstractEvent + */ export class CollidableEvent extends AbstractEvent { static type = 'collidable'; + /** + * Drag event that triggered this colliable event + * @property dragEvent + * @type {DragEvent} + * @readonly + */ get dragEvent() { return this.data.dragEvent; } } +/** + * Collidable in event + * @class CollidableInEvent + * @module CollidableInEvent + * @extends CollidableEvent + */ export class CollidableInEvent extends CollidableEvent { static type = 'collidable:in'; + /** + * Element you are currently colliding with + * @property collidingElement + * @type {HTMLElement} + * @readonly + */ get collidingElement() { return this.data.collidingElement; } } +/** + * Collidable out event + * @class CollidableOutEvent + * @module CollidableOutEvent + * @extends CollidableEvent + */ export class CollidableOutEvent extends CollidableEvent { static type = 'collidable:out'; + /** + * Element you were previously colliding with + * @property collidingElement + * @type {HTMLElement} + * @readonly + */ get collidingElement() { return this.data.collidingElement; } diff --git a/src/Plugins/Collidable/CollidableEvent/README.md b/src/Plugins/Collidable/CollidableEvent/README.md index b4f18b69..91e2c287 100644 --- a/src/Plugins/Collidable/CollidableEvent/README.md +++ b/src/Plugins/Collidable/CollidableEvent/README.md @@ -1 +1,50 @@ ## Collidable event + +The base collidable event for all Collidable events that `Collidable` emits. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Interface** | `CollidableEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `collidable` | + +### API + +**`collidableEvent.dragEvent: DragEvent`** +Read-only property for drag event that triggered this collidable event + +## CollidableInEvent + +`CollidableInEvent` gets triggered by `Collidable` when colliding with an element specified by the +`collidable` options. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `CollidableEvent` | +| **Interface** | `CollidableInEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `collidable:in` | + +### API + +**`collidableEvent.collidingElement: HTMLElement`** +Read-only property for currently colliding element + +## CollidableOutEvent + +`CollidableOutEvent` gets triggered by `Collidable` when leaving a colliding area. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `CollidableEvent` | +| **Interface** | `CollidableOutEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `collidable:out` | + +### API + +**`collidableEvent.collidingElement: HTMLElement`** +Read-only property for previously colliding element diff --git a/src/Plugins/Collidable/README.md b/src/Plugins/Collidable/README.md index daea804e..bcaa0d9f 100644 --- a/src/Plugins/Collidable/README.md +++ b/src/Plugins/Collidable/README.md @@ -1 +1,51 @@ ## Collidable + +When you use the collidable plugin you can specify which elements you **can't** drag over and it will freeze +the mirror movement for you. These currently only work with `Sortable`, `Swappable` and `Droppable`. + +This plugin is not included by default, so make sure to import it before using. + +### Import + +```js +import {Collidable} from '@shopify/draggable'; +``` + +```js +import Collidable from '@shopify/draggable/plugins/collidable'; +``` + +```html + +``` + +```html + +``` + +### Options + +**`collidables {String|HTMLElement[]|NodeList|HTMLElement|Function}`** +A css selector string, an array of elements, a NodeList, a HTMLElement or a function returning elements for collidable elements. + +### Events + +| Name | Description | Cancelable | Cancelable action | +| --------------------- | ---------------------------------------------------------- | ----------- | -------------------- | +| `collidable:in` | Gets fired when dragging near a collidable element | false | - | +| `collidable:out` | Gets fired when dragging away from a collidable element | false | - | + +### Example + +```js +import {Sortable, Plugins} from '@shopify/draggable'; + +const sortable = new Sortable(document.querySelectorAll('ul'), { + draggable: 'li', + collidables: '.other-list', + plugins: [Plugins.Collidable] +}); + +sortable.on('collidable:in', () => console.log('collidable:in')); +sortable.on('collidable:out', () => console.log('collidable:out')); +``` diff --git a/src/Plugins/Snappable/README.md b/src/Plugins/Snappable/README.md index a19b58f7..a47fa8a3 100644 --- a/src/Plugins/Snappable/README.md +++ b/src/Plugins/Snappable/README.md @@ -1 +1,49 @@ ## Snappable + +Snappable simulates a "snap" by hiding the mirror and removing the `'source:dragging'` class from the source. +It also sets the `'source:placed'` class for potential drop animations. + +This plugin is not included by default, so make sure to import it before using. + +### Import + +```js +import {Snappable} from '@shopify/draggable'; +``` + +```js +import Snappable from '@shopify/draggable/snappable'; +``` + +```html + +``` + +```html + +``` + +### Options + +_No options_ + +### Events + +| Name | Description | Cancelable | Cancelable action | +| --------------------- | ---------------------------------------------------------- | ----------- | --------------------- | +| `snap:in` | Gets fired when just before snapping in | true | Prevents snapping | +| `snap:out` | Gets fired when snapping out | true | Prevents snapping out | + +### Example + +```js +import {Sortable, Plugins} from '@shopify/draggable'; + +const sortable = new Sortable(document.querySelectorAll('ul'), { + draggable: 'li', + plugins: [Plugins.Snappable] +}); + +sortable.on('snap:in', () => console.log('snap:in')); +sortable.on('snap:out', () => console.log('snap:out')); +``` diff --git a/src/Plugins/Snappable/Snappable.js b/src/Plugins/Snappable/Snappable.js index 8dd36ef6..8ea5798a 100644 --- a/src/Plugins/Snappable/Snappable.js +++ b/src/Plugins/Snappable/Snappable.js @@ -75,6 +75,7 @@ export default class Snappable { source.classList.remove(this.draggable.getClassNameFor('source:dragging')); source.classList.add(this.draggable.getClassNameFor('source:placed')); + // Need to cancel this in drag out setTimeout(() => { source.classList.remove(this.draggable.getClassNameFor('source:placed')); }, this.draggable.options.placedTimeout); diff --git a/src/Plugins/Snappable/SnappableEvent/README.md b/src/Plugins/Snappable/SnappableEvent/README.md index e69de29b..f8a46fa5 100644 --- a/src/Plugins/Snappable/SnappableEvent/README.md +++ b/src/Plugins/Snappable/SnappableEvent/README.md @@ -0,0 +1,39 @@ +## Snap event + +The base snap event for all Snap events that `Snappable` emits. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Interface** | `SnapEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `snap` | + +### API + +**`snapEvent.dragEvent: DragEvent`** +Read-only property for drag event that triggered this snappable event + +## SnapInEvent + +`SnapInEvent` gets triggered by `Snappable` before snapping into place. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SnapEvent` | +| **Interface** | `SnapInEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents snap in effect | +| **type** | `snap:in` | + +## SnapOutEvent + +`SnapOutEvent` gets triggered by `Snappable` before snapping out. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SnapEvent` | +| **Interface** | `SnapOutEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents snap out effect | +| **type** | `snap:out` | diff --git a/src/Plugins/Snappable/SnappableEvent/SnappableEvent.js b/src/Plugins/Snappable/SnappableEvent/SnappableEvent.js index a7bd135e..a0e76a11 100644 --- a/src/Plugins/Snappable/SnappableEvent/SnappableEvent.js +++ b/src/Plugins/Snappable/SnappableEvent/SnappableEvent.js @@ -1,15 +1,43 @@ import AbstractEvent from 'shared/AbstractEvent'; +/** + * Base snap event + * @class SnapEvent + * @module SnapEvent + * @extends AbstractEvent + */ export class SnapEvent extends AbstractEvent { + static type = 'snap'; + + /** + * Drag event that triggered this snap event + * @property dragEvent + * @type {DragEvent} + * @readonly + */ get dragEvent() { return this.data.dragEvent; } } +/** + * Snap in event + * @class SnapInEvent + * @module SnapInEvent + * @extends SnapEvent + */ export class SnapInEvent extends SnapEvent { static type = 'snap:in'; + static cancelable = true; } +/** + * Snap out event + * @class SnapOutEvent + * @module SnapOutEvent + * @extends SnapEvent + */ export class SnapOutEvent extends SnapEvent { static type = 'snap:out'; + static cancelable = true; } diff --git a/src/Plugins/SwapAnimation/README.md b/src/Plugins/SwapAnimation/README.md index 55c9a070..0d98e2f4 100644 --- a/src/Plugins/SwapAnimation/README.md +++ b/src/Plugins/SwapAnimation/README.md @@ -9,11 +9,19 @@ This plugin is not included by default, so make sure to import it before using. ### Import ```js -import {SwapAnimation} from '@shopify/draggable/plugins/swap-animation'; +import {Plugins} from '@shopify/draggable'; +``` + +```js +import SwapAnimation from '@shopify/draggable/plugins/swap-animation'; +``` + +```html + ``` ```html - + ``` ### API diff --git a/src/Sortable/README.md b/src/Sortable/README.md index b0c20297..96c6ea77 100644 --- a/src/Sortable/README.md +++ b/src/Sortable/README.md @@ -3,9 +3,27 @@ Sortable is built on top of Draggable and allows you to reorder elements. It maintains the order internally and fires three events on top of the draggable events: `sortable:start`, `sortable:sorted` and `sortable:stop`. +### Import + +```js +import {Sortable} from '@shopify/sortable'; +``` + +```js +import Sortable from '@shopify/draggable/sortable'; +``` + +```html + +``` + +```html + +``` + ### API -Check out Draggables API for the base API +Check out [Draggables API](../Draggable#api) for the base API ### Options diff --git a/src/Sortable/Sortable.js b/src/Sortable/Sortable.js index 6eca7b22..987343a2 100644 --- a/src/Sortable/Sortable.js +++ b/src/Sortable/Sortable.js @@ -118,7 +118,7 @@ export default class Sortable extends Draggable { const sortableSortEvent = new SortableSortEvent({ dragEvent: event, - oldIndex, + currentIndex: oldIndex, source, over, }); @@ -164,7 +164,7 @@ export default class Sortable extends Draggable { const sortableSortEvent = new SortableSortEvent({ dragEvent: event, - oldIndex, + currentIndex: oldIndex, source, over, }); diff --git a/src/Sortable/SortableEvent/README.md b/src/Sortable/SortableEvent/README.md index 92b6116f..5c0e3e79 100644 --- a/src/Sortable/SortableEvent/README.md +++ b/src/Sortable/SortableEvent/README.md @@ -1 +1,113 @@ -## Sortable event +## SortableEvent + +The base sortable event for all Sortable events that `Sortable` emits. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Interface** | `SortableEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `sortable` | + +### API + +**`sortableEvent.dragEvent: DragEvent`** +Read-only property for the original drag event that triggered the sortable event. + +## SortableStartEvent + +`SortableStartEvent` gets triggered by `Sortable` when on drag start. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SortableEvent` | +| **Interface** | `SortableStartEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents drag start | +| **type** | `sortable:start` | + +### API + +**`sortableEvent.startIndex: Number`** +Read-only property for the start index of the current draggable source. + +**`sortableEvent.startContainer: HTMLElement`** +Read-only property for the start container of the current draggable source. + +## SortableSortEvent + +`SortableSortedEvent` gets triggered by `Sortable` before sorting with another draggable. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SortableEvent` | +| **Interface** | `SortableSortEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents sorting | +| **type** | `sortable:sort` | + +### API + +**`sortableEvent.oldIndex: Number`** +Read-only property for the old index of the current draggable source. + +**`sortableEvent.newIndex: Number`** +Read-only property for the new index of the current draggable source. + +**`sortableEvent.oldContainer: HTMLElement`** +Read-only property for the old container of the current draggable source. + +**`sortableEvent.newContainer: HTMLElement`** +Read-only property for the new container of the current draggable source. + +## SortableSortedEvent + +`SortableSortedEvent` gets triggered by `Sortable` when sorted with another draggable. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SortableEvent` | +| **Interface** | `SortableSortedEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `sortable:sorted` | + +### API + +**`sortableEvent.oldIndex: Number`** +Read-only property for the old index of the current draggable source. + +**`sortableEvent.newIndex: Number`** +Read-only property for the new index of the current draggable source. + +**`sortableEvent.oldContainer: HTMLElement`** +Read-only property for the old container of the current draggable source. + +**`sortableEvent.newContainer: HTMLElement`** +Read-only property for the new container of the current draggable source. + +## SortableStopEvent + +`SortableStopEvent` gets triggered by `Sortable` on drag stop. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SortableEvent` | +| **Interface** | `SortableStopEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `sortable:stop` | + +### API + +**`sortableEvent.oldIndex: Number`** +Read-only property for the old index of the current draggable source. + +**`sortableEvent.newIndex: Number`** +Read-only property for the new index of the current draggable source. + +**`sortableEvent.oldContainer: HTMLElement`** +Read-only property for the old container of the current draggable source. + +**`sortableEvent.newContainer: HTMLElement`** +Read-only property for the new container of the current draggable source. diff --git a/src/Sortable/SortableEvent/SortableEvent.js b/src/Sortable/SortableEvent/SortableEvent.js index c20eea1a..3e0590bd 100644 --- a/src/Sortable/SortableEvent/SortableEvent.js +++ b/src/Sortable/SortableEvent/SortableEvent.js @@ -1,78 +1,192 @@ import AbstractEvent from 'shared/AbstractEvent'; +/** + * Base sortable event + * @class SortableEvent + * @module SortableEvent + * @extends AbstractEvent + */ export class SortableEvent extends AbstractEvent { + static type = 'sortable'; + + /** + * Original drag event that triggered this sortable event + * @property dragEvent + * @type {DragEvent} + * @readonly + */ get dragEvent() { return this.data.dragEvent; } } +/** + * Sortable start event + * @class SortableStartEvent + * @module SortableStartEvent + * @extends SortableEvent + */ export class SortableStartEvent extends SortableEvent { static type = 'sortable:start'; - + static cancelable = true; + + /** + * Start index of source on sortable start + * @property startIndex + * @type {Number} + * @readonly + */ get startIndex() { return this.data.startIndex; } + /** + * Start container on sortable start + * @property startContainer + * @type {HTMLElement} + * @readonly + */ get startContainer() { return this.data.startContainer; } } +/** + * Sortable sort event + * @class SortableSortEvent + * @module SortableSortEvent + * @extends SortableEvent + */ export class SortableSortEvent extends SortableEvent { static type = 'sortable:sort'; - - get oldIndex() { - return this.data.oldIndex; + static cancelable = true; + + /** + * Index of current draggable element + * @property currentIndex + * @type {Number} + * @readonly + */ + get currentIndex() { + return this.data.currentIndex; } + /** + * Draggable element you are hovering over + * @property over + * @type {HTMLElement} + * @readonly + */ get over() { return this.data.oldIndex; } + /** + * Draggable container element you are hovering over + * @property overContainer + * @type {HTMLElement} + * @readonly + */ get overContainer() { return this.data.newIndex; } } +/** + * Sortable sorted event + * @class SortableSortedEvent + * @module SortableSortedEvent + * @extends SortableEvent + */ export class SortableSortedEvent extends SortableEvent { static type = 'sortable:sorted'; - get moves() { - return this.data.moves; - } - + /** + * Index of last sorted event + * @property oldIndex + * @type {Number} + * @readonly + */ get oldIndex() { return this.data.oldIndex; } + /** + * New index of this sorted event + * @property newIndex + * @type {Number} + * @readonly + */ get newIndex() { return this.data.newIndex; } + /** + * Old container of draggable element + * @property oldContainer + * @type {HTMLElement} + * @readonly + */ get oldContainer() { return this.data.oldContainer; } + /** + * New container of draggable element + * @property newContainer + * @type {HTMLElement} + * @readonly + */ get newContainer() { return this.data.newContainer; } } +/** + * Sortable stop event + * @class SortableStopEvent + * @module SortableStopEvent + * @extends SortableEvent + */ export class SortableStopEvent extends SortableEvent { static type = 'sortable:stop'; + /** + * Original index on sortable start + * @property oldIndex + * @type {Number} + * @readonly + */ get oldIndex() { return this.data.oldIndex; } + /** + * New index of draggable element + * @property newIndex + * @type {Number} + * @readonly + */ get newIndex() { return this.data.newIndex; } + /** + * Original container of draggable element + * @property oldContainer + * @type {HTMLElement} + * @readonly + */ get oldContainer() { return this.data.oldContainer; } + /** + * New container of draggable element + * @property newContainer + * @type {HTMLElement} + * @readonly + */ get newContainer() { return this.data.newContainer; } diff --git a/src/Swappable/README.md b/src/Swappable/README.md index 381fb1a9..53e37863 100644 --- a/src/Swappable/README.md +++ b/src/Swappable/README.md @@ -3,9 +3,27 @@ Droppable is built on top of Draggable and allows you to swap elements by dragging over them. No order will be maintained (unlike Sortable), so any draggable element that gets dragged over will be swapped with the source element. +### Import + +```js +import {Swappable} from '@shopify/sortable'; +``` + +```js +import Swappable from '@shopify/draggable/swappable'; +``` + +```html + +``` + +```html + +``` + ### API -Check out Draggables API for the base API +Check out [Draggables API](../Draggable#api) for the base API ### Options diff --git a/src/Swappable/SwappableEvent/README.md b/src/Swappable/SwappableEvent/README.md index 86f58f53..c4281b3d 100644 --- a/src/Swappable/SwappableEvent/README.md +++ b/src/Swappable/SwappableEvent/README.md @@ -1 +1,76 @@ -## Swappable event +## Swappable + +The base swappable event for all Swappable events that `Swappable` emits. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Interface** | `SwappableEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `swappable` | + +### API + +**`swappableEvent.dragEvent: DragEvent`** +Read-only property for the original drag event that triggered the swappable event. + +## SwappableStartEvent + +`SwappableStartEvent` gets triggered by `Swappable` on drag start. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SwappableEvent` | +| **Interface** | `SwappableStartEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents drag start | +| **type** | `swappable:start` | + +## SwappableSwapEvent + +`SwappableSwapEvent` gets triggered by `Swappable` before swapping with another draggable. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SwappableEvent` | +| **Interface** | `SwappableSwapEvent` | +| **Cancelable** | true | +| **Cancel action** | Prevents swapping | +| **type** | `swappable:swap` | + +### API + +**`swappableEvent.over: HTMLElement`** +Read-only property for the draggable element that you are over. + +**`swappableEvent.overContainer: HTMLElement`** +Read-only property for the draggable container element that you are over. + +## SwappableSwappedEvent + +`SwappableSwappedEvent` gets triggered by `Swappable` when sorted with another draggable. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SwappableEvent` | +| **Interface** | `SwappableSwappedEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `swappable:swapped` | + +### API + +**`swappableEvent.swappedElement: HTMLElement`** +Read-only property for the draggable element you swapped with. + +## SwappableStopEvent + +`SwappableStopEvent` gets triggered by `Swappable` on drag stop. + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `SwappableEvent` | +| **Interface** | `SwappableStopEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `swappable:stop` | diff --git a/src/Swappable/SwappableEvent/SwappableEvent.js b/src/Swappable/SwappableEvent/SwappableEvent.js index 280f4f2f..47c02123 100644 --- a/src/Swappable/SwappableEvent/SwappableEvent.js +++ b/src/Swappable/SwappableEvent/SwappableEvent.js @@ -1,35 +1,93 @@ import AbstractEvent from 'shared/AbstractEvent'; +/** + * Base swappable event + * @class SwappableEvent + * @module SwappableEvent + * @extends AbstractEvent + */ export class SwappableEvent extends AbstractEvent { + static type = 'swappable'; + + /** + * Original drag event that triggered this swappable event + * @property dragEvent + * @type {DragEvent} + * @readonly + */ get dragEvent() { return this.data.dragEvent; } } +/** + * Swappable start event + * @class SwappableStartEvent + * @module SwappableStartEvent + * @extends SwappableEvent + */ export class SwappableStartEvent extends SwappableEvent { static type = 'swappable:start'; + static cancelable = true; } +/** + * Swappable swap event + * @class SwappableSwapEvent + * @module SwappableSwapEvent + * @extends SwappableEvent + */ export class SwappableSwapEvent extends SwappableEvent { static type = 'swappable:swap'; + static cancelable = true; + /** + * Draggable element you are over + * @property over + * @type {HTMLElement} + * @readonly + */ get over() { return this.data.over; } + /** + * Draggable container you are over + * @property overContainer + * @type {HTMLElement} + * @readonly + */ get overContainer() { return this.data.overContainer; } } +/** + * Swappable swapped event + * @class SwappableSwappedEvent + * @module SwappableSwappedEvent + * @extends SwappableEvent + */ export class SwappableSwappedEvent extends SwappableEvent { static type = 'swappable:swapped'; + /** + * The draggable element that you swapped with + * @property swappedElement + * @type {HTMLElement} + * @readonly + */ get swappedElement() { return this.data.swappedElement; } } +/** + * Swappable stop event + * @class SwappableStopEvent + * @module SwappableStopEvent + * @extends SwappableEvent + */ export class SwappableStopEvent extends SwappableEvent { static type = 'swappable:stop'; } diff --git a/src/shared/AbstractEvent/AbstractEvent.js b/src/shared/AbstractEvent/AbstractEvent.js index f9573501..bb29e2c1 100644 --- a/src/shared/AbstractEvent/AbstractEvent.js +++ b/src/shared/AbstractEvent/AbstractEvent.js @@ -3,10 +3,27 @@ * cancel a specific event or you can check if an event has been canceled by * calling `canceled()`. * @abstract - * @class + * @class AbstractEvent + * @module AbstractEvent */ export default class AbstractEvent { + + /** + * Event type + * @static + * @abstract + * @property type + * @type {String} + */ static type = 'event'; + + /** + * Event cancelable + * @static + * @abstract + * @property cancelable + * @type {Boolean} + */ static cancelable = false; constructor(data) { @@ -14,23 +31,29 @@ export default class AbstractEvent { this.data = data; } + /** + * Read-only type + * @abstract + * @return {String} + */ get type() { return this.constructor.type; } + /** + * Read-only cancelable + * @abstract + * @return {Boolean} + */ get cancelable() { return this.constructor.cancelable; } /** - * Cancels a specific event + * Cancels the event instance * @abstract */ cancel() { - // We should be declaring if events are cancelable - // if (!this.cancelable) { - // throw new Error('This event is not cancelable'); - // } this._canceled = true; } diff --git a/src/shared/AbstractEvent/README.md b/src/shared/AbstractEvent/README.md index 9787ff50..6011be0a 100644 --- a/src/shared/AbstractEvent/README.md +++ b/src/shared/AbstractEvent/README.md @@ -1 +1,26 @@ -## Abstract Event +## Abstract event + +| | | +| --------------------- | ---------------------------------------------------------- | +| **Specification** | `AbstractEvent` | +| **Interface** | `AbstractEvent` | +| **Cancelable** | false | +| **Cancel action** | - | +| **type** | `event` | + +### API + +**`new AbstractEvent(data: Object): AbstractEvent`** +Creates an `AbstractEvent` instance. + +**`abstractEvent.cancel(data: Object): null`** +Cancels drag start event. + +**`abstractEvent.canceled(): Boolean`** +Checks if event has been canceled. + +**`abstractEvent.type: String`** +Read-only property to find out event type + +**`abstractEvent.cancelable: String`** +Read-only property to check if event is cancelable diff --git a/webpack.config.js b/webpack.config.js index d44b0f46..e2723277 100644 --- a/webpack.config.js +++ b/webpack.config.js @@ -45,6 +45,7 @@ module.exports = [ createConfig({name: 'Plugins', filename: 'plugins', source: 'Plugins/index'}), createConfig({name: 'Collidable', filename: 'collidable', path: 'plugins/', source: 'Plugins/Collidable/index'}), createConfig({name: 'Snappable', filename: 'snappable', path: 'plugins/', source: 'Plugins/Snappable/index'}), + createConfig({name: 'SwapAnimation', filename: 'swap-animation', path: 'plugins/', source: 'Plugins/SwapAnimation/index'}), createConfig({name: 'utils', filename: 'utils', source: 'shared/utils/index'}), ];