electron-menubar 11.1.1 → 11.1.3

package/README.md

@@ -1,6 +1,7 @@
 <h1 align="center">➖ electron-menubar</h1>
 
 <p align="center">
+  <a href="https://electron-menubar.gitify.io"><img src="https://img.shields.io/badge/docs-mintlify-18E299?logo=mintlify&amp;logoColor=black" alt="Documentation" /></a>
   <a href="https://github.com/gitify-app/electron-menubar/actions"><img src="https://img.shields.io/github/actions/workflow/status/gitify-app/electron-menubar/test.yml?logo=github&amp;label=ci" alt="CI Workflow" /></a>
   <a href="https://github.com/gitify-app/electron-menubar/actions"><img src="https://img.shields.io/github/actions/workflow/status/gitify-app/electron-menubar/release.yml?logo=github&amp;label=release" alt="Release Workflow" /></a>
   <a href="https://sonarcloud.io/summary/new_code?id=gitify-app_electron-menubar"><img src="https://img.shields.io/sonar/quality_gate/gitify-app_electron-menubar?server=https%3A%2F%2Fsonarcloud.io&amp;logo=sonarqubecloud" alt="Quality Gate Status" /></a>
@@ -14,11 +15,11 @@
 </p>
 
 <h5 align="center"><i>formerly known as menubar</i></h5>
-<h4 align="center">High level way to create menubar desktop applications with Electron.</h4>
+<h4 align="center">A high-level way to build menubar apps with Electron.</h4>
 
 <br />
 
-## Features
+## 📦 Features
 
 - ⚡️ Quick start for creating menubar applications using Electron.
 - 🚀 Zero runtime dependencies.
@@ -31,7 +32,7 @@
 > [!NOTE]
 > On native Wayland, the desktop compositor controls window placement, so the popover cannot be anchored to the tray icon and is positioned by the desktop (usually centered). This is a Wayland limitation, not something the library can override. Tray-relative positioning works under X11/XWayland. See [window positioning on Linux][platforms] for the detail and a workaround.
 
