clean up code, factor processing lazy candidates, better docs

lib/mixins/lazy-upgrade-mixin.html

@@ -17,15 +17,23 @@
   /**
    * Element class mixin that provides API for lazily upgrading Polymer Elements.
    *
-   * This mixin can be used with the `disable-upgrade` attribute to lazily upgrade elements
-   * that are descendants of this element. This is useful for elements that need to display
-   * many elements.
+   * This mixin can be used to lazily upgrade elements that are descendants of this element.
+   * This is useful for elements that have expensive descendants that are not necessary for
+   * the first rendering.
+   *
+   * To lazily upgrade descendant elements, those elements must have
+   * `disable-upgrade` and `lazy-upgrade` attributes.
+   * In addition, `<dom-if>` elements can be lazily displayed with just the
+   * `lazy-upgrade` attribute.
+   *
+   * The `lazy-upgrade` attribute can be given an optional priority value.
+   * The higher the value, the lower the priority. Default priority is 0.
    *
    * When upgrading elements, the mixin will upgrade as many as it can within the budget
    * set by `_lazyUpgradeBudget`, which defaults to 16ms.
    *
    * When finished processing lazy-upgrade elements, this mixin will set `_lazyUpgrading`
-   * to false on the instance.
+   * to false on the host.
    *
    * @polymerMixin
    * @memberof Polymer
@@ -35,9 +43,10 @@
 
       const LAZY_UPGRADE = 'lazy-upgrade';
       const DISABLE_UPGRADE = 'disable-upgrade';
-      const LAZY_UPGRADE_QUERY = `[${LAZY_UPGRADE}]`;
+      const LAZY_UPGRADE_QUERY = `[${DISABLE_UPGRADE}][${LAZY_UPGRADE}], dom-if[${LAZY_UPGRADE}]`;
       const LAZY_UPGRADE_BUDGET = 16;
 
+      // sort lazy-upgrade nodes for ascending value
       function sortCandidates(a, b) {
         let orderA = parseInt(a.getAttribute(LAZY_UPGRADE), 10) || 0;
         let orderB = parseInt(b.getAttribute(LAZY_UPGRADE), 10) || 0;
@@ -58,20 +67,22 @@
         node.removeAttribute(LAZY_UPGRADE);
       }
 
-      /** @polymerMixinClass */
-      return class LazyUpgrade extends base {
+      /**
+       * @polymerMixinClass
+       */
+      class LazyUpgrade extends base {
         static get properties() {
           return {
             /**
-             * Instance-level property for configuring the frame budget for lazy-upgrading elements.
-             * Defaults to 16ms
+             * Instance-level property for configuring the frame budget in ms for lazy-upgrading elements.
+             * Defaults to 16 ms
              */
             _lazyUpgradeBudget: {
               type: Number,
               value: LAZY_UPGRADE_BUDGET
             },
             /**
-             * Instance-level property that is shows when the element is lazy-upgrading elements
+             * Instance-level property that is shows when the element is lazy-upgrading elements.
              */
             _lazyUpgrading: {
               type: Boolean
@@ -91,18 +102,25 @@
          */
         __lazyUpgrade() {
           if (this.__lazyUpgradeQueue.length) {
-            Polymer.RenderStatus.afterNextRender(this, () => {
-              const deadline = performance.now() + this._lazyUpgradeBudget;
-              while (this.__lazyUpgradeQueue.length && (performance.now() < deadline)) {
-                upgradeNode(this.__lazyUpgradeQueue.shift());
-              }
-              this.__lazyUpgrade();
-            });
+            Polymer.RenderStatus.afterNextRender(this, this.__processLazyCandidates);
           } else {
             this._lazyUpgrading = false;
           }
         }
+
+        /**
+         * @private
+         */
+        __processLazyCandidates() {
+          const deadline = performance.now() + this._lazyUpgradeBudget;
+          while (this.__lazyUpgradeQueue.length && (performance.now() < deadline)) {
+            upgradeNode(this.__lazyUpgradeQueue.shift())
+          }
+          this.__lazyUpgrade();
+        }
       }
+
+      return LazyUpgrade;
     });
   })();
 </script>