docs: useDynamicAnimation; mention Reanimated 2 version upgrade

docs/docs/api/use-dynamic-animation.md

@@ -0,0 +1,156 @@
+---
+id: use-dynamic-animation
+title: useDynamicAnimation
+sidebar_label: useDynamicAnimation
+---
+
+`useDynamicAnimation` is a hook that lets you use style objects dynamically, rather than using static variants.
+
+## `useDynamicAnimation(initialState?)`
+
+```tsx
+const animation = useDynamicAnimation(() => {
+  // optional function that returns your initial style
+  return {
+    height: 100,
+  }
+})
+
+const onLayout = ({ nativeEvent }) => {
+  animation.animateTo({
+    ...animation.current,
+    height: nativeEvent.layout.height,
+  })
+}
+
+// pass the animation to state of any Moti component
+return <MotiView state={animation} />
+```
+
+### Benefits
+
+- High performance
+- Zero re-renders
+- Animations run on the native thread
+- Easy API
+
+## Arguments
+
+Receives one (optional) argument: a pure function which returns the initial state. This is similar to React's `useState`.
+
+```ts
+const animation = useDynamicAnimation(() => {
+  // this is your initial state
+  return {
+    height: 100,
+  }
+})
+```
+
+## Returns
+
+### `current`
+
+Get the current animation state. Unlike `useState`'s return value, this can be safely read and accessed asynchronously.
+
+```ts
+const animation = useDynamicAnimation(() => {
+  // this is your initial state
+  return {
+    height: 100,
+  }
+})
+
+const onPress = () => {
+  console.log(animation.current) // { height: 100 }
+}
+```
+
+### `animateTo(next)`
+
+A function to animate to your next state. This is a worklet, so you can call it from the native thread.
+
+```ts
+const animation = useDynamicAnimation(() => {
+  return {
+    height: 100,
+  }
+})
+
+const onPress = () => {
+  animation.animateTo({ height: 200 })
+}
+```
+
+You can also pass a function which receives the current style and returns the next state:
+
+```ts
+const animation = useDynamicAnimation(() => {
+  return {
+    height: 100,
+    width: 100,
+  }
+})
+
+const onPress = () => {
+  animation.animateTo((current) => ({ ...current, height: 200 }))
+
+  // or, you could do this! they're the same
+  animation.animateTo({
+    ...animation.current,
+    height: 200,
+  })
+}
+```
+
+### Do not destructure
+
+```ts
+// 😡 don't do this
+const { current, animateTo } = useDynamicAnimation()
+
+// ✅ do this!
+const animation = useDynamicAnimation()
+```
+
+## Full example: Touchable pulse
+
+```tsx
+import React from 'react'
+import { MotiView, useDynamicAnimation } from 'moti'
+import {
+  TapGestureHandler,
+  TapGestureHandlerGestureEvent,
+} from 'react-native-gesture-handler'
+import { useAnimatedGestureHandler } from 'react-native-reanimated'
+
+export default function HoverPulse({
+  scaleTo = 1.05,
+  style,
+  children,
+  ...props
+}) {
+  const animation = useDynamicAnimation(() => ({
+    scale: 1,
+  }))
+
+  const onGestureEvent = useAnimatedGestureHandler<TapGestureHandlerGestureEvent>(
+    {
+      onStart: () => {
+        animation.animateTo({ scale: scaleTo })
+      },
+      onFinish: () => {
+        animation.animateTo({ scale: 1 })
+      },
+    }
+  )
+
+  return (
+    <TapGestureHandler onGestureEvent={onGestureEvent}>
+      <MotiView style={style} state={animation}>
+        {children}
+      </MotiView>
+    </TapGestureHandler>
+  )
+}
+```

docs/docs/installation.md

@@ -21,13 +21,17 @@ npm install moti
 
 ## Install Reanimated 2
 
-Moti requires that you install `react-native-reanimated`. The minimum version of Reanimated it's been tested on is `2.0.0-rc.0`.
+Moti requires that you install `react-native-reanimated`.
+
+Moti `0.8.x` and higher requires at least Reanimated v2 stable (`2.0.0` or higher). This version is compatible with Expo starting SDK 41.
+
+If you haven't upgraded Reanimated past `2.0.0-rc.0`, you can also use Moti `0.7.x`. However, I recommend upgrading to get the latest features/fixes.
 
 ### If you're using Expo
 
 Please follow the [Expo instructions](https://docs.expo.io/versions/latest/sdk/reanimated/#experimental-support-for-v2) for installing `react-native-reanimated` v2.
 
-You'll need at least [Expo SDK 40](https://docs.expo.io/workflow/upgrading-expo-sdk-walkthrough/).
+You'll need at least [Expo SDK 40](https://docs.expo.io/workflow/upgrading-expo-sdk-walkthrough/), but I recommend using SDK 41.
 
 ### If you aren't using Expo
 
@@ -43,7 +47,7 @@ Please see the following guides:
 
 ## Hermes/Android Support
 
-Moti uses `Proxy` under the hood, which is not supported on older versions of Hermes (see [hermes#33](https://github.com/facebook/hermes/issues/33)).
+Moti uses `Proxy` under the hood, which is not supported on older versions of Hermes (see [hermes#33](https://github.com/facebook/hermes/issues/33)). Follow the steps below if you're using Hermes.
 
 ### If you're using React Native 0.63.x
 
@@ -67,8 +71,6 @@ As mentioned in this [Moti issue](https://github.com/nandorojo/moti/issues/13),
 Property 'Proxy' doesn't exist, js engine: hermes [Mon Feb 08 2021 19:21:54.427] ERROR Invariant Violation: Module AppRegistry is not a registered callable module (calling runApplication), js engine: hermes
 ```
 
-If you see this, you haven't correctly installed the right version of Hermes, so please confirm that.
-
 ## Using inline requires
 
 If you're using [Inline Requires](https://instagram-engineering.com/making-instagram-com-faster-code-size-and-execution-optimizations-part-4-57668be796a8), you might need to import `react-native-reanimated` in the root of your app before using any Moti code.