feat: add WindowManagerMacOS for multi-window support

.changeset/multi-window-support.md

@@ -0,0 +1,5 @@
+---
+'react-native-macos': patch
+---
+
+Add `WindowManagerMacOS`, an API for opening and managing additional windows from JavaScript. Each window hosts its own React root (registered via `AppRegistry.registerComponent`) while sharing a single bridge and JavaScript runtime. Also makes `RCTKeyWindow()` fall back to the main window and then any visible window, so `Dimensions` no longer reports a zero-sized window when no window has key focus.

packages/react-native/Libraries/WindowManager/NativeWindowManagerMacOS.js

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+export * from '../../src/private/specs_DEPRECATED/modules/NativeWindowManagerMacOS';
+import NativeWindowManagerMacOS from '../../src/private/specs_DEPRECATED/modules/NativeWindowManagerMacOS';
+
+export default NativeWindowManagerMacOS;

packages/react-native/Libraries/WindowManager/WindowManagerMacOS.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ *
+ * @format
+ */
+
+// [macOS]
+
+import type {EventSubscription} from '../vendor/emitter/EventEmitter';
+
+export type WindowManagerEventMap = {
+  windowDidOpen: WindowInfo;
+  windowDidClose: {key: string; moduleName: string};
+  windowDidFocus: WindowInfo;
+  windowDidBlur: WindowInfo;
+  windowDidResize: WindowInfo;
+};
+
+export interface WindowOptions {
+  moduleName: string;
+  key?: string | undefined;
+  initialProps?: Object | undefined;
+  title?: string | undefined;
+  width?: number | undefined;
+  height?: number | undefined;
+  minWidth?: number | undefined;
+  minHeight?: number | undefined;
+  x?: number | undefined;
+  y?: number | undefined;
+  resizable?: boolean | undefined;
+  closable?: boolean | undefined;
+  minimizable?: boolean | undefined;
+  titlebarAppearsTransparent?: boolean | undefined;
+  hidesOnDeactivate?: boolean | undefined;
+  alwaysOnTop?: boolean | undefined;
+  rememberFrame?: boolean | undefined;
+  focus?: boolean | undefined;
+}
+
+export interface WindowInfo {
+  key: string;
+  moduleName: string;
+  title: string;
+  width: number;
+  height: number;
+  x: number;
+  y: number;
+  isKey: boolean;
+  isVisible: boolean;
+}
+
+export interface WindowManagerMacOSImpl {
+  isSupported: boolean;
+  addListener<K extends keyof WindowManagerEventMap>(
+    eventType: K,
+    listener: (event: WindowManagerEventMap[K]) => void,
+    context?: unknown,
+  ): EventSubscription;
+  removeAllListeners<K extends keyof WindowManagerEventMap>(
+    eventType?: K | null,
+  ): void;
+  open(options: WindowOptions): Promise<WindowInfo>;
+  close(key: string): Promise<boolean>;
+  focus(key: string): Promise<boolean>;
+  setTitle(key: string, title: string): Promise<boolean>;
+  isOpen(key: string): Promise<boolean>;
+  getWindows(): Promise<WindowInfo[]>;
+}
+
+export const WindowManagerMacOS: WindowManagerMacOSImpl;
+export type WindowManagerMacOS = WindowManagerMacOSImpl;

packages/react-native/Libraries/WindowManager/WindowManagerMacOS.js

