feat: add support for share menu on macOS (electron#25629)

docs/api/menu-item.md

@@ -14,7 +14,7 @@ See [`Menu`](menu.md) for examples.
     * `menuItem` MenuItem
     * `browserWindow` [BrowserWindow](browser-window.md) | undefined - This will not be defined if no window is open.
     * `event` [KeyboardEvent](structures/keyboard-event.md)
-  * `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu` - Define the action of the menu item, when specified the
+  * `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `shareMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu` - Define the action of the menu item, when specified the
     `click` property will be ignored. See [roles](#roles).
   * `type` String (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
     `radio`.
@@ -31,6 +31,7 @@ See [`Menu`](menu.md) for examples.
     menu items.
   * `registerAccelerator` Boolean (optional) _Linux_ _Windows_ - If false, the accelerator won't be registered
     with the system, but it will still be displayed. Defaults to true.
+  * `sharingItem` SharingItem (optional) _macOS_ - The item to share when the `role` is `shareMenu`.
   * `submenu` (MenuItemConstructorOptions[] | [Menu](menu.md)) (optional) - Should be specified
     for `submenu` type menu items. If `submenu` is specified, the `type: 'submenu'` can be omitted.
     If the value is not a [`Menu`](menu.md) then it will be automatically converted to one using
@@ -112,6 +113,7 @@ The following additional roles are available on _macOS_:
 * `services` - The submenu is a ["Services"](https://developer.apple.com/documentation/appkit/nsapplication/1428608-servicesmenu?language=objc) menu. This is only intended for use in the Application Menu and is *not* the same as the "Services" submenu used in context menus in macOS apps, which is not implemented in Electron.
 * `recentDocuments` - The submenu is an "Open Recent" menu.
 * `clearRecentDocuments` - Map to the `clearRecentDocuments` action.
+* `shareMenu` - The submenu is [share menu][ShareMenu]. The `sharingItem` property must also be set to indicate the item to share.
 
 When specifying a `role` on macOS, `label` and `accelerator` are the only
 options that will affect the menu item. All other options will be ignored.
@@ -200,10 +202,18 @@ system or just displayed.
 
 This property can be dynamically changed.
 
+#### `menuItem.sharingItem` _macOS_
+
+A `SharingItem` indicating the item to share when the `role` is `shareMenu`.
+
+This property can be dynamically changed.
+
 #### `menuItem.commandId`
 
 A `Number` indicating an item's sequential unique id.
 
 #### `menuItem.menu`
 
 A `Menu` that the item is a part of.
+
+[ShareMenu]: https://developer.apple.com/design/human-interface-guidelines/macos/extensions/share-extensions/

docs/api/share-menu.md

@@ -0,0 +1,45 @@
+## Class: ShareMenu
+
+> Create share menu on macOS.
+
+Process: [Main](../glossary.md#main-process)
+
+The `ShareMenu` class creates [Share Menu][share-menu] on macOS, which can be
+used to share information from the current context to apps, social media
+accounts, and other services.
+
+For including the share menu as a submenu of other menus, please use the
+`shareMenu` role of [`MenuItem`](menu-item.md).
+
+### `new ShareMenu(sharingItem)`
+
+* `sharingItem` SharingItem - The item to share.
+
+Creates a new share menu.
+
+### Instance Methods
+
+The `shareMenu` object has the following instance methods:
+
+#### `shareMenu.popup([options])`
+
+* `options` PopupOptions (optional)
+  * `browserWindow` [BrowserWindow](browser-window.md) (optional) - Default is the focused window.
+  * `x` Number (optional) - Default is the current mouse cursor position.
+    Must be declared if `y` is declared.
+  * `y` Number (optional) - Default is the current mouse cursor position.
+    Must be declared if `x` is declared.
+  * `positioningItem` Number (optional) _macOS_ - The index of the menu item to
+    be positioned under the mouse cursor at the specified coordinates. Default
+    is -1.
+  * `callback` Function (optional) - Called when menu is closed.
+
+Pops up this menu as a context menu in the [`BrowserWindow`](browser-window.md).
+
+#### `shareMenu.closePopup([browserWindow])`
+
+* `browserWindow` [BrowserWindow](browser-window.md) (optional) - Default is the focused window.
+
+Closes the context menu in the `browserWindow`.
+
+[share-menu]: https://developer.apple.com/design/human-interface-guidelines/macos/extensions/share-extensions/

docs/api/structures/sharing-item.md

@@ -0,0 +1,5 @@
+# SharingItem Object
+
+* `texts` String[] (optional) - An array of text to share.
+* `filePaths` String[] (optional) - An array of files to share.
+* `urls` String[] (optional) - An array of URLs to share.

filenames.auto.gni

@@ -49,6 +49,7 @@ auto_filenames = {
     "docs/api/screen.md",
     "docs/api/service-workers.md",
     "docs/api/session.md",
+    "docs/api/share-menu.md",
     "docs/api/shell.md",
     "docs/api/structures",
     "docs/api/synopsis.md",
@@ -119,6 +120,7 @@ auto_filenames = {
     "docs/api/structures/serial-port.md",
     "docs/api/structures/service-worker-info.md",
     "docs/api/structures/shared-worker-info.md",
+    "docs/api/structures/sharing-item.md",
     "docs/api/structures/shortcut-details.md",
     "docs/api/structures/size.md",
     "docs/api/structures/task.md",
@@ -219,6 +221,7 @@ auto_filenames = {
     "lib/browser/api/protocol.ts",
     "lib/browser/api/screen.ts",
     "lib/browser/api/session.ts",
+    "lib/browser/api/share-menu.ts",
     "lib/browser/api/system-preferences.ts",
     "lib/browser/api/touch-bar.ts",
     "lib/browser/api/tray.ts",

lib/browser/api/menu-item-roles.ts

@@ -6,7 +6,7 @@ const isLinux = process.platform === 'linux';
 
 type RoleId = 'about' | 'close' | 'copy' | 'cut' | 'delete' | 'forcereload' | 'front' | 'help' | 'hide' | 'hideothers' | 'minimize' |
   'paste' | 'pasteandmatchstyle' | 'quit' | 'redo' | 'reload' | 'resetzoom' | 'selectall' | 'services' | 'recentdocuments' | 'clearrecentdocuments' | 'startspeaking' | 'stopspeaking' |
-  'toggledevtools' | 'togglefullscreen' | 'undo' | 'unhide' | 'window' | 'zoom' | 'zoomin' | 'zoomout' | 'appmenu' | 'filemenu' | 'editmenu' | 'viewmenu' | 'windowmenu'
+  'toggledevtools' | 'togglefullscreen' | 'undo' | 'unhide' | 'window' | 'zoom' | 'zoomin' | 'zoomout' | 'appmenu' | 'filemenu' | 'editmenu' | 'viewmenu' | 'windowmenu' | 'sharemenu'
 interface Role {
   label: string;
   accelerator?: string;
@@ -261,6 +261,11 @@ export const roleList: Record<RoleId, Role> = {
         { role: 'close' }
       ] as MenuItemConstructorOptions[])
     ]
+  },
+  // Share submenu
+  sharemenu: {
+    label: 'Share',
+    submenu: []
   }
 };
 

lib/browser/api/menu.ts

@@ -41,6 +41,12 @@ Menu.prototype._shouldRegisterAcceleratorForCommandId = function (id) {
   return this.commandsMap[id] ? this.commandsMap[id].registerAccelerator : false;
 };
 
+if (process.platform === 'darwin') {
+  Menu.prototype._getSharingItemForCommandId = function (id) {
+    return this.commandsMap[id] ? this.commandsMap[id].sharingItem : null;
+  };
+}
+
 Menu.prototype._executeCommand = function (event, id) {
   const command = this.commandsMap[id];
   if (!command) return;

lib/browser/api/module-list.ts

@@ -26,6 +26,7 @@ export const browserModuleList: ElectronInternal.ModuleEntry[] = [
   { name: 'protocol', loader: () => require('./protocol') },
   { name: 'screen', loader: () => require('./screen') },
   { name: 'session', loader: () => require('./session') },
+  { name: 'ShareMenu', loader: () => require('./share-menu') },
   { name: 'systemPreferences', loader: () => require('./system-preferences') },
   { name: 'TouchBar', loader: () => require('./touch-bar') },
   { name: 'Tray', loader: () => require('./tray') },

lib/browser/api/module-names.ts

@@ -29,6 +29,7 @@ export const browserModuleNames = [
   'protocol',
   'screen',
   'session',
+  'ShareMenu',
   'systemPreferences',
   'TouchBar',
   'Tray',

lib/browser/api/share-menu.ts

@@ -0,0 +1,19 @@
+import { BrowserWindow, Menu, SharingItem, PopupOptions } from 'electron/main';
+
+class ShareMenu {
+  private menu: Menu;
+
+  constructor (sharingItem: SharingItem) {
+    this.menu = new (Menu as any)({ sharingItem });
+  }
+
+  popup (options?: PopupOptions) {
+    this.menu.popup(options);
+  }
+
+  closePopup (browserWindow?: BrowserWindow) {
+    this.menu.closePopup(browserWindow);
+  }
+}
+
+export default ShareMenu;

shell/browser/api/electron_api_menu.cc

@@ -12,12 +12,39 @@
 #include "shell/browser/native_window.h"
 #include "shell/common/gin_converters/accelerator_converter.h"
 #include "shell/common/gin_converters/callback_converter.h"
+#include "shell/common/gin_converters/file_path_converter.h"
+#include "shell/common/gin_converters/gurl_converter.h"
 #include "shell/common/gin_converters/image_converter.h"
 #include "shell/common/gin_helper/dictionary.h"
 #include "shell/common/gin_helper/object_template_builder.h"
 #include "shell/common/node_includes.h"
 #include "ui/base/models/image_model.h"
 
+#if defined(OS_MAC)
+
+namespace gin {
+
+using SharingItem = electron::ElectronMenuModel::SharingItem;
+
+template <>
+struct Converter<SharingItem> {
+  static bool FromV8(v8::Isolate* isolate,
+                     v8::Local<v8::Value> val,
+                     SharingItem* out) {
+    gin_helper::Dictionary dict;
+    if (!ConvertFromV8(isolate, val, &dict))
+      return false;
+    dict.GetOptional("texts", &(out->texts));
+    dict.GetOptional("filePaths", &(out->file_paths));
+    dict.GetOptional("urls", &(out->urls));
+    return true;
+  }
+};
+
+}  // namespace gin
+
+#endif
+
 namespace electron {
 
 namespace api {
@@ -26,6 +53,15 @@ gin::WrapperInfo Menu::kWrapperInfo = {gin::kEmbedderNativeGin};
 
 Menu::Menu(gin::Arguments* args) : model_(new ElectronMenuModel(this)) {
   model_->AddObserver(this);
+
+#if defined(OS_MAC)
+  gin_helper::Dictionary options;
+  if (args->GetNext(&options)) {
+    ElectronMenuModel::SharingItem item;
+    if (options.Get("sharingItem", &item))
+      model_->SetSharingItem(std::move(item));
+  }
+#endif
 }
 
 Menu::~Menu() {
@@ -81,6 +117,19 @@ bool Menu::ShouldRegisterAcceleratorForCommandId(int command_id) const {
                           command_id);
 }
 
+#if defined(OS_MAC)
+bool Menu::GetSharingItemForCommandId(
+    int command_id,
+    ElectronMenuModel::SharingItem* item) const {
+  v8::Isolate* isolate = JavascriptEnvironment::GetIsolate();
+  v8::HandleScope handle_scope(isolate);
+  v8::Local<v8::Value> val =
+      gin_helper::CallMethod(isolate, const_cast<Menu*>(this),
+                             "_getSharingItemForCommandId", command_id);
+  return gin::ConvertFromV8(isolate, val, item);
+}
+#endif
+
 void Menu::ExecuteCommand(int command_id, int flags) {
   v8::Isolate* isolate = JavascriptEnvironment::GetIsolate();
   v8::HandleScope scope(isolate);

shell/browser/api/electron_api_menu.h

@@ -64,6 +64,11 @@ class Menu : public gin::Wrappable<Menu>,
       bool use_default_accelerator,
       ui::Accelerator* accelerator) const override;
   bool ShouldRegisterAcceleratorForCommandId(int command_id) const override;
+#if defined(OS_MAC)
+  bool GetSharingItemForCommandId(
+      int command_id,
+      ElectronMenuModel::SharingItem* item) const override;
+#endif
   void ExecuteCommand(int command_id, int event_flags) override;
   void OnMenuWillShow(ui::SimpleMenuModel* source) override;
 

shell/browser/ui/cocoa/electron_menu_controller.h

@@ -23,7 +23,8 @@ class ElectronMenuModel;
 // allow for hierarchical menus). The tag is the index into that model for
 // that particular item. It is important that the model outlives this object
 // as it only maintains weak references.
-@interface ElectronMenuController : NSObject <NSMenuDelegate> {
+@interface ElectronMenuController
+    : NSObject <NSMenuDelegate, NSSharingServiceDelegate> {
  @protected
   base::WeakPtr<electron::ElectronMenuModel> model_;
   base::scoped_nsobject<NSMenu> menu_;