Add previously undocumented useReanimatedAnimationBuilder hook doc (#…

…237)

* added new useReanimatedAnimationBuilder

* Update AnimatedContainer  props

* Fix typo

* touch-up wording and links

* Add links

packages/animations/docs/components/AnimatedContainer.md

@@ -21,7 +21,7 @@ import { AnimatedContainer } from '@react-native-ama/animations';
 />;
 ```
 
-When the component is mounted, it will animate it from: `from -> to`, and when it is unmounted, it will animate it from: `exitFrom -> to`.
+When the component is mounted, it will animate it from: `from -> to`, and when it is unmounted, it will animate it from: `exitFrom -> exitTo`.
 If the property `exitFrom from` is not specified, it will then play the animation in reverse: `to -> from`.
 
 ## Accessibility
@@ -30,6 +30,8 @@ For both, enter and exitFrom animation, the component will use a `duration={0}`
 
 ## Props
 
+Props extend the [`UseReanimatedAnimationBuilder`](../hooks/useReanimatedAnimationBuilder.md) props.
+
 ### `autofocus`
 
 If set to true, wraps the child inside the [AutofocusContainer](./AutofocusContainer)
@@ -61,7 +63,7 @@ The initial value of the animation.
 | ViewStyle \| ReanimatedEntryValues |
 
 This parameter sets the initial values for the [Reanimated custom animations](https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/custom-animations).
-In additional to `ViewStyle`, this property also allows access to special values available by Reanimated:
+In additional to `ViewStyle`, this property also allows access to special [values](https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/custom-animations/#arguments-1) available by Reanimated:
 
 | Value               | Description                                                   |
 | ------------------- | ------------------------------------------------------------- |
@@ -112,7 +114,7 @@ The initial value for the unmounting animation.
 | --------------------------------- |
 | ViewStyle \| ReanimatedExitValues |
 
-In additional to `ViewStyle` this property also allows to access to special values available by Reanimated:
+In additional to `ViewStyle` this property also allows to access to special [values](https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/custom-animations/#arguments) available by Reanimated:
 
 | Value                | Description                                                   |
 | -------------------- | ------------------------------------------------------------- |

packages/animations/docs/hooks/useReanimatedAnimationBuilder.md

@@ -0,0 +1,123 @@
+import { Required } from '@site/src/components'
+
+# useReanimatedAnimationBuilder
+
+A hook distilling [Reanimated custom animations](https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/custom-animations) functionality
+to animate the entry and exiting of an Animated components, honouring
+the [Reduce Motion](https://reactnative.dev/docs/accessibilityinfo) preference.
+
+## Usage
+
+```jsx
+import { useReanimatedAnimationBuilder } from '@react-native-ama/animations';
+
+const Example = () => {
+  const { entering, exiting } = useReanimatedAnimationBuilder({
+    from: { transform: [{ translateY: 'targetHeight' }] },
+    to: { transform: [{ translateY: 0 }] },
+    exitFrom: { transform: [{ translateY: 'currentHeight' }] },
+    exitTo,
+    duration: 300,
+  });
+
+  return (
+    <Animated.Text entering={entering} exiting={exiting}>
+      Text
+    </Animated.Text>
+  );
+};
+```
+
+When the hook is mounted, it will animate entering: `from -> to`, and when it is unmounted, it will animate exiting: `exitFrom -> exitTo`.
+If the property `exitFrom` is not specified, it will then play the animation in reverse: `to -> from`.
+
+## Accessibility
+
+For both, `from` and `exitFrom` starting animation, the hook will use a `duration={0}` for each [motion property](../utils/isMotionAnimation) when [Reduce Motion](../hooks/useAMAContext#isreducemotionenabled) option is enabled.
+
+## Props
+
+### <Required /> `duration`
+
+The preferred animation duration.
+
+| Type   | Default   |
+| ------ | --------- |
+| number | undefined |
+
+:::note
+
+The hook will use a `duration={0}` for each [motion property](../utils/isMotionAnimation) when [Reduce Motion](../hooks/useAMAContext#isreducemotionenabled) option is enabled.
+
+:::
+
+### <Required /> `from`
+
+The initial value of the animation.
+
+| Type                               |
+| ---------------------------------- |
+| ViewStyle \| ReanimatedEntryValues |
+
+This parameter sets the initial values for the [Reanimated custom animations](https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/custom-animations).
+In additional to `ViewStyle`, this property also allows access to special [values](https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/custom-animations/#arguments-1) available by Reanimated:
+
+| Value               | Description                                                   |
+| ------------------- | ------------------------------------------------------------- |
+| targetOriginX       | X coordinate of top left corner in parent's coordinate system |
+| targetOriginY       | Y coordinate of top left corner in parent's coordinate system |
+| targetWidth         | view's width                                                  |
+| targetHeight        | view's height                                                 |
+| targetGlobalOriginX | X coordinate of top left corner in global coordinate system   |
+| targetGlobalOriginY | Y coordinate of top left corner in global coordinate system   |
+
+### <Required /> `to`
+
+The final (or initial) value of the animation.
+
+| Type      |
+| --------- |
+| ViewStyle |
+
+This value is used for both entering and exiting animation.
+For the entering animation, this is used as the final state; for the exitFrom one, as the initial state.
+
+### `exitFrom`
+
+The initial value for the unmounting animation.
+
+| Type                              |
+| --------------------------------- |
+| ViewStyle \| ReanimatedExitValues |
+
+In additional to `ViewStyle` this property also allows to access to special [values](https://docs.swmansion.com/react-native-reanimated/docs/layout-animations/custom-animations/#arguments) available by Reanimated:
+
+| Value                | Description                                                   |
+| -------------------- | ------------------------------------------------------------- |
+| currentOriginX       | X coordinate of top left corner in parent's coordinate system |
+| currentOriginY       | Y coordinate of top left corner in parent's coordinate system |
+| currentWidth         | view's width                                                  |
+| currentHeight        | view's height                                                 |
+| currentGlobalOriginX | X coordinate of top left corner in global coordinate system   |
+| currentGlobalOriginY | Y coordinate of top left corner in global coordinate system   |
+
+Because in the [from](#from) animation, we did specify the special value **targetHeight** we need to provide a "different" value for the exiting animation
+as that special name does not exist for the exitFrom animation.
+
+:::note
+
+If not specified, the [from](#from) value is used as the final one for the unmounting animation.
+
+:::
+
+### `exitTo`
+
+The final value for the unmounting animation.
+
+| Type      |
+| --------- |
+| ViewStyle |
+
+## Related guidelines
+
+- [Animations](/guidelines/animations)

packages/animations/src/hooks/useReanimatedAnimationBuilder.ts

@@ -114,7 +114,7 @@ type ReanimatedStyle<K> = {
 } & {
   transform?:
     | (
-        | PerpectiveTransform<K>
+        | PerspectiveTransform<K>
         | RotateTransform<K>
         | RotateXTransform<K>
         | RotateYTransform<K>
@@ -131,7 +131,7 @@ type ReanimatedStyle<K> = {
     | undefined;
 };
 
-type PerpectiveTransform<K> = {
+type PerspectiveTransform<K> = {
   c: string | K;
 };