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

package/ios/React/Slots/ANNSlotScreenView.mm

@@ -0,0 +1,254 @@
+#import "ANNSlotScreenView.h"
+#import "ANNAppearanceDispatcher.h"
+#import "ANNScreenAppearance.h"
+#import "ANNScreenReadiness.h"
+#import "ANNSlotHost.h"
+#import "../../cpp/react/renderer/components/ApexNavigationSpec/ANNSlotState.h"
+#import <React/RCTConstants.h>
+#import <React/RCTSurfacePresenter.h>
+#import <React/RCTUtils.h>
+#import <ReactCommon/RCTHost.h>
+
+@interface ANNSlotScreenView () <RCTSurfacePresenterObserver, ANNScreenReadinessListener>
+@end
+
+@implementation ANNSlotScreenView {
+    ANNScreenAppearance *_appearance;
+    __weak RCTSurfacePresenter *_surfacePresenter;
+    NSString *_componentId;
+    NSString *_moduleName;
+    ANNReactViewReadyCompletionBlock _reactViewReadyBlock;
+    NSMutableDictionary<NSString *, void (^)(void)> *_contentDidMountHandlers;
+    BOOL _isMounted;
+    BOOL _stopped;
+    // The ready signal went: the content mounted and rendered.
+    BOOL _ready;
+    // The host's surface mounts now: readiness is decided as that mount ends.
+    BOOL _hostMounting;
+    CGSize _lastSize;
+}
+
+- (instancetype)initWithComponentId:(NSString *)componentId
+                               name:(NSString *)name
+                               host:(RCTHost *)host
+                       eventEmitter:(ANNEventEmitter *)eventEmitter
+                reactViewReadyBlock:(ANNReactViewReadyCompletionBlock)reactViewReadyBlock {
+    self = [super initWithFrame:CGRectZero];
+    if (self) {
+        _componentId = [componentId copy];
+        _moduleName = ANNComponentNameWithoutSlotPrefix(name);
+        _eventEmitter = eventEmitter;
+        _reactViewReadyBlock = [reactViewReadyBlock copy];
+        // The core's dispatcher holds the appearance until the slot's content mounted here (`isReady` and the mount
+        // handlers), at most 0.5 s, and keeps it balanced.
+        _appearance = [[ANNScreenAppearance alloc] initWithComponentId:_componentId
+                                                         componentName:_moduleName
+                                                         componentType:ANNReactComponentTypeScreen
+                                                               content:self
+                                                          eventEmitter:eventEmitter];
+        [ANNSlotHost startWithHost:host];
+        [ANNSlotContainers setContainer:self forSlotId:_componentId];
+        _surfacePresenter = host.surfacePresenter;
+        [_surfacePresenter addObserver:self];
+        // Ready once the slot's content mounted here and the screen rendered into its safe area view: the empty safe
+        // area view mounts a commit before the screen renders. A slot whose screen renders nothing holds a waiting
+        // command no longer than the command's own limit.
+        [ANNScreenReadiness setListener:self forScreenId:_componentId];
+    }
+    return self;
+}
+
+- (RCTFabricSurface *)surface {
+    return nil;
+}
+
+// The slot lays its content out at this size: every change goes to it (rotation, a sheet detent, the bars).
+- (void)layoutSubviews {
+    [super layoutSubviews];
+    if (!CGSizeEqualToSize(self.bounds.size, _lastSize)) {
+        _lastSize = self.bounds.size;
+        [ANNSlotContainers containerDidChange:_componentId];
+    }
+}
+
+// React Native hears of the app's light or dark style only from its hosting views. In one tree the screens have none in
+// the window: the host's is in a hidden window, which UIKit gives no trait changes, so `useColorScheme` kept the old
+// theme. The screen's view tells React Native as the hosting view of a screen would, with its filter
+// (`ANNSurfaceHostingView`): only a style its window shares, so the theme follows the window alone. React Native skips
+// the traits UIKit takes for the snapshots in the background; so does this.
+- (void)traitCollectionDidChange:(UITraitCollection *)previousTraitCollection {
+    [super traitCollectionDidChange:previousTraitCollection];
+    UIWindow *window = self.window;
+    UIUserInterfaceStyle style = self.traitCollection.userInterfaceStyle;
+    if (!window || style == previousTraitCollection.userInterfaceStyle ||
+        style != window.traitCollection.userInterfaceStyle ||
+        RCTSharedApplication().applicationState == UIApplicationStateBackground) {
+        return;
+    }
+    [[NSNotificationCenter defaultCenter]
+        postNotificationName:RCTUserInterfaceStyleDidChangeNotification
+                      object:self
+                    userInfo:@{
+                        RCTUserInterfaceStyleDidChangeNotificationTraitCollectionKey : self.traitCollection
+                    }];
+}
+
+- (void)stopSurface {
+    if (!RCTIsMainQueue()) {
+        dispatch_async(dispatch_get_main_queue(), ^{
+          [self stopSurface];
+        });
+        return;
+    }
+    if (_stopped) {
+        return;
+    }
+    _stopped = YES;
+    [_surfacePresenter removeObserver:self];
+    [ANNScreenReadiness removeListener:self forScreenId:_componentId];
+    // A later screen shown under the same id keeps the slot.
+    if ([ANNSlotContainers containerForSlotId:_componentId] != self) {
+        return;
+    }
+    facebook::react::ANNSlotContentHeights::forget(_componentId.UTF8String ?: "");
+    [ANNSlotContainers removeContainerForSlotId:_componentId];
+    [_eventEmitter sendSlotDestroyed:_componentId];
+}
+
+// The slot measures its content in its own layout: the first question asks for it and lays the slot out again; the
+// height comes with that layout, before the mount the content's mount handlers hear. The width is the container's, at
+// which the slot lays its content out.
+- (CGFloat)contentHeightAtWidth:(CGFloat)width {
+    std::string slotId = _componentId.UTF8String ?: "";
+    if (_stopped || slotId.empty()) {
+        return 0;
+    }
+    if (!facebook::react::ANNSlotContentHeights::isRequested(slotId)) {
+        facebook::react::ANNSlotContentHeights::request(slotId);
+        [ANNSlotContainers containerDidChange:_componentId];
+        return 0;
+    }
+    facebook::react::Float height = facebook::react::ANNSlotContentHeights::height(slotId);
+    return height > 0 ? (CGFloat)height : 0;
+}
+
+- (void)setContentDidMount:(void (^)(void))handler forKey:(NSString *)key {
+    if (!_contentDidMountHandlers) {
+        _contentDidMountHandlers = [NSMutableDictionary new];
+    }
+    _contentDidMountHandlers[key] = [handler copy];
+}
+
+#pragma mark - ANNSlotContainer
+
+- (void)slotContentDidMount {
+    _isMounted = YES;
+    if (!_ready) {
+        if (!_hostMounting) {
+            [self becomeReadyIfRendered];
+        }
+        return;
+    }
+    [self runContentDidMountHandlers];
+}
+
+// The content is in the slot, and its safe area view said the screen rendered into it, or no safe area view ever
+// spoke for the id (the mount counts then, as for a React root without one).
+- (void)becomeReadyIfRendered {
+    if (_ready || _stopped || !_isMounted ||
+        [ANNScreenReadiness contentRenderedOfScreen:_componentId] == ANNContentRenderedNo) {
+        return;
+    }
+    // The handlers of this mount first (the held appearance, the bar, the sizes), then the ready block that lets a
+    // waiting command go on, as for a React root.
+    _ready = YES;
+    [self runContentDidMountHandlers];
+    [self reactViewReady];
+}
+
+- (void)runContentDidMountHandlers {
+    for (void (^handler)(void) in _contentDidMountHandlers.allValues) {
+        handler();
+    }
+}
+
+#pragma mark - ANNScreenReadinessListener
+
+// The safe area view says so while the host mounts: the screen gets ready as that mount ends.
+- (void)screenReadinessContentDidRender:(NSString *)screenId {
+    if (!_hostMounting) {
+        [self becomeReadyIfRendered];
+    }
+}
+
+#pragma mark - RCTSurfacePresenterObserver
+
+// React mounts the views deeper in the screen's content (a list, rendered once the screen's safe area view is laid
+// out) in the host's surface, and the slot hears only of its own children: the screen hears of every mount of the
+// host, as the React view of a screen hears of every mount of its surface (a large title's color goes into the list
+// as it mounts, during the push). Only while it is in the window: a screen gets the rest as it appears.
+- (void)willMountComponentsWithRootTag:(NSInteger)rootTag {
+    if (rootTag == ANNSlotHost.rootTag) {
+        _hostMounting = YES;
+    }
+}
+
+- (void)didMountComponentsWithRootTag:(NSInteger)rootTag {
+    if (rootTag != ANNSlotHost.rootTag) {
+        return;
+    }
+    _hostMounting = NO;
+    if (!_ready) {
+        [self becomeReadyIfRendered];
+        return;
+    }
+    if (!_isMounted || _stopped || !self.window) {
+        return;
+    }
+    [self runContentDidMountHandlers];
+}
+
+- (void)dealloc {
+    [_surfacePresenter removeObserver:self];
+}
+
+- (void)reactViewReady {
+    _ready = YES;
+    if (_reactViewReadyBlock) {
+        ANNReactViewReadyCompletionBlock block = _reactViewReadyBlock;
+        _reactViewReadyBlock = nil;
+        block();
+    }
+}
+
+#pragma mark - ANNComponentProtocol
+
+- (ANNScreenAppearance *)appearance {
+    return _appearance;
+}
+
+- (BOOL)isReady {
+    return _ready;
+}
+
+- (NSString *)componentId {
+    return _componentId;
+}
+
+- (ANNReactComponentType)componentType {
+    return ANNReactComponentTypeScreen;
+}
+
+- (void)componentWillAppear {
+    [ANNAppearanceDispatcher willAppear:_appearance];
+}
+
+- (void)componentDidAppear {
+    [ANNAppearanceDispatcher didAppear:_appearance];
+}
+
+- (void)componentDidDisappear {
+    [ANNAppearanceDispatcher didDisappear:_appearance];
+}
+
+@end

