Merge pull request #9 from lemonde/yej-20150805-enhancements

feat(handlers): add dragenter handler + preventDefaults + more tests + dragging class + debug hooks

.editorconfig

@@ -0,0 +1,15 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+
+indent_style = space
+indent_size = 2
+
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.jshintrc

@@ -0,0 +1,53 @@
+{
+  "bitwise": true,
+  "camelcase": true,
+  "curly": false,
+  "eqeqeq": true,
+  "es3": false,
+  "forin": true,
+  "immed": true,
+  "indent": 2,
+  "latedef": "nofunc",
+  "newcap": true,
+  "noarg": true,
+  "noempty": true,
+  "nonew": false,
+  "plusplus": false,
+  "quotmark": true,
+  "regexp": false,
+  "undef": true,
+  "unused": true,
+  "strict": true,
+  "trailing": true,
+  "maxparams": 4,
+  "maxdepth": 2,
+  "maxstatements": 30,
+  "maxcomplexity": 10,
+  "maxlen": 110,
+
+  "asi": false,
+  "boss": false,
+  "debug": false,
+  "eqnull": true,
+  "esnext": false,
+  "evil": false,
+  "expr": false,
+  "funcscope": false,
+  "globalstrict": false,
+  "iterator": false,
+  "lastsemic": false,
+  "laxbreak": false,
+  "laxcomma": false,
+  "loopfunc": false,
+  "moz": false,
+  "multistr": true,
+  "proto": false,
+  "scripturl": false,
+  "smarttabs": false,
+  "shadow": false,
+  "sub": false,
+  "supernew": false,
+  "validthis": true,
+
+  "node": true
+}

README.md

@@ -1,10 +1,28 @@
 # angular-draganddrop
 [![Build Status](https://travis-ci.org/lemonde/angular-draganddrop.svg?branch=master)](https://travis-ci.org/lemonde/angular-draganddrop)
-[![Dependency Status](https://david-dm.org/neoziro/angular-draganddrop.svg?theme=shields.io)](https://david-dm.org/neoziro/angular-draganddrop)
-[![devDependency Status](https://david-dm.org/neoziro/angular-draganddrop/dev-status.svg?theme=shields.io)](https://david-dm.org/neoziro/angular-draganddrop#info=devDependencies)
+[![Dependency Status](https://david-dm.org/lemonde/angular-draganddrop.svg?theme=shields.io)](https://david-dm.org/lemonde/angular-draganddrop)
+[![devDependency Status](https://david-dm.org/lemonde/angular-draganddrop/dev-status.svg?theme=shields.io)](https://david-dm.org/lemonde/angular-draganddrop#info=devDependencies)
 
 Drag and drop directives for Angular using native HTML5 API.
 
+
+## introduction
+
+This module is a simple Angular wrapping of the native HTML5 drag & drop API + a few common utilities.
+Callbacks are invoked in Angular context.
+
+It defines 2 directives :
+* "draggable" for a draggable element
+* "drop" for a drop zone
+It handles data type control, adding a CSS class on drag and on hover and takes care of one HTML5 quirk.
+
+**CAUTION** The HTML5 drag&drop API is NOT trivial.
+* If you know it and want to use it, proceed with this package
+* If you don't know it, consider using a 3rd-party re-implementation : http://www.quirksmode.org/blog/archives/2009/09/the_html5_drag.html
+* Reference doc for drag&drop API :
+ * https://html.spec.whatwg.org/multipage/interaction.html#dnd
+
+
 ## Install
 
 ### Using bower
@@ -19,9 +37,11 @@ bower install angular-draganddrop
 npm install angular-draganddrop
 ```
 
+
 ## Usage
 
-HTML :
+1. read the warning in introduction (really)
+2. HTML :
 
 ```html
 <!-- Load files. -->
@@ -39,7 +59,7 @@ HTML :
 </div>
 ```
 
-JavaScript :
+3. JavaScript :
 
 ```js
 angular.module('controllers.dragDrop', ['draganddrop'])
@@ -65,22 +85,36 @@ angular.module('controllers.dragDrop', ['draganddrop'])
 
 ### "draggable" directive
 
+Parameters :
 - "draggable" Make the element draggable. Accepts a boolean.
 - "effect-allowed" Allowed effects for the dragged element, see https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer#effectAllowed.28.29. Accepts a string.
 - "draggable-type" Type of data object attached to the dragged element, this type is prefixed by "json/". Accepts a string.
 - "draggable-data" Data attached to the dragged element, data are serialized in JSON. Accepts an Angular expression.
+- "dragging-class" Class set during the drag. Accepts a string.
+- "drag-start" (optional) an Angular expression to be evaluated on drag start ("dragstart" event).
+- "drag-end" (optional) an Angular expression to be evaluated on drag end ("dragend" event).
 
 The draggable directive serializes data as JSON and prefix the specified type with "json/".
 
 ### "drop" directive
 
+The drop directive automatically :
+- calls the event.preventDefault() for dragenter and dragleave, as asked in the spec
+- unserializes data with the "json" format, other data are not formatted
+- throttles the dragover event (200ms) to avoid burning your CPU during the drag&drop
+
+Parameters :
 - "drop" Drop handler, executed on drop. Accepts an Angular expression.
 - "drop-effect" Drop effect to set, see https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer#dropEffect.28.29. Accepts a string.
 - "drop-accept" Types accepted or function to prevent unauthorized drag and drop. Accepts a string, an array, a function or a boolean.
-- "drag-over" Drag over handler, executed on drag over. Accepts an Angular expression.
 - "drag-over-class" Class set on drag over, when the drag is authorized. Accepts a string.
+- "drag-over" (optional) an Angular expression to be evaluated on drag over ("dragover" event).
+- "drag-enter" (optional) an Angular expression to be evaluated on drag enter ("dragenter" event).
+- "drag-leave" (optional) an Angular expression to be evaluated on drag leave ("dragleave" event).
+- "drop" (optional) an Angular expression to be evaluated on drag over ("drop" event).
+
+Handlers are called with : `(data, event)`
 
-The drop directive automatically unserializes data with the "json" format, other data are not formatted.
 
 ## Browsers support