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

package/ios/Layouts/Screen/ANNScreenEnvironment.h

@@ -0,0 +1,63 @@
+#import "ANNEventEmitter.h"
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// A view that keeps a screen's content out of its padding (the screen's safe area view).
+@protocol ANNScreenPaddingListener <NSObject>
+/// The padding of its screen changed. Main queue.
+- (void)screenPaddingDidChange;
+@end
+
+/// What JavaScript knows of each screen's place, by the screen's id, in one record: its safe area (the insets
+/// JavaScript gets, `useSafeAreaInsets`, and the padding of its safe area view), its reserved regions
+/// (`useReservedRegions`) and, in a pair, its arrangement (`useArrangement`). The core measures them
+/// (`ANNScreenSafeArea`, `ANNScreenRegions`, the pair's layout) on the main queue and keeps them here; JavaScript reads
+/// them from its own thread for a screen's first render, under one lock, and gets every change as an event. When the
+/// screen goes, `removeScreenId:` clears all of it. As on Android (`ScreenEnvironment`).
+@interface ANNScreenEnvironment : NSObject
+
+/// Keeps the screen's insets and the padding of its safe area view. The padding is the part of the insets the safe
+/// area view keeps the content out of (the edges the screen's options give); JavaScript gets the rest, what still
+/// covers the content (0 on a padded edge). Tells the padding's listeners of that screen when the padding changed, then
+/// JavaScript (`ANN.ScreenInsetsChanged`) when its insets did. Main queue.
++ (void)setInsets:(UIEdgeInsets)insets
+          padding:(UIEdgeInsets)padding
+      forScreenId:(NSString *)screenId
+     eventEmitter:(ANNEventEmitter *)eventEmitter;
+/// The padding of the screen's safe area view; none before the screen was laid out. Any thread.
++ (UIEdgeInsets)paddingForScreenId:(NSString *)screenId;
+/// `{ top, right, bottom, left }`, or nil before the screen was laid out. Any thread.
++ (nullable NSDictionary<NSString *, NSNumber *> *)insetsForScreenId:(NSString *)screenId;
+
+/// Keeps the screen's regions (`{ division, occlusion }`) and tells JavaScript (`ANN.ScreenRegionsChanged`) when they
+/// changed. None at first is what JavaScript reads before the first layout: it is neither kept nor told. Main queue.
++ (void)setRegions:(NSDictionary<NSString *, NSArray *> *)regions
+       forScreenId:(NSString *)screenId
+      eventEmitter:(ANNEventEmitter *)eventEmitter;
+/// `{ division, occlusion }`, or nil before the screen's regions were first kept. Any thread.
++ (nullable NSDictionary<NSString *, NSArray *> *)regionsForScreenId:(NSString *)screenId;
+
+/// Keeps the screen's arrangement (`{ placement, layout, front, hidden }`) and tells JavaScript
+/// (`ANN.ArrangementChanged`) when it changed; nothing goes without an emitter. Main queue.
++ (void)setArrangement:(NSDictionary<NSString *, id> *)arrangement
+           forScreenId:(NSString *)screenId
+          eventEmitter:(nullable ANNEventEmitter *)eventEmitter;
+/// The screen's arrangement, or nil for a screen outside a pair. Any thread.
++ (nullable NSDictionary<NSString *, id> *)arrangementForScreenId:(NSString *)screenId;
+
+/// Tells `listener` of each change of the screen's padding, until it is removed or goes (held weakly). Several
+/// listeners may listen to one screen. Main queue.
++ (void)addPaddingListener:(id<ANNScreenPaddingListener>)listener forScreenId:(NSString *)screenId;
++ (void)removePaddingListener:(id<ANNScreenPaddingListener>)listener
+                  forScreenId:(NSString *)screenId;
+
+/// Forgets everything kept for the screen. Its padding listeners stay: a live safe area view keeps listening while it
+/// keeps the id, and stops itself. Main queue.
++ (void)removeScreenId:(NSString *)screenId;
+/// Forgets every screen: after a reload the new JavaScript counts its ids anew. Main queue.
++ (void)removeAll;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Layouts/Screen/ANNScreenEnvironment.mm

