chore: document deprecated systemPreferences APIs (#39492)

chore: document deprecated systemPreferences APIs (#39343)

* chore: document deprecated systemPreferences APIs

* chore: forgot systemPreferences.appLevelAppearance

* test: expect deprecation messages

docs/api/system-preferences.md

@@ -435,7 +435,7 @@ Returns an object with system animation settings.
 
 ## Properties
 
-### `systemPreferences.appLevelAppearance` _macOS_
+### `systemPreferences.appLevelAppearance` _macOS_ _Deprecated_
 
 A `string` property that can be `dark`, `light` or `unknown`. It determines the macOS appearance setting for
 your application. This maps to values in: [NSApplication.appearance](https://developer.apple.com/documentation/appkit/nsapplication/2967170-appearance?language=objc). Setting this will override the

docs/breaking-changes.md

@@ -39,6 +39,41 @@ w.webContents.getPrintersAsync().then((printers) => {
 })
 ```
 
+### Deprecated: `systemPreferences.{get,set}AppLevelAppearance` and `systemPreferences.appLevelAppearance`
+
+The `systemPreferences.getAppLevelAppearance` and `systemPreferences.setAppLevelAppearance`
+methods have been deprecated, as well as the `systemPreferences.appLevelAppearance` property.
+Use the `nativeTheme` module instead.
+
+```js
+// Deprecated
+systemPreferences.getAppLevelAppearance()
+// Replace with
+nativeTheme.shouldUseDarkColors
+
+// Deprecated
+systemPreferences.appLevelAppearance
+// Replace with
+nativeTheme.shouldUseDarkColors
+
+// Deprecated
+systemPreferences.setAppLevelAppearance('dark')
+// Replace with
+nativeTheme.themeSource = 'dark'
+```
+
+### Deprecated: `alternate-selected-control-text` value for `systemPreferences.getColor`
+
+The `alternate-selected-control-text` value for `systemPreferences.getColor`
+has been deprecated. Use `selected-content-background` instead.
+
+```js
+// Deprecated
+systemPreferences.getColor('alternate-selected-control-text')
+// Replace with
+systemPreferences.getColor('selected-content-background')
+```
+
 ## Planned Breaking API Changes (25.0)
 
 ### Deprecated: `protocol.{register,intercept}{Buffer,String,Stream,File,Http}Protocol`

lib/browser/api/system-preferences.ts

@@ -1,12 +1,31 @@
+import * as deprecate from '@electron/internal/common/deprecate';
+
 const { systemPreferences } = process._linkedBinding('electron_browser_system_preferences');
 
 if ('getAppLevelAppearance' in systemPreferences) {
   const nativeALAGetter = systemPreferences.getAppLevelAppearance;
   const nativeALASetter = systemPreferences.setAppLevelAppearance;
+  const warnALA = deprecate.warnOnce('appLevelAppearance');
+  const warnALAGetter = deprecate.warnOnce('getAppLevelAppearance function');
+  const warnALASetter = deprecate.warnOnce('setAppLevelAppearance function');
   Object.defineProperty(systemPreferences, 'appLevelAppearance', {
-    get: () => nativeALAGetter.call(systemPreferences),
-    set: (appearance) => nativeALASetter.call(systemPreferences, appearance)
+    get: () => {
+      warnALA();
+      return nativeALAGetter.call(systemPreferences);
+    },
+    set: (appearance) => {
+      warnALA();
+      nativeALASetter.call(systemPreferences, appearance);
+    }
   });
+  systemPreferences.getAppLevelAppearance = () => {
+    warnALAGetter();
+    return nativeALAGetter.call(systemPreferences);
+  };
+  systemPreferences.setAppLevelAppearance = (appearance) => {
+    warnALASetter();
+    nativeALASetter.call(systemPreferences, appearance);
+  };
 }
 
 if ('getEffectiveAppearance' in systemPreferences) {

spec/api-native-theme-spec.ts

@@ -6,6 +6,7 @@ import * as path from 'path';
 import * as semver from 'semver';
 import { setTimeout } from 'timers/promises';
 
+import { expectDeprecationMessages } from './lib/deprecate-helpers';
 import { ifdescribe } from './lib/spec-helpers';
 import { closeAllWindows } from './lib/window-helpers';
 
@@ -61,11 +62,16 @@ describe('nativeTheme module', () => {
     });
 
     ifdescribe(process.platform === 'darwin' && semver.gte(os.release(), '18.0.0'))('on macOS 10.14', () => {
-      it('should update appLevelAppearance when set', () => {
-        nativeTheme.themeSource = 'dark';
-        expect(systemPreferences.appLevelAppearance).to.equal('dark');
-        nativeTheme.themeSource = 'light';
-        expect(systemPreferences.appLevelAppearance).to.equal('light');
+      it('should update appLevelAppearance when set', async () => {
+        await expectDeprecationMessages(
+          () => {
+            nativeTheme.themeSource = 'dark';
+            expect(systemPreferences.appLevelAppearance).to.equal('dark');
+            nativeTheme.themeSource = 'light';
+            expect(systemPreferences.appLevelAppearance).to.equal('light');
+          },
+          "(electron) 'appLevelAppearance' is deprecated and will be removed."
+        );
       });
     });
 

spec/api-system-preferences-spec.ts

@@ -1,5 +1,6 @@
 import { expect } from 'chai';
 import { systemPreferences } from 'electron/main';
+import { expectDeprecationMessages } from './lib/deprecate-helpers';
 import { ifdescribe } from './lib/spec-helpers';
 
 describe('systemPreferences module', () => {
@@ -174,9 +175,8 @@ describe('systemPreferences module', () => {
       }).to.throw(`Unknown color: ${color}`);
     });
 
-    it('returns a valid color', () => {
+    it('returns a valid color', async () => {
       const colors = [
-        'alternate-selected-control-text',
         'control-background',
         'control',
         'control-text',
@@ -209,12 +209,20 @@ describe('systemPreferences module', () => {
         'unemphasized-selected-text',
         'window-background',
         'window-frame-text'
-      ];
+      ] as const;
 
       colors.forEach(color => {
-        const sysColor = systemPreferences.getColor(color as any);
+        const sysColor = systemPreferences.getColor(color);
         expect(sysColor).to.be.a('string');
       });
+
+      await expectDeprecationMessages(
+        () => {
+          const sysColor = systemPreferences.getColor('alternate-selected-control-text');
+          expect(sysColor).to.be.a('string');
+        },
+        "'alternate-selected-control-text' is deprecated as an input to getColor.  Use 'selected-content-background' instead."
+      );
     });
   });
 
@@ -233,15 +241,25 @@ describe('systemPreferences module', () => {
     });
 
     describe('with functions', () => {
-      it('returns a valid appearance', () => {
-        const appearance = systemPreferences.getAppLevelAppearance();
-        expect(options).to.include(appearance);
+      it('returns a valid appearance', async () => {
+        await expectDeprecationMessages(
+          () => {
+            const appearance = systemPreferences.getAppLevelAppearance();
+            expect(options).to.include(appearance);
+          },
+          "(electron) 'getAppLevelAppearance function' is deprecated and will be removed."
+        );
       });
 
-      it('can be changed', () => {
-        systemPreferences.setAppLevelAppearance('dark');
-        const appearance = systemPreferences.getAppLevelAppearance();
-        expect(appearance).to.eql('dark');
+      it('can be changed', async () => {
+        await expectDeprecationMessages(
+          () => {
+            systemPreferences.setAppLevelAppearance('dark');
+            const appearance = systemPreferences.getAppLevelAppearance();
+            expect(appearance).to.eql('dark');
+          },
+          "(electron) 'setAppLevelAppearance function' is deprecated and will be removed."
+        );
       });
     });
   });