fix(iOS): load header items icons synchronously when feasible (#3355)

## Description

When using RCTImageLoader for images in headerRightItems/headerLeftItems
the asynchronous `loadImageWithURLRequest` produces som layout bugs as
shown under "Screenshots". These are:
1. When setting title and image the title is briefly visible before the
image is set.
2. When setting only image the bar button item is briefly shown as a
very wide item without any content.

## Changes

1. If the image is a `ImageRequireSource` load the image with
`[RCTConvert UIImage]`. I know its deprecated but thats the only
synchronous image loader that I know of.
2. If the image is a `ImageURISource` set the bar button title in the
completion block of `loadImageWithURLRequest`
3. Updates `BarButtonItems` example to latest types/api from
react-navigation/native-stack.

## Screenshots / GIFs

### Before

**Title briefly shown**


https://github.com/user-attachments/assets/0b964e1a-cfea-4be8-bdf8-a50297ceee9e

**Wide bar button item while `loadImageWithURLRequest` completes**


https://github.com/user-attachments/assets/0c2fcca0-1860-4cea-b4fe-16d07a5e3a95

### After


https://github.com/user-attachments/assets/653f4c16-c1ff-4aea-bd18-211a1e6eb404

## Test code and steps to reproduce

Use any of the examples with required images in BarButtonItems

## Checklist

- [x] Included code example that can be used to test this change
- [ ] Updated TS types
- [ ] Updated documentation: <!-- For adding new props to native-stack
-->
- [ ]
https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
- [ ]
https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
- [ ]
https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
- [ ]
https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
- [ ] Ensured that CI passes

---------

Co-authored-by: Kacper Kafara <[email protected]>

Author: johankasperi

apps/Example.tsx

@@ -30,7 +30,7 @@ import Orientation from './src/screens/Orientation';
 import SearchBar from './src/screens/SearchBar';
 import Events from './src/screens/Events';
 import Gestures from './src/screens/Gestures';
-// import BarButtonItems from './src/screens/BarButtonItems';
+import BarButtonItems from './src/screens/BarButtonItems';
 
 import { GestureDetectorProvider } from 'react-native-screens/gesture-handler';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
@@ -128,11 +128,11 @@ const SCREENS: Record<
     component: Gestures,
     type: 'playground',
   },
