Holds the WAAPI engine state.

Keep this in your model.

The msg type parameter is your Msg type.

type alias Model =
    { animState : WAAPI.AnimState Msg }

The name of the animation group you want to target.

Base animation builder type for this engine.

Builder type for WAAPI-only builders.

Use this in type annotations when a builder function should only work with this engine.

📖 See Engine Capabilities for patterns and examples.

Initialize the engine state.

Takes the command port, message port, and a list of property initializers:

import Anim.Engine.WAAPI as WAAPI
import Anim.Property.Opacity as Opacity


WAAPI.init motionCmd motionMsg <|
    [ Opacity.init "animGroupName" 0.5
    , ... -- any other property initializers
    ]

Select the animation group that subsequent property builders will target.

WAAPI.for "animGroupName"
    >> Opacity.begin
    >> Opacity.to 0.2
    >> Opacity.end

Trigger animations.

Returns the updated animation state and the command to send to JavaScript.

import Anim.Engine.WAAPI as WAAPI


let
    ( animState, animCmd ) =
        WAAPI.animate model.animState entryAnim
in
( { model | animState = animState }, animCmd )

Execute a fire-and-forget animation without state tracking.

import Anim.Engine.WAAPI as WAAPI
import Json.Encode as Encode


port motionCmd : Encode.Value -> Cmd msg


WAAPI.fireAndForget motionCmd entryAnim

Useful if you don't need to track the animation state in your model or handle events from the engine, and just want to trigger an animation with a one-off command.

Change the targeted properties instantly to their new values. If currently animating, stop.

This is a convenience function for immediately snapping properties or axes to new values without needing to construct a full animation builder with animate.

Just target the properties or axes you want to change, and any properties or axes you don't mention will be left untouched - if mid-flight, they will continue.

import Anim.Engine.WAAPI as WAAPI
import Anim.Property.Translate as Translate


let
    ( animState, animCmd ) =
        WAAPI.retarget model.animState <|
            WAAPI.for "animGroupName"
                >> Translate.begin
                >> Translate.toY 0
                >> Translate.end
in
( { model | animState = animState }, animCmd )

Animation lifecycle events from this engine.

Opt in to per-frame Progress events.

Off by default.

Progress events can create a lot of noise in your update loop, especially when debugging the Msg flow in your app. Therefore they are suppressed by default and you need to explicitly opt in to receive them.

This is a precedence function, so it can operate as a global setting for all groups in the builder chain, or you can set it on a per-group basis which overrides any global setting for that group.

WAAPI.withProgressEvents True -- global setting
    >> WAAPI.for "box"
    >> WAAPI.withProgressEvents False -- overrides global for this group
    >> ... -- other builders

Set the minimum interval in milliseconds between per-frame propertyUpdate emissions from the JavaScript runtime.

The visual animation is driven by the browser compositor and is never affected by this setting - it only controls how much port traffic is generated.

This is a precedence function, so it can operate as a global setting for all groups in the builder chain, or you can set it on a per-group basis which overrides any global setting for that group.

• Pass 0 (the default) to emit on every requestAnimationFrame tick, matching the display refresh rate (60 Hz, 120 Hz, 144 Hz, …).
• Pass a positive number of milliseconds to cap the emission rate, e.g. 16 for ~60 Hz, 33 for ~30 Hz.

Note: Higher throttle values reduce Elm-side mid-flight precision for queries and interruption bookkeeping.

WAAPI.setUpdateThrottle 33 -- global default
        >> WAAPI.for "hero"
        >> WAAPI.setUpdateThrottle 0 -- dense updates for interactions
        >> ... -- other builders
        >> WAAPI.for "background"
        >> WAAPI.setUpdateThrottle 50 -- lower traffic for passive motion
        >> ... -- other builders

Message type used with update.

import Anim.Engine.WAAPI as WAAPI


type Msg
    = WaapiMsg WAAPI.AnimMsg
    | ...

Handle messages from this engine.

Returns the updated state and the event for this message.

Messages that do not belong to this engine return (animState, Nothing).

import Anim.Engine.WAAPI as WAAPI


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        WaapiMsg animMsg ->
            let
                ( animState, maybeAnimEvent ) =
                    WAAPI.update animMsg model.animState
            in
            handleAnimationEvent maybeAnimEvent { model | animState = animState }


handleAnimationEvent : Maybe WAAPI.AnimEvent -> Model -> ( Model, Cmd Msg )
handleAnimationEvent event model =
    case event of
        ...

Subscribe to receive animation updates from JavaScript.

Without this, your app won't receive any animation events or updates.

import Anim.Engine.WAAPI as WAAPI


type Msg
    = WaapiMsg WAAPI.AnimMsg
    | ...


