feat(iOS, Tabs, ScreenStack): orientation for Tabs and ScreenStack (#3014)

## Description

Adds orientation management for `Tabs`.

Closes
software-mansion/react-native-screens-labs#97.

Moved from
software-mansion/react-native-screens-labs#262.

Overriding `supportedInterfaceOrientaitons` for `TabBarController` and
`TabsScreenViewController` is not enough. UIKit calls these methods only
once and does not enforce orientation they return. UIKit asks root view
controller more often - that's why we already swizzled
`supportedInterfaceOrientations` to get access to return value from root
`UIViewController` (from react-native) in `ScreenStack` implementation
(useful article about [UIKit's
behavior](https://gist.github.com/SergLam/802dd8a354ff9b925bb3ede8cae1f644)).

I decided to use our own methods to handle orientation instead of
overriding `supportedInterfaceOrientations` for tabs-related view
controllers and use swizzled `supportedInterfaceOrientation` in root to
return appropriate orientation mask to UIKit.

In `ScreenStack`, `orientation: 'default'` is mapped to
`UIInterfaceOrientationMaskAllButUpsideDown` but this is correct only
for iPhones (e.g. iPads use `UIInterfaceOrientationMaskAll`). There is
no other option that maps to
`UIInterfaceOrientationMaskAllButUpsideDown`.

In new implementation, I added options for all
`UIInterfaceOrientationMask` enum values and changed `'default'` into
`'inherit'` to use as default value. This value means that view
controller does not have any preference for orientation. When root is
asked for `supportedInterfaceOrientations`, it checks if their last
child conforms to `RNSOrientationProviding`. If so, it asks the child
view controller for orientation. These calls are propagated down the
hierarchy with the last child having priority. If the last child returns
`Inherit`, view controller above returns its preference. If root
receives `Inherit`, it uses mask defined in `Info.plist`
([docs](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/application(_:supportedinterfaceorientationsfor:)?language=objc)),
otherwise it maps received `RNSOrientation` into
`UIInterfaceOrientationMask`.

For `ScreenStack`, we use old implementation of handling orientation at
the screen level (we map result from its
`supportedInterfaceOrientations` to `RNSOrientation`). Old stack does
not support new props, including `RNSOrientationInherit`.

### Example
```
UIViewController (React)
       |
       | last child view controller's orientation
       | or orientation from Info.plist
       |
RNSTabBarController
       |
       | selected view controller's orientation 
       | or RNSOrientationInherit
       |
RNSTabsScreenViewController
       |
       | last child view controller's orientation 
       | or orientation provided via prop (defaults to RNSOrientationInherit)
       |
RNSNavigationController
       |
       | top view controller's orientation 
       | or RNSOrientationInherit
       |
RNSScreen
       |
       | RNSOrientation mapped from UIInterfaceOrientationMask 
       | returned from supportedInterfaceOrientations (previous implementation)
       |
      ...
```

In the future, we need to implement orientation management for new
`Stack` implementation as well as `SplitView`. This should be
straightforward. `Stack` implementation will be a mix of old
`ScreenStack` and new `Tabs` implementations. `SplitView` implementation
should take into account orientation defined via prop at host
controller.

> [!NOTE]
> Changing orientation manually (editing and saving file) via config in
`TestBottomTabs.tsx` seems buggy but it is due to "Refreshing..." bar in
debug mode. If you change the prop in JS (e.g. with `setInterval`), it
works as expected.
> | Manually | In JS | 
> | --- | --- |
> | <video
src="https://github.com/user-attachments/assets/eef43c27-e6d0-475f-860e-6854e9b42c4f"
/> | <video
src="https://github.com/user-attachments/assets/5356a1ee-bb90-4811-a427-12a3e94109e4"
/> |

## Changes

- add `RNSOrientationProviding` protocol
- implement it for tabs and screenstack

## Test code and steps to reproduce

Run example app and switch between tabs/screens in nested stack.

## Checklist

- [x] Included code example that can be used to test this change
- [ ] Ensured that CI passes

Author: kligarski

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/TabScreenViewManager.kt

@@ -187,6 +187,11 @@ class TabScreenViewManager :
         view.iconResourceName = value
     }
 
+    override fun setOrientation(
+        view: TabScreen,
+        value: String?,
+    ) = Unit
+
     companion object {
         const val REACT_CLASS = "RNSBottomTabsScreen"
     }

android/src/paper/java/com/facebook/react/viewmanagers/RNSBottomTabsScreenManagerDelegate.java

@@ -63,6 +63,9 @@ public void setProperty(T view, String propName, @Nullable Object value) {
       case "title":
         mViewManager.setTitle(view, value == null ? null : (String) value);
         break;
+      case "orientation":
+        mViewManager.setOrientation(view, (String) value);
+        break;
       case "iconResourceName":
         mViewManager.setIconResourceName(view, value == null ? null : (String) value);
         break;

android/src/paper/java/com/facebook/react/viewmanagers/RNSBottomTabsScreenManagerInterface.java

@@ -28,6 +28,7 @@ public interface RNSBottomTabsScreenManagerInterface<T extends View>  {
   void setTabBarItemIconColor(T view, @Nullable Integer value);
   void setTabBarItemBadgeBackgroundColor(T view, @Nullable Integer value);
   void setTitle(T view, @Nullable String value);
+  void setOrientation(T view, @Nullable String value);
   void setIconResourceName(T view, @Nullable String value);
   void setTabBarItemBadgeTextColor(T view, @Nullable Integer value);
   void setIconType(T view, @Nullable String value);

apps/src/tests/TestBottomTabs/index.tsx

@@ -55,6 +55,7 @@ const TAB_CONFIGS: TabConfiguration[] = [
       tabBarItemIconColor: Colors.RedDark120,
       iconResourceName: 'sym_call_missed', // Android specific
       title: 'Tab2',
+      orientation: 'landscape',
     },
     component: Tab2,
   },
@@ -72,6 +73,7 @@ const TAB_CONFIGS: TabConfiguration[] = [
       },
       iconResourceName: 'sym_action_email', // Android specific
       title: 'Tab3',
+      orientation: 'portrait',
     },
     component: Tab3,
   },
@@ -87,6 +89,7 @@ const TAB_CONFIGS: TabConfiguration[] = [
       iconResourceName: 'sym_action_chat', // Android specific
       title: 'Tab4',
       badgeValue: '',
+      orientation: 'portrait',
     },
     component: Tab4,
   },

