Update documentation

joshwcomeau · Nov 18, 2016 · d54bc16 · d54bc16
1 parent 0cfb268
commit d54bc16
Show file tree

Hide file tree

Showing 4 changed files with 377 additions and 66 deletions.
diff --git a/README.md b/README.md
@@ -74,7 +74,7 @@ UMD builds are also available via CDN:
 
 Flip Move was inspired by Ryan Florence's awesome <a href="https://github.com/ryanflorence/react-magic-move" target="_blank">_Magic Move_</a>, and offers:
 
-  * Full compatibility with React 0.13, 0.14, and 15-rc2. Will be maintained.
+  * Full compatibility with React 0.13, 0.14, and 15. Will be maintained.
 
   * Exclusive use of hardware-accelerated CSS properties (`transform: translate`) instead of positioning properties (`top`, `left`). <a href="https://aerotwist.com/blog/pixels-are-expensive/" target="_blank">_Read why this matters_</a>.
 
@@ -130,73 +130,8 @@ Curious how this works, under the hood? [__Read the Medium post__](https://mediu
 
 ## Enter/Leave Animations
 
-v2.0 introduces Enter/Leave animations. For convenience, several presets are provided:
 
 
-#### Elevator (default)
-
-![Elevator](https://s3.amazonaws.com/githubdocs/fm-elevator.gif)
-
-```js
-<FlipMove enterAnimation="elevator" leaveAnimation="elevator" />
-```
-
-#### Fade
-
-![Fade](https://s3.amazonaws.com/githubdocs/fm-fade.gif)
-
-```js
-<FlipMove enterAnimation="fade" leaveAnimation="fade" />
-```
-
-#### Accordian (Vertical)
-
-![Accordian (Vertical)](https://s3.amazonaws.com/githubdocs/fm-accordian-vertical.gif)
-
-```js
-<FlipMove enterAnimation="accordianVertical" leaveAnimation="accordianVertical" />
-```
-
-#### Accordian (Horizontal)
-
-![Accordian (Horizontal)](https://s3.amazonaws.com/githubdocs/fm-accordian-horizontal.gif)
-
-```js
-<FlipMove enterAnimation="accordianHorizontal" leaveAnimation="accordianHorizontal" />
-```
-
-#### Custom
-
-You can supply your own CSS-based transitions to customize the behaviour. Both `enterAnimation` and `leaveAnimation` take an object with `from` and `to` properties. You can then provide any valid CSS properties to this object, although for performance reasons it is recommended that you stick to `transform` and `opacity`.
-
-![Custom](https://s3.amazonaws.com/githubdocs/fm-custom-rotate-x.gif)
-
-```js
- <FlipMove
-   staggerDelayBy={150}
-   enterAnimation={{
-     from: {
-       transform: 'rotateX(180deg)',
-       opacity: 0.1,
-     },
-     to: {
-       transform: '',
-     },
-   }}
-   leaveAnimation={{
-     from: {
-        transform: '',
-     },
-     to: {
-       transform: 'rotateX(-120deg)',
-       opacity: 0.1,
-     },
-   }}
- >
-   {this.renderRows()}
- </FlipMove>
-```
-
 
 ## Options
 

diff --git a/SUMMARY.md b/SUMMARY.md
@@ -0,0 +1,5 @@
+# Summary
+
+* [API Reference](documentation/api_reference.md)
+* [Enter/Leave Animations](documentation/enter_leave_animations.md)
+
diff --git a/documentation/api_reference.md b/documentation/api_reference.md
@@ -0,0 +1,303 @@
+# API Reference
+
+FlipMove is a React component, and is configured via the following props:
+
+
+
+### `children`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Array`, `Object` | `undefined` |
+
+
+The children passed to FlipMove are the component(s) or DOM element(s) that will be moved about. Accepts either a single child (as long as it has a unique `key` property) or an array of children.
+
+---
+
+### `easing`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `String` | "ease-in-out" |
+
+
+Any valid CSS3 timing function (eg. "linear", "ease-in", "cubic-bezier(1, 0, 0, 1)").
+
+---
+
+### `duration`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Number` | `350` |
+
+
+The length, in milliseconds, that the transition ought to take.
+
+
+---
+
+### `delay`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Number` | `0` |
+
+
+The length, in milliseconds, to wait before the animation begins.
+
+---
+
+### `staggerDurationBy`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Number` | `0` |
+
+
+The length, in milliseconds, to be added to the duration of each subsequent element.
+
+For example, if you are animating 4 elements with a `duration` of 200 and a `staggerDurationBy` of 20:
+
+* The first element will take 200ms to transition.
+* The second element will take 220ms to transition.
+* The third element will take 240ms to transition.
+* The fourth element will take 260ms to transition.
+
+This effect is great for "humanizing" transitions and making them feel less robotic.
+
+---
+
+### `staggerDelayBy`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Number` | `0` |
+
+
+The length, in milliseconds, to be added to the delay of each subsequent element.
+
+For example, if you are animating 4 elements with a `delay` of 0 and a `staggerDelayBy` of 20:
+
+* The first element will start transitioning immediately.
+* The second element will start transitioning after 20ms.
+* The third element will start transitioning after 40ms.
+* The fourth element will start transitioning after 60ms.
+
+Similarly to staggerDurationBy, This effect is great for "humanizing" transitions and making them feel less robotic.
+
+**Protip:** You can make elements animate one-at-a-time by using an identical `duration` and `staggerDelayBy`.
+
+---
+
+### `enterAnimation`
+
+| **Accepted Types:**            | **Default Value** |
+|--------------------------------|-------------------|
+|  `String`, `Boolean`, `Object` | 'elevator'        |
+
+Control the onEnter animation that runs when new items are added to the DOM. For examples of this property, see the <strong><a href="https://github.com/joshwcomeau/react-flip-move#enterleave-animations">feature description above</a></strong>.
+
+Accepts several types:
+
+**String:** You can enter one of the following presets to select that as your enter animation:
+  * `elevator` (default)
+  * `fade`
+  * `accordionVertical`
+  * `accordionHorizontal`
+  * `none`
+
+<a href="https://github.com/joshwcomeau/react-flip-move/blob/master/src/enter-leave-presets.js">View the CSS implementation of these presets.</a>
+
+**Boolean:** You can enter `false` to disable the enter animation, or `true` to select the default enter animation (elevator).
+
+**Object:** For fully granular control, you can pass in an object that contains the styles you'd like to animate.
+
+It requires two keys: `from` and `to`. Each key holds an object of CSS properties. You can supply any valid camelCase CSS properties, and flip-move will transition between the two, over the course of the specified `duration`.
+
+Example:
+
+```js
+const customEnterAnimation = {
+  from: { transform: 'scale(0.5, 1)' },
+  to:   { transform: 'scale(1, 1)' }
+};
+
+<FlipMove enterAnimation={customEnterAnimation}>
+  {renderChildren()}
+</FlipMove>
+```
+
+It is recommended that you stick to hardware-accelerated CSS properties for optimal performance: transform and opacity.
+
+---
+
+### `leaveAnimation`
+
+| **Accepted Types:**            | **Default Value** |
+|--------------------------------|-------------------|
+|  `String`, `Boolean`, `Object` | 'elevator'        |
+
+Control the onLeave animation that runs when new items are removed from the DOM. For examples of this property, see the <strong><a href="https://github.com/joshwcomeau/react-flip-move#enterleave-animations">feature description above</a></strong>.
+
+This property functions identically to `enterAnimation`.
+
+Accepts several types:
+
+**String:** You can enter one of the following presets to select that as your enter animation:
+  * `elevator` (default)
+  * `fade`
+  * `accordionVertical`
+  * `accordionHorizontal`
+  * `none`
+
+<a href="https://github.com/joshwcomeau/react-flip-move/blob/master/src/enter-leave-presets.js">View the CSS implementation of these presets.</a>
+
+**Boolean:** You can enter `false` to disable the leave animation, or `true` to select the default leave animation (elevator).
+
+**Object:** For fully granular control, you can pass in an object that contains the styles you'd like to animate.
+
+It requires two keys: `from` and `to`. Each key holds an object of CSS properties. You can supply any valid camelCase CSS properties, and flip-move will transition between the two, over the course of the specified `duration`.
+
+Example:
+
+```js
+const customLeaveAnimation = {
+  from: { transform: 'scale(1, 1)' },
+  to:   { transform: 'scale(0.5, 1) translateY(-20px)' }
+};
+
+<FlipMove leaveAnimation={customLeaveAnimation}>
+  {renderChildren()}
+</FlipMove>
+```
+
+It is recommended that you stick to hardware-accelerated CSS properties for optimal performance: transform and opacity.
+
+---
+
+### `maintainContainerHeight`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Boolean`          | `false`           |
+
+Do not collapse container height until after leaving animations complete.
+
+When `false`, children are immediately removed from the DOM flow as they animate away. Setting this value to `true` will maintain the height of the container until after their leaving animation completes.
+
+---
+
+### `onStart`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Function`         | `undefined`       |
+
+
+A callback to be invoked **once per child element** at the start of the animation.
+
+The callback is invoked with two arguments:
+
+* `childElement`: A reference to the React Element being animated.
+* `domNode`: A reference to the unadulterated DOM node being animated.
+
+In general, it is advisable to ignore the `domNode` argument and work with the `childElement`. The `domNode` is just an escape hatch for doing complex things not otherwise possible.
+
+---
+
+### `onFinish`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Function`         | `undefined`       |
+
+
+A callback to be invoked **once per child element** at the end of the animation.
+
+The callback is invoked with two arguments:
+
+* `childElement`: A reference to the React Element being animated.
+* `domNode`: A reference to the unadulterated DOM node being animated.
+
+In general, it is advisable to ignore the `domNode` argument and work with the `childElement`. The `domNode` is just an escape hatch for doing complex things not otherwise possible.
+
+---
+
+### `onStartAll`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Function`         | `undefined`       |
+
+
+A callback to be invoked **once per group** at the start of the animation.
+
+The callback is invoked with two arguments:
+
+* `childElements`: An array of the references to the React Element(s) being animated.
+* `domNodes`: An array of the references to the unadulterated DOM node(s) being animated.
+
+These arguments are similar to the ones provided for `onStart`, except we provide an *array* of the elements and nodes. The order of both arguments is guaranteed; this means you can use a zipping function like <a href="https://lodash.com/docs#zip">lodash's .zip</a> to get pairs of element/node, if needed.
+
+In general, it is advisable to ignore the `domNodes` argument and work with the `childElements`. The `domNodes` are just an escape hatch for doing complex things not otherwise possible.
+
+---
+
+### `onFinishAll`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Function`         | `undefined`       |
+
+
+A callback to be invoked **once per group** at the end of the animation.
+
+The callback is invoked with two arguments:
+
+* `childElements`: An array of the references to the React Element(s) being animated.
+* `domNodes`: An array of the references to the unadulterated DOM node(s) being animated.
+
+These arguments are similar to the ones provided for `onFinish`, except we provide an *array* of the elements and nodes. The order of both arguments is guaranteed; this means you can use a zipping function like <a href="https://lodash.com/docs#zip">lodash's .zip</a> to get pairs of element/node, if needed.
+
+In general, it is advisable to ignore the `domNodes` argument and work with the `childElements`. The `domNodes` are just an escape hatch for doing complex things not otherwise possible.
+
+---
+
+### `typeName`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `String`           | 'div'             |
+
+
+Flip Move wraps your children in a container element. By default, this element is a `div`, but you may wish to provide a custom HTML element (for example, if your children are list items, you may wish to set this to `ul`).
+
+Any valid HTML element type is accepted, but peculiar things may happen if you use an unconventional element.
+
+---
+
+### `disableAllAnimations`
+
+| **Accepted Types:** | **Default Value** |
+|---------------------|-------------------|
+|  `Boolean`          | `false`           |
+
+
+Sometimes, you may wish to temporarily disable the animations and have the normal behaviour resumed. Setting this flag to `true` skips all animations.
+
+---
+
+### `getPosition`
+
+| **Accepted Types:** | **Default Value**       |
+|---------------------|-------------------------|
+|  `Function`         | `getBoundingClientRect` |
+
+
+This function is called with a DOM node as the only argument. It should return an object as specified by the [getBoundingClientRect() spec](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+
+For normal usage of FlipMove you won't need this. An example of usage is when FlipMove is used in a container that is scaled using CSS. You can correct the values from `getBoundingClientRect` by using this prop.
+
+---