add special case for return value of remove operation

gr0uch · Mar 20, 2016 · af32cee · af32cee
1 parent d7b0556
commit af32cee
Show file tree

Hide file tree

Showing 4 changed files with 21 additions and 4 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,14 @@
 # Changelog
 
 
+### 0.12.0 (2016-03-20)
+- Feature: returning any non-undefined value from a mutator function when the Node is about to be removed prevents the automatic call to remove the Node.
+
+
+### 0.11.0 (2016-03-16)
+- Breaking change: the fourth argument to the mutator function is now a path, instead of index.
+
+
 ### 0.10.2 (2016-02-24)
 - Polish: remove restriction on binding multiple keys to the same DOM node, it wasn't necessary.
 

diff --git a/README.md b/README.md
@@ -87,7 +87,10 @@ A mutator function can be determined to be an insert, mutate, or remove operatio
 - Value and previous value: mutate operation.
 - No value: remove operation.
 
-There is a special case for the mutator function: if the bound node is the same as its parent, its value will not be iterated over if it is an array.
+There are some special cases for the mutator function:
+
+- If the bound node is the same as its parent, its value will not be iterated over if it is an array.
+- If the mutator function returns a non-undefined value for a remove operation, then `Node.removeChild` will not be called. This is useful for implementing animations when removing a Node from the DOM.
 
 
 ## Advanced Usage

diff --git a/lib/bind_keys.js b/lib/bind_keys.js
@@ -126,6 +126,7 @@ function bindKeys (scope, obj, def, parentNode, path) {
     function removeNode (value, previousValue, i) {
       var activeNode = activeNodes[i]
       var endPath = keyPath
+      var returnValue
 
       // Cast previous value to null if undefined.
       if (previousValue === void 0) previousValue = null
@@ -138,9 +139,14 @@ function bindKeys (scope, obj, def, parentNode, path) {
             endPath = keyPath.concat(i)
             endPath.root = path.root
           }
-          mutator(activeNode, null, previousValue, endPath)
+          returnValue = mutator(activeNode, null, previousValue, endPath)
         }
-        branch.marker.parentNode.removeChild(activeNode)
+
+        // If a mutator function returns a non-undefined value, skip the call
+        // to the DOM.
+        if (returnValue === void 0)
+          branch.marker.parentNode.removeChild(activeNode)
+
         delete activeNodes[i]
       }
     }

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "simulacra",
   "description": "One-way data binding for web applications.",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "author": {
     "email": "0x8890@airmail.cc",