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

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

package/ios/Options/Params/ANNImageSource.mm

@@ -0,0 +1,101 @@
+#import "ANNImageSource.h"
+
+// The path of a `file:` source the app may write again: a file outside the app's bundle (documents, caches, a temporary
+// folder); nil for any other source. The bundle's files and assets don't change while the app runs.
+static NSString *ANNWritablePathOf(ANNImageSourceKind kind, NSURL *url) {
+    if (kind != ANNImageSourceKindFile || !url.isFileURL) {
+        return nil;
+    }
+    NSString *path = url.path;
+    NSString *bundle = NSBundle.mainBundle.bundlePath;
+    if (!path.isAbsolutePath || [path isEqualToString:bundle] ||
+        [path hasPrefix:[bundle stringByAppendingString:@"/"]]) {
+        return nil;
+    }
+    return path;
+}
+
+// The modification date and size of the file at `path` (else of its `.png`, as the loader looks for it), or nil.
+static NSString *ANNFileStampOf(NSString *path) {
+    NSFileManager *files = NSFileManager.defaultManager;
+    NSDictionary<NSFileAttributeKey, id> *attributes = [files attributesOfItemAtPath:path
+                                                                                error:nil];
+    if (!attributes && path.pathExtension.length == 0) {
+        attributes = [files attributesOfItemAtPath:[path stringByAppendingPathExtension:@"png"]
+                                             error:nil];
+    }
+    NSDate *modified = attributes.fileModificationDate;
+    if (!modified) {
+        return nil;
+    }
+    return [NSString stringWithFormat:@"%.6f|%llu", modified.timeIntervalSinceReferenceDate,
+                                      attributes.fileSize];
+}
+
+@implementation ANNImageSource {
+    // The key without the file's stamp, and the path whose stamp joins it.
+    NSString *_baseKey;
+    NSString *_writablePath;
+}
+
++ (instancetype)symbolNamed:(NSString *)name fallback:(ANNImageSource *)fallback {
+    ANNImageSource *source = [[self alloc] initWithKind:ANNImageSourceKindSymbol
+                                                    url:nil
+                                                address:name
+                                                  scale:0
+                                                  width:0
+                                                 height:0];
+    source->_symbolName = [name copy];
+    source->_fallback = fallback;
+    return source;
+}
+
++ (instancetype)sourceOfKind:(ANNImageSourceKind)kind
+                         url:(NSURL *)url
+                     address:(NSString *)address
+                       scale:(CGFloat)scale
+                       width:(CGFloat)width
+                      height:(CGFloat)height {
+    return [[self alloc] initWithKind:kind
+                                  url:url
+                              address:address
+                                scale:scale
+                                width:width
+                               height:height];
+}
+
+- (instancetype)initWithKind:(ANNImageSourceKind)kind
+                         url:(NSURL *)url
+                     address:(NSString *)address
+                       scale:(CGFloat)scale
+                       width:(CGFloat)width
+                      height:(CGFloat)height {
+    if (self = [super init]) {
+        _kind = kind;
+        _url = url;
+        _address = [address copy];
+        _scale = scale;
+        _width = width;
+        _height = height;
+        _baseKey = [NSString stringWithFormat:@"%g|%g|%@", scale, width, _address];
+        _writablePath = ANNWritablePathOf(kind, url);
+    }
+    return self;
+}
+
+// Read at each ask: a file the app writes again at the same path is another image.
+- (NSString *)key {
+    NSString *stamp = _writablePath ? ANNFileStampOf(_writablePath) : nil;
+    return stamp ? [NSString stringWithFormat:@"%@|%@", _baseKey, stamp] : _baseKey;
+}
+
+- (NSString *)sourceKey {
+    NSString *own = [NSString stringWithFormat:@"%ld|%@", (long)_kind, _baseKey];
+    return _fallback ? [NSString stringWithFormat:@"%@|%@", own, _fallback.sourceKey] : own;
+}
+
+- (BOOL)loadsLater {
+    return _kind == ANNImageSourceKindFile || _kind == ANNImageSourceKindData;
+}
+
+@end

