add documentation for spaces API, sessions API and new menu typed act…

…ion buttons

browserAction.rst

@@ -102,7 +102,7 @@ Manifest file properties
       :name: [``default_popup``]
       :type: (string, optional)
 
-      The html document to be opened as a popup when the user clicks on the browserAction button.
+      The html document to be opened as a popup when the user clicks on the browserAction button. Ignored for action buttons with type :value:`menu`.
 
 
    .. api-member::
@@ -133,6 +133,21 @@ Manifest file properties
 
       Specifies dark and light icons to be used with themes. The ``light`` icon is used on dark backgrounds and vice versa. **Note:** The default theme uses the ``default_icon`` for light backgrounds (if specified).
 
+
+   .. api-member::
+      :name: [``type``]
+      :type: (`string`, optional)
+
+      Specifies the type of the button. Default type is :code:`button`.
+
+      Supported values:
+
+      .. api-member::
+         :name: :value:`button`
+
+      .. api-member::
+         :name: :value:`menu`
+
 
 .. rst-class:: api-permission-info
 
@@ -685,7 +700,7 @@ openPopup([options])
 
 .. api-section-annotation-hack:: 
 
-Opens the action's popup window in the specified window. Defaults to the current window. Returns false if the popup could not be opened because the action is disabled or has been removed from the toolbar.
+Opens the action's popup window in the specified window. Defaults to the current window. Returns false if the popup could not be opened because the action has no popup, is of type :value:`menu`, is disabled or has been removed from the toolbar.
 
 .. api-header::
    :label: Parameters

changes/beta115.rst

@@ -9,6 +9,7 @@ If an add-on is not requesting that permission, but a reviewer concludes that it
 browserAction API
 =================
 * Deprecate the ``default_area`` manifest entry in favour of the recently added ``allowed_spaces`` manifest entry.
+* Add support for the ``type`` manifest entry to define a ``menu`` button, whose menu entries can be controlled through the :ref:`menus_api` and a new ``browser_action_menu`` context.
 
 addressBooks API
 ================
@@ -18,15 +19,28 @@ commands API
 ============
 * Add the :ref:`commands.onChanged` event to be notified when a command shortcut has been changed.
 
+compose API
+===========
+* Add support for the ``type`` manifest entry to define a ``menu`` button, whose menu entries can be controlled through the :ref:`menus_api` and a new ``compose_action_menu`` context.
+
 messages API
 ============
 * The ``queryInfo`` parameter for :ref:`messages.query` is now optional.
 * Added :ref:`messages.openAttachment` to open message attachments with the registered application. A big thank you to Mark Banner.
+* Add support for the ``type`` manifest entry to define a ``menu`` button, whose menu entries can be controlled through the :ref:`menus_api` and a new ``message_display_action_menu`` context.
 
 messageDisplay API
 ==================
 * Added support for :ref:`messageDisplay.open` to open messages from a DOM File object.
 
+sessions API
+==========
+* Add a first simple version of the :ref:`sessions_api` to allow extensions to store tab related session data, which is restored on app restart.
+
+spaces API
+==========
+* Add :ref:`spaces_api` which supersedes the spacesToolbar and allows to manage built-in and custom spaces.
+
 spacesToolbar API
 =================
 * Add :ref:`spacesToolbar.clickButton` to trigger a click on the button of a space in the spaces toolbar. In Manifest v3 the button-centric ``spacesToolbar API`` was removed and replaced by the space-centric ``spaces API``, where the corresponding method is named `spaces.open() <https://webextension-api.thunderbird.net/en/latest-mv3/spaces.html#open-spaceid-windowid>`__.

composeAction.rst

@@ -66,7 +66,7 @@ Manifest file properties
       :name: [``default_popup``]
       :type: (string, optional)
 
-      The html document to be opened as a popup when the user clicks on the composeAction button.
+      The html document to be opened as a popup when the user clicks on the composeAction button. Ignored for action buttons with type :value:`menu`.
 
 
    .. api-member::
@@ -82,6 +82,21 @@ Manifest file properties
 
       Specifies dark and light icons to be used with themes. The ``light`` icon is used on dark backgrounds and vice versa. **Note:** The default theme uses the ``default_icon`` for light backgrounds (if specified).
 
