Adding upstream version 110.0.1.upstream/110.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 364 insertions, 0 deletions

diff --git a/browser/components/touchbar/docs/index.rst b/browser/components/touchbar/docs/index.rst
new file mode 100644
index 0000000000..c6f7b05634
--- /dev/null
+++ b/browser/components/touchbar/docs/index.rst
@@ -0,0 +1,364 @@
+Touch Bar
+=========
+
+The Touch Bar is a hardware component on some MacBook Pros released from 2016.
+It is a display above the keyboard that allows more flexible types of
+input than is otherwise possible with a normal keyboard. Apple offers Touch Bar
+APIs so developers can extend the Touch Bar to display inputs specific to their
+application. Firefox consumes these APIs to offer a customizable row of inputs
+in the Touch Bar.
+
+In Apple's documentation, the term "the Touch Bar" refers to the hardware.
+The term "a Touch Bar" refers not to the hardware but to a collection of inputs
+shown on the Touch Bar. This means that there can be multiple "Touch Bars" that
+switch out as the user switches contexts. The same naming convention is used in
+this document.
+
+In this document and in the code, the word "input" is used to refer to
+an interactive element in the Touch Bar. It is often interchangeable with
+"button", but "input" can also refer to any element displayed in the Touch Bar.
+
+The Touch Bar should never offer functionality unavailable to Firefox users
+without the Touch Bar. Most macOS Firefox users do not have the Touch Bar and
+some choose to disable it. Apple's own `Human Interface Guidelines`_ (HIG)
+forbids this kind of Touch Bar functionality. Please read the HIG for more
+design considerations before you plan on implementing a new Touch Bar feature.
+
+If you have questions about the Touch Bar that are not answered in this
+document, feel free to reach out to `Harry Twyford`_ (:harry on Slack).
+He wrote this document and Firefox's initial Touch Bar implementation.
+
+.. _Human Interface Guidelines: https://developer.apple.com/design/human-interface-guidelines/macos/touch-bar/touch-bar-overview/
+
+.. _Harry Twyford: mailto:harry@mozilla.com
+
+.. contents:: Table of Contents
+
+Overview
+~~~~~~~~
+
+Firefox's Touch Bar implementation is equal parts JavaScript and Cocoa
+(Objective-C++). The JavaScript code lives in ``browser/components/touchbar``
+and the Cocoa code lives in ``widget/cocoa``, mostly in ``nsTouchBar.mm``. The
+Cocoa code is a consumer of Apple's Touch Bar APIs and defines what types of
+Touch Bar inputs are available to its own consumers. The JS code in
+``browser/components/touchbar`` provides services to ``nsTouchBar.mm`` and
+defines what inputs the user actually sees in the Touch Bar. There is two-way
+communication between the JS and the Cocoa: the Cocoa code asks the JS what
+inputs it should display, and the JS asks the Cocoa code to update those inputs
+when needed.
+
+JavaScript API
+~~~~~~~~~~~~~~
+
+``browser/components/touchbar/MacTouchBar.jsm`` defines what specific inputs are
+available to the user, what icon they will have, what action they will perform,
+and so on. Inputs are defined in the ``gBuiltInInputs`` object `in that file`_.
+When creating a new object in ``gBuiltInInputs``, the available properties are
+documented in the JSDoc for ``TouchBarInput``:
+
+.. highlight:: JavaScript
+.. code::
+
+  /**
+   * A representation of a Touch Bar input.
+   *     @param {string} input.title
+   *            The lookup key for the button's localized text title.
+   *     @param {string} input.image
+   *            A URL pointing to an SVG internal to Firefox.
+   *     @param {string} input.type
+   *            The type of Touch Bar input represented by the object.
+   *            Must be a value from kInputTypes.
+   *     @param {Function} input.callback
+   *            A callback invoked when a touchbar item is touched.
+   *     @param {string} [input.color]
+   *            A string in hex format specifying the button's background color.
+   *            If omitted, the default background color is used.
+   *     @param {bool} [input.disabled]
+   *            If `true`, the Touch Bar input is greyed out and inoperable.
+   *     @param {Array} [input.children]
+   *            An array of input objects that will be displayed as children of
+   *            this input. Available only for types KInputTypes.POPOVER and
+   *            kInputTypes.SCROLLVIEW.
+   */
+
+Clarification on some of these properties is warranted.
+
+* ``title`` is the key to a Fluent translation defined in ``browser/locales/<LOCALE>/browser/touchbar/touchbar.ftl``.
+* ``type`` must be a value from the ``kInputTypes`` enum in ``MacTouchBar.jsm``.
+  For example, ``kInputTypes.BUTTON``. More information on input types follows
+  below.
+* ``callback`` points to a JavaScript function. Any chrome-level JavaScript can
+  be executed. ``execCommand`` is a convenience method in ``MacTouchBar.jsm``
+  that takes a XUL command as a string and executes that command. For instance,
+  one input sets ``callback`` to ``execCommand("Browser:Back")``.
+* ``children`` is an array of objects with the same properties as members of
+  ``gBuiltInInputs``. When used with an input of type
+  ``kInputTypes.SCROLLVIEW``, ``children`` can only contain inputs of type
+  ``kInputTypes.BUTTON``. When used with an input of type
+  ``kInputTypes.POPOVER``, any input type except another ``kInputTypes.POPOVER``
+  can be used.
+
+.. _in that file: https://searchfox.org/mozilla-central/rev/ebe492edacc75bb122a2b380e4cafcca3470864c/browser/components/touchbar/MacTouchBar.jsm#82
+
+Input types
+-----------
+
+Button
+  A simple button. If ``image`` is not specified, the buttons displays the text
+  label from ``title``. If both ``image`` and ``title`` are specified, only the
+  ``image`` is shown. The action specified in ``callback`` is executed when the
+  button is pressed.
+
+  .. caution::
+
+    Even if the ``title`` will not be shown in the Touch Bar, you must still
+    define a ``title`` property.
+
+Main Button
+  Similar to a button, but displayed at double the width. A main button
+  displays both the string in ``title`` and the icon in ``image``. Only one
+  main button should be shown in the Touch Bar at any time, although this is
+  not enforced.
+
+Label
+  A non-interactive text label. This input takes only the attributes ``title``
+  and ``type``.
+
+Popover
+  Initially represented in the Touch Bar as a button, a popover will display an
+  entirely different set of inputs when pressed. These different inputs should
+  be defined in the ``children`` property of the parent. Popovers can also be
+  shown and hidden programmatically, by calling
+
+  .. highlight:: JavaScript
+  .. code::
+
+    gTouchBarUpdater.showPopover(
+      TouchBarHelper.baseWindow,
+      [POPOVER],
+      {true | false}
+    );
+
+  where the second argument is a reference to a popover TouchBarInput and
+  the third argument is whether the popover should be shown or hidden.
+
+Scroll View
+  A Scroll View is a scrolling list of buttons. The buttons should be defined
+  in the Scroll View's ``children`` array.
+
+  .. note::
+
+    In Firefox, a list of search shortcuts appears in the Touch Bar when the
+    address bar is focused. This is an example of a ScrollView contained within
+    a popover. The popover is opened programmatically with
+    ``gTouchBarUpdater.showPopover`` when the address bar is focused and it is
+    hidden when the address bar is blurred.
+
+Examples
+--------
+Some examples of ``gBuiltInInputs`` objects follow.
+
+A simple button
+  .. highlight:: JavaScript
+  .. code::
+
+    Back: {
+      title: "back",
+      image: "chrome://browser/skin/back.svg",
+      type: kInputTypes.BUTTON,
+      callback: () => execCommand("Browser:Back", "Back"),
+    },
+
+  A button is defined with a title, icon, type, and a callback. The callback
+  simply calls the XUL command to go back.
+
+The search popover
+  This is the input that occupies the Touch Bar when the address bar is focused.
+
+  .. highlight:: JavaScript
+  .. code::
+
+    SearchPopover: {
+      title: "search-popover",
+      image: "chrome://global/skin/icons/search-glass.svg",
+      type: kInputTypes.POPOVER,
+      children: {
+        SearchScrollViewLabel: {
+          title: "search-search-in",
+          type: kInputTypes.LABEL,
+        },
+        SearchScrollView: {
+          key: "search-scrollview",
+          type: kInputTypes.SCROLLVIEW,
+          children: {
+            Bookmarks: {
+              title: "search-bookmarks",
+              type: kInputTypes.BUTTON,
+              callback: () =>
+                gTouchBarHelper.insertRestrictionInUrlbar(
+                  UrlbarTokenizer.RESTRICT.BOOKMARK
+                ),
+            },
+            History: {
+              title: "search-history",
+              type: kInputTypes.BUTTON,
+              callback: () =>
+                gTouchBarHelper.insertRestrictionInUrlbar(
+                  UrlbarTokenizer.RESTRICT.HISTORY
+                ),
+            },
+            OpenTabs: {
+              title: "search-opentabs",
+              type: kInputTypes.BUTTON,
+              callback: () =>
+                gTouchBarHelper.insertRestrictionInUrlbar(
+                  UrlbarTokenizer.RESTRICT.OPENPAGE
+                ),
+            },
+            Tags: {
+              title: "search-tags",
+              type: kInputTypes.BUTTON,
+              callback: () =>
+                gTouchBarHelper.insertRestrictionInUrlbar(
+                  UrlbarTokenizer.RESTRICT.TAG
+                ),
+            },
+            Titles: {
+              title: "search-titles",
+              type: kInputTypes.BUTTON,
+              callback: () =>
+                gTouchBarHelper.insertRestrictionInUrlbar(
+                  UrlbarTokenizer.RESTRICT.TITLE
+                ),
+            },
+          },
+        },
+      },
+    },
+
+  At the top level, a Popover is defined. This allows a collection of children
+  to be shown in a separate Touch Bar. The Popover has two children: a Label,
+  and a Scroll View. The Scroll View displays five similar buttons that call a
+  helper method to insert search shortcut symbols into the address bar.
+
+Adding a new input
+------------------
+Adding a new input is easy: just add a new object to ``gBuiltInInputs``. This
+will make the input available in the Touch Bar customization window (accessible
+from the Firefox menu bar item).
+
+If you want to to add your new input to the default set, add its identifier
+here_, where ``type`` is a value from ``kAllowedInputTypes`` in that
+file and ``key`` is the value you set for ``title`` in ``gBuiltInInputs``.
+You should request approval from UX before changing the default set of inputs.
+
+.. _here: https://searchfox.org/mozilla-central/rev/ebe492edacc75bb122a2b380e4cafcca3470864c/widget/cocoa/nsTouchBar.mm#100
+
+If you are interested in adding new features to Firefox's implementation of the
+Touch Bar API, read on!
+
+
+Cocoa API
+~~~~~~~~~
+Firefox implements Apple's Touch Bar API in its Widget: Cocoa code with an
+``nsTouchBar`` class. ``nsTouchBar`` interfaces between Apple's Touch Bar API
+and the ``TouchBarHelper`` JavaScript API.
+
+The best resource to understand the Touch Bar API is Apple's
+`official documentation`_. This documentation will cover how Firefox implements
+these APIs and how one might extend ``nsTouchBar`` to enable new Touch Bar
+features.
+
+Every new Firefox window initializes ``nsTouchBar`` (link_). The function
+``makeTouchBar`` is looked for automatically on every new instance of an
+``NSWindow*``. If ``makeTouchBar`` is defined, that window will own a new
+instance of ``nsTouchBar``.
+
+At the time of this writing, every window initializes ``nsTouchBar`` with a
+default set of inputs. In the future, Firefox windows other than the main
+browser window (such as the Library window or DevTools) may initialize
+``nsTouchBar`` with a different set of inputs.
+
+``nsTouchBar`` has two different initialization methods: ``init`` and
+``initWithInputs``. The former is a convenience method for the latter, calling
+``initWithInputs`` with a nil argument. When that happens, a Touch Bar is
+created containing a default set of inputs. ``initWithInputs`` can also take an
+``NSArray<TouchBarInput*>*``. In that case, a non-customizable Touch Bar will be
+initialized with only those inputs available.
+
+.. _official documentation: https://developer.apple.com/documentation/appkit/nstouchbar?language=objc
+.. _link: https://searchfox.org/mozilla-central/rev/ebe492edacc75bb122a2b380e4cafcca3470864c/widget/cocoa/nsCocoaWindow.mm#2877
+
+NSTouchBarItemIdentifiers
+-------------------------
+The architecture of the Touch Bar is based largely around an ``NSString*``
+wrapper class called ``NSTouchBarItemIdentifier``. Every input in the Touch Bar
+has a unique ``NSTouchBarItemIdentifier``. They are structured in reverse-URI
+format like so:
+
+``com.mozilla.firefox.touchbar.[TYPE].[KEY]``
+
+[TYPE] is a string indicating the type of the input, e.g. "button". If an
+input is a child of another input, the parent's type is prepended to the child's
+type, e.g. "scrubber.button" indicates a button contained in a scrubber.
+
+[KEY] is the ``title`` attribute defined for that input on the JS side.
+
+If you need to generate an identifier, use the convenience method
+``[TouchBarInput nativeIdentifierWithType:withKey:]``.
+
+.. caution::
+
+  Do not create a new input that would have the same identifier as any other
+  input. All identifiers must be unique.
+
+.. warning::
+
+  ``NSTouchBarItemIdentifier`` `is used in one other place`_: setting
+  ``customizationIdentifier``. Do not ever change this string. If it is changed,
+  any customizations users have made to the layout of their Touch Bar in Firefox
+  will be erased.
+
+Each identifier is tied to a ``TouchBarInput``. ``TouchBarInput`` is a class
+that holds the properties specified for each input in ``gBuiltInInputs``.
+``nsTouchBar`` uses them to create instances of ``NSTouchBarItem``
+which are the actual objects used by Apple's Touch Bar API and displayed in the
+Touch Bar. It is important to understand the difference between
+``TouchBarInput`` and ``NSTouchBarItem``!
+
+.. _is used in one other place: https://searchfox.org/mozilla-central/rev/ebe492edacc75bb122a2b380e4cafcca3470864c/widget/cocoa/nsTouchBar.mm#71
+
+TouchBarInput creation flow
+---------------------------
+Creating a Touch Bar and its ``TouchBarInputs`` flows as follows:
+
+#. ``[nsTouchBar init]`` is called from ``[NSWindow makeTouchBar]``.
+
+#. ``init`` populates two NSArrays: ``customizationAllowedItemIdentifiers`` and
+   ``defaultItemIdentifiers``. It also initializes a ``TouchBarInput`` object
+   for every element in the union of the two arrays and stores them in
+   ``NSMutableDictionary<NSTouchBarItemIdentifier, TouchBarInput*>* mappedLayoutItems``.
+
+#. ``touchBar:makeItemForIdentifier:`` is called for every element in the union
+   of the two arrays of identifiers. This method retrieves the ``TouchBarInput``
+   for the given identifier and uses it to initialize a ``NSTouchBarItem``.
+   ``touchBar:makeItemForIdentifier:`` reads the ``type`` attribute from the
+   ``TouchBarInput`` to determine what ``NSTouchBarItem`` subclass should be
+   initialized. Our Touch Bar code currently supports ``NSCustomTouchBarItem``
+   (buttons, main buttons); ``NSPopoverTouchBarItem`` (popovers);
+   ``NSTextField`` (labels); and ``NSScrollView`` (ScrollViews).
+
+#. Once the ``NSTouchBarItem`` is initialized, its properties are populated with
+   an assortment of "update" methods. These include ``updateButton``,
+   ``updateMainButton``, ``updateLabel``, ``updatePopover``, and
+   ``updateScrollView``.
+
+#. Since the localization of ``TouchBarInput`` titles happens asynchronously in
+   JavaScript code, the l10n callback executes
+   ``[nsTouchBarUpdater updateTouchBarInputs:]``. This method reads the
+   identifier of the input(s) that need to be updated and calls their respective
+   "update" methods. This method is most often used to update ``title`` after
+   l10n is complete. It can also be used to update any property of a
+   ``TouchBarInput``;  for instance, one might wish to change ``color``
+   when a specific event occurs in the browser.