react-native-external-keyboard 0.9.1 → 1.0.0

package/src/components/KeyboardFocusView/KeyboardFocusView.tsx

@@ -1,31 +1,20 @@
 import React, { useMemo } from 'react';
-import { View, StyleSheet, Platform } from 'react-native';
-import type { KeyboardFocusViewProps } from '../../types/KeyboardFocusView.types';
-import { BaseKeyboardView } from '../BaseKeyboardView/BaseKeyboardView';
+import { Platform } from 'react-native';
 import type {
+  KeyboardFocusViewProps,
   BaseKeyboardViewType,
   KeyboardFocus,
-} from '../../types/BaseKeyboardView';
-import type { TintType } from '../../types/WithKeyboardFocus';
-import {
-  type RenderProp,
-  RenderPropComponent,
-} from '../RenderPropComponent/RenderPropComponent';
-import { useFocusStyle } from '../../utils/useFocusStyle';
-import { useKeyboardPress } from '../../utils/useKeyboardPress/useKeyboardPress';
+} from '../../types';
+import { BaseKeyboardView } from '../BaseKeyboardView/BaseKeyboardView';
+import { useKeyboardFocusContainer } from '../../utils/useKeyboardFocusContainer';
 import { IsViewFocusedContext } from '../../context/IsViewFocusedContext';
 
 export const KeyboardFocusView = React.forwardRef<
   BaseKeyboardViewType | KeyboardFocus,
