Improve the TypeScript definition

sindresorhus · Apr 9, 2019 · e9c36f0 · e9c36f0
1 parent d447280
commit e9c36f0
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 84 deletions.
diff --git a/fixture-menu.js b/fixture-menu.js
@@ -1,4 +1,5 @@
 'use strict';
+const path = require('path');
 const {
 	app,
 	BrowserWindow
@@ -32,5 +33,5 @@ contextMenu({
 (async () => {
 	await app.whenReady();
 
-	new BrowserWindow().loadURL(`file://${__dirname}/fixture.html`);
+	new BrowserWindow().loadFile(path.join(__dirname, 'fixture.html'));
 })();
diff --git a/fixture.js b/fixture.js
@@ -1,4 +1,5 @@
 'use strict';
+const path = require('path');
 const {app, BrowserWindow} = require('electron');
 const contextMenu = require('.');
 
@@ -41,5 +42,5 @@ contextMenu({
 (async () => {
 	await app.whenReady();
 
-	new BrowserWindow().loadURL(`file://${__dirname}/fixture.html`);
+	new BrowserWindow().loadFile(path.join(__dirname, 'fixture.html'));
 })();
diff --git a/index.d.ts b/index.d.ts
@@ -85,17 +85,6 @@ declare namespace contextMenu {
 			browserWindow: BrowserWindow | WebviewTag
 		) => MenuItem[];
 
-		/**
-		Should return an array of [menu items](https://electronjs.org/docs/api/menu-item) to override the default context menu.
-
-		@default [defaultActions.cut(), defaultActions.copy(), defaultActions.paste(), defaultActions.separator(), defaultActions.saveImage(), defaultActions.saveImageAs(), defaultActions.copyImageAddress(), defaultActions.separator(), defaultActions.copyLink(), defaultActions.separator(), defaultActions.inspect()]
-		*/
-		readonly menu?: (
-			defaultActions: Actions,
-			params: ContextMenuParams,
-			browserWindow: BrowserWindow | WebviewTag
-		) => MenuItem[];
-
 		/**
 		Should return an array of [menu items](https://electronjs.org/docs/api/menu-item) to be appended to the context menu.
 		*/
@@ -130,6 +119,16 @@ declare namespace contextMenu {
 		Overwrite labels for the default menu items. Useful for i18n.
 
 		@default {}
+
+		@example
+		```
+		{
+			labels: {
+				copy: 'Configured Copy',
+				saveImageAs: 'Configured Save Image As…'
+			}
+		}
+		```
 		*/
 		readonly labels?: Labels;
 
@@ -139,49 +138,65 @@ declare namespace contextMenu {
 
 		@example
 		```
-		// Doesn't show the menu if the element is editable
-		shouldShowMenu: (event, params) => !params.isEditable
+		{
+			// Doesn't show the menu if the element is editable
+			shouldShowMenu: (event, params) => !params.isEditable
+		}
 		```
 		*/
 		readonly shouldShowMenu?: (
 			event: ElectronEvent,
 			params: ContextMenuParams
 		) => boolean;
+
+		/**
+		This option lets you manually pick what menu items to include. It's meant for advanced needs. The default menu with the other options should be enough for most use-cases, and it ensures correct behavior, for example, correct order of menu items. So prefer the `append` and `prepend` option instead of `menu` whenever possible.
+
+		The function passed to this option is expected to return [`MenuItem[]`](https://electronjs.org/docs/api/menu-item/). The first argument the function receives is an array of default actions that can be used. These actions are functions that can take an object with a transform property (except for `separator` and `inspect`). The transform function will be passed the content of the action and can modify it if needed.
+
+		Even though you include an action, it will still only be shown/enabled when appropriate. For example, the `saveImage` action is only shown when right-clicking an image.
+
+		The following options are ignored when `menu` is used:
+
+		- `showCopyImageAddress`
+		- `showSaveImageAs`
+		- `showInspectElement`
+
+		@default [defaultActions.cut(), defaultActions.copy(), defaultActions.paste(), defaultActions.separator(), defaultActions.saveImage(), defaultActions.saveImageAs(), defaultActions.copyImageAddress(), defaultActions.separator(), defaultActions.copyLink(), defaultActions.separator(), defaultActions.inspect()]
+		*/
+		readonly menu?: (
+			defaultActions: Actions,
+			params: ContextMenuParams,
+			browserWindow: BrowserWindow | WebviewTag
+		) => MenuItem[];
 	}
 }
 
-declare const contextMenu: {
-	/**
-	This module gives you a nice extensible context menu with items like `Cut`/`Copy`/`Paste` for text, `Save Image` for images, and `Copy Link` for links. It also adds an `Inspect Element` menu item when in development to quickly view items in the inspector like in Chrome.
-
-	You can use this module directly in both the main and renderer process.
-
-	@example
-	```
-	import {app, BrowserWindow} from 'electron';
-	import contextMenu = require('electron-context-menu');
-
-	contextMenu({
-		prepend: (params, browserWindow) => [{
-			label: 'Rainbow',
-			// Only show it when right-clicking images
-			visible: params.mediaType === 'image'
-		}]
-	});
-
-	let win;
-	(async () => {
-		await app.whenReady();
-		win = new BrowserWindow();
-	});
-	```
-	*/
-	(options?: contextMenu.Options): void;
-
-	// TODO: Remove this for the next major release, refactor the whole definition to:
-	// declare function contextMenu(options?: contextMenu.Options): void;
-	// export = contextMenu;
-	default: typeof contextMenu;
-};
+/**
+This module gives you a nice extensible context menu with items like `Cut`/`Copy`/`Paste` for text, `Save Image` for images, and `Copy Link` for links. It also adds an `Inspect Element` menu item when in development to quickly view items in the inspector like in Chrome.
+
+You can use this module directly in both the main and renderer process.
+
+@example
+```
+import {app, BrowserWindow} from 'electron';
+import contextMenu = require('electron-context-menu');
+
+contextMenu({
+	prepend: (params, browserWindow) => [{
+		label: 'Rainbow',
+		// Only show it when right-clicking images
+		visible: params.mediaType === 'image'
+	}]
+});
+
+let mainWindow;
+(async () => {
+	await app.whenReady();
+	mainWindow = new BrowserWindow();
+});
+```
+*/
+declare function contextMenu(options?: contextMenu.Options): void;
 
 export = contextMenu;
diff --git a/readme.md b/readme.md
@@ -64,13 +64,17 @@ When not specified, the context menu will be added to all existing and new windo
 
 Type: `Function`
 
-Should return an array of [MenuItem](https://electronjs.org/docs/api/menu-item/)'s to be prepended to the context menu. The first argument is an array of default actions that can be used. The second argument is [this `params` object](https://electronjs.org/docs/api/web-contents/#event-context-menu). The third argument is the [BrowserWindow](https://electronjs.org/docs/api/browser-window/) the context menu was requested for.
+Should return an array of [MenuItem](https://electronjs.org/docs/api/menu-item/)'s to be prepended to the context menu.
+
+The first argument is an array of default actions that can be used. The second argument is [this `params` object](https://electronjs.org/docs/api/web-contents/#event-context-menu). The third argument is the [BrowserWindow](https://electronjs.org/docs/api/browser-window/) the context menu was requested for.
 
 #### append
 
 Type: `Function`
 
-Should return an array of [MenuItem](https://electronjs.org/docs/api/menu-item/)'s to be appended to the context menu. The first argument is an array of default actions that can be used. The second argument is [this `params` object](https://electronjs.org/docs/api/web-contents/#event-context-menu). The third argument is the [BrowserWindow](https://electronjs.org/docs/api/browser-window/) the context menu was requested for.
+Should return an array of [MenuItem](https://electronjs.org/docs/api/menu-item/)'s to be appended to the context menu.
+
+The first argument is an array of default actions that can be used. The second argument is [this `params` object](https://electronjs.org/docs/api/web-contents/#event-context-menu). The third argument is the [BrowserWindow](https://electronjs.org/docs/api/browser-window/) the context menu was requested for.
 
 #### showCopyImageAddress
 
@@ -103,38 +107,38 @@ Overwrite labels for the default menu items. Useful for i18n.
 Format:
 
 ```js
-labels: {
-	cut: 'Configured Cut',
-	copy: 'Configured Copy',
-	paste: 'Configured Paste',
-	save: 'Configured Save Image',
-	saveImageAs: 'Configured Save Image As…'
-	copyLink: 'Configured Copy Link',
-	copyImageAddress: 'Configured Copy Image Address',
-	inspect: 'Configured Inspect'
+{
+	labels: {
+		copy: 'Configured Copy',
+		saveImageAs: 'Configured Save Image As…'
+	}
 }
 ```
 
 #### shouldShowMenu
 
 Type: `Function`
 
-Determines whether or not to show the menu. Can be useful if you for example have other code presenting a context menu in some contexts. The second argument is [this `params` object](https://electronjs.org/docs/api/web-contents#event-context-menu).
+Determines whether or not to show the menu. Can be useful if you for example have other code presenting a context menu in some contexts.
+
+The second argument is [this `params` object](https://electronjs.org/docs/api/web-contents#event-context-menu).
 
 Example:
 
 ```js
-// Doesn't show the menu if the element is editable
-shouldShowMenu: (event, params) => !params.isEditable
+{
+	// Doesn't show the menu if the element is editable
+	shouldShowMenu: (event, params) => !params.isEditable
+}
 ```
 
 #### menu
 
 Type: `Function`
 
-This option lets you manually pick what menu items to include. It's meant for advanced needs. The default menu with the other options should be enough for most use-cases, and it ensures correct behavior, for example, correct order of menu items. Prefer the `append`/`prepend` options instead of `menu` whenever possible.
+This option lets you manually pick what menu items to include. It's meant for advanced needs. The default menu with the other options should be enough for most use-cases, and it ensures correct behavior, for example, correct order of menu items. So prefer the `append` and `prepend` option instead of `menu` whenever possible.
 
-The function passed this options is expected to return [`MenuItem[]`](https://electronjs.org/docs/api/menu-item/). The first argument the function receives is an array of default actions that can be used. These actions are functions that can take an object with a transform property (except for `separator` and `inspect`). The transform function will be passed the content of the action and can modify it if needed.
+The function passed to this option is expected to return [`MenuItem[]`](https://electronjs.org/docs/api/menu-item/). The first argument the function receives is an array of default actions that can be used. These actions are functions that can take an object with a transform property (except for `separator` and `inspect`). The transform function will be passed the content of the action and can modify it if needed.
 
 Even though you include an action, it will still only be shown/enabled when appropriate. For example, the `saveImage` action is only shown when right-clicking an image.
 
@@ -159,26 +163,28 @@ Default actions:
 Example:
 
 ```js
-menu: actions => [
-	actions.copyLink({
-		transform: content => `modified_link_${content}`
-	}),
-	actions.separator(),
-	{
-		label: 'Unicorn'
-	},
-	actions.separator(),
-	actions.copy({
-		transform: content => `modified_copy_${content}`
-	}),
-	{
-		label: 'Invisible',
-		visible: false
-	},
-	actions.paste({
-		transform: content => `modified_paste_${content}`
-	})
-]
+{
+	menu: actions => [
+		actions.copyLink({
+			transform: content => `modified_link_${content}`
+		}),
+		actions.separator(),
+		{
+			label: 'Unicorn'
+		},
+		actions.separator(),
+		actions.copy({
+			transform: content => `modified_copy_${content}`
+		}),
+		{
+			label: 'Invisible',
+			visible: false
+		},
+		actions.paste({
+			transform: content => `modified_paste_${content}`
+		})
+	]
+}
 ```