@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/ios/Layouts/Root/ANNSplashViewController.h

@@ -0,0 +1,30 @@
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// What the navigation's window shows while it has no root of the app: the copy of the launch screen at the start, the
+/// blank screen after a reload of JavaScript. Both count as the splash: a root without an animation of its own replaces
+/// either at once. The status bar follows the Info.plist keys `UIStatusBarStyle` and `UIStatusBarHidden`. Main queue.
+@interface ANNSplashViewController : UIViewController
+
+/// The copy of the launch screen: the initial view controller of `UILaunchStoryboardName` as a child (a storyboard
+/// that doesn't load: the first view of the nib of that name), else the legacy launch images, full screen. Nil when the
+/// app has none of these: the window then has no root view controller until the first root.
++ (nullable instancetype)launchScreenCopyWithBounds:(CGRect)bounds;
+
+/// The blank screen after a reload: clear when the default options give the window a color (`window.backgroundColor`),
+/// else the system background.
++ (instancetype)blankScreen;
+
+/// Whether this is the blank screen of a reload.
+@property(nonatomic, readonly) BOOL isBlankScreen;
+
+- (instancetype)initWithNibName:(nullable NSString *)nibNameOrNil
+                         bundle:(nullable NSBundle *)nibBundleOrNil NS_UNAVAILABLE;
+- (nullable instancetype)initWithCoder:(NSCoder *)coder NS_UNAVAILABLE;
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Layouts/Root/ANNSplashViewController.mm

