feat(statusbar): Simple built-in status bar background

This adds a background behind the status bar automatically when a page
does not request to extend itself behind the status bar using a meta tag
with `viewport-fit=cover`. It automatically shows and hides as the value
of the viewport-fit option changes.

On iOS 16.4 and newer, it will be coloured according to the meta
`theme-color` tag, and a default colour can be set in the storyboard for
a CDVViewController.

We expose a very basic JS API hanging off the existing
`window.statusbar` property that allows controlling the visibility (of
the status bar contents entirely, not just of the background view) and
overriding the background colour.

The colour is determined as follows:
  1. Any colour set explicitly with the JS API (if any)
  2. Any colour pulled from the meta tag (iOS 16.4+, if any)
  3. The default colour specified in the storyboard (if any)
  4. The background colour specified in the storyboard (if any)
  5. The default system background colour

Efforts were made to ensure that this does not interfere with the
existing CDVStatusBar plugin implementation (although maybe this can
replace it for most common use cases), by making the display of this
built-in conditional on not having the CDVStatusBar plugin installed.

CordovaLib/Classes/Private/CDVViewController+Private.h

@@ -0,0 +1,28 @@
+/*
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ */
+
+#import <Cordova/CDVViewController.h>
+
+@interface CDVViewController (Private)
+
+- (void)setStatusBarWebViewColor:(UIColor *)color;
+
+- (void)showStatusBar:(BOOL)visible;
+
+@end

CordovaLib/Classes/Private/Plugins/CDVLaunchScreen/CDVLaunchScreen.m

@@ -18,6 +18,7 @@ Licensed to the Apache Software Foundation (ASF) under one
  */
 
 #import "CDVLaunchScreen.h"
+#import "CDVViewController+Private.h"
 
 @implementation CDVLaunchScreen
 

CordovaLib/Classes/Private/Plugins/CDVStatusBarInternal/CDVStatusBarInternal.h

@@ -0,0 +1,28 @@
+/*
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ */
+
+#import <Cordova/CDVPlugin.h>
+
+@interface CDVStatusBarInternal : CDVPlugin
+
+- (void)setVisible:(CDVInvokedUrlCommand*)command;
+- (void)setBackgroundColor:(CDVInvokedUrlCommand*)command;
+
+@end
+

CordovaLib/Classes/Private/Plugins/CDVStatusBarInternal/CDVStatusBarInternal.m

@@ -0,0 +1,46 @@
+/*
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ */
+
+#import "CDVStatusBarInternal.h"
+#import "CDVViewController+Private.h"
+
+@implementation CDVStatusBarInternal
+
+- (void)setVisible:(CDVInvokedUrlCommand *)command
+{
+    id value = [command argumentAtIndex:0];
+    if (!([value isKindOfClass:[NSNumber class]])) {
+        value = [NSNumber numberWithBool:YES];
+    }
+
+    [self.viewController showStatusBar:[value boolValue]];
+}
+
+- (void)setBackgroundColor:(CDVInvokedUrlCommand *)command
+{
+    NSInteger valueR = [[command argumentAtIndex:0 withDefault:@0] integerValue];
+    NSInteger valueG = [[command argumentAtIndex:1 withDefault:@0] integerValue];
+    NSInteger valueB = [[command argumentAtIndex:2 withDefault:@0] integerValue];
+
+    UIColor *bgColor = [UIColor colorWithRed:valueR/255.f green:valueG/255.f blue:valueB/255.f alpha:1.f];
+    [self.viewController setStatusBarBackgroundColor:bgColor];
+}
+
+@end
+

CordovaLib/Classes/Private/Plugins/CDVWebViewEngine/CDVWebViewEngine.m

@@ -22,6 +22,7 @@ Licensed to the Apache Software Foundation (ASF) under one
 #import "CDVURLSchemeHandler.h"
 #import <Cordova/CDVWebViewProcessPoolFactory.h>
 #import <Cordova/CDVSettingsDictionary.h>
+#import "CDVViewController+Private.h"
 
 #import <objc/message.h>
 
@@ -242,6 +243,8 @@ - (void)pluginInitialize
         wkWebView.customUserAgent = [settings cordovaSettingForKey:@"OverrideUserAgent"];
     }
 
