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

package/ios/Layouts/Stack/ANNStackPresenter.h

@@ -0,0 +1,44 @@
+#import "ANNNodePresenter.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Which visibilities of the stack's bars an application of the shared part sets. A bar the user hid (`hideOnScroll`
+/// before iOS 27, `hideOnTap`, `hideOnKeyboard`) comes back only when the top changes, at the top's appearance, or by a
+/// merge that names its visibility.
+typedef NS_OPTIONS(NSUInteger, ANNSharedBarVisibility) {
+    ANNSharedBarVisibilityNone = 0,
+    /// The bar's (`topBar.visible`).
+    ANNSharedBarVisibilityBar = 1 << 0,
+    /// The toolbar's (`toolbar.visible`, `toolbar.buttons`).
+    ANNSharedBarVisibilityToolbar = 1 << 1,
+    ANNSharedBarVisibilityAll = ANNSharedBarVisibilityBar | ANNSharedBarVisibilityToolbar,
+};
+
+/// The visibilities a merge names.
+FOUNDATION_EXPORT ANNSharedBarVisibility ANNSharedBarVisibilityOfMerge(ANNNavigationOptions *mergeOptions);
+
+/// The presenter of a stack: large titles always allowed in its bar (whether a screen shows one is its own options'),
+/// `popGesture` of the top into the swipes back (`popGesture`), and the parts of the bar the stack shares, from the
+/// options of the screen UIKit shows on top only: the bar's visibility, `hidesBarsOnSwipe` (before iOS 27),
+/// `hidesBarsOnTap` (`hideOnKeyboard` is the stack's, at each keyboard), `barStyle`, `clipsToBounds`, the bar's
+/// `testID`, the toolbar's visibility and `testID`, on iOS 26 a copy of the screen's look on the bar, and the screen's
+/// React background in the bar. The screens' items keep the rest (`ANNTopBarPresenter`). The stack's view takes the
+/// resolved background.
+@interface ANNStackPresenter : ANNNodePresenter
+
+/// The stack's view gets `layout.backgroundColor` of `resolvedOptions` (the shown child's over the stack's over the
+/// defaults): seen through clear bars and around the screens during transitions; none or "no color" is clear.
+- (void)applyBackground:(ANNNavigationOptions *)resolvedOptions;
+
+/// The shared parts from `options`, the resolved options of `screen`, which UIKit shows on top. `animated`: the
+/// visibility of the bar animates by `topBar.animate` (and the toolbar's), along `coordinator` when one runs, with
+/// which the background crossfades too. `visibility`: which of the bars' visibilities are set.
+- (void)applySharedBar:(ANNNavigationOptions *)options
+              ofScreen:(UIViewController *)screen
+              animated:(BOOL)animated
+           coordinator:(nullable id<UIViewControllerTransitionCoordinator>)coordinator
+            visibility:(ANNSharedBarVisibility)visibility;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Layouts/Stack/ANNStackPresenter.mm

