[web-animations] Renaming iterationDuration etc. (was: [web-animations] Default fill mode)

(2013/08/06 9:35), Brian Birtles wrote:
 > (I've suggested renaming 'iterationDuration' to 'duration' before but
 > no-one seemed interested. Having now noticed that jQuery uses 'duration'
 > for this I think it's worth re-considering.)

Since it seems like we're mostly settled on (1), I'd like to raise the 
issue of renaming. I know it's still a long way to CR which is when we 
traditionally rename all the things, but I couldn't wait.

The specific proposals (in decreasing order of how much I care about 
them) are below:


(A) iterationDuration -> duration

Two new data points make this renaming worthwhile.

i. We made the effective default fill mode for animations 'none'. As a 
result, for common usage authors can no longer use the shortcut where 
the duration is a numeric argument, but must now type:

   elem.animate({ left: '100px' }, { iterationDuration: 3, fillMode: 
'forwards' });

ii. I recently noticed that jQuery, which I suspect is the most commonly 
used animation API on the Web today and which defines an Element.animate 
method that is is remarkably similar to that in Web Animations API, 
calls this parameter 'duration'. e.g.

   $(elem).animate({ left: '100px' }, { duration: 3 });

Other data points which are not particularly new but worth mentioning:

iii. CSS Animations and CSS Transitions call this simply 'duration' 
(i.e. 'animation-duration' not 'animation-iteration-duration').

iv. Every other API in the _whole_wide_world_ calls this duration :)

e.g.
   QML: duration
   CA: duration (the active duration is called repeatDuration)
   Android: duration
   SMIL: dur (ok, not 'duration', but it's even shorter still!)
   WPF: Duration
   MathBox: duration
   HTMLMediaElement: duration
   d3: duration
   YUI: duration
   S2.FX: duration

We would, of course, in the *model* still refer to this as the 
'iteration duration' for clarity but in the API (both Timing interface 
and TimingInput dictionary) it would just be 'duration'. The description 
of the 'duration' would say that it refers to the 'iteration duration'.

activeDuration would remain activeDuration. It's used much less often 
and CA offers a precedent for naming this differently.

That would make common to-animation with filling a little easier:

   elem.animate({ left: '100px' }, { duration: 3, fillMode: 'forwards' });


(B) startDelay -> delay

I'm not quite as concerned about this, but I notice many other APIs call 
this 'delay'. 'startDelay' seems unnecessarily long.

A quick survey of other APIs that have a similar property:

   GSAP: delay
   Raphaël: delay()
   CA: timeOffset
   Android: startDelay
   MathBox: delay
   d3: delay

So only Android thinks it's important to spell out 'start'.

More critically, CSS calls this delay (i.e. 'animation-delay' and 
'transition-delay') which I think is a pretty persuasive reason to adopt 
that naming in the API.

Once again, the model would continue to refer to 'start delay' for clarity.

As a further data point, when I come to do the SVG bindings I'll 
probably introduce the 'delay' attribute.


(C) fillMode -> fill

I'd *really* like to rename this so that our common usage becomes:

   elem.animate({ left: '100px' }, { duration: 3, fill: 'forwards' });

Looking at other APIs with a fill mode we have:

   SVG/SMIL: fill
   CA: fillMode
   WPF: FillBehavior

So nothing conclusive there.

However, CSS uses 'animation-fill-mode' so maybe we should stick with that.


While we're talking about renaming, a few other possibilities that I 
don't necessarily think are worthwhile but are worth considering anyway:

(D) iterationCount -> repeat

This one I'm really not concerned about. Just looking at other APIs though:

   GSAP: repeat
   Raphaël: repeat()
   CA: repeatCount
   Android: repeatCount
   QML: loops
   YUI: iterations (confusingly iterationCount corresponds to our 
currentIteration)

Again, although repeat is nice and short, I think keeping consistency 
with CSS' 'animation-iteration-count' is probably key here.


(E) timingFunction -> easing

Again, looking around we have:

  jQuery: easing
  GSAP: ease
  QML: easing
  MathBox: ease
  d3: ease
  YUI: easing

But we're probably stuck with CSS' 'animation-timing-function'.


What do you think?

Best regards,

Brian

Received on Thursday, 8 August 2013 01:54:54 UTC