@apexnative/navigation 1.0.0-alpha.0 → 1.0.0-alpha.10

package/ios/Core/ANNDeepLinkQueue.mm

@@ -1,12 +1,41 @@
 #import "ANNDeepLinkQueue.h"
 #import "ANNAssert.h"
+#import "ANNEventEmitter.h"
+#import "ApexNavigation+Internal.h"
 #import <React/RCTLinkingManager.h>
 #import <React/RCTRootView.h>
 #import <UIKit/UIKit.h>
 
+// A link on its way to `Linking`, with the scene's own context or user activity it came in when it came from a scene.
+@interface ANNDeepLink : NSObject
+@property(nonatomic, readonly) NSURL *url;
+@property(nonatomic, readonly, nullable) UIOpenURLContext *context;
+@property(nonatomic, readonly, nullable) NSUserActivity *activity;
+@property(nonatomic, readonly, weak, nullable) UIScene *scene;
+@end
+
+@implementation ANNDeepLink
+
+- (instancetype)initWithURL:(NSURL *)url
+                    context:(UIOpenURLContext *)context
+                   activity:(NSUserActivity *)activity
+                      scene:(UIScene *)scene {
+    if (self = [super init]) {
+        _url = url;
+        _context = context;
+        _activity = activity;
+        _scene = scene;
+    }
+    return self;
+}
+
+@end
+
 // Main queue only.
 static BOOL ANNDeepLinkQueueStarted = NO;
-static NSMutableArray<NSURL *> *ANNPendingDeepLinkURLs;
+static NSMutableArray<ANNDeepLink *> *ANNPendingDeepLinks;
+// The scene's link the scene delegate is handing to the app delegate: the app delegate dispatches its URL.
+static ANNDeepLink *ANNForwardedSceneLink;
 // React content appeared: `RCTLinkingManager` exists and JS listens to `url` events.
 static BOOL ANNReactContentAppeared = NO;
 // Every URL that launched the app was dispatched.
@@ -20,7 +49,7 @@ static ANNLaunchLinkCompletion ANNWaitingLaunchLinkCompletion;
 
 + (void)initialize {
     if (self == ANNDeepLinkQueue.class) {
-        ANNPendingDeepLinkURLs = [NSMutableArray new];
+        ANNPendingDeepLinks = [NSMutableArray new];
     }
 }
 
@@ -42,15 +71,51 @@ static ANNLaunchLinkCompletion ANNWaitingLaunchLinkCompletion;
                                            selector:@selector(applicationDidBecomeActive:)
                                                name:UIApplicationDidBecomeActiveNotification
                                              object:nil];
