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/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');
     }
   }