subscriptions : Model -> Sub Msg
subscriptions model =
    WAAPI.subscriptions WaapiMsg model.animState

Apply baseline and state styles to your element.

Sets the element's starting, current, and end property values as inline styles, and adds the data-anim-target attribute so the JavaScript companion can locate the element when the animation is triggered.

import Anim.Engine.WAAPI as WAAPI
import Html exposing (div, text)


div
    (WAAPI.attributes "animGroupName" model.animState)
    [ text "Animating element" ]

A resize handler that updates animation configurations in response to a layout changes.

Pair this with the bounds functions in property modules in order to remap the properties to new element dimensions or positions on the fly.

Example resize handler targeting two groups in one call:

import Anim.Engine.WAAPI as WAAPI
import Anim.Property.Scale as Scale
import Anim.Property.Translate as Translate


GotTrack (Ok element) ->
    let
        ( animState, animCmd ) =
            WAAPI.onResize model.animState <|
                Translate.bounds "box" translateBounds
                    >> Scale.bounds "cube" scaleBounds
    in
    ( { model | animState = animState }
    , animCmd
    )

Set how many times an animation should repeat.

Make an animation loop infinitely.

Make an animation alternate direction on each iteration.

alternate only has a visible effect when the animation runs more than once, so calling it when iterations is unset or 1 automatically bumps iterations to 2. An explicit iterations count (or loopForever) set before or after alternate is preserved.

Set the global delay for all animations in this builder.

introAnim : EngineBuilder -> EngineBuilder
introAnim =
    delay 500
        >> fadeInHeader
        >> slideInSidebar
        >> fadeInContent

Set the global duration for all animations in this builder.

introAnim : EngineBuilder -> EngineBuilder
introAnim =
    duration 500
        >> fadeInHeader
        >> slideInSidebar
        >> fadeInContent

Set the global speed for all animations in this builder.

introAnim : EngineBuilder -> EngineBuilder
introAnim =
    speed 300
        >> slideDownHeader
        >> slideInSidebar
        >> slideUpContent

Set the global easing function.

heroEntrance : EngineBuilder -> EngineBuilder
heroEntrance =
    easing EaseInOut
        >> fadeInHeroTitle
        >> slideInHeroArtwork
        >> revealPrimaryCta

Set the global spring.

draggableCardSettle : EngineBuilder -> EngineBuilder
draggableCardSettle =
    spring Spring.wobbly
        >> settleCardPosition
        >> settleCardShadow

Set the default length unit for all length-bearing properties.

responsivePanelMotion : EngineBuilder -> EngineBuilder
responsivePanelMotion =
    cssUnit Unit.Vw
        >> slidePanelIn
        >> growPanelHeight

Set the default length unit for the X axis.

responsiveDrawerMotion : EngineBuilder -> EngineBuilder
responsiveDrawerMotion =
    cssUnitX Unit.Vw
        >> slideDrawerX
        >> alignDrawerLabelX

Set the default length unit for the Y axis.

responsiveSheetMotion : EngineBuilder -> EngineBuilder
responsiveSheetMotion =
    cssUnitY Unit.Vh
        >> slideSheetY
        >> alignSheetHeaderY

Set the default length unit for the Z axis.

layeredSceneMotion : EngineBuilder -> EngineBuilder
layeredSceneMotion =
    cssUnitZ Unit.Px
        >> pushSceneBackgroundBack
        >> bringFloatingCardForward

Set the default length unit used for width values in WAAPI animations.

responsiveCardWidth : EngineBuilder -> EngineBuilder
responsiveCardWidth =
    cssUnitWidth Unit.Vw
        >> growCardWidth
        >> settleCardSpacing

Set the default length unit used for height values in WAAPI animations.

responsivePanelHeight : EngineBuilder -> EngineBuilder
responsivePanelHeight =
    cssUnitHeight Unit.Vh
        >> expandPanelHeight
        >> alignPanelHeaderY

Stop a running animation by instantly jumping to its end state.

import Anim.Engine.WAAPI as WAAPI


let
    ( animState, stopCmd ) =
        WAAPI.stop "animGroup" model.animState
in
( { model | animState = animState }, stopCmd )

Reset an animation by instantly jumping back to its start state.

import Anim.Engine.WAAPI as WAAPI


let
    ( animState, resetCmd ) =
        WAAPI.reset "animGroup" model.animState
in
( { model | animState = animState }, resetCmd )

Restart an animation from the beginning.

import Anim.Engine.WAAPI as WAAPI


let
    ( animState, restartCmd ) =
        WAAPI.restart "animGroup" model.animState
in
( { model | animState = animState }, restartCmd )

