react-native-external-keyboard 0.6.7 → 0.7.0-rc

package/README.md

@@ -5,152 +5,59 @@ 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.
+iOS | Android
+-- | --
+<img src="/.github/images/rnek-ios-example.gif" height="500" /> | <img src="/.github/images/rnek-android-example.gif" height="500" />
 
-```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>
-```
+## Features
 
-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)
+- 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.
 
-| 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` |
+## New Release: Focus Lock
 
-## Indexes Focus Order
+| iOS | Android |
+| :-- | :-- |
+| <img src="/.github/images/rnek-focus-lock-ios.gif" height="500" /> |  <img src="/.github/images/rnek-focus-lock-ios.gif" height="500" />  |
 
-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.
+> 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
-<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 requres `orderGroup` param for proper order set,  you can use `KeyboardOrderFocusGroup` or provide `orderGroup` to the component.
-
-```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
@@ -324,7 +231,7 @@ containerStyle | Style for the container | StyleProp<ViewStyle>
 containerFocusStyle?: | Style applied to the container when focused | `FocusStyle`
 tintType?: | Tint behavior type | `'default' \\| 'hover' \\| 'background' \\| 'none'`
 FocusHoverComponent?: | Component displayed on focus | `\\| ReactElement  \\| FunctionComponent  \\| (() => ReactElement);`
-onSubmitEditing?: | Extended `onSubmitEditing` for mulitline input | `(e: NativeSyntheticEvent<TextInputSubmitEditingEventData>) => void)`
+onSubmitEditing?: | Extended `onSubmitEditing` for multiline input | `(e: NativeSyntheticEvent<TextInputSubmitEditingEventData>) => void)`
 ...rest | Remaining TextInput props  | `TextInputProps`
 
 
@@ -336,7 +243,7 @@ import { KeyboardExtendedBaseView } from 'react-native-external-keyboard';
   <KeyboardExtendedBaseView
     onKeyDownPress={...}
     onKeyUpPress={...}
-    focussable
+    focusable
   >
     <Text>Content</Text>
   </KeyboardExtendedBaseView>

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/RNCEKVFocusDelegate/RNCEKVFocusDelegate.mm

@@ -13,46 +13,83 @@
 #import "RNCEKVFocusEffectUtility.h"
 
 @implementation RNCEKVFocusDelegate{
-    UIView<RNCEKVFocusProtocol>* _delegate;
+  UIView<RNCEKVFocusProtocol>* _delegate;
 }
 
 - (instancetype _Nonnull )initWithView:(UIView<RNCEKVFocusProtocol> *_Nonnull)delegate{
-    self = [super init];
-    if (self) {
-        _delegate = delegate;
+  self = [super init];
+  if (self) {
+    _delegate = delegate;
+  }
+  return self;
+}
+
+- (UIView*)getFirstFocusable:(UIView*)view {
+  if(view.subviews.count == 0) return nil;
+  UIView* child = view.subviews[0];
+  if(child.canBecomeFocused) {
+    return child;
+  } else {
+    return [self getFirstFocusable: child];
+  }
+}
+
+
+- (UIView *)focusingViewForGestureHandler {
+    UIView *view = _delegate.subviews.firstObject;
+    // Handle the special case for RNGestureHandlerButtonComponentView
+    if (view && [NSStringFromClass([view class]) isEqualToString:@"RNGestureHandlerButtonComponentView"] &&
+        view.subviews.count > 0) {
+        return view.subviews.firstObject;
+    }
+    return nil;
+}
+
+- (UIView *)firstObject {
+    UIView *firstChild = _delegate.subviews.firstObject;
+    if (firstChild && firstChild.canBecomeFocused) {
+        return firstChild;
     }
-    return self;
+    return nil;
 }
 
+
+
 // ToDo RNCEKV-2, Double check condition, count more then 1 means that a view can be a ViewGroup, bun when we use hover component it can be considered as ViewGroup instead of touchable component, it can be improved by flag, or by removing hover component from js implementation
-- (UIView*)getFocusingView {
-    if(_delegate.isGroup) {
+- (UIView *)getFocusingView {
+    if (_delegate.isGroup) {
         return _delegate;
     }
     
-    if(_delegate.subviews.count > 0 && _delegate.subviews[0].canBecomeFocused) {
-        return _delegate.subviews[0];
+    UIView *gestureHandlerView = [self focusingViewForGestureHandler];
+    if (gestureHandlerView) {
+        return gestureHandlerView;
+    }
+    
+    UIView *firstObject = [self firstObject];
+    if (firstObject) {
+        return firstObject;
     }
     
     return _delegate;
 }
 
 - (BOOL)canBecomeFocused {
-    if(!_delegate.canBeFocused) {
-        return false;
-    }
-    return [self getFocusingView] == _delegate;
+  if(!_delegate.canBeFocused) {
+    return false;
+  }
+  return [self getFocusingView] == _delegate;
 }
 
 - (NSNumber*)isFocusChanged:(UIFocusUpdateContext *)context {
-    UIView* view = [self getFocusingView];
-    if(context.nextFocusedView == view) {
-        return @YES;
-    } else if (context.previouslyFocusedView == view) {
-        return @NO;
-    }
-    
-    return nil;
+  UIView* view = [self getFocusingView];
+  if(context.nextFocusedView == view) {
+    return @YES;
+  } else if (context.previouslyFocusedView == view) {
+    return @NO;
+  }
+  
+  return nil;
 }
 
 

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 */