-## Why electron-menubar?
+## 💡 Why electron-menubar?
 
 `electron-menubar` builds on [max-mapper/menubar][github-upstream-repo], with fixes and controls developed for [Gitify](https://github.com/gitify-app/gitify). The original provides the tray-app foundation. This fork brings more of the platform-specific behavior into the library so applications have less to implement themselves.
 
@@ -46,7 +47,7 @@
 | Packaging                     | Zero runtime dependencies, including a built-in positioner. Ships CommonJS and ESM entry points with TypeScript declarations.                                                                                         |
 | Verification                  | Unit tests, native Electron end-to-end tests on macOS, Windows, and Linux, and visual checks that the tray icon and window render. The [platform report][platforms] includes screenshots and positioning limitations. |
 
-### Popup behavior without platform checks
+### 🪟 Popup behavior without platform checks
 
 Menubar manages popup stacking and focus on every platform. A plain `menubar()` dismisses on click-away and opens above the Windows hidden-icons panel. To keep it open, change one option:
 
@@ -59,20 +60,20 @@ mb.setOption('hideOnBlur', true); // Resume click-away dismissal.
 
 Opening DevTools temporarily keeps the popup open. Closing DevTools restores the latest `hideOnBlur` preference. Options set before window creation also apply when the window is recreated.
 
-#### Migrating from 10.x
+#### 🚚 Migrating from 10.x
 
 These defaults apply starting with 11.0.0. Previously, menubar inferred dismissal from `window.isAlwaysOnTop()`. Use `hideOnBlur: false` for persistent popups instead of `browserWindow.alwaysOnTop: true` or runtime `window.setAlwaysOnTop(true)` calls. `browserWindow.alwaysOnTop` now controls stacking only; it does not disable dismissal. Setting `hideOnBlur: false` also keeps the popup on top on macOS and Linux.
 
 Remove Windows `pop-up-menu` workarounds and DevTools focus handlers from apps. Menubar owns stacking during window creation, showing, preference changes, and DevTools transitions. Apps can still customize DevTools dimensions and layout.
 See the [changelog](CHANGELOG.md) for released changes and the [API documentation](#api-documentation) for all options.
 
-## Installation
+## 🚀 Installation
 
 ```bash
 pnpm add electron-menubar
 ```
 
-## Usage
+## 🔧 Usage
 
 Starting with your own new project, run these commands:
 
@@ -101,17 +102,17 @@ Then use `electron` to run the app:
 $ electron myApp.js
 ```
 
-## Examples
+## 📚 Examples
 
 See [`examples`][examples] folder for a selection of working examples.
 
-## API Documentation
+## 📖 API Documentation
 
-### `Menubar` Class
+### 🧱 `Menubar` Class
 
 The return value of `menubar()` is a `Menubar` class instance, which exposes the following properties and methods.
 
-#### Properties
+#### 🧾 Properties
 
 | Property     | Description                                                                   |
 | ------------ | ----------------------------------------------------------------------------- |
@@ -120,7 +121,7 @@ The return value of `menubar()` is a `Menubar` class instance, which exposes the
 | `tray`       | The [Electron Tray][electron-docs-tray] instance.                             |
 | `positioner` | The `Positioner` instance used to compute the window's on-screen coordinates. |
 
-#### Methods
+#### 🧰 Methods
 
 | Method                           | Description                                                                                                  |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
@@ -136,7 +137,7 @@ The return value of `menubar()` is a `Menubar` class instance, which exposes the
 | `destroy()`                      | Tear down the menubar instance.                                                                              |
 | `isDestroyed()`                  | Whether the menubar is currently destroyed.                                                                  |
 
-### `menubar()` Options
+### 🎛️ `menubar()` Options
 
 You can pass an optional options object into the `menubar({ ... })` function:
 
@@ -162,7 +163,7 @@ You can pass an optional options object into the `menubar({ ... })` function:
 | `ignoreDoubleClickEvents` | `true` (macOS only)                                      | Calls `tray.setIgnoreDoubleClickEvents(true)` so an accidental double-click doesn't race the close-on-blur handler and flicker the tray icon. Pass `false` to opt out. No-op on Linux/Windows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `globalShortcut`          |                                                          | An [Accelerator][electron-docs-accelerator] string registered as a global keyboard shortcut that toggles the menubar window. Unregistered automatically on `destroy()`. Use `mb.setGlobalShortcut(accelerator)` to change or clear it at runtime.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
-### Events
+### 📡 Events
 
 The `Menubar` class is an event emitter:
 
@@ -179,7 +180,7 @@ The `Menubar` class is an event emitter:
 | `after-close`         | After the `.window` (BrowserWindow) property has been deleted.                                                                                                                                                  |
 | `focus-lost`          | Emitted on click-away when `hideOnBlur` is `false` or DevTools is open.                                                                                                                                         |
 
-## Tips
+## 🧠 Tips
 
 - Use `mb.on('after-create-window', callback)` to run things after your app has loaded. For example you could run `mb.window.openDevTools()` to open the developer tools for debugging, or load a different URL with `mb.window.loadURL()`
 - Use `mb.on('focus-lost')` if you would like to perform some operation when using the option `hideOnBlur: false`
@@ -187,7 +188,7 @@ The `Menubar` class is an event emitter:
 - To attach a native context menu, pass it as `contextMenu`: `menubar({ contextMenu })`. The library wires it via `setContextMenu` on Linux and `popUpContextMenu` on right-click on macOS/Windows so left-click still toggles the window. See [this example][examples-native] for more information.
 - To avoid a flash when opening your menubar app, you can disable backgrounding the app using the following: `mb.app.commandLine.appendSwitch('disable-backgrounding-occluded-windows', 'true');`
 
-## Acknowledgements
+## 🤝 Acknowledgements
 
 Originally created by [Max][github-upstream-creator] — hard-forked from [max-mapper/menubar][github-upstream-repo].
 

package/lib/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region \0rolldown/runtime.js
+// \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -20,7 +20,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
-//#endregion
 let electron = require("electron");
 let node_events = require("node:events");
 let node_fs = require("node:fs");
@@ -29,7 +28,7 @@ let node_path = require("node:path");
 node_path = __toESM(node_path);
 let node_url = require("node:url");
 node_url = __toESM(node_url);
-//#region src/Positioner.ts
+// src/Positioner.ts
 /**
 * Computes `{x, y}` coordinates for placing a {@link BrowserWindow} at a named
 * position, optionally relative to a tray icon's bounds. Ported from
@@ -40,10 +39,14 @@ var Positioner = class {
 	constructor(browserWindow) {
 		this.browserWindow = browserWindow;
 	}
-	calculate(position, trayBounds) {
+	/**
+	* @param windowSize - Size to place, when it differs from the window's
+	* current size (e.g. the size about to be applied with `setBounds`).
+	*/
+	calculate(position, trayBounds, windowSize) {
 		if (!position) throw new TypeError("Positioner.calculate: a `position` argument is required.");
 		const screenSize = trayBounds ? electron.screen.getDisplayMatching(trayBounds).workArea : electron.screen.getDisplayNearestPoint(electron.screen.getCursorScreenPoint()).workArea;
-		const [windowWidth, windowHeight] = this.browserWindow.getSize();
+		const [windowWidth, windowHeight] = windowSize ? [windowSize.width, windowSize.height] : this.browserWindow.getSize();
 		const trayX = trayBounds?.x ?? NaN;
 		const trayWidth = trayBounds?.width ?? NaN;
 		const positions = {
@@ -118,8 +121,7 @@ var Positioner = class {
 		return coords;
 	}
 };
-//#endregion
-//#region src/util/cleanOptions.ts
+// src/util/cleanOptions.ts
 /**
 * @ignore
 */
@@ -150,8 +152,7 @@ function cleanOptions(opts) {
 	options.browserWindow.height = options.browserWindow.height !== void 0 ? options.browserWindow.height : DEFAULT_WINDOW_HEIGHT;
 	return options;
 }
-//#endregion
-//#region src/util/getWindowPosition.ts
+// src/util/getWindowPosition.ts
 /**
 * Utilities to get taskbar position and consequently menubar's position
 */
@@ -221,8 +222,7 @@ function getWindowPosition(tray) {
 	}
 	return "topRight";
 }
-//#endregion
-//#region src/Menubar.ts
+// src/Menubar.ts
 /**
 * Grace period after `showWindow()` during which a `blur` on the popup is
 * treated as the spurious Windows post-show blur and ignored instead of
@@ -230,6 +230,12 @@ function getWindowPosition(tray) {
 */
 const BLUR_HIDE_GRACE_MS = 400;
 /**
+* Window after a blur-triggered hide during which a tray click on Linux is
+* taken as the click that caused the blur, so it leaves the popup closed. See
+* {@link Menubar.clicked}.
+*/
+const TRAY_CLICK_AFTER_BLUR_HIDE_MS = 500;
+/**
 * Delay before re-asserting the hidden dock after startup. macOS can silently
 * drop an `app.dock.hide()` that races the app's launch activation
 * transition, leaving the dock icon stuck for the whole session. See the
@@ -237,6 +243,12 @@ const BLUR_HIDE_GRACE_MS = 400;
 */
 const DOCK_REHIDE_DELAY_MS = 2e3;
 /**
+* Largest size change per dimension, in DIPs, taken as rounding drift from
+* moving the window on a display with a fractional scale factor. A move there
+* changes each dimension by up to 2 DIPs. See {@link Menubar.holdSize}.
+*/
+const FRACTIONAL_SCALE_DRIFT = 4;
+/**
 * The main Menubar class.
 */
 var Menubar = class extends node_events.EventEmitter {
@@ -254,8 +266,10 @@ var Menubar = class extends node_events.EventEmitter {
 	_rightClickContextMenuBound = false;
 	_warnedNoPositioning = false;
 	_lastShowTime = 0;
+	_lastBlurHideTime = 0;
 	_dockRehideTimeout;
 	_repositioning = false;
+	_heldSize;
 	_showOnAllWorkspaces = false;
 	_tray;
 	constructor(app, options) {
@@ -404,8 +418,13 @@ var Menubar = class extends node_events.EventEmitter {
 	recenterOnTray() {
 		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));
+		const size = this.holdSize(this._browserWindow);
+		const { x, y } = this.positioner.calculate("trayCenter", bounds, size);
+		this._browserWindow.setBounds({
+			x: Math.round(x),
+			y: Math.round(y),
+			...size
+		});
 	}
 	/**
 	* Replace the tray context menu after construction. On Linux this also
@@ -480,6 +499,7 @@ var Menubar = class extends node_events.EventEmitter {
 		this.positionWindow();
 		this.applyWindowFocusBehavior();
 		this._lastShowTime = Date.now();
+		this._lastBlurHideTime = 0;
 		this._browserWindow.show();
 		this._isVisible = true;
 		this.emit("after-show");
@@ -502,6 +522,52 @@ var Menubar = class extends node_events.EventEmitter {
 		}
 	};
 	/**
+	* Re-anchor the window after the app resizes it (e.g. via `setSize`).
+	* Ignores the resize that moving the window itself causes; see
+	* {@link holdSize}.
+	*/
+	onWindowResize = () => {
+		if (!this._browserWindow) return;
+		const [width, height] = this._browserWindow.getSize();
+		const held = this._heldSize;
+		const drift = this.sizeDrift(this._browserWindow);
+		if (held && Math.abs(width - held.width) <= drift && Math.abs(height - held.height) <= drift) return;
+		this.positionWindow();
+	};
+	/**
+	* Pick the size to apply with the next move and remember it.
+	*
+	* On X11 with fractional display scaling, `setPosition` grows the window by
+	* a pixel or two per call, and so does `setBounds` with the size `getSize`
+	* reports, because each conversion between DIPs and device pixels rounds
+	* up. That drift often lands without a `resize` event, so only the size can
+	* tell it apart: a dimension within {@link sizeDrift} of the held size keeps
+	* the held value, and any other value came from the app and becomes the new
+	* held one.
+	*/
+	holdSize(win) {
+		const [width, height] = win.getSize();
+		const held = this._heldSize;
+		const drift = this.sizeDrift(win);
+		const size = {
+			width: held && Math.abs(width - held.width) <= drift ? held.width : width,
+			height: held && Math.abs(height - held.height) <= drift ? held.height : height
+		};
+		this._heldSize = size;
+		return size;
+	}
+	/**
+	* Size change per dimension, in DIPs, that moving the window can cause.
+	* Rounding drift only happens at a fractional scale factor, so on any other
+	* display every size change counts as the app's. At a fractional scale, an
+	* app resize of up to this many DIPs is indistinguishable from drift and is
+	* not kept.
+	*/
+	sizeDrift(win) {
+		const { scaleFactor } = electron.screen.getDisplayMatching(win.getBounds());
+		return Number.isInteger(scaleFactor) ? 0 : FRACTIONAL_SCALE_DRIFT;
+	}
+	/**
 	* Compute and apply the tray-anchored position. Always call through
 	* {@link positionWindow}, which guards against re-entrancy.
 	*/
@@ -511,12 +577,17 @@ var Menubar = class extends node_events.EventEmitter {
 		const trayPos = this._cachedBounds ?? this._tray.getBounds?.();
 		let noBoundsPosition;
 		if ((trayPos === void 0 || trayPos.x === 0) && this._options.windowPosition?.startsWith("tray")) noBoundsPosition = process.platform === "win32" ? "bottomRight" : "topRight";
-		const position = this.positioner.calculate(this._options.windowPosition || noBoundsPosition, trayPos);
+		const size = this.holdSize(this._browserWindow);
+		const position = this.positioner.calculate(this._options.windowPosition || noBoundsPosition, trayPos, size);
 		const x = this._options.browserWindow.x !== void 0 ? this._options.browserWindow.x : position.x;
 		const y = this._options.browserWindow.y !== void 0 ? this._options.browserWindow.y : position.y;
 		const targetX = Math.round(x);
 		const targetY = Math.round(y);
-		this._browserWindow.setPosition(targetX, targetY);
+		this._browserWindow.setBounds({
+			x: targetX,
+			y: targetY,
+			...size
+		});
 		if (process.platform === "linux" && !!process.env.WAYLAND_DISPLAY && !this._warnedNoPositioning) {
 			const [actualX, actualY] = this._browserWindow.getPosition();
 			if (Math.abs(actualX - targetX) > 24 || Math.abs(actualY - targetY) > 24) {
@@ -560,6 +631,10 @@ var Menubar = class extends node_events.EventEmitter {
 		if (event && (event.shiftKey || event.ctrlKey || event.metaKey)) return this.hideWindow();
 		if (this._blurTimeout) clearInterval(this._blurTimeout);
 		if (this._browserWindow && this._isVisible) return this.hideWindow();
+		if (process.platform === "linux" && Date.now() - this._lastBlurHideTime < TRAY_CLICK_AFTER_BLUR_HIDE_MS) {
+			this._lastBlurHideTime = 0;
+			return;
+		}
 		this._cachedBounds = bounds || this._cachedBounds;
 		await this.showWindow(this._cachedBounds);
 	};
@@ -629,7 +704,10 @@ var Menubar = class extends node_events.EventEmitter {
 			if (this._blurTimeout) clearTimeout(this._blurTimeout);
 			this._blurTimeout = setTimeout(() => {
 				this._blurTimeout = null;
-				if (this.shouldHideOnBlur()) this.hideWindow();
+				if (this.shouldHideOnBlur()) {
+					this.hideWindow();
+					this._lastBlurHideTime = Date.now();
+				}
 			}, 100);
 		});
 		this._showOnAllWorkspaces = this._options.showOnAllWorkspaces !== false;
@@ -643,7 +721,7 @@ var Menubar = class extends node_events.EventEmitter {
 			if (input.type === "keyDown" && input.key === "Escape") this.hideWindow();
 		});
 		this._browserWindow.on("closed", this.windowClear.bind(this));
-		this._browserWindow.on("resize", this.positionWindow);
+		this._browserWindow.on("resize", this.onWindowResize);
 		this.emit("before-load");
 		if (this._options.index !== false) await this._browserWindow.loadURL(this._options.index, this._options.loadUrlOptions);
 		this.emit("after-create-window");
@@ -669,11 +747,11 @@ var Menubar = class extends node_events.EventEmitter {
 	}
 	windowClear() {
 		this._browserWindow = void 0;
+		this._heldSize = void 0;
 		this.emit("after-close");
 	}
 };
-//#endregion
-//#region src/index.ts
+// src/index.ts
 /**
 * Entry point of menubar
 * @example
@@ -691,7 +769,6 @@ var Menubar = class extends node_events.EventEmitter {
 function menubar(options) {
 	return new Menubar(electron.app, options);
 }
-//#endregion
 exports.Menubar = Menubar;
 exports.getWindowPosition = getWindowPosition;
 exports.menubar = menubar;