update elements and fix some bugs

lib/src/iron-list/iron-list.html

 <!--
 @license
 Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
 This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
 The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
 Code distributed by Google as part of the polymer project is also
 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
 -->
 
@@ skipping 51 matching lines @@
       <iron-ajax url="data.json" last-response="{{data}}" auto></iron-ajax>
       <iron-list items="[[data]]" as="item">
         <template>
           <div>
             Name: <span>[[item.name]]</span>
           </div>
         </template>
       </iron-list>
     </template>
 
+### Styling
+
+Use the `--iron-list-items-container` mixin to style the container of items, e.g.
+
+    iron-list {
+     --iron-list-items-container: {
+        margin: auto;
+      };
+    }
+
 ### Resizing
 
-`iron-list` lays out the items when it recives a notification via the `resize` event.
+`iron-list` lays out the items when it recives a notification via the `iron-resize` event.
 This event is fired by any element that implements `IronResizableBehavior`.
 
 By default, elements such as `iron-pages`, `paper-tabs` or `paper-dialog` will trigger
 this event automatically. If you hide the list manually (e.g. you use `display: none`)
 you might want to implement `IronResizableBehavior` or fire this event manually right
 after the list became visible again. e.g.
 
-    document.querySelector('iron-list').fire('resize');
+    document.querySelector('iron-list').fire('iron-resize');
 
 
 @group Iron Element
 @element iron-list
-@demo demo/index.html
+@demo demo/index.html Simple list
+@demo demo/selection.html Selection of items
+@demo demo/collapse.html Collapsable items
 -->
 
 <dom-module id="iron-list">
-  <style>
+  <template>
+    <style>
+      :host {
+        display: block;
+      }
 
-    :host {
-      display: block;
-    }
+      :host(.has-scroller) {
+        overflow: auto;
+      }
 
-    :host(.has-scroller) {
-      overflow: auto;
-    }
+      :host(:not(.has-scroller)) {
+        position: relative;
+      }
 
-    :host(:not(.has-scroller)) {
-      position: relative;
-    }
+      #items {
+        @apply(--iron-list-items-container);
+        position: relative;
+      }
 
-    #items {
-      position: relative;
-    }
-
-    #items > ::content > * {
-      width: 100%;
-      box-sizing: border-box;
-      position: absolute;
-      top: 0;
-      will-change: transform;
-    }
-
-  </style>
-  <template>
+      #items > ::content > * {
+        width: 100%;
+        box-sizing: border-box;
+        position: absolute;
+        top: 0;
+        will-change: transform;
+      }
+    </style>
 
     <array-selector id="selector" items="{{items}}"
-        selected="{{selectedItems}}" selected-item="{{selectedItem}}">
+      selected="{{selectedItems}}" selected-item="{{selectedItem}}">
     </array-selector>
 
     <div id="items">
       <content></content>
     </div>
 
   </template>
 </dom-module>
 
 <script>
@@ skipping 23 matching lines @@
        * The name of the variable to add to the binding scope for the array
        * element associated with a given template instance.
        */
       as: {
         type: String,
         value: 'item'
       },
 
       /**
        * The name of the variable to add to the binding scope with the index
-       * for the row.  If `sort` is provided, the index will reflect the
-       * sorted order (rather than the original array order).
+       * for the row.
        */
       indexAs: {
         type: String,
         value: 'index'
       },
 
       /**
        * The name of the variable to add to the binding scope to indicate
        * if the row is selected.
        */