@@ -0,0 +1,138 @@
+#import "ANNSplashViewController.h"
+#import "ANNDefaultOptions.h"
+
+// The legacy launch images by the screen's height in points: `Default` with its suffix, then the names an asset
+// catalog's `LaunchImage` set compiles to. `UIImage` picks the scale.
+static NSArray<NSString *> *ANNLegacyLaunchImageNames(CGFloat height) {
+    NSMutableArray<NSString *> *names = [NSMutableArray new];
+    NSDictionary<NSNumber *, NSArray<NSString *> *> *byHeight = @{
+        @568 : @[ @"Default-568h", @"LaunchImage-700-568h" ],
+        @667 : @[ @"Default-667h", @"LaunchImage-800-667h" ],
+        @736 : @[ @"Default-736h", @"LaunchImage-800-Portrait-736h" ],
+        @812 : @[ @"Default-812h", @"LaunchImage-1100-Portrait-2436h" ],
+    };
+    NSArray<NSString *> *sized = byHeight[@((NSInteger)round(height))];
+    if (sized) {
+        [names addObjectsFromArray:sized];
+    }
+    // The sets the Info.plist lists (`UILaunchImages`), for this size.
+    NSArray *launchImages = [NSBundle.mainBundle objectForInfoDictionaryKey:@"UILaunchImages"];
+    if ([launchImages isKindOfClass:NSArray.class]) {
+        for (NSDictionary *entry in launchImages) {
+            if (![entry isKindOfClass:NSDictionary.class]) {
+                continue;
+            }
+            NSString *name = entry[@"UILaunchImageName"];
+            NSString *size = entry[@"UILaunchImageSize"];
+            if ([name isKindOfClass:NSString.class] && [size isKindOfClass:NSString.class] &&
+                CGSizeFromString(size).height == round(height)) {
+                [names addObject:name];
+            }
+        }
+    }
+    [names addObjectsFromArray:@[ @"Default", @"LaunchImage" ]];
+    return names;
+}
+
+@implementation ANNSplashViewController {
+    UIViewController *_content;
+    UIView *_contentView;
+}
+
+- (instancetype)initWithContent:(UIViewController *)content
+                    contentView:(UIView *)contentView
+                          blank:(BOOL)blank {
+    if (self = [super initWithNibName:nil bundle:nil]) {
+        _content = content;
+        _contentView = contentView;
+        _isBlankScreen = blank;
+    }
+    return self;
+}
+
++ (instancetype)launchScreenCopyWithBounds:(CGRect)bounds {
+    NSBundle *bundle = NSBundle.mainBundle;
+    NSString *storyboardName = [bundle objectForInfoDictionaryKey:@"UILaunchStoryboardName"];
+    if ([storyboardName isKindOfClass:NSString.class] && storyboardName.length > 0) {
+        UIViewController *initial = nil;
+        @try {
+            UIStoryboard *storyboard = [UIStoryboard storyboardWithName:storyboardName bundle:nil];
+            initial = [storyboard instantiateInitialViewController];
+        } @catch (NSException *exception) {
+            initial = nil;
+        }
+        if (initial) {
+            return [[self alloc] initWithContent:initial contentView:nil blank:NO];
+        }
+        if ([bundle pathForResource:storyboardName ofType:@"nib"]) {
+            for (id object in [bundle loadNibNamed:storyboardName owner:nil options:nil]) {
+                if ([object isKindOfClass:UIView.class]) {
+                    return [[self alloc] initWithContent:nil contentView:object blank:NO];
+                }
+            }
+        }
+    }
+    for (NSString *name in ANNLegacyLaunchImageNames(bounds.size.height)) {
+        UIImage *image = [UIImage imageNamed:name];
+        if (image) {
+            UIImageView *imageView = [[UIImageView alloc] initWithImage:image];
+            imageView.contentMode = UIViewContentModeScaleAspectFill;
+            imageView.clipsToBounds = YES;
+            return [[self alloc] initWithContent:nil contentView:imageView blank:NO];
+        }
+    }
+    return nil;
+}
+
++ (instancetype)blankScreen {
+    return [[self alloc] initWithContent:nil contentView:nil blank:YES];
+}
+
+- (void)viewDidLoad {
+    [super viewDidLoad];
+    UIView *view = self.view;
+    if (_isBlankScreen) {
+        // Over the window's own color when the app gave it one.
+        BOOL windowHasColor = ANNDefaultOptions.current.window.backgroundColor.hasValue;
+        view.backgroundColor = windowHasColor ? UIColor.clearColor : UIColor.systemBackgroundColor;
+        return;
+    }
+    UIView *contentView = _contentView;
+    if (_content) {
+        [self addChildViewController:_content];
+        contentView = _content.view;
+    }
+    contentView.frame = view.bounds;
+    contentView.autoresizingMask =
+        UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+    [view addSubview:contentView];
+    [_content didMoveToParentViewController:self];
+}
+
+#pragma mark - The status bar, as the launch screen had it
+
+- (UIStatusBarStyle)preferredStatusBarStyle {
+    NSString *style = [NSBundle.mainBundle objectForInfoDictionaryKey:@"UIStatusBarStyle"];
+    if ([style isEqual:@"UIStatusBarStyleLightContent"]) {
+        return UIStatusBarStyleLightContent;
+    }
+    if ([style isEqual:@"UIStatusBarStyleDarkContent"]) {
+        return UIStatusBarStyleDarkContent;
+    }
+    return UIStatusBarStyleDefault;
+}
+
+- (BOOL)prefersStatusBarHidden {
+    id hidden = [NSBundle.mainBundle objectForInfoDictionaryKey:@"UIStatusBarHidden"];
+    return [hidden respondsToSelector:@selector(boolValue)] && [hidden boolValue];
+}
+
+- (UIViewController *)childViewControllerForStatusBarStyle {
+    return nil;
+}
+
+- (UIViewController *)childViewControllerForStatusBarHidden {
+    return nil;
+}
+
+@end

package/ios/Layouts/Screen/ANNComponentPresenter.h

@@ -0,0 +1,32 @@
+#import "ANNNodePresenter.h"
+
+@class ANNTopBarPresenter;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The presenter of a screen (`Component`, `ExternalComponent`): the background, the status bar's blur
+/// (`statusBar.blur`), the "under bars" rule with the root frame and the safe area again on `mergeOptions`
+/// (`mergeOptions` step 4), and the screen's part of the top bar (`topBar`). It applies at the screen's creation, at
+/// each appearance (the screen's `screenWillAppear`, the path of every report), at a `mergeOptions` of the screen, and
+/// on new default options.
+@interface ANNComponentPresenter : ANNNodePresenter
+
+/// The screen's part of the bar: its item, its bar components, its lists (made as the presenter binds its screen).
+@property(nonatomic, strong, readonly, nullable) ANNTopBarPresenter *topBar;
+
+/// The screen's view gets `layout.backgroundColor` (the system background without it, clear for "no color"); the
+/// content (the React root; a slot screen's container) gets `layout.componentBackgroundColor` over it, clear without
+/// it. Nothing before the screen's view is loaded.
+- (void)applyBackground:(ANNNavigationOptions *)resolvedOptions;
+
+/// `statusBar.blur` (iOS): UIKit's regular blur over the screen's own view in the frame of the scene's status bar at
+/// this moment (x 0, the view's width; it doesn't follow a rotation); `false` or none removes it. At each appearance
+/// and at a merge that names it; nothing before the screen's view is loaded.
+- (void)applyStatusBarBlur:(ANNNavigationOptions *)resolvedOptions;
+
+/// The blur stays the last subview of the screen's view: the content added after it goes under it.
+- (void)keepStatusBarBlurOnTop;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Layouts/Screen/ANNComponentPresenter.mm

