[web-animations-2] Custom effects

[graouts]

I would like to revive work on custom effects, an idea currently unofficially drafted in Web Animations Level 2. I have filed a patch for WebKit to support the CustomEffect interface as well as a new document.timeline.animate() method. The motivation is to bridge the gap between the poorly-named and rudimentary requestAnimationFrame() and Web Animations allowing authors to harness the full power of the Web Animations model such that scripted animations may be paused, resumed, seeked, etc.

Some example usage:

const animation = new Animation;
animation.effect = new CustomEffect(progress => { … }, 1000);
animation.play();

This code is equivalent to the more idiomatic:

document.timeline.animate(progress => { … }, 1000);

The idea here is that document.timeline.animate() should be to CustomEffect what element.animate() is to KeyframeEffect.

The section on custom effects in the current level 2 spec starts with this issue:

This whole feature needs to be revisited. The current thinking is that rather than having custom effects, we should simply have an onupdate callback on each animation effect. That would allow, for example, augmenting an existing effect with a function that performs logging or triggers additional actions at certain times. With the current arrangement, doing this would require adding a parent group just to achieve this.

I personally think that a dedicated CustomEffect interface is a simple and purposeful way to specify an animation where its application is performed by script. I expect that it is simpler to specify how this specific class of effects would work rather than trying to add an onupdate callback that would apply to keyframe effects as well.

You'll also notice the lack of a target for CustomEffect. I believe that it should not be necessary to specify a target for a custom effect since it may not target a single node, or even a node at all, but rather a JS object controlling the rendering of a scene using <canvas> APIs.

That being said, I am very open to all feedback to work towards exposing callback-based animations in Web Animations. All work conducted in WebKit is behind an off-by-default experimental feature flag and we have no intention to expose this to the Web until we have consensus on the way forward.

Cc @birtles @flackr @stephenmcgruer @kevers-google @majido @smfr @grorg @hober @ogerchikov @BorisChiou @hiikezoe

[birtles]

That all makes sense to me. Thanks for picking this up.

[okikio]

Is there a related CSS value interpolation API?

[graouts]

Is there a related CSS value interpolation API?

I hadn't considered that, but it's something that's worth exploring alongside this proposal. Would you have something to propose?

[okikio]

@graouts

Is there a related CSS value interpolation API?

I hadn't considered that, but it's something that's worth exploring alongside this proposal. Would you have something to propose?

I'm not super experienced in interpolation and/or making proposals for the csswg, I wouldn't mind though, however, I'm mostlikely going to need some help.

cc @mattgperry

[mattgperry]

Hey @graouts

This came out of a discussion between @okikio and myself about the limitations custom effects leaves us with. I'm super excited about custom effects but I think there's a remaining black hole when talking about interpolating complex values like KeyframeEffect that would limit the ability for many JS libraries to leverage existing interpolators already present in the browser.

My first thought was having CustomEffect also optionally support keyframes but I think this limits what is clearly a low-level API. For example, it wouldn't allow for custom easing functions like circIn etc. Whereas a stand-alone interpolator API would:

const mixColors = new Interpolation("#f00", "rgba(255,255,255,0.5)")

document.timeline.animate(p => {
  arbitraryElement.innerHTML = mixColors(circIn(p)) 
})

Ideally the interpolator would support unclamped progress values so we could support overshoot easing.

Supported interpolators that would be helpful:

• Number
• Unit numbers (20px ↔️ 5px, 100% ↔️ 0)
• Colors (blue ↔️ rgba(0,0,0, .5))
• Transforms (none ↔️ scale(3) translateX(100px))
• Shadows (5px 5px rgba(0,0,0,0.1) ↔️ 10px 10px rgba(0,0,0,0.05), 2px 2px 2px rgba(0,0,0,0.2) )
• Complex strings with matching number formatting, like complex path types

All of these (and more) are already leveraged within browsers, I think direct access would pair very well with CustomEffect.

[okikio]

In addition to what @mattgperry posted something like this would also be awesome,

CSS.mix("50٪ by ease", "red", "blue") // purple (in rgb format)
CSS.mix("50٪ by ease", "currentColor", "blue",  document.querySelector(".red-text")) // purple (in rgb format)

// Easing is linear by default
// Percentages function like they would on normal CSS
CSS.mix(0.5, "100%", "200",  document.querySelector(".red-text"), "width") // 150px

The API would very similar to the currently discussed CSS counter part mix() #581 (comment)

[birtles]

See also #6697 and #6700.

[flackr]

The section on custom effects in the current level 2 spec starts with this issue:

This whole feature needs to be revisited. The current thinking is that rather than having custom effects, we should simply have an onupdate callback on each animation effect. That would allow, for example, augmenting an existing effect with a function that performs logging or triggers additional actions at certain times. With the current arrangement, doing this would require adding a parent group just to achieve this.

I personally think that a dedicated CustomEffect interface is a simple and purposeful way to specify an animation where its application is performed by script. I expect that it is simpler to specify how this specific class of effects would work rather than trying to add an onupdate callback that would apply to keyframe effects as well.

I think that the timing with respect to other effects needs to be clear either way. I think having a set of post-animation update callbacks is probably simpler to be honest.

The other thing that may be cleaner about an update callback is that we may be able to skip it if the effect easing resulted in no change. E.g.

canvas.animate({}, {duration: 1000, easing: steps(10)}).addEventListener('update', (localTime) => {
  // Only needs to be called 10 times?
});

You'll also notice the lack of a target for CustomEffect. I believe that it should not be necessary to specify a target for a custom effect since it may not target a single node, or even a node at all, but rather a JS object controlling the rendering of a scene using <canvas> APIs.

I agree that conceptually it makes sense to not have a target, though it could be a nice feature if we could skip custom effects if the target (e.g. the canvas being drawn to) was not in view or at least if the target is detached.

[flackr]

I think @bramus also had a good use case where an update callback would be much simpler ergonomically than needing to create a separate animation.

[bramus]

Thanks for pointing me to this thread, @flackr.

I’m currently building a demo that uses a scroll-driven animation on an input[type=range]. The progress of that SDA is then used to rotate a 3D element on the page in response. You can try it out in Chrome Canary with the Experimental Web Platform Features flag enabled: as you drag the slider, the 3D model rotates: https://codepen.io/bramus/pen/VwoYoLR

One thing I found missing while building this is having progress event on the Animation itself to hook this all onto. Yes, I can read the animation’s progress, but I need a trigger for when to read it.

Right now, I rely on the input’s input+change events to read the animation progress. While using these two events in this case here works, my reflex as an author is to listen to the animation’s progress instead as my brain is in animation mode, not in input mode. Would such a progress event be available, I can easily take the animation + listener and attach it to some other input mechanisms in CSS (such as a regular ScrollTimeline) without needing to set up other JS listeners for other types of events (such as scroll).

Using a CustomEffect would be possible here, but that would require me to create a CustomEffect in JS on top of the already CSS existing animation. This feels like a lot of extra work just to get notified of an already existing animation’s tick.

I believe a progress or update event on the animation would be a more convenient way for authors to achieve what I want to do here.