Use native qSA

Add documentation about when to use scopeSubtree

lib/utils/scope-subtree.js

@@ -9,13 +9,14 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 */
 
 import './boot.js';
-import { wrap } from './wrap.js';
 
 const ShadyDOM = window.ShadyDOM;
 const ShadyCSS = window.ShadyCSS;
 
 /**
  * Ensure that elements in a ShadowDOM container are scoped correctly.
+ * This function is only needed when ShadyDOM is used and unpatched DOM APIs are used in third party code.
+ * This can happen in noPatch mode or when specialized APIs like ranges or tables are used to mutate DOM.
  *
  * @param  {!Element} container Container element to scope
  * @param  {boolean=} shouldObserve if true, start a mutation observer for added nodes to the container
@@ -26,8 +27,8 @@ export function scopeSubtree(container, shouldObserve = false) {
   if (!ShadyDOM || !ShadyCSS) {
     return null;
   }
-  // ShadyCSS handles DOM mutations in patched mode
-  if (!ShadyDOM['noPatch']) {
+  // ShadyCSS handles DOM mutations when ShadyDOM does not handle scoping itself
+  if (!ShadyDOM['handlesDynamicScoping']) {
     return null;
   }
   const ScopingShim = ShadyCSS['ScopingShim'];
@@ -39,8 +40,9 @@ export function scopeSubtree(container, shouldObserve = false) {
   const containerScope = ScopingShim['scopeForNode'](container);
 
   const scopify = (node) => {
-    const wrappedNode = wrap(node);
-    const elements = [node, ...(wrappedNode.querySelectorAll('*'))];
+    // NOTE: native qSA does not honor scoped DOM, but it is faster, and the same behavior as Polymer v1
+    const descendants = ShadyDOM['nativeMethods']['querySelectorAll'].call(node, '*');
+    const elements = [node, ...descendants];
     for (let i = 0; i < elements.length; i++) {
       const el = elements[i];
       const currentScope = ScopingShim['currentScopeForNode'](el);