@@ -0,0 +1,181 @@
+#import "ANNScreenEnvironment.h"
+#import "ANNEventContract.h"
+
+// One screen's record; nil for a fact not known yet (not laid out, no regions, outside a pair). Changed and read only
+// under the lock of `ANNEnvironmentById`; the values are immutable, so a reader keeps what it took.
+@interface ANNScreenEnvironmentRecord : NSObject
+@property(nonatomic, copy, nullable) NSDictionary<NSString *, NSNumber *> *insets;
+@property(nonatomic, strong, nullable) NSValue *padding;
+@property(nonatomic, copy, nullable) NSDictionary<NSString *, NSArray *> *regions;
+@property(nonatomic, copy, nullable) NSDictionary<NSString *, id> *arrangement;
+@end
+
+@implementation ANNScreenEnvironmentRecord
+@end
+
+// Written on the main queue, read from any thread: every access holds its lock.
+static NSMutableDictionary<NSString *, ANNScreenEnvironmentRecord *> *ANNEnvironmentById;
+// The safe area views of each screen, by its id (the id's value: the view's id and the core's are other strings), held
+// weakly. Main queue only.
+static NSMutableDictionary<NSString *, NSHashTable<id<ANNScreenPaddingListener>> *>
+    *ANNPaddingListenersById;
+
+@implementation ANNScreenEnvironment
+
++ (void)initialize {
+    if (self == ANNScreenEnvironment.class) {
+        ANNEnvironmentById = [NSMutableDictionary new];
+        ANNPaddingListenersById = [NSMutableDictionary new];
+    }
+}
+
+// The screen's record, a new one for a screen not kept yet. Under the lock.
++ (ANNScreenEnvironmentRecord *)recordOf:(NSString *)screenId {
+    ANNScreenEnvironmentRecord *record = ANNEnvironmentById[screenId];
+    if (!record) {
+        record = [ANNScreenEnvironmentRecord new];
+        ANNEnvironmentById[screenId] = record;
+    }
+    return record;
+}
+
+#pragma mark - Insets and padding
+
++ (void)setInsets:(UIEdgeInsets)insets
+          padding:(UIEdgeInsets)padding
+      forScreenId:(NSString *)screenId
+     eventEmitter:(ANNEventEmitter *)eventEmitter {
+    NSValue *paddingValue = [NSValue valueWithUIEdgeInsets:padding];
+    // 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 = @{
+        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)),
+    };
+    BOOL paddingChanged;
+    BOOL insetsChanged;
+    @synchronized(ANNEnvironmentById) {
+        ANNScreenEnvironmentRecord *record = [self recordOf:screenId];
+        paddingChanged = ![record.padding isEqualToValue:paddingValue];
+        insetsChanged = ![record.insets isEqualToDictionary:value];
+        record.padding = paddingValue;
+        record.insets = value;
+    }
+    // The listeners read the padding back, so it is kept before they are told. A copy: a listener may stop or start
+    // listening while it is told.
+    if (paddingChanged) {
+        NSHashTable<id<ANNScreenPaddingListener>> *listeners = ANNPaddingListenersById[screenId];
+        for (id<ANNScreenPaddingListener> listener in listeners.allObjects) {
+            [listener screenPaddingDidChange];
+        }
+    }
+    if (insetsChanged) {
+        [eventEmitter sendScreenInsetsChanged:screenId insets:value];
+    }
+}
+
++ (UIEdgeInsets)paddingForScreenId:(NSString *)screenId {
+    @synchronized(ANNEnvironmentById) {
+        return ANNEnvironmentById[screenId].padding.UIEdgeInsetsValue;
+    }
+}
+
++ (NSDictionary<NSString *, NSNumber *> *)insetsForScreenId:(NSString *)screenId {
+    @synchronized(ANNEnvironmentById) {
+        return ANNEnvironmentById[screenId].insets;
+    }
+}
+
+#pragma mark - Regions
+
++ (void)setRegions:(NSDictionary<NSString *, NSArray *> *)regions
+       forScreenId:(NSString *)screenId
+      eventEmitter:(ANNEventEmitter *)eventEmitter {
+    const auto &keys = ANNEventContract.ScreenRegionsChanged;
+    BOOL empty = [regions[keys.division] count] == 0 && [regions[keys.occlusion] count] == 0;
+    @synchronized(ANNEnvironmentById) {
+        NSDictionary<NSString *, NSArray *> *before = ANNEnvironmentById[screenId].regions;
+        if ((!before && empty) || [before isEqualToDictionary:regions]) {
+            return;
+        }
+        [self recordOf:screenId].regions = regions;
+    }
+    [eventEmitter sendScreenRegionsChanged:screenId regions:regions];
+}
+
++ (NSDictionary<NSString *, NSArray *> *)regionsForScreenId:(NSString *)screenId {
+    @synchronized(ANNEnvironmentById) {
+        return ANNEnvironmentById[screenId].regions;
+    }
+}
+
+#pragma mark - Arrangement
+
++ (void)setArrangement:(NSDictionary<NSString *, id> *)arrangement
+           forScreenId:(NSString *)screenId
+          eventEmitter:(ANNEventEmitter *)eventEmitter {
+    @synchronized(ANNEnvironmentById) {
+        ANNScreenEnvironmentRecord *record = [self recordOf:screenId];
+        if ([record.arrangement isEqualToDictionary:arrangement]) {
+            return;
+        }
+        record.arrangement = arrangement;
+    }
+    [eventEmitter sendArrangementChanged:screenId state:arrangement];
+}
+
++ (NSDictionary<NSString *, id> *)arrangementForScreenId:(NSString *)screenId {
+    @synchronized(ANNEnvironmentById) {
+        return ANNEnvironmentById[screenId].arrangement;
+    }
+}
+
+#pragma mark - Padding listeners
+
++ (void)addPaddingListener:(id<ANNScreenPaddingListener>)listener
+               forScreenId:(NSString *)screenId {
+    NSHashTable<id<ANNScreenPaddingListener>> *listeners = ANNPaddingListenersById[screenId];
+    if (!listeners) {
+        listeners = [NSHashTable weakObjectsHashTable];
+        ANNPaddingListenersById[screenId] = listeners;
+    }
+    [listeners addObject:listener];
+}
+
++ (void)removePaddingListener:(id<ANNScreenPaddingListener>)listener
+                  forScreenId:(NSString *)screenId {
+    NSHashTable<id<ANNScreenPaddingListener>> *listeners = ANNPaddingListenersById[screenId];
+    [listeners removeObject:listener];
+    [self forgetListenersOfScreenIdIfNone:screenId];
+}
+
+// A view that went (it doesn't remove itself in its `dealloc`) leaves no entry in the weak table: `allObjects` counts
+// only the live ones. The table of a screen nobody listens to goes with the last one, or with the screen's record.
++ (void)forgetListenersOfScreenIdIfNone:(NSString *)screenId {
+    NSHashTable<id<ANNScreenPaddingListener>> *listeners = ANNPaddingListenersById[screenId];
+    if (listeners && listeners.allObjects.count == 0) {
+        [ANNPaddingListenersById removeObjectForKey:screenId];
+    }
+}
+
+#pragma mark - Removal
+
++ (void)removeScreenId:(NSString *)screenId {
+    @synchronized(ANNEnvironmentById) {
+        [ANNEnvironmentById removeObjectForKey:screenId];
+    }
+    [self forgetListenersOfScreenIdIfNone:screenId];
+}
+
++ (void)removeAll {
+    @synchronized(ANNEnvironmentById) {
+        [ANNEnvironmentById removeAllObjects];
+    }
+    for (NSString *screenId in ANNPaddingListenersById.allKeys) {
+        [self forgetListenersOfScreenIdIfNone:screenId];
+    }
+}
+
+@end

