Introduce menu entry support

Summary:
[interesting] since it shows how Flipper APIs are exposed through sandy. However, the next diff is a much simpler example of that

This diff adds support for adding menu entries for sandy plugin (renamed keyboard actions to menus, as it always creates a menu entry, but not necessarily a keyboard shortcut)

```

  client.addMenuEntry(
    // custom entry
    {
      label: 'Reset Selection',
      topLevelMenu: 'Edit',
      handler: () => {
        selectedID.set(null);
      },
    },
    // based on built-in action (sets standard label, shortcut)
    {
      action: 'createPaste',
      handler: () => {
        console.log('creating paste');
      },
    },
  );
```

Most of this diff is introducing the concept of FlipperUtils, a set of static Flipper methods (not related to a device or client) that can be used from Sandy. This will for example be used to implement things as `createPaste` as well

Reviewed By: nikoant

Differential Revision: D22766990

fbshipit-source-id: ce90af3b700e6c3d9a779a3bab4673ba356f3933

desktop/flipper-plugin/src/__tests__/test-utils.node.tsx

@@ -286,3 +286,45 @@ test('device plugins can receive deeplinks', async () => {
   plugin.triggerDeepLink('test');
   expect(plugin.instance.field1.get()).toBe('test');
 });
+
+test('plugins can register menu entries', async () => {
+  const plugin = TestUtils.startPlugin({
+    plugin(client: PluginClient) {
+      const counter = createState(0);
+      client.addMenuEntry(
+        {
+          action: 'createPaste',
+          handler() {
+            counter.set(counter.get() + 1);
+          },
+        },
+        {
+          label: 'Custom Action',
+          topLevelMenu: 'Edit',
+          handler() {
+            counter.set(counter.get() + 3);
+          },
+        },
+      );
+      return {counter};
+    },
+    Component() {
+      return null;
+    },
+  });
+
+  expect(plugin.instance.counter.get()).toBe(0);
+  plugin.triggerDeepLink('test');
+  plugin.triggerMenuEntry('createPaste');
+  plugin.triggerMenuEntry('Custom Action');
+  expect(plugin.instance.counter.get()).toBe(4);
+  expect(plugin.flipperLib.enableMenuEntries).toBeCalledTimes(1);
+
+  plugin.deactivate();
+
+  expect(() => {
+    plugin.triggerMenuEntry('Non Existing');
+  }).toThrowErrorMatchingInlineSnapshot(
+    `"No menu entry found with action: Non Existing"`,
+  );
+});

desktop/flipper-plugin/src/index.ts

@@ -7,6 +7,7 @@
  * @format
  */
 
