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.
| Parameter | Type | Description |
|---|---|---|
| track | TrackRegion<State>[] | The array of regions that make up the animation. |
| defaults | State | The animation's default state. |
| config | TrackConfig<State> | Various configuration for the computed animation. |
- Returns:
Animation<State>
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:
- Apply config defaults for values not provided.
- Separate track regions by layer.
- Validate regions layer-by-layer, creating a frame state getter function for each region based on its properties.
- When groups are encountered, calculate a sub-animation for each group recursively.
- Add every region to an interval tree, including data about each state property's activity.
- Build a frame state getter for the entire interval tree involving the configured layer resolver.
- Return the frame state getter function and assorted data via an
Animationobject.
gen -- Config Defaults
The following default config properties will be used for every value of config not specified:
| Property | Default |
|---|---|
| endBehavior | "stop" |
| easing | Lib.d3Ease.easeCubic |
| interp | Lib.d3Interpolate.interpolate |
| resolver | TrackUtils.layerResolvers.overrideLast |
gen - Playground
SyntaxError: Unexpected token (1:8)
1 : return ()
^group
Places one or more track regions into a single group.
| Parameter | Type | Description |
|---|---|---|
| regions | TrackRegion or TrackRegion[] | The region or regions to be grouped. |
| config | Omit<TrackRegionGroup<State>, "regions"> | Any region properties to be applied to the finished group, excluding regions. (Optional) |
- Returns:
TrackRegionGroup<State>
group -- Playground
SyntaxError: Unexpected token (1:8)
1 : return ()
^layer
Returns one or more new regions with the given layer name.
| Parameter | Type | Description |
|---|---|---|
| layerName | string or number | The layer name to apply to the regions. Since TrackRegion.layer must be a string, a number passed here will be cast to a string. |
| regions | TrackRegion or TrackRegion[] | The region or regions to be copied with the new layer. |
- Returns:
TrackRegionorTrackRegion[], depending on whether or not one or more regions were passed to the function.
layer -- Playground
SyntaxError: Unexpected token (1:8)
1 : return ()
^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
- Type:
TrackLayerResolver
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.
| Parameter | Type | Description |
|---|---|---|
| regions | TrackRegion or TrackRegion[] | The region or regions to be placed into the looping group. |
| config | boolean or number or LoopConfig | If 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. |
- Returns:
TrackRegionGroup<State>
loop -- Playground
SyntaxError: Unexpected token (1:8)
1 : return ()
^multi
Flattens a collection of tracks into a single group's track, with the regions from each sub-track on separate layers.
| Parameter | Type | Description |
|---|---|---|
| track | Either: 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. |
| config | Omit<TrackRegionGroup<State>, "regions"> | Any region properties to be applied to the finished group, excluding regions. (Optional) |
- Returns:
TrackRegionGroup<State>
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 ()
^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 ()
^