Adding search.query and search.search disposition

files/en-us/mozilla/add-ons/webextensions/api/search/index.md

@@ -15,19 +15,21 @@ browser-compat: webextensions.api.search
 
 {{AddonSidebar}}
 
-Retrieves search engines and executes a search with a specific search engine.
+Use the search API to retrieve the installed search engines and execute searches.
 
 To use this API you need to have the `"search"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
 
 ## Functions
 
 - {{WebExtAPIRef("search.get()")}}
   - : Retrieve all search engines.
+- {{WebExtAPIRef("search.query()")}}
+  - : Search using the browser's default search engine.
 - {{WebExtAPIRef("search.search()")}}
-  - : Search using the specified search engine.
-
-## Browser compatibility
+  - : Search using a specified search engine.
 
 {{WebExtExamples("h2")}}
 
+## Browser compatibility
+
 {{Compat}}

files/en-us/mozilla/add-ons/webextensions/api/search/query/index.md

@@ -0,0 +1,94 @@
+---
+title: search.query()
+slug: Mozilla/Add-ons/WebExtensions/API/search/query
+tags:
+  - API
+  - Add-ons
+  - Extensions
+  - Reference
+  - Search
+  - Search Engines
+  - WebExtensions
+browser-compat: webextensions.api.search.query
+---
+
+{{AddonSidebar()}}
+
+Perform a search using the browser's default search engine.
+
+The results are displayed in the current tab, a new tab, or a new window according to the `disposition` property or in the tab specified in the `tabId` property. If neither is specified, the results display in a new tab.
+
+To use this function, your extension must have the `"search"` [manifest permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
+
+To get the installed search engines, use {{WebExtAPIRef("search.get()")}}.
+
+## Syntax
+
+```js-nolint
+browser.search.query(
+  queryInfo             // object
+)
+```
+
+### Parameters
+
+- `queryInfo`
+
+  - : `object`. An object with the following properties:
+
+    - `disposition` {{optional_inline}}
+      - : `string`. The location where the search results are displayed. Valid values are `CURRENT_TAB`, `NEW_TAB`, and `NEW_WINDOW`. Defaults to `NEW_TAB`. Cannot be specified with `tabId`.
+    - `tabId` {{optional_inline}}
+      - : `integer`. An optional identifier for the tab you want to execute the search in. If this property is omitted, the search results are displayed in a new tab. Cannot be specified with `disposition`.
+    - `text`
+      - : `string`. The search query.
+
+### Return value
+
+None.
+
+## Examples
+
+A search with the results shown in the current tab (default):
+
+```js
+function search() {
+  browser.search.query({
+    text: "styracosaurus"
+  });
+}
+
+browser.browserAction.onClicked.addListener(search);
+```
+
+A search with the results shown in a new window:
+
+```js
+function search() {
+  browser.search.query({
+    text: "styracosaurus",
+    disposition: "NEW_WINDOW"
+  });
+}
+
+browser.browserAction.onClicked.addListener(search);
+```
+
+A search with the results shown in the current tab:
+
+```js
+function search(tab) {
+  browser.search.query({
+    query: "styracosaurus",
+    tabId: tab.id
+  });
+}
+
+browser.browserAction.onClicked.addListener(search);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/mozilla/add-ons/webextensions/api/search/search/index.md

@@ -15,11 +15,11 @@ browser-compat: webextensions.api.search.search
 
 {{AddonSidebar()}}
 
-Perform a search using the search engine specified, or the default search engine if no search engine is specified.
+Perform a search using the search engine specified or the default search engine if no search engine is specified.
 
-The results will be displayed in a new tab, or if the `tabId` argument is given, in the tab identified by this.
+The results are displayed in the current tab, a new tab, or a new window according to the `disposition` property or in the tab specified in the `tabId` property. If neither is specified, the results display in a new tab.
 
-To use this function in your extension you must ask for the `"search"` [manifest permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
+To use this function, your extension must have the `"search"` [manifest permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
 
 To get the installed search engines, use {{WebExtAPIRef("search.get()")}}.
 
@@ -37,24 +37,22 @@ browser.search.search(
 
   - : `object`. An object with the following properties:
 
+    - `disposition` {{optional_inline}}
+      - : `string`. The location where the search results are displayed. Valid values are `CURRENT_TAB`, `NEW_TAB`, and `NEW_WINDOW`. Defaults to `NEW_TAB`. Cannot be specified with `tabId`.
+    - `engine` {{optional_inline}}
+      - : `string`. The name of the search engine. If the search engine name doesn't exist, the function throws an error. If this property is omitted, the default search engine is used.
     - `query`
       - : `string`. The search query.
-    - `engine` {{optional_inline}}
-      - : `string`. The name of the search engine. If the search engine name you specify doesn't exist, the function throws an error. If this property is omitted the default search engine will be used.
     - `tabId` {{optional_inline}}
-      - : `integer`. An optional identifier for the tab you want to execute the search in. If this property is omitted the search results will be displayed in a new tab.
+      - : `integer`. An optional identifier for the tab you want to execute the search in. If this property is omitted, the search results are displayed in a new tab. Cannot be specified with `disposition`.
 
 ### Return value
 
 None.
 
-## Browser compatibility
-
-{{Compat}}
-
 ## Examples
 
-Search using the default search engine. The results will be shown in a new tab:
+A search using the default search engine with the results shown in the current tab (default):
 
 ```js
 function search() {
@@ -66,20 +64,21 @@ function search() {
 browser.browserAction.onClicked.addListener(search);
 ```
 
-Search using Wikipedia. The results will be shown in a new tab:
+A search using Wikipedia with the results shown in a new window:
 
 ```js
 function search() {
   browser.search.search({
     query: "styracosaurus",
     engine: "Wikipedia (en)"
+    disposition: "NEW_WINDOW"
   });
 }
 
 browser.browserAction.onClicked.addListener(search);
 ```
 
-Search using Wikipedia. The results will be shown in the active tab:
+A search using Wikipedia with the results shown in the current tab:
 
 ```js
 function search(tab) {
@@ -94,3 +93,7 @@ browser.browserAction.onClicked.addListener(search);
 ```
 
 {{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/mozilla/firefox/releases/111/index.md

@@ -70,7 +70,9 @@ This article provides information about the changes in Firefox 111 that affect d
 
 ## Changes for add-on developers
 
-- `matchDiacritics` has been added to the {{WebExtAPIRef("Find.find")}} API. This option enables searches to distinguish between accented letters and their base letters. For example, when set to `true`, searching for "résumé" does not find a match for "resume" ([Firefox bug 1680606](https://bugzil.la/1680606))
+- `matchDiacritics` has been added to the {{WebExtAPIRef("Find.find")}} API. This option enables searches to distinguish between accented letters and their base letters. For example, when set to `true`, searching for "résumé" does not find a match for "resume" [Firefox bug 1680606](https://bugzil.la/1680606).
+- {{WebExtAPIRef("search.query")}} has been added, providing search API compatibility with Chromium-based browsers [Firefox bug 1804357](https://bugzil.la/1804357).
+- The `disposition` property has been added to {{WebExtAPIRef("search.search")}}, enabling results to be displayed in a new tab or window [Firefox bug 1811274](https://bugzil.la/1811274).
 
 ### Removals