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

package/ios/Core/ANNAppDelegate.mm

@@ -0,0 +1,122 @@
+#import "ANNAppDelegate.h"
+#import "ANNDeepLinkQueue.h"
+#import "ANNSceneDelegate.h"
+#import "ApexNavigation+Internal.h"
+#import <React/RCTBridge.h>
+#import <React/RCTLog.h>
+#import <React/RCTUtils.h>
+#import <ReactAppDependencyProvider/RCTAppDependencyProvider.h>
+#import <ReactCommon/RCTHost.h>
+
+// The version of React Native the app builds with (`REACT_NATIVE_VERSION_MINOR`, written by React Native's release
+// script): the calls React Native 0.87 removed are made only below it.
+#if __has_include(<cxxreact/ReactNativeVersion.h>)
+#import <cxxreact/ReactNativeVersion.h>
+#endif
+#if defined(REACT_NATIVE_VERSION_MAJOR) && REACT_NATIVE_VERSION_MAJOR == 0 && \
+    REACT_NATIVE_VERSION_MINOR < 87
+#define ANN_REACT_NATIVE_BEFORE_0_87 1
+#if __has_include(<React-RCTAppDelegate/RCTAppSetupUtils.h>)
+#import <React-RCTAppDelegate/RCTAppSetupUtils.h>
+#elif __has_include(<React_RCTAppDelegate/RCTAppSetupUtils.h>)
+#import <React_RCTAppDelegate/RCTAppSetupUtils.h>
+#else
+#import <React/RCTAppSetupUtils.h>
+#endif
+#endif
+
+#if __has_include(<React-RCTAppDelegate/RCTReactNativeFactory.h>)
+#import <React-RCTAppDelegate/RCTDefaultReactNativeFactoryDelegate.h>
+#import <React-RCTAppDelegate/RCTReactNativeFactory.h>
+#elif __has_include(<React_RCTAppDelegate/RCTReactNativeFactory.h>)
+#import <React_RCTAppDelegate/RCTDefaultReactNativeFactoryDelegate.h>
+#import <React_RCTAppDelegate/RCTReactNativeFactory.h>
+#else
+#import <React/RCTDefaultReactNativeFactoryDelegate.h>
+#import <React/RCTReactNativeFactory.h>
+#endif
+
+// The app declares the scene life cycle: its window shows once the scene connects (`ANNSceneDelegate`).
+static BOOL ANNAppUsesScenes(void) {
+    return [NSBundle.mainBundle objectForInfoDictionaryKey:@"UIApplicationSceneManifest"] != nil;
+}
+
+@implementation ANNAppDelegate
+
+// React Native starts with no surface of its own: the navigation shows every screen. The host starts at once and loads
+// the bundle while the window is made; the first root comes from JavaScript.
+- (BOOL)application:(UIApplication *)application
+    didFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey, id> *)launchOptions {
+    RCTDefaultReactNativeFactoryDelegate *delegate = self.reactNativeDelegate;
+    if (!delegate) {
+        RCTLogError(@"[ApexNavigation] ANNAppDelegate: set reactNativeDelegate before application:"
+                    @"didFinishLaunchingWithOptions: of ANNAppDelegate runs.");
+        return YES;
+    }
+#ifdef ANN_REACT_NATIVE_BEFORE_0_87
+    RCTAppSetupPrepareApp(application, YES);
+    RCTEnableTurboModuleInteropBridgeProxy(YES);
+#endif
+#ifndef RCT_REMOVE_LEGACY_MODULE_INTEROP
+    // The app's modules written for the bridge keep working as TurboModules.
+    RCTEnableTurboModuleInterop(YES);
+#endif
+    // The codegen's provider of the app's modules and components, generated for the app.
+    if (!delegate.dependencyProvider) {
+        delegate.dependencyProvider = [RCTAppDependencyProvider new];
+    }
+    self.reactNativeFactory = [[RCTReactNativeFactory alloc] initWithDelegate:delegate];
+    RCTRootViewFactory *rootViewFactory = self.reactNativeFactory.rootViewFactory;
+    RCTHost *host = [rootViewFactory createReactHost:launchOptions];
+    rootViewFactory.reactHost = host;
+    [ApexNavigation bootstrapWithHost:host];
+    self.window = ApexNavigation.mainWindow;
+    // The links that come before React content wait for it; the launch link waits for the scene.
+    [ANNDeepLinkQueue start];
+    if (!ANNAppUsesScenes()) {
+        [self.window makeKeyAndVisible];
+    }
+    return YES;
+}
+
+- (UISceneConfiguration *)application:(UIApplication *)application
+    configurationForConnectingSceneSession:(UISceneSession *)connectingSceneSession
+                                   options:(UISceneConnectionOptions *)options {
+    UISceneConfiguration *configuration = [connectingSceneSession.configuration copy];
+    // Only the app's own scene takes the navigation window: an external display's scene doesn't.
+    BOOL isAppScene =
+        [connectingSceneSession.role isEqualToString:UIWindowSceneSessionRoleApplication];
+    if (!configuration.delegateClass && isAppScene) {
+        configuration.delegateClass = ANNSceneDelegate.class;
+    }
+    return configuration;
+}
+
+// From any thread (a push SDK calls from its own): the queue lives on the main queue.
+- (void)dispatchDeepLinkURL:(NSURL *)url {
+    if (!url) {
+        return;
+    }
+    RCTExecuteOnMainQueue(^{
+      [ANNDeepLinkQueue dispatchURL:url];
+    });
+}
+
+- (BOOL)application:(UIApplication *)application
+            openURL:(NSURL *)url
+            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
+    [self dispatchDeepLinkURL:url];
+    return YES;
+}
+
+- (BOOL)application:(UIApplication *)application
+    continueUserActivity:(NSUserActivity *)userActivity
+      restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *restorableObjects))restorationHandler {
+    if (![userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
+        return NO;
+    }
+    [self dispatchDeepLinkURL:userActivity.webpageURL];
+    return YES;
+}
+
+@end

package/ios/Core/ANNAppDirection.h

@@ -0,0 +1,43 @@
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The direction of the app: `layout.direction` of the default options, which JS puts there (`createNavigation({
+/// direction })`, `setDirection`), `'ltr'`, `'rtl'` or `'locale'`.
+///
+/// Applied at every `setRoot` (step 1) and every `setDefaultOptions` whose defaults have the key, and only when it
+/// differs from the value applied last: React Native's direction at once; on iOS 17+ the trait of the navigation
+/// window's scene, its windows take it at once, then the shown stacks drop the direction their pushes forced (kept for
+/// later when the window has no scene yet); on iOS 15–16 the appearance of the views made after it. Without the key
+/// nothing changes. Main queue.
+@interface ANNAppDirection : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// `layout.direction` of the default options now, applied as described above.
++ (void)applyDefaultOptionsDirection;
+
+/// The navigation window joined its scene: the scene's part of a direction set before applies now.
++ (void)windowSceneDidConnect;
+
+/// What a push forces on its stack's view and bar before UIKit's change: React Native's direction, without the key or
+/// before iOS 17; with the key on iOS 17+ nothing, so that the stack follows the scene.
+@property(class, nonatomic, readonly) UISemanticContentAttribute pushDirection;
+
+/// React Native lays out from right to left (`I18nManager`): its scroll views are mirrored then, whatever UIKit's
+/// direction.
+@property(class, nonatomic, readonly) BOOL reactNativeIsRightToLeft;
+
+/// `navigation` (a shown stack, UIKit's More navigation) follows the scene's direction now: its view and bar get the
+/// direction their traits have, then none, so that UIKit takes the swipe's edge again even when they had none already
+/// (a stack that followed the scene through one change keeps the old edge otherwise).
++ (void)followSceneDirectionIn:(UINavigationController *)navigation;
+
+/// `navigation`, in a window now, didn't follow the scene's last change of direction from a window (it was off screen
+/// then, where its traits stayed the old ones): it follows when it shows.
++ (BOOL)navigationMissedSceneDirection:(UINavigationController *)navigation;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Core/ANNAppDirection.mm

@@ -0,0 +1,194 @@
+#import "ANNAppDirection.h"
+#import "ANNAssert.h"
+#import "ANNBottomTabsController.h"
+#import "ANNDefaultOptions.h"
+#import "ANNStackController.h"
+#import "ANNUtils.h"
+#import <React/RCTI18nUtil.h>
+#import <objc/runtime.h>
+
+// How deep the walk of the shown stacks goes at most.
+static const NSUInteger ANNDirectionWalkLimit = 64;
+
+// Main queue: the value applied last, nil before any; and the scene's part of it while the navigation window has no
+// scene yet (iOS 17+), apart from the value, so that "the same value again" never drops it.
+static NSString *ANNAppliedDirection;
+static NSString *ANNPendingSceneDirection;
+// How many times the scene's direction changed, and, on each navigation, the change it last followed in a window.
+static NSUInteger ANNSceneDirectionChanges;
+static const void *ANNFollowedDirectionKey = &ANNFollowedDirectionKey;
+
+static UISemanticContentAttribute ANNAttributeOfDirection(NSString *direction) {
+    if ([direction isEqualToString:@"rtl"]) {
+        return UISemanticContentAttributeForceRightToLeft;
+    }
+    if ([direction isEqualToString:@"ltr"]) {
+        return UISemanticContentAttributeForceLeftToRight;
+    }
+    return UISemanticContentAttributeUnspecified;
+}
+
+@implementation ANNAppDirection
+
++ (nullable NSString *)defaultOptionsDirection {
+    NSString *direction = [ANNDefaultOptions.current.layout.direction withDefault:nil];
+    return direction.length > 0 ? direction : nil;
+}
+
++ (void)applyDefaultOptionsDirection {
+    ANNAssertMainQueue();
+    NSString *direction = [self defaultOptionsDirection];
+    if (!direction) {
+        return;
+    }
+    if (![direction isEqualToString:ANNAppliedDirection]) {
+        ANNAppliedDirection = [direction copy];
+        [self applyToReactNative:direction];
+        if (@available(iOS 17.0, *)) {
+            ANNPendingSceneDirection = ANNAppliedDirection;
+        } else {
+            // Every view and bar made from now on (F5): a stack shown now keeps its direction until
+            // its next push, a new root builds in the new one.
+            [UIView appearance].semanticContentAttribute = ANNAttributeOfDirection(direction);
+        }
+    }
+    [self applyPendingSceneDirection];
+}
+
++ (void)windowSceneDidConnect {
+    ANNAssertMainQueue();
+    [self applyPendingSceneDirection];
+}
+
++ (UISemanticContentAttribute)pushDirection {
+    if ([self defaultOptionsDirection]) {
+        if (@available(iOS 17.0, *)) {
+            return UISemanticContentAttributeUnspecified;
+        }
+    }
+    return [self reactNativeIsRightToLeft] ? UISemanticContentAttributeForceRightToLeft
+                                           : UISemanticContentAttributeForceLeftToRight;
+}
+
++ (BOOL)reactNativeIsRightToLeft {
+    return [RCTI18nUtil sharedInstance].isRTL;
+}
+
+// UIKit takes the swipe's edge when a navigation's direction is set and changes: two real sets, the traits' own
+// direction and then none, re-read it whatever the navigation had before. Out of a window the traits may still be the
+// old ones: the navigation counts as following only from a window.
++ (void)followSceneDirectionIn:(UINavigationController *)navigation {
+    if (navigation.viewIfLoaded.window) {
+        objc_setAssociatedObject(navigation, ANNFollowedDirectionKey, @(ANNSceneDirectionChanges),
+                                 OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+    }
+    BOOL rightToLeft =
+        navigation.traitCollection.layoutDirection == UITraitEnvironmentLayoutDirectionRightToLeft;
+    UISemanticContentAttribute traits = rightToLeft ? UISemanticContentAttributeForceRightToLeft
+                                                    : UISemanticContentAttributeForceLeftToRight;
+    NSMutableArray<UIView *> *views = [NSMutableArray arrayWithObject:navigation.navigationBar];
+    UIView *view = navigation.viewIfLoaded;
+    if (view) {
+        [views addObject:view];
+    }
+    for (UIView *target in views) {
+        if (target.semanticContentAttribute != traits) {
+            target.semanticContentAttribute = traits;
+        }
+        target.semanticContentAttribute = UISemanticContentAttributeUnspecified;
+    }
+}
+
++ (BOOL)navigationMissedSceneDirection:(UINavigationController *)navigation {
+    if (ANNSceneDirectionChanges == 0 || !navigation.viewIfLoaded.window) {
+        return NO;
+    }
+    NSNumber *followed = objc_getAssociatedObject(navigation, ANNFollowedDirectionKey);
+    return followed.unsignedIntegerValue != ANNSceneDirectionChanges;
+}
+
+#pragma mark - The parts
+
+// React Native lays out in it the surfaces made after it and keeps it across launches.
++ (void)applyToReactNative:(NSString *)direction {
+    BOOL rightToLeft = [direction isEqualToString:@"rtl"];
+    RCTI18nUtil *i18n = [RCTI18nUtil sharedInstance];
+    [i18n allowRTL:rightToLeft || [direction isEqualToString:@"locale"]];
+    [i18n forceRTL:rightToLeft];
+}
+
++ (void)applyPendingSceneDirection {
+    NSString *direction = ANNPendingSceneDirection;
+    UIWindowScene *scene = ANNUtils.mainWindow.windowScene;
+    if (!direction || !scene) {
+        return;
+    }
+    ANNPendingSceneDirection = nil;
+    if (@available(iOS 17.0, *)) {
+        [self applyDirection:direction toScene:scene];
+    }
+}
+
+// In this order: the scene's trait (`locale` removes the override: the app's language decides), every window of the
+// scene with a root takes the new traits now (the keyboard's and an overlay's on its way have none and are skipped),
+// then the stacks follow the scene: UIKit takes the swipe's edge as a stack's direction is set, from the direction its
+// view has then.
++ (void)applyDirection:(NSString *)direction
+               toScene:(UIWindowScene *)scene API_AVAILABLE(ios(17.0)) {
+    ANNSceneDirectionChanges++;
+    id<UITraitOverrides> overrides = scene.traitOverrides;
+    if ([direction isEqualToString:@"rtl"]) {
+        overrides.layoutDirection = UITraitEnvironmentLayoutDirectionRightToLeft;
+    } else if ([direction isEqualToString:@"ltr"]) {
+        overrides.layoutDirection = UITraitEnvironmentLayoutDirectionLeftToRight;
+    } else if ([overrides containsTrait:UITraitLayoutDirection.class]) {
+        [overrides removeTrait:UITraitLayoutDirection.class];
+    }
+    NSMutableArray<UIWindow *> *windows = [NSMutableArray new];
+    for (UIWindow *window in scene.windows) {
+        if (window.rootViewController) {
+            [window updateTraitsIfNeeded];
+            [windows addObject:window];
+        }
+    }
+    for (UIWindow *window in windows) {
+        NSUInteger depth = 0;
+        for (UIViewController *controller = window.rootViewController;
+             controller && depth < ANNDirectionWalkLimit;
+             controller = controller.presentedViewController, depth++) {
+            [self dropForcedDirectionIn:controller depth:0];
+        }
+    }
+}
+
+// Every stack, shown or not (an unselected tab, under a full-screen modal, in a closed menu), and UIKit's More
+// navigation of tabs with more than five: each takes the scene's new direction now. One out of the window takes its
+// traits first, which it would otherwise get only once it is in a window again.
++ (void)dropForcedDirectionIn:(UIViewController *)controller depth:(NSUInteger)depth {
+    if (depth >= ANNDirectionWalkLimit) {
+        return;
+    }
+    if ([controller isKindOfClass:ANNStackController.class] && controller.isViewLoaded) {
+        if (@available(iOS 17.0, *)) {
+            [controller updateTraitsIfNeeded];
+        }
+        [(ANNStackController *)controller dropForcedDirection];
+    }
+    ANNBottomTabsController *tabs = [controller isKindOfClass:ANNBottomTabsController.class]
+                                        ? (ANNBottomTabsController *)controller
+                                        : nil;
+    if (tabs.layoutTabs.count > 5) {
+        UINavigationController *more = tabs.moreNavigationController;
+        if (more.isViewLoaded) {
+            if (@available(iOS 17.0, *)) {
+                [more updateTraitsIfNeeded];
+            }
+            [self followSceneDirectionIn:more];
+        }
+    }
+    for (UIViewController *child in controller.childViewControllers) {
+        [self dropForcedDirectionIn:child depth:depth + 1];
+    }
+}
+
+@end

package/ios/Core/ANNAppearanceDispatcher.h

@@ -0,0 +1,117 @@
+#import "ANNScreenAppearance.h"
+#import <UIKit/UIKit.h>
+
+@class ANNCommandAnswer;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The one place that sends `ANN.ComponentWillAppear`, `ANN.ComponentDidAppear` and `ANN.ComponentDidDisappear`, and
+/// the events of a transition and of a node that goes. Everything is synchronous, on the main queue: the only delay is
+/// the hold of an appearance until its content mounted, at most 0.5 s, and it never delays a transition.
+///
+/// Per record (`ANNScreenAppearance`): at most one `WillAppear` and one `DidAppear` per appearance, `DidAppear` only
+/// after `WillAppear`, `DidDisappear` only after a `WillAppear` JavaScript heard. A record of a JavaScript that went
+/// sends nothing: its emitter is silent.
+@interface ANNAppearanceDispatcher : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+#pragma mark - A record
+
+/// The appearance starts: `WillAppear`, now when the record is ready, else held. Nothing when it started already.
++ (void)willAppear:(ANNScreenAppearance *)appearance;
+
+/// The appearance ended: `WillAppear` first when it wasn't asked, then `DidAppear`, now when nothing is held and the
+/// record is ready, else held behind what is held. Nothing when it was asked already.
++ (void)didAppear:(ANNScreenAppearance *)appearance;
+
+/// The thing went or got covered: `DidDisappear` when JavaScript heard the `WillAppear`; when the `WillAppear` is still
+/// held, what is held is dropped and nothing goes (JavaScript never heard of the appearance). Nothing while hidden.
++ (void)didDisappear:(ANNScreenAppearance *)appearance;
+
+/// The record is ready (`markReady`, the mount of its content, the hold limit): what is held goes now, in order.
++ (void)appearanceBecameReady:(ANNScreenAppearance *)appearance;
+
+/// `block` runs right after the `DidAppear` of `appearance` is sent, in the same turn (also a held one, when it goes):
+/// at once when it was sent already or no appearance is pending (the record is hidden, or there is none), and when the
+/// appearance ends without its `DidAppear` (the content went before). Never dropped: a tab switch sends
+/// `ANN.BottomTabSelected` this way.
++ (void)afterDidAppearOf:(nullable ANNScreenAppearance *)appearance run:(dispatch_block_t)block;
+
+#pragma mark - Nodes
+
+/// Each screen `node` shows (`shownComponentViewControllers`) starts to appear.
++ (void)nodeWillAppear:(UIViewController *)node;
+
+/// Each screen `node` shows appeared (with `WillAppear` first where it wasn't asked).
++ (void)nodeDidAppear:(UIViewController *)node;
+
+/// Every screen of the node's subtree (`layoutChildren`, depth first) disappeared; those not shown ignore it.
++ (void)nodeDidDisappear:(UIViewController *)node;
+
+#pragma mark - Transitions
+
+/// A transition starts: `nodeWillAppear:` of each node that comes. The screens it began are remembered (weakly) until
+/// an end names a node that holds them.
++ (void)beginTransitionShowing:(NSArray<UIViewController *> *)shown;
+
+/// A transition ended, in this order: first a screen a transition began inside a node of `shown` that left the window
+/// and isn't one of that node's shown screens gets its `DidDisappear`; then `DidDisappear` of every screen of `hidden`,
+/// `DidAppear` of what `shown` shows, the navigation state now when it changed, `events` (the transition's own events,
+/// `ANN.ScreenPopped` and `ANN.ModalDismissed`, and what must follow them, like stopping the content that went), then
+/// `answer` resolves with `value` (its own state step finds nothing new, then the promise, then
+/// `ANN.CommandCompleted`). A user's action passes no answer. The callbacks of UIKit that come later find the phases
+/// set and send nothing.
++ (void)endTransitionHiding:(NSArray<UIViewController *> *)hidden
+                    showing:(NSArray<UIViewController *> *)shown
+                     events:(nullable dispatch_block_t)events
+                     answer:(nullable ANNCommandAnswer *)answer
+                      value:(nullable id)value;
+
+/// A switch of a container's shown child ended (a tab switch): the same close of the screens begun and gone first, then
+/// `DidDisappear` of every screen of `hidden`, `DidAppear` of what `shown` shows, then `events`. Unlike
+/// `endTransitionHiding:…` it reports no state now: the events that went ask for the coalesced one, which comes after
+/// what `events` sends.
++ (void)endSwitchHiding:(NSArray<UIViewController *> *)hidden
+                showing:(NSArray<UIViewController *> *)shown
+                 events:(nullable dispatch_block_t)events;
+
+#pragma mark - A command drives the appearance
+
+/// From now on a command reports the appearance of `nodes` and of their layout subtrees itself (`setRoot` replacing
+/// the window's root): UIKit's appearance callbacks of their screens send nothing, because UIKit calls them while the
+/// root is replaced, out of the command's order. The dispatcher's own calls are not affected. Balanced by
+/// `stopDrivingAppearanceOf:`; two commands may drive one node. Main queue.
++ (void)driveAppearanceOf:(NSArray<UIViewController *> *)nodes;
+
+/// The command that drove `nodes` ended: UIKit's callbacks report them again once no command drives them.
++ (void)stopDrivingAppearanceOf:(NSArray<UIViewController *> *)nodes;
+
+/// Whether a command drives the appearance of `screen`: it, or one of its layout parents, is driven.
++ (BOOL)isAppearanceDriven:(UIViewController *)screen;
+
+#pragma mark - The events of a transition and of a node that goes
+
+/// The node left its stack (EVT-ScreenPopped): `ANN.ScreenPopped` for each screen of its `screensLeavingWithNode` (a
+/// pair: both), else for the node alone, then the node's own `screenPopped` cleanup. Call it inside `events` of the
+/// transition, before the content of the node stops.
++ (void)screenPopped:(UIViewController *)node;
+
+/// The visible screen of `node`: the last screen down its current children that are nodes of the layout; nil when that
+/// chain has no screen. The one walk that names the screen of `ANN.ModalDismissed`, `ANN.ModalAttemptedToDismiss` and
+/// `ANN.SheetDetentChanged`.
++ (nullable UIViewController *)visibleScreenOf:(UIViewController *)node;
+
+/// The modal went (EVT-ModalDismissed): `ANN.ModalDismissed` with the id and the name of its visible screen
+/// (`visibleScreenOf:`) and the number of modals that went with it. A chain with no screen sends the modal's own id
+/// with an empty name.
++ (void)modalDismissed:(UIViewController *)modal count:(NSUInteger)count;
+
+/// The native screen left the layout (EVT-NativeScreenReleased): `ANN.NativeScreenReleased`, once per node however it
+/// went; nothing for a node of a JavaScript that went.
++ (void)nativeScreenReleased:(UIViewController *)screen;
+
+@end
+
+NS_ASSUME_NONNULL_END