Add deltaX and deltaY to callback, update README and examples.

STRML · STRML · commit d3b44ee03b49 · 2015-10-27T17:28:15.000-04:00
diff --git a/README.md b/README.md
@@ -1,27 +1,28 @@
-# react-draggable [![Build Status](https://travis-ci.org/mzabriskie/react-draggable.svg?branch=master)](https://travis-ci.org/mzabriskie/react-draggable)
+# React-Draggable [![Build Status](https://travis-ci.org/mzabriskie/react-draggable.svg?branch=master)](https://travis-ci.org/mzabriskie/react-draggable)
 
 A simple component for making elements draggable.
 
 [View the Changelog](CHANGELOG.md)
 
-## Demo
+### Demo
 
 [View Demo](http://mzabriskie.github.io/react-draggable/example/)
 
 
-## Installing
+### Installing
 
 ```bash
 $ npm install react-draggable
 ```
 
 If you aren't using browserify/webpack, a
 [UMD version of react-draggable](dist/react-draggable.js) is available. It is updated per-release only.
+This bundle is also what is loaded when installing from npm. It expects external `React` and `ReactDOM`.
 
 If you want a UMD version of the latest `master` revision, you can generate it yourself from master by cloning this
 repository and running `$ make`. This will create umd dist files in the `dist/` folder.
 
-## Details
+## Draggable
 
 A `<Draggable>` element wraps an existing element and extends it with new event handlers and styles.
 It does not create a wrapper element in the DOM.
@@ -32,41 +33,83 @@ positioning (relative, absolute, or static). Elements can also be moved between
 If the item you are dragging already has a CSS Transform applied, it will be overwritten by `<Draggable>`. Use
 an intermediate wrapper (`<Draggable><span>...</span></Draggable>`) in this case.
 
-## API
+
+### Draggable API
+
 The `<Draggable/>` component transparently adds draggable to whatever element is supplied as `this.props.children`.
 **Note**: Only a single element is allowed or an Error will be thrown.
 
 Props:
 
-**`axis`**: determines which axis the draggable can move. Accepted values:
-- `both` allows movement horizontally and vertically (default).
-- `x` limits movement to horizontal axis.
-- `y` limits movement to vertical axis.
-
-**`handle`**: specifies a selector to be used as the handle that initiates drag.
-
-**`cancel`**: specifies a selector to be used to prevent drag initialization.
-
-**`grid`**: specifies the x and y that dragging should snap to.
-
-**`bounds`**: specifies movement boundaries. Accepted values:
-- `parent` restricts movement within the node's offsetParent (nearest node with position relative or absolute), or
-- An object with `left, top, right, and bottom` properties. These indicate how far in each direction the draggable can be moved. See [example/index.html](https://github.com/mzabriskie/react-draggable/blob/master/example/index.html) for more on this.
-
-**`start`**: specifies the `x` and `y` that the dragged item should start at. This is generally not necessary to use (you can use absolute or relative positioning of the child directly), but can be helpful for uniformity in your callbacks and with css transforms.
-
-**`moveOnStartChange`**: if true (it defaults false), will move the element if there is a change in `start`. We set this by default to `false` because it can cause unwanted effects if you are not aware of it.
-
-**`zIndex`**: specifies the zIndex to use while dragging.
-
-**`onStart`**: called when dragging starts.
+```js
+{
+// Called when dragging starts. If `false` is returned from this method,
+// dragging will cancel.
+// These callbacks are called with the arity
+// (event: Event,
+//  {
+//     position: {left: number, top: number},
+//     deltaX: number,
+//     deltaY: number
+//  }
+// )
+onStart: Function,
+
+// Called while dragging.
+onDrag: Function,
+
+// Called when dragging stops.
+onStop: Function,
+
+// Called whenever the user mouses down. Called regardless of handle or
+//  disabled status.
+onMouseDown: Function,
+
+// Specifies the `x` and `y` that the dragged item should start at.
+// This is generally not necessary to use (you can use absolute or relative
+// positioning of the child directly), but can be helpful for uniformity in
+// your callbacks and with css transforms.
+start: {x: number, y: number},
+
+// If true, will not call any drag handlers.
+disabled: boolean,
+
+// Specifies a selector to be used to prevent drag initialization.
+// Example: '.body'
+cancel: string,
+
+// Specifies a selector to be used as the handle that initiates drag.
+// Example: '.handle'
+handle: string,
+
+// Determines which axis the draggable can move. Accepted values:
+// - `both` allows movement horizontally and vertically (default).
+// - `x` limits movement to horizontal axis.
+// - `y` limits movement to vertical axis.
+axis: string,
+
+// Specifies movement boundaries. Accepted values:
+// - `parent` restricts movement within the node's offsetParent
+//    (nearest node with position relative or absolute), or
+// - An object with `left, top, right, and bottom` properties.
+//   These indicate how far in each direction the draggable
+//   can be moved.
+bounds: {left: number, top: number, right: number, bottom: number} | string,
+
+// Specifies the x and y that dragging should snap to.
+grid: [number, number],
+
+// Specifies the zIndex to use while dragging.
+zIndex: number
+}
+```
 
-**`onDrag`**: called while dragging.
 
-**`onStop`**: called when dragging stops.
+Note that sending `className`, `style`, or `transform` as properties will error - set them on the child element
+directly.
 
 
-## Example usage
+### Draggable Usage
 
 ```js
 /** @jsx React.DOM */
@@ -81,12 +124,12 @@ var App = React.createClass({
 
 	handleDrag: function (event, ui) {
 		console.log('Event: ', event);
-        console.log('Position: ', ui.position);
+    console.log('Position: ', ui.position);
 	},
 
 	handleStop: function (event, ui) {
 		console.log('Event: ', event);
-        console.log('Position: ', ui.position);
+    console.log('Position: ', ui.position);
 	},
 
 	render: function () {
@@ -113,40 +156,60 @@ var App = React.createClass({
 React.renderComponent(<App/>, document.body);
 ```
 
-## State Problems?
+## <DraggableCore>
+
+For users that require more control, a `<DraggableCore>` element is available. This is useful for more programmatic
+usage of the element. See [React-Resizable](https://github.com/STRML/react-resizable) and
+[React-Grid-Layout](https://github.com/STRML/react-grid-layout) for some examples of this.
 
-`<Draggable>` is a stateful component. This means that it is storing its current drag offsets in its internal state.
-This can cause problems with certain integrations. For example, if you change the position of the element manually,
-`<Draggable>` can get into trouble as it assumes a translation in the DOM. If you see an element jump around the page
-when you click it, this is affecting you.
+`<DraggableCore>` is a useful building block for other libraries that simply want to abstract browser-specific
+quirks and receive callbacks when a user attempts to move an element. It does not set styles or transforms
+on itself.
 
-This is an unfortunate side-effect of dragging, which is inherently stateful.
+### DraggableCore API
 
-If you move the element manually, you have two options:
+`<DraggableCore>` takes all of the above `<Draggable>` options, with the exception of:
 
-1. Feed the `<Draggable>` an `x` and `y` parameter in the `start` param, and change it as you go while setting
-`moveOnStartChange` to `true`, or,
-2. When moving the `<Draggable>`, ref the element and
-[call `resetState()`](https://github.com/STRML/react-resizable/blob/master/lib/Resizable.jsx#L48).
+* `axis`
+* `bounds`
+* `grid`
+* `start`
+* `zIndex`
+
+Drag callbacks are called with the following parameters:
+
+```js
+{
+  node: Node
+  position:
+    {
+    	// lastX + deltaX === clientX
+      deltaX: number, deltaY: number,
+      lastX: number, lastY: number,
+      clientX: number, clientY: number
+    }
+};
+```
 
+----
 
-## Contributing
+### Contributing
 
 - Fork the project
-- Run the project in development mode: `$ make dev`
+- Run the project in development mode: `$ npm run dev`
 - Make changes.
 - Add appropriate tests
-- `$ make test`
+- `$ npm test`
 - If tests don't pass, make them pass.
 - Update README with appropriate docs.
 - Commit and PR
 
-## Release checklist
+### Release checklist
 
 - Update CHANGELOG
 - `make release-patch`, `make release-minor`, or `make-release-major`
 - `make publish`
 
-## License
+### License
 
 MIT
diff --git a/example/index.html b/example/index.html
@@ -48,24 +48,29 @@
   </style>
 </head>
 <body>
-<script src="//cdnjs.cloudflare.com/ajax/libs/react/0.13.3/react-with-addons.min.js"></script>
-<script src="//cdnjs.cloudflare.com/ajax/libs/react/0.13.3/JSXTransformer.js"></script>
+<script src="//cdnjs.cloudflare.com/ajax/libs/react/0.14.0/react.min.js"></script>
+<script src="//cdnjs.cloudflare.com/ajax/libs/react/0.14.0/react-dom.min.js"></script>
+<script src="//cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.29/browser.min.js"></script>
 <script src="../dist/react-draggable.js"></script>
-<script type="text/jsx">
+<script type="text/babel">
   var Draggable = ReactDraggable;
   var App = React.createClass({
     getInitialState: function () {
       return {
-        position: {
+        deltaPosition: {
           top: 0, left: 0
         },
         activeDrags: 0
       };
     },
 
     handleDrag: function (e, ui) {
+      var {left, top} = this.state.position;
       this.setState({
-        position: ui.position
+        deltaPosition: {
+          left: left + ui.deltaX,
+          top: top + ui.deltaY,
+        }
       });
     },
 
@@ -79,6 +84,7 @@
 
     render: function () {
       var drags = {onStart: this.onStart, onStop: this.onStop};
+      var {top. left} = this.state.deltaPosition;
       return (
         <div>
           <h1>React Draggable</h1>
@@ -97,8 +103,8 @@ <h1>React Draggable</h1>
           </Draggable>
           <Draggable onDrag={this.handleDrag} {...drags}>
             <div className="box">
-              <div>I track my position</div>
-              <div>top: {this.state.position.top.toFixed(0)}, left: {this.state.position.left.toFixed(0)}</div>
+              <div>I track my deltas</div>
+              <div>top: {top.toFixed(0)}, left: {left.toFixed(0)}</div>
             </div>
           </Draggable>
           <Draggable handle="strong" {...drags}>
diff --git a/lib/utils/domFns.es6 b/lib/utils/domFns.es6
@@ -155,6 +155,8 @@ export function createUIEvent(draggable, coreEvent) {
     position: {
       top: coreEvent.position.clientY,
       left: coreEvent.position.clientX
-    }
+    },
+    deltaX: coreEvent.position.deltaX,
+    deltaY: coreEvent.position.deltaY
   };
 }
diff --git a/webpack.config.js b/webpack.config.js
@@ -17,7 +17,12 @@ module.exports = {
       // React dep should be available as window.React, not window.react
       'root': 'React'
     },
-    'react-dom': 'react-dom'
+    'react-dom': {
+      'commonjs': 'react-dom',
+      'commonjs2': 'react-dom',
+      'amd': 'react-dom',
+      'root': 'ReactDOM'
+    }
   },
 	module: {
 		loaders: [
