feat: KeyboardToolbar.Group (#881)

## 📜 Description

Added `KeyboardToolbar.Group` component.

## 💡 Motivation and Context

This PR adds new `KeyboardToolbar.Group` component and corresponding
native view. The idea is that with new component we can define a
**group** of **related inputs** so that other inputs will not be
scanned.

The idea is similar to
https://github.com/hackiftekhar/IQKeyboardManager/wiki/Manual-Management#show-previousnext-arrow-buttons-for-textfield-which-are-not-direct-disblings

Closes
#470

## 📢 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 API reference how to use new API;

### JS

- declare `KeyboardToolbarGroupView` component (codegen);
- updated mocks file;
- added snapshot testing for rendering compound `KeyboardToolbar`;

### iOS

- update traversal algorithm to take `KeyboardToolbarGroupView` into
consideration;
- added unit tests to cover new functionality;

### Android

- update traversal algorithm to take `KeyboardToolbarGroupView` into
consideration;
- added unit tests to cover new functionality;

## 🤔 How Has This Been Tested?

Tested manually on:
- Pixel 7 Pro (API 36, real device)
- iPhone 17 Pro (iOS 26.2, simulator)

## 📸 Screenshots (if appropriate):

|Android|iOS|
|--------|----|
|<video
src="https://github.com/user-attachments/assets/05cd4c1f-06bc-4ac2-8ccb-540103f1199c">|<video
src="https://github.com/user-attachments/assets/1a399979-bc64-4ecd-b5e9-a83760248075">|

## 📝 Checklist

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

Author: kirillzyusko

FabricExample/__tests__/__snapshots__/components-rendering.spec.tsx.snap

@@ -133,3 +133,38 @@ exports[`components rendering should render \`OverKeyboardView\` 1`] = `
   />
 </OverKeyboardView>
 `;
+
+exports[`components rendering should render compound \`KeyboardToolbar\` 1`] = `
+[
+  <View>
+    <KeyboardToolbar.Background>
+      <View
+        style={
+          {
+            "backgroundColor": "black",
+            "height": 20,
+            "width": 20,
+          }
+        }
+      />
+    </KeyboardToolbar.Background>
+    <KeyboardToolbar.Content>
+      <View
+        style={
+          {
+            "backgroundColor": "black",
+            "height": 20,
+            "width": 20,
+          }
+        }
+      />
+    </KeyboardToolbar.Content>
+    <KeyboardToolbar.Prev />
+    <KeyboardToolbar.Next />
+    <KeyboardToolbar.Done />
+  </View>,
+  <KeyboardToolbar.Group>
+    <TextInput />
+  </KeyboardToolbar.Group>,
+]
+`;

FabricExample/__tests__/components-rendering.spec.tsx

@@ -1,6 +1,6 @@
 import { render } from "@testing-library/react-native";
 import React from "react";
-import { View } from "react-native";
+import { TextInput, View } from "react-native";
 import {
   KeyboardAvoidingView,
   KeyboardAwareScrollView,
@@ -68,6 +68,27 @@ function KeyboardToolbarTest() {
   return <KeyboardToolbar content={content} />;
 }
 
+function KeyboardToolbarCompoundTest() {
+  return (
+    <>
+      <KeyboardToolbar>
+        <KeyboardToolbar.Background>
+          <EmptyView />
+        </KeyboardToolbar.Background>
+        <KeyboardToolbar.Content>
+          <EmptyView />
+        </KeyboardToolbar.Content>
+        <KeyboardToolbar.Prev />
+        <KeyboardToolbar.Next />
+        <KeyboardToolbar.Done />
+      </KeyboardToolbar>
+      <KeyboardToolbar.Group>
+        <TextInput />
+      </KeyboardToolbar.Group>
+    </>
+  );
+}
+
 function OverKeyboardViewTest() {
   return (
     <OverKeyboardView visible={true}>
@@ -109,6 +130,10 @@ describe("components rendering", () => {
     expect(render(<KeyboardToolbarTest />)).toMatchSnapshot();
   });
 
+  it("should render compound `KeyboardToolbar`", () => {
+    expect(render(<KeyboardToolbarCompoundTest />)).toMatchSnapshot();
+  });
+
   it("should render `OverKeyboardView`", () => {
     expect(render(<OverKeyboardViewTest />)).toMatchSnapshot();
   });

FabricExample/src/screens/Examples/Toolbar/index.tsx

@@ -1,3 +1,4 @@
+import BottomSheet, { BottomSheetView } from "@gorhom/bottom-sheet";
 import React, { useCallback, useEffect, useState } from "react";
 import { Modal, Platform, StyleSheet, Text, View } from "react-native";
 import {
@@ -214,6 +215,24 @@ export default function ToolbarExample({ navigation }: Props) {
           <Form />
         </View>
       </Modal>
+      <BottomSheet index={-1}>
+        <BottomSheetView style={styles.bottomSheetContent}>
+          <KeyboardToolbar.Group>
+            <TextInput
+              keyboardType="default"
+              placeholder="Group input 1"
+              testID="TextInput#14"
+              title="Group Input 1"
+            />
+            <TextInput
+              keyboardType="default"
+              placeholder="Group input 2"
+              testID="TextInput#15"
+              title="Group Input 2"
+            />
+          </KeyboardToolbar.Group>
+        </BottomSheetView>
+      </BottomSheet>
     </>
   );
 }
@@ -245,4 +264,7 @@ const styles = StyleSheet.create({
   modal: {
     marginTop: 32,
   },
+  bottomSheetContent: {
+    flex: 1,
+  },
 });

android/src/base/java/com/reactnativekeyboardcontroller/KeyboardControllerPackage.kt

@@ -60,5 +60,6 @@ class KeyboardControllerPackage : BaseReactPackage() {
       OverKeyboardViewManager(),
       KeyboardBackgroundViewManager(),
       ClippingScrollViewDecoratorViewManager(),
+      KeyboardToolbarGroupViewManager(),
     )
 }

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

@@ -0,0 +1,23 @@
+package com.reactnativekeyboardcontroller
+
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.ViewGroupManager
+import com.facebook.react.uimanager.ViewManagerDelegate
+import com.facebook.react.viewmanagers.KeyboardToolbarGroupViewManagerDelegate
+import com.facebook.react.viewmanagers.KeyboardToolbarGroupViewManagerInterface
+import com.reactnativekeyboardcontroller.managers.KeyboardToolbarGroupViewManagerImpl
+import com.reactnativekeyboardcontroller.views.KeyboardToolbarGroupReactViewGroup
+
+class KeyboardToolbarGroupViewManager :
+  ViewGroupManager<KeyboardToolbarGroupReactViewGroup>(),
+  KeyboardToolbarGroupViewManagerInterface<KeyboardToolbarGroupReactViewGroup> {
+  private val manager = KeyboardToolbarGroupViewManagerImpl()
+  private val mDelegate = KeyboardToolbarGroupViewManagerDelegate(this)
+
+  override fun getDelegate(): ViewManagerDelegate<KeyboardToolbarGroupReactViewGroup> = mDelegate
+
+  override fun getName(): String = KeyboardToolbarGroupViewManagerImpl.NAME
+
+  override fun createViewInstance(context: ThemedReactContext): KeyboardToolbarGroupReactViewGroup =
+    manager.createViewInstance(context)
+}

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

@@ -120,7 +120,8 @@ class FocusedInputObserver(
         selectionSubscription = newFocus.addOnSelectionChangedListener(selectionListener)
         FocusedInputHolder.set(newFocus)
 
-        val allInputFields = ViewHierarchyNavigator.getAllInputFields(context?.rootView)
+        val groupAncestor = ViewHierarchyNavigator.findGroupAncestor(newFocus)
+        val allInputFields = ViewHierarchyNavigator.getAllInputFields(groupAncestor ?: context?.rootView)
         val currentIndex = allInputFields.indexOf(newFocus)
 
         context.emitEvent(

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

@@ -0,0 +1,13 @@
+package com.reactnativekeyboardcontroller.managers
+
+import com.facebook.react.uimanager.ThemedReactContext
+import com.reactnativekeyboardcontroller.views.KeyboardToolbarGroupReactViewGroup
+
+class KeyboardToolbarGroupViewManagerImpl {
+  fun createViewInstance(reactContext: ThemedReactContext): KeyboardToolbarGroupReactViewGroup =
+    KeyboardToolbarGroupReactViewGroup(reactContext)
+
+  companion object {
+    const val NAME = "KeyboardToolbarGroupView"
+  }
+}

android/src/main/java/com/reactnativekeyboardcontroller/traversal/ViewHierarchyNavigator.kt

@@ -5,6 +5,7 @@ import android.view.ViewGroup
 import android.widget.EditText
 import com.facebook.react.bridge.UiThreadUtil
 import com.reactnativekeyboardcontroller.extensions.focus
+import com.reactnativekeyboardcontroller.views.KeyboardToolbarGroupReactViewGroup
 
 object ViewHierarchyNavigator {
   fun setFocusTo(
@@ -25,19 +26,40 @@ object ViewHierarchyNavigator {
     fun findEditTexts(view: View?) {
       if (isValidTextInput(view)) {
         editTexts.add(view as EditText)
-      } else if (view is ViewGroup) {
+      } else if (view is ViewGroup && view !is KeyboardToolbarGroupReactViewGroup) {
         for (i in 0 until view.childCount) {
           findEditTexts(view.getChildAt(i))
         }
       }
     }
 
-    // Start the search with the provided viewGroup
-    findEditTexts(viewGroup)
+    // If the root is a group itself, search within it (for group-scoped queries)
+    if (viewGroup is KeyboardToolbarGroupReactViewGroup) {
+      for (i in 0 until viewGroup.childCount) {
+        findEditTexts(viewGroup.getChildAt(i))
+      }
+    } else {
+      findEditTexts(viewGroup)
+    }
 
     return editTexts
   }
 
+  /**
+   * Finds the closest [KeyboardToolbarGroupReactViewGroup] ancestor of the given view.
+   * Returns null if the view is not inside any group.
+   */
+  fun findGroupAncestor(view: View?): KeyboardToolbarGroupReactViewGroup? {
+    var current = view?.parent
+    while (current != null) {
+      if (current is KeyboardToolbarGroupReactViewGroup) {
+        return current
+      }
+      current = current.parent
+    }
+    return null
+  }
+
   private fun findNextEditText(currentFocus: View): EditText? = findEditTextInDirection(currentFocus, 1)
 
   private fun findPreviousEditText(currentFocus: View): EditText? = findEditTextInDirection(currentFocus, -1)
@@ -64,6 +86,11 @@ object ViewHierarchyNavigator {
       i += direction
     }
 
+    // Don't navigate outside the group boundary
+    if (parentViewGroup is KeyboardToolbarGroupReactViewGroup) {
+      return null
+    }
+
     // Recurse to the parent's parent if no sibling EditText is found
     return findEditTextInDirection(parentViewGroup, direction)
   }
@@ -91,7 +118,7 @@ object ViewHierarchyNavigator {
 
     if (isValidTextInput(child)) {
       result = child as EditText
-    } else if (child is ViewGroup) {
+    } else if (child is ViewGroup && child !is KeyboardToolbarGroupReactViewGroup) {
       // If the child is a ViewGroup, check its children recursively
       result = findEditTextInHierarchy(child, direction)
     }

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

@@ -0,0 +1,13 @@
+package com.reactnativekeyboardcontroller.views
+
+import android.annotation.SuppressLint
+import android.content.Context
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.views.view.ReactViewGroup
+
+@SuppressLint("ViewConstructor")
+class KeyboardToolbarGroupReactViewGroup : ReactViewGroup {
+  constructor(reactContext: ThemedReactContext) : super(reactContext)
+  internal constructor(context: Context) : super(context)
+  // semantic view used in KeyboardToolbar traverse algorithm
+}

android/src/main/jni/RNKC.h

@@ -15,6 +15,7 @@
 #include <react/renderer/components/RNKC/RNKCOverKeyboardViewComponentDescriptor.h>
 #include <react/renderer/components/RNKC/RNKCKeyboardBackgroundViewComponentDescriptor.h>
 #include <react/renderer/components/RNKC/RNKCClippingScrollViewDecoratorViewComponentDescriptor.h>
+#include <react/renderer/components/RNKC/RNKCKeyboardToolbarGroupViewComponentDescriptor.h>
 
 #include <memory>
 #include <string>