@apexnative/navigation 1.0.0-alpha.2 → 1.0.0-alpha.4

package/ios/Core/ANNErrorHandler.h

@@ -14,7 +14,7 @@ NS_ASSUME_NONNULL_BEGIN
 /// 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>`.
+/// 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

@@ -23,8 +23,10 @@
     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/ANNEventEmitter.h

@@ -28,7 +28,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - The contract
 
-/// `ANN.AppLaunched`, without a payload. While JavaScript has no listener of it, it is kept and goes once JavaScript
+/// `ANN.AppLaunched`, with an empty payload. While JavaScript has no listener of it, it is kept and goes once JavaScript
 /// adds the first one. Main queue.
 - (void)sendAppLaunched;
 

package/ios/Core/ANNEventEmitter.mm

@@ -60,7 +60,7 @@ static NSUInteger ANNAppLaunchedBundle;
         return;
     }
     ANNAppLaunchedPending = NO;
-    [eventEmitter sendIfListened:ANNEventContract.AppLaunched.event body:nil];
+    [eventEmitter sendIfListened:ANNEventContract.AppLaunched.event body:@{}];
 }
 
 + (void)eventEmitterListensToAppLaunched:(ANNTurboEventEmitter *)eventEmitter {
@@ -69,7 +69,7 @@ static NSUInteger ANNAppLaunchedBundle;
         return;
     }
     ANNAppLaunchedPending = NO;
-    [eventEmitter sendIfListened:ANNEventContract.AppLaunched.event body:nil];
+    [eventEmitter sendIfListened:ANNEventContract.AppLaunched.event body:@{}];
 }
 
 // Only an `AppLaunched` of the module's own JavaScript or an older one: the module is made while its bundle runs,

package/ios/Core/ANNJavaScriptCalls.h

@@ -0,0 +1,34 @@
+#import <Foundation/Foundation.h>
+
+@class RCTCallInvoker;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The way of the calls JavaScript makes to `ANNTurboModule`, for a step that must come after them. A call without an
+/// answer (`mergeOptions`) leaves the JavaScript thread as it is made, goes to the module's queue (React Native's
+/// `ModuleNativeMethodCallInvoker`, a `dispatch_async` to it) and from there to the main queue (`ANNCommandRunner`):
+/// a step that takes the same three hops after them comes after them on the main queue, as each of the three runs its
+/// work in order. The module tells its call invoker and its queue when React Native made it, and that it went when
+/// React Native invalidates it (a reload). Any thread, except `afterCallsMadeSoFar:`.
+@interface ANNJavaScriptCalls : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The module of the JavaScript that runs now, its call invoker (the JavaScript thread) and its queue.
++ (void)setCallInvoker:(nullable RCTCallInvoker *)callInvoker
+           methodQueue:(nullable dispatch_queue_t)methodQueue
+              ofModule:(id)module;
+
+/// The module went: with no newer module told since, no JavaScript runs to wait for.
++ (void)moduleWent:(id)module;
+
+/// `block` runs on the main queue once every call JavaScript made to the module before the next task of its thread is
+/// applied on the main queue: a task on the JavaScript thread, from there one on the module's queue, from there one on
+/// the main queue. With no JavaScript to ask (none yet, a reload), at once. Main queue. A JavaScript thread that never
+/// runs the task again (its runtime went) never runs `block`: a caller that can't wait for long has a limit of its own.
++ (void)afterCallsMadeSoFar:(dispatch_block_t)block;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Core/ANNJavaScriptCalls.mm