@@ -0,0 +1,199 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import type {EventSubscription} from '../vendor/emitter/EventEmitter';
+
+import NativeEventEmitter from '../EventEmitter/NativeEventEmitter';
+import NativeWindowManagerMacOS from './NativeWindowManagerMacOS';
+
+export type WindowOptions = {
+  +moduleName: string,
+  +key?: ?string,
+  // $FlowFixMe[unclear-type] unclear type of arbitrary initial props
+  +initialProps?: ?Object,
+  +title?: ?string,
+  +width?: ?number,
+  +height?: ?number,
+  +minWidth?: ?number,
+  +minHeight?: ?number,
+  +x?: ?number,
+  +y?: ?number,
+  +resizable?: ?boolean,
+  +closable?: ?boolean,
+  +minimizable?: ?boolean,
+  +titlebarAppearsTransparent?: ?boolean,
+  +hidesOnDeactivate?: ?boolean,
+  +alwaysOnTop?: ?boolean,
+  +rememberFrame?: ?boolean,
+  +focus?: ?boolean,
+};
+
+export type WindowInfo = {
+  +key: string,
+  +moduleName: string,
+  +title: string,
+  +width: number,
+  +height: number,
+  +x: number,
+  +y: number,
+  +isKey: boolean,
+  +isVisible: boolean,
+};
+
+type WindowManagerEventMap = {
+  windowDidOpen: [WindowInfo],
+  windowDidClose: [{key: string, moduleName: string}],
+  windowDidFocus: [WindowInfo],
+  windowDidBlur: [WindowInfo],
+  windowDidResize: [WindowInfo],
+};
+
+function rejectNotSupported<T>(): Promise<T> {
+  return Promise.reject(
+    new Error('WindowManagerMacOS is only available on macOS'),
+  );
+}
+
+/**
+ * `WindowManagerMacOS` lets you open additional NSWindows, each hosting its
+ * own React root, from JavaScript.
+ *
+ * First register the component you want to display in a window, just like
+ * any other app key:
+ *
+ *   AppRegistry.registerComponent('Settings', () => SettingsScreen);
+ *
+ * Then open a window for it:
+ *
+ *   WindowManagerMacOS.open({
+ *     moduleName: 'Settings',
+ *     title: 'Settings',
+ *     width: 480,
+ *     height: 360,
+ *   });
+ *
+ * All windows share a single bridge and JavaScript runtime, so plain module
+ * state (or any store) is visible to every window. Note that
+ * `Dimensions`/`useWindowDimensions` still report the app's key window, not
+ * the window a given root is rendered into.
+ */
+class WindowManagerMacOS {
+  /**
+   * Whether the native module backing this API is present. It is only ever
+   * true on macOS.
+   */
+  isSupported: boolean = NativeWindowManagerMacOS != null;
+
+  _emitter: ?NativeEventEmitter<WindowManagerEventMap> = null;
+
+  /**
+   * The emitter is created lazily and never in the constructor: on iOS and
+   * macOS `new NativeEventEmitter()` asserts on a null module, so building it
+   * eagerly would make merely importing this module throw on every platform
+   * that has no window manager — defeating the `isSupported` check below.
+   */
+  _getEmitter(): NativeEventEmitter<WindowManagerEventMap> {
+    let emitter = this._emitter;
+    if (emitter == null) {
+      if (NativeWindowManagerMacOS == null) {
+        throw new Error('WindowManagerMacOS is only available on macOS');
+      }
+      emitter = new NativeEventEmitter<WindowManagerEventMap>(
+        NativeWindowManagerMacOS,
+      );
+      this._emitter = emitter;
+    }
+    return emitter;
+  }
+
+  /**
+   * Subscribe to window lifecycle events. Throws on platforms where
+   * `isSupported` is false.
+   */
+  addListener<TEvent: $Keys<WindowManagerEventMap>>(
+    eventType: TEvent,
+    listener: (...args: WindowManagerEventMap[TEvent]) => mixed,
+    context?: mixed,
+  ): EventSubscription {
+    return this._getEmitter().addListener(eventType, listener, context);
+  }
+
+  removeAllListeners<TEvent: $Keys<WindowManagerEventMap>>(
+    eventType: ?TEvent,
+  ): void {
+    if (this._emitter != null) {
+      this._emitter.removeAllListeners(eventType);
+    }
+  }
+
+  /**
+   * Open a new window hosting `options.moduleName`. If a window with the
+   * same `key` (defaulting to `moduleName`) already exists, it is focused
+   * and its current info is resolved instead of opening a new window.
+   */
+  open(options: WindowOptions): Promise<WindowInfo> {
+    if (NativeWindowManagerMacOS == null) {
+      return rejectNotSupported();
+    }
+    return NativeWindowManagerMacOS.open(options);
+  }
+
+  /**
+   * Close the window registered under `key`.
+   */
+  close(key: string): Promise<boolean> {
+    if (NativeWindowManagerMacOS == null) {
+      return rejectNotSupported();
+    }
+    return NativeWindowManagerMacOS.close(key);
+  }
+
+  /**
+   * Bring the window registered under `key` to the front.
+   */
+  focus(key: string): Promise<boolean> {
+    if (NativeWindowManagerMacOS == null) {
+      return rejectNotSupported();
+    }
+    return NativeWindowManagerMacOS.focus(key);
+  }
+
+  /**
+   * Update the title of the window registered under `key`.
+   */
+  setTitle(key: string, title: string): Promise<boolean> {
+    if (NativeWindowManagerMacOS == null) {
+      return rejectNotSupported();
+    }
+    return NativeWindowManagerMacOS.setTitle(key, title);
+  }
+
+  /**
+   * Whether a window is currently open for `key`.
+   */
+  isOpen(key: string): Promise<boolean> {
+    if (NativeWindowManagerMacOS == null) {
+      return Promise.resolve(false);
+    }
+    return NativeWindowManagerMacOS.isOpen(key);
+  }
+
+  /**
+   * Info for all currently open windows.
+   */
+  getWindows(): Promise<Array<WindowInfo>> {
+    if (NativeWindowManagerMacOS == null) {
+      return Promise.resolve([]);
+    }
+    return NativeWindowManagerMacOS.getWindows();
+  }
+}
+
+export default (new WindowManagerMacOS(): WindowManagerMacOS);

