Overview.src.html

<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: csswg
</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 interface>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>