feat: add app.isHidden API for macOS

[mitchchn]

Description of Change

Refs #30485.

Added an API to check if the app is hidden on macOS. This is a distinct state from the app windows being hidden, and can be used to implement unique behaviour on activation. It is also useful in conjunction with NSWindow.canHide, which I will introduce in a follow-up MR if there are no objections.

Checklist

• PR description included and stakeholders cc'd
• npm test passes
• tests are changed or added
• relevant documentation is changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: Added app.isHidden() to check if the app is hidden (e.g. with Command-H) on macOS.

[jkleinsc]

API LGTM

[mitchchn]

It looks like CI timed out but I'm unable to re-run it. There shouldn't be any test failures.

[nornagon]

Should perhaps also be exposed as .hidden given https://github.com/electron/governance/blob/main/wg-api/best-practices.md#use-getters-and-setters-as-well-as-properties ?

[mitchchn]

@nornagon the reason I didn't add a getter is because there is no setter (unless app.hidden = true hides the app, which feels wrong to me?) and also out of analogy with BrowserWindow.isVisible() which does not have a getter. I can add one if you still think it should be there.

[jkleinsc]

Looks like newly added tests are failing

[nornagon]

@mitchchn I don't feel strongly enough about it to block this, so API LGTM.

[samuelmaddock]

API LGTM

[mitchchn]

Looks like newly added tests are failing

@jkleinsc hiding and unhiding is async. To reliably wait on these events in the test suite I would need to expose "hide" and "unhide" events on app for macOS (https://developer.apple.com/documentation/appkit/nsapplication/1428562-didhidenotification). How would we feel about that? These events may be useful to users and good complements to the app.show(), app.hide() and app.isHIdden() APIs.

[jkleinsc]

@mitchchn you can use the waitUntil spec helper:

      await expect(
        waitUntil(() => app.isHidden() === true)
      ).to.eventually.be.fulfilled();

[jkleinsc]

API LGTM

[codebytere]

API LGTM

[jkleinsc]

The documentation for this feature needs to specify that the return value is a boolean so that the typescript generator can properly label this function's return value.

[jkleinsc]

The new test should use the ifdescribe helper

[mitchchn]

@jkleinsc: thanks for your review feedback. Is there anything left for me to do here? It looks like CI is timing out, not failing on my test, but if that's not the case I can investigate.

[release-clerk]

Release Notes Persisted

Added app.isHidden() to check if the app is hidden (e.g. with Command-H) on macOS.

[trop]

I was unable to backport this PR to "18-x-y" cleanly;
you will need to perform this backport manually.

[trop]

I was unable to backport this PR to "19-x-y" cleanly;
you will need to perform this backport manually.