feat: add a context menu to the toolbar button

The menu lets users disconnect with a mouse click.
Also added a stopwatch utility to measure the time while debugging.

Author: snipsnipsnip

manifest_template.json

@@ -23,6 +23,7 @@
     "alarms",
     "compose",
     "notifications",
+    "menus",
     "scripting",
     "storage"
   ],

src/app-background/api.ts

@@ -1,4 +1,5 @@
 import type { IComposeWindow } from "src/ghosttext-adaptor/api"
+import type { MessageId } from "src/util"
 
 export type { IGhostServerPort } from "src/ghosttext-adaptor/api"
 
@@ -40,3 +41,32 @@ export interface IComposeWindowDetector {
    */
   tryWrap(tab: ITab): IComposeWindow | undefined
 }
+
+/** Controls the context menu on the toolbar button */
+export interface IButtonMenu {
+  /** @returns whether the menu has been initialized */
+  isInitialized(): boolean
+
+  /**
+   * Creates a context menu shown when the toolbar button is right clicked.
+   * @param menuItems Items to show in the menu
+   * @param currentShown Information about the menu currently shown
+   */
+  initItems(menuItems: ReadonlyArray<MenuItem>, currentShown: MenuShownInfo | undefined): Promise<void>
+}
+
+/** Information about a menu that is about to be shown */
+export type MenuShownInfo = {
+  /** A list of IDs of the menu items that is about to be shown */
+  menuIds: ReadonlyArray<string>
+}
+
+/** An item in a context menu */
+export type MenuItem = {
+  /** ID of the text to be displayed in the item */
+  label: MessageId
+  /** The command to execute when the menu item is clicked */
+  id: CommandId
+  /** path to the icon to display in the menu item */
+  icon: string
+}

src/app-background/background_event_router.ts

@@ -1,13 +1,15 @@
-import type { IComposeWindow } from "src/ghosttext-adaptor/api"
+import type { MenuHandler, MenuShownInfo } from "."
 import type { CommandId, IComposeWindowDetector, ITab } from "./api"
-import type { ComposeActionNotifier } from "./compose_action_notifier"
+import type { CommandHandler } from "./command_handler"
 
+/** Redirects events from Thunderbird to the appropriate handlers */
 export class BackgroundEventRouter {
   static isSingleton = true
 
   constructor(
-    private readonly composeActionNotifier: ComposeActionNotifier,
     private readonly composeTabDetector: IComposeWindowDetector,
+    private readonly commandHandler: CommandHandler,
+    private readonly menuHandler: MenuHandler,
   ) {}
 
   /** Handles shortcut key presses defined in the manifest.json */
@@ -17,20 +19,7 @@ export class BackgroundEventRouter {
       return Promise.reject(Error("Event dropped"))
     }
 
-    return this.runCommand(command, composeTab)
-  }
-
-  /** Executes a command in the context of a compose tab */
-  private runCommand(command: string, composeTab: IComposeWindow): Promise<void> {
-    switch (command as CommandId) {
-      case "start_ghostbird":
-        return this.composeActionNotifier.start(composeTab)
-      case "stop_ghostbird":
-        return this.composeActionNotifier.stop(composeTab)
-      case "toggle_ghostbird":
-        return this.composeActionNotifier.toggle(composeTab)
-    }
-    // We don't handle default here so that tsc checks for exhaustiveness
+    return this.commandHandler.runCommand(command as CommandId, composeTab)
   }
 
   /** Handles the toolbar button press */
@@ -42,7 +31,22 @@ export class BackgroundEventRouter {
       return Promise.reject(Error("Event dropped"))
     }
 
-    return this.composeActionNotifier.start(composeTab)
+    return this.commandHandler.runCommand("start_ghostbird", composeTab)
+  }
+
+  /** Handles right-click on the toolbar button */
+  handleMenuShown(info: MenuShownInfo, _tab: ITab): void | Promise<void> {
+    return this.menuHandler.handleMenuShown(info)
+  }
+
+  /** Handles clicks on the item in the toolbar button's context menu */
+  handleMenuClick(menuItemId: string, tab: ITab): Promise<void> {
+    let composeTab = this.composeTabDetector.tryWrap(tab)
+    if (!composeTab) {
+      return Promise.reject(Error("Event dropped"))
+    }
+
+    return this.menuHandler.handleMenuItemClicked(menuItemId, composeTab)
   }
 
   /** handles one-off messages from content scripts */

src/app-background/command_handler.ts

