• Overview
  • Guides
    • Controller
    • Lib
    • SimpleControlPanel
    • Timeline
    • TrackUtils
    • Type Definitions

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.

PropertyTypeDescription
lengthnumberThe length of the animation (in milliseconds).
configRequired<TrackConfig<State>>The complete config that was used to generate the animation. Changing these values has no effect on the animation.
getFrameState(frame: number) => StateThe animation's frame state generator. Returns the current state of the animation at any time value.
layersRecord<string, CalculatedTrackRegion<State>[]>The calculated track regions, grouped by layer name, that were generated to create this animation.
activeVarsSet<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.

PropertyTypeDescription
idstringThe region's unique identifier.
activeVarsSet<keyof State>The state properties that are animated at any point during the region.
get(current: number) => StateThe region's frame state generator. Returns the current state of the animation at any time value within the region.
startnumberThe region's starting point (in milliseconds).
endnumberThe region's ending point (in milliseconds).
layerstringThe 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.

PropertyTypeDescription
ticknumberThe track's time position (in milliseconds).
lengthnumber or nullThe length of the animation (in milliseconds).
playingbooleanWhether the animation is playing.
directionDirectionThe mode of playback.
setTick(tick: number) => voidCallback to signal a manual tick change.
play() => voidCallback to signal a manual play.
pause() => voidCallback to signal a manual pause.
fastForward() => voidCallback to signal a manual fast-forward toggle (on or off).
reverse() => voidCallback 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.

ValueDescription
Direction.NormalThe animation is playing forwards at normal speed.
Direction.FastForwardThe animation is playing forwards at a faster speed. The exact rate is configured by Controller.
Direction.ReverseThe 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.

PropertyTypeDescription
animationAnimation<State>The generated animation.

LoopConfig

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

PropertyTypeDescription
boomerangbooleanWhether the region should "boomerang" back to its initial values after each execution. (Optional)
countnumberThe number of times the region should loop in addition to its regular execution. (Optional)
untilnumberThe absolute time in milliseconds the region should loop until. (Optional)
durationnumberThe 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.

PropertyTypeDescription
fromTIf specified, the state property will be set to this value at the start of the region.
toTIf specified, the state property will gradually change to this value over the duration of the region.
setT or (previous: T) => TIf 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.

PropertyTypeDescription
namestringThe region's layer name.
ranknumberThe 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.
agenumberThe milliseconds that have passed since this state property was changed in this layer.
valueTThe value of this state property in this layer at this time.

TickEvent

Event payload returned by Timeline on each tick.

PropertyTypeDescription
valuenumberThe 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.

ValueDescription
"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.

PropertyTypeDescription
endBehaviorTimelineEndBehaviorHow the engine will calculate frame states for time values greater than the length of the animation. (Optional)
easingEasingFunctionThe easing function that will be applied to each region if it does not specify its own. (Optional)
interpInterpolationFunctionThe interpolation function that will be applied to each region if it does not specify its own. (Optional)
resolverTrackLayerResolverThe 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.

ParameterTypeDescription
stateKeykeyof StateThe key of the state property in question.
layersResolverLayerDataMetadata 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:

PropertyTypeDescription
startnumberThe region's starting point, in milliseconds. (Optional)
endnumberThe region's ending point, in milliseconds. (Optional)
easingEasingFunctionThe region's easing function, which will override the TrackConfig easing function. (Optional)
interpInterpolationFunctionThe region's interpolation function, which will override the TrackConfig interpolation function. (Optional)
layerstringThe region's layer name. (Optional)
loopLoopConfig or booleanDetermines 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.

PropertyTypeDescription
durationnumberThe region's length, in milliseconds. (Optional)
stateRegionState<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.

PropertyTypeDescription
regionsTrackRegion[]The array of regions to be grouped and considered as a single region.
relativeTimebooleanWhether 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.

PropertyTypeDescription
stateStateThe animation's frame state at the time the event was generated.
Previous:
TrackUtils
Next:
Examples
Copyright © 2020 Joseph Cowman. All rights reserved.
React Ensemble is licensed under the MIT License.