tylerjpeterson/value-chase

Creates a value chase incorporating an ease and friction.

valueChase

Creates a value chase incorporating an ease and friction.

This module creates a chase between a provided value and target value. For example, if you had a dot follow every mouse click on a page, animating against the output of this module allows us to have the dot move to our current location gradually rather than immediately jumping to it. And if we move the mouse while it's traveling to its target, it will correct course smoothly.

User-defined friction, ease, and specificity (tolerance) requirements allow you to control how quickly and aggressively a value chases its target.

This module is a trait more than a class, and is meant to be augmented by other modules such as pointer-chase and scroll-chase. It extends EventEmitter, and broadcasts progress towards reaching its target.

Basic demo.

Installation

Install via npm:

$ npm i value-chase

Usage

const ValueChase = require('value-chase');
const valueChase = new ValueChase();

valueChase.on('render', evt => {
  console.log(evt.progress);
});

valueChase.start();

window.setTimeout(() => {
  valueChase.setProgress(100);
}, 1000);

Methods

Methods that accept parameters always expect numeric values.

method	description
ValueChase.destroy()	Stops the module, removes all listeners, destroys its internal ticker-js instance, and broadcasts the destroyed event.
ValueChase.start()	Starts the internal ticker-js instance and begins calculating the current value.
ValueChase.stop()	Stops the internal ticker-js instance and pauses calculating current value. Also stops all events from being emitted.
ValueChase.isRunning()	Whether or not the instance is currently stopped.
ValueChase.setValue(number)	Immediately jump to the provided value and force a render.
ValueChase.setProgress(number)	This is how we pass a target value to the motion curve calculator. This is often what needs to be overwritten if you have coordinate or vector values to update.
ValueChase.setFriction(number)	Set friction used by calculator.
ValueChase.setTolerance(number)	Set the specificity requirements necessary to indicate when value has reached target.

Events

This module emits update and render events. All calculations and measurements should occur on update, and the actual rendering of those measurements within the DOM should occur on render.

For example, if we want to have an object slide horizontally as we scroll vertically, determining the x-axis transform based on a value should be done on update. Actually applying the transform via a style tag is done on render.

event	description
render	Apply DOM transformations / animations
update	Calculate any necessary animation values

Tests, Coverage, and Documentation

Tests, coverage reports, and documentation can be run / generated by calling their appropriate npm script. See the package.json for script names.