[jamesreggio]

This PR exposes three static methods (pushStackEntry, popStackEntry, and replaceStackEntry) on StatusBar that enable imperative manipulation of the StatusBar style within the stack established by mounted StatusBar components.

Motivation:

The StatusBar component provides a sensible API for manipulating that StatusBar style: every time a StatusBar component is mounted, its props are pushed onto a stack, and the props from the most recently mounted component are applied.

However, there are some scenarios where you may need to manipulate the StatusBar style from imperative code — particularly when invoking imperative third-party APIs that cause UI to appear. (For example, a user feedback utility or bug reporter that launches a full-screen modal.)

In modern iOS development, UIViewControllerBasedStatusBarAppearance is typically set to YES, which allows the third-party UIViewController to specify its preferred status bar style. However, as has been discussed at length in #11710, React Native has disabled this setting, which means that either the app's code or the third-party's React Native wrapper needs to manually manipulate React Native's StatusBar API to achieve the desired outcome.

The existing imperative StatusBar APIs are not a good fit for these needs because they simply overwrite the existing StatusBar styles, and provide no means of reverting StatusBar style changes when the third-party UI is dismissed.

To improve upon this situation, this PR makes it possible to call StatusBar.pushStackEntry before launching the third-party UI, wait for the UI to dismiss, and then call StatusBar.popStackEntry (supplying the token returned from the push call).

I've featured the new stack-based imperative methods in the documentation, but stopped short of explicitly deprecating the older imperative methods — though I can think of no reason not to deprecate them. Feedback is welcome on this point.

Test Plan:

We've been using this patch in our production app without issue since February 2018.

I've recorded a video that shows the that the imperatively-pushed StatusBar stack entries interface correctly with mounted StatusBar components. You can see the code for this example here (though you'll need to apply this PR to run it).

Release Notes:

[GENERAL] [ENHANCEMENT] [StatusBar] - Add static methods to manipulate StatusBar stack imperatively

[analysis-bot]

eslint found some issues. You may run yarn prettier or npm run prettier to fix these.

[jamesreggio]

Regarding @analysis-bot, my method documentation is consistent with the existing code. Resolving.

[hramos]

Thanks for the PR! Importing for further review.

If merged, we'll need to update the docs at https://github.com/facebook/react-native-website, but no need to send a PR there yet.

[facebook-github-bot]

hramos has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

[cpojer]

I just rebased and updated this internally and will land it in a moment. Your explanation makes sense to me, especially since React Native chose to limit this functionality in the first place as you described.

[react-native-bot]

@jamesreggio merged commit 01f1780 into facebook:master.