Animation Keyframes API Design [feedback welcome!]

[rtfeldman]

Prior discussions: https://github.com/rtfeldman/elm-css/issues/430 https://github.com/rtfeldman/elm-css/issues/431 https://github.com/rtfeldman/elm-css/pull/227 #275

I'd like to add animations to elm-css, which requires some API design work. CSS Tricks has the best intro I've read on the subject of CSS animations, and it also has links to MDN at the end.

Here's a draft of an API to address how keyframes would work. (Let's assume the other properties exist; those don't have any more API challenges than the typical elm-css API, whereas keyframes is trickier.)

keyframes : List Style -> List ( Float, List Style ) -> List Style -> Keyframes

animationName : Keyframes -> Style

The basic ideas are:

1. You use Css.keyframes to define a Keyframes value. The 0% and 100% (aka from and to) styles are mandatory, but you can optionally specify other percentages as ( Float, List Style ) tuples in between.
2. You can pass this Keyframes value to animation-related properties like animationName and the shorthand animation.
3. The animation name is automatically generated as a hash of the contents of the Keyframes value, just like how classnames are automatically generated by the css attribute today. So you'd never need to manually synchronize animation names.

This doesn't offer a way to manually specify an animation name string if you really want to. That said, it would be possible to add a Css.Global.keyframes : String -> Keyframes -> Snippet to support that. (Note that without this, it would be impossible to specify two different animations which have the same transitions and styles, but different names. Is that a problem? I can't think of why it would be, but maybe there's a scenario I'm unaware of.)

Concerns with this API:

1. Because keyframes receives a List Style, you can use things like hover and important with it, even though those aren't supported in the context of keyframes. It would be nice if using hover or important in these Style values didn't compile, but I can't think of a way to do that without introducing a phantom type variable to Style. That doesn't seem worth it to me. Can anyone think of alternate ways to enforce that?
2. There's no way to avoid specifying the 0% and 100% transition steps. That seems like a good thing by default, since if you're doing something unusual where you don't want transition steps, you can always set them to be the same thing. However, this is CSS; there might conceivably be situations where specifying the same 0% and 100% is not equivalent to specifying only one of them - which the spec theoretically supports, but which I don't know why anyone would want.

Thoughts?

[stoeffel]

It looks like all of the css animations at NRI are animating exactly one property (opacity or transform). I wonder if it would be nicer to have keyframes : Style -> List ( Float, Style ) -> Style -> Keyframes. You could still use batch if you need to animate multiple properties.

[littleStudent]

With the current API users would be forced to provide at least 0% and 100%, which is nice i think. But atm you could use a different property at 0% and 100%. Would there be a nice way to enforce that properties you want to animate need to have 0% and 100%?

[enetsee]

This sounds great!

Regarding the 0%/from and 100%/to, I'm not sure these are mandatory. The following is taken from the MDN pages:

If a keyframe rule doesn't specify the start or end states of the animation (that is, 0%/from and 100%/to, browsers will use the element's existing styles for the start/end states. This can be used to animate an element from its initial state and back.

This means that the same animation can be applied to elements with different initial styles (example here) which I can imagine being quite useful.

I could also see specifying different 0% and 100% styles being useful e.g. for a fade-in animation.

Given these use cases, how about the following:

keyframes : { a | from : Maybe (List Style), to: Maybe (List Style) } -> List ( Float, List Style ) -> List Style -> Keyframes

The issue around passing non-animatable properties seems a bit tricky without introducing the phantom type on Style. Are there any other 'classes' of properties that could also be handled this way to make introducing a phantom type slightly more compelling?

[rtfeldman]

Interesting! Here's another possible design based on that observation, as well as on the realization that it's actually possible to support animationName none and animationName inherit and such:

keyframes : List ( Float, List Style ) -> Value { provides | keyframes : Supported }

animationName :
    Value
        { keyframes : Supported
        , none : Supported
        , unset : Supported
        , initial : Supported
        , inherit : Supported
        }
    -> Style

(If you called animationName (keyframes []) it would be equivalent to calling animationName none.)

The implementation is a bit sneaky because as of the phantom-types branch, Value only holds a String and nothing else. However, this can work out nicely because other than keyframes, animation-name only accepts string constants that are known at compile time.

This would work by having keyframes compile to the CSS that would go in @keyframes, store it as a plain String, and then animationName would check the string it receives to see if it's "none", "unset", "initial", or "inherit". If it's any of these, return AppendProperty ("animation-name" ++ str). Otherwise, it must be a keyframes string; store that in a Style union type constructor that knows what to do with it (hash it to determine its animation name, emit an @keyframes definition for the <style> tag, etc.)

[rootkc]

When can we expect this to be merged?

[bengolds]

Not sure if this is still open or if you'd rather I open another bug. The API works really well! The one thing I miss is animation-play-state. As far as I can tell, there's only paused and running.

[erlandsona]

Sorry to necro-bump this but I'm trying to use two separate keyframe animations one on an infinite cycle and the other as a "show/hide" on opacity/height.

Am I missing a way to do this with the current api or do I just need to drop down to Css.Animations.custom?