@apexnative/navigation 1.0.0-alpha.0 → 1.0.0-alpha.10

package/ios/Options/ANNOptions.h

@@ -20,6 +20,13 @@ NS_ASSUME_NONNULL_BEGIN
 /// The group of options under `key`: nil when it is not an object (`null` included), which reads as an empty group.
 NSDictionary *_Nullable ANNOptionsDictionary(NSDictionary *_Nullable dict, NSString *key);
 
+/// Two values a group of options holds are the same: params and groups by `isSameValueAs:`, arrays item by item,
+/// anything else as `ANNJSONValuesSame` says. nil is the same only as nil (an unset array is not an empty one).
+BOOL ANNOptionValuesSame(id _Nullable a, id _Nullable b);
+
+/// A hash of a value `ANNOptionValuesSame` compares: values that are the same have the same hash.
+NSUInteger ANNOptionValueHash(id _Nullable value);
+
 #if DEBUG
 /// Development only: checks the field table of `root` and of every group class reached through its group and
 /// group-array fields.
@@ -51,12 +58,30 @@ void ANNCheckOptionClassesFrom(Class root);
 /// The group has any value.
 - (BOOL)hasValue;
 
+/// Takes the value at `path` out, in place: the JSON keys from this group, the last one a value, an array or a whole
+/// group, which gets what a freshly made group has there (unset). A key of a text's font goes through the text. A
+/// module's group (an empty field table) is walked by its properties named as the keys. NO, and nothing changes, when
+/// a key of the path is none of the group's or a key before the last is no group. Only on a copy of own options
+/// (`changeOwnOptions:`), never on options in use.
+- (BOOL)clearValueAtPath:(NSArray<NSString *> *)path;
+
 /// A deep copy: a new group of the same class with these merged into it. The copy shares values, never groups.
 - (instancetype)copy;
 
 /// These over a copy of `defaults`; neither changes.
 - (instancetype)withDefault:(nullable ANNOptions *)defaults;
 
+/// A group of the same class with the same options, field by field at any depth: two reads of the same JSON, a copy,
+/// two resolutions of the same layers. The fields are the field table's; a module's group (an empty table) compares
+/// every property of an options kind it declares. A value that is nil is the same only as nil.
+///
+/// Not `isEqual:`: a group changes in place (a merge, the pick of a menu's item), so a hash by value would move under
+/// a set or a dictionary that holds it. `==` and `isEqual:` stay identity.
+- (BOOL)isSameValueAs:(nullable ANNOptions *)other;
+
+/// A hash consistent with `isSameValueAs:`; it changes when the group does.
+- (NSUInteger)valueHash;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Options/ANNOptions.mm

@@ -11,7 +11,6 @@ NSDictionary *ANNOptionsDictionary(NSDictionary *dict, NSString *key) {
     return [value isKindOfClass:NSDictionary.class] ? value : nil;
 }
 
-#if DEBUG
 // The kinds of property a group holds options in.
 static BOOL ANNIsOptionClass(Class cls) {
     return [cls isSubclassOfClass:ANNParam.class] || [cls isSubclassOfClass:ANNOptions.class] ||
@@ -33,6 +32,7 @@ static Class ANNPropertyClass(objc_property_t property) {
     return name ? NSClassFromString(name) : nil;
 }
 
+#if DEBUG
 // There is no iOS test target: in development each group of the core checks once that its table names every property
 // that holds options, and that every field of the table has its property (the stand-in for the whole-tree test of
 // Android). A missing field would be neither read, merged, copied nor given defaults.
@@ -86,6 +86,94 @@ static NSArray<ANNOptionField *> *ANNFieldsOf(Class cls) {
     }
 }
 
