[Key handling] pass through all keys; allow specifying modifiers for validKeys[Down|Up]

Libraries/Components/Pressable/Pressable.js

@@ -26,6 +26,7 @@ import type {
   AccessibilityState,
   AccessibilityValue,
 } from '../View/ViewAccessibility';
+import type {HandledKeyboardEvent} from '../View/ViewPropTypes'; // [macOS]
 
 import {PressabilityDebugView} from '../../Pressability/PressabilityDebug';
 import usePressability from '../../Pressability/usePressability';
@@ -185,16 +186,27 @@ type Props = $ReadOnly<{|
   onKeyUp?: ?(event: KeyEvent) => void,
 
   /**
-   * Array of keys to receive key down events for
-   * For arrow keys, add "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown",
+   * When `true`, allows `onKeyDown` and `onKeyUp` to receive events not specified in
+   * `validKeysDown` and `validKeysUp`, respectively. Events matching `validKeysDown` and `validKeysUp`
+   * are still removed from the event queue, but the others are not.
+   *
+   * @platform macos
    */
-  validKeysDown?: ?Array<string>,
+  passthroughAllKeyEvents?: ?boolean,
 
   /**
-   * Array of keys to receive key up events for
-   * For arrow keys, add "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown",
+   * Array of keys to receive key down events for. These events have their default native behavior prevented.
+   *
+   * @platform macos
+   */
+  validKeysDown?: ?Array<string | HandledKeyboardEvent>,
+
+  /**
+   * Array of keys to receive key up events for. These events have their default native behavior prevented.
+   *
+   * @platform macos
    */
-  validKeysUp?: ?Array<string>,
+  validKeysUp?: ?Array<string | HandledKeyboardEvent>,
 
   /**
    * Specifies whether the view should receive the mouse down event when the

Libraries/Components/View/ReactNativeViewAttributes.js

@@ -47,6 +47,7 @@ const UIView = {
   onDrop: true,
   onKeyDown: true,
   onKeyUp: true,
+  passthroughAllKeyEvents: true,
   validKeysDown: true,
   validKeysUp: true,
   draggedTypes: true,

Libraries/Components/View/ViewPropTypes.js

@@ -100,22 +100,58 @@ type DirectEventProps = $ReadOnly<{|
 |}>;
 
 // [macOS
-type KeyboardEventProps = $ReadOnly<{|
+/**
+ * Represents a key that could be passed to `validKeysDown` and `validKeysUp`.
+ *
+ * `key` is the actual key, such as "a", or one of the special values:
+ * "Tab", "Escape", "Enter", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown",
+ * "Backspace", "Delete", "Home", "End", "PageUp", "PageDown".
+ *
+ * The rest are modifiers that when absent mean false.
+ *
+ * @platform macos
+ */
+export type HandledKeyboardEvent = $ReadOnly<{|
+  altKey?: ?boolean,
+  ctrlKey?: ?boolean,
+  metaKey?: ?boolean,
+  shiftKey?: ?boolean,
+  key: string,
+|}>;
+
+export type KeyboardEventProps = $ReadOnly<{|
+  /**
+   * Called after a key down event is detected.
+   */
   onKeyDown?: ?(event: KeyEvent) => void,
+
+  /**
+   * Called after a key up event is detected.
+   */
   onKeyUp?: ?(event: KeyEvent) => void,
+
+  /**
+   * When `true`, allows `onKeyDown` and `onKeyUp` to receive events not specified in
+   * `validKeysDown` and `validKeysUp`, respectively. Events matching `validKeysDown` and `validKeysUp`
+   * are still removed from the event queue, but the others are not.
+   *
+   * @platform macos
+   */
+  passthroughAllKeyEvents?: ?boolean,
+
   /**
-   * Array of keys to receive key down events for
+   * Array of keys to receive key down events for. These events have their default native behavior prevented.
    *
    * @platform macos
    */
-  validKeysDown?: ?Array<string>,
+  validKeysDown?: ?Array<string | HandledKeyboardEvent>,
 
   /**
-   * Array of keys to receive key up events for
+   * Array of keys to receive key up events for. These events have their default native behavior prevented.
    *
    * @platform macos
    */
-  validKeysUp?: ?Array<string>,
+  validKeysUp?: ?Array<string | HandledKeyboardEvent>,
 |}>;
 // macOS]
 

Libraries/NativeComponent/BaseViewConfig.macos.js

@@ -52,6 +52,7 @@ const validAttributesForNonEventProps = {
   draggedTypes: true,
   enableFocusRing: true,
   tooltip: true,
+  passthroughAllKeyEvents: true,
   validKeysDown: true,
   validKeysUp: true,
   mouseDownCanMoveWindow: true,

Libraries/Text/TextInput/Multiline/RCTUITextView.m

@@ -555,6 +555,14 @@ - (void)deleteBackward {
   }
 }
 #else // [macOS
+- (BOOL)performKeyEquivalent:(NSEvent *)event {
+  if (!self.hasMarkedText && ![self.textInputDelegate textInputShouldHandleKeyEvent:event]) {
+    return YES;
+  }
+
+  return [super performKeyEquivalent:event];
+}
+
 - (void)keyDown:(NSEvent *)event {
   // If has marked text, handle by native and return
   // Do this check before textInputShouldHandleKeyEvent as that one attempts to send the event to JS

Libraries/Text/TextInput/RCTBaseTextInputView.m

@@ -21,6 +21,7 @@
 #import <React/RCTTextSelection.h>
 #import <React/RCTUITextView.h> // [macOS]
 #import "../RCTTextUIKit.h" // [macOS]
+#import <React/RCTHandledKey.h> // [macOS]
 
 @implementation RCTBaseTextInputView {
   __weak RCTBridge *_bridge;
@@ -668,7 +669,8 @@ - (BOOL)textInputShouldHandleDeleteForward:(__unused id)sender {
 }
 
 - (BOOL)hasValidKeyDownOrValidKeyUp:(NSString *)key {
-  return [self.validKeysDown containsObject:key] || [self.validKeysUp containsObject:key];
+  return [RCTHandledKey key:key matchesFilter:self.validKeysDown]
+	||  [RCTHandledKey key:key matchesFilter:self.validKeysUp];
 }
 
 - (NSDragOperation)textInputDraggingEntered:(id<NSDraggingInfo>)draggingInfo

React/Base/RCTConvert.h

@@ -20,6 +20,8 @@
 #import <WebKit/WebKit.h>
 #endif
 
+@class RCTHandledKey; // [macOS]
+
 /**
  * This class provides a collection of conversion functions for mapping
  * JSON objects to native types and classes. These are useful when writing
@@ -147,6 +149,8 @@ typedef BOOL css_backface_visibility_t;
 
 #if TARGET_OS_OSX // [macOS
 + (NSString *)accessibilityRoleFromTraits:(id)json;
+
++ (NSArray<RCTHandledKey *> *)RCTHandledKeyArray:(id)json;
 #endif // macOS]
 @end
 

React/Base/RCTConvert.m

@@ -12,6 +12,7 @@
 #import <CoreText/CoreText.h>
 
 #import "RCTDefines.h"
+#import "RCTHandledKey.h" // [macOS]
 #import "RCTImageSource.h"
 #import "RCTParserUtils.h"
 #import "RCTUtils.h"
@@ -1500,6 +1501,9 @@ + (NSString *)accessibilityRoleFromTraits:(id)json
   }
   return NSAccessibilityUnknownRole;
 }
+
+RCT_JSON_ARRAY_CONVERTER(RCTHandledKey);
+
 #endif // macOS]
 
 @end

React/Views/RCTHandledKey.h

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// [macOS]
+
+#if TARGET_OS_OSX
+#import <React/RCTConvert.h>
+
+// This class is used for specifying key filtering e.g. for -[RCTView validKeysDown] and -[RCTView validKeysUp]
+// Also see RCTViewKeyboardEvent, which is a React representation of an actual NSEvent that is dispatched to JS.
+@interface RCTHandledKey : NSObject
+
++ (BOOL)event:(NSEvent *)event matchesFilter:(NSArray<RCTHandledKey *> *)filter;
++ (BOOL)key:(NSString *)key matchesFilter:(NSArray<RCTHandledKey *> *)filter;
+
+- (instancetype)initWithKey:(NSString *)key;
+- (BOOL)matchesEvent:(NSEvent *)event;
+
+@property (nonatomic, copy) NSString *key;
+
+// For the following modifiers, nil means we don't care about the presence of the modifier when filtering the key
+// They are still expected to be only boolean when not nil.
+@property (nonatomic, assign) NSNumber *altKey;
+@property (nonatomic, assign) NSNumber *ctrlKey;
+@property (nonatomic, assign) NSNumber *metaKey;
+@property (nonatomic, assign) NSNumber *shiftKey;
+
+@end
+
+@interface RCTConvert (RCTHandledKey)
+
++ (RCTHandledKey *)RCTHandledKey:(id)json;
+
+@end
+
+#endif

React/Views/RCTHandledKey.m

@@ -0,0 +1,145 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// [macOS]
+
+#import "objc/runtime.h"
+#import <React/RCTAssert.h>
+#import <React/RCTUtils.h>
+#import <RCTConvert.h>
+#import <RCTHandledKey.h>
+#import <RCTViewKeyboardEvent.h>
+
+#if TARGET_OS_OSX
+
+@implementation RCTHandledKey
+
++ (NSArray<NSString *> *)validModifiers {
+  // keep in sync with actual properties and RCTViewKeyboardEvent
+  return @[@"altKey", @"ctrlKey", @"metaKey", @"shiftKey"];
+}
+
++ (BOOL)event:(NSEvent *)event matchesFilter:(NSArray<RCTHandledKey *> *)filter {
+  for (RCTHandledKey *key in filter) {
+	if ([key matchesEvent:event]) {
+	  return YES;
+	}
+  }
+
+  return NO;
+}
+
++ (BOOL)key:(NSString *)key matchesFilter:(NSArray<RCTHandledKey *> *)filter {
+  for (RCTHandledKey *aKey in filter) {
+	if ([[aKey key] isEqualToString:key]) {
+	  return YES;
+	}
+  }
+
+  return NO;
+}
+
+- (instancetype)initWithKey:(NSString *)key {
+  if ((self = [super init])) {
+    self.key = key;
+  }
+  return self;
+}
+
+- (BOOL)matchesEvent:(NSEvent *)event
+{
+  NSEventType type = [event type];
+  if (type != NSEventTypeKeyDown && type != NSEventTypeKeyUp) {
+    RCTFatal(RCTErrorWithMessage([NSString stringWithFormat:@"Wrong event type (%d) sent to -[RCTHandledKey matchesEvent:]", (int)type]));
+    return NO;
+  }
+
+  NSDictionary *body = [RCTViewKeyboardEvent bodyFromEvent:event];
+  NSString *key = body[@"key"];
+  if (key == nil) {
+    RCTFatal(RCTErrorWithMessage(@"Event body has missing value for 'key'"));
+    return NO;
+  }
+
+  if (![key isEqualToString:self.key]) {
+    return NO;
+  }
+
+  NSArray<NSString *> *modifiers = [RCTHandledKey validModifiers];
+  for (NSString *modifier in modifiers) {
+    NSNumber *myValue = [self valueForKey:modifier];
+
+    if (myValue == nil) {
+		continue;
+	}
+
+	NSNumber *eventValue = (NSNumber *)body[modifier];
+	if (eventValue == nil) {
+		RCTFatal(RCTErrorWithMessage([NSString stringWithFormat:@"Event body has missing value for '%@'", modifier]));
+		return NO;
+	}
+
+	if (![eventValue isKindOfClass:[NSNumber class]]) {
+		RCTFatal(RCTErrorWithMessage([NSString stringWithFormat:@"Event body has unexpected value of class '%@' for '%@'",
+			NSStringFromClass(object_getClass(eventValue)), modifier]));
+		return NO;
+    }
+
+	if (![myValue isEqualToNumber:body[modifier]]) {
+		return NO;
+	}
+  }
+
+  return YES;  // keys matched; all present modifiers matched
+}
+
+@end
+
+@implementation RCTConvert (RCTHandledKey)
+
++ (RCTHandledKey *)RCTHandledKey:(id)json
+{
+  // legacy way of specifying validKeysDown and validKeysUp -- here we ignore the modifiers when comparing to the NSEvent
+  if ([json isKindOfClass:[NSString class]]) {
+    return [[RCTHandledKey alloc] initWithKey:(NSString *)json];
+  }
+
+  // modern way of specifying validKeys and validKeysUp -- here we assume missing modifiers to mean false\NO
+  if ([json isKindOfClass:[NSDictionary class]]) {
+    NSDictionary *dict = (NSDictionary *)json;
+    NSString *key = dict[@"key"];
+    if (key == nil) {
+      RCTLogConvertError(dict, @"a RCTHandledKey -- must include \"key\"");
+      return nil;
+    }
+
+	RCTHandledKey *handledKey = [[RCTHandledKey alloc] initWithKey:key];
+    NSArray<NSString *> *modifiers = RCTHandledKey.validModifiers;
+    for (NSString *key in modifiers) {
+      id value = dict[key];
+      if (value == nil) {
+        value = @NO;	// assume NO -- instead of nil i.e. "don't care" unlike the string case above.
+	  }
+
+      if (![value isKindOfClass:[NSNumber class]]) {
+        RCTLogConvertError(value, @"a boolean");
+        return nil;
+      }
+
+      [handledKey setValue:@([(NSNumber *)value boolValue]) forKey:key];
+    }
+
+    return handledKey;
+  }
+
+  RCTLogConvertError(json, @"a RCTHandledKey -- allowed types are string and object");
+  return nil;
+}
+
+@end
+
+#endif