Type Definitions API

React Ensemble is written in TypeScript. Although you can use the library freely with JavaScript, the structure of your application's inputs will be expected to match certain types. Therefore, referencing the type definitions can be useful even for JavaScript developers.

The type definitions in this file are considered part of React Ensemble's public API.

Animation

Representation of a React Ensemble animation that can generate state at any point in time.

Property	Type	Description
length	`number`	The length of the animation (in milliseconds).
config	`Required<TrackConfig<State>>`	The complete config that was used to generate the animation. Changing these values has no effect on the animation.
getFrameState	`(frame: number) => State`	The animation's frame state generator. Returns the current state of the animation at any time value.
layers	`Record<string, CalculatedTrackRegion<State>[]>`	The calculated track regions, grouped by layer name, that were generated to create this animation.
activeVars	`Set<keyof State>`	The state properties that are animated at any point during the animation.

Generated by TrackUtils.gen. The function getFrameState is used by Timeline to calculate animation state.

CalculatedTrackRegion

A track region that has been parsed into an animation-readable format by TrackUtils.gen.

Property	Type	Description
id	`string`	The region's unique identifier.
activeVars	`Set<keyof State>`	The state properties that are animated at any point during the region.
get	`(current: number) => State`	The region's frame state generator. Returns the current state of the animation at any time value within the region.
start	`number`	The region's starting point (in milliseconds).
end	`number`	The region's ending point (in milliseconds).
layer	`string`	The region's layer name.

ControlPanelProps

Includes all the data necessary to render a responsive playback control with play/pause, fast-forward, reverse, and progress bar features.

Property	Type	Description
tick	`number`	The track's time position (in milliseconds).
length	`number` or `null`	The length of the animation (in milliseconds).
playing	`boolean`	Whether the animation is playing.
direction	`Direction`	The mode of playback.
setTick	`(tick: number) => void`	Callback to signal a manual tick change.
play	`() => void`	Callback to signal a manual play.
pause	`() => void`	Callback to signal a manual pause.
fastForward	`() => void`	Callback to signal a manual fast-forward toggle (on or off).
reverse	`() => void`	Callback to signal a manual reverse toggle (on or off).

Used primarily by Controller to communicate with its panel prop, which is SimpleControlPanel by default.

Direction

Enumeration of all possible playback modes in a Controller.

Value	Description
`Direction.Normal`	The animation is playing forwards at normal speed.
`Direction.FastForward`	The animation is playing forwards at a faster speed. The exact rate is configured by `Controller`.
`Direction.Reverse`	The animation is playing backwards, sometimes at a faster speed. The exact rate is configured by `Controller`.

EasingFunction

A function that will transform a normalized time [0,1] according to some curve.

InterpolationFunction

A function that, based on two values, creates a function that will blend between the two values over a normalized time range [0,1].

LoadEvent

Event payload returned by Timeline when it finishes initializing the animation.

Property	Type	Description
animation	`Animation<State>`	The generated animation.

LoopConfig

Configuration for if and how a track region should loop during an animation.

Property	Type	Description
boomerang	`boolean`	Whether the region should "boomerang" back to its initial values after each execution. (Optional)
count	`number`	The number of times the region should loop in addition to its regular execution. (Optional)
until	`number`	The absolute time in milliseconds the region should loop until. (Optional)
duration	`number`	The number of milliseconds the region should loop for. (Optional)

If used for an animation parsed by TrackUtils.gen, the following rules apply:

Zero or one of the properties count, until, and duration may be defined, but no more.
If none of the properties count, until, or duration are defined, the region will be a passive loop.

RegionState

Helper type that maps every property of an animation's state to a declarative RegionStateProperty for use in a TrackRegionAtom.

For example, this object would work for RegionState<{ x: number, y: number }>

RegionStateProperty

Description of how an animation's state property should change over the course of a single track region.

Property	Type	Description
from	`T`	If specified, the state property will be set to this value at the start of the region.
to	`T`	If specified, the state property will gradually change to this value over the duration of the region.
set	`T` or `(previous: T) => T`	If specified, the state property will be set to this value (or the output of this function when given the previous value) at the start of the region.

If used for an animation parsed by TrackUtils.gen, the following rules apply:

At least to or set must be defined.
If set is defined, from and to must not be defined.

ResolverLayerData

Used within a TrackLayerResolver, contains metadata about any region across any layer that is animating the state property at this point.

Property	Type	Description
name	`string`	The region's layer name.
rank	`number`	The region's layer rank, calculated by alphanumerically sorting all the layer names in the track. A higher rank means a higher position in that list.
age	`number`	The milliseconds that have passed since this state property was changed in this layer.
value	`T`	The value of this state property in this layer at this time.