+// The properties that hold the options of a group, asked once per class: its field table's, or for a module's group
+// (its own read and merge, an empty table) every property of an options kind its classes declare up to `ANNOptions`.
+static NSArray<NSString *> *ANNValuePropertiesOf(Class cls) {
+    static NSMutableDictionary<NSString *, NSArray<NSString *> *> *propertiesByClass;
+    NSString *name = NSStringFromClass(cls);
+    @synchronized(ANNOptions.class) {
+        if (!propertiesByClass) {
+            propertiesByClass = [NSMutableDictionary new];
+        }
+        NSArray<NSString *> *names = propertiesByClass[name];
+        if (names) {
+            return names;
+        }
+    }
+    NSArray<ANNOptionField *> *fields = ANNFieldsOf(cls);
+    NSMutableArray<NSString *> *found = [NSMutableArray new];
+    if (fields.count) {
+        for (ANNOptionField *field in fields) {
+            [found addObject:field.property];
+        }
+    } else {
+        NSSet<NSString *> *inherited =
+            [NSSet setWithArray:@[ @"description", @"debugDescription" ]];
+        for (Class current = cls; current && current != ANNOptions.class;
+             current = class_getSuperclass(current)) {
+            unsigned int count = 0;
+            objc_property_t *properties = class_copyPropertyList(current, &count);
+            for (unsigned int i = 0; i < count; i++) {
+                NSString *property = @(property_getName(properties[i]));
+                Class propertyClass = ANNPropertyClass(properties[i]);
+                if (propertyClass && ANNIsOptionClass(propertyClass) &&
+                    ![inherited containsObject:property] && ![found containsObject:property]) {
+                    [found addObject:property];
+                }
+            }
+            free(properties);
+        }
+    }
+    NSArray<NSString *> *names = [found copy];
+    @synchronized(ANNOptions.class) {
+        propertiesByClass[name] = names;
+    }
+    return names;
+}
+
+BOOL ANNOptionValuesSame(id a, id b) {
+    if (a == b) {
+        return YES;
+    }
+    if ([a isKindOfClass:ANNParam.class]) {
+        return [b isKindOfClass:ANNParam.class] && [(ANNParam *)a isSameValueAs:b];
+    }
+    if ([a isKindOfClass:ANNOptions.class]) {
+        return [b isKindOfClass:ANNOptions.class] && [(ANNOptions *)a isSameValueAs:b];
+    }
+    if ([a isKindOfClass:NSArray.class]) {
+        if (![b isKindOfClass:NSArray.class] || [a count] != [b count]) {
+            return NO;
+        }
+        NSArray *items = b;
+        NSUInteger index = 0;
+        for (id item in (NSArray *)a) {
+            if (!ANNOptionValuesSame(item, items[index++])) {
+                return NO;
+            }
+        }
+        return YES;
+    }
+    return ANNJSONValuesSame(a, b);
+}
+
+NSUInteger ANNOptionValueHash(id value) {
+    if ([value isKindOfClass:ANNParam.class]) {
+        return [(ANNParam *)value valueHash];
+    }
+    if ([value isKindOfClass:ANNOptions.class]) {
+        return [(ANNOptions *)value valueHash];
+    }
+    if ([value isKindOfClass:NSArray.class]) {
+        NSUInteger hash = [value count];
+        for (id item in value) {
+            hash = hash * 31 + ANNOptionValueHash(item);
+        }
+        return hash;
+    }
+    return ANNJSONValueHash(value);
+}
+
 #if DEBUG
 // Runs the check on `root` and on every class reached through its group and group-array fields, so a class that only
 // an array holds (a button, an action of a fab, a token of the search bar) is checked although no object of it is made.
@@ -310,6 +398,51 @@ static NSArray *ANNCopyItems(NSArray *items) {
     return NO;
 }
 
