Allow to open the contextmenu through keyboard shortcuts when in widgets (#2226)

## Context

In browsers, I can usually press the Menu key, Shift+F10, or, more
specifically on macOS, Ctrl+Enter, to open a context menu, which is the
menu that appears when right-clicking something with my mouse.

But for now in Grist, when we are focused on a widget, we can't open the
active cell's context menu through the keyboard. This is because when
focused on a widget, the actual keyboard focus is on the hidden
clipboard element. So, pressing the key triggers a browser's native
contextmenu on the hidden element, appearing on the top left corner of
the screen.

We'd rather make it so that pressing the key correctly opens the custom
context menu of the active cell, just like right-clicking.

## Proposed solution

- make it so that the clipboard's hidden element just passes through the
`contextmenu` events it receives, to the active cursor, if any. This
makes the keyboard handling rather straightforward in the code: we don't
have to code anything more than what is already there to handle the
`contextmenu` event of cells,
- add a way to describe commands with different shortcuts for macOS to
allow us to better match each OS habits. This enables us to show to the
user, in the keyboard shorcuts list, either `Menu` or `^+Enter`
depending on wether we are on macOS.

## Has this been tested?

<!-- Put an `x` in the box that applies: -->

- [x] 👍 yes, I added tests to the test suite
- [ ] 💭 no, because this PR is a draft and still needs work
- [ ] 🙅 no, because this is not relevant here
- [ ] 🙋 no, because I need help <!-- Detail how we can help you -->

## Screenshots / Screencasts

Before:



https://github.com/user-attachments/assets/6508215e-1acf-4f39-8a0b-c22a2f701957

After:


https://github.com/user-attachments/assets/2d9ae04b-1e7f-499a-97fb-d785fdb4ffa3

Author: manuhabitela

app/client/components/Clipboard.ts

@@ -112,6 +112,26 @@ export class Clipboard extends Disposable {
       dom.on("copy", this._onCopy.bind(this)),
       dom.on("cut", this._onCut.bind(this)),
       dom.on("paste", this._onPaste.bind(this)),
+      // The contextmenu event can be triggered with keyboard shortcuts. In that case, we redirect the event to the
+      // active cursor element, if any.
+      dom.on("contextmenu", (event) => {
+        redirectContextmenuEvent(event);
+      }),
+      // On Mac, no contextmenu event is triggered when pressing usual shortcuts, so we
+      // manually check for Shift+F10 or Ctrl+Enter (the default ContextMenu shortcut on macOS)
+      dom.on("keydown", (event) => {
+        if (!isMac) {
+          return;
+        }
+        if (event.key === "F10" && event.shiftKey && !event.metaKey && !event.ctrlKey && !event.altKey) {
+          redirectContextmenuEvent(event);
+          return;
+        }
+        if (event.key === "Enter" && event.ctrlKey && !event.metaKey && !event.altKey && !event.shiftKey) {
+          redirectContextmenuEvent(event);
+          return;
+        }
+      }),
     );
     document.body.appendChild(this.copypasteField);
     this.onDispose(() => { dom.domDispose(this.copypasteField); this.copypasteField.remove(); });
@@ -285,6 +305,21 @@ const FOCUS_TARGET_TAGS = new Set([
   "IFRAME",
 ]);
 
+function redirectContextmenuEvent(event: MouseEvent | KeyboardEvent) {
+  event.preventDefault();
+  event.stopPropagation();
+  const activeCursor = document.querySelector(".active_cursor");
+  if (activeCursor) {
+    const rect = activeCursor.getBoundingClientRect();
+    activeCursor.dispatchEvent(new PointerEvent("contextmenu", {
+      bubbles: true,
+      cancelable: true,
+      clientX: rect.left,
+      clientY: rect.bottom,
+    }));
+  }
+}
+
 /**
  * Returns data formatted as a 2D array of strings, suitable for pasting within Grist.
  *

app/client/components/commandList.ts

@@ -125,6 +125,7 @@ export type CommandName =
   "detachEditor" |
   "activateAssistant" |
   "viewAsCard" |
+  "openContextMenu" |
   "showColumns" |
   "createForm" |
   "insertField" |
@@ -133,7 +134,7 @@ export type CommandName =
 
 export interface CommandDef {
   name: CommandName;
-  keys: string[];
+  keys: CommandKey[];
   desc: (() => string) | null;
   bindKeys?: boolean;
   /**
@@ -143,6 +144,13 @@ export interface CommandDef {
   deprecated?: boolean;
 }
 
+export interface PlatformSpecificCommandKey {
+  default: string;
+  mac?: string;
+}
+
+export type CommandKey = string | PlatformSpecificCommandKey;
+
 export interface MenuCommand {
   humanKeys: string[];
   run: (...args: any[]) => any;
@@ -410,6 +418,12 @@ export const groups: CommendGroupDef[] = [{
       name: "viewAsCard",
       keys: ["Space"],
       desc: () => t("Show the record card widget of the selected record"),
+    }, {
+      // This matches browser's default `contextmenu` event keybindings. This is here to show the keyboard shortcut
+      // to the user, but we rely on the `contextmenu` event rather than the `openContextMenu` command in the code.
+      name: "openContextMenu",
+      keys: [{ default: "Menu", mac: "Ctrl+Enter" }, "Shift+F10"],
+      desc: () => t("Open the context menu"),
     },
   ],
 }, {

app/client/components/commands.ts

@@ -7,7 +7,13 @@
  * command is active at any time.
  */
 
-import { CommandDef, CommandName, CommendGroupDef, groups } from "app/client/components/commandList";
+import {
+  CommandDef,
+  CommandKey,
+  CommandName,
+  CommendGroupDef,
+  groups,
+} from "app/client/components/commandList";
 import { get as getBrowserGlobals } from "app/client/lib/browserGlobals";
 import dom from "app/client/lib/dom";
 import * as Mousetrap from "app/client/lib/Mousetrap";
@@ -122,6 +128,13 @@ export function getHumanKey(key: string, mac: boolean): string {
   return keys.join(mac ? "" : " + ");
 }
 
+function resolveKeyForPlatform(key: CommandKey) {
+  if (typeof key === "string") {
+    return key;
+  }
+  return (isMac && key.mac) ? key.mac : key.default;
+}
+
 export interface CommandOptions {
   bindKeys?: boolean;
   deprecated?: boolean;
@@ -152,11 +165,12 @@ export class Command implements CommandDef {
   private _implGroupStack: CommandGroup[] = [];
   private _activeFunc: (...args: any[]) => any = _.noop;
 
-  constructor(name: CommandName, desc: (() => string) | null, keys: string[], options: CommandOptions = {}) {
+  constructor(name: CommandName, desc: (() => string) | null, keys: CommandKey[], options: CommandOptions = {}) {
+    const platformKeys = keys.map(resolveKeyForPlatform);
     this.name = name;
     this.desc = desc;
-    this.humanKeys = keys.map(key => getHumanKey(key, isMac));
-    this.keys = keys.map(function(k) { return k.trim().toLowerCase().replace(/ *\+ */g, "+"); });
+    this.humanKeys = platformKeys.map(key => getHumanKey(key, isMac));
+    this.keys = platformKeys.map(function(k) { return k.trim().toLowerCase().replace(/ *\+ */g, "+"); });
     this.bindKeys = options.bindKeys ?? true;
     this.alwaysOn = options.alwaysOn ?? false;
     this.isActive = ko.observable(false);

app/client/lib/Mousetrap.js

@@ -21,7 +21,7 @@ if (typeof window === "undefined") {
   // Minus is different on Gecko:
   // see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode
   // and https://github.com/ccampbell/mousetrap/pull/215
-  Mousetrap.addKeycodes({173: "-"});
+  Mousetrap.addKeycodes({173: "-", 93: "menu"});
 
   var customStopCallbacks = new WeakMap();
 

app/client/ui/contextMenu.ts

@@ -50,13 +50,21 @@ class ContextMenuController extends Disposable implements IOpenController {
 
     // On click anywhere on the page (outside popup content), close it.
     const onClick = (evt: MouseEvent) => {
-      const target: Node | null = evt.target as Node;
-      if (target && !content.contains(target)) {
+      if (evt.target && !content.contains(evt.target as Node)) {
         this.close();
       }
     };
-    this.autoDispose(dom.onElem(document, "contextmenu", onClick, { useCapture: true }));
+    // Handle the specific case if right-clicking/pressing the Menu key inside the menu itself (we ignore it)
+    const onContextMenu = (evt: MouseEvent) => {
+      if (evt.target && content.contains(evt.target as Node)) {
+        evt.preventDefault();
+        evt.stopPropagation();
+        return;
+      }
+      onClick(evt);
+    };
     this.autoDispose(dom.onElem(document, "click", onClick, { useCapture: true }));
+    this.autoDispose(dom.onElem(document, "contextmenu", onContextMenu, { useCapture: true }));
 
     // Cleanup involves removing the element.
     this.onDispose(() => {

static/locales/en.client.json

@@ -2589,7 +2589,8 @@
         "When in the search bar, close it and focus the current match": "When in the search bar, close it and focus the current match",
         "When typed at the start of a cell, make this a formula column": "When typed at the start of a cell, make this a formula column",
         "showing a behavioral popup": "showing a behavioral popup",
-        "Filter this column by just this cell's value": "Filter this column by just this cell's value"
+        "Filter this column by just this cell's value": "Filter this column by just this cell's value",
+        "Open the context menu": "Open the context menu"
     },
     "GridViewMenusDateHelpers": {
         "12-hour format": "12-hour format",

static/locales/fr.client.json

@@ -2549,7 +2549,8 @@
         "When in the search bar, close it and focus the current match": "Quand on est dans la barre de recherche, la fermer et mettre le focus sur la correspondance actuelle",
         "When typed at the start of a cell, make this a formula column": "Quand tapé au début d'une cellule, transformer celle-ci en colonne de formule",
         "showing a behavioral popup": "affichage d'une fenêtre contextuelle comportementale",
-        "Filter this column by just this cell's value": "Filtrer cette colonne par la valeur de cette cellule uniquement"
+        "Filter this column by just this cell's value": "Filtrer cette colonne par la valeur de cette cellule uniquement",
+        "Open the context menu": "Ouvrir le menu contextuel"
     },
     "GridViewMenusDateHelpers": {
         "12-hour format": "format 12-heures",

test/nbrowser/ViewContextMenu.ts

@@ -0,0 +1,57 @@
+import * as gu from "test/nbrowser/gristUtils";
+import { setupTestSuite } from "test/nbrowser/testUtils";
+
+import { assert, driver, Key } from "mocha-webdriver";
+
+describe("ViewContextMenu", function() {
+  this.timeout(20000);
+  const cleanup = setupTestSuite();
+
+  before(async function() {
+    const session = await gu.session().login();
+    await session.tempNewDoc(cleanup);
+  });
+
+  afterEach(() => gu.checkForErrors());
+
+  it("should support opening a GridView cell context menu with keyboard", async function() {
+    await assertShiftF10Works();
+  });
+
+  it("should support opening a RecordView context menu with keyboard", async function() {
+    await gu.addNewSection("Card", "Table1");
+    await assertShiftF10Works();
+  });
+
+  it("should not open a context menu twice when opening it with keyboard", async function() {
+    await pressShiftF10();
+    assert.isTrue(await gu.findOpenMenu().isDisplayed());
+    await pressShiftF10(true);
+    await driver.sleep(100);
+    const openedMenus = await driver.findAll(".grist-floating-menu");
+    assert.equal(openedMenus.length, 1);
+
+    await gu.sendKeys(Key.ESCAPE);
+    await gu.waitForMenuToClose();
+  });
+
+  it("should hide the context menu when clicking outside of it after opening it with keyboard", async function() {
+    await pressShiftF10();
+    assert.isTrue(await gu.findOpenMenu().isDisplayed());
+    await gu.selectSectionByTitle("Table1");
+    await gu.waitForMenuToClose();
+  });
+});
+
+async function assertShiftF10Works() {
+  await gu.waitAppFocus();
+  await pressShiftF10();
+  assert.isTrue(await gu.findOpenMenu().isDisplayed());
+  await gu.sendKeys(Key.ESCAPE);
+  await gu.waitForMenuToClose();
+}
+
+// Using gu.sendKeys doesn't work with Shift+F10 so we have to deal with the testing environment limitations.
+async function pressShiftF10(inMenu: boolean = false) {
+  return driver.find(inMenu ? ".grist-floating-menu" : ".copypaste").sendKeys(Key.chord(Key.SHIFT, Key.F10));
+}