Repository: electron/electron
Pull request: feat: expose `nativeTheme.shouldUseDarkColorsForSystemIntegratedUI`

#### Description of Change

Closes https://github.com/electron/electron/issues/46429.
Refs https://github.com/electron/electron/pull/19735.

This PR adds a new API `shouldUseDarkColorsForSystemIntegratedUI` to the `nativeTheme` module. This API returns a boolean indicating whether the system is using dark colors for system integrated UI elements. This is useful for applications that want to adapt their UI to match the system theme, especially for those that use system integrated UI elements like the shell theme or taskbar appearance.

#### Checklist
<!-- Remove items that do not apply. For completed items, change [ ] to [x]. -->

- [x] PR description included and stakeholders cc'd
- [x] `npm test` passes
- [x] tests are [changed or added](https://github.com/electron/electron/blob/main/docs/development/testing.md)
- [x] relevant API documentation, tutorials, and examples are updated and follow the [documentation style guide](https://github.com/electron/electron/blob/main/docs/development/style-guide.md)
- [x] [PR release notes](https://github.com/electron/clerk/blob/main/README.md) describe the change in a way relevant to app developers, and are [capitalized, punctuated, and past tense](https://github.com/electron/clerk/blob/main/README.md#examples).

#### Release Notes

Notes: Added `nativeTheme.shouldUseDarkColorsForSystemIntegratedUI` to distinguish system and app theme.

Changed files:
filename: docs/api/native-theme.md
patch: @@ -63,6 +63,14 @@ Your application should then always use `shouldUseDarkColors` to determine what
 A `boolean` for if the OS / Chromium currently has high-contrast mode enabled
 or is being instructed to show a high-contrast UI.
 
+### `nativeTheme.shouldUseDarkColorsForSystemIntegratedUI` _macOS_ _Windows_ _Readonly_
+
+A `boolean` property indicating whether or not the system theme has been set to dark or light.
+
+On Windows this property distinguishes between system and app light/dark theme, returning
+`true` if the system theme is set to dark theme and `false` otherwise. On macOS the return
+value will be the same as `nativeTheme.shouldUseDarkColors`.
+
 ### `nativeTheme.shouldUseInvertedColorScheme` _macOS_ _Windows_ _Readonly_
 
 A `boolean` for if the OS / Chromium currently has an inverted color scheme

filename: shell/browser/api/electron_api_native_theme.cc
patch: @@ -63,6 +63,10 @@ bool NativeTheme::ShouldUseHighContrastColors() {
   return ui_theme_->UserHasContrastPreference();
 }
 
+bool NativeTheme::ShouldUseDarkColorsForSystemIntegratedUI() {
+  return ui_theme_->ShouldUseDarkColorsForSystemIntegratedUI();
+}
+
 bool NativeTheme::InForcedColorsMode() {
   return ui_theme_->InForcedColorsMode();
 }
@@ -109,6 +113,8 @@ gin::ObjectTemplateBuilder NativeTheme::GetObjectTemplateBuilder(
                    &NativeTheme::SetThemeSource)
       .SetProperty("shouldUseHighContrastColors",
                    &NativeTheme::ShouldUseHighContrastColors)
+      .SetProperty("shouldUseDarkColorsForSystemIntegratedUI",
+                   &NativeTheme::ShouldUseDarkColorsForSystemIntegratedUI)
       .SetProperty("shouldUseInvertedColorScheme",
                    &NativeTheme::ShouldUseInvertedColorScheme)
       .SetProperty("inForcedColorsMode", &NativeTheme::InForcedColorsMode)

filename: shell/browser/api/electron_api_native_theme.h
patch: @@ -48,6 +48,7 @@ class NativeTheme final : public gin::Wrappable<NativeTheme>,
   ui::NativeTheme::ThemeSource GetThemeSource() const;
   bool ShouldUseDarkColors();
   bool ShouldUseHighContrastColors();
+  bool ShouldUseDarkColorsForSystemIntegratedUI();
   bool ShouldUseInvertedColorScheme();
   bool InForcedColorsMode();
   bool GetPrefersReducedTransparency();

filename: spec/api-native-theme-spec.ts
patch: @@ -102,6 +102,12 @@ describe('nativeTheme module', () => {
     });
   });
 
+  describe('nativeTheme.shouldUseDarkColorsForSystemIntegratedUI', () => {
+    it('returns a boolean', () => {
+      expect(nativeTheme.shouldUseDarkColorsForSystemIntegratedUI).to.be.a('boolean');
+    });
+  });
+
   describe('nativeTheme.inForcedColorsMode', () => {
     it('returns a boolean', () => {
       expect(nativeTheme.inForcedColorsMode).to.be.a('boolean');