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

package/ios/Layouts/Modal/ANNModalPresentation.mm

@@ -118,21 +118,21 @@ static NSDictionary<NSString *, NSNumber *> *ANNTransitionStyles(void) {
     return nil;
 }
 
-// UIKit takes `partialCurl` only for a full-screen modal over a controller that fills the screen, and a controller
-// shown with `partialCurl` presents nothing more: the command rejects before it asks UIKit.
-- (NSString *)problemPresentingFrom:(UIViewController *)presenting
-                         windowRoot:(UIViewController *)windowRoot {
+// UIKit curls only a full-screen modal over a controller that fills the screen: elsewhere `partialCurl` is
+// `coverVertical`, so the modal still shows. A controller shown with `partialCurl` presents nothing more: the command
+// rejects before it asks UIKit.
+- (NSString *)fitToPresenting:(UIViewController *)presenting
+                   windowRoot:(UIViewController *)windowRoot {
     if (presenting.presentingViewController &&
         presenting.modalTransitionStyle == UIModalTransitionStylePartialCurl) {
-        return @"partialCurl needs a full screen modal";
+        return @"a modal shown with partialCurl can't show another modal";
     }
-    if (_transitionStyle != UIModalTransitionStylePartialCurl) {
-        return nil;
-    }
-    BOOL presentingFills = presenting == windowRoot ||
-                           presenting.modalPresentationStyle == UIModalPresentationFullScreen;
-    if (_style != UIModalPresentationFullScreen || !presentingFills) {
-        return @"partialCurl needs a full screen modal";
+    if (_transitionStyle == UIModalTransitionStylePartialCurl) {
+        BOOL presentingFills = presenting == windowRoot ||
+                               presenting.modalPresentationStyle == UIModalPresentationFullScreen;
+        if (_style != UIModalPresentationFullScreen || !presentingFills) {
+            _transitionStyle = UIModalTransitionStyleCoverVertical;
+        }
     }
     return nil;
 }

package/ios/Layouts/Modal/ANNSheetPresenter.mm

@@ -1,6 +1,7 @@
 #import "ANNSheetPresenter.h"
 #import "ANNModalSizePresenter.h"
 #import "ANNReactView.h"
+#import "ANNUtils.h"
 #import "UIViewController+LayoutProtocol.h"
 #import <React/RCTLog.h>
 #import <objc/runtime.h>
@@ -53,7 +54,7 @@ static NSString *const ANNContentDetent = @"content";
 + (void)applyOptions:(ANNSheetOptions *)options toSheet:(UISheetPresentationController *)sheet {
     if (options.detents) {
         NSMutableArray<UISheetPresentationControllerDetent *> *detents = [NSMutableArray new];
-        for (id value in options.detents) {
+        for (id value in [self sortedDetents:options.detents ofSheet:sheet]) {
             UISheetPresentationControllerDetent *detent = [self detentFor:value ofSheet:sheet];
             if (detent) {
                 [detents addObject:detent];
@@ -81,6 +82,85 @@ static NSString *const ANNContentDetent = @"content";
     }
 }
 
+// UIKit wants the detents once each, from the lowest to the highest: it takes the last for the largest and closes the
+// sheet on a drag down from the first. The options may give them in any order and more than once; the first of a
+// repeat stays, and detents of the same height keep their order.
++ (NSArray *)sortedDetents:(NSArray *)values ofSheet:(UISheetPresentationController *)sheet {
+    NSMutableArray *detents = [NSMutableArray new];
+    NSMutableSet<NSString *> *identifiers = [NSMutableSet new];
+    for (id value in values) {
+        NSString *identifier = [self identifierFor:value];
+        if (identifier && ![identifiers containsObject:identifier]) {
+            [identifiers addObject:identifier];
+            [detents addObject:value];
+        }
+    }
+    CGFloat maximum = [self maximumDetentHeightOf:sheet];
+    return [detents sortedArrayWithOptions:NSSortStable
+                           usingComparator:^NSComparisonResult(id a, id b) {
+                             return [self compareHeightOf:a
+                                                     with:b
+                                                  maximum:maximum
+                                                  ofSheet:sheet];
+                           }];
+}
+
+// The content of a sheet sized to it changed its height, and with it maybe its place among the other detents.
++ (void)sortDetentsOfSheet:(UISheetPresentationController *)sheet API_AVAILABLE(ios(16.0)) {
+    CGFloat maximum = [self maximumDetentHeightOf:sheet];
+    NSArray<UISheetPresentationControllerDetent *> *detents = sheet.detents;
+    NSArray<UISheetPresentationControllerDetent *> *sorted = [detents
+        sortedArrayWithOptions:NSSortStable
+               usingComparator:^NSComparisonResult(UISheetPresentationControllerDetent *a,
+                                                   UISheetPresentationControllerDetent *b) {
+                 return [self compareHeightOf:[self detentForIdentifier:a.identifier]
+                                         with:[self detentForIdentifier:b.identifier]
+                                      maximum:maximum
+                                      ofSheet:sheet];
+               }];
+    if (![sorted isEqualToArray:detents]) {
+        sheet.detents = sorted;
+    }
+}
+
++ (NSComparisonResult)compareHeightOf:(id)a
+                                 with:(id)b
+                              maximum:(CGFloat)maximum
+                              ofSheet:(UISheetPresentationController *)sheet {
+    CGFloat heightA = [self heightOf:a maximum:maximum ofSheet:sheet];
+    CGFloat heightB = [self heightOf:b maximum:maximum ofSheet:sheet];
+    return heightA < heightB ? NSOrderedAscending
+                             : heightA > heightB ? NSOrderedDescending : NSOrderedSame;
+}
+
+// The height a detent of the options stands at, to sort them, as its resolver gives it: 'medium' half of the largest
+// height (UIKit's is about half), 'large' all of it, a height capped at it, 'content' the content's height now, all of
+// it while the content isn't measured.
++ (CGFloat)heightOf:(id)value
+            maximum:(CGFloat)maximum
+            ofSheet:(UISheetPresentationController *)sheet {
+    if ([value isEqual:@"medium"]) {
+        return maximum / 2;
+    }
+    if ([value isKindOfClass:NSNumber.class]) {
+        return MIN([value doubleValue], maximum);
+    }
+    if ([value isEqual:ANNContentDetent]) {
+        CGFloat height = [self contentHeightOf:sheet.presentedViewController];
+        return height > 0 ? MIN(height, maximum) : maximum;
+    }
+    return maximum;
+}
+
+// About the largest height of a sheet: its container, or the window before it is shown, below the top safe area.
++ (CGFloat)maximumDetentHeightOf:(UISheetPresentationController *)sheet {
+    UIView *view = sheet.containerView ?: ANNUtils.mainWindow;
+    if (!view) {
+        return ANNUtils.mainScreen.bounds.size.height;
+    }
+    return view.bounds.size.height - view.safeAreaInsets.top;
+}
+
 + (UISheetPresentationControllerDetent *)detentFor:(id)value
                                            ofSheet:(UISheetPresentationController *)sheet {
     if ([value isEqual:@"medium"]) {
@@ -180,6 +260,7 @@ static NSString *const ANNContentDetent = @"content";
               }
               height = newHeight;
               [strongSheet animateChanges:^{
+                [self sortDetentsOfSheet:strongSheet];
                 [strongSheet invalidateDetents];
               }];
             }
@@ -201,6 +282,7 @@ static NSString *const ANNContentDetent = @"content";
             // The new screen's content mounts may come later: its mounts resolve the detents again too.
             [self followContentOfSheet:sheet when:YES];
             [sheet animateChanges:^{
+              [self sortDetentsOfSheet:sheet];
               [sheet invalidateDetents];
             }];
         }

package/ios/Layouts/Root/ANNRootCoordinator.mm

@@ -69,7 +69,10 @@ typedef NS_ENUM(NSInteger, ANNRootShowState) {
 // The nodes whose appearance the transition reports itself (`driveAppearanceOf:`), while `driving`.
 @property(nonatomic, copy) NSArray<UIViewController *> *driven;
 @property(nonatomic) BOOL driving;
+// The snapshot of the window as it was: it dissolves over the new root (`dissolves`), plays its `exit` (`custom`), or
+// only covers the old root's modals while they go, and leaves as the new root is the window's.
 @property(nonatomic, strong, nullable) UIView *snapshot;
+@property(nonatomic) BOOL dissolves;
 // The root is the window's root: the old root's modals went before it (`startTransitionOf:done:`).
 @property(nonatomic) BOOL installed;
 // The root's view waits in the window under the current root (`park:`).
@@ -415,9 +418,14 @@ static __weak ANNRootShow *ANNAnimatingShow;
     BOOL seen = !window.hidden && scene != nil &&
                 scene.activationState != UISceneActivationStateBackground;
     BOOL dissolves = !overSplash && !enterDisabled && !custom && seen;
+    show.dissolves = dissolves;
     show.custom = custom && seen;
-    UIView *snapshot =
-        dissolves || show.custom ? [window snapshotViewAfterScreenUpdates:NO] : nil;
+    // UIKit draws the dismissal of the old root's modals, without animation too (a sheet's dim goes a frame before
+    // its card): with nothing to dissolve, the snapshot covers them until the new root is in place.
+    BOOL covers = seen && old.presentedViewController != nil;
+    UIView *snapshot = dissolves || show.custom || covers
+                           ? [window snapshotViewAfterScreenUpdates:NO]
+                           : nil;
 
     show.state = ANNRootShowStateTransition;
     // It shows from here: a stack in it counts as on screen.
@@ -480,7 +488,8 @@ static __weak ANNRootShow *ANNAnimatingShow;
         [self endTransitionOf:show];
         return;
     }
-    if (!snapshot) {
+    // A snapshot that only covered the old root's modals leaves in this turn, with the new root in place under it.
+    if (!snapshot || !show.dissolves) {
         [self endTransitionOf:show];
         return;
     }

package/ios/Layouts/Screen/ANNComponentPresenter.h

@@ -19,11 +19,19 @@ NS_ASSUME_NONNULL_BEGIN
 /// it. Nothing before the screen's view is loaded.
 - (void)applyBackground:(ANNNavigationOptions *)resolvedOptions;
 
-/// `statusBar.blur` (iOS): UIKit's regular blur over the screen's own view in the frame of the scene's status bar at
-/// this moment (x 0, the view's width; it doesn't follow a rotation); `false` or none removes it. At each appearance
-/// and at a merge that names it; nothing before the screen's view is loaded.
+/// `statusBar.blur` (iOS): UIKit's regular blur over the screen's own view in the frame of the scene's status bar (x 0,
+/// the view's width), laid out at once; `false` or none removes it. At each appearance and at a merge that names it;
+/// nothing before the screen's view is loaded.
 - (void)applyStatusBarBlur:(ANNNavigationOptions *)resolvedOptions;
 
+/// The blur takes the status bar's frame as it is now; nothing without a blur. The single place of its frame: the blur
+/// as it is applied, the screen's view laid out (a rotation, a new window size, a new safe area), a size transition
+/// along its animation and at its end, the turn after new traits, and `statusBarDidChange`.
+- (void)layOutStatusBarBlur;
+
+/// The status bar was asked again (hidden or shown, a new style): every blur takes its frame.
++ (void)statusBarDidChange;
+
 /// The blur stays the last subview of the screen's view: the content added after it goes under it.
 - (void)keepStatusBarBlurOnTop;
 

package/ios/Layouts/Screen/ANNComponentPresenter.mm

@@ -5,6 +5,10 @@
 #import "ANNTopBarPresenter.h"
 #import "ANNUtils.h"
 
+// The presenters whose screen shows `statusBar.blur`: the status bar hidden or shown lays out no view, so they hear of
+// it from the system UI (`statusBarDidChange`).
+static NSHashTable<ANNComponentPresenter *> *ANNBlurringPresenters;
+
 @implementation ANNComponentPresenter {
     // `statusBar.blur` while it is on.
     UIVisualEffectView *_statusBarBlur;
@@ -95,9 +99,7 @@
 
 #pragma mark - The status bar's blur (`statusBar.blur`)
 
-// Over the screen's own view, never over a React view; no touches, nothing for VoiceOver. The frame is the scene's
-// status bar's as it is now, in the view's own coordinates without a conversion: a pushed screen's view may still be
-// out of place while it appears.
+// Over the screen's own view, never over a React view; no touches, nothing for VoiceOver.
 - (void)applyStatusBarBlur:(ANNNavigationOptions *)resolvedOptions {
     ANNComponentViewController *screen = self.screen;
     if (!screen.isViewLoaded) {
@@ -106,6 +108,7 @@
     if (![resolvedOptions.statusBar.blur withDefault:NO]) {
         [_statusBarBlur removeFromSuperview];
         _statusBarBlur = nil;
+        [ANNBlurringPresenters removeObject:self];
         return;
     }
     UIView *view = screen.view;
@@ -115,15 +118,40 @@
         _statusBarBlur.userInteractionEnabled = NO;
         _statusBarBlur.isAccessibilityElement = NO;
         _statusBarBlur.accessibilityElementsHidden = YES;
+        if (!ANNBlurringPresenters) {
+            ANNBlurringPresenters = [NSHashTable weakObjectsHashTable];
+        }
+        [ANNBlurringPresenters addObject:self];
     }
-    CGRect statusBar = ANNUtils.statusBarFrame;
-    _statusBarBlur.frame = CGRectMake(0, CGRectGetMinY(statusBar), CGRectGetWidth(view.bounds),
-                                      CGRectGetHeight(statusBar));
     if (_statusBarBlur.superview != view) {
         [view addSubview:_statusBarBlur];
     } else {
         [view bringSubviewToFront:_statusBarBlur];
     }
+    [self layOutStatusBarBlur];
+}
+
+// The status bar's frame in the scene of the screen's window (the main window's before the screen is in one), in the
+// view's own coordinates without a conversion: a pushed screen's view may still be out of place while it appears. A
+// hidden status bar has no frame, and the blur no height.
+- (void)layOutStatusBarBlur {
+    UIView *view = _statusBarBlur.superview;
+    if (!view) {
+        return;
+    }
+    UIWindowScene *scene = view.window.windowScene;
+    CGRect statusBar = scene ? scene.statusBarManager.statusBarFrame : ANNUtils.statusBarFrame;
+    CGRect frame = CGRectMake(0, CGRectGetMinY(statusBar), CGRectGetWidth(view.bounds),
+                              CGRectGetHeight(statusBar));
+    if (!CGRectEqualToRect(_statusBarBlur.frame, frame)) {
+        _statusBarBlur.frame = frame;
+    }
+}
+
++ (void)statusBarDidChange {
+    for (ANNComponentPresenter *presenter in ANNBlurringPresenters.allObjects) {
+        [presenter layOutStatusBarBlur];
+    }
 }
 
 - (void)keepStatusBarBlurOnTop {

package/ios/Layouts/Screen/ANNComponentViewController.mm

@@ -3,6 +3,7 @@
 #import "ANNArrangementState.h"
 #import "ANNBottomTabsController.h"
 #import "ANNComponentPresenter.h"
+#import "ANNEventContract.h"
 #import "ANNHinge.h"
 #import "ANNKeyCommands.h"
 #import "ANNNodeRegistry.h"
@@ -66,6 +67,12 @@
 
 #pragma mark - The view
 
+- (nullable ANNComponentPresenter *)componentPresenter {
+    ANNNodePresenter *presenter = self.presenter;
+    return [presenter isKindOfClass:ANNComponentPresenter.class] ? (ANNComponentPresenter *)presenter
+                                                                  : nil;
+}
+
 // The size of the screen of the navigation window's scene, not the deprecated main screen: a surface made before the
 // screen is in a window starts with the width it will have.
 - (void)loadView {
@@ -94,6 +101,22 @@
     }
     // The pair the screen is in may lie otherwise now.
     [self.arrangement screenDidChangeLayout:self];
+    [self.componentPresenter layOutStatusBarBlur];
+}
+
+// UIKit names the size transition as the moment the status bar's frame changes (a rotation, a new window size): the
+// blur follows it along the animation and takes the final frame at its end.
+- (void)viewWillTransitionToSize:(CGSize)size
+       withTransitionCoordinator:(id<UIViewControllerTransitionCoordinator>)coordinator {
+    [super viewWillTransitionToSize:size withTransitionCoordinator:coordinator];
+    __weak ANNComponentViewController *weakSelf = self;
+    [coordinator
+        animateAlongsideTransition:^(id<UIViewControllerTransitionCoordinatorContext> context) {
+          [weakSelf.componentPresenter layOutStatusBarBlur];
+        }
+        completion:^(id<UIViewControllerTransitionCoordinatorContext> context) {
+          [weakSelf.componentPresenter layOutStatusBarBlur];
+        }];
 }
 
 - (void)viewSafeAreaInsetsDidChange {
@@ -110,6 +133,7 @@
     __weak ANNComponentViewController *weakSelf = self;
     dispatch_async(dispatch_get_main_queue(), ^{
       [weakSelf updateRootLayout];
+      [weakSelf.componentPresenter layOutStatusBarBlur];
     });
 }
 
@@ -200,9 +224,7 @@
 #pragma mark - The root frame and the safe area
 
 - (void)applyBackground {
-    if ([self.presenter isKindOfClass:ANNComponentPresenter.class]) {
-        [(ANNComponentPresenter *)self.presenter applyBackground:[self resolveOptionsWithDefault]];
-    }
+    [self.componentPresenter applyBackground:[self resolveOptionsWithDefault]];
 }
 
 // The navigation controller that shows the screen's stack: the stack, or UIKit's More navigation while a tab of More
@@ -434,7 +456,8 @@
     if (!regions) {
         return;
     }
-    BOOL empty = [regions[@"division"] count] == 0 && [regions[@"occlusion"] count] == 0;
+    const auto &keys = ANNEventContract.ScreenRegionsChanged;
+    BOOL empty = [regions[keys.division] count] == 0 && [regions[keys.occlusion] count] == 0;
     if (empty && ![ANNScreenRegions regionsForScreenId:componentId]) {
         return;
     }
@@ -606,9 +629,7 @@
     content.autoresizingMask = UIViewAutoresizingNone;
     content.frame = [self rootFrameForOptions:[self resolveOptionsWithDefault]];
     [view addSubview:content];
-    if ([self.presenter isKindOfClass:ANNComponentPresenter.class]) {
-        [(ANNComponentPresenter *)self.presenter keepStatusBarBlurOnTop];
-    }
+    [self.componentPresenter keepStatusBarBlurOnTop];
     [self applyBackground];
     [self updateRootLayout];
 }

package/ios/Layouts/Screen/ANNNativeScreenContext.mm

@@ -1,5 +1,6 @@
 #import "ANNNativeScreenContext+Internal.h"
 #import "ANNErrorTexts.h"
+#import "ANNEventContract.h"
 #import "ANNEventEmitter.h"
 #import "ANNNativeScreenCalls.h"
 #import <React/RCTUtils.h>
@@ -71,12 +72,13 @@
                                                                  componentId:self->_componentId]];
           return;
       }
+      const auto &keys = ANNEventContract.NativeScreenCall;
       [eventEmitter sendNativeScreenCall:@{
-          @"componentId" : self->_componentId,
-          @"callId" : callId,
-          @"kind" : kind,
-          @"name" : name,
-          @"args" : arguments ?: @[],
+          keys.componentId : self->_componentId,
+          keys.callId : callId,
+          keys.kind : kind,
+          keys.name : name,
+          keys.args : arguments ?: @[],
       }];
     });
 }