@@ -0,0 +1,23 @@
+import type { IComposeWindow } from "src/ghosttext-adaptor"
+import type { CommandId } from "./api"
+import type { ComposeActionNotifier } from "./compose_action_notifier"
+
+/** Handles execution of commands in the context a compose tab */
+
+export class CommandHandler {
+  static isSingleton = true
+  constructor(private readonly composeActionNotifier: ComposeActionNotifier) {}
+
+  /** Executes a command in the context of a compose tab */
+  runCommand(command: CommandId, composeTab: IComposeWindow): Promise<void> {
+    switch (command) {
+      case "start_ghostbird":
+        return this.composeActionNotifier.start(composeTab)
+      case "stop_ghostbird":
+        return this.composeActionNotifier.stop(composeTab)
+      case "toggle_ghostbird":
+        return this.composeActionNotifier.toggle(composeTab)
+    }
+    // We don't handle default here so that tsc checks for exhaustiveness
+  }
+}

src/app-background/menu_handler.ts

@@ -0,0 +1,32 @@
+import type { IComposeWindow } from "src/ghosttext-adaptor"
+import type { CommandHandler, CommandId, IButtonMenu, MenuItem, MenuShownInfo } from "."
+
+/** Responsible for handling the context menu on the toolbar button */
+export class MenuHandler {
+  static isSingleton = true
+
+  constructor(
+    private readonly buttonMenu: IButtonMenu,
+    private readonly commandHandler: CommandHandler,
+    private readonly menuItems: ReadonlyArray<MenuItem>,
+  ) {}
+
+  /** Handles right-click on the toolbar button */
+  handleMenuShown(info: MenuShownInfo): Promise<void> | void {
+    // Compare the shown menu with menuItems and (re-)initialize the menu if necessary
+    console.debug(info)
+
+    if (!this.buttonMenu.isInitialized()) {
+      console.debug("Initializing menu")
+      return this.buttonMenu.initItems(this.menuItems, info)
+    }
+
+    console.debug("Menu is already initialized")
+  }
+
+  /** Handles click on a menu item */
+  handleMenuItemClicked(menuItemId: string, composeTab: IComposeWindow): Promise<void> {
+    // We use command ID as menu item ID, so we can directly pass it to the command handler
+    return this.commandHandler.runCommand(menuItemId as CommandId, composeTab)
+  }
+}

src/root/background.ts

@@ -3,7 +3,7 @@
  * This script may be suspended and reloaded occasionally by Thunderbird.
  */
 
-import type { BackgroundEventRouter } from "src/app-background"
+import type { BackgroundEventRouter, MenuItem, MenuShownInfo } from "src/app-background"
 import { type LazyThen, makeLazyThen } from "src/util/lazy_then"
 
 console.info("starting", import.meta.url)
@@ -13,9 +13,17 @@ const prepareThen: LazyThen<BackgroundEventRouter> = makeLazyThen(async () => {
     import("./startup/startup_background"),
     import("webext-options-sync"),
   ])
+  /** Menu items to be shown in the context menu. */
+  let menuItems: ReadonlyArray<MenuItem> = [
+    {
+      label: "manifest_commands_stop_ghostbird_description",
+      id: "stop_ghostbird",
+      icon: "gray.svg",
+    },
+  ]
   let heart = new AlarmHeart(messenger)
 
