basalt-appkit 0.0.0-rc5

package/native/appkit/AppKitDropTarget.mm

@@ -0,0 +1,292 @@
+#import "AppKitDropTarget.h"
+
+#include "DragAndDrop.h"
+
+#import <AppKit/AppKit.h>
+
+#include <string>
+
+namespace basalt {
+
+facebook::react::Tag dropTargetAt(RnAppKitView *root, double x, double y, std::uint16_t accepts) {
+  if (root == nil) {
+    return 0;
+  }
+  // `RnAppKitHitTest`, not NSView's `hitTest:`. The platform's own is what
+  // touches use -- it honours pointer-events, clipping, transforms and z
+  // order the way this renderer means them -- and AppKit's stops at the first
+  // subview whose own hitTest: answers, which for these views is the page
+  // rather than the target inside it. Using the wrong one found a view two
+  // steps below the root and no marker anywhere above it.
+  //
+  // From there the walk up is ours, for the reason core/DragAndDrop.h gives:
+  // a label inside a drop target should not need marking.
+  RnAppKitView *hit = RnAppKitHitTest(root, x, y);
+  for (NSView *view = hit; view != nil; view = view.superview) {
+    if ([view isKindOfClass:[RnAppKitView class]]) {
+      auto *candidate = (RnAppKitView *)view;
+      NSString *identifier = candidate.rnNativeId;
+      if (identifier != nil) {
+        const std::uint16_t wanted = dropAcceptsFrom(identifier.UTF8String);
+        if (wanted != DropAcceptsNone && (wanted & accepts) != 0) {
+          return (facebook::react::Tag)candidate.rnTag;
+        }
+      }
+    }
+    if (view == root) {
+      break;
+    }
+  }
+  return 0;
+}
+
+} // namespace basalt
+
+// What AppKit asks about the drag while it is in flight.
+//
+// A class of its own because RnAppKitView does not conform to
+// NSDraggingSource, and should not: a view is a drag source only while a drag
+// it started is running, and that is a session's lifetime rather than a
+// view's.
+@interface RnDragSource : NSObject <NSDraggingSource>
+@end
+
+@implementation RnDragSource
+
+- (NSDragOperation)draggingSession:(NSDraggingSession *)session
+    sourceOperationMaskForDraggingContext:(NSDraggingContext)context {
+  (void)session;
+  // Copy in both contexts. This platform has no notion of a drag that moves
+  // or links, and offering one it cannot honour would be a cursor promising
+  // something the drop does not do -- the same rule the drop side applies.
+  (void)context;
+  return NSDragOperationCopy;
+}
+
+@end
+
+namespace basalt {
+namespace {
+
+// Alive for as long as the session is. AppKit holds the source weakly, and a
+// source collected mid-drag is a drag that stops answering.
+RnDragSource *gDragSource = nil;
+
+} // namespace
+
+DragPayload dragPayloadAt(RnAppKitView *root, double x, double y) {
+  if (root == nil) {
+    return {};
+  }
+  RnAppKitView *hit = RnAppKitHitTest(root, x, y);
+  // The same walk the drop side makes: a label inside a draggable view should
+  // be draggable without being marked itself.
+  for (NSView *view = hit; view != nil; view = view.superview) {
+    if ([view isKindOfClass:[RnAppKitView class]]) {
+      NSString *identifier = ((RnAppKitView *)view).rnNativeId;
+      if (identifier != nil) {
+        const DragPayload payload = dragPayloadFrom(identifier.UTF8String);
+        if (!payload.empty()) {
+          return payload;
+        }
+      }
+    }
+    if (view == root) {
+      break;
+    }
+  }
+  return {};
+}
+
+bool beginDragIfMarked(RnAppKitView *root, double x, double y) {
+  const DragPayload payload = dragPayloadAt(root, x, y);
+  if (payload.empty()) {
+    return false;
+  }
+
+  // What the rest of the desktop will receive. A file URL for a file and a
+  // string for text, which are the two every other application understands.
+  id<NSPasteboardWriting> item = nil;
+  if (payload.hasFiles()) {
+    item = [NSURL fileURLWithPath:[NSString stringWithUTF8String:payload.files.front().c_str()]];
+  } else {
+    item = [NSString stringWithUTF8String:payload.text.c_str()];
+  }
+
+  NSDraggingItem *dragged =
+      [[NSDraggingItem alloc] initWithPasteboardWriter:item];
+  // Something to see while dragging. A plain rectangle where the view is,
+  // rather than a snapshot: a snapshot means rendering the view again into an
+  // image, and the drag has to start on this event or not at all.
+  const NSRect frame = NSMakeRect(x - 40, y - 20, 80, 40);
+  [dragged setDraggingFrame:frame contents:nil];
+
+  NSEvent *event = NSApp.currentEvent;
+  if (event == nil) {
+    return false;
+  }
+  if (gDragSource == nil) {
+    gDragSource = [[RnDragSource alloc] init];
+  }
+  [root beginDraggingSessionWithItems:@[ dragged ] event:event source:gDragSource];
+  return true;
+}
+
+} // namespace basalt
+
+// The dragging destination itself.
+//
+// On a view of its own, layered over the surface root, rather than on
+// RnAppKitView: every RnAppKitView would otherwise inherit the protocol and
+// AppKit would ask the deepest one, which is the opposite of the rule -- the
+// deepest *marked* view decides, and most views are not marked.
+@interface RnDropTargetView : NSView
+@property(nonatomic, weak, nullable) RnAppKitView *rnRoot;
+@property(nonatomic) facebook::react::Tag rnCurrent;
+@end
+
+@implementation RnDropTargetView
+
+// Not drawn and not hit-testable for anything but drags: a view that swallowed
+// clicks would break every press in the app.
+- (NSView *)hitTest:(NSPoint)point {
+  (void)point;
+  return nil;
+}
+
+- (std::uint16_t)rnOfferedBy:(id<NSDraggingInfo>)info {
+  std::uint16_t offered = basalt::DropAcceptsNone;
+  NSPasteboard *board = info.draggingPasteboard;
+  if ([board canReadObjectForClasses:@[ [NSURL class] ]
+                             options:@{NSPasteboardURLReadingFileURLsOnlyKey : @YES}]) {
+    offered |= basalt::DropAcceptsFiles;
+  }
+  if ([board canReadObjectForClasses:@[ [NSString class] ] options:@{}]) {
+    offered |= basalt::DropAcceptsText;
+  }
+  return offered;
+}
+
+// The point a drag is over, in the root's coordinates.
+- (NSPoint)rnPointFor:(id<NSDraggingInfo>)info {
+  RnAppKitView *root = self.rnRoot;
+  if (root == nil) {
+    return NSZeroPoint;
+  }
+  return [root convertPoint:info.draggingLocation fromView:nil];
+}
+
+- (void)rnReportLeaveAt:(NSPoint)point {
+  if (self.rnCurrent == 0) {
+    return;
+  }
+  basalt::DropEvent event;
+  event.tag = self.rnCurrent;
+  event.phase = basalt::DropPhase::Leave;
+  event.x = point.x;
+  event.y = point.y;
+  basalt::reportDrop(event);
+  self.rnCurrent = 0;
+}
+
+- (NSDragOperation)rnUpdate:(id<NSDraggingInfo>)info {
+  const NSPoint point = [self rnPointFor:info];
+  const facebook::react::Tag found =
+      basalt::dropTargetAt(self.rnRoot, point.x, point.y, [self rnOfferedBy:info]);
+
+  if (found != self.rnCurrent) {
+    [self rnReportLeaveAt:point];
+  }
+  if (found == 0) {
+    // Nothing here takes it, which is what makes the cursor say so.
+    return NSDragOperationNone;
+  }
+  self.rnCurrent = found;
+
+  basalt::DropEvent event;
+  event.tag = found;
+  event.phase = basalt::DropPhase::Over;
+  event.x = point.x;
+  event.y = point.y;
+  basalt::reportDrop(event);
+  return NSDragOperationCopy;
+}
+
+- (NSDragOperation)draggingEntered:(id<NSDraggingInfo>)sender {
+  return [self rnUpdate:sender];
+}
+
+- (NSDragOperation)draggingUpdated:(id<NSDraggingInfo>)sender {
+  return [self rnUpdate:sender];
+}
+
+- (void)draggingExited:(id<NSDraggingInfo>)sender {
+  [self rnReportLeaveAt:sender != nil ? [self rnPointFor:sender] : NSZeroPoint];
+}
+
+- (BOOL)performDragOperation:(id<NSDraggingInfo>)sender {
+  NSPasteboard *board = sender.draggingPasteboard;
+
+  basalt::DragPayload payload;
+  NSArray<NSURL *> *urls =
+      [board readObjectsForClasses:@[ [NSURL class] ]
+                           options:@{NSPasteboardURLReadingFileURLsOnlyKey : @YES}];
+  for (NSURL *url in urls) {
+    if (url.isFileURL && url.path != nil) {
+      // A path, not a URL: core/DragAndDrop.h says every host hands back
+      // something path-shaped, and an app that wanted a URL can make one.
+      payload.files.emplace_back(url.path.UTF8String);
+    }
+  }
+  NSString *text = [board stringForType:NSPasteboardTypeString];
+  if (text != nil) {
+    payload.text = text.UTF8String;
+  }
+
+  // Asked again from the contents rather than from what the pasteboard could
+  // read, for the reason the GTK host gives: this is the moment the payload is
+  // known.
+  std::uint16_t carries = basalt::DropAcceptsNone;
+  if (payload.hasFiles()) {
+    carries |= basalt::DropAcceptsFiles;
+  }
+  if (payload.hasText()) {
+    carries |= basalt::DropAcceptsText;
+  }
+
+  const NSPoint point = [self rnPointFor:sender];
+  const facebook::react::Tag found =
+      basalt::dropTargetAt(self.rnRoot, point.x, point.y, carries);
+  self.rnCurrent = 0;
+  if (found == 0) {
+    return NO;
+  }
+
+  basalt::DropEvent event;
+  event.tag = found;
+  event.phase = basalt::DropPhase::Drop;
+  event.x = point.x;
+  event.y = point.y;
+  event.payload = payload;
+  basalt::reportDrop(event);
+  return YES;
+}
+
+@end
+
+namespace basalt {
+
+void attachDropTarget(RnAppKitView *root) {
+  if (root == nil) {
+    return;
+  }
+  RnDropTargetView *target = [[RnDropTargetView alloc] initWithFrame:root.bounds];
+  target.rnRoot = root;
+  target.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable;
+  [target registerForDraggedTypes:@[ NSPasteboardTypeFileURL, NSPasteboardTypeString ]];
+  // Above everything, so no app view can shadow the destination -- it is not
+  // hit-testable for clicks, so being on top costs nothing.
+  [root addSubview:target positioned:NSWindowAbove relativeTo:nil];
+}
+
+} // namespace basalt