@@ -0,0 +1,181 @@
+#import "ANNStackPresenter.h"
+#import "ANNBarBackgroundComponent.h"
+#import "ANNStackController.h"
+#import "ANNSystemUI.h"
+#import "ANNTopBarPresenter.h"
+
+ANNSharedBarVisibility ANNSharedBarVisibilityOfMerge(ANNNavigationOptions *mergeOptions) {
+    ANNSharedBarVisibility visibility = ANNSharedBarVisibilityNone;
+    if (mergeOptions.topBar.visible.hasValue) {
+        visibility |= ANNSharedBarVisibilityBar;
+    }
+    ANNToolbarOptions *toolbar = mergeOptions.toolbar;
+    if (toolbar.visible.hasValue || toolbar.buttons != nil) {
+        visibility |= ANNSharedBarVisibilityToolbar;
+    }
+    return visibility;
+}
+
+@implementation ANNStackPresenter
+
+- (nullable ANNStackController *)stack {
+    UIViewController *bound = self.boundViewController;
+    return [bound isKindOfClass:ANNStackController.class] ? (ANNStackController *)bound : nil;
+}
+
+#pragma mark - ANNNodePresenter
+
+// The bar exists before the view: it allows large titles from the start.
+- (void)applyOptionsOnInit:(ANNNavigationOptions *)initialOptions {
+    [super applyOptionsOnInit:initialOptions];
+    self.stack.navigationBar.prefersLargeTitles = YES;
+}
+
+// A top screen appeared (UIKit's `didShowViewController:`): what the stack shows follows its options.
+- (void)applyOptions:(ANNNavigationOptions *)options {
+    [super applyOptions:options];
+    ANNStackController *stack = self.stack;
+    [stack updateSwipeBack];
+    [stack applySharedBarIfTopChangedAnimated:NO];
+    [self applyBackground:options];
+}
+
+// A merge with the stack's id: the top screen's bar takes the merge's bar part with its own resolved options (its item
+// holds title, buttons and back button), then the stack its shared part (correction 7).
+- (void)mergeOptions:(ANNNavigationOptions *)mergeOptions
+     resolvedOptions:(ANNNavigationOptions *)resolvedOptions {
+    [super mergeOptions:mergeOptions resolvedOptions:resolvedOptions];
+    ANNStackController *stack = self.stack;
+    if (mergeOptions.popGesture.hasValue) {
+        [stack updateSwipeBack];
+    }
+    UIViewController *top = [stack getCurrentChild];
+    UIViewController *screen = top ? ANNStackOptionsScreen(top) : nil;
+    ANNTopBarPresenter *topBar = screen ? [ANNTopBarPresenter presenterOfScreen:screen] : nil;
+    if (topBar) {
+        [topBar mergeParentOptions:mergeOptions resolvedOptions:[screen resolveOptionsWithDefault]];
+    }
+    [stack applySharedBarAnimated:YES visibility:ANNSharedBarVisibilityOfMerge(mergeOptions)];
+    if (mergeOptions.layout.backgroundColor.hasValue) {
+        [self applyBackground:resolvedOptions];
+    }
+}
+
+// New default options repaint the shown stack's bar at once, without its visibility.
+- (void)applyDefaultOptionsChange:(ANNNavigationOptions *)resolvedOptions {
+    [super applyDefaultOptionsChange:resolvedOptions];
+    [self.stack applySharedBarAnimated:NO visibility:ANNSharedBarVisibilityNone];
+    [self applyBackground:resolvedOptions];
+}
+
+#pragma mark - The background (`layout.backgroundColor`)
+
+- (void)applyBackground:(ANNNavigationOptions *)resolvedOptions {
+    UIView *view = self.stack.viewIfLoaded;
+    if (!view) {
+        return;
+    }
+    UIColor *color = [resolvedOptions.layout.backgroundColor withDefault:nil];
+    if (!(view.backgroundColor == color || [view.backgroundColor isEqual:color])) {
+        view.backgroundColor = color;
+    }
+}
+
+#pragma mark - The shared parts of the bar
+
+- (void)applySharedBar:(ANNNavigationOptions *)options
+              ofScreen:(UIViewController *)screen
+              animated:(BOOL)animated
+           coordinator:(id<UIViewControllerTransitionCoordinator>)coordinator
+            visibility:(ANNSharedBarVisibility)visibility {
+    ANNStackController *stack = self.stack;
+    if (!stack) {
+        return;
+    }
+    // In More the screens show in UIKit's More navigation: the shared parts go onto it.
+    UINavigationController *navigation = stack.shownNavigationController;
+    UINavigationBar *bar = navigation.navigationBar;
+    BOOL inWindow = navigation.viewIfLoaded.window != nil;
+    ANNTopBarOptions *topBar = options.topBar;
+    BOOL barsChanged = NO;
+    // `visible` (`topBar.visible`), animated by the resolved `animate`; UIKit animates it with the transition that
+    // runs.
+    BOOL hidden = ![topBar.visible withDefault:YES];
+    if ((visibility & ANNSharedBarVisibilityBar) && navigation.navigationBarHidden != hidden) {
+        BOOL animates = animated && inWindow && [topBar.animate withDefault:YES];
+        [navigation setNavigationBarHidden:hidden animated:animates];
+        barsChanged = YES;
+        // `hideWithTopBar` follows the bar: UIKit's More navigation's too.
+        [ANNSystemUI setNeedsUpdateOfGroups:ANNSystemUIGroupStatusBar];
+    }
+    // The toolbar shows while the screen has buttons and `toolbar.visible` isn't `false`.
+    BOOL toolbarHidden = !options.toolbar.shouldShow;
+    if ((visibility & ANNSharedBarVisibilityToolbar) && navigation.toolbarHidden != toolbarHidden) {
+        [navigation setToolbarHidden:toolbarHidden animated:animated && inWindow];
+        barsChanged = YES;
+    }
+    // The hiding modes: before iOS 27 `hideOnScroll` is the stack's swipe; from 27 the screen's item minimizes the bar.
+    BOOL hidesOnSwipe = [topBar.hideOnScroll withDefault:NO];
+    if (@available(iOS 27.0, *)) {
+        hidesOnSwipe = NO;
+    }
+    if (navigation.hidesBarsOnSwipe != hidesOnSwipe) {
+        navigation.hidesBarsOnSwipe = hidesOnSwipe;
+    }
+    BOOL hidesOnTap = [topBar.hideOnTap withDefault:NO];
+    if (navigation.hidesBarsOnTap != hidesOnTap) {
+        navigation.hidesBarsOnTap = hidesOnTap;
+    }
+    // `hideOnKeyboard` is the stack's own (`keyboardWillShow:` of `ANNStackController`), read from the top at each
+    // keyboard: UIKit's `hidesBarsWhenKeyboardAppears`, once on, kept hiding the bar for the screens shown after the
+    // one that set it, also after it was set back to `NO`. UIKit's flag stays off.
+    if (navigation.hidesBarsWhenKeyboardAppears) {
+        navigation.hidesBarsWhenKeyboardAppears = NO;
+    }
+    // Passed through.
+    BOOL black = [[topBar.barStyle withDefault:nil] isEqualToString:@"black"];
+    UIBarStyle barStyle = black ? UIBarStyleBlack : UIBarStyleDefault;
+    if (bar.barStyle != barStyle) {
+        bar.barStyle = barStyle;
+    }
+    BOOL clips = [topBar.background.clipToBounds withDefault:NO];
+    if (bar.clipsToBounds != clips) {
+        bar.clipsToBounds = clips;
+    }
+    // Without a `testID` UIKit names the bar by its title. Each value is set only when it changes: nothing of the bar
+    // moves in the middle of a transition for nothing.
+    NSString *testID = [topBar.testID withDefault:nil];
+    testID = testID.length > 0 ? testID : nil;
+    if (![bar.accessibilityIdentifier ?: @"" isEqualToString:testID ?: @""]) {
+        bar.accessibilityIdentifier = testID;
+    }
+    // The toolbar exists once it shows or has an id to carry: asking for it makes it.
+    NSString *toolbarTestID = [options.toolbar.testID withDefault:nil];
+    toolbarTestID = toolbarTestID.length > 0 ? toolbarTestID : nil;
+    if (toolbarTestID || !navigation.toolbarHidden) {
+        UIToolbar *toolbar = navigation.toolbar;
+        if (![toolbar.accessibilityIdentifier ?: @"" isEqualToString:toolbarTestID ?: @""]) {
+            toolbar.accessibilityIdentifier = toolbarTestID;
+        }
+    }
+    // iOS 26: the bar keeps a copy of the shown screen's look too.
+    if (@available(iOS 26.0, *)) {
+        UINavigationBarAppearance *standard = screen.navigationItem.standardAppearance;
+        if (standard && ![bar.standardAppearance isEqual:standard]) {
+            bar.standardAppearance = [standard copy];
+        }
+    }
+    ANNTopBarPresenter *screenBar = [ANNTopBarPresenter presenterOfScreen:screen];
+    [ANNBarBackgroundComponent show:screenBar.background inBar:bar coordinator:coordinator];
+    // Outside a transition the screen places it at once (in the list under an expanded large title); after a
+    // transition its appearance does.
+    if (!coordinator) {
+        [screenBar updateBackgroundPlacement];
+    }
+    // The screens apply their "under bars" rule again (`hasShownTopBar`, the toolbar's padding).
+    if (barsChanged) {
+        [stack updateRootLayoutOfShownEntries];
+    }
+}
+
+@end