+
+   .. api-member::
+      :name: [``type``]
+      :type: (`string`, optional)
+
+      Specifies the type of the button. Default type is :code:`button`.
+
+      Supported values:
+
+      .. api-member::
+         :name: :value:`button`
+
+      .. api-member::
+         :name: :value:`menu`
+
 
 .. rst-class:: api-permission-info
 
@@ -634,7 +649,7 @@ openPopup([options])
 
 .. api-section-annotation-hack:: 
 
-Opens the action's popup window in the specified window. Defaults to the current window. Returns false if the popup could not be opened because the action is disabled or has been removed from the toolbar.
+Opens the action's popup window in the specified window. Defaults to the current window. Returns false if the popup could not be opened because the action has no popup, is of type :value:`menu`, is disabled or has been removed from the toolbar.
 
 .. api-header::
    :label: Parameters

index.rst

@@ -82,6 +82,10 @@ Thunderbird provides the following messenger related WebExtension APIs, which ar
 +-------------------------------+------------------------------------------------------------+
 | :doc:`messages`               | |messages-Description|                                     |
 +-------------------------------+------------------------------------------------------------+
+| :doc:`sessions`               | |sessions-Description|                                       |
++-------------------------------+------------------------------------------------------------+
+| :doc:`spaces`                 | |spaces-Description|                                       |
++-------------------------------+------------------------------------------------------------+
 | :doc:`spacesToolbar`          | |spacesToolbar-Description|                                |
 +-------------------------------+------------------------------------------------------------+
 | :doc:`tabs`                   | |tabs-Description|                                         |
@@ -111,6 +115,8 @@ Thunderbird provides the following messenger related WebExtension APIs, which ar
 .. |messageDisplayAction-Description| replace:: Enables an extension to interact with a `message display action button`_. 
 .. |messageDisplayScripts-Description| replace:: Functionally is the same as the contentScripts API except that it works on the document of email messages being displayed.
 .. |messages-Description| replace:: Enables an extension to list, search, read, copy, move and delete messages.
+.. |sessions-Description| replace:: Enables an extension to store tab related session data for individual tabs (restored on app restart).
+.. |spaces-Description| replace:: Enables an extension to interact with Thunderbird's spaces, and to create custom spaces.
 .. |spacesToolbar-Description| replace:: Enables an extension to interact with Thunderbird's spaces toolbar.
 .. |tabs-Description| replace:: Enables an extension to interact with Thunderbird's tab system. It allows to create, modify, and rearrange tabs and to communicate with scripts in tabs.
 .. |windows-Description| replace:: Enables an extension to interact with Thunderbird's windows which can contain webpage tabs and also with other window types like composer or address books that cannot contain webpage tabs. You can use this API to create, modify, and rearrange windows.
@@ -257,6 +263,8 @@ as well. The APIs listed in the following table are known to work with Thunderbi
   messageDisplayAction
   messageDisplayScripts
   messages
+  sessions
+  spaces
   spacesToolbar
   theme
   tabs

menus.rst

@@ -563,6 +563,9 @@ The different contexts a menu can appear in. Specifying :value:`all` is equivale
          .. api-member::
             :name: :value:`compose_action`
 
+         .. api-member::
+            :name: :value:`compose_action_menu`
+
          .. api-member::
             :name: :value:`compose_attachments`
 
@@ -590,6 +593,9 @@ The different contexts a menu can appear in. Specifying :value:`all` is equivale
          .. api-member::
             :name: :value:`message_display_action`
 
+         .. api-member::
+            :name: :value:`message_display_action_menu`
+
          .. api-member::
             :name: :value:`message_list`
 
@@ -626,6 +632,9 @@ OR
 
          .. api-member::
             :name: :value:`browser_action`
+
+         .. api-member::
+            :name: :value:`browser_action_menu`
 
 
 .. _menus.ItemType:

messageDisplayAction.rst

@@ -60,7 +60,7 @@ Manifest file properties
       :name: [``default_popup``]
       :type: (string, optional)
 
