feat: insets prop for KeyboardToolbar (#866)

## 📜 Description

Handle safe-area paddings in `KeyboardToolbar` component (landscape
mode).

## 💡 Motivation and Context

I had a lot of ideas how to fix this problem. Some of them:
- pass `insets` as prop;
- automatically grab insets from `useSafeAreaInsets` hook;
- render view wrapper (users can add their own SafeAreaView
implementation).

The **automatically grab insets from `useSafeAreaInsets` hook** idea has
failed, because in my case `react-native-safe-area-context` was
resolving to other packages (maybe it's the problem with package linking
in example app). But this is still not a perfect approach, because I'll
force users to install additional package.

The **render view wrapper (users can add their own SafeAreaView
implementation)** was perspective, but it would be very complex for end
users. Mostly because we have to provide additional props, such as
`backgroundColor` etc., so it would look like:

```tsx
<KeyboardToolbar
  wrapper={(props) => <SafeAreaView {...props} />}
/>
```

And there is still a lot of open topics on how to handle many aspects -
we would have to write conditional code when wrapper is not provided and
render `View`.

So in the end I decided to add `insets` property - and it would be up to
lib users to provide it or not. Maybe not ideal solution, but definitely
better than having an open issues for 9+ months 🙃

Closes
#572

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

### JS

- added new `insets` property.

## 🤔 How Has This Been Tested?

Tested manually on iPhone 15 (iOS 17.5), Fabric.

## 📸 Screenshots (if appropriate):

|Before|After|
|------|-----|

|![image](https://github.com/user-attachments/assets/a90955a5-c33b-44d9-80fb-e4e7e88bc735)|![image](https://github.com/user-attachments/assets/c64a54df-f0e9-4f5a-b62b-26b2f679134b)|

## 📝 Checklist

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

Author: kirillzyusko

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

@@ -6,6 +6,7 @@ import {
   KeyboardAwareScrollView,
   KeyboardToolbar,
 } from "react-native-keyboard-controller";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
 
 import TextInput from "../../../components/TextInput";
 
@@ -33,6 +34,7 @@ export default function ToolbarExample() {
   const onHideAutoFill = useCallback(() => {
     setShowAutoFill(false);
   }, []);
+  const insets = useSafeAreaInsets();
 
   return (
     <>
@@ -158,6 +160,7 @@ export default function ToolbarExample() {
             <AutoFillContacts onContactSelected={onContactSelected} />
           ) : null
         }
+        insets={insets}
         opacity={Platform.OS === "ios" ? "4F" : "DD"}
         onDoneCallback={haptic}
         onNextCallback={haptic}

docs/docs/api/components/keyboard-toolbar/index.mdx

@@ -144,6 +144,20 @@ const Icon: KeyboardToolbarProps["icon"] = ({ type }) => {
 <KeyboardToolbar icon={Icon} />;
 ```
 
+### `insets`
+
+An object containing `left` and `right` properties that define the `KeyboardToolbar` padding. This helps prevent overlap with system UI elements, especially in landscape orientation:
+
+```tsx
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+
+// ...
+
+const insets = useSafeAreaInsets();
+
+<KeyboardToolbar insets={insets} />;
+```
+
 ### `onDoneCallback`
 
 A callback that is called when the user presses the **done** button. The callback receives an instance of `GestureResponderEvent` which can be used to cancel the default action (for advanced use-cases).

docs/versioned_docs/version-1.16.0/api/components/keyboard-toolbar/index.mdx

@@ -144,6 +144,20 @@ const Icon: KeyboardToolbarProps["icon"] = ({ type }) => {
 <KeyboardToolbar icon={Icon} />;
 ```
 
+### `insets`
+
+An object containing `left` and `right` properties that define the `KeyboardToolbar` padding. This helps prevent overlap with system UI elements, especially in landscape orientation:
+
+```tsx
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+
+// ...
+
+const insets = useSafeAreaInsets();
+
+<KeyboardToolbar insets={insets} />;
+```
+
 ### `onDoneCallback`
 
 A callback that is called when the user presses the **done** button. The callback receives an instance of `GestureResponderEvent` which can be used to cancel the default action (for advanced use-cases).

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

@@ -6,6 +6,7 @@ import {
   KeyboardAwareScrollView,
   KeyboardToolbar,
 } from "react-native-keyboard-controller";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
 
 import TextInput from "../../../components/TextInput";
 
@@ -33,6 +34,7 @@ export default function ToolbarExample() {
   const onHideAutoFill = useCallback(() => {
     setShowAutoFill(false);
   }, []);
+  const insets = useSafeAreaInsets();
 
   return (
     <>
@@ -158,6 +160,7 @@ export default function ToolbarExample() {
             <AutoFillContacts onContactSelected={onContactSelected} />
           ) : null
         }
+        insets={insets}
         opacity={Platform.OS === "ios" ? "4F" : "DD"}
         onDoneCallback={haptic}
         onNextCallback={haptic}

src/components/KeyboardToolbar/index.tsx

@@ -15,6 +15,11 @@ import type { KeyboardStickyViewProps } from "../KeyboardStickyView";
 import type { ReactNode } from "react";
 import type { GestureResponderEvent, ViewProps } from "react-native";
 
+type SafeAreaInsets = {
+  left: number;
+  right: number;
+};
+
 export type KeyboardToolbarProps = Omit<
   ViewProps,
   "style" | "testID" | "children"
@@ -54,6 +59,7 @@ export type KeyboardToolbarProps = Omit<
    * A value for container opacity in hexadecimal format (e.g. `ff`). Default value is `ff`.
    */
   opacity?: HEX;
+  insets?: SafeAreaInsets;
 } & Pick<KeyboardStickyViewProps, "offset" | "enabled">;
 
 const TEST_ID_KEYBOARD_TOOLBAR = "keyboard.toolbar";
@@ -83,6 +89,7 @@ const KeyboardToolbar: React.FC<KeyboardToolbarProps> = ({
   opacity = DEFAULT_OPACITY,
   offset: { closed = 0, opened = 0 } = {},
   enabled = true,
+  insets,
   ...rest
 }) => {
   const colorScheme = useColorScheme();
@@ -110,8 +117,12 @@ const KeyboardToolbar: React.FC<KeyboardToolbarProps> = ({
       {
         backgroundColor: `${theme[colorScheme].background}${opacity}`,
       },
+      {
+        paddingLeft: insets?.left,
+        paddingRight: insets?.right,
+      },
     ],
-    [colorScheme, opacity, theme],
+    [colorScheme, opacity, theme, insets],
   );
   const offset = useMemo(
     () => ({ closed: closed + KEYBOARD_TOOLBAR_HEIGHT, opened }),