not-react-native-macos 0.87.1-rc.4 → 0.87.1-rc.5

package/Libraries/Components/View/ViewPropTypes.js

@@ -132,7 +132,40 @@ type FocusEventProps = Readonly<{
 // a .macos file because ViewPropTypes is shared, and a prop that is simply
 // absent on other platforms costs them nothing. The native side is
 // HostPlatformViewProps under components/view/platform/macos. macOS]
+/**
+ * A key the view means to act on itself. A modifier left out is a wildcard:
+ * `{key: 'c'}` matches Cmd-C and a bare c alike.
+ *
+ * @platform macos
+ */
+export type HandledKeyEvent = Readonly<{
+  key: string,
+  altKey?: ?boolean,
+  ctrlKey?: ?boolean,
+  metaKey?: ?boolean,
+  shiftKey?: ?boolean,
+}>;
+
 type MacOSViewProps = Readonly<{
+  /**
+   * Keys this view handles itself, suppressing AppKit's own interpretation of
+   * them -- Tab moving focus, Escape cancelling, an unclaimed key beeping.
+   *
+   * Separate from `onKeyDown`, deliberately: listening to a key does not change
+   * what it does, so a view that observes Tab still lets Tab move focus. Only
+   * listing a key here claims it.
+   *
+   * @platform macos
+   */
+  keyDownEvents?: ?$ReadOnlyArray<HandledKeyEvent>,
+
+  /**
+   * As `keyDownEvents`, for key release.
+   *
+   * @platform macos
+   */
+  keyUpEvents?: ?$ReadOnlyArray<HandledKeyEvent>,
+
   /**
    * The view's help tag, shown when the pointer rests over it.
    *

package/Libraries/NativeComponent/BaseViewConfig.macos.js

@@ -51,6 +51,8 @@ const validAttributesForNonEventProps = {
   allowsVibrancy: true,
   enableFocusRing: true,
   focusable: true,
+  keyDownEvents: true,
+  keyUpEvents: true,
   mouseDownCanMoveWindow: true,
   tooltip: true,
 };

package/Libraries/Types/CoreEventTypes.js

@@ -351,6 +351,17 @@ export type KeyEvent = Readonly<{
    * @see https://developer.mozilla.org/en-US/docs/Web/API/CompositionEvent/isComposing
    */
   isComposing?: boolean,
+  // [macOS] Modifiers AppKit reports and no other platform has. Optional, so
+  // shared code that never reads them is unaffected.
+  /** @platform macos */
+  capsLockKey?: boolean,
+  /** @platform macos */
+  numericPadKey?: boolean,
+  /** @platform macos */
+  helpKey?: boolean,
+  /** @platform macos */
+  functionKey?: boolean,
+  // macOS]
 }>;
 
 export type KeyUpEvent = NativeSyntheticEvent<KeyEvent>;

package/React/Fabric/Mounting/ComponentViews/View/RCTViewComponentView.mm

@@ -10,6 +10,7 @@
 
 #import <CoreGraphics/CoreGraphics.h>
 #import <QuartzCore/QuartzCore.h>
+#import <algorithm> // [macOS] std::find, for matching a press against keyDownEvents
 #import <objc/runtime.h>
 #import <ranges>
 
@@ -740,6 +741,133 @@ static BOOL RCTLayerTransformCollapsesAxis(CALayer *layer)
   }
 }
 
