Use position/defaultPosition for controlled/uncontrolled behavior.

Misc. cleanup.

See #140 for context.

Author: STRML

.eslintrc

@@ -8,11 +8,13 @@
     "quotes": [1, "single"],
     "curly": [1, "multi-line"],
     "camelcase": 0,
-    "comma-dangle": 1,
+    "comma-dangle": 0,
+    "no-console": 2,
     "no-use-before-define": [1, "nofunc"],
     "no-underscore-dangle": 0,
     "no-unused-vars": 1,
     "new-cap": 0,
+    "prefer-const": 1,
     "semi": 1
   },
   env: {

.flowconfig

@@ -13,8 +13,8 @@ suppress_comment=\\(.\\|\n\\)*\\s*\\$FlowBug.*
 suppress_comment=\\(.\\|\n\\)*\\s*\\$FlowIgnore.*
 suppress_comment=\\(.\\|\n\\)*\\s*\\$FlowNewLine.*
 suppress_comment=\\(.\\|\n\\)*\\s*\\$FlowIssue
-esproposal.class_instance_fields=ignore
-esproposal.class_static_fields=ignore
+esproposal.class_instance_fields=enable
+esproposal.class_static_fields=enable
 module.file_ext=.js
 module.file_ext=.jsx
 module.file_ext=.es5

CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+### 2.0.0-beta1 (Apr 14, 2016)
+
+- Due to API changes, this is a major release.
+
+#### Breaking Changes:
+
+- Both `<DraggableCore>` and `<Draggable>` have had their callback types changed and unified.
+
+```js
+type DraggableEventHandler = (e: Event, data: DraggableData) => void | false;
+type DraggableData = {
+  node: HTMLElement,
+  // lastX + deltaX === x
+  x: number, y: number,
+  deltaX: number, deltaY: number,
+  lastX: number, lastY: number
+};
+```
+
+- The `start` option has been renamed to `defaultPosition`.
+- The `zIndex` option has been removed.
+
+#### Possibly Breaking Changes:
+
+- When determining deltas, we now use a new method that checks the delta against the Draggable's `offsetParent`.
+  This method allows us to support arbitrary nested scrollable ancestors without scroll handlers!
+  - This may cause issues in certain layouts. If you find one, please open an issue.
+
+#### Enhancements:
+
+- `<Draggable>` now has a `position` attribute. Its relationship to `defaultPosition` is much like
+  `value` to `defaultValue` on React `<input>` nodes. If set, the position is fixed and cannot be mutated.
+  If empty, the component will manage its own state. See [#140](https://github.com/mzabriskie/react-draggable/pull/140)
+  for more info & motivations.
+- Misc. bugfixes.
+
 ### 1.4.0-beta1 (Apr 13, 2016)
 
 - Major improvements to drag tracking that now support even nested scroll boxes.
@@ -11,7 +47,7 @@
 
 ### 1.3.6 (Apr 8, 2016)
 
-- Republish after 1.3.5 contained a bundling error.
+- Republished after 1.3.5 contained a bundling error.
 
 ### 1.3.5 (Apr 8, 2016)
 

README.md

@@ -67,46 +67,15 @@ React.DOM elements support the above six properties by default, so you may use t
 Props:
 
 ```js
+type DraggableEventHandler = (e: Event, data: DraggableData) => void | false;
+type DraggableData = {
+  node: HTMLElement,
+  // lastX + deltaX === x
+  x: number, y: number,
+  deltaX: number, deltaY: number,
+  lastX: number, lastY: number
+};
 {
-// 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,
-
 // If set to `true`, will allow dragging on non left-button clicks.
 allowAnyClick: boolean,
 
@@ -127,11 +96,44 @@ axis: string,
 //   can be moved.
 bounds: {left: number, top: number, right: number, bottom: number} | string,
 
+// Specifies a selector to be used to prevent drag initialization.
+// Example: '.body'
+cancel: string,
+
+// 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.
+defaultPosition: {x: number, y: number},
+
+// If true, will not call any drag handlers.
+disabled: boolean,
+
 // Specifies the x and y that dragging should snap to.
 grid: [number, number],
 
-// Specifies the zIndex to use while dragging.
-zIndex: number
+// Specifies a selector to be used as the handle that initiates drag.
+// Example: '.handle'
+handle: string,
+
+// Called whenever the user mouses down. Called regardless of handle or
+// disabled status.
+onMouseDown: (e: MouseEvent) => boolean,
+
+// Called when dragging starts. If `false` is returned any handler,
+// the action will cancel.
+onStart: DraggableEventHandler,
+
+// Called while dragging.
+onDrag: DraggableEventHandler,
+
+// Called when dragging stops.
+onStop: DraggableEventHandler,
+
+// Much like React form elements, if this property is present, the item
+// becomes 'controlled' and is not responsive to user input. Use `position`
+// if you need to have direct control of the element.
+position: {x: number, y: number}
 }
 ```
 
@@ -168,7 +170,8 @@ var App = React.createClass({
 			<Draggable
 				axis="x"
 				handle=".handle"
-				start={{x: 0, y: 0}}
+				defaultPosition={{x: 0, y: 0}}
+        position={null}
 				grid={[25, 25]}
 				zIndex={100}
 				onStart={this.handleStart}
@@ -198,28 +201,39 @@ on itself.
 
 ### DraggableCore API
 
-`<DraggableCore>` takes all of the above `<Draggable>` options, with the exception of:
+`<DraggableCore>` takes a limited subset of options:
+
+```js
+{
+  allowAnyClick: boolean,
+  cancel: string,
+  disabled: boolean,
+  enableUserSelectHack: boolean,
+  grid: [number, number],
+  handle: string,
+  onStart: DraggableEventHandler,
+  onDrag: DraggableEventHandler,
+  onStop: DraggableEventHandler
+  onMouseDown: (e: MouseEvent) => void
+}
+```
 
-* `axis`
-* `bounds`
-* `start`
-* `zIndex`
+Note that there is no start position. `<DraggableCore>` simply calls `drag` handlers with the below parameters,
+indicating its position (as inferred from the underlying MouseEvent) and deltas. It is up to the parent
+to set actual positions on `<DraggableCore>`.
 
-Drag callbacks are called with the following parameters:
+Drag callbacks (`onDragStart`, `onDrag`, `onDragEnd`) are called with the following parameters:
 
 ```js
 (
- event: Event,
- ui:{
-      node: Node
-      position:
-        {
-        	// lastX + deltaX === clientX
-          deltaX: number, deltaY: number,
-          lastX: number, lastY: number,
-          clientX: number, clientY: number
-        }
-    }
+  event: Event,
+  data: {
+    node: HTMLElement,
+  	// lastX + deltaX === x
+    x: number, y: number,
+    deltaX: number, deltaY: number,
+    lastX: number, lastY: number
+  }
 )
 ```