@apexnative/navigation 1.0.0-alpha.3 → 1.0.0-alpha.5

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;

package/ios/Core/ANNRenderWait.mm

@@ -1,12 +1,26 @@
 #import "ANNRenderWait.h"
 #import "ANNAssert.h"
 #import "ANNComponentViewController.h"
+#import "ANNJavaScriptCalls.h"
 #import "ANNScreenReadiness.h"
 #import "UIViewController+LayoutProtocol.h"
+#import <QuartzCore/QuartzCore.h>
 
 // A screen whose rendered state stays unknown counts as ready after this, with `unknownContentRule`.
 static const NSTimeInterval ANNUnknownContentLimit = 1;
 
+// What a kind of the bar whose limit passed in the content phase still gets, with `barLimitsFromStart`: a limit of 0
+// would mean none of its own.
+static const NSTimeInterval ANNPassedBarLimit = 0.001;
+
+// What is left of a bar kind's `limit` after `spent`; no limit of its own stays none.
+static NSTimeInterval ANNBarLimitLeft(NSTimeInterval limit, NSTimeInterval spent) {
+    if (limit <= 0) {
+        return limit;
+    }
+    return MAX(limit - spent, ANNPassedBarLimit);
+}
+
 // The number of the last wait made: each wait listens under a key of its own.
 static NSUInteger ANNRenderWaitCount;
 
@@ -18,12 +32,18 @@ static NSUInteger ANNRenderWaitCount;
     ANNRenderWaitBar _bar;
     ANNBarWaitLimits _barLimits;
     NSString *_key;
+    // When the running wait started (`barLimitsFromStart`).
+    CFTimeInterval _startTime;
     // The token: each start, phase and end takes the next one, so that what an earlier one set up does nothing.
     NSUInteger _number;
     // Inside `start`: a step runs as it is, under the caller's protection.
     BOOL _starting;
     // Inside `setUp`: a ready handler leaves the node to the readiness test after it.
     BOOL _settingUp;
+    // The content is there and the phase waits for the calls JavaScript made by then (`settlesThroughJavaScript`); the
+    // number of that settle, so that one of an earlier take does nothing.
+    BOOL _settling;
+    NSUInteger _settleNumber;
     // The content nodes still waited, and every node the wait set its ready handler on.
     NSHashTable<UIViewController *> *_waited;
     NSHashTable<UIViewController *> *_listened;
@@ -70,6 +90,7 @@ static NSUInteger ANNRenderWaitCount;
     _isWaiting = YES;
     _isInBarPhase = NO;
     _mountLimitPassed = NO;
+    _startTime = CACurrentMediaTime();
     NSUInteger number = ++_number;
     _starting = YES;
     @try {
@@ -117,11 +138,9 @@ static NSUInteger ANNRenderWaitCount;
     if (![self runs:number]) {
         return;
     }
-    if (_content == ANNRenderWaitContentNode && _node && [self screensAreReady]) {
-        [_waited removeObject:_node];
-    }
+    [self testNode];
     if (_waited.count == 0 && !_barWait) {
-        [self phaseOfNumber:number endedMarkingReady:NO];
+        [self contentOfNumber:number];
     }
 }
 
@@ -206,7 +225,7 @@ static NSUInteger ANNRenderWaitCount;
     }
     [_waited removeObject:node];
     if (_waited.count == 0 && !_barWait) {
-        [self phaseOfNumber:number endedMarkingReady:NO];
+        [self contentOfNumber:number];
     }
 }
 
@@ -219,6 +238,36 @@ static NSUInteger ANNRenderWaitCount;
     if (_waited.count > 0) {
         return;
     }
+    [self contentOfNumber:number];
+}
+
+// What the running phase waited for came by its signals, or was there already. The content phase with
+// `settlesThroughJavaScript` ends once the calls JavaScript made by now are applied: the commit that mounted the content
+// ran its layout effects (`useScreenOptions`) in the same task of the JavaScript thread, so their `mergeOptions` are on
+// their way to the main queue ahead of the settle. Content that was there already (as the wait starts or takes its
+// screens again) may have mounted in a commit that ran just now: it settles too. The bar phase, and screens without
+// React content (a native screen), end at once.
+- (void)contentOfNumber:(NSUInteger)number {
+    if (!_settlesThroughJavaScript || _isInBarPhase || ![self hasReactScreen]) {
+        [self phaseOfNumber:number endedMarkingReady:NO];
+        return;
+    }
+    if (_settling) {
+        return;
+    }
+    _settling = YES;
+    NSUInteger settle = ++_settleNumber;
+    __weak ANNRenderWait *weakSelf = self;
+    [ANNJavaScriptCalls afterCallsMadeSoFar:^{
+      [weakSelf settleOfNumber:number settle:settle];
+    }];
+}
+
+- (void)settleOfNumber:(NSUInteger)number settle:(NSUInteger)settle {
+    if (![self runs:number] || !_settling || settle != _settleNumber) {
+        return;
+    }
+    _settling = NO;
     [self phaseOfNumber:number endedMarkingReady:NO];
 }
 