apps/src/tests/TestBottomTabs/tabs/Tab4.tsx

@@ -113,13 +113,14 @@ export function Tab4() {
         <Stack.Screen
           name="Screen1"
           component={Screen1}
-          options={{ headerTransparent: true }}
+          options={{ headerTransparent: true, orientation: 'landscape' }}
         />
         <Stack.Screen
           name="Screen2"
           component={Screen2}
           options={{
             headerLargeTitle: true,
+            orientation: 'default',
           }}
         />
         <Stack.Screen

ios/RNSEnums.h

@@ -140,3 +140,15 @@ typedef NS_ENUM(NSInteger, RNSTabBarMinimizeBehavior) {
   RNSTabBarMinimizeBehaviorOnScrollUp,
 };
 #endif
+
+typedef NS_ENUM(NSInteger, RNSOrientation) {
+  RNSOrientationInherit,
+  RNSOrientationAll,
+  RNSOrientationAllButUpsideDown,
+  RNSOrientationPortrait,
+  RNSOrientationPortraitUp,
+  RNSOrientationPortraitDown,
+  RNSOrientationLandscape,
+  RNSOrientationLandscapeLeft,
+  RNSOrientationLandscapeRight,
+};

ios/RNSOrientationProviding.h

@@ -0,0 +1,11 @@
+#import "RNSEnums.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol RNSOrientationProviding
+
+- (RNSOrientation)evaluateOrientation;
+
+@end
+
+NS_ASSUME_NONNULL_END

ios/RNSScreen.h

@@ -6,6 +6,10 @@
 #import "RNSScreenContentWrapper.h"
 #import "RNSScrollViewBehaviorOverriding.h"
 
+#if !TARGET_OS_TV
+#import "RNSOrientationProviding.h"
+#endif // !TARGET_OS_TV
+
 #if RCT_NEW_ARCH_ENABLED
 #import <React/RCTViewComponentView.h>
 #else
@@ -33,8 +37,13 @@ namespace react = facebook::react;
 
 @class RNSScreenView;
 
-@interface RNSScreen : UIViewController <RNSViewControllerDelegate>
-
+@interface RNSScreen : UIViewController <
+                           RNSViewControllerDelegate
+#if !TARGET_OS_TV
+                           ,
+                           RNSOrientationProviding
+#endif // !TARGET_OS_TV
+                           >
 - (instancetype)initWithView:(UIView *)view;
 - (UIViewController *)findChildVCForConfigAndTrait:(RNSWindowTrait)trait includingModals:(BOOL)includingModals;
 - (BOOL)hasNestedStack;

ios/RNSScreen.mm

@@ -28,6 +28,7 @@
 #import <React/RCTUIManager.h>
 #import <React/RCTUIManagerUtils.h>
 
+#import "RNSConversions.h"
 #import "RNSScreenFooter.h"
 #import "RNSScreenStack.h"
 #import "RNSScreenStackHeaderConfig.h"
@@ -1979,6 +1980,26 @@ - (void)presentViewController:(UIViewController *)viewControllerToPresent
   [super presentViewController:viewControllerToPresent animated:flag completion:completion];
 }
 
+#pragma mark - RNSOrientationProviding
+
+#if !TARGET_OS_TV
+
+- (RNSOrientation)evaluateOrientation
+{
+  if ([self.childViewControllers.lastObject respondsToSelector:@selector(evaluateOrientation)]) {
+    id<RNSOrientationProviding> child = static_cast<id<RNSOrientationProviding>>(self.childViewControllers.lastObject);
+    RNSOrientation childOrientation = [child evaluateOrientation];
+
+    if (childOrientation != RNSOrientationInherit) {
+      return childOrientation;
+    }
+  }
+
+  return rnscreens::conversion::RNSOrientationFromUIInterfaceOrientationMask([self supportedInterfaceOrientations]);
+}
+
+#endif // !TARGET_OS_TV
+
 #ifdef RCT_NEW_ARCH_ENABLED
 #pragma mark - Fabric specific
 

ios/RNSScreenStack.h

@@ -8,6 +8,10 @@
 #import "RNSBottomTabsSpecialEffectsSupporting.h"
 #import "RNSScreenContainer.h"
 
+#if !TARGET_OS_TV
+#import "RNSOrientationProviding.h"
+#endif // !TARGET_OS_TV
+
 #ifdef RNS_GAMMA_ENABLED
 #import "RNSFrameCorrectionProvider.h"
 #endif // RNS_GAMMA_ENABLED
@@ -17,6 +21,10 @@ NS_ASSUME_NONNULL_BEGIN
 @interface RNSNavigationController : UINavigationController <
                                          RNSViewControllerDelegate,
                                          RNSBottomTabsSpecialEffectsSupporting
+#if !TARGET_OS_TV
+                                         ,
+                                         RNSOrientationProviding
+#endif // !TARGET_OS_TV
 #ifdef RNS_GAMMA_ENABLED
                                          ,
                                          RNSFrameCorrectionProvider