Merge pull request #1428 from bitovi/998-event-docs-and-fixes

add/remove events always give you back arrays

list/list.js

@@ -115,7 +115,7 @@ steal("can/util", "can/map", "can/map/bubble.js",function (can, Map, bubble) {
 				// `batchTrigger` direct add and remove events...
 				var index = +attr;
 				// Make sure this is not nested and not an expando
-				if (!~attr.indexOf('.') && !isNaN(index)) {
+				if (!~(""+attr).indexOf('.') && !isNaN(index)) {
 
 					if (how === 'add') {
 						can.batch.trigger(this, how, [newVal, index]);
@@ -141,6 +141,23 @@ steal("can/util", "can/map", "can/map/bubble.js",function (can, Map, bubble) {
 					return this;
 				}
 			},
+			__set: function (prop, value, current) {
+				// We want change events to notify using integers if we're
+				// setting an integer index. Note that <float> % 1 !== 0;
+				prop = isNaN(+prop) || (prop % 1) ? prop : +prop;
+
+				// Check to see if we're doing a .attr() on an out of
+				// bounds index property.
+				if (typeof prop === "number" &&
+					prop > this.length - 1) {
+					var newArr = new Array((prop + 1) - this.length);
+					newArr[newArr.length-1] = value;
+					value = newArr;
+					prop = this.length;
+				}
+
+				return can.Map.prototype.__set.call(this, ""+prop, value, current);
+			},
 			___set: function (attr, val) {
 				this[attr] = val;
 				if (+attr >= this.length) {
@@ -490,8 +507,7 @@ steal("can/util", "can/map", "can/map/bubble.js",function (can, Map, bubble) {
 			 *
 			 * - _ev_ The event object.
 			 * - _newElements_ The new elements.
-			 * If more than one element is added, _newElements_ will be an array.
-			 * Otherwise, it is simply the new element itself.
+			 * An array of zero or more elements that were added.
 			 * - _index_ Where the add or insert took place.
 			 *
 			 * Here is a concrete tour through the _add_ event handler's arguments:
@@ -518,8 +534,7 @@ steal("can/util", "can/map", "can/map/bubble.js",function (can, Map, bubble) {
 			 *
 			 * - _ev_ The event object.
 			 * - _removedElements_ The removed elements.
-			 * If more than one element was removed, _removedElements_ will be an array.
-			 * Otherwise, it is simply the element itself.
+			 * An array of zero or more elements that were removed.
 			 * - _index_ Where the removal took place.
 			 *
 			 * Here is a concrete tour through the _remove_ event handler's arguments:
@@ -804,6 +819,11 @@ steal("can/util", "can/map", "can/map/bubble.js",function (can, Map, bubble) {
 		// Creates a `remove` type method
 		function (where, name) {
 			list.prototype[name] = function () {
+				if (!this.length) {
+					// For shift and pop, we just return undefined without
+					// triggering events.
+					return undefined;
+				}
 
 				var args = getArgs(arguments),
 					len = where && this.length ? this.length - 1 : 0;

list/list_test.js

@@ -234,4 +234,42 @@ steal("can/util", "can/list", "can/test", "can/compute", function(){
 		list.splice(0,2,"a","b");
 	});
 
+	test("add event always returns an array as the value (#998)", function() {
+		var list = new can.List([]),
+			msg;
+		list.bind("add", function(ev, newElements, index) {
+			deepEqual(newElements, [4], msg);
+		});
+		msg = "works on push";
+		list.push(4);
+		list.pop();
+		msg = "works on attr()";
+		list.attr(0, 4);
+		list.pop();
+		msg = "works on replace()";
+		list.replace([4]);
+	});
+
+	test("Setting with .attr() out of bounds of length triggers add event with leading undefineds", function() {
+		var list = new can.List([1]);
+		list.bind("add", function(ev, newElements, index) {
+			deepEqual(newElements, [undefined, undefined, 4],
+					  "Leading undefineds are included");
+			equal(index, 1, "Index takes into account the leading undefineds from a .attr()");
+		});
+		list.attr(3, 4);
+	});
+
+	test("No events should fire if removals happened on empty arrays", function() {
+		var list = new can.List([]),
+			msg;
+		list.bind("remove", function(ev, removed, index) {
+			ok(false, msg);
+		});
+		msg = "works on pop";
+		list.pop();
+		msg = "works on shift";
+		list.shift();
+		ok(true, "No events were fired.");
+	});
 });