Update observe-dom.js

tmorehouse · web-flow · commit 8a630c41de7e · 2017-09-13T21:28:22.000-03:00
diff --git a/lib/utils/observe-dom.js b/lib/utils/observe-dom.js
@@ -1,4 +1,3 @@
-
 import { assign } from './object';
 import { isElement } from '../utils/dom';
 
@@ -26,7 +25,7 @@ export default function observeDOM(el, callback, opts) {
         // Define a new observer
         obs = new MutationObserver(mutations => {
             let changed = false;
-            // A Mutation can contain several changes, so we loop through them to see what has changed
+            // A Mutation can contain several change records, so we loop through them to see what has changed.
             // We break out of the loop early if any "significant" change has been detected
             for (let i = 0; i < mutations.length && !changed; i++) {
                 // The muttion record
@@ -43,11 +42,14 @@ export default function observeDOM(el, callback, opts) {
                     // So we compare the old value to the new value
                     changed = true;
                 } else if (type === 'attributes' && target.getAttribute(mutation.attributeName) !== old) {
-                    // Updating an attribute with the same value still triggers a mutation
-                    // So we compare the old value to the new value
+                    // Updating an attribute with the same value still triggers a mutation, so we compare
+                    // the old value to the new value. For atributes like class or style, the content order
+                    // could change (i.e. classes changed order in string), but have no affect on layout.
+                    // We could pre-process these here but that added overhead might be more than the
+                    // callback's overhead.  So we just run callback anyways.
                     changed = true;
                 } else if (type === 'childList' && (mutation.addedNodes.length > 0 || mutation.removedNodes.length > 0)) {
-                    // This includes HTMLElement and Text Nodes being added/removed
+                    // This includes HTMLElement and Text Nodes being added/removed/re-arranged
                     changed = true;
                 }
             }
@@ -65,5 +67,7 @@ export default function observeDOM(el, callback, opts) {
         el.addEventListener('DOMNodeRemoved', callback, false);
     }
 
+    // We return a reference to the observer so that obs.disconnect() can be called if necessary
+    // To reduce overhead when the root element is hiiden
     return obs;
 }
