From f38df564a90661f78da238970afbf0665cfdf195 Mon Sep 17 00:00:00 2001
From: George Gevoian <george@gevoian.com>
Date: Tue, 26 Sep 2023 16:37:27 -0400
Subject: [PATCH] (core) Add Command API to Grist Plugin API

Summary:
The new Command API provides limited access to Grist Commands from within cusotm
widgets. This includes the ability to perform undo and redo, which is bound to
the same keyboard shortcut as Grist by default.

Test Plan: Browser tests.

Reviewers: jarek

Reviewed By: jarek

Subscribers: paulfitz, jarek

Differential Revision: https://phab.getgrist.com/D4050
---
 app/client/components/CustomView.ts  |  5 +++++
 app/client/components/WidgetFrame.ts | 22 ++++++++++++++++++++++
 app/plugin/grist-plugin-api.ts       |  8 ++++++++
 package.json                         |  1 +
 static/custom-widget.html            |  1 +
 test/fixtures/sites/readout/page.js  |  1 +
 test/nbrowser/CustomView.ts          | 27 ++++++++++++++++++++++++++-
 yarn.lock                            |  5 +++++
 8 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/app/client/components/CustomView.ts b/app/client/components/CustomView.ts
index ae14ed61..32f1b019 100644
--- a/app/client/components/CustomView.ts
+++ b/app/client/components/CustomView.ts
@@ -3,6 +3,7 @@ import * as commands from 'app/client/components/commands';
 import {Cursor} from 'app/client/components/Cursor';
 import {GristDoc} from 'app/client/components/GristDoc';
 import {
+  CommandAPI,
   ConfigNotifier,
   CustomSectionAPIImpl,
   GristDocAPIImpl,
@@ -240,6 +241,10 @@ export class CustomView extends Disposable {
             access,
             this._promptAccess.bind(this)),
           new MinimumLevel(AccessLevel.none));
+        frame.exposeAPI(
+          "CommandAPI",
+          new CommandAPI(access),
+          new MinimumLevel(AccessLevel.none));
         frame.useEvents(RecordNotifier.create(frame, view), new MinimumLevel(AccessLevel.read_table));
         frame.useEvents(TableNotifier.create(frame, view), new MinimumLevel(AccessLevel.read_table));
         frame.exposeAPI(
diff --git a/app/client/components/WidgetFrame.ts b/app/client/components/WidgetFrame.ts
index 731b57a4..6c08d5c7 100644
--- a/app/client/components/WidgetFrame.ts
+++ b/app/client/components/WidgetFrame.ts
@@ -1,4 +1,6 @@
 import BaseView from 'app/client/components/BaseView';
+import {CommandName} from 'app/client/components/commandList';
+import * as commands from 'app/client/components/commands';
 import {GristDoc} from 'app/client/components/GristDoc';
 import {hooks} from 'app/client/Hooks';
 import {get as getBrowserGlobals} from 'app/client/lib/browserGlobals';
@@ -484,6 +486,26 @@ export class WidgetAPIImpl implements WidgetAPI {
   }
 }
 
+const COMMAND_MINIMUM_ACCESS_LEVELS: Map<CommandName, AccessLevel> = new Map([
+  ['undo', AccessLevel.full],
+  ['redo', AccessLevel.full],
+]);
+
+export class CommandAPI {
+  constructor(private _currentAccess: AccessLevel) {}
+
+  public async run(commandName: CommandName): Promise<unknown> {
+    const minimumAccess = COMMAND_MINIMUM_ACCESS_LEVELS.get(commandName);
+    if (minimumAccess === undefined || !isSatisfied(this._currentAccess, minimumAccess)) {
+      // If the command name is unrecognized, or the current access level doesn't meet the
+      // command's minimum access level, do nothing.
+      return;
+    }
+
+    return await commands.allCommands[commandName].run();
+  }
+}
+
 /************************
  * Events that are sent to the CustomWidget.
  *
diff --git a/app/plugin/grist-plugin-api.ts b/app/plugin/grist-plugin-api.ts
index f617b33e..9c3fbf51 100644
--- a/app/plugin/grist-plugin-api.ts
+++ b/app/plugin/grist-plugin-api.ts
@@ -65,6 +65,8 @@ export const widgetApi = rpc.getStub<WidgetAPI>('WidgetAPI', checkers.WidgetAPI)
  */
 export const sectionApi = rpc.getStub<CustomSectionAPI>('CustomSectionAPI', checkers.CustomSectionAPI);
 
+export const commandApi = rpc.getStub<any>('CommandAPI');
+
 /**
  * Shortcut for [[GristView.allowSelectBy]].
  */
@@ -437,6 +439,12 @@ export async function addImporter(name: string, path: string, mode: 'fullscreen'
   });
 }
 
