path: root/comm/mail/components/extensions/schemas/theme.json

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
[
  {
    "namespace": "manifest",
    "types": [
      {
        "$extend": "PermissionNoPrompt",
        "choices": [
          {
            "type": "string",
            "enum": ["theme"]
          }
        ]
      },
      {
        "id": "ThemeColor",
        "description": "Defines a color value.",
        "choices": [
          {
            "type": "string",
            "description": "A string containing a valid `CSS color string <|link-css-color-string|>`__, including hexadecimal or functional representations. For example the color *crimson* can be specified as: <li><value>crimson</value> <li><value>#dc143c</value> <li><value>rgb(220, 20, 60)</value> (or <value>rgba(220, 20, 60, 0.5)</value> to set 50% opacity) <li><value>hsl(348, 83%, 47%)</value> (or <value>hsla(348, 83%, 47%, 0.5)</value> to set 50% opacity)"
          },
          {
            "type": "array",
            "description": "An RGB array of 3 integers. For example <value>[220, 20, 60]</value> for the color *crimson*.",
            "minItems": 3,
            "maxItems": 3,
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 255
            }
          },
          {
            "type": "array",
            "description": "An RGBA array of 3 integers and a fractional (a float between 0 and 1). For example <value>[220, 20, 60, 0.5]<value> for the color *crimson* with 50% opacity.",
            "minItems": 4,
            "maxItems": 4,
            "items": {
              "type": "number"
            }
          }
        ]
      },
      {
        "id": "ThemeExperiment",
        "description": "Defines additional color, image and property keys to be used in :ref:`theme.ThemeType`, extending the theme-able areas of Thunderbird.",
        "type": "object",
        "properties": {
          "stylesheet": {
            "optional": true,
            "description": "URL to a stylesheet introducing additional CSS variables, extending the theme-able areas of Thunderbird. The `theme_experiment add-on in our example repository <https://github.com/thunderbird/sample-extensions/tree/master/theme_experiment>`__ is using the stylesheet shown below, to add the <value>--chat-button-color</value> CSS color variable: <literalinclude>includes/theme/theme_experiment_style.css<lang>CSS</lang></literalinclude>The following <em>manifest.json</em> file maps the </value>--chat-button-color</value> CSS color variable to the theme color key <value>exp_chat_button</value> and uses it to set a color for the chat button: <literalinclude>includes/theme/theme_experiment_manifest.json<lang>JSON</lang></literalinclude>",
            "$ref": "ExtensionURL"
          },
          "images": {
            "type": "object",
            "optional": true,
            "description": "A <em>dictionary object</em> with one or more <em>key-value</em> pairs to map new theme image keys to internal Thunderbird CSS image variables. The new image key is usable as an image reference in :ref:`theme.ThemeType`. Example: <literalinclude>includes/theme/theme_experiment_image.json<lang>JSON</lang></literalinclude>",
            "additionalProperties": {
              "type": "string"
            }
          },
          "colors": {
            "type": "object",
            "optional": true,
            "description": "A <em>dictionary object</em> with one or more <em>key-value</em> pairs to map new theme color keys to internal Thunderbird CSS color variables. The example shown below maps the theme color key <value>popup_affordance</value> to the CSS color variable </value>--arrowpanel-dimmed</value>. The new color key is usable as a color reference in :ref:`theme.ThemeType`. <literalinclude>includes/theme/theme_experiment_color.json<lang>JSON</lang></literalinclude>",
            "additionalProperties": {
              "type": "string"
            }
          },
          "properties": {
            "type": "object",
            "optional": true,
            "description": "A <em>dictionary object</em> with one or more <em>key-value</em> pairs to map new theme property keys to internal Thunderbird CSS property variables. The new property key is usable as a property reference in :ref:`theme.ThemeType`. Example: <literalinclude>includes/theme/theme_experiment_property.json<lang>JSON</lang></literalinclude>",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      {
        "id": "ThemeType",
        "description": "Contains the color, image and property settings of a theme.",
        "type": "object",
        "properties": {
          "images": {
            "description": "A <em>dictionary object</em> with one or more <em>key-value</em> pairs to map images to theme image keys. The following built-in theme image keys are supported:",
            "type": "object",
            "optional": true,
            "properties": {
              "additional_backgrounds": {
                "type": "array",
                "items": {
                  "$ref": "ImageDataOrExtensionURL"
                },
                "maxItems": 15,
                "optional": true,
                "description": "Additional images added to the header area and displayed behind the ``theme_frame`` image."
              },
              "headerURL": {
                "$ref": "ImageDataOrExtensionURL",
                "optional": true,
                "deprecated": "Unsupported images property, use ``theme.images.theme_frame``, this alias is ignored in Thunderbird >= 70."
              },
              "theme_frame": {
                "$ref": "ImageDataOrExtensionURL",
                "optional": true,
                "description": "Foreground image on the header area."
              }
            },
            "additionalProperties": {
              "$ref": "ImageDataOrExtensionURL"
            }
          },
          "colors": {
            "description": "A <em>dictionary object</em> with one or more <em>key-value</em> pairs to map color values to theme color keys. The following built-in theme color keys are supported:",
            "type": "object",
            "optional": true,
            "properties": {
              "tab_selected": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "Background color of the selected tab. Defaults to the color specified by ``toolbar``."
              },
              "accentcolor": {
                "$ref": "ThemeColor",
                "optional": true,
                "deprecated": "Unsupported colors property, use ``theme.colors.frame``, this alias is ignored in Thunderbird >= 70."
              },
              "frame": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The background color of the header area."
              },
              "frame_inactive": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The background color of the header area when the window is inactive."
              },
              "textcolor": {
                "$ref": "ThemeColor",
                "optional": true,
                "deprecated": "Unsupported color property, use ``theme.colors.tab_background_text``, this alias is ignored in Thunderbird >= 70."
              },
              "tab_background_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The text color of the unselected tabs."
              },
              "tab_background_separator": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the vertical separator of the background tabs."
              },
              "tab_loading": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the tab loading indicator."
              },
              "tab_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The text color for the selected tab. Defaults to the color specified by ``toolbar_text``."
              },
              "tab_line": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the selected tab line."
              },
              "toolbar": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The background color of the toolbars. Also used as default value for ``tab_selected``."
              },
              "toolbar_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The text color in the main Thunderbird toolbar. Also used as default value for ``icons`` and ``tab_text``."
              },
              "bookmark_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "Not used in Thunderbird."
              },
              "toolbar_field": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The background color for fields in the toolbar, such as the search field."
              },
              "toolbar_field_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The text color for fields in the toolbar."
              },
              "toolbar_field_border": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The border color for fields in the toolbar."
              },
              "toolbar_field_separator": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "Not used in Thunderbird.",
                "deprecated": "This color property is ignored in >= 89."
              },
              "toolbar_top_separator": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the line separating the top of the toolbar from the region above."
              },
              "toolbar_bottom_separator": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the line separating the bottom of the toolbar from the region below."
              },
              "toolbar_vertical_separator": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the vertical separators on the toolbars."
              },
              "icons": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the toolbar icons. Defaults to the color specified by ``toolbar_text``."
              },
              "icons_attention": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the toolbar icons in attention state such as the chat icon with new messages."
              },
              "button_background_hover": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the background of the toolbar buttons on hover."
              },
              "button_background_active": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color of the background of the pressed toolbar buttons."
              },
              "popup": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The background color of popups such as the AppMenu."
              },
              "popup_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The text color of popups."
              },
              "popup_border": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The border color of popups."
              },
              "toolbar_field_focus": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The focused background color for fields in the toolbar."
              },
              "toolbar_field_text_focus": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The text color in the focused fields in the toolbar."
              },
              "toolbar_field_border_focus": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The focused border color for fields in the toolbar."
              },
              "popup_highlight": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The background color of items highlighted using the keyboard inside popups."
              },
              "popup_highlight_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The text color of items highlighted using the keyboard inside popups."
              },
              "ntp_background": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "Not used in Thunderbird."
              },
              "ntp_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "Not used in Thunderbird."
              },
              "sidebar": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The background color of the trees."
              },
              "sidebar_border": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The border color of the trees."
              },
              "sidebar_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The text color of the trees. Needed to enable the tree theming."
              },
              "sidebar_highlight": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The background color of highlighted rows in trees."
              },
              "sidebar_highlight_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The text color of highlighted rows in trees."
              },
              "sidebar_highlight_border": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The border color of highlighted rows in trees."
              },
              "toolbar_field_highlight": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The background color used to indicate the current selection of text in the search field."
              },
              "toolbar_field_highlight_text": {
                "$ref": "ThemeColor",
                "optional": true,
                "description": "The color used to draw text that's currently selected in the search field."
              }
            },
            "additionalProperties": {
              "$ref": "ThemeColor"
            }
          },
          "properties": {
            "description": "A <em>dictionary object</em> with one or more <em>key-value</em> pairs to map property values to theme property keys. The following built-in theme property keys are supported:",
            "type": "object",
            "optional": true,
            "properties": {
              "additional_backgrounds_alignment": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "bottom",
                    "center",
                    "left",
                    "right",
                    "top",
                    "center bottom",
                    "center center",
                    "center top",
                    "left bottom",
                    "left center",
                    "left top",
                    "right bottom",
                    "right center",
                    "right top"
                  ]
                },
                "maxItems": 15,
                "optional": true
              },
              "additional_backgrounds_tiling": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": ["no-repeat", "repeat", "repeat-x", "repeat-y"]
                },
                "maxItems": 15,
                "optional": true
              },
              "color_scheme": {
                "description": "If set, overrides the general theme (context menus, toolbars, content area).",
                "optional": true,
                "type": "string",
                "enum": ["light", "dark", "auto"]
              },
              "content_color_scheme": {
                "description": "If set, overrides the color scheme for the content area.",
                "optional": true,
                "type": "string",
                "enum": ["light", "dark", "auto"]
              }
            },
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "additionalProperties": {
          "$ref": "UnrecognizedProperty"
        }
      },
      {
        "id": "ThemeManifest",
        "type": "object",
        "description": "Contents of manifest.json for a static theme",
        "$import": "manifest.ManifestBase",
        "properties": {
          "theme": {
            "$ref": "ThemeType"
          },
          "dark_theme": {
            "$ref": "ThemeType",
            "optional": true,
            "description": "Fallback properties for the dark system theme."
          },
          "default_locale": {
            "type": "string",
            "optional": true
          },
          "theme_experiment": {
            "$ref": "ThemeExperiment",
            "optional": true,
            "description": "CSS file with additional styles."
          },
          "icons": {
            "type": "object",
            "optional": true,
            "patternProperties": {
              "^[1-9]\\d*$": {
                "type": "string"
              }
            },
            "description": "Icons shown in the Add-ons Manager."
          }
        }
      },
      {
        "$extend": "WebExtensionManifest",
        "properties": {
          "theme_experiment": {
            "$ref": "ThemeExperiment",
            "optional": true,
            "description": "A theme experiment allows modifying the user interface of Thunderbird beyond what is currently possible using the built-in color, image and property keys of :ref:`theme.ThemeType`. These experiments are a precursor to proposing new theme features for inclusion in Thunderbird. Experimentation is done by mapping internal CSS color, image and property variables to new theme keys and using them in :ref:`theme.ThemeType` and by loading additional style sheets to add new CSS variables, extending the theme-able areas of Thunderbird. Can be used in static and dynamic themes."
          }
        }
      }
    ]
  },
  {
    "namespace": "theme",
    "description": "The theme API allows for customization of Thunderbird's visual elements.",
    "types": [
      {
        "id": "ThemeUpdateInfo",
        "type": "object",
        "description": "Info provided in the onUpdated listener.",
        "properties": {
          "theme": {
            "$ref": "ThemeType",
            "description": "The new theme after update"
          },
          "windowId": {
            "type": "integer",
            "description": "The id of the window the theme has been applied to",
            "optional": true
          }
        }
      }
    ],
    "events": [
      {
        "name": "onUpdated",
        "type": "function",
        "description": "Fired when a new theme has been applied",
        "parameters": [
          {
            "$ref": "ThemeUpdateInfo",
            "name": "updateInfo",
            "description": "Details of the theme update"
          }
        ]
      }
    ],
    "functions": [
      {
        "name": "getCurrent",
        "type": "function",
        "async": "callback",
        "description": "Returns the current theme for the specified window or the last focused window.",
        "parameters": [
          {
            "type": "integer",
            "name": "windowId",
            "optional": true,
            "description": "The window for which we want the theme."
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "$ref": "ThemeType"
              }
            ]
          }
        ]
      },
      {
        "name": "update",
        "type": "function",
        "async": true,
        "description": "Make complete updates to the theme. Resolves when the update has completed.",
        "permissions": ["theme"],
        "parameters": [
          {
            "type": "integer",
            "name": "windowId",
            "optional": true,
            "description": "The id of the window to update. No id updates all windows."
          },
          {
            "name": "details",
            "$ref": "manifest.ThemeType",
            "description": "The properties of the theme to update."
          }
        ]
      },
      {
        "name": "reset",
        "type": "function",
        "async": true,
        "description": "Removes the updates made to the theme.",
        "permissions": ["theme"],
        "parameters": [
          {
            "type": "integer",
            "name": "windowId",
            "optional": true,
            "description": "The id of the window to reset. No id resets all windows."
          }
        ]
      }
    ]
  }
]