react-native-external-keyboard 0.6.8 → 0.7.0

package/README.md

@@ -5,152 +5,60 @@ React Native library for enhanced external keyboard support.
 - ⚡️ The New Architecture is supported
 - ⚡️ Bridgeless
 
-> [!NOTE]
-> React Native `0.80.0` (`0.79.0`) includes a fix for `TextInput` focus on Android.
-> `TextInput`: Can now focus TextInput with keyboard ([e00028f6bb](https://github.com/facebook/react-native/commit/e00028f6bb6c19de861f9a25f377295755f3671b) by [@joevilches](https://github.com/joevilches))
->
-> This means that there is no need to use the workaround with `KeyboardExtendedInput`, and it is recommended to use the default `TextInput` instead. Additionally, because of changes in `TextInput`, `focusType="press"` for `KeyboardExtendedInput`  no longer works on Android.
-
-
-## New Release: Focus Lock and Focus Order
-Improved keyboard focus control with features like focus order, ordered links, and focus lock.
-
-|Android| iOS|
-|-|-|
-| <image alt="Android Focus Order Example" src="https://github.com/user-attachments/assets/8bae353e-cf4b-41f7-8796-fd1cceae5df5" height="400" />|  <image alt="iOS Focus Order Example" src="https://github.com/user-attachments/assets/51850cc6-9573-4ccb-b69c-14deefbb4b65" height="400"/> |
-
-<details>
-  <summary>More Information</summary>
-
-Advanced focus order functionality for Android and iOS, plus focus lock!
-
-It can be really challenging to manage focus in React Native, but fortunately, there are tools available to simplify the process.
-
-## Link Focus Order
-
-`Linking` components could be the most logical way to define focus order. By using properties such as `orderId` and `orderBackward`, `orderForward`, `orderLeft`, `orderRight`, `orderUp`, and `orderDown`, you can customize the focus order according to your needs.
-
-```tsx
-<View>
-  <Pressable
-    onPress={onPress}
-    orderId="0_0"
-    orderForward="0_2"
-  >
-    <Text>1</Text>
-  </Pressable>
-  <Pressable
-    onPress={onPress}
-    orderId="0_2"
-    orderBackward="0_1"
-  >
-    <Text>3</Text>
-  </Pressable>
-  <Pressable
-    onPress={onPress}
-    orderId="0_1"
-    orderForward="0_2"
-    orderBackward="0_0"
-  >
-    <Text>2</Text>
-  </Pressable>
-</View>
-```
+iOS | Android
+-- | --
+<img src="/.github/images/rnek-ios-example.gif" height="500" /> | <img src="/.github/images/rnek-android-example.gif" height="500" />
 
-You can find more examples here: [Focus Link Order](https://github.com/ArturKalach/react-native-external-keyboard/blob/release/0.6.0-rc/example/src/components/FocusOrderExample/FocusLinkOrder.tsx), [DPad Order](https://github.com/ArturKalach/react-native-external-keyboard/blob/release/0.6.0-rc/example/src/components/FocusOrderExample/FocusDPadOrder.tsx)
+## Features
 
-| Props | Description | Type |
-| :-- | :-- | :-- |
-| orderId? | A unique ID used for link target identification. | `string` |
-| orderBackward? | ID of the target for backward navigation with "Tab + Shift". | `string` |
-| orderForward? | ID of the target for forward navigation with "Tab". | `string` |
-| orderLeft? | ID of the target for navigation to the left. | `string` |
-| orderRight? | ID of the target for navigation to the right. | `string` |
-| orderUp? | ID of the target for navigation upward. | `string` |
-| orderDown? | ID of the target for navigation downward. | `string` |
+- Keyboard focus management and autofocus capabilities.
+- Key press event handling.
+- Focus management for `TextInput` and `Pressable` components.
+- Customization of the `Halo Effect` and `tintColor` for iOS.
+- Keyboard focus order.
+- Focus Lock.
 
-## Indexes Focus Order
+## New Release: Focus Lock
 
-Linking is one of the best ways to set up focus order. However, there may be cases where you need to define the order of multiple elements, such as groups. As an alternative solution, you can use Indexes.
+| iOS | Android |
+| :-- | :-- |
+| <img src="/.github/images/rnek-focus-lock-ios.gif" height="500" /> |  <img src="/.github/images/rnek-focus-lock-ios.gif" height="500" />  |
 
-```tsx
-<KeyboardOrderFocusGroup>
-  <View>
-    <Pressable
-      onPress={onPress}
-      orderIndex={0}
-    >
-      <Text>First</Text>
-    </Pressable>
-    <Pressable
-      onPress={onPress}
-      orderIndex={2}
-    >
-      <Text>Third</Text>
-    </Pressable>
-    <Pressable
-      onPress={onPress}
-      orderIndex={1}
-    >
-      <Text>Second</Text>
-    </Pressable>
-  </View>
-</KeyboardOrderFocusGroup>
-```
-Indexing requires `orderGroup` param for proper order set,  you can use `KeyboardOrderFocusGroup` or provide `orderGroup` to the component.
+> A new type of focus lock functionality has been introduced, featuring two new components: `Focus.Frame` and `Focus.Trap`. These components help manage and lock focus within specific areas of the screen.
 
-```tsx
- <Pressable
-      orderGroup="main"
-      onPress={onPress}
-      orderIndex={2}
-    >
-      <Text>Back</Text>
-  </Pressable>
-```
+<details>
+  <summary>More Information</summary>
 
-| Props | Description | Type |
-| :-- | :-- | :-- |
-| orderGroup? | The name of the group containing ordered elements. | `string` |
-| orderIndex? | The order index of the element within the group. | `number` |
+- On iOS, `Focus.Trap` uses the native `accessibilityViewIsModal` property to keep the focus within a defined area.
+- On Android, where no equivalent to `accessibilityViewIsModal` exists, custom logic has been implemented as a workaround. By default, Android uses a custom Activity or Modal to limit focus. While using a Modal is considered the best practice for focus locking on Android, some scenarios—such as issues with React Native's Modal or library-specific constraints—may require alternative implementations.
 
+#### How It Works
 
-You can find more examples here: [Focus Order via indexes](https://github.com/ArturKalach/react-native-external-keyboard/blob/release/0.6.0-rc/example/src/components/FocusOrderExample/FocusOrder.tsx)
+The focus lock functionality should be used as a pair:
 
-## Focus Lock
+- `Focus.Frame`: This component is used at the root level of a "screen" to detect focus leaks and ensure that focus remains contained.
+- `Focus.Trap`: This component wraps the content area where focus should be explicitly locked.
 
-Finally, you can lock focus to specific directions.
+| Prop | Description |
+| :-- | :-- |
+| ViewProps | Includes all standard React Native View properties, such as style, testID, etc. |
 
 ```tsx
- <Pressable
-  lockFocus={['down', 'right']}
->
-  <Text>Lock Example</Text>
-</Pressable>
+<Focus.Frame>
+  ...
+  <Focus.Trap>
+    <Text accessibilityRole="header">Locked Area</Text>
+    <Button
+      title="Confirm"
+      accessibilityLabel="Confirm action"
+    />
+  </Focus.Trap>
+  ...
+</Focus.Frame>
 ```
 
-
-| Props | Description | Type |
-| :-- | :-- | :-- |
-| lockFocus? | An array of directions to lock focus. | Array of 'left' | 'right' | 'up' | 'down' | 'forward' | 'backward' | 'first' | 'last' |
-
-> [!NOTE]
-> `first` and `last` are specific to `iOS`. When focus is blocked for `forward` and `backward` on iOS, it checks for the `last` and `first` elements to focus.
 </details>
 
-
-iOS | Android
--- | --
-<img src="/.github/images/rnek-ios-example.gif" height="500" /> | <img src="/.github/images/rnek-android-example.gif" height="500" />
-
-## Features
-
-- Keyboard focus management and autofocus capabilities.
-- Key press event handling.
-- Focus management for `TextInput` and `Pressable` components.
-- Customization of the `Halo Effect` and `tintColor` for iOS.
-- Keyboard focus order.
-
 ## Installation
 
 ```sh

package/android/src/main/java/com/externalkeyboard/ExternalKeyboardViewPackage.java

@@ -2,6 +2,7 @@ package com.externalkeyboard;
 
 
 import com.externalkeyboard.modules.ExternalKeyboardModule;
+import com.externalkeyboard.views.ExternalKeyboardLockView.ExternalKeyboardLockViewManager;
 import com.externalkeyboard.views.ExternalKeyboardView.ExternalKeyboardViewManager;
 import com.externalkeyboard.views.KeyboardFocusGroup.KeyboardFocusGroupManager;
 import com.externalkeyboard.views.TextInputFocusWrapper.TextInputFocusWrapperManager;
@@ -50,6 +51,7 @@ public class ExternalKeyboardViewPackage extends TurboReactPackage {
     viewManagers.add(new ExternalKeyboardViewManager());
     viewManagers.add(new TextInputFocusWrapperManager());
     viewManagers.add(new KeyboardFocusGroupManager());
+    viewManagers.add(new ExternalKeyboardLockViewManager());
 
     return viewManagers;
   }

package/android/src/main/java/com/externalkeyboard/helper/FocusHelper.java

@@ -7,6 +7,9 @@ import android.view.ViewGroup;
 import java.util.HashMap;
 import java.util.Map;
 
+import androidx.annotation.Nullable;
+import androidx.core.view.ViewCompat;
+
 public class FocusHelper {
   private static final int MASK_FOCUS_UP = 0b1;
   private static final int MASK_FOCUS_DOWN = 0b10;
@@ -60,4 +63,71 @@ public class FocusHelper {
 
     return null;
   }
+  public static boolean isAccessible(@Nullable View view) {
+    return view != null && ViewCompat.isImportantForAccessibility(view);
+  }
+
+  public static View findFirstAccessible(@Nullable ViewGroup viewGroup, boolean ignoreRoot) {
+    if (viewGroup == null) {
+      return null;
+    }
+
+    if (!ignoreRoot && isAccessible(viewGroup)) {
+      return viewGroup;
+    }
+
+    for (int i = 0; i < viewGroup.getChildCount(); i++) {
+      View child = viewGroup.getChildAt(i);
+      if (isAccessible(child)) {
+        return child;
+      }
+
+      if (child instanceof ViewGroup) {
+        View accessibleChild = findFirstAccessible((ViewGroup) child, true);
+        if (accessibleChild != null) {
+          return accessibleChild;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  public static View findFirstAccessible(@Nullable ViewGroup viewGroup) {
+    return findFirstAccessible(viewGroup, false);
+  }
+
+  public static View findFirstFocusable(@Nullable ViewGroup viewGroup, boolean ignoreRoot) {
+    if (viewGroup == null) {
+      return null;
+    }
+
+    if (!ignoreRoot && isKeyboardFocusable(viewGroup)) {
+      return viewGroup;
+    }
+
+    for (int i = 0; i < viewGroup.getChildCount(); i++) {
+      View child = viewGroup.getChildAt(i);
+      if (isKeyboardFocusable(child)) {
+        return child;
+      }
+
+      if (child instanceof ViewGroup) {
+        View focusableChild = findFirstFocusable((ViewGroup) child, true);
+        if (focusableChild != null) {
+          return focusableChild;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  public static View findFirstFocusable(@Nullable ViewGroup viewGroup) {
+    return findFirstFocusable(viewGroup, false);
+  }
+
+  private static boolean isKeyboardFocusable(View view) {
+    return view.isFocusable() && view.getVisibility() == View.VISIBLE && view.isEnabled();
+  }
 }

package/android/src/main/java/com/externalkeyboard/views/ExternalKeyboardLockView/ExternalKeyboardLockView.java

@@ -0,0 +1,115 @@
+package com.externalkeyboard.views.ExternalKeyboardLockView;
+
+import android.content.Context;
+import android.view.View;
+import android.view.ViewGroup;
+import android.view.accessibility.AccessibilityEvent;
+
+import com.externalkeyboard.helper.FocusHelper;
+import com.facebook.react.views.view.ReactViewGroup;
+
+public class ExternalKeyboardLockView extends ReactViewGroup {
+  private int componentType;
+  private Boolean lockDisable = false;
+
+  public ExternalKeyboardLockView(Context context) {
+    super(context);
+  }
+
+  public static boolean isParentOf(ViewGroup parent, View child) {
+    View current = child;
+    while (current.getParent() instanceof View) {
+      current = (View) current.getParent();
+      if (current == parent) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  public void setComponentType(int value) {
+    this.componentType = value;
+  }
+
+  public void setLockDisabled(boolean lockDisabled) {
+    this.lockDisable = lockDisabled;
+  }
+
+  @Override
+  public View focusSearch(View focused, int direction) {
+    try {
+      LockService lockService = LockService.getInstance();
+
+      if (componentType == 1) {
+        View keyboardView = lockService.getKeyboardView();
+        if (keyboardView != null && keyboardView != focused) {
+          return keyboardView;
+        }
+        return super.focusSearch(focused, direction);
+      }
+
+      if (componentType == 0) {
+        View nextView = super.focusSearch(focused, direction);
+        View result = isParentOf(this, nextView) ? nextView : focused;
+        lockService.setKeyboardView(result);
+        return result;
+      }
+
+      return super.focusSearch(focused, direction);
+    } catch (Exception e) {
+      return focused;
+    }
+  }
+
+  @Override
+  public boolean onRequestSendAccessibilityEvent(View child, AccessibilityEvent event) {
+    if (this.lockDisable) {
+      return super.onRequestSendAccessibilityEvent(child, event);
+    }
+
+    if (event.getEventType() != AccessibilityEvent.TYPE_VIEW_ACCESSIBILITY_FOCUSED) {
+      return super.onRequestSendAccessibilityEvent(child, event);
+    }
+
+    LockService lockService = LockService.getInstance();
+
+    if (componentType == 0) {
+      lockService.setView(child);
+      return false;
+    }
+
+    if (componentType == 1) {
+      View storedView = lockService.getView();
+      if (storedView != null && storedView != child) {
+        storedView.sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_FOCUSED);
+        return false;
+      }
+    }
+
+    return super.onRequestSendAccessibilityEvent(child, event);
+  }
+
+  @Override
+  protected void onAttachedToWindow() {
+    super.onAttachedToWindow();
+    this.post(this::focusFirstAccessible);
+  }
+
+  @Override
+  protected void onDetachedFromWindow() {
+    super.onDetachedFromWindow();
+    LockService.getInstance().clear();
+  }
+
+  private void focusFirstAccessible() {
+    View firstAccessible = FocusHelper.findFirstAccessible(this);
+    if (firstAccessible != null) {
+      firstAccessible.sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_FOCUSED);
+    }
+
+    View firstFocusable = FocusHelper.findFirstFocusable(this);
+    if (firstFocusable != null) {
+      firstFocusable.requestFocus();
+    }
+  }
+}

package/android/src/main/java/com/externalkeyboard/views/ExternalKeyboardLockView/ExternalKeyboardLockViewManager.java

@@ -0,0 +1,32 @@
+package com.externalkeyboard.views.ExternalKeyboardLockView;
+
+import com.facebook.react.module.annotations.ReactModule;
+import com.facebook.react.uimanager.ThemedReactContext;
+import com.facebook.react.uimanager.annotations.ReactProp;
+
+@ReactModule(name = ExternalKeyboardLockViewManager.NAME)
+public class ExternalKeyboardLockViewManager extends com.externalkeyboard.ExternalKeyboardLockViewManagerSpec<ExternalKeyboardLockView> {
+  public static final String NAME = "ExternalKeyboardLockView";
+
+  @Override
+  public String getName() {
+    return NAME;
+  }
+
+  @Override
+  public ExternalKeyboardLockView createViewInstance(ThemedReactContext context) {
+    return new ExternalKeyboardLockView(context);
+  }
+
+  @Override
+  @ReactProp(name = "componentType")
+  public void setComponentType(ExternalKeyboardLockView view, int value) {
+    view.setComponentType(value);
+  }
+
+  @Override
+  @ReactProp(name = "lockDisabled")
+  public void setLockDisabled(ExternalKeyboardLockView view, boolean value) {
+    view.setLockDisabled(value);
+  }
+}

package/android/src/main/java/com/externalkeyboard/views/ExternalKeyboardLockView/LockService.java

@@ -0,0 +1,44 @@
+package com.externalkeyboard.views.ExternalKeyboardLockView;
+
+import android.view.View;
+
+import java.lang.ref.WeakReference;
+
+public class LockService {
+  private static LockService instance;
+
+  private WeakReference<View> viewRef;
+  private WeakReference<View> keyboardViewRef;
+
+
+  private LockService() {
+  }
+
+  public static synchronized LockService getInstance() {
+    if (instance == null) {
+      instance = new LockService();
+    }
+    return instance;
+  }
+
+  public View getView() {
+    return viewRef != null ? viewRef.get() : null;
+  }
+
+  public void setView(View view) {
+    viewRef = new WeakReference<>(view);
+  }
+
+  public View getKeyboardView() {
+    return keyboardViewRef != null ? keyboardViewRef.get() : null;
+  }
+
+  public void setKeyboardView(View view) {
+    keyboardViewRef = new WeakReference<>(view);
+  }
+
+  public void clear() {
+    this.viewRef = null;
+    this.keyboardViewRef = null;
+  }
+}

package/android/src/newarch/ExternalKeyboardLockViewManagerSpec.java

@@ -0,0 +1,8 @@
+package com.externalkeyboard;
+
+import com.facebook.react.viewmanagers.ExternalKeyboardLockViewManagerInterface;
+import com.facebook.react.views.view.ReactViewGroup;
+import com.facebook.react.views.view.ReactViewManager;
+
+public abstract class ExternalKeyboardLockViewManagerSpec<T extends ReactViewGroup> extends ReactViewManager implements ExternalKeyboardLockViewManagerInterface<T> {
+}

package/android/src/oldarch/ExternalKeyboardLockViewManagerSpec.java

@@ -0,0 +1,12 @@
+package com.externalkeyboard;
+
+
+import com.externalkeyboard.views.ExternalKeyboardLockView.ExternalKeyboardLockView;
+import com.facebook.react.views.view.ReactViewManager;
+
+
+public abstract class ExternalKeyboardLockViewManagerSpec<T extends ExternalKeyboardLockView> extends ReactViewManager {
+  public abstract void setComponentType(T view, int value);
+  public abstract void setLockDisabled(T view, boolean value);
+}
+

package/ios/Delegates/RNCEKVFocusOrderDelegate/RNCEKVFocusGuideDelegate/RNCEKVFocusGuideDelegate.h

@@ -0,0 +1,36 @@
+//
+//  RNCEKVFocusGuideDelegate.h
+//  Pods
+//
+//  Created by Artur Kalach on 16/07/2025.
+//
+
+#ifndef RNCEKVFocusGuideDelegate_h
+#define RNCEKVFocusGuideDelegate_h
+
+#import <Foundation/Foundation.h>
+#import "RNCEKVFocusOrderProtocol.h"
+#import "RNCEKVFocusGuideHelper.h"
+
+@interface RNCEKVFocusGuideDelegate : NSObject
+
+- (instancetype _Nonnull)initWithView:(UIView<RNCEKVFocusOrderProtocol> *_Nonnull)view;
+
+//- (void)setLeftGuide:(UIView *_Nullable)view;
+//- (void)setRightGuide:(UIView *_Nullable)view;
+//- (void)setUpGuide:(UIView *_Nullable)view;
+//- (void)setDownGuide:(UIView *_Nullable)view;
+//
+//- (void)removeLeftGuide;
+//- (void)removeRightGuide;
+//- (void)removeUpGuide;
+//- (void)removeDownGuide;
+
+- (void)setIsFocused:(BOOL)value;
+
+- (void)setGuideFor:(RNCEKVFocusGuideDirection)direction withView: (UIView *_Nonnull)view;
+- (void)removeGuideFor:(RNCEKVFocusGuideDirection)direction;
+
+@end
+
+#endif /* RNCEKVFocusGuideDelegate_h */