add readme

Author: pinyin

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Robert Bao
+Copyright (c) 2018 Robert Bao (https://github.com/pinyin)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,2 +1,111 @@
 # tween-here
-The animation library to use when you don't want to bother about animations.
+
+The animation library to use when you don't really care about animations.
+
+------
+
+### Install
+
+`npm install --save @pinyin/tween-here`
+
+It should support typescript out of the box. If not, please submit an issue.
+
+### Usage
+
+```typescript jsx
+import {tweenHere, tweenExit, getTweenState} from '@pinyin/tween-here'
+
+// Get a reference to the animation target 
+// For React, you may want to use refs(https://reactjs.org/docs/refs-and-the-dom.html)
+const element: Element = document.getElementById("")
+
+// Make it fade in smoothly
+// For React, this line may be placed in componentDidMount()
+tweenHere(element, snapshot=> ({...snapshot, opacity: 0}))
+
+// Tweening from one place to another
+// 1. snapshot current position before element is moved
+// For React, this line may be in componentWillUpdate() or getSnapshotBeforeUpdate()
+const snapshot = getTweenState(element)
+// 2. when element is moved, call tweenHere on the snapshot
+tweenHere(element, snapshot)
+
+// When this element is detached from dom, make it fade out instead of suddenly disappear.
+// For React, this may appear in componentWillUpdate(), getSnapshotBeforeUpdate() or componentWillUnmount()
+// Yes, you can specify a component's unmount animation inside the component itself.
+tweenExit(element, snapshot=>({...snapshot, opacity: 0}))
+
+```
+
+Demo is planned. For now, please refer to this [InfiniteList component demo](http://pinyin.github.io/InfiniteMasonry/InfiniteMasonry.html) to see this library in action. 
+
+All animations in the current demo are implemented with this library.
+
+### Design Targets
+
+[Motions are important](https://material.io/guidelines/motion/material-motion.html#material-motion-why-does-motion-matter).
+
+But they are hard to implement.
+
+We've had many web animation solutions that are both precise and powerful, like [Popmotion](https://popmotion.io/) and [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) and may other awesome ones, but sometimes, even these precise solutions seem to be a little too much for the simple use case.
+
+> Just make this element appear smoothly, please. It should be simple.
+
+That's what `tween-here` is designed for. 
+
+
+### APIs
+
+The document is not complete yet. Any contributions are welcome.
+
+`tween-here` comes with two functions, `tweenHere` and `tweenExit`, each function provides a fast way to implement a kind of motions. 
+
+```typescript jsx
+async function tweenHere(
+    element: HTMLElement,
+    from: Maybe<TweenState> | ((snapshot: TweenState, to: TweenState) => Maybe<TweenState>) = nothing,
+    duration: ms | ((from: TweenState, to: TweenState) => ms) = 200,
+    easing: CubicBezierParam = [0, 0, 1, 1]
+): Promise<void> 
+
+async function tweenExit(
+    element: HTMLElement,
+    to: Maybe<TweenState> | ((from: TweenState) => Maybe<TweenState>) = nothing,
+    duration: ms | ((from: TweenState, to: TweenState) => ms) = 200,
+    easing: CubicBezierParam = [0, 0, 1, 1]
+): Promise<void> 
+```
+
+In general, use `tweenHere` when you want a element to move smoothly, use `tweenExit` when you know an element is being detached from `document` and what it to disappear smoothly.
+
+TweenState is an object representing the position of an element (relative to viewport):
+```typescript jsx
+type TweenState = {
+    x: number
+    y: number
+    width: number
+    height: number
+    opacity: number
+} 
+```
+In practise, you may get these numbers from `getBoundingClientRect()` and many other native APIs. 
+
+For convenience, this library provides two helper functions, `getTweenState` and `getOriginalTweenState`, to capture the `TweenState` from an existing element. 
+
+```typescript jsx
+getTweenState(element: HTMLElement): TweenState
+getOriginalTweenState(element: HTMLElement): TweenState
+```
+
+By using these helper functions and `tweenHere`, you can easily make an element tween smoothly from the position of another element, constructing an visual effect of they are the same element.
+
+
+### Notice
+
+This library is very unstable yet, any contributions(code, issue, use cases proposal...) are welcome.
+
+### License
+
+MIT
+
+

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinyin/tween-here",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "The animation library to use when you don't want to bother about animations.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/index.ts

@@ -1,3 +1,4 @@
+export {getOriginalTweenState} from './getOriginalTweenState'
 export {getTweenState} from './getTweenState'
 export {tweenEnd} from './tweenEnd'
 export {tweenHere} from './tweenHere'