package/ios/Options/Params/ANNOptionImages.h

@@ -0,0 +1,37 @@
+#import "ANNImageSource.h"
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The images of the options, every one of them (bar buttons and their menus, the back button, tab icons, search
+/// tokens and suggestions): one cache for the app, by the source's key (`NSCache`, its cost the image's bytes, let go
+/// at a memory warning). The images don't depend on the JavaScript, so a reload keeps them.
+///
+/// Every decode runs on one serial queue of the loader: `imageOf:` waits for it, `loadLater:done:` doesn't. A failure
+/// (a missing file, data that isn't an image or doesn't decode, an exception while decoding) never throws: no image,
+/// and one warning per address in the log. It is not cached, as on Android: it answers for a moment (1 s, the reads of
+/// one apply), then the next read tries again, so a file written later or Metro's server back shows.
+@interface ANNOptionImages : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The image of `source`: a symbol, what the cache has, or else loaded before this returns; nil on a failure. Any
+/// thread.
++ (nullable UIImage *)imageOf:(ANNImageSource *)source;
+
+/// The cache doesn't have the image of `source`, it didn't fail a moment ago, and it loads off the main queue
+/// (`loadsLater` of the source): what `loadLater:done:` doesn't give at once. Any thread.
++ (BOOL)loadsLater:(ANNImageSource *)source;
+
+/// Loads `source` on the loader's queue and gives `done` the image, or nil on a failure, on the main queue; one load
+/// for every caller that asks for the same image meanwhile. What the cache has, or what doesn't load off the main
+/// queue, comes at once, before this returns. Main queue.
++ (void)loadLater:(ANNImageSource *)source done:(void (^)(UIImage *_Nullable image))done;
+
+/// Lets every image of the cache go. Any thread.
++ (void)clear;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/Params/ANNOptionImages.mm

@@ -0,0 +1,284 @@
+#import "ANNOptionImages.h"
+#import <React/RCTAssert.h>
+#import <React/RCTLog.h>
+#import <React/RCTUtils.h>
+
+// The options' icons are small: 16 MB of decoded pixels holds hundreds of them.
+static const NSUInteger ANNOptionImagesCostLimit = 16 * 1024 * 1024;
+
+// The longest piece of an address a warning names (a `data:` address is the whole image).
+static const NSUInteger ANNOptionImagesLoggedAddressLength = 80;
+
+// How long a failure answers for its source without a new try: the many reads of one apply ask once, a later apply
+// tries again (a file written since, Metro's server back).
+static const NSTimeInterval ANNOptionImagesFailureMoment = 1;
+
+static const void *ANNOptionImagesQueueKey = &ANNOptionImagesQueueKey;
+
+static NSCache<NSString *, UIImage *> *ANNCache;
+static dispatch_queue_t ANNQueue;
+// The addresses already named in a warning: one each.
+static NSMutableSet<NSString *> *ANNWarned;
+// The keys whose last try failed, with the system's uptime then; guarded by itself. Failures never go into the cache.
+static NSMutableDictionary<NSString *, NSNumber *> *ANNFailures;
+// The loads off the main queue under way, with who waits for each. Main queue.
+static NSMutableDictionary<NSString *, NSMutableArray *> *ANNLoading;
+
+static void ANNSetUp(void) {
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      ANNCache = [NSCache new];
+      ANNCache.name = @"ApexNavigation option images";
+      ANNCache.totalCostLimit = ANNOptionImagesCostLimit;
+      dispatch_queue_attr_t attributes = dispatch_queue_attr_make_with_qos_class(
+          DISPATCH_QUEUE_SERIAL, QOS_CLASS_USER_INITIATED, 0);
+      ANNQueue = dispatch_queue_create("dev.apexnative.navigation.images", attributes);
+      dispatch_queue_set_specific(ANNQueue, ANNOptionImagesQueueKey,
+                                  (void *)ANNOptionImagesQueueKey, NULL);
+      ANNWarned = [NSMutableSet new];
+      ANNFailures = [NSMutableDictionary new];
+      ANNLoading = [NSMutableDictionary new];
+      NSNotificationCenter *center = NSNotificationCenter.defaultCenter;
+      [center addObserverForName:UIApplicationDidReceiveMemoryWarningNotification
+                          object:nil
+                           queue:nil
+                      usingBlock:^(NSNotification *notification) {
+                        [ANNCache removeAllObjects];
+                      }];
+    });
+}
+
+// The bytes of the decoded image, the cost the cache weighs it with.
+static NSUInteger ANNBytesOf(UIImage *image) {
+    CGImageRef cgImage = image.CGImage;
+    if (cgImage) {
+        return CGImageGetBytesPerRow(cgImage) * CGImageGetHeight(cgImage);
+    }
+    CGFloat width = image.size.width * image.scale;
+    CGFloat height = image.size.height * image.scale;
+    return (NSUInteger)MAX(1, width * height * 4);
+}
+
+static void ANNWarnOnce(ANNImageSource *source, NSString *why) {
+    @synchronized(ANNWarned) {
+        if ([ANNWarned containsObject:source.address]) {
+            return;
+        }
+        [ANNWarned addObject:source.address];
+    }
+    NSString *address = source.address;
+    if (address.length > ANNOptionImagesLoggedAddressLength) {
+        address = [[address substringToIndex:ANNOptionImagesLoggedAddressLength]
+            stringByAppendingString:@"…"];
+    }
+    RCTLogWarn(@"[ApexNavigation] could not load the image %@: %@", address, why);
+}
+
+// The last try of `key` failed a moment ago.
+static BOOL ANNFailedJustNow(NSString *key) {
+    @synchronized(ANNFailures) {
+        NSNumber *at = ANNFailures[key];
+        if (!at) {
+            return NO;
+        }
+        NSTimeInterval since = NSProcessInfo.processInfo.systemUptime - at.doubleValue;
+        if (since < ANNOptionImagesFailureMoment) {
+            return YES;
+        }
+        [ANNFailures removeObjectForKey:key];
+        return NO;
+    }
+}
+
+static void ANNSetFailed(NSString *key, BOOL failed) {
+    @synchronized(ANNFailures) {
+        if (failed) {
+            ANNFailures[key] = @(NSProcessInfo.processInfo.systemUptime);
+        } else {
+            [ANNFailures removeObjectForKey:key];
+        }
+    }
+}
+
+// A file at the address: an image with nothing but its pixels, which can be decoded ahead. An asset of a catalog
+// (found by name) may have a dark variant, which a decoded copy would lose.
+static BOOL ANNIsFileAt(NSURL *url) {
+    NSString *path = url.path;
+    if (path.length == 0) {
+        return NO;
+    }
+    NSFileManager *files = NSFileManager.defaultManager;
+    if ([files fileExistsAtPath:path]) {
+        return YES;
+    }
+    return path.pathExtension.length == 0 &&
+           [files fileExistsAtPath:[path stringByAppendingPathExtension:@"png"]];
+}
+
+@implementation ANNOptionImages
+
++ (UIImage *)imageOf:(ANNImageSource *)source {
+    if (source.kind == ANNImageSourceKindSymbol) {
+        UIImage *symbol = [UIImage systemImageNamed:source.symbolName];
+        return symbol ?: (source.fallback ? [self imageOf:source.fallback] : nil);
+    }
+    ANNSetUp();
+    NSString *key = source.key;
+    UIImage *cached = [ANNCache objectForKey:key];
+    if (cached || ANNFailedJustNow(key)) {
+        return cached;
+    }
+    if (dispatch_get_specific(ANNOptionImagesQueueKey)) {
+        return [self loadOnQueue:source];
+    }
+    __block UIImage *image = nil;
+    dispatch_sync(ANNQueue, ^{
+      image = [self loadOnQueue:source];
+    });
+    return image;
+}
+
+// A failure of a moment ago answers at once, so an item built again when its load failed doesn't load again.
++ (BOOL)loadsLater:(ANNImageSource *)source {
+    if (!source.loadsLater) {
+        return NO;
+    }
+    ANNSetUp();
+    NSString *key = source.key;
+    return [ANNCache objectForKey:key] == nil && !ANNFailedJustNow(key);
+}
+
++ (void)loadLater:(ANNImageSource *)source done:(void (^)(UIImage *))done {
+    RCTAssertMainQueue();
+    if (![self loadsLater:source]) {
+        done([self imageOf:source]);
+        return;
+    }
+    NSString *key = source.key;
+    NSMutableArray *waiters = ANNLoading[key];
+    if (waiters) {
+        [waiters addObject:[done copy]];
+        return;
+    }
+    ANNLoading[key] = [NSMutableArray arrayWithObject:[done copy]];
+    dispatch_async(ANNQueue, ^{
+      UIImage *image = [self loadOnQueue:source];
+      dispatch_async(dispatch_get_main_queue(), ^{
+        NSArray *waiting = ANNLoading[key];
+        [ANNLoading removeObjectForKey:key];
+        for (void (^waiter)(UIImage *) in waiting) {
+            waiter(image);
+        }
+      });
+    });
+}
+
++ (void)clear {
+    ANNSetUp();
+    [ANNCache removeAllObjects];
+    @synchronized(ANNFailures) {
+        [ANNFailures removeAllObjects];
+    }
+}
+
+#pragma mark - The loader's queue
+
+// The cache again (a load that came first), else the decode. An image goes into the cache; a failure doesn't, as on
+// Android: it answers only for a moment (`ANNFailedJustNow`), and the next apply after that tries again.
++ (UIImage *)loadOnQueue:(ANNImageSource *)source {
+    NSString *key = source.key;
+    UIImage *cached = [ANNCache objectForKey:key];
+    if (cached || ANNFailedJustNow(key)) {
+        return cached;
+    }
+    NSString *failure = nil;
+    UIImage *image = nil;
+    @try {
+        image = [self decode:source failure:&failure];
+    } @catch (NSException *exception) {
+        image = nil;
+        failure = [NSString
+            stringWithFormat:@"decoding it threw %@ (%@)", exception.name, exception.reason];
+    }
+    if (!image) {
+        ANNSetFailed(key, YES);
+        ANNWarnOnce(source, failure ?: @"it can't be decoded");
+        return nil;
+    }
+    ANNSetFailed(key, NO);
+    [ANNCache setObject:image forKey:key cost:ANNBytesOf(image)];
+    return image;
+}
+
+// The image of an address, as React Native's converter of images reads it, with the scale of the source; nil with
+// what failed. A plain file and data are decoded here, so the first frame that shows them doesn't.
++ (UIImage *)decode:(ANNImageSource *)source failure:(NSString **)failure {
+    NSURL *url = source.url;
+    UIImage *image = nil;
+    BOOL decodesAhead = YES;
+    switch (source.kind) {
+    case ANNImageSourceKindFile:
+        image = RCTImageFromLocalAssetURL(url) ?: RCTImageFromLocalBundleAssetURL(url);
+        if (!image) {
+            *failure = @"there is no image at that address";
+            return nil;
+        }
+        decodesAhead = ANNIsFileAt(url);
+        break;
+    case ANNImageSourceKindData:
+    case ANNImageSourceKindMetro: {
+        // Metro's assets in development: read from the dev server, as before the cache.
+        NSError *error = nil;
+        NSData *data = url ? [NSData dataWithContentsOfURL:url options:0 error:&error] : nil;
+        if (data.length == 0) {
+            *failure = error.localizedDescription ?: @"it has no data";
+            return nil;
+        }
+        image = [UIImage imageWithData:data];
+        if (!image) {
+            *failure = @"its data is not an image";
+            return nil;
+        }
+        break;
+    }
+    case ANNImageSourceKindSymbol:
+        return nil;
+    }
+    // An image UIKit can't prepare (16 bits a channel, CMYK) it still draws: it stays as it is then, decoded when it
+    // first shows.
+    UIImage *decoded = decodesAhead ? [image imageByPreparingForDisplay] : nil;
+    if (decoded) {
+        image = decoded.CGImage ? [UIImage imageWithCGImage:decoded.CGImage
+                                                      scale:image.scale
+                                                orientation:image.imageOrientation]
+                                : decoded;
+    }
+    if (!(image.size.width > 0) || !(image.size.height > 0)) {
+        *failure = @"it is empty";
+        return nil;
+    }
+    return [self image:image scaledBy:source];
+}
+
+// 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:(ANNImageSource *)source {
+    CGFloat scale = source.scale;
+    CGFloat width = source.width;
+    CGFloat height = source.height;
+    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;
+}
+
+@end

