Add option to specify locking offsets of the helper in the container. (fixes clauderic#21)

Author: ziadkh0

README.md

@@ -102,6 +102,10 @@ More code examples are available [here](https://github.com/clauderic/react-sorta
 | useWindowAsScrollContainer | Boolean  | `false` | If you want, you can set the `window` as the scrolling container                                                                                                                                                             |
 | hideSortableGhost          | Boolean  | `true`  | Whether to auto-hide the ghost element. By default, as a convenience, React Sortable List will automatically hide the element that is currently being sorted. Set this to false if you would like to apply your own styling. |
 | lockToContainerEdges       | Boolean  | `false` | You can lock movement of the sortable element to it's parent `SortableContainer`                                                                                                                                             |
+| lockOffset                 | `OffsetValue`\* \| [`OffsetValue`\*, `OffsetValue`\*] | `"50%"` | When `lockToContainerEdges` is set to `true`, this controls the offset distance between the sortable helper and the top/bottom edges of it's parent `SortableContainer`. Percentage values are relative to the height of the item currently being sorted. If you wish to specify different behaviours for locking to the *top* of the container vs the *bottom*, you may also pass in an `array` (For example: `["0%", "100%"]`). |
+
+\* `OffsetValue` is either a finite `Number` or a `String` made-up of a number and a unit (`px` or `%`).
+Examples: `10` (is the same as `"10px"`), `"50%"`
 
 #### SortableElement HOC
 | Property   | Type             | Default | Required? | Description                                                                                                                                                                                                                               |

src/SortableContainer/index.js

@@ -1,7 +1,7 @@
 import React, {Component, PropTypes} from 'react';
 import ReactDOM from 'react-dom';
 import Manager from '../Manager';
-import {closest, events, vendorPrefix} from '../utils';
+import {closest, events, vendorPrefix, limit} from '../utils';
 import invariant from 'invariant';
 
 // Export Higher Order Sortable Container Component
@@ -25,7 +25,8 @@ export default function SortableContainer(WrappedComponent, config = {withRef: f
 			useWindowAsScrollContainer: false,
 			hideSortableGhost: true,
 			contentWindow: window,
-			lockToContainerEdges: false
+			lockToContainerEdges: false,
+			lockOffset: '50%',
 		};
 		static propTypes = {
 			axis: PropTypes.string,
@@ -40,7 +41,12 @@ export default function SortableContainer(WrappedComponent, config = {withRef: f
 			useDragHandle: PropTypes.bool,
 			useWindowAsScrollContainer: PropTypes.bool,
 			hideSortableGhost: PropTypes.bool,
-			lockToContainerEdges: PropTypes.bool
+			lockToContainerEdges: PropTypes.bool,
+			lockOffset: PropTypes.oneOfType([
+				PropTypes.number,
+				PropTypes.string,
+				PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.number, PropTypes.string]))
+			]),
 		};
 		static childContextTypes = {
 			manager: PropTypes.object.isRequired
@@ -218,6 +224,56 @@ export default function SortableContainer(WrappedComponent, config = {withRef: f
 				y: (e.touches) ? e.touches[0].clientY : e.clientY
 			}
 		}
+		getLockPixelOffsets() {
+			let {lockOffset} = this.props;
+
+			if (!Array.isArray(lockOffset)) {
+				lockOffset = [lockOffset, lockOffset];
+			}
+			invariant(
+				lockOffset.length === 2,
+				'lockOffset prop of SortableContainer should be a single ' +
+				'value or an array of exactly two values. Given %s',
+				lockOffset
+			);
+
+			const [minLockOffset, maxLockOffset] = lockOffset;
+
+			return [
+				this.getLockPixelOffset(minLockOffset),
+				this.getLockPixelOffset(maxLockOffset),
+			];
+		}
+		getLockPixelOffset(lockOffset) {
+			let offset = lockOffset;
+			let unit = 'px';
+
+			if (typeof lockOffset === 'string') {
+				const match = /^[+-]?\d*(?:\.\d*)?(px|%)$/.exec(lockOffset);
+
+				invariant(
+					match !== null,
+					'lockOffset value should be a number or a string of a ' +
+					'number followed by "px" or "%". Given %s',
+					lockOffset
+				);
+
+				offset = parseFloat(lockOffset);
+				unit = match[1];
+			}
+
+			invariant(
+				isFinite(offset),
+				'lockOffset value should be a finite. Given %s',
+				lockOffset
+			);
+
+			if (unit === '%') {
+				offset = offset * this.dimension / 100;
+			}
+
+			return offset;
+		}
 		updatePosition(e) {
 			let {axis, lockAxis, lockToContainerEdges} = this.props;
 			let offset = this.getOffset(e);
@@ -229,11 +285,15 @@ export default function SortableContainer(WrappedComponent, config = {withRef: f
 			this.translate = translate[axis];
 
 			if (lockToContainerEdges) {
-				if (translate[axis] < this.minTranslate) {
-					translate[axis] = this.minTranslate;
-				} else if (translate[axis] > this.maxTranslate) {
-					translate[axis] = this.maxTranslate;
-				}
+				const [minLockOffset, maxLockOffset] = this.getLockPixelOffsets();
+				const minOffset = this.dimension / 2 - minLockOffset;
+				const maxOffset = this.dimension / 2 - maxLockOffset;
+
+				translate[axis] = limit(
+					this.minTranslate + minOffset,
+					this.maxTranslate - maxOffset,
+					translate[axis]
+				);
 			}
 
 			switch (lockAxis) {

src/utils.js

@@ -37,3 +37,13 @@ export function closest(el, fn) {
         el = el.parentNode;
     }
 }
+
+export function limit(min, max, value) {
+    if (value < min) {
+        return min;
+    }
+    if (value > max) {
+        return max;
+    }
+    return value;
+}