+// Generic over the whole tree, so that any option an edit takes out (`clearOptions`) goes without a list of options:
+// the field table names each key's property; a module's group, which reads its JSON itself, names its properties as
+// the keys.
+- (BOOL)clearValueAtPath:(NSArray<NSString *> *)path {
+    NSString *key = path.firstObject;
+    if (key.length == 0) {
+        return NO;
+    }
+    NSArray<ANNOptionField *> *fields = ANNFieldsOf(self.class);
+    NSString *property = nil;
+    if (fields.count) {
+        for (ANNOptionField *field in fields) {
+            if ([field.key isEqualToString:key]) {
+                property = field.property;
+                break;
+            }
+        }
+        if (!property) {
+            // A group without a key (the font of a text) holds keys of its parent's object.
+            for (ANNOptionField *field in fields) {
+                if (field.kind == ANNOptionFieldKindGroup && !field.key &&
+                    [[self valueForKey:field.property] clearValueAtPath:path]) {
+                    return YES;
+                }
+            }
+            return NO;
+        }
+    } else if ([ANNValuePropertiesOf(self.class) containsObject:key]) {
+        property = key;
+    } else {
+        return NO;
+    }
+    if (path.count == 1) {
+        ANNOptions *fresh = [[self.class alloc] initWithDict:nil];
+        [self setValue:[fresh valueForKey:property] forKey:property];
+        return YES;
+    }
+    id value = [self valueForKey:property];
+    if (![value isKindOfClass:ANNOptions.class]) {
+        return NO;
+    }
+    NSArray<NSString *> *rest = [path subarrayWithRange:NSMakeRange(1, path.count - 1)];
+    return [(ANNOptions *)value clearValueAtPath:rest];
+}
+
 - (id)copyWithZone:(NSZone *)zone {
     ANNOptions *copy = [[self.class alloc] initWithDict:nil];
     [copy mergeOptions:self];
@@ -326,4 +459,27 @@ static NSArray *ANNCopyItems(NSArray *items) {
     return result;
 }
 
+- (BOOL)isSameValueAs:(ANNOptions *)other {
+    if (other == self) {
+        return YES;
+    }
+    if (other.class != self.class) {
+        return NO;
+    }
+    for (NSString *property in ANNValuePropertiesOf(self.class)) {
+        if (!ANNOptionValuesSame([self valueForKey:property], [other valueForKey:property])) {
+            return NO;
+        }
+    }
+    return YES;
+}
+
+- (NSUInteger)valueHash {
+    NSUInteger hash = (NSUInteger)(__bridge void *)self.class;
+    for (NSString *property in ANNValuePropertiesOf(self.class)) {
+        hash = hash * 31 + ANNOptionValueHash([self valueForKey:property]);
+    }
+    return hash;
+}
+
 @end

package/ios/Options/ANNOptionsCache.h

@@ -2,13 +2,14 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// The one point where options change: a number for the whole process that grows each time a node's own options or the
-/// default options change. A node's resolved options are cached with the number they were built at, so any change makes
-/// every cache miss. Main queue.
+/// The one point where options change: a number for the whole process that grows each time a node's own options, its
+/// user layer or the default options change. A node's resolved options are cached with the number they were built at,
+/// so any change makes every cache miss. Main queue.
 ///
-/// Exactly two places call `optionsChanged`: the setter of a node's own options (`ANNNodeHelper.options`, which
-/// `mergeOwnOptions:` and `changeOwnOptions:` go through) and the store of new default options (`ANNDefaultOptions`).
-/// Nothing else may change own options or defaults: a write past them would leave caches stale.
+/// Exactly three places call `optionsChanged`: the setter of a node's own options (`ANNNodeHelper.options`, which
+/// `mergeOwnOptions:` and `changeOwnOptions:` go through), the setter of its user layer
+/// (`ANNNodeHelper setUserChoice:forKey:`) and the store of new default options (`ANNDefaultOptions`). Nothing else may
+/// change own options, choices or defaults: a write past them would leave caches stale.
 @interface ANNOptionsCache : NSObject
 
 /// The generation of the options now.

package/ios/Options/ANNOptionsReader.mm

@@ -1,12 +1,119 @@
 #import "ANNOptionsReader.h"
 #import "ANNAssert.h"
 #import "ANNNavigationOptions.h"
+#if DEBUG
+#import <React/RCTLog.h>
+#endif
 
 // The parse runs on the main queue, one tree at a time: the path and the first failure are its state. A group read
 // outside a parse (a module that reads its own JSON) finds an empty path and keeps no failure.
 static NSMutableArray<NSString *> *ANNPathComponents;
 static NSString *ANNFirstFailure;
 
+#if DEBUG
+// A deep mutable copy of `json` with `value` at `path` (keys, and indexes of arrays); nil `value` removes the key.
+static id ANNJSONWith(id json, NSArray *path, id value) {
+    if (path.count == 0) {
+        return value;
+    }
+    NSArray *rest = [path subarrayWithRange:NSMakeRange(1, path.count - 1)];
+    if ([json isKindOfClass:NSArray.class]) {
+        NSMutableArray *items = [json mutableCopy];
+        NSUInteger index = [path[0] unsignedIntegerValue];
+        items[index] = ANNJSONWith(items[index], rest, value);
+        return items;
+    }
+    NSMutableDictionary *fields = [json mutableCopy];
+    id inner = ANNJSONWith(fields[path[0]], rest, value);
+    if (inner) {
+        fields[path[0]] = inner;
+    } else {
+        [fields removeObjectForKey:path[0]];
+    }
+    return fields;
+}
+
+// There is no iOS test target: in development the value equality of the options (`isSameValueAs:`) checks itself
+// once on a tree with a value of each kind: two reads, a copy and a merge give the same options and the same hash, and
+// a change of one value at any depth gives other options. A module's group (the menu) compares by its properties.
+static void ANNCheckSameValues(void) {
+    NSDictionary *button = @{
+        @"id" : @"save",
+        @"text" : @"Save",
+        @"icon" : @{@"system" : @"star"},
+        @"enabled" : @YES,
+        @"badge" : @1,
+        @"fontSize" : @15,
+        @"menu" : @{
+            @"title" : @"More",
+            @"items" : @[ @{@"id" : @"details", @"title" : @"Details", @"checked" : @YES} ],
+        },
+    };
+    NSDictionary *json = @{
+        @"topBar" : @{
+            @"title" : @{@"text" : @"Home", @"color" : @(0xFF112233)},
+            @"rightButtonColor" : @{@"light" : @(0xFF000000), @"dark" : @(0xFFFFFFFF)},
+            @"leftButtonColor" : NSNull.null,
+            @"rightButtons" : @[ button ],
+            @"leftButtons" : @[],
+            @"height" : @44,
+        },
+        @"keyCommands" : @[ @{@"input" : @"k", @"modifiers" : @[ @"command" ]} ],
+    };
+    ANNNavigationOptions *options = [[ANNNavigationOptions alloc] initWithDict:json];
+    ANNNavigationOptions *again = [[ANNNavigationOptions alloc] initWithDict:json];
+    ANNNavigationOptions *copy = [options copy];
+    ANNNavigationOptions *overEmpty = [options withDefault:[ANNNavigationOptions new]];
+    for (ANNNavigationOptions *same in @[ again, copy, overEmpty ]) {
+        if (![options isSameValueAs:same] || options.valueHash != same.valueHash) {
+            RCTLogError(@"[ApexNavigation] options read, copied or resolved from the same JSON are "
+                        @"not the same value");
+        }
+    }
+    // Each change: the path of one value and its new value; an unset key is not the same as `null` or `[]`.
+    NSDictionary<NSString *, NSArray *> *changes = @{
+        @"a text" : @[ @[ @"topBar", @"title", @"text" ], @"Profile" ],
+        @"a color" : @[ @[ @"topBar", @"title", @"color" ], @(0xFF112234) ],
+        @"a side of a color pair" : @[ @[ @"topBar", @"rightButtonColor", @"dark" ], @(0xFFEEEEEE) ],
+        @"a number" : @[ @[ @"topBar", @"height" ], @45 ],
+        @"an image" : @[ @[ @"topBar", @"rightButtons", @0, @"icon", @"system" ], @"heart" ],
+        @"a boolean" : @[ @[ @"topBar", @"rightButtons", @0, @"enabled" ], @NO ],
+        @"a boolean for a number" : @[ @[ @"topBar", @"rightButtons", @0, @"badge" ], @YES ],
+        @"a font" : @[ @[ @"topBar", @"rightButtons", @0, @"fontSize" ], @16 ],
+        @"a module's group" :
+            @[ @[ @"topBar", @"rightButtons", @0, @"menu", @"items", @0, @"checked" ], @NO ],
+        @"an object of an array" : @[ @[ @"keyCommands", @0, @"modifiers", @0 ], @"shift" ],
+    };
+    NSDictionary<NSString *, NSArray *> *removals = @{
+        @"a color of `null` and no color" : @[ @"topBar", @"leftButtonColor" ],
+        @"an empty array and no array" : @[ @"topBar", @"leftButtons" ],
+    };
+    NSMutableDictionary<NSString *, id> *variants = [NSMutableDictionary new];
+    [changes enumerateKeysAndObjectsUsingBlock:^(NSString *what, NSArray *change, BOOL *stop) {
+      variants[what] = ANNJSONWith(json, change[0], change[1]);
+    }];
+    [removals enumerateKeysAndObjectsUsingBlock:^(NSString *what, NSArray *path, BOOL *stop) {
+      variants[what] = ANNJSONWith(json, path, nil);
+    }];
+    [variants enumerateKeysAndObjectsUsingBlock:^(NSString *what, NSDictionary *variant,
+                                                  BOOL *stop) {
+      ANNNavigationOptions *changed = [[ANNNavigationOptions alloc] initWithDict:variant];
+      if ([options isSameValueAs:changed] || [changed isSameValueAs:options]) {
+          RCTLogError(@"[ApexNavigation] options that differ in %@ are the same value", what);
+      }
+    }];
+    ANNNavigationOptions *merged = [options copy];
+    [merged mergeOptions:[[ANNNavigationOptions alloc]
+                             initWithDict:@{@"topBar" : @{@"title" : @{@"text" : @"Profile"}}}]];
+    ANNNavigationOptions *read = [[ANNNavigationOptions alloc]
+        initWithDict:ANNJSONWith(json, @[ @"topBar", @"title", @"text" ], @"Profile")];
+    if (![merged isSameValueAs:read] || merged.valueHash != read.valueHash) {
+        RCTLogError(@"[ApexNavigation] merged options are not the same value as the same options "
+                    @"read at once");
+    }
+}
+#endif
+
 @implementation ANNOptionsReader
 
 + (ANNNavigationOptions *)optionsFrom:(NSDictionary *)json unreadablePath:(NSString **)unreadablePath {
@@ -15,6 +122,7 @@ static NSString *ANNFirstFailure;
     static dispatch_once_t checkOnce;
     dispatch_once(&checkOnce, ^{
       ANNCheckOptionClassesFrom(ANNNavigationOptions.class);
+      ANNCheckSameValues();
     });
 #endif
     NSMutableArray<NSString *> *outerPath = ANNPathComponents;

package/ios/Options/ANNSearchBarOptions.h

@@ -15,9 +15,10 @@ typedef NS_ENUM(NSInteger, SearchBarPlacement) {
     SearchBarPlacementIntegratedCentered,
 };
 
-/// `topBar.searchBar` (`OptionsSearchBar`): the search of a screen. `ANNSearchPresenter` applies it. The scope, the
-/// tokens and the suggestions are written back by the search as the user changes them (`changeOwnOptions:`), so they
-/// stay when the options apply again.
+/// `topBar.searchBar` (`OptionsSearchBar`): the search of a screen. `ANNSearchPresenter` applies it. The scope the user
+/// picks, the tokens the user deletes or brings back and the suggestions UIKit removes go into the screen's user layer
+/// (`setUserChoice:forKey:`), not into these options: they stay when the options apply again and through a
+/// `mergeOptions` that sends the same values, and give way when a merge changes the field.
 @interface ANNSearchBarOptions : ANNOptions
 
 @property(nonatomic, strong) Bool *visible;

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/Options/ANNSideMenuOptions.h

@@ -12,6 +12,8 @@ NS_ASSUME_NONNULL_BEGIN
 @property(nonatomic, strong) Text *openGestureMode;
 /// `'parallax'`, `'slide'`, `'slide-and-scale'` or `'door'`.
 @property(nonatomic, strong) Text *animationType;
+/// `'together'`, `'afterCenter'` or `'onOpen'`.
+@property(nonatomic, strong) Text *menusAttachMode;
 @property(nonatomic, strong) Text *testID;
 
 @end

package/ios/Options/ANNSideMenuOptions.mm

@@ -9,6 +9,8 @@
         [ANNOptionField enumField:@"openGestureMode" values:@[ @"bezel", @"entireScreen" ]],
         [ANNOptionField enumField:@"animationType"
                            values:@[ @"parallax", @"slide", @"slide-and-scale", @"door" ]],
+        [ANNOptionField enumField:@"menusAttachMode"
+                           values:@[ @"together", @"afterCenter", @"onOpen" ]],
         [ANNOptionField textField:@"testID"],
     ];
 }

