feat(iOS, Tabs): Migrate to UITab API for iOS >= 26.1

ios/tabs/RNSTabBarAppearanceCoordinator.mm

@@ -4,6 +4,7 @@
 #import <React/RCTLog.h>
 #import "RCTConvert+RNSTabs.h"
 #import "RNSConversions-Tabs.h"
+#import "RNSDefines.h"
 #import "RNSImageLoadingHelper.h"
 #import "RNSTabBarController.h"
 #import "RNSTabsHostComponentView.h"
@@ -56,6 +57,20 @@ - (void)configureTabBarItemForTabScreenController:(nonnull RNSTabsScreenViewCont
               withImageLoader:imageLoader];
 }
 
+/// Sets the normal icon on both the item (renders the iPhone bar) and the UITab (renders the
+/// iPad floating bar / sidebar, which never reads the item).
+- (void)setNormalImage:(nullable UIImage *)image
+         forTabBarItem:(nonnull UITabBarItem *)tabBarItem
+          ofScreenView:(nullable RNSTabsScreenComponentView *)screenView
+{
+  tabBarItem.image = image;
+#if RNS_UITAB_API_SDK_AVAILABLE
+  if (RNS_UITAB_API_ENABLED) {
+    screenView.controller.tab.image = image;
+  }
+#endif // RNS_UITAB_API_SDK_AVAILABLE
+}
+
 - (void)setIconsForTabBarItem:(UITabBarItem *)tabBarItem
                fromScreenView:(RNSTabsScreenComponentView *)screenView
               withImageLoader:(RCTImageLoader *_Nullable)imageLoader
@@ -67,13 +82,13 @@ - (void)setIconsForTabBarItem:(UITabBarItem *)tabBarItem
         if (image == nil) {
           RCTLogWarn(@"[RNScreens] Failed to load SF Symbol \"%@\" for tab bar item", screenView.iconResourceName);
         }
-        tabBarItem.image = image;
+        [self setNormalImage:image forTabBarItem:tabBarItem ofScreenView:screenView];
       } else {
         UIImage *image = [UIImage imageNamed:screenView.iconResourceName];
         if (image == nil) {
           RCTLogWarn(@"[RNScreens] Failed to load xcasset \"%@\" for tab bar item", screenView.iconResourceName);
         }
-        tabBarItem.image = image;
+        [self setNormalImage:image forTabBarItem:tabBarItem ofScreenView:screenView];
       }
     } else if (screenView.systemItem != RNSTabsScreenSystemItemNone) {
       // Restore default system item icon
@@ -85,9 +100,11 @@ - (void)setIconsForTabBarItem:(UITabBarItem *)tabBarItem
             (long)screenView.systemItem);
         return;
       }
-      tabBarItem.image = [[UITabBarItem alloc] initWithTabBarSystemItem:systemItem.value() tag:0].image;
+      UIImage *_Nullable systemItemImage =
+          [[UITabBarItem alloc] initWithTabBarSystemItem:systemItem.value() tag:0].image;
+      [self setNormalImage:systemItemImage forTabBarItem:tabBarItem ofScreenView:screenView];
     } else {
-      tabBarItem.image = nil;
+      [self setNormalImage:nil forTabBarItem:tabBarItem ofScreenView:screenView];
     }
 
     if (screenView.selectedIconResourceName != nil) {
@@ -141,7 +158,7 @@ - (void)setIconsForTabBarItem:(UITabBarItem *)tabBarItem
                                             forScreenView:weakScreenView];
                                  }];
     } else {
-      tabBarItem.image = nil;
+      [self setNormalImage:nil forTabBarItem:tabBarItem ofScreenView:screenView];
     }
 
     // Selected icon
@@ -183,7 +200,7 @@ - (void)updateTabBarItem:(nullable UITabBarItem *)tabBarItem
   if (isSelected) {
     tabBarItem.selectedImage = image;
   } else {
-    tabBarItem.image = image;
+    [self setNormalImage:image forTabBarItem:tabBarItem ofScreenView:screenView];
   }
 
   // A layout pass is required because the image might be loaded asynchronously,

ios/tabs/RNSTabBarItemCoordinator.h