package/ios/Options/Params/Image.h

@@ -1,15 +1,24 @@
+#import "ANNImageSource.h"
 #import "Param.h"
 #import <UIKit/UIKit.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// An image of the options, loaded when the options were read. An image that didn't load is no value: the element shows
-/// without it.
+/// An image of the options: its source, read with the options, and the image, loaded when an element asks for it
+/// through the shared cache (`ANNOptionImages`). A source that doesn't load is no image: the element shows without it.
+/// A value that is a `UIImage` is that image, with no source: an element made again from an image that came already
+/// (a tab's icon loaded off the main queue) doesn't ask the cache again.
 @interface Image : Param
 
+/// The image, loaded at once when the cache doesn't have it; nil without a source and when it doesn't load.
 - (nullable UIImage *)get;
+/// The image, or `defaultValue` without a source and when it doesn't load. `hasValue` says only that the options name
+/// an image: a choice between an image and what shows without one reads the image itself.
 - (nullable UIImage *)withDefault:(nullable UIImage *)defaultValue;
 
+/// What the options name; nil without a value.
+@property(nonatomic, strong, readonly, nullable) ANNImageSource *source;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Options/Params/Image.mm

@@ -1,13 +1,26 @@
 #import "Image.h"
+#import "ANNOptionImages.h"
 
 @implementation Image
 