package/ios/Options/ANNStackPopAnimationOptions.h

@@ -0,0 +1,13 @@
+#import "ANNStackAnimationOptions.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// `animations.pop` (`StackPopAnimationOptions`).
+@interface ANNStackPopAnimationOptions : ANNStackAnimationOptions
+
+/// The swipe back plays the screen's own pop under the finger.
+@property(nonatomic, strong) Bool *interactive;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/ANNStackPopAnimationOptions.mm

@@ -0,0 +1,11 @@
+#import "ANNStackPopAnimationOptions.h"
+
+@implementation ANNStackPopAnimationOptions
+
++ (NSArray<ANNOptionField *> *)optionFields {
+    return [[super optionFields] arrayByAddingObjectsFromArray:@[
+        [ANNOptionField boolField:@"interactive"],
+    ]];
+}
+
+@end

package/ios/Options/ANNUserChoice.h

@@ -0,0 +1,57 @@
+#import "ANNNavigationOptions.h"
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Writes a choice into options being resolved: `options` is a copy the block may change, but its lists and their
+/// items are shared with other trees, so the block puts in a new list with a copy of what it changes, never a change in
+/// place. It finds what it changes by identity (a button by its id, a menu item by its id, a scope by its id) and
+/// leaves the options as they are when that is not there.
+typedef void (^ANNUserChoiceApply)(ANNNavigationOptions *options, id value);
+
+/// The value of a choice after the app's `mergeOptions` into the node, by Android's rules (`UserChoices.yieldTo`):
+/// `merge` is what the app sent, `own` the node's own options before it, `before` and `after` the node's resolution
+/// with the defaults and without any user layer (the app's options alone) before and after the merge. The same `value`
+/// keeps the choice, a smaller value keeps part of it, nil drops it. A part leaves when what it was made in is gone
+/// from `after` (a button, a menu item, a scope), or when `merge` gives its field a value other than the one the app
+/// had there: `own`'s, or `before`'s where `own` has no such field (a list the node takes from its stack or the
+/// defaults). The same value sent again (a re-render) keeps it.
+typedef id _Nullable (^ANNUserChoiceMerged)(id value, ANNNavigationOptions *merge,
+                                             ANNNavigationOptions *own,
+                                             ANNNavigationOptions *before,
+                                             ANNNavigationOptions *after);
+
+/// One choice the user made in native UI (a toggled button, the check of a single-selection menu, the search scope, the
+/// tokens and the suggestions UIKit removed, a renamed title), kept in the node's user layer
+/// (`ANNNodeHelper setUserChoice:forKey:`) apart from its own options. The node's resolution writes it over the own
+/// options (`applyTo:`); the app's real change of the same field, or a merge after which what it is about is gone,
+/// takes it away (`choiceAfterMerge:own:before:after:`). The blocks capture only plain data (a side, an id, a key),
+/// never a presenter: the node keeps them as long as the choice.
+@interface ANNUserChoice : NSObject
+
+/// What the user chose, never changed: a number, a string, an array of ids or of option copies.
+@property(nonatomic, strong, readonly) id value;
+
++ (instancetype)choiceWithValue:(id)value
+                          apply:(ANNUserChoiceApply)apply
+                         merged:(ANNUserChoiceMerged)merged;
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The same choice with another value.
+- (instancetype)choiceWithValue:(id)value;
+
+/// The choice written into `options` (a copy being resolved).
+- (void)applyTo:(ANNNavigationOptions *)options;
+
+/// The choice after the app's `mergeOptions` (`ANNUserChoiceMerged`): itself, the choice with a smaller value, or nil
+/// when it goes.
+- (nullable ANNUserChoice *)choiceAfterMerge:(ANNNavigationOptions *)merge
+                                         own:(ANNNavigationOptions *)own
+                                      before:(ANNNavigationOptions *)before
+                                       after:(ANNNavigationOptions *)after;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/ANNUserChoice.mm

