feat(iOS): add support for using native behavior in hideNavigationBar, obscureBackground props in SearchBar

[kligarski]

Description

Follow-up to #3199.

Adds support for using native behavior in hideNavigationBar, obscureBackground props in SearchBar.

This will require changes in react-navigation docs - ticket for this: https://github.com/software-mansion/react-native-screens-labs/issues/384.

Values table

obscureBackground JS prop (initial)	prop value passed to native	controller setting
undefined	RNSOptionalBooleanUndefined	native behavior
true	RNSOptionalBooleanTrue	true
false	RNSOptionalBooleanFalse	false

Changes from true/false to undefined in runtime are unsupported.

Native behavior

obscureBackground

/* On iOS, default is NO for apps linked on iOS 15.0 and later, YES otherwise.
 On tvOS, default is NO when contained in UISearchContainerViewController, YES otherwise.
 */
@property (nonatomic, assign) BOOL obscuresBackgroundDuringPresentation API_AVAILABLE(ios(9.1));

hideNavigationBar

/// Default is `YES` for apps linked before iOS 26.0, other than on MacCatalyst, where the default is `NO`.
/// On iOS 26.0 for apps linked on iOS 26.0 and later, the value is determined by context unless directly set through the API. The default remains `NO` on MacCatalyst.
@property (nonatomic, assign) BOOL hidesNavigationBarDuringPresentation;

Closes https://github.com/software-mansion/react-native-screens-labs/issues/415.

Changes

• change native component to use enum for obscureBackground and hideNavigationBar
• add util converting boolean | undefined to 'undefined' | 'true' | 'false'
• add RNSOptionalBoolean enum and conversions for Paper and Fabric
• change native prop setters to handle enum
• add warning for dynamic change back to undefined

Test code and steps to reproduce

Run Test758. You can comment out obscureBackground, hideNavigationBar props before running the test.

Checklist

• Included code example that can be used to test this change
• Updated TS types
• Updated documentation:
  • 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

[kmichalikk]

It should be relatively easy to refactor out to some helper function

[kligarski]

As discussed internally, we decided to leave it as it is for now to maintain readability. If we use RNSOptionalBoolean more in the future, we can consider creating a macro.

[kkafar]

Beside the fact, that we could maybe refactor out some parts in RNSSearchBar implementation, this PR looks really good. Thank you! Let's create follow-up for react-navigation.