+export function enableKeyboardShortcuts() {
+  const Mousetrap = require('mousetrap');
+  Mousetrap.bind('mod+z', () => commandApi.run('undo'));
+  Mousetrap.bind(['mod+shift+z', 'ctrl+y'], () => commandApi.run('redo'));
+}
+
 /**
  * Options when initializing connection to Grist.
  */
diff --git a/package.json b/package.json
index 3a6c451d..21eabdb8 100644
--- a/package.json
+++ b/package.json
@@ -66,6 +66,7 @@
     "@types/minio": "7.0.15",
     "@types/mocha": "5.2.5",
     "@types/moment-timezone": "0.5.9",
+    "@types/mousetrap": "1.6.2",
     "@types/node": "^14",
     "@types/node-fetch": "2.6.2",
     "@types/pidusage": "2.0.1",
diff --git a/static/custom-widget.html b/static/custom-widget.html
index f7492ae6..c01c8764 100644
--- a/static/custom-widget.html
+++ b/static/custom-widget.html
@@ -7,6 +7,7 @@
   <script src="/grist-plugin-api.js"></script>
   <script>
     grist.ready();
+    grist.enableKeyboardShortcuts();
   </script>
   <style>
     body {
diff --git a/test/fixtures/sites/readout/page.js b/test/fixtures/sites/readout/page.js
index dd466612..6a870192 100644
--- a/test/fixtures/sites/readout/page.js
+++ b/test/fixtures/sites/readout/page.js
@@ -32,6 +32,7 @@ function setup() {
   grist.onNewRecord(function(rec) {
     document.getElementById('record').innerHTML = 'new';
   });
+  grist.enableKeyboardShortcuts();
 }
 
 window.onload = setup;
diff --git a/test/nbrowser/CustomView.ts b/test/nbrowser/CustomView.ts
index 5919d96a..80bc28fc 100644
--- a/test/nbrowser/CustomView.ts
+++ b/test/nbrowser/CustomView.ts
@@ -236,6 +236,31 @@ describe('CustomView', function() {
         await gu.undo();
       });
 
+      const undoTestTitle = access === 'full'
+        ? 'allows undo/redo via keyboard'
+        : 'does not allow undo/redo via keyboard';
+      it (undoTestTitle, async function() {
+        const iframe = gu.getSection('Friends custom').find('iframe');
+        await driver.switchTo().frame(iframe);
+        await driver.find('body').click();
+
+        await gu.sendKeys(Key.chord(Key.CONTROL, 'y'));
+        const expected = access === 'full'
+          ? withAccess(['Rabbit', 'Tom', 'Sydney', 'Bill', 'Evan', 'Mary'], undefined)
+          : withAccess(['Roger', 'Tom', 'Sydney', 'Bill', 'Evan', 'Mary'], undefined);
+        await gu.waitToPass(async () => {
+          assert.deepEqual(readJson(await driver.find('#placeholder').getText())?.Name, expected);
+        }, 1000);
+
+        await gu.sendKeys(Key.chord(await gu.modKey(), 'z'));
+        await gu.waitToPass(async () => {
+          assert.deepEqual(readJson(await driver.find('#placeholder').getText())?.Name,
+          withAccess(['Roger', 'Tom', 'Sydney', 'Bill', 'Evan', 'Mary'], undefined));
+        }, 1000);
+
+        await driver.switchTo().defaultContent();
+      });
+
       it('allows switching to custom section by clicking inside it', async function() {
         await gu.getCell({section: 'FRIENDS', col: 0, rowNum: 1}).click();
         assert.equal(await gu.getActiveSectionTitle(), 'FRIENDS');
@@ -245,7 +270,7 @@ describe('CustomView', function() {
         await driver.switchTo().frame(iframe);
         await driver.find('body').click();
 
-        // Check that the right secton is active, and its settings visible in the side panel.
+        // Check that the right section is active, and its settings visible in the side panel.
         await driver.switchTo().defaultContent();
         assert.equal(await gu.getActiveSectionTitle(), 'FRIENDS Custom');
         assert.equal(await driver.find('.test-config-widget-url').isPresent(), true);
diff --git a/yarn.lock b/yarn.lock
index 158b1b93..3f82821d 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -843,6 +843,11 @@
   dependencies:
     moment ">=2.14.0"
 
+"@types/mousetrap@1.6.2":
+  version "1.6.2"
+  resolved "https://registry.yarnpkg.com/@types/mousetrap/-/mousetrap-1.6.2.tgz#5f48bdbd28c8a447167263ae436488f1d8be072d"
+  integrity sha512-m67PUdzoHJGmYJ6Fno4iXocl+azw9cuz8tdUG21M04UzMRUT1YfxPIIIt3lQkXLMGwlGSKXYNGxCOMxKlGegIw==
+
 "@types/node-fetch@2.6.2":
   version "2.6.2"
   resolved "https://registry.yarnpkg.com/@types/node-fetch/-/node-fetch-2.6.2.tgz#d1a9c5fd049d9415dce61571557104dec3ec81da"