third_party/web-animations-js/sources/README.md

   1
   2 Quick Start
   3 -----------
   4
   5 To provide native Chrome Web Animation features (`Element.animate` and Playback
   6 Control) in other browsers, use `web-animations.min.js`. To explore all of the
   7 proposed Web Animations API, use `web-animations-next.min.js`.
   8
   9 What is Web Animations?
  10 -----------------------
  11
  12 Web Animations is a new JavaScript API for driving animated content on the web.
  13 By unifying the animation features of SVG and CSS, Web Animations unlocks
  14 features previously only usable declaratively, and exposes powerful,
  15 high-performance animation capabilities to developers.
  16
  17 For more details see the
  18 [W3C specification](http://w3c.github.io/web-animations/).
  19
  20 What is the polyfill?
  21 ---------------------
  22
  23 The polyfill is a JavaScript implementation of the Web Animations API. It works
  24 on modern versions of all major browsers. For more details about browser
  25 support see <https://www.polymer-project.org/resources/compatibility.html>.
  26
  27 Getting Started
  28 ---------------
  29
  30 Here's a simple example of an animation that scales and changes the opacity of
  31 a `<div>` over 0.5 seconds. The animation alternates producing a pulsing
  32 effect.
  33
  34     <script src="web-animations.min.js"></script>
  35     <div class="pulse" style="width:150px;">Hello world!</div>
  36     <script>
  37         var elem = document.querySelector('.pulse');
  38         var animation = elem.animate([
  39             {opacity: 0.5, transform: "scale(0.5)"},
  40             {opacity: 1.0, transform: "scale(1)"}
  41         ], {
  42             direction: 'alternate',
  43             duration: 500,
  44             iterations: Infinity
  45         });
  46     </script>
  47
  48 Web Animations supports off-main-thread animations, and also allows procedural
  49 generation of animations and fine-grained control of animation playback. See
  50 <http://web-animations.github.io> for ideas and inspiration!
  51
  52 Native Fallback
  53 ---------------
  54
  55 When the polyfill runs on a browser that implements `Element.animate` and
  56 `Animation` Playback Control it will detect and use the underlying native
  57 features.
  58
  59 Different Build Targets
  60 -----------------------
  61
  62 ### web-animations.min.js
  63
  64 Tracks the Web Animations features that are supported natively in browsers.
  65 Today that means Element.animate and Playback Control in Chrome. If you’re not
  66 sure what features you will need, start with this.
  67
  68 ### web-animations-next.min.js
  69
  70 Contains all of web-animations.min.js plus features that are still undergoing
  71 discussion or have yet to be implemented natively.
  72
  73 ### web-animations-next-lite.min.js
  74
  75 A cut down version of web-animations-next, it removes several lesser used
  76 property handlers and some of the larger and less used features such as matrix
  77 interpolation/decomposition.
  78
  79 ### Build Target Comparison
  80
  81 |                        | web-animations | web-animations-next | web-animations-next-lite |
  82 |------------------------|:--------------:|:-------------------:|:------------------------:|
  83 |Size (gzipped)          | 12.5kb         | 14kb                | 10.5kb                   |
  84 |Element.animate         | ✔             | ✔                  | ✔                       |
  85 |Timing input (easings, duration, fillMode, etc.) for animation effects| ✔ | ✔ | ✔             |
  86 |Playback control        | ✔             | ✔                  | ✔                       |
  87 |Support for animating lengths, transforms and opacity| ✔ | ✔ | ✔                       |
  88 |Support for animating other CSS properties| ✔ | ✔            | 🚫                       |
  89 |Matrix fallback for transform animations | ✔ | ✔             | 🚫                       |
  90 |KeyframeEffect constructor   | 🚫             | ✔                  | ✔                       |
  91 |Simple GroupEffects & SequenceEffects           | 🚫             | ✔                  | ✔                       |
  92 |Custom Effects          | 🚫             | ✔                  | ✔                       |
  93 |Timing input (easings, duration, fillMode, etc.) for groups</div>| 🚫 | 🚫\* | 🚫         |
  94 |Additive animation      | 🚫\*           | 🚫\*                | 🚫                       |
  95 |Motion path             | 🚫\*           | 🚫\*                | 🚫                       |
  96 |Modifiable keyframe effect timing| 🚫          | 🚫\*                | 🚫\*                     |
  97 |Modifiable group timing | 🚫             | 🚫\*                | 🚫\*                     |
  98 |Usable inline style\*\* | ✔             | ✔                  | 🚫                       |
  99
 100 \* support is planned for these features.
 101 \*\* see inline style caveat below.
 102
 103 Caveats
 104 -------
 105
 106 Some things won’t ever be faithful to the native implementation due to browser
 107 and CSS API limitations. These include:
 108
 109 ### Inline Style
 110
 111 Inline style modification is the mechanism used by the polyfill to animate
 112 properties. Both web-animations and web-animations-next incorporate a module
 113 that emulates a vanilla inline style object, so that style modification from
 114 JavaScript can still work in the presence of animations. However, to keep the
 115 size of web-animations-next-lite as small as possible, the style emulation
 116 module is not included. When using this version of the polyfill, JavaScript
 117 inline style modification will be overwritten by animations.
 118 Due to browser constraints inline style modification is not supported on iOS 7
 119 or Safari 6 (or earlier versions).
 120
 121 ### Prefix handling
 122
 123 The polyfill will automatically detect the correctly prefixed name to use when
 124 writing animated properties back to the platform. Where possible, the polyfill
 125 will only accept unprefixed versions of experimental features. For example:
 126
 127     var effect = new KeyframeEffect(elem, {"transform": "translate(100px, 100px)"}, 2000);
 128
 129 will work in all browsers that implement a conforming version of transform, but
 130
 131     var effect = new KeyframeEffect(elem, {"-webkit-transform": "translate(100px, 100px)"}, 2000);
 132
 133 will not work anywhere.
 134
 135 API and Specification Feedback
 136 ------------------------------
 137
 138 File an issue on GitHub: <https://github.com/w3c/web-animations/issues/new>.
 139 Alternatively, send an email to <public-fx@w3.org> with subject line
 140 “[web-animations] … message topic …”
 141 ([archives](http://lists.w3.org/Archives/Public/public-fx/)).
 142
 143 Polyfill Issues
 144 ---------------
 145
 146 Report any issues with this implementation on GitHub:
 147 <https://github.com/web-animations/web-animations-next/issues/new>.
 148
 149 Breaking changes
 150 ----------------
 151
 152 When we make a potentially breaking change to the polyfill's API
 153 surface (like a rename) we will, where possible, continue supporting the
 154 old version, deprecated, for three months, and ensure that there are
 155 console warnings to indicate that a change is pending. After three
 156 months, the old version of the API surface (e.g. the old version of a
 157 function name) will be removed. *If you see deprecation warnings you
 158 can't avoid it by not updating*.
 159
 160 We also announce anything that isn't a bug fix on
 161 [web-animations-changes@googlegroups.com](https://groups.google.com/forum/#!forum/web-animations-changes).