+    [wkWebView addObserver:self forKeyPath:@"themeColor" options:NSKeyValueObservingOptionInitial context:nil];
+
     self.engineWebView = wkWebView;
 
     if ([self.viewController conformsToProtocol:@protocol(WKUIDelegate)]) {
@@ -477,6 +480,15 @@ - (CDVWebViewPermissionGrantType)parsePermissionGrantType:(NSString*)optionStrin
     return result;
 }
 
+- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context
+{
+    if ([keyPath isEqualToString:@"themeColor"]) {
+        if (@available(iOS 15.0, *)) {
+            [self.viewController setStatusBarWebViewColor:((WKWebView *)self.engineWebView).themeColor];
+        }
+    }
+}
+
 #pragma mark - WKScriptMessageHandler implementation
 
 - (void)userContentController:(WKUserContentController*)userContentController didReceiveScriptMessage:(WKScriptMessage*)message

CordovaLib/Classes/Public/CDVViewController.m

@@ -30,23 +30,27 @@ Licensed to the Apache Software Foundation (ASF) under one
 #import <Cordova/CDVTimer.h>
 #import "CDVCommandDelegateImpl.h"
 
-static UIColor* defaultBackgroundColor(void) {
+static UIColor *defaultBackgroundColor(void) {
     return UIColor.systemBackgroundColor;
 }
 
-@interface CDVViewController () <CDVWebViewEngineConfigurationDelegate> {
+@interface CDVViewController () <CDVWebViewEngineConfigurationDelegate, UIScrollViewDelegate> {
     id <CDVWebViewEngineProtocol> _webViewEngine;
     id <CDVCommandDelegate> _commandDelegate;
     NSMutableDictionary<NSString *, CDVPlugin *> *_pluginObjects;
     NSMutableDictionary<NSString *, NSString *> *_pluginsMap;
     CDVCommandQueue* _commandQueue;
-    UIColor* _backgroundColor;
-    UIColor* _splashBackgroundColor;
+    UIColor *_backgroundColor;
+    UIColor *_splashBackgroundColor;
+    UIColor *_statusBarBackgroundColor;
+    UIColor *_statusBarWebViewColor;
+    UIColor *_statusBarDefaultColor;
     CDVSettingsDictionary* _settings;
 }
 
 @property (nonatomic, readwrite, strong) NSMutableArray* startupPluginNames;
-@property (nonatomic, readwrite, strong) UIView* launchView;
+@property (nonatomic, readwrite, strong) UIView *launchView;
+@property (nonatomic, readwrite, strong) UIView *statusBar;
 @property (readwrite, assign) BOOL initialized;
 
 @end
@@ -60,6 +64,7 @@ @implementation CDVViewController
 @synthesize webViewEngine = _webViewEngine;
 @synthesize backgroundColor = _backgroundColor;
 @synthesize splashBackgroundColor = _splashBackgroundColor;
+@synthesize statusBarBackgroundColor = _statusBarBackgroundColor;
 @synthesize settings = _settings;
 @dynamic webView;
 @dynamic enumerablePlugins;
@@ -168,11 +173,49 @@ - (void)setWwwFolderName:(NSString *)name
 - (void)setBackgroundColor:(UIColor *)color
 {
     _backgroundColor = color ?: defaultBackgroundColor();
+
+    [self.webView setBackgroundColor:self.backgroundColor];
 }
 
 - (void)setSplashBackgroundColor:(UIColor *)color
 {
     _splashBackgroundColor = color ?: self.backgroundColor;
+
+    [self.launchView setBackgroundColor:self.splashBackgroundColor];
+}
+
+- (UIColor *)statusBarBackgroundColor
+{
+    // If a status bar background color has been explicitly set using the JS API, we always use that.
+    // Otherwise, if the webview reports a themeColor meta tag (iOS 15.4+) we use that.
+    // Otherwise, we use the status bar background color provided in IB (from config.xml).
+    // Otherwise, we use the background color.
+    return _statusBarBackgroundColor ?: _statusBarWebViewColor ?: _statusBarDefaultColor ?: self.backgroundColor;
+}
+
+- (void)setStatusBarBackgroundColor:(UIColor *)color
+{
+    // We want the initial value from IB to set the statusBarDefaultColor and
+    // then all future changes to set the statusBarBackgroundColor.
+    //
+    // The reason for this is that statusBarBackgroundColor is treated like a
+    // forced override when it is set, and we don't want that for the initial
+    // value from config.xml set via IB.
+
+    if (!_statusBarBackgroundColor && !_statusBarWebViewColor && !_statusBarDefaultColor) {
+        _statusBarDefaultColor = color;
+    } else {
+        _statusBarBackgroundColor = color;
+    }
+
+    [self.statusBar setBackgroundColor:self.statusBarBackgroundColor];
+}
+
+- (void)setStatusBarWebViewColor:(UIColor *)color
+{
+    _statusBarWebViewColor = color;
+
+    [self.statusBar setBackgroundColor:self.statusBarBackgroundColor];
 }
 
 // Only for testing
@@ -320,6 +363,11 @@ - (void)viewDidLoad
         [self createGapView];
     }
 
+    // Instantiate the status bar
+    if (!self.statusBar) {
+        [self createStatusBarView];
+    }
+
     // /////////////////
 
     if ([self.startupPluginNames count] > 0) {
@@ -358,6 +406,7 @@ - (void)viewDidLoad
 
     [self.webView setBackgroundColor:self.backgroundColor];
     [self.launchView setBackgroundColor:self.splashBackgroundColor];
+    [self.statusBar setBackgroundColor:self.statusBarBackgroundColor];
 
     if (self.showInitialSplashScreen) {
         [self.launchView setAlpha:1];
@@ -525,6 +574,11 @@ - (void)onWebViewPageDidLoad:(NSNotification*)notification
 {
     self.webView.hidden = NO;
 
+    if ([self.webView respondsToSelector:@selector(scrollView)]) {
+        UIScrollView *scrollView = [self.webView performSelector:@selector(scrollView)];
+        [self scrollViewDidChangeAdjustedContentInset:scrollView];
+    }
+
     if ([self.settings cordovaBoolSettingForKey:@"AutoHideSplashScreen" defaultValue:YES]) {
         CGFloat splashScreenDelaySetting = [self.settings cordovaFloatSettingForKey:@"SplashScreenDelay" defaultValue:0];
 
@@ -541,6 +595,23 @@ - (void)onWebViewPageDidLoad:(NSNotification*)notification
     }
 }
 
+- (void)scrollViewDidChangeAdjustedContentInset:(UIScrollView *)scrollView
+{
+    if (self.webView.hidden) {
+        self.statusBar.hidden = true;
+        return;
+    }
+
+    self.statusBar.hidden = (scrollView.contentInsetAdjustmentBehavior == UIScrollViewContentInsetAdjustmentNever);
+}
+
+- (BOOL)prefersStatusBarHidden
+{
+    // The CDVStatusBar plugin overrides this in a category extension, and
+    // should bypass this implementation entirely
+    return self.statusBar.alpha < 0.0001f;
+}
+
 #pragma mark - View Setup
 
 - (void)loadSettings
@@ -667,6 +738,31 @@ - (void)createGapView
 
     [self.view addSubview:view];
     [self.view sendSubviewToBack:view];
+
+    if ([self.webView respondsToSelector:@selector(scrollView)]) {
+        UIScrollView *scrollView = [self.webView performSelector:@selector(scrollView)];
+        scrollView.delegate = self;
+    }
+}
+
+- (void)createStatusBarView
+{
+    // If cordova-plugin-statusbar is loaded, we'll let it handle the status
+    // bar to avoid introducing conflict
+    if (NSClassFromString(@"CDVStatusBar") != nil)
+        return;
+
+    self.statusBar = [[UIView alloc] init];
+    self.statusBar.translatesAutoresizingMaskIntoConstraints = NO;
+
+    [self.view addSubview:self.statusBar];
+
+    [self.statusBar.leadingAnchor constraintEqualToAnchor:self.view.leadingAnchor].active = YES;
+    [self.statusBar.trailingAnchor constraintEqualToAnchor:self.view.trailingAnchor].active = YES;
+    [self.statusBar.topAnchor constraintEqualToAnchor:self.view.topAnchor].active = YES;
+    [self.statusBar.bottomAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.topAnchor].active = YES;
+
+    self.statusBar.hidden = YES;
 }
 
 #pragma mark CordovaCommands
@@ -783,6 +879,12 @@ - (void)showSplashScreen:(BOOL)visible
     }];
 }
 
+- (void)showStatusBar:(BOOL)visible
+{
+    [self.statusBar setAlpha:(visible ? 1 : 0)];
+    [self setNeedsStatusBarAppearanceUpdate];
+}
+
 - (void)parseSettingsWithParser:(id <NSXMLParserDelegate>)delegate
 {
     [CDVConfigParser parseConfigFile:self.configFilePath withDelegate:delegate];