feedback #2

Author: nakambo

Libraries/Components/Pressable/Pressable.js

@@ -195,14 +195,14 @@ type Props = $ReadOnly<{|
   passthroughAllKeyEvents?: ?boolean,
 
   /**
-   * Array of keys to receive key down events for. These events are always removed from the system event queue.
+   * 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 are always removed from the system event queue.
+   * Array of keys to receive key up events for. These events have their default native behavior prevented.
    *
    * @platform macos
    */

Libraries/Components/View/ViewPropTypes.js

@@ -140,14 +140,14 @@ export type KeyboardEventProps = $ReadOnly<{|
   passthroughAllKeyEvents?: ?boolean,
 
   /**
-   * Array of keys to receive key down events for. These events are always removed from the system event queue.
+   * 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 are always removed from the system event queue.
+   * Array of keys to receive key up events for. These events have their default native behavior prevented.
    *
    * @platform macos
    */

Libraries/Text/TextInput/RCTBaseTextInputView.m

@@ -21,7 +21,7 @@
 #import <React/RCTTextSelection.h>
 #import <React/RCTUITextView.h> // [macOS]
 #import "../RCTTextUIKit.h" // [macOS]
-#import "RCTHandledKey.h" // [macOS]
+#import <React/RCTHandledKey.h> // [macOS]
 
 @implementation RCTBaseTextInputView {
   __weak RCTBridge *_bridge;

React/Views/RCTHandledKey.h

@@ -5,9 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-#if TARGET_OS_OSX // [macOS
+// [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;
@@ -17,10 +21,13 @@
 - (BOOL)matchesEvent:(NSEvent *)event;
 
 @property (nonatomic, copy) NSString *key;
-@property (nonatomic, assign) NSNumber *altKey; // boolean; nil == don't care
-@property (nonatomic, assign) NSNumber *ctrlKey; // boolean; nil == don't care
-@property (nonatomic, assign) NSNumber *metaKey; // boolean; nil == don't care
-@property (nonatomic, assign) NSNumber *shiftKey; // boolean; nil == don't care
+
+// 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
 
@@ -30,4 +37,4 @@
 
 @end
 
-#endif // macOS]
+#endif

React/Views/RCTHandledKey.m

@@ -5,14 +5,16 @@
  * 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 // [macOS
+#if TARGET_OS_OSX
 
 @implementation RCTHandledKey
 
@@ -101,10 +103,12 @@ @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"];
@@ -138,4 +142,4 @@ + (RCTHandledKey *)RCTHandledKey:(id)json
 
 @end
 
-#endif // macOS]
+#endif

React/Views/RCTView.m

@@ -1723,7 +1723,7 @@ - (RCTViewKeyboardEvent*)keyboardEvent:(NSEvent*)event shouldBlock:(BOOL *)shoul
     ];
   }
 
-  // If a view specifies a key, it will always be removed from the system event queue (i.e. "handled")
+  // If a view specifies a key, it will always be removed from the responder chain (i.e. "handled")
   *shouldBlock = [RCTHandledKey event:event matchesFilter:validKeys];
 
   // If an event isn't being removed from the queue, but was requested to "passthrough" by a view,