@@ -240,9 +289,18 @@ static NSUInteger ANNRenderWaitCount;
     }
 }
 
-// The limit: what is still waited counts as rendered from now on, its held events go at once.
+// The limit: what is still waited counts as rendered from now on, its held events go at once. A phase that only waits
+// for the calls of JavaScript (its content is there) ends without marking anything.
 - (void)limitOfNumber:(NSUInteger)number {
-    if (![self runs:number] || (_waited.count == 0 && !_barWait)) {
+    if (![self runs:number]) {
+        return;
+    }
+    if (_settling) {
+        [self stopSettling];
+        [self phaseOfNumber:number endedMarkingReady:NO];
+        return;
+    }
+    if (_waited.count == 0 && !_barWait) {
         return;
     }
     [self phaseOfNumber:number endedMarkingReady:YES];
@@ -288,7 +346,7 @@ static NSUInteger ANNRenderWaitCount;
           [self markContentReady];
       }
       if (self->_bar == ANNRenderWaitBarAfterContent && !self->_isInBarPhase) {
-          [self startBarPhase];
+          [self startBarPhaseWithLimits:[self barLimitsAfterContent]];
           return;
       }
       [self finish];
@@ -309,9 +367,10 @@ static NSUInteger ANNRenderWaitCount;
 
 #pragma mark - The bar phase
 
-// The content is there: the bar components of the screens now, each kind to its own limit from now. Nothing to wait
-// for ends the wait at once.
-- (void)startBarPhase {
+// The content is there: the bar components of the screens now, each kind to its limit in `limits` from now. Nothing to
+// wait for ends the wait at once.
+- (void)startBarPhaseWithLimits:(ANNBarWaitLimits)limits {
+    [self stopSettling];
     [_barWait cancel];
     _barWait = nil;
     [self releaseContent];
@@ -321,7 +380,7 @@ static NSUInteger ANNRenderWaitCount;
     NSArray<UIViewController *> *barScreens = [self barScreens];
     [self rememberTakenScreens:barScreens states:nil];
     ANNBarComponentsWait *barWait = [ANNBarComponentsWait waitForScreens:barScreens
-                                                                  limits:_barLimits
+                                                                  limits:limits
                                                                     done:^{
                                                                       [weakSelf barOfNumber:number];
                                                                     }];
@@ -344,23 +403,28 @@ static NSUInteger ANNRenderWaitCount;
     }
     if (_isInBarPhase) {
         [self runStep:^{
-          [self startBarPhase];
+          [self startBarPhaseWithLimits:self->_barLimits];
         }];
         return;
     }
     // The same token: the limit set at the start stays.
     NSUInteger number = _number;
+    [self stopSettling];
     [self releaseContent];
     [_barWait cancel];
     _barWait = nil;
-    if (take) {
-        [self takeScreensOfNumber:number];
-    } else {
+    if (!take) {
         _takenScreens = nil;
         _takenStates = nil;
+        [self phaseOfNumber:number endedMarkingReady:NO];
+        return;
     }
+    // As at the start: a node ready already counts at once (its ready handler waits for the next time), and content
+    // that is there settles again, the settle of the last take having stopped.
+    [self takeScreensOfNumber:number];
+    [self testNode];
     if (_waited.count == 0 && !_barWait) {
-        [self phaseOfNumber:number endedMarkingReady:NO];
+        [self contentOfNumber:number];
     }
 }
 
@@ -382,6 +446,7 @@ static NSUInteger ANNRenderWaitCount;
 
 // The wait lets go of everything: its handlers, its bar wait; its limits find another token.
 - (void)stop {
+    [self stopSettling];
     _isWaiting = NO;
     _isInBarPhase = NO;
     _takenScreens = nil;
@@ -404,6 +469,12 @@ static NSUInteger ANNRenderWaitCount;
 
 #pragma mark - Helpers
 
+// A settle on its way does nothing from now on.
+- (void)stopSettling {
+    _settling = NO;
+    _settleNumber++;
+}
+
 // What the content phase's take reads of each screen to decide what it waits for: the readiness it needs, whether it
 // has its content yet, whether that content is ready, and whether its root mounted.
 - (NSArray<NSNumber *> *)takeStateOfScreens:(NSArray<UIViewController *> *)screens {
@@ -470,6 +541,37 @@ static NSUInteger ANNRenderWaitCount;
     return screens;
 }
 
+// With `ANNRenderWaitContentNode`, the node counts as ready when every screen of it is.
+- (void)testNode {
+    if (_content == ANNRenderWaitContentNode && _node && [self screensAreReady]) {
+        [_waited removeObject:_node];
+    }
+}
+
+// The limits of the bar phase that follows the content phase: with `barLimitsFromStart`, what is left of each since the
+// wait started.
+- (ANNBarWaitLimits)barLimitsAfterContent {
+    ANNBarWaitLimits limits = _barLimits;
+    if (!_barLimitsFromStart) {
+        return limits;
+    }
+    NSTimeInterval spent = CACurrentMediaTime() - _startTime;
+    limits.titleAndBackground = ANNBarLimitLeft(limits.titleAndBackground, spent);
+    limits.buttons = ANNBarLimitLeft(limits.buttons, spent);
+    return limits;
+}
+
+// A screen with React content is among the screens: a commit of React mounted it.
+- (BOOL)hasReactScreen {
+    for (UIViewController *node in [self screens]) {
+        if ([node isKindOfClass:ANNComponentViewController.class] &&
+            ((ANNComponentViewController *)node).reactView) {
+            return YES;
+        }
+    }
+    return NO;
+}
+
 // Every screen has no content to wait for (a native screen) or its content is ready.
 - (BOOL)screensAreReady {
     for (UIViewController *node in [self screens]) {

package/ios/Core/UIViewController+LayoutProtocol.h

@@ -64,10 +64,17 @@ FOUNDATION_EXPORT ANNWaitedReadiness ANNWaitedReadinessOf(UIViewController *scre
 /// The own options merged with `options` (`ANNNodeHelper mergeOwnOptions:`).
 - (void)mergeOwnOptions:(ANNNavigationOptions *)options;
 
-/// A change of the own options on a copy (`ANNNodeHelper changeOwnOptions:`): the way a presenter or a module keeps a
-/// choice of the user (a scope, tokens, a checked menu item, a toggled button).
+/// A change of the own options on a copy (`ANNNodeHelper changeOwnOptions:`): what the core keeps of the app's merges.
 - (void)changeOwnOptions:(void (^)(ANNNavigationOptions *options))change;
 
+/// A choice of the user in the node's user layer (`ANNNodeHelper setUserChoice:forKey:`): the way a presenter or a
+/// module keeps what the user did (a scope, tokens, a checked menu item, a toggled button, a renamed title). Nil
+/// removes it.
+- (void)setUserChoice:(nullable ANNUserChoice *)choice forKey:(NSString *)key;
+
+/// The choice of the user layer under `key`, or nil (`ANNNodeHelper userChoiceForKey:`).
+- (nullable ANNUserChoice *)userChoiceForKey:(NSString *)key;
+
 #pragma mark - Readiness
 
 /// A ready handler of the node under the waiter's own key (`ANNNodeHelper setReadyHandler:forKey:`): it runs once, the

package/ios/Core/UIViewController+LayoutProtocol.mm

@@ -125,6 +125,14 @@ ANNWaitedReadiness ANNWaitedReadinessOf(UIViewController *screen) {
     [self.nodeHelper changeOwnOptions:change];
 }
 
+- (void)setUserChoice:(ANNUserChoice *)choice forKey:(NSString *)key {
+    [self.nodeHelper setUserChoice:choice forKey:key];
+}
+
+- (ANNUserChoice *)userChoiceForKey:(NSString *)key {
+    return [self.nodeHelper userChoiceForKey:key];
+}
+
 #pragma mark - Readiness
 
 - (void)setReadyHandler:(dispatch_block_t)handler forKey:(NSString *)key {

package/ios/Layouts/Modal/ANNModalCoordinator.h

@@ -25,7 +25,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 /// `dismissModal`: the record of `componentId` (its root's id or any id inside, also of a modal closed below or by the
 /// user), the options merged into its visible screen, the animation from the command's screen, then its state decides.
-/// Answers with the root's id.
+/// Answers with the root's id. The last modal over no root rejects `[ANNErrorTexts modalWithoutRoot:]`, as on Android.
 + (void)dismissModal:(NSString *)componentId
              options:(nullable NSDictionary *)options
               answer:(ANNCommandAnswer *)answer;