-  return prepareBackgroundRouter({ messenger, heart, optionsSyncCtor })
+  return prepareBackgroundRouter({ messenger, heart, optionsSyncCtor, menuItems })
 })
 
 messenger.composeAction.onClicked.addListener((tab, _info): Promise<void> | void =>
@@ -42,4 +50,24 @@ messenger.alarms.onAlarm.addListener((alarm) => {
   console.debug("beep", alarm)
 })
 
+messenger.menus.onShown.addListener((info, tab) =>
+  prepareThen((router) => {
+    console.debug({ info, tab })
+
+    return router.handleMenuShown(info as MenuShownInfo, tab)
+  }),
+)
+
+messenger.menus.onClicked.addListener(({ menuItemId }, tab): Promise<void> | void =>
+  prepareThen((router) => {
+    console.debug({ menuItemId, tab })
+    if (!tab || typeof menuItemId !== "string") {
+      return Promise.reject(Error(`event dropped`))
+    }
+    let p = router.handleMenuClick(menuItemId, tab)
+
+    return p ?? Promise.reject(Error(`unknown command ${menuItemId}`))
+  }),
+)
+
 console.info("started", import.meta.url)

src/root/startup/startup_background.ts

@@ -1,4 +1,4 @@
-import type { ComposeActionNotifier, IComposeWindowDetector } from "src/app-background"
+import type { CommandHandler, IComposeWindowDetector, MenuHandler, MenuItem } from "src/app-background"
 import * as appBackground from "src/app-background"
 import { BackgroundEventRouter } from "src/app-background"
 import * as adaptor from "src/ghosttext-adaptor"
@@ -17,11 +17,13 @@ export type BackgroundConstants = {
   messenger: typeof globalThis.messenger
   heart: AlarmHeart
   optionsSyncCtor: typeof OptionsSync
+  menuItems: ReadonlyArray<MenuItem>
 }
 
 export type BackgroundCatalog = BackgroundConstants & {
-  composeActionNotifier: ComposeActionNotifier
   composeTabDetector: IComposeWindowDetector
+  menuHandler: MenuHandler
+  commandHandler: CommandHandler
 }
 
 /** Collects related classes and prepares the injector for background.js */

src/test/sanity.test.ts

@@ -20,6 +20,7 @@ describe(prepareBackgroundRouter, () => {
       messenger,
       heart: new AlarmHeart(messenger),
       optionsSyncCtor: Symbol("optionsSyncCtor") as unknown as typeof OptionsSync,
+      menuItems: [],
     })
     expect(router).instanceOf(BackgroundEventRouter)
   })

src/test/startup.test.ts

@@ -34,6 +34,7 @@ const modules: AnyModules = {
 describe("startup", () => {
   const constants: [string, AnyEntry][] = [
     ["messenger", ["const", makeDummyMessenger()]],
+    ["menuItems", ["const", Symbol("menuItems")]],
     ["body", ["const", Symbol("body")]],
     ["domParser", ["const", Symbol("domParser")]],
     ["selection", ["const", Symbol("selection")]],

src/thunderbird/background_util/button_menu.ts

@@ -0,0 +1,76 @@
+import type { IButtonMenu, MenuItem, MenuShownInfo } from "src/app-background"
+
+/**
+ * Controls the context menu on the toolbar button
+ */
+export class ButtonMenu implements IButtonMenu {
+  static isSingleton = true
+
+  private initWork: Promise<void> | undefined
+
+  constructor(private readonly messenger: typeof global.messenger) {}
+
+  isInitialized(): boolean {
+    return Boolean(this.initWork)
+  }
+
+  initItems(menuItems: ReadonlyArray<MenuItem>, _currentShown: MenuShownInfo | undefined): Promise<void> {
+    if (this.initWork) {
+      console.debug("ButtonMenu is already initialized; Skip creating menu items.")
+    }
+    this.initWork ??= this.createMenuItems(menuItems)
+
+    return this.initWork
+  }
+
+  async createMenuItems(menuItems: ReadonlyArray<MenuItem>): Promise<void> {
+    // Load a flag to avoid creating menu in case of MV3 suspension
+    if (await this.loadInitialized()) {
+      return
+    }
+    await this.createMenu(menuItems)
+    await this.saveInitialized()
+  }
+
+  private saveInitialized(): Promise<void> {
+    return this.messenger.storage.session.set({ buttonMenuInitialized: true })
+  }
+
+  private async loadInitialized(): Promise<boolean> {
+    let got = await this.messenger.storage.session.get("buttonMenuInitialized")
+    console.debug(got)
+    let { buttonMenuInitialized } = got
+    return Boolean(buttonMenuInitialized)
+  }
+
+  private async createMenu(menuItems: readonly MenuItem[]): Promise<void> {
+    await this.messenger.menus.removeAll()
+    await Promise.all(menuItems.map((item) => this.createMenuItem(item)))
+    await this.messenger.menus.refresh()
+  }
+
+  private createMenuItem({ id, label, icon }: MenuItem): Promise<void> {
+    const contexts: messenger.menus.ContextType[] = ["compose_action"]
+
+    let { promise, reject, resolve } = Promise.withResolvers<void>()
+    this.messenger.menus.create(
+      {
+        id,
+        title: this.messenger.i18n.getMessage(label),
+        icons: icon,
+        contexts,
+        // `command` option doesn't seem to work as of TB128, so we use `onclick` event instead
+      },
+      () => {
+        if (this.messenger.runtime.lastError) {
+          reject(this.messenger.runtime.lastError)
+        } else {
+          console.debug(`Menu item ${id} created`)
+          resolve()
+        }
+      },
+    )
+
+    return promise
+  }
+}