@shopify/draggable - npm Package Compare versions

Comparing version 1.0.0-beta to 1.0.0-beta.2

package.json

 {
   "name": "@shopify/draggable",
-  "version": "1.0.0-beta",
+  "version": "1.0.0-beta.2",
   "private": false,
@@ -5,0 +5,0 @@ "license": "MIT",

README.md

@@ -5,28 +5,32 @@ <a href="https://circleci.com/gh/Shopify/draggable">
 
+<hr/>
+
 <a href="https://shopify.github.io/draggable" title="Visit Draggable website">
   <img src="https://user-images.githubusercontent.com/643944/30787041-84ccc1aa-a14e-11e7-982d-972978185636.png" alt="">
 </a>
+
 <hr/>
 
-**Warning: Draggable is still in beta version**
 
-Get complete control over drag and drop behavior with Draggable! Draggable abstracts
+> **Warning:** Draggable is currently in beta
+
+Get complete control over drag and drop behaviour with Draggable! Draggable abstracts
 native browser events into a comprehensive API to create a custom drag and drop experience.
 `Draggable` comes with additional modules: `Sortable`, `Droppable`, `Swappable`. Draggable
-itself does not perform any sorting behavior while dragging, but does the heavy lifting, e.g.
+itself does not perform any sorting behaviour while dragging, but does the heavy lifting, e.g.
 creates mirror, emits events, manages sensor events, makes elements draggable.
 
 The additional modules are built on top of `Draggable` and therefore provide a similar API
-interface, read the documentation below.
+interface, for more information read the documentation below.
 
 **Features**
 - Works with native drag, mouse, touch and force touch events
-- Can extend dragging behavior by hooking into draggables event life cycle
+- Can extend dragging behaviour by hooking into draggables event life cycle
 - Can extend drag detection by adding sensors to draggable
-- The library is modular, so you can require what you need only
+- The library is targeted ES6 first
 
 ## Table of Contents
 
-* [Install](#Install)
-* [Draggable](#draggable-1)
+* [Install](#install)
+* [Draggable](#draggable)
   * [API](#api)
@@ -58,3 +62,6 @@ * [Options](#options)
   * [Snappable](#snappable)
+* [Known issues](#known-issues)
 * [Contributing](#contributing)
+* [Roadmap](#roadmap)
+* [Copyright](#copyright)
 
@@ -75,2 +82,8 @@ ## Install
 
+or via CDN
+
+```
+<script src="https://cdn.jsdelivr.net/npm/@shopify/draggable@1.0.0-beta/lib/draggable.js"></script>
+```
+
 ## Draggable
@@ -80,3 +93,3 @@
 
-**`new Draggable(containers: Array[HTMLElement]|NodeList, options: Object): Draggable`**
+**`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.
@@ -86,14 +99,14 @@ `[document.body]` would work too. The second argument is an options object, which is described
 
-**`draggable.on(eventName: String, listener: Function): Draggable`**
+**`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`**
+**`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`**
+**`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`**
+**`draggable.destroy(): void`**  
 Detaches all sensors and listeners, and cleans up after itself.
@@ -103,24 +116,28 @@
 
-**`draggable {String}`**
+**`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
+**`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
+**`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 behavior. By default
-it will use mouse events to detect drag behavior. You can only customize the mirror element when
+**`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 behavior to Draggable by hooking into its life cycle, e.g. one of the default
-plugins controls the mirror movement. Default: `[Mirror, Accessibility]`
+**`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: `[]`
 
-**`classes {Object}`**
+**`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
@@ -178,3 +195,3 @@ on elements in certain states.
 
-**`new Sortable(containers: Array[HTMLElement]|NodeList, options: Object): Sortable`**
+**`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.
@@ -184,14 +201,14 @@ `[document.body]` would work too. The second argument is an options object, which is described
 
-**`sortable.on(eventName: String, listener: Function): Sortable`**
+**`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`**
+**`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`**
+**`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`**
+**`sortable.destroy(): void`**  
 Detaches all sensors and listeners, and cleans up after itself.
@@ -231,9 +248,7 @@
 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`.
 
-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 Droppable(containers: Array[HTMLElement]|NodeList, options: Object): Droppable`**
+**`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.
@@ -243,14 +258,14 @@ `[document.body]` would work too. The second argument is an options object, which is described
 
-**`droppable.on(eventName: String, listener: Function): Droppable`**
+**`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`**
+**`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`**
+**`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`**
+**`droppable.destroy(): void`**  
 Detaches all sensors and listeners, and cleans up after itself.
@@ -260,3 +275,3 @@
 
-**`droppable {String|Array[HTMLElement]|NodeList|Function}`**
+**`droppable {String|Array[HTMLElement]|NodeList|Function}`**  
 A css selector string, an array of elements, a NodeList or a function returning elements for droppable
@@ -291,4 +306,4 @@ elements within the `containers` specified.
 
-droppable.on('droppable:over', () => console.log('sortable:start'))
-droppable.on('droppable:out', () => console.log('sortable:sorted'));
+droppable.on('droppable:over', () => console.log('droppable:over'))
+droppable.on('droppable:out', () => console.log('droppable:out'));
 ```
@@ -303,3 +318,3 @@
 
-**`new Swappable(containers: Array[HTMLElement]|NodeList, options: Object): Swappable`**
+**`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.
@@ -309,14 +324,14 @@ `[document.body]` would work too. The second argument is an options object, which is described
 
-**`swappable.on(eventName: String, listener: Function): Swappable`**
+**`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`**
+**`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`**
+**`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`**
+**`droppable.destroy(): void`**  
 Detaches all sensors and listeners, and cleans up after itself.
@@ -363,7 +378,7 @@
 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.
+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}`**
+**`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
@@ -382,5 +397,5 @@ elements.
 ```js
-import {Draggable, Collidable} from '@shopify/draggable';
+import {Sortable, Collidable} from '@shopify/draggable';
 
-const draggable = new Draggable(document.querySelectorAll('ul'), {
+const sortable = new Sortable(document.querySelectorAll('ul'), {
   draggable: 'li',
@@ -391,4 +406,4 @@ collidables: '.other-list',
 
-swappable.on('collidable:in', () => console.log('collidable:in'))
-swappable.on('collidable:out', () => console.log('collidable:out'));
+sortable.on('collidable:in', () => console.log('collidable:in'));
+sortable.on('collidable:out', () => console.log('collidable:out'));
 ```
@@ -415,5 +430,5 @@
 ```js
-import {Draggable, Snappable} from '@shopify/draggable';
+import {Sortable, Snappable} from '@shopify/draggable';
 
-const draggable = new Draggable(document.querySelectorAll('ul'), {
+const sortable = new Sortable(document.querySelectorAll('ul'), {
   draggable: 'li',
@@ -423,6 +438,11 @@ plugins: [Snappable]
 
-swappable.on('snap:in', () => console.log('snap:in'))
-swappable.on('snap:out', () => console.log('snap:out'));
+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
+
 ## Contributing
@@ -432,7 +452,3 @@
 
-1. Clone the repo: `git clone [e-mail]:Shopify/draggable`
-2. `cd draggable`
-3. `yarn install` or `npm install`
-4. Run tests with `yarn test` or `npm run test`
-5. Submit PR
+For more information, please checkout the [contribution document](https://github.com/Shopify/draggable/blob/master/CONTRIBUTION.md).
 
@@ -439,0 +455,0 @@ ## Roadmap

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

214296

increased by12.7%

Number of package files

5

increased by25%

Lines of code

5221

increased by15.25%

Number of lines in readme file

442

increased by3.76%

No dependency changes