feat: sync layout from JS (#1213)

## 📜 Description

Added an ability to have a bi-directional communication and read/update
layout from JS on demand.

## 💡 Motivation and Context

This PR adds a command that we can dispatch from JS in order to get an
actual layout of focused input. The task sounds pretty simple, but I
anyway had some problems, and would like to describe solutions from them
here.

First of all the querying of layout is an async operation and we need to
wait for completion before running a worklet code (so that we can be
sure, that event has been actually dispatched and shared-value has
up-to-date value). But default mechanism for view commands not suppose
to return any kind of data back to the JS thread. Alternative option is
to define "module" method and return the data/completion status from
there. However in new architecture it is highly not recommended to use
such approach, because this approach relies on RN internals that can be
changed/removed from the future. So I decided to go with recommended
approach. To overcome asynchronous stuff I decided to set one-time
listener and resolve a promise when I get specific
`layoutDidSynchronize` event - this is not a perfect solution but does a
job for now and doesn't use deprecated stuff, so I'm pretty happy.

On a high level overview - we pass `update` function through the
`context`, because `context` has an access to `KeyboardControllerView`
and from there we dispatch/wait.

Also I decided to expose `assureFocusedInputVisible` method for
`KeyboardAwareScrollView`. In the past I had requirements to scroll a
little bit when validation error appears, and back to the time I just
hard-coded it like `ref.current.scrollTo(50)`, but of course this fix
didn't handle all the cases. Now it's just enough to call
`ref.current.assureFocusedInputVisible()` and enjoy pixel perfect
automatic calculations 😎

And in the end I decided to cover new functionality with e2e tests so
that we will not break them accidentally in the future 🤞

Closes
#1208

## 📢 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

- added info about new `update` method;
- added info about `assureFocusedInputVisible` method of ref;

### E2E

- cover new functionality described in
#1208
- cover use cases when we set a focus on input that doesn't belong to
`KeyboardAwareScrollView`;

### JS

- added `synchronizeFocusedInputLayout` command for
`KeyboardControllerView`;
- added `KeyboardController::layoutDidSynchronize` event;
- expose `assureFocusedInputVisible` method for
`KeyboardAwareScrollView`;

### iOS

- implement `synchronizeFocusedInputLayout` command for paper/fabric;

### Android

- implement `synchronizeFocusedInputLayout` command for paper/fabric;

## 🤔 How Has This Been Tested?

Tested manually on iPhone 16 Pro (iOS 26.0)/Pixel 6 Pro (API 31, 35)
both paper/fabric.

## 📸 Screenshots (if appropriate):

|Android|iOS|
|-------|-----|
|<video
src="https://github.com/user-attachments/assets/42a48042-e244-4a2d-8017-606d5fabfb7e">|<video
src="https://github.com/user-attachments/assets/d72ee356-3fd6-4019-b5c6-9e09ef60608d">|

## 📝 Checklist

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

Author: kirillzyusko

android/src/fabric/java/com/reactnativekeyboardcontroller/KeyboardControllerViewManager.kt

@@ -1,5 +1,6 @@
 package com.reactnativekeyboardcontroller
 
+import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.ViewManagerDelegate
 import com.facebook.react.uimanager.annotations.ReactProp
@@ -56,6 +57,23 @@ class KeyboardControllerViewManager :
   ) = manager.setEnabled(view as EdgeToEdgeReactViewGroup, value)
   // endregion
 
+  // region Commands
+  override fun receiveCommand(
+    root: ReactViewGroup,
+    commandId: String,
+    args: ReadableArray?,
+  ) {
+    when (commandId) {
+      "synchronizeFocusedInputLayout" -> synchronizeFocusedInputLayout(root)
+      else -> super.receiveCommand(root, commandId, args)
+    }
+  }
+
+  override fun synchronizeFocusedInputLayout(view: ReactViewGroup) {
+    manager.synchronizeFocusedInputLayout(view as EdgeToEdgeReactViewGroup)
+  }
+  // endregion
+
   // region Getters
   override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Any> =
     manager.getExportedCustomDirectEventTypeConstants()

android/src/main/java/com/reactnativekeyboardcontroller/listeners/KeyboardAnimationCallback.kt

@@ -109,7 +109,7 @@ class KeyboardAnimationCallback(
         }
       }
     }
