Addition of the webextensions.api.tabGroups documentation

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

@@ -0,0 +1,30 @@
+---
+title: tabGroups.Color
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/Color
+page-type: webextension-api-type
+browser-compat: webextensions.api.tabGroups.Color
+---
+
+{{AddonSidebar}}
+
+The color of a tab group.
+
+## Type
+
+Values of this type are a {{jsxref("string")}} and can take these values:
+
+- blue
+- cyan
+- grey
+- green
+- orange
+- pink
+- purple
+- red
+- yello
+
+{{WebExtExamples("h2")}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,33 @@
+---
+title: tabGroups.get
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/get
+page-type: webextension-api-function
+browser-compat: webextensions.api.tabGroups.get
+---
+
+{{AddonSidebar}}
+
+Returns details about a tab group.
+
+## Syntax
+
+```js-nolint
+let tabGroupDetails = await browser.tabGroups.get(
+    groupId                // integer
+);
+```
+
+### Parameters
+
+- `groupId`
+  - : `integer` The ID of the tab group to return details for.
+
+### Return value
+
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("tabGroups.TabGroup")}} object. If the request fails, the promise is rejected with an error message.
+
+{{WebExtExamples("h2")}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,65 @@
+---
+title: tabGroups
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups
+page-type: webextension-api
+browser-compat: webextensions.api.tabGroups
+---
+
+{{AddonSidebar}}
+
+This API enables extensions to modify and rearrange [tab groups](https://support.mozilla.org/en-US/kb/tab-groups).
+
+Tab groups persist across browser restarts, except for tab groups in private browsing windows.
+
+The `tabGroups` API does not offer the ability to create or remove tab groups. Use the {{WebExtAPIRef("tabs.group()")}} and {{WebExtAPIRef("tabs.ungroup()")}} methods instead. To query the position of a tab group within a window, use {{WebExtAPIRef("tabs.query()")}}. These APIs in the `tabs` namespace do not require any permissions.
+
+## Permissions
+
+To use this API, an extension must request the `"tabGroups"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in its [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. The `"tabGroups"` permission is not shown to users in permission prompts.
+
+## Types
+
+- {{WebExtAPIRef("tabGroups.Color")}}
+  - : The color of a tab group.
+- {{WebExtAPIRef("tabGroups.TabGroup")}}
+  - : The state of a tab group.
+
+## Properties
+
+- {{WebExtAPIRef("tabGroups.TAB_GROUP_ID_NONE")}}
+  - : The tab group ID value returned when a tab isn't in a tab group.
+
+## Functions
+
+- {{WebExtAPIRef("tabGroups.get()")}}
+  - : Returns details about a tab group.
+- {{WebExtAPIRef("tabGroups.move()")}}
+  - : Moves a tab group within or to another window.
+- {{WebExtAPIRef("tabGroups.query()")}}
+  - : Returns all tab groups or finds tab groups with certain properties.
+- {{WebExtAPIRef("tabGroups.update()")}}
+  - : Modifies the state of a tab group.
+
+## Events
+
+- {{WebExtAPIRef("tabGroups.onCreated")}}
+  - : Fires when a tab group is created.
+- {{WebExtAPIRef("tabGroups.onMoved")}}
+  - : Fires when a tab group is moved, within a window or to another window.
+- {{WebExtAPIRef("tabGroups.onRemoved")}}
+  - : Fires when a tab group is removed.
+- {{WebExtAPIRef("tabGroups.onUpdated")}}
+  - : Fires when a tab group is updated.
+
+{{WebExtExamples("h2")}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{WebExtAPIRef("tabs.group()")}}
+- {{WebExtAPIRef("tabs.ungroup()")}}
+- {{WebExtAPIRef("tabs.query()")}}
+- {{WebExtAPIRef("tabs.Tab")}}

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

@@ -0,0 +1,42 @@
+---
+title: tabGroups.move
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/move
+page-type: webextension-api-function
+browser-compat: webextensions.api.tabGroups.move
+---
+
+{{AddonSidebar}}
+
+Moves a tab group within or to another window.
+
+## Syntax
+
+```js-nolint
+let movedTabGroup = await browser.tabGroups.move(
+    groupId,                // integer
+    moveProperties          // object
+);
+```
+
+### Parameters
+
+- `groupId`
+
+  - : `integer` The ID of the tab group to move.
+
+- `moveProperties`
+  - : An object containing details of the location to move the tab group to.
+    - `index`
+      - : `integer` The position to move the group to. Use -1 to place the group at the end of the window.
+    - `windowId` {{optional_inline}}
+      - : `integer` The window to move the group to. Defaults to the window the group is in. Groups can only be moved to and from windows with {{WebExtAPIRef("windows.WindowType")}} type `"normal"`.
+
+### Return value
+
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("tabGroups.TabGroup")}} object. If the request fails, the promise is rejected with an error message.
+
+{{WebExtExamples("h2")}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,58 @@
+---
+title: tabGroups.onCreated
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onCreated
+page-type: webextension-api-event
+browser-compat: webextensions.api.tabGroups.onCreated
+---
+
+{{AddonSidebar}}
+
+Fires when a tab group is created.
+
+## Syntax
+
+```js-nolint
+browser.tabGroups.onCreated.addListener(listener)
+browser.tabGroups.onCreated.removeListener(listener)
+browser.tabGroups.onCreated.hasListener(listener)
+```
+
+Events have three functions:
+
+- `addListener(listener)`
+  - : Adds a listener to this event.
+- `removeListener(listener)`
+  - : Stops listening to this event. The `listener` argument is the listener to remove.
+- `hasListener(listener)`
+  - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
+
+## addListener syntax
+
+### Parameters
+
+- `listener`
+
+  - : The function called when this event occurs. The function is passed this argument:
+
+    - `group`
+      - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the created tab group's state.
+
+## Examples
+
+Listen for and log tab group creation:
+
+```js
+function tabGroupCreated(group) {
+  console.log(
+    `Tab group with ID ${group.id} was created in window ${group.windowId}.`,
+  );
+}
+
+browser.tabGroups.onCreated.addListener(tabGroupCreated);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,61 @@
+---
+title: tabGroups.onMoved
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onMoved
+page-type: webextension-api-event
+browser-compat: webextensions.api.tabGroups.onMoved
+---
+
+{{AddonSidebar}}
+
+Fires when a tab group is moved, within a window or to another window. {{WebExtAPIRef("tabs.onMoved")}} also fire for the tabs within the group.
+
+The event is passed a {{WebExtAPIRef("tabGroups.TabGroup")}} object. This includes the `windowId` but not the position of the tab group. To determine the position of the tab group, use {{WebExtAPIRef("tabs.query()")}} with the `groupId`, and read the `index` property of the returned result.
+In Chrome, this event doesn't fire when a tab group is moved between windows; instead, the group is removed from one window and created in another (firing {{WebExtAPIRef("tabGroups.onRemoved")}} and {{WebExtAPIRef("tabGroups.onCreated")}}.
+
+## Syntax
+
+```js-nolint
+browser.tabGroups.onMoved.addListener(listener)
+browser.tabGroups.onMoved.removeListener(listener)
+browser.tabGroups.onMoved.hasListener(listener)
+```
+
+Events have three functions:
+
+- `addListener(listener)`
+  - : Adds a listener to this event.
+- `removeListener(listener)`
+  - : Stops listening to this event. The `listener` argument is the listener to remove.
+- `hasListener(listener)`
+  - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
+
+## addListener syntax
+
+### Parameters
+
+- `listener`
+
+  - : The function called when this event occurs. The function is passed this argument:
+
+    - `group`
+      - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the moved tab group's state.
+
+## Examples
+
+Listen for and log tab group movement:
+
+```js
+function tabGroupMoved(group) {
+  console.log(
+    `Tab group with ID ${group.id} was moved to window ${group.windowId}.`,
+  );
+}
+
+browser.tabGroups.onMoved.addListener(tabGroupMoved);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,58 @@
+---
+title: tabGroups.onRemoved
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onRemoved
+page-type: webextension-api-event
+browser-compat: webextensions.api.tabGroups.onRemoved
+---
+
+{{AddonSidebar}}
+
+Fires when a tab group is removed. This can occur when a user closes a tab group or a tab group is closed automatically because another change means it no longer contained any tabs.
+
+> [!NOTE] In Firefox, this event does not fire when a window is closed ([bug 1965007](https://bugzil.la/1965007)). As an alternative, use {{WebExtAPIRef("windows.onRemoved")}} to detect closed windows, and retrieve the remaining set of groups with {{WebExtAPIRef("tabGroups.query()")}}.
+
+## Syntax
+
+```js-nolint
+browser.tabGroups.onRemoved.addListener(listener)
+browser.tabGroups.onRemoved.removeListener(listener)
+browser.tabGroups.onRemoved.hasListener(listener)
+```
+
+Events have three functions:
+
+- `addListener(listener)`
+  - : Adds a listener to this event.
+- `removeListener(listener)`
+  - : Stops listening to this event. The `listener` argument is the listener to remove.
+- `hasListener(listener)`
+  - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
+
+## addListener syntax
+
+### Parameters
+
+- `listener`
+
+  - : The function called when this event occurs. The function is passed this argument:
+
+    - `group`
+      - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the removed tab group's state.
+
+## Examples
+
+Listen for and log tab group removals:
+
+```js
+function tabGroupRemoved(group) {
+  console.log(`Tab group with ID ${group.id} was removed.`);
+}
+
+browser.tabGroups.onRemoved.addListener(tabGroupRemoved);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}