csswg-drafts/web-animations-css-integration/Overview.src.html at 0ac534789c3657246bb5e85a711dff5866a15ef3 · w3c/csswg-drafts · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
<h1>Web Animations CSS Integration</h1>
<pre class='metadata'>
Status: ED
ED: none
Shortname: web-animations-css
Level: 1
Editor: Shane Stephens, Google, shans@google.com
Abstract: This specification defines mappings between [[CSS3-ANIMATIONS]], [[CSS3-TRANSITIONS]] and the [[WEB-ANIMATIONS]] model.
Group: fxtf
</pre>

<div boilerplate="status">
      <p>
	This is a public copy of the editors' draft.
	It is provided for discussion only and may change at any moment.
	Its publication here does not imply endorsement of its contents by W3C.
	Don’t cite this document other than as work in progress.

</p>

      <p>
        The contents of this draft are intended to be incorporated into Level 2
        of both the CSS Animations and CSS Transitions specifications as these
        specifications are drafted.
      </p>

      <p>
	The (<a href="http://lists.w3.org/Archives/Public/public-fx/">archived</a>) public mailing list
	<a href="mailto:public-fx@w3.org?Subject=%5Bweb-animations-css%5D%20PUT%20SUBJECT%20HERE">public-fx@w3.org</a>
	(see <a href="http://www.w3.org/Mail/Request">instructions</a>)
	is preferred for discussion of this specification.
	When sending e-mail,
	please put the text “web-animations-css” in the subject,
	preferably like this:
	“[web-animations-css] <em>…summary of comment…</em>”

</p>
      <p>
	This document was produced by the <a href="http://www.w3.org/Style/CSS/members">CSS Working Group</a>
	(part of the <a href="http://www.w3.org/Style/">Style Activity</a>) and the <a href="http://www.w3.org/Graphics/SVG/WG/">SVG Working Group</a> (part of the
	<a href="http://www.w3.org/Graphics/">Graphics Activity</a>).

</p>
      <p>
	This document was produced by groups operating under
	the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent Policy</a>.
	W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/32061/status" rel="disclosure">public list of any patent disclosures (CSS)</a>
	and a <a href="http://www.w3.org/2004/01/pp-impl/19480/status" rel="disclosure">public list of any patent disclosures (SVG)</a>
	made in connection with the deliverables of each group;
	these pages also includes instructions for disclosing a patent.
	An individual who has actual knowledge of a patent which the individual believes contains
	<a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a>
	must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>.</p>
</div>

<h2>Introduction</h2>

[[CSS3-ANIMATIONS]] and [[CSS3-TRANSITIONS]] provide models for defining
declarative animations via CSS. [[SVG12]] provides a model for defining
declarative animations via SVG. However, the three specifications do not
define or present a unified animation model.

To solve this problem, the [[WEB-ANIMATIONS]] specification defines a
comprehensive animation model that is capable of supporting [[CSS3-ANIMATIONS]],
[[CSS3-TRANSITIONS]] and [[SVG12]].

This document describes how [[CSS3-ANIMATIONS]] and [[CSS3-TRANSITIONS]] are
supported by the [[WEB-ANIMATIONS]] model.

<h2>CSS Transitions</h2>

<div spec='css-transitions'>

For CSS Transitions, mappings into the Web Animations model are established
pairwise for a specific CSS property, the <dfn>transitioning property</dfn>, on
a specific element, the <dfn>transitioning element</dfn>.

When a CSS Transition is started for the <a>transitioning property</a> of a
<a>transitioning element</a>, an <a>Animation</a> is constructed and
associated with a <a>Player</a> on the <a>document timeline</a>, configured
with a <a>custom player priority</a> which ensures that the <a>Player</a> sorts
before <a>Player</a>s created through the Web Animations API and those generated
for CSS Animations. The <a>Animation</a> is configured as follows:

<ul>
<li>The <a>target element</a> is set to the <a>transitioning element</a>.
<li>The <a>start delay</a> is set to the current used value of the 'transition-delay'
property.
<li>The <a>iteration duration</a> is set to the current used value of the
'transition-duration' property.
<li>The <a>timing function</a> is set to the current used value of the
'transition-timing-function' property.
<li>The <a>animation effect</a> is set to a <a>keyframe animation effect</a>
with two <a>keyframes</a> defined as follows:
    <ul>
    <li>The first keyframe references the <a>transitioning property</a> with a
    value set to the <a>start value</a> of the transition.
    <li>The second and final keyframe references the
    <a>transitioning property</a> with a value set to the <a>end value</a> of
    the transition.
    </ul>
</ul>

Note, changes to the values of the 'transition-delay', 'transition-duration',
and 'transition-timing-function' have no effect on a transition once it has
started.

When a transition affecting the <a>transitioning property</a> of a
<a>transitioning element</a> is removed or interrupted the <a>cancel</a>
method of the corresponding <a>Player</a> is called.

