Introducing RCTSurface, new experimental thread-safe interop layer

Summary:
RCTSurface instance represents React Native-powered piece of a user interface
which can be a full-screen app, separate modal view controller,
or even small widget. It is called "Surface".

The RCTSurface instance is completely thread-safe by design;
it can be created on any thread, and any its method can be called from
any thread (if the opposite is not mentioned explicitly).
The primary goals of the RCTSurface are:
 - ability to measure and layout the surface in a thread-safe and synchronous manner;
 - ability to create a UIView instance on demand (later);
 - ability to communicate the current stage of the surface granularly.

Differential Revision: D6202576

fbshipit-source-id: 8e644c87fcaad2b6a9c9304b58384d7192747556

Author: shergin

React/Base/Surface/RCTSurface.h

@@ -0,0 +1,119 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ */
+
+#import <Foundation/Foundation.h>
+
+#import <React/RCTSurfaceStage.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class RCTBridge;
+@class RCTSurfaceView;
+@protocol RCTSurfaceDelegate;
+
+/**
+ * RCTSurface instance represents React Native-powered piece of a user interface
+ * which can be a full-screen app, separate modal view controller,
+ * or even small widget.
+ * It is called "Surface".
+ *
+ * The RCTSurface instance is completely thread-safe by design;
+ * it can be created on any thread, and any its method can be called from
+ * any thread (if the opposite is not mentioned explicitly).
+ *
+ * The primary goals of the RCTSurface are:
+ *  * ability to measure and layout the surface in a thread-safe
+ *    and synchronous manner;
+ *  * ability to create a UIView instance on demand (later);
+ *  * ability to communicate the current stage of the surface granularly.
+ */
+@interface RCTSurface : NSObject
+
+@property (atomic, readonly) RCTSurfaceStage stage;
+@property (atomic, readonly) RCTBridge *bridge;
+@property (atomic, readonly) NSString *moduleName;
+@property (atomic, readonly) NSNumber *rootViewTag;
+
+@property (atomic, readwrite, weak, nullable) id<RCTSurfaceDelegate> delegate;
+
+@property (atomic, copy, readwrite) NSDictionary *properties;
+
+- (instancetype)initWithBridge:(RCTBridge *)bridge
+                    moduleName:(NSString *)moduleName
+             initialProperties:(NSDictionary *)initialProperties NS_DESIGNATED_INITIALIZER;
+
+#pragma mark - Dealing with UIView representation, the Main thread only access
+
+/**
+ * Creates (if needed) and returns `UIView` instance which represents the Surface.
+ * The Surface will cache and *retain* this object.
+ * Returning the UIView instance does not mean that the Surface is ready
+ * to execute and layout. It can be just a handler which Surface will use later
+ * to mount the actual views.
+ * RCTSurface does not control (or influence in any way) the size or origin
+ * of this view. Some superview (or another owner) must use other methods
+ * of this class to setup proper layout and interop interactions with UIKit
+ * or another UI framework.
+ * This method must be called only from the main queue.
+ */
+- (RCTSurfaceView *)view;
+
+#pragma mark - Layout: Setting the size constrains
+
+/**
+ * Sets `minimumSize` and `maximumSize` layout constraints for the Surface.
+ */
+- (void)setMinimumSize:(CGSize)minimumSize
+           maximumSize:(CGSize)maximumSize;
+
+/**
+ * Previously set `minimumSize` layout constraint.
+ * Defaults to `{0, 0}`.
+ */
+@property (atomic, assign, readonly) CGSize minimumSize;
+
+/**
+ * Previously set `maximumSize` layout constraint.
+ * Defaults to `{INFINITY, INFINITY}`.
+ */
+@property (atomic, assign, readonly) CGSize maximumSize;
+
+
+/**
+ * Simple shortcut to `-[RCTSurface setMinimumSize:size maximumSize:size]`.
+ */
+- (void)setSize:(CGSize)size;
+
+#pragma mark - Layout: Measuring
+
+/**
+ * Measures the Surface with given constraints.
+ * This method does not cause any side effects on the surface object.
+ */
+- (CGSize)sizeThatFitsMinimumSize:(CGSize)minimumSize
+                      maximumSize:(CGSize)maximumSize;
+
+/**
+ * Return the current size of the root view based on (but not clamp by) current
+ * size constraints.
+ */
+@property (atomic, assign, readonly) CGSize intrinsicSize;
+
+#pragma mark - Synchronous waiting
+
+/**
+ * Synchronously blocks the current thread up to given `timeout` until
+ * the Surface will not have given `stage`.
+ * Do nothing, if called from the main or `UIManager` queue.
+ */
+- (BOOL)synchronouslyWaitForStage:(RCTSurfaceStage)stage timeout:(NSTimeInterval)timeout;
+
+@end
+
+NS_ASSUME_NONNULL_END