feat: add macOS-only api to determine if app is currently active (#49622)

* feat: add macOS-only api to determine if app is currently active

You can `focus()` the app and get events for `did-become-active`, but there's currently not a way to directly check if your app is the active (foreground) application.

* test: add unit test for app.isActive api

* fix: ensure we hide app after showing in test

If the app is still active, it may affect other tests like dock.bounce
that behave differently depending on whether the app is active

* docs: simplify isActive api description

docs/api/app.md

@@ -573,6 +573,10 @@ focus but may instead show a notification or flash the app icon (Wayland).
 
 You should seek to use the `steal` option as sparingly as possible.
 
+### `app.isActive()` _macOS_
+
+Returns `boolean` - `true` if the application is active (i.e. focused).
+
 ### `app.hide()` _macOS_
 
 Hides all application windows without minimizing them.

shell/browser/api/electron_api_app.cc

@@ -1873,6 +1873,7 @@ gin::ObjectTemplateBuilder App::GetObjectTemplateBuilder(v8::Isolate* isolate) {
       .SetMethod("isEmojiPanelSupported",
                  base::BindRepeating(&Browser::IsEmojiPanelSupported, browser))
 #if BUILDFLAG(IS_MAC)
+      .SetMethod("isActive", base::BindRepeating(&Browser::IsActive, browser))
       .SetMethod("hide", base::BindRepeating(&Browser::Hide, browser))
       .SetMethod("isHidden", base::BindRepeating(&Browser::IsHidden, browser))
       .SetMethod("show", base::BindRepeating(&Browser::Show, browser))

shell/browser/browser.h

@@ -165,6 +165,9 @@ class Browser : private WindowListObserver {
   // Set the handler which decides whether to shutdown.
   void SetShutdownHandler(base::RepeatingCallback<bool()> handler);
 
+  // Returns whether the application is active.
+  bool IsActive();
+
   // Hide the application.
   void Hide();
   bool IsHidden();

shell/browser/browser_mac.mm

@@ -146,6 +146,10 @@ void Browser::Focus(gin::Arguments* args) {
   [[AtomApplication sharedApplication] activateIgnoringOtherApps:steal_focus];
 }
 
+bool Browser::IsActive() {
+  return [[AtomApplication sharedApplication] isActive];
+}
+
 void Browser::Hide() {
   [[AtomApplication sharedApplication] hide:nil];
 }

spec/api-app-spec.ts

@@ -1773,6 +1773,31 @@ describe('app module', () => {
     });
   });
 
+  ifdescribe(process.platform === 'darwin')('app isActive API', () => {
+    describe('app.isActive', () => {
+      afterEach(closeAllWindows);
+
+      it('returns true when the app becomes active', async () => {
+        expect(app.isActive()).to.equal(false);
+
+        const w = new BrowserWindow({
+          width: 200,
+          height: 200,
+          show: false
+        });
+
+        w.show();
+
+        await expect(
+          waitUntil(() => app.isActive())
+        ).to.eventually.be.fulfilled();
+
+        w.close();
+        app.hide();
+      });
+    });
+  });
+
   ifdescribe(process.platform === 'darwin')('app hide and show API', () => {
     describe('app.isHidden', () => {
       it('returns true when the app is hidden', async () => {