From 7b9e66c07763808e782e6f057a47ba09a1943ab1 Mon Sep 17 00:00:00 2001 From: Paul Henschel Date: Sun, 8 Apr 2018 21:15:19 +0200 Subject: [PATCH] document new api --- API.md | 19 ++++++-- package.json | 2 +- readme.md | 80 +++++++++++++++++++++----------- src/animated/AnimatedTracking.js | 1 - 4 files changed, 69 insertions(+), 33 deletions(-) diff --git a/API.md b/API.md index bce4ae60da..e3bdb12ba6 100644 --- a/API.md +++ b/API.md @@ -33,12 +33,16 @@ class Spring extends React.PureComponent { to: PropTypes.oneOfType([PropTypes.object, PropTypes.func]), // Callback when the animation comes to a still-stand onRest: PropTypes.func, + // Frame by frame callback, first argument passed is the animated value + onFrame: PropTypes.func, // Takes a function that receives interpolated styles children: PropTypes.func, // Same as children, but takes precedence if present render: PropTypes.func, // Prevents animation if true, you can also pass individual keys immediate: PropTypes.oneOfType([PropTypes.bool, PropTypes.arrayOf(PropTypes.string)]), + // When true it literally resets: from -> to + reset: PropTypes.bool, } static defaultProps = { from: {}, to: {}, config: config.default, native: false, immediate: false } } @@ -56,17 +60,26 @@ class Transition extends React.PureComponent { native: PropTypes.bool, config: PropTypes.object, // Base styles - from: PropTypes.object, + from: PropTypes.oneOfType([PropTypes.object, PropTypes.func]), // Animated styles when the component is mounted - enter: PropTypes.object, + enter: PropTypes.oneOfType([PropTypes.object, PropTypes.func]), // Unmpount styles - leave: PropTypes.object, + leave: PropTypes.oneOfType([PropTypes.object, PropTypes.func]), + // + update: PropTypes.oneOfType([PropTypes.object, PropTypes.func]), // A collectiomn of unique keys that must match with the childrens order // Can be omitted if children/render aren't an array + // Can be a function, which then acts as a key-accessor which is useful when you use the items prop keys: PropTypes.oneOfType([ + PropTypes.func, PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.string, PropTypes.number])), PropTypes.oneOfType([PropTypes.string, PropTypes.number]), ]), + // Optional. Let items refer to the actual data and from/enter/leaver/update can return per-object styles + items: PropTypes.oneOfType([ + PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.object])), + PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.object]), + ]), children: PropTypes.oneOfType([PropTypes.arrayOf(PropTypes.func), PropTypes.func]), render: PropTypes.oneOfType([PropTypes.arrayOf(PropTypes.func), PropTypes.func]), } diff --git a/package.json b/package.json index 8018d58b5b..6d2e95cfb1 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "react-spring", - "version": "4.0.0", + "version": "4.0.1", "description": "Animate React with ease", "main": "dist/react-spring", "module": "dist/react-spring.es", diff --git a/readme.md b/readme.md index 96cf44d657..03ac1a0448 100644 --- a/readme.md +++ b/readme.md @@ -5,26 +5,27 @@ npm install react-spring # Table of Contents 👇 -* [Installation](#installation-) -* [Why](#why-) -* [Overview](#overview-) -* [API Overview](#api-overview-) - * [Springs and Interpolation](#springs-and-interpolation) - * [Render Props](#render-props) - * [Native rendering](#native-rendering-demo) - * [Transitions](#transitions) - * [Parallax and page transitions](#parallax-and-page-transitions) -* [License](#license-) + +* [Installation](#installation-) +* [Why](#why-) +* [Overview](#overview-) +* [API Overview](#api-overview-) + * [Springs and Interpolation](#springs-and-interpolation) + * [Render Props](#render-props) + * [Native rendering](#native-rendering-demo) + * [Transitions](#transitions) + * [Parallax and page transitions](#parallax-and-page-transitions) +* [License](#license-) # Why 🤔 react-spring is a cooked down fork of Christopher Chedeau's [animated](https://github.com/animatedjs/animated) (which is used in react-native by default). It is trying to bridge it with Cheng Lou's [react-motion](https://github.com/chenglou/react-motion). Although both are similar in that they are spring-physics based, they have their pros and cons and could definitively benefit from one another: -| | Declarative | Primitives | Interpolations | Performance | -|----------------|-------------|----------------|----------------|-------------| -| React-motion   | ✅ | ✅ | ❌ | ❌ -| Animated       | ❌ | ❌ | ✅ | ✅ -| React-spring   | ✅ | ✅ | ✅ | ✅ +| | Declarative | Primitives | Interpolations | Performance | +| -------------- | ----------- | ---------- | -------------- | ----------- | +| React-motion   | ✅ | ✅ | ❌ | ❌ | +| Animated       | ❌ | ❌ | ✅ | ✅ | +| React-spring   | ✅ | ✅ | ✅ | ✅ | react-spring inherits react-motions api (and simplifies it), has lots of primitives (springs, trails, transitions, reveals, parallax), can interpolate mostly everything (colors, gradients, percentages, degrees, svg-paths, arrays, etc.) and last but not least, can animate by committing directly to the dom instead of re-rendering a component frame-by-frame. @@ -76,10 +77,7 @@ A `Spring` will move data from one state to another. It remembers the current st Given a single child instead of a list you can reveal components with it. ```jsx - + {toggle ? ComponentA : ComponentB} ``` @@ -100,8 +98,12 @@ Given a single child instead of a list you can reveal components with it. ```jsx - first Page - second Page + + first Page + + + second Page + ``` @@ -127,6 +129,8 @@ You can interpolate almost everything, from numbers, colors, svg-paths, percenta }}> ``` +A couple of extra props you might be interested in are `onRest`, which fires once the animations stops, `onFrame`, which fires on every frame and gives you the animation value, `reset`, which literally resets the spring so that it goes through `from` to `to` again, `immediate` which can enforce values to spring to their to-values immediatelly (can be `true` for a zero-time spring or an array where you can pass the key-names individually). + ### Render props Don't like the way render props wrap your code? @@ -142,7 +146,6 @@ const Header = ({ children, bold, ...styles }) => ( hello there - ``` Et voilà! `Header` animates on prop changes! Props that `Spring` doesn't recognize will be spread over the receiving component, in this example `bold`, but it also includes `children` if you use `render` to refer to the render-child. @@ -153,7 +156,7 @@ By default we'll render the receiving component every frame as it gives you more Just be aware of the following conditions: -1. It only animates element styles and attributes, the values you receive *are opaque objects, not regular values* +1. It only animates element styles and attributes, the values you receive _are opaque objects, not regular values_ 2. Receiving elements must be `animated.[elementName]`, for instance `div` becomes `animated.div` 3. If you need to interpolate styles use the `template` string literal @@ -169,6 +172,16 @@ import { Spring, animated, template } from 'react-spring' ``` +You have several interpolation options, not just `template`. `interpolate` can be called on the value itself or as a stand-alone function which can read multiple values. It accepts either a function which receives the animation value(/s), or a range. + +```jsx +import { Spring, animated, interpolate } from 'react-spring' + + `translate(${x}px, ${y}px)`), color: time.interpolate({ inputRange: [0, 1], outputRange: ['red', rgba(1, 50, 210, 0.5)] }) }}> + + +``` + ### Transitions Animates children as they mount and unmount. `from` denotes base styles, `enter` styles are applied when objects appear, `leave` styles are applied when objects disappear. Keys and children have to match in their order! The keys are the same that you would provide in any other looping situation. @@ -190,14 +203,25 @@ import { Transition } from 'react-spring' You can use this prototype for two-state reveals, simply render a single child that you can switch out for another. You don't have to pass keys for this one. ```jsx - + {toggle ? ComponentA : ComponentB} ``` +For more complex animations you can return per-object styles individually. Let Transition know the actual data by passing it raw to `items`, either pass your keys like always or give it an accessor. And for more control, there's `update` which fires for nodes that are neither entering nor leaving. + +```jsx + item.key} + from={item => ({ opacity: 0 })} + enter={item => ({ opacity: 1 })} + update={item => ({ opacity: 0.5 })} + leave={item => ({ opacity: 0 })}> + {items.map(item => styles =>
  • {item.text}
    • )} +     +``` + ### Trails/Staggered transitions `Trail` animates the first child of the list you pass, the others will follow in a trailing motion. The api is similar to `Transition` though it will assume your list is fixed. @@ -230,8 +254,8 @@ import { Parallax } from 'react-spring' # Links 🔗 - [API](https://github.com/drcmda/react-spring/blob/master/API.md) | [Changelog](https://github.com/drcmda/react-spring/blob/master/CHANGELOG.md) # License ⚖ + ### [MIT](https://github.com/drcmda/react-spring/blob/master/LICENSE) diff --git a/src/animated/AnimatedTracking.js b/src/animated/AnimatedTracking.js index f5892a452e..68a9f2272d 100644 --- a/src/animated/AnimatedTracking.js +++ b/src/animated/AnimatedTracking.js @@ -1,5 +1,4 @@ import Animated from './Animated' -import AnimatedValue from './AnimatedValue' export default class AnimatedTracking extends Animated { constructor(value, parent, animationClass, animationConfig, callback) {