package/native/appkit/AppKitFocus.h

@@ -0,0 +1,120 @@
+// Keyboard focus, for everything that is not a <TextInput>.
+//
+// Deliberately the same shape as basalt-gtk's GtkFocusManager,
+// down to what makes a view focusable and what activating one dispatches,
+// because none of that is about the toolkit: if the two diverge, an app's
+// buttons will be reachable from the keyboard on one desktop and not the other.
+//
+// ## What makes a view focusable
+//
+// `accessible`. React Native has a `focusable` prop and it does not reach this
+// platform: ReactCommon parses it only into Android's and tvOS's
+// `HostPlatformViewProps`, and the C++ host's is a bare alias of
+// `BaseViewProps`. So the signal has to be something that does arrive, and
+// `accessible` is both the nearest true thing and the right one -- it is what
+// `<Pressable>` sets on everything it renders, and what a screen reader already
+// stops on.
+//
+// ## What activating one does
+//
+// Dispatches `topClick` with an empty payload, which is what React Native for
+// Android does from `ReactViewManager.setFocusable`. Pressability listens for
+// it and calls `onPress`, but only when the payload has no `pointerType` -- a
+// click that came from a pointer would fire `onPress` twice. So this cannot go
+// through `TouchEventEmitter::onClick`, which always carries one.
+//
+// ## The chain, which AppKit does not contribute
+//
+// This is the one place the two desktops genuinely differ. GTK hands over its
+// focus chain: a focusable widget joins the window's order and Tab works. AppKit
+// has a key-view loop and it is not usable here -- `selectNextKeyView:` needs
+// `nextKeyView` links or `autorecalculatesKeyViewLoop`, both of which assume a
+// window built from a nib, and a programmatically built one with neither simply
+// does nothing. Which is exactly what it did: seven Tab presses, no focus.
+//
+// So the order is walked here, in tree order, which is what GTK's chain
+// produces anyway. A <TextInput> is a stop like any other: the responder for
+// one is its NSTextField peer rather than the view, because that is the thing
+// AppKit will make first responder.
+
+#pragma once
+
+#include "KeyEvents.h"
+
+#import "RnAppKitView.h"
+
+#include "AppKitMountingManager.h"
+
+namespace basalt {
+
+class AppKitFocusManager {
+ public:
+  AppKitFocusManager(AppKitMountingManager *mountingManager, RnAppKitView *surfaceRoot);
+  ~AppKitFocusManager();
+
+  AppKitFocusManager(const AppKitFocusManager &) = delete;
+  AppKitFocusManager &operator=(const AppKitFocusManager &) = delete;
+  AppKitFocusManager(AppKitFocusManager &&) = delete;
+  AppKitFocusManager &operator=(AppKitFocusManager &&) = delete;
+
+  // Moves focus to the next or previous focusable view, and reports whether
+  // anything took it. The keyboard's own Tab goes through AppKit; this is the
+  // entry point automation uses, for the same reason `synthesiseTap` exists --
+  // a real Tab needs a window the window server considers key, which an
+  // automated run does not reliably have.
+  bool moveFocus(bool forward);
+
+  // Activates whatever has focus, as Enter or space does.
+  bool activateFocused();
+
+  // A key press arriving at `view`, which is the first responder. Answers whether
+  // some view from there outwards declared this combination -- and reports it to
+  // JavaScript when one did. The answer has to come back in this call stack,
+  // because the caller consumes the key or passes it on by it; see
+  // core/KeyEvents.h.
+  bool handleKey(RnAppKitView *view, NSEvent *event);
+
+  // BASALT_TEST_KEY. The same delivery a real press gets, minus the NSEvent
+  // translation -- which is the half this cannot exercise and which
+  // tests/test_appkit_key_events.mm covers instead. See core/TestKeys.h.
+  bool deliverTestKey(const KeyCombination &pressed);
+
+  // A real key press that the responder chain was never going to bring here.
+  //
+  // `handleKey` above is reached from `RnAppKitView keyDown:`, which AppKit only
+  // calls on the first responder. An app whose shortcut holder is the root view
+  // has no first responder inside the React tree at all -- nothing focuses it,
+  // `focusable` only makes a view eligible -- so the press goes to the window
+  // and is gone. Every shortcut in such an app is dead, which is what kino was.
+  //
+  // Called from the window's key monitor for exactly that case, and only that
+  // case: with a text field or any other view focused, the responder chain does
+  // reach `handleKey` and this must not run as well.
+  bool deliverWindowKey(NSEvent *event);
+
+  // The tag of the focused view, or 0. For tests and for automation.
+  facebook::react::Tag focusedTag() const {
+    return focusedTag_;
+  }
+
+  // The main-thread halves, called by the Objective-C trampoline.
+  void viewDidChangeFocus(RnAppKitView *view, bool focused);
+  bool activate(RnAppKitView *view);
+
+ private:
+  void emitFocus(facebook::react::Tag tag, bool focused);
+  bool dispatchClick(facebook::react::Tag tag);
+
+  // The path walk and the decision, shared by a real press and by the
+  // instrument. Only the translation above them differs.
+  bool deliverKeyFrom(RnAppKitView *view, const KeyCombination &pressed);
+
+  AppKitMountingManager *mountingManager_;
+  RnAppKitView *surfaceRoot_;
+  // The object the root forwards focus changes to. Held so it outlives the
+  // root's weak reference to it, exactly as the touch dispatcher does.
+  id focusTarget_;
+  facebook::react::Tag focusedTag_{0};
+};
+
+} // namespace basalt