@@ -0,0 +1,136 @@
+#import "ANNComponentPresenter.h"
+#import "ANNBottomTabsController.h"
+#import "ANNComponentViewController.h"
+#import "ANNDefaultOptions.h"
+#import "ANNTopBarPresenter.h"
+#import "ANNUtils.h"
+
+@implementation ANNComponentPresenter {
+    // `statusBar.blur` while it is on.
+    UIVisualEffectView *_statusBarBlur;
+}
+
+- (nullable ANNComponentViewController *)screen {
+    UIViewController *bound = self.boundViewController;
+    return [bound isKindOfClass:ANNComponentViewController.class] ? (ANNComponentViewController *)bound
+                                                                    : nil;
+}
+
+#pragma mark - ANNNodePresenter
+
+// The bar's part comes with the screen: its registry takes the screen's creator, set before the presenter binds.
+- (void)bindViewController:(UIViewController *)viewController {
+    [super bindViewController:viewController];
+    if (!_topBar && [viewController isKindOfClass:ANNComponentViewController.class]) {
+        _topBar = [[ANNTopBarPresenter alloc] initWithScreen:viewController];
+    }
+}
+
+// The screen has no view yet at its creation (a screen not shown at once makes its content when UIKit first loads its
+// view): its background comes when the view loads. Its bar takes the screen's own options over the defaults now (the
+// stack's aren't known yet).
+- (void)applyOptionsOnInit:(ANNNavigationOptions *)initialOptions {
+    [super applyOptionsOnInit:initialOptions];
+    [_topBar applyOptionsOnInit:[initialOptions withDefault:ANNDefaultOptions.current]];
+}
+
+// Each appearance, with the options of the stack and the tabs the screen is in now: the bar first (it may show or hide
+// the stack's bar), then the containers around the screen, then the rule of the root frame.
+- (void)applyOptions:(ANNNavigationOptions *)options {
+    [super applyOptions:options];
+    [self applyBackground:options];
+    [self applyStatusBarBlur:options];
+    [_topBar applyOptions:options];
+    // The tabs follow the screen their selected tab shows: their bar's look and visibility, before the screen reads
+    // whether a tab bar shows (`hasShownTabBar`).
+    UIViewController *bound = self.boundViewController;
+    if (bound) {
+        [[ANNBottomTabsController tabsOf:bound] screenWillAppear:bound options:options];
+        // A container that applies its options at every appearance of a screen inside it (a side menu) does it now, the
+        // nearest first.
+        for (UIViewController *parent = bound.layoutParent; parent.isLayoutNode;
+             parent = parent.layoutParent) {
+            [parent.presenter descendantWillAppear:bound];
+        }
+    }
+    [self.screen updateRootLayout];
+}
+
+// The rule and the safe area are read again on every merge: the edges, the large title or the bars may have changed
+// (`mergeOptions` step 4).
+- (void)mergeOptions:(ANNNavigationOptions *)mergeOptions
+     resolvedOptions:(ANNNavigationOptions *)resolvedOptions {
+    [super mergeOptions:mergeOptions resolvedOptions:resolvedOptions];
+    ANNLayoutOptions *layout = mergeOptions.layout;
+    if (layout.backgroundColor.hasValue || layout.componentBackgroundColor.hasValue) {
+        [self applyBackground:resolvedOptions];
+    }
+    if (mergeOptions.statusBar.blur.hasValue) {
+        [self applyStatusBarBlur:resolvedOptions];
+    }
+    [_topBar mergeOptions:mergeOptions resolvedOptions:resolvedOptions];
+    [self.screen updateRootLayout];
+}
+
+// New default options repaint the background and the bar; the rule and the safe area stay.
+- (void)applyDefaultOptionsChange:(ANNNavigationOptions *)resolvedOptions {
+    [super applyDefaultOptionsChange:resolvedOptions];
+    [self applyBackground:resolvedOptions];
+    [_topBar applyDefaultOptionsChange:resolvedOptions];
+}
+
+#pragma mark - Background
+
+- (void)applyBackground:(ANNNavigationOptions *)resolvedOptions {
+    ANNComponentViewController *screen = self.screen;
+    if (!screen.isViewLoaded) {
+        return;
+    }
+    ANNLayoutOptions *layout = resolvedOptions.layout;
+    screen.view.backgroundColor =
+        [layout.backgroundColor withDefault:UIColor.systemBackgroundColor] ?: UIColor.clearColor;
+    screen.reactView.backgroundColor =
+        [layout.componentBackgroundColor withDefault:UIColor.clearColor] ?: UIColor.clearColor;
+}
+
+#pragma mark - The status bar's blur (`statusBar.blur`)
+
+// Over the screen's own view, never over a React view; no touches, nothing for VoiceOver. The frame is the scene's
+// status bar's as it is now, in the view's own coordinates without a conversion: a pushed screen's view may still be
+// out of place while it appears.
+- (void)applyStatusBarBlur:(ANNNavigationOptions *)resolvedOptions {
+    ANNComponentViewController *screen = self.screen;
+    if (!screen.isViewLoaded) {
+        return;
+    }
+    if (![resolvedOptions.statusBar.blur withDefault:NO]) {
+        [_statusBarBlur removeFromSuperview];
+        _statusBarBlur = nil;
+        return;
+    }
+    UIView *view = screen.view;
+    if (!_statusBarBlur) {
+        UIBlurEffect *effect = [UIBlurEffect effectWithStyle:UIBlurEffectStyleRegular];
+        _statusBarBlur = [[UIVisualEffectView alloc] initWithEffect:effect];
+        _statusBarBlur.userInteractionEnabled = NO;
+        _statusBarBlur.isAccessibilityElement = NO;
+        _statusBarBlur.accessibilityElementsHidden = YES;
+    }
+    CGRect statusBar = ANNUtils.statusBarFrame;
+    _statusBarBlur.frame = CGRectMake(0, CGRectGetMinY(statusBar), CGRectGetWidth(view.bounds),
+                                      CGRectGetHeight(statusBar));
+    if (_statusBarBlur.superview != view) {
+        [view addSubview:_statusBarBlur];
+    } else {
+        [view bringSubviewToFront:_statusBarBlur];
+    }
+}
+
+- (void)keepStatusBarBlurOnTop {
+    UIView *superview = _statusBarBlur.superview;
+    if (superview && superview.subviews.lastObject != _statusBarBlur) {
+        [superview bringSubviewToFront:_statusBarBlur];
+    }
+}
+
+@end

