Skip to content

Commit 0749ead

Browse files
suzyhalancutter
suzyh
authored and
alancutter
committed
Update README.md and add extra docs
1 parent 9779cac commit 0749ead

File tree

5 files changed

+421
-145
lines changed

5 files changed

+421
-145
lines changed

‎CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Example: `http://localhost:9876/base/test/web-platform-tests/web-animations/anim
5454
"version": "3.13.37",
5555
```
5656

57-
1. Build the polyfill with `npm install && grunt` then update `README.md`'s Build Target Comparison with the current gzipped sizes.
57+
1. Build the polyfill with `npm install && grunt` then update `docs/experimental.md`'s Build Target Comparison with the current gzipped sizes.
5858
5959
1. Submit both changes to web-animations-next then follow the procedure to push from web-animations-next to web-animations-js.
6060

‎README.md

Lines changed: 52 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -1,172 +1,80 @@
11

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-
92
What is Web Animations?
103
-----------------------
114

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.
5+
A new JavaScript API for driving animated content on the web. By unifying
6+
the animation features of SVG and CSS, Web Animations unlocks features
7+
previously only usable declaratively, and exposes powerful, high-performance
8+
animation capabilities to developers.
169

17-
For more details see the
18-
[W3C specification](http://w3c.github.io/web-animations/).
10+
What is in this repository?
11+
---------------------------
1912

20-
What is the polyfill?
21-
---------------------
13+
A JavaScript implementation of the Web Animations API that provides Web
14+
Animation features in browsers that do not support it natively. The polyfill
15+
falls back to the native implementation when one is available.
2216

23-
The polyfill is a JavaScript implementation of the Web Animations API. It is
24-
supported on modern versions of all major browsers, including:
25-
26-
* Chrome
27-
* Firefox 27+
28-
* IE10+ (including Edge)
29-
* Safari (iOS) 7.1+
30-
* Safari (Mac) 9+
31-
32-
Getting Started
33-
---------------
17+
Quick start
18+
-----------
3419

35-
Here's a simple example of an animation that scales and changes the opacity of
36-
a `<div>` over 0.5 seconds. The animation alternates producing a pulsing
37-
effect.
20+
Here's a simple example of an animation that fades and scales a `<div>`.
21+
[Try it as a live demo.](http://jsbin.com/yageyezabo/edit?html,js,output)
3822

3923
```html
24+
<!-- Include the polyfill -->
4025
<script src="web-animations.min.js"></script>
41-
<div class="pulse" style="width:150px;">Hello world!</div>
26+
27+
<!-- Set up a target to animate -->
28+
<div class="pulse" style="width: 150px;">Hello world!</div>
29+
30+
<!-- Animate! -->
4231
<script>
4332
var elem = document.querySelector('.pulse');
44-
var animation = elem.animate([
45-
{opacity: 0.5, transform: "scale(0.5)"},
46-
{opacity: 1.0, transform: "scale(1)"}
47-
], {
33+
var animation = elem.animate({
34+
opacity: [0.5, 1],
35+
transform: ['scale(0.5)', 'scale(1)'],
36+
}, {
4837
direction: 'alternate',
4938
duration: 500,
50-
iterations: Infinity
39+
iterations: Infinity,
5140
});
5241
</script>
5342
```
5443

55-
Web Animations supports off-main-thread animations, and also allows procedural
56-
generation of animations and fine-grained control of animation playback. See
57-
<http://web-animations.github.io> for ideas and inspiration - or [web-animations-codelabs](https://github.com/web-animations/web-animations-codelabs).
44+
Documentation
45+
-------------
5846

59-
Native Fallback
60-
---------------
61-
62-
When the polyfill runs on a browser that implements `Element.animate` and
63-
`Animation` Playback Control it will detect and use the underlying native
64-
features.
47+
* [Codelab tutorial](https://github.com/web-animations/web-animations-codelabs)
48+
* [Examples of usage](/docs/examples.md)
49+
* [Live demos](https://web-animations.github.io/web-animations-demos)
50+
* [MDN reference](https://developer.mozilla.org/en-US/docs/Web/API/Element/animate)
51+
* [W3C specification](http://w3c.github.io/web-animations/)
6552

66-
Different Build Targets
67-
-----------------------
53+
We love feedback!
54+
-----------------
6855

69-
### web-animations.min.js
70-
71-
Tracks the Web Animations features that are supported natively in browsers.
72-
Today that means Element.animate and Playback Control in Chrome. If you’re not
73-
sure what features you will need, start with this.
74-
75-
### web-animations-next.min.js
76-
77-
Contains all of web-animations.min.js plus features that are still undergoing
78-
discussion or have yet to be implemented natively.
79-
80-
### web-animations-next-lite.min.js
81-
82-
A cut down version of web-animations-next, it removes several lesser used
83-
property handlers and some of the larger and less used features such as matrix
84-
interpolation/decomposition.
85-
86-
### Build Target Comparison
87-
88-
| | web-animations | web-animations-next | web-animations-next-lite |
89-
|------------------------|:--------------:|:-------------------:|:------------------------:|
90-
|Size (gzipped) | 15KB | 18KB | 15KB |
91-
|Element.animate | ✔ | ✔ | ✔ |
92-
|Timing input (easings, duration, fillMode, etc.) for animation effects| ✔ | ✔ | ✔ |
93-
|Playback control | ✔ | ✔ | ✔ |
94-
|Support for animating lengths, transforms and opacity| ✔ | ✔ | ✔ |
95-
|Support for animating other CSS properties| ✔ | ✔ | 🚫 |
96-
|Matrix fallback for transform animations | ✔ | ✔ | 🚫 |
97-
|KeyframeEffect constructor | 🚫 | ✔ | ✔ |
98-
|Simple GroupEffects & SequenceEffects | 🚫 | ✔ | ✔ |
99-
|Custom Effects | 🚫 | ✔ | ✔ |
100-
|Timing input (easings, duration, fillMode, etc.) for groups</div>| 🚫 | 🚫\* | 🚫 |
101-
|Additive animation | 🚫\* | 🚫\* | 🚫 |
102-
|Motion path | 🚫\* | 🚫\* | 🚫 |
103-
|Modifiable keyframe effect timing| 🚫 | 🚫\* | 🚫\* |
104-
|Modifiable group timing | 🚫 | 🚫\* | 🚫\* |
105-
|Usable inline style\*\* | ✔ | ✔ | 🚫 |
106-
107-
\* support is planned for these features.
108-
\*\* see inline style caveat below.
109-
110-
Caveats
111-
-------
112-
113-
Some things won’t ever be faithful to the native implementation due to browser
114-
and CSS API limitations. These include:
115-
116-
### Inline Style
117-
118-
Inline style modification is the mechanism used by the polyfill to animate
119-
properties. Both web-animations and web-animations-next incorporate a module
120-
that emulates a vanilla inline style object, so that style modification from
121-
JavaScript can still work in the presence of animations. However, to keep the
122-
size of web-animations-next-lite as small as possible, the style emulation
123-
module is not included. When using this version of the polyfill, JavaScript
124-
inline style modification will be overwritten by animations.
125-
Due to browser constraints inline style modification is not supported on iOS 7
126-
or Safari 6 (or earlier versions).
127-
128-
### Prefix handling
129-
130-
The polyfill will automatically detect the correctly prefixed name to use when
131-
writing animated properties back to the platform. Where possible, the polyfill
132-
will only accept unprefixed versions of experimental features. For example:
133-
134-
```js
135-
var effect = new KeyframeEffect(elem, {"transform": "translate(100px, 100px)"}, 2000);
136-
```
137-
138-
will work in all browsers that implement a conforming version of transform, but
139-
140-
```js
141-
var effect = new KeyframeEffect(elem, {"-webkit-transform": "translate(100px, 100px)"}, 2000);
142-
```
143-
144-
will not work anywhere.
145-
146-
API and Specification Feedback
147-
------------------------------
148-
149-
File an issue on GitHub: <https://github.com/w3c/web-animations/issues/new>.
150-
Alternatively, send an email to <[email protected]> with subject line
151-
“[web-animations] … message topic …”
56+
* For feedback on the API and the specification:
57+
* File an issue on GitHub: <https://github.com/w3c/web-animations/issues/new>
58+
* Alternatively, send an email to <[email protected]> with subject line
59+
"[web-animations] ... message topic ..."
15260
([archives](http://lists.w3.org/Archives/Public/public-fx/)).
15361

154-
Polyfill Issues
155-
---------------
62+
* For issues with the polyfill, report them on GitHub:
63+
<https://github.com/web-animations/web-animations-js/issues/new>.
15664

157-
Report any issues with this implementation on GitHub:
158-
<https://github.com/web-animations/web-animations-next/issues/new>.
65+
Keep up-to-date
66+
---------------
15967

160-
Breaking changes
161-
----------------
68+
Breaking polyfill changes will be announced on this low-volume mailing list:
69+
[[email protected]](https://groups.google.com/forum/#!forum/web-animations-changes).
16270

163-
When we make a potentially breaking change to the polyfill's API
164-
surface (like a rename) we will, where possible, continue supporting the
165-
old version, deprecated, for three months, and ensure that there are
166-
console warnings to indicate that a change is pending. After three
167-
months, the old version of the API surface (e.g. the old version of a
168-
function name) will be removed. *If you see deprecation warnings you
169-
can't avoid it by not updating*.
71+
More info
72+
---------
17073

171-
We also announce anything that isn't a bug fix on
172-
[[email protected]](https://groups.google.com/forum/#!forum/web-animations-changes).
74+
* [Technical details about the polyfill](/docs/support.md)
75+
* [Browser support](/docs/support.md#browser-support)
76+
* [Fallback to native](/docs/support.md#native-fallback)
77+
* [Feature list](/docs/support.md#features)
78+
* [Feature deprecation and removal processes](/docs/support.md#process-for-breaking-changes)
79+
* To test experimental API features, try one of the
80+
[experimental targets](/docs/experimental.md)

0 commit comments

Comments
 (0)