@@ -0,0 +1,61 @@
+#import "ANNJavaScriptCalls.h"
+#import "ANNAssert.h"
+#import <React/RCTCallInvoker.h>
+#import <React/RCTUtils.h>
+#import <ReactCommon/CallInvoker.h>
+
+// The module told last, weakly: a module that went takes its invoker and its queue with it.
+static __weak id ANNCallsModule;
+static RCTCallInvoker *ANNCallsInvoker;
+static dispatch_queue_t ANNCallsQueue;
+
+@implementation ANNJavaScriptCalls
+
++ (void)setCallInvoker:(RCTCallInvoker *)callInvoker
+           methodQueue:(dispatch_queue_t)methodQueue
+              ofModule:(id)module {
+    @synchronized(self) {
+        ANNCallsModule = module;
+        ANNCallsInvoker = callInvoker;
+        ANNCallsQueue = methodQueue;
+    }
+}
+
++ (void)moduleWent:(id)module {
+    @synchronized(self) {
+        if (ANNCallsModule != module) {
+            return;
+        }
+        ANNCallsModule = nil;
+        ANNCallsInvoker = nil;
+        ANNCallsQueue = nil;
+    }
+}
+
++ (void)afterCallsMadeSoFar:(dispatch_block_t)block {
+    ANNAssertMainQueue();
+    RCTCallInvoker *callInvoker = nil;
+    dispatch_queue_t queue = nil;
+    @synchronized(self) {
+        if (ANNCallsModule) {
+            callInvoker = ANNCallsInvoker;
+            queue = ANNCallsQueue;
+        }
+    }
+    std::shared_ptr<facebook::react::CallInvoker> invoker =
+        callInvoker ? callInvoker.callInvoker : nullptr;
+    if (!invoker || !queue) {
+        block();
+        return;
+    }
+    dispatch_block_t done = [block copy];
+    // The JavaScript thread runs the task after the one it runs now, which made the calls of this moment (a commit of
+    // React and its layout effects); the module's queue then has those calls before this hop, and the main queue too.
+    invoker->invokeAsync([queue, done](facebook::jsi::Runtime &) {
+        dispatch_async(queue, ^{
+          RCTExecuteOnMainQueue(done);
+        });
+    });
+}
+
+@end

package/ios/Core/ANNNavigationState.h

@@ -24,11 +24,15 @@ NS_ASSUME_NONNULL_BEGIN
 + (void)releaseUpdates;
 
 /// The state now, sent when it changed: at the end of a transition, at once after a tab chosen from code. A walk that
-/// throws logs one line and sends nothing, so its caller always goes on.
+/// throws logs one line, `[ApexNavigation] <commandName>: could not report the navigation state: <reason>` (as on
+/// Android; `transition` without a command), and sends nothing, so its caller always goes on.
++ (void)updateNowFor:(nullable NSString *)commandName;
+
+/// `updateNowFor:` without a command.
 + (void)updateNow;
 
-/// A command is about to answer: when what shows changed, the new state goes now, before the promise.
-+ (void)reportBeforeAnswer;
+/// The command `commandName` is about to answer: when what shows changed, the new state goes now, before the promise.
++ (void)reportBeforeAnswerOf:(NSString *)commandName;
 
 /// Forgets the last state sent: the next one goes even if it is the same (a new bundle, `AppLaunched`).
 + (void)reset;

package/ios/Core/ANNNavigationState.mm

@@ -2,12 +2,12 @@
 #import "ANNAssert.h"
 #import "ANNBottomTabsController.h"
 #import "ANNComponentViewController.h"
+#import "ANNErrorHandler.h"
 #import "ANNErrorTexts.h"
 #import "ANNModalCoordinator.h"
 #import "ANNSlotContainers.h"
 #import "ApexNavigation+Internal.h"
 #import "UIViewController+LayoutProtocol.h"
-#import <React/RCTLog.h>
 
 // Main queue.
 static BOOL ANNUpdateScheduled;