@@ -0,0 +1,44 @@
+#import "ANNUserChoice.h"
+
+@implementation ANNUserChoice {
+    ANNUserChoiceApply _apply;
+    ANNUserChoiceMerged _merged;
+}
+
++ (instancetype)choiceWithValue:(id)value
+                          apply:(ANNUserChoiceApply)apply
+                         merged:(ANNUserChoiceMerged)merged {
+    return [[self alloc] initWithValue:value apply:apply merged:merged];
+}
+
+- (instancetype)initWithValue:(id)value
+                        apply:(ANNUserChoiceApply)apply
+                       merged:(ANNUserChoiceMerged)merged {
+    if (self = [super init]) {
+        _value = value;
+        _apply = [apply copy];
+        _merged = [merged copy];
+    }
+    return self;
+}
+
+- (instancetype)choiceWithValue:(id)value {
+    return [[ANNUserChoice alloc] initWithValue:value apply:_apply merged:_merged];
+}
+
+- (void)applyTo:(ANNNavigationOptions *)options {
+    _apply(options, _value);
+}
+
+- (ANNUserChoice *)choiceAfterMerge:(ANNNavigationOptions *)merge
+                                own:(ANNNavigationOptions *)own
+                             before:(ANNNavigationOptions *)before
+                              after:(ANNNavigationOptions *)after {
+    id value = _merged(_value, merge, own, before, after);
+    if (!value) {
+        return nil;
+    }
+    return value == _value ? self : [self choiceWithValue:value];
+}
+
+@end