-  KeyboardFocusViewProps & {
-    tintType?: TintType;
-    FocusHoverComponent?: RenderProp;
-    withView?: boolean;
-  }
+  KeyboardFocusViewProps
 >(
   (
     {
-      tintType = 'default',
       autoFocus,
       focusStyle,
       style,
@@ -34,15 +23,13 @@ export const KeyboardFocusView = React.forwardRef<
       onLongPress,
       onKeyUpPress,
       onKeyDownPress,
-      group = false,
+      focusableWrapper = false,
       haloEffect = true,
-      canBeFocused = true,
-      focusable = true,
-      withView = true, //ToDo RNCEKV-9 update and rename Discussion #63
+      focusable,
+      withView = true,
       tintColor,
       onFocus,
       onBlur,
-      FocusHoverComponent,
       children,
       accessible,
       triggerCodes,
@@ -51,81 +38,55 @@ export const KeyboardFocusView = React.forwardRef<
     },
     ref
   ) => {
-    const { focused, containerFocusedStyle, onFocusChangeHandler, hoverColor } =
-      useFocusStyle({
-        onFocusChange,
-        tintColor,
-        containerFocusStyle: focusStyle,
-        tintType,
-      });
-
-    const withHaloEffect = tintType === 'default' && haloEffect;
-
-    const { onKeyUpPressHandler, onKeyDownPressHandler } = useKeyboardPress({
+    const {
+      focused,
+      containerFocusedStyle,
+      onFocusChangeHandler,
+      onKeyUpPressHandler,
+      onKeyDownPressHandler,
+    } = useKeyboardFocusContainer({
+      onFocusChange,
+      containerFocusStyle: focusStyle,
       onKeyUpPress,
       onKeyDownPress,
       onPress,
       onLongPress,
       triggerCodes,
-      disabled: (props as { disabled?: boolean })?.disabled,
     });
 
-    const HoverComonent = useMemo(() => {
-      if (FocusHoverComponent) return FocusHoverComponent;
-      if (tintType === 'hover')
-        return <View style={[hoverColor, styles.absolute, styles.opacity]} />;
-
-      return undefined;
-    }, [FocusHoverComponent, hoverColor, tintType]);
+    const a11y =
+      (Platform.OS === 'android' && withView && accessible !== false) ||
+      accessible;
 
-    const a11y = useMemo(() => {
-      return (
-        (Platform.OS === 'android' && withView && accessible !== false) ||
-        accessible
-      );
-    }, [accessible, withView]);
+    const containerStyleArr = useMemo(
+      () => [style, containerFocusedStyle],
+      [style, containerFocusedStyle]
+    );
 
     return (
       <IsViewFocusedContext.Provider value={focused}>
         <BaseKeyboardView
-          style={[style, containerFocusedStyle]}
-          ref={ref}
+          style={containerStyleArr}
+          ref={ref as React.Ref<BaseKeyboardViewType>}
           onKeyUpPress={onKeyUpPressHandler}
           onKeyDownPress={onKeyDownPressHandler}
           onFocus={onFocus}
           onBlur={onBlur}
           onFocusChange={onFocusChangeHandler}
           onContextMenuPress={onLongPress}
-          haloEffect={withHaloEffect}
+          haloEffect={haloEffect}
           defaultFocusHighlightEnabled={defaultFocusHighlightEnabled}
           autoFocus={autoFocus}
-          canBeFocused={canBeFocused}
           focusable={focusable}
           tintColor={tintColor}
-          group={group}
+          focusableWrapper={focusableWrapper}
           accessible={a11y}
           enableContextMenu={Boolean(onLongPress)}
           {...props}
         >
           {children}
-          {focused && HoverComonent && (
-            <RenderPropComponent render={HoverComonent} />
-          )}
         </BaseKeyboardView>
       </IsViewFocusedContext.Provider>
     );
   }
 );
-
-const styles = StyleSheet.create({
-  absolute: {
-    position: 'absolute',
-    top: 0,
-    left: 0,
-    right: 0,
-    bottom: 0,
-  },
-  opacity: {
-    opacity: 0.3,
-  },
-});

package/src/components/Touchable/Pressable.tsx

@@ -6,11 +6,11 @@ import {
 } from 'react-native';
 
 import { withKeyboardFocus } from '../../utils/withKeyboardFocus';
-import type { WithKeyboardPropsTypeDeclaration } from '../../types/WithKeyboardFocus';
+import type { WithKeyboardFocusPropsWithRef } from '../../types';
 
 export const Pressable = withKeyboardFocus(RNPressable);
 
-export type KeyboardPressableProps = WithKeyboardPropsTypeDeclaration<
+export type KeyboardPressableProps = WithKeyboardFocusPropsWithRef<
   PressableProps,
   ViewProps['style'],
   View

package/src/components/index.ts

@@ -7,3 +7,15 @@ export {
   KeyboardFocusView,
   KeyboardFocusView as KeyboardExtendedView,
 } from './KeyboardFocusView';
+export { KeyboardFocusGroup } from './KeyboardFocusGroup/KeyboardFocusGroup';
+export {
+  KeyboardExtendedInput,
+  KeyboardExtendedInput as TextInput,
+} from './KeyboardExtendedInput/KeyboardExtendedInput';
+export {
+  Pressable,
+  Pressable as KeyboardExtendedPressable,
+  type KeyboardPressableProps,
+} from './Touchable/Pressable';
+export { FocusFrame } from './KeyboardFocusLock/FocusFrame/FocusFrame';
+export { FocusTrap } from './KeyboardFocusLock/FocusTrap/FocusTrap';

package/src/index.tsx

@@ -1,49 +1,53 @@
-import { FocusFrame } from './components/KeyboardFocusLock/FocusFrame/FocusFrame';
-import { FocusTrap } from './components/KeyboardFocusLock/FocusTrap/FocusTrap';
+import {
+  FocusFrame,
+  FocusTrap,
+  KeyboardFocusView,
+  KeyboardExtendedInput,
+  Pressable,
+} from './components';
+import * as Keyboard from './modules/Keyboard';
 
+// Native spec
 export {
   ExternalKeyboardViewNative,
   TextInputFocusWrapperNative,
   type KeyPress,
 } from './nativeSpec';
 
-export type {
-  OnKeyPress,
-  KeyboardFocus,
-  BaseKeyboardViewType as KeyboardExtendedViewType,
-} from './types/BaseKeyboardView';
-
-export type {
-  TintType,
-  WithKeyboardFocusDeclaration,
-  WithKeyboardPropsTypeDeclaration,
-  WithKeyboardFocus,
-} from './types/WithKeyboardFocus';
-
+// Components
 export {
   BaseKeyboardView,
+  BaseKeyboardView as ExternalKeyboardView,
+  BaseKeyboardView as KeyboardExtendedBaseView,
   KeyboardFocusView,
-  ExternalKeyboardView,
-  KeyboardExtendedView,
-  KeyboardExtendedBaseView,
-} from './components';
-export {
+  KeyboardFocusView as KeyboardExtendedView,
+  KeyboardFocusGroup,
+  KeyboardExtendedInput,
+  KeyboardExtendedInput as TextInput,
   Pressable,
   Pressable as KeyboardExtendedPressable,
-  type KeyboardPressableProps,
-} from './components/Touchable/Pressable';
+} from './components';
 
+// Types
 export {
-  KeyboardExtendedInput,
-  KeyboardExtendedInput as TextInput,
-} from './components/KeyboardExtendedInput/KeyboardExtendedInput';
-export type {
-  KeyboardInputPropsDeclaration,
-  KeyboardInputProps,
-  ExtraKeyboardProps,
-} from './components/KeyboardExtendedInput/KeyboardExtendedInput.types';
+  LockComponentType,
+  type OnKeyPress,
+  type OnKeyPressFn,
+  type KeyboardFocus,
+  type OnFocusChangeFn,
+  type BaseKeyboardViewType,
+  type WithKeyboardFocusProps,
+  type WithKeyboardFocusPropsWithRef,
+  type KeyboardFocusableComponent,
+  type KeyboardFocusableComponentDeclaration,
+  type KeyboardFocusLockProps,
+  type KeyboardInputPropsDeclaration,
+  type KeyboardInputProps,
+  type ExtraKeyboardProps,
+} from './types';
+export type { KeyboardPressableProps } from './components';
 