package/ios/TopBar/ANNBackButtonPresenter.h

@@ -0,0 +1,35 @@
+#import "ANNNavigationOptions.h"
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The back button of a screen in a stack (`topBar.backButton.*`): UIKit's system button. Its title and mode go to the
+/// screen below (`backButtonTitle`, `backButtonDisplayMode`), which the core marks as configured; when the screen on
+/// top has no back options, what the core set before goes, and a back button a native screen set on its own item is
+/// never touched. An own `backBarButtonItem` only with `enableMenu: false` or an `iconBackground` with a color. Its
+/// color, font and arrow are the shown screen's look (`ANNBarAppearance`). No `testID`: UIKit names it `BackButton`.
+@interface ANNBackButtonPresenter : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The back button of `screen` from its resolved `options`; nothing without a screen below.
++ (void)applyOptions:(ANNNavigationOptions *)options ofScreen:(UIViewController *)screen;
+
+/// `backButton.visible` into the screen's own item (`hidesBackButton`).
++ (void)applyVisibility:(ANNNavigationOptions *)options ofScreen:(UIViewController *)screen;
+
+/// A new look of a shown back button (font, color, icon, SF Symbol, icon background): UIKit applies it only when it
+/// builds the button again, so its mode is switched there and back on the screen below, never during a transition.
++ (void)rebuildBackButtonOfScreen:(UIViewController *)screen;
+
+/// Whether `screen` has a back button: an entry above the first of its stack, `backButton.visible` not `false` (by the
+/// options). `iconBackground.color` of the back button: with it the back button is the core's own, its icon drawn on
+/// that background (`topBar.backButton.iconBackground`); nil without one.
++ (nullable UIColor *)iconBackgroundColorOf:(ANNTopBarBackButtonOptions *)backButton;
+
++ (BOOL)screenHasBackButton:(UIViewController *)screen options:(ANNNavigationOptions *)options;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/TopBar/ANNBackButtonPresenter.mm