@@ -0,0 +1,16 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+#import "RNSTabsScreenViewController.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface RNSTabBarItemCoordinator : NSObject
+
+- (void)createTabBarItemsForTabScreenControllers:(nullable NSArray<RNSTabsScreenViewController *> *)tabScreenCtrls;
+
+- (void)updateTabBarItemsForTabScreenControllers:(nullable NSArray<RNSTabsScreenViewController *> *)tabScreenCtrls;
+
+@end
+
+NS_ASSUME_NONNULL_END

ios/tabs/RNSTabBarItemCoordinator.mm

@@ -0,0 +1,143 @@
+#import "RNSTabBarItemCoordinator.h"
+#import <React/RCTLog.h>
+#import "RNSConversions-Tabs.h"
+#import "RNSDefines.h"
+#import "RNSTabsScreenComponentView.h"
+
+@implementation RNSTabBarItemCoordinator
+
+/**
+ * Creates UITabBarItem instance with set systemItem. Needs to be called before UITab creation for the same
+ * viewController.
+ */
+- (void)createTabBarItemsForTabScreenControllers:(nullable NSArray<RNSTabsScreenViewController *> *)tabScreenCtrls
+{
+  for (RNSTabsScreenViewController *tabScreenCtrl in tabScreenCtrls) {
+    RNSTabsScreenComponentView *screenView = tabScreenCtrl.tabScreenComponentView;
+    if (screenView == nil) {
+      RCTLogWarn(@"[RNScreens] Nullish component view of TabScreen while tab bar item creation!");
+      continue;
+    }
+
+    if (screenView.tabBarItemNeedsRecreation) {
+      screenView.tabBarItemNeedsRecreation = NO;
+      [self createTabBarItemForTabScreenController:tabScreenCtrl];
+    }
+  }
+}
+
+/**
+ * Updates the runtime properties of UITabBarItem: title and badge. If used with UITab API, it should be called after
+ * the tab is built.
+ */
+- (void)updateTabBarItemsForTabScreenControllers:(nullable NSArray<RNSTabsScreenViewController *> *)tabScreenCtrls
+{
+  for (RNSTabsScreenViewController *tabScreenCtrl in tabScreenCtrls) {
+    RNSTabsScreenComponentView *screenView = tabScreenCtrl.tabScreenComponentView;
+    if (screenView == nil) {
+      RCTLogWarn(@"[RNScreens] Nullish component view of TabScreen while tab bar item update!");
+      continue;
+    }
+
+    if (screenView.tabBarItemNeedsUpdate) {
+      screenView.tabBarItemNeedsUpdate = NO;
+      [self updateTabBarItemForTabScreenController:tabScreenCtrl];
+    }
+  }
+}
+
+- (void)createTabBarItemForTabScreenController:(nonnull RNSTabsScreenViewController *)tabScreenCtrl
+{
+  RNSTabsScreenComponentView *screenView = tabScreenCtrl.tabScreenComponentView;
+
+  UITabBarItem *tabBarItem = nil;
+  if (screenView.systemItem != RNSTabsScreenSystemItemNone) {
+    std::optional<UITabBarSystemItem> systemItem =
+        rnscreens::conversion::RNSTabsScreenSystemItemToUITabBarSystemItem(screenView.systemItem);
+    if (!systemItem) {
+      RCTLogError(
+          @"[RNScreens] Conversion from tabs screen systemItem to UITabBarSystemItem failed for systemItem [%ld]",
+          (long)screenView.systemItem);
+      return;
+    }
+    tabBarItem = [[UITabBarItem alloc] initWithTabBarSystemItem:systemItem.value() tag:0];
+  } else {
+    tabBarItem = [[UITabBarItem alloc] init];
+  }
+
+  [self applyTabBarItemRepaintWorkaroundForTabScreenController:tabScreenCtrl];
+  tabScreenCtrl.tabBarItem = tabBarItem;
+}
+
+/**
+ * TODO: This is an ugly workaround and I would love to see it replaced.
+ * With UITab-managed children (iOS >= 26.1) any change to the systemItem for the first time
+ * results in missing icon and wrong title. Assigning a throwaway item first flips the internal logic
+ * so that the real assignment that follows paints synchronously.
+ * Remove once UIKit internals no longer require it.
+ */
+- (void)applyTabBarItemRepaintWorkaroundForTabScreenController:(nonnull RNSTabsScreenViewController *)tabScreenCtrl
+{
+#if RNS_UITAB_API_SDK_AVAILABLE
+  if (RNS_UITAB_API_ENABLED) {
+    tabScreenCtrl.tabBarItem = [[UITabBarItem alloc] init];
+  }
+#endif // RNS_UITAB_API_SDK_AVAILABLE
+}
+
+- (void)updateTabBarItemForTabScreenController:(nonnull RNSTabsScreenViewController *)tabScreenCtrl
+{
+  RNSTabsScreenComponentView *screenView = tabScreenCtrl.tabScreenComponentView;
+
+  NSString *evaluatedTitle = screenView.title;
+  if (screenView.title == nil && screenView.systemItem != RNSTabsScreenSystemItemNone) {
+    // Restore default system item title
+    std::optional<UITabBarSystemItem> systemItem =
+        rnscreens::conversion::RNSTabsScreenSystemItemToUITabBarSystemItem(screenView.systemItem);
+    if (!systemItem) {
+      RCTLogError(
+          @"[RNScreens] Conversion from tabs screen systemItem to UITabBarSystemItem failed for systemItem [%ld]",
+          (long)screenView.systemItem);
+      return;
+    }
+    evaluatedTitle = [[UITabBarItem alloc] initWithTabBarSystemItem:systemItem.value() tag:0].title;
+  }
+
+  [self updateTabBarItemTitle:evaluatedTitle forTabScreenController:tabScreenCtrl];
+  [self updateTabBarItemBadge:screenView.badgeValue forTabScreenController:tabScreenCtrl];
+}
+
+- (void)updateTabBarItemTitle:(NSString *)newTitle
+       forTabScreenController:(nonnull RNSTabsScreenViewController *)tabScreenCtrl
+{
+  // Setting controller title updates also controller's tabBarItem.title but only if there
+  // is a change to controller title. After creating new tabBarItem, controller title
+  // remains the same but tabBarItem.title is nil. For consistency, we always
+  // update both.
+  if (![tabScreenCtrl.tabBarItem.title isEqualToString:newTitle] || ![tabScreenCtrl.title isEqualToString:newTitle]) {
+    tabScreenCtrl.title = newTitle;
+    tabScreenCtrl.tabBarItem.title = newTitle;
+#if RNS_UITAB_API_SDK_AVAILABLE
+    if (RNS_UITAB_API_ENABLED) {
+      // iPad sources the rendered title from the tab, not the item.
+      tabScreenCtrl.tab.title = newTitle;
+    }
+#endif // RNS_UITAB_API_SDK_AVAILABLE
+  }
+}
+
+- (void)updateTabBarItemBadge:(NSString *)badgeValue
+       forTabScreenController:(nonnull RNSTabsScreenViewController *)tabScreenCtrl
+{
+  if (![tabScreenCtrl.tabBarItem.badgeValue isEqualToString:badgeValue]) {
+    // The badge must land on both the item (viewController API) and the tab (UITab API) to render.
+    tabScreenCtrl.tabBarItem.badgeValue = badgeValue;
+#if RNS_UITAB_API_SDK_AVAILABLE
+    if (RNS_UITAB_API_ENABLED) {
+      tabScreenCtrl.tab.badgeValue = badgeValue;
+    }
+#endif // RNS_UITAB_API_SDK_AVAILABLE
+  }
+}
+
+@end

ios/tabs/host/RNSTabBarController.h

@@ -4,6 +4,7 @@
 #import "RNSContainer.h"
 #import "RNSReactMountingTransactionObserving.h"
 #import "RNSTabBarAppearanceCoordinator.h"
+#import "RNSTabBarItemCoordinator.h"
 #import "RNSTabsNavigationState.h"
 #import "RNSTabsScreenViewController.h"
 
@@ -117,6 +118,8 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property (nonatomic, readonly, strong, nonnull) RNSTabBarAppearanceCoordinator *tabBarAppearanceCoordinator;
 
+@property (nonatomic, readonly, strong, nonnull) RNSTabBarItemCoordinator *tabBarItemCoordinator;
+
 /**
  * If true, the controller will reject any navigation state updates if the provenance of the
  * update is stale.