package/ios/Layouts/Screen/ANNScreenInsets.mm

@@ -1,4 +1,5 @@
 #import "ANNScreenInsets.h"
+#import "ANNEventContract.h"
 
 NSNotificationName const ANNScreenSafeAreaPaddingDidChangeNotification = @"ANNScreenSafeAreaPaddingDidChange";
 
@@ -26,11 +27,12 @@ static NSMutableDictionary<NSString *, NSValue *> *ANNScreenPaddingById;
                                                           object:screenId];
     }
     // JavaScript gets what still covers the content: the edges the safe area view keeps it off are 0.
+    const auto &keys = ANNEventContract.ScreenInsetsChanged;
     NSDictionary<NSString *, NSNumber *> *value = @{
-        @"top" : @(MAX(insets.top - padding.top, 0)),
-        @"right" : @(MAX(insets.right - padding.right, 0)),
-        @"bottom" : @(MAX(insets.bottom - padding.bottom, 0)),
-        @"left" : @(MAX(insets.left - padding.left, 0)),
+        keys.top : @(MAX(insets.top - padding.top, 0)),
+        keys.right : @(MAX(insets.right - padding.right, 0)),
+        keys.bottom : @(MAX(insets.bottom - padding.bottom, 0)),
+        keys.left : @(MAX(insets.left - padding.left, 0)),
     };
     @synchronized(ANNScreenInsetsById) {
         if ([ANNScreenInsetsById[screenId] isEqualToDictionary:value]) {

package/ios/Layouts/Screen/ANNScreenRegions.mm

@@ -1,4 +1,5 @@
 #import "ANNScreenRegions.h"
+#import "ANNEventContract.h"
 
 static NSMutableDictionary<NSString *, NSDictionary<NSString *, NSArray *> *> *ANNScreenRegionsById;
 
@@ -36,11 +37,12 @@ ANNRegionRects(NSArray<UIViewReservedRegion *> *regions, UIView *view, UIView *c
         if (CGRectIsNull(frame)) {
             continue;
         }
+        const auto &keys = ANNEventContract.ScreenRegionRect;
         [rects addObject:@{
-            @"x" : @(frame.origin.x),
-            @"y" : @(frame.origin.y),
-            @"width" : @(frame.size.width),
-            @"height" : @(frame.size.height),
+            keys.x : @(frame.origin.x),
+            keys.y : @(frame.origin.y),
+            keys.width : @(frame.size.width),
+            keys.height : @(frame.size.height),
         }];
     }
     return rects;
@@ -63,9 +65,10 @@ ANNRegionRects(NSArray<UIViewReservedRegion *> *regions, UIView *view, UIView *c
             [view reservedRegionsOfKind:[UIViewReservedRegionKind divisionRegionKind]];
         NSArray<UIViewReservedRegion *> *occlusion =
             [view reservedRegionsOfKind:[UIViewReservedRegionKind occlusionRegionKind]];
+        const auto &keys = ANNEventContract.ScreenRegionsChanged;
         return @{
-            @"division" : ANNRegionRects(division, view, coordinateView),
-            @"occlusion" : ANNRegionRects(occlusion, view, coordinateView),
+            keys.division : ANNRegionRects(division, view, coordinateView),
+            keys.occlusion : ANNRegionRects(occlusion, view, coordinateView),
         };
     }
 #endif

package/ios/Layouts/SplitView/ANNSplitViewController.mm

@@ -1,5 +1,6 @@
 #import "ANNSplitViewController.h"
 #import "ANNErrorHandler.h"
+#import "ANNErrorTexts.h"
 #import "ANNShownScreens.h"
 #import "UISplitViewController+ANNOptions.h"
 #import "UIViewController+LayoutProtocol.h"
@@ -213,19 +214,15 @@ static UISplitViewControllerColumn ANNSplitViewColumn(NSString *name) {
             completion:(ANNTransitionCompletionBlock)completion
              rejection:(ANNTransitionRejectionBlock)rejection {
     UIViewController *previous = _columns[column];
+    NSString *fromId = fromViewController.layoutInfo.componentId;
     if (!previous) {
-        rejection([NSString stringWithFormat:@"the split view of the screen '%@' has no '%@' column",
-                                             fromViewController.layoutInfo.componentId, column],
-                  nil);
+        rejection([ANNErrorTexts noSuchColumn:fromId column:column], nil);
         return;
     }
     if ([previous isKindOfClass:UINavigationController.class]) {
         // UIKit does not take a navigation controller among the screens of another.
         if ([screen isKindOfClass:UINavigationController.class]) {
-            rejection([NSString stringWithFormat:@"the '%@' column of the split view of the screen '%@' is a "
-                                                 @"stack: it takes a screen, not a stack",
-                                                 column, fromViewController.layoutInfo.componentId],
-                      nil);
+            rejection([ANNErrorTexts columnIsStack:fromId column:column], nil);
             return;
         }
         // In place, as a column of UIKit apps changes; UIKit animates a column it brings on top.

package/ios/Options/ANNSheetOptions.h

@@ -7,7 +7,10 @@
  */
 @interface ANNSheetOptions : ANNOptions
 
-/** The detents as the options give them: NSString ('medium', 'large', 'content') or NSNumber. */
+/**
+ * The detents as the options give them, in any order and with repeats: NSString ('medium', 'large', 'content') or
+ * NSNumber. ANNSheetPresenter sorts them and drops the repeats.
+ */
 @property(nonatomic, strong) NSArray *detents;
 @property(nonatomic, strong) Param *selectedDetent;
 /** The largest detent the screen below stays undimmed and touchable at. */

package/ios/Public/ApexNavigation/ANNSceneDelegate.h

@@ -9,6 +9,9 @@ NS_ASSUME_NONNULL_BEGIN
  * When the scene connects, the navigation window moves into it. URLs, user activities and foreground/background
  * changes that UIKit now delivers to the scene are forwarded to the app delegate's usual methods, so
  * the deep links (`dispatchDeepLinkURL:`) and app delegate overrides keep working.
+ *
+ * The app's own scene delegate can extend it (`class SceneDelegate: ANNSceneDelegate {}`, which `setup` makes of React
+ * Native 0.88's template); a method it overrides calls `super`.
  */
 @interface ANNSceneDelegate : UIResponder <UIWindowSceneDelegate>
 

package/ios/RECIPES.md

@@ -34,7 +34,8 @@ you do exactly that; the map is `ios/CLAUDE.md`.
 4. **The layout check:** a new node type goes into `ANNLayoutType` and `ANNLayoutReader` (its place, its children), and
    gets a maker in `ANNLayoutFactory`.
 5. **Error texts** come from `ANNErrorTexts`, one sentence per case, the same as Android; a text deep in a maker is
-   thrown with `+[ANNErrorTexts rejection:]`.
+   thrown with `+[ANNErrorTexts rejection:]`. A new text goes into `src/interfaces/contract/errors.json`, and
+   `node scripts/contract.mjs` makes `ANNErrorTexts` (and Android's `ErrorTexts`) from it; never edit them by hand.
 6. **The answer:** end through `ANNAppearanceDispatcher` (`endTransitionHiding:…answer:value:`) or call
    `-[ANNCommandAnswer resolve:]`; the state and `ANN.CommandCompleted` follow by themselves for the names in
    `ANNCompletedCommandNames`. Add the name there when the command shows or dismisses.

package/ios/TurboModules/ANNTurboEventEmitter.mm

@@ -1,5 +1,6 @@
 #import "ANNTurboEventEmitter.h"
 #import "ANNAssert.h"
+#import "ANNEventContract.h"
 #import "ANNEventEmitter.h"
 #import "ANNReloadCoordinator.h"
 #import <React/RCTUtils.h>
@@ -40,41 +41,9 @@ RCT_EXPORT_MODULE(ANNTurboEventEmitter)
     return self;
 }
 
-// Every event of the navigation and of the modules.
+// Every event of the navigation and of the modules, as the types of `src/interfaces/` name them.
 - (NSArray<NSString *> *)supportedEvents {
-    return @[
-        @"ANN.AppLaunched",
-        @"ANN.ArrangementChanged",
-        @"ANN.BottomAccessoryPlacementChanged",
-        @"ANN.BottomTabLongPressed",
-        @"ANN.BottomTabPressed",
-        @"ANN.BottomTabSelected",
-        @"ANN.CommandCompleted",
-        @"ANN.ComponentDidAppear",
-        @"ANN.ComponentDidDisappear",
-        @"ANN.ComponentWillAppear",
-        @"ANN.HingeChanged",
-        @"ANN.KeyCommandPressed",
-        @"ANN.ModalAttemptedToDismiss",
-        @"ANN.ModalDismissed",
-        @"ANN.NativeScreenCall",
-        @"ANN.NativeScreenReleased",
-        @"ANN.NavigationButtonPressed",
-        @"ANN.NavigationStateChanged",
-        @"ANN.PreviewCompleted",
-        @"ANN.ScreenInsetsChanged",
-        @"ANN.ScreenPopped",
-        @"ANN.ScreenRegionsChanged",
-        @"ANN.SearchBarCancelPressed",
-        @"ANN.SearchBarSubmitted",
-        @"ANN.SearchBarUpdated",
-        @"ANN.SearchSuggestionPicked",
-        @"ANN.SheetDetentChanged",
-        @"ANN.SlotDestroyed",
-        @"ANN.SplitViewColumnsStacked",
-        @"ANN.SplitViewDisplayModeChanged",
-        @"ANN.TitleRenamed",
-    ];
+    return ANNEventContractNames();
 }
 
 #pragma mark - Listeners
@@ -99,7 +68,7 @@ RCT_EXPORT_MODULE(ANNTurboEventEmitter)
 
 - (void)addListener:(NSString *)eventName {
     [super addListener:eventName];
-    if ([eventName isEqualToString:@"ANN.AppLaunched"] && !_listensToAppLaunched) {
+    if ([eventName isEqualToString:ANNEventContract.AppLaunched.event] && !_listensToAppLaunched) {
         _listensToAppLaunched = YES;
         [ANNEventEmitter eventEmitterListensToAppLaunched:self];
     }

package/ios/TurboModules/ANNTurboModule.mm

@@ -5,7 +5,9 @@
 #import "ANNComponentViewController.h"
 #import "ANNDeepLinkQueue.h"
 #import "ANNDefaultOptions.h"
+#import "ANNErrorHandler.h"
 #import "ANNErrorTexts.h"
+#import "ANNEventContract.h"
 #import "ANNExternalViewController.h"
 #import "ANNHinge.h"
 #import "ANNLayoutReader.h"
@@ -248,7 +250,7 @@ RCT_EXPORT_MODULE(ANNTurboModule)
              layout:(NSDictionary *)layout
             resolve:(RCTPromiseResolveBlock)resolve
              reject:(RCTPromiseRejectBlock)reject {
-    resolve(nil);
+    [ANNErrorHandler resolve:resolve of:@"preparePush" value:nil];
 }
 
 - (void)cancelPreparedPush:(NSString *)componentId {
@@ -511,7 +513,8 @@ RCT_EXPORT_MODULE(ANNTurboModule)
 
 - (NSDictionary *)getScreenRegions:(NSString *)componentId {
     NSDictionary *regions = [ANNScreenRegions regionsForScreenId:componentId];
-    return regions ?: @{@"division" : @[], @"occlusion" : @[]};
+    const auto &keys = ANNEventContract.ScreenRegionsChanged;
+    return regions ?: @{keys.division : @[], keys.occlusion : @[]};
 }
 
 // `setHingeUpdates`: JavaScript counts its `useHinge` hooks; the events go with the emitter of the JavaScript that runs

package/lib/module/ARCHITECTURE.md

@@ -63,7 +63,8 @@ form of `src/api/events/navigationEvents.ts`. Everything in `src/engine` is inte
   `LinkParams`, `PendingLink`, …). `linkPaths.ts`: a URL into its path and query (`parseLink`), the patterns ordered
   (`compileRoutes`) and matched (`matchLink`). `linking.ts`: the links of the app — the launch link, the `url` events
   of React Native's `Linking`, the routes run, the pending link opened after `setContext`. `pendingLinks.ts`: the one
-  waiting link and its listeners, which `navigation` and `usePendingLink` read.
+  waiting link and its listeners, which `navigation` and `usePendingLink` read. `dispatchedLinks.ts` (iOS): hands
+  `Linking` the links of `ANN.DeepLinkDispatched`.
 - `events/` — `navigationEvents.ts`: the events by name, the native event behind each, `onNavigationEvent`,
   `listeners`. `screenLifecycle.ts`: what goes when a screen unmounts, `whenScreenUnmounts`. `tabPresses.ts`: the
   handlers of `useTabPress`.
@@ -268,7 +269,9 @@ its push, which the hook ignores.
   given once; JS asks only with `linking`) and `getStartInfo` (synchronous: `coldStart`, true for the whole life of
   the first JavaScript runtime of the process, and `splashLogo`, the size of the native splash's logo the CLI wrote,
   or null; `arrangements`, whether it shows pairs). The links that come while the app runs reach JS through React Native's
-  `Linking`, not through `ANN.*` events.
+  `Linking`, not through `ANN.*` events. One exception, iOS only: a link the app dispatched (`dispatchDeepLinkURL`) that
+  `Linking` doesn't take from the native side (React Native 0.88 and newer, with a scene delegate) comes as
+  `ANN.DeepLinkDispatched`, and `src/api/linking/dispatchedLinks.ts` hands it to `Linking` as a `url` event.
 - Events: `ANN.AppLaunched`, `ANN.ComponentWillAppear`, `ANN.ComponentDidAppear`, `ANN.ComponentDidDisappear`,
   `ANN.NavigationButtonPressed`, `ANN.BottomTabSelected`, `ANN.BottomTabPressed`, `ANN.BottomTabLongPressed`,
   `ANN.ModalDismissed`, `ANN.ModalAttemptedToDismiss`, `ANN.ScreenPopped`, `ANN.SearchBarUpdated`,
@@ -276,8 +279,8 @@ its push, which the hook ignores.
   `ANN.NavigationStateChanged`, `ANN.SlotDestroyed`, `ANN.ScreenInsetsChanged`, `ANN.TitleRenamed`,
   `ANN.BottomAccessoryPlacementChanged`, `ANN.SheetDetentChanged`, `ANN.SplitViewDisplayModeChanged`,
   `ANN.KeyCommandPressed`, `ANN.NativeScreenCall`, `ANN.NativeScreenReleased`, `ANN.ScreenRegionsChanged`,
-  `ANN.ArrangementChanged`, `ANN.HingeChanged`, `ANN.SplitViewColumnsStacked`. Their payloads are typed in
-  `src/interfaces/ComponentEvents.ts` and `Events.ts`. Both platforms also send `ANN.CommandCompleted`
+  `ANN.ArrangementChanged`, `ANN.HingeChanged`, `ANN.SplitViewColumnsStacked`, `ANN.DeepLinkDispatched` (iOS). Their
+  payloads are typed in `src/interfaces/ComponentEvents.ts` and `Events.ts`. Both platforms also send `ANN.CommandCompleted`
   (`CommandCompletedEvent`), which nothing in JS listens to.
 - Native components: `ANNSlot` (`src/api/slots`) and `ANNSafeAreaView` (`src/api/safeArea`), with C++ of their own in
   `ios/cpp`, which Android builds too (their states hold a size and a padding; the first one comes from the props