packages/react-native/React/Base/RCTUtils.mm

@@ -680,7 +680,23 @@ BOOL RCTRunningInAppExtension(void)
 
   return nil;
 #else // [macOS
-  return [NSApp keyWindow];
+  NSWindow *keyWindow = [NSApp keyWindow];
+  if (keyWindow != nil) {
+    return keyWindow;
+  }
+  // [macOS] With multiple windows open, or while the app is inactive, AppKit may report no key
+  // window at all. Fall back to the main window and then to any visible, focusable window so that
+  // callers (e.g. RCTDeviceInfo's `Dimensions`) never observe a zero-sized window.
+  NSWindow *mainWindow = [NSApp mainWindow];
+  if (mainWindow != nil) {
+    return mainWindow;
+  }
+  for (NSWindow *window in [NSApp windows]) {
+    if (window.isVisible && window.canBecomeKeyWindow) {
+      return window;
+    }
+  }
+  return nil;
 #endif // macOS]
 }
 

packages/react-native/React/CoreModules/CoreModulesPlugins.h

@@ -17,6 +17,7 @@
 // OSS-compatibility layer
 
 #import <Foundation/Foundation.h>
+#import <TargetConditionals.h> // [macOS]
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wreturn-type-c-linkage"
@@ -52,6 +53,9 @@ Class RCTStatusBarManagerCls(void) __attribute__((used));
 Class RCTTimingCls(void) __attribute__((used));
 Class RCTWebSocketModuleCls(void) __attribute__((used));
 Class RCTBlobManagerCls(void) __attribute__((used));
+#if TARGET_OS_OSX // [macOS]
+Class RCTWindowManagerCls(void) __attribute__((used));
+#endif // [macOS]
 
 #ifdef __cplusplus
 }

packages/react-native/React/CoreModules/CoreModulesPlugins.mm

@@ -46,6 +46,9 @@ Class RCTCoreModulesClassProvider(const char *name) {
     {"Timing", RCTTimingCls},
     {"WebSocketModule", RCTWebSocketModuleCls},
     {"BlobModule", RCTBlobManagerCls},
+#if TARGET_OS_OSX // [macOS]
+    {"WindowManagerMacOS", RCTWindowManagerCls},
+#endif // [macOS]
   };
 
   auto p = sCoreModuleClassMap->find(name);

packages/react-native/React/CoreModules/RCTWindowManager.h

@@ -0,0 +1,15 @@
+/*
+ * 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.
+ */
+
+#import <React/RCTUIKit.h> // [macOS]
+
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+@interface RCTWindowManager : RCTEventEmitter <RCTBridgeModule>
+
+@end