Add setNativeProps docs (#5044)

# Motivation

This PR documents the new `setNativeProps` function added in
#4595


https://github.com/software-mansion/react-native-reanimated/assets/39658211/32ab57fa-37a5-4e3e-abfb-2afdf1a99157

# Testing

```sh
cd docs
yarn
yarn start
```

docs/docs/advanced/dispatchCommand.mdx

@@ -1,3 +1,7 @@
+---
+sidebar_position: 6
+---
+
 # dispatchCommand
 
 :::info

docs/docs/advanced/setNativeProps.mdx

@@ -0,0 +1,84 @@
+---
+sidebar_position: 7
+---
+
+# setNativeProps
+
+`setNativeProps` lets you imperatively update component properties.
+
+:::caution
+
+`setNativeProps` is an escape hatch for specific edge-cases.
+
+You should always reach for [`useAnimatedStyle`](docs/core/useAnimatedStyle) and [`useAnimatedProps`](docs/core/useAnimatedProps) first when animating styles or properties.
+
+:::
+
+## Reference
+
+```jsx
+import { setNativeProps } from 'react-native-reanimated';
+
+function App() {
+  const animatedRef = useAnimatedRef();
+
+  const tap = Gesture.Tap().onEnd(() => {
+    // highlight-start
+    setNativeProps(animatedRef, { text: '' });
+    // highlight-end
+  });
+
+  return <TextInput ref={animatedRef} />;
+}
+```
+
+<details>
+<summary>Type definitions</summary>
+
+```typescript
+function setNativeProps<T extends Component>(
+  animatedRef: AnimatedRef<T>,
+  updates: StyleProps
+) => void;
+```
+
+</details>
+
+### Arguments
+
+#### `animatedRef`
+
+An [animated ref](/docs/core/useAnimatedRef#returns) connected to the component you'd want to get the measurements from. The animated ref has to be passed either to an [Animated component](/docs/fundamentals/glossary#animated-component) or a React Native built-in component.
+
+#### `updates`
+
+An object with properties you want to update. These could be both style props (eg. `width`, `backgroundColor`) and regular props (eg. `text`).
+
+### Returns
+
+`setNativeProps` returns `undefined`.
+
+## Example
+
+import SetNativeProps from '@site/src/examples/SetNativeProps';
+import SetNativePropsSrc from '!!raw-loader!@site/src/examples/SetNativeProps';
+
+<InteractiveExample src={SetNativePropsSrc} component={<SetNativeProps />} />
+
+## Remarks
+
+- You should always reach for [`useAnimatedStyle`](docs/core/useAnimatedStyle) and [`useAnimatedProps`](docs/core/useAnimatedProps) first when animating styles or properties.
+
+- `setNativeProps` is supposed to only be used on the [UI thread](/docs/fundamentals/glossary#ui-thread).
+
+- `setNativeProps` function was created to allow updating props imperatively from gesture handlers. Because in other cases, you need to wrap `setNativeProps` with an additional `runOnUI` call, React Native's [built-in `setNativeProps`](https://reactnative.dev/docs/animations#setnativeprops) proves to work better with fewer jumps between runtimes.
+
+## Platform compatibility
+
+<div className="compatibility">
+
+| Android | iOS | Web |
+| ------- | --- | --- |
+| ✅      | ✅  | ✅  |
+
+</div>

docs/src/examples/SetNativeProps.jsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import { Button, StyleSheet, View } from 'react-native';
+import Animated, {
+  runOnUI,
+  setNativeProps,
+  useAnimatedRef,
+} from 'react-native-reanimated';
+
+const COLORS = ['#FFE780', '#87CCE8', '#FFA3A1', '#B1DFD0', '#B58DF1'];
+
+export default function Example() {
+  const animatedRef = useAnimatedRef();
+
+  const handlePress = () => {
+    runOnUI(() => {
+      // highlight-next-line
+      setNativeProps(animatedRef, {
+        backgroundColor: COLORS[Math.floor(Math.random() * COLORS.length)],
+        // highlight-next-line
+      });
+    })();
+  };
+
+  return (
+    <View style={styles.container}>
+      <Animated.View ref={animatedRef} style={styles.box} />
+      <Button title="change color" onPress={handlePress} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  box: {
+    height: 120,
+    width: 120,
+    backgroundColor: '#B58DF1',
+    borderRadius: 20,
+    marginBottom: 30,
+  },
+});

docs/src/theme/DocSidebarItems/index.js

@@ -5,7 +5,7 @@ import SidebarLabel from '@site/src/components/SidebarLabel';
 import styles from './styles.module.css';
 
 const EXPERIMENTAL_APIs = ['shared-element-transitions/overview'];
-const NEW_APIS = ['advanced/dispatchCommand', 'device/useReducedMotion'];
+const NEW_APIS = ['advanced/setNativeProps', 'device/useReducedMotion'];
 // TODO this item should probably not receive the "activePath" props
 // TODO this triggers whole sidebar re-renders on navigation
 function DocSidebarItems({ items, ...props }) {