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

package/ios/Options/Params/ImageParser.mm

@@ -2,7 +2,6 @@
 #import "ANNOptionsReader.h"
 #import <React/RCTConvert.h>
 #import <React/RCTLog.h>
-#import <React/RCTUtils.h>
 
 @implementation ImageParser
 
@@ -12,10 +11,10 @@
         return [[Image alloc] initWithValue:nil];
     }
     NSString *path = [ANNOptionsReader pathOfKey:key];
-    return [[Image alloc] initWithValue:[self imageOf:value path:path]];
+    return [[Image alloc] initWithValue:[self sourceOf:value path:path]];
 }
 
-+ (UIImage *)imageOf:(id)value path:(NSString *)path {
++ (ANNImageSource *)sourceOf:(id)value path:(NSString *)path {
     if ([value isKindOfClass:NSArray.class]) {
         RCTLogError(@"[ApexNavigation] the image of '%@' is a list of sources, which options don't support: give "
                     @"one source",
@@ -23,27 +22,28 @@
         return nil;
     }
     if ([value isKindOfClass:NSDictionary.class] && value[@"system"]) {
-        return [self systemImageOf:value path:path];
+        return [self symbolOf:value path:path];
     }
     if (![value isKindOfClass:NSString.class] && ![value isKindOfClass:NSDictionary.class]) {
         return nil;
     }
-    return [self imageOfSource:value path:path];
+    return [self addressOf:value path:path];
 }
 
 // An SF Symbol; a name the system doesn't have takes the fallback source, read the same way.
-+ (UIImage *)systemImageOf:(NSDictionary *)value path:(NSString *)path {
++ (ANNImageSource *)symbolOf:(NSDictionary *)value path:(NSString *)path {
     id name = value[@"system"];
-    UIImage *image = [name isKindOfClass:NSString.class] ? [UIImage systemImageNamed:name] : nil;
-    if (image) {
-        return image;
-    }
     id fallback = value[@"fallback"];
-    return fallback && fallback != NSNull.null ? [self imageOf:fallback path:path] : nil;
+    ANNImageSource *fallbackSource =
+        fallback && fallback != NSNull.null ? [self sourceOf:fallback path:path] : nil;
+    if (![name isKindOfClass:NSString.class] || [name length] == 0) {
+        return fallbackSource;
+    }
+    return [ANNImageSource symbolNamed:name fallback:fallbackSource];
 }
 
-// A resolved source, loaded synchronously as React Native's converter of images does, with the scale of the source.
-+ (UIImage *)imageOfSource:(id)source path:(NSString *)path {
+// A resolved source: its address and the fields its scale comes from.
++ (ANNImageSource *)addressOf:(id)source path:(NSString *)path {
     NSDictionary *fields = [source isKindOfClass:NSDictionary.class] ? source : nil;
     id address = fields ? (fields[@"uri"] ?: fields[@"url"]) : source;
     if (![address isKindOfClass:NSString.class] || [address length] == 0) {
@@ -56,48 +56,30 @@
     }
     NSURL *url = [RCTConvert NSURL:address];
     NSString *scheme = url.scheme.lowercaseString;
-    BOOL metroAsset = ANNJSONIsBoolean(fields[@"__packager_asset"]) && [fields[@"__packager_asset"] boolValue];
-    UIImage *image = nil;
+    id packagerAsset = fields[@"__packager_asset"];
+    BOOL metroAsset = ANNJSONIsBoolean(packagerAsset) && [packagerAsset boolValue];
+    ANNImageSourceKind kind;
     if ([scheme isEqualToString:@"file"]) {
-        image = RCTImageFromLocalAssetURL(url) ?: RCTImageFromLocalBundleAssetURL(url);
+        kind = ANNImageSourceKindFile;
     } else if ([scheme isEqualToString:@"data"]) {
-        image = [UIImage imageWithData:[NSData dataWithContentsOfURL:url]];
+        kind = ANNImageSourceKindData;
     } else if (([scheme isEqualToString:@"http"] || [scheme isEqualToString:@"https"]) && metroAsset) {
-        // Metro's assets in development: loaded from the dev server, synchronously.
-        image = [UIImage imageWithData:[NSData dataWithContentsOfURL:url]];
+        kind = ANNImageSourceKindMetro;
     } else {
         RCTLogError(@"[ApexNavigation] the image of '%@' is not loaded: remote images are not supported in options "
                     @"(%@)",
                     path, address);
         return nil;
     }
-    if (!image) {
-        RCTLogError(@"[ApexNavigation] the image of '%@' could not be loaded: %@", path, address);
-        return nil;
-    }
-    return [self image:image scaledBy:fields];
-}
-
-// The scale of the source; without it the pixel width over `width`; without both, the file's own. A size that
-// doesn't match is only logged.
-+ (UIImage *)image:(UIImage *)image scaledBy:(NSDictionary *)fields {
-    id scaleValue = fields[@"scale"];
-    id widthValue = fields[@"width"];
-    id heightValue = fields[@"height"];
-    CGFloat scale = ANNJSONIsNumber(scaleValue) ? [scaleValue doubleValue] : 0;
-    CGFloat width = ANNJSONIsNumber(widthValue) ? [widthValue doubleValue] : 0;
-    CGFloat height = ANNJSONIsNumber(heightValue) ? [heightValue doubleValue] : 0;
-    if (scale <= 0 && width > 0 && image.CGImage) {
-        scale = CGImageGetWidth(image.CGImage) / width;
-    }
-    if (scale > 0 && image.CGImage && scale != image.scale) {
-        image = [UIImage imageWithCGImage:image.CGImage scale:scale orientation:image.imageOrientation];
-    }
-    if (width > 0 && height > 0 && !CGSizeEqualToSize(image.size, CGSizeMake(width, height))) {
-        RCTLogInfo(@"[ApexNavigation] an image of the options is %@, its source says %@",
-                   NSStringFromCGSize(image.size), NSStringFromCGSize(CGSizeMake(width, height)));
-    }
-    return image;
+    id scale = fields[@"scale"];
+    id width = fields[@"width"];
+    id height = fields[@"height"];
+    return [ANNImageSource sourceOfKind:kind
+                                    url:url
+                                address:address
+                                  scale:ANNJSONIsNumber(scale) ? [scale doubleValue] : 0
+                                  width:ANNJSONIsNumber(width) ? [width doubleValue] : 0
+                                 height:ANNJSONIsNumber(height) ? [height doubleValue] : 0];
 }
 
 @end

package/ios/Public/ApexNavigation/ApexNavigation.h

@@ -37,7 +37,7 @@ NS_SWIFT_NAME(NativeScreenContext)
 
 /**
  * Runs a command of the navigation from this screen in JS, as `useNavigation()` of a React screen does: push, pop,
- * popTo, popToRoot, showInColumn, showModal, dismiss, showOverlay, dismissOverlay, setOptions, selectTab, setTabBadge.
+ * popTo, popToRoot, showInColumn, showModal, dismiss, showOverlay, setOptions, selectTab, setTabBadge.
  * `arguments` are those of the JS command; `completion` gets what it resolved with.
  *
  * ```swift

package/ios/RECIPES.md

@@ -16,9 +16,14 @@ you do exactly that; the map is `ios/CLAUDE.md`.
    what the merge names) and in `applyDefaultOptionsChange:`. A system-UI option also goes into
    `+[ANNSystemUI groupsNamedBy:onlyRead:]`; a bar-placement option into `ANNOptionsChangeScreenBars`.
 4. **The cache.** Never invalidate by hand. Own options change through `ANNNodeHelper` (`mergeOwnOptions:`,
-   `changeOwnOptions:`) and defaults through `+[ANNDefaultOptions setCurrent:]`; both call
-   `+[ANNOptionsCache optionsChanged]`. A presenter or module that keeps a choice of the user writes it with
-   `changeOwnOptions:`, never into the options in place.
+   `changeOwnOptions:`), the user layer through `setUserChoice:forKey:`, and defaults through
+   `+[ANNDefaultOptions setCurrent:]`; all call `+[ANNOptionsCache optionsChanged]`. `changeOwnOptions:` is for what
+   the core keeps of the app's merges. A presenter or module that keeps a choice of the user (a toggle, a menu check,
+   a scope) puts an `ANNUserChoice` into the node's user layer under a key of its own: its `apply` block writes the
+   choice by identity (a button or item by its id) on a copy, its `merged` block says when the app's merge takes it
+   away, by Android's rules (`UserChoices.yieldTo`): a value other than the app had there (the own options', else the
+   node's resolution before the merge), or what the choice is about gone from the resolution after it. Never into the
+   options in place.
 5. **Android** reads the same JSON and has unit tests of parsing and merging; the iOS side has none (see Checks in `ios/CLAUDE.md`).
 6. **The rule:** an option does what its name promises, with the same meaning on both platforms
    (`.claude/rules/general.md`, `.claude/rules/options.md`). A platform that can't, says so in the JSDoc.
@@ -37,6 +42,7 @@ you do exactly that; the map is `ios/CLAUDE.md`.
    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.
+   `-[ANNCommandAnswer resolve:]`; the state and `ANN.CommandCompleted` follow by themselves as `ANNCommandContract`
+   says. A new command with a promise gets its entry in `src/interfaces/contract/commands.json` (what it resolves
+   with, `state`, `completed`), then `node scripts/contract.mjs`.
 7. **Android** gets the same command; its tests check the texts.

package/ios/React/Slots/ANNSlotComponentView.mm

@@ -8,11 +8,13 @@
 
 using namespace facebook::react;
 
+@interface ANNSlotComponentView () <ANNSlotView>
+@end
+
 @implementation ANNSlotComponentView {
     // The React children live here. It waits hidden inside the slot, then moves into the container.
     ANNSlotContentView *_contentView;
     ANNSlotShadowNode::ConcreteState::Shared _state;
-    BOOL _observing;
     // The layout that measures the content was asked for once.
     BOOL _measureAsked;
 }
@@ -33,19 +35,8 @@ using namespace facebook::react;
     return self;
 }
 
-- (void)dealloc {
-    [NSNotificationCenter.defaultCenter removeObserver:self];
-}
-
 - (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &)oldProps {
     [super updateProps:props oldProps:oldProps];
-    if (!_observing) {
-        _observing = YES;
-        [NSNotificationCenter.defaultCenter addObserver:self
-                                               selector:@selector(containerDidChange:)
-                                                   name:ANNSlotContainerDidChangeNotification
-                                                 object:nil];
-    }
     [self attachContent];
 }
 
@@ -54,13 +45,23 @@ using namespace facebook::react;
     [self attachContent];
 }
 
-- (void)containerDidChange:(NSNotification *)notification {
-    if ([notification.object isEqual:self.nativeId]) {
+#pragma mark - ANNSlotView
+
+- (void)slotContainerDidChange:(NSString *)slotId {
+    if ([slotId isEqualToString:self.nativeId]) {
         [self attachContent];
     }
 }
 
+#pragma mark - Content
+
 - (void)attachContent {
+    // The view hears the changes of the container under the slot id it has now, and no other.
+    if (self.nativeId != nil) {
+        [ANNSlotContainers registerSlotView:self forSlotId:self.nativeId];
+    } else {
+        [ANNSlotContainers unregisterSlotView:self];
+    }
     UIView *container = self.nativeId ? [ANNSlotContainers containerForSlotId:self.nativeId] : nil;
     UIView *target = container ?: self;
     if (_contentView.superview != target) {
@@ -108,15 +109,21 @@ using namespace facebook::react;
     return nil;
 }
 
-// A recycled slot waits for another screen: it stops listening and drops the old screen's state.
+// A recycled slot waits for another screen: it leaves its slot id and drops the old screen's state. Its new props put
+// it under the new id.
 - (void)prepareForRecycle {
     [super prepareForRecycle];
-    [NSNotificationCenter.defaultCenter removeObserver:self];
-    _observing = NO;
+    [ANNSlotContainers unregisterSlotView:self];
     _measureAsked = NO;
     _state.reset();
     [_contentView removeFromSuperview];
     _contentView.hidden = YES;
 }
 
+// An unmounted slot that Fabric doesn't keep for reuse leaves its slot id too.
+- (void)invalidate {
+    [super invalidate];
+    [ANNSlotContainers unregisterSlotView:self];
+}
+
 @end

package/ios/React/Slots/ANNSlotContainers.h

@@ -2,9 +2,6 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// Posted when the container of a slot appears or changes its size; the object is the slot id.
-extern NSNotificationName const ANNSlotContainerDidChangeNotification;
-
 /// A component named with this prefix is a screen of the app's one React tree: it has no React surface of its own,
 /// and the slot of the tree with its componentId shows it. Events and the state give its name without the prefix.
 extern NSString *const ANNSlotPrefix;
@@ -17,8 +14,14 @@ NSString *ANNComponentNameWithoutSlotPrefix(NSString *name);
 - (void)slotContentDidMount;
 @end
 
-/// The native containers the slots of the app's React tree show their children in, by slot id. A destroyed
-/// container drops out on its own.
+/// A slot view of the app's React tree: it hears when the container of its slot id appears, goes or changes its size.
+@protocol ANNSlotView <NSObject>
+- (void)slotContainerDidChange:(NSString *)slotId;
+@end
+
+/// The native containers the slots of the app's React tree show their children in, by slot id, and the slot views by
+/// the same id: a change of a container goes straight to the views of its id. A destroyed container and a deallocated
+/// view drop out on their own. Main queue only.
 @interface ANNSlotContainers : NSObject
 
 + (void)setContainer:(UIView *)container forSlotId:(NSString *)slotId;
@@ -26,9 +29,14 @@ NSString *ANNComponentNameWithoutSlotPrefix(NSString *name);
 /// The container goes: its slot takes its content back.
 + (void)removeContainerForSlotId:(NSString *)slotId;
 
-/// The container of a slot appeared or changed its size.
+/// The container of a slot appeared or changed its size: the slot views under its id, and only they, hear it.
 + (void)containerDidChange:(NSString *)slotId;
 
+/// The slot view goes under its slot id, and out from under the id it had. Held weakly.
++ (void)registerSlotView:(id<ANNSlotView>)view forSlotId:(NSString *)slotId;
+/// The slot view unmounted or lost its slot id: no change of a container reaches it.
++ (void)unregisterSlotView:(id<ANNSlotView>)view;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/React/Slots/ANNSlotContainers.mm

@@ -1,6 +1,6 @@
 #import "ANNSlotContainers.h"
+#import "ANNAssert.h"
 
-NSNotificationName const ANNSlotContainerDidChangeNotification = @"ANNSlotContainerDidChange";
 NSString *const ANNSlotPrefix = @"slot:";
 
 NSString *ANNComponentNameWithoutSlotPrefix(NSString *name) {
@@ -32,8 +32,81 @@ NSString *ANNComponentNameWithoutSlotPrefix(NSString *name) {
     [self containerDidChange:slotId];
 }
 
+// The slot views by slot id, weakly, in the order they came. Two live views under one id both stay and both hear
+// the change, in that order, as every view with the id did when the change went to all of them.
++ (NSMutableDictionary<NSString *, NSPointerArray *> *)slotViews {
+    static NSMutableDictionary *slotViews;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      slotViews = [NSMutableDictionary dictionary];
+    });
+    return slotViews;
+}
+
+// The id each slot view is under, so a view is under one id at a time.
++ (NSMapTable<id<ANNSlotView>, NSString *> *)slotIds {
+    static NSMapTable *slotIds;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      slotIds = [[NSMapTable alloc]
+          initWithKeyOptions:NSPointerFunctionsWeakMemory | NSPointerFunctionsObjectPointerPersonality
+                valueOptions:NSPointerFunctionsStrongMemory
+                    capacity:0];
+    });
+    return slotIds;
+}
+
 + (void)containerDidChange:(NSString *)slotId {
-    [NSNotificationCenter.defaultCenter postNotificationName:ANNSlotContainerDidChangeNotification object:slotId];
+    ANNAssertMainQueue();
+    // A copy: a view may register or leave while it hears the change.
+    for (id<ANNSlotView> view in [self slotViewsForSlotId:slotId]) {
+        [view slotContainerDidChange:slotId];
+    }
+}
+
++ (void)registerSlotView:(id<ANNSlotView>)view forSlotId:(NSString *)slotId {
+    ANNAssertMainQueue();
+    if ([[self.slotIds objectForKey:view] isEqualToString:slotId]) {
+        return;
+    }
+    [self unregisterSlotView:view];
+    [self.slotIds setObject:slotId forKey:view];
+    NSPointerArray *views = self.slotViews[slotId];
+    if (views == nil) {
+        views = [NSPointerArray weakObjectsPointerArray];
+        self.slotViews[slotId] = views;
+    }
+    [views addPointer:(__bridge void *)view];
+}
+
++ (void)unregisterSlotView:(id<ANNSlotView>)view {
+    ANNAssertMainQueue();
+    NSString *slotId = [self.slotIds objectForKey:view];
+    if (slotId == nil) {
+        return;
+    }
+    [self.slotIds removeObjectForKey:view];
+    [self pruneSlotId:slotId dropping:view];
+}
+
++ (NSArray<id<ANNSlotView>> *)slotViewsForSlotId:(NSString *)slotId {
+    [self pruneSlotId:slotId dropping:nil];
+    return self.slotViews[slotId].allObjects ?: @[];
+}
+
+// Drops the deallocated views under the id and `view`; an id with no views left goes. By hand rather than with
+// `compact`, which keeps the nil entries of a weak pointer array.
++ (void)pruneSlotId:(NSString *)slotId dropping:(nullable id<ANNSlotView>)view {
+    NSPointerArray *views = self.slotViews[slotId];
+    for (NSInteger index = (NSInteger)views.count - 1; index >= 0; index--) {
+        void *pointer = [views pointerAtIndex:(NSUInteger)index];
+        if (pointer == NULL || pointer == (__bridge void *)view) {
+            [views removePointerAtIndex:(NSUInteger)index];
+        }
+    }
+    if (views != nil && views.count == 0) {
+        [self.slotViews removeObjectForKey:slotId];
+    }
 }
 
 @end

package/ios/TopBar/ANNBarButtons.h

@@ -17,7 +17,7 @@ typedef NS_ENUM(NSInteger, ANNBarButtonsSide) {
 /// merge of a side. Each button is an `ANNUIBarButtonItem` of the first kind its fields give (React view → icon and
 /// text → image button → SF Symbol → image → text → system item); a button without `id` is not placed. Side colors go
 /// onto what is built, never into the options; what the user chose (a toggle, a menu's check) goes into the screen's
-/// own options. The React buttons' slots are kept by component id, so a button built again reuses its slot. Main queue.
+/// user layer. The React buttons' slots are kept by component id, so a button built again reuses its slot. Main queue.
 @interface ANNBarButtons : NSObject
 
 - (instancetype)initWithScreen:(UIViewController *)screen
@@ -49,12 +49,16 @@ typedef NS_ENUM(NSInteger, ANNBarButtonsSide) {
 /// The width the slot of a React button measured; 0 before it rendered.
 - (CGFloat)measuredWidthOf:(NSString *)componentId;
 
-/// A menu item `itemId` was picked: `ANN.NavigationButtonPressed` with its id, then the check of a single-selection
-/// menu written into the screen's own copy of the menu. `menuOf` gives the menu in `options` (a button's, the title's,
-/// the overflow menu); `setMenu` puts the copy into the own options.
+/// A menu item `itemId` was picked: `ANN.NavigationButtonPressed` with its id, then, in a single-selection list, the
+/// pick kept in the screen's user layer under `choiceKey`, one choice per menu. The resolution plays the picks again on
+/// a copy of the menu it has. `menuOf` gives the menu in `options` (a button's, the title's, the overflow menu),
+/// `setMenu` puts a changed copy there. A merge into the screen takes a pick away when the screen's resolution after it
+/// has no such item, or when it gives the menu with other checks in the pick's level than the app had there, as on
+/// Android. The two blocks capture no presenter: the node keeps them with the choice.
 - (void)menuItemPicked:(NSString *)itemId
+             choiceKey:(NSString *)choiceKey
                 menuOf:(ANNMenuOptions *_Nullable (^)(ANNNavigationOptions *options))menuOf
-               setMenu:(void (^)(ANNNavigationOptions *own, ANNMenuOptions *menu))setMenu;
+               setMenu:(void (^)(ANNNavigationOptions *options, ANNMenuOptions *menu))setMenu;
 
 /// A copy of `menu` that shares no item with it (a new `ANNMenuOptions` and a new `ANNMenuItemOptions` per item, at
 /// any depth).