feat: add setContentStyle method to statusBar for dynamic content style changes

[seamlink-aalves]

Platforms affected

Android

Motivation and Context

In order to replace statusbar plugin with the native implementation of the statusbar in cordova 15 a function to set the color of the content was missing. This adds support for setting the color of the content.

Description

A new function setContentStyle is added with this PR accepting either default or lightcontent. It will dinamically set the color of the content in statusbar.

Testing

Checklist

• I've run the tests to see all new and existing tests pass
• I added automated test coverage as appropriate for this change
• Commit is prefixed with (platform) if this change only applies to one platform (e.g. (android))
• If this Pull Request resolves an issue, I linked to the issue in the text above (and used the correct keyword to close issues using keywords)
• I've updated the documentation if necessary

[erisu]

Is there a specific reason we need to support this manual logic? The code already handles changing the font color of the statusbar area using luminance-based thresholds to ensure sufficient contrast (e.g., when setting dark background it should automatically select light text). I'm wondering if keeping manual control could reintroduce cases where text becomes hard to read.

[seamlink-aalves]

As mentioned in apache/cordova-discuss#114 when having the App in edge-to-edge the background is the webview.

This requires that the color of the content to be controlled dynamically and changed at any time, for example, when I'm changing from dark to light mode and the background changes color.

[erisu]

Could you provide a reproducible repo with minimal changes to a standard Cordova app that demonstrates the color conflict and resulting readability issues requiring manual overrides?

From what I recall, in a default app:

• Switching between light and dark mode automatically updates the text color on resume
• If the background color is hardcoded, the text color remains unchanged
• If the background color is changed via the JS API, the text color should update based on luminance-based thresholds

[seamlink-aalves]

In edge-to-edge there is no statusbar background since the webview extends to the full height of the device.

In this case the background color is never set, either by configuration or by JS API. This is why I'm proposing this PR to set the content color.

[erisu]

Ah, I understand the issue now.

---

Issue Use Case Summary:

In this example, we have two vertically stacked boxes. Each box fills the area of the screen, making the app scrollable.

The first box has a black background, and the second box has a white background.

Initially, we expect the status bar appearance (text) to be white so it is visible against the black background. As the webview scrolls and the white box enters the status bar area, we expect the status bar text to switch to black to maintain readability but in the present condition, the text remains white and is unreadable.

---

I might have an idea for how we could update the appearance dynamically, but I don't think adding it to the Cordova-Android core is the right decision. In fact, I believe we should consider opening a ticket with Google to see if they can properly implement this within Chromium and the AndroidX WebView library.

Although the release announcement states that the status bar plugin will be deprecated, I believe it can still be installed and that the styleDefault() and styleLightContent() APIs can still be used. I tested this, and it worked.

While the plugin includes initialization code, I didn't notice any issues with it. We could continue using the plugin for handling the status bar appearance as no changes would be required. If there are changes in core, it would be simple adding a JS API to map to the plugin, if the plugin exists.

And then open a ticket with Google to see if we can get a proper fix.

[seamlink-aalves]

In order to move to cordova-android 15 we had to keep the dependency for the statusbar plugin and use the styleDefault() and styleLightContent() APIs.

Our intention with this PR was to have this functionality in the core platform to be able to remove the plugin dependency.

If this was accepted we would also do a PR for the cordova-ios platform which has the same problem/limitation.