@@ -58,6 +58,10 @@ static BOOL ANNSameValue(id a, id b) {
 }
 
 + (void)updateNow {
+    [self updateNowFor:nil];
+}
+
++ (void)updateNowFor:(NSString *)commandName {
     ANNAssertMainQueue();
     NSString *screenId = nil;
     NSString *name = nil;
@@ -74,8 +78,9 @@ static BOOL ANNSameValue(id a, id b) {
         }
     } @catch (NSException *exception) {
         NSString *reason = exception.reason.length > 0 ? exception.reason : exception.name;
-        RCTLogWarn(@"[ApexNavigation] %@",
-                   [ANNErrorTexts couldNot:@"report the navigation state" reason:reason]);
+        [ANNErrorHandler logFailureOf:commandName ?: @"transition"
+                                 text:[ANNErrorTexts couldNot:@"report the navigation state"
+                                                        reason:reason]];
         return;
     }
     if (ANNHasLastState && ANNSameValue(screenId, ANNLastScreenId) &&
@@ -89,8 +94,8 @@ static BOOL ANNSameValue(id a, id b) {
     [ApexNavigation.eventEmitter sendNavigationStateChanged:screenId name:name tab:tab];
 }
 
-+ (void)reportBeforeAnswer {
-    [self updateNow];
++ (void)reportBeforeAnswerOf:(NSString *)commandName {
+    [self updateNowFor:commandName];
 }
 
 + (void)reset {

package/ios/Core/ANNNodeHelper.h

@@ -3,6 +3,7 @@
 #import "ANNLayoutInfo.h"
 #import "ANNNavigationOptions.h"
 #import "ANNNodePresenter.h"
+#import "ANNUserChoice.h"
 #import <UIKit/UIKit.h>
 
 NS_ASSUME_NONNULL_BEGIN
@@ -24,9 +25,11 @@ FOUNDATION_EXPORT NSString *const ANNContainerReadyHandlerKey;
 @property(nonatomic, weak, readonly, nullable) UIViewController *node;
 
 @property(nonatomic, strong, nullable) ANNLayoutInfo *layoutInfo;
-/// The node's own options: its layout options with every `mergeOptions` into it and the choices of the user the modules
-/// keep. The setter stores them without the one-shot options and makes every resolved options miss its cache; it is the
-/// only way to change them. Never change them in place: `mergeOwnOptions:` or `changeOwnOptions:`.
+/// The node's own options: its layout options with every `mergeOptions` into it and what the core keeps of a merge (the
+/// title component a merged text drops, side colors). The user's choices are not here but in the user layer
+/// (`setUserChoice:forKey:`). The setter stores them without the one-shot options and makes every resolved options miss
+/// its cache; it is the only way to change them. Never change them in place: `mergeOwnOptions:` or
+/// `changeOwnOptions:`.
 @property(nonatomic, strong, nullable) ANNNavigationOptions *options;
 /// The default options of the app (`ANNDefaultOptions.current`); setting it does nothing, the defaults are the app's.
 @property(nonatomic, strong, nullable) ANNNavigationOptions *defaultOptions;
@@ -57,21 +60,38 @@ FOUNDATION_EXPORT NSString *const ANNContainerReadyHandlerKey;
 /// the layout, else the fallback (when there is none, the parent view controller).
 - (nullable UIViewController *)layoutParent;
 
-/// `options` merged with `options` given and stored through the setter.
+/// The app's `mergeOptions` into the node: `options` merged with `options` given and stored through the setter. A
+/// choice of the user layer that the merge changes leaves the layer, by Android's rules
+/// (`ANNUserChoice choiceAfterMerge:own:before:after:`): a field given a value other than the app had there (the own
+/// options', else the node's resolution before the merge), or the button, item or scope of the choice gone from the
+/// node's resolution after it; the same value sent again keeps it.
 - (void)mergeOwnOptions:(ANNNavigationOptions *)options;
 
-/// A change of the own options by the core or a module: `change` gets a copy of them, and the copy is stored through
-/// the setter. A presenter or module that keeps a choice of the user in the node's options (a scope, tokens, a
-/// checked menu item, a toggled button) writes it this way, never into the options in place.
+/// A change of the own options by the core: `change` gets a copy of them, and the copy is stored through the setter.
+/// For what the core keeps of the app's merges (the title component a merged text drops, side colors), never for a
+/// choice of the user, which goes into the user layer.
 - (void)changeOwnOptions:(void (^)(ANNNavigationOptions *options))change;
 
-/// The common resolve: a copy of the node's own options with the resolved options of its current child over them, down
-/// the visible chain. A new object each call: a container's override may change it in place.
+/// The user layer: the choices the user made in native UI (a toggled button, the check of a single-selection menu, the
+/// search scope, the tokens and suggestions UIKit removed, a renamed title), one per key, apart from the own options.
+/// The resolution writes them over the own options, by identity (`ANNUserChoice applyTo:`): defaults < parents < own <
+/// user. Setting one (nil removes it) makes every resolved options miss its cache, as a change of own options does.
+/// `setDefaultOptions` never touches the layer; it goes with the node.
+- (void)setUserChoice:(nullable ANNUserChoice *)choice forKey:(NSString *)key;
+
+/// The choice under `key`, or nil.
+- (nullable ANNUserChoice *)userChoiceForKey:(NSString *)key;
+
+/// The common resolve: a copy of the node's own options with its user layer written over them, then the resolved
+/// options of its current child over that, down the visible chain. A new object each call: a container's override may
+/// change it in place.
 - (ANNNavigationOptions *)resolveOptions;
 
-/// What the node shows with: the default options, then the own options of its parents from the farthest to the nearest,
-/// then the node's `resolveOptions`. Cached until any options change (`ANNOptionsCache`), the node has another parent,
-/// or a node of its visible chain has another current child. Read-only: copy it before changing anything.
+/// What the node shows with: the default options, then the own options of its parents (each with its user layer) from
+/// the farthest to the nearest, then the node's `resolveOptions`; a node without a current child (a screen) writes its
+/// user layer once more at the end, so a choice also reaches a list the screen takes from its stack or the defaults.
+/// Cached until any options or user layer change (`ANNOptionsCache`), the node has another parent, or a node of its
+/// visible chain has another current child. Read-only: copy it before changing anything.
 - (ANNNavigationOptions *)resolveOptionsWithDefault;
 
 /// `resolveOptionsWithDefault` built now, without the cache: for a reader whose node resolves through more than its

package/ios/Core/ANNNodeHelper.mm

@@ -29,8 +29,14 @@ static NSPointerArray *ANNWeakNodes(NSArray<UIViewController *> *nodes) {
 
 NSString *const ANNContainerReadyHandlerKey = @"ApexNavigation.container";
 
+// Set while a node works out the app's resolution (`appResolution`): no user layer is written. Main queue.
+static BOOL ANNUserLayersLeftOut = NO;
+
 @implementation ANNNodeHelper {
     ANNNavigationOptions *_options;
+    // The user layer: the choices by key, and their keys in the order they were set, the order they are written in.
+    NSMutableDictionary<NSString *, ANNUserChoice *> *_userChoices;
+    NSMutableArray<NSString *> *_userChoiceKeys;
     // The ready handlers by key, and their keys in the order they were first set.
     NSMutableDictionary<NSString *, dispatch_block_t> *_readyHandlers;
     NSMutableArray<NSString *> *_readyKeys;
@@ -108,10 +114,27 @@ NSString *const ANNContainerReadyHandlerKey = @"ApexNavigation.container";
 - (void)setDefaultOptions:(ANNNavigationOptions *)defaultOptions {
 }
 
+// With a user layer, the choices meet the merge as on Android: they see the app's resolution before it and after it
+// (the merge in place for that, uncached), and those the merge changes leave; the setter then moves the cache once for
+// both, also when a choice's rule throws: the new own options never stay with a cache of the old ones.
 - (void)mergeOwnOptions:(ANNNavigationOptions *)options {
-    ANNNavigationOptions *merged = _options ? [_options copy] : [ANNNavigationOptions new];
+    ANNAssertMainQueue();
+    ANNNavigationOptions *own = _options ?: [ANNNavigationOptions new];
+    ANNNavigationOptions *merged = [own copy];
     [merged mergeOptions:options];
-    self.options = merged;
+    if (_userChoiceKeys.count == 0) {
+        self.options = merged;
+        return;
+    }
+    ANNNavigationOptions *before = [self appResolution];
+    ANNNavigationOptions *stored = [merged withoutOneShotOptions];
+    _options = stored;
+    @try {
+        ANNNavigationOptions *after = [self appResolution];
+        [self userChoicesMeetMerge:options own:own before:before after:after];
+    } @finally {
+        self.options = stored;
+    }
 }
 
 - (void)changeOwnOptions:(void (^)(ANNNavigationOptions *options))change {
@@ -120,10 +143,78 @@ NSString *const ANNContainerReadyHandlerKey = @"ApexNavigation.container";
     self.options = changed;
 }
 
+#pragma mark - The user layer
+
+- (void)setUserChoice:(ANNUserChoice *)choice forKey:(NSString *)key {
+    ANNAssertMainQueue();
+    if (!choice && !_userChoices[key]) {
+        return;
+    }
+    if (!_userChoices) {
+        _userChoices = [NSMutableDictionary new];
+        _userChoiceKeys = [NSMutableArray new];
+    }
+    // A choice set again goes last: it is the newest.
+    [_userChoiceKeys removeObject:key];
+    if (choice) {
+        _userChoices[key] = choice;
+        [_userChoiceKeys addObject:key];
+    } else {
+        [_userChoices removeObjectForKey:key];
+    }
+    [ANNOptionsCache optionsChanged];
+}
+
+- (ANNUserChoice *)userChoiceForKey:(NSString *)key {
+    return _userChoices[key];
+}
+
+// Each choice answers the merge itself: it stays, keeps a part, or goes. The order of the rest stays.
+- (void)userChoicesMeetMerge:(ANNNavigationOptions *)merge
+                         own:(ANNNavigationOptions *)own
+                      before:(ANNNavigationOptions *)before
+                       after:(ANNNavigationOptions *)after {
+    for (NSString *key in [_userChoiceKeys copy]) {
+        ANNUserChoice *choice = _userChoices[key];
+        ANNUserChoice *kept = [choice choiceAfterMerge:merge own:own before:before after:after];
+        if (kept == choice) {
+            continue;
+        }
+        if (kept) {
+            _userChoices[key] = kept;
+        } else {
+            [_userChoices removeObjectForKey:key];
+            [_userChoiceKeys removeObject:key];
+        }
+    }
+}
+
+// The node's resolution with the defaults and without any user layer: what the app's options alone give (Android's
+// `resolveCurrentOptions().withDefaultOptions`). Built now, never cached: the resolution reads no cache on the way.
+- (ANNNavigationOptions *)appResolution {
+    BOOL leftOut = ANNUserLayersLeftOut;
+    ANNUserLayersLeftOut = YES;
+    @try {
+        return [self resolveOptionsWithDefaultUncached];
+    } @finally {
+        ANNUserLayersLeftOut = leftOut;
+    }
+}
+
+- (void)applyUserLayerTo:(ANNNavigationOptions *)options {
+    if (ANNUserLayersLeftOut) {
+        return;
+    }
+    for (NSString *key in _userChoiceKeys) {
+        [_userChoices[key] applyTo:options];
+    }
+}
+
 #pragma mark - Resolving
 
 - (ANNNavigationOptions *)resolveOptions {
     ANNNavigationOptions *result = _options ? [_options copy] : [ANNNavigationOptions new];
+    [self applyUserLayerTo:result];
     UIViewController *child = [_node getCurrentChild];
     if (child) {
         [result mergeOptions:[child resolveOptions]];
@@ -168,7 +259,9 @@ NSString *const ANNContainerReadyHandlerKey = @"ApexNavigation.container";
     return [self resolveOfNode:node parents:parents];
 }
 
-// Built on copies: the defaults never go into a node's own options.
+// Built on copies: the defaults never go into a node's own options. Each parent's user layer goes over its own
+// options; a node without a current child writes its own layer once more at the end, for the lists it takes from its
+// parents or the defaults (a toggle of a button of the stack's). Writing a choice twice gives the same result.
 - (ANNNavigationOptions *)resolveOfNode:(UIViewController *)node
                                 parents:(NSArray<UIViewController *> *)parents {
     ANNNavigationOptions *result = [ANNDefaultOptions.current copy];
@@ -177,8 +270,12 @@ NSString *const ANNContainerReadyHandlerKey = @"ApexNavigation.container";
         if (own) {
             [result mergeOptions:own];
         }
+        [parent.nodeHelper applyUserLayerTo:result];
     }
     [result mergeOptions:[node resolveOptions]];
+    if (![node getCurrentChild]) {
+        [self applyUserLayerTo:result];
+    }
     return result;
 }
 

package/ios/Core/ANNRenderWait.h

@@ -5,7 +5,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 /// What content a render wait waits for.
 typedef NS_ENUM(NSInteger, ANNRenderWaitContent) {
-    /// No content: the bar components alone (a push without `waitForRender`).
+    /// No content: the bar components alone.
     ANNRenderWaitContentNone,
     /// Each screen of `screens` whose React content isn't ready, by its own ready handler (a root's screens). The limit
     /// marks ready the screens still waited.
@@ -59,6 +59,20 @@ typedef NS_ENUM(NSInteger, ANNRenderWaitBar) {
 /// has none).
 @property(nonatomic) BOOL unknownContentRule;
 
+/// The content phase ends only once every call JavaScript made by then is applied on the main queue
+/// (`ANNJavaScriptCalls`): the options a screen merges in the commit that mounted it are there before the owner's next
+/// step. Also when the content is there already as the wait starts or takes its screens again (the commit that mounted
+/// it may have run just now): such a phase ends after `start`, through `protect`, while JavaScript has a call invoker;
+/// without one (no JavaScript running) the calls are applied already and the phase ends inside `start`, as without
+/// this. Screens without React content (a native screen) end the phase at once. The limit still ends the phase
+/// meanwhile. Off by default.
+@property(nonatomic) BOOL settlesThroughJavaScript;
+
+/// With `ANNRenderWaitBarAfterContent`, the bar phase that follows the content phase counts its limits from the wait's
+/// start, not from its own: the time the content took comes off each kind's limit, and a kind past it by then waits no
+/// more. A bar phase that starts again (`retakeScreens:`) counts from then, as without it. Off by default.
+@property(nonatomic) BOOL barLimitsFromStart;
+
 /// Runs inside `start`, after the ready handlers are set and before the readiness test (the stack parks and renders
 /// its entry there). A ready handler that runs inside it is left to the test after it.
 @property(nonatomic, copy, nullable) dispatch_block_t setUp;