Adds remove method to layer (#63).

examples/scripts/bar-chart.js

@@ -34,8 +34,7 @@ d3.chart("BarChart", {
 
     function onExitTrans() {
       this.duration(1000)
-          .attr("x", function(d, i) { return chart.x(i - 1) - .5; })
-          .remove();
+          .attr("x", function(d, i) { return chart.x(i - 1) - .5; });
     }
 
     function dataBind(data) {

src/layer-extensions.js

@@ -13,9 +13,12 @@ d3.selection.prototype.layer = function(options) {
 	var layer = new Layer(this);
 	var eventName;
 
-	// Set layer methods (required)
+	// Set layer methods (databind/insert required, remove optional)
 	layer.dataBind = options.dataBind;
 	layer.insert = options.insert;
+	if (options.remove) {
+		layer.remove = options.remove;
+	}
 
 	// Bind events (optional)
 	if ("events" in options) {

src/layer.js

@@ -39,6 +39,15 @@ Layer.prototype.insert = function() {
 	d3cAssert(false, "Layers must specify an `insert` method.");
 };
 
+/**
+ * Invoked by {@link Layer#draw} in order to remove exiting DOM nodes from
+ * this layer's `base`. This default implementation may be overridden by
+ * Layer instances.
+ */
+Layer.prototype.remove = function() {
+	this.remove();
+};
+
 /**
  * Subscribe a handler to a "lifecycle event". These events (and only these
  * events) are triggered when {@link Layer#draw} is invoked--see that method
@@ -113,9 +122,12 @@ Layer.prototype.off = function(eventName, handler) {
 
 /**
  * Render the layer according to the input data: Bind the data to the layer
- * (according to {@link Layer#dataBind}, insert new elements (according to
- * {@link Layer#insert}, make lifecycle selections, and invoke all relevant
- * handlers (as attached via {@link Layer#on}) with the lifecycle selections.
+ * (according to {@link Layer#dataBind}), insert new elements (according to
+ * {@link Layer#insert}), make lifecycle selections, invoke all relevant
+ * handlers (as attached via {@link Layer#on}) with the lifecycle selections,
+ * then remove exiting elements (according to {@link Layer#remove}).
+ *
+ * The lifecycle selections are:
  *
  * - update
  * - update:transition
@@ -216,4 +228,6 @@ Layer.prototype.draw = function(data) {
 			}
 		}
 	}
+
+	this.remove.call(selection);
 };

test/tests/layer.js

@@ -49,11 +49,18 @@ suite("d3.layer", function() {
 				sinon.spy(entering, "transition");
 				return entering;
 			});
+			var remove = this.remove = sinon.spy();
 			var base = this.base = d3.select("#test").append("svg");
 
 			this.layer = base.layer({
 				dataBind: dataBind,
-				insert: insert
+				insert: insert,
+			});
+
+			this.layerWithRemove = this.base.append('g').layer({
+				dataBind: dataBind,
+				insert: insert,
+				remove: remove
 			});
 		});
 
@@ -82,7 +89,24 @@ suite("d3.layer", function() {
 			this.layer.draw([]);
 			assert(this.insert.calledOn(this.dataBind.returnValues[0].enter.returnValues[0]));
 		});
-
+		test("by default removes exiting nodes from the DOM", function() {
+			this.layer.draw([1]);
+			assert.equal(this.layer.selectAll('g').size(), 1);
+			this.layer.draw([]);
+			assert.equal(this.layer.selectAll('g').size(), 0);
+		});
+		test("invokes the provided `remove` method in the context of the layer's bound 'exit' selection", function() {
+      var updating, exiting;
+
+			this.layerWithRemove.draw([1, 2, 3]);
+			this.layerWithRemove.draw([]);
+
+      updating = this.dataBind.returnValues[1];
+      exiting = updating.exit.returnValues[0];
+
+			assert(this.remove.calledOn(exiting));
+		});
+
 		suite("event triggering", function() {
 			test("invokes event handlers with the correct selection", function() {
 				var layer = this.base.append("g").layer({
@@ -137,19 +161,25 @@ suite("d3.layer", function() {
 					},
 					insert: function() {
 						return this.append("g");
-					}
+					},
+          remove: function() {
+            return this.remove();
+          }
 				});
 				var enterSpy = sinon.spy();
 				var updateSpy = sinon.spy();
+				var exitSpy = sinon.spy();
 				layer.draw([1]);
 
 				layer.on("enter", enterSpy);
 				layer.on("update", updateSpy);
+				layer.on("exit", exitSpy);
 
 				layer.draw([1]);
 
 				sinon.assert.callCount(enterSpy, 0);
 				sinon.assert.callCount(updateSpy, 1);
+				sinon.assert.callCount(exitSpy, 0);
 			});
 
 			suite("Layer#off", function() {