feat: surface more webContents text selection commands (#37978)

* feat: surface more text selection commands

* refactor: use options argument

* docs: correct for review

docs/api/web-contents.md

@@ -1389,6 +1389,10 @@ Executes the editing command `cut` in web page.
 
 Executes the editing command `copy` in web page.
 
+#### `contents.centerSelection()`
+
+Centers the current text selection in web page.
+
 #### `contents.copyImageAt(x, y)`
 
 * `x` Integer
@@ -1416,6 +1420,46 @@ Executes the editing command `selectAll` in web page.
 
 Executes the editing command `unselect` in web page.
 
+#### `contents.scrollToTop()`
+
+Scrolls to the top of the current `webContents`.
+
+#### `contents.scrollToBottom()`
+
+Scrolls to the bottom of the current `webContents`.
+
+#### `contents.adjustSelection(options)`
+
+* `options` Object
+  * `start` Number (optional) - Amount to shift the start index of the current selection.
+  * `end` Number (optional) - Amount to shift the end index of the current selection.
+
+Adjusts the current text selection starting and ending points in the focused frame by the given amounts. A negative amount moves the selection towards the beginning of the document, and a positive amount moves the selection towards the end of the document.
+
+Example:
+
+```js
+const win = new BrowserWindow()
+
+// Adjusts the beginning of the selection 1 letter forward,
+// and the end of the selection 5 letters forward.
+win.webContents.adjustSelection({ start: 1, end: 5 })
+
+// Adjusts the beginning of the selection 2 letters forward,
+// and the end of the selection 3 letters backward.
+win.webContents.adjustSelection({ start: 2, end: -3 })
+```
+
+For a call of `win.webContents.adjustSelection({ start: 1, end: 5 })`
+
+Before:
+
+<img width="487" alt="Image Before Text Selection Adjustment" src="https://user-images.githubusercontent.com/2036040/231761306-cd4e7b15-c2ed-46cf-8e80-10811f6de83e.png">
+
+After:
+
+<img width="487" alt="Image After Text Selection Adjustment" src="https://user-images.githubusercontent.com/2036040/231761169-887eb8ef-06fb-46e4-9efa-898bcb0d6a2b.png">
+
 #### `contents.replace(text)`
 
 * `text` string

docs/api/webview-tag.md

@@ -463,6 +463,10 @@ Executes editing command `cut` in page.
 
 Executes editing command `copy` in page.
 
+#### `<webview>.centerSelection()`
+
+Centers the current text selection in page.
+
 ### `<webview>.paste()`
 
 Executes editing command `paste` in page.
@@ -483,6 +487,25 @@ Executes editing command `selectAll` in page.
 
 Executes editing command `unselect` in page.
 
+#### `<webview>.scrollToTop()`
+
+Scrolls to the top of the current `<webview>`.
+
+#### `<webview>.scrollToBottom()`
+
+Scrolls to the bottom of the current `<webview>`.
+
+#### `<webview>.adjustSelection(options)`
+
+* `options` Object
+  * `start` Number (optional) - Amount to shift the start index of the current selection.
+  * `end` Number (optional) - Amount to shift the end index of the current selection.
+
+Adjusts the current text selection starting and ending points in the focused frame by the given amounts. A negative amount moves the selection towards the beginning of the document, and a positive amount moves the selection towards the end of the document.
+
+See [`webContents.adjustSelection`](web-contents.md#contentsadjustselectionoptions) for
+examples.
+
 ### `<webview>.replace(text)`
 
 * `text` string

lib/common/web-view-methods.ts

@@ -31,11 +31,15 @@ export const syncMethods = new Set([
   'redo',
   'cut',
   'copy',
+  'centerSelection',
   'paste',
   'pasteAndMatchStyle',
   'delete',
   'selectAll',
   'unselect',
+  'scrollToTop',
+  'scrollToBottom',
+  'adjustSelection',
   'replace',
   'replaceMisspelling',
   'findInPage',

shell/browser/api/electron_api_web_contents.cc

@@ -3095,6 +3095,10 @@ void WebContents::Copy() {
   web_contents()->Copy();
 }
 
+void WebContents::CenterSelection() {
+  web_contents()->CenterSelection();
+}
+
 void WebContents::Paste() {
   web_contents()->Paste();
 }
@@ -3115,6 +3119,30 @@ void WebContents::Unselect() {
   web_contents()->CollapseSelection();
 }
 
+void WebContents::ScrollToTopOfDocument() {
+  web_contents()->ScrollToTopOfDocument();
+}
+
+void WebContents::ScrollToBottomOfDocument() {
+  web_contents()->ScrollToBottomOfDocument();
+}
+
+void WebContents::AdjustSelectionByCharacterOffset(gin::Arguments* args) {
+  int start_adjust = 0;
+  int end_adjust = 0;
+
+  gin_helper::Dictionary dict;
+  if (args->GetNext(&dict)) {
+    dict.Get("start", &start_adjust);
+    dict.Get("matchCase", &end_adjust);
+  }
+
+  // The selection menu is a Chrome-specific piece of UI.
+  // TODO(codebytere): maybe surface as an event in the future?
+  web_contents()->AdjustSelectionByCharacterOffset(
+      start_adjust, end_adjust, false /* show_selection_menu */);
+}
+
 void WebContents::Replace(const std::u16string& word) {
   web_contents()->Replace(word);
 }
@@ -4148,11 +4176,16 @@ void WebContents::FillObjectTemplate(v8::Isolate* isolate,
       .SetMethod("redo", &WebContents::Redo)
       .SetMethod("cut", &WebContents::Cut)
       .SetMethod("copy", &WebContents::Copy)
+      .SetMethod("centerSelection", &WebContents::CenterSelection)
       .SetMethod("paste", &WebContents::Paste)
       .SetMethod("pasteAndMatchStyle", &WebContents::PasteAndMatchStyle)
       .SetMethod("delete", &WebContents::Delete)
       .SetMethod("selectAll", &WebContents::SelectAll)
       .SetMethod("unselect", &WebContents::Unselect)
+      .SetMethod("scrollToTop", &WebContents::ScrollToTopOfDocument)
+      .SetMethod("scrollToBottom", &WebContents::ScrollToBottomOfDocument)
+      .SetMethod("adjustSelection",
+                 &WebContents::AdjustSelectionByCharacterOffset)
       .SetMethod("replace", &WebContents::Replace)
       .SetMethod("replaceMisspelling", &WebContents::ReplaceMisspelling)
       .SetMethod("findInPage", &WebContents::FindInPage)

shell/browser/api/electron_api_web_contents.h

@@ -241,11 +241,15 @@ class WebContents : public ExclusiveAccessContext,
   void Redo();
   void Cut();
   void Copy();
+  void CenterSelection();
   void Paste();
   void PasteAndMatchStyle();
   void Delete();
   void SelectAll();
   void Unselect();
+  void ScrollToTopOfDocument();
+  void ScrollToBottomOfDocument();
+  void AdjustSelectionByCharacterOffset(gin::Arguments* args);
   void Replace(const std::u16string& word);
   void ReplaceMisspelling(const std::u16string& word);
   uint32_t FindInPage(gin::Arguments* args);