-  // BarButtonItems: {
-  //   title: 'Bar Button Items',
-  //   component: BarButtonItems,
-  //   type: 'playground',
-  // },
+  BarButtonItems: {
+    title: 'Bar Button Items',
+    component: BarButtonItems,
+    type: 'playground',
+  },
 };
 
 if (isTestSectionEnabled()) {

ios/RNSBarButtonItem.mm

@@ -2,7 +2,7 @@
 #import <React/RCTConvert.h>
 #import <React/RCTFont.h>
 #import <React/RCTImageSource.h>
-#import <objc/runtime.h>
+#import "RCTImageSource+AccessHiddenMembers.h"
 #import "RNSDefines.h"
 
 @implementation RNSBarButtonItem {
@@ -20,48 +20,36 @@ - (instancetype)initWithConfig:(NSDictionary<NSString *, id> *)dict
     return self;
   }
 
-  self.title = dict[@"title"];
-
+  NSString *title = dict[@"title"];
   NSDictionary *imageSourceObj = dict[@"imageSource"];
   NSDictionary *templateSourceObj = dict[@"templateSource"];
-
-  RCTImageSource *imageSource = nil;
-  if (imageSourceObj) {
-    imageSource = [RCTConvert RCTImageSource:imageSourceObj];
-  } else if (templateSourceObj) {
-    imageSource = [RCTConvert RCTImageSource:templateSourceObj];
-  }
-
-  if (imageSource) {
-    [imageLoader loadImageWithURLRequest:imageSource.request
-        size:imageSource.size
-        scale:imageSource.scale
-        clipped:true
-        resizeMode:RCTResizeModeContain
-        progressBlock:^(int64_t progress, int64_t total) {
-        }
-        partialLoadBlock:^(UIImage *_Nonnull image) {
-        }
-        completionBlock:^(NSError *_Nullable error, UIImage *_Nullable image) {
-          dispatch_async(dispatch_get_main_queue(), ^{
-            UIImage *imageWithRenderingMode = nil;
-            if (imageSourceObj) {
-              imageWithRenderingMode = [image imageWithRenderingMode:UIImageRenderingModeAlwaysOriginal];
-            } else if (templateSourceObj) {
-              imageWithRenderingMode = [image imageWithRenderingMode:UIImageRenderingModeAlwaysTemplate];
-            }
-            self.image = imageWithRenderingMode;
-          });
-        }];
-  }
   NSString *sfSymbolName = dict[@"sfSymbolName"];
-  if (sfSymbolName) {
+
+  if (imageSourceObj != nil) {
+    void (^completionAction)(NSError *_Nullable, UIImage *_Nullable) =
+        ^(NSError *_Nullable error, UIImage *_Nullable image) {
+          self.image = [image imageWithRenderingMode:UIImageRenderingModeAlwaysOriginal];
+        };
+    [self loadImageSyncFromImageSourceJson:imageSourceObj withImageLoader:imageLoader completionBlock:completionAction];
+  } else if (templateSourceObj != nil) {
+    void (^completionAction)(NSError *_Nullable, UIImage *_Nullable) =
+        ^(NSError *_Nullable error, UIImage *_Nullable image) {
+          self.image = [image imageWithRenderingMode:UIImageRenderingModeAlwaysTemplate];
+        };
+    [self loadImageSyncFromImageSourceJson:templateSourceObj
+                           withImageLoader:imageLoader
+                           completionBlock:completionAction];
+  } else if (sfSymbolName != nil) {
     self.image = [UIImage systemImageNamed:sfSymbolName];
   }
 
-  NSDictionary *titleStyle = dict[@"titleStyle"];
-  if (titleStyle) {
-    [self setTitleStyleFromConfig:titleStyle];
+  if (title != nil) {
+    self.title = title;
+
+    NSDictionary *titleStyle = dict[@"titleStyle"];
+    if (titleStyle != nil) {
+      [self setTitleStyleFromConfig:titleStyle];
+    }
   }
 
   id tintColorObj = dict[@"tintColor"];
@@ -339,4 +327,55 @@ - (void)setBadgeFromConfig:(NSDictionary *)badgeObj
 }
 #endif
 
+/**
+ * Should be called from UI thread only. If done so, the method **tries** to load the image synchronously.
+ * There is no guarantee, because in release mode we rely on `RCTImageLoader` implementation details.
+ * No matter how the image is loaded, `completionBlock` is executed on main queue.
+ */
+- (void)loadImageSyncFromImageSourceJson:(nonnull NSDictionary *)imageSourceJson
+                         withImageLoader:(nullable RCTImageLoader *)imageLoader
+                         completionBlock:
+                             (void (^_Nonnull)(NSError *_Nullable error, UIImage *_Nullable image))completion
+{
+  RCTAssert(RCTIsMainQueue(), @"[RNScreens] Expected to run on main queue");
+
+  RCTImageSource *imageSource = [RCTConvert RCTImageSource:imageSourceJson];
+  RCTAssert(imageSource != nil, @"[RNScreens] Expected nonnill image source");
+
+  // We use `+ [RCTConvert UIImage:]` only in debug mode, because it is deprecated, however
+  // I haven't found different way to load image synchronously in debug other than
+  // writing the code manually.
+
+#if !defined(NDEBUG) // We're in debug mode here
+  if (!imageSource.packagerAsset) {
+    // This is rather unexpected. In debug mode local asset should be sourced from packager.
+    RCTLogWarn(@"[RNScreens] Unexpected case during image load: loading not a packager asset");
+  }
+
+  // Try to load anyway.
+  UIImage *loadedImage = [RCTConvert UIImage:imageSourceJson];
+  completion(nil, loadedImage);
+  return;
+#else // We're in release mode here
+  [imageLoader loadImageWithURLRequest:imageSource.request
+      size:imageSource.size
+      scale:imageSource.scale
+      clipped:true
+      resizeMode:RCTResizeModeContain
+      progressBlock:^(int64_t progress, int64_t total) {
+      }
+      partialLoadBlock:^(UIImage *_Nonnull image) {
+      }
+      completionBlock:^(NSError *_Nullable error, UIImage *_Nullable image) {
+        if (RCTIsMainQueue()) {
+          completion(error, image);
+        } else {
+          dispatch_async(dispatch_get_main_queue(), ^{
+            completion(error, image);
+          });
+        }
+      }];
+#endif
+}
+
 @end

ios/utils/extensions/RCTImageSource+AccessHiddenMembers.h

@@ -0,0 +1,9 @@
+#pragma once
+
+// This field should exist in extension in `RCTImageSource.m`
+
+@interface RCTImageSource (AccessHiddenMembers)
+
+@property (nonatomic, assign) BOOL packagerAsset;
+
+@end

react-navigation

@@ -1,6 +1,6 @@
 'use strict';
 
-import { View } from "react-native";
+import { View } from 'react-native';
 
 /* eslint-disable */
 
@@ -24,11 +24,11 @@ export function getShadowNodeWrapperAndTagFromRef(ref: View | null): {
     return {
       shadowNodeWrapper: null,
       tag: -1,
-    }
+    };
   }
   const internalRef = ref as unknown as HostInstance;
   return {
     shadowNodeWrapper: internalRef.__internalInstanceHandle.stateNode.node,
     tag: internalRef.__nativeTag,
-  }
+  };
 }