+- (ANNImageSource *)source {
+    id value = self.value;
+    return [value isKindOfClass:ANNImageSource.class] ? value : nil;
+}
+
 - (UIImage *)get {
-    return [super get];
+    id value = self.value;
+    if ([value isKindOfClass:UIImage.class]) {
+        return value;
+    }
+    ANNImageSource *source = self.source;
+    return source ? [ANNOptionImages imageOf:source] : nil;
 }
 
+// A source that doesn't load is no image: the default then, as without a value.
 - (UIImage *)withDefault:(UIImage *)defaultValue {
-    return [super withDefault:defaultValue];
+    UIImage *image = self.hasValue ? self.get : nil;
+    return image ?: defaultValue;
 }
 
 @end

package/ios/Options/Params/ImageParser.h

@@ -2,11 +2,11 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// Reads `key` of the options' JSON as an image and loads it at once, on the main queue: `{ system, fallback? }` is an
-/// SF Symbol, else the fallback source; a source (a string, or an object with `uri`, `bundle`, `scale`, `width`,
-/// `height` and Metro's asset flag) loads a file, an asset of the app's bundle, a `data:` address, or in development a
-/// Metro asset. Remote addresses and arrays of sources are not loaded. A failure is no image and an error in the React
-/// Native log; it never throws.
+/// Reads `key` of the options' JSON as the source of an image, which loads when an element shows it (`Image`):
+/// `{ system, fallback? }` is an SF Symbol, else the fallback source; a source (a string, or an object with `uri`,
+/// `bundle`, `scale`, `width`, `height` and Metro's asset flag) is a file, an asset of the app's bundle, a `data:`
+/// address, or in development a Metro asset. Remote addresses and arrays of sources are no image, with an error in the
+/// React Native log; it never throws.
 @interface ImageParser : NSObject
 
 + (Image *)parse:(nullable NSDictionary *)json key:(NSString *)key;