Add support for interpolation precision; change spring() format

This changes the format of `spring(val, [stiffness, damping])` to
`spring(val, {stiffness, damping, onRest, precision})`.

Docs of this breaking change coming soon, but tldr: second argument now
an object (still optional). `{stiffness: 120, damping: 12}` is clearer
than the previous `[120, 12]`. onRest is for the future end callback
(name subject to change, no implementation yet). Precision is the
rounding of interpolating value. All alltributes are optionals and have
sensible defaults.

More on precision: #100. We don't actually round the numbers; just a
check on whether the destination delta and speed is smaller than a
certain threshold. Rounding the number during interpolation _might not_
be very useful. The main concern is that we can optimize by not
rendering, when the number's so small that it doesn't change. But I'm
not sure the probability of every (rounded) value in `style` not
changing, at any frame, compared to the last, is high enough to justify
the overhead of checking it every frame. We'll see.

src/Types.js

@@ -3,6 +3,8 @@ export type SpringConfig = {
   val: number,
   stiffness: number,
   damping: number,
+  precision: number,
+  onRest?: (() => void),
 };
 export type Style = {
   [key: string]: number | SpringConfig,
@@ -13,6 +15,7 @@ export type CurrentStyle = {
 export type Velocity = {
   [key: string]: number,
 };
+// TODO: gather all the public types here
 export type TransitionStyles = {
   [key: string]: Style,
 };

src/makeMotion.js

@@ -191,6 +191,7 @@ export default function makeMotion(React: Object): Object {
                 propsStyle[key].val,
                 propsStyle[key].stiffness,
                 propsStyle[key].damping,
+                propsStyle[key].precision,
               );
 
               newLastIdealStyle[key] = interpolated[0];
@@ -204,6 +205,7 @@ export default function makeMotion(React: Object): Object {
               propsStyle[key].val,
               propsStyle[key].stiffness,
               propsStyle[key].damping,
+              propsStyle[key].precision,
             );
 
             newCurrentStyle[key] =

src/makeStaggeredMotion.js

@@ -222,6 +222,7 @@ export default function makeStaggeredMotion(React: Object): Object {
                   destStyle[key].val,
                   destStyle[key].stiffness,
                   destStyle[key].damping,
+                  destStyle[key].precision,
                 );
 
                 newLastIdealStyle[key] = interpolated[0];
@@ -235,6 +236,7 @@ export default function makeStaggeredMotion(React: Object): Object {
                 destStyle[key].val,
                 destStyle[key].stiffness,
                 destStyle[key].damping,
+                destStyle[key].precision,
               );
 
               newCurrentStyle[key] =

src/makeTransitionMotion.js

@@ -412,6 +412,7 @@ export default function makeTransitionMotion(React: Object): Object {
                   destStyle[key].val,
                   destStyle[key].stiffness,
                   destStyle[key].damping,
+                  destStyle[key].precision,
                 );
 
                 newLastIdealStyle[key] = interpolated[0];
@@ -425,6 +426,7 @@ export default function makeTransitionMotion(React: Object): Object {
                 destStyle[key].val,
                 destStyle[key].stiffness,
                 destStyle[key].damping,
+                destStyle[key].precision,
               );
 
               newCurrentStyle[key] =

src/presets.js

@@ -1,8 +1,7 @@
 /* @flow */
-// [stiffness, damping]
 export default {
-  noWobble: [170, 26], // the default
-  gentle: [120, 14],
-  wobbly: [180, 12],
-  stiff: [210, 20],
+  noWobble: {stiffness: 170, damping: 26}, // the default
+  gentle: {stiffness: 120, damping: 14},
+  wobbly: {stiffness: 180, damping: 12},
+  stiff: {stiffness: 210, damping: 20},
 };

src/spring.js

@@ -2,12 +2,18 @@
 import presets from './presets';
 import type {SpringConfig} from './Types';
 
-export default function spring(
-  val: number,
-  config?: [number, number] = presets.noWobble): SpringConfig {
-  return {
-    val,
-    stiffness: config[0],
-    damping: config[1],
-  };
+type SpringHelperConfig = {
+  stiffness?: number,
+  damping?: number,
+  onRest?: () => void,
+  precision?: number,
+};
+
+const defaultConfig = {
+  ...presets.noWobble,
+  precision: 0.001,
+};
+
+export default function spring(val: number, config?: SpringHelperConfig): SpringConfig {
+  return {...defaultConfig, ...config, val};
 }

src/stepper.js

@@ -1,13 +1,12 @@
 /* @flow */
-const errorMargin = 0.001;
-
 export default function stepper(
-  frameRate: number,
+  secondPerFrame: number,
   x: number,
   v: number,
   destX: number,
   k: number,
-  b: number): [number, number] {
+  b: number,
+  precision: number): [number, number] {
   // Spring stiffness, in kg / s^2
 
   // for animations, destX is really spring length (spring at rest). initial
@@ -22,10 +21,10 @@ export default function stepper(
   // let a = (Fspring + Fdamper) / mass;
   const a = Fspring + Fdamper;
 
-  const newV = v + a * frameRate;
-  const newX = x + newV * frameRate;
+  const newV = v + a * secondPerFrame;
+  const newX = x + newV * secondPerFrame;
 
-  if (Math.abs(newV) < errorMargin && Math.abs(newX - destX) < errorMargin) {
+  if (Math.abs(newV) < precision && Math.abs(newX - destX) < precision) {
     return [destX, 0];
   }
 

test/makeMotion-test.js

@@ -195,7 +195,9 @@ describe('Motion', () => {
     const App = React.createClass({
       render() {
         return (
-          <Motion defaultStyle={{a: 0}} style={{a: spring(10, [100, 50])}}>
+          <Motion
+              defaultStyle={{a: 0}}
+              style={{a: spring(10, {stiffness: 100, damping: 50, precision: 16})}}>
             {({a}) => {
               count.push(a);
               return null;
@@ -206,12 +208,17 @@ describe('Motion', () => {
     });
     TestUtils.renderIntoDocument(<App />);
 
-    expect(count).toEqual([0]);
-    mockRaf.step(2);
+    mockRaf.step(99);
     expect(count).toEqual([
       0,
       0.2777777777777778,
       0.5941358024691358,
+      0.9081361454046639,
+      1.213021309632678,
+      1.5079182450697726,
+      1.7929588941684615,
+      2.0684390330691236,
+      10,
     ]);
   });
 

test/makeStaggeredMotion-test.js

@@ -84,7 +84,7 @@ describe('StaggeredMotion', () => {
         return (
           <StaggeredMotion
             defaultStyles={[{a: 0}]}
-            styles={() => [{a: spring(10, [100, 50])}]}>
+            styles={() => [{a: spring(10, {stiffness: 100, damping: 50, precision: 16})}]}>
             {([{a}]) => {
               count.push(a);
               return null;
@@ -95,12 +95,17 @@ describe('StaggeredMotion', () => {
     });
     TestUtils.renderIntoDocument(<App />);
 
-    expect(count).toEqual([0]);
-    mockRaf.step(2);
+    mockRaf.step(99);
     expect(count).toEqual([
       0,
       0.2777777777777778,
       0.5941358024691358,
+      0.9081361454046639,
+      1.213021309632678,
+      1.5079182450697726,
+      1.7929588941684615,
+      2.0684390330691236,
+      10,
     ]);
   });
 

test/makeTransitionMotion-test.js

@@ -81,7 +81,7 @@ describe('TransitionMotion', () => {
         return (
           <TransitionMotion
             defaultStyles={{key: {a: 0}}}
-            styles={{key: {a: spring(10, [100, 50])}}}>
+            styles={{key: {a: spring(10, {stiffness: 100, damping: 50, precision: 16})}}}>
             {({key: {a}}) => {
               count.push(a);
               return null;
@@ -92,13 +92,17 @@ describe('TransitionMotion', () => {
     });
     TestUtils.renderIntoDocument(<App />);
 
-    expect(count).toEqual([0]);
-    // Move "time" by 8 steps, which is equivalent to 8 calls to `raf`
-    mockRaf.step(2);
+    mockRaf.step(99);
     expect(count).toEqual([
       0,
       0.2777777777777778,
       0.5941358024691358,
+      0.9081361454046639,
+      1.213021309632678,
+      1.5079182450697726,
+      1.7929588941684615,
+      2.0684390330691236,
+      10,
     ]);
   });