+#pragma mark - Keyboard Events
+
+/**
+ * The W3C `key` name for a press, per https://www.w3.org/TR/uievents-key/.
+ *
+ * `charactersIgnoringModifiers` already gives the right answer for anything
+ * printable. The cases below are the ones where it gives a private-use unichar
+ * (the arrows, the function keys) or a control character (Return, Delete)
+ * instead of a name. Tab and Escape are matched on keyCode rather than
+ * character because AppKit reports them as \t and \e, which would otherwise
+ * arrive as those literal characters.
+ *
+ * Naming follows the cross-platform reconciliation react-native-windows and
+ * react-native-macos both use, so a key handler is portable between them.
+ */
+static NSString *RCTKeyFromNSEvent(NSEvent *event)
+{
+  NSString *characters = event.charactersIgnoringModifiers;
+  unichar code = characters.length > 0 ? [characters characterAtIndex:0] : 0;
+
+  switch (event.keyCode) {
+    case 48:
+      return @"Tab";
+    case 53:
+      return @"Escape";
+    default:
+      break;
+  }
+
+  switch (code) {
+    case NSEnterCharacter:
+    case NSNewlineCharacter:
+    case NSCarriageReturnCharacter:
+      return @"Enter";
+    case NSLeftArrowFunctionKey:
+      return @"ArrowLeft";
+    case NSRightArrowFunctionKey:
+      return @"ArrowRight";
+    case NSUpArrowFunctionKey:
+      return @"ArrowUp";
+    case NSDownArrowFunctionKey:
+      return @"ArrowDown";
+    case NSBackspaceCharacter:
+    case NSDeleteCharacter:
+      return @"Backspace";
+    case NSDeleteFunctionKey:
+      return @"Delete";
+    case NSHomeFunctionKey:
+      return @"Home";
+    case NSEndFunctionKey:
+      return @"End";
+    case NSPageUpFunctionKey:
+      return @"PageUp";
+    case NSPageDownFunctionKey:
+      return @"PageDown";
+    default:
+      break;
+  }
+
+  if (code >= NSF1FunctionKey && code <= NSF12FunctionKey) {
+    return [NSString stringWithFormat:@"F%u", (unsigned)(code - NSF1FunctionKey + 1)];
+  }
+
+  return characters;
+}
+
+/**
+ * Emits the press and reports whether the view claimed it.
+ *
+ * Claiming matters because AppKit interprets an unclaimed key itself once the
+ * responder chain is done with it: Tab moves focus, Escape cancels, anything
+ * else beeps. A view says which keys it means to act on through `keyDownEvents`
+ * / `keyUpEvents`, and only those suppress the default behaviour. Listening via
+ * `onKeyDown` alone deliberately does not, so observing a key does not change
+ * what it does.
+ */
+- (BOOL)_handleKeyboardEvent:(NSEvent *)event
+{
+  NSEventModifierFlags flags = event.modifierFlags;
+  KeyEvent keyEvent = {
+      .key = RCTStringFromNSString(RCTKeyFromNSEvent(event)),
+      .altKey = static_cast<bool>(flags & NSEventModifierFlagOption),
+      .ctrlKey = static_cast<bool>(flags & NSEventModifierFlagControl),
+      .shiftKey = static_cast<bool>(flags & NSEventModifierFlagShift),
+      .metaKey = static_cast<bool>(flags & NSEventModifierFlagCommand),
+      .capsLockKey = static_cast<bool>(flags & NSEventModifierFlagCapsLock),
+      .numericPadKey = static_cast<bool>(flags & NSEventModifierFlagNumericPad),
+      .helpKey = static_cast<bool>(flags & NSEventModifierFlagHelp),
+      .functionKey = static_cast<bool>(flags & NSEventModifierFlagFunction),
+  };
+
+  BOOL isKeyDown = event.type == NSEventTypeKeyDown;
+  const auto &viewProps = static_cast<const ViewProps &>(*_props);
+
+  // Calling super walks the responder chain, which is the view hierarchy, so
+  // every ancestor view would emit the same press. Fabric bubbles the event
+  // through the shadow tree on its own, so only the innermost view should emit.
+  // The flag rides on the NSEvent because that is the one object the whole
+  // chain shares.
+  static const char kEmittedKey = 0;
+  if (_eventEmitter != nullptr && !((NSNumber *)objc_getAssociatedObject(event, &kEmittedKey)).boolValue) {
+    if (isKeyDown) {
+      _eventEmitter->onKeyDown(keyEvent);
+    } else {
+      _eventEmitter->onKeyUp(keyEvent);
+    }
+    objc_setAssociatedObject(event, &kEmittedKey, @YES, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+  }
+
+  const auto &handled = isKeyDown ? viewProps.keyDownEvents : viewProps.keyUpEvents;
+  return std::find(handled.cbegin(), handled.cend(), keyEvent) != handled.cend();
+}
+
+- (void)keyDown:(NSEvent *)event
+{
+  if (![self _handleKeyboardEvent:event]) {
+    [super keyDown:event];
+  }
+}
+
+- (void)keyUp:(NSEvent *)event
+{
+  if (![self _handleKeyboardEvent:event]) {
+    [super keyUp:event];
+  }
+}
+
 - (BOOL)allowsVibrancy
 {
   return _allowsVibrancy;
@@ -1922,7 +2050,16 @@ static NSString *RCTRecursiveAccessibilityLabel(UIView *view)
 
 - (void)focus
 {
+#if TARGET_OS_OSX // [macOS] On AppKit -becomeFirstResponder is the window
+  // notifying the view that it happened, not the view asking. Sending it
+  // directly changes nothing: -makeFirstResponder: is the request. Without
+  // this, `focusable` views never receive key events, because nothing ever
+  // makes them first responder -- AppKit moves focus on Tab only, and only
+  // when Full Keyboard Access is on.
+  [self.window makeFirstResponder:self];
+#else // [macOS]
   [self becomeFirstResponder];
+#endif // [macOS]
 
 #if TARGET_OS_TV
   RCTSurfaceHostingProxyRootView *rootView = [self containingRootView];
@@ -1938,7 +2075,14 @@ static NSString *RCTRecursiveAccessibilityLabel(UIView *view)
 
 - (void)blur
 {
+#if TARGET_OS_OSX // [macOS] Symmetrically: resigning is granted by the window,
+  // and only if this view still holds the focus.
+  if (self.window.firstResponder == self) {
+    [self.window makeFirstResponder:nil];
+  }
+#else // [macOS]
   [self resignFirstResponder];
+#endif // [macOS]
 }
 
 - (BOOL)becomeFirstResponder

package/ReactCommon/react/renderer/components/view/platform/macos/react/renderer/components/view/HostPlatformViewEventEmitter.cpp

@@ -20,6 +20,30 @@ static jsi::Value mouseEventPayload(jsi::Runtime &runtime, const HostPlatformVie
   payload.setProperty(runtime, "screenY", event.screenY);
   payload.setProperty(runtime, "pageX", event.pageX);
   payload.setProperty(runtime, "pageY", event.pageY);
+  payload.setProperty(runtime, "altKey", event.altKey);
+  payload.setProperty(runtime, "ctrlKey", event.ctrlKey);
+  payload.setProperty(runtime, "shiftKey", event.shiftKey);
+  payload.setProperty(runtime, "metaKey", event.metaKey);
+  payload.setProperty(runtime, "button", event.button);
+  // Pressability's click guard reads this to tell a real mouse click apart from
+  // one synthesised by the responder system, which would otherwise fire onPress
+  // twice.
+  payload.setProperty(runtime, "pointerType", "mouse");
+  return payload;
+}
+
+static jsi::Value keyEventPayload(jsi::Runtime &runtime, const KeyEvent &event)
+{
+  auto payload = jsi::Object(runtime);
+  payload.setProperty(runtime, "key", jsi::String::createFromUtf8(runtime, event.key));
+  payload.setProperty(runtime, "altKey", event.altKey);
+  payload.setProperty(runtime, "ctrlKey", event.ctrlKey);
+  payload.setProperty(runtime, "shiftKey", event.shiftKey);
+  payload.setProperty(runtime, "metaKey", event.metaKey);
+  payload.setProperty(runtime, "capsLockKey", event.capsLockKey);
+  payload.setProperty(runtime, "numericPadKey", event.numericPadKey);
+  payload.setProperty(runtime, "helpKey", event.helpKey);
+  payload.setProperty(runtime, "functionKey", event.functionKey);
   return payload;
 }
 
@@ -36,4 +60,15 @@ RCT_MACOS_MOUSE_EVENT(onMouseLeave)
 RCT_MACOS_MOUSE_EVENT(onDoubleClick)
 RCT_MACOS_MOUSE_EVENT(onAuxClick)
 
+#define RCT_MACOS_KEY_EVENT(name)                                                     \
+  void HostPlatformViewEventEmitter::name(const KeyEvent &event) const                \
+  {                                                                                   \
+    dispatchEvent(#name, [event](jsi::Runtime &runtime) {                             \
+      return keyEventPayload(runtime, event);                                         \
+    });                                                                               \
+  }
+
+RCT_MACOS_KEY_EVENT(onKeyDown)
+RCT_MACOS_KEY_EVENT(onKeyUp)
+
 } // namespace facebook::react

package/ReactCommon/react/renderer/components/view/platform/macos/react/renderer/components/view/HostPlatformViewEventEmitter.h

@@ -5,12 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// [macOS] Adds the pointer events AppKit can report and UIKit cannot.
+// [macOS] Adds the pointer and key events AppKit can report and UIKit cannot.
 
 #pragma once
 
 #include <react/renderer/components/view/BaseViewEventEmitter.h>
 
+#include "KeyEvent.h"
+
 namespace facebook::react {
 
 class HostPlatformViewEventEmitter : public BaseViewEventEmitter {
@@ -28,12 +30,23 @@ class HostPlatformViewEventEmitter : public BaseViewEventEmitter {
     Float screenY{};
     Float pageX{};
     Float pageY{};
+
+    bool altKey{false};
+    bool ctrlKey{false};
+    bool shiftKey{false};
+    bool metaKey{false};
+
+    /** DOM button numbering: 0 left, 1 middle, 2 right. */
+    int button{0};
   };
 
   void onMouseEnter(const MouseEvent &event) const;
   void onMouseLeave(const MouseEvent &event) const;
   void onDoubleClick(const MouseEvent &event) const;
   void onAuxClick(const MouseEvent &event) const;
+
+  void onKeyDown(const KeyEvent &event) const;
+  void onKeyUp(const KeyEvent &event) const;
 };
 
 } // namespace facebook::react

package/ReactCommon/react/renderer/components/view/platform/macos/react/renderer/components/view/HostPlatformViewEvents.h

@@ -27,6 +27,8 @@ struct HostPlatformViewEvents {
     MouseLeave = 1,
     DoubleClick = 2,
     AuxClick = 3,
+    KeyDown = 4,
+    KeyUp = 5,
   };
 
   constexpr bool operator[](Offset offset) const

package/ReactCommon/react/renderer/components/view/platform/macos/react/renderer/components/view/HostPlatformViewProps.cpp

@@ -33,6 +33,8 @@ static inline HostPlatformViewEvents convertRawProp(
   RCT_MACOS_CONVERT_EVENT("onMouseLeave", MouseLeave);
   RCT_MACOS_CONVERT_EVENT("onDoubleClick", DoubleClick);
   RCT_MACOS_CONVERT_EVENT("onAuxClick", AuxClick);
+  RCT_MACOS_CONVERT_EVENT("onKeyDown", KeyDown);
+  RCT_MACOS_CONVERT_EVENT("onKeyUp", KeyUp);
 
 #undef RCT_MACOS_CONVERT_EVENT
 
@@ -59,6 +61,8 @@ HostPlatformViewProps::HostPlatformViewProps(
               : convertRawProp(context, rawProps, sourceProps.hostPlatformEvents, {})),
       RCT_MACOS_PROP(focusable),
       RCT_MACOS_PROP(enableFocusRing),
+      RCT_MACOS_PROP(keyDownEvents),
+      RCT_MACOS_PROP(keyUpEvents),
       RCT_MACOS_PROP(tooltip),
       RCT_MACOS_PROP(acceptsFirstMouse),
       RCT_MACOS_PROP(allowsVibrancy),
@@ -99,8 +103,12 @@ void HostPlatformViewProps::setProp(
     RCT_MACOS_EVENT_CASE(MouseLeave);
     RCT_MACOS_EVENT_CASE(DoubleClick);
     RCT_MACOS_EVENT_CASE(AuxClick);
+    RCT_MACOS_EVENT_CASE(KeyDown);
+    RCT_MACOS_EVENT_CASE(KeyUp);
     RAW_SET_PROP_SWITCH_CASE_BASIC(focusable);
     RAW_SET_PROP_SWITCH_CASE_BASIC(enableFocusRing);
+    RAW_SET_PROP_SWITCH_CASE_BASIC(keyDownEvents);
+    RAW_SET_PROP_SWITCH_CASE_BASIC(keyUpEvents);
     RAW_SET_PROP_SWITCH_CASE_BASIC(tooltip);
     RAW_SET_PROP_SWITCH_CASE_BASIC(acceptsFirstMouse);
     RAW_SET_PROP_SWITCH_CASE_BASIC(allowsVibrancy);

package/ReactCommon/react/renderer/components/view/platform/macos/react/renderer/components/view/HostPlatformViewProps.h

@@ -20,8 +20,10 @@
 
 #include <optional>
 #include <string>
+#include <vector>
 
 #include "HostPlatformViewEvents.h"
+#include "KeyEvent.h"
 
 namespace facebook::react {
 
@@ -47,6 +49,14 @@ class HostPlatformViewProps : public BaseViewProps {
   /** Draws the focus ring while first responder. On by default, as in AppKit. */
   bool enableFocusRing{true};
 
+  /**
+   * Keys the view handles itself, rather than letting AppKit interpret them.
+   * See HandledKey: a press not declared here still reaches onKeyDown, but
+   * AppKit's own handling runs afterwards.
+   */
+  std::vector<HandledKey> keyDownEvents{};
+  std::vector<HandledKey> keyUpEvents{};
+
   /** The view's help tag. std::nullopt leaves any inherited tooltip alone. */
   std::optional<std::string> tooltip{};
 

package/ReactCommon/react/renderer/components/view/platform/macos/react/renderer/components/view/HostPlatformViewTraitsInitializer.h

@@ -26,7 +26,8 @@ inline bool formsView(const ViewProps &props)
   // flattened away: a focusable view has to join the key view loop, a tooltip
   // has to attach to something, and mouse tracking needs an NSTrackingArea
   // owner. Flattening is otherwise invisible -- the handler simply never fires.
-  return props.focusable || props.tooltip.has_value() || props.hostPlatformEvents.bits.any();
+  return props.focusable || props.tooltip.has_value() || props.hostPlatformEvents.bits.any() ||
+      !props.keyDownEvents.empty() || !props.keyUpEvents.empty();
 }
 
 inline bool isKeyboardFocusable(const ViewProps &props)

package/ReactCommon/react/renderer/components/view/platform/macos/react/renderer/components/view/KeyEvent.h

@@ -0,0 +1,100 @@
+/*
+ * 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] Key input, which only a desktop platform has to model.
+//
+// Two shapes, and the distinction matters. `KeyEvent` is what a view reports
+// happened. `HandledKey` is what a view declares in advance that it wants,
+// which is a filter, not an event: AppKit gives a key to the responder chain
+// and then to its own interpretation -- Tab moves focus, Escape cancels, an
+// unclaimed key beeps -- so a view that means to act on a key has to say so
+// before the press, or the default behaviour happens as well.
+//
+// Names follow https://www.w3.org/TR/uievents-key/ rather than AppKit's
+// keyCodes, so `keyDownEvents={[{key: 'Enter'}]}` is the same declaration it
+// would be on the web, and matches microsoft/react-native-macos.
+
+#pragma once
+
+#include <react/renderer/core/PropsParserContext.h>
+#include <react/renderer/core/propsConversions.h>
+
+#include <optional>
+#include <string>
+#include <unordered_map>
+
+namespace facebook::react {
+
+/**
+ * A key the view intends to handle itself.
+ *
+ * A modifier left unset means "don't care": `{key: 'c'}` matches Cmd-C and a
+ * bare c alike, while `{key: 'c', metaKey: true}` matches only the former.
+ */
+struct HandledKey {
+  std::string key{};
+  std::optional<bool> altKey{};
+  std::optional<bool> ctrlKey{};
+  std::optional<bool> shiftKey{};
+  std::optional<bool> metaKey{};
+};
+
+inline bool operator==(const HandledKey &lhs, const HandledKey &rhs)
+{
+  return lhs.key == rhs.key && lhs.altKey == rhs.altKey && lhs.ctrlKey == rhs.ctrlKey &&
+      lhs.shiftKey == rhs.shiftKey && lhs.metaKey == rhs.metaKey;
+}
+
+/** A key press, as reported to `onKeyDown` / `onKeyUp`. */
+struct KeyEvent {
+  std::string key{};
+  bool altKey{false};
+  bool ctrlKey{false};
+  bool shiftKey{false};
+  bool metaKey{false};
+  bool capsLockKey{false};
+  bool numericPadKey{false};
+  bool helpKey{false};
+  bool functionKey{false};
+};
+
+/** Whether an actual press satisfies a declaration; unset modifiers match anything. */
+inline bool operator==(const KeyEvent &lhs, const HandledKey &rhs)
+{
+  return lhs.key == rhs.key && (!rhs.altKey.has_value() || lhs.altKey == *rhs.altKey) &&
+      (!rhs.ctrlKey.has_value() || lhs.ctrlKey == *rhs.ctrlKey) &&
+      (!rhs.shiftKey.has_value() || lhs.shiftKey == *rhs.shiftKey) &&
+      (!rhs.metaKey.has_value() || lhs.metaKey == *rhs.metaKey);
+}
+
+/**
+ * Accepts either the object form or a bare string, so `keyDownEvents={['Enter']}`
+ * works as shorthand for the common no-modifier case.
+ */
+inline void fromRawValue(const PropsParserContext &context, const RawValue &value, HandledKey &result)
+{
+  if (value.hasType<std::unordered_map<std::string, RawValue>>()) {
+    auto map = static_cast<std::unordered_map<std::string, RawValue>>(value);
+    for (const auto &pair : map) {
+      if (pair.first == "key") {
+        result.key = static_cast<std::string>(pair.second);
+      } else if (pair.first == "altKey") {
+        result.altKey = static_cast<bool>(pair.second);
+      } else if (pair.first == "ctrlKey") {
+        result.ctrlKey = static_cast<bool>(pair.second);
+      } else if (pair.first == "shiftKey") {
+        result.shiftKey = static_cast<bool>(pair.second);
+      } else if (pair.first == "metaKey") {
+        result.metaKey = static_cast<bool>(pair.second);
+      }
+    }
+  } else if (value.hasType<std::string>()) {
+    result.key = static_cast<std::string>(value);
+  }
+}
+
+} // namespace facebook::react

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "not-react-native-macos",
-  "version": "0.87.1-rc.4",
+  "version": "0.87.1-rc.5",
   "description": "A framework for building native apps using React",
   "license": "MIT",
   "repository": {