diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad62b8c..b8325b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,7 +54,7 @@ Example: `http://localhost:9876/base/test/web-platform-tests/web-animations/anim "version": "3.13.37", ``` -1. Build the polyfill with `npm install && grunt` then update `README.md`'s Build Target Comparison with the current gzipped sizes. +1. Build the polyfill with `npm install && grunt` then update `docs/experimental.md`'s Build Target Comparison with the current gzipped sizes. 1. Submit both changes to web-animations-next then follow the procedure to push from web-animations-next to web-animations-js. diff --git a/README.md b/README.md index 0739e37..e3410b6 100644 --- a/README.md +++ b/README.md @@ -1,172 +1,80 @@ -Quick Start ------------ - -To provide native Chrome Web Animation features (`Element.animate` and Playback -Control) in other browsers, use `web-animations.min.js`. To explore all of the -proposed Web Animations API, use `web-animations-next.min.js`. - What is Web Animations? ----------------------- -Web Animations is a new JavaScript API for driving animated content on the web. -By unifying the animation features of SVG and CSS, Web Animations unlocks -features previously only usable declaratively, and exposes powerful, -high-performance animation capabilities to developers. +A new JavaScript API for driving animated content on the web. By unifying +the animation features of SVG and CSS, Web Animations unlocks features +previously only usable declaratively, and exposes powerful, high-performance +animation capabilities to developers. -For more details see the -[W3C specification](http://w3c.github.io/web-animations/). +What is in this repository? +--------------------------- -What is the polyfill? ---------------------- +A JavaScript implementation of the Web Animations API that provides Web +Animation features in browsers that do not support it natively. The polyfill +falls back to the native implementation when one is available. -The polyfill is a JavaScript implementation of the Web Animations API. It is -supported on modern versions of all major browsers, including: - -* Chrome -* Firefox 27+ -* IE10+ (including Edge) -* Safari (iOS) 7.1+ -* Safari (Mac) 9+ - -Getting Started ---------------- +Quick start +----------- -Here's a simple example of an animation that scales and changes the opacity of -a `
` over 0.5 seconds. The animation alternates producing a pulsing -effect. +Here's a simple example of an animation that fades and scales a `
`. +[Try it as a live demo.](http://jsbin.com/yageyezabo/edit?html,js,output) ```html + -
Hello world!
+ + +
Hello world!
+ + ``` -Web Animations supports off-main-thread animations, and also allows procedural -generation of animations and fine-grained control of animation playback. See - for ideas and inspiration - or [web-animations-codelabs](https://github.com/web-animations/web-animations-codelabs). +Documentation +------------- -Native Fallback ---------------- - -When the polyfill runs on a browser that implements `Element.animate` and -`Animation` Playback Control it will detect and use the underlying native -features. +* [Codelab tutorial](https://github.com/web-animations/web-animations-codelabs) +* [Examples of usage](/docs/examples.md) +* [Live demos](https://web-animations.github.io/web-animations-demos) +* [MDN reference](https://developer.mozilla.org/en-US/docs/Web/API/Element/animate) +* [W3C specification](http://w3c.github.io/web-animations/) -Different Build Targets ------------------------ +We love feedback! +----------------- -### web-animations.min.js - -Tracks the Web Animations features that are supported natively in browsers. -Today that means Element.animate and Playback Control in Chrome. If you’re not -sure what features you will need, start with this. - -### web-animations-next.min.js - -Contains all of web-animations.min.js plus features that are still undergoing -discussion or have yet to be implemented natively. - -### web-animations-next-lite.min.js - -A cut down version of web-animations-next, it removes several lesser used -property handlers and some of the larger and less used features such as matrix -interpolation/decomposition. - -### Build Target Comparison - -| | web-animations | web-animations-next | web-animations-next-lite | -|------------------------|:--------------:|:-------------------:|:------------------------:| -|Size (gzipped) | 15KB | 18KB | 15KB | -|Element.animate | ✔ | ✔ | ✔ | -|Timing input (easings, duration, fillMode, etc.) for animation effects| ✔ | ✔ | ✔ | -|Playback control | ✔ | ✔ | ✔ | -|Support for animating lengths, transforms and opacity| ✔ | ✔ | ✔ | -|Support for animating other CSS properties| ✔ | ✔ | 🚫 | -|Matrix fallback for transform animations | ✔ | ✔ | 🚫 | -|KeyframeEffect constructor | 🚫 | ✔ | ✔ | -|Simple GroupEffects & SequenceEffects | 🚫 | ✔ | ✔ | -|Custom Effects | 🚫 | ✔ | ✔ | -|Timing input (easings, duration, fillMode, etc.) for groups
| 🚫 | 🚫\* | 🚫 | -|Additive animation | 🚫\* | 🚫\* | 🚫 | -|Motion path | 🚫\* | 🚫\* | 🚫 | -|Modifiable keyframe effect timing| 🚫 | 🚫\* | 🚫\* | -|Modifiable group timing | 🚫 | 🚫\* | 🚫\* | -|Usable inline style\*\* | ✔ | ✔ | 🚫 | - -\* support is planned for these features. -\*\* see inline style caveat below. - -Caveats -------- - -Some things won’t ever be faithful to the native implementation due to browser -and CSS API limitations. These include: - -### Inline Style - -Inline style modification is the mechanism used by the polyfill to animate -properties. Both web-animations and web-animations-next incorporate a module -that emulates a vanilla inline style object, so that style modification from -JavaScript can still work in the presence of animations. However, to keep the -size of web-animations-next-lite as small as possible, the style emulation -module is not included. When using this version of the polyfill, JavaScript -inline style modification will be overwritten by animations. -Due to browser constraints inline style modification is not supported on iOS 7 -or Safari 6 (or earlier versions). - -### Prefix handling - -The polyfill will automatically detect the correctly prefixed name to use when -writing animated properties back to the platform. Where possible, the polyfill -will only accept unprefixed versions of experimental features. For example: - -```js -var effect = new KeyframeEffect(elem, {"transform": "translate(100px, 100px)"}, 2000); -``` - -will work in all browsers that implement a conforming version of transform, but - -```js -var effect = new KeyframeEffect(elem, {"-webkit-transform": "translate(100px, 100px)"}, 2000); -``` - -will not work anywhere. - -API and Specification Feedback ------------------------------- - -File an issue on GitHub: . -Alternatively, send an email to with subject line -“[web-animations] … message topic …” +* For feedback on the API and the specification: + * File an issue on GitHub: + * Alternatively, send an email to with subject line +"[web-animations] ... message topic ..." ([archives](http://lists.w3.org/Archives/Public/public-fx/)). -Polyfill Issues ---------------- +* For issues with the polyfill, report them on GitHub: +. -Report any issues with this implementation on GitHub: -. +Keep up-to-date +--------------- -Breaking changes ----------------- +Breaking polyfill changes will be announced on this low-volume mailing list: +[web-animations-changes@googlegroups.com](https://groups.google.com/forum/#!forum/web-animations-changes). -When we make a potentially breaking change to the polyfill's API -surface (like a rename) we will, where possible, continue supporting the -old version, deprecated, for three months, and ensure that there are -console warnings to indicate that a change is pending. After three -months, the old version of the API surface (e.g. the old version of a -function name) will be removed. *If you see deprecation warnings you -can't avoid it by not updating*. +More info +--------- -We also announce anything that isn't a bug fix on -[web-animations-changes@googlegroups.com](https://groups.google.com/forum/#!forum/web-animations-changes). +* [Technical details about the polyfill](/docs/support.md) + * [Browser support](/docs/support.md#browser-support) + * [Fallback to native](/docs/support.md#native-fallback) + * [Feature list](/docs/support.md#features) + * [Feature deprecation and removal processes](/docs/support.md#process-for-breaking-changes) +* To test experimental API features, try one of the + [experimental targets](/docs/experimental.md) diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..7957a29 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,241 @@ +#Examples of using Web Animations + +Property indexed keyframes syntax +--------------------------------- +- Each CSS property specifies its keyframe values as a list, different properties may have differently sized lists. +- The `easing` property applies its timing function to all keyframes. + +[**Live demo**](http://jsbin.com/qiyeriruru/edit?js,output) +```javascript +element.animate({ + transform: [ + 'scaleY(0.5)', + 'scaleX(0.5)', + 'scaleY(0.5)', + ], + background: [ + 'red', + 'blue', + 'orange', + 'red', + ], + easing: 'ease-in-out', +}, { + duration: 2000, + iterations: Infinity, +}); +``` + +Keyframe list syntax +-------------------- +- Keyframes can be specified as a list of multiple CSS property values. +- Individual keyframes can be given specific offsets and easings. +- Not all properties need to be specified in every keyframe. +- Offsets are implicitly distributed if not specified. + +[**Live demo**](http://jsbin.com/yajatoyere/edit?js,output) +```javascript +element.animate([ + { + background: 'red', + transform: 'none', + easing: 'ease-out', + }, + { + offset: 0.1, + transform: 'translateY(100px)', + easing: 'ease-in-out', + }, + { + offset: 0.2, + transform: 'translate(100px, 100px)', + easing: 'ease-in-out', + }, + { + offset: 0.4, + transform: 'translateX(100px)', + easing: 'ease-out', + }, + { + background: 'blue', + transform: 'none', + }, +], { + duration: 4000, + iterations: Infinity, +}); +``` + +Timing parameters +----------------- +- Web Animations inherits many of its timing parameters from CSS Animations. +- See the [specification](http://w3c.github.io/web-animations/#animationeffecttimingreadonly) for details on each parameter. + +[**Live demo**](http://jsbin.com/dabehipiyo/edit?js,output) +```javascript +element.animate({ + transform: ['none', 'translateX(100px)'], + background: ['green', 'lime'], +}, { + // Apply effect during delay. + fill: 'backwards', + + // Delay starting by 500ms. + delay: 500, + + // Iterations last for 2000ms. + duration: 2000, + + // Start at 25% through an iteration. + iterationStart: 0.25, + + // Run for 2 iterations. + iterations: 2, + + // Play every second iteration backwards. + direction: 'alternate', + + // Stop animating 500ms earlier. + endDelay: -500, + + // The timing function to use with each iteration. + easing: 'ease-in-out', +}); +``` + +Playback controls +----------------- +- element.animate() returns an Animation object with basic playback controls. +- See the [specification](http://w3c.github.io/web-animations/#the-animation-interface) for details on each method. + +[**Live demo**](http://jsbin.com/kutaqoxejo/edit?js,output) +```javascript +var animation = element.animate({ + transform: ['none', 'translateX(200px)'], + background: ['red', 'orange'], +}, { + duration: 4000, + fill: 'both', +}); +animation.play(); +animation.reverse(); +animation.pause(); +animation.currentTime = 2000; +animation.playbackRate += 0.25; +animation.playbackRate -= 0.25; +animation.finish(); +animation.cancel(); +``` + +Transitioning states with element.animate() +------------------------------------------- +- This is an example of how to animate from one state to another using Web Animations. + +[**Live demo**](http://jsbin.com/musufiwule/edit?js,output) +```javascript +var isOpen = false; +var openHeight = '100px'; +var closedHeight = '0px'; +var duration = 300; + +button.addEventListener('click', function() { + // Prevent clicks while we transition states. + button.disabled = true; + button.textContent = '...'; + + // Determine where we're animation from/to. + var fromHeight = isOpen ? openHeight : closedHeight; + var toHeight = isOpen ? closedHeight : openHeight; + + // Start an animation transitioning from our current state to the final state. + var animation = element.animate({ height: [fromHeight, toHeight] }, duration); + + // Update the button once the animation finishes. + animation.onfinish = function() { + isOpen = !isOpen; + button.textContent = isOpen ? 'Close' : 'Open'; + button.disabled = false; + }; + + // Put our element in the final state. + // Inline styles are overridden by active animations. + // When the above animation finishes it will stop applying and + // the element's style will fall back onto this inline style value. + element.style.setProperty('height', toHeight); +}); +``` + +Generating animations +--------------------- +- The Javascript API allows for procedurally generating a diverse range of interesting animations. + +[**Live demo**](http://jsbin.com/xolacasiyu/edit?js,output) +```html + + + + + +
+
+
+ + +``` diff --git a/docs/experimental.md b/docs/experimental.md new file mode 100644 index 0000000..a9ae811 --- /dev/null +++ b/docs/experimental.md @@ -0,0 +1,58 @@ + +Experimental build targets +-------------------------- + +Most people should use the basic polyfill in `web-animations.min.js`. This +tracks the Web Animations features that are supported natively in browsers. +However, we also provide two additional build targets that contain experimental +features. + +### web-animations-next.min.js + +Contains all of web-animations.min.js plus features that are still undergoing +discussion or have yet to be implemented natively. + +### web-animations-next-lite.min.js + +A cut down version of web-animations-next, it removes several lesser used +property handlers and some of the larger and less used features such as matrix +interpolation/decomposition. + +Build target comparison +----------------------- + +| | web-animations | web-animations-next | web-animations-next-lite | +|------------------------|:--------------:|:-------------------:|:------------------------:| +|Size (gzipped) | 15KB | 18KB | 15KB | +|Element.animate | ✔ | ✔ | ✔ | +|Timing input (easings, duration, fillMode, etc.) for animation effects| ✔ | ✔ | ✔ | +|Playback control | ✔ | ✔ | ✔ | +|Support for animating lengths, transforms and opacity| ✔ | ✔ | ✔ | +|Support for animating other CSS properties| ✔ | ✔ | 🚫 | +|Matrix fallback for transform animations | ✔ | ✔ | 🚫 | +|KeyframeEffect constructor | 🚫 | ✔ | ✔ | +|Simple GroupEffects & SequenceEffects | 🚫 | ✔ | ✔ | +|Custom Effects | 🚫 | ✔ | ✔ | +|Timing input (easings, duration, fillMode, etc.) for groups
| 🚫 | 🚫\* | 🚫 | +|Additive animation | 🚫\* | 🚫\* | 🚫 | +|Motion path | 🚫\* | 🚫\* | 🚫 | +|Modifiable keyframe effect timing| 🚫 | 🚫\* | 🚫\* | +|Modifiable group timing | 🚫 | 🚫\* | 🚫\* | +|Usable inline style\*\* | ✔ | ✔ | 🚫 | + +\* support is planned for these features. +\*\* see inline style caveat below. + +Caveat: Inline style +-------------------- + +Inline style modification is the mechanism used by the polyfill to animate +properties. Both web-animations and web-animations-next incorporate a module +that emulates a vanilla inline style object, so that style modification from +JavaScript can still work in the presence of animations. However, to keep the +size of web-animations-next-lite as small as possible, the style emulation +module is not included. When using this version of the polyfill, JavaScript +inline style modification will be overwritten by animations. +Due to browser constraints inline style modification is not supported on iOS 7 +or Safari 6 (or earlier versions). + diff --git a/docs/support.md b/docs/support.md new file mode 100644 index 0000000..e6ad592 --- /dev/null +++ b/docs/support.md @@ -0,0 +1,69 @@ + +Getting the polyfill +-------------------- + +There are three ways to get a copy of the polyfill: + +1. Download and use the `web-animations.min.js` file directly from this repository +1. Using npm: Add [`web-animations-js`](https://www.npmjs.com/package/web-animations-js) to your `package.json` +1. Using Bower: Add `web-animations/web-animations-js` to your `bower.json` + +Browser support +--------------- + +The polyfill is supported on modern versions of all major browsers, including: + +* Chrome +* Firefox 27+ +* IE10+ (including Edge) +* Safari (iOS) 7.1+ +* Safari (Mac) 9+ + +Native fallback +--------------- + +When the polyfill runs on a browser that implements `Element.animate()` and +`Animation` playback control, it will detect and use the underlying native +features for better performance. + +Features +-------- + +The `web-animations.min.js` polyfill target tracks the Web Animations features +that are supported natively in browsers. These include: + +* Element.animate() +* Timing input (easings, duration, fillMode, etc.) for animation effects +* Playback control (play, pause, reverse, currentTime, cancel, onfinish) +* Support for animating CSS properties + +Caveat: Prefix handling +----------------------- + +The polyfill will automatically detect the correctly prefixed name to use when +writing animated properties back to the platform. Where possible, the polyfill +will only accept unprefixed versions of experimental features. For example: + +```js +element.animate({transform: ['none', 'translateX(100px)']}, 1000); +``` + +will work in all browsers that implement a conforming version of transform, but + +```js +element.animate({webkitTransform: ['none', 'translateX(100px)']}, 1000); +``` + +will not work anywhere. + +Process for breaking changes +---------------------------- + +When we make a potentially breaking change to the polyfill's API +surface (like a rename) we will, where possible, continue supporting the +old version, deprecated, for three months, and ensure that there are +console warnings to indicate that a change is pending. After three +months, the old version of the API surface (e.g. the old version of a +function name) will be removed. *If you see deprecation warnings, you +can't avoid them by not updating*. +