When a transition affecting the <a>transitioning property</a> of a
<a>transitioning element</a> is reversed the <a>cancel</a>
method of the corresponding <a>Player</a> is called and a new <a>Player</a> is
generated as if the transition had just begun.

<h3>CSS Transitions events</h3>
The <a>transitionend</a> event is triggered to fire each time the
corresponding <a>Animation</a> enters the <a>after phase</a> during a
<a>sample</a>.
</div>

<h2>CSS Animations</h2>

<h3>The CSSKeyframesMap mapping</h3>

Issue: This feature is at risk.

<div spec='html5'>

<pre class='idl' style='display:none'>
//FIXME: figure out the appropriate thing to do here and remove this!

interface String { };
</pre>

<pre class='idl'>

[MapClass(String, AnimationEffect)]
interface CSSKeyframesMap {
};

partial interface Document {
    readonly attribute CSSKeyframesMap keyframes;
};
</pre>

</div>

<div spec='css-animations'>

<h4>The CSSKeyframesMap interface</h4>

The <dfn interface>CSSKeyframesMap</dfn> interface defines a map type that can
be used to store sequences of Keyframes indexed by Strings.

<h4>Document.keyframes</h4>

The <dfn attribute for='Document'>keyframes</dfn> attribute on the
<a interface spec='html5'>Document</a> interface references a map of type
<a interface>CSSKeyframesMap</a>.

Note: The <a interface>CSSKeyframesMap</a> enables animations created using the
Web Animations API to re-use the keyframe rules declared by CSS, and for
animations declared by CSS to act on <a interface>AnimationEffect</a>s created
through the API.

Note: The processing defined in this section does not alter the way in which
keyframes rules are selected when CSS animations are started, unless a name is
explicitly overridden by setting its value in the map.

When a new <a>@keyframes</a> rule name is encountered in a
style sheet, the action taken depends upon the current value stored against the
name in the <a attribute>keyframes</a> map.

<dl>
<dt>If the current value has never been set, or has only been set due to
style changes:</dt>
<dd>
The keyframes defined by the <a>@keyframes</a> rule are
converted into a <a interface>KeyframeEffect</a> (see
<a href='#conversion-of-css-keyframes' section></a>), then stored against the
name in the <a attribute>keyframes</a> map.
<dt>Otherwise:
<dd>
The rule is ignored.
</dl>

Issue: Should the KeyframeEffects generated by @keyframes rules be read-only?

When the used <a>@keyframes</a> rule associated with a
given name changes due to a change in a style sheet, the action taken depends
upon the current value stored against the name in the
<a attribute>keyframes</a> map.

<dl>
<dt>If the current value has only been set due to style changes:
<dd>
The keyframes defined by the new rule are converted into a
<a interface>KeyframeEffect</a>
(see <a href='#conversion-of-css-keyframes' section></a>), then stored
against the name in the <a attribute>keyframes</a> map.
<dt>Otherwise:
<dd>The change is ignored.
</dl>

When the last <a>@keyframes</a> rule for a given name is
removed from a style sheet, the action taken depends upon the current value
stored against the name in the <a attribute>keyframes</a>
map.

<dl>
<dt>If the current value has only been set due to style changes:
<dd>
The value referenced by the <a>@keyframes</a> name is
cleared from the <a attribute>keyframes</a> map.
<dt>Otherwise:
<dd>The removal is ignored.
</dl>

<h4 id='conversion-of-css-keyframes'>Converting a CSS Keyframes rule into a
KeyframeEffect</h4>

A CSS <a>@keyframes</a> rule <em>keyframes</em> is
converted into a <a interface>KeyframeEffect</a> using the following process:

<ol>
<li>Initialize an empty list <em>keyframeList</em>.
<li>For each <em>keyframe</em> in keyframes:
<ol>
<li>Create a new dictionary <em>newKeyframe</em>.
<li>Set <em>newKeyframe</em>'s <a>offset</a> to the offset defined by
<em>keyframe</em>.
<li>If <em>keyframe</em> defines an 'animation-timing-function', set
<em>newKeyframe</em>'s <a>easing</a> to the defined 'animation-timing-function'.
<li>For each <em>property</em> defined in <em>keyframe</em>:
<ol>
<li>Set <em>newKeyframe[property]</em> to the value associated with that
property in <em>keyframe</em>
<li>Add <em>property</em> to referencedProperties.
</ol>
</ol>
<li>Add <em>newKeyframe</em> to <em>keyframeList</em>.
<li>Remove keyframes with duplicated offsets from <em>keyframeList</em>such that
only the last keyframe to specify a given offset remains.
<li>Construct a new <a interface>KeyframeEffect</a>, providing
<em>keyframeList</em> as the frames parameter.
</ol>

</div>

<h3>Web Animations Instantiation</h3>

<div spec='css-animations'>

For CSS Animations, mappings into the Web Animations model are established
pairwise between a specific <a interface>AnimationEffect</a>, the
<dfn>animating effect</dfn>, and a specific element, the
<dfn>animating element</dfn>.