package/ios/Layouts/Stack/ANNStackQueue.h

@@ -0,0 +1,194 @@
+#import "ANNCommandAnswer.h"
+#import "ANNLayoutProtocol.h"
+#import <UIKit/UIKit.h>
+
+@class ANNComponentViewController;
+@class ANNTransitionPlan;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The screen whose options an entry of a stack shows with: a pair's `optionsScreen` (its primary), else the entry.
+FOUNDATION_EXPORT UIViewController *ANNStackOptionsScreen(UIViewController *entry);
+
+/// The stack command that answers with the id of an entry (`ANNStackAnswerIdOf`).
+typedef NS_ENUM(NSInteger, ANNStackAnswerCommand) {
+    /// `push`, also one interrupted before it showed.
+    ANNStackAnswerCommandPush,
+    /// `setStackRoot` and every other replace of the list: its new top.
+    ANNStackAnswerCommandReplace,
+    /// `pop` from the stack's id: the top that leaves.
+    ANNStackAnswerCommandPop,
+    /// `popToRoot`: the first entry.
+    ANNStackAnswerCommandPopToRoot,
+    /// A push or a preview whose key names an entry of the stack: that entry.
+    ANNStackAnswerCommandKey,
+    /// `showInColumn` that put the screen in a column: the screen.
+    ANNStackAnswerCommandShowInColumn,
+};
+
+/// The one rule of the id a stack command answers with for an entry: `push` answers the node's own id (a pair's id for
+/// a pair), every other command the id of the entry's options screen (`ANNStackOptionsScreen`: a pair's primary). An
+/// entry that isn't a pair answers its own id with every command. A command that answers the id it was given (`popTo`,
+/// `pop` from a screen) doesn't ask.
+FOUNDATION_EXPORT NSString *ANNStackAnswerIdOf(UIViewController *entry,
+                                               ANNStackAnswerCommand command);
+
+/// Every screen of an entry of a stack: the entry itself, or the screens of a pair, also one out of the window. Not the
+/// screens a wait is about: those are the entry's `waitedComponentViewControllers` (a pair: the screens it puts in the
+/// window).
+FOUNDATION_EXPORT NSArray<ANNComponentViewController *> *
+ANNStackScreensOfEntry(UIViewController *entry);
+
+/// The readiness test of a waited entry after its `render`: each of its screens has no content to wait for (a native
+/// screen) or its content is ready.
+FOUNDATION_EXPORT BOOL ANNStackEntryIsReady(UIViewController *entry);
+
+/// How UIKit's list of a stack changes.
+typedef NS_ENUM(NSInteger, ANNStackChange) {
+    /// The last entry comes on top (`pushViewController:animated:`).
+    ANNStackChangePush,
+    /// Back to the last entry (`popToViewController:animated:`).
+    ANNStackChangePop,
+    /// The whole list (`setViewControllers:animated:`).
+    ANNStackChangeReplace,
+};
+
+/// What the queue asks of its stack (`ANNStackController`): the calls to UIKit, whether the stack is seen, the
+/// waiting place of a screen. The queue itself knows no view.
+@protocol ANNStackDisplay <NSObject>
+
+/// The stack's own view controller: the layout parent of the nodes it took and doesn't show yet.
+- (UIViewController *)stackViewController;
+
+/// The stack is seen: its view is in a window, and it isn't inside a layer that waits to show (`ANNPendingLayers`).
+- (BOOL)stackIsOnScreen;
+
+/// A transition UIKit runs on the stack now (one the queue didn't start); nil when none runs.
+- (nullable id<UIViewControllerTransitionCoordinator>)stackRunningTransition;
+
+/// UIKit's list becomes `entries`, by `change`. `plan`: the change's own custom transition, which UIKit gets when it
+/// asks for the transition of this change; nil: UIKit's own (or a zoom of the pushed screen).
+- (void)stackChange:(ANNStackChange)change
+          toEntries:(NSArray<UIViewController *> *)entries
+           animated:(BOOL)animated
+               plan:(nullable ANNTransitionPlan *)plan;
+
+/// `ended` runs once, when the transition UIKit has just started ends (its coordinator, never `CATransaction`), or at
+/// once when UIKit runs none. `cancelled` only for an interactive one.
+- (void)stackWhenTransitionEnds:(void (^)(BOOL cancelled))ended;
+
+/// A screen waits for its content in the window, at the stack's size, unseen; and leaves that place.
+- (void)stackPark:(UIViewController *)entry;
+- (void)stackUnpark:(UIViewController *)entry;
+
+/// An entry joins UIKit's list (its back button, its root frame); `first` is the stack's first entry.
+- (void)stackEntryJoins:(UIViewController *)entry first:(BOOL)first;
+
+/// UIKit's list is about to lose entries or change whole: the lower screens that render in the stack's view leave it.
+- (void)stackEntriesWillMove;
+
+/// The lower new entries of a list made their way into UIKit's list: they make their content now.
+- (void)stackRenderLowerEntries:(NSArray<UIViewController *> *)entries;
+
+/// An operation ended: the top may be another one.
+- (void)stackOperationEnded;
+
+@end
+
+/// The one queue of a stack: every command of the stack and every action of the user goes through it, in order. It
+/// keeps the stack's two lists: `entries`, the stack as JavaScript sees it, changed when a command or an action is
+/// accepted (every check reads it), and `shown`, what UIKit's list has, changed as each operation runs. It is at rest,
+/// waits for a screen to render, or runs one UIKit transition; what comes meanwhile interrupts, completes or waits.
+/// Each operation answers once, with the end steps, `ANN.ScreenPopped` of every entry that left before its content
+/// stops. Main queue.
+@interface ANNStackQueue : NSObject
+
+- (instancetype)initWithDisplay:(id<ANNStackDisplay>)display NS_DESIGNATED_INITIALIZER;
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The stack as JavaScript sees it, bottom to top.
+@property(nonatomic, readonly) NSArray<UIViewController *> *entries;
+
+/// What UIKit's list has of the stack's entries, bottom to top; its last is the stack's current child.
+@property(nonatomic, readonly) NSArray<UIViewController *> *shown;
+
+/// Nothing runs, nothing waits, nothing is queued, and UIKit runs no transition of its own.
+@property(nonatomic, readonly) BOOL isAtRest;
+
+/// Every node the stack holds: those shown, those waiting, those taken and not run yet, those leaving.
+@property(nonatomic, readonly) NSArray<UIViewController *> *heldNodes;
+
+/// The list the stack was made with (the layout factory): shown and entries both, no transition, no event.
+- (void)setInitialEntries:(NSArray<UIViewController *> *)entries;
+
+#pragma mark - Operations
+
+/// `push` of `node`, made and checked: it joins `entries` now and shows by the queue's rules. `componentId` is the
+/// command's (for its texts), `source` the node it came from.
+- (void)push:(UIViewController *)node
+         answer:(ANNCommandAnswer *)answer
+           what:(NSString *)what
+    componentId:(NSString *)componentId
+         source:(nullable UIViewController *)source;
+
+/// The same with two of the rules set by the caller: `animated` NO pushes without an animation whatever the node's
+/// `animations.push` (a preview that grows into its screen), YES as they say; `waits` NO never waits for a render
+/// before the transition (a screen rendered already: a preview, `showInColumn`'s push).
+- (void)push:(UIViewController *)node
+         answer:(ANNCommandAnswer *)answer
+           what:(NSString *)what
+    componentId:(NSString *)componentId
+         source:(nullable UIViewController *)source
+       animated:(BOOL)animated
+          waits:(BOOL)waits;
+
+/// Every entry above `target` leaves (`pop`, `popTo`, `popToRoot`, a key that leads back; a user's back with no
+/// answer). The visible top leaves with its `animations.pop`, the others without an animation; `silent` moves without
+/// an animation and without appearance events (`popToRootOnBlur`).
+- (void)cutTo:(UIViewController *)target
+         answer:(nullable ANNCommandAnswer *)answer
+          value:(nullable id)value
+           what:(NSString *)what
+    componentId:(nullable NSString *)componentId
+         source:(nullable UIViewController *)source
+         silent:(BOOL)silent;
+
+/// `nodes` in place of every entry (`setStackRoot`; the split view's call with `waits` NO). The answer or the
+/// completion comes at the end; the rejection of a split view's call when it fails.
+- (void)replaceWith:(NSArray<UIViewController *> *)nodes
+           animated:(BOOL)animated
+              waits:(BOOL)waits
+             answer:(nullable ANNCommandAnswer *)answer
+               what:(NSString *)what
+        componentId:(NSString *)componentId
+             source:(nullable UIViewController *)source
+         completion:(nullable dispatch_block_t)completion
+          rejection:(nullable ANNTransitionRejectionBlock)rejection;
+
+/// A command that moves nothing (`popTo` of the top) answers `value` in its turn.
+- (void)noneWithValue:(id)value
+               answer:(ANNCommandAnswer *)answer
+          componentId:(NSString *)componentId
+               source:(nullable UIViewController *)source;
+
+#pragma mark - The swipe back and the stack
+
+/// UIKit started the interactive pop of the stack's top (`willShowViewController:` with an interactive coordinator):
+/// the swipe is the queue's operation until its coordinator completes. NO when the queue doesn't take it.
+- (BOOL)swipeBeganFrom:(UIViewController *)top revealing:(UIViewController *)revealed;
+
+/// UIKit changed its list by itself while the queue didn't run it (its own pop, a swipe the queue didn't take): the
+/// entries UIKit no longer lists leave the stack's lists, get `ScreenPopped` and are destroyed.
+- (void)uikitShows:(NSArray<UIViewController *> *)viewControllers;
+
+/// The stack left the screen: an operation that waits for its screen runs now, as in a stack off screen.
+- (void)stackWentOffScreen;
+
+/// The stack goes: the waiting, running and queued commands reject `the screen '<id>' is not shown`, the actions of the
+/// user end without a word, nothing waits any more. The nodes to destroy come back.
+- (NSArray<UIViewController *> *)destroyQueue;
+
+@end
+
+NS_ASSUME_NONNULL_END