1. Delta specification
This is a delta specification, meaning that it currently contains only the differences from CSS Transitions Level 1 [CSS3-TRANSITIONS]. Once the Level 1 specification is closer to complete, it will be merged with the additions here into a complete level 2 specification.
2. Starting of transitions
Associated with each top-level browsing context is a current transition generation that is incremented on each style change event.
Each time a new transition is generated, the current value of the (already incremented) current transition generation is stored as the transition’s transition generation.
2.1. The transition property name
Although the transition-property may specify shorthand properties and the all keyword, individual transitions are generated for each longhand sub-property that is animatable. The expanded transition property name of a transition is the name of the longhand sub-property for which the transition was generated (e.g. border-left-width).
2.2. The transition timing function
When creating a KeyframeEffect
for a transition, the effect’s easing
option is set to the value of the matching transition-timing-function property,
which must be used by getComputedTiming()
.
Note: Unlike CSS animations, the timing function for CSS transitions applies to the animation effect as opposed to the individual keyframes since this allows it to be reflected in the transformed progress as used when calculating the reversing shortening factor.
2.3. Owning element
The owning element of a transition refers to the element or pseudo-element to which the transition-property property was applied that generated the animation.
If a transition was generated directly by script (e.g. using the CSSTransition
constructor) then it has no owning element.
If a transition generated using the markup defined in this specification is later disassociated from that markup because it is cancelled or replaced by a newer transition, the animation is disassociated from its owning element (that is, it has no owning element from that point forwards).
Define the above more precisely once we rewrite firing of transitions in terms of Web Animations concepts (specifically when we spell out when we cancel an animation).
2.4. Animation composite order
Animations generated from the markup and
interfaces (e.g. the CSSTransition
constructor) defined in this
specification have an animation class of ‘CSS Transition’.
CSS Transitions have an earlier composite order that CSS Animations and animations without a specific animation class.
Within the set of CSS Transitions, two animations A and B are sorted in composite order (first to last) as follows:
-
If neither A nor B has an owning element, sort based on their relative position in the global animation list.
-
Otherwise, if only one of A or B has an owning element, let the animation with an owning element sort first.
-
Otherwise, if the owning element of A and B differs, sort A and B by tree order of their corresponding owning elements. With regard to pseudo-elements, the sort order is as follows:
-
element
-
::marker
-
::before
-
::after
-
element children
-
-
Otherwise, if A and B have different transition generation values, sort by their corresponding transition generation in ascending order.
-
Otherwise, sort A and B in ascending order by the Unicode codepoints that make up the expanded transition property name of each transition (i.e. without attempting case conversion and such that ‘-moz-column-width’ sorts before ‘column-width’).
Transitions generated using the markup defined in this specification are not added to the global animation list when they are created. Instead, these animations are appended to the global animation list at the first moment when they transition out of the idle play state after being disassociated from their owning element. Transitions that have been disassociated from their owning element but are still idle do not have a defined composite order.
Note, this behavior relies on the fact that disassociating a transition from its owning element always causes it to enter (or remain) in the idle play state.
Transitions created using the CSSTransition
constructor are appended
to the global animation list at the moment they are constructed.
3. Transition Events
3.1. Event dispatch
Note, this is a more general description of event dispatch than that of CSS Transitions Level 1 [CSS3-TRANSITIONS] since it must account for the possibility of animations being seeked or reversed using the Web Animations API [WEB-ANIMATIONS]. Furthermore, it is possible using the Web Animations API to substitute the transition effect with an entirely different effect with properties not normally used with transitions (e.g. an effect that repeats multiple times) and hence this section provides a generic definition that accounts for the full complexity of the Web Animations model.
To avoid firing redundant events, the set of events to dispatch is based on comparing the phase of the transition in the previous sample (animation frame) to its current state.
The transition phase of a transition is initially ‘idle’ and is updated on each sample according to the first matching condition from below:
- If the transition has no target effect,
-
The transition phase is set according to the first matching condition
from below:
- If the transition has an unresolved current time,
- The transition phase is ‘idle’.
- If the transition has a current time < 0,
- The transition phase is ‘before’.
- Otherwise,
- The transition phase is ‘after’.
- If the transition is pending and its phase was previously ‘idle’ or ‘pending’,
- The transition phase is ‘pending’.
- Otherwise,
- The transition phase is the phase of its target effect.
For calculating the elapsedTime
of each event, the following
definitions are used:
-
interval start =
max(min(-start delay, active duration), 0)
-
interval end =
max(min(target effect end - start delay, active duration), 0)
In the above formulae, references to the start delay, active duration, current iteration, iteration start, and iteration duration of a transition should be understood to refer to the corresponding properties of the transition’s target effect.
Each time an animation is sampled, the events to dispatch are determined by comparing the transition phase before and after the sample as follows:
Change | Events dispatched | Elapsed time (ms) |
---|---|---|
idle → pending or before | transitionrun
| interval start |
idle → active ٭ | transitionrun
| interval start |
transitionstart
| ||
idle → after ٭ | transitionrun
| interval start |
transitionstart
| ||
transitionend
| interval end | |
pending or before → active | transitionstart
| interval start |
pending or before → after ٭ | transitionstart
| interval start |
transitionend
| interval end | |
active → after | transitionend
| interval end |
active → before | transitionend
| interval start |
after → active | transitionstart
| interval end |
after → before ٭ | transitionstart
| interval end |
transitionend
| interval start | |
not idle and not after → idle | transitioncancel
| The active time of the animation at the moment it was cancelled calculated using a fill mode of both. |
٭ Where multiple events are listed for a state change, all events are dispatched in the order listed and in immediate succession.
Since the elapsed time defined in the table and procedure above is
expressed in milliseconds, it must be divided by 1,000 to produce a value in
seconds before being assigned to the elapsedTime
member of
the TransitionEvent
.
The above state transition chart ensures that, with the exception of transitions that are paused or have an infinite running time, the following invariants hold:
-
For every
transitionrun
event there will be a exactly onetransitionend
ortransitioncancel
and never both. -
For every
transitionstart
event there will be a exactly onetransitionend
ortransitioncancel
and never both. -
Every
transitionend
event is preceded by a correspondingtransitionstart
event.
The typical sequences of events, then, are as follows:
-
Regular playback:
transitionrun
,transitionstart
,transitionend
. -
Interrupted playback:
transitionrun
,transitionstart
,transitioncancel
. -
Interrupted playback during delay or pending phase:
transitionrun
,transitioncancel
. -
Reversed playback after completion:
transitionrun
,transitionstart
,transitionend
,transitionstart
,transitionend
.
4. DOM Interfaces
4.1. The CSSTransition interface
[Exposed =Window ]interface :
CSSTransition Animation {readonly attribute CSSOMString transitionProperty ; };
transitionProperty
, of type CSSOMString, readonly-
The expanded transition property name of this transition.
This interface needs a constructor. Perhaps something like the following,
[Constructor (Animatable ?target ,CSSOMString transitionProperty ,any transitionValue ,optional (unrestricted double or KeyframeEffectOptions )options ),Constructor (Animatable ?target ,CSSOMString transitionProperty ,any transitionValue , (unrestricted double or KeyframeEffectOptions )options ,AnimationTimeline ?timeline )]partial interface CSSTransition { };
Using any
as the type for transitionValue
would allow
the following usage:
var transition= new CSSTransition( elem, 'opacity' , 1 , 2000 ); transition. play();
The above example, however, is not equivalent to triggering a transition. It has the following differences:
-
It does not update the specified style.
-
It would not cancel any existing transition on the given property unless we add special wording to that effect.
-
It would exhibit different composite order to a regular transition (this should be easily fixed, however).
-
It has been suggested that script-generated animations should not apply to the transition level of the cascade.
It is unclear how much we should extend the CSSTransition
constructor to
overcome the above limitations so that it can be used to generate transitions
programmatically, or whether we should introduce a separate helper method such
as has been suggested
elsewhere.
4.2. Requirements on pending style changes
Various operations may affect the computed values of properties on elements. User agents may, as an optimization, defer recomputing these values until it becomes necessary. However, all operations included in programming interface defined in this specification, as well as those operations defined in Web Animations [WEB-ANIMATIONS] that may return objects defined by this specification, must produce a result consistent with having fully processed any such pending changes to computed values.
elem
’s opacity property is updated, a user agent may defer
recalculating the computed value of the animation property.
The first time this occurs, calling getComputedStyle(elt)
and
subsequently accessing the opacity
property of the result will
cause the user agent to recompute the value of opacity.
After the opacity property is updated a second time, the getAnimations()
method is called on elem
.
This method is specified by Web Animations and can return CSSTransition
objects as defined in this specification.
Hence, as result of the requirements in this section, the user agent must apply
any pending style changes thus generating a new CSSTransition
for the opacity property before returning its result.
5. Issues commonly raised as issues with previous levels
These issues were commonly reported issues with the previous level of the specification.
More powerful timing function syntax is a common request from developers. See, for example: 2013 message or 2015 thread.
Developers frequently have to trigger style flushes in order to force transitions to start. It would be good to have an API that would avoid this requirement. See, for example, 2011 proposal.
6. Issues deferred from previous levels of the spec
These issues were in previous levels of the specification, but may not turn out to be important in this level either.