When a CSS Animation is to be started, the value of 'animation-name' is used
as an index into the <a>keyframes</a> map, and the matching
<a i
8000
nterface>AnimationEffect</a> (if any) is used to instantiate the
<a>animating effect</a> by following the procedure defined below
(see <a section href='#instantiating-an-animating-effect'></a>).

When a CSS Animation is started an <a>Animation</a> is constructed and
associated with a <a>Player</a> on the <a>Document Timeline</a>. The animation
is configured as follows:

<ul>
<li>The <a>target element</a> is set to the <a>animating element</a>.
<li>The <a>start delay</a> is set to the current used value of the
'animation-delay' property for the <a>animating element</a>.
<li>The <a>iteration duration</a> is set to the current used value of the
'animation-duration' property for the <a>animating element</a>.
<li>The <a>iteration count</a> is set to the current used value of the
'animation-iteration-count' property for the <a>animating element</a>.
<li>The <a>direction</a> is set to the current used value of the
'animation-direction' property for the <a>animating element</a>.
<li>The <a>fill mode</a> is set to the current used value of the
'animation-fill-mode' property for the <a>animating element</a>.
<li>The <a>animation effect</a> is set to the <a>animating effect</a>
</ul>

Issue: Deal with animation-play-state

Issue: Explain where we need to cancel the Player for a css animation.

<h3>CSS Animations Events</h3>

The <a event>animationstart</a> event is triggered to fire each time the
corresponding <a>Animation</a> enters the <a>active phase</a> or
<a>after phase</a> during a <a>sample</a>.

The <a event>animationiteration</a> event is triggered to fire, on each <a>sample</a>
where all of the following conditions are met:
<ol>
<li>the corresponding <a>Animation</a> is in the <a>active phase</a>
<li>the corresponding <a>Animation</a> was in the <a>active phase</a> on the
last <a>sample</a>
<li>the corresponding <a>Animation</a> has a <a>current iteration</a> which is
different to the
<a>current iteration</a> of the last <a>sample</a>.
</ol>

The <a event>animationend</a> event is triggered to fire each time the
corresponding <a>Animation</a> enters the <a>after phase</a> during a
<a>sample</a>.

<h3 id='instantiating-an-animating-effect'>Instantiating the animating effect
</h3>

The <a>animating effect</a> is instantiated from an
<a interface>AnimationEffect</a> (the <em>reference effect</em>) stored in the
<a attribute>keyframes</a> attribute using the following process:

Issue: turn this into boring old specificese

<dl>
<dt>If the <em>reference effect</em> is a KeyframeEffect which was converted
from a CSS <a spec='css-animations'>@keyframes</a> rule using the process
defined in <a section href='#conversion-of-css-keyframes'></a>:
<dd>
<ol>
<li>The <em>result effect</em> is created as a clone of the
<em>reference effect</em>.
<li>Convert "add" keyframes at an offset of 0 and 1 by snapshotting
their referenced properties from the computed style of the
<a>animating element</a>, then changing the keyframe to a "replace" keyframe.
<li>Set the <a>easing</a> of all keyframes which do not have an <a>easing</a>
to the value of 'animation-timing-function'.
</ol>
<dt>Otherwise
<dd> The <a>animating effect</a> is the <em>reference effect</em>.

<h2>Exposure in the Web Animations API</h2>

<a>Player</a>s generated by CSS Animations and CSS Transitions are accessible
via <a>getAnimationPlayers</a> with the restriction that <a>source</a> will
point to a read-only <a>TimedItem</a> which disallows changes to its
<a>specified timing</a> and <a>effect</a>.

Note: The <a>Player</a> remains fully functional. The <a>source</a>,
<a>playbackRate</a>, <a>currentTime</a>, startTime and play control methods will
be live and function as normal.

</div>

<div style='display:none'>
REMOVE ME: Definitions that should be resolved by Web Animations

<dfn>animation</dfn>
<dfn>player</dfn>
<dfn>document timeline</dfn>
<dfn>target element</dfn>
<dfn>start delay</dfn>
<dfn>iteration duration</dfn>
<dfn>timing function</dfn>
<dfn>animation effect</dfn>
<dfn>keyframe animation effect</dfn>
<dfn>keyframes</dfn>
<dfn>after phase</dfn>
<dfn>custom player priority</dfn>
<dfn>cancel</dfn>
<dfn>getanimationplayers</dfn>
<dfn>TimedItem</dfn>
<dfn>source</dfn>
<dfn>specified timing</dfn>
<dfn>effect</dfn>
<dfn>playbackRate</dfn>
<dfn>currentTime</dfn>
<dfn interface>keyframeEffect</dfn>
<dfn>offset</dfn>
<dfn interface>animationEffect</dfn>
<dfn>sample</dfn>
<dfn>easing</dfn>
<dfn>iteration count</dfn>
<dfn>direction</dfn>
<dfn>fill mode</dfn>
<dfn>current iteration</dfn>
<dfn>active phase</dfn>
</div>