feat: add transparency checking to `nativeTheme` (#43024)

* feat: add transparency checking to nativeTheme

Refs https://chromium-review.googlesource.com/c/chromium/src/+/4684870

Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com>

* chore: deprecate previous function

Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com>

* chore: fix lint

Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com>

---------

Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com>
Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com>

docs/api/native-theme.md

@@ -72,3 +72,7 @@ or is being instructed to use an inverted color scheme.
 
 A `boolean` indicating whether Chromium is in forced colors mode, controlled by system accessibility settings.
 Currently, Windows high contrast is the only system setting that triggers forced colors mode.
+
+### `nativeTheme.prefersReducedTransparency` _Readonly_
+
+A `boolean` that indicates the whether the user has chosen via system accessibility settings to reduce transparency at the OS level.

docs/api/system-preferences.md

@@ -401,10 +401,12 @@ Returns an object with system animation settings.
 
 ## Properties
 
-### `systemPreferences.accessibilityDisplayShouldReduceTransparency()` _macOS_
+### `systemPreferences.accessibilityDisplayShouldReduceTransparency` _macOS_ _Deprecated_
 
 A `boolean` property which determines whether the app avoids using semitransparent backgrounds. This maps to [NSWorkspace.accessibilityDisplayShouldReduceTransparency](https://developer.apple.com/documentation/appkit/nsworkspace/1533006-accessibilitydisplayshouldreduce)
 
+**Deprecated:** Use the new [`nativeTheme.prefersReducedTransparency`](native-theme.md#nativethemeprefersreducedtransparency-readonly) API.
+
 ### `systemPreferences.effectiveAppearance` _macOS_ _Readonly_
 
 A `string` property that can be `dark`, `light` or `unknown`.

docs/breaking-changes.md

@@ -12,6 +12,20 @@ This document uses the following convention to categorize breaking changes:
 * **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release.
 * **Removed:** An API or feature was removed, and is no longer supported by Electron.
 
+## Planned Breaking API Changes (33.0)
+
+### Deprecated: `systemPreferences.accessibilityDisplayShouldReduceTransparency`
+
+The `systemPreferences.accessibilityDisplayShouldReduceTransparency` property is now deprecated in favor of the new `nativeTheme.prefersReducedTransparency`, which provides identical information and works cross-platform.
+
+```js
+// Deprecated
+const shouldReduceTransparency = systemPreferences.accessibilityDisplayShouldReduceTransparency
+
+// Replace with:
+const prefersReducedTransparency = nativeTheme.prefersReducedTransparency
+```
+
 ## Planned Breaking API Changes (32.0)
 
 ### Removed: `File.path`

filenames.auto.gni

@@ -354,6 +354,7 @@ auto_filenames = {
     "lib/browser/message-port-main.ts",
     "lib/common/api/net-client-request.ts",
     "lib/common/define-properties.ts",
+    "lib/common/deprecate.ts",
     "lib/common/init.ts",
     "lib/common/webpack-globals-provider.ts",
     "lib/utility/api/exports/electron.ts",

lib/browser/api/system-preferences.ts

@@ -1,3 +1,4 @@
+import * as deprecate from '@electron/internal/common/deprecate';
 const { systemPreferences } = process._linkedBinding('electron_browser_system_preferences');
 
 if ('getEffectiveAppearance' in systemPreferences) {
@@ -7,4 +8,15 @@ if ('getEffectiveAppearance' in systemPreferences) {
   });
 }
 
+if ('accessibilityDisplayShouldReduceTransparency' in systemPreferences) {
+  const reduceTransparencyDeprecated = deprecate.warnOnce('systemPreferences.accessibilityDisplayShouldReduceTransparency', 'nativeTheme.prefersReducedTransparency');
+  const nativeReduceTransparency = systemPreferences.accessibilityDisplayShouldReduceTransparency;
+  Object.defineProperty(systemPreferences, 'accessibilityDisplayShouldReduceTransparency', {
+    get: () => {
+      reduceTransparencyDeprecated();
+      return nativeReduceTransparency;
+    }
+  });
+}
+
 export default systemPreferences;

shell/browser/api/electron_api_native_theme.cc

@@ -68,6 +68,10 @@ bool NativeTheme::InForcedColorsMode() {
   return ui_theme_->InForcedColorsMode();
 }
 
+bool NativeTheme::GetPrefersReducedTransparency() {
+  return ui_theme_->GetPrefersReducedTransparency();
+}
+
 #if BUILDFLAG(IS_MAC)
 const CFStringRef WhiteOnBlack = CFSTR("whiteOnBlack");
 const CFStringRef UniversalAccessDomain = CFSTR("com.apple.universalaccess");
@@ -108,7 +112,9 @@ gin::ObjectTemplateBuilder NativeTheme::GetObjectTemplateBuilder(
                    &NativeTheme::ShouldUseHighContrastColors)
       .SetProperty("shouldUseInvertedColorScheme",
                    &NativeTheme::ShouldUseInvertedColorScheme)
-      .SetProperty("inForcedColorsMode", &NativeTheme::InForcedColorsMode);
+      .SetProperty("inForcedColorsMode", &NativeTheme::InForcedColorsMode)
+      .SetProperty("prefersReducedTransparency",
+                   &NativeTheme::GetPrefersReducedTransparency);
 }
 
 const char* NativeTheme::GetTypeName() {

shell/browser/api/electron_api_native_theme.h

@@ -46,6 +46,7 @@ class NativeTheme : public gin::Wrappable<NativeTheme>,
   bool ShouldUseHighContrastColors();
   bool ShouldUseInvertedColorScheme();
   bool InForcedColorsMode();
+  bool GetPrefersReducedTransparency();
 
   // ui::NativeThemeObserver:
   void OnNativeThemeUpdated(ui::NativeTheme* theme) override;

spec/api-native-theme-spec.ts

@@ -105,4 +105,10 @@ describe('nativeTheme module', () => {
       expect(nativeTheme.inForcedColorsMode).to.be.a('boolean');
     });
   });
+
+  describe('nativeTheme.prefersReducesTransparency', () => {
+    it('returns a boolean', () => {
+      expect(nativeTheme.prefersReducedTransparency).to.be.a('boolean');
+    });
+  });
 });