Adding dedicated spring action

README.md

@@ -5,7 +5,7 @@
 Create unique animations and interactions with tweens, physics and input tracking.
 
 Popmotion is:
-- **Tiny:** At ~9kb, it's 75% smaller than GreenSock.
+- **Tiny:** At ~10kb, it's 75% smaller than GreenSock.
 - **Fast:** Stands up to popular alternatives in [performance tests](http://codepen.io/popmotion/pen/zNYXmR).
 - **Compatible:** Full browser support and preloaded with CSS, SVG and SVG path renderers.
 - **Composable:** Actions and output functions can be composed to [create complex motion systems](http://codepen.io/popmotion/pen/EZaPxZ).

docs/api/action/spring.md

@@ -0,0 +1,47 @@
+---
+title: Spring
+description: A UI spring simulation, based on Apple's CASpringAnimation.
+category: action
+---
+
+# Spring
+
+A highly-accurate spring simulation based on Apple's `CASpringAnimation` implementation.
+
+This simulation offers greater variety and accuracy than the basic spring equations in [`physics`](/api/physics).
+
+`spring(props <Object>)`
+
+## Props
+- `stiffness <Number>`: The spring stiffness (default: `100`)
+- `damping <Number>`: The strength of the friction force used to dampen motion (default: `10`)
+- `mass <Number>`: Mass of the moving object. (default: `1.0`)
+- `velocity <Number>`: The initial velocity of the spring. (default: `0.0`)
+- `from <Number>`: Start from this number. (default `0`)
+- `to <Number>`: End at this number. (default `0`)
+- `restDisplacement <Number>`: End the animation if the distance to target is below this value (and `restSpeed`) (default: `0.01`)
+- `restSpeed <Number>`: End the animation if the speed drops below this value (and `restDisplacement`) (default: `0.01`)
+
+## Methods
+
+[...Action](/api/action)
+
+## Playground
+
+```javascript
+import { spring } from 'popmotion';
+```
+
+```marksy
+<Example template="Ball">{`
+const ball = document.querySelector('.ball');
+const ballRenderer = css(ball);
+
+spring({
+  mass: 2,
+  stiffness: 1000,
+  damping: 50,
+  to: 300
+}).start();
+`}</Example>
+```

packages/popmotion-react/stories/index.js

@@ -7,6 +7,7 @@ import { linkTo } from '@storybook/addon-links';
 import DragSingleChild from './react/DragSingleChild';
 import TransitionGroup from './react/TransitionGroup';
 import Toggle from './popmotion/Toggle';
+import Spring from './popmotion/Spring';
 import SpinnableDom from './spinnable/SpinnableDOM';
 import SpinnableSvg from './spinnable/SpinnableSVG';
 import Timeline from './timeline/Timeline';
@@ -37,5 +38,9 @@ storiesOf('timeline').add('Timeline stagger', () => <TimelineStagger />);
 // Draggable
 storiesOf('draggable').add('Drag XY', () => <DragXY />);
 
+// Spring
+storiesOf('spring').add('Spring', () => <Spring />);
+
+
 // Inertia
 //storiesOf('inertia').add('Throw to inertia', () => <Inertia />);

packages/popmotion-react/stories/popmotion/Spring.js

@@ -0,0 +1,41 @@
+import React from 'react';
+import { spring } from 'popmotion';
+import { MotionValue } from '../../src';
+
+const springProps = {
+  stiffness: 10000,
+  damping: 10,
+  mass: 10,
+  velocity: 1000
+};
+
+export default () => (
+  <MotionValue
+    onStateChange={{
+      on: ({value}) => spring({
+        from: value.get(),
+        to: 300,
+        ...springProps,
+        onUpdate: value
+      }).start(),
+      off: ({value}) => spring({
+        from: value.get(),
+        to: 0,
+        ...springProps,
+        onUpdate: value
+      }).start()
+    }}
+  >
+    {({ v, state, setStateTo }) => (
+      <div
+        style={{
+          background: 'red',
+          width: '100px',
+          height: '100px',
+          transform: 'translateX(' + v + 'px)'
+        }}
+        onClick={state === 'on' ? setStateTo.off : setStateTo.on}
+      />
+    )}
+  </MotionValue>
+);

site/components/examples/Example.js

@@ -28,6 +28,7 @@ import {
   trackOffset,
   tween,
   stagger,
+  spring,
   value,
   Renderer,
   css,
@@ -102,6 +103,7 @@ export default ({ children, template, id, isReactComponent=false }) => {
         pointer,
         trackOffset,
         tween,
+        spring,
         stagger,
         value,
         Renderer,

site/templates/homepage/USPs.js

@@ -70,7 +70,7 @@ export default () => (
       </USP>
       <USP>
         <Header>Tiny</Header>
-        <Description>At ~9kb, it's <Strong>75% smaller</Strong> than Greensock TweenMax. Great for users on slower connections.</Description>
+        <Description>At ~10kb, it's <Strong>75% smaller</Strong> than Greensock TweenMax. Great for users on slower connections.</Description>
       </USP>
       <USP>
         <Header>Blazing Fast</Header>

src/actions/spring.js

@@ -0,0 +1,93 @@
+/*
+  The closed-form damped harmonic oscillating spring.
+  Or, spring.
+
+  This is a direct port of Adam Miskiewicz's (@skevy) React Animated
+  PR #15322 https://github.com/facebook/react-native/pull/15322/
+
+  ```
+  spring({
+    mass: 2,
+    damping: 10,
+    stiffness: 100,
+    to: 100
+  }).start();
+  ```
+
+  Adam Miskiewicz:
+  @skevy (twitter.com/skevy, github.com/skevy)
+ */
+import Action from './';
+import { timeSinceLastFrame } from '../framesync';
+
+class Spring extends Action {
+  static defaultProps = {
+    stiffness: 100,
+    damping: 10,
+    mass: 1.0,
+    velocity: 0.0,
+    from: 0.0,
+    to: 0.0,
+    restSpeed: 0.01,
+    restDisplacement: 0.01
+  };
+
+  onStart() {
+    const { velocity, to } = this.props;
+    this.t = 0;
+    this.initialVelocity = velocity / 1000;
+    this.isComplete = false;
+    this.delta = to - this.from;
+  }
+
+  update() {
+    const { stiffness, damping, mass, from, to, restSpeed, restDisplacement } = this.props;
+    const { delta, initialVelocity } = this;
+
+    const timeDelta = timeSinceLastFrame() / 1000;
+    const t = this.t = this.t + timeDelta;
+
+    const dampingRatio = damping / (2 * Math.sqrt(stiffness * mass));
+    const angularFreq = Math.sqrt(stiffness / mass);
+    const expoDecay = angularFreq * Math.sqrt(Math.abs(1.0 - (dampingRatio * dampingRatio)));
+
+    const x0 = 1;
+    let oscillation = 0.0;
+    let velocity = 0.0;
+
+    // Underdamped
+    if (dampingRatio < 1) {
+      const envelope = Math.exp(-dampingRatio * angularFreq * t);
+      oscillation = envelope * (((initialVelocity + dampingRatio * angularFreq * x0) / expoDecay) * Math.sin(expoDecay * t) + (x0 * Math.cos(expoDecay * t)));
+      velocity = (envelope * ((Math.cos(expoDecay * t) * (initialVelocity + dampingRatio * angularFreq * x0)) - (expoDecay * x0 * Math.sin(expoDecay * t))) -
+        ((dampingRatio * angularFreq * envelope) * ((((Math.sin(expoDecay * t) * (initialVelocity + dampingRatio * angularFreq * x0)) ) / expoDecay) + (x0 * Math.cos(expoDecay * t)))));
+    // Critically damped
+    } else {
+      const envelope = Math.exp(-expoDecay * t);
+      oscillation = envelope * (x0 + (initialVelocity + (expoDecay * x0)) * t);
+      velocity = envelope * ((t * initialVelocity * angularFreq) - (t * x0 * (angularFreq * angularFreq)) + initialVelocity);
+    }
+
+    const fraction = 1 - oscillation;
+    let position = from + fraction * delta;
+
+    // Check if simulation is complete
+    // We do this here instead of `isActionComplete` as it allows us
+    // to clamp to end during update)
+    const isBelowVelocityThreshold = Math.abs(velocity) <= restSpeed;
+    const isBelowDisplacementThreshold = Math.abs(to - position) <= restDisplacement;
+    this.isComplete = isBelowVelocityThreshold && isBelowDisplacementThreshold;
+
+    if (this.isComplete) {
+      position = to;
+    }
+
+    return position;
+  }
+
+  isActionComplete() {
+    return this.isComplete;
+  }
+}
+
+export default (props) => new Spring(props);

src/popmotion.js

@@ -31,6 +31,7 @@ export pointer from './actions/pointer';
 export trackOffset from './actions/track-offset';
 export tween from './actions/tween';
 export stagger from './actions/stagger';
+export spring from './actions/spring';
 export value from './actions/value';
 
 // Renderers