Pause a running animation.

import Anim.Engine.WAAPI as WAAPI


let
    ( animState, pauseCmd ) =
        WAAPI.pause "animGroup" model.animState
in
( { model | animState = animState }, pauseCmd )

Resume a paused animation.

import Anim.Engine.WAAPI as WAAPI


let
    ( animState, resumeCmd ) =
        WAAPI.resume "animGroup" model.animState
in
( { model | animState = animState }, resumeCmd )

Add a discrete CSS property for entry animations.

The value is applied as an inline style from the first frame and held throughout the animation. Use this when an element is appearing (e.g., going from display: none to display: block).

This function is a precedence function, so it can operate as a global setting for all groups in the builder chain, or you can set it on a per-group basis which overrides any global setting for that group.

import Anim.Engine.WAAPI as WAAPI
import Anim.Property.Opacity as Opacity


WAAPI.animate model.animState <|
    WAAPI.discreteEntry "display" "block"
        >> WAAPI.discreteEntry "visibility" "visible"
        >> WAAPI.for "box"
        >> Opacity.begin
        >> Opacity.to 1
        >> Opacity.end

Add a discrete CSS property for exit animations.

Exit animations need to hold their initial state until the very end of the animation, at which point they flip to the final state. Therefore you need to set both entry and exit values for the property.

This function is a precedence function, so it can operate as a global setting for all groups in the builder chain, or you can set it on a per-group basis which overrides any global setting for that group.

Use when an element is disappearing (e.g., going from display: block to display: none).

import Anim.Engine.WAAPI as WAAPI
import Anim.Property.Opacity as Opacity


WAAPI.animate model.animState <|
    WAAPI.discreteExit "display" "block" "none"
        >> WAAPI.for "box"
        >> Opacity.begin
        >> Opacity.to 0
        >> Opacity.end

Set the transform order.

The transform order specifies how translate, rotate, skew and scale transforms are combined. Start the list with the transform to apply first.

This is a precedence function, so it can operate as a global setting for all groups in the builder chain, or you can set it on a per-group basis which overrides any global setting for that group.

Any missing transforms are automatically appended in the default order (Translate → Rotate → Skew → Scale).

import Anim.Engine.WAAPI as WAAPI
import Anim.Extra.TransformOrder exposing (TransformProperty(..))


WAAPI.transformOrder [ Scale, Rotate, Translate, Skew ] -- global setting
    >> WAAPI.for "box"
    >> WAAPI.transformOrder [ Rotate, Translate ] -- overrides global for this group
    >> ... -- other builders

Identifies a property that can be frozen at its current animated position.

Use with freezeX, freezeY, etc. to hold specific axes at their current values during animation interruptions.

Freeze the translate property.

Freeze the rotate property.

Freeze the scale property.

Freeze the skew property.

Freeze the X axis of the specified properties at their current animated values.

The named axis indicates which axis will remain frozen while you animate the others.

import Anim.Engine.WAAPI as WAAPI
import Anim.Property.Translate as Translate


let
    ( animState, animCmd ) =
        WAAPI.animate model.animState <|
            WAAPI.freezeX [ WAAPI.translate ]
                >> WAAPI.for "box"
                >> Translate.begin
                >> Translate.toY 0
                >> Translate.end
in
( { model | animState = animState }, animCmd )

Freeze the Y axis of the specified properties at their current animated values.

Freeze the Z axis of the specified properties at their current animated values.

Freeze the X and Y axes of the specified properties at their current animated values.

Freeze the X and Z axes of the specified properties at their current animated values.

Freeze the Y and Z axes of the specified properties at their current animated values.

Freeze all axes of the specified properties at their current animated values.

Unfreeze the X axis of the specified properties, allowing it to animate again.

Unfreeze the Y axis of the specified properties, allowing it to animate again.

Unfreeze the Z axis of the specified properties, allowing it to animate again.

Unfreeze the X and Y axes of the specified properties.

Unfreeze the X and Z axes of the specified properties.

Unfreeze the Y and Z axes of the specified properties.

Unfreeze all axes of the specified properties.

Check if any animations are currently running.

Returns Nothing if there are no animations.

Check if a specific animation group is currently running.

Returns Nothing if there are no animations for the group.

Check if all animations are complete.

Returns Nothing if there are no animations.

Check if a specific animation group has completed.

Returns Nothing if there are no animations for the group.

Get the current progress of an animation group as a value from 0.0 to 1.0.

Returns Nothing if there are no animations for the group.

import Anim.Engine.WAAPI as WAAPI


WAAPI.getProgress "myAnimation" model.animState
-- Just 0.5 (halfway through)

Get the current interpolated value of a custom property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom property.

