Add contextualIdentities.move (mdn#31191)

* Add contextualIdentities.move

* typo

* Apply suggestions from review

* Examples update

* Apply suggestions from review

Co-authored-by: Rob Wu <rob@robwu.nl>

---------

Co-authored-by: Rob Wu <rob@robwu.nl>

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

@@ -35,7 +35,9 @@ To use this API you need to include the "contextualIdentities" and "cookies" [pe
 - {{WebExtAPIRef("contextualIdentities.create()")}}
   - : Creates a new contextual identity.
 - {{WebExtAPIRef("contextualIdentities.get()")}}
-  - : Retrieves a single contextual identity, given its cookie store ID.
+  - : Retrieves a contextual identity, given its cookie store ID.
+- {{WebExtAPIRef("contextualIdentities.move()")}}
+  - : Moves one or more contextual identities within the list of contextual identities.
 - {{WebExtAPIRef("contextualIdentities.query()")}}
   - : Retrieves all contextual identities, or all contextual identities with a particular name.
 - {{WebExtAPIRef("contextualIdentities.update()")}}

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

@@ -0,0 +1,94 @@
+---
+title: contextualIdentities.move()
+slug: Mozilla/Add-ons/WebExtensions/API/contextualIdentities/move
+page-type: webextension-api-function
+browser-compat: webextensions.api.contextualIdentities.move
+---
+
+{{AddonSidebar()}}
+
+Moves one or more contextual identities to a new position within the list of contextual identities.
+
+This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+
+## Syntax
+
+```js-nolint
+let moveContainers = browser.contextualIdentities.move(
+  cookieStoreIds,                  // string or array of string
+  position                         // integer
+)
+```
+
+### Parameters
+
+- `cookieStoreIds`
+  - : `string` or `array` of `string`. An ordered list of the contextual identity cookie store IDs to move.
+- `position`
+  - : `integer`. The position to move `cookieStoreIds` to in the list of contextual identities. Zero-based; `0` indicates the first position. `-1` indicates that the items are moved to the end of the list.
+
+### Return value
+
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled when the contextual identities are reordered. The promise is rejected if the request is for an invalid move or the contextual identities feature is not enabled.
+
+## Examples
+
+This example moves the first identity to the end and then back to the start.
+
+```js
+let identities = await browser.contextualIdentities.query({});
+let firstId = identities[0].cookieStoreId;
+
+// Moves first identity to the end.
+await browser.contextualIdentities.move(firstId, -1);
+
+// Move identity to the start again.
+await browser.contextualIdentities.move(firstId, 0);
+```
+
+Another way of moving the first identity to the end is by moving all other identities to the start.
+
+```js
+let identities = await browser.contextualIdentities.query({});
+let ids = identities.map((identity) => identity.cookieStoreId);
+// Create an array without the first item:
+let otherIds = ids.slice(1);
+
+// Move other identities to the start,
+// effectively putting the first identity at the end.
+await browser.contextualIdentities.move(otherIds, 0);
+```
+
+This example moves the "Personal" identity to before "Work". The example assumes containers with these names to exist. This may not be the case in customized or localized (non-English) Firefox instances.
+
+```js
+let identities = await browser.contextualIdentities.query({});
+
+// Find the index and ID of the container with the name "Personal".
+let personalIndex = identities.findIndex((ci) => ci.name === "Personal");
+if (personalIndex === -1) {
+  throw new Error("Personal container not found");
+}
+let personalId = identities[personalIndex].cookieStoreId;
+
+// Find the index of the container with the name "Work".
+let workIndex = identities.findIndex((identity) => identity.name === "Work");
+if (workIndex === -1) {
+  throw new Error("Work container not found!");
+}
+
+if (personalIndex < workIndex) {
+  // When the Personal identity moves, all following
+  // identities shift to the left by one. To place
+  // the Personal identity before the Work identity,
+  // we should therefore subtract one.
+  workIndex--;
+}
+await browser.contextualIdentities.move(personalId, workIndex);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -56,6 +56,8 @@ This article provides information about the changes in Firefox 123 that affect d
 
 ## Changes for add-on developers
 
+- Addition of fhe {{WebExtAPIRef("contextualIdentities.move")}} function enables items to be moved in the list of contextual identities. This function enables extensions to customize the order in which contextual identities display in the UI ([Firefox bug 1333395](https://bugzil.la/1333395)).
+
 ### Removals
 
 ### Other