fix(iOS, Tabs): Request layout pass after loading image from source (#3596)

## Description

Before assigning the image, the tab bar might already be attached to the
view hierarchy. This can cause an issue where the tab bar layout is not
correctly updated, as it might have been added to the window before the
image was set. As a result, the layout adjustments (e.g., image
positioning) are not applied immediately.

To resolve this, we explicitly request an additional layout pass after
the image is assigned. This ensures that the tab bar updates its layout
properly without requiring user interaction (e.g., switching tabs) to
trigger a recalculation.

The issue is illustrated in the image below.

<img width="405" height="848" alt="before-image"
src="https://github.com/user-attachments/assets/a1f45277-86b5-491b-a31b-5e146ee5a782"
/>

## Changes

- Add layout request in the completion callback when the image is loaded
from source.
- Add example & assets demonstrating the issue.

## Before & after - visual documentation

| Before | After |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/bcaedb0f-ded8-482e-9402-7c178c50773c"
/> | <video
src="https://github.com/user-attachments/assets/7e8dd72a-e496-4af4-9606-50cc5b9a1277"
/> |

## Test plan

Added Test3596, performed regression testing on TestBottomTabs

## Checklist

- [x] Included code example that can be used to test this change.
- [ ] Updated / created local changelog entries in relevant test files.
- [x] For visual changes, included screenshots / GIFs / recordings
documenting the change.
- [ ] For API changes, updated relevant public types.
- [x] Ensured that CI passes

---------

Co-authored-by: Kacper Kafara <kacper.kafara@swmansion.com>

Author: t0maboro

apps/assets/variableIcons/globe_oversized@1x.png

@@ -0,0 +1,83 @@
+import React from 'react';
+
+import { enableFreeze } from 'react-native-screens';
+import ConfigWrapperContext, {
+  type Configuration,
+  DEFAULT_GLOBAL_CONFIGURATION,
+} from '../../shared/gamma/containers/bottom-tabs/ConfigWrapperContext';
+import {
+  BottomTabsContainer,
+  type TabConfiguration,
+} from '../../shared/gamma/containers/bottom-tabs/BottomTabsContainer';
+import { CenteredLayoutView } from '../../shared/CenteredLayoutView';
+import { Text } from 'react-native';
+import Colors from '../../shared/styling/Colors';
+
+enableFreeze(true);
+
+const ICON = require('../../../assets/variableIcons/globe_oversized.png');
+
+function makeTab(title: string) {
+  return function Tab() {
+    return (
+      <CenteredLayoutView style={{backgroundColor: Colors.PurpleLight60}}>
+        <Text>{title}</Text>
+      </CenteredLayoutView>
+    );
+  };
+}
+
+const TAB_CONFIGS: TabConfiguration[] = [
+  {
+    tabScreenProps: {
+      tabKey: 'Tab1',
+      title: 'Tab 1',
+      icon: {
+        shared: {
+          type: 'imageSource',
+          imageSource: ICON,
+        },
+      },
+    },
+    component: makeTab('Tab 1'),
+  },
+  {
+    tabScreenProps: {
+      tabKey: 'Tab2',
+      title: 'Tab 2',
+      icon: {
+        shared: {
+          type: 'imageSource',
+          imageSource: ICON,
+        },
+      },
+    },
+    component: makeTab('Tab 2'),
+  },
+  {
+    tabScreenProps: {
+      tabKey: 'Tab3',
+      title: 'Tab 3',
+      systemItem: 'search',
+    },
+    component: makeTab('Tab 3'),
+  },
+];
+
+function App() {
+  const [config, setConfig] = React.useState<Configuration>(
+    DEFAULT_GLOBAL_CONFIGURATION,
+  );
+
+  return (
+    <ConfigWrapperContext.Provider
+      value={{
+        config,
+        setConfig,
+      }}>
+      <BottomTabsContainer tabConfigs={TAB_CONFIGS} />
+    </ConfigWrapperContext.Provider>
+  );
+}
+
+export default App;

apps/assets/variableIcons/globe_oversized@2x.png

@@ -179,6 +179,7 @@ export { default as Test3522 } from './Test3522';
 export { default as Test3564 } from './Test3564';
 export { default as Test3566 } from './Test3566';
 export { default as Test3576 } from './Test3576';
+export { default as Test3596 } from './Test3596';
 export { default as TestScreenAnimation } from './TestScreenAnimation';
 // The following test was meant to demo the "go back" gesture using Reanimated
 // but the associated PR in react-navigation is currently put on hold

apps/assets/variableIcons/globe_oversized@3x.png

@@ -97,7 +97,10 @@ - (void)setIconsForTabBarItem:(UITabBarItem *)tabBarItem
                                  withImageLoader:imageLoader
                                       asTemplate:isTemplate
                                  completionBlock:^(UIImage *image) {
-                                   tabBarItem.image = image;
+                                   [self updateTabBarItem:tabBarItem
+                                                withImage:image
+                                               isSelected:NO
+                                            forScreenView:screenView];
                                  }];
     } else {
       tabBarItem.image = nil;
@@ -109,7 +112,10 @@ - (void)setIconsForTabBarItem:(UITabBarItem *)tabBarItem
                                  withImageLoader:imageLoader
                                       asTemplate:isTemplate
                                  completionBlock:^(UIImage *image) {
-                                   tabBarItem.selectedImage = image;
+                                   [self updateTabBarItem:tabBarItem
+                                                withImage:image
+                                               isSelected:YES
+                                            forScreenView:screenView];
                                  }];
     } else {
       tabBarItem.selectedImage = nil;
@@ -119,6 +125,29 @@ - (void)setIconsForTabBarItem:(UITabBarItem *)tabBarItem
   }
 }
 
+- (void)updateTabBarItem:(UITabBarItem *)tabBarItem
+               withImage:(UIImage *)image
+              isSelected:(BOOL)isSelected
+           forScreenView:(RNSBottomTabsScreenComponentView *)screenView
+{
+  if (isSelected) {
+    tabBarItem.selectedImage = image;
+  } else {
+    tabBarItem.image = image;
+  }
+
+  // A layout pass is required because the image might be loaded asynchronously,
+  // after the tab bar has already been attached to the window.
+  // This code handles case where image passed by the user is not 
+  // of appropriate size & needs to be readjusted. W/o additional 
+  // layout here the icon would be displayed with original dimensions.
+  UIViewController *parent = screenView.controller.parentViewController;
+  if ([parent isKindOfClass:[UITabBarController class]]) {
+    UITabBarController *tabBarVC = (UITabBarController *)parent;
+    [tabBarVC.tabBar setNeedsLayout];
+  }
+}
+
 + (void)configureTabBarAppearance:(nonnull UITabBarAppearance *)tabBarAppearance
               fromAppearanceProps:(nonnull NSDictionary *)appearanceProps
 {