feat(iOS, SplitView): Add support for preferredDisplayMode prop (#3000)

## Description

Closes
software-mansion/react-native-screens-labs#223

This property specifies the display mode which will be preferred to use
in SplitView, when the layout requirements are met.

Possible DisplayMode values:

- `secondaryOnly` - only the secondary column is displayed
- `oneBesideSecondary` - a sidebar is displayed side-by-side with the
secondary column
- `twoBesideSecondary` - two sidebars are displayed side-by-side with
the secondary column
- `oneOverSecondary` - a one sidebar is displayed over the secondary
column
- `twoOverSecondary` - two sidebars are displayed over the secondary
column
- `twoDisplaceSecondary` - two sidebars are displacind the secondary
column, moving it partially offscreen
- `automatic` - leaving the choice to OS (default)

## Changes

- Added prop definition in TS
- Added enums and converters on the native side
- Included new prop in `updateProps` and `resetProps` methods
- Added warning for non-matching splitBehavior-displayMode pairs

## Test code and steps to reproduce

`SplitViewBaseApp` was updated to cover the specific prop.


https://github.com/user-attachments/assets/c722cfb3-f066-4b21-9e45-cbb156ac0220

## Checklist

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

Closes: #223

Author: t0maboro

apps/src/tests/TestSplitView/SplitViewBaseApp.tsx

@@ -23,7 +23,7 @@ const SplitViewBaseApp = () => {
   const [buttonState4, setButtonState4] = React.useState('Initial');
 
   return (
-    <SplitViewHost splitBehavior='tile' primaryEdge='leading'>
+    <SplitViewHost displayMode='oneOverSecondary' primaryEdge='leading' splitBehavior='tile'>
       <SplitViewScreen>
         <View style={[styles.container, { backgroundColor: Colors.RedDark100 }]}>
           <TestButton setButtonState={setButtonState} />

ios/RNSEnums.h

@@ -73,20 +73,6 @@ typedef NS_ENUM(NSInteger, RNSSearchBarPlacement) {
   RNSSearchBarPlacementStacked,
 };
 
-#pragma mark - SplitView
-
-typedef NS_ENUM(NSInteger, RNSSplitViewSplitBehavior) {
-  RNSSplitViewSplitBehaviorAutomatic,
-  RNSSplitViewSplitBehaviorDisplace,
-  RNSSplitViewSplitBehaviorOverlay,
-  RNSSplitViewSplitBehaviorTile,
-};
-
-typedef NS_ENUM(NSInteger, RNSSplitViewPrimaryEdge) {
-  RNSSplitViewPrimaryEdgeLeading,
-  RNSSplitViewPrimaryEdgeTrailing
-};
-
 // Redefinition of UIBlurEffectStyle. We need to represent additional case of `None`.
 typedef NS_ENUM(NSInteger, RNSBlurEffectStyle) {
   /// No blur effect should be visible

ios/conversion/RNSConversions-SplitView.mm

@@ -4,65 +4,59 @@
 
 #pragma mark RN Codegen enum to internal enum conversions
 
-RNSSplitViewSplitBehavior RNSSplitViewSplitBehaviorFromHostProp(
+UISplitViewControllerSplitBehavior SplitViewSplitBehaviorFromHostProp(
     facebook::react::RNSSplitViewHostSplitBehavior splitBehavior)
 {
   using enum facebook::react::RNSSplitViewHostSplitBehavior;
-  
+
   switch (splitBehavior) {
     case Displace:
-      return RNSSplitViewSplitBehaviorDisplace;
+      return UISplitViewControllerSplitBehaviorDisplace;
     case Overlay:
-      return RNSSplitViewSplitBehaviorOverlay;
+      return UISplitViewControllerSplitBehaviorOverlay;
     case Tile:
-      return RNSSplitViewSplitBehaviorTile;
+      return UISplitViewControllerSplitBehaviorTile;
     case Automatic:
     default:
-      return RNSSplitViewSplitBehaviorAutomatic;
+      return UISplitViewControllerSplitBehaviorAutomatic;
   }
 }
 
-RNSSplitViewPrimaryEdge RNSSplitViewPrimaryEdgeFromHostProp(
+UISplitViewControllerPrimaryEdge SplitViewPrimaryEdgeFromHostProp(
     facebook::react::RNSSplitViewHostPrimaryEdge primaryEdge)
 {
   using enum facebook::react::RNSSplitViewHostPrimaryEdge;
-  
+
   switch (primaryEdge) {
     case Trailing:
-      return RNSSplitViewPrimaryEdgeTrailing;
+      return UISplitViewControllerPrimaryEdgeTrailing;
     case Leading:
     default:
-      return RNSSplitViewPrimaryEdgeLeading;
-  }
-}
-
-#pragma mark Internal enum to UISplitViewController enum conversions
-
-UISplitViewControllerSplitBehavior RNSSplitBehaviorToUISplitViewControllerSplitBehavior(
-    RNSSplitViewSplitBehavior behavior)
-{
-  switch (behavior) {
-    case RNSSplitViewSplitBehaviorDisplace:
-      return UISplitViewControllerSplitBehaviorDisplace;
-    case RNSSplitViewSplitBehaviorOverlay:
-      return UISplitViewControllerSplitBehaviorOverlay;
-    case RNSSplitViewSplitBehaviorTile:
-      return UISplitViewControllerSplitBehaviorTile;
-    case RNSSplitViewSplitBehaviorAutomatic:
-    default:
-      return UISplitViewControllerSplitBehaviorAutomatic;
+      return UISplitViewControllerPrimaryEdgeLeading;
   }
 }
 
-UISplitViewControllerPrimaryEdge RNSPrimaryEdgeToUISplitViewControllerPrimaryEdge(
-    RNSSplitViewPrimaryEdge primaryEdge)
+UISplitViewControllerDisplayMode SplitViewDisplayModeFromHostProp(
+    facebook::react::RNSSplitViewHostDisplayMode displayMode)
 {
-  switch (primaryEdge) {
-    case RNSSplitViewPrimaryEdgeTrailing:
-      return UISplitViewControllerPrimaryEdgeTrailing;
-    case RNSSplitViewPrimaryEdgeLeading:
+  using enum facebook::react::RNSSplitViewHostDisplayMode;
+
+  switch (displayMode) {
+    case SecondaryOnly:
+      return UISplitViewControllerDisplayModeSecondaryOnly;
+    case OneBesideSecondary:
+      return UISplitViewControllerDisplayModeOneBesideSecondary;
+    case OneOverSecondary:
+      return UISplitViewControllerDisplayModeOneOverSecondary;
+    case TwoBesideSecondary:
+      return UISplitViewControllerDisplayModeTwoBesideSecondary;
+    case TwoOverSecondary:
+      return UISplitViewControllerDisplayModeTwoOverSecondary;
+    case TwoDisplaceSecondary:
+      return UISplitViewControllerDisplayModeTwoDisplaceSecondary;
+    case Automatic:
     default:
-      return UISplitViewControllerPrimaryEdgeLeading;
+      return UISplitViewControllerDisplayModeAutomatic;
   }
 }
 

ios/conversion/RNSConversions.h

@@ -32,19 +32,15 @@ UIOffset RNSBottomTabsScreenTabBarItemTitlePositionAdjustmentStruct(
 
 #pragma mark SplitView
 
-RNSSplitViewSplitBehavior RNSSplitViewSplitBehaviorFromHostProp(
-    react::RNSSplitViewHostSplitBehavior);
+UISplitViewControllerSplitBehavior SplitViewSplitBehaviorFromHostProp(
+    react::RNSSplitViewHostSplitBehavior behavior);
 
-RNSSplitViewPrimaryEdge RNSSplitViewPrimaryEdgeFromHostProp(
-    react::RNSSplitViewHostPrimaryEdge);
+UISplitViewControllerPrimaryEdge SplitViewPrimaryEdgeFromHostProp(
+    react::RNSSplitViewHostPrimaryEdge primaryEdge);
 
-UISplitViewControllerSplitBehavior
-RNSSplitBehaviorToUISplitViewControllerSplitBehavior(
-    RNSSplitViewSplitBehavior behavior);
+UISplitViewControllerDisplayMode SplitViewDisplayModeFromHostProp(
+    react::RNSSplitViewHostDisplayMode displayMode);
 
-UISplitViewControllerPrimaryEdge
-RNSPrimaryEdgeToUISplitViewControllerPrimaryEdge(
-    RNSSplitViewPrimaryEdge primaryEdge);
 }; // namespace rnscreens::conversion
 
 #endif

ios/gamma/split-view/RNSSplitViewHostComponentView.h

@@ -18,8 +18,9 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface RNSSplitViewHostComponentView ()
 
-@property (nonatomic, readonly) RNSSplitViewSplitBehavior splitBehavior;
-@property (nonatomic, readonly) RNSSplitViewPrimaryEdge primaryEdge;
+@property (nonatomic, readonly) UISplitViewControllerSplitBehavior splitBehavior;
+@property (nonatomic, readonly) UISplitViewControllerPrimaryEdge primaryEdge;
+@property (nonatomic, readonly) UISplitViewControllerDisplayMode displayMode;
 
 @end
 

ios/gamma/split-view/RNSSplitViewHostComponentView.mm

@@ -46,8 +46,9 @@ - (void)resetProps
   static const auto defaultProps = std::make_shared<const react::RNSSplitViewHostProps>();
   _props = defaultProps;
 
-  _splitBehavior = RNSSplitViewSplitBehaviorAutomatic;
-  _primaryEdge = RNSSplitViewPrimaryEdgeLeading;
+  _splitBehavior = UISplitViewControllerSplitBehaviorAutomatic;
+  _primaryEdge = UISplitViewControllerPrimaryEdgeLeading;
+  _displayMode = UISplitViewControllerDisplayModeAutomatic;
 }
 
 - (void)didMoveToWindow
@@ -140,15 +141,18 @@ - (void)updateProps:(const facebook::react::Props::Shared &)props
   const auto &newComponentProps = *std::static_pointer_cast<const react::RNSSplitViewHostProps>(props);
 
   if (oldComponentProps.splitBehavior != newComponentProps.splitBehavior) {
-    _splitBehavior = rnscreens::conversion::RNSSplitViewSplitBehaviorFromHostProp(newComponentProps.splitBehavior);
-    _controller.preferredSplitBehavior =
-        rnscreens::conversion::RNSSplitBehaviorToUISplitViewControllerSplitBehavior(_splitBehavior);
+    _splitBehavior = rnscreens::conversion::SplitViewSplitBehaviorFromHostProp(newComponentProps.splitBehavior);
+    _controller.preferredSplitBehavior = _splitBehavior;
   }
 
   if (oldComponentProps.primaryEdge != newComponentProps.primaryEdge) {
-    _primaryEdge = rnscreens::conversion::RNSSplitViewPrimaryEdgeFromHostProp(newComponentProps.primaryEdge);
-    _controller.primaryEdge =
-        rnscreens::conversion::RNSPrimaryEdgeToUISplitViewControllerPrimaryEdge(_primaryEdge);
+    _primaryEdge = rnscreens::conversion::SplitViewPrimaryEdgeFromHostProp(newComponentProps.primaryEdge);
+    _controller.primaryEdge = _primaryEdge;
+  }
+
+  if (oldComponentProps.displayMode != newComponentProps.displayMode) {
+    _displayMode = rnscreens::conversion::SplitViewDisplayModeFromHostProp(newComponentProps.displayMode);
+    _controller.preferredDisplayMode = _displayMode;
   }
 
   [super updateProps:props oldProps:oldProps];

src/components/gamma/SplitViewHost.tsx

@@ -4,22 +4,76 @@ import type { ViewProps } from 'react-native';
 import SplitViewHostNativeComponent from '../../fabric/gamma/SplitViewHostNativeComponent';
 import type {
   NativeProps,
+  SplitViewDisplayMode,
   SplitViewSplitBehavior,
 } from '../../fabric/gamma/SplitViewHostNativeComponent';
 
 export type SplitViewNativeProps = NativeProps & {
   // SplitView appearance
 
+  displayMode?: SplitViewDisplayMode;
   splitBehavior?: SplitViewSplitBehavior;
 };
 
 type SplitViewHostProps = {
   children?: ViewProps['children'];
 } & SplitViewNativeProps;
 
-function SplitViewHost({ children, splitBehavior, primaryEdge }: SplitViewHostProps) {
+// According to the UIKit documentation: https://developer.apple.com/documentation/uikit/uisplitviewcontroller/displaymode-swift.enum
+// Only specific pairs for displayMode - splitBehavior are valid and others may lead to unexpected results.
+// Therefore, we're adding check on the JS side to return a feedback to the client when that pairing isn't valid.
+// However, we're not blocking these props to be set on the native side, because it doesn't crash, just the result or transitions may not work as expected.
+const displayModeForSplitViewCompatibilityMap: Record<
+  SplitViewSplitBehavior,
+  SplitViewDisplayMode[]
+> = {
+  tile: ['secondaryOnly', 'oneBesideSecondary', 'twoBesideSecondary'],
+  overlay: ['secondaryOnly', 'oneOverSecondary', 'twoOverSecondary'],
+  displace: ['secondaryOnly', 'oneBesideSecondary', 'twoDisplaceSecondary'],
+  automatic: [], // placeholder for satisfying types; we'll handle it specially in logic
+};
+
+const isValidDisplayModeForSplitBehavior = (
+  displayMode: SplitViewDisplayMode,
+  splitBehavior: SplitViewSplitBehavior,
+) => {
+  if (splitBehavior === 'automatic') {
+    // for automatic we cannot easily verify the compatibility, because it depends on the system preference for display mode, therefore we're assuming that 'automatic' has only valid combinations
+    return true;
+  }
+  return displayModeForSplitViewCompatibilityMap[splitBehavior].includes(
+    displayMode,
+  );
+};
+
+function SplitViewHost({
+  children,
+  displayMode,
+  primaryEdge,
+  splitBehavior,
+}: SplitViewHostProps) {
+  React.useEffect(() => {
+    if (displayMode && splitBehavior) {
+      const isValid = isValidDisplayModeForSplitBehavior(
+        displayMode,
+        splitBehavior,
+      );
+      if (!isValid) {
+        const validDisplayModes =
+          displayModeForSplitViewCompatibilityMap[splitBehavior];
+        console.warn(
+          `Invalid display mode "${displayMode}" for split behavior "${splitBehavior}".` +
+            `\nValid modes for "${splitBehavior}" are: ${validDisplayModes.join(
+              ', ',
+            )}.`,
+        );
+      }
+    }
+  }, [displayMode, splitBehavior]);
+
   return (
     <SplitViewHostNativeComponent
+      displayMode={displayMode}
       style={styles.container}
       splitBehavior={splitBehavior}
       primaryEdge={primaryEdge}>

src/fabric/gamma/SplitViewHostNativeComponent.ts

@@ -12,8 +12,19 @@ export type SplitViewSplitBehavior =
 
 export type SplitViewPrimaryEdge = 'leading' | 'trailing';
 
+export type SplitViewDisplayMode =
+  | 'automatic'
+  | 'secondaryOnly'
+  | 'oneBesideSecondary'
+  | 'oneOverSecondary'
+  | 'twoBesideSecondary'
+  | 'twoOverSecondary'
+  | 'twoDisplaceSecondary';
+
 export interface NativeProps extends ViewProps {
   // Appearance
+
+  displayMode?: WithDefault<SplitViewDisplayMode, 'automatic'>;
   splitBehavior?: WithDefault<SplitViewSplitBehavior, 'automatic'>;
   primaryEdge?: WithDefault<SplitViewPrimaryEdge, 'leading'>;
 }