package/ios/Layouts/Screen/ANNScreenRegions.h

@@ -1,12 +1,10 @@
-#import "ANNEventEmitter.h"
 #import <UIKit/UIKit.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// The reserved regions of each screen (`useReservedRegions`), iOS 27.1: `division`, where the screen divides (the fold
-/// of a partly folded device), and `occlusion`, where hardware covers it (a camera); each a list of
-/// `{ x, y, width, height }`. The native side keeps them on the main queue; JavaScript reads them from its own thread
-/// for a screen's first render, and gets every change as `ANN.ScreenRegionsChanged`.
+/// The reserved regions of a screen (`useReservedRegions`), iOS 27.1: `division`, where the screen divides (the fold of
+/// a partly folded device), and `occlusion`, where hardware covers it (a camera); each a list of
+/// `{ x, y, width, height }`. Measured here; kept for JavaScript by `ANNScreenEnvironment`.
 @interface ANNScreenRegions : NSObject
 
 /// The active regions UIKit reserves in `view`, without the margins it adds around them for interactive content, in
@@ -15,19 +13,6 @@ NS_ASSUME_NONNULL_BEGIN
 + (nullable NSDictionary<NSString *, NSArray *> *)regionsOfView:(UIView *)view
                                                 inCoordinatesOf:(UIView *)coordinateView;
 