package/native/appkit/AppKitFocus.mm

@@ -0,0 +1,293 @@
+#import "AppKitFocus.h"
+
+#import "AppKitTextPeer.h"
+
+#import "AppKitKeyEvents.h"
+
+#include <optional>
+#include <vector>
+
+#include <folly/dynamic.h>
+
+#include <react/renderer/components/view/ViewEventEmitter.h>
+#include <react/renderer/core/EventEmitter.h>
+
+// The bridge between AppKit's protocol and the C++ manager. A C++ object cannot
+// conform to an Objective-C protocol, and the root holds its handler weakly, so
+// this exists and the manager owns it -- the same arrangement
+// AppKitTouchDispatcher has.
+@interface RnAppKitFocusTarget : NSObject <RnAppKitFocusHandler>
+@property(nonatomic, assign) basalt::AppKitFocusManager *manager;
+@end
+
+@implementation RnAppKitFocusTarget
+
+- (void)rnView:(RnAppKitView *)view didChangeFocus:(BOOL)focused {
+  if (_manager != nullptr) {
+    _manager->viewDidChangeFocus(view, focused);
+  }
+}
+
+- (BOOL)rnActivateView:(RnAppKitView *)view {
+  return _manager != nullptr && _manager->activate(view);
+}
+
+- (BOOL)rnMoveFocusForward:(BOOL)forward {
+  return _manager != nullptr && _manager->moveFocus(forward) ? YES : NO;
+}
+
+- (BOOL)rnView:(RnAppKitView *)view handlesKey:(NSEvent *)event {
+  return _manager != nullptr && _manager->handleKey(view, event) ? YES : NO;
+}
+
+@end
+
+namespace basalt {
+
+using facebook::react::RawEvent;
+using facebook::react::Tag;
+
+AppKitFocusManager::AppKitFocusManager(AppKitMountingManager *mountingManager,
+                                       RnAppKitView *surfaceRoot)
+    : mountingManager_(mountingManager), surfaceRoot_(surfaceRoot) {
+  RnAppKitFocusTarget *target = [[RnAppKitFocusTarget alloc] init];
+  target.manager = this;
+  focusTarget_ = target;
+  surfaceRoot_.rnFocusHandler = target;
+}
+
+AppKitFocusManager::~AppKitFocusManager() {
+  // The root's reference is weak, so it goes nil on its own; clearing the back
+  // pointer first means a focus change already in flight cannot reach a dead
+  // object.
+  ((RnAppKitFocusTarget *)focusTarget_).manager = nullptr;
+  focusTarget_ = nil;
+}
+
+void AppKitFocusManager::viewDidChangeFocus(RnAppKitView *view, bool focused) {
+  const auto tag = static_cast<Tag>(view.rnTag);
+  if (focused) {
+    // A blur for the view that had it, before the focus for the one that took
+    // it. AppKit resigns before it makes anyone else first responder, so this
+    // is usually already true; it is written out because an app reading
+    // onFocus/onBlur as a pair must not see two focuses in a row.
+    if (focusedTag_ != 0 && focusedTag_ != tag) {
+      emitFocus(focusedTag_, false);
+    }
+    focusedTag_ = tag;
+    emitFocus(tag, true);
+    return;
+  }
+  if (focusedTag_ != tag) {
+    return;
+  }
+  focusedTag_ = 0;
+  emitFocus(tag, false);
+}
+
+void AppKitFocusManager::emitFocus(Tag tag, bool focused) {
+  const auto emitter = std::dynamic_pointer_cast<const facebook::react::ViewEventEmitter>(
+      mountingManager_->eventEmitterForTag(tag));
+  if (emitter == nullptr) {
+    return;
+  }
+  // `topFocus` and `topBlur`, which React Native registers as bubbling events
+  // with an empty payload. BaseViewEventEmitter has both, so nothing here has
+  // to know the names.
+  if (focused) {
+    emitter->onFocus();
+  } else {
+    emitter->onBlur();
+  }
+}
+
+bool AppKitFocusManager::activate(RnAppKitView *view) {
+  return dispatchClick(static_cast<Tag>(view.rnTag));
+}
+
+bool AppKitFocusManager::handleKey(RnAppKitView *view, NSEvent *event) {
+  // Cheap first: almost every app declares no keys at all, and every one of them
+  // presses some. Without this the walk below runs on every keystroke in every
+  // text field in every app that never asked for a shortcut.
+  if (handledKeyViewCount() == 0) {
+    return false;
+  }
+
+  const std::optional<KeyCombination> pressed = keyCombinationFrom(event);
+  if (!pressed.has_value()) {
+    // A bare modifier or a dead key. Nothing to match and nothing to consume.
+    return false;
+  }
+  return deliverKeyFrom(view, *pressed);
+}
+
+bool AppKitFocusManager::deliverKeyFrom(RnAppKitView *view, const KeyCombination &pressed) {
+  // From the first responder outwards, so the innermost claim wins -- the order
+  // core/KeyEvents.h's `handledBy` expects. Only RnAppKitViews, because only they
+  // have a React tag; a scroll view's clip view in between is not a step in the
+  // React tree.
+  std::vector<Tag> path;
+  for (NSView *current = view; current != nil; current = current.superview) {
+    if ([current isKindOfClass:[RnAppKitView class]]) {
+      path.push_back(static_cast<Tag>(((RnAppKitView *)current).rnTag));
+    }
+  }
+
+  std::optional<Tag> handler = handledBy(path, pressed);
+  if (!handler.has_value() && focusedTag_ == 0) {
+    // Nothing focused, so there is no path to be outside of and no text field
+    // taking keys. A window-level shortcut holder is a child of the root rather
+    // than the root itself, so the walk above cannot reach it -- and that is
+    // every app that declares its shortcuts once at the top. See
+    // core/KeyEvents.h on why this is only safe unfocused.
+    handler = handledByAny(pressed);
+  }
+  if (!handler.has_value()) {
+    return false;
+  }
+  // Decided. Reporting is asynchronous from here -- it crosses to the JavaScript
+  // thread -- which is why the answer could not have come from there.
+  reportKey(*handler, pressed);
+  return true;
+}
+
+bool AppKitFocusManager::deliverWindowKey(NSEvent *event) {
+  // Cheap first, for the same reason handleKey checks: most apps declare no
+  // keys, and this runs on every press that reaches the window.
+  if (handledKeyViewCount() == 0) {
+    return false;
+  }
+  const std::optional<KeyCombination> pressed = keyCombinationFrom(event);
+  if (!pressed.has_value()) {
+    return false;
+  }
+  // The same walk the scripted path takes: from whatever has focus, or the root
+  // when nothing does. That the two now share it is the point -- the instrument
+  // could reach a claim a real press could not, which is how this stayed hidden
+  // while a scenario passed.
+  return deliverTestKey(*pressed);
+}
+
+bool AppKitFocusManager::deliverTestKey(const KeyCombination &pressed) {
+  // From whatever has focus, or from the root when nothing does -- which is the
+  // ordinary case for a window-level shortcut holder and the one a scenario
+  // exercises. A real press reaches the first responder, and with nothing
+  // focusable focused that is the root too.
+  RnAppKitView *from = nil;
+  if (focusedTag_ != 0 && mountingManager_ != nullptr) {
+    from = mountingManager_->viewForTag(focusedTag_);
+  }
+  if (from == nil) {
+    from = surfaceRoot_;
+  }
+  return deliverKeyFrom(from, pressed);
+}
+
+bool AppKitFocusManager::activateFocused() {
+  if (focusedTag_ == 0) {
+    return false;
+  }
+  // A <Switch> is toggled from here too. It listens for no click -- React
+  // Native's is a controlled component driven by its own native control -- so
+  // without this a switch that Tab reaches is one Enter cannot work. The same
+  // call the touch path makes, and a no-op for every view that is not a switch.
+  mountingManager_->pressedView(focusedTag_);
+  return dispatchClick(focusedTag_);
+}
+
+bool AppKitFocusManager::dispatchClick(Tag tag) {
+  // True whether or not anything is listening: the key belongs to the focused
+  // view either way, and letting it travel on because a view between a Remove
+  // and its Delete has no emitter would deliver it somewhere else.
+  const auto emitter = mountingManager_->eventEmitterForTag(tag);
+  if (emitter == nullptr) {
+    return true;
+  }
+  // `topClick` with an empty payload, which is exactly what React Native for
+  // Android sends from a focusable view's OnClickListener. It cannot go through
+  // TouchEventEmitter::onClick: that carries a PointerEvent, and Pressability
+  // ignores a click with a `pointerType` on it so that a real click does not
+  // fire onPress twice. See the header.
+  emitter->dispatchEvent("click", folly::dynamic::object(), RawEvent::Category::Discrete);
+  return true;
+}
+
+namespace {
+
+// Everything Tab should stop on, in tree order.
+//
+// Tree order rather than paint order: zIndex changes what is on top and must
+// not change what Tab reaches next, which is also what the GTK side's chain
+// does. A <TextInput> contributes its peer rather than its view, because the
+// peer is the thing AppKit will make first responder -- so a field sits in the
+// same order as the buttons around it without this file knowing what a text
+// input is beyond that.
+void collectFocusStops(RnAppKitView *view, NSMutableArray<RnAppKitView *> *stops) {
+  if (view == nil || view.hidden) {
+    return;
+  }
+  if (view.rnEditable != nil || view.rnFocusable) {
+    [stops addObject:view];
+  }
+  for (NSView *child in view.subviews) {
+    if ([child isKindOfClass:[RnAppKitView class]]) {
+      collectFocusStops((RnAppKitView *)child, stops);
+    }
+  }
+}
+
+// What AppKit should be asked to make first responder for a stop.
+NSResponder *responderForStop(RnAppKitView *view) {
+  return view.rnEditable != nil ? (NSResponder *)view.rnEditable : (NSResponder *)view;
+}
+
+// Whether this stop is the one that holds focus now. Not just a pointer
+// comparison: while a single-line field is being edited the first responder is
+// its *field editor* rather than the field.
+bool stopHoldsFocus(RnAppKitView *view, NSResponder *current) {
+  if (current == nil) {
+    return false;
+  }
+  if (responderForStop(view) == current) {
+    return true;
+  }
+  return view.rnEditable != nil && RnPeerEditor(view.rnEditable) == current;
+}
+
+} // namespace
+
+bool AppKitFocusManager::moveFocus(bool forward) {
+  NSWindow *window = surfaceRoot_.window;
+  if (window == nil) {
+    return false;
+  }
+
+  NSMutableArray<RnAppKitView *> *stops = [NSMutableArray array];
+  collectFocusStops(surfaceRoot_, stops);
+  if (stops.count == 0) {
+    return false;
+  }
+
+  // Where focus is now. Not focusedTag_: a <TextInput> holds focus through its
+  // peer and never reports a tag here, so the responder is the question with an
+  // answer for both kinds of stop.
+  NSResponder *current = window.firstResponder;
+  NSUInteger index = [stops indexOfObjectPassingTest:^BOOL(RnAppKitView *stop, NSUInteger, BOOL *) {
+    return stopHoldsFocus(stop, current) ? YES : NO;
+  }];
+
+  NSUInteger next = 0;
+  if (index == NSNotFound) {
+    next = forward ? 0 : stops.count - 1;
+  } else if (forward) {
+    next = (index + 1) % stops.count;
+  } else {
+    next = (index + stops.count - 1) % stops.count;
+  }
+  // Wrapping, unlike GTK's `gtk_widget_child_focus` on a container, which stops
+  // at the end. A window's Tab order wraps on both desktops, and this is the
+  // window's order.
+  return [window makeFirstResponder:responderForStop(stops[next])] == YES;
+}
+
+} // namespace basalt