Change API, add an ability to pause transition, small enhancements

README.md

@@ -2,37 +2,54 @@
 
 # utransition
 
-A tiny library providing you an easy way to manage time-based transitions.
+A tiny (~2KB) library providing you an easy way to manage time-based transitions. You just set prefered duration and easing and then specify how things should change basing on transition progress. For example, you can write small wrapper around this library that allows you to animate page scroll dynamically.
+
+utransition is available via npm:
+
+```bash
+$ npm install utransition
+```
 
 ## Usage
 
 ```javascript
 import utransition from 'utransition';
 
 const transition = utransition(200, requestAnimationFrame);
+let wasPaused = false;
 
-transition.onStart = function () {
+transition.onStart = () => {
 	console.log('transition started');
 };
 
-transition.onProgress = function (easedProgress, linearProgress) {
-	console.log(`eased progress: ${easedProgress}`);
-	console.log(`linear progress: ${linearProgress}`);
+transition.onProgress = () => {
+	console.log(`eased progress: ${transition.easedProgress}`);
+	console.log(`linear progress: ${transition.linearProgress}`);
 
-	if (linearProgress > 0.5) {
+	if (linearProgress > 0.4 && !wasPaused) {
+		transition.pause();
+	} else if (wasPaused && linearProgress > 0.6) {
 		transition.abort();
 	}
 }
 
-transition.onEnd = function () {
-	console.log('transition finished');
-}
+transition.onPause = () => {
+	console.log('transition paused');
+};
+
+transition.onResume = () => {
+	console.log('transition resumed');
+};
 
-transition.onAbort = function () {
+transition.onAbort = () => {
 	console.log('transition aborted');
 }
 
-transition.start();
+transition.onEnd = () => {
+	console.log('transition finished');
+}
+
+transition.play();
 ```
 
 ## API
@@ -65,85 +82,166 @@ Timer like `window.requestAnimationFrame`.
 Type: `Function`<br />
 Default: linear `(progress) => progress`
 
-Custom easing function.
+Custom easing function that takes linear progress in range from 0 to 1 and should return eased progress.
 
 ### transition object
 
 Created by `utransition` call:
 
 ```javascript
 const transition = utransition(200, requestAnimationFrame);
+
+// API:
+transition === {
+	play() {},
+	pause() {},
+	abort() {},
+
+	onStart() {},
+	onPause() {},
+	onResume() {},
+	onAbort() {},
+	onEnd() {},
+
+	state: Enumerable['stopped', 'in progress', 'paused'],
+	easedProgress: Number,
+	linearProgress: Number,
+};
 ```
 
-#### transition.start
+All callbacks are invoked in the `transition` context, so you can
+do things like `this.abort()` inside callbacks.
 
-Type: `Function`
+#### transition.state
+
+Type: `String`<br />
+Overridable: `false`
+
+Current transition state. One of `stopped`, `paused`, `in progress`.
+
+#### transition.linearProgress
+
+Type: `Number`<br />
+Overridable: `false`
+
+Current linear progress.
+
+#### transition.easedProgress
+
+Type: `Number`<br />
+Overridable: `false`
+
+Current eased progress.
+
+#### transition.play()
+
+Type: `Function`<br />
+Overridable: `false`
+
+Starts or resumes transition.
+
+#### transition.pause()
+
+Type: `Function`<br />
+Overridable: `false`
+
+Pauses transition.
+
+#### transition.abort()
+
+Type: `Function`<br />
+Overridable: `false`
+
+Aborts transition.
+
+#### transition.onStart
+
+Type: `Function`<br />
+Overridable: `true`<br />
+Context: `transition`
 
-Starts transition. You can't override this method:
+Called when transition starts. Usage:
 
 ```javascript
 const transition = utransition(...);
-transition.start = () => {}; // will have no effect
+transition.onStart = () => {
+	console.log('transition started');
+};
 ```
 
-#### transition.abort
+#### transition.onPause
 
-Type: `Function`
+Type: `Function`<br />
+Overridable: `true`<br />
+Context: `transition`
 
-Aborts transition. Not overridable.
+Called when transition pauses. Usage:
 
-#### transition.onStart
+```javascript
+const transition = utransition(...);
+transition.onPause = () => {
+	console.log('transition paused');
+};
+```
+
+#### transition.onResume
 
 Type: `Function`<br />
+Overridable: `true`<br />
 Context: `transition`
 
-Called when transition starts. Usage:
+Called when transition resumes. Usage:
 
 ```javascript
 const transition = utransition(...);
-transition.onStart = function () {
-	transition.abort(); // or this.abort()
-}
+transition.onResume = () => {
+	console.log('transition resumed');
+};
 ```
 
-#### transition.onProgress
+#### transition.onAbort
 
-Type: `Function`
-Arguments: `Number` easedProgress, `Number` linearProgress
+Type: `Function`<br />
+Overridable: `true`<br />
+Context: `transition`
 
-Called on every timer tick. Usage:
+Called when transition aborts. Usage:
 
 ```javascript
 const transition = utransition(...);
-transition.onProgress = function (easedProgress, linearProgress) {
-	if (linearProgress > 0.5) {
-		transition.abort();
-	}
+transition.onAbort = () => {
+	console.log('transition aborted');
 }
 ```
 
-#### transition.onEnd
+#### transition.onProgress
 
-Type: `Function`
+Type: `Function`<br />
+Overridable: `true`<br />
+Context: `transition`
 
-Called when transition ends. Usage:
+Called on every timer tick except first tick after start or resume. Usage:
 
 ```javascript
 const transition = utransition(...);
-transition.onEnd = function () {
-	console.log('transition finished!');
+transition.onProgress = () => {
+	if (transition.linearProgress > 0.5) {
+		transition.abort();
+	}
 }
 ```
 
-#### transition.onAbort
+#### transition.onEnd
 
-Type: `Function`
+Type: `Function`<br />
+Overridable: `true`<br />
+Context: `transition`
 
-Called when transition aborts by calling `transition.abort()`. Usage:
+Called when transition ends. Usage:
 
 ```javascript
 const transition = utransition(...);
-transition.onAbort = function () {
-	console.log('transition aborted!');
+transition.onEnd = () => {
+	console.log('transition finished!');
 }
 ```

package.json

@@ -1,7 +1,7 @@
 {
   "name": "utransition",
-  "version": "1.0.1",
-  "main": "build/utransition-1.0.1.js",
+  "version": "2.0.0",
+  "main": "build/utransition-2.0.0.js",
   "author": "Andrew Romanov <me@andrew-r.ru>",
   "license": "MIT",
   "scripts": {