Update Polymer from 1.2.1 -> 1.2.3

third_party/polymer/v1_0/components-chromium/iron-list/iron-list.html

Index: third_party/polymer/v1_0/components-chromium/iron-list/iron-list.html
diff --git a/third_party/polymer/v1_0/components-chromium/iron-list/iron-list.html b/third_party/polymer/v1_0/components-chromium/iron-list/iron-list.html
index 3684aba847828af389bbdca27555dc3076018939..9b3148af1bdf1440377fab2f5c748da6d9313be9 100644
--- a/third_party/polymer/v1_0/components-chromium/iron-list/iron-list.html
+++ b/third_party/polymer/v1_0/components-chromium/iron-list/iron-list.html
@@ -23,7 +23,7 @@ be reused with a new model at any time. Particularly, any state that may change
 as the result of a user interaction with the list item must be bound to the model
 to avoid view state inconsistency.
 
-__Important:__ `iron-list` must ether be explicitly sized, or delegate scrolling to an
+__Important:__ `iron-list` must either be explicitly sized, or delegate scrolling to an
 explicitly sized parent. By "explicitly sized", we mean it either has an explicit
 CSS `height` property set via a class or inline style, or else is sized by other
 layout means (e.g. the `flex` or `fit` classes).
@@ -47,39 +47,45 @@ For example, given the following `data` array:
 
 ##### data.json
 
-    [
-      {"name": "Bob"},
-      {"name": "Tim"},
-      {"name": "Mike"}
-    ]
+```js
+[
+  {"name": "Bob"},
+  {"name": "Tim"},
+  {"name": "Mike"}
+]
+```
 
 The following code would render the list (note the name and checked properties are
 bound from the model object provided to the template scope):
 
-    <template is="dom-bind">
-      <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>
+```html
+<template is="dom-bind">
+  <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;
-      };
-    }
+```css
+iron-list {
+ --iron-list-items-container: {
+    margin: auto;
+  };
+}
+```
 
 ### Resizing
 
-`iron-list` lays out the items when it recives a notification via the `iron-resize` event.
+`iron-list` lays out the items when it receives 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
@@ -87,8 +93,21 @@ this event automatically. If you hide the list manually (e.g. you use `display:
 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('iron-resize');
+```js
+document.querySelector('iron-list').fire('iron-resize');
+```
+
+### When should `<iron-list>` be used?
+
+`iron-list` should be used when a page has significantly more DOM nodes than the ones
+visible on the screen. e.g. the page has 500 nodes, but only 20 are visible at the time.
+This is why we refer to it as a `virtual` list. In this case, a `dom-repeat` will still
+create 500 nodes which could slow down the web app, but `iron-list` will only create 20.
 
+However, having an `iron-list` does not mean that you can load all the data at once. 
+Say, you have a million records in the database, you want to split the data into pages
+so you can bring a page at the time. The page could contain 500 items, and iron-list
+will only render 20.
 
 @group Iron Element
 @element iron-list