+    // Started once the app is active (an app that starts React Native later, on demand), the queue missed the scene's
+    // connection and the notification: the links that launched the app went elsewhere, and none waits for them.
+    if (UIApplication.sharedApplication.applicationState == UIApplicationStateActive) {
+        [self launchLinksKnown];
+    }
 }
 
 + (void)dispatchURL:(NSURL *)url {
-    ANNAssertMainQueue();
-    if (ANNReactContentAppeared && ANNWaitingLaunchLinkCompletion == nil) {
-        [self openURL:url];
+    // The URL of the scene's link keeps its context; one the app delegate changed is a URL of its own.
+    ANNDeepLink *link = [ANNForwardedSceneLink.url isEqual:url]
+                            ? ANNForwardedSceneLink
+                            : [[ANNDeepLink alloc] initWithURL:url context:nil activity:nil scene:nil];
+    [self dispatchLink:link];
+}
+
++ (void)forwardURLContext:(UIOpenURLContext *)context
+                  ofScene:(UIScene *)scene
+                  through:(NS_NOESCAPE dispatch_block_t)forward {
+    [self forwardLink:[[ANNDeepLink alloc] initWithURL:context.URL context:context activity:nil scene:scene]
+              through:forward];
+}
+
++ (void)forwardUserActivity:(NSUserActivity *)activity
+                    ofScene:(UIScene *)scene
+                    through:(NS_NOESCAPE dispatch_block_t)forward {
+    if (activity.webpageURL == nil) {
+        forward();
         return;
     }
-    [ANNPendingDeepLinkURLs addObject:url];
+    [self forwardLink:[[ANNDeepLink alloc] initWithURL:activity.webpageURL context:nil activity:activity scene:scene]
+              through:forward];
+}
+
++ (void)dispatchURLContext:(UIOpenURLContext *)context ofScene:(UIScene *)scene {
+    [self dispatchLink:[[ANNDeepLink alloc] initWithURL:context.URL context:context activity:nil scene:scene]];
+}
+
++ (void)dispatchUserActivity:(NSUserActivity *)activity ofScene:(UIScene *)scene {
+    if (activity.webpageURL == nil) {
+        return;
+    }
+    [self dispatchLink:[[ANNDeepLink alloc] initWithURL:activity.webpageURL
+                                                context:nil
+                                               activity:activity
+                                                  scene:scene]];
 }
 
 + (void)windowSceneDidConnect {
@@ -98,10 +163,10 @@ static ANNLaunchLinkCompletion ANNWaitingLaunchLinkCompletion;
     if (ANNWaitingLaunchLinkCompletion != nil) {
         return;
     }
-    NSArray<NSURL *> *urls = [ANNPendingDeepLinkURLs copy];
-    [ANNPendingDeepLinkURLs removeAllObjects];
-    for (NSURL *url in urls) {
-        [self openURL:url];
+    NSArray<ANNDeepLink *> *links = [ANNPendingDeepLinks copy];
+    [ANNPendingDeepLinks removeAllObjects];
+    for (ANNDeepLink *link in links) {
+        [self openLink:link];
     }
 }
 
@@ -124,13 +189,55 @@ static ANNLaunchLinkCompletion ANNWaitingLaunchLinkCompletion;
 // One link opens the app. The links queued before it are dropped: opened after it, they would take the app elsewhere.
 + (void)giveLaunchLink:(ANNLaunchLinkCompletion)completion {
     ANNLaunchLinkTaken = YES;
-    NSURL *url = ANNPendingDeepLinkURLs.lastObject;
-    [ANNPendingDeepLinkURLs removeAllObjects];
+    NSURL *url = ANNPendingDeepLinks.lastObject.url;
+    [ANNPendingDeepLinks removeAllObjects];
     completion(url);
 }
 
-+ (void)openURL:(NSURL *)url {
-    [RCTLinkingManager application:UIApplication.sharedApplication openURL:url options:@{}];
++ (void)dispatchLink:(ANNDeepLink *)link {
+    ANNAssertMainQueue();
+    if (ANNReactContentAppeared && ANNWaitingLaunchLinkCompletion == nil) {
+        [self openLink:link];
+        return;
+    }
+    [ANNPendingDeepLinks addObject:link];
+}
+
++ (void)forwardLink:(ANNDeepLink *)link through:(NS_NOESCAPE dispatch_block_t)forward {
+    ANNAssertMainQueue();
+    ANNDeepLink *outer = ANNForwardedSceneLink;
+    ANNForwardedSceneLink = link;
+    forward();
+    ANNForwardedSceneLink = outer;
+}
+
+// React Native 0.88 and newer take a scene's links through its scene methods: in an app whose Info.plist names a scene
+// delegate, its app delegate methods take none. The earlier versions have only the app delegate methods.
++ (void)openLink:(ANNDeepLink *)link {
+    UIScene *scene = link.scene;
+    if (scene != nil && link.context != nil) {
+        SEL openContexts = NSSelectorFromString(@"scene:openURLContexts:");
+        if ([RCTLinkingManager respondsToSelector:openContexts]) {
+            IMP implementation = [RCTLinkingManager methodForSelector:openContexts];
+            ((void (*)(id, SEL, UIScene *, NSSet<UIOpenURLContext *> *))implementation)(
+                RCTLinkingManager.class, openContexts, scene, [NSSet setWithObject:link.context]);
+            return;
+        }
+    }
+    if (scene != nil && link.activity != nil) {
+        SEL continueActivity = NSSelectorFromString(@"scene:continueUserActivity:");
+        if ([RCTLinkingManager respondsToSelector:continueActivity]) {
+            IMP implementation = [RCTLinkingManager methodForSelector:continueActivity];
+            ((void (*)(id, SEL, UIScene *, NSUserActivity *))implementation)(
+                RCTLinkingManager.class, continueActivity, scene, link.activity);
+            return;
+        }
+    }
+    // A link of the app's own (`dispatchDeepLinkURL`) has no scene: on React Native 0.88 and newer, with a scene
+    // delegate in Info.plist, `Linking` doesn't take it from here. JavaScript hands it to `Linking` itself.
+    if (![RCTLinkingManager application:UIApplication.sharedApplication openURL:link.url options:@{}]) {
+        [ApexNavigation.eventEmitter sendDeepLinkDispatched:link.url];
+    }
 }
 
 @end

package/ios/Core/ANNErrorHandler.h

@@ -3,13 +3,18 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /// How a failed command tells JavaScript: a rejection carries only a sentence, never a code of its own, and a command
-/// without a promise writes the sentence to the log. The sentences are those of `ANNErrorTexts`.
+/// without a promise writes the sentence to the log. The sentences are those of `ANNErrorTexts`. The one place that
+/// calls a command's promise blocks: a block that is nil (a caller that passed none) is never called.
 @interface ANNErrorHandler : NSObject
 
-/// Rejects a command's promise with the sentence alone: React Native puts its own default code on it.
-+ (void)reject:(RCTPromiseRejectBlock)reject text:(NSString *)text;
+/// Rejects a command's promise with the sentence alone: React Native puts its own default code on it. Without a
+/// reject block the sentence goes to the log as `logFailureOf:text:` writes it.
++ (void)reject:(nullable RCTPromiseRejectBlock)reject of:(NSString *)method text:(NSString *)text;
 
-/// The log line of a command without a promise: `[ApexNavigation] <method>: <text>`.
+/// Resolves a command's promise with `value`. Without a resolve block one line goes to the log instead.
++ (void)resolve:(nullable RCTPromiseResolveBlock)resolve of:(NSString *)method value:(nullable id)value;
+
+/// The log line of a command without a promise: `[ApexNavigation] <method>: <text>`, a warning (`RCTLogWarn`).
 + (void)logFailureOf:(NSString *)method text:(NSString *)text;
 
 @end

package/ios/Core/ANNErrorHandler.mm

@@ -1,14 +1,32 @@
 #import "ANNErrorHandler.h"
+#import "ANNErrorTexts.h"
 #import <React/RCTLog.h>
 
 @implementation ANNErrorHandler
 
-+ (void)reject:(RCTPromiseRejectBlock)reject text:(NSString *)text {
+// Calling a nil block ends the app (`EXC_BAD_ACCESS` at 0x10, its invoke field): JavaScript always passes both blocks,
+// so a nil one comes from a caller in native code, and the answer goes to the log.
++ (void)reject:(RCTPromiseRejectBlock)reject of:(NSString *)method text:(NSString *)text {
+    if (!reject) {
+        [self logFailureOf:method text:text];
+        return;
+    }
     reject(nil, text, nil);
 }
 
++ (void)resolve:(RCTPromiseResolveBlock)resolve of:(NSString *)method value:(id)value {
+    if (!resolve) {
+        [self logFailureOf:method
+                      text:[ANNErrorTexts couldNot:@"resolve its promise" reason:@"the command came without one"]];
+        return;
+    }
+    resolve(value);
+}
+
+// A warning, not an error: a failed command without a promise (a `mergeOptions` the screen can't take) is the app's
+// to notice, not a red box over it; Android logs it the same way, without a dialog.
 + (void)logFailureOf:(NSString *)method text:(NSString *)text {
-    RCTLogError(@"[ApexNavigation] %@: %@", method, text);
+    RCTLogWarn(@"[ApexNavigation] %@: %@", method, text);
 }
 
 @end

package/ios/Core/ANNEventContract.h

@@ -0,0 +1,246 @@
+// Made by scripts/contract.mjs from the event types of src/interfaces/: change them and run the script again.
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The names of the events `ANN.<Name>` (`event`) and the keys of their payloads, as the types of `src/interfaces/`
+/// give them; what each field means is its JSDoc there. The object types a field holds have keys of their own. The
+/// senders take every name and key from here: `ANNEventContract.CommandCompleted.commandId`.
+FOUNDATION_EXPORT const struct ANNEventContractTable {
+    /// `ANN.AppLaunched`.
+    struct {
+        __unsafe_unretained NSString *event;
+    } AppLaunched;
+    /// `ANN.ArrangementChanged`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *placement;
+        __unsafe_unretained NSString *layout;
+        __unsafe_unretained NSString *front;
+        __unsafe_unretained NSString *hidden;
+    } ArrangementChanged;
+    /// `ANN.BottomAccessoryPlacementChanged` (iOS).
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *placement;
+    } BottomAccessoryPlacementChanged;
+    /// `ANN.BottomTabLongPressed`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *selectedTabIndex;
+        __unsafe_unretained NSString *bottomTabsId;
+    } BottomTabLongPressed;
+    /// `ANN.BottomTabPressed`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *tabIndex;
+        __unsafe_unretained NSString *bottomTabsId;
+        /// Optional.
+        __unsafe_unretained NSString *screenId;
+        __unsafe_unretained NSString *wasSelected;
+    } BottomTabPressed;
+    /// `ANN.BottomTabSelected`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *selectedTabIndex;
+        __unsafe_unretained NSString *unselectedTabIndex;
+        __unsafe_unretained NSString *bottomTabsId;
+    } BottomTabSelected;
+    /// `ANN.CommandCompleted`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *commandName;
+        __unsafe_unretained NSString *commandId;
+        __unsafe_unretained NSString *completionTime;
+    } CommandCompleted;
+    /// `ANN.ComponentDidAppear`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *componentName;
+        __unsafe_unretained NSString *componentType;
+    } ComponentDidAppear;
+    /// `ANN.ComponentDidDisappear`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *componentName;
+        __unsafe_unretained NSString *componentType;
+    } ComponentDidDisappear;
+    /// `ANN.ComponentWillAppear`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *componentName;
+        __unsafe_unretained NSString *componentType;
+    } ComponentWillAppear;
+    /// `ANN.DeepLinkDispatched` (iOS).
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *url;
+    } DeepLinkDispatched;
+    /// `ANN.HingeChanged`.
+    struct {
+        __unsafe_unretained NSString *event;
+        /// Optional.
+        __unsafe_unretained NSString *state;
+        /// Optional.
+        __unsafe_unretained NSString *angle;
+    } HingeChanged;
+    /// `ANN.KeyCommandPressed` (iOS).
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *keyCommandId;
+    } KeyCommandPressed;
+    /// `ANN.ModalAttemptedToDismiss`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+    } ModalAttemptedToDismiss;
+    /// `ANN.ModalDismissed`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *componentName;
+        __unsafe_unretained NSString *modalsDismissed;
+    } ModalDismissed;
+    /// `ANN.NativeScreenCall`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *callId;
+        __unsafe_unretained NSString *kind;
+        __unsafe_unretained NSString *name;
+        __unsafe_unretained NSString *args;
+    } NativeScreenCall;
+    /// `ANN.NativeScreenReleased`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+    } NativeScreenReleased;
+    /// `ANN.NavigationButtonPressed`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *buttonId;
+        /// Optional, iOS only.
+        __unsafe_unretained NSString *selected;
+    } NavigationButtonPressed;
+    /// `ANN.NavigationStateChanged`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *screen;
+        __unsafe_unretained NSString *tab;
+    } NavigationStateChanged;
+    /// The object of `ANN.NavigationStateChanged.screen`.
+    struct {
+        __unsafe_unretained NSString *id;
+        __unsafe_unretained NSString *name;
+    } NavigationStateChangedScreen;
+    /// `ANN.PreviewCompleted` (iOS).
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *previewComponentId;
+    } PreviewCompleted;
+    /// `ANN.ScreenInsetsChanged`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *top;
+        __unsafe_unretained NSString *right;
+        __unsafe_unretained NSString *bottom;
+        __unsafe_unretained NSString *left;
+    } ScreenInsetsChanged;
+    /// `ANN.ScreenPopped`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+    } ScreenPopped;
+    /// The object of `ANN.ScreenRegionsChanged.division`.
+    struct {
+        __unsafe_unretained NSString *x;
+        __unsafe_unretained NSString *y;
+        __unsafe_unretained NSString *width;
+        __unsafe_unretained NSString *height;
+    } ScreenRegionRect;
+    /// `ANN.ScreenRegionsChanged`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *division;
+        __unsafe_unretained NSString *occlusion;
+    } ScreenRegionsChanged;
+    /// `ANN.SearchBarCancelPressed`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+    } SearchBarCancelPressed;
+    /// `ANN.SearchBarSubmitted`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *text;
+        /// Optional.
+        __unsafe_unretained NSString *scope;
+        /// Optional, iOS only.
+        __unsafe_unretained NSString *tokens;
+    } SearchBarSubmitted;
+    /// `ANN.SearchBarUpdated`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *text;
+        __unsafe_unretained NSString *isFocused;
+        /// Optional.
+        __unsafe_unretained NSString *scope;
+        /// Optional, iOS only.
+        __unsafe_unretained NSString *tokens;
+    } SearchBarUpdated;
+    /// `ANN.SearchSuggestionPicked`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *suggestionId;
+    } SearchSuggestionPicked;
+    /// `ANN.SheetDetentChanged`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *detent;
+    } SheetDetentChanged;
+    /// `ANN.SlotDestroyed`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+    } SlotDestroyed;
+    /// `ANN.SplitViewColumnsStacked`.
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *stacked;
+    } SplitViewColumnsStacked;
+    /// `ANN.SplitViewDisplayModeChanged` (iOS).
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *displayMode;
+        /// Optional.
+        __unsafe_unretained NSString *inspectorVisible;
+    } SplitViewDisplayModeChanged;
+    /// `ANN.TitleRenamed` (iOS).
+    struct {
+        __unsafe_unretained NSString *event;
+        __unsafe_unretained NSString *componentId;
+        __unsafe_unretained NSString *text;
+    } TitleRenamed;
+} ANNEventContract;
+
+/// The name of every event, `ANN.<Name>`.
+FOUNDATION_EXPORT NSArray<NSString *> *ANNEventContractNames(void);
+
+NS_ASSUME_NONNULL_END