package/ios/Options/Params/ANNImageSource.h

@@ -0,0 +1,61 @@
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Where an image of the options comes from.
+typedef NS_ENUM(NSInteger, ANNImageSourceKind) {
+    /// An SF Symbol (`{ system, fallback? }`); a name the system doesn't have takes the fallback.
+    ANNImageSourceKindSymbol,
+    /// A `file:` address: a file, or an asset of the app's bundle that React Native resolved.
+    ANNImageSourceKindFile,
+    /// A `data:` address.
+    ANNImageSourceKindData,
+    /// Metro's asset in development, read from the dev server.
+    ANNImageSourceKindMetro,
+};
+
+/// An image the options name, as they name it: read when the options are read, loaded when an element shows it
+/// (`ANNOptionImages`). Immutable; any thread.
+@interface ANNImageSource : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// An SF Symbol, with the source a name the system doesn't have takes.
++ (instancetype)symbolNamed:(NSString *)name fallback:(nullable ANNImageSource *)fallback;
+
+/// An address of `kind` (not a symbol) with the source's `scale`, `width` and `height` (0 without them).
++ (instancetype)sourceOfKind:(ANNImageSourceKind)kind
+                         url:(NSURL *)url
+                     address:(NSString *)address
+                       scale:(CGFloat)scale
+                       width:(CGFloat)width
+                      height:(CGFloat)height;
+
+@property(nonatomic, readonly) ANNImageSourceKind kind;
+@property(nonatomic, copy, readonly, nullable) NSString *symbolName;
+@property(nonatomic, strong, readonly, nullable) ANNImageSource *fallback;
+@property(nonatomic, strong, readonly, nullable) NSURL *url;
+/// The address as the options gave it (with its bundle); the symbol's name for a symbol.
+@property(nonatomic, copy, readonly) NSString *address;
+@property(nonatomic, readonly) CGFloat scale;
+@property(nonatomic, readonly) CGFloat width;
+@property(nonatomic, readonly) CGFloat height;
+
+/// What the decoded image depends on: the address, the scale and the width (the scale without one), and for a `file:`
+/// source outside the app's bundle the file's modification date and size, read at each ask, so a file the app writes
+/// again at the same path shows its new content. The cache's key.
+@property(nonatomic, copy, readonly) NSString *key;
+
+/// What the options name, as text: the kind, the address, the scale and the width, and a symbol's fallback, without the
+/// file's stamp, so what the file holds now never changes it. Reads nothing from the disk. For telling whether two
+/// options name the same image (`key` is for the decoded one).
+@property(nonatomic, copy, readonly) NSString *sourceKey;
+
+/// The image reads from the device alone (a file, an asset of the app, a `data:` address), so it may load off the main
+/// queue; Metro's asset reads from the network and a symbol is the system's.
+@property(nonatomic, readonly) BOOL loadsLater;
+
+@end
+
+NS_ASSUME_NONNULL_END