Web Animations CSS Integration
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
Introduction
[[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.
CSS Transitions
CSS Animations
The CSSKeyframesMap mapping
Issue: This feature is at risk.
//FIXME: figure out the appropriate thing to do here and remove this!
interface String { };
[MapClass(String, AnimationEffect)]
interface CSSKeyframesMap {
};
partial interface Document {
readonly attribute CSSKeyframesMap keyframes;
};
The CSSKeyframesMap interface
The
CSSKeyframesMap interface defines a map type that can
be used to store sequences of Keyframes indexed by Strings.
Document.keyframes
The
keyframes attribute on the
Document interface references a map of type
CSSKeyframesMap.
Note: The
CSSKeyframesMap 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
AnimationEffects 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
@keyframes rule name is encountered in a
style sheet, the action taken depends upon the current value stored against the
name in the
keyframes map.
- If the current value has never been set, or has only been set due to
style changes:
-
The keyframes defined by the @keyframes rule are
converted into a KeyframeEffect (see
), then stored against the
name in the keyframes map.
- Otherwise:
-
The rule is ignored.
Issue: Should the KeyframeEffects generated by @keyframes rules be read-only?
When the used
@keyframes 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
keyframes map.
- If the current value has only been set due to style changes:
-
The keyframes defined by the new rule are converted into a
KeyframeEffect
(see ), then stored
against the name in the keyframes map.
- Otherwise:
- The change is ignored.
When the last
@keyframes 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
keyframes
map.
- If the current value has only been set due to style changes:
-
The value referenced by the @keyframes name is
cleared from the keyframes map.
- Otherwise:
- The removal is ignored.
Converting a CSS Keyframes rule into a
KeyframeEffect
A CSS
@keyframes rule
keyframes is
converted into a
KeyframeEffect using the following process:
- Initialize an empty list keyframeList.
- For each keyframe in keyframes:
- Create a new dictionary newKeyframe.
- Set newKeyframe's offset to the offset defined by
keyframe.
- If keyframe defines an 'animation-timing-function', set
newKeyframe's easing to the defined 'animation-timing-function'.
- For each property defined in keyframe:
- Set newKeyframe[property] to the value associated with that
property in keyframe
- Add property to referencedProperties.
- Add newKeyframe to keyframeList.
- Remove keyframes with duplicated offsets from keyframeListsuch that
only the last keyframe to specify a given offset remains.
- Construct a new KeyframeEffect, providing
keyframeList as the frames parameter.
Web Animations Instantiation
For CSS Animations, mappings into the Web Animations model are established
pairwise between a specific
AnimationEffect, the
animating effect, and a specific element, the
animating element.
When a CSS Animation is to be started, the value of 'animation-name' is used
as an index into the
keyframes map, and the matching
AnimationEffect (if any) is used to instantiate the
animating effect by following the procedure defined below
(see
).
When a CSS Animation is started an
Animation is constructed and
associated with a
Player on the
Document Timeline. The animation
is configured as follows:
Issue: Deal with animation-play-state
Issue: Explain where we need to cancel the Player for a css animation.
CSS Animations Events
The
animationstart event is triggered to fire each time the
corresponding
Animation enters the
active phase or
after phase during a
sample.
The
animationiteration event is triggered to fire, on each
sample
where all of the following conditions are met:
- the corresponding Animation is in the active phase
- the corresponding Animation was in the active phase on the
last sample
- the corresponding Animation has a current iteration which is
different to the
current iteration of the last sample.
The
animationend event is triggered to fire each time the
corresponding
Animation enters the
after phase during a
sample.
Instantiating the animating effect
The
animating effect is instantiated from an
AnimationEffect (the
reference effect) stored in the
keyframes attribute using the following process:
Issue: turn this into boring old specificese
- If the reference effect is a KeyframeEffect which was converted
from a CSS @keyframes rule using the process
defined in :
-
- The result effect is created as a clone of the
reference effect.
- Convert "add" keyframes at an offset of 0 and 1 by snapshotting
their referenced properties from the computed style of the
animating element, then changing the keyframe to a "replace" keyframe.
- Set the easing of all keyframes which do not have an easing
to the value of 'animation-timing-function'.
- Otherwise
- The animating effect is the reference effect.
Exposure in the Web Animations API
Players generated by CSS Animations and CSS Transitions are accessible
via getAnimationPlayers with the restriction that source will
point to a read-only TimedItem which disallows changes to its
specified timing and effect.
Note: The Player remains fully functional. The source,
playbackRate, currentTime, startTime and play control methods will
be live and function as normal.
REMOVE ME: Definitions that should be resolved by Web Animations
animation
player
document timeline
target element
start delay
iteration duration
timing function
animation effect
keyframe animation effect
keyframes
after phase
custom player priority
cancel
getanimationplayers
TimedItem
source
specified timing
effect
playbackRate
currentTime
keyframeEffect
offset
animationEffect
sample
easing
iteration count
direction
fill mode
current iteration
active phase