-export { KeyboardFocusGroup } from './components/KeyboardFocusGroup/KeyboardFocusGroup';
+// Hooks & context
 export { withKeyboardFocus } from './utils/withKeyboardFocus';
 export { useIsViewFocused } from './context/IsViewFocusedContext';
 export {
@@ -51,10 +55,18 @@ export {
   OrderFocusGroupContext,
   useOrderFocusGroup,
 } from './context/OrderFocusContext';
-import * as Keyboard from './modules/Keyboard';
+
+// Modules
 export { Keyboard };
 
+// Namespaces
 export const Focus = {
   Frame: FocusFrame,
   Trap: FocusTrap,
 };
+
+export const K = {
+  Input: KeyboardExtendedInput,
+  View: KeyboardFocusView,
+  Pressable,
+};

package/src/nativeSpec/ExternalKeyboardLockViewNativeComponent.ts

@@ -1,7 +1,5 @@
-import type { ViewProps } from 'react-native';
+import { codegenNativeComponent, type ViewProps } from 'react-native';
 import type { Int32 } from 'react-native/Libraries/Types/CodegenTypes';
-// eslint-disable-next-line @react-native/no-deep-imports
-import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
 
 export interface ExternalKeyboardLockViewNativeComponentProps
   extends ViewProps {

package/src/nativeSpec/ExternalKeyboardViewNativeComponent.ts

@@ -1,4 +1,9 @@
-import type { ColorValue, ViewProps } from 'react-native';
+import {
+  codegenNativeComponent,
+  codegenNativeCommands,
+  type ColorValue,
+  type ViewProps,
+} from 'react-native';
 import type {
   BubblingEventHandler,
   DirectEventHandler,
@@ -6,10 +11,6 @@ import type {
   Int32,
 } from 'react-native/Libraries/Types/CodegenTypes';
 import type { ComponentType } from 'react';
-// eslint-disable-next-line @react-native/no-deep-imports
-import codegenNativeCommands from 'react-native/Libraries/Utilities/codegenNativeCommands';
-// eslint-disable-next-line @react-native/no-deep-imports
-import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
 
 export type FocusChange = Readonly<{
   isFocused: boolean;
@@ -48,10 +49,10 @@ export interface ExternalKeyboardNativeProps extends ViewProps {
   haloCornerRadius?: Float;
   haloExpendX?: Float;
   haloExpendY?: Float;
+  roundedHaloFix?: boolean;
   tintColor?: ColorValue;
-  group?: boolean;
+  focusableWrapper?: boolean;
   groupIdentifier?: string;
-  enableA11yFocus?: boolean;
   screenAutoA11yFocus?: boolean;
   screenAutoA11yFocusDelay?: Int32;
   orderGroup?: string;
@@ -71,11 +72,13 @@ export interface ExternalKeyboardNativeProps extends ViewProps {
 
 export interface NativeCommands {
   // @ts-ignore
-  focus: (viewRef: React.ElementRef<ComponentType>) => void;
+  rnekKeyboardFocus: (viewRef: React.ElementRef<ComponentType>) => void;
+  // @ts-ignore
+  rnekScreenReaderFocus: (viewRef: React.ElementRef<ComponentType>) => void;
 }
 
 export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
-  supportedCommands: ['focus'],
+  supportedCommands: ['rnekKeyboardFocus', 'rnekScreenReaderFocus'],
 });
 
 export default codegenNativeComponent<ExternalKeyboardNativeProps>(

package/src/nativeSpec/KeyboardFocusGroupNativeComponent.ts

@@ -1,7 +1,9 @@
-import type { ViewProps, ColorValue } from 'react-native';
+import {
+  codegenNativeComponent,
+  type ViewProps,
+  type ColorValue,
+} from 'react-native';
 import type { DirectEventHandler } from 'react-native/Libraries/Types/CodegenTypes';
-// eslint-disable-next-line @react-native/no-deep-imports
-import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
 
 export type FocusChange = Readonly<{
   isFocused: boolean;

package/src/nativeSpec/TextInputFocusWrapperNativeComponent.ts

@@ -1,11 +1,13 @@
-import type { ViewProps, ColorValue } from 'react-native';
+import {
+  codegenNativeComponent,
+  type ViewProps,
+  type ColorValue,
+} from 'react-native';
 import type {
   DirectEventHandler,
   Float,
   Int32,
 } from 'react-native/Libraries/Types/CodegenTypes';
-// eslint-disable-next-line @react-native/no-deep-imports
-import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
 
 export type FocusChange = Readonly<{
   isFocused: boolean;
@@ -21,10 +23,12 @@ export interface TextInputFocusWrapperNativeComponent extends ViewProps {
   focusType?: Int32;
   blurType?: Int32;
   canBeFocused?: boolean;
+  hasOnFocusChanged?: boolean;
   haloEffect?: boolean;
   haloCornerRadius?: Float;
   haloExpendX?: Float;
   haloExpendY?: Float;
+  roundedHaloFix?: boolean;
   tintColor?: ColorValue;
   blurOnSubmit?: boolean;
   multiline?: boolean;

package/src/types/KeyboardFocusLock.types.ts

@@ -1,7 +1,22 @@
 import type { ViewProps } from 'react-native';
 
+/**
+ * Native role for a KeyboardFocusLock component on Android.
+ * iOS does not consume this value.
+ *
+ * Values must match the constants in
+ * `android/src/main/java/com/externalkeyboard/views/ExternalKeyboardLockView/ExternalKeyboardLockView.java`.
+ */
+export enum LockComponentType {
+  Trap = 0,
+  Frame = 1,
+}
+
 export type KeyboardFocusLockProps = ViewProps & {
-  componentType?: number;
+  /** Native role of the lock — `Trap` (containment) or `Frame` (leak detection). */
+  componentType?: LockComponentType;
+  /** When `true`, disables the lock without unmounting the component. */
   lockDisabled?: boolean;
+  /** When `true`, forces focus containment even when it would otherwise be allowed to leave. */
   forceLock?: boolean;
 };

package/src/types/KeyboardFocusView.types.ts

@@ -1,29 +1,28 @@
-import type { NativeSyntheticEvent, GestureResponderEvent } from 'react-native';
-import type { FocusStyle } from './FocusStyle';
+import type { GestureResponderEvent } from 'react-native';
+import type { FocusStyle } from './focusStyle.types';
 import type {
   BaseFocusViewProps,
   BaseKeyboardViewProps,
-  OnKeyPress,
-} from './BaseKeyboardView';
-
-export type KeyboardFocusEvent = NativeSyntheticEvent<{
-  isFocused: boolean;
-}>;
-
-export type OnFocusChangeFn = (e: KeyboardFocusEvent) => void;
-
-export type FocusStateCallbackType = {
-  readonly focused: boolean;
-};
+} from './baseKeyboardView.types';
+import type { OnKeyPress } from './keyPress.types';
 
 export type FocusViewProps = {
-  exposeMethods?: string[];
+  /** Key codes that trigger `onPress` / `onLongPress`. Defaults to spacebar and enter. */
   triggerCodes?: number[];
+  /** Style applied to the inner component while focused. */
   focusStyle?: FocusStyle;
+  /** Called on press — from touch (`GestureResponderEvent`) or physical key ({@link OnKeyPress}). */
   onPress?: (e: GestureResponderEvent | OnKeyPress) => void;
+  /** Called on long press — from touch (`GestureResponderEvent`) or physical key ({@link OnKeyPress}). */
   onLongPress?: (e?: GestureResponderEvent | OnKeyPress) => void;
-  onFocus?: () => void;
-  onBlur?: () => void;
 } & BaseFocusViewProps;
 
-export type KeyboardFocusViewProps = BaseKeyboardViewProps & FocusViewProps;
+export type KeyboardFocusViewProps = BaseKeyboardViewProps &
+  FocusViewProps & {
+    /**
+     * Wraps children in an extra native view.
+     *
+     * @see https://github.com/anfedorov/react-native-external-keyboard/discussions/63
+     */
+    withView?: boolean;
+  };

package/src/types/baseKeyboardView.types.ts

@@ -0,0 +1,122 @@
+import type { ViewProps, ColorValue } from 'react-native';
+import type { OnFocusChangeFn } from './focus.types';
+import type { OnKeyPressFn } from './keyPress.types';
+import type { FocusOrderProps, LockFocusType } from './focusOrder.types';
+
+/** Focus props shared by every keyboard-focusable component. */
+export type CommonFocusProps = {
+  /** Whether the component can receive keyboard focus. Defaults to `true`. */
+  focusable?: boolean;
+  /**
+   * Enables the halo highlight ring drawn around the component on focus.
+   *
+   * @platform ios
+   */
+  haloEffect?: boolean;
+  /**
+   * Keeps a disabled halo (`haloEffect={false}`) suppressed on views that have
+   * a `borderRadius`. UIKit re-arms the halo from the view's
+   * `layer.cornerRadius` (set by RN from `borderRadius`) on every layout pass,
+   * so the halo can reappear after being disabled; this watches layout changes
+   * and resets the focus effect each pass. Only takes effect when
+   * `haloEffect={false}`. Alternatively, move `borderRadius` to `containerStyle`
+   * so the focused view itself stays square.
+   *
+   * @platform ios
+   */
+  roundedHaloFix?: boolean;
+  /** Color used to tint the component on focus. */
+  tintColor?: ColorValue;
+  /**
+   * iOS `focusGroupIdentifier` — the identifier of the focus group this view belongs to.
+   *
+   * @platform ios
+   */
+  groupIdentifier?: string;
+  /** Directions in which focus movement is locked. See {@link LockFocusType}. */
+  lockFocus?: LockFocusType[];
+  /**
+   * Enables Android's default focus highlight for the focused native view.
+   *
+   * @platform android
+   * @default true
+   */
+  defaultFocusHighlightEnabled?: boolean;
+  /**
+   * Cross-platform focus highlight mode. `'none'` disables the focus highlight
+   * entirely — the iOS halo and the Android default highlight — equivalent to
+   * `haloEffect={false}` / `defaultFocusHighlightEnabled={false}`. `'default'`
+   * (the default) keeps the platform highlight.
+   *
+   * @default 'default'
+   */
+  tintType?: 'default' | 'none';
+};
+
+export type BaseFocusViewProps = {
+  /** Treats the view as a transparent focus wrapper rather than a focusable target itself. */
+  focusableWrapper?: boolean;
+  /** Called when the component gains or loses keyboard focus. */
+  onFocusChange?: OnFocusChangeFn;
+  /** Handler for the physical key-up event. */
+  onKeyUpPress?: OnKeyPressFn;
+  /** Handler for the physical key-down event. */
+  onKeyDownPress?: OnKeyPressFn;
+  /**
+   * Handler for long-press events triggered by the context-menu command.
+   *
+   * @platform ios
+   */
+  onContextMenuPress?: () => void;
+  /**
+   * Bubbling variant of {@link BaseFocusViewProps.onContextMenuPress} — fires for
+   * context-menu presses that bubble up from descendants.
+   *
+   * @platform ios
+   */
+  onBubbledContextMenuPress?: () => void;
+  /** Whether the component should automatically gain focus on mount. */
+  autoFocus?: boolean;
+  /** Called when the component gains keyboard focus. */
+  onFocus?: () => void;
+  /** Called when the component loses keyboard focus. */
+  onBlur?: () => void;
+  /**
+   * Corner radius of the halo ring, in points.
+   *
+   * @platform ios
+   */
+  haloCornerRadius?: number;
+  /**
+   * Horizontal expansion of the halo ring beyond the view bounds, in points.
+   *
+   * @platform ios
+   */
+  haloExpendX?: number;
+  /**
+   * Vertical expansion of the halo ring beyond the view bounds, in points.
+   *
+   * @platform ios
+   */
+  haloExpendY?: number;
+  /** Enables the context-menu interaction on the view. */
+  enableContextMenu?: boolean;
+  /** Enables moving screen reader focus to this component automatically. */
+  screenAutoA11yFocus?: boolean;
+  /**
+   * Delay before screen reader auto-focus is applied. On Android focus can only be
+   * applied after render, which may take 300–500 ms.
+   *
+   * @platform android
+   * @default 300
+   */
+  screenAutoA11yFocusDelay?: number;
+  /**
+   * @deprecated No longer has any effect — kept only for backwards compatibility.
+   */
+  enableA11yFocus?: boolean;
+} & CommonFocusProps &
+  FocusOrderProps;
+
+/** Props for `BaseKeyboardView` — standard `ViewProps` plus all focus props. */
+export type BaseKeyboardViewProps = ViewProps & BaseFocusViewProps;

package/src/types/focus.types.ts

@@ -0,0 +1,40 @@
+import type { HostInstance, NativeSyntheticEvent } from 'react-native';
+
+/**
+ * Handler invoked when a view gains or loses keyboard focus.
+ *
+ * @param isFocused `true` on focus, `false` on blur.
+ * @param tag Native view tag of the affected element, when available.
+ */
+export type OnFocusChangeFn = (isFocused: boolean, tag?: number) => void;
+
+/** Imperative focus handle exposed via `ref` on keyboard-focusable components. */
+export type KeyboardFocusHandle = {
+  /** Moves both physical-keyboard and screen-reader focus to this element. */
+  focus: () => void;
+  /** Moves physical-keyboard focus to this element. */
+  keyboardFocus: () => void;
+  /** Moves screen reader (VoiceOver / TalkBack) focus to this element. */
+  screenReaderFocus: () => void;
+};
+
+/**
+ * The underlying native view instance augmented with the imperative
+ * {@link KeyboardFocusHandle}. Uses RN's `HostInstance` (the host view ref —
+ * `measure`, `measureInWindow`, `setNativeProps`, …) rather than the `View`
+ * component type, so it resolves correctly under both the legacy and strict
+ * (`react-native-strict-api`) RN type sets.
+ */
+export type KeyboardFocus = HostInstance & KeyboardFocusHandle;
+
+/** Alias of {@link KeyboardFocus}. */
+export type BaseKeyboardViewType = KeyboardFocus;
+
+/** Native event payload emitted by the view's focus-change callback. */
+export type KeyboardFocusEvent = NativeSyntheticEvent<{
+  isFocused: boolean;
+  target?: number;
+}>;
+
+/** Handler receiving the raw {@link KeyboardFocusEvent} from the native view. */
+export type NativeFocusChangeHandler = (e: KeyboardFocusEvent) => void;