├── .eslintignore ├── .eslintrc.json ├── .gitignore ├── .prettierignore ├── .prettierrc ├── .travis.yml ├── CHANGELOG.md ├── LICENSE ├── README.md ├── demo ├── client.js ├── index.html └── style.css ├── package.json ├── spring.test.js ├── spring.ts ├── tsconfig.json └── webpack.config.js /.eslintignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | -------------------------------------------------------------------------------- /.eslintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "root": true, 3 | "plugins": ["prettier"], 4 | "extends": ["eslint:recommended", "prettier"], 5 | "env": { 6 | "browser": true, 7 | "es6": true, 8 | "node": true 9 | }, 10 | "parser": "babel-eslint", 11 | "parserOptions": { 12 | "ecmaVersion": 6, 13 | "ecmaFeatures": { 14 | "classes": true 15 | }, 16 | "sourceType": "module" 17 | }, 18 | "rules": { 19 | "prettier/prettier": [ 20 | "warn", 21 | { 22 | "endOfLine": "auto", 23 | "singleQuote": true 24 | } 25 | ], 26 | "strict": 0, 27 | "eqeqeq": 1, 28 | "no-console": 1, 29 | "no-irregular-whitespace": 1, 30 | "no-use-before-define": [2, "nofunc"], 31 | "no-unused-vars": [ 32 | 1, 33 | { 34 | "vars": "all", 35 | "args": "after-used", 36 | "argsIgnorePattern": "(^_|^next$)" 37 | } 38 | ], 39 | "arrow-parens": [1, "as-needed"], 40 | "no-dupe-keys": 2, 41 | "no-dupe-args": 2, 42 | "semi": 1 43 | } 44 | } 45 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | node_modules 3 | /spring.js 4 | /spring.d.ts 5 | yarn.lock 6 | package-lock.json -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | package.json -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "singleQuote": true 3 | } 4 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | node_js: 'lts/*' 3 | cache: yarn 4 | install: yarn 5 | script: 6 | - yarn build 7 | - yarn test:ci 8 | deploy: 9 | provider: npm 10 | email: $NPM_EMAIL 11 | api_key: $NPM_TOKEN 12 | on: 13 | branch: master 14 | skip_cleanup: true 15 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## 1.0.0 4 | 5 | - No breaking changes (it seemed about time to properly semver this) 6 | - Adds `onRest` callback 7 | 8 | ## 0.3.2 9 | 10 | - Fixes typos and updates things in README.md 11 | 12 | ## 0.3.1 13 | 14 | - Adds repo field to `package.json` 15 | 16 | ## 0.3.0 17 | 18 | - Fixes fast, consecutive updates animating way too fast 19 | - BREAKING: Inverts the magnitude of `precision`. Larger values now give greater precision. Default is now at `100` (which is more precise in practice than before). To convert old precision values, divide one by the old value: 20 | 21 | ``` 22 | const oldValue = 0.001; 23 | const newValue = 1 / oldValue; // 100 24 | ``` 25 | 26 | ## 0.2.1 27 | 28 | - Fixes missing files! 29 | 30 | ## 0.2.0 31 | 32 | - Refactors from class to function. `new` keyword is no longer necessary. 33 | - Tinier! Now 2kB (600B gzipped), instead 4kB (1kB gzipped). 34 | - Adds typescript definition file. 35 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Asbjørn Hegdahl 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # tiny-spring 2 | 3 | [![npm version](https://img.shields.io/npm/v/tiny-spring)](https://npmjs.com/package/tiny-spring) 4 | ![](https://img.shields.io/badge/dependencies-zero-green) 5 | ![](https://img.shields.io/bundlephobia/min/tiny-spring) 6 | 7 | Simple spring dynamics for physics-driven animations. Also it's tiny (2kB before minification and gzip). 8 | 9 | ``` 10 | npm install tiny-spring 11 | ``` 12 | 13 | This small library helps you interpolate values using [spring dynamics](https://en.wikipedia.org/wiki/Harmonic_oscillator). There's no DOM-stuff or framework specifics included so you can use it with whatever framework or library you want. 14 | 15 | If you're using `React.js`, there is [use-spring-effect](https://www.npmjs.com/package/use-spring-effect) which uses `tiny-spring` internally. 16 | 17 | ## Browser support 18 | 19 | `tiny-spring` uses `requestAnimationFrame`, so if you need to support older browsers make sure you use a polyfill. 20 | 21 | ## TLDR usage 22 | 23 | ```js 24 | import Spring from 'tiny-spring'; 25 | 26 | const spring = Spring(); 27 | const element = document.getElementById('some-id'); 28 | 29 | spring.onUpdate(val => { 30 | element.style.transform = `translateX(${val}px)`; 31 | }); 32 | 33 | // Set value to 50 without animating 34 | spring.setValue(50); 35 | 36 | // Transition from current value (50) to 100 37 | spring.transitionTo(100); 38 | 39 | // Transition again from whatever the current value is to 200 40 | spring.transitionTo(200); 41 | 42 | // Stop animation and remove callback 43 | spring.destroy(); 44 | ``` 45 | 46 | ## API 47 | 48 | ### `Spring(initialValue: number, config: SpringConfig): spring` 49 | 50 | A factory function that returns a new `spring` object. 51 | 52 | ### `SpringConfig (object)` 53 | 54 | **`stiffness: number = 200`** 55 | 56 | Stiffness controls how "fast" your animation will be. Higher values result in faster motion. 57 | 58 | **`damping: number = 10`** 59 | 60 | Damping controls how much friction is applied to the spring. You can think of this as how "wobbly" the resulting motion is. Lower values result in more wobblyness. 61 | 62 | **`precision: number = 100`** 63 | 64 | Used to determine when to stop animating. With a precision of `0` the spring will reach its end value immediately. With really high values it might keep animating fractions of a pixel for a long time. Tweak this value if animations end abruptly or linger for too long. When tweaking this value you'll want to make big changes in order to see an effect (like adding/removing zeros). 65 | 66 | ### `spring (object)` 67 | 68 | **`onUpdate(fn: (value: number): void)`** 69 | 70 | Add a callback which will be called every time the value of the spring changes. 71 | 72 | **NOTE**: `spring` only supports one callback, so calling this method more than once results in previously attached callbacks being overwritten. 73 | 74 | ```js 75 | spring.onUpdate(value => { 76 | /* do something with value */ 77 | }); 78 | ``` 79 | 80 | **`onRest(fn: (value: number): void)`** 81 | 82 | Add a callback which will be called when the spring comes to a rest. 83 | 84 | **NOTE**: `spring` only supports one callback, so calling this method more than once results in previously attached callbacks being overwritten. 85 | 86 | ```js 87 | spring.onRest(value => { 88 | /* do something with value */ 89 | }); 90 | ``` 91 | 92 | **`setValue(value: number)`** 93 | 94 | Set the value of the spring without animating. 95 | 96 | **`transitionTo(value: number)`** 97 | 98 | Start animating to `value` from the current value of the spring. 99 | 100 | **`destroy()`** 101 | 102 | Aborts animation and removes the callback. 103 | -------------------------------------------------------------------------------- /demo/client.js: -------------------------------------------------------------------------------- 1 | import Spring from '../spring.ts'; 2 | 3 | const box = document.getElementById('box'); 4 | const button = document.getElementById('button'); 5 | 6 | const spring = Spring(100); 7 | 8 | spring.onUpdate(val => { 9 | box.style.transform = `translateX(${val}px) rotate(${val / 3}deg)`; 10 | }); 11 | 12 | spring.onRest(() => { 13 | console.log('spring completed!'); 14 | }); 15 | 16 | let value = 0; 17 | button.addEventListener('click', () => { 18 | value = value === 0 ? 300 : 0; 19 | spring.transitionTo(value); 20 | }); 21 | 22 | const box2 = document.getElementById('box2'); 23 | const spring2 = Spring(0, { stiffness: 50 }); 24 | 25 | spring2.onUpdate(val => { 26 | box2.style.transform = `translateX(${val}px)`; 27 | }); 28 | 29 | spring2.onRest(() => { 30 | console.log('spring2 completed!'); 31 | }); 32 | 33 | window.addEventListener('mousemove', e => { 34 | spring2.transitionTo(e.clientX); 35 | }); 36 | -------------------------------------------------------------------------------- /demo/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 8 | tiny-spring demo 9 | 10 | 11 |
12 | 13 |
14 | 15 | 16 | -------------------------------------------------------------------------------- /demo/style.css: -------------------------------------------------------------------------------- 1 | html { 2 | font-family: sans-serif; 3 | } 4 | .box { 5 | height: 200px; 6 | width: 200px; 7 | background-color: salmon; 8 | pointer-events: none; 9 | } 10 | 11 | .demo-wrapper { 12 | overflow: hidden; 13 | background-color: whitesmoke; 14 | height: 500px; 15 | } 16 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "tiny-spring", 3 | "version": "1.0.0", 4 | "description": "Simple spring dynamics for physics-driven animations", 5 | "keywords": [ 6 | "spring", 7 | "animated", 8 | "animation", 9 | "physics", 10 | "spring dynamics" 11 | ], 12 | "author": "Asbjørn Hegdahl", 13 | "repository": { 14 | "type": "git", 15 | "url": "https://github.com/asbjornh/tiny-spring.git" 16 | }, 17 | "license": "MIT", 18 | "main": "./spring.js", 19 | "files": [ 20 | "spring.js", 21 | "spring.d.ts", 22 | "LICENSE", 23 | "README.md" 24 | ], 25 | "scripts": { 26 | "build": "tsc", 27 | "dev": "webpack-dev-server --mode=development", 28 | "test": "yarn build && ava", 29 | "test:ci": "ava" 30 | }, 31 | "dependencies": {}, 32 | "devDependencies": { 33 | "ava": "^2.4.0", 34 | "css-loader": "^2.0.0", 35 | "html-webpack-plugin": "^3.2.0", 36 | "mini-css-extract-plugin": "^0.5.0", 37 | "prettier": "^1.9.2", 38 | "suppress-chunks-webpack-plugin": "^1.0.5", 39 | "ts-loader": "^6.2.1", 40 | "typescript": "^3.6.4", 41 | "webpack": "^4.10.1", 42 | "webpack-cli": "^3.0.2", 43 | "webpack-dev-server": "^3.1.4" 44 | } 45 | } 46 | -------------------------------------------------------------------------------- /spring.test.js: -------------------------------------------------------------------------------- 1 | const test = require('ava'); 2 | 3 | global.requestAnimationFrame = func => setTimeout(func, 16); 4 | global.cancelAnimationFrame = id => clearTimeout(id); 5 | 6 | const packageJson = require('./package.json'); 7 | 8 | // NOTE: Import from built source rather than source 9 | const Spring = require(packageJson.main).default; 10 | 11 | test('Initial value', t => { 12 | let value = 0; 13 | const spring = Spring(100); 14 | spring.onUpdate(v => (value = v)); 15 | t.is(100, value); 16 | }); 17 | 18 | test.cb('Config', t => { 19 | let v1 = 0; 20 | let v2 = 0; 21 | let v3 = 0; 22 | let v4 = 0; 23 | 24 | const s1 = Spring(0); 25 | const s2 = Spring(0, { stiffness: 500 }); 26 | const s3 = Spring(0, { damping: 40 }); 27 | const s4 = Spring(0, { precision: 0.01 }); 28 | 29 | s1.onUpdate(v => (v1 = v)); 30 | s2.onUpdate(v => (v2 = v)); 31 | s3.onUpdate(v => (v3 = v)); 32 | s4.onUpdate(v => (v4 = v)); 33 | 34 | s1.transitionTo(100); 35 | s2.transitionTo(100); 36 | s3.transitionTo(100); 37 | s4.transitionTo(100); 38 | 39 | setTimeout(() => { 40 | t.not(v1, v2); 41 | t.not(v1, v3); 42 | t.not(v1, v4); 43 | t.end(); 44 | }, 500); 45 | }); 46 | 47 | test('setValue', t => { 48 | let value = 0; 49 | const spring = Spring(); 50 | spring.onUpdate(v => (value = v)); 51 | t.is(0, value); 52 | spring.setValue(100); 53 | t.is(100, value); 54 | }); 55 | 56 | test.cb('transitionTo', t => { 57 | let value = 0; 58 | const spring = Spring(); 59 | spring.onUpdate(v => (value = v)); 60 | spring.transitionTo(100); 61 | 62 | setTimeout(() => { 63 | t.is(true, value > 0); 64 | 65 | setTimeout(() => { 66 | t.is(100, value); 67 | t.end(); 68 | }, 2000); 69 | }, 500); 70 | }); 71 | 72 | test.cb('onUpdate', t => { 73 | const spring = Spring(); 74 | const endValue = 100; 75 | let values = []; 76 | spring.onUpdate(v => (values = values.concat(v))); 77 | 78 | spring.transitionTo(endValue); 79 | 80 | // NOTE: 50 values is very arbitrary and might need to be adjusted if tests fail 81 | setTimeout(() => { 82 | t.is(true, values.length > 50); 83 | t.is(true, values.every(v => typeof v === 'number')); 84 | t.not(values[0], values[1]); 85 | t.is(endValue, values.slice(-1)[0]); 86 | t.end(); 87 | }, 2500); 88 | }); 89 | 90 | test.cb('onRest', t => { 91 | const spring = Spring(); 92 | let completed = false; 93 | 94 | spring.onRest(v => (completed = true)); 95 | spring.transitionTo(10); 96 | 97 | setTimeout(() => { 98 | t.is(true, completed); 99 | t.end(); 100 | }, 2000); 101 | }); 102 | -------------------------------------------------------------------------------- /spring.ts: -------------------------------------------------------------------------------- 1 | export default function Spring( 2 | initialPosition = 0, 3 | { stiffness = 200, damping = 10, precision = 100 } = {} 4 | ) { 5 | let position = initialPosition; 6 | let endPosition = 0; 7 | let secPerFrame = 1 / 60; 8 | let velocity = 0; 9 | let onUpdate = v => {}; 10 | let onRest = v => {}; 11 | let raf; 12 | 13 | const interpolate = () => { 14 | const distance = endPosition - position; 15 | const acceleration = stiffness * distance - damping * velocity; 16 | const newVelocity = velocity + acceleration * secPerFrame; 17 | const newPosition = position + newVelocity * secPerFrame; 18 | 19 | const isComplete = 20 | Math.abs(newVelocity) < 1 / precision && 21 | Math.abs(newPosition - endPosition) < 1 / precision; 22 | 23 | position = isComplete ? endPosition : newPosition; 24 | velocity = newVelocity; 25 | onUpdate(position); 26 | 27 | if (!isComplete) raf = requestAnimationFrame(interpolate); 28 | else onRest(position); 29 | }; 30 | 31 | return { 32 | setValue: (v = 0) => { 33 | cancelAnimationFrame(raf); 34 | position = endPosition = v; 35 | onUpdate(position); 36 | }, 37 | transitionTo: (v = 0) => { 38 | cancelAnimationFrame(raf); 39 | endPosition = v; 40 | raf = requestAnimationFrame(interpolate); 41 | }, 42 | onUpdate: (fn = v => {}) => { 43 | onUpdate = fn; 44 | fn(position); 45 | }, 46 | onRest: (fn = v => {}) => { 47 | onRest = fn; 48 | }, 49 | destroy: () => { 50 | cancelAnimationFrame(raf); 51 | onUpdate = () => {}; 52 | onRest = () => {}; 53 | } 54 | }; 55 | } 56 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "files": ["./spring.ts"], 3 | "compilerOptions": { 4 | "declaration": true, 5 | "module": "commonjs" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /webpack.config.js: -------------------------------------------------------------------------------- 1 | /* eslint-env node */ 2 | /* eslint-disable no-console */ 3 | const path = require('path'); 4 | const HtmlPlugin = require('html-webpack-plugin'); 5 | const MiniCssExtractPlugin = require('mini-css-extract-plugin'); 6 | 7 | module.exports = { 8 | devServer: { 9 | inline: true, 10 | stats: 'minimal' 11 | }, 12 | devtool: 'cheap-module-eval-demo-map', 13 | entry: { 14 | style: './demo/style.css', 15 | client: './demo/client.js' 16 | }, 17 | output: { 18 | path: path.resolve('./dist'), 19 | filename: '[name].[chunkhash].js' 20 | }, 21 | module: { 22 | rules: [ 23 | { 24 | test: /\.ts$/, 25 | exclude: /node_modules/, 26 | use: ['ts-loader'] 27 | }, 28 | { 29 | test: /\.css$/, 30 | exclude: /node_modules/, 31 | use: [{ loader: MiniCssExtractPlugin.loader }, 'css-loader'] 32 | } 33 | ] 34 | }, 35 | plugins: [ 36 | new MiniCssExtractPlugin({ filename: '[name].[contenthash].css' }), 37 | new HtmlPlugin({ template: 'demo/index.html' }) 38 | ] 39 | }; 40 | --------------------------------------------------------------------------------