@@ skipping 58 matching lines @@
     },
 
     /**
      * The ratio of hidden tiles that should remain in the scroll direction.
      * Recommended value ~0.5, so it will distribute tiles evely in both directions.
      */
     _ratio: 0.5,
 
     /**
      * The element that controls the scroll
+     * @type {?Element}
      */
     _scroller: null,
 
     /**
      * The padding-top value of the `scroller` element
      */
     _scrollerPaddingTop: 0,
 
     /**
      * This value is the same as `scrollTop`.
@@ skipping 61 matching lines @@
      */
     _scrollHeight: 0,
 
     /**
      * The size of the viewport
      */
     _viewportSize: 0,
 
     /**
      * An array of DOM nodes that are currently in the tree
+     * @type {?Array<!TemplatizerNode>}
      */
     _physicalItems: null,
 
     /**
      * An array of heights for each item in `_physicalItems`
+     * @type {?Array<number>}
      */
     _physicalSizes: null,
 
     /**
      * A cached value for the visible index.
      * See `firstVisibleIndex`
+     * @type {?number}
      */
     _firstVisibleIndexVal: null,
 
     /**
      * A Polymer collection for the items.
+     * @type {?Polymer.Collection}
      */
     _collection: null,
 
     /**
      * True if the current item list was rendered for the first time
      * after attached.
      */
     _itemsRendered: false,
 
     /**
      * The bottom of the physical content.
      */
     get _physicalBottom() {
       return this._physicalTop + this._physicalSize;
     },
 
     /**
+     * The bottom of the scroll.
+     */
+    get _scrollBottom() {
+      return this._scrollPosition + this._viewportSize;
+    },
+
+    /**
      * The n-th item rendered in the last physical item.
      */
     get _virtualEnd() {
       return this._virtualStartVal + this._physicalCount - 1;
     },
 
     /**
      * The lowest n-th value for an item such that it can be rendered in `_physicalStart`.
      */
     _minVirtualStart: 0,
 
     /**
      * The largest n-th value for an item such that it can be rendered in `_physicalStart`.
      */
     get _maxVirtualStart() {
-      return this._virtualCount < this._physicalCount ?
-          this._virtualCount : this._virtualCount - this._physicalCount;
+      return Math.max(0, this._virtualCount - this._physicalCount);
     },
 
     /**
      * The height of the physical content that isn't on the screen.
      */
     get _hiddenContentSize() {
       return this._physicalSize - this._viewportSize;
     },
 
     /**
@@ skipping 32 matching lines @@
     },
 
    /**
     * True if the current list is visible.
     */
     get _isVisible() {
       return this._scroller && Boolean(this._scroller.offsetWidth || this._scroller.offsetHeight);
     },
 
     /**
-     * Gets the first visible item in the viewport.
+     * Gets the index of the first visible item in the viewport.
      *
-     * @property firstVisibleIndex
+     * @type {number}
      */
     get firstVisibleIndex() {
       var physicalOffset;
 
       if (this._firstVisibleIndexVal === null) {
         physicalOffset = this._physicalTop;
 
         this._firstVisibleIndexVal = this._iterateItems(
           function(pidx, vidx) {
             physicalOffset += this._physicalSizes[pidx];
@@ skipping 18 matching lines @@
     },
 
     /**
      * When the element has been attached to the DOM tree.
      */
     attached: function() {
       // delegate to the parent's scroller
       // e.g. paper-scroll-header-panel
       var el = Polymer.dom(this);
 
-      if (el.parentNode && el.parentNode.scroller) {
-        this._scroller = el.parentNode.scroller;
+      var parentNode = /** @type {?{scroller: ?Element}} */ (el.parentNode);
+      if (parentNode && parentNode.scroller) {
+        this._scroller = parentNode.scroller;
       } else {
         this._scroller = this;
         this.classList.add('has-scroller');
       }
 
       if (IOS_TOUCH_SCROLLING) {
         this._scroller.style.webkitOverflowScrolling = 'touch';
       }
 
       this._scroller.addEventListener('scroll', this._scrollListener);
@@ skipping 13 matching lines @@
     },
 
     /**
      * Invoke this method if you dynamically update the viewport's
      * size or CSS padding.
      *
      * @method updateViewportBoundaries
      */
     updateViewportBoundaries: function() {
       var scrollerStyle = window.getComputedStyle(this._scroller);
-      this._scrollerPaddingTop = parseInt(scrollerStyle['padding-top']);
+      this._scrollerPaddingTop = parseInt(scrollerStyle['padding-top'], 10);
       this._viewportSize = this._scroller.offsetHeight;
     },
 
     /**
      * Update the models, the position of the
      * items in the viewport and recycle tiles as needed.
      */
     _refresh: function() {
-      var SCROLL_DIRECTION_UP = -1;
-      var SCROLL_DIRECTION_DOWN = 1;
-      var SCROLL_DIRECTION_NONE = 0;
-
       // clamp the `scrollTop` value
       // IE 10|11 scrollTop may go above `_maxScrollTop`
       // iOS `scrollTop` may go below 0 and above `_maxScrollTop`
       var scrollTop = Math.max(0, Math.min(this._maxScrollTop, this._scroller.scrollTop));
-
-      var tileHeight, kth, recycledTileSet;
+      var tileHeight, tileTop, kth, recycledTileSet, scrollBottom;
       var ratio = this._ratio;
       var delta = scrollTop - this._scrollPosition;
-      var direction = SCROLL_DIRECTION_NONE;
       var recycledTiles = 0;
       var hiddenContentSize = this._hiddenContentSize;
       var currentRatio = ratio;
       var movingUp = [];
 
       // track the last `scrollTop`
       this._scrollPosition = scrollTop;
 
       // clear cached visible index
       this._firstVisibleIndexVal = null;
 
+      scrollBottom = this._scrollBottom;
+
       // random access
       if (Math.abs(delta) > this._physicalSize) {
         this._physicalTop += delta;
-        direction = SCROLL_DIRECTION_NONE;
         recycledTiles =  Math.round(delta / this._physicalAverage);
       }
       // scroll up
       else if (delta < 0) {
         var topSpace = scrollTop - this._physicalTop;
         var virtualStart = this._virtualStart;
+        var physicalBottom = this._physicalBottom;
 
-        direction = SCROLL_DIRECTION_UP;
         recycledTileSet = [];
 
         kth = this._physicalEnd;
         currentRatio = topSpace / hiddenContentSize;
 
         // move tiles from bottom to top
         while (
             // approximate `currentRatio` to `ratio`
             currentRatio < ratio &&
             // recycle less physical items than the total
             recycledTiles < this._physicalCount &&
             // ensure that these recycled tiles are needed
-            virtualStart - recycledTiles > 0
+            virtualStart - recycledTiles > 0 &&
+            // ensure that the tile is not visible
+            physicalBottom - this._physicalSizes[kth] > scrollBottom
         ) {
 
-          tileHeight = this._physicalSizes[kth] || this._physicalAverage;
+          tileHeight = this._physicalSizes[kth];
           currentRatio += tileHeight / hiddenContentSize;
-
+          physicalBottom -= tileHeight;
           recycledTileSet.push(kth);
           recycledTiles++;
           kth = (kth === 0) ? this._physicalCount - 1 : kth - 1;
         }
 
         movingUp = recycledTileSet;
         recycledTiles = -recycledTiles;
-
       }
       // scroll down
       else if (delta > 0) {
-        var bottomSpace = this._physicalBottom - (scrollTop + this._viewportSize);
+        var bottomSpace = this._physicalBottom - scrollBottom;
         var virtualEnd = this._virtualEnd;
         var lastVirtualItemIndex = this._virtualCount-1;
 
-        direction = SCROLL_DIRECTION_DOWN;
         recycledTileSet = [];
 
         kth = this._physicalStart;
         currentRatio = bottomSpace / hiddenContentSize;
 
         // move tiles from top to bottom
         while (
             // approximate `currentRatio` to `ratio`
             currentRatio < ratio &&
             // recycle less physical items than the total
             recycledTiles < this._physicalCount &&
             // ensure that these recycled tiles are needed
-            virtualEnd + recycledTiles < lastVirtualItemIndex
+            virtualEnd + recycledTiles < lastVirtualItemIndex &&
+            // ensure that the tile is not visible
+            this._physicalTop + this._physicalSizes[kth] < scrollTop
           ) {
 
-          tileHeight = this._physicalSizes[kth] || this._physicalAverage;
+          tileHeight = this._physicalSizes[kth];
           currentRatio += tileHeight / hiddenContentSize;
 
           this._physicalTop += tileHeight;
           recycledTileSet.push(kth);
           recycledTiles++;
           kth = (kth + 1) % this._physicalCount;
         }
       }
 
-      if (recycledTiles !== 0) {
+      if (recycledTiles === 0) {
+        // If the list ever reach this case, the physical average is not significant enough
+        // to create all the items needed to cover the entire viewport.
+        // e.g. A few items have a height that differs from the average by serveral order of magnitude.
+        if (this._increasePoolIfNeeded()) {
+          // yield and set models to the new items
+          this.async(this._update);
+        }
+      } else {
         this._virtualStart = this._virtualStart + recycledTiles;
         this._update(recycledTileSet, movingUp);
       }
     },
 
     /**
      * Update the list of items, starting from the `_virtualStartVal` item.
+     * @param {!Array<number>=} itemSet
+     * @param {!Array<number>=} movingUp
      */
     _update: function(itemSet, movingUp) {
       // update models
       this._assignModels(itemSet);
 
       // measure heights
-      // TODO(blasten) pass `recycledTileSet`
-      this._updateMetrics();
+      this._updateMetrics(itemSet);
 
       // adjust offset after measuring
       if (movingUp) {
         while (movingUp.length) {
           this._physicalTop -= this._physicalSizes[movingUp.pop()];
         }
       }
-
       // update the position of the items
       this._positionItems();
 
       // set the scroller size
       this._updateScrollerSize();
 
       // increase the pool of physical items if needed
-      if (itemSet = this._increasePoolIfNeeded()) {
-        // set models to the new items
-        this.async(this._update.bind(this, itemSet));
+      if (this._increasePoolIfNeeded()) {
+        // yield set models to the new items
+        this.async(this._update);
       }
     },
 
     /**
      * Creates a pool of DOM elements and attaches them to the local dom.
      */
     _createPool: function(size) {
       var physicalItems = new Array(size);
 
       this._ensureTemplatized();
 
       for (var i = 0; i < size; i++) {
         var inst = this.stamp(null);
 
         // First element child is item; Safari doesn't support children[0]
         // on a doc fragment
         physicalItems[i] = inst.root.querySelector('*');
         Polymer.dom(this).appendChild(inst.root);
       }
 
       return physicalItems;
     },
 
     /**
-     * Increases the pool size. That is, the physical items in the DOM.
+     * Increases the pool of physical items only if needed.
      * This function will allocate additional physical items
      * (limited by `MAX_PHYSICAL_COUNT`) if the content size is shorter than
      * `_optPhysicalSize`
      *
-     * @return Array
+     * @return boolean
      */
     _increasePoolIfNeeded: function() {
-      if (this._physicalSize >= this._optPhysicalSize || this._physicalAverage === 0) {
-        return null;
+      if (this._physicalAverage === 0) {
+        return false;
       }
+      if (this._physicalBottom < this._scrollBottom || this._physicalTop > this._scrollPosition) {
+        return this._increasePool(1);
+      }
+      if (this._physicalSize < this._optPhysicalSize) {
+        return this._increasePool(Math.round((this._optPhysicalSize - this._physicalSize) * 1.2 / this._physicalAverage));
+      }
+      return false;
+    },
 
-      // the estimated number of physical items that we will need to reach
-      // the cap established by `_optPhysicalSize`.
-      var missingItems = Math.round(
-          (this._optPhysicalSize - this._physicalSize) * 1.2 / this._physicalAverage
-        );
-
+    /**
+     * Increases the pool size.
+     */
+    _increasePool: function(missingItems) {
       // limit the size
       var nextPhysicalCount = Math.min(
           this._physicalCount + missingItems,
           this._virtualCount,
           MAX_PHYSICAL_COUNT
         );
 
       var prevPhysicalCount = this._physicalCount;
       var delta = nextPhysicalCount - prevPhysicalCount;
 
       if (delta <= 0) {
-        return null;
+        return false;
       }
 
-      var newPhysicalItems = this._createPool(delta);
-      var emptyArray = new Array(delta);
-
-      [].push.apply(this._physicalItems, newPhysicalItems);
-      [].push.apply(this._physicalSizes, emptyArray);
+      [].push.apply(this._physicalItems, this._createPool(delta));
+      [].push.apply(this._physicalSizes, new Array(delta));
 
       this._physicalCount = prevPhysicalCount + delta;
 
-      // fill the array with the new item pos
-      while (delta > 0) {
-        emptyArray[--delta] = prevPhysicalCount + delta;
-      }
-
-      return emptyArray;
+      return true;
     },
 
     /**
      * Render a new list of items. This method does exactly the same as `update`,
      * but it also ensures that only one `update` cycle is created.
      */
     _render: function() {
       var requiresUpdate = this._virtualCount > 0 || this._physicalCount > 0;
 
       if (this.isAttached && !this._itemsRendered && this._isVisible && requiresUpdate)  {
@@ skipping 129 matching lines @@
         this._virtualCount = this.items ? this.items.length : 0;
 
         this.debounce('refresh', this._render);
 
       } else {
         // update a single item
         this._forwardItemPath(change.path.split('.').slice(1).join('.'), change.value);
       }
     },
 
+    /**
+     * @param {!Array<!PolymerSplice>} splices
+     */
     _adjustVirtualIndex: function(splices) {
       var i, splice, idx;
 
       for (i = 0; i < splices.length; i++) {
         splice = splices[i];
 
         // deselect removed items
         splice.removed.forEach(this.$.selector.deselect, this.$.selector);
 
         idx = splice.index;
         // We only need to care about changes happening above the current position
         if (idx >= this._virtualStartVal) {
           break;
         }
 
         this._virtualStart = this._virtualStart +
             Math.max(splice.addedCount - splice.removed.length, idx - this._virtualStartVal);
       }
     },
 
     _scrollHandler: function() {
       this._refresh();
     },
 
     /**
      * Executes a provided function per every physical index in `itemSet`
      * `itemSet` default value is equivalent to the entire set of physical indexes.
+     *
+     * @param {!function(number, number)} fn
+     * @param {!Array<number>=} itemSet
      */
     _iterateItems: function(fn, itemSet) {
       var pidx, vidx, rtn, i;
 
       if (arguments.length === 2 && itemSet) {
         for (i = 0; i < itemSet.length; i++) {
           pidx = itemSet[i];
           if (pidx >= this._physicalStart) {
             vidx = this._virtualStartVal + (pidx - this._physicalStart);
           } else {
@@ skipping 18 matching lines @@
         for (; pidx < this._physicalStart; pidx++, vidx++) {
           if ((rtn = fn.call(this, pidx, vidx)) != null) {
             return rtn;
           }
         }
       }
     },
 
     /**
      * Assigns the data models to a given set of items.
+     * @param {!Array<number>=} itemSet
      */
     _assignModels: function(itemSet) {
       this._iterateItems(function(pidx, vidx) {
         var el = this._physicalItems[pidx];
         var inst = el._templateInstance;
         var item = this.items && this.items[vidx];
 
         if (item) {
           inst[this.as] = item;
           inst.__key__ = this._collection.getKey(item);
-          inst[this.selectedAs] = this.$.selector.isSelected(item);
+          inst[this.selectedAs] =
+            /** @type {!ArraySelectorElement} */ (this.$.selector).isSelected(item);
           inst[this.indexAs] = vidx;
           el.removeAttribute('hidden');
           this._physicalIndexForKey[inst.__key__] = pidx;
         } else {
           inst.__key__ = null;
           el.setAttribute('hidden', '');
         }
 
       }, itemSet);
     },
 
     /**
      * Updates the height for a given set of items.
+     *
+     * @param {!Array<number>=} itemSet
      */
-    _updateMetrics: function() {
-      var total = 0;
+     _updateMetrics: function(itemSet) {
+      var newPhysicalSize = 0;
+      var oldPhysicalSize = 0;
       var prevAvgCount = this._physicalAverageCount;
       var prevPhysicalAvg = this._physicalAverage;
-
       // Make sure we distributed all the physical items
       // so we can measure them
       Polymer.dom.flush();
 
-      for (var i = 0; i < this._physicalCount; i++) {
-        this._physicalSizes[i] = this._physicalItems[i].offsetHeight;
-        total += this._physicalSizes[i];
-        this._physicalAverageCount += this._physicalSizes[i] ? 1 : 0;
-      }
+      this._iterateItems(function(pidx, vidx) {
+        oldPhysicalSize += this._physicalSizes[pidx] || 0;
+        this._physicalSizes[pidx] = this._physicalItems[pidx].offsetHeight;
+        newPhysicalSize += this._physicalSizes[pidx];
+        this._physicalAverageCount += this._physicalSizes[pidx] ? 1 : 0;
+      }, itemSet);
 
-      this._physicalSize = total;
+      this._physicalSize = this._physicalSize + newPhysicalSize - oldPhysicalSize;
       this._viewportSize = this._scroller.offsetHeight;
 
+      // update the average if we measured something
       if (this._physicalAverageCount !== prevAvgCount) {
         this._physicalAverage = Math.round(
-            ((prevPhysicalAvg * prevAvgCount) + total) /
+            ((prevPhysicalAvg * prevAvgCount) + newPhysicalSize) /
             this._physicalAverageCount);
       }
     },
 
     /**
      * Updates the position of the physical items.
      */
-    _positionItems: function(itemSet) {
+    _positionItems: function() {
       this._adjustScrollPosition();
 
       var y = this._physicalTop;
 
       this._iterateItems(function(pidx) {
 
         this.transform('translate3d(0, ' + y + 'px, 0)', this._physicalItems[pidx]);
         y += this._physicalSizes[pidx];
 
-      }, itemSet);
+      });
     },
 
     /**
      * Adjusts the scroll position when it was overestimated.
      */
     _adjustScrollPosition: function() {
       var deltaHeight = this._virtualStartVal === 0 ? this._physicalTop :
           Math.min(this._scrollPosition + this._physicalTop, 0);
 
       if (deltaHeight) {
@@ skipping 11 matching lines @@
      */
     _resetScrollPosition: function(pos) {
       if (this._scroller) {
         this._scroller.scrollTop = pos;
         this._scrollPosition = this._scroller.scrollTop;
       }
     },
 
     /**
      * Sets the scroll height, that's the height of the content,
+     *
+     * @param {boolean=} forceUpdate If true, updates the height no matter what.
      */
     _updateScrollerSize: function(forceUpdate) {
       this._estScrollHeight = (this._physicalBottom +
           Math.max(this._virtualCount - this._physicalCount - this._virtualStartVal, 0) * this._physicalAverage);
 
       forceUpdate = forceUpdate || this._scrollHeight === 0;
       forceUpdate = forceUpdate || this._scrollPosition >= this._estScrollHeight - this._physicalSize;
 
       // amortize height adjustment, so it won't trigger repaints very often
       if (forceUpdate || Math.abs(this._estScrollHeight - this._scrollHeight) >= this._optPhysicalSize) {
         this.$.items.style.height = this._estScrollHeight + 'px';
         this._scrollHeight = this._estScrollHeight;
       }
     },
 
     /**
      * Scroll to a specific item in the virtual list regardless
      * of the physical items in the DOM tree.
      *
      * @method scrollToIndex
      * @param {number} idx The index of the item
      */
     scrollToIndex: function(idx) {
       if (typeof idx !== 'number') {
         return;
       }
 
-      var itemSet;
       var firstVisible = this.firstVisibleIndex;
 
       idx = Math.min(Math.max(idx, 0), this._virtualCount-1);
 
       // start at the previous virtual item
       // so we have a item above the first visible item
       this._virtualStart = idx - 1;
 
       // assign new models
       this._assignModels();
@@ skipping 19 matching lines @@
       // update the scroller size
       this._updateScrollerSize(true);
 
       // update the position of the items
       this._positionItems();
 
       // set the new scroll position
       this._resetScrollPosition(this._physicalTop + targetOffsetTop + 1);
 
       // increase the pool of physical items if needed
-      if (itemSet = this._increasePoolIfNeeded()) {
-        // set models to the new items
-        this.async(this._update.bind(this, itemSet));
+      if (this._increasePoolIfNeeded()) {
+        // yield set models to the new items
+        this.async(this._update);
       }
-
       // clear cached visible index
       this._firstVisibleIndexVal = null;
     },
 
     /**
      * Reset the physical average and the average count.
      */
     _resetAverage: function() {
       this._physicalAverage = 0;
       this._physicalAverageCount = 0;
     },
 
     /**
-     * A handler for the `resize` event triggered by `IronResizableBehavior`
+     * A handler for the `iron-resize` event triggered by `IronResizableBehavior`
      * when the element is resized.
      */
     _resizeHandler: function() {
       this.debounce('resize', function() {
         this._render();
         if (this._itemsRendered && this._physicalItems && this._isVisible) {
           this._resetAverage();
           this.updateViewportBoundaries();
           this.scrollToIndex(this.firstVisibleIndex);
         }
       });
     },
 
     _getModelFromItem: function(item) {
       var key = this._collection.getKey(item);
       var pidx = this._physicalIndexForKey[key];
 
       if (pidx !== undefined) {
         return this._physicalItems[pidx]._templateInstance;
       }
       return null;
     },
 
     /**
+     * Gets a valid item instance from its index or the object value.
+     *
+     * @param {(Object|number)} item The item object or its index
+     */
+    _getNormalizedItem: function(item) {
+      if (typeof item === 'number') {
+        item = this.items[item];
+        if (!item) {
+          throw new RangeError('<item> not found');
+        }
+      } else if (this._collection.getKey(item) === undefined) {
+        throw new TypeError('<item> should be a valid item');
+      }
+      return item;
+    },
+
+    /**
      * Select the list item at the given index.
      *
      * @method selectItem
-     * @param {(Object|number)} item the item object or its index
+     * @param {(Object|number)} item The item object or its index
      */
     selectItem: function(item) {
-      if (typeof item === 'number') {
-        item = this.items[item];
-        if (!item) {
-          throw new RangeError('<item> not found');
-        }
-      } else {
-        if (this._collection.getKey(item) === undefined) {
-          throw new TypeError('<item> should be a valid item');
-        }
-      }
-
+      item = this._getNormalizedItem(item);
       var model = this._getModelFromItem(item);
 
       if (!this.multiSelection && this.selectedItem) {
         this.deselectItem(this.selectedItem);
       }
       if (model) {
         model[this.selectedAs] = true;
       }
       this.$.selector.select(item);
     },
 
     /**
      * Deselects the given item list if it is already selected.
      *
+
      * @method deselect
-     * @param {(Object|number)} item the item object or its index
+     * @param {(Object|number)} item The item object or its index
      */
     deselectItem: function(item) {
-      if (typeof item === 'number') {
-        item = this.items[item];
-        if (!item) {
-          throw new RangeError('<item> not found');
-        }
-      } else {
-        if (this._collection.getKey(item) === undefined) {
-          throw new TypeError('<item> should be a valid item');
-        }
-      }
-
+      item = this._getNormalizedItem(item);
       var model = this._getModelFromItem(item);
 
       if (model) {
         model[this.selectedAs] = false;
       }
       this.$.selector.deselect(item);
     },
 
     /**
      * Select or deselect a given item depending on whether the item
      * has already been selected.
      *
      * @method toggleSelectionForItem
-     * @param {(Object|number)} item the item object or its index
+     * @param {(Object|number)} item The item object or its index
      */
     toggleSelectionForItem: function(item) {
-      var item = typeof item === 'number' ? this.items[item] : item;
-      if (this.$.selector.isSelected(item)) {
+      item = this._getNormalizedItem(item);
+      if (/** @type {!ArraySelectorElement} */ (this.$.selector).isSelected(item)) {
         this.deselectItem(item);
       } else {
         this.selectItem(item);
       }
     },
 
     /**
      * Clears the current selection state of the list.
      *
      * @method clearSelection
      */
     clearSelection: function() {
       function unselect(item) {
         var model = this._getModelFromItem(item);
         if (model) {
           model[this.selectedAs] = false;
         }
       }
 
       if (Array.isArray(this.selectedItems)) {
         this.selectedItems.forEach(unselect, this);
       } else if (this.selectedItem) {
         unselect.call(this, this.selectedItem);
       }
 
-      this.$.selector.clearSelection();
+      /** @type {!ArraySelectorElement} */ (this.$.selector).clearSelection();
     },
 
     /**
      * Add an event listener to `tap` if `selectionEnabled` is true,
      * it will remove the listener otherwise.
      */
     _selectionEnabledChanged: function(selectionEnabled) {
       if (selectionEnabled) {
         this.listen(this, 'tap', '_selectionHandler');
+        this.listen(this, 'keypress', '_selectionHandler');
       } else {
         this.unlisten(this, 'tap', '_selectionHandler');
+        this.unlisten(this, 'keypress', '_selectionHandler');
       }
     },
 
     /**
      * Select an item from an event object.
      */
     _selectionHandler: function(e) {
-      var model = this.modelForElement(e.target);
-      if (model) {
-        this.toggleSelectionForItem(model[this.as]);
+      if (e.type !== 'keypress' || e.keyCode === 13) {
+        var model = this.modelForElement(e.target);
+        if (model) {
+          this.toggleSelectionForItem(model[this.as]);
+        }
       }
     },
 
     _multiSelectionChanged: function(multiSelection) {
       this.clearSelection();
       this.$.selector.multi = multiSelection;
+    },
+
+    /**
+     * Updates the size of an item.
+     *
+     * @method updateSizeForItem
+     * @param {(Object|number)} item The item object or its index
+     */
+    updateSizeForItem: function(item) {
+      item = this._getNormalizedItem(item);
+      var key = this._collection.getKey(item);
+      var pidx = this._physicalIndexForKey[key];
+
+      if (pidx !== undefined) {
+        this._updateMetrics([pidx]);
+        this._positionItems();
+      }
     }
   });
 
 })();
 
 </script>