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

TrackUtils API

The TrackUtils module contains contains utility functions related to building and parsing animation tracks.

Import

Interface

gen

Parses an animation's track and configuration into a queryable Animation object.

ParameterTypeDescription
trackTrackRegion<State>[]The array of regions that make up the animation.
defaultsStateThe animation's default state.
configTrackConfig<State>Various configuration for the computed animation.

This function contains React Ensemble's core animation parsing engine.

Timeline calls gen internally to calculate its animation, but there may be instances where you would want to parse and query animations directly.

Roughly, gen calculates an animation via these steps:

  1. Apply config defaults for values not provided.
  2. Separate track regions by layer.
  3. Validate regions layer-by-layer, creating a frame state getter function for each region based on its properties.
  4. When groups are encountered, calculate a sub-animation for each group recursively.
  5. Add every region to an interval tree, including data about each state property's activity.
  6. Build a frame state getter for the entire interval tree involving the configured layer resolver.
  7. Return the frame state getter function and assorted data via an Animation object.

gen -- Config Defaults

The following default config properties will be used for every value of config not specified:

PropertyDefault
endBehavior"stop"
easingLib.d3Ease.easeCubic
interpLib.d3Interpolate.interpolate
resolverTrackUtils.layerResolvers.overrideLast

gen - Playground

SyntaxError: Unexpected token (1:8)
1 : return ()
            ^
(Minimized Live Code)

group

Places one or more track regions into a single group.

ParameterTypeDescription
regionsTrackRegion or TrackRegion[]The region or regions to be grouped.
configOmit<TrackRegionGroup<State>, "regions">Any region properties to be applied to the finished group, excluding regions. (Optional)

group -- Playground

SyntaxError: Unexpected token (1:8)
1 : return ()
            ^
(Minimized Live Code)

layer

Returns one or more new regions with the given layer name.

ParameterTypeDescription
layerNamestring or numberThe layer name to apply to the regions. Since TrackRegion.layer must be a string, a number passed here will be cast to a string.
regionsTrackRegion or TrackRegion[]The region or regions to be copied with the new layer.
  • Returns: TrackRegion or TrackRegion[], depending on whether or not one or more regions were passed to the function.

layer -- Playground

SyntaxError: Unexpected token (1:8)
1 : return ()
            ^
(Minimized Live Code)

layerResolvers

Contains layer resolver functions—currently, only overrideLast—to be used by gen to calculate an animation's frame state getter.

Layer resolvers are used to calculate the composite value for a single animation state property that exists in multiple track layers at the same time. When such a case arises, information about the layers that contain the state property are given to the animation's track layer resolver, and the output of the resolver is used as the state property's value for that frame.

See the Layer Resolution guide or TrackLayerResolver type definition for more information.

layerResolvers.overrideLast

Selects the value candidate with the lowest age (least amount of time since it was last updated).

If multiple candidates have the same age, the one with the highest layer rank will be used. Layer rank is calculated by alphanumerically sorting all layer names that exist in the track.

loop

Places one or more regions into a group with the specified loop configuration.

ParameterTypeDescription
regionsTrackRegion or TrackRegion[]The region or regions to be placed into the looping group.
configboolean or number or LoopConfigIf a number, the region will be configured to loop that number of times. Otherwise, the config passed here will be the group's loop property. See the Looping guide.

loop -- Playground

SyntaxError: Unexpected token (1:8)
1 : return ()
            ^
(Minimized Live Code)

multi

Flattens a collection of tracks into a single group's track, with the regions from each sub-track on separate layers.

ParameterTypeDescription
trackEither: An array of TrackRegion and TrackRegion[], or an object with each value as a TrackRegion or TrackRegion[]The tracks to be flattened. If a 2D array is passed, each track's new layer will be its index in the 2D array. If an object is passed, the key referring to each track will be used as the layer.
configOmit<TrackRegionGroup<State>, "regions">Any region properties to be applied to the finished group, excluding regions. (Optional)

This function is useful for assembling groups with multiple concurrent layers.

multi -- Playground

If the input track is a list of lists/single regions, each layer name will be the index of the input sub-track:

SyntaxError: Unexpected token (1:8)
1 : return ()
            ^
(Minimized Live Code)

If the input track is a object where every value is a list or single region, each layer name will be the key of that group:

SyntaxError: Unexpected token (1:8)
1 : return ()
            ^
(Minimized Live Code)
Previous:
Timeline
Next:
Type Definitions
Copyright © 2020 Joseph Cowman. All rights reserved.
React Ensemble is licensed under the MIT License.