-      The html document to be opened as a popup when the user clicks on the messageDisplayAction button.
+      The html document to be opened as a popup when the user clicks on the messageDisplayAction button. Ignored for action buttons with type :value:`menu`.
 
 
    .. api-member::
@@ -76,6 +76,21 @@ Manifest file properties
 
       Specifies dark and light icons to be used with themes. The ``light`` icon is used on dark backgrounds and vice versa. **Note:** The default theme uses the ``default_icon`` for light backgrounds (if specified).
 
+
+   .. api-member::
+      :name: [``type``]
+      :type: (`string`, optional)
+
+      Specifies the type of the button. Default type is :code:`button`.
+
+      Supported values:
+
+      .. api-member::
+         :name: :value:`button`
+
+      .. api-member::
+         :name: :value:`menu`
+
 
 .. rst-class:: api-permission-info
 
@@ -628,7 +643,7 @@ openPopup([options])
 
 .. api-section-annotation-hack:: 
 
-Opens the action's popup window in the specified window. Defaults to the current window. Returns false if the popup could not be opened because the action is disabled or has been removed from the toolbar.
+Opens the action's popup window in the specified window. Defaults to the current window. Returns false if the popup could not be opened because the action has no popup, is of type :value:`menu`, is disabled or has been removed from the toolbar.
 
 .. api-header::
    :label: Parameters

overlay/sessions.rst

@@ -0,0 +1,5 @@
+========
+sessions
+========
+
+The sessions API first appeared in Thunderbird 115. It allows to add tab related session data to Thunderbird's tabs, which will be restored on app restart.

overlay/spaces.rst

@@ -0,0 +1,5 @@
+======
+spaces
+======
+
+The spaces API first appeared in Thunderbird 115. It allows to manage built-in and custom spaces, and to add buttons for custom spaces to Thunderbird's spaces toolbar.

sessions.rst

@@ -0,0 +1,114 @@
+.. _sessions_api:
+
+========
+sessions
+========
+
+The sessions API first appeared in Thunderbird 115. It allows to add tab related session data to Thunderbird's tabs, which will be restored on app restart.
+
+.. role:: permission
+
+.. role:: value
+
+.. role:: code
+
+.. rst-class:: api-main-section
+
+Functions
+=========
+
+.. _sessions.setTabValue:
+
+setTabValue(tabId, key, value)
+------------------------------
+
+.. api-section-annotation-hack:: 
+
+Store a key/value pair associated with a given tab.
+
+.. api-header::
+   :label: Parameters
+
+
+   .. api-member::
+      :name: ``tabId``
+      :type: (integer)
+
+      ID of the tab with which you want to associate the data. Error is thrown if ID is invalid.
+
+
+   .. api-member::
+      :name: ``key``
+      :type: (string)
+
+      Key that you can later use to retrieve this particular data value.
+
+
+   .. api-member::
+      :name: ``value``
+      :type: (string)
+
+
+.. _sessions.getTabValue:
+
+getTabValue(tabId, key)
+-----------------------
+
+.. api-section-annotation-hack:: 
+
+Retrieve a previously stored value for a given tab, given its key.
+
+.. api-header::
+   :label: Parameters
+
+
+   .. api-member::
+      :name: ``tabId``
+      :type: (integer)
+
+      ID of the tab whose data you are trying to retrieve. Error is thrown if ID is invalid.
+
+
+   .. api-member::
+      :name: ``key``
+      :type: (string)
+
+      Key identifying the particular value to retrieve.
+
+
+.. api-header::
+   :label: Return type (`Promise`_)
+
+
+   .. api-member::
+      :type: string
+
+
+   .. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+.. _sessions.removeTabValue:
+
+removeTabValue(tabId, key)
+--------------------------
+
+.. api-section-annotation-hack:: 
+
+Remove a key/value pair from a given tab.
+
+.. api-header::
+   :label: Parameters
+
+
+   .. api-member::
+      :name: ``tabId``
+      :type: (integer)
+
+      ID of the tab whose data you are trying to remove. Error is thrown if ID is invalid.
+
+
+   .. api-member::
+      :name: ``key``
+      :type: (string)
+
+      Key identifying the particular value to remove.
+