docs: mention, that React commits blocks REA commits in KAV, KASV components (#1370)

## 📜 Description

Adds an explanation how to fix
#1086

## 💡 Motivation and Context

The problem is caused by the fact that react commits pause reanimated
commits. To fix this problem we need to enable feature flag. I tested in
FabricExample project and it indeed solves the issue.

Closes
#1086

## 📢 Changelog

<!-- High level overview of important changes -->
<!-- For example: fixed status bar manipulation; added new types
declarations; -->
<!-- If your changes don't affect one of platform/language below - then
remove this platform/language -->

### Docs

- add explanation how to fix missing animation on new arch for
`KeyboardAvoidingView` with `translate-with-padding` behavior
- add explanation how to fix missing animation on new arch for
`KeyboardChatScrollView`

## 🤔 How Has This Been Tested?

Tested via preview.

## 📸 Screenshots (if appropriate):

<img width="1344" height="1131" alt="image"
src="https://github.com/user-attachments/assets/42a69496-05d0-4b7e-a4f3-a41b236f1947"
/>

## 📝 Checklist

- [x] CI successfully passed
- [x] I added new mocks and corresponding unit-tests if library API was
changed

Author: kirillzyusko

FabricExample/patches/react-native+0.81.4.patch

@@ -0,0 +1,13 @@
+diff --git a/node_modules/react-native/ReactCommon/react/featureflags/ReactNativeFeatureFlags.cpp b/node_modules/react-native/ReactCommon/react/featureflags/ReactNativeFeatureFlags.cpp
+index 667aec1..5cd9376 100644
+--- a/node_modules/react-native/ReactCommon/react/featureflags/ReactNativeFeatureFlags.cpp
++++ b/node_modules/react-native/ReactCommon/react/featureflags/ReactNativeFeatureFlags.cpp
+@@ -215,7 +215,7 @@ double ReactNativeFeatureFlags::preparedTextCacheSize() {
+ }
+ 
+ bool ReactNativeFeatureFlags::preventShadowTreeCommitExhaustion() {
+-  return getAccessor().preventShadowTreeCommitExhaustion();
++  return true;
+ }
+ 
+ bool ReactNativeFeatureFlags::traceTurboModulePromiseRejectionsOnAndroid() {

FabricExample/patches/react-native-reanimated+4.2.1.patch

@@ -0,0 +1,13 @@
+diff --git a/node_modules/react-native-reanimated/Common/cpp/reanimated/Fabric/updates/UpdatesRegistryManager.cpp b/node_modules/react-native-reanimated/Common/cpp/reanimated/Fabric/updates/UpdatesRegistryManager.cpp
+index 48a3e33..a242150 100644
+--- a/node_modules/react-native-reanimated/Common/cpp/reanimated/Fabric/updates/UpdatesRegistryManager.cpp
++++ b/node_modules/react-native-reanimated/Common/cpp/reanimated/Fabric/updates/UpdatesRegistryManager.cpp
+@@ -22,7 +22,7 @@ void UpdatesRegistryManager::addRegistry(const std::shared_ptr<UpdatesRegistry>
+ }
+ 
+ void UpdatesRegistryManager::pauseReanimatedCommits() {
+-  if constexpr (!StaticFeatureFlags::getFlag("DISABLE_COMMIT_PAUSING_MECHANISM")) {
++  if constexpr (false) {
+     isPaused_ = true;
+   }
+ }

docs/docs/api/components/keyboard-avoiding-view.mdx

@@ -194,3 +194,21 @@ Since `StatusBar.currentHeight` is an **Android-only** property, using `?? 0` en
 When `true`, the view automatically detects its position on screen, accounting for navigation headers, modals, and other layout offsets. This means `keyboardVerticalOffset` becomes purely additive extra space rather than compensation for unknown positioning.
 
 Default is `false`.
+
+## Troubleshooting
+
+### Missing iOS animation with `translate-with-padding` behavior
+
+On iOS, updating React state right before a keyboard event can cause animations to be skipped entirely. This happens because a React commit can block Reanimated from applying its animated updates in the same frame.
+
+Common triggers include:
+
+- updating state in the `onFocus` callback of a `TextInput`;
+- updating state in response to the `keyboardWillShow` event;
+- using `KeyboardToolbar` or other components that trigger a state update before the keyboard appears.
+
+To fix this, enable the [DISABLE_COMMIT_PAUSING_MECHANISM](https://docs.swmansion.com/react-native-reanimated/docs/guides/feature-flags/#disable_commit_pausing_mechanism) feature flag. See the link for detailed setup instructions.
+
+:::info Do I need to enable this flag?
+This issue can occur even if the state update comes from a different screen (e.g. a parent navigator). To check, open the React Profiler and look for any React commits that happen just before the keyboard event — if you see one, you likely need this flag.
+:::

docs/docs/api/components/keyboard-chat-scroll-view.mdx

@@ -267,7 +267,7 @@ On Android we adjust the scroll position inside the [`onMove`](../hooks/keyboard
 
 ## Troubleshooting
 
-### Reanimated feature flag
+### De-synchronized Android animation (new arch only)
 
 `KeyboardChatScrollView` relies on a Reanimated commit hook internally. If you're using **Reanimated < 4.3.0**, you need to enable the [`USE_COMMIT_HOOK_ONLY_FOR_REACT_COMMITS`](https://docs.swmansion.com/react-native-reanimated/docs/guides/feature-flags/#use_commit_hook_only_for_react_commits) feature flag in your `package.json`:
 
@@ -290,3 +290,19 @@ If you're on **Reanimated 4.3.0+**, this flag is enabled by default — no extra
 :::info What it affects?
 If you don't enable this flag you'll see de-synchronized keyboard animation on Android/Fabric architecture.
 :::
+
+### Missing animations on iOS (new arch only)
+
+On iOS (New Architecture only), updating React state right before a keyboard event can cause animations to be skipped entirely. This happens because a React commit can block Reanimated from applying its animated updates in the same frame.
+
+Common triggers include:
+
+- updating state in the `onFocus` callback of a `TextInput`;
+- updating state in response to the `keyboardWillShow` event;
+- using `KeyboardToolbar` or other components that trigger a state update before the keyboard appears.
+
+To fix this, enable the [DISABLE_COMMIT_PAUSING_MECHANISM](https://docs.swmansion.com/react-native-reanimated/docs/guides/feature-flags/#disable_commit_pausing_mechanism) feature flag. See the link for detailed setup instructions.
+
+:::info Do I need to enable this flag?
+This issue can occur even if the state update comes from a different screen (e.g. a parent navigator). To check, open the React Profiler and look for any React commits that happen just before the keyboard event — if you see one, you likely need this flag.
+:::

docs/versioned_docs/version-1.21.0/api/components/keyboard-avoiding-view.mdx

@@ -194,3 +194,21 @@ Since `StatusBar.currentHeight` is an **Android-only** property, using `?? 0` en
 When `true`, the view automatically detects its position on screen, accounting for navigation headers, modals, and other layout offsets. This means `keyboardVerticalOffset` becomes purely additive extra space rather than compensation for unknown positioning.
 
 Default is `false`.
+
+## Troubleshooting
+
+### Missing iOS animation with `translate-with-padding` behavior
+
+On iOS, updating React state right before a keyboard event can cause animations to be skipped entirely. This happens because a React commit can block Reanimated from applying its animated updates in the same frame.
+
+Common triggers include:
+
+- updating state in the `onFocus` callback of a `TextInput`;
+- updating state in response to the `keyboardWillShow` event;
+- using `KeyboardToolbar` or other components that trigger a state update before the keyboard appears.
+
+To fix this, enable the [DISABLE_COMMIT_PAUSING_MECHANISM](https://docs.swmansion.com/react-native-reanimated/docs/guides/feature-flags/#disable_commit_pausing_mechanism) feature flag. See the link for detailed setup instructions.
+
+:::info Do I need to enable this flag?
+This issue can occur even if the state update comes from a different screen (e.g. a parent navigator). To check, open the React Profiler and look for any React commits that happen just before the keyboard event — if you see one, you likely need this flag.
+:::

docs/versioned_docs/version-1.21.0/api/components/keyboard-chat-scroll-view.mdx

@@ -267,7 +267,7 @@ On Android we adjust the scroll position inside the [`onMove`](../hooks/keyboard
 
 ## Troubleshooting
 
-### Reanimated feature flag
+### De-synchronized Android animation (new arch only)
 
 `KeyboardChatScrollView` relies on a Reanimated commit hook internally. If you're using **Reanimated < 4.3.0**, you need to enable the [`USE_COMMIT_HOOK_ONLY_FOR_REACT_COMMITS`](https://docs.swmansion.com/react-native-reanimated/docs/guides/feature-flags/#use_commit_hook_only_for_react_commits) feature flag in your `package.json`:
 
@@ -290,3 +290,19 @@ If you're on **Reanimated 4.3.0+**, this flag is enabled by default — no extra
 :::info What it affects?
 If you don't enable this flag you'll see de-synchronized keyboard animation on Android/Fabric architecture.
 :::
+
+### Missing animations on iOS (new arch only)
+
+On iOS (New Architecture only), updating React state right before a keyboard event can cause animations to be skipped entirely. This happens because a React commit can block Reanimated from applying its animated updates in the same frame.
+
+Common triggers include:
+
+- updating state in the `onFocus` callback of a `TextInput`;
+- updating state in response to the `keyboardWillShow` event;
+- using `KeyboardToolbar` or other components that trigger a state update before the keyboard appears.
+
+To fix this, enable the [DISABLE_COMMIT_PAUSING_MECHANISM](https://docs.swmansion.com/react-native-reanimated/docs/guides/feature-flags/#disable_commit_pausing_mechanism) feature flag. See the link for detailed setup instructions.
+
+:::info Do I need to enable this flag?
+This issue can occur even if the state update comes from a different screen (e.g. a parent navigator). To check, open the React Profiler and look for any React commits that happen just before the keyboard event — if you see one, you likely need this flag.
+:::