TickEvent

Event payload returned by Timeline on each tick.

Property	Type	Description
value	`number`	The track's time position (in milliseconds).

TimelineEndBehavior

Describes how the engine will calculate frame states for time values greater than the length of the animation.

Value	Description
`"stop"`	Time will be clamped to the length of the animation. Gives the impression of the animation pausing once it is finished.
`"continue"`	Time will continue to increase. Passive loops will continue to run indefinitely.
`"loop"`	Time will reset back to the start of the animation. Gives the impression of the animation looping.
`"boomerang"`	Time will be transformed so the animation appears to run backwards after it completes, then start over.

TrackConfig

Top-level configuration for an animation.

Property	Type	Description
endBehavior	`TimelineEndBehavior`	How the engine will calculate frame states for time values greater than the length of the animation. (Optional)
easing	`EasingFunction`	The easing function that will be applied to each region if it does not specify its own. (Optional)
interp	`InterpolationFunction`	The interpolation function that will be applied to each region if it does not specify its own. (Optional)
resolver	`TrackLayerResolver`	The function that will be used to determine which state value to use when multiple layers animate the same one. (Optional)

TrackLayerResolver

Function used inside Animation.getFrameState that will determine the value for a state property animated by multiple layers at once.

Parameter	Type	Description
stateKey	`keyof State`	The key of the state property in question.
layers	`ResolverLayerData`	Metadata about any region across any layer that is animating the state property at this point.

Returns: The composite value to be used for that state property.

TrackRegion

Data used to describe an animation's behavior over a given time frame.

TrackRegion is actually a union of two types of track regions: TrackRegionAtom and TrackRegionGroup. Wherever track regions are expected, there can be any assortment of these two region types.

Although TrackRegionAtom and TrackRegionGroup have some unique properties, they have many in common. The properties shared across all types of track regions include:

Property	Type	Description
start	`number`	The region's starting point, in milliseconds. (Optional)
end	`number`	The region's ending point, in milliseconds. (Optional)
easing	`EasingFunction`	The region's easing function, which will override the `TrackConfig` easing function. (Optional)
interp	`InterpolationFunction`	The region's interpolation function, which will override the `TrackConfig` interpolation function. (Optional)
layer	`string`	The region's layer name. (Optional)
loop	`LoopConfig` or `boolean`	Determines if and how the region should loop within the animation. (Optional) If true, will be a passive loop. If an object, will be parsed according to `LoopConfig`

If used for an animation parsed by TrackUtils.gen, the following rules apply:

If defined, start must be later than or equal to the end of the region before it in the same layer.
If defined, end must be later than or equal to start.
If loop is defined, end must not be defined.

TrackRegionAtom

A TrackRegion that describes a single "curve" of an animation, which involves zero or more state properties changing in a particular way over a defined time frame.

Includes all the common TrackRegion properties.

Property	Type	Description
duration	`number`	The region's length, in milliseconds. (Optional)
state	`RegionState<State>`	Description of any state property changes over the course of the region. (Optional)

If used for an animation parsed by TrackUtils.gen, the following rules apply:

If duration and end are defined, end must equal duration plus the region before it in the same layer's end time.
If loop is defined, duration must be defined.

TrackRegionGroup

A group of track regions that should be treated as a single region.

Includes all the common TrackRegion properties.

Property	Type	Description
regions	`TrackRegion[]`	The array of regions to be grouped and considered as a single region.
relativeTime	`boolean`	Whether the timestamps of all regions in the group will be parsed as if this group's starting time equals zero. Default: `false`

When parsed by TrackUtils.gen, every group becomes its own self-contained animation. This has the following effects:

relativeTime will determine whether every region's timestamps are relative to the start of the group. If true, start: 100 would be interpreted as start: (group_start) + 100.
Layers will be namespaced according to this pattern: "parent-layer-name.layer-name". Therefore, a region with the layer "foo" in a group will not be in the same layer as "foo" at the top level.

UpdateEvent

Event payload returned by Timeline every time its time value updates.

Property	Type	Description
state	`State`	The animation's frame state at the time the event was generated.

TrackUtils

Examples

Type Definitions API

.css-rg7n4{color:var(--theme-ui-colors-text,#231d35);-webkit-text-decoration:none;text-decoration:none;font-family:allumi-std,sans-serif;}.css-rg7n4:hover{-webkit-text-decoration:underline;text-decoration:underline;}Animation

Animation