-/// Keeps the screen's regions and tells when they changed. Main queue.
-+ (void)setRegions:(NSDictionary<NSString *, NSArray *> *)regions
-       forScreenId:(NSString *)screenId
-      eventEmitter:(ANNEventEmitter *)eventEmitter;
-
-/// `{ division, occlusion }`, or nil before the screen was laid out. Any thread.
-+ (nullable NSDictionary<NSString *, NSArray *> *)regionsForScreenId:(NSString *)screenId;
-
-+ (void)removeScreenId:(NSString *)screenId;
-
-/// Forgets every screen: after a reload the new JavaScript counts its ids anew. Main queue.
-+ (void)removeAll;
-
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Layouts/Screen/ANNScreenRegions.mm

@@ -1,8 +1,6 @@
 #import "ANNScreenRegions.h"
 #import "ANNEventContract.h"
 
-static NSMutableDictionary<NSString *, NSDictionary<NSString *, NSArray *> *> *ANNScreenRegionsById;
-
 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 270100
 // The part of a region inside the screen, CGRectNull for a region outside it (the fold beside a screen of a pair, the
 // camera above a screen under the bar). A fold is 0 wide or 0 high: it is inside where its line crosses the screen,
@@ -51,12 +49,6 @@ ANNRegionRects(NSArray<UIViewReservedRegion *> *regions, UIView *view, UIView *c
 
 @implementation ANNScreenRegions
 
-+ (void)initialize {
-    if (self == ANNScreenRegions.class) {
-        ANNScreenRegionsById = [NSMutableDictionary new];
-    }
-}
-
 + (NSDictionary<NSString *, NSArray *> *)regionsOfView:(UIView *)view
                                        inCoordinatesOf:(UIView *)coordinateView {
 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 270100
@@ -75,34 +67,4 @@ ANNRegionRects(NSArray<UIViewReservedRegion *> *regions, UIView *view, UIView *c
     return nil;
 }
 
-+ (void)setRegions:(NSDictionary<NSString *, NSArray *> *)regions
-       forScreenId:(NSString *)screenId
-      eventEmitter:(ANNEventEmitter *)eventEmitter {
-    @synchronized(ANNScreenRegionsById) {
-        if ([ANNScreenRegionsById[screenId] isEqualToDictionary:regions]) {
-            return;
-        }
-        ANNScreenRegionsById[screenId] = regions;
-    }
-    [eventEmitter sendScreenRegionsChanged:screenId regions:regions];
-}
-
-+ (NSDictionary<NSString *, NSArray *> *)regionsForScreenId:(NSString *)screenId {
-    @synchronized(ANNScreenRegionsById) {
-        return ANNScreenRegionsById[screenId];
-    }
-}
-
-+ (void)removeScreenId:(NSString *)screenId {
-    @synchronized(ANNScreenRegionsById) {
-        [ANNScreenRegionsById removeObjectForKey:screenId];
-    }
-}
-
-+ (void)removeAll {
-    @synchronized(ANNScreenRegionsById) {
-        [ANNScreenRegionsById removeAllObjects];
-    }
-}
-
 @end

package/ios/Layouts/Screen/ANNScreenSafeArea.h

@@ -7,10 +7,6 @@ NS_ASSUME_NONNULL_BEGIN
 typedef struct {
     /// The screen is in a stack.
     BOOL inStack;
-    /// The screen's stack shows its toolbar.
-    BOOL stackShowsToolbar;
-    /// The bottom of the window's safe area: the home indicator.
-    CGFloat windowBottomSafeArea;
     /// The physical side of the iPhone Duo vertical bar (iOS 27.1): `UIRectEdgeLeft`, `UIRectEdgeRight`, or
     /// `UIRectEdgeNone` without one.
     UIRectEdge verticalBarSide;
@@ -27,11 +23,10 @@ FOUNDATION_EXPORT UIEdgeInsets ANNScreenInsetsOverRoot(CGRect rootFrame, CGSize
                                                       UIEdgeInsets safeArea);
 
 /// The padding the screen's safe area view keeps (`layout.safeAreaEdges`): the insets on the padded edges, 0 on the
-/// others. With `layout.safeAreaEdges` exactly those edges (an explicit `'top'` keeps the top under a large title too);
-/// without it every edge but: the top under a shown top bar (in a stack, under the top bar, `topBar.visible` not
-/// `false`) or with a large title that can show; the bottom when the bottom inset covers more than the window's home
-/// indicator (by over 0.5 pt), or in a stack with a toolbar and `topBar.hideOnScroll`; the side of the vertical bar
-/// unless `layout.drawBehindVerticalBar` or `layout.verticalBars` is `false`.
+/// others. With `layout.safeAreaEdges` exactly those edges, but the top under a large title that can show (in a stack,
+/// `topBar.visible` not `false`); without it every edge but: the top under a shown top bar (in a stack, under the top
+/// bar, `topBar.visible` not `false`) or with a large title that can show; the bottom, always; the side of the
+/// vertical bar unless `layout.drawBehindVerticalBar` or `layout.verticalBars` is `false`.
 FOUNDATION_EXPORT UIEdgeInsets ANNScreenPadding(UIEdgeInsets insets, ANNNavigationOptions *options,
                                                 ANNScreenPaddingContext context);
 

package/ios/Layouts/Screen/ANNScreenSafeArea.mm

@@ -1,9 +1,6 @@
 #import "ANNScreenSafeArea.h"
 #import "ANNScreenBars.h"
 
-// A bar at the bottom covers more than the home indicator when the bottom inset passes it by more than this.
-static const CGFloat ANNBottomBarThreshold = 0.5;
-
 CGRect ANNScreenRootFrame(CGRect bounds, UIEdgeInsets safeArea, BOOL fromTop, BOOL toBottom) {
     CGFloat top = fromTop ? 0 : safeArea.top;
     CGFloat bottom = toBottom ? CGRectGetHeight(bounds) : CGRectGetHeight(bounds) - safeArea.bottom;
@@ -20,31 +17,32 @@ UIEdgeInsets ANNScreenInsetsOverRoot(CGRect rootFrame, CGSize viewSize, UIEdgeIn
 
 UIEdgeInsets ANNScreenPadding(UIEdgeInsets insets, ANNNavigationOptions *options,
                               ANNScreenPaddingContext context) {
+    ANNTopBarOptions *topBar = options.topBar;
+    BOOL topBarShown = [topBar.visible withDefault:YES];
+    // Under a large title the list keeps its first rows clear of the bar itself. A padded top would follow the bar as
+    // it collapses and move the list with it, and UIKit, which collapses the title by the list's offset, would keep
+    // the small title hidden.
+    BOOL largeTitleShown = topBarShown && context.inStack && ANNLargeTitleCanShow(options);
     NSArray<NSString *> *edges = options.layout.safeAreaEdges;
     if (edges) {
-        // Exactly the edges given; unknown names count for nothing (`layout.safeAreaEdges`).
-        return UIEdgeInsetsMake([edges containsObject:@"top"] ? insets.top : 0,
+        // Exactly the edges given, but the top under a large title; unknown names count for nothing
+        // (`layout.safeAreaEdges`).
+        BOOL top = [edges containsObject:@"top"] && !largeTitleShown;
+        return UIEdgeInsetsMake(top ? insets.top : 0,
                                 [edges containsObject:@"left"] ? insets.left : 0,
                                 [edges containsObject:@"bottom"] ? insets.bottom : 0,
                                 [edges containsObject:@"right"] ? insets.right : 0);
     }
     UIEdgeInsets padding = insets;
-    ANNTopBarOptions *topBar = options.topBar;
-    BOOL topBarShown = [topBar.visible withDefault:YES];
     // A bar hidden for a while (`hideOnScroll`, `hideOnTap`, `hideOnKeyboard`) still counts as shown: only
     // `topBar.visible: false` gives the content its top back. A large title that can show takes the top too: the list
     // goes under the bar that collapses it.
-    if (topBarShown && context.inStack &&
-        (ANNScreenIsUnderTopBar(options) || ANNLargeTitleCanShow(options))) {
+    if (largeTitleShown || (topBarShown && context.inStack && ANNScreenIsUnderTopBar(options))) {
         padding.top = 0;
     }
-    // A bar at the bottom over the home indicator (a tab bar, a toolbar, the bottom search field of iOS 26): the list
-    // goes under it. A tab bar at the top on iPad adds nothing to the bottom. A toolbar that hides on scroll counts as
-    // there.
-    if (insets.bottom > context.windowBottomSafeArea + ANNBottomBarThreshold ||
-        (context.inStack && context.stackShowsToolbar && [topBar.hideOnScroll withDefault:NO])) {
-        padding.bottom = 0;
-    }
+    // The bottom is free: the content goes down to the bottom of the screen, under the home indicator and under a bar
+    // at the bottom, and a list keeps its last rows clear with `useSafeAreaInsets()`.
+    padding.bottom = 0;
     BOOL behindVerticalBar = [options.layout.drawBehindVerticalBar withDefault:YES] &&
                              [options.layout.verticalBars withDefault:YES];
     if (behindVerticalBar) {

package/ios/Layouts/Stack/ANNPreviewPush.h

@@ -5,12 +5,13 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// The preview of a push (`usePreview`): a push that waits for a tap on its preview. Its screen is made and renders
-/// unseen, out of the stack, its key kept; the view with `preview.nativeID` is looked for on the source screen at once
-/// and on the next frames, 30 tries in all; found, the preview module (`ANNPreviewInteraction`) shows the screen from
-/// it on a long press. A tap that commits pushes the screen without an animation and without a wait, or goes back to
-/// the entry with its key; a preview that goes without being opened destroys its screen and rejects the push. Main
-/// queue.
+/// The preview of a push (`usePreview`): a push that waits for a tap on its preview. Its screen is made at once, out of
+/// the stack, its key kept, and renders unseen: a React screen with a root of its own as a press on the view starts, a
+/// native screen or one of the app's one tree at once. The view with `preview.nativeID` is looked for on the source
+/// screen at once, then at each mount of the source's content (on each frame for a slot screen), for at most 0.5 s;
+/// found, the preview module (`ANNPreviewInteraction`) shows the screen from it on a long press. A tap that commits
+/// pushes the screen without an animation (and without a wait once its content is there), or goes back to the entry
+/// with its key; a preview that goes without being opened destroys its screen and rejects the push. Main queue.
 @interface ANNPreviewPush : NSObject
 
 - (instancetype)init NS_UNAVAILABLE;