@@ -0,0 +1,187 @@
+#import "ANNBackButtonPresenter.h"
+#import "ANNExternalViewController.h"
+#import "ANNIconButtonImage.h"
+#import "ANNStackController.h"
+#import <objc/runtime.h>
+
+// The item below that the core configured: what it set may go again.
+static const void *ANNBackButtonConfiguredKey = &ANNBackButtonConfiguredKey;
+
+// The own back button: with `enableMenu: false` it takes no history menu (UIKit gives the menu to the back item).
+@interface ANNBackBarButtonItem : UIBarButtonItem
+@property(nonatomic) BOOL allowsMenu;
+@end
+
+@implementation ANNBackBarButtonItem
+
+- (void)setMenu:(UIMenu *)menu {
+    [super setMenu:self.allowsMenu ? menu : nil];
+}
+
+@end
+
+@implementation ANNBackButtonPresenter
+
+// The entries of the stack the screen is in, as they show (a pushed screen is there before UIKit's list has it).
++ (nullable NSArray<UIViewController *> *)entriesOf:(UIViewController *)screen
+                                             entry:(UIViewController *_Nullable *_Nonnull)entry {
+    UINavigationController *stack = screen.stack;
+    if (![stack isKindOfClass:ANNStackController.class]) {
+        *entry = nil;
+        return nil;
+    }
+    ANNStackController *stackController = (ANNStackController *)stack;
+    *entry = [stackController entryOf:screen];
+    return stackController.queue.shown;
+}
+
++ (nullable UIViewController *)entryBelow:(UIViewController *)screen {
+    UIViewController *entry = nil;
+    NSArray<UIViewController *> *entries = [self entriesOf:screen entry:&entry];
+    NSUInteger index = entry ? [entries indexOfObjectIdenticalTo:entry] : NSNotFound;
+    return index != NSNotFound && index > 0 ? entries[index - 1] : nil;
+}
+
++ (BOOL)screenHasBackButton:(UIViewController *)screen options:(ANNNavigationOptions *)options {
+    if (![options.topBar.backButton.visible withDefault:YES]) {
+        return NO;
+    }
+    UIViewController *entry = nil;
+    NSArray<UIViewController *> *entries = [self entriesOf:screen entry:&entry];
+    NSUInteger index = entry ? [entries indexOfObjectIdenticalTo:entry] : NSNotFound;
+    if (index == NSNotFound) {
+        // A screen not in a list yet (its push waits): it shows above what the stack has.
+        return entries.count > 0 && entry != nil;
+    }
+    return index > 0;
+}
+
++ (void)applyVisibility:(ANNNavigationOptions *)options ofScreen:(UIViewController *)screen {
+    Bool *visible = options.topBar.backButton.visible;
+    // A native screen's item is the app's: its own `hidesBackButton` stays unless the options say.
+    if (!visible.hasValue && [screen isKindOfClass:ANNExternalViewController.class]) {
+        return;
+    }
+    BOOL hidden = ![visible withDefault:YES];
+    if (screen.navigationItem.hidesBackButton != hidden) {
+        screen.navigationItem.hidesBackButton = hidden;
+    }
+}
+
++ (void)applyOptions:(ANNNavigationOptions *)options ofScreen:(UIViewController *)screen {
+    [self applyVisibility:options ofScreen:screen];
+    UIViewController *below = [self entryBelow:screen];
+    if (!below) {
+        return;
+    }
+    UINavigationItem *item = below.navigationItem;
+    BOOL configured = [objc_getAssociatedObject(item, ANNBackButtonConfiguredKey) boolValue];
+    // A back button the screen below set itself (a native screen's own item) stays as it is.
+    BOOL ownedByScreen =
+        item.backButtonTitle != nil || item.backBarButtonItem != nil ||
+        item.backButtonDisplayMode != UINavigationItemBackButtonDisplayModeDefault;
+    if (!configured && ownedByScreen) {
+        return;
+    }
+    ANNTopBarBackButtonOptions *backButton = options.topBar.backButton;
+    NSString *title = [backButton.title withDefault:nil];
+    NSString *belowTitle = below.navigationItem.title;
+    UINavigationItemBackButtonDisplayMode mode = [self displayModeOf:backButton];
+    if (backButton.showTitle.hasValue) {
+        if (backButton.showTitle.get) {
+            title = title ?: belowTitle;
+        } else {
+            mode = UINavigationItemBackButtonDisplayModeMinimal;
+        }
+    }
+    BOOL ownButton = (backButton.enableMenu.hasValue && !backButton.enableMenu.get) ||
+                     [self iconBackgroundColorOf:backButton] != nil;
+    if (!title && mode == UINavigationItemBackButtonDisplayModeDefault && !ownButton) {
+        if (configured) {
+            item.backButtonTitle = nil;
+            item.backBarButtonItem = nil;
+            item.backButtonDisplayMode = UINavigationItemBackButtonDisplayModeDefault;
+            objc_setAssociatedObject(item, ANNBackButtonConfiguredKey, nil,
+                                     OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+        }
+        return;
+    }
+    objc_setAssociatedObject(item, ANNBackButtonConfiguredKey, @YES,
+                             OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+    item.backButtonTitle = title;
+    item.backButtonDisplayMode = mode;
+    item.backBarButtonItem =
+        ownButton ? [self ownButtonOf:backButton title:title belowTitle:belowTitle] : nil;
+}
+
++ (UINavigationItemBackButtonDisplayMode)displayModeOf:(ANNTopBarBackButtonOptions *)backButton {
+    NSString *mode = [backButton.displayMode withDefault:nil];
+    if ([mode isEqualToString:@"generic"]) {
+        return UINavigationItemBackButtonDisplayModeGeneric;
+    }
+    if ([mode isEqualToString:@"minimal"]) {
+        return UINavigationItemBackButtonDisplayModeMinimal;
+    }
+    return UINavigationItemBackButtonDisplayModeDefault;
+}
+
++ (nullable UIColor *)iconBackgroundColorOf:(ANNTopBarBackButtonOptions *)backButton {
+    Color *color = backButton.iconBackground.color;
+    if (!color.hasValue || color.isNoColor) {
+        return nil;
+    }
+    return [color withDefault:UIColor.clearColor];
+}
+
+// The icon (own, or `chevron.backward`) drawn on its background into an image; the history menu stays unless
+// `enableMenu: false`; before iOS 26 the title of the screen below shows, as on the system button.
++ (UIBarButtonItem *)ownButtonOf:(ANNTopBarBackButtonOptions *)backButton
+                           title:(nullable NSString *)title
+                      belowTitle:(nullable NSString *)belowTitle {
+    ANNBackBarButtonItem *item = [ANNBackBarButtonItem new];
+    item.allowsMenu = [backButton.enableMenu withDefault:YES];
+    item.style = UIBarButtonItemStylePlain;
+    BOOL before26 = YES;
+    if (@available(iOS 26.0, *)) {
+        before26 = NO;
+    }
+    item.title = title ?: (before26 ? belowTitle : nil);
+    UIColor *background = [self iconBackgroundColorOf:backButton];
+    if (background) {
+        NSString *symbol = [backButton.sfSymbol withDefault:nil];
+        UIImage *icon = symbol.length > 0 ? [UIImage systemImageNamed:symbol] : nil;
+        icon = icon ?: [backButton.icon withDefault:nil];
+        icon = icon ?: [UIImage systemImageNamed:@"chevron.backward"];
+        Color *color = backButton.color;
+        UIColor *tint =
+            color.hasValue && !color.isNoColor ? [color withDefault:UIColor.tintColor] : nil;
+        ANNIconBackgroundOptions *iconBackground = backButton.iconBackground;
+        item.image = [ANNIconButtonImage
+            imageWithIcon:icon
+                     tint:tint
+               background:background
+             cornerRadius:[iconBackground.cornerRadius withDefault:0]
+                     size:CGSizeMake([iconBackground.width withDefault:0],
+                                     [iconBackground.height withDefault:0])
+                   insets:UIEdgeInsetsZero];
+        if (@available(iOS 26.0, *)) {
+            item.hidesSharedBackground = [backButton.hideSharedBackground withDefault:YES];
+        }
+    }
+    return item;
+}
+
++ (void)rebuildBackButtonOfScreen:(UIViewController *)screen {
+    UIViewController *below = [self entryBelow:screen];
+    if (!below || screen.transitionCoordinator) {
+        return;
+    }
+    UINavigationItem *item = below.navigationItem;
+    UINavigationItemBackButtonDisplayMode mode = item.backButtonDisplayMode;
+    item.backButtonDisplayMode = mode == UINavigationItemBackButtonDisplayModeMinimal
+                                     ? UINavigationItemBackButtonDisplayModeDefault
+                                     : UINavigationItemBackButtonDisplayModeMinimal;
+    item.backButtonDisplayMode = mode;
+}
+
+@end

package/ios/TopBar/ANNBarAppearance.h

@@ -0,0 +1,53 @@
+#import "ANNNavigationOptions.h"
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// What the look of a screen's bar depends on beyond its options: decided by the screen's presenter from its place.
+typedef struct {
+    /// iOS 26, a large title that collapses into the list can show: the edge look is transparent.
+    BOOL transparentEdge;
+    /// A large title that doesn't collapse sits under the row (`always`, or `inline` next to a back button): the bar
+    /// needs a background, `background.color` or else the system blur (`topBar.largeTitle.collapseOnScroll`).
+    BOOL largeTitleNeedsBackground;
+} ANNBarAppearanceContext;
+
+/// The look of a screen's bar (`topBar.background.*`, `.scrollEdgeAppearance.*`, `.noBorder`, `.borderColor`, the
+/// titles' fonts and colors, the back button's look): one builder fills the screen's own two appearances from its
+/// resolved options, whole each time, so the border and the edge survive a merge of the background. The appearances are
+/// the screen's: filled, never replaced.
+@interface ANNBarAppearance : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// Fills `standard` and `scrollEdge` from `options`. `traits` resolve the colors drawn into images (the 1×1
+/// background of iOS 26, in the current style).
++ (void)fillStandard:(UINavigationBarAppearance *)standard
+          scrollEdge:(UINavigationBarAppearance *)scrollEdge
+         withOptions:(ANNNavigationOptions *)options
+             context:(ANNBarAppearanceContext)context
+              traits:(UITraitCollection *)traits;
+
+/// The attributes of the title (`topBar.title`): a font only when a font option is set, over UIKit's font of the
+/// place; the color when set.
++ (NSDictionary<NSAttributedStringKey, id> *)titleAttributesOf:(ANNNavigationOptions *)options;
+
+/// The attributes of the title at the scroll edge: `scrollEdgeAppearance.title` when set, else the title's.
++ (NSDictionary<NSAttributedStringKey, id> *)scrollEdgeTitleAttributesOf:
+    (ANNNavigationOptions *)options;
+
+/// The color of the title for the push of iOS 26: the title's (or the edge title's) color resolved for `traits`, else
+/// the label color resolved; a fixed color that doesn't follow the glass.
++ (UIColor *)pinnedTitleColor:(nullable Color *)color traits:(UITraitCollection *)traits;
+
+/// `background.color` as a solid fill of the bar: nil without a color, for "no color" and for a color clear in `traits`
+/// (a clear color is a clear bar). The one rule for the bar, its color in the list and the top edge effect.
++ (nullable UIColor *)solidColorOf:(nullable Color *)color traits:(UITraitCollection *)traits;
+
+/// A 1×1 image of `color` resolved for `traits`.
++ (UIImage *)imageOfColor:(UIColor *)color traits:(UITraitCollection *)traits;
+
+@end
+
+NS_ASSUME_NONNULL_END