Get the end value of a custom property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom property.

Get the custom property range (start and end) of an element being animated.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom property.

Get the start value of a custom property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom property.

Returns Just 0 if no explicit start value was set, which is the default when no start value is set.

Get the current interpolated value of a custom color property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom color property.

Get the end value of a custom color property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom color property.

Get the custom color property range (start and end) of an element being animated.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom color property.

Get the start value of a custom color property animation.

The second argument is the CSS property name.

Returns Nothing if the element has no animation for the given custom color property.

Returns transparent white (rgba 255 255 255 0) if no explicit start value was set, which is the default when no start value is set.

Get the opacity range (start and end) of an element being animated.

Returns Nothing if the element has no opacity animation.

Get the start opacity of an element being animated.

Returns Nothing if the element has no opacity animation.

Returns Just 1.0 (fully opaque) if no explicit start value was set, which is the default when no start value is set.

Get the end opacity of an element being animated.

Returns Nothing if the element has no opacity animation.

Get the current opacity of an element based on its animation state.

Returns Nothing if the element has no opacity animation.

Returns the start opacity if the animation has not started yet.

Returns the current interpolated opacity if the animation is running.

Returns the end opacity if the animation has completed.

Get the perspective origin range (start and end) of an element being animated.

Returns Nothing if the element has no perspective origin animation.

Get the start perspective origin of an element being animated.

Returns Nothing if the element has no perspective origin animation.

Returns Just { x = 50, y = 50 } if no explicit start value was set, which is the default when no start value is set.

Get the end perspective origin of an element being animated.

Returns Nothing if the element has no perspective origin animation.

Get the current perspective origin of an element based on its animation state.

Returns Nothing if the element has no perspective origin animation.

Returns the current perspective origin from the latest engine snapshot.

Get the rotate range (start and end) of an element being animated.

Returns Nothing if the element has no rotate animation.

Get the start rotation of an element being animated.

Returns Nothing if the element has no rotate animation.

Returns Just { x = 0, y = 0, z = 0 } if no explicit start value was set, which is the default when no start value is set.

Get the end rotation of an element being animated.

Returns Nothing if the element has no rotate animation.

Get the current rotation of an element based on its animation state.

Returns Nothing if the element has no rotate animation.

Returns the start rotation if the animation has not started yet.

Returns the current interpolated rotation if the animation is running.

Returns the end rotation if the animation has completed.

Get the scale range (start and end) of an element being animated.

Returns Nothing if the element has no scale animation.

Get the start scale of an element being animated.

Returns Nothing if the element has no scale animation.

Returns Just { x = 1, y = 1, z = 1 } if no explicit start value was set, which is the default when no start value is set.

Get the end scale of an element being animated.

Returns Nothing if the element has no scale animation.

Get the current scale of an element based on its animation state.

Returns Nothing if the element has no scale animation.

Returns the start scale if the animation has not started yet.

Returns the current interpolated scale if the animation is running.

Returns the end scale if the animation has completed.

Get the size range (start and end) of an element being animated.

Returns Nothing if the element has no size animation.

Get the start size of an element being animated.

Returns Nothing if the element has no size animation.

Returns Just { width = 0, height = 0 } if no explicit start value was set, which is the default when no start value is set.

Get the end size of an element being animated.

Returns Nothing if the element has no size animation.

Get the current size of an element based on its animation state.

Returns Nothing if the element has no size animation.

Returns the start size if the animation has not started yet.

Returns the current interpolated size if the animation is running.

Returns the end size if the animation has completed.

Get the skew range (start and end) of an element being animated.

Returns Nothing if the element has no skew animation.

Get the start skew of an element being animated.

Returns Nothing if the element has no skew animation.

Returns Just {x = 0, y = 0} if no explicit start value was set, which is the default when no start value is set.

Get the end skew of an element being animated.

Returns Nothing if the element has no skew animation.

Get the current skew of an element based on its animation state.

Returns Nothing if the element has no skew animation.

Returns the start skew if the animation has not started yet.

Returns the current interpolated skew if the animation is running.

Returns the end skew if the animation has completed.

Get the translate range (start and end) of an element being animated.

Returns Nothing if the element has no translate animation.

Get the start translate of an element being animated.

Returns Nothing if the element has no translate animation.

Returns Just {x = 0, y = 0, z = 0} if no explicit start value was set, which is the default when no start value is set.

Get the end translate of an element being animated.

Returns Nothing if the element has no translate animation.

Get the current translate of an element based on its animation state.

Returns Nothing if the element has no translate animation.

Returns the start translate if the animation has not started yet.

Returns the current interpolated translate if the animation is running.

Returns the end translate if the animation has completed.