[Docs][NA] Add measurements and Direct Manipulation (facebook#4286)

* [Docs][NA] Add measurements and Direct Manipulation

* Apply review feedback

* Change title of snack player

Author: cipolleschi

docs/the-new-architecture/direct-manipulation.md

@@ -0,0 +1,128 @@
+---
+id: direct-manipulation-new-architecture
+title: Direct Manipulation
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';
+
+It is sometimes necessary to make changes directly to a component without using state/props to trigger a re-render of the entire subtree. When using React in the browser for example, you sometimes need to directly modify a DOM node, and the same is true for views in mobile apps. `setNativeProps` is the React Native equivalent to setting properties directly on a DOM node.
+
+:::caution
+Use `setNativeProps` when frequent re-rendering creates a performance bottleneck!
+
+Direct manipulation will not be a tool that you reach for frequently. You will typically only be using it for creating continuous animations to avoid the overhead of rendering the component hierarchy and reconciling many views.
+`setNativeProps` is imperative and stores state in the native layer (DOM, UIView, etc.) and not within your React components, which makes your code more difficult to reason about.
+
+Before you use it, try to solve your problem with `setState` and [`shouldComponentUpdate`](https://reactjs.org/docs/optimizing-performance.html#shouldcomponentupdate-in-action).
+:::
+
+## setNativeProps to edit TextInput value
+
+Another very common use case of `setNativeProps` is to edit the value of the TextInput. The `controlled` prop of TextInput can sometimes drop characters when the `bufferDelay` is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use `setNativeProps` to directly manipulate the TextInput value when necessary.
+
+For example, the following code demonstrates editing the input when you tap a button:
+
+<Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>
+<TabItem value="javascript">
+
+```SnackPlayer name=setNativeProps%20on%20TextInput&ext=js
+import React from 'react';
+import {useCallback, useRef} from 'react';
+import {
+  StyleSheet,
+  TextInput,
+  Text,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+
+const App = () => {
+  const inputRef = useRef(null);
+  const editText = useCallback(() => {
+    inputRef.current.setNativeProps({text: 'Edited Text'});
+  }, []);
+
+  return (
+    <View style={styles.container}>
+      <TextInput ref={inputRef} style={styles.input} />
+      <TouchableOpacity onPress={editText}>
+        <Text>Edit text</Text>
+      </TouchableOpacity>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  input: {
+    height: 50,
+    width: 200,
+    marginHorizontal: 20,
+    borderWidth: 1,
+    borderColor: '#ccc',
+  },
+});
+
+export default App;
+```
+
+</TabItem>
+<TabItem value="typescript">
+
+```SnackPlayer name=Clear%20text&ext=tsx
+import React from 'react';
+import {useCallback, useRef} from 'react';
+import {
+  StyleSheet,
+  TextInput,
+  Text,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+
+const App = () => {
+  const inputRef = useRef<TextInput>(null);
+  const editText = useCallback(() => {
+    inputRef.current?.setNativeProps({text: 'Edited Text'});
+  }, []);
+
+  return (
+    <View style={styles.container}>
+      <TextInput ref={inputRef} style={styles.input} />
+      <TouchableOpacity onPress={editText}>
+        <Text>Edit text</Text>
+      </TouchableOpacity>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  input: {
+    height: 50,
+    width: 200,
+    marginHorizontal: 20,
+    borderWidth: 1,
+    borderColor: '#ccc',
+  },
+});
+
+export default App;
+```
+
+</TabItem>
+</Tabs>
+
+You can use the [`clear`](../textinput#clear) method to clear the `TextInput` which clears the current input text using the same approach.
+
+## Avoiding conflicts with the render function
+
+If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from `setNativeProps` will be completely ignored and overridden.

docs/the-new-architecture/layout-measurements.md

@@ -0,0 +1,53 @@
+# Measuring the Layout
+
+Sometimes, you need to measure the current layout to apply some changes to the overall layout or to make decisions and call some specific logic.
+
+React Native provides some native methods to know what are the measurements of the views.
+
+The best way to invoke those methods is in a `useLayoutEffect` hook: this will give you the most recent values for those measurements and it will let you apply changes in the same frame when the measurements are computed.
+
+Typical code will look like this:
+
+```tsx
+function AComponent(children) {
+  const targetRef = React.useRef(null)
+
+  useLayoutEffect(() => {
+    targetRef.current?.measure(({measurements}) => {
+      //do something with the `measurements`
+    });
+  }, [ /* add dependencies here */]);
+
+  return (
+    <View ref={targetRef}>
+     {children}
+    <View />
+  );
+}
+```
+
+:::note
+The methods described here are available on most of the default components provided by React Native. However, they are _not_ available on composite components that aren't directly backed by a native view. This will generally include most components that you define in your own app.
+:::
+
+## measure(callback)
+
+Determines the location on screen (`x` and `y`), `width`, and `height` in the viewport of the given view. Returns the values via an async callback. If successful, the callback will be called with the following arguments:
+
+- `x`: the `x` coordinate of the origin (top-left corner) of the measured view in the viewport.
+- `y`: the `y` coordinate of the origin (top-left corner) of the measured view in the viewport.
+- `width`: the `width` of the view.
+- `height`: the `height` of the view.
+- `pageX`: the `x` coordinate of the view in the viewport (typically the the whole screen).
+- `pageY`: the `y` coordinate of the view in the viewport (typically the the whole screen).
+
+Also the `width` and `height` returned by `measure()` are the `width` and `height` of the component in the viewport.
+
+## measureInWindow(callback)
+
+Determines the location (`x` and `y`) of the given view in the window and returns the values via an async callback. If the React root view is embedded in another native view, this will give you the absolute coordinates. If successful, the callback will be called with the following arguments:
+
+- `x`: the `x` coordinate of the view in the current window.
+- `y`: the `y` coordinate of the view in the current window.
+- `width`: the `width` of the view.
+- `height`: the `height` of the view.

website/sidebars.json

@@ -86,6 +86,10 @@
       "the-new-architecture/custom-cxx-types",
       "the-new-architecture/create-module-library"
     ],
+    "Native Components": [
+      "the-new-architecture/direct-manipulation-new-architecture",
+      "the-new-architecture/layout-measurements"
+    ],
     "Android and iOS guides": [
       {
         "type": "category",