+import './plugin/PluginBase';
 import * as TestUtilites from './test-utils/test-utils';
 
 export {
@@ -26,6 +27,12 @@ export {SandyPluginDefinition} from './plugin/SandyPluginDefinition';
 export {SandyPluginRenderer} from './plugin/PluginRenderer';
 export {SandyPluginContext, usePlugin} from './plugin/PluginContext';
 export {createState, useValue, Atom} from './state/atom';
+export {FlipperLib} from './plugin/FlipperLib';
+export {
+  MenuEntry,
+  NormalizedMenuEntry,
+  buildInMenuEntries,
+} from './plugin/MenuEntry';
 
 // It's not ideal that this exists in flipper-plugin sources directly,
 // but is the least pain for plugin authors.

desktop/flipper-plugin/src/plugin/DevicePlugin.tsx

@@ -9,6 +9,7 @@
 
 import {SandyPluginDefinition} from './SandyPluginDefinition';
 import {BasePluginInstance, BasePluginClient} from './PluginBase';
+import {FlipperLib} from './FlipperLib';
 
 export type DeviceLogListener = (entry: DeviceLogEntry) => void;
 
@@ -69,11 +70,12 @@ export class SandyDevicePluginInstance extends BasePluginInstance {
   client: DevicePluginClient;
 
   constructor(
-    realDevice: RealFlipperDevice,
+    flipperLib: FlipperLib,
     definition: SandyPluginDefinition,
+    realDevice: RealFlipperDevice,
     initialStates?: Record<string, any>,
   ) {
-    super(definition, initialStates);
+    super(flipperLib, definition, initialStates);
     const device: Device = {
       // N.B. we model OS as string, not as enum, to make custom device types possible in the future
       os: realDevice.os,

desktop/flipper-plugin/src/plugin/FlipperLib.tsx

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+import {NormalizedMenuEntry} from './MenuEntry';
+
+/**
+ * This interface exposes all global methods for which an implementation will be provided by Flipper itself
+ */
+export interface FlipperLib {
+  enableMenuEntries(menuEntries: NormalizedMenuEntry[]): void;
+}

desktop/flipper-plugin/src/plugin/MenuEntry.tsx

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+export type DefaultKeyboardAction = 'clear' | 'goToBottom' | 'createPaste';
+export type TopLevelMenu = 'Edit' | 'View' | 'Window' | 'Help';
+
+export type MenuEntry = BuiltInMenuEntry | CustomMenuEntry;
+
+export type NormalizedMenuEntry = {
+  label: string;
+  accelerator?: string;
+  topLevelMenu: TopLevelMenu;
+  handler: () => void;
+  action: string;
+};
+
+export type CustomMenuEntry = {
+  label: string;
+  accelerator?: string;
+  topLevelMenu: TopLevelMenu;
+  handler: () => void;
+};
+
+export type BuiltInMenuEntry = {
+  action: keyof typeof buildInMenuEntries;
+  handler: () => void;
+};
+
+export const buildInMenuEntries = {
+  clear: {
+    label: 'Clear',
+    accelerator: 'CmdOrCtrl+K',
+    topLevelMenu: 'View',
+    action: 'clear',
+  },
+  goToBottom: {
+    label: 'Go To Bottom',
+    accelerator: 'CmdOrCtrl+B',
+    topLevelMenu: 'View',
+    action: 'goToBottom',
+  },
+  createPaste: {
+    label: 'Create Paste',
+    topLevelMenu: 'Edit',
+    action: 'createPaste',
+  },
+} as const;
+
+export function normalizeMenuEntry(entry: MenuEntry): NormalizedMenuEntry;
+export function normalizeMenuEntry(entry: any): NormalizedMenuEntry {
+  const builtInEntry:
+    | NormalizedMenuEntry
+    | undefined = (buildInMenuEntries as any)[entry.action];
+  return builtInEntry
+    ? {...builtInEntry, ...entry}
+    : {
+        ...entry,
+        action: entry.action || entry.label,
+      };
+}

desktop/flipper-plugin/src/plugin/Plugin.tsx

@@ -9,6 +9,7 @@
 
 import {SandyPluginDefinition} from './SandyPluginDefinition';
 import {BasePluginInstance, BasePluginClient} from './PluginBase';
+import {FlipperLib} from './FlipperLib';
 
 type EventsContract = Record<string, any>;
 type MethodsContract = Record<string, (params: any) => Promise<any>>;
@@ -96,11 +97,12 @@ export class SandyPluginInstance extends BasePluginInstance {
   connected = false;
 
   constructor(
-    realClient: RealFlipperClient,
+    flipperLib: FlipperLib,
     definition: SandyPluginDefinition,
+    realClient: RealFlipperClient,
     initialStates?: Record<string, any>,
   ) {
-    super(definition, initialStates);
+    super(flipperLib, definition, initialStates);
     this.realClient = realClient;
     this.definition = definition;
     this.client = {

desktop/flipper-plugin/src/plugin/PluginBase.tsx

@@ -10,6 +10,8 @@
 import {SandyPluginDefinition} from './SandyPluginDefinition';
 import {EventEmitter} from 'events';
 import {Atom} from '../state/atom';
+import {MenuEntry, NormalizedMenuEntry, normalizeMenuEntry} from './MenuEntry';
+import {FlipperLib} from './FlipperLib';
 
 export interface BasePluginClient {
   /**
@@ -31,6 +33,11 @@ export interface BasePluginClient {
    * Triggered when this plugin is opened through a deeplink
    */
   onDeepLink(cb: (deepLink: unknown) => void): void;
+
+  /**
+   * Register menu entries in the Flipper toolbar
+   */
+  addMenuEntry(...entry: MenuEntry[]): void;
 }
 
 let currentPluginInstance: BasePluginInstance | undefined = undefined;
@@ -46,6 +53,8 @@ export function getCurrentPluginInstance(): typeof currentPluginInstance {
 }
 
 export abstract class BasePluginInstance {
+  /** generally available Flipper APIs */
+  flipperLib: FlipperLib;
   /** the original plugin definition */
   definition: SandyPluginDefinition;
   /** the plugin instance api as used inside components and such  */
@@ -62,10 +71,14 @@ export abstract class BasePluginInstance {
   // last seen deeplink
   lastDeeplink?: any;
 
+  menuEntries: NormalizedMenuEntry[] = [];
+
   constructor(
+    flipperLib: FlipperLib,
     definition: SandyPluginDefinition,
     initialStates?: Record<string, any>,
   ) {
+    this.flipperLib = flipperLib;
     this.definition = definition;
     this.initialStates = initialStates;
   }
@@ -95,6 +108,21 @@ export abstract class BasePluginInstance {
       onDestroy: (cb) => {
         this.events.on('destroy', cb);
       },
+      addMenuEntry: (...entries) => {
+        for (const entry of entries) {
+          const normalized = normalizeMenuEntry(entry);
+          if (
+            this.menuEntries.find(
+              (existing) =>
+                existing.label === normalized.label ||
+                existing.action === normalized.action,
+            )
+          ) {
+            throw new Error(`Duplicate menu entry: '${normalized.label}'`);
+          }
+          this.menuEntries.push(normalizeMenuEntry(entry));
+        }
+      },
     };
   }
 
@@ -103,6 +131,7 @@ export abstract class BasePluginInstance {
     this.assertNotDestroyed();
     if (!this.activated) {
       this.activated = true;
+      this.flipperLib.enableMenuEntries(this.menuEntries);
       this.events.emit('activate');
     }
   }
@@ -112,8 +141,8 @@ export abstract class BasePluginInstance {
       return;
     }
     if (this.activated) {
-      this.lastDeeplink = undefined;
       this.activated = false;
+      this.lastDeeplink = undefined;
       this.events.emit('deactivate');
     }
   }

desktop/flipper-plugin/src/test-utils/test-utils.tsx

@@ -35,6 +35,7 @@ import {
   DeviceLogListener,
 } from '../plugin/DevicePlugin';
 import {BasePluginInstance} from '../plugin/PluginBase';
+import {FlipperLib} from '../plugin/FlipperLib';
 
 type Renderer = RenderResult<typeof queries>;
 
@@ -61,6 +62,11 @@ type ExtractEventsType<
   : never;
 
 interface BasePluginResult {
+  /**
+   * Mock for Flipper utilities
+   */
+  flipperLib: FlipperLib;
+
   /**
    * Emulates the 'onActivate' event
    */
@@ -84,6 +90,11 @@ interface BasePluginResult {
    * Grab all the persistable state
    */
   exportState(): any;
+
+  /**
+   * Trigger menu entry by label
+   */
+  triggerMenuEntry(label: string): void;
 }
 
 interface StartPluginResult<Module extends FlipperPluginModule<any>>
@@ -165,8 +176,9 @@ export function startPlugin<Module extends FlipperPluginModule<any>>(
   }
 
   const sendStub = jest.fn();
-  const fakeFlipper: RealFlipperClient = {
-    isBackgroundPlugin() {
+  const flipperUtils = createMockFlipperLib();
+  const fakeFlipperClient: RealFlipperClient = {
+    isBackgroundPlugin(_pluginId: string) {
       return !!options?.isBackgroundPlugin;
     },
     initPlugin() {
@@ -186,8 +198,9 @@ export function startPlugin<Module extends FlipperPluginModule<any>>(
   };
 
   const pluginInstance = new SandyPluginInstance(
-    fakeFlipper,
+    flipperUtils,
     definition,
+    fakeFlipperClient,
     options?.initialState,
   );
 
@@ -258,10 +271,12 @@ export function startDevicePlugin<Module extends FlipperDevicePluginModule>(
     );
   }
 
+  const flipperLib = createMockFlipperLib();
   const testDevice = createMockDevice(options);
   const pluginInstance = new SandyDevicePluginInstance(
-    testDevice,
+    flipperLib,
     definition,
+    testDevice,
     options?.initialState,
   );
 
@@ -306,10 +321,17 @@ export function renderDevicePlugin<Module extends FlipperDevicePluginModule>(
   };
 }
 
+export function createMockFlipperLib(): FlipperLib {
+  return {
+    enableMenuEntries: jest.fn(),
+  };
+}
+
 function createBasePluginResult(
   pluginInstance: BasePluginInstance,
 ): BasePluginResult {
   return {
+    flipperLib: pluginInstance.flipperLib,
     activate: () => pluginInstance.activate(),
     deactivate: () => pluginInstance.deactivate(),
     exportState: () => pluginInstance.exportState(),
@@ -317,6 +339,13 @@ function createBasePluginResult(
       pluginInstance.triggerDeepLink(deepLink);
     },
     destroy: () => pluginInstance.destroy(),
+    triggerMenuEntry: (action: string) => {
+      const entry = pluginInstance.menuEntries.find((e) => e.action === action);
+      if (!entry) {
+        throw new Error('No menu entry found with action: ' + action);
+      }
+      entry.handler();
+    },
   };
 }