├── .gitignore ├── LICENSE.txt ├── README.md ├── bower.json ├── demo ├── demos.html ├── dom-repeat-demo.html ├── masonry-demo.html ├── parent-element.html ├── shadow-demo.html ├── simple-card.html └── simple-demo.html └── zero-list-hero.html /.gitignore: -------------------------------------------------------------------------------- 1 | bower_components/ 2 | images/ 3 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Jason JC Lee 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | v0.2.1 2 | # `` 3 | 4 | It's hero time! A Polymer 1.1+ web component that hero-animates and layouts a 5 | sequence of elements. I do this so you don't have to. 6 | 7 | ![demo.gif](https://zerodevx.github.io/zero-list-hero/images/demo.gif) 8 | 9 | Featuring: 10 | * Automatic transitions. 11 | * NEW! Automatic responsive layout - masonry using first-fit algorithm à la 12 | Pinterest. 13 | * Bespoke cascaded entry-exit effects à la Google Play Newsstand App. 14 | * Built-in debouncer. 15 | * Configurable animations. 16 | * Almost entirely declarative - works by itself! 17 | 18 | 19 | ### Let's get this money 20 | 21 | 1. Import `web-components-lite` polyfill. 22 | ```html 23 | 24 | ``` 25 | 26 | 2. Import `zero-list-hero` web component. 27 | ```html 28 | 29 | ``` 30 | 31 | 3. Profit! 32 | 33 | **Basic usage:** 34 | 35 | ```html 36 | 37 | 38 | ... 39 |
I'm Tom
40 |
I'm Mary
41 |
I'm John
42 | ... 43 |
44 | ``` 45 | 46 | **With Polymer's `dom-repeat`:** 47 | 48 | ```html 49 | 50 | 53 | 54 | ``` 55 | 56 | **Using built-in responsive masonry layout:** 57 | 58 | ```html 59 | 60 | 63 | 64 | ``` 65 | 66 | 67 | ### Implementation notes 68 | 69 | 1. Assign a unique `hero-id` for every display element that is wrapped inside 70 | the `...` tags. 71 | 72 | 2. If you're using Polymer's data-binding (eg. inside a `dom-repeat` template), 73 | set your target attributes annotatively via the ***`$=`*** syntax. 74 | 75 | 3. Transitions are automatic - create, update and remove operations on any 76 | `hero` element is detected, consolidated and debounced with a default delay of 77 | 500ms (optionally change delay timing using `debounce-delay` attribute). 78 | 79 | 4. Note that automatic transitions **do not work** under native shadow DOM 80 | behaviour. 81 | 82 | 83 | ### Layout 84 | 85 | `` now handles the layout of children hero elements 86 | responsively. To enable this feature, set the `layout` (and optionally the 87 | `layoutOptions`) attribute declaratively in your HTML. 88 | 89 | **Included layouts** 90 | 91 | Currently, only *Masonry* layout is shipped. ``'s definition 92 | of this is a *left-to-right* display of a sequence of *fixed width*, *variable 93 | height* elements: 94 | 95 | ![masonry-demo.png](https://zerodevx.github.io/zero-list-hero/images/masonry-demo.png) 96 | 97 | Layout is responsive; bin-packing is based on a first-fit algorithm where the 98 | next element is placed into the shortest column. 99 | 100 | **Layout attributes** 101 | 102 | | Attribute | Type | Values | Description | 103 | |---------------|----------|----------------|-------------| 104 | | layout | String | masonry | A *left-to-right* display of a sequence of *fixed width*, *variable height* hero elements. | 105 | | layoutOptions | Object | "breakpoint" | *Number* in px (default is 300) for the breakpoint multiple (ie. max-width of each column) before `` attempts to repack the display elements again. | 106 | 107 | Note that `layoutOptions` takes in a JSON object; it must be properly formatted 108 | valid JSON. This means that properties (and *String* values if applicable) must 109 | be wrapped with *double-quotes* ***""***. 110 | 111 | **Example of Masonry layout, breakpoint of 100px** 112 | 113 | ```html 114 | ... 115 | 116 |
Red
117 |
Blue
118 |
Green
119 | ... 120 |
121 | ``` 122 | 123 | 124 | ### Styling 125 | 126 | If you're using Polymer, follow the Polymer-pattern and style hero elements 127 | using the exposed custom CSS mixin `--zero-list-hero-item-mixin`. The mixin 128 | will be applied on every hero element that is displayed. 129 | 130 | **Example styling using Polymer's custom CSS** 131 | 132 | ```html 133 | ... 134 | 151 | ``` 152 | 153 | If you are using `` as an individual component, it runs by 154 | default under *Shady DOM*, so you can simply style your hero elements directly. 155 | 156 | **Example styling using simple CSS** 157 | 158 | ```html 159 | 166 | 167 |
Item 1
168 |
Item 2
169 |
Item 3
170 | ... 171 |
172 | ``` 173 | 174 | 175 | ### Shady vs Shadow 176 | 177 | Essentially, changes to contents inside the `` tag are observed 178 | through the *MutationObservers* API - when change is detected, the `animate()` 179 | method is automatically called to start the transition. 180 | 181 | Unfortunately, *mutation observers* are currently unable to detect changes to 182 | distributed nodes under native shadow behavior. Ongoing spec discussions can be 183 | found [here](https://groups.google.com/forum/#!msg/polymer-dev/GMYzuuqlQ7k/2-gxqwJdNpcJ) 184 | and [here](https://bugzilla.mozilla.org/show_bug.cgi?id=1026236). 185 | 186 | Therefore, if you are using `` natively, detect changes 187 | *outside* the component and manually call the `animate()` method. Asserting 188 | the `manual` attribute disables *MutationObservers* usage entirely. 189 | 190 | So unless you plan to stick with shady DOM for the forever, future-proof your 191 | app by disabling automatic transitions and wire up your change observers 192 | manually. As a recommended pattern (that works under BOTH ***Shady*** and 193 | ***Shadow DOM***): 194 | 195 | `parent-element.html` 196 | 197 | ```html 198 | 199 | 200 | 201 | 210 | 225 | 226 | 227 | ``` 228 | 229 | **UPDATE: 2015-10-07** 230 | 231 | BREAKING CHANGE - what is previously known as `shadow` attribute has now been 232 | **renamed** to `manual` attribute. 233 | 234 | 235 | ### Other issues 236 | 237 | 1. Polymer has an ongoing issue retrieving distributed content nodes through 238 | `Polymer.dom(content).getDistributedNodes()`. The bug has been filed 239 | [here](https://github.com/Polymer/polymer/issues/2283). As a workaround, 240 | `` will first try retrieving nodes via vanilla js (which works 241 | under ***Shady*** behavior), and will silently fall back to Polymer's `domAPI` 242 | should ***Shadow*** behavior be detected. 243 | 244 | **UPDATE: 2015-10-07** 245 | 246 | The bug has been [fixed](https://github.com/Polymer/polymer/issues/2283). 247 | Retrieval of content nodes will from v0.2.0 onwards will use the normalised 248 | `domAPI.getDistributedNodes()` method. 249 | 250 | 251 | ### Demos 252 | 253 | **Simple demo** 254 | 255 | ![simple-demo.png](https://zerodevx.github.io/zero-list-hero/images/simple-demo.png) 256 | 257 | https://zerodevx.github.io/zero-list-hero/simple-demo.html 258 | 259 | **Demo using `dom-repeat`** 260 | 261 | ![dom-repeat-demo.png](https://zerodevx.github.io/zero-list-hero/images/dom-repeat-demo.png) 262 | 263 | https://zerodevx.github.io/zero-list-hero/dom-repeat-demo.html 264 | 265 | **Demo under native shadow-dom behavior** 266 | 267 | ![shadow-demo.png](https://zerodevx.github.io/zero-list-hero/images/shadow-demo.png) 268 | 269 | https://zerodevx.github.io/zero-list-hero/shadow-demo.html 270 | 271 | **Use in-built masonry layout** 272 | 273 | ![masonry-demo.png](https://zerodevx.github.io/zero-list-hero/images/masonry-demo.png) 274 | 275 | https://zerodevx.github.io/zero-list-hero/masonry-demo.html 276 | 277 | **Go crazy with Material Design - a demo Newsreader App** 278 | 279 | ![newsreader-demo.png](https://zerodevx.github.io/zero-list-hero/images/newsreader-demo.png) 280 | 281 | https://zerodevx.github.io/zero-list-hero/newsreader-demo.html 282 | 283 | 284 | ### Published properties 285 | 286 | | Property | Type | Description | 287 | |-----------------|---------|-------------| 288 | | debounceDelay | Number | Debounce delay between consolidating changes to `hero` elements and actually starting the transition; defaults to 500ms. | 289 | | cascadeDelay | Number | Animation delay between multiple additions or removals of `hero` elements; defaults to 50ms. | 290 | | addAnimation | String | [Animation](https://github.com/PolymerElements/neon-animation/tree/master/animations) to use when `hero` elements are **added** into view; if unspecified, a special `zero-entry-animation` custom animation is used. | 291 | | removeAnimation | String | [Animation](https://github.com/PolymerElements/neon-animation/tree/master/animations) to use when `hero` elements are **removed** from view; if unspecified, a special `zero-exit-animation` custom animation is used. | 292 | | manual | Boolean | If `true`, disables *MutationObserver* usage. Manually call the `animate()` method to trigger the transitions. | 293 | | inTransit | Boolean | Read-only convenience property; switches to `true` whenever a transition is ongoing. | 294 | | layout | String | Allowed values: ["masonry"]. Use `` to handle element layout. At the moment, only 'masonry' layout is shipped. 295 | | layoutOptions | Object | Allowed values: [ { "breakpoint": *Number* } ]. Under 'masonry' layout mechanism, sets the "width" of each column in px before an attempt to add/remove a column is made. Defaults to 300. | 296 | 297 | 298 | ### Public methods 299 | 300 | | Method | Parameters | Description | 301 | |-----------|------------|-------------| 302 | | animate() | *none* | Starts the transition process. Under ***shady*** dom behavior, this method is automatically called whenever changes are detected by the *MutationObserver* API. | 303 | 304 | 305 | ### Exposed CSS mixins 306 | 307 | | Name | Description | 308 | |-----------------------------|-------------| 309 | | --zero-list-hero-item-mixin | Basket of CSS style rules to be applied to every `.zero-list-hero-item`. | 310 | 311 | 312 | ### Installation 313 | 314 | Install through bower. 315 | 316 | bower install --save zerodevx/zero-list-hero#^0.2.1 317 | 318 | Alternatively, download the project as a ZIP file and unpack into your 319 | components directory. `` uses the following: 320 | * `Polymer`: 321 | https://github.com/Polymer/polymer 322 | * Polymer Elements' ``: 323 | https://github.com/PolymerElements/neon-animation 324 | * Polymer Elements' `` for viewport change detection 325 | (and to play nicely with other Googly components): 326 | https://github.com/PolymerElements/iron-resizable-behavior 327 | * zerodevx's `` for `iron-flex-layout` style module 328 | (because `/deep/` and other shadow-piercing combinators are deprecated): 329 | https://github.com/zerodevx/polymer-style-modules 330 | * as well as their related dependencies. 331 | 332 | Source provided as-is - no assumptions are made on your production build 333 | workflow. 334 | 335 | 336 | ### License 337 | 338 | MIT, though I'll greatly appreciate a note if you find this useful. 339 | 340 | 341 | ### Version history 342 | 343 | 1. 2015-08-19: v0.1.0 344 | * Initial commit. 345 | 346 | 2. 2015-10-07: v0.2.0 347 | * BREAKING: `shadow` attribute renamed to `manual`. 348 | * Add automatic layout layer (included layout: Masonry). 349 | * Remove shadow dom detection workaround for content nodes retrieval. 350 | * Use ``'s in-built animatable wrapper instead. 351 | * Improve async dom write timing resolutions. 352 | * Other performance improvements. 353 | 354 | 3. 2015-10-12: v0.2.1 355 | * Updated README.md. 356 | * Cleaned up stray comments in `zero-list-hero.html`. 357 | 358 | -------------------------------------------------------------------------------- /bower.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "zero-list-hero", 3 | "version": "0.2.1", 4 | "authors": [ 5 | "Jason JC Lee " 6 | ], 7 | "description": "It's hero time! A Polymer 1.1+ web component that hero-animates a sequence of elements.", 8 | "keywords": [ 9 | "web-components", 10 | "polymer", 11 | "neon-animation", 12 | "hero", 13 | "animations", 14 | "layout", 15 | "masonry" 16 | ], 17 | "main": "zero-list-hero.html", 18 | "license": "https://github.com/zerodevx/zero-list-hero/blob/master/LICENSE", 19 | "homepage": "https://github.com/zerodevx/zero-list-hero/", 20 | "ignore": [ 21 | "/.*", 22 | "/test/" 23 | ], 24 | "dependencies": { 25 | "polymer": "Polymer/polymer#^1.1.0", 26 | "neon-animation": "PolymerElements/neon-animation#^1.0.0", 27 | "iron-resizable-behavior": "PolymerElements/iron-resizable-behavior#^1.0.0", 28 | "polymer-style-modules": "zerodevx/polymer-style-modules#^1.0.0" 29 | } 30 | } 31 | -------------------------------------------------------------------------------- /demo/demos.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | <zero-list-hero> demo catalogue 6 | 7 | 8 | 9 | 10 |

<zero-list-hero> demo catalogue


11 | Simple Demo

12 | With `dom-repeat`

13 | Using native shadow DOM

14 | Masonry layout demo

15 | 16 | 17 | -------------------------------------------------------------------------------- /demo/dom-repeat-demo.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | <zero-list-hero> dom-repeat demo 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 18 | 19 |

<zero-list-hero> dom-repeat demo

20 | 21 | 22 | 23 |

24 | 25 | 34 | 35 | 96 | 97 | 98 | 99 | -------------------------------------------------------------------------------- /demo/masonry-demo.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | <zero-list-hero> masonry layout demo 6 | 7 | 8 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 34 | 35 |

<zero-list-hero> masonry layout demo (resize me!)

36 | 37 | 38 |

39 | 40 | 41 |
1
42 |
2
43 |
3
44 |
4
45 |
5
46 |
6
47 |
7
48 |
8
49 |
9
50 |
10
51 |
52 | 53 | 97 | 98 | 99 | 100 | -------------------------------------------------------------------------------- /demo/parent-element.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 9 | 10 | 24 | 25 | 83 | 84 | -------------------------------------------------------------------------------- /demo/shadow-demo.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | <zero-list-hero> shadow-dom demo 6 | 7 | 8 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 23 | 24 | 25 | -------------------------------------------------------------------------------- /demo/simple-card.html: -------------------------------------------------------------------------------- 1 | 2 | 19 | 25 | 34 | 35 | -------------------------------------------------------------------------------- /demo/simple-demo.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | <zero-list-hero> simple demo 6 | 7 | 8 | 12 | 13 | 14 | 15 | 16 | 17 | 27 | 28 |

<zero-list-hero> simple demo

29 | 30 | 31 | 32 |

33 | 34 | 35 |
I'm Tom
36 |
I'm Mary
37 |
I'm John
38 |
39 | 40 | 96 | 97 | 98 | 99 | -------------------------------------------------------------------------------- /zero-list-hero.html: -------------------------------------------------------------------------------- 1 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 53 | 54 | 55 | 316 | --------------------------------------------------------------------------------