package/ios/Layouts/Screen/ANNComponentViewController.h

@@ -0,0 +1,100 @@
+#import "ANNArrangementScreenDelegate.h"
+#import "ANNLayoutProtocol.h"
+#import "ANNScreenAppearance.h"
+#import "UIViewController+LayoutProtocol.h"
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// A screen of the layout (`Component`): its content is a React view, or the slot screen view of one React tree.
+///
+/// Its view has the size of the screen of the navigation window's scene; the content sits in the root frame, by the one
+/// "under bars" rule (`ANNScreenBars`). Every recompute of the frame (a layout, a change of the safe area or the
+/// traits, `mergeOptions`, an appearance) gives the modules the screen's insets, padding and regions
+/// (`ANNScreenInsets`, `ANNScreenRegions`). Its presenter is an `ANNComponentPresenter`.
+///
+/// The screen answers UIKit's questions about the system UI (native screens too): the status bar's style and visibility
+/// (never animated), the orientations, the home indicator, the deferred edges and the vertical bars, from its resolved
+/// options by its presenter's rules; a screen of an overlay by the overlay's own options, or as the main window's
+/// deciding controller answers for what the overlay doesn't set (`ANNSystemUI`). Its appearance and disappearance mark
+/// the system UI's owner.
+///
+/// The screen reports its appearance through its content's record (`ANNScreenAppearance`, sent by
+/// `ANNAppearanceDispatcher`): UIKit's appearance callbacks, which reach a child through containment, and the
+/// dispatcher's node walkers both call `screenWillAppear`, `screenDidAppear`, `screenDidDisappear`; whichever comes
+/// second finds the phase set and sends nothing. UIKit's callbacks do nothing while a command drives the screen's
+/// appearance (`+[ANNAppearanceDispatcher isAppearanceDriven:]`).
+@interface ANNComponentViewController : UIViewController <ANNLayoutProtocol>
+
+- (instancetype)initWithLayoutInfo:(ANNLayoutInfo *)layoutInfo
+                           creator:(id<ANNComponentViewCreator>)creator
+                           options:(ANNNavigationOptions *)options
+                    defaultOptions:(ANNNavigationOptions *)defaultOptions
+                         presenter:(ANNNodePresenter *)presenter
+                      eventEmitter:(ANNEventEmitter *)eventEmitter
+              childViewControllers:(nullable NSArray<UIViewController *> *)childViewControllers;
+
+/// What the screen shows; nil before the screen made it (`render`).
+@property(nonatomic, strong, readonly, nullable) UIView<ANNComponentProtocol> *reactView;
+
+/// Makes the content with the node's creator, once, in the root frame of the screen's view: a React surface starts,
+/// or the slot screen view takes its slot. The screen is ready (`readyForPresentation`) once its content is. A screen
+/// nobody rendered gets its content when UIKit first loads its view.
+- (void)render;
+
+/// Applies the "under bars" rule to the root frame again, then gives the modules the insets, the padding and the
+/// regions of the screen. Nothing before the view loaded; the safe area only in a window.
+- (void)updateRootLayout;
+
+/// The content view (only the core's React view, never the screen's own view) mounts unseen in `host` (the tabs'
+/// preload window) at the frame it has, while the screen's tab isn't shown. NO when there is nothing to lend: no React
+/// view of its own, in a window already, lent already, or the screen went.
+- (BOOL)lendContentTo:(UIView *)host;
+
+/// The lent content comes back into the screen's view at its root frame; also as the screen first appears.
+- (void)takeContentBack;
+
+/// The content is lent (`lendContentTo:`): `updateRootLayout` leaves its frame alone meanwhile.
+@property(nonatomic, readonly) BOOL contentIsLent;
+
+/// The transition that removes the screen starts (before its destroy): with `blurOnUnmount` in its resolved options,
+/// the editing inside its view ends and the keyboard goes (`blurOnUnmount`).
+- (void)screenWillLeave;
+
+/// `screenWillLeave` of every screen of the layout subtree of `node`.
++ (void)nodeWillLeave:(UIViewController *)node;
+
+/// The navigation controller that shows the screen's stack: the stack, or UIKit's More navigation while a tab of More
+/// holds its screens; nil out of a stack. Its bar is the one `statusBar.hideWithTopBar` follows.
+- (nullable UINavigationController *)shownNavigation;
+
+/// The pair the screen is in (`ANNArrangementViewController`): the screen tells it when it lays out, appears,
+/// disappears or its traits change, and when it sets its toolbar items.
+@property(nonatomic, weak, nullable) id<ANNArrangementScreenDelegate> arrangement;
+
+/// `keyCommands`: the screen becomes the first responder when it is in a window, has commands (its own, else its
+/// nearest layout parent's) and nothing takes the keyboard; never while it waits unseen (parked, or in a layer that
+/// waits to show) or is a preview's screen. The screen tries after its appearance, once JavaScript heard its
+/// `DidAppear`, and on the next turn after an edit ended; a merge that names `keyCommands` makes the screens of its
+/// node try. Whether it became the first responder.
+- (BOOL)takeKeyCommandsFocus;
+
+/// The record the screen reports its appearance with: its content's, or a native screen's own; nil while a React
+/// screen has no content yet. A command whose readiness wait ended calls its `markReady`.
+@property(nonatomic, readonly, nullable) ANNScreenAppearance *appearance;
+
+/// The screen starts to appear, appeared, disappeared: `ANN.ComponentWillAppear`, `DidAppear`, `DidDisappear` through
+/// the dispatcher. `screenWillAppear` first applies the screen's resolved options (its presenter's `applyOptions:`).
+- (void)screenWillAppear;
+- (void)screenDidAppear;
+- (void)screenDidDisappear;
+
+/// Once, in this order: `DidDisappear` if the screen showed (where UIKit doesn't send it: `setRoot`, `dismissOverlay`,
+/// a pop that stops the content), the registry forgets it, its content stops, the content view leaves the screen's
+/// view, and its data by id (insets, regions, the pair's state, readiness) goes when no other node has the id. A second
+/// call does nothing.
+- (void)destroy;
+
+@end
+
+NS_ASSUME_NONNULL_END