{"id":15386660,"url":"https://github.com/zerodevx/zero-list-hero","last_synced_at":"2025-04-14T09:30:51.499Z","repository":{"id":36657091,"uuid":"40963411","full_name":"zerodevx/zero-list-hero","owner":"zerodevx","description":"DEPRECATED - It's hero time! A Polymer 1.1+ web component that hero-animates and layouts a sequence of elements.","archived":false,"fork":false,"pushed_at":"2018-04-10T06:52:28.000Z","size":6949,"stargazers_count":15,"open_issues_count":2,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-27T22:48:35.664Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://zerodevx.github.io/zero-list-hero/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zerodevx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-18T09:37:02.000Z","updated_at":"2018-04-10T08:14:41.000Z","dependencies_parsed_at":"2022-08-31T09:20:37.362Z","dependency_job_id":null,"html_url":"https://github.com/zerodevx/zero-list-hero","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodevx%2Fzero-list-hero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodevx%2Fzero-list-hero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodevx%2Fzero-list-hero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodevx%2Fzero-list-hero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zerodevx","download_url":"https://codeload.github.com/zerodevx/zero-list-hero/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248854115,"owners_count":21172296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T14:50:05.468Z","updated_at":"2025-04-14T09:30:51.466Z","avatar_url":"https://github.com/zerodevx.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"v0.2.1\n# `\u003czero-list-hero\u003e`\n\nIt's hero time! A Polymer 1.1+ web component that hero-animates and layouts a\nsequence of elements. I do this so you don't have to.\n\n![demo.gif](https://zerodevx.github.io/zero-list-hero/images/demo.gif)\n\nFeaturing:\n* Automatic transitions.\n* NEW! Automatic responsive layout - masonry using first-fit algorithm à la\nPinterest.\n* Bespoke cascaded entry-exit effects à la Google Play Newsstand App.\n* Built-in debouncer.\n* Configurable animations.\n* Almost entirely declarative - works by itself!\n\n\n### Let's get this money\n\n1. Import `web-components-lite` polyfill.\n  ```html\n\u003cscript src=\"bower_components/webcomponentsjs/webcomponents-lite.js\"\u003e\u003c/script\u003e\n  ```\n\n2. Import `zero-list-hero` web component.\n  ```html\n\u003clink rel=\"import\" href=\"bower_components/zero-list-hero/zero-list-hero.html\"\u003e\n  ```\n\n3. Profit!\n\n  **Basic usage:**\n\n  ```html\n\u003czero-list-hero\u003e\n  \u003c!-- Dynamically append/remove elements inside here --\u003e\n  ...\n  \u003cdiv hero-id=\"hero1\"\u003eI'm Tom\u003c/div\u003e\n  \u003cdiv hero-id=\"hero3\"\u003eI'm Mary\u003c/div\u003e\n  \u003cdiv hero-id=\"hero2\"\u003eI'm John\u003c/div\u003e\n  ...\n\u003c/zero-list-hero\u003e\n  ```\n\n  **With Polymer's `dom-repeat`:**\n\n  ```html\n\u003czero-list-hero\u003e\n  \u003ctemplate is=\"dom-repeat\" items=\"[[list]]\"\u003e\n    \u003cmy-card hero-id$=\"[[item.foo]]\" foo$=\"[[item.foo]]\" bar$=\"[[item.bar]]\"\u003e\u003c/my-card\u003e\n  \u003c/template\u003e\n\u003c/zero-list-hero\u003e\n  ```\n\n  **Using built-in responsive masonry layout:**\n\n  ```html\n\u003czero-list-hero layout=\"masonry\"\u003e\n  \u003ctemplate is=\"dom-repeat\" items=\"[[list]]\"\u003e\n    \u003cmy-card hero-id$=\"[[item.foo]]\" foo$=\"[[item.foo]]\" bar$=\"[[item.bar]]\"\u003e\u003c/my-card\u003e\n  \u003c/template\u003e\n\u003c/zero-list-hero\u003e\n  ```\n\n\n### Implementation notes\n\n1. Assign a unique `hero-id` for every display element that is wrapped inside\nthe `\u003czero-list-hero\u003e...\u003c/zero-list-hero\u003e` tags.\n\n2. If you're using Polymer's data-binding (eg. inside a `dom-repeat` template),\nset your target attributes annotatively via the ***`$=`*** syntax.\n\n3. Transitions are automatic - create, update and remove operations on any\n`hero` element is detected, consolidated and debounced with a default delay of\n500ms (optionally change delay timing using `debounce-delay` attribute).\n\n4. Note that automatic transitions **do not work** under native shadow DOM\nbehaviour.\n\n\n### Layout\n\n`\u003czero-list-hero\u003e` now handles the layout of children hero elements\nresponsively. To enable this feature, set the `layout` (and optionally the\n`layoutOptions`) attribute declaratively in your HTML.\n\n**Included layouts**\n\nCurrently, only *Masonry* layout is shipped. `\u003czero-list-hero\u003e`'s definition\nof this is a *left-to-right* display of a sequence of *fixed width*, *variable\nheight* elements:\n\n![masonry-demo.png](https://zerodevx.github.io/zero-list-hero/images/masonry-demo.png)\n\nLayout is responsive; bin-packing is based on a first-fit algorithm where the\nnext element is placed into the shortest column.\n\n**Layout attributes**\n\n| Attribute     | Type     | Values         | Description |\n|---------------|----------|----------------|-------------|\n| layout        | String   | masonry        | A *left-to-right* display of a sequence of *fixed width*, *variable height* hero elements. |\n| layoutOptions | Object   | \"breakpoint\"   | *Number* in px (default is 300) for the breakpoint multiple (ie. max-width of each column) before `\u003czero-list-hero\u003e` attempts to repack the display elements again. |\n\nNote that `layoutOptions` takes in a JSON object; it must be properly formatted\nvalid JSON. This means that properties (and *String* values if applicable) must\nbe wrapped with *double-quotes* ***\"\"***.\n\n**Example of Masonry layout, breakpoint of 100px**\n\n```html\n...\n\u003czero-list-hero layout=\"masonry\" layout-options='{\"breakpoint\": 100}'\u003e\n  \u003cdiv hero-id=\"1\"\u003eRed\u003c/div\u003e\n  \u003cdiv hero-id=\"2\"\u003eBlue\u003c/div\u003e\n  \u003cdiv hero-id=\"3\"\u003eGreen\u003c/div\u003e\n  ...\n\u003c/zero-list-hero\u003e\n```\n\n\n### Styling\n\nIf you're using Polymer, follow the Polymer-pattern and style hero elements\nusing the exposed custom CSS mixin `--zero-list-hero-item-mixin`. The mixin\nwill be applied on every hero element that is displayed.\n\n**Example styling using Polymer's custom CSS**\n\n```html\n...\n\u003ctemplate\u003e\n  \u003cstyle\u003e\n    :host {\n      --zero-list-hero-item-mixin: {\n        background-color: blue;\n        font-size: 24px;\n        height: 96px;\n      };\n    }\n  \u003c/style\u003e\n  \u003czero-list-hero\u003e\n    \u003cdiv hero-id=\"1\"\u003eItem 1\u003c/div\u003e\n    \u003cdiv hero-id=\"2\"\u003eItem 2\u003c/div\u003e\n    \u003cdiv hero-id=\"3\"\u003eItem 3\u003c/div\u003e\n    ...\n  \u003c/zero-list-hero\u003e\n\u003c/template\u003e\n```\n\nIf you are using `\u003czero-list-hero\u003e` as an individual component, it runs by\ndefault under *Shady DOM*, so you can simply style your hero elements directly.\n\n**Example styling using simple CSS**\n\n```html\n\u003cstyle\u003e\n  .my-element {\n    background-color: blue;\n    font-size: 24px;\n    height: 96px;\n  }\n\u003c/style\u003e\n\u003czero-list-hero\u003e\n  \u003cdiv hero-id=\"1\" class=\"my-element\"\u003eItem 1\u003c/div\u003e\n  \u003cdiv hero-id=\"2\" class=\"my-element\"\u003eItem 2\u003c/div\u003e\n  \u003cdiv hero-id=\"3\" class=\"my-element\"\u003eItem 3\u003c/div\u003e\n  ...\n\u003c/zero-list-hero\u003e\n```\n\n\n### Shady vs Shadow\n\nEssentially, changes to contents inside the `\u003czero-list-hero\u003e` tag are observed\nthrough the *MutationObservers* API - when change is detected, the `animate()`\nmethod is automatically called to start the transition.\n\nUnfortunately, *mutation observers* are currently unable to detect changes to\ndistributed nodes under native shadow behavior. Ongoing spec discussions can be\nfound [here](https://groups.google.com/forum/#!msg/polymer-dev/GMYzuuqlQ7k/2-gxqwJdNpcJ)\nand [here](https://bugzilla.mozilla.org/show_bug.cgi?id=1026236).\n\nTherefore, if you are using `\u003czero-list-hero\u003e` natively, detect changes\n*outside* the component and manually call the `animate()` method. Asserting\nthe `manual` attribute disables *MutationObservers* usage entirely.\n\nSo unless you plan to stick with shady DOM for the forever, future-proof your\napp by disabling automatic transitions and wire up your change observers\nmanually. As a recommended pattern (that works under BOTH ***Shady*** and\n***Shadow DOM***):\n\n`parent-element.html`\n\n```html\n\u003clink rel=\"import\" href=\"bower_components/zero-list-hero/zero-list-hero.html\"\u003e\n\u003clink rel=\"import\" href=\"elements/my-card.html\"\u003e\n\u003cdom-module id=\"parent-element\"\u003e\n  \u003ctemplate\u003e\n    ...\n    \u003czero-list-hero id=\"myhero\" manual\u003e\n      \u003ctemplate is=\"dom-repeat\" items=\"{{list}}\"\u003e\n        \u003cmy-card hero-id$=\"{{list.id}}\" card-id=\"{{item.id}}\" card-name=\"{{item.name}}\"\u003e\u003c/my-card\u003e\n      \u003c/template\u003e\n    \u003c/zero-list-hero\u003e\n    ...\n  \u003c/template\u003e\n  \u003cscript\u003e\n    Polymer({\n      is: \"parent-element\",\n      properties: {\n        list: { type: Array, value: function () { return []; } }\n      },\n      observers: [\n        \"listChanged(list.*)\"\n      ],\n      listChanged: function (changeRecord) {\n        this.$.myhero.animate();\n      }\n      ...\n    });\n  \u003c/script\u003e\n\u003c/dom-module\u003e\n\n```\n\n**UPDATE: 2015-10-07**\n\nBREAKING CHANGE - what is previously known as `shadow` attribute has now been\n**renamed** to `manual` attribute.\n\n\n### Other issues\n\n1. Polymer has an ongoing issue retrieving distributed content nodes through\n`Polymer.dom(content).getDistributedNodes()`. The bug has been filed\n[here](https://github.com/Polymer/polymer/issues/2283). As a workaround,\n`\u003czero-list-hero\u003e` will first try retrieving nodes via vanilla js (which works\nunder ***Shady*** behavior), and will silently fall back to Polymer's `domAPI`\nshould ***Shadow*** behavior be detected.\n\n**UPDATE: 2015-10-07**\n\nThe bug has been [fixed](https://github.com/Polymer/polymer/issues/2283).\nRetrieval of content nodes will from v0.2.0 onwards will use the normalised\n`domAPI.getDistributedNodes()` method.\n\n\n### Demos\n\n**Simple demo**\n\n![simple-demo.png](https://zerodevx.github.io/zero-list-hero/images/simple-demo.png)\n\nhttps://zerodevx.github.io/zero-list-hero/simple-demo.html\n\n**Demo using `dom-repeat`**\n\n![dom-repeat-demo.png](https://zerodevx.github.io/zero-list-hero/images/dom-repeat-demo.png)\n\nhttps://zerodevx.github.io/zero-list-hero/dom-repeat-demo.html\n\n**Demo under native shadow-dom behavior**\n\n![shadow-demo.png](https://zerodevx.github.io/zero-list-hero/images/shadow-demo.png)\n\nhttps://zerodevx.github.io/zero-list-hero/shadow-demo.html\n\n**Use in-built masonry layout**\n\n![masonry-demo.png](https://zerodevx.github.io/zero-list-hero/images/masonry-demo.png)\n\nhttps://zerodevx.github.io/zero-list-hero/masonry-demo.html\n\n**Go crazy with Material Design - a demo Newsreader App**\n\n![newsreader-demo.png](https://zerodevx.github.io/zero-list-hero/images/newsreader-demo.png)\n\nhttps://zerodevx.github.io/zero-list-hero/newsreader-demo.html\n\n\n### Published properties\n\n| Property        | Type    | Description |\n|-----------------|---------|-------------|\n| debounceDelay   | Number  | Debounce delay between consolidating changes to `hero` elements and actually starting the transition; defaults to 500ms. |\n| cascadeDelay    | Number  | Animation delay between multiple additions or removals of `hero` elements; defaults to 50ms. |\n| 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. |\n| 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. |\n| manual          | Boolean | If `true`, disables *MutationObserver* usage. Manually call the `animate()` method to trigger the transitions. |\n| inTransit       | Boolean | Read-only convenience property; switches to `true` whenever a transition is ongoing. |\n| layout          | String  | Allowed values: [\"masonry\"]. Use `\u003czero-list-hero\u003e` to handle element layout. At the moment, only 'masonry' layout is shipped.\n| 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. |\n\n\n### Public methods\n\n| Method    | Parameters | Description |\n|-----------|------------|-------------|\n| animate() | *none*     | Starts the transition process. Under ***shady*** dom behavior, this method is automatically called whenever changes are detected by the *MutationObserver* API. |\n\n\n### Exposed CSS mixins\n\n| Name                        | Description |\n|-----------------------------|-------------|\n| --zero-list-hero-item-mixin | Basket of CSS style rules to be applied to every `.zero-list-hero-item`. |\n\n\n### Installation\n\nInstall through bower.\n\n    bower install --save zerodevx/zero-list-hero#^0.2.1\n\nAlternatively, download the project as a ZIP file and unpack into your\ncomponents directory. `\u003czero-list-hero\u003e` uses the following:\n* `Polymer`:\nhttps://github.com/Polymer/polymer\n* Polymer Elements' `\u003cneon-animation\u003e`:\nhttps://github.com/PolymerElements/neon-animation\n* Polymer Elements' `\u003ciron-resizable-behavior\u003e` for viewport change detection\n(and to play nicely with other Googly components):\nhttps://github.com/PolymerElements/iron-resizable-behavior\n* zerodevx's `\u003cpolymer-style-modules\u003e` for `iron-flex-layout` style module\n(because `/deep/` and other shadow-piercing combinators are deprecated):\nhttps://github.com/zerodevx/polymer-style-modules\n* as well as their related dependencies.\n\nSource provided as-is - no assumptions are made on your production build\nworkflow.\n\n\n### License\n\nMIT, though I'll greatly appreciate a note if you find this useful.\n\n\n### Version history\n\n1. 2015-08-19: v0.1.0\n  * Initial commit.\n\n2. 2015-10-07: v0.2.0\n  * BREAKING: `shadow` attribute renamed to `manual`.\n  * Add automatic layout layer (included layout: Masonry).\n  * Remove shadow dom detection workaround for content nodes retrieval.\n  * Use `\u003cneon-animation\u003e`'s in-built animatable wrapper instead.\n  * Improve async dom write timing resolutions.\n  * Other performance improvements.\n\n3. 2015-10-12: v0.2.1\n  * Updated README.md.\n  * Cleaned up stray comments in `zero-list-hero.html`.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodevx%2Fzero-list-hero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzerodevx%2Fzero-list-hero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodevx%2Fzero-list-hero/lists"}