├── .clang-format
├── .editorconfig
├── .gitignore
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE.md
├── Motivation.md
├── README.md
├── study-group
    ├── Angular-Material-virtual-scroll.md
    ├── Polymer-iron-list.md
    ├── README.md
    ├── REQUIREMENTS.md
    ├── WinJS.md
    └── iOS-UITableView.md
└── w3c.json


/.clang-format:
--------------------------------------------------------------------------------
1 | # Defines the Chromium style for automatic reformatting.
2 | # http://clang.llvm.org/docs/ClangFormatStyleOptions.html
3 | BasedOnStyle: Chromium
4 | 


--------------------------------------------------------------------------------
/.editorconfig:
--------------------------------------------------------------------------------
 1 | root = true
 2 | 
 3 | [*]
 4 | end_of_line = lf
 5 | insert_final_newline = true
 6 | charset = utf-8
 7 | indent_size = 2
 8 | indent_style = space
 9 | trim_trailing_whitespace = true
10 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | bower_components
2 | node_modules
3 | yarn.lock
4 | .vscode


--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Code of Conduct
2 | 
3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/).
4 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
 1 | # Web Platform Incubator Community Group
 2 | 
 3 | This repository is being used for work in the W3C Web Platform Incubator Community Group, governed by the [W3C Community License
 4 | Agreement (CLA)](http://www.w3.org/community/about/agreements/cla/). To make substantive contributions,
 5 | you must join the CG.
 6 | 
 7 | If you are not the sole contributor to a contribution (pull request), please identify all
 8 | contributors in the pull request comment.
 9 | 
10 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows:
11 | 
12 | ```
13 | +@github_username
14 | ```
15 | 
16 | If you added a contributor by mistake, you can remove them in a comment with:
17 | 
18 | ```
19 | -@github_username
20 | ```
21 | 
22 | If you are making a pull request on behalf of someone else but you had no part in designing the
23 | feature, you can remove yourself with the above syntax.
24 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | All Reports in this Repository are licensed by Contributors
 2 | under the
 3 | [W3C Software and Document License](http://www.w3.org/Consortium/Legal/2015/copyright-software-and-document).
 4 | 
 5 | Contributions to Specifications are made under the
 6 | [W3C CLA](https://www.w3.org/community/about/agreements/cla/).
 7 | 
 8 | Contributions to Test Suites are made under the
 9 | [W3C 3-clause BSD License](https://www.w3.org/Consortium/Legal/2008/03-bsd-license.html)
10 | 
11 | 


--------------------------------------------------------------------------------
/Motivation.md:
--------------------------------------------------------------------------------
 1 | # Why a virtual scroller?
 2 | 
 3 | As explained in [the README](./README.md), virtualized content is an important and common pattern on the web, but it's a hard one to get right. Here we dive into those arguments further, to justify why we believe this is an important feature to provide out of the box with the web platform.
 4 | 
 5 | ## Performance
 6 | 
 7 | **The most important reason that we believe that virtual scrollers are a good pattern, and that we want to provide a solution as part of the web's standard library, is because they are one of the most effective things developers can do to get reliably good rendering performance.**
 8 | 
 9 | Good rendering performance is about rendered DOM size. Fundamentally, having a lot of rendered DOM nodes causes significant performance impact in ways that browsers can only optimize so much.
10 | 
11 | It’s not uncommon to see pages with tens of thousands of DOM nodes, and on those pages, style recalcs and layouts are often quite expensive in unpredictable ways (e.g. changing a class name ends up causing a huge DOM subtree to recalc and relayout).
12 | 
13 | Native mobile platforms immediately steer you towards a virtualized view. As a result, apps are naturally in a pit of success because they just don’t end up with thousands of views that the OS framework needs to manage.
14 | 
15 | If most pages on the web defaulted to using a virtualized view, then many of the performance problems we see would never happen in the first place.
16 | 
17 | ## Standardization
18 | 
19 | So, we think virtual scrollers can have a huge impact on performance. Why bake it into the browser, instead of continuing with the current trend of hoping web developers use libraries? There are a few reasons.
20 | 
21 | One of the primary impacts of standardization is as a coordination function, to shift the ecosystem. As such, we think having a standard virtual scroller element in the browser will have a big impact on usage. Using virtualized content—which, per the above, is key to building fast pages on the web—would be considerably easier and require considerably less expertise.
22 | 
23 | We'd like to get to a world where the browser's built-in virtual scroller is good enough, and easy enough to use, to make it a default path for most web pages. Imagine not just virtualized contact lists or social media streams, but also long-form articles where each paragraph is virtualized, or GitHub issue threads where each comment is virtualized. (The [virtualized single-page HTML Standard](https://github.com/valdrinkoshi/virtual-scroller/tree/virtual-content/demo/html-standard) is a good demo in this vein.) Any scrollable content should end up in a virtual scroller.
24 | 
25 | For example, if you go look at any Cocoa (iOS) starter tutorial, the first code they tell you to write is to use a `UITableView` (a virtualized view). It’s hard to imagine how we could get starter tutorials to point developers to virtualized views if there isn’t at least one variant built into the browser. ("OK, so first pick a framework; these three are popular this week. Make sure to learn it in enough detail to understand how third party components fit into those frameworks. Then, if you're using React, React Virtualized is good, and works this way, but has these caveats... If you're using Angular...")
26 | 
27 | Shipping a virtual scroller with the browser also means that developers only need to ship the code for their virtualized view over the wire if they need to do something bespoke. This makes the web easier to develop on for everyone, increases the pit of success for developers, and improves the experience for users who are now interfacing with more lightweight sites.
28 | 
29 | ## Layering
30 | 
31 | While we do want a standardized virtual scroller that ships with the browser, we insist on [building it in a layered way](https://extensiblewebmanifesto.org/), on top of primitives that web developers can already access. This is in contrast to other semi-recent HTML controls, like `<details>` or `<dialog>`, which cannot be replicated on top of primitives.
32 | 
33 | This layered approach ensures that all the primitives that make for a good virtual scroller are also accessible to other frameworks building virtualization solutions. This includes already-existing primitives like `IntersectionObserver`, `ResizeObserver`, and shadow DOM, as well as still-speculative primitives like [display locking](https://github.com/WICG/display-locking/), designed to solve the problems of accessibility, indexability, find-in-page, in-page anchors, and other ways in which the disconnect between content and DOM cause user experience issues.
34 | 
35 | In particular, we don't insist that the virtual-scroller element we ship with the browser be the perfect solution for 100% of virtualized content cases. We're aiming more for 90%. This is inevitable; higher-level APIs need to be more opinionated than lower-level primitives, so they can’t meet all the developer needs. As such, it’s critical that people who have other needs can meet them with the same richness as browser built-ins. The layered strategy for virtual scroller ensures this. It also gives an easy transition path for existing virtualized content solutions and libraries which do fall within that 90% case: they can, over time, port their implementations to be a wrapper around the browser built-in one, with even more (likely framework-specific) opinions.
36 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # A built-in virtual scroller for the web platform
  2 | 
  3 | This repository hosts explorations for a new web platform feature, a virtual scroller control. The idea of a virtual scroller is to provide a scrolling "viewport" onto some content, allow extremely large numbers of elements to exist, but maintain high performance by only paying the cost for those that are currently visible. Traditionally, we say that the non-visible content is _virtualized_.
  4 | 
  5 | ## Current status
  6 | 
  7 | This project is no longer being actively developed. Instead we are pursuing primitives [here](https://github.com/WICG/display-locking).
  8 | 
  9 | ## Why a virtual scroller?
 10 | 
 11 | Virtualized content is a popular and important pattern on the web. Most content uses it in some form: the https://m.twitter.com and https://facebook.com feeds; Google Photos and YouTube comments; and many news sites which have an automatic "scroll to next article" feature. Most popular frameworks have at least one high-usage virtualization component, e.g. [React Virtualized](https://bvaughn.github.io/react-virtualized/) with [~290K weekly downloads](https://www.npmjs.com/package/react-virtualized). See the [infinite list study group](https://github.com/domenic/infinite-list-study-group) for more research on existing virtualization solutions, both on the web and in other platforms like iOS.
 12 | 
 13 | At the same time, virtual scrollers are complex and hard to get right. In fact, having a first-class experience with virtualized content is currently impossible, because browsers don't expose the right hooks: things like accessible landmark navigation, find in page, or intra-page anchor navigation are based solely on DOM structure, and virtualized content is by definition not in the DOM. Additionally, today's virtualized content does not work with search engine crawlers, which means that sites that care about search engine ranking are unable to apply this important performance technique. This is bad for the web.
 14 | 
 15 | We believe that, like native platforms, the web deserves a first-class virtual scroller implementation that works out of the box.
 16 | 
 17 | For more details on the motivation, see [Motivation.md](./Motivation.md).
 18 | 
 19 | ## Sample code
 20 | 
 21 | ```html
 22 | <!--
 23 |   virtual-scroller lives in a built-in module and needs to be imported before use.
 24 |   (The name of the module is subject to change.)
 25 | -->
 26 | <script type="module">
 27 | import "std:virtual-scroller";
 28 | </script>
 29 | 
 30 | <!--
 31 |   The <virtual-scroller> will manage the rendering of its children.
 32 |   It will prioritize rendering things that are in the viewport and not render
 33 |   children that are far away, such that we are only paying as little rendering
 34 |   cost as possible while still allowing them to work with find-in-page,
 35 |   accessibility features, focus navigation, fragment URL navigation, etc.
 36 | -->
 37 | <virtual-scroller id='scroller'>
 38 |   <div>Item 1</div>
 39 |   <div>Item 2</div>
 40 |   ...
 41 |   <div>Item 1000</div>
 42 | </virtual-scroller>
 43 | 
 44 | <script>
 45 | // You can add, remove, modify children of the <virtual-scroller> as you would
 46 | // a regular element, using DOM APIs.
 47 | scroller.append(...newChildren);
 48 | 
 49 | // When the set of actually-rendered children is about to change,
 50 | // the <virtual-scroller> will fire a "rangechange" event with the
 51 | // new range of rendered children.
 52 | scroller.addEventListener('rangechange', (event) => {
 53 |   if (event.first === 0) {
 54 |     console.log('rendered first item.');
 55 |   }
 56 |   if (event.last === scroller.children.length - 1) {
 57 |     console.log('rendered last item.');
 58 |     // Perhaps you would want to load more data for display!
 59 |   }
 60 | });
 61 | </script>
 62 | ```
 63 | 
 64 | ## Goals
 65 | 
 66 | * Be flexible enough to be used for various kinds of scrolling, larger-than-viewport content, from news articles to typeaheads to contact lists to photo galleries.
 67 | * Only pay the rendering costs for _visible_ child elements of the scroller (with some margin).
 68 | * Allow contents of the scroller to work with find-in-page, accessibility features, focus, fragment URL navigation, etc., just as they would in a non-virtualized context.
 69 | * Be flexible enough to allow developers to integrate advanced features and behaviors, such as groupings, sticky headers, animations, swiping, item selection, etc.
 70 | * Support 1D horizontal/1D vertical/2D wrapped-grid layouts.
 71 | 
 72 | ## Non-goals
 73 | 
 74 | * Allow data that are not part of the DOM to work with find-in-page, accessibility, etc. The DOM remains the source of truth for these browser features, not e.g. the server-side, or other in-memory JavaScript data structures. See [below](#almost-infinite-data-from-the-server) for more elaboration.
 75 | 
 76 | And, at least in v1, the following are out of scope:
 77 | 
 78 | * Built-in support for advanced features and behaviors, such as those mentioned above.
 79 | * Support infinite-grid (spreadsheet-like), multi-column (content continues from bottom of col(N) to top of col(N+1)) or masonry layouts.
 80 | 
 81 | ## Proposed APIs
 82 | 
 83 | ### `<virtual-scroller>` element
 84 | 
 85 | The `<virtual-scroller>` element represents a container that will manage the rendering of its children.
 86 | The children of this element might not get rendered/updated if they are not near or in the viewport.
 87 | The element is aware of changes to the viewport, as well as to its own size, and will manage the rendered state of its children accordingly.
 88 | 
 89 | Its children can be any element.
 90 | Semantically, the element is similar to a `<div>`, with the addition of focus on only the visible contents when the element overflows its container and is scrolled.
 91 | 
 92 | The sizes and other layout values of the non-rendered children, which might affect scrollbar height, etc., are approximate sizes and might not be always accurate.
 93 | The rendered children always have accurate style and layout values, just like other normal DOM nodes.
 94 | 
 95 | All children, rendered or non-rendered, will work with find-in-page, focus navigation, fragment URL navigation, and accessibility technology, just like normal DOM nodes.
 96 | 
 97 | ### `rangechange` event
 98 | 
 99 | Fired when `<virtual-scroller>` is about to render a new range of items, e.g. because the user scrolled.
100 | This will fire at `requestAnimationFrame` timing, i.e. before the browser is about to paint.
101 | 
102 | The event has the following properties:
103 | 
104 | * `first`: an integer, the 0-based index of the first children currently rendered.
105 | * `last`: an integer, the 0-based index of the last children currently rendered.
106 | * `bubbles`: false
107 | * `cancelable`: false
108 | * `composed`: false
109 | 
110 | As an example, this can be used to delay more costly rendering work.
111 | For example, a scrolling code listing could perform just-in-time syntax highlighting on lines right before they become visible, leaving the un-adorned code accessible by find-in-page/etc. but improving the code's appearance before the user sees it.
112 | 
113 | _TODO: do we need `first` and `last` on the event, or should we just use the properties of the element?_
114 | 
115 | ### `rangeFirst` and `rangeLast` getters
116 | 
117 | These return 0-based indices giving the first and last children currently rendered.
118 | 
119 | _TODO: these names are kind of bad?_
120 | 
121 | ### Constraints and effects
122 | 
123 | Ideally, we would like there to be zero constraints on the contents of the `<virtual-scroller>` element, or on the virtual-scroller element itself.
124 | 
125 | Similarly, we would like to avoid any observable effects on the element or its children. Just like how `<select>` does not cause its `<option>` elements to change observably when you open the select box, ideally `<virtual-scroller>` should not cause observable effects on its children as the user scrolls around.
126 | 
127 | This may prove difficult to specify or implement. In reality, we expect to have to add constraints such as:
128 | 
129 | * Overriding the default values for certain CSS properties (and ignoring web developer attempts to set them).
130 | * Having degenerate behavior if visual order does not match DOM order (e.g. via `flex-order` or `position: absolute`).
131 | 
132 | And the control may influence its children via effects such as:
133 | 
134 | * Changing the computed style of children (observable via `getComputedStyle(child)`).
135 | * Changing the display-locked status of children (observable via `child.displayLock.locked`).
136 | * Changing the layout of non-visible children's descendants (observable via e.g. `child.children[0].getBoundingClientRect()`).
137 | 
138 | Figuring out the exact set of constraints (including what happens when they're violated), and the exact set of effects, is a key blocker for standardization that we expect to address over time.
139 | 
140 | ## Use cases
141 | 
142 | ### Cases this proposal covers well
143 | 
144 | This design is intended to cover the following cases:
145 | 
146 | * Short (10-100 item) scrollers.
147 |   Previously, virtualizing such scrollers was done rarely, as virtualization caused sacrifices in developer and user experience.
148 |   We are hopeful that with a first-class virtualization element in the web platform, it will become more expected to use `<virtual-scroller>` in places where overflow-scrolling `<div>`s were previously seen, thus [improving overall UI performance](./Motivation.md#performance).
149 | 
150 | * Medium (100-10&nbsp;000 item) scrollers.
151 |   This is where virtual scrollers have traditionally thrived.
152 |   We also want to expand this category to include not just traditional list- or feed-like scenarios, but also cases like news articles.
153 | 
154 | * Large (10&nbsp;000+ item) scrollers, where data is added progressively.
155 |   As long as the data can be held in memory, `<virtual-scroller>` ensures that there are no rendering costs, and so can scale indefinitely.
156 |   An example here would be any interface where scrolling down loads more content from the server, indefinitely, such as a social feed or a busy person's inbox.
157 | 
158 |   However, note that adding a large amount of data _at once_ is tricky with this API; see below.
159 | 
160 | ### Very large amounts of initial data
161 | 
162 | Consider the cases of the [singlepage HTML specification](http://html.spec.whatwg.org/), or of long-but-finite lists such as a large company directory.
163 | 
164 | We believe that all these scenarios are still suited for use with this virtual scroller control.
165 | As long as the data could feasibly fit in memory in any form, the user experience will be best if it is stored in the DOM, inside a virtual scroller that makes the rendering costs of out-of-viewport items zero.
166 | This allows access to the data by browser features, such as find-in-page or accessibility tooling, as well as by search engines.
167 | 
168 | However, using the above API in these scenarios suffers from the problem of initial page load costs.
169 | Trying to server-render all of the items as `<virtual-scroller>` children, or trying to do an initial JSON-to-HTML client-render pass, will jank the page.
170 | For example, just the parsing time alone for the single-page HTML specification [can take 0.6–4.4 seconds](https://github.com/valdrinkoshi/virtual-scroller/pull/92).
171 | And there are staging problems in trying to deliver large amounts of HTML while the `"std:virtual-scroller"` module is still being imported, which could prevent it from properly avoiding initial rendering costs.
172 | 
173 | As such we think there is still room for improvement in these scenarios, e.g. with an API that makes it easy to progressively stream data during idle time to allow the initial few screenfuls to render ASAP and without jank.
174 | We will be exploring this problem over time, after we feel confident that we can specify and implement a solution for the core use cases.
175 | 
176 | ### Almost-infinite data from the server
177 | 
178 | A consistent point of confusion about the virtual scroller proposal is how it purports to solve cases like social feeds, where there is an "almost infinite" amount of data available.
179 | 
180 | This proposal's answer is that: if you were going to have the data in memory anyway, then it should be in the `<virtual-scroller>`, and thus accessible to the browser or other technologies (such as search engines) that operate on the DOM.
181 | But, if you were going to leave the data on the server, then it is fine to continue leaving it on the server, even with a `<virtual-scroller>` in play.
182 | 
183 | For example, in one session while browsing https://m.twitter.com/, it limited itself to only keeping 5 tweets in the DOM at one time, using traditional virtualization techniques.
184 | However, it appeared to have about 100 tweets in memory (available for display even if the user goes offline).
185 | And, when the user began scrolling toward the bottom of the page, it queried the server to increase the amount of in-memory tweets it had available.
186 | With a native `<virtual-scroller>` in the browser, which mitigates the rendering costs while still allowing you to keep items in the DOM, we're hopeful that it'd be possible to keep those 100+ tweets as DOM nodes, not just in-memory JavaScript values that are locked away from find-in-page and friends.
187 | 
188 | This proposed design does mean that there could be things on the Twitter servers which are not findable by find-in-page, because they have not yet been pulled from the server and into the DOM.
189 | That is OK.
190 | Find-in-page is not meant to be find-in-site, and users of social feeds are able to understand the idea that not everything is yet loaded.
191 | What is harder for them to understand is when they saw a phrase, they scroll past it by 100 pixels, and then find-in-page can't see it anymore, because it's been moved out of the DOM.
192 | `<virtual-scroller>` addresses this latter problem.
193 | 
194 | ## Alternatives considered
195 | 
196 | ### Using traditional virtualization
197 | 
198 | Previously, we intended to specify a traditional approach to virtualization for the built-in virtual scroller.
199 | With that approach, the element would map JavaScript values ("items") to DOM element children, putting only a small portion of the items in the DOM, with callbacks for creating, updating, and recycling the DOM elements given an item.
200 | 
201 | However, this approach suffers the same problem as existing traditionally-virtualized scrollers regarding accessibility, find-in-page, fragment URL and focus navigation, etc., all of which depend on having the content be part of the DOM to work correctly.
202 | This is a known issue with traditional virtualization, which web developers have to grapple with today, trading off these functionalities with the performance improvement.
203 | As we intend for the built-in virtual scroller to be a standard building block that a lot of web authors would use or build on, we don't want to continue having this disadvantage.
204 | 
205 | In other words, given the problem of too much DOM causing bad performance, traditional virtualization is managing the symptoms, by decreasing the amount of DOM. For a standard solution, we want to tackle the core problem head-on.
206 | 
207 | ### [Find-in-page APIs](https://github.com/rakina/find-in-page-api)
208 | 
209 | As mentioned in the [previous section](#using-traditional-virtualization), we want to make features like find-in-page work with the built-in virtual scroller.
210 | We have briefly considered adding a set of find-in-page APIs to the web platform, that would support cases like giving the web author a way to completely override the find-in-page command, or interacting with and adding results to the user agent's built-in find-in-page functionality.
211 | 
212 | However, designing these APIs proved to be quite challenging, given the breadth of find-in-page user interfaces across browsers.
213 | Worse, providing a find-in-page-specific solution might unintentionally become a disadvantage for other things like accessibility: web developers might be inclined to think that a virtual scroller that works with find-in-page is good enough, and not think about the remainder of the missing functionality caused by virtualization.
214 | 
215 | ### Libraries
216 | 
217 | Another approach would be to standardize and implement only the low-level primitives which allow mitigating the cost of DOM, i.e. [display locking](https://github.com/WICG/display-locking/).
218 | We would then leave the building of high-level virtual scroller APIs to libraries.
219 | 
220 | We fully expect that some applications and libraries will take this route, and even encourage it when appropriate.
221 | But we still believe there is value in providing a high-level virtual scroller control built into the platform, for the 90% case.
222 | For more on our reasoning, see [the motivation document](./Motivation.md)'s ["Standardization"](./Motivation.md#standardization) and ["Layering"](./Motivation.md#layering) sections.
223 | 
224 | ## Sample implementations
225 | 
226 | ### Chrome
227 | 
228 | Launch chrome with flags `--enable-blink-features=DisplayLocking,BuiltInModuleAll`
229 | to get a working virtual-scroller element.
230 | 
231 | ## Demos
232 | 
233 | https://github.com/fergald/virtual-scroller-demos
234 | 


--------------------------------------------------------------------------------
/study-group/Angular-Material-virtual-scroll.md:
--------------------------------------------------------------------------------
  1 | # Angular Material's Virtual Scroll
  2 | * Study author: [@mmalerba](https://github.com/mmalerba)
  3 | * Platform: web
  4 | 
  5 | ## Background on Angular Material
  6 | [Angular Material](https://material.angular.io/) is a Google project to provide
  7 | [Material Design](https://material.io/) components for the [Angular](https://angular.io/) framework.
  8 | In addition to providing the Material Design components themselves, Angular Material publishes a
  9 | Component Development Kit (CDK) which exposes some of the building blocks used in Angular Material
 10 | that may be useful to developers of other Angular component libraries.
 11 | 
 12 | The `<cdk-virtual-scroll-viewport>` (and related components) are components currently being
 13 | developed for the CDK to provide virtual scrolling functionality. Code will go into a
 14 | [feature branch](https://github.com/angular/material2/tree/virtual-scroll) during development. The
 15 | [initial PR](https://github.com/angular/material2/pull/9316) sets up much of the infrastructure and
 16 | implements a simple fixed item size virtual scrolling strategy. More features and virtual scrolling
 17 | strategies will be added in future PRs. This document covers the current implementation + planned
 18 | work for the near future.
 19 | 
 20 | ## Motivating use cases
 21 | There are a number of Angular Material components that would benefit from having the option to
 22 | virtualize scrolling (although we don't want to force users to use virtual scrolling with any of
 23 | these components):
 24 | 
 25 | * [Accordion](https://material.angular.io/components/expansion/overview#accordion) with many
 26 |   expandable panels
 27 | * [Autocomplete](https://material.angular.io/components/autocomplete/overview) with many options
 28 | * [Datepicker](https://material.angular.io/components/datepicker/overview) (for ability to scroll
 29 |   through years, in addition to clicking forward/back)
 30 | * [List](https://material.angular.io/components/list/overview) with many items
 31 | * [Select](https://material.angular.io/components/select/overview) with many options
 32 | * [Table](https://material.angular.io/components/table/overview) with lots of data
 33 | * Tree (currently being implemented) with many nodes
 34 | 
 35 | ## Overview
 36 | The Angular Material implementation of virtual scroll will be divided into a number of smaller
 37 | pieces each with its own responsibilities.
 38 | 
 39 | ### `cdk-virtual-scroll-viewport`
 40 | Will be responsible for managing the state of the viewport. This includes things like:
 41 | 
 42 | 1. Monitoring scroll and resize events
 43 | 2. Updating the offset for the rendered portion of the data
 44 | 3. Updating the spacer element to reflect our best estimate of the size of the entire scrollable
 45 |    content 
 46 | 4. Keeping track of if whether we're virtualizing in the horizontal or vertical direction
 47 | 
 48 | ### `*cdkVirtualForOf`
 49 | Will be responsible for managing the items themselves. This includes things like:
 50 | 
 51 | 1. Diffing changes to the rendered range of items and stamping out new template instances as needed
 52 | 2. Caching item instances that are no longer needed so they can be recycled later
 53 | 3. Measuring the size of the rendered DOM corresponding to a given item
 54 | 
 55 | ### `VirtualScrollStrategy`
 56 | Will be responsible for deciding what range of data to render. This is merely an interface that will
 57 | have different implementations. For example we will likely have an implementation that assumes
 58 | equal-sized items, one that measures items, and one that disables virtualization and just renders
 59 | everything (we don't want any of the Angular Material components to force virtualization on users
 60 | since it may be detrimental to accessibility). The strategy can be set globally using Angular's
 61 | dependency injection system or on a case-by-case basis using Angular Directives (e.g. adding the
 62 | `itemSize="xxx"` attribute to a `cdk-virtual-scroll-viewport` will automatically switch the
 63 | `VirtualScrollStrategy` to a fixed item size one.)
 64 | 
 65 | ### `DataSource`
 66 | Will be responsible for fetching the data (whether it be all in memory, loading additional data from
 67 | the server as the user gets close to the end of the currently loaded data, etc). The user can either
 68 | pass a `DataSource` that implements fetching logic or just pass a simple array and have a static
 69 | `DataSource` created automatically.
 70 | 
 71 | ## Essential sample code
 72 | ```ts
 73 | @Component({...})
 74 | class MyComponent {
 75 |   names = ['Domenic', 'Ojan', ...];
 76 | }
 77 | ```
 78 | 
 79 | ```html
 80 | <cdk-virtual-scroll-container [itemSize]="50">
 81 |   <div *cdkVirtualForOf="let name of names">{{name}}</div>
 82 | </cdk-virtual-scroll-container>
 83 | ```
 84 | 
 85 | ## Resulting DOM structure
 86 | ```html
 87 | <cdk-virtual-scroll-viewport class="cdk-virtual-scroll-viewport"
 88 |                              style="overflow:auto; ...">
 89 |   <div class="cdk-virtual-scroll-content-wrapper"
 90 |        style="position:absolute; transform:translateY(200px); ...">
 91 |     <div>Domenic</div>
 92 |     <div>Ojan</div>
 93 |     ...
 94 |   </div>
 95 |   <div class="cdk-virtual-scroll-spacer"
 96 |        style="position:absolute; transform:translateY(10000px); ..."></div>
 97 | </cdk-virtual-scroll-viewport>
 98 | ```
 99 | 
100 | ## Customization options
101 | - Supports horizontal & vertical scroll direction
102 | - Easily swappable scroll strategies and mechanisms to change strategy for entire app, portions of
103 |   the app, or individual virtual scroller containers
104 | - Easily swappable data sources for different async strategies (e.g. placeholder elements vs
105 |   changing the size of the list)
106 | - Supports element and attribute selectors (useful in situations where children need to be a
107 |   specific tag name, e.g. a `<ul>` with `<li>` children)
108 | - Supports `0..*` HTML nodes per list item (useful in situations where you can't wrap, e.g. stamping
109 |   out `<li>` elements
110 | 
111 | ## API
112 | - `@Input() direction` - The direction to virtualize (vertical or horizontal)
113 | - `@Input() cdkVirtualForOf` - Sets the data source
114 | - `@Output() startIndex` - The index of the first visible item
115 | - `scrollTo(position)` - scroll to the given scroll position
116 | - `scrollToIndex(index)` - scroll to the given index in the list
117 | - `VirtualScrollStrategy` settable through dependency injection or directives
118 | - `VirtualScrollStrategy` implementations have buffer parameters that user can adjust
119 | 
120 | ## Noteworthy features & implementation details
121 | 
122 | ### Plan for variable size items
123 | I've done some research and experimentation into how to handle variable sized items, and have a plan
124 | for how to do it, but haven't implemented it yet. My first thought was to just measure the scroll
125 | delta on each scroll event, estimate how many items I need to render to fill the new space, based on
126 | the average of items I've seen so far (with additional render-measure cycles if necessary), and then
127 | remove the items that have moved off screen. The problem with this, however, is that the scroll
128 | delta can be very large if the user takes the scroll handle and whips it to the bottom. At this
129 | point I'm essentially rendering the entire list, only to delete most of it shortly after.
130 | 
131 | Instead I believe a better solution would be to use the strategy above only if the scroll delta is
132 | less than the size of the viewport. If it's greater than the size of the viewport the user isn't
133 | going to notice any discontinuities, so just estimate where you should be in the list and render
134 | that part. The problem now is that if I jump to somewhere in the middle of the list and then slowly
135 | scroll backward it may turn out that my estimate was wrong and when I get to the top there will be a
136 | gap or some elements that are stuck beyond the start of the viewport. To mitigate this I will monitor
137 | the error between my current position and my latest estimate as I scroll up and correct it more and
138 | more aggressively the closer I get to the top (I imagine something like "reduce the error by
139 | percent-scrolled-toward-top * total-error", so by the time I get to the top the error is completely
140 | corrected).
141 | 
142 | This will be implemented as a separate scroll strategy. If users know the size of their items they
143 | can use the more performant fixed size strategy, and if they don't they can use this strategy.
144 | 
145 | ### Support for `<ul>`, `<table>`, etc.
146 | Some elements have certain requirements for their children (e.g. `<ul>` must have `<li>` children).
147 | In order to support these elements in our virtual scrolling solution we will allow both element and
148 | attribute selectors. For example:
149 | 
150 | ```html
151 | <table cdkVirtualScrollViewport>
152 |   <tbody cdkVirtualScrollContent>
153 |     <tr *cdkVirtualForOf="let row of data">
154 |       <td>{{row.cols[0]}}</td>
155 |       <td>{{rows.cols[1]}}</td>
156 |     </tr>
157 |   </tbody>
158 | </table>
159 | ```
160 | 
161 | ```html
162 | <cdk-virtual-scroll-viewport>
163 |   <ul cdkVirtualScrollContent>
164 |     <li *cdkVirtualForOf="let item of data">{{item.name}}</li>
165 |   </ul>
166 | </cdk-virtual-scroll-viewport>
167 | ```
168 | 
169 | ### Viewport and content resizing
170 | We should be able to automatically handle rendering additional content when the viewport or content
171 | resizes. We can detect changes as follows:
172 | 
173 | - viewport shrinks - we don't care about this case, we'll just have slightly more content rendered
174 |   than necessary until the next scroll event
175 | - viewport grows - we can use `IntersectionObserver` to know if the bottom of the rendered content
176 |   crosses the bottom of the viewport and render more content
177 | - content shrinks - we can use the same `IntersectionObserver` to catch this case
178 | - content grows - we don't really care about detecting this case either, our estimated content size
179 |   will just be incorrect until the next scroll event
180 | 
181 | ### Template instance recycling
182 | As the user scrolls and template instances go off the edge of the viewport the `CdkVirtualForOf`
183 | removes them from the DOM and adds them to a template cache. Later when new template instances need
184 | to be created, the instances from the cache are rebound to the new data and added back into the DOM.
185 | This is less expensive than constantly creating and destroying instances. We will likely want to put
186 | some cap on our template cache to prevent wasting too much memory.
187 | 
188 | ## Resources
189 | - [Feature branch](https://github.com/angular/material2/tree/virtual-scroll)
190 | - [Initial PR](https://github.com/angular/material2/pull/9316) (not yet merged)
191 | 


--------------------------------------------------------------------------------
/study-group/Polymer-iron-list.md:
--------------------------------------------------------------------------------
  1 | # Polymer's `<iron-list>`
  2 | 
  3 | - Study Author: [@kschaaf](https://github.com/kschaaf)
  4 | - Platform: web
  5 | 
  6 | ## Background on Polymer & Web Components
  7 | 
  8 | [Polymer](http://www.polymer-project.org/) is a Google project focused on developer experience for creating, vending, and building applications using [Web Components](https://www.webcomponents.org/introduction).
  9 | 
 10 | Web Components is an ubmrella term referring to a series of new browser API's that allow defining custom HTML elements whose internal details and rendering are encapsulated. Taken together, the Web Components specs form a built-in, browser-native UI component model.  Once a custom element definition is imported, users may create and interact with custom elements using the same browser API's and idioms as any other built-in HTML element.
 11 | 
 12 | The Polymer team ships a library of the same name (effectively, a custom element base class) that layers a number of features onto the built-in Web Components primitives, such as property change observation, template-based declarative data-binding, and declarative event handlers.
 13 | 
 14 | 
 15 | ## Overview
 16 | 
 17 | `<iron-list>` is a Web Component built using the Polymer library that implements a virtualized, "infinite-scrolling" list.  As its primary inputs it accepts an array of list data (via property) and a template (via light dom) containing the prototypical dom for each list item, including Polymer-specific data-bindings that determine how to propagate array item data to each template instance.  It then stamps enough template instances to fill the viewport, plus a sufficient "runway" of off-screen items to maintain the illusion of continuous items during scrolling.  At each scroll event, it uses a boundary-based heuristic to determine when to rotate off-screen items from one edge of the list to the other, repositions one or more template instances via css transform, and updates the data-bindings in the template instance with a new item from the array.
 18 | 
 19 | The design is optimized for the following assumptions/biases:
 20 | * Bounding the total number of DOM nodes ever made by the list is important to avoid memory pressure
 21 | * The cost of showing new items during scroll (via any strategy) directly affects the risk of checkerboarding
 22 | * Updating existing DOM with new data (recycling) is cheaper than making new DOM and then updating it with data
 23 | * Support for variable height items is important to solve a number of use cases in the most flexible way (grouping, heterogenus content, etc.)
 24 | 
 25 | ## Essential sample code
 26 | 
 27 | ```html
 28 | <iron-list id="list">
 29 |   <template>
 30 |     <div class="item">[[index]] - [[item.name]]</div>
 31 |   </template>
 32 | </iron-list>
 33 | 
 34 | <script>
 35 |   list.items = [{name: 'Domenic'}, {name: 'Ojan'}, ...];
 36 | </script>
 37 | ```
 38 | 
 39 | ## Resulting DOM structure
 40 | 
 41 | ```html
 42 | <iron-list id="list" style="overflow-y: auto;">
 43 |   #shadow-root
 44 |     <style>/*...*/</style>
 45 |     <array-selector id="selector"></array-selector>
 46 |     <div id="items" style="height: 9000px;">
 47 |       <slot>
 48 |         <!-- projected list items stamped into light dom, shown here for understandability -->
 49 |         <div class="item" style="transform: translate3d(0px, 0px, 0px);">0 - Domenic</div>      
 50 |         <div class="item" style="transform: translate3d(0px, 18px, 0px);">1 - Ojan</div>
 51 |         <div class="item" style="transform: translate3d(0px, 36px, 0px);">2 - Drew</div>
 52 |         <div class="item" style="transform: translate3d(0px, 54px, 0px);">3 - Kevin</div>
 53 |         <div class="item" style="transform: translate3d(0px, 72px, 0px);">4 - Gray</div> 
 54 |         ...
 55 |       </slot>
 56 |     </div>
 57 |   (end #shadow-root)
 58 |   <!-- the physical list items above are actually appended here -->
 59 | </iron-list>
 60 | ```
 61 | 
 62 | ## Live examples:
 63 | * [minimal usage example](http://jsbin.com/qoletob/edit?html,output)
 64 | * [x-ray example](http://jsbin.com/yesezed/edit?html,output)
 65 | * [x-ray variable height](http://jsbin.com/tukulub/edit?html,output)
 66 | * [all element demos](https://raw-dot-custom-elements.appspot.com/PolymerElements/iron-list/v2.0.12/iron-list/demo/index.html)
 67 | 
 68 | ## Customization options
 69 | 
 70 | * `grid` (true/false) - toggles row vs. grid mode
 71 | * `selectionEnabled` (true/false) - toggles selection on/off. When selected (via tap), items get `selected` class applied which can be styled, and places the item in a `selected` array
 72 | * `multiSelection` (true/false) - toggles multiple selection on/off
 73 | * `scrollTarget` (element reference, id ref, or `'document'`) - by default the `<iron-list>` will be the scroll target, and must be sized; alternatively `<iron-list>` can be placed inside another scrolling region, in which case it is not the scroller and the `scrollTarget` must then specify the scroller element (to determine sizing, listen for `scroll` event, etc.)
 74 | * `scrollOffset` (integer, pixels) -  offset from the scrolling element to the top of iron-list element
 75 | 
 76 | ## Imperative API
 77 | 
 78 | * scroll to item/index
 79 |   * `scrollToIndex(idx)`
 80 |   * `scrollToItem(item)`
 81 | * update size
 82 |   * `updateSizeForIndex(index)`
 83 |   * `updateSizeForItem(item)`
 84 |   * `updateViewportBoundaries()`
 85 | * update data (standard Polymer structured data API)
 86 |   * `set(path, value)`
 87 |   * `push(array, value)`
 88 |   * `splice(array, value)`
 89 |   * ...
 90 | * selection
 91 |   * `clearSelection()`
 92 |   * `selectIndex(index)`
 93 |   * `selectItem(item)`
 94 |   * `deselectIndex(index)`
 95 |   * `deselectItem(item)`
 96 |   * `toggleSelectionForIndex(index)`
 97 |   * `toggleSelectionForItem(item)`
 98 | * accessibility
 99 |   * `focusItem(idx)`
100 | 
101 | ## Read-only properties (outputs)
102 | 
103 | * `firstVisibleIndex`
104 | * `lastVisibleIndex`
105 | * `selectedItem`
106 | * `selectedItems`
107 | 
108 | ## Events
109 | 
110 | Any events passed to declarative event handlers in item templates are decorated with information to associate them to the user data associated with the item receiving the event:
111 | 
112 | * `event.model.index` - index in user array
113 | * `event.model.item` - item from user array
114 | 
115 | ## Noteworthy features & implementation details
116 | 
117 | ### Item recycling, sizing, and positioning
118 | 
119 | `iron-list` creates a pool of template instances that are repositioned via css transform and re-bound to array items during scrolling.  An algorithm described below is used to ensure the pool of items is roughly 2x the size of the visible viewport, to help prevent checkerboarding when scrolling if the time to recycle items from e.g. top to bottom exceeds a scroll frame.  Composited scrolling will keep the list scrolling at 60fps, but if a scroll event blows its budget, the extra items in the pool can cover the lower framerate (for some amount of scroll length, leading to a better UX especially on mobile).  The amount of runway is not technically configurable (it was in previous iterations), but could be.
120 | 
121 | `iron-list` does not require fixed-size items, for maximum flexibility; it measures the natural size of newly created items after binding data into them, and then translates items in the viewort adjacent to the previous item's position. This design ensures that until the item is recycled, there is zero paint/layout cost to this item during scrolling or recycling of other items (would not be the case if any sort of static/flow/flex layout were used to position the pool of adjacent items).  This does mean, however, that if the item changes after the initial rendering, the list must be notified via e.g. `updateSizeForIndex` to ensure positioning is correct, which is a performance/ergonomics tradeoff.
122 | 
123 | Supporting variable, naturally sized items poses a question about how many items to create for the pool that will be recycled: creating too many unnecessarily delays initial painting of any list items; creating too few means needing to do multiple rounds of create+layout+measure, which is also inefficient.  As such, `iron-list` uses an incremental "increase pool if needed" algorightm as follows: it initially creates 3 items (a fixed constant), and if the items do not yet fill the viewport, it increases the pool size by 50%, and tries again. This continues synchronously (blocking paint) until the viewport is (just) filled.  After this, it yields to paint the initial items, and then switches to use `requestIdleCallback` to render the remaining items in the pool to reach 2x of the viewport height, in chunks of `n` items per `rIC`, where `n` is calculated emperically as the number of template instances that can be stamped in 50ms (to maintain responsiveness while completing initial render).  It is a bit fancy, but was refined during development of `chrome://history` and `chrome://downloads` to meet the performance sensitivity of initial rendering for those applications.
124 | 
125 | ### Configurable scroll target
126 | 
127 | `iron-list` can either _be_ the scroller (useful when e.g. multiple lists are needed on the same page), or delegate to a scrollable parent (particularly useful for document scrolling to ensure users get the native "URL bar scrolls away" behavior of modern mobile browsers).
128 | 
129 | The `scrollTarget` property supports string-based "idref" to select a scrollable parent (useful for fully declarative usage in HTML, but the id-referenced element must be in the same in the same shadow root scope).  Alternatively users can assign an element reference imperatively.
130 | 
131 | Annoyingly, the semantics of document-based scrolling requires special case logic: unlike overflow scrolling where `scrollTop` and `scroll` events come from the same element, with document based scrolling the `scroll` event fires on `document.documentElement` (`<html>`), but the effective `scrollTop` must be read from `window.pageYOffset`.  Similarly with setting the scroll position (assigning `scrollTop` vs. calling `window.scrollTo()`)  Hence a magic `'document'` value which can be used to toggle these semantics.
132 | 
133 | ### Virtual list sizing
134 | 
135 | Since `iron-list` supports variable height, to maintain (the illusion of) correct scrollbar sizing and positioning, the container inside the list that holds the positioned items is sized to the estimated full length of the list.
136 | 
137 | A continuously updating average height of items rendered is maintained and used to size the remaining unknown length of the list. As the user scrolls closer to the bottom, the amount of error trends towards zero, and reaches zero once the last set of items have been assigned to rows in the physical pool.  This can cause small jumps in the scroll thumb positioning, but it is usually imperceptable, especially for large lists.
138 | 
139 | The average is also used when scrolling to an arbitrary point in the list.  When scrolling to an arbitrary `scrollTop`, it is used to guess what array item would be at that spot. Likewise, when scrolling to an arbitrary array index, it is used to guess what the `scrollTop` should be set at.  The same process of updating the height of the container is used to trim the error back out of the list as the user approaches either end of the list (although since items are translated from the top, trimming error from the top of the list also requires updating the `scrollTop` and positioning of items).
140 | 
141 | ### Resize handling
142 | 
143 | There are a couple of considerations that `iron-list` implements regarding resizing the list:
144 | 
145 | First, when the list is resized, it attempts to maintain the same content visible on screen by adjusting the scroll position to keep the top-most visible item on the screen.  This may be questionable, but we felt it provided a much better UX than what normally happens when a traditional page full of content is resized (content either wraps more or less, causing the content in the visible viewport to change, which is a hair-pulling experience when e.g. rotating midway down a page on a phone).
146 | 
147 | Second, to implement the above, but also to simply ensure that the physical items are actually positioned correctly in the viewport, the list needs to know when its size has changed.  It listens to `resize` on `window`, but this is not sufficient to handle all cases where the list is resized (e.g. lists sized based on draggable pane splitters, for instance).  In the future, `ResizeObserver` should solve this problem, but in the meantime and for cross-platform support, `iron-list` uses the [`iron-resizable-behavior`](https://www.webcomponents.org/element/PolymerElements/iron-resizable-behavior/behaviors/Polymer.IronResizableBehavior) mixin, which is an approach for having resizable parents notify children (such as `iron-list`) when their size has changed via a cooperative event-based API.
148 | 
149 | ### Accessibility
150 | 
151 | `iron-list` has some built-in handling for keyboard navigation of the list, such that only one item in the list is ever tab-focusable, and focus for items _within the list_ can then be navigated via arrow keys.  This list-managed focus handling can be opted into by binding `[[tabIndex]]` to the `tabindex` attribute of a list item.  Via this data-binding, the list ensures only one item is ever focusable (all others get `tabindex="-1"`), and moves the focus and sets `tabindex="0"` for the next/previous item via arrow keys.
152 | 
153 | There is also some careful handling to avoid the currently focused item from being recycled, to both prevent the focus from looping while scrolling, and to prevent unnaturally thrashing `focus`/`blur` events on the focused item if it is scrolled in/out of the viewport.  Essentially, as long as an item becomes focused, it is never recycled; at the point where it would have been recycled it is positioned off screen (and another item is stamped to fill its place in the pool).  The list also ensures that e.g. pressing an arrow key once the focused item has been scrolled off screen causes the list to scroll back to the focused item (and then moves focus to the adjacent peer appropriately).
154 | 
155 | ### Template-based data-binding
156 | 
157 | The declarative template-based data-binding approach central to `iron-list`'s update process when recycling is probably the most non-portable, Polymer-specific aspect of `iron-list`.  Since the template and the data-binding annotations form the complete mapping of data to dom, no user code is needed to either generate the list item instances (the template is stamped) nor update items with new data (new item data from the `items` array is simply fed into the template instance via the data binging system).  This gives good ergonomics in that the list can be constructed in a fully declarative manner, but is also constrained by the limits of the Polymer data binding system.
158 | 
159 | The binding scope for each template instance is an object with the following structure:
160 | 
161 | ```js
162 | {
163 |   index: 0,        // index in the item array
164 |   selected: false, // true if the current item is selected
165 |   tabIndex: -1,    // a dynamically generated tabIndex for focus management
166 |   item: {}         // user data corresponding to items[index]
167 | }
168 | ```
169 | 
170 | It's important to note that `iron-list` does rely on Polymer 1.0/2.0's synchronous data binding system to provide well-known semantics for when DOM updates based on data changes have completed, since this is required to know when to measure item sizes and re-position them accordingly.  If the side effects of updating item data were async, a protocol would be needed to coordinate this process (e.g. a Promise-based API), which has implications for being able to render arbitrary DOM (including custom elements).
171 | 
172 | ### API for updating data
173 | 
174 | By virtue of extending from Polymer's base class, `iron-list` exposes Polymer's [structured data API](https://www.polymer-project.org/2.0/docs/devguide/data-system#make-observable-changes) for making changes to the `items` array or objects within the array in a way observable to the list, such that the rendering is automatically updated.  Examples:
175 | 
176 | ```js
177 | const list = document.querySelector('iron-list#mylist');
178 | list.push('items', {name: 'John'});            // Add to end of list
179 | list.splice('items', 0, 1, {name: 'Sally'});   // Replace first item in list
180 | list.set('items.3.name', 'Ben');               // Set items[3].name = 'Ben'
181 | ```
182 | 
183 | Using these API's provides enough informatino about the change that, when changes occur to data outside the viewport, the effective scroll position can be adjusted to avoid unpleasent sudden changes to the content visible to the user.  Also, when using `iron-list` within a larger app that is fully composed from templates using Polymer's data-bindings, information about changes made via these API's to the array data in one part of the application are communicated to the list as a special-case of polymer's normal property-based data-binding.
184 | 
185 | Alternatively, users can use immutable data patterns to update list data, which is typical among unidirectional state management such as when using e.g. Redux. Example:
186 | 
187 | ```js
188 | const list = document.querySelector('iron-list#mylist');
189 | list.items = [{name: 'Junior'}, ...list.items];  // Add to beginning of list
190 | ```
191 | 
192 | However, in this case content may move on screen since the exact location of the change cannot be known without diffing the array (which is not currently implemented).
193 | 
194 | ## Coordination with other elements
195 | 
196 | ### `<iron-scroll-threshold>`
197 | 
198 | `iron-list` has no built-in mechanisms for e.g. lazy-loading more data into the list, however it was designed to be used with [`<iron-scroll-threshold>`](https://www.webcomponents.org/element/PolymerElements/iron-scroll-threshold/elements/iron-scroll-threshold) to implement such a pattern.  Example:
199 | 
200 | ```html
201 | <iron-scroll-threshold id="threshold" lower-threshold="200">
202 |   <iron-list id="list" scroll-target="threshold">
203 |     <template>
204 |       <div>[[index]]</div>
205 |     </template>
206 |   </iron-list>
207 | </iron-scroll-threshold>
208 | 
209 | <script>
210 | threshold.addEventListener('lower-threshold', async e => {
211 |   const resp = await fetch(`data.json?page=${currentPage++}`);
212 |   const data = await resp.json();
213 |   list.push('items', ...data);
214 |   threshold.clearTriggers();
215 | }
216 | </script>
217 | ```
218 | 
219 | ### `<iron-image>`
220 | 
221 | An issue that comes up with images in recycled lists is that simply changing an `<img>`'s `src` when recycling can lead to the stale image being shown until the network fetch for the image completes (despite the fact that other aspects of the rendering for the newly recycled item, e.g. `textContent` have changed, which can be extra confusing).  As such, it is recommended to use [`<iron-image>`](https://www.webcomponents.org/element/PolymerElements/iron-image/elements/iron-image) in `<iron-list>`, which has the feature of automatically blanking the image when the src is changed, with other options for e.g. showing a loading placeholder image until the image has loaded, fading the loaded image in, etc.
222 | 
223 | ## Unimplemented Feature Requests
224 | [Github enhancements list](https://github.com/PolymerElements/iron-list/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement)
225 | 
226 | * grouping/sections/dividers/headers
227 | * collapsable sections
228 | * sticky headers
229 | * polymorphic templates (aka, non-regularized infinite scrolling)
230 | * bottom-up mode
231 | * horizontal mode
232 | * drag-and-drop reordering
233 | * multiple lists in one scrolling region
234 | * text search (ctrl+f)
235 | 
236 | ## Resources
237 | 
238 | - [API documentation](https://www.webcomponents.org/element/PolymerElements/iron-list) (API documentation)
239 | - [Source code](https://github.com/PolymerElements/iron-list)
240 | - [Demos](https://www.webcomponents.org/element/PolymerElements/iron-list/demo/demo/index.html)
241 | 


--------------------------------------------------------------------------------
/study-group/README.md:
--------------------------------------------------------------------------------
 1 | # Virtual scroller study group
 2 | 
 3 | This subdirectory contains studies of existing virtual scroller controls in various ecosystems, both on the web and elsewhere. These are useful to inform the capabilities of the built-in virtual scroller element proposed in this repository.
 4 | 
 5 | In addition to studies, we also have a [requirements document](./REQUIREMENTS.md) which we put together based on these studies.
 6 | 
 7 | If you would like to contribute your own study to the study group, please feel free to send a pull request; we would love to have more. Try to follow the format of the existing studies to some degree, but there are no strict rules.
 8 | 
 9 | ---
10 | 
11 | <small>This content originally lived in [domenic/infinite-list-study-group](https://github.com/domenic/infinite-list-study-group).</small>
12 | 


--------------------------------------------------------------------------------
/study-group/REQUIREMENTS.md:
--------------------------------------------------------------------------------
 1 | # Virtual scroller requirements
 2 | 
 3 | This document gathers the various features we've identified for a virtual scroller, along with their priority. If you disagree with these priorities, or would like to add additional features, please file an issue to discuss.
 4 | 
 5 | We use the following priority system:
 6 | 
 7 | - **P0** means that the we consider the element unusable if it does not include the feature. These need to be included in any "minimum viable product" (MVP) specification.
 8 | - **P1** means that we plan to include the feature in the MVP, but can drop it if it proves impossible, overly complex, or would delay delivering the value of the MVP.
 9 | - **P2** features will not be included in the MVP, and may never be included.
10 | 
11 | This document was created before the current [explainer](../README.md), based only on the study-group's studies, so it may feel a bit dated. But we think it's a valuable reference to refer back to at times.
12 | 
13 | ## P0
14 | 
15 | - Accurate scrollbar position for elements that have been loaded
16 | - Overall list structure supports screen readers and accessibility controls
17 | - Heterogeneous elements
18 | - Fallback element UI is possible (perhaps manually)
19 | - Grid layout
20 | - Overall scroller header and footer
21 | - Configurable layout and style for elements in the scroller
22 | - Clickable child elements
23 | 
24 | ## P1
25 | 
26 | - Find in page (<kbd>Ctrl+F</kbd>) highlights elements that have been loaded
27 | - Subgroups within the scroller (e.g. letter groupings for a contact list), with potentially-sticky headers
28 | - Maintains scroll position across page load
29 | - "Load more" button
30 | - Ability to animate items in/out, with changing sizes
31 | - Horizontal layout
32 | 
33 | ## P2
34 | 
35 | - Built-in backing by a remote data source
36 | - Built-in selectable children
37 | - Built-in rearrangeable children
38 | - Built-in pull to refresh
39 | - Find in page (<kbd>Ctrl+F</kbd>) highlights elements that haven't been loaded from the server
40 | - Accurate scrollbar position including elements that haven't been loaded from the server
41 | - Discoverable by screen readers for elements that haven't been loaded from the server
42 | - Animation coordination (like `UITableView`)
43 | 


--------------------------------------------------------------------------------
/study-group/WinJS.md:
--------------------------------------------------------------------------------
  1 | # WinJS `ListView`
  2 | 
  3 | - Study Author: [@domenic](https://github.com/domenic)
  4 | - Platform: web / Windows 8
  5 | 
  6 | ## Background on WinJS
  7 | 
  8 | [WinJS](http://try.buildwinjs.com/) is a Microsoft project originally designed to allow writing Windows 8 "Metro" applications in JavaScript and HTML. It has since grown into a cross-platform JavaScript library, [maintained on GitHub](https://github.com/winjs/winjs).
  9 | 
 10 | The project appears to be [in maintenance mode](https://github.com/winjs/winjs#status). However, I think it's especially worth investigating as it's a recent attempt to build an operating system's worth of UI controls using web technologies.
 11 | 
 12 | ## Essential sample code
 13 | 
 14 | ### With imperative rendering
 15 | 
 16 | ```js
 17 | const items = getTonsAndTonsOfItems();
 18 | window.itemList = new WinJS.Binding.List(items);
 19 | 
 20 | window.templateProcessor = async itemPromise => {
 21 |   const item = await itemPromise;
 22 |   // item has various other useful properties: e.g. index, isOnScreen
 23 | 
 24 |   const div = document.createElement("div");
 25 |   div.textContent = item.data.text;
 26 |   return div;
 27 | };
 28 | 
 29 | // Some sort of security precaution:
 30 | // http://try.buildwinjs.com/tutorial/1Basics/markSupport/
 31 | WinJS.Utilities.markSupportedForProcessing(window.templateProcessor);
 32 | 
 33 | ```
 34 | 
 35 | ```html
 36 | <div data-win-control="WinJS.UI.ListView"
 37 |      data-win-options="{
 38 |        itemDataSource: itemsList.dataSource,
 39 |        itemTemplate: templateProcessor,
 40 |        layout: { type: WinJS.UI.ListLayout }
 41 |      }">
 42 | </div>
 43 | ```
 44 | 
 45 | [Live demo, including all supporting code](https://jsbin.com/kuyemit/edit?html,output)
 46 | 
 47 | ### With custom placeholders while data loads
 48 | 
 49 | ```js
 50 | window.templateProcessor = itemPromise => {
 51 |   const div = document.createElement("div");
 52 |   div.textContent = "...";
 53 | 
 54 |   return {
 55 |     element: div,
 56 |     renderComplete: Promise.all([delay(1000 * Math.random()), itemPromise]).then(([,item]) => {
 57 |       div.textContent = item.data.text;
 58 |     })
 59 |   };
 60 | };
 61 | ```
 62 | 
 63 | [Live demo, including all supporting code](https://jsbin.com/habubas/edit?html,output)
 64 | 
 65 | ### With declarative template stamping
 66 | 
 67 | ```js
 68 | const items = getTonsAndTonsOfItems();
 69 | window.itemList = new WinJS.Binding.List(items);
 70 | ```
 71 | 
 72 | ```html
 73 | <div id="template" data-win-control="WinJS.Binding.Template" style="display: none">
 74 |   <div data-win-bind="textContent: text"></div>
 75 | </div>
 76 | 
 77 | <div data-win-control="WinJS.UI.ListView"
 78 |      data-win-options="{
 79 |        itemDataSource: itemsList.dataSource,
 80 |        itemTemplate: select('#template'),
 81 |        layout: { type: WinJS.UI.ListLayout }
 82 |      }">
 83 | </div>
 84 | ```
 85 | 
 86 | [Live demo, including all supporting code](https://jsbin.com/sovobeh/edit?html,output)
 87 | 
 88 | ## Resulting DOM structure
 89 | 
 90 | ```html
 91 | <div data-win-control="WinJS.UI.ListView"
 92 |      data-win-options="... as given ..."
 93 |      class="win-disposable win-listview win-element-resize"
 94 |      role="listbox" aria-multiselectable="true" tabindex="-1"
 95 |      style="position: relative;">
 96 |   <div tabindex="0" aria-hidden="true"></div>
 97 |   <div tabindex="-1" role="group" class="win-viewport win-vertical" style="opacity: 1;" aria-label="Scrolling Container">
 98 |     <div id="element__86" aria-flowto="element__2"></div>
 99 |     <div class="win-headercontainer" style="opacity: 1;"></div>
100 |     <div class="win-surface win-listlayout win-nocssgrid _win-dynamic-containersize-0 win-structuralnodes win-single-itemsblock" style="width: 682px; opacity: 1;">
101 |       <div class="_win-proxy"></div>
102 |       <div class="win-itemscontainer win-uniformlistlayout" style="height: 8671px;">
103 |         <div class="win-itemscontainer-padder"></div>
104 |         <div class="win-itemsblock">
105 |           <div class="win-container win-container-even">
106 |             <div class="win-itembox">
107 |               <div tabindex="0" class="win-item" id="element__2" x-ms-aria-flowfrom="element__86" role="option" aria-setsize="299" aria-posinset="1" aria-flowto="element__16">1</div>
108 |             </div>
109 |           </div>
110 |           <div class="win-container win-container-odd">
111 |             <div class="win-itembox">
112 |               <div tabindex="0" class="win-item" id="element__16" x-ms-aria-flowfrom="element__2" role="option" aria-setsize="299" aria-posinset="2" aria-flowto="element__17">2</div>
113 |             </div>
114 |           </div>
115 |           ... repeats for 44 total items ...
116 |           <div class="win-container win-container-even win-backdrop"></div>
117 |           <div class="win-container win-container-odd win-backdrop"></div>
118 |           ... repeats for 255 total placeholders ...
119 |         </div>
120 |       </div>
121 |     </div>
122 |     <div class="win-footercontainer" style="opacity: 1; min-height: 0px;"></div>
123 |     <div id="element__87" x-ms-aria-flowfrom="element__28"></div>
124 |   </div>
125 |   <div tabindex="0" aria-hidden="true"></div>
126 |   <div aria-hidden="true" style="position:absolute;left:50%;top:50%;width:0px;height:0px;" tabindex="-1"></div>
127 |   <div style="animation-name: WinJS-node-inserted; animation-duration: 0.01s; position: absolute;"></div>
128 | </div>
129 | ```
130 | 
131 | ## Customization options
132 | 
133 | `ListView` is an industrial-strength control. Without even diving into the API documentation, you can tell from the Microsoft-provided demos that there are a lot of axes of customization:
134 | 
135 | - List vs. grid layout vs. cell spanning layout vs. custom layout.
136 | - Ability to create "groupings" of items within the list, with a header per grouping
137 | - Ability to select one or more items in the list
138 | - Headers and footers
139 | - A boolean switch to make the items drag-drop reorderable, which will reorder both the UI and the underlying data
140 | - A separate boolean switch to make the items draggable in general, e.g. to other parts of the UI; combines well with the previous one
141 | - A `footervisibilitychanged` event which provides an opportunity to know when to load more data
142 | - CSS classes, `win-container-even` and `win-container-odd`, which allow striping. (This seems unnecessary given that `:nth-of-type` would work fine?)
143 | 
144 | Note that the control comes with a default height of `400px`; it does not try to automatically infer from the items.
145 | 
146 | ## API
147 | 
148 | Going through the API documentation, here are some highlights not mentioned above:
149 | 
150 | - **Events**: various item dragging events, an item being "invoked" (clicked), keyboard navigation, loading state changes, selection changes
151 | - **Methods**: `elementFromIndex()`, `indexOfElement()`, some stuff related to loading of pages (??), some stuff that should never need to be called for re-doing layout
152 | - **Properties**: `currentItem`; `groupDataSource` vs. `itemDataSource`; `indexOf{First|Last}Visible`, properties for controlling how many items to "load" (render) before/after the currently-visible ones
153 | 
154 | ## Miscellaneous thoughts and takeaways
155 | 
156 | - The idea of requiring the data source to be wrapped into a custom class is interesting and perhaps useful. This avoids the diffing that many modern frameworks do.
157 | - The reliance on global variables to hook things up is very sad.
158 | - The way in which it modifies your markup, to insert classes, ARIA, `tabindex`, etc., is a little sad. We may be able to avoid some of this with shadow DOM?
159 | - They appear to dynamically create a CSS rule to set the placeholder items to be the same size as the other items. I haven't dug into the code to see what heuristic they use here (e.g., what happens if different items are different sizes).
160 | - It's heartening to see that both grid and list layouts appear to use the same DOM structure, with only CSS differences. Cell-spanning layout appears to use additional inline CSS to set `with`, `height`, and CSS grid properties.
161 | - It seems to use some concept of "page" to control loading behavior. I think this just means "how many items can fit on the screen".
162 | - The "item" abstraction, passed to the renderer function, is interesting; I can't find any API documentation for it, but it makes some sense. I don't quite understand why it's a promise, i.e. I don't understand in what scenario it might take some time to acquire the promise. But the framework for returning a custom placeholder then filling it in later seems nice.
163 | 
164 | ## Resources
165 | 
166 | - [Comprehensive API documentation](https://docs.microsoft.com/en-us/previous-versions/windows/apps/br211837(v=win.10))
167 | - [Optimizing `ListView` item rendering](https://blogs.msdn.microsoft.com/windowsappdev/2013/06/17/optimizing-listview-item-rendering/) blog post
168 | - Relevant tutorial sections:
169 |   - [Binding lists](http://try.buildwinjs.com/tutorial/2WinJS_Binding/bindingList/) shows how they expect you to wrap your data in a `WinJS.Binding.List`. To introduce this concept it uses a separate control, `Repeater`, which is much simpler than `ListView`.
170 |   - [Projections](http://try.buildwinjs.com/tutorial/3Control_Manipulation/projections/) talks about how you can create new `WinJS.Binding.List` instances "projected" from the original, e.g. a sorted one.
171 |   - [Binding templates](http://try.buildwinjs.com/tutorial/2WinJS_Binding/bindingTemplates/) shows how to use a `ListView` to stamp out templates
172 |   - [Function rendering](http://try.buildwinjs.com/tutorial/3Control_Manipulation/functionRend/) (i.e. imperative rendering) is the lower-level technology that underlies the template binding
173 | - Demos:
174 |   - [The new playground](http://try.buildwinjs.com/playground/) has three relevant demos, each of which demonstrate different ways to customize the `ListView`
175 |   - [The former playground](http://winjs.azurewebsites.net/) has the same demos with different presentation
176 |   - [This interactive demo](http://winjs.azurewebsites.net/pages/listview/options/default.html) lets you customize all the different options individually
177 | 


--------------------------------------------------------------------------------
/study-group/iOS-UITableView.md:
--------------------------------------------------------------------------------
  1 | # `UITableView` (iOS)
  2 | 
  3 | - Study Author: [@valdrinkoshi](https://github.com/valdrinkoshi)
  4 | - Platform: iOS
  5 | 
  6 | ## Background on iOS
  7 | 
  8 | [iOS](https://developer.apple.com/ios/) is a mobile operative system created and developed by Apple, and powers many of the company's mobile devices, including the iPhone, iPad, and iPod Touch.
  9 | 
 10 | The iOS SDK allows for the development of mobile apps on iOS.
 11 | Combined with [Xcode](https://developer.apple.com/xcode/), it helps developers write iOS apps using officially-supported programming languages, including [Swift](https://developer.apple.com/swift/) and [Objective-C](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html).
 12 | 
 13 | The iOS SDK ships the [UIKit framework](https://developer.apple.com/documentation/uikit), which provides the required infrastructure for building iOS apps: animation support, document support, drawing and printing support, information about the current device, text management and display, search support, accessibility support, app extension support, and resource management. UITableView is part of the UIKit framework.
 14 | 
 15 | ## Overview
 16 | 
 17 | UIKit provides 2 types of Container Views, to be used for organizing and presenting large data sets:
 18 | - [Table Views](https://developer.apple.com/documentation/uikit/views_and_controls/table_views) to display data in a single column of customizable rows
 19 | - [Collection Views](https://developer.apple.com/documentation/uikit/views_and_controls/collection_views) to display nested views using a configurable and highly customizable layout
 20 | 
 21 | Both are structured following the MVC model: a Controller initializes the View and the Model, reacts to events on the View and provides data to it through the Model.
 22 | 
 23 | Both [UITableView](https://developer.apple.com/documentation/uikit/uitableview) and [UICollectionView](https://developer.apple.com/documentation/uikit/uicollectionview):
 24 | - inherit from [UIScrollView](https://developer.apple.com/documentation/uikit/uiscrollview)
 25 | - rely on a `dataSource` for row/cell creation and data management, and expect data manipulation to be communicated via APIs like `deleteRows/deleteItems`
 26 | - use a `delegate` protocol to allow the delegate to manage sections, configure section headings and footers, help to delete and reorder cells, and perform other actions
 27 | - delegate accessibility concerns to the cell/row provider (the `dataSource`)
 28 | - expect rows/cells to extend `UITableViewCell/UICollectionViewCell`
 29 | 
 30 | ## Essential sample code
 31 | 
 32 | ```swift
 33 | class FirstViewController:
 34 |         UIViewController, UITableViewDataSource, UITableViewDelegate {
 35 | 
 36 |     override func viewDidLoad() {
 37 |         super.viewDidLoad()
 38 |         
 39 |         // Setup
 40 |         let tableView = UITableView(frame: self.view.bounds)
 41 |         // Create a new UITableViewCell if no reusable cell is available.
 42 |         tableView.register(UITableViewCell.self,
 43 |                            forCellReuseIdentifier: "MyCell")
 44 |         // Data provider.
 45 |         tableView.dataSource = self
 46 |         // Layout provider.
 47 |         tableView.delegate = self
 48 |         tableView.allowsMultipleSelection = true
 49 |         
 50 |         self.view.addSubview(tableView)
 51 |     }
 52 |     
 53 |     /* UITableViewDataSource methods */
 54 |     
 55 |     func tableView(_ tableView: UITableView,
 56 |                    numberOfRowsInSection section: Int) -> Int {
 57 |         return 1000
 58 |     }
 59 |     
 60 |     func tableView(_ tableView: UITableView,
 61 |                    cellForRowAt indexPath: IndexPath) -> UITableViewCell {
 62 | 
 63 |         // This will either reuse or lazily init a new cell.
 64 |         let cell = tableView.dequeueReusableCell(withIdentifier: "MyCell",
 65 |                                                  for: indexPath)
 66 |         
 67 |         // ALWAYS setup cell.
 68 |         cell.textLabel?.text = String(indexPath.row)
 69 |         if (indexPath.row % 2 == 0) {
 70 |             cell.textLabel?.textColor = UIColor.red
 71 |         } else {
 72 |             cell.textLabel?.textColor = UIColor.black
 73 |         }
 74 |         cell.accessibilityLabel = "Row number " + String(indexPath.row)
 75 |         
 76 |         return cell
 77 |     }
 78 |     
 79 |     /* UITableViewDelegate methods */
 80 |     
 81 |     func tableView(_ tableView: UITableView,
 82 |                    heightForRowAt indexPath: IndexPath) -> CGFloat {
 83 |         return 60;
 84 |     }
 85 |     
 86 |     func tableView(_ tableView: UITableView,
 87 |                    didSelectRowAt indexPath: IndexPath) {
 88 |         print("Num: \(indexPath.row)")
 89 |     }
 90 | 
 91 | }
 92 | ```
 93 | 
 94 | ## View organization and unidirectional data flow 
 95 | 
 96 | The separation of Container View from Cell View allows has several benefits, like easier coordination of selection states, cell manipulation and animations.
 97 | 
 98 | ### Container View
 99 | 
100 | Container Views force the user to separate data from view. 
101 | 
102 | `UITableView` requires the user to provide the data and layout information through the `UITableViewDataSource` and `UITableViewDelegate` protocols, and it controls the timing of when these calls are made. Some examples:
103 | 
104 | `tableView:cellForRowAtIndexPath:` is called by the `UITableView` on its `dataSource` when a cell is needed, this can be either when a cell is first shown, or when the user is scrolling and the cell will appear. It is the responsibility of the user to create a cell, and always update it with the information for a specific index path.
105 | 
106 | Likewise, `tableView:didSelectRowAt:` provides the hook to the user to perform an action on row selection, while at the same time allows `UITableView` to control when this should be triggered (e.g. not during an animation of that cell, nor during scrolling).
107 | 
108 | ### Cell View
109 | 
110 | `UITableViewCell` provides out-of-the-box features like selection management, state change animations, edit mode, accessory views (e.g. delete/details button).
111 | 
112 | The user is encouraged to extend `UITableViewCell` in order to customize the cell display. The cell should expose properties to be displayed and protocols to delegate the handling of events, e.g. This shopping cart item cell displays an item and delegates the click handling:
113 | ```swift
114 | 
115 | class ShoppingCartItem { /* model of the item */ }
116 | 
117 | protocol ShoppingCartItemCellDelegate: class {
118 |     func increaseQuantity(_ item: ShoppingCartItem)
119 | }
120 | 
121 | class ShoppingCartItemCell: UITableViewCell {
122 |     var item: ShoppingCartItem?
123 |     weak var delegate: ShoppingCartItemCellDelegate?
124 |     
125 |     // connect the button from your cell with this method
126 |     @IBAction func increaseButtonPressed(_ sender: UIButton) {
127 |         delegate?.increaseQuantity(item!)
128 |     }
129 | }
130 | 
131 | class FirstViewController: UIViewController, UITableViewDataSource, UITableViewDelegate,
132 |                            ShoppingCartItemCellDelegate {
133 |     
134 |     // ...
135 |     
136 |     func tableView(_ tableView: UITableView,
137 |                    cellForRowAt indexPath: IndexPath) -> UITableViewCell {
138 |         let cell = tableView.dequeueReusableCell(withIdentifier: "MyCell",
139 |                                                  for: indexPath) as! ShoppingCartItemCell; 
140 |         
141 |         cell.item = self.itemForPath(indexPath)
142 |         cell.delegate = self
143 |         
144 |         return cell
145 |     }
146 |     
147 |     func itemForPath(_ indexPath: IndexPath) -> ShoppingCartItem? {
148 |         // return the item somehow...    
149 |     }
150 |     
151 |     /* ShoppingCartItemCellDelegate method */
152 |     func increaseQuantity(_ item: ShoppingCartItem) {
153 |         // do stuff with item here...
154 |     }
155 | ```
156 | ### Data flow
157 | 
158 | The data flow is uni-directional, top to bottom: each update (layout/data) will be triggered through the Container View and forwarded down to the Cell views. It's the duty of the controller to listen for data changes and notify the Container View about it.
159 | 
160 | ## Noteworthy features & implementation details
161 | 
162 | - Having Container separated from Cell naturally pushes developers to move the layout logic into the cell, and expose clear APIs regarding which data each cell needs, and which events/actions it exposes
163 | - Delegation protocols enforce 1-to-1 event/action handling, and make the debugging experience slightly simpler
164 | - Actions that require coordination between multiple cells can be done using the methods `tableView.beginUpdates()` and `tableView.endUpdates()`. e.g. animate the row height, or add and remove multiple rows at the same time.
165 | - Accessibility is delegated to the provider of the data source. UIKit elements like labels and buttons already handle accessibility.
166 | 
167 | ## Resources
168 | 
169 | - [Smooth Scrolling in UITableView and UICollectionView](https://medium.com/capital-one-developers/smooth-scrolling-in-uitableview-and-uicollectionview-a012045d77f): how to optimize for optimal recycling
170 | - [Fluent pagination](http://www.iosnomad.com/blog/2014/4/21/fluent-pagination): best practices for avoiding jumpy scrolling
171 | - [UITableViewCell](https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/TableView_iPhone/TableViewCells/TableViewCells.html): 
172 | - [Table view reuse logic](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/TableView/TableViewOverview/TableViewOverview.html#//apple_ref/doc/uid/10000026i-CH2-SW10)
173 | 


--------------------------------------------------------------------------------
/w3c.json:
--------------------------------------------------------------------------------
1 |  {
2 |     "group":      [80485]
3 | ,   "contacts":   ["yoavweiss"]
4 | ,   "repo-type":  "cg-report"
5 | }
6 | 


--------------------------------------------------------------------------------