-  private var layoutObserver: FocusedInputObserver? = null
+  internal var layoutObserver: FocusedInputObserver? = null
 
   init {
     require(config.persistentInsetTypes and config.deferredInsetTypes == 0) {

android/src/main/java/com/reactnativekeyboardcontroller/managers/KeyboardControllerViewManagerImpl.kt

@@ -1,11 +1,13 @@
 package com.reactnativekeyboardcontroller.managers
 
+import com.facebook.react.bridge.Arguments
 import com.facebook.react.common.MapBuilder
 import com.facebook.react.uimanager.ThemedReactContext
 import com.reactnativekeyboardcontroller.events.FocusedInputLayoutChangedEvent
 import com.reactnativekeyboardcontroller.events.FocusedInputSelectionChangedEvent
 import com.reactnativekeyboardcontroller.events.FocusedInputTextChangedEvent
 import com.reactnativekeyboardcontroller.events.KeyboardTransitionEvent
+import com.reactnativekeyboardcontroller.extensions.emitEvent
 import com.reactnativekeyboardcontroller.listeners.WindowDimensionListener
 import com.reactnativekeyboardcontroller.views.EdgeToEdgeReactViewGroup
 
@@ -25,6 +27,11 @@ class KeyboardControllerViewManagerImpl {
     listener = null
   }
 
+  fun synchronizeFocusedInputLayout(view: EdgeToEdgeReactViewGroup) {
+    view.callback?.layoutObserver?.syncUpLayout()
+    view.reactContext.emitEvent("KeyboardController::layoutDidSynchronize", Arguments.createMap())
+  }
+
   fun setEnabled(
     view: EdgeToEdgeReactViewGroup,
     enabled: Boolean,

android/src/main/java/com/reactnativekeyboardcontroller/views/EdgeToEdgeReactViewGroup.kt

@@ -38,7 +38,7 @@ object EdgeToEdgeViewRegistry {
 @Suppress("detekt:TooManyFunctions")
 @SuppressLint("ViewConstructor")
 class EdgeToEdgeReactViewGroup(
-  private val reactContext: ThemedReactContext,
+  val reactContext: ThemedReactContext,
 ) : ReactViewGroup(reactContext) {
   // props
   private var isStatusBarTranslucent = false
@@ -58,7 +58,7 @@ class EdgeToEdgeReactViewGroup(
   // internal class members
   private var eventView: ReactViewGroup? = null
   private var wasMounted = false
-  private var callback: KeyboardAnimationCallback? = null
+  internal var callback: KeyboardAnimationCallback? = null
   private val config =
     KeyboardAnimationCallbackConfig(
       persistentInsetTypes = WindowInsetsCompat.Type.systemBars(),

android/src/paper/java/com/reactnativekeyboardcontroller/KeyboardControllerViewManager.kt

@@ -1,5 +1,6 @@
 package com.reactnativekeyboardcontroller
 
+import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.annotations.ReactProp
 import com.facebook.react.views.view.ReactViewGroup
@@ -58,6 +59,21 @@ class KeyboardControllerViewManager : ReactViewManager() {
   }
   // endregion
 
+  // region Commands
+  override fun receiveCommand(
+    root: ReactViewGroup,
+    commandId: String,
+    args: ReadableArray?,
+  ) {
+    when (commandId) {
+      "synchronizeFocusedInputLayout" -> {
+        manager.synchronizeFocusedInputLayout(root as EdgeToEdgeReactViewGroup)
+      }
+      else -> super.receiveCommand(root, commandId, args)
+    }
+  }
+  //endregion
+
   // region Getters
   override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Any> =
     manager.getExportedCustomDirectEventTypeConstants()

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

@@ -244,6 +244,14 @@ export function Example() {
 }
 ```
 
+## Methods
+
+### `assureFocusedInputVisible`
+
+A method that assures that focused input is visible and not obscured by keyboard or other elements.
+
+You may want to call it, when layout inside `ScrollView` changes (for example validation message appears or disappears and it shifts position of focused input).
+
 ## Example
 
 ```tsx

docs/docs/api/hooks/input/use-reanimated-focused-input.md

@@ -26,7 +26,7 @@ Hook will update its value in next cases:
 The value from `useReanimatedFocusedInput` will be always updated before keyboard events, so you can safely read values in `onStart` handler and be sure they are up-to-date.
 :::
 
-## Event structure
+## `input`
 
 The `input` property from this hook is returned as `SharedValue`. The returned data has next structure:
 
@@ -47,10 +47,14 @@ type FocusedInputLayoutChangedEvent = {
 };
 ```
 
+### `update`
+
+To update the focused input, use `update` function. Thus you can query the position on demand from JS thread.
+
 ## Example
 
 ```tsx
-const { input } = useReanimatedFocusedInput();
+const { input, update } = useReanimatedFocusedInput();
 ```
 
 Also have a look on [example](https://github.com/kirillzyusko/react-native-keyboard-controller/tree/main/example) app for more comprehensive usage.

e2e/kit/016-aware-scroll-view-with-sticky-view.e2e.ts

@@ -1,12 +1,18 @@
 import { expectBitmapsToBeEqual } from "./asserts";
 import {
   scrollDownUntilElementIsVisible,
+  tap,
   waitAndTap,
   waitForExpect,
 } from "./helpers";
 
 const BLINKING_CURSOR = 0.35;
 
+const closeKeyboard = async () => {
+  // tap outside to close a keyboard
+  await tap("aware_scroll_sticky_view_scroll_container", { x: 0, y: 100 });
+};
+
 describe("AwareScrollView with StickyView test cases", () => {
   it("should push input above keyboard on focus", async () => {
     await waitAndTap("aware_scroll_view_sticky_footer");
@@ -32,4 +38,35 @@ describe("AwareScrollView with StickyView test cases", () => {
       );
     });
   });
+
+  it("should react on `bottomOffset` change even if input is not visible", async () => {
+    await scrollDownUntilElementIsVisible(
+      "aware_scroll_sticky_view_scroll_container",
+      "TextInput#9",
+      { x: 0, y: 0.2, checkScrollViewVisibility: false },
+    );
+    await waitAndTap("toggle_height");
+    await waitForExpect(async () => {
+      await expectBitmapsToBeEqual(
+        "AwareScrollViewWithStickyViewFirstInputFocused",
+        BLINKING_CURSOR,
+      );
+    });
+  });
+
+  it("shouldn't scroll a scroll view when focusing input inside sticky view", async () => {
+    await closeKeyboard();
+    await element(by.id("aware_scroll_sticky_view_scroll_container")).swipe(
+      "down",
+      "fast",
+      1,
+    );
+    await waitAndTap("Amount");
+    await waitForExpect(async () => {
+      await expectBitmapsToBeEqual(
+        "AwareScrollViewWithStickyViewStickyInputFocused",
+        BLINKING_CURSOR,
+      );
+    });
+  });
 });