refactor: inline Positioner to drop electron-positioner dependency (#12)

Author: afonsojramos

README.md

@@ -13,7 +13,7 @@
 
 This module provides boilerplate for setting up a menubar application using Electron. All you have to do is point it at your `index.html` and `menubar` will handle the rest.
 
-✅ Only one dependency, and one peer-dependency.
+✅ Zero runtime dependencies, only one peer-dependency.
 
 ✅ Works on macOS, Windows and most Linuxes. See [tested platforms](./PLATFORMS.md).
 
@@ -67,7 +67,7 @@ The return value of `menubar()` is a `Menubar` class instance, which has these p
 - `app`: the [Electron App](https://electronjs.org/docs/api/app) instance,
 - `window`: the [Electron Browser Window](https://electronjs.org/docs/api/browser-window) instance,
 - `tray`: the [Electron Tray](https://electronjs.org/docs/api/tray) instance,
-- `positioner`: the [Electron Positioner](https://github.com/jenslind/electron-positioner) instance,
+- `positioner`: the `Positioner` instance used to compute the window's on-screen coordinates,
 - `setOption(option, value)`: change an option after menubar is created,
 - `getOption(option)`: get an menubar option,
 - `showWindow()`: show the menubar window,
@@ -93,7 +93,7 @@ You can pass an optional options object into the `menubar({ ... })` function:
 - `preloadWindow` (default false) - Create [BrowserWindow](https://electronjs.org/docs/api/browser-window#new-browserwindowoptions) instance before it is used -- increasing resource usage, but making the click on the menubar load faster.
 - `loadUrlOptions` - (default undefined) The options passed when loading the index URL in the menubar's browserWindow. Everything browserWindow.loadURL supports is supported; this object is simply passed onto [browserWindow.loadURL](https://electronjs.org/docs/api/browser-window#winloadurlurl-options)
 - `showOnAllWorkspaces` (default true) - Makes the window available on all OS X workspaces.
-- `windowPosition` (default trayCenter and trayBottomCenter on Windows) - Sets the window position (x and y will still override this), check [positioner docs](https://github.com/jenslind/electron-positioner#docs) for valid values.
+- `windowPosition` (default `trayCenter` on macOS/Linux, `trayBottomCenter` on Windows) - Sets the window position (`browserWindow.x` / `browserWindow.y` will still override this). Valid values: `trayLeft`, `trayBottomLeft`, `trayRight`, `trayBottomRight`, `trayCenter`, `trayBottomCenter`, `topLeft`, `topRight`, `bottomLeft`, `bottomRight`, `topCenter`, `bottomCenter`, `leftCenter`, `rightCenter`, `center`.
 - `showDockIcon` (default false) - Configure the visibility of the application dock icon.
 - `trigger` (default `'click'`) - Tray event that toggles the menubar window. One of `'click'`, `'right-click'`, or `'none'`. Use `'none'` to disable automatic toggling — useful when a single tray icon serves multiple windows. The window can still be shown by calling `mb.showWindow()` directly.
 - `showOnRightClick` (default false) - **Deprecated**, use `trigger: 'right-click'` instead. Show the window on 'right-click' event instead of regular 'click'.

bun.lock

@@ -61,9 +61,6 @@
     "test:visual": "bun run tests/visual/run.ts",
     "typecheck": "tsc --noEmit"
   },
-  "dependencies": {
-    "electron-positioner": "^4.1.0"
-  },
   "devDependencies": {
     "@playwright/test": "^1.49.0",
     "@types/pngjs": "^6.0.5",

package.json

@@ -3,8 +3,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { BrowserWindow, Tray } from 'electron';
-import Positioner from 'electron-positioner';
 
+import { Positioner } from './Positioner';
 import type { Options } from './types';
 import { cleanOptions } from './util/cleanOptions';
 import { getWindowPosition } from './util/getWindowPosition';
@@ -47,8 +47,8 @@ export class Menubar extends EventEmitter {
   }
 
   /**
-   * The [electron-positioner](https://github.com/jenslind/electron-positioner)
-   * instance.
+   * The {@link Positioner} instance used to compute where the menubar window
+   * should appear on screen. Available after the `after-create-window` event.
    */
   get positioner(): Positioner {
     if (!this._positioner) {

src/Menubar.ts

@@ -0,0 +1,93 @@
+import type { BrowserWindow, Display, Rectangle } from 'electron';
+import { screen } from 'electron';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { Positioner, type WindowPosition } from './Positioner';
+
+vi.mock('electron', () => import('./__mocks__/electron'));
+
+const WORK_AREA = { x: 0, y: 0, width: 1920, height: 1080 };
+// Picked so no `tray*` position triggers the Windows overflow guard; that case
+// has its own dedicated test below.
+const TRAY_BOUNDS: Rectangle = { x: 1000, y: 0, width: 32, height: 22 };
+
+function createWindow(size: [number, number] = [400, 400]): BrowserWindow {
+  return { getSize: vi.fn(() => size) } as unknown as BrowserWindow;
+}
+
+const displayWith = (workArea: Rectangle): Display =>
+  ({ workArea }) as unknown as Display;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.mocked(screen.getDisplayMatching).mockReturnValue(displayWith(WORK_AREA));
+  vi.mocked(screen.getDisplayNearestPoint).mockReturnValue(
+    displayWith(WORK_AREA),
+  );
+  vi.mocked(screen.getCursorScreenPoint).mockReturnValue({ x: 0, y: 0 });
+});
+
+describe('Positioner.calculate', () => {
+  const expected: Record<WindowPosition, { x: number; y: number }> = {
+    trayLeft: { x: 1000, y: 0 },
+    trayBottomLeft: { x: 1000, y: 680 },
+    trayRight: { x: 632, y: 0 },
+    trayBottomRight: { x: 632, y: 680 },
+    trayCenter: { x: 816, y: 0 },
+    trayBottomCenter: { x: 816, y: 680 },
+    topLeft: { x: 0, y: 0 },
+    topRight: { x: 1520, y: 0 },
+    bottomLeft: { x: 0, y: 680 },
+    bottomRight: { x: 1520, y: 680 },
+    topCenter: { x: 760, y: 0 },
+    bottomCenter: { x: 760, y: 680 },
+    leftCenter: { x: 0, y: 340 },
+    rightCenter: { x: 1520, y: 340 },
+    center: { x: 760, y: 340 },
+  };
+
+  for (const [position, coords] of Object.entries(expected) as Array<
+    [WindowPosition, { x: number; y: number }]
+  >) {
+    it(`computes ${position}`, () => {
+      const positioner = new Positioner(createWindow());
+      expect(positioner.calculate(position, TRAY_BOUNDS)).toEqual(coords);
+    });
+  }
+
+  it('resolves screen via getDisplayMatching when tray bounds are provided', () => {
+    const positioner = new Positioner(createWindow());
+    positioner.calculate('trayCenter', TRAY_BOUNDS);
+    expect(screen.getDisplayMatching).toHaveBeenCalledWith(TRAY_BOUNDS);
+    expect(screen.getDisplayNearestPoint).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the cursor display when no tray bounds are given', () => {
+    const positioner = new Positioner(createWindow());
+    positioner.calculate('center');
+    expect(screen.getCursorScreenPoint).toHaveBeenCalled();
+    expect(screen.getDisplayNearestPoint).toHaveBeenCalled();
+    expect(screen.getDisplayMatching).not.toHaveBeenCalled();
+  });
+
+  it('snaps tray positions back to topRight.x when they overflow the right edge', () => {
+    const positioner = new Positioner(createWindow());
+    const overflowing: Rectangle = { x: 1900, y: 0, width: 32, height: 22 };
+    expect(positioner.calculate('trayRight', overflowing)).toEqual({
+      x: 1520,
+      y: 0,
+    });
+  });
+
+  it('leaves non-tray positions alone even when their x would overflow', () => {
+    const positioner = new Positioner(createWindow([3000, 400]));
+    expect(positioner.calculate('topRight')).toEqual({ x: -1080, y: 0 });
+  });
+
+  it('throws a TypeError when called without a position', () => {
+    const positioner = new Positioner(createWindow());
+    expect(() =>
+      (positioner as unknown as { calculate: () => unknown }).calculate(),
+    ).toThrow(TypeError);
+  });
+});

src/Positioner.spec.ts

@@ -0,0 +1,138 @@
+import { type BrowserWindow, type Rectangle, screen } from 'electron';
+
+/**
+ * Named anchor points for placing the menubar window. The `tray*` values are
+ * relative to the tray icon's bounds; the rest are relative to the work area
+ * of the display containing the cursor (or the tray, when bounds are given).
+ */
+export type WindowPosition =
+  | 'trayLeft'
+  | 'trayBottomLeft'
+  | 'trayRight'
+  | 'trayBottomRight'
+  | 'trayCenter'
+  | 'trayBottomCenter'
+  | 'topLeft'
+  | 'topRight'
+  | 'bottomLeft'
+  | 'bottomRight'
+  | 'topCenter'
+  | 'bottomCenter'
+  | 'leftCenter'
+  | 'rightCenter'
+  | 'center';
+
+/**
+ * Computes `{x, y}` coordinates for placing a {@link BrowserWindow} at a named
+ * position, optionally relative to a tray icon's bounds. Ported from
+ * `electron-positioner@4.1.0` to drop the unmaintained runtime dependency.
+ */
+export class Positioner {
+  private readonly browserWindow: BrowserWindow;
+
+  constructor(browserWindow: BrowserWindow) {
+    this.browserWindow = browserWindow;
+  }
+
+  calculate(
+    position?: WindowPosition,
+    trayBounds?: Rectangle,
+  ): { x: number; y: number } {
+    if (!position) {
+      throw new TypeError(
+        'Positioner.calculate: a `position` argument is required.',
+      );
+    }
+
+    const screenSize = trayBounds
+      ? screen.getDisplayMatching(trayBounds).workArea
+      : screen.getDisplayNearestPoint(screen.getCursorScreenPoint()).workArea;
+    const [windowWidth, windowHeight] = this.browserWindow.getSize();
+    const trayX = trayBounds?.x ?? Number.NaN;
+    const trayWidth = trayBounds?.width ?? Number.NaN;
+
+    const positions: Record<WindowPosition, { x: number; y: number }> = {
+      trayLeft: {
+        x: Math.floor(trayX),
+        y: screenSize.y,
+      },
+      trayBottomLeft: {
+        x: Math.floor(trayX),
+        y: Math.floor(screenSize.height - (windowHeight - screenSize.y)),
+      },
+      trayRight: {
+        x: Math.floor(trayX - windowWidth + trayWidth),
+        y: screenSize.y,
+      },
+      trayBottomRight: {
+        x: Math.floor(trayX - windowWidth + trayWidth),
+        y: Math.floor(screenSize.height - (windowHeight - screenSize.y)),
+      },
+      trayCenter: {
+        x: Math.floor(trayX - windowWidth / 2 + trayWidth / 2),
+        y: screenSize.y,
+      },
+      trayBottomCenter: {
+        x: Math.floor(trayX - windowWidth / 2 + trayWidth / 2),
+        y: Math.floor(screenSize.height - (windowHeight - screenSize.y)),
+      },
+      topLeft: {
+        x: screenSize.x,
+        y: screenSize.y,
+      },
+      topRight: {
+        x: Math.floor(screenSize.x + (screenSize.width - windowWidth)),
+        y: screenSize.y,
+      },
+      bottomLeft: {
+        x: screenSize.x,
+        y: Math.floor(screenSize.height - (windowHeight - screenSize.y)),
+      },
+      bottomRight: {
+        x: Math.floor(screenSize.x + (screenSize.width - windowWidth)),
+        y: Math.floor(screenSize.height - (windowHeight - screenSize.y)),
+      },
+      topCenter: {
+        x: Math.floor(screenSize.x + (screenSize.width / 2 - windowWidth / 2)),
+        y: screenSize.y,
+      },
+      bottomCenter: {
+        x: Math.floor(screenSize.x + (screenSize.width / 2 - windowWidth / 2)),
+        y: Math.floor(screenSize.height - (windowHeight - screenSize.y)),
+      },
+      leftCenter: {
+        x: screenSize.x,
+        y:
+          screenSize.y +
+          Math.floor(screenSize.height / 2) -
+          Math.floor(windowHeight / 2),
+      },
+      rightCenter: {
+        x: Math.floor(screenSize.x + (screenSize.width - windowWidth)),
+        y:
+          screenSize.y +
+          Math.floor(screenSize.height / 2) -
+          Math.floor(windowHeight / 2),
+      },
+      center: {
+        x: Math.floor(screenSize.x + (screenSize.width / 2 - windowWidth / 2)),
+        y: Math.floor(
+          (screenSize.height + screenSize.y) / 2 - windowHeight / 2,
+        ),
+      },
+    };
+
+    const coords = positions[position];
+
+    // On Windows, a tray-relative position can push the window past the right
+    // edge of the work area. Snap back to `topRight` x in that case so it stays
+    // visible. See https://github.com/jenslind/electron-positioner.
+    if (position.startsWith('tray')) {
+      if (coords.x + windowWidth > screenSize.width + screenSize.x) {
+        return { x: positions.topRight.x, y: coords.y };
+      }
+    }
+
+    return coords;
+  }
+}

src/Positioner.ts

@@ -18,13 +18,28 @@ export const app: {
 
 export class BrowserWindow {
   destroy: Mock = vi.fn();
+  getSize: Mock = vi.fn(() => [400, 400]);
   loadURL: Mock = vi.fn();
   on: Mock = vi.fn();
+  setPosition: Mock = vi.fn();
   setVisibleOnAllWorkspaces: Mock = vi.fn();
+  show: Mock = vi.fn();
 }
 
 export class Tray {
   on: Mock = vi.fn();
   removeListener: Mock = vi.fn();
   setToolTip: Mock = vi.fn();
 }
+
+const defaultWorkArea = { x: 0, y: 0, width: 1920, height: 1080 };
+
+export const screen: {
+  getCursorScreenPoint: Mock;
+  getDisplayMatching: Mock;
+  getDisplayNearestPoint: Mock;
+} = {
+  getCursorScreenPoint: vi.fn(() => ({ x: 0, y: 0 })),
+  getDisplayMatching: vi.fn(() => ({ workArea: defaultWorkArea })),
+  getDisplayNearestPoint: vi.fn(() => ({ workArea: defaultWorkArea })),
+};

src/__mocks__/electron.ts

@@ -4,6 +4,8 @@ import type {
   Tray,
 } from 'electron';
 
+import type { WindowPosition } from './Positioner';
+
 /**
  * Options for creating a menubar application
  */
@@ -93,23 +95,8 @@ export interface Options {
    */
   tray?: Tray;
   /**
-   * Sets the window position (x and y will still override this), check
-   * electron-positioner docs for valid values.
+   * Sets the window position (x and y will still override this). See
+   * {@link WindowPosition} for the list of valid values.
    */
-  windowPosition?:
-    | 'trayLeft'
-    | 'trayBottomLeft'
-    | 'trayRight'
-    | 'trayBottomRight'
-    | 'trayCenter'
-    | 'trayBottomCenter'
-    | 'topLeft'
-    | 'topRight'
-    | 'bottomLeft'
-    | 'bottomRight'
-    | 'topCenter'
-    | 'bottomCenter'
-    | 'leftCenter'
-    | 'rightCenter'
-    | 'center';
+  windowPosition?: WindowPosition;
 }