feat: add setGlobalShortcut, toggleWindow and recenterOnTray helpers

Author: afonsojramos

src/Menubar.spec.ts

@@ -1,4 +1,4 @@
-import { app, BrowserWindow, Tray } from 'electron';
+import { app, BrowserWindow, globalShortcut, Tray } from 'electron';
 import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { Menubar } from './Menubar';
@@ -177,6 +177,138 @@ describe('Menubar hideOnClose option', () => {
   });
 });
 
+describe('Menubar global shortcut', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('registers the configured accelerator on ready', () => {
+    const mb = new Menubar(app, {
+      preloadWindow: true,
+      globalShortcut: 'CmdOrCtrl+Shift+G',
+    });
+    return new Promise<void>((resolve) => {
+      mb.on('ready', () => {
+        expect(globalShortcut.register).toHaveBeenCalledWith(
+          'CmdOrCtrl+Shift+G',
+          expect.any(Function),
+        );
+        resolve();
+      });
+    });
+  });
+
+  it('unregisters the previous accelerator when replacing it', () => {
+    const mb = new Menubar(app, {
+      preloadWindow: true,
+      globalShortcut: 'CmdOrCtrl+Shift+G',
+    });
+    return new Promise<void>((resolve) => {
+      mb.on('ready', () => {
+        mb.setGlobalShortcut('Alt+Space');
+        expect(globalShortcut.unregister).toHaveBeenCalledWith(
+          'CmdOrCtrl+Shift+G',
+        );
+        expect(globalShortcut.register).toHaveBeenLastCalledWith(
+          'Alt+Space',
+          expect.any(Function),
+        );
+        resolve();
+      });
+    });
+  });
+
+  it('clears the accelerator when called with undefined', () => {
+    const mb = new Menubar(app, {
+      preloadWindow: true,
+      globalShortcut: 'CmdOrCtrl+Shift+G',
+    });
+    return new Promise<void>((resolve) => {
+      mb.on('ready', () => {
+        (globalShortcut.register as Mock).mockClear();
+        mb.setGlobalShortcut(undefined);
+        expect(globalShortcut.unregister).toHaveBeenCalledWith(
+          'CmdOrCtrl+Shift+G',
+        );
+        expect(globalShortcut.register).not.toHaveBeenCalled();
+        resolve();
+      });
+    });
+  });
+
+  it('does not retain a failed registration', () => {
+    (globalShortcut.register as Mock).mockReturnValueOnce(false);
+    const mb = new Menubar(app, { preloadWindow: true });
+    return new Promise<void>((resolve) => {
+      mb.on('ready', () => {
+        const ok = mb.setGlobalShortcut('CmdOrCtrl+Shift+G');
+        expect(ok).toBe(false);
+        (globalShortcut.unregister as Mock).mockClear();
+        mb.destroy();
+        expect(globalShortcut.unregister).not.toHaveBeenCalled();
+        resolve();
+      });
+    });
+  });
+
+  it('unregisters on destroy()', () => {
+    const mb = new Menubar(app, {
+      preloadWindow: true,
+      globalShortcut: 'CmdOrCtrl+Shift+G',
+    });
+    return new Promise<void>((resolve) => {
+      mb.on('ready', () => {
+        mb.destroy();
+        expect(globalShortcut.unregister).toHaveBeenCalledWith(
+          'CmdOrCtrl+Shift+G',
+        );
+        resolve();
+      });
+    });
+  });
+});
+
+describe('Menubar toggleWindow and recenterOnTray', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('toggleWindow shows when hidden and hides when visible', () => {
+    const mb = new Menubar(app, { preloadWindow: true });
+    return new Promise<void>((resolve) => {
+      mb.on('after-create-window', async () => {
+        await mb.toggleWindow();
+        expect(mb.window!.show).toHaveBeenCalledTimes(1);
+        await mb.toggleWindow();
+        expect(mb.window!.hide).toHaveBeenCalledTimes(1);
+        resolve();
+      });
+    });
+  });
+
+  it('recenterOnTray sets a new position from tray bounds', () => {
+    const mb = new Menubar(app, { preloadWindow: true });
+    return new Promise<void>((resolve) => {
+      mb.on('after-create-window', () => {
+        (mb.window!.setPosition as Mock).mockClear();
+        mb.recenterOnTray();
+        expect(mb.window!.setPosition).toHaveBeenCalled();
+        resolve();
+      });
+    });
+  });
+
+  it('recenterOnTray is a no-op without a window', () => {
+    const mb = new Menubar(app, {});
+    return new Promise<void>((resolve) => {
+      mb.on('ready', () => {
+        expect(() => mb.recenterOnTray()).not.toThrow();
+        resolve();
+      });
+    });
+  });
+});
+
 describe('Menubar contextMenu option', () => {
   const originalPlatform = process.platform;
   const fakeMenu = { __menu: true } as unknown as Electron.Menu;

src/Menubar.ts

@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { BrowserWindow, type Menu, Tray } from 'electron';
+import { BrowserWindow, globalShortcut, type Menu, Tray } from 'electron';
 
 import { Positioner } from './Positioner';
 import type { Options } from './types';
@@ -23,6 +23,7 @@ export class Menubar extends EventEmitter {
   private _cachedBounds?: Electron.Rectangle; // _cachedBounds are needed for double-clicked event
   private _options: Options;
   private _positioner: Positioner | undefined;
+  private _shortcut?: Electron.Accelerator;
   private _tray?: Tray;
 
   constructor(app: Electron.App, options?: Partial<Options>) {
@@ -99,6 +100,11 @@ export class Menubar extends EventEmitter {
     // intercepting it.
     this._isDestroyed = true;
 
+    if (this._shortcut) {
+      globalShortcut.unregister(this._shortcut);
+      this._shortcut = undefined;
+    }
+
     if (this._browserWindow) {
       this._browserWindow.destroy();
       this._browserWindow = undefined;
@@ -155,6 +161,59 @@ export class Menubar extends EventEmitter {
     this.refreshLinuxContextMenu();
   }
 
+  /**
+   * Register a global keyboard accelerator that toggles the menubar window.
+   * Replaces any previously registered shortcut owned by this Menubar.
+   * Pass `undefined` to clear the current shortcut without registering a new
+   * one. Returns whether the registration succeeded.
+   *
+   * @param accelerator - An Electron
+   * [Accelerator](https://electronjs.org/docs/api/accelerator) string, or
+   * `undefined` to clear.
+   */
+  setGlobalShortcut(accelerator: Electron.Accelerator | undefined): boolean {
+    if (this._shortcut) {
+      globalShortcut.unregister(this._shortcut);
+      this._shortcut = undefined;
+    }
+    this._options.globalShortcut = accelerator;
+    if (!accelerator) {
+      return true;
+    }
+    const ok = globalShortcut.register(accelerator, () => this.toggleWindow());
+    if (ok) {
+      this._shortcut = accelerator;
+    }
+    return ok;
+  }
+
+  /**
+   * Toggle the menubar window: hide it if visible, show it otherwise.
+   * Resolves once the window finishes showing or hiding.
+   */
+  async toggleWindow(): Promise<void> {
+    if (this._browserWindow && this._isVisible) {
+      this.hideWindow();
+      return;
+    }
+    await this.showWindow();
+  }
+
+  /**
+   * Re-center the menubar window over the tray icon. Convenience wrapper for
+   * `positioner.move('trayCenter', tray.getBounds())` that's safe to call
+   * after the `after-create-window` event. No-op if the window doesn't
+   * exist yet.
+   */
+  recenterOnTray(): void {
+    if (!this._browserWindow || !this._tray) {
+      return;
+    }
+    const bounds = this._tray.getBounds();
+    const { x, y } = this.positioner.calculate('trayCenter', bounds);
+    this._browserWindow.setPosition(Math.round(x), Math.round(y));
+  }
+
   /**
    * Replace the tray context menu after construction. On Linux this also
    * re-publishes the menu to the SNI host, which is required after mutating
@@ -298,6 +357,10 @@ export class Menubar extends EventEmitter {
       this.bindContextMenu(this._options.contextMenu);
     }
 
+    if (this._options.globalShortcut) {
+      this.setGlobalShortcut(this._options.globalShortcut);
+    }
+
     if (!this._options.windowPosition) {
       this._options.windowPosition = getWindowPosition(this.tray);
     }

src/__mocks__/electron.ts

@@ -29,6 +29,16 @@ export class BrowserWindow {
   webContents: { on: Mock } = { on: vi.fn() };
 }
 
+export const globalShortcut: {
+  isRegistered: Mock;
+  register: Mock;
+  unregister: Mock;
+} = {
+  isRegistered: vi.fn(() => false),
+  register: vi.fn(() => true),
+  unregister: vi.fn(),
+};
+
 export class Tray {
   getBounds: Mock = vi.fn(() => ({ x: 0, y: 0, width: 32, height: 32 }));
   isDestroyed: Mock = vi.fn(() => false);

src/types.ts

@@ -47,6 +47,15 @@ export interface Options {
    * The app source directory.
    */
   dir: string;
+  /**
+   * Register this accelerator as a global shortcut that toggles the menubar
+   * window. Calls
+   * [`globalShortcut.register`](https://electronjs.org/docs/api/global-shortcut#globalshortcutregisteraccelerator-callback)
+   * after `ready` and unregisters it on {@link Menubar.destroy}. The same
+   * accelerator can be set or cleared later via
+   * {@link Menubar.setGlobalShortcut}.
+   */
+  globalShortcut?: Electron.Accelerator;
   /**
    * Hide the window on `close` instead of letting it be destroyed, so the
    * next tray click re-uses the same {@link BrowserWindow} instance. On