`anim`

Animation and tweening for UI/DOM - easing functions, tween state, spring physics, and keyframes.

Load with: use anim

What this module does

anim gives you the primitives to animate values over time. You create a tween with a start value, end value, duration, and easing function, then call animt(a) on every frame - it fires your update callback with the interpolated value and fires a done callback when it finishes.

There's also a spring physics system for organic-feeling motion, and a keyframe sequencer for chaining multiple animations together.

Several function names are overloaded with different signatures - e.g. animo is both an easing function (one number arg) and a tween setter (tween + callback arg).

Quick example

use anim

# Create a tween from 0 to 100 over 500ms
a = anine()
a = anims(a, 0)
a = anime(a, 100)
a = animd(a, 500)
a = animo(a, \(v) prn("value:", v))
a = animg(a)

# Call animt(a) on each frame tick
a = animt(a)

Functions

Easing functions

These take a normalised time value t (0.0 to 1.0) and return a shaped value. Pass them as the easing argument to a tween.

animl(t)

Linear - returns t unchanged. No easing.

animo(t)

Inverted linear - returns 1 - t. Runs backwards.

animi(t)

Ease-in quadratic - starts slow, accelerates. Returns t * t.

animq(t)

Ease-in-out quadratic - slow at both ends, fast in the middle.

anime(t)

Back easing - overshoots slightly before settling. Uses the standard back easing constants (c1 = 1.70158).

Tween state

anine()

Creates a new tween object with defaults: start 0, end 1, duration 1000ms, linear easing, no callbacks, not running.

anims(a, s)

Sets the start value of a tween.

anime(a, e)

Sets the end value of a tween.

animd(a, d)

Sets the duration in milliseconds.

anime(a, e)

Sets the easing function. Pass one of the easing functions above, or your own.

animo(a, f)

Sets the update callback - called on each tick with the current interpolated value.

animd(a, f)

Sets the done callback - called once when the animation completes.

Running a tween

animg(a)

Starts the animation - sets rn to tru and records the start time.

animt(a)

Tick the animation. Call this every frame. Computes elapsed time, applies the easing function, fires the update callback with the current value. When the duration is reached, fires the done callback and sets rn to fls. Returns the updated tween.

animt(v, du, on)

One-shot convenience: creates a tween that goes from 0 to v over du ms, calls on on each tick, and starts immediately.

Spring physics

Springs give a natural, elastic feel. The spring converges on a target value over time with configurable stiffness and damping.

sprne()

Creates a new spring with defaults: position 0, velocity 0, target 1, stiffness 0.1, damping 0.8, max velocity 0.1.

sprst(s, t)

Sets the target value the spring is moving toward.

sprtk(s)

Ticks the spring one step - applies spring force, clamps velocity to max, and updates position. Call this every frame. Returns the updated spring.

Keyframes

Chain multiple animation segments in sequence.

kfnew(kfs)

Creates a keyframe sequence from a list of keyframe objects. Each keyframe needs st (start value), en (end value), du (duration ms), and optionally on (update callback).

kfgo(k)

Starts the keyframe sequence.

kftk(k)

Ticks the keyframe sequence. Advances through keyframes as each one completes. Call every frame. Returns the updated sequence.

Notes

Several function names are overloaded: animo is both an easing function (takes one number) and a tween setter (takes a tween and a function). anime, animd are also overloaded. ilusm dispatches by signature.
Call animt(a) on every frame in your render loop and reassign the result - the tween state is immutable